Task phụ thuộc và Task Group

Khi các task có ràng buộc thứ tự hoặc cần chạy song song trong giới hạn, trang này hướng dẫn dùng dependency gating, chip subtask và Task Group với maxConcurrency.

Đối tượng: member chạy nhiều task có ràng buộc thứ tự hoặc muốn chạy song song có giới hạn. Điều kiện: bạn là member trở lên của Space; quan hệ phụ thuộc chỉ nối 2 task cùng Space.

Dependency gating — task chờ task

Ví dụ: PAY-101 (Backend: API tạo giao dịch QR) blocks PAY-102 (Frontend: màn hình quét QR).

Khi kích hoạt, Gating Engine đọc work_item_links: task không blocker thì chạy, task bị block giữ ở backlog kèm Activity "Task bị khoá do đang chờ PAY-101 hoàn thành".
Một blocker được coi là xong chỉ khi columnId là done.
Không bỏ chặn non: khi BE xong, PAY-101 mới sang cột review — code chưa merge vào main. Hệ thống tuyệt đối không mở PAY-102 lúc này (agent FE sẽ đọc mã nguồn cũ).
Bỏ chặn khi done: approve PAY-101 → merge vào main → done → PAY-102 tự mở khoá và chạy, kéo code BE mới nhất từ main.
Lưới bảo hiểm hai tầng: microtask mở chặn ngay khi blocker done, sweeper 15s quét lại task bị block, chống mất event. Mở chặn chỉ phát sự kiện task_unblocked — task không tự chạy, bạn bấm Run.

Thêm / xem / gỡ quan hệ phụ thuộc

Thêm quan hệ (linkType là blocks, is_blocked_by hoặc relates_to):

curl -X POST http://<host>/api/tasks/<taskId-PAY-101>/links \
  -H 'Content-Type: application/json' \
  -d '{"targetTaskId": "<taskId-PAY-102>", "linkType": "blocks"}'

Lần đầu trả 201 với link vừa tạo; link đã tồn tại trả 200 kèm header Idempotent-Replay.

Bạn gọi	Kết quả	Vì sao
Thiếu `targetTaskId`	`400 {"error": "targetTaskId is required"}`	Chưa chỉ task đích
`linkType` lạ	`400 {"error": "linkType must be one of: blocks, is_blocked_by, relates_to"}`	Chỉ 3 loại quan hệ
Tự link chính mình	`400 {"error": "Cannot link a work item to itself"}`	Cấm tự phụ thuộc
Task đích không tồn tại	`404 {"error": "target task not found"}`	Sai id đích
Hai task khác Space	`400 {"error": "Cross-project linking is not allowed. Both tasks must belong to the same project."}`	Phụ thuộc không xuyên Space
Run / kéo sang `in-progress` khi còn blocker	`400 {"error": "Cannot run task: blocked by unresolved tasks: [...]", "blockers": [...]}`	Gating chặn — xong blocker rồi chạy lại

Xem và gỡ:

curl http://<host>/api/tasks/<taskId>/links
curl -X DELETE http://<host>/api/tasks/<taskId>/links/<linkId>

Vì sao thiết kế vậy? Xem Vì sao task chỉ mở khi blocker done.

Gating chặn ở hai điểm, không chặn ở group drain

POST /api/tasks/:id/run và PATCH /:id sang in-progress đều kiểm tra blocker. Hàng đợi Task Group đẩy task con theo thứ tự pending mà không kiểm tra lại gating — đừng nhét cặp BE→FE phụ thuộc nhau vào cùng một group, hoặc xếp chúng ở group khác nhau.

Chip subtask trong tab Comments

Mở task cha → tab Comments → mỗi comment từng sinh subtask hiện một hàng chip ([mã] tiêu đề @persona).
Bấm chip → nhảy thẳng tới task con (mở được cả thẻ Backlog).
Chip đọc từ metadata.spawnedSubtasks server đã ghi lúc tạo comment — không suy từ nội dung comment.

Phân biệt hai cách có task con:

	Mention-batch (từ comment)	Tạo tay
Cách tạo	Gõ `@persona <việc>` trong Comments	New Task / API rồi gán `parentId`
Quan hệ cha-con	Tự gán `parentId` + `externalSource: mention`	Bạn tự gán
Trạng thái ban đầu	`backlog` / `idle`, không tự chạy	Do bạn chọn
Giới hạn	≤5/comment, 1 transaction, 6 luật rớt (xem Tạo task & chạy agent)	Ràng buộc hierarchy chung (tối đa 3 tầng)

Task Group — chạy song song có trần

New Group (phím G) → điền title, priority, repoPath, baseBranch. Group cần 2–20 task con (children ít hơn → 400 children must be an array with at least 2 items; nhiều hơn → 400 children must have at most 20 items).
Đặt maxConcurrency bằng ParallelismSlider — trần số agent chạy đồng thời trong group (1 đến số task con, mặc định 2; ngoài khoảng → 400 maxConcurrency must be between 1 and N).

Mỗi agent là một process CLI + một worktree

maxConcurrency=8 trên máy 8GB RAM sẽ hết bộ nhớ. Bắt đầu từ 2–3.

Thêm task con (children), hoặc bật autoRun để group tự chạy khi tạo. Task con kế thừa priority của group, agentType/useWorktree có mặc định theo Space, nhánh tự đặt group/<8-ký-tự>/<số>-<slug-tiêu-đề>.
Run Group (POST /api/groups/:id/run). Hàng đợi giữ đúng maxConcurrency task chạy đồng thời; task xong thì task kế tiếp trong hàng được đẩy vào. Cả group không lỗi thì tự sang review.
Stop Group (POST /api/groups/:id/stop) dừng toàn bộ task đang chạy trong group, task còn dở đánh failed.

Tạo group qua API:

curl -X POST http://<host>/api/groups \
  -H 'Content-Type: application/json' \
  -d '{
    "projectId": "<spaceId>",
    "title": "Checkout song song",
    "maxConcurrency": 2,
    "children": [
      {"title": "BE: API giỏ hàng"},
      {"title": "FE: trang giỏ hàng"}
    ]
  }'

Bạn gọi	Kết quả	Vì sao
Run group đang chạy	`409 {"error": "group is already running"}`	Mỗi group một hàng đợi tại một thời điểm
Run/Stop sai id	`404 {"error": "group not found"}`	Sai id group
Bấm dồn liên tục	`429 {"error": "Rate limited — wait a few seconds"}`	Đợi vài giây rồi kiểm tra lại

Checklist tự xác minh

Kéo task FE sang in-progress khi BE chưa done → bị chặn kèm thông báo rõ; BE done → FE tự mở.
Trong lúc group chạy, số task ở in-progress không bao giờ vượt maxConcurrency.
GET /api/tasks/<id>/links liệt kê đúng quan hệ vừa tạo; link trùng trả 200, không nhân đôi.

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

Đi tiếp: Tạo task & chạy agent · Vì sao task chỉ mở khi blocker done

Dependency gating — task chờ task​

Thêm / xem / gỡ quan hệ phụ thuộc​

Chip subtask trong tab Comments​

Task Group — chạy song song có trần​

Checklist tự xác minh​

Dependency gating — task chờ task

Thêm / xem / gỡ quan hệ phụ thuộc

Chip subtask trong tab Comments

Task Group — chạy song song có trần

Checklist tự xác minh