用途:AK Task 用于在 Agent Kanban 中管理单个任务,覆盖创建、指派、监控与评审流程,通过 Realmroot Toolbox 命令行操作。仅在用户明确要求 AK Task 或 Agent Kanban 任务时使用。
创建前准备:先用通用 Toolbox 读取解析看板、仓库与已有任务,例如 realmroot toolbox get agent-kanban/boards --json、realmroot toolbox get agent-kanban/repositories --json、realmroot toolbox get 'agent-kanban/tasks?boardId=<board-id>' --json。查找可用 Agent 用 realmroot toolbox get 'agent-kanban/agents?schedulable=true' --json,并以所选 Agent 的 subject 作为 assignedTo;若无合适 Agent 且已授权配置,可通过 agent-kanban/agents 创建。创建前需消除实质歧义,并向用户展示确切任务预览,包含标题、看板、仓库、指派人、描述、依赖与验收检查。
创建与指派:先创建未指派任务,再 patch 其 assignedTo 字段。命令为 realmroot toolbox post agent-kanban/tasks --content-type application/json @task.json --json,以及 realmroot toolbox patch agent-kanban/tasks/<task-id> --content-type application/merge-patch+json '{"assignedTo":"<realmroot-agent-actor-id>"}' --json。Toolbox 会生成所需幂等键并在本次调用的瞬时重试中复用;仅在结果未知的早期调用中恢复时,才显式提供已知 Idempotency-Key。任务体使用 lowerCamelCase 字段,如 boardId、title、description、repositoryId、labels、dependsOn、createdFrom、scheduledAt;创建时省略 scheduledAt,不支持延迟调度。PATCH 结果未知后应先重读任务再决定是否再次写入,不要另建任务。
监控:使用有界 task wait 调用,并将返回的 cursor 带入下一次调用,不要构建无界轮询循环,例如 realmroot toolbox agent-kanban task wait <task-id> in-review --wait-seconds 25 --json。每次有意义的状态变化后,用通用 GET 检查任务与 Notes。已取消任务为终态。
评审:任务进入 in-review 后,验证提交的工作,再重读任务后做评审决定,例如 realmroot toolbox get agent-kanban/tasks/<task-id> --include --json。拒绝时 patch status 为 in-progress 并给出 statusReason;通过时 patch status 为 done。若验收证据或实现不足则拒绝,然后等待新的 in-review 状态;仅在请求结果被证明后完成。若已验证的评审者 actor 等于任务 assignedTo,不得做任一决定,须由另一授权主体评审。取消非终态任务同样通过 patch status 为 cancelled 完成。
限制:不支持延迟调度;取消为终态;评审者不能与指派人相同;需避免无界轮询与重复创建任务。