워크로그 API

beginner 🤖 LLM 친화적 2 분 · 319 단어 업데이트: 2026-10-19 한국어

에이전트 팀을 위한 태스크별 append-only 워크로그 — 모든 단계를 기록해 아무것도 잃지 않도록. 태스크, 에이전트, 종류, 시간으로 조회 가능.

워크로그 API

워크로그는 플릿 작업 이력의 단일 진실 공급원입니다. append-only이며 태스크별로 조회할 수 있습니다. /memory가 에이전트가 아는 것을 저장한다면, 워크로그는 에이전트가 한 것을 저장합니다 — 태스크별 내구성 있고 감사 가능한 흔적으로. Michael의 상설 규칙(#8882, #10509에서 재확인): push-first — 모든 마일스톤에 엔트리를 남깁니다. 그러면 죽은 세션도 자기 이야기를 잃지 않고, 어떤 형제 에이전트든 정확히 멈춘 지점에서 이어갈 수 있습니다.

개념

용어	의미
태스크 워크로그	자유 형식의 `task_id`(UUID 접두사, 티켓, 티켓 스타일 슬러그 등 직접 선택)로 식별되는 이름 있는 로그.
엔트리	append-only 레코드 하나: `kind`, `agent`, `content`, 선택적 `title`, 타임스탬프.
상태	`active`(열림) → `completed`(닫힘) 또는 `abandoned`. `/close`로 설정.

엔드포인트

모든 엔드포인트는 인증(Mind Key 또는 사용자 JWT)이 필요하고 호출자의 마인드로 스코프됩니다 — 다른 마인드의 워크로그는 절대 보이지 않습니다.

푸시 — 단일 호출 패턴

가장 편리한 엔드포인트; 엔트리를 추가하고 없으면 태스크 레코드를 만듭니다:

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

워크로그 생성 / 열기

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            # 전체 태스크 워크로그 제거

둘 다 GET 변형이 있습니다(/worklog/:task_id/close, /worklog/:task_id/delete) — open-tool LLM 클라이언트용. 닫아도 로그는 유지됩니다 — 삭제만이 유일한 파괴적 작업입니다.

에이전트를 위한 권장 리듬

start — 태스크를 청구할 때 start 엔트리(청구 증거).
progress — 모든 마일스톤마다 progress 엔트리 — 커밋 SHA, MR 번호, 판정, 파이프라인 상태. push-first(Michael #8882): 세션 끝까지 몰아두지 마세요.
error — 기억할 가치가 있는 모든 실패에 error 엔트리, 수정 내용과 함께.
summary — 컨텍스트가 다 되기 전에 summary — 다음 런이 state 스크립트 + 워크로그에서 이어갑니다.
close — 태스크가 끝나면 close(마지막 엔트리에 증거).

플릿 전체 태스크 컨벤션(GET /script/fleet-worklog-tasks-spec)은 이 API 위에 구축되었습니다. 에이전트 가이드 에이전트를 위한 워크로그에 복사-붙여넣기용 프롬프트 블록이 있어 어떤 에이전트도 이 기능을 "잊지" 않습니다(Michael #10509).

task_id 규칙 (v1.39.46)

완전한 UUID 형식의 task_id는 모든 쓰기 경로 (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 작업을 만들지 않습니다. UUID 형식이 아닌 자유 id (run-145-ci-27, morpheus-life, 29140fb0-team-stats 같은 접두사 슬러그) 는 계속 자유롭게 만들 수 있습니다(MEGA-1A 설계). 읽기·삭제 경로는 변경 없음 — 절대 아무것도 만들지 않습니다.