maya/scheduler-gateway
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
bbb364cd69
scheduler-gateway/docs/TEAM-ORCHESTRATION.md
Liuxinyu176 bbb364cd69 feat: DSH 调度网关（互联网关）v6.0.0 — 四模型合并版 R1+R2+R3 
- 零第三方依赖，Node >=20 原生 ESM
- 团队式编排引擎：拆解/路由/执行/审查/合并全真实 LLM
- 阶段心跳、单一权威清单守卫、all-keys-failed 如实上报
- H4 会话视图/amend/watchdog 有界重试/产物区 artifacts.json
- H5 零依赖三栏控制台
2026-10-09 23:20:27 +08:00

9.7 KiB
Raw Blame History

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

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

1. 三条现场验收命令

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 确定性覆盖）。