Chuyển tới nội dung chính
Phiên bản: Next

Hợp đồng I/O .board/ — tra cứu đầy đủ

Đây là toàn bộ giao diện giữa AgentJira và agent CLI. Hiểu nó là hiểu tại sao hệ thống tất định.

Server ghi vào worktree (trước khi agent chạy)​

FileNội dung
.board/task.jsonTiêu đề, mô tả, acceptance criteria, non-goals, verification rules, schema của result.json
.board/wiki/INDEX.mdMục lục tri thức đã bơm từ Space — No wiki pages available nếu Space chưa link hoặc Arkon vắng
.board/wiki/*.mdNội dung từng trang Wiki liên quan (tối đa 5 trang, song song)
.board/history.mdGhi chú rework (người) + repair loop (Repair Attempt 1/2, tối đa 2 vòng)
.board/plan-research.md(chỉ ở task spike của Planner) Báo cáo nghiên cứu codebase
.mcp.jsonMCP token của persona — thuộc K5 đã hoãn, chưa ghi

.board/ và .mcp.json được thêm vào .git/info/exclude — chúng không bao giờ lọt vào diff hay commit.

Agent ghi ra (sau khi làm việc)​

.board/result.json — bắt buộc. Schema:

{
  "success": true,
  "summary": "Mô tả ngắn việc đã làm",
  "filesChanged": ["src/a.ts", "src/a.test.ts"],
  "notes": "Ghi chú thêm",
  "followUpSuggestions": ["Cần thêm rate limit"],
  "wikiProposals": [
    { "contentMd": "# ADR-014…", "note": "…" }
  ]
}
  • success (boolean) và summary (string không rỗng): bắt buộc.
  • filesChanged, notes, followUpSuggestions: tuỳ chọn.
  • wikiProposals[]: tuỳ chọn, nhưng mỗi phần tử bắt buộc contentMd không rỗng.
  • Sai schema → repair loop (tối đa 2 vòng) → nếu vẫn sai, suy biến mềm về trích xuất regex.

Reviewer Agent ghi ra​

.board/review-verdict.json:

{
  "score": 95,
  "verdict": "approved",
  "summary": "…",
  "findings": [
    { "file": "src/x.ts", "severity": "minor", "message": "…" }
  ]
}
  • score: 0–100. verdict ∈ approved | changes_requested | rejected.
  • severity ∈ critical | major | minor | info.

Bốn cơ chế đã nối — kill-switch và suy biến​

Cơ chếHàmKhi nào chạySuy biếnKill-switch
Bơm tri thức vào worktreesyncBoardWikiContextTrước session.execute(), song song với createSession() (deadline 8s)INDEX.md rỗng + event Space wiki context unavailableAGENTBOARD_WIKI_CONTEXT=0
Nhận đề xuất WikiingestWikiProposalsSau terminateOnce (đã ở review/peer-review)Event nêu reason, đề xuất ở lại result.jsonAGENTBOARD_WIKI_CONTEXT=0
Repair loop result.jsonwriteRepairHistory + formatRepairPromptNgay sau readBoardResult() nếu !valid (tối đa 2 vòng, deadline 5m/vòng)history.md + fallback extractTaskSummaryAGENTBOARD_BOARD_REPAIR=0
Reviewer AgentReviewerAgentServiceSau afterCompletion, chỉ khi reviewState==='peer-review'Ở lại peer-review, event Peer review unavailableAGENTBOARD_REVIEWER_AGENT=off (auto mặc định)
Reviewer cần LLM thật

AGENTBOARD_REVIEWER_AGENT=auto (mặc định) chỉ chạy khi AGENTBOARD_LLM_MODE ∈ record và có AGENTBOARD_LLM_API_KEY/OPENAI_API_KEY và AGENTBOARD_LLM_MODEL. Nếu không, nó tự tắt thay vì tạo bản ghi audit giả (score 95 approved) — đây là hành vi có chủ ý. heuristic là opt-in cho E2E (prefix [heuristic]).

.mcp.json vẫn chưa ghi — K5 đã hoãn có chủ ý

5 MCP token vẫn nằm trong DB, decryptToken chỉ có call site khi K5 xong. Vì vậy Wiki hai chiều hiện hoạt động qua file (.board/wiki/** và wikiProposals), chưa qua MCP trực tiếp.

Sự kiện realtime & phòng WebSocket theo Space​

Tab Comments đọc qua WebSocket (/ws, room theo spaceId):

Sự kiệnPayloadClient làm gì
activity_createdactivity comment đầy đủ (+ metadata.spawnedSubtasks / skippedMentions)Thêm dòng comment + chip subtask nếu cùng taskId (trùng id thì bỏ qua)
activity_deleted{ id, taskId }Gỡ dòng comment khỏi thread
subscribed / unsubscribed{ spaceId }Đánh dấu phòng đã vào / đã rời
error + code: IDENTITY_PENDING{ spaceId }Danh tính chưa giải xong — client tự retry tối đa 4 lần (backoff tới 4s)
error + code: FORBIDDEN{ spaceId }Subscribe chéo Space bị từ chối — không retry, badge hiện No updates

Mất nối → client nối lại và tải lại state (không phát lại event lỡ).

Tự kiểm chứng (không tin UI — đi tìm file và dòng DB)​

# 1. Wiki đã vào worktree
WT=$(curl -s "$API/api/tasks?projectId=$PID" | jq -r '.[0].worktreePath')
docker exec agentjira_dev_server sh -c "cat $WT/.board/wiki/INDEX.md"
# → liệt kê trang, không phải "No wiki pages available"

# 2. result.json → summary API khớp nhau
docker exec agentjira_dev_server sh -c "cat $WT/.board/result.json" | jq .summary
curl -s "$API/api/tasks/$ID" | jq .summary

# 3. Reviewer verdict
docker exec agentjira_dev_server sh -c "cat $WT/.board/review-verdict.json" | jq .
curl -s "$API/api/tasks/$ID/reviews" | jq .

# 4. Đề xuất Wiki → draft Arkon
curl -s "http://localhost:5055/api/wiki/drafts?department_id=$DEPT" -H "Authorization: Bearer $TOKEN" | jq .

# 5. Repair loop
docker exec agentjira_dev_server sh -c "cat $WT/.board/history.md" | grep "Repair Attempt"

# 6. .board/ không lọt git
docker exec agentjira_dev_server sh -c "cd $WT && git add -A && git diff --cached --name-only | grep -q .board && echo FAIL || echo OK"

Ratchet chống tái phát: tests/wiring-liveness.test.ts quét src/**/*.ts và assert mỗi hàm trên có call site ngoài file định nghĩa, pin ở agent-manager.ts. Xóa call site là CI đỏ.