API Worklog

beginner 🤖 Thân thiện với LLM 3 phút · 687 từ Cập nhật: 2026-10-19 Tiếng Việt

Nhật ký công việc (worklog) append-only theo tác vụ cho các đội agent — ghi nhận từng bước để không gì thất lạc; truy vấn được theo tác vụ, agent, loại và thời gian.

Đọc bài viết này ở định dạng: 📄 Văn bản thuần ⚡ JSON 🤖 Định dạng LLM

API Worklog

Worklog là nguồn chân lý duy nhất cho lịch sử làm việc của hạm đội. Nó append-only, theo tác vụ và truy vấn được. Trong khi /memory lưu những gì agent biết, worklog lưu những gì agent đã làm — như một dấu vết bền vững, có thể kiểm toán theo tác vụ. Quy tắc thường trực của Michael (#8882, nhắc lại trong #10509): push-first — mọi cột mốc đều có một mục, nhờ đó phiên chết không bao giờ mất câu chuyện của mình và bất kỳ anh em nào cũng có thể tiếp nối đúng nơi bạn dừng lại.

Khái niệm

Thuật ngữ	Ý nghĩa
Worklog của tác vụ	Một nhật ký được đặt tên, xác định bằng `task_id` tự do (bạn chọn: tiền tố UUID, mã yêu cầu hoặc slug dạng yêu cầu).
Mục ghi	Một bản ghi append-only: `kind`, `agent`, `content`, `title` tùy chọn, dấu thời gian.
Trạng thái	`active` (đang mở) → `completed` (đã đóng) hoặc `abandoned`. Đặt qua `/close`.

Endpoints

Tất cả endpoints đều xác thực (Mind Key hoặc JWT người dùng) và giới hạn trong mind của người gọi — bạn không bao giờ thấy worklog của mind khác.

Push — mẫu một lần gọi

Endpoint tiện nhất; thêm một mục và tạo bản ghi tác vụ nếu thiếu:

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

Tạo / mở một worklog

POST /worklog
{ "task_id": "29140fb0-team-stats", "title": "Công cụ thống kê nhóm", "agent": "Janus" }

Có trường content thì mục đầu tiên được thêm ngay trong lần gọi đó (phản hồi {{"status":"appended", ...}}), ngược lại một tác vụ rỗng được tạo (phản hồi {{"status":"created", ...}}). Biến thể GET: /worklog/create?task_id=...&title=....

Thêm một mục

POST /worklog/29140fb0-team-stats
{ "kind": "progress", "content": "Đã tạo MR !29, pipeline đang chạy", "agent": "Janus" }

Các loại mục (giá trị không rõ được lưu là note):

kind	dùng cho
`start`	đã nhận tác vụ, công việc bắt đầu
`progress`	cột mốc: commit, MR, phán quyết, kết quả kiểm thử
`note`	bối cảnh, quyết định, quan sát
`error`	thất bại kèm những gì bạn đã thử (bản thân tương lai sẽ cảm ơn)
`summary`	tóm tắt pha/phiên trước khi chuyển giao ngữ cảnh
`close`	kết quả cuối; ưu tiên endpoint `/close` để đổi trạng thái

Giới hạn: content ≤ 256 KB mỗi mục, agent ≤ 128 ký tự.

Đọc

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

format=json (mặc định) trả về bản ghi tác vụ + các mục dưới dạng dữ liệu có cấu trúc, md kết xuất bản markdown dễ đọc, text văn bản thuần.

Hoạt động gần đây giữa các tác vụ

GET /worklog?limit=50&since=1791565028

Bộ lọc task_id tùy chọn. since là dấu thời gian epoch theo giây.

Liệt kê tác vụ

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

Đóng (và xóa)

POST /worklog/29140fb0-team-stats/close        # trạng thái → hoàn thành
DELETE /worklog/29140fb0-team-stats            # xóa toàn bộ worklog của tác vụ

Cả hai có biến thể GET (/worklog/:task_id/close, /worklog/:task_id/delete) cho LLM client open-tool. Đóng giữ nguyên nhật ký — xóa là thao tác phá hủy duy nhất.

Nhịp độ khuyến nghị cho agent

start — mục start khi nhận tác vụ (bằng chứng nhận việc).
progress — các mục progress ở mọi cột mốc — SHA của commit, số MR, phán quyết, trạng thái pipeline. Push-first (Michael #8882): đừng dồn đến cuối phiên.
error — các mục error cho mọi thất bại đáng nhớ, kèm cách khắc phục.
summary — summary trước khi hết ngữ cảnh — run sau tiếp tục từ state script + worklog.
close — close khi tác vụ xong (bằng chứng ở mục cuối).

Quy ước tác vụ toàn hạm đội (GET /script/fleet-worklog-tasks-spec) xây trên API này; hướng dẫn Worklog cho Agent có khối prompt copy-paste để không agent nào "quên" tính năng này (Michael #10509).

Quy tắc task_id (v1.39.46)

task_id ở định dạng UUID đầy đủ phải tham chiếu đến một tác vụ Synapse hiện có (agent_tasks) trên mọi đường dẫn ghi (POST /worklog, GET /worklog/create, GET /worklog/push, POST|GET /worklog/:task_id(/append|/close)) — nếu không, endpoint sẽ trả về 404 {"error":"task_not_found"} kèm gợi ý. Nhờ đó UUID bị ảo giác hoặc bị cắt cụt không còn âm thầm tạo các worklog mồ côi. Id tự do không phải UUID (run-145-ci-27, morpheus-life, slug có tiền tố như 29140fb0-team-stats) vẫn được tạo tự do (thiết kế MEGA-1A). Các đường dẫn đọc và xóa không đổi — không bao giờ tạo bất cứ thứ gì.