Dùng Wiki hai chiều

Khi đã có tài liệu trên Wiki của Department gắn với Space, trang này hướng dẫn cách tri thức tự đi vào worktree của agent và cách đề xuất ghi ngược lại Wiki qua khâu duyệt.

Đối tượng: member muốn agent tuân thủ convention team mà không copy-paste, và muốn tri thức mới quay về Wiki. Điều kiện: Space đã link Department Arkon (chưa link thì chiều đọc trả rỗng, xem Xử lý sự cố).

Hai chiều nhìn một mạch

Chiều đọc — tri thức tự động đi vào công việc

Trước khi agent chạy, server tìm semantic search trên Arkon Wiki của Department gắn với Space (câu truy vấn là tiêu đề + mô tả task, lấy tối đa 5 trang, deadline 8 giây), rồi ghi vào worktree:

<worktree>/.board/wiki/
├── INDEX.md                    ← mục lục các trang đã bơm
├── coding-standards.md
└── payment-architecture-adr.md

.board/task.json chỉ agent đọc INDEX.md trước khi viết code. Nhờ vậy agent tuân thủ convention của team mà bạn không phải copy-paste.

Kiểm tra trong worktree của task đang chạy: .board/wiki/INDEX.md phải tồn tại và liệt kê trang (- [Tên trang](./ten-trang.md) — tóm tắt). Chiều đọc là suy biến mềm — Arkon vắng, Space chưa link hay quá deadline đều không báo 500, chỉ ghi INDEX.md với đúng một dòng:

No wiki pages available for this space.

Tab Wiki trống / INDEX.md ghi "No wiki pages available"?

Arkon không kết nối được và suy biến mềm đang che nó. Xem Wiki tắt lặng — 4 dấu hiệu.

Chiều ghi — agent đề xuất, người duyệt

Agent ghi wikiProposals[] trong .board/result.json (mỗi đề xuất bắt buộc có contentMd không rỗng; kèm slug/title/note tùy chọn):

{
  "success": true,
  "summary": "Thêm webhook VNPay + retry policy",
  "filesChanged": ["src/payment/vnpay.ts", "src/payment/vnpay.test.ts"],
  "wikiProposals": [
    {
      "contentMd": "# ADR-014: Retry policy cho VNPay webhook\n\nQuyết định: retry 3 lần, backoff…",
      "note": "Sinh ra từ task PAY-101"
    }
  ]
}

Server ingest thành draft Arkon sau khi task complete — gửi dưới token của chính persona viết (contributor, không tự duyệt được), giữ vết taskId/runId để truy ngược. result.json sai schema thì vào vòng repair (tối đa 2 vòng) trước khi kết luận. Bạn vào Wiki View → Review Queue xem draft; duyệt do admin làm (xem Duyệt Wiki draft).

Đề xuất draft tay qua API (thiếu contentMd → 400 {"error": "contentMd is required"}):

curl -X POST 'http://<host>/api/wiki/drafts?projectId=<spaceId>' \
  -H 'Content-Type: application/json' \
  -d '{"title": "ADR-014: Retry VNPay", "contentMd": "# ADR-014…", "note": "Sinh ra từ task PAY-101"}'

Nạp tài liệu gốc vào Wiki làm bên Arkon :3119: Knowledge → Upload Source → pipeline MRP phân tích → bạn Approve Plan → Arkon biên dịch cây trang liên kết chéo. Chi tiết: Nạp tài liệu vào Wiki.

Checklist tự xác minh

• Trong worktree của task đang chạy, .board/wiki/INDEX.md tồn tại và không rỗng.
• Sau khi agent xong, Review Queue có draft mới từ wikiProposals.
• INDEX.md rỗng với đúng dòng No wiki pages available for this space → biết ngay là Space chưa link Wiki, không phải agent lười đọc.

Gặp lỗi? Xem Xử lý sự cố.

Đi tiếp: Nạp tài liệu vào Wiki · Duyệt và approve