large-task-orchestrator

大型任务 driver

这是流程类 Skill，仅在用户显式调用 $large-task-orchestrator 时运行。它只接管已经通过 large-task-planning v2 校验的计划：脚本是控制面，Worker、Validator 和异常时的 Judge 都是经 bb-dispatch 创建的短生命周期 BB 线程。

开始前阅读相邻的 large-task-planning 计划格式、bb-model-routing 和联合设计。计划 JSON 与 Git 是权威状态；每个 (仓库, 计划) 的 .local/large-task-orchestrator/<topic-slug>/ 保存可回看的运行事实。

生命周期用法

1. 先确定用户指定的计划；未指定时只能使用当前仓库唯一的计划。阅读仓库规则、SPEC.md、STATUS.md，检查 分支、git status --short 和 git worktree list，保留并发改动。然后只对这个 (仓库, 计划) 查询状态：

python3 <orchestrator-skill>/scripts/large_task_driver.py status \
  --plan <topic>/agent/plan.json --stories-dir <topic>/agent/stories

1. 若 status 显示 driver 仍在运行，把 completed/total、每张 in-progress Story 的阶段、线程 ID 和难度翻译给 用户；不要自己运行主循环，也不要读线程全文。若 last_stop 非空或有 blocked Story，说明事实，并只向用户索取 继续所需的最小决定。需要停止时使用 stop [--wait]；它只在当前 run_once 结束后退出，不会中断 BB 线程。

2. 若没有运行中的 driver，用 start 启动指定计划。start 自己会先执行计划校验和 bb-dispatch --dry-run， 然后在新 session 中派生后台 run；本轮到此结束，向用户报告 pid、日志路径和后续状态命令。不要在本轮改用 前台 run 等待结果。

python3 <orchestrator-skill>/scripts/large_task_driver.py start \
  --plan <topic>/agent/plan.json \
  --stories-dir <topic>/agent/stories \
  --repository <repo-root> \
  --environment <bb-environment-id>

同一计划已有存活 pid 时 start 以退出码 4 拒绝重复启动；陈旧 pid 自动覆盖。不同仓库或同一仓库不同计划使用 独立的状态目录与锁，可以同时运行。计划中的 owner 保留 Worker 线程 ID；遗失计划本地状态时，driver 会从计划 和 BB 线程恢复。仅在排障或定时任务需要前台单次推进时才用 run 或 start --foreground 加 --once。

正常循环与异常

正常路径由 driver 选择 ready frontier、领取 Story、派 Worker、核对 Git 改动事实，再派 Validator 判断 Acceptance、Story 边界和 Worker 路径归属；通过后更新 Handoff、刷新投影并只 checkpoint Validator 确认归属的 Worker 路径。

发生 Worker blocked/failed、线程 error、待处理 interaction、空改动、报告无法解析或 Validator 多轮失败时，driver 才派 complex Judge。Judge 只能选择 retry、escalate、patch、 block、replan 或 stop。block 后继续其他 ready Story；replan 后重新校验计划；stop 或没有 ready Story 时退出并把最小原因写到 stderr。

不要手动篡改 driver 状态文件、Story 的 owner 或 Handoff 来跳过这些状态转换。要处理停下原因，先读 driver status --json、计划状态和该计划的 jsonl；只有在既定 Goal 和授权内作出必要处理后，才在下一次本 Skill 调用时 按上述流程重新 start。需要凭据、权限、外部/破坏性动作、显著成本或稳定边界变更时才请用户决定。