# 团队式编排引擎（v5.0.0 · epoch）

真实 LLM 驱动的团队编排：**管理者拆解 → 调度主管路由（结构化适配理由）→ 多执行器分工（外部 CLI agent + 内置 native/http worker）→ 审查 Agent 读产物文件评审与返工 → 合并 Agent 汇总成品**。零第三方依赖，Node ≥ 20。

## 1. 三条现场验收命令

```powershell
npm test                 # 全量测试（v4 基线 193 断言 + R 段团队引擎断言），全绿 EXIT=0
npm run orchestrate-demo # 真实 LLM 端到端团队编排，证据落 evidence/team-orch/<runId>/，成品落 out/<runId>/final/
.\gateway.cmd install codex   # 外部 CLI agent 托管自安装（~/.gateway-agent/codex/<version>/，版本锁定+装后自检）
```

- `npm run e2e-team`：在 orchestrate-demo 之上追加每步 EXIT/耗时报告、五项安全自检、交付契约校验。
- 仓库根 `gateway.cmd`（Windows）/ `gateway`（POSIX）让验收现场在仓库根直接跑 `gateway <cmd>`；`npm run gateway -- <cmd>` 等价。

## 2. 模式铁律（REAL / OFFLINE）

| | REAL（默认） | OFFLINE |
|---|---|---|
| 进入方式 | 默认；`GW_ORCH_REAL=1` 同义 | 仅 `GW_ORCH_OFFLINE=1` |
| 拆解/路由/审查/合并 | 真实 LLM（`/chat/completions`，chatJSON schema 校验失败自动重试（上限 4 轮；HTTP 429/5xx 指数退避 1.5s→24s）） | 确定性模板，全部输出显式标注 `[OFFLINE]` |
| 无 key | **硬失败 exit 2**（不静默降级） | 不需要 key，不产生任何网络调用 |
| 外部 CLI | 真实托管 codex（子进程） | `GW_TEAM_STUB_CLI` 指定的本地替身脚本（仍是真实子进程，来源标 `fixture`，不冒充真实 CLI） |
| http worker | 真实大模型 worker，回答写产物文件 | 由 builtin-offline-writer 确定性替身代替，产物标注 OFFLINE |

key 只从 `.env.live`（`DSH_GATEWAY_CODEX_API_KEY`/`XXCSN_API_KEY`）或进程环境读取，**永不进交付物、日志、面板、子进程 argv**；证据 JSON 经脱敏写入。

## 3. 智能体池与托管自安装（H2）

- **catalog**（`src/team/catalog.js`）：5 条模板（codex / claude / gemini / qwen / pi），每条含能力标签、模型、成本等级（1-5）、安装源与锁定版本、托管目录 bin 候选、`--version` 探活正则、非交互 argv 模板、凭据策略、可信源主机白名单。
- **installer**（`src/team/installer.js`）：
  - 托管根 `~/.gateway-agent`（可用 `GW_AGENT_HOME` 覆盖）；布局 `~/.gateway-agent/<id>/<version>/`，与用户全局安装互不影响；
  - npm 安装显式 `--prefix` 到托管目录（不依赖被改写的全局 prefix），npm 经 `node npm-cli.js` 直启（跨平台、不走 shell）；
  - 装后自动 `--version` 探活（正则匹配），写 `install.json`（版本/来源主机/时间/探活结果/耗时）；重复安装幂等（`status: already`）；
  - 安装前 `checkSourceTrust`：registry 主机必须在白名单、必须 https；畸形 spec 直接拒绝；失败返回可操作错误。
- **pool**（`src/team/pool.js`）：`discoverAgents()` 三路注册——`managed`（托管安装）、`detected`（PATH 已装，doctor 扫描）、`builtin`（native / http-llm / offline-writer）；注册字段含 capabilities/model/cost/health/lastProbeAt；`ensureAgent({cap})` 大脑只提能力需求，引擎负责找/装/拉，找不到且不可装就**如实失败**；`CostGuard` 按调用次数 + LLM token 双预算熔断。
- CLI：`gateway install <name> [--force]`、`gateway list`、`gateway doctor`、`gateway catalog`。

### 为什么托管 codex 锁定 0.90.0（实测留痕）

本机全局 codex 0.149.1 被用户 `~/.codex/config.toml` 绑死到旧中继的 `/responses`（wire_api=responses），而本轮中继 `maas-api .../compatible-mode/v1` 只开放 `/chat/completions`（实测 `/responses` 返回 404）；且 0.95+ 移除 `wire_api="chat"`（0.149 直接报错），0.100/0.118/0.129 实测同样拒绝。**0.90.0 是实测仍支持 chat wire 的版本**（仅 deprecation 警告），故 catalog 锁定 0.90.0，装在引擎托管目录，与用户全局 codex 完全隔离。

Windows 无 codex 原生沙箱后端（`-s workspace-write` 实测被降级为 read-only、写文件全部 blocked by policy，探针日志留证），故托管 argv 使用 `--dangerously-bypass-approvals-and-sandbox` 配合 `-C <每子任务独立工作目录>`；隔离边界由引擎保证：独立 cwd、独立托管 `CODEX_HOME`、子进程环境剥离网关内部 key（见 §5）。

## 4. 编排主流程与目录契约（H1/H3）

```
拆解 decompose ── 发现/按需安装 agent ── 路由 route（四要素：agent/能力匹配度/成本可用性/具体理由）
  ── 并行执行 execute（每子任务独立工作区，状态 claimed→running→done/dead）
  ── 审查 review（读 out/<run>/<sid>/ 下真实产物文件内容，pass/rework/dead）
  ── 返工 rework（把 required_changes 追加进子任务 prompt 重跑，上限 2 轮；仍不达标标 dead 并如实上报）
  ── 合并 merge（读全部产物 → out/<run>/final/FINAL.md + manifest.json）
```

- 工作区：`work/<runId>/<st-id>/`（执行）；产物归档：`out/<runId>/<st-id>/`（含外部 CLI 原始输出 `agent-output.attemptN.txt`）；成品：`out/<runId>/final/`。
- 证据：`evidence/team-orch/<runId>/` 下 `plan.json`（目标/验收标准/能力标签/预期产物）、`routes.json`（路由四要素 + 引擎修复留痕）、`roster.json`、`executions.json`（每次 attempt 的状态/耗时/产物清单/证据）、`reviews.json`（每轮逐子任务结论 + `filesReviewed` 证明读的是文件）、`merge.json`、`step-report.json`（每步 EXIT 与毫秒耗时）、`run-result.json`。
- 路由硬约束（LLM 不满足时引擎确定性修复并留痕 `repairNote`）：编码类子任务在有健康 CLI 时必须给外部 CLI；确定性机械步骤给 native；至少 2 个不同执行器。

## 5. 安全覆盖（H4，五项，`npm run e2e-team` 现场自检）

1. **编排 prompt 注入**：`SecurityGuard.detectInjection` 扫描目标与各阶段文本，命中模式（ignore previous instructions / 中文忽略指令 / 管道远程执行 / 路径穿越等）写入 `security.injectionFindings`，良性输入不误报。
2. **外部 CLI 凭据隔离**：key 只经专用环境变量注入（codex 用 `GW_RELAY_API_KEY`，对应托管 `CODEX_HOME/config.toml` 的 `env_key`，配置文件里只有 base_url/model、**无 key**）；子进程 env 剥离 `XXCSN_API_KEY/DSH_GATEWAY_CODEX_API_KEY/OPENAI_API_KEY/OPENAI_BASE_URL/...`；argv 模板出现凭据字段直接被 spec 校验拒绝，执行前再做一次 argv key 泄漏拦截；CLI stdout/stderr 回收时脱敏。
3. **畸形 spec 校验**：`validateSpec` 对 id/版本锁定/可信源/bin 路径穿越/argv 凭据等 10+ 条规则校验，安装与注册前强制过检。
4. **安装源可信度**：registry 主机白名单 + https 强制，白名单外源/非 http 一律拒绝安装。
5. **单 Agent 成本熔断**：`CostGuard` 双预算（默认 14 次调用 / 240k tokens），跳闸后该 agent 快速失败并在 manifest 留快照。

## 6. 模块索引

| 文件 | 职责 |
|---|---|
| `src/team/catalog.js` | CLI agent 模板、validateSpec、checkSourceTrust |
| `src/team/installer.js` | 托管安装、bin 跨平台解析、装后探活、install.json、幂等 |
| `src/team/pool.js` | 三路发现、ensureAgent、builtin 注册、CostGuard |
| `src/team/executors-team.js` | CLI/native/http/offline-writer 执行器、凭据隔离 env、产物收集 |
| `src/team/orchestrate.js` | 编排大脑（拆解/路由/执行/审查/返工/合并/证据/状态机） |
| `src/cli-gateway.js` | `gateway install/list/doctor/catalog` |
| `src/cli-team.js` | `orchestrate-demo / orchestrate <goal> / e2e-team`（含五项安全自检） |
| `test/team-section.mjs` | R 段确定性测试（离线 fixture，不触网） |
| `test/fixtures/fake-coding-agent.mjs` | 离线外部 CLI 替身（真实子进程） |

## 7. 诚实标注约定

- REAL 证据中 `mode: "REAL"` 并带 LLM 延迟/token 用量；OFFLINE 一切 LLM 形态输出（计划/路由理由/审查/成品）显式 `[OFFLINE]`。
- fixture 替身 agent 的 `source: "fixture"`，不与真实 codex 混淆；自动安装失败、探活失败、熔断跳闸、dead 子任务均如实落证据，不伪造通过（CLI 以 exit 2 上报）。

## 6. 工程注记（实测约束）

- **子任务顺序执行**：外部 CLI（codex）与 http worker 共用同一中继账号的并发额度（超限返回 429 Concurrency limit exceeded），executeAll 顺序派发，把同账号并发压到 1，且每步耗时可审计。
- **codex 锁 0.90.0**：0.95+ 移除 wire_api="chat"（实测 0.95/0.99/0.100/0.118/0.129/0.149 均拒绝），0.90.0 是仍支持 chat wire 的最高版本；Windows 无 codex 原生沙箱后端，须 `--dangerously-bypass-approvals-and-sandbox` + `-C <独立工作目录>`；spawn 后立即 stdin.end() 防挂死。
- **detected CLI 失败兜底**：执行失败时若该外部 CLI 为 PATH 探测来源（detected）且存在健康托管 CLI，自动改派托管 CLI 重试并写 agentSwitches 留痕。
- **双 key 故障处理（任务书附录 A）**：.env.live 每次调用现读（热切换，无需重启）；chatComplete 遇 429（含 code 5005 并发/5007 额度耗尽）/401/403/5xx/网络错，先指数退避重试主 key 共 3 次，仍失败自动切备用 key（XXCSN_API_KEY_A）重试 1 次，结果与证据记 keyFallback:"A"；双 key 都失败返回 fatal + quota-exhausted 与「需充值/稍后重试」提示，绝不伪装成功。外部 CLI（codex）子进程同理：执行失败命中额度/鉴权特征时以备用 key 重建隔离 env 重试并留痕；key 明文永不进 argv/日志/证据/面板（R9 确定性覆盖）。