# API Worklog

Worklog คือ **แหล่งความจริงเพียงแหล่งเดียวของประวัติการทำงานของฟลีต** เป็นแบบ append-only รายงาน และค้นหาได้ ขณะที่ `/memory` เก็บสิ่งที่เอเจนต์ *รู้* worklog เก็บสิ่งที่เอเจนต์ *ทำ* — เป็นร่องรอยที่ถาวรและตรวจสอบได้รายงาน กฎประจำของ Michael (#8882, ยืนยันซ้ำใน #10509): **push-first** — ทุกหมุดหมายได้รับหนึ่งรายการ ทำให้เซสชันที่ล่มไม่เคยสูญเสียเรื่องราว และพี่น้องเอเจนต์คนใดก็ได้สานต่อจากจุดที่คุณหยุดพอดี

## แนวคิด

| คำศัพท์ | ความหมาย |
| --- | --- |
| เวิร์กล็อกของงาน | บันทึกที่มีชื่อ ระบุด้วย `task_id` อิสระ (เลือกเอง เช่น คำนำหน้า UUID, หมายเลขงาน หรือ slug ลักษณะงาน) |
| รายการ | บันทึกแบบ append-only หนึ่งรายการ: `kind`, `agent`, `content`, `title` (ไม่บังคับ), ประทับเวลา |
| สถานะ | `active` (เปิด) → `completed` (ปิดแล้ว) หรือ `abandoned` ตั้งผ่าน `/close` |

## Endpoints

ทุก endpoint ต้องยืนยันตัวตน (Mind Key หรือ JWT ผู้ใช้) และจำกัดขอบเขตใน mind ของผู้เรียก — คุณจะไม่เห็นเวิร์กล็อกของ mind อื่นเด็ดขาด

### Push — รูปแบบเรียกครั้งเดียว

Endpoint ที่สะดวกที่สุด; เพิ่มรายการและสร้างเรกคอร์ดงานหากยังไม่มี:

```
GET /worklog/push?task_id=run-145-ci-27&kind=progress&content=Pin-Fix pushed&agent=Janus
```

### สร้าง / เปิดเวิร์กล็อก

```
POST /worklog
{ "task_id": "29140fb0-team-stats", "title": "เครื่องมือสถิติทีม", "agent": "Janus" }
```

หากมีฟิลด์ `content` รายการแรกจะถูกเพิ่มในการเรียกเดียวกัน (ผลลัพธ์ `{{"status":"appended", ...}}`) หากไม่มี จะสร้างงานเปล่า (ผลลัพธ์ `{{"status":"created", ...}}`) รูปแบบ GET: `/worklog/create?task_id=...&title=...`

### เพิ่มรายการ

```
POST /worklog/29140fb0-team-stats
{ "kind": "progress", "content": "สร้าง MR !29 แล้ว, pipeline กำลังรัน", "agent": "Janus" }
```

ชนิดรายการ (ค่าที่ไม่รู้จักจะถูกเก็บเป็น `note`):

| kind | ใช้เมื่อ |
| --- | --- |
| `start` | รับงานแล้ว เริ่มทำงาน |
| `progress` | หมุดหมาย: commit, MR, คำตัดสิน, ผลทดสอบ |
| `note` | บริบท การตัดสินใจ ข้อสังเกต |
| `error` | ความล้มเหลวพร้อมสิ่งที่คุณลอง (ตัวคุณในอนาคตจะขอบคุณ) |
| `summary` | สรุปเฟส/เซสชันก่อนส่งต่อบริบท |
| `close` | ผลลัพธ์สุดท้าย; นิยมใช้ endpoint `/close` สำหรับการเปลี่ยนสถานะ |

ขีดจำกัด: `content` ไม่เกิน 256 KB ต่อรายการ, `agent` ไม่เกิน 128 ตัวอักษร

### อ่าน

```
GET /worklog/29140fb0-team-stats?format=md
```

`format=json` (ค่าเริ่มต้น) คืนเรกคอร์ดงาน + รายการเป็นข้อมูลมีโครงสร้าง, `md` เรนเดอร์บันทึก markdown อ่านง่าย, `text` เป็นข้อความธรรมดา

### กิจกรรมล่าสุดข้ามงาน

```
GET /worklog?limit=50&since=1791565028
```

ตัวกรอง `task_id` ไม่บังคับ `since` เป็นประทับเวลา epoch หน่วย**วินาที**

### รายการงาน

```
GET /worklog/list?status=active&limit=20
```

### ปิด (และลบ)

```
POST /worklog/29140fb0-team-stats/close        # สถานะ → เสร็จสมบูรณ์
DELETE /worklog/29140fb0-team-stats            # ลบเวิร์กล็อกของงานทั้งหมด
```

ทั้งสองมีรูปแบบ GET (`/worklog/:task_id/close`, `/worklog/:task_id/delete`) สำหรับ LLM client แบบ open-tool การปิดยังเก็บบันทึกไว้ — การลบคือการกระทำที่ทำลายเพียงอย่างเดียว

## จังหวะที่แนะนำสำหรับเอเจนต์

1. **`start`** — รายการ **`start`** เมื่อรับงาน (หลักฐานการรับ)
2. **`progress`** — รายการ **`progress`** ทุกหมุดหมาย — SHA ของ commit, หมายเลข MR, คำตัดสิน, สถานะ pipeline push-first (Michael #8882): อย่ารวบไว้จนจบเซสชัน
3. **`error`** — รายการ **`error`** สำหรับทุกความล้มเหลวที่ควรจดจำ พร้อมวิธีแก้
4. **`summary`** — **`summary`** ก่อนบริบทหมด — รันถัดไปเริ่มต่อจาก state script + เวิร์กล็อก
5. **`close`** — **`close`** เมื่องานเสร็จ (หลักฐานในรายการสุดท้าย)

ธรรมเนียมงานระดับฟลีต (`GET /script/fleet-worklog-tasks-spec`) สร้างบน API นี้ คู่มือ [Worklog สำหรับเอเจนต์](/docs/th/guides/worklog-for-agents) มีบล็อกพรอมต์สำหรับคัดลอกวาง เพื่อไม่ให้เอเจนต์คนใด "ลืม" ฟีเจอร์นี้ (Michael #10509)

## กฎ task_id (v1.39.46)

`task_id` ที่อยู่ในรูปแบบ UUID เต็มต้องอ้างอิงงาน Synapse ที่มีอยู่
(`agent_tasks`) ในทุกเส้นทางการเขียน (`POST /worklog`, `GET /worklog/create`,
`GET /worklog/push`, `POST|GET /worklog/:task_id(/append|/close)`) — มิฉะนั้น
endpoint จะตอบ `404 {"error":"task_not_found"}` พร้อมคำแนะนำ ทำให้ UUID ที่
hallucinate หรือถูกตัดขาดไม่สร้าง worklog กำพร้าอย่างเงียบ ๆ อีกต่อไป id แบบ
อิสระที่ไม่ใช่ UUID (`run-145-ci-27`, `morpheus-life`, slug แบบมีคำนำหน้า
อย่าง `29140fb0-team-stats`) ยังสร้างได้อย่างอิสระ (ดีไซน์ MEGA-1A) เส้นทาง
อ่านและลบไม่เปลี่ยนแปลง — ไม่เคยสร้างสิ่งใด