Nối Board với Wiki, Skills và MCP

Trang này hướng dẫn gắn tri thức Wiki với vòng đời task Board, quản lý AI Skills và kết nối Claude qua MCP. Đọc khi bạn đã nạp tài liệu vào Wiki và muốn agent lẫn nhân sự dùng chung tri thức đúng phạm vi.

Đối tượng: knowledge role phối hợp với team Board; nhân sự dùng Claude với tri thức công ty. Điều kiện: đã quen Nạp tài liệu & duyệt Wiki.

Vòng đời tri thức gắn với Board

• Chiều Board đọc: server semantic-search Wiki của Department gắn Space → ghi .board/wiki/INDEX.md + tối đa 5 trang vào worktree trước khi agent chạy (deadline 8s, tắt bằng AGENTBOARD_WIKI_CONTEXT=0).
• Chiều Board ghi: wikiProposals trong result.json → ingest thành draft Arkon sau task complete → bạn duyệt ở Wiki Review như draft thường.
• Nạp tài liệu kiến trúc vào Wiki trước khi team chạy Planner — Planner tìm semantic search trên đó nên chất lượng plan tăng rõ rệt. Chi tiết phía Board: Wiki hai chiều.

Kiểm chứng nhanh phía Board: task đang chạy có .board/wiki/INDEX.md không rỗng (không phải "No wiki pages available"); sau task xong có draft mới trong Review Queue.

Tắt bơm Wiki khi cần

Bơm tri thức vào worktree tắt bằng AGENTBOARD_WIKI_CONTEXT=0 (mặc định bật). Tắt khi worktree chật hoặc bạn muốn agent chạy "chay" để đối chứng chất lượng có/không tri thức.

Deep wiki 404 là đúng thiết kế khi cờ tắt

Tám route sâu (revisions, rollback, graph, lint, branches, branches/:id, merge, close) trả 404 (không phải 403) khi AGENTBOARD_WIKI_DEEP_UI tắt — bề mặt coi như không tồn tại. GET /api/wiki/pages + GET /api/wiki/drafts vẫn 200 bình thường (tắt = Phase 1).

AI Skills — gói tri thức cho agent

• Upload gói skill (.zip có SKILL.md, versioned), phân phối theo department.
• Contributor đề xuất, reviewer duyệt (Approve & Merge / Reject).
• Theo dõi ở /skills: MyContributions (của bạn) / PendingContributions (chờ duyệt).

Danh tính thật & token persona (Chặng 0B)

• User tokens (AGENTBOARD_ARKON_USER_TOKENS=1): lời gọi Arkon mang email chính user — hết thời audit log ghi admin@arkon.local cho thao tác của người. User chưa xác thực không sinh token.
• Persona tokens (AGENTBOARD_ARKON_PERSONA_TOKENS=1): đề xuất wiki của agent ký @persona theo đúng task.persona (@architect / @coder / @reviewer / @qa / @devops). Tra nguồn gốc một trang ở wiki_draft_origins (persona, actor_id, run_id). Persona không tự duyệt draft của chính nó — kể cả draft nó vừa tạo.
• MCP per-run (AGENTBOARD_ARKON_MCP=1): credential bơm vào worktree lúc run, thu hồi sau run (kể cả khi agent lỗi).

Đừng nhầm token MCP với JWT SSO

Token MCP (POST /api/employees/{id}/token) chỉ dùng được ở /mcp/; đem gọi REST Arkon → 401. Đề xuất wiki của agent đi bằng JWT qua POST /api/auth/sso. Nhầm hai loại này làm mọi đề xuất wiki thất bại khi bật cờ.

MCP cho người dùng Claude

Nhân sự kết nối Claude Desktop / Claude.ai qua connector https://<arkon-host>/mcp (OAuth 2.1 + PKCE, không copy token tay). Tool agent được dùng theo scope token:

Nhóm	Tool
Wiki	search_wiki, read_wiki_page, list_wiki_pages
Drill-down nguồn	get_source, get_source_outline, get_source_pages, list_sources
Edit workflow	propose_wiki_edit, edit_wiki_page, list_pending_drafts, review_draft, approve_draft, reject_draft
Discovery	list_knowledge_types, get_knowledge_type_docs

MCP token cá nhân: tự phục vụ ở Profile → McpTokenCard; admin cấp/thu hồi ở Employees (POST/DELETE /api/employees/{id}/token). Đổi role/dept/revoke hiệu lực ngay (verify mỗi request, không cache).

Việc bạn KHÔNG làm được (và vì sao)

Bạn thử	Kết quả	Vì sao
Contributor duyệt draft / direct edit	bị chặn	Cần wiki:write:all (manager/admin)
Persona duyệt draft do chính nó đề xuất	bị chặn	Bất biến 0B: người đề xuất không tự duyệt
Đọc Wiki department khác	không thấy nội dung	Cô lập scope; admin mới thấy all

Không đổi model embedding sau khi đã nạp tài liệu

Vector khác số chiều sẽ làm hỏng search. Muốn đổi: chạy Online Re-embed Migration (admin, atomic flip, không downtime) và verify Diagnose #6 trước khi re-embed.

Checklist tự xác minh

• Biết khi nào gọi admin: đổi embedding model, re-index, cấp token, MRP kẹt, audit.denied tăng đột biến (Dashboard).
• Kết nối thử Claude qua /mcp và search_wiki ra trang trong dept mình; trang dept khác không lộ nội dung.

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

Đi tiếp: Nạp tài liệu & duyệt Wiki · Wiki hai chiều phía Board · Xử lý sự cố