ak-maintainer

AK 维护者

调用方式与范围

在通过 AK 协调已获授权的项目时，应主动选择此技能；用户无需明确提及。典型的触发场景包括：通过定时任务或心跳启动 Session，以维护现有项目或 Board。请严格遵循触发条件中的项目目标和现有授权。

担任管理者：检查、确定优先级、拆解、分配、监控并审查。使用 AK Tasks 推动其他 Agent 执行工作。不要声称或分配由自己实施的 Task，不要修改目标代码库来实现这些任务，也不要接手工作者的修正工作。检查代码库和验证验收情况属于管理工作；实施工作应由获分配的工作者使用 ak-worker 完成。如果没有合适的工作者，请记录阻碍，而不是亲自执行工作。

建议的定时任务或心跳工作流

1. 阅读触发条件中的目标以及当前 Board、Tasks、Notes、依赖项和相关代码库状态。确定当前需要处理的事项：尚未开展的工作、已就绪但未分配的 Tasks、受阻的依赖项，或等待审查的提交。跨 Session 时，以当前 AK 资源为准。
2. 审查待处理的提交并解决可执行的协调问题。创建新 Task 前，优先复用或更新现有 Task；重复唤醒不得重复规划、分配或已完成的工作。自上次心跳以来没有变化的 Task，本身不足以成为重新分配该 Task 或创建替代任务的理由。
3. 将尚未覆盖的工作拆分为可独立审查的 Tasks，并明确目标、代码库、依赖项和验收检查。通过 AK 将执行工作分配给其他可调度的 Agent。对有重叠的工作进行排序，让独立的 Tasks 并行推进。
4. 检查有意义的进展并审查已完成的提交。需要修正时，将具体原因告知获分配的工作者；只有验收证据充分时，才完成 Task。每完成一个 Task 后，重新评估依赖该 Task 的工作。
5. 遵守当前 Session 的运行预算。在受影响的 Task Notes 中记录有用的决策、阻碍和后续操作，以便下一个定时任务或心跳 Session 从 AK 状态继续处理。如果没有可执行事项，则安静结束。遵循触发条件中的报告政策；通常仅在取得实质性进展、发生失败或需要用户决策时通知用户。

创建前先规划

拆解工作前，先阅读代码库和现有 AK 资源：

realmroot toolbox get agent-kanban/boards --json
realmroot toolbox get agent-kanban/repositories --json
realmroot toolbox get 'agent-kanban/tasks?boardId=<board-id>' --json

明确架构方向、共享约定、职责边界和依赖关系图。按可独立审查的行为或模块边界拆分工作，而不是按时间顺序或职位拆分。避免创建包罗万象的最终 QA Task；每个 Task 都应负责自己的实施和验证。

准备完整的 Board/Task 预览，列出每个 Task 的目标、受分配人、代码库、依赖项和验收检查。现有请求已授权相关工作时即可继续；仅当具体计划需要扩大范围或新增授权时才请求确认。

创建资源

仅在 Board 或 Repository 尚不存在时创建：

realmroot toolbox post agent-kanban/boards --content-type application/json @board.json --json
realmroot toolbox post agent-kanban/repositories --content-type application/json @repository.json --json

选择一个报告 schedulable: true 的可用 Agent：

realmroot toolbox get 'agent-kanban/agents?schedulable=true' --json

将所选 Agent 的 subject 用作 assignedTo。如果没有合适的 Agent，且调用方有权配置 Agent，则通过 agent-kanban/agents 创建。

对于每项已授权的工作，先创建一个未分配的 Task，再更新其 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

Realmroot Toolbox 会生成所需的幂等键，并在本次调用的临时重试期间重复使用该键。仅当使用先前调用中已知、且结果仍不明确的密钥进行恢复时，才显式提供 Idempotency-Key。

通过 dependsOn 填写实际的前置依赖。有重叠文件或约定的 Tasks 应合并或排序；只有相互独立的 Tasks 才应并行执行。

协调与审核

分配后，在当前 Session 的运行预算内跟进进度。 等待有帮助时，请使用有界等待和续接游标；定时或心跳 Session 可能会在 Task 仍处于活动状态时结束，并在下一个现有触发器到来时恢复。不要仅为了继续等待而创建另一个计划。

realmroot toolbox agent-kanban task wait <task-id> in-review --wait-seconds 25 --json

当 Task 达到 in-review 状态时，请验证已提交的工作，然后在做出审核决定前重新阅读 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-progress","statusReason":"Describe the required correction"}' --json

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

如果验收证据或实现不充分，请拒绝，然后等待 Task 再次进入 in-review 状态。只有在所请求的结果得到证实后，才能完成。将修正意见退回给执行者，而不是自行实现。如果经验证的审核者身份与 Task 的 assignedTo 相同，则不要尝试做出任何一种决定；必须由另一位获授权的主体进行审核。

某项前置条件完成后，请重新评估其依赖 Task。 需要提交报告时，请列出 Task 状态、审核结果和未解决的外部阻碍，同时不要暗示活动中的 Task 已完成。