Chuyển tới nội dung chính

Lập kế hoạch bằng AI Planner

Khi yêu cầu quá lớn để làm trong một task và Planner đã có LLM ở chế độ live, trang này hướng dẫn biến một câu ý tưởng thành cây Epic/Task rồi rà soát trước khi apply.

Đối tượng: Product Owner / Tech Lead / member khi yêu cầu lớn cần phân rã. Điều kiện: Planner cần AGENTBOARD_LLM_MODE=live + key + model (ở mode replay sẽ lỗi [LLM VCR ERROR] — liên hệ sysadmin).

Luồng 2 chặng (tự động)​

  1. Vào Planner View → New Plan, nhập ý tưởng (ví dụ "Tích hợp cổng thanh toán VNPay qua QR Code"). Bật research codebase nếu muốn Planner đọc repo trước — chậm hơn nhưng chất lượng cao hơn nhiều.
  2. Chặng 1 — nghiên cứu: server đọc trực tiếp thư mục repo của Space (liệt kê cây thư mục tầng trên, tóm tắt package.json + README) và ghi báo cáo vào <repoPath>/.board/plan-research.md. Không có repo (hoặc đọc lỗi) thì dùng ghi chú dự phòng, không chặn chặng 2. Muốn bỏ qua hẳn: options.skipResearch: true.
  3. Chặng 2 — phân rã: server ghép ý tưởng + tên Space + báo cáo nghiên cứu rồi gọi LLM với Structured Outputs — ra cây kế hoạch Epic → Story → Task kèm dependsOn, priority, persona, estimate, acceptanceCriteria.
Planner không tự tìm Wiki ở chặng 2

Request gửi cho LLM chỉ gồm ý tưởng + tên Space + báo cáo research — không kèm kết quả semantic search Wiki. Vì vậy hãy nạp tài liệu kiến trúc vào Arkon Wiki trước khi plan để tri thức đó đi vào từng task lúc agent chạy (xem Wiki hai chiều), và tự đối chiếu draft với tài liệu ở bước tinh chỉnh bên dưới.

Tạo plan qua API (trả 201 với draft gồm projectId, prompt, planTree, researchNotes):

curl -X POST http://<host>/api/projects/<spaceId>/plans \
  -H 'Content-Type: application/json' \
  -d '{"prompt": "Tích hợp cổng thanh toán VNPay qua QR Code"}'

Thiếu prompt → 400 {"error": "Field \"prompt\" is required and must be a non-empty string"}; sai Space → 404 {"error": "Project '<id>' not found"}.

Planner cần gì từ sysadmin​

BiếnÝ nghĩa
AGENTBOARD_LLM_MODE=liveBật gọi LLM thật (mặc định replay chỉ đọc cassette, prompt mới nào cũng miss)
AGENTBOARD_LLM_API_KEY (hoặc OPENAI_API_KEY) + AGENTBOARD_LLM_MODELKey và model cụ thể (ví dụ gpt-5.2); có key mà thiếu model → lỗi [LLM ERROR]
AGENTBOARD_LLM_BASE_URLTùy chọn, mặc định endpoint OpenAI
Chưa có key live thì draft vẫn ra, nhưng là mẫu cố định

Không key live, server dùng generator mẫu xác định: 1 Epic → 1 Story → 2 task (task frontend dependsOn task backend). Đủ để thử flow Apply, không đủ để plan thật.

Tinh chỉnh — bước quan trọng nhất​

Đừng apply plan chưa đọc

Mở PlanDraftEditor và sửa: tiêu đề, mô tả, acceptance criteria, persona phụ trách (@architect / @coder / @reviewer / @qa / @devops), thêm/xoá task, sửa quan hệ phụ thuộc.

Hai điểm kỹ thuật cần nhớ khi sửa:

  • dependsOn khớp theo id hoặc tiêu đề (không phân biệt hoa thường). Tham chiếu tới task không tồn tại bị bỏ lặng — rà lại cây trước khi apply. Tự tham chiếu chính mình cũng bị bỏ.
  • Persona lạ bị chuẩn hoá về coder. Muốn task do @qa làm thì gán đúng handle trong 5 persona.

Muốn sinh lại một nhánh bằng AI (targetType: epic):

curl -X POST http://<host>/api/plans/<draftId>/regenerate-branch \
  -H 'Content-Type: application/json' \
  -d '{"targetId": "<epicId>", "targetType": "epic"}'

Thiếu trường → 400 {"error": "Fields \"targetId\" and \"targetType\" (epic|story) are required"}; sai id Epic → 404 {"error": "Epic with id '<id>' not found in plan tree"}.

Apply Plan (một transaction duy nhất)​

Bấm Apply Plan (POST /api/plans/:id/apply) — toàn bộ diễn ra nguyên tử:

  • INSERT tất cả record tasks (Epic → Story → Task, đầy đủ parentId);
  • INSERT quan hệ blocks vào work_item_links từ dependsOn đã khớp;
  • Đánh dấu draft applied;
  • Mirror bản spec từng Epic (Architecture Spec: <tên Epic>, slug spec-<epic-key>) lên Arkon Wiki.
curl -X POST http://<host>/api/plans/<draftId>/apply
{
  "success": true,
  "planDraftId": "<draftId>",
  "projectId": "<spaceId>",
  "createdTasksCount": 12,
  "epicIds": ["…"],
  "storyIds": ["…"],
  "taskIds": ["…"],
  "linksCount": 4,
  "arkonMirrored": true
}

Lỗi ở bước ghi task/link → rollback sạch, Board không có task nửa vời. Mirror Wiki là suy biến mềm: Arkon hỏng thì apply vẫn thành công với arkonMirrored: false.

Kết quả applyÝ nghĩa
Draft không tồn tại404 {"error": "Plan draft '<id>' not found"}
Draft đã apply rồi400 {"error": "Plan draft '<id>' has already been applied"} — mỗi draft apply đúng 1 lần
dependsOn tạo vòng (A→B→A)500 {"error": "Failed to apply plan: Circular dependency detected in plan tree: …"} — sửa trong PlanDraftEditor rồi apply lại
Planner lỗi [LLM VCR ERROR] Cassette cache miss?

AGENTBOARD_LLM_MODE đang là replay (mặc định). Cần sysadmin đặt live + key + model. Xem Xử lý sự cố.

Checklist tự xác minh​

  • Board có đủ số thẻ (createdTasksCount); Tree View thấy đúng cấu trúc cây; tab Wiki có trang spec.
  • Task phụ thuộc (ví dụ FE chờ BE) có badge blocked.
  • Nạp tài liệu kiến trúc vào Arkon Wiki trước khi plan — tri thức đó đi vào worktree lúc agent chạy. Xem Nạp tài liệu vào Wiki.
  • Apply lại cùng draft → 400 đã applied; Board không nhân đôi task.

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

Đi tiếp: Tạo task & chạy agent · Task phụ thuộc & Task Group

Cập nhật lần cuối vào