# API Worklog
SUMMARY: เวิร์กล็อกแบบ append-only รายงานสำหรับทีมเอเจนต์ — บันทึกทุกขั้นตอนเพื่อไม่ให้อะไรหาย; ค้นได้ตามงาน เอเจนต์ ชนิด และเวลา

KEY CONTEXT:
Auth: Mind Key (or user JWT). All endpoints mind-scoped via the caller's mind/user.
Push (1 call): GET /worklog/push?task_id=T&kind=progress&content=...&agent=Janus&title=...
Create/open a task worklog: POST /worklog { task_id, title? }  (content? -> appends first entry)
Append entry: POST /worklog/:task_id { kind, content, agent?, title? }  (GET variant: /worklog/:task_id/append)
Read: GET /worklog/:task_id?format=json|md|text
Recent across tasks: GET /worklog?limit=50&since=<epoch sec>&task_id=
List tasks: GET /worklog/list?status=active|completed|all&limit=20
Close: POST /worklog/:task_id/close  (GET variant exists)
Delete: DELETE /worklog/:task_id  (GET variant exists)
kinds: start | progress | note | error | summary | close (unknown -> note)
Limits: content max 256 KB per entry; agent max 128 chars; task_id [a-zA-Z0-9._/-] max 256.
Fleet rule (Michael #8882/#10509): POST /worklog at EVERY milestone — fix commit, verdict, escalation, handover, takeover, CRITICAL — not only at session end.
task_ids แบบ UUID: append/create/close ตอบ 404 (task_not_found) เมื่อไม่มีงาน Synapse (agent_tasks) สำหรับ UUID นั้น ส่วน slug รูปแบบอิสระยังสร้างได้อย่างอิสระ (v1.39.46)

API Worklog
Worklog คือ แหล่งความจริงเพียงแหล่งเดียวของประวัติการทำงานของฟลีต เป็นแบบ append-only รายงาน และค้นหาได้ ขณะที่  เก็บสิ่งที่เอเจนต์ รู้ worklog เก็บสิ่งที่เอเจนต์ ทำ — เป็นร่องรอยที่ถาวรและตรวจสอบได้รายงาน กฎประจำของ Michael (#8882, ยืนยันซ้ำใน #10509): push-first — ทุกหมุดหมายได้รับหนึ่งรายการ ทำให้เซสชันที่ล่มไม่เคยสูญเสียเรื่องราว และพี่น้องเอเจนต์คนใดก็ได้สานต่อจากจุดที่คุณหยุดพอดี
แนวคิด
| คำศัพท์ | ความหมาย |
| --- | --- |
| เวิร์กล็อกของงาน | บันทึกที่มีชื่อ ระบุด้วย  อิสระ (เลือกเอง เช่น คำนำหน้า UUID, หมายเลขงาน หรือ slug ลักษณะงาน) |
| รายการ | บันทึกแบบ append-only หนึ่งรายการ: , , ,  (ไม่บังคับ), ประทับเวลา |
| สถานะ |  (เปิด) →  (ปิดแล้ว) หรือ  ตั้งผ่าน  |
Endpoints
ทุก endpoint ต้องยืนยันตัวตน (Mind Key หรือ JWT ผู้ใช้) และจำกัดขอบเขตใน mind ของผู้เรียก — คุณจะไม่เห็นเวิร์กล็อกของ mind อื่นเด็ดขาด
Push — รูปแบบเรียกครั้งเดียว
Endpoint ที่สะดวกที่สุด; เพิ่มรายการและสร้างเรกคอร์ดงานหากยังไม่มี:
[CODE BLOCK]
สร้าง / เปิดเวิร์กล็อก
[CODE BLOCK]
หากมีฟิลด์  รายการแรกจะถูกเพิ่มในการเรียกเดียวกัน (ผลลัพธ์ ) หากไม่มี จะสร้างงานเปล่า (ผลลัพธ์ ) รูปแบบ GET: 
เพิ่มรายการ
[CODE BLOCK]
ชนิดรายการ (ค่าที่ไม่รู้จักจะถูกเก็บเป็น ):
| kind | ใช้เมื่อ |
| --- | --- |
|  | รับงานแล้ว เริ่มทำงาน |
|  | หมุดหมาย: commit, MR, คำตัดสิน, ผลทดสอบ |
|  | บริบท การตัดสินใจ ข้อสังเกต |
|  | ความล้มเหลวพร้อมสิ่งที่คุณลอง (ตัวคุณในอนาคตจะขอบคุณ) |
|  | สรุปเฟส/เซสชันก่อนส่งต่อบริบท |
|  | ผลลัพธ์สุดท้าย; นิยมใช้ endpoint  สำหรับการเปลี่ยนสถานะ |
ขีดจำกัด:  ไม่เกิน 256 KB ต่อรายการ,  ไม่เกิน 128 ตัวอักษร
อ่าน
[CODE BLOCK]
 (ค่าเริ่มต้น) คืนเรกคอร์ดงาน + รายการเป็นข้อมูลมีโครงสร้าง,  เรนเดอร์บันทึก markdown อ่านง่าย,  เป็นข้อความธรรมดา
กิจกรรมล่าสุดข้ามงาน
[CODE BLOCK]
ตัวกรอง  ไม่บังคับ  เป็นประทับเวลา epoch หน่วยวินาที
รายการงาน
[CODE BLOCK]
ปิด (และลบ)
[CODE BLOCK]
ทั้งสองมีรูปแบบ GET (, ) สำหรับ LLM client แบบ open-tool การปิดยังเก็บบันทึกไว้ — การลบคือการกระทำที่ทำลายเพียงอย่างเดียว
จังหวะที่แนะนำสำหรับเอเจนต์
1.  — รายการ  เมื่อรับงาน (หลักฐานการรับ)
2.  — รายการ  ทุกหมุดหมาย — SHA ของ commit, หมายเลข MR, คำตัดสิน, สถานะ pipeline push-first (Michael #8882): อย่ารวบไว้จนจบเซสชัน
3.  — รายการ  สำหรับทุกความล้มเหลวที่ควรจดจำ พร้อมวิธีแก้
4.  —  ก่อนบริบทหมด — รันถัดไปเริ่มต่อจาก state script + เวิร์กล็อก
5.  —  เมื่องานเสร็จ (หลักฐานในรายการสุดท้าย)
ธรรมเนียมงานระดับฟลีต () สร้างบน API นี้ คู่มือ Worklog สำหรับเอเจนต์ มีบล็อกพรอมต์สำหรับคัดลอกวาง เพื่อไม่ให้เอเจนต์คนใด "ลืม" ฟีเจอร์นี้ (Michael #10509)
กฎ taskid (v1.39.46)
 ที่อยู่ในรูปแบบ UUID เต็มต้องอ้างอิงงาน Synapse ที่มีอยู่
() ในทุกเส้นทางการเขียน (, ,
, ) — มิฉะนั้น
endpoint จะตอบ  พร้อมคำแนะนำ ทำให้ UUID ที่
hallucinate หรือถูกตัดขาดไม่สร้าง worklog กำพร้าอย่างเงียบ ๆ อีกต่อไป id แบบ
อิสระที่ไม่ใช่ UUID (, , slug แบบมีคำนำหน้า
อย่าง ) ยังสร้างได้อย่างอิสระ (ดีไซน์ MEGA-1A) เส้นทาง
อ่านและลบไม่เปลี่ยนแปลง — ไม่เคยสร้างสิ่งใด