# Worklog-API
SUMMARY: Журналы работы (worklog) только-на-добавление для каждой задачи — документируйте каждый шаг, чтобы ничего не терялось; запросы по задаче, агенту, типу и времени.

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), если для UUID нет задачи Synapse (agent_tasks). Свободные slug-и по-прежнему создаются свободно. (v1.39.46)

Worklog-API
Worklog — единственный источник истины по истории работы флота. Он append-only, по-задачный и запрашиваемый. Пока  хранит то, что агент знает, worklog хранит то, что агент сделал — как прочный, проверяемый след по каждой задаче. Постоянное правило Майкла (#8882, подтверждено в #10509): push-first — каждая веха получает запись, так что упавшая сессия никогда не теряет свою историю, и любой брат может продолжить ровно с того места, где вы остановились.
Понятия
| Термин | Значение |
| --- | --- |
| Журнал задачи | Именованный лог, идентифицируемый свободным  (на ваш выбор: префикс UUID, тикет или тикето-подобный слаг). |
| Запись | Одна append-only запись: , , , необязательный , временная метка. |
| Статус |  (открыто) →  (закрыто) или . Устанавливается через . |
Эндпоинты
Все эндпоинты аутентифицированы (Mind Key или пользовательский JWT) и ограничены mind'ом вызывающего — вы никогда не увидите worklog'и других mind'ов.
Push — паттерн одного вызова
Самый удобный эндпоинт; добавляет запись и создаёт запись задачи, если её нет:
[CODE BLOCK]
Создать / открыть worklog
[CODE BLOCK]
С полем  первая запись добавляется в том же вызове (ответ ), иначе создаётся пустая задача (ответ ). GET-вариант: .
Добавить запись
[CODE BLOCK]
Виды записей (неизвестные значения сохраняются как ):
| kind | использовать для |
| --- | --- |
|  | задача взята, работа начата |
|  | веха: коммит, MR, вердикт, результат теста |
|  | контекст, решения, наблюдения |
|  | сбои вместе с тем, что вы пробовали (будущий вы скажет спасибо) |
|  | итог фазы/сессии перед передачей контекста |
|  | финальный результат; для смены статуса предпочитайте эндпоинт  |
Ограничения:  ≤ 256 KB на запись,  ≤ 128 символов.
Чтение
[CODE BLOCK]
 (по умолчанию) возвращает запись задачи + записи как структурированные данные,  — человекочитаемую markdown-расшифровку,  — простой текст.
Недавняя активность по задачам
[CODE BLOCK]
Необязательный фильтр .  — временная метка эпохи в секундах.
Список задач
[CODE BLOCK]
Закрыть (и удалить)
[CODE BLOCK]
У обоих есть GET-варианты (, ) для open-tool LLM-клиентов. Закрытие сохраняет лог — удаление единственная деструктивная операция.
Рекомендуемый ритм для агентов
1.  — запись  при взятии задачи (доказательство claim'а).
2.  — записи  на каждой вехе — SHA коммита, номер MR, вердикт, состояние пайплайна. Push-first (Майкл #8882): не копите до конца сессии.
3.  — записи  для каждого достойного запоминания сбоя, с исправлением.
4.  —  перед нехваткой контекста — следующий run возобновляет от state-скрипта + worklog'а.
5.  —  когда задача готова (доказательства в последней записи).
Общефлотская конвенция задач () построена на этом API; гайд Worklog для агентов содержит копипаст-блок промпта, чтобы ни один агент не «забыл» эту функцию (Майкл #10509).
Правила taskid (v1.39.46)
 в полном формате UUID должны на каждом записывающем пути
(, , ,
) ссылаться на существующую
задачу Synapse () — иначе эндпоинт отвечает
 с подсказкой. Галлюцинированные или
обрезанные UUID больше не создают молча осиротевшие worklog-задачи. Свободные
id без формата UUID (, , slug-и с префиксом
вроде ) по-прежнему создаются свободно (дизайн MEGA-1A).
Пути чтения и удаления не изменились — они ничего не создают.