Khái niệm cốt lõi
Mười ba khái niệm dưới đây xuất hiện trong mọi trang khác của tài liệu này. Mỗi khái niệm gồm định nghĩa, vì sao nó tồn tại, và đường đi sâu — đọc một lượt ở đây rồi khỏi phải đoán nghĩa khi đọc bài thao tác.
Đối tượng: mọi vai trò, đọc trước khi thao tác lần đầu. Đối chiếu chữ trên giao diện: giao diện Board hiển thị tiếng Anh, tài liệu này viết tiếng Việt — tên gốc ghi kèm trong ngoặc ở mỗi mục.
1. Space (Space / projectId)
Đơn vị dự án, và cũng là đơn vị phân quyền. Một Space gắn với một repo (repoPath) và một nhánh gốc (baseBranch). Quyền của bạn luôn là quyền trong một Space cụ thể, không phải quyền toàn hệ thống.
Vì sao: nếu quyền cấp toàn hệ thống thì thêm một dự án là mở quyền cho tất cả; fail-closed theo Space nghĩa là chưa được cấp thì mặc định 403.
→ Phân quyền Board · Tạo Space & mời thành viên
Trong API, tham số vẫn tên projectId (GET /api/tasks?projectId=<spaceId>) — cùng một thứ với Space trên giao diện.
2. Task và 4 loại của nó (Task)
Đơn vị việc. Bốn loại: epic · story · task · bug. epic và story là cấp gom nhóm (xem ở Tree View), task và bug là việc agent thực sự chạy.
Trường quan trọng nhất là description: agent chỉ biết những gì bạn viết trong đó, cộng với tri thức từ Wiki. Mô tả chung chung là nguyên nhân số một của kết quả tệ.
→ Tạo task & chạy agent · Máy trạng thái task
3. Bốn cột của bảng (Board columns)
backlog → in-progress → review → done. Agent chỉ chạy khi task ở in-progress. Agent xong việc không tự đặt done — server chuyển task sang review, chờ thẩm định.
Vì sao chỉ 4 cột: mỗi cột tương ứng một trạng thái mà hệ thống thực sự xử lý khác nhau, không phải một bước quy trình do người tự đặt ra.
4. Group (Task Group)
Tập task chạy cùng nhau: bấm chạy một lần, nhiều task khởi động song song, có thanh điều chỉnh mức song song. Group cũng có thể dừng và lưu trữ theo cả nhóm.
Vì sao: một yêu cầu thật thường tách thành 5–10 task; không có Group thì phải bấm chạy từng cái và tự nhớ cái nào phụ thuộc cái nào.
5. Worktree cách ly (useWorktree)
Mỗi lần chạy, agent làm việc trong một git worktree riêng tên agent/<task-key> — một bản checkout độc lập của repo. Code bạn đang viết dở trong thư mục làm việc của mình không bị đụng tới, và nhiều agent chạy song song không tranh nhau file.
Vì sao đây là bắt buộc, không phải tùy chọn cho tiện: đó là ranh giới an toàn duy nhất giữa "agent thử nghiệm" và "nhánh chính của team".
6. Agent CLI và Agent Profile (agentType / Agent Profile)
Agent CLI là công cụ thực sự chạy việc: claude, codex, copilot… Bạn chọn qua trường agentType của task; CLI phải có trên PATH của máy chủ, không thì task tạo được nhưng không chạy.
Agent Profile là bộ cấu hình tái dùng cho một kiểu agent: tên hiển thị, vai trò, danh sách skills và systemPrompt riêng, có thể đặt một cái làm mặc định. Thay vì dán lại cùng một đoạn hướng dẫn vào mọi task, bạn cấu hình một lần rồi gán.
7. Persona (persona token)
Năm danh tính agent chuẩn mà hệ thống cấp token riêng cho: architect · coder · reviewer · qa · devops. Khi bật persona token, mỗi lần chạy agent mượn danh tính persona tương ứng để đọc/ghi tri thức, thay vì dùng chung một token toàn quyền.
Vì sao: token dùng chung thì mọi vết ghi vào Wiki đều vô danh và không thu hồi được riêng lẻ. Persona cho phép trả lời "ai (cái gì) đã ghi dòng này".
Persona khác Agent Profile: persona là danh tính để phân quyền, Agent Profile là cấu hình cách làm việc.
8. Thẩm định 3 tầng và reviewState
Task vào cột review sẽ đi qua các trạng thái: peer-review (checks + Reviewer Agent) → human-gate (chờ người) → approved hoặc rejected / changes-requested; gặp xung đột git thì merge-conflict.
Ba tầng, mỗi tầng bắt một loại lỗi khác nhau: máy bắt lỗi cú pháp và test, Reviewer Agent bắt lỗi logic và quy ước, con người bắt lỗi "việc này không nên làm".
→ Máy trạng thái task · Duyệt và approve
9. Human Gate
Chốt cuối: chỉ actor có type === 'human' mới approve được. Service token phân giải về system và bị từ chối — không có scope nào, cờ nào, header nào bypass được. Kể cả CI cũng không approve thay người.
Vì sao thiết kế cứng thế: một cổng duyệt có đường tránh thì trong thực tế nó luôn bị tránh.
→ Vì sao Human Gate không bypass được · Pentest Human Gate
10. Dependency gating (blocks / dependsOn)
Task A chặn task B thì B không chạy được cho tới khi A done. Việc gác nằm ở server, không phải nhắc nhau trong chat. Kế hoạch tạo vòng phụ thuộc (A→B→A) bị từ chối ngay lúc apply.
→ Dependency gating · Task phụ thuộc & Group
11. Plan và AI Planner (Plan / Apply Plan)
AI Planner đọc yêu cầu (và tùy chọn khảo sát codebase) rồi sinh plan draft: cây epic → story → task kèm quan hệ phụ thuộc. Bạn sửa trong trình soạn plan rồi Apply Plan — lúc đó toàn bộ cây task mới được tạo, nguyên tử: hoặc tạo hết, hoặc không tạo gì.
Vì sao có bước draft: kế hoạch sai thì sửa một chỗ trong draft rẻ hơn nhiều so với xoá 20 task đã tạo.
12. Wiki, Skill, Source (Arkon)
Ba thứ khác nhau, hay bị gọi lẫn:
| Là gì | Ai/cái gì dùng | |
|---|---|---|
| Wiki | Trang tri thức đã duyệt của dự án (kiến trúc, quy ước, quyết định) | Bơm vào worktree mỗi lần agent chạy; người cũng đọc |
| Skill | Năng lực đóng gói mà agent gọi được (quy trình, công cụ, mẫu) | Agent |
| Source | Tài liệu thô bạn nạp vào (tải file hoặc trỏ URL), qua bước trích xuất rồi mới thành tri thức | Là đầu vào của Wiki, không phải Wiki |
Wiki chạy hai chiều: bơm vào trước khi chạy, và agent xong việc thì đề xuất tri thức mới quay về dạng draft chờ người duyệt — không tự ghi thẳng vào Wiki.
→ Nạp tài liệu vào Wiki · Wiki hai chiều · Board ↔ Wiki ↔ Skills ↔ MCP
13. MCP và lease 30 giây
MCP (Model Context Protocol) là đường agent gọi tới tri thức Arkon. Trước mỗi lần chạy, hệ thống bơm .mcp.json vào worktree và thu hồi sau khi chạy xong — token không nằm lại trong repo.
Lease 30 giây là cơ chế chống mất việc: một lần chạy giữ "giấy phép" phải gia hạn liên tục. Server sập giữa lúc agent chạy thì lease hết hạn, lần khởi động sau hệ thống đưa task về idle và ghi một Activity system_recovery — worktree vẫn còn nguyên, bấm chạy lại là tiếp tục. Không mất việc, và cũng không có hai agent cùng chạy một task.
→ Kiến trúc tổng thể · Khi agent trễ
Bước tiếp theo: Lần đầu đăng nhập để dùng những khái niệm này trên hệ thống thật · Phân quyền Board để biết vai trò của bạn làm được gì · AgentJira là gì nếu bạn nhảy thẳng vào trang này