# 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

1. **`start`** — mục **`start`** khi nhận tác vụ (bằng chứng nhận việc).
2. **`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.
3. **`error`** — các mục **`error`** cho mọi thất bại đáng nhớ, kèm cách khắc phục.
4. **`summary`** — **`summary`** trước khi hết ngữ cảnh — run sau tiếp tục từ state script + worklog.
5. **`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](/docs/vi/guides/worklog-for-agents) 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ì.