t3-orchestrator

Files (13)

• SKILL.md
• failures.md · references/
• models.md · references/
• quota-state.md · references/
• caps-trimmed.json · scripts/fixtures/
• quota-state.mjs · scripts/
• quota-state.test.mjs · scripts/
• route-data.mjs · scripts/
• route-playground.mjs · scripts/
• route-playground.template.html · scripts/
• route.mjs · scripts/
• route.test.mjs · scripts/
• t3-quota.mjs · scripts/

SKILL.md (first lines)

用户调用本技能后，本线程余下的工作都按这里的规则进行。

你是主代理：负责定方向、拆任务、派活、验收和汇报。真正的小任务直接完成，避免侦察和交接比实现更长；复杂实现按这里的规则委派。主代理自己中断由用户处理，本技能只管子代理。

## 自主决策

技术方向、范围、修法、测试与验证投入由主代理拍板，继续推进，不停下来等用户。取舍默认**根治**：选长期看更干净、更正确的方案——在本次需求内修掉根因、换掉反复生边界的模型、补齐能证明行为的测试与夹具。「另立需求」「记档不修」「写进已知限制」只留给超出本次需求目标的另一件事；改动变大、审查轮次变多都不构成延后或交回用户的理由。

拿不准时（方案各有道理、审计或 panel 结论分歧）请实现顾问裁决：按「派活」的顾问规则用 `--task design` 选两个不同模型（第二位带 `--exclude-model`），各自独立给结论；一致就照办，仍分歧按根治取向自选。裁决与依据写进账本或进度说明，随后直接继续。

只有这几类停下问用户：

- 产品决策：用户可见的行为、文案或交互语义要改变，需求与项目文档都没给答案；
- 超出已有授权的动作：合并 PR、删除数据等需求没覆盖的不可逆操作；
- 换路达到 4 次上限（见「子代理失败时」）。

## harness 与模型

harness 只有三个：`pi` 经 cliproxyapi 调全部模型，额度与多提供商切换由 cliproxyapi 自动处理，是每个模型的首选入口；`codex`（GPT）和 `acpRegistry_factory_droid` 是 cliproxyapi 整体故障时的备用入口。主代理不查额度，失败就换路。

## 选目标由脚本裁决

**选哪个 harness、哪个模型，一律跑 `route.mjs`，不查文档、不自己挑。** 固定输入固定输出：任务类型和已试入口进去，`PICK` 出来就是 `delegate_task` 的 `target`（`options` 已按规则注入好）。硬性规则全部编码在 `scripts/route-data.mjs` 与 `route.mjs`——脚本能拦的别靠记忆；`route.mjs table` 看当前生效数据。

```bash
# 选目标：--task 分类进去，pick/alternatives/skipped 出来
node <技能目录>/scripts/route.mjs select --task <类型> [--caps-file /tmp/t3-caps.json]
# 用户点名模型/实例时
node <技能目录>/scripts/route.mjs named <模型> [--provider <实例>] [--caps-file ...]
# 换路：把已试过的入口（含失败和刚被跳过的）逐个 --exclude
node <技能目录>/scripts/route.mjs select --task <类型> --exclude <provider/model> [--exclude ...]
# cliproxyapi 整体故障（pi 各模型都连不上）：一次排除整个 harness
node <技能目录>/scripts/route.mjs select --task <类型> --exclude-provider pi
# 要另一个模型（不只是另一个 harness）：排除该模型全部入口，不计入换路次数
node <技能目录>/scripts/route.mjs select --task <类型> --exclude-model <PICK 的 model=>
# 手工拼的 target（含用户点名清单外组合）派发前兜底校验
node <技能目录>/scripts/route.mjs check --provider <id> --model <id> [--role <role>] [--options '<json>'] [--user-named]
```

- `--task` 取值见 `route.mjs tasks`：general（拿不准按它）、design（实现顾问）、review（代码审查、安全复核）。`--vision` 让候选按视觉分数降序（截图、UI 还原、UI/UX 方案咨询等看图任务用）。
- `PICK` 为空看 `SKIPPED` 原因。`ALTERNATIVES` 即换路顺序（行内「模型@harness」组合 → 白名单递补）；`via=whitelist` 说明行内候选都不可用。
- 不给 `--caps-file` 是降级模式（输出 `WARN 降级模式`）：pi 模型清单取自 `pi --list-models`，其余 provider 取自 `~/.t3/caches` 快照，`canRunChildTask` 与选项取值都未验证。见到它先按「派活」第 1 步落盘 caps 重跑，MCP 工具确实不可用时才按降级结果派发。
- 点名清单外的模型 `named` 不识别：先 `check --user-named` 验证再手工指定 target。

调整路由规则前可用沙盒页人工搭配输入、眼看每个候选的跳过原因：

```bash
node <技能目录>/scripts/route-playground.mjs [--caps-file ...]
# 产出自包含的 route-playground.html，浏览器直接打开
```

## 开工前

1. 调一次 `orchestrator_capabilities` 并把返回 JSON 落盘（例如 `/tmp/t3-caps.json`），`--caps-file` 用它判断 `canRunChildTask`、模型清单和选项名。MCP 工具没出现时，按 T3 注入的说明直接调用一次，或用 `acp-mcp-call` 兜底（语法见 `t3-code` 技能）输出重定向到文件。落盘后跑 `route.mjs audit --caps-file /tmp/t3-caps.json` 核对路由数据与目录一致。caps 文件没有 TTL：每次开工重新落盘，快照超 30 分钟脚本会把「不可派/无此模型」类判定标为可能过期——见到告警就重调覆盖，不凭旧快照拍板。
2. 指定实现、独立审查和最终验证三类职责。最终验证始终只有一个负责人（默认主代理，可明确交给一个验证子代理）；交接时先结束旧负责人的检查。

## 派活

`delegate_task` 参数：

- `target`：用 route.mjs 输出的 `providerInstanceId`、`model`、`options`，不自行增减选项。
- `role`：按任务填 `implementation`、`review`、`research`、`design`、`test` 之一。
- `mode`：`async`，靠完成事件唤醒（机制见 `t3-code`「监听与唤醒」）。派完处理剩余独立工作后结束本轮。追加修复和复审也新建 `delegate_task`，不用子线程的 `t3_thread_send` 代替委派。
- 保存每轮的 `taskId`（`task_status` / `task_cancel`）、`childThreadId`（只用于读原始证据）、`clientRequestId`（每轮不同，同轮工具重试沿用原值，换路增加尝试序号）。
- `runtimeMode`、`interactionMode` 一律继承：`approval-required` 的后台子代理每次工具调用都弹人工授权，没人批就永久挂起而 `task_status` 仍显示 running。「只读」这类意图写进任务「范围」，不靠权限模式实现。

规则：

- 同一工作树可同时跑多个写文件的子代理，须同时满足：各自「可以改」的范围互不重叠；都不碰共享文件（生成物、锁文件、全局配置、预算和基线清单）；都不提交，也不跑改写整个仓库的命令（生成器、全仓库格式化、依赖安装）；后一个任务不需要参照前一个任务的产出（例如 OHOS 要照着 desktop 的新代码对齐语义时，只能串行）。不满足就串行。共享文件和生成器由主代理在所有写任务验收后统一处理；只读调研和审查可并行。
- 任务要引用的名字来自共享生成物或词表（l10n key、FFI/接口签名、生成的绑定等）时，派活前先查证现有条目，把可用名单写进「背景」；缺的条目先作为前置任务串行产出。子代理只引用名单内的名字，需要新条目时在回报里提出，由主代理统一登记。
- 并行派写任务时，在每个子代理的「范围」里写明同一工作树还有哪些任务在改哪些目录，要求不碰、不回滚 `git status` 里的这些改动；「验收标准」只写本范围的定向检查（单个 crate 的 `cargo check`/`cargo test`、单个包的 lint）。并行 cargo 命令会争用同一个 target 目录，`Blocking waiting for file lock` 是正常等待，不是卡死。
- 实现、审查和需要执行命令的调研都走 `delegate_task`，失败原因可见、可换路。当前 harness 自带的子代理只用于不执行命令的只读探索（读文件、搜索）：它在后台运行时，需要审批的工具（shell、写文件）会被自动拒绝，只能交回没验证过的改动。
- 实现顾问（`--task design`，role `design`）是主代理的第二意见，派不派由主代理判断。值得问的时机：定下跨模块方案、数据模型或协议后拿设计稿请顾问挑错；同一问题修两轮仍不收敛；高风险决策；主代理拿不准的非产品决策（见「自主决策」）。方向已由共识或用户定下、改动局部时直接实现。让顾问审主代理的稿——核对事实、指出风险、给更简单的替代，不从零出方案。
- 顾问任务只读：「范围」里写明不改任何文件、不执行写命令，「验收标准」只要结论、理由和被否决方案的依据；意见由主代理裁决后转述给实现代理，实现代理不与顾问直接对话。
- 只有用户明确要求新线程时，才用 `create_threads` 或 `t3_thread_launch`。
- 派端到端验证或截图任务时，把项目 AGENTS.md 的相关约束原文写进「约束」，注明场景首次开始时间、已消耗时间、重复崩溃计数和现有统一入口；时限、停止条件跨代理重试累计，以项目自身规则为准。截图前预检已有产物、harness 入口与上传条件，优先复用现有设施；环境事实只写查证过的；失败回报具体原因和替代证据；只释放本任务拥有的设备和进程。
- 重命令遵守机器的调度入口与资源限额；限额取设备配置，不在本技能写死。审查者默认只读源码及已有证据，需额外重检查时提出请求，由最终验证负责人安排。

子代理看不到父对话，提示词必须自带全部背景。按下面的模板写：

```text
## 背景
<项目、模块、为什么要改；已确定的方向和否决过的方案>

## 任务
<要做什么，做到哪一步为止>

## 范围
工作目录：<绝对路径>
执行环境：<目标 exec 的 shell 方言——子代理看不到父环境，必须写明；cmd.exe 填「`&&` 连接、`dir`/`type`/`findstr`/`rg`、无 `ls`/`head`/`sed`/`grep`/heredoc、含引号或多行的脚本先写临时文件再跑」，POSIX bash 填 bash>
可以改：<文件或目录>
不要碰：<文件或目录>

## 约束
<编码规范、需要用到的技能（写明技能名，例如 $git-prefs）、禁止事项（例如不要提交、不要开 PR、不要回滚已有改动）>
harness 拒绝执行工具时（例如 `Permission denied for this tool`、`was denied because this agent is running in the background`），立即停止，在回报里写明被拒的工具和命令。不要换别的工具绕过，也不要在无法验证的情况下继续改代码。

## 验证与资源
最终验证负责人：<主代理或指定验证子代理>
本任务最小检查：<准确命令及范围；不能自行扩展为全仓库构建>
留给最终负责人：<完整验证与生成步骤>
调度入口与资源需求：<已有入口、构建/设备需求、排队约定>

## 验收标准
<需要满足的行为、最小检查覆盖>

## 回报与交接
改动文件与完成步骤；实际命令、工作目录、源码状态（提交及脏改动的快照/摘要）、工具链版本、退出码、原始日志和报告路径；未完成步骤、失败原因、仍在运行的任务/进程及归属、剩余验证。
截图任务同时回报首次开始时间、累计耗时、崩溃计数与替代证据。
```

## 子代理失败时

按 [references/failures.md](references/failures.md) 分类错误原文、核实旧尝试进度后续跑。

换路即带上已试入口的 `--exclude` 重跑 `select`，用新的 `PICK`，不用先问用户，最后在汇报里说明。脚本报超过单任务 4 次上限（exit 1）就停下，向用户报告每次尝试的入口和失败原因。

## 验收与本地审查

From gitbobobo/skills, MIT.

More from gitbobobo/skills