autonomous-dispatcher

自主开发团队调度器

扫描 GitHub 问题并分派开发／评审任务。每次 cron 触发都会执行一次 dispatcher-tick.sh（单项目）或 dispatcher-multi-tick.sh（多项目）。完整状态机、各步骤语义和不变量见源代码仓库中的 docs/pipeline/——该目录是规范文件；本文档是 Agent 的调用约定。

前置条件

• gh 和 jq 位于 PATH 中。
• 使用本地后端时：设置 $PROJECT_DIR，使其指向项目根目录。每个项目各自配置 autonomous.conf（参见 scripts/autonomous.conf.example）。
• 使用多项目／远程后端时：配置 dispatcher.conf，声明 PROJECTS=()（参见 scripts/dispatcher.conf.example）。
• autonomous-dev.sh 和 autonomous-review.sh 需要具有执行权限（模式 100755）——已在上游恢复，并由 dispatcher-tick.sh 在每次 tick 时自动修复（#97）。

安全提示：此调度器会将 GitHub 问题内容作为输入处理。在公开仓库中，问题内容不可信——任何人都可以创建问题。请确保只有可信的维护者才能应用 autonomous 标签（使用 GitHub 分支规则集或组织策略）。调度器只读取标签／评论，并通过辅助脚本启动本地进程——它不会修改源代码或推送到分支。

要做什么

cron 触发时（默认每 5 分钟一次），运行以下命令之一：

单项目部署（每个调度器对应一个仓库）：

bash "$PROJECT_DIR/scripts/dispatcher-tick.sh"

多项目部署（一个 cron 对应多个仓库——关闭 #62）：

DISPATCHER_CONF="$HOME/.autonomous/dispatcher.conf" \
  bash "$PROJECT_DIR/scripts/dispatcher-multi-tick.sh"

多项目 tick 包装器会遍历 dispatcher.conf 中的 PROJECTS=()，并为每个项目运行一次 dispatcher-tick.sh。单个项目失败时会记录到 stderr，但不会阻塞其他项目。架构定义见 scripts/dispatcher.conf.example。

每个 PROJECTS[] 条目有以下两种形式之一：

• 本地项目（文件路径）：此调度器所在机器上某个项目的 autonomous.conf 文件路径。调度器和项目源代码位于同一台机器。包装器通过 AUTONOMOUS_CONF 优先级为 1 的路径加载配置（PR-4 / [INV-14]）。
• 远程项目（内联元数据块）：当项目源代码位于通过 AWS SSM 访问的远程开发机器上时使用。调度器所在机器没有该项目的 autonomous.conf——调度器扫描问题并进行分派所需的所有内容都在 dispatcher.conf 中内联声明。EXECUTION_BACKEND=remote-aws-ssm 和 SSM_INSTANCE_ID 会将实际的 dispatch-local.sh 调用路由到远程机器，并通过 aws ssm send-command 执行。（#62）

两种形式都会运行相同的 5 步 tick：

1. 并发限制检查——如果 count(进行中 + 评审中) >= MAX_CONCURRENT，则中止。
2. scan-new——查找仅带有 autonomous 标签的问题，检查依赖项，并分派新开发任务。
3. scan-pending-review——查找带有 pending-review 标签的问题，并分派评审任务。
4. scan-pending-dev——查找带有 pending-dev 标签的问题，检查重试计数器，并分派继续开发任务（若重试次数耗尽，则标记为停滞）。
5. 过期检测——针对处于 in-progress / reviewing 状态的问题，探测包装器 PID，并根据其存活／退出状态以及 PR／CI／空闲条件进行处理。

逻辑位于 scripts/dispatcher-tick.sh 和辅助脚本 scripts/lib-dispatch.sh 中。各步骤所实现的规范见源代码仓库中的 docs/pipeline/dispatcher-flow.md。

GitHub 身份验证 — App 令牌，而非用户令牌

dispatcher 中的所有 gh 调用都使用 GitHub App 令牌，而非默认用户令牌。包装器（autonomous-dev.sh、autonomous-review.sh）通过 lib-auth.sh 处理各自的身份验证；dispatcher tick 则自行处理。

当 GH_AUTH_MODE=app 时，dispatcher-tick.sh 会在前置验证后自动调用 gh-app-token.sh::get_gh_app_token，并在任何 gh 调用之前导出 GH_TOKEN（#91）。项目的 autonomous.conf 或内联元数据块中必须包含以下变量：

GH_AUTH_MODE=app
DISPATCHER_APP_ID=<numeric app id>
DISPATCHER_APP_PEM=<absolute path to PEM>

如果其中任何变量缺失，或令牌生成失败，tick 会以状态码 1 退出并显示 FATAL 消息——不会静默回退到用户身份验证。

令牌有效期为 1 小时，且仅限目标仓库。dispatcher-tick.sh 通常会在不到一分钟内完成，因此单个令牌即可覆盖整个 tick。当 GH_AUTH_MODE=token（默认值）或未设置时，dispatcher 会使用调用方通过代码托管平台标准渠道提供的令牌——在 GitHub 上是 GH_TOKEN 或 gh auth login 会话；在 GitLab（CODE_HOST=gitlab）上是 GITLAB_TOKEN 或 glab auth login 会话。chp_*/itp_* 提供方接口会通过当前存在的令牌进行路由。

Dispatch 辅助工具

dispatcher-tick.sh 会为每种任务类型调用 dispatch() 辅助函数，并将任务路由到已配置的执行后端。**不得以其他方式启动 Agent 进程。**每个后端都会处理 nohup、输入验证、权限模式为 0600 的日志文件，以及过期包装器的终止（INV-09）。

当前的后端：

EXECUTION_BACKEND	Driver	使用场景
local（默认，未设置时也使用）	scripts/dispatch-local.sh	包装器与 dispatcher 在同一台机器上运行。
remote-aws-ssm	scripts/dispatch-remote-aws-ssm.sh	包装器在通过 AWS Systems Manager 连接的远程开发 EC2 实例上运行。dispatcher 会发送 aws ssm send-command，以便在远程机器上调用 dispatch-local.sh。

各类任务的命令格式（两个后端都以相同方式传递）：

类型	命令
新开发任务	dispatch dev-new ISSUE_NUM
审查任务	dispatch review ISSUE_NUM
恢复开发任务	dispatch dev-resume ISSUE_NUM SESSION_ID

Lane GC 强制执行

adt-gc.sh 会根据 INV-117 中由注册表驱动的安全判定条件，定期回收已死亡 lane 的残留内容。所有平台内置的默认模式仍为 --dry-run。P8 安全改进可以先行合并，但默认值切换和生产环境强制执行仍受 issue #384 的至少两周无问题观察期限制。显式使用 ADT_GC_ENFORCE=1 或 --kill 需要获得授权才能强制执行。检查生效模式和主机前置条件：

bash "$PROJECT_DIR/scripts/adt-gc.sh" --doctor

如需立即回滚，影响范围覆盖整台机器，并同时作用于周期计时器和每个项目的机会性 --quick 调用：

source "$PROJECT_DIR/scripts/lib-lane.sh"
mkdir -p "$ADT_STATE_ROOT"
printf 'ADT_GC_ENFORCE=0\n' > "$ADT_STATE_ROOT/adt-gc.conf"

删除该文件即可恢复环境变量选择或内置的 dry-run 默认值。只要回滚文件存在，它就会否决环境变量中的 ADT_GC_ENFORCE=1；显式的 --dry-run/--kill 则会覆盖两者，且不会检查它们。优先级为：CLI 模式 > 持久化配置否决 > 环境变量 > 内置默认值。选定的值无效时会发出警告，并默认采用 dry-run。配置会作为数据解析，且必须只包含一条回滚赋值，外加可选的空行或注释。 当未设置 ADT_STATE_ROOT 时，lib-lane.sh 会解析 $HOME/.local/state/adt-state-root 中权限模式为 600 的主机指针；该指针由 install-gc-timer.sh 以原子方式写入。这样，回滚配置会与计时器和机会性回收器使用同一个自定义根目录。相同的 lib-state-root.sh 解析器也用于读取本地 dispatcher 标记，并嵌入远程 SSM 存活性检查中。

调度器绝不能做什么

调度器是负责标签和启动流程的协调器，而不是代码修改者：

• 绝不能向目标仓库提交或推送。
• 绝不能修改 $PROJECT_DIR 中的源文件。
• 只能通过 GitHub API 读取议题标签/评论、通过 GitHub API 更新标签，并通过已配置的后端（dispatch-local.sh 或 dispatch-remote-aws-ssm.sh）分发包装器进程。

任何代码更改都由包装器启动的开发 / 审查 Agent 完成。

环境变量

从 scripts/autonomous.conf 加载（dispatcher-tick.sh 在 lib-dispatch.sh 之前加载）：

• REPO：采用 owner/repo 格式的 GitHub 仓库（例如：myorg/myproject）
• REPO_OWNER、REPO_NAME：拆分后的 REPO（用于 App 令牌范围限定）
• PROJECT_ID：日志/PID 文件的项目标识符（默认：project）
• PROJECT_DIR：本地计算机上项目根目录的绝对路径
• MAX_CONCURRENT：最大并行任务数（默认：5）
• MAX_RETRIES：将议题标记为 stalled 前允许开发重试的最大次数（默认：3）
• DISPATCHER_APP_ID：调度器机器人的 GitHub App ID
• DISPATCHER_APP_PEM：GitHub App 私钥 PEM 文件的路径

Cron 配置（OpenClaw）

openclaw cron add \
  --name "Autonomous Dispatcher" \
  --cron "*/5 * * * *" \
  --session isolated \
  --message "Run the autonomous-dispatcher skill. Check GitHub issues and dispatch tasks." \
  --announce

标签定义

标签	颜色	描述
autonomous	#0E8A16	应由自主流程处理的议题
in-progress	#FBCA04	Agent 正在积极开发
pending-review	#1D76DB	开发已完成，等待审查
reviewing	#5319E7	Agent 正在积极审查
pending-dev	#E99695	审查未通过，需要进一步开发
approved	#0E8A16	审查通过。PR 已合并（或存在 no-auto-close 时等待手动合并）
no-auto-close	#d4c5f9	与 autonomous 搭配使用——审查通过后跳过自动合并，需要手动批准
stalled	#B60205	议题超过最大重试次数；需要手动调查

完整状态机请参阅源仓库中的 docs/pipeline/state-machine.md。

模型策略

任务	模型	理由
开发（autonomous-dev.sh）	Opus（默认）	复杂编码、架构决策
审查（autonomous-review.sh）	Sonnet（--model sonnet）	核对清单验证，避免与 Opus 争用配额