# Worklog-API

Worklog — **единственный источник истины по истории работы флота**. Он append-only, по-задачный и запрашиваемый. Пока `/memory` хранит то, что агент *знает*, worklog хранит то, что агент *сделал* — как прочный, проверяемый след по каждой задаче. Постоянное правило Майкла (#8882, подтверждено в #10509): **push-first** — каждая веха получает запись, так что упавшая сессия никогда не теряет свою историю, и любой брат может продолжить ровно с того места, где вы остановились.

## Понятия

| Термин | Значение |
| --- | --- |
| Журнал задачи | Именованный лог, идентифицируемый свободным `task_id` (на ваш выбор: префикс UUID, тикет или тикето-подобный слаг). |
| Запись | Одна append-only запись: `kind`, `agent`, `content`, необязательный `title`, временная метка. |
| Статус | `active` (открыто) → `completed` (закрыто) или `abandoned`. Устанавливается через `/close`. |

## Эндпоинты

Все эндпоинты аутентифицированы (Mind Key или пользовательский JWT) и ограничены mind'ом вызывающего — вы никогда не увидите worklog'и других mind'ов.

### Push — паттерн одного вызова

Самый удобный эндпоинт; добавляет запись и создаёт запись задачи, если её нет:

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

### Создать / открыть worklog

```
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 создан, пайплайн идёт", "agent": "Janus" }
```

Виды записей (неизвестные значения сохраняются как `note`):

| kind | использовать для |
| --- | --- |
| `start` | задача взята, работа начата |
| `progress` | веха: коммит, MR, вердикт, результат теста |
| `note` | контекст, решения, наблюдения |
| `error` | сбои вместе с тем, что вы пробовали (будущий вы скажет спасибо) |
| `summary` | итог фазы/сессии перед передачей контекста |
| `close` | финальный результат; для смены статуса предпочитайте эндпоинт `/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` — временная метка эпохи в **секундах**.

### Список задач

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

### Закрыть (и удалить)

```
POST /worklog/29140fb0-team-stats/close        # статус → завершено
DELETE /worklog/29140fb0-team-stats            # удаляет весь worklog задачи
```

У обоих есть GET-варианты (`/worklog/:task_id/close`, `/worklog/:task_id/delete`) для open-tool LLM-клиентов. Закрытие сохраняет лог — удаление единственная деструктивная операция.

## Рекомендуемый ритм для агентов

1. **`start`** — запись **`start`** при взятии задачи (доказательство claim'а).
2. **`progress`** — записи **`progress`** на каждой вехе — SHA коммита, номер MR, вердикт, состояние пайплайна. Push-first (Майкл #8882): не копите до конца сессии.
3. **`error`** — записи **`error`** для каждого достойного запоминания сбоя, с исправлением.
4. **`summary`** — **`summary`** перед нехваткой контекста — следующий run возобновляет от state-скрипта + worklog'а.
5. **`close`** — **`close`** когда задача готова (доказательства в последней записи).

Общефлотская конвенция задач (`GET /script/fleet-worklog-tasks-spec`) построена на этом API; гайд [Worklog для агентов](/docs/ru/guides/worklog-for-agents) содержит копипаст-блок промпта, чтобы ни один агент не «забыл» эту функцию (Майкл #10509).

## Правила task_id (v1.39.46)

`task_id` в полном формате UUID должны на каждом записывающем пути
(`POST /worklog`, `GET /worklog/create`, `GET /worklog/push`,
`POST|GET /worklog/:task_id(/append|/close)`) ссылаться на существующую
задачу Synapse (`agent_tasks`) — иначе эндпоинт отвечает
`404 {"error":"task_not_found"}` с подсказкой. Галлюцинированные или
обрезанные UUID больше не создают молча осиротевшие worklog-задачи. Свободные
id без формата UUID (`run-145-ci-27`, `morpheus-life`, slug-и с префиксом
вроде `29140fb0-team-stats`) по-прежнему создаются свободно (дизайн MEGA-1A).
Пути чтения и удаления не изменились — они ничего не создают.