agent-kanban

Agent Kanban v2 已分配的 Agent

使用已附加到 Agency Agent 的 Realmroot 身份。切勿运行已移除的 ak CLI，也不要创建 AK 凭据、Machines、运行时 Sessions、邮箱状态、签名密钥或 Agent 角色。

任务生命周期

1. 使用通用 Toolbox 资源操作读取 Task：

   realmroot toolbox get agent-kanban/tasks/<task-id> --include --json
   

   将返回的表示视为权威信息。Task PATCH 操作会自行执行乐观并发检查；如果返回 409，请重新读取 Task，再决定是否重试。

2. 在更改目标仓库前先认领任务：

   realmroot toolbox post agent-kanban/tasks/<task-id>/claims --json
   

   如果认领被拒绝，请停止操作，不要修改仓库。只有当前分配给该 Task 且身份已验证的 Realmroot Agent 才能认领它。

3. 将有用的进展记录为 Task Note 资源：

   realmroot toolbox post agent-kanban/tasks/<task-id>/notes \
     --content-type application/json \
     '{"detail":"Implemented the parser and verified malformed input."}' --json
   

   Realmroot Toolbox v0.5.0 或更高版本会生成所需的幂等键，并在本次调用的临时重试中重复使用该键。只有在使用先前调用中已知的密钥进行恢复，且该调用结果仍然未知时，才显式提供 Idempotency-Key。

4. 完成工作并运行能验证更改行为及边界的最小检查。将仓库工作放在可供审查的分支上。对于需要身份验证的 GitHub 命令，请使用 Realmroot 的 GitHub Resource，例如 realmroot exec github -- git push 或 realmroot exec github -- gh ...。

5. 发布一条最终备注，说明结果、确切的检查以及任何尚未解决的阻碍，然后提交 Task 以供审查：

   realmroot toolbox get agent-kanban/tasks/<task-id> --include --json
   realmroot toolbox patch agent-kanban/tasks/<task-id> \
     --content-type application/merge-patch+json \
     '{"status":"in-review","pullRequestUrl":"https://github.com/owner/repo/pull/123"}' --json
   

   如果 Task 没有关联的 pull request，请提交显式的空表示：

   realmroot toolbox patch agent-kanban/tasks/<task-id> \
     --content-type application/merge-patch+json \
     '{"status":"in-review"}' --json
   

Agency 工作 Session 停止前，必须将其认领的 Task 提交以供审查。如果工作无法继续，请在最终 Task Note 中说明阻碍并提交当前状态；不要让不活跃的 Session 保持为 in_progress。

已发布的命令

对 AK 资源使用 Toolbox 通用的动词优先操作：

realmroot toolbox get agent-kanban/tasks/<task-id> --json
realmroot toolbox get agent-kanban/tasks/<task-id>/notes --json
realmroot toolbox post agent-kanban/tasks/<task-id>/notes \
  --content-type application/json @note.json --json
realmroot toolbox post agent-kanban/tasks/<task-id>/claims --json
realmroot toolbox patch agent-kanban/tasks/<task-id> \
  --content-type application/merge-patch+json \
  '{"status":"in-review"}' --json
realmroot toolbox agent-kanban task wait <task-id> in-review --wait-seconds 25 --json

task wait 是唯一由 AK 生成的资源优先便捷命令。不要使用已移除的 task claim、task release、task review、task reject、task complete 或 task cancel 别名。

如果服务器契约已部署，但 Toolbox 仍显示这些已移除的别名，请刷新一次其缓存的操作清单：

realmroot toolbox sync agent-kanban

如果生成的命令请求格式不清楚，请检查契约，不要猜测标志：

realmroot toolbox patch agent-kanban/tasks/<task-id> --generate-body

分配会直接启动 Enbor Session。其初始提示词会提供 Task ID 和确切的 AK Context ID。每次 Toolbox 操作都使用该 Context，然后先读取 Task 再采取行动。使用自己已附加的 Agent 身份认领 Task；切勿写入或猜测 Session ID。AK 的 Session 注解会记录创建回执，而 Claim 会记录经过验证的执行身份。

审查被拒后，反馈会发送到同一个 Session。重新读取 Task 和 Notes，在现有 Claim 下继续工作，并在完成后重新提交审查。 完成和取消操作会关闭关联的 Session。收件箱消息不是启动或继续工作的机制。

对于个人 Owner ID 编码为 user:<subject-id> 的历史业务引用，Context ID 为 <subject-id>；组织 Owner ID 则保持原样。尚未实现延迟调度。

故障处理

• 401 或无效的 DPoP：Realmroot 权限不可用；不要创建备用凭据。
• 403：经过验证的执行者或授权不具备所需权限；更改请求正文无法授予权限。
• 409：重新读取受影响的资源，并根据其当前状态作出判断；不要盲目重放冲突的状态转换。
• 412：条件删除使用了过期的资源 ETag；先重新读取，再决定是否仍应删除。
• 429 或 503：遵循 Retry-After。Task PATCH 的结果未知后，请重新读取其当前表示，再决定是否重试。Claim 创建受幂等键保护。