scheduler-gateway/README.md

scheduler-gateway-merged

DSH 调度网关 · 四模型合并版（R1+R2+R3 能力集于一身）

以 fjord(doubao-live R3，评分最高) 为骨架，合并 lodestone(nexus-live)、nexus(ai-hard)、epoch(v2-live) 的代码与测试， 修复各版本已知历史问题后的统一交付物。零第三方依赖，Node ≥20 原生 ESM。

v5.0.0 团队式编排引擎（第五轮）

真实 LLM 驱动的团队编排（详见 docs/TEAM-ORCHESTRATION.md）：

npm test                    # 321 断言全绿（v4 基线 193 + 团队引擎 R 段 128）
npm run orchestrate-demo    # 真实 LLM：拆解→路由（结构化适配理由）→多执行器→审查读产物文件/返工→合并成品
npm run e2e-team            # 端到端 + 每步 EXIT/耗时 + 五项安全自检 + 交付契约校验
.\gateway.cmd install codex # 外部 CLI agent 托管自安装到 ~/.gateway-agent/<name>/<version>/（版本锁定+装后自检）
.\gateway.cmd list         # 智能体池：内置 native/http-llm + 托管/探测到的外部 CLI，未装显式"未检测到"

• 编排大脑四阶段全部真实 LLM：拆解（目标/验收标准/能力标签/预期产物）、路由（agent/能力匹配度/成本可用性/具体适配理由，schema 失败自动重试，引擎硬约束修复留痕）、审查（读 out/// 产物文件评审，rework≤2，仍不达标如实 dead）、合并（out//final/FINAL.md）。
• ≥2 类执行器，含真实外部 CLI：托管 codex 0.90.0（隔离 CODEX_HOME + chat wire 中继 + 凭据仅经 env）、内置 native 确定性 worker、http 真实大模型 worker；每子任务独立工作区，状态 claimed→running→done/dead。
• agent 池与自安装：catalog 5 模板（codex/claude/gemini/qwen/pi）、doctor 扫描 PATH 自动注册、npm --prefix 托管安装、可信源白名单+https 强制、畸形 spec 校验、ensureAgent 按需找/装/拉、单 agent 成本熔断。
• 模式铁律：默认 REAL（无 key 硬失败 exit 2，不静默降级）；仅 GW_ORCH_OFFLINE=1 可离线，所有 LLM 形态输出显式 [OFFLINE]，外部 CLI 用 fixture 子进程替身并标 source=fixture。

能力总览

• 中心网关 + 能力感知调度：优先级队列、依赖门、审批门、节点能力匹配、负载均衡、重试退避、死信重投、执行失败熔断（连续失败的节点短期冷却不接新活，全冷却时回退防饿死；冷却时长随连击 ×2 指数升级；面板可见 ⛔ 徽章）
• 两类节点：native 直连节点（内置 worker/命令执行）与 adapter 兼容转化层（cmd / http 真实大模型 / codex），统一 gw-node/1 协议（register/heartbeat/poll/result，x-node-token 鉴权）
• 真实大模型多智能体编排：planner→跨节点 workers→reviewer(可 rework≤2 轮)→merger，全部真实 OpenAI 兼容调用（deepseek-v4-flash），结构化校验 + 有限重试 + 失败时诚实回退；POST /api/pipeline 异步启动（立即返回 runId，全程后台跑），GET /api/runs 轮询进度（规划→拆解→评审→返工→合并→完成/失败），面板「任务清单」顶部有运行条实时渲染
• http 适配器 = 真实 LLM worker：node src/cli-nodes.js adapter --adapt http（能力 adapter/http/llm/worker）——所有普通子任务可交给真实大模型执行；Windows 下 CLI 适配器把 prompt 当 argv 传给 .cmd 跳板会有中文乱码（已知限制），http 适配器天然绕开
• 双形态：standalone server + /panel（REST/SSE/导出/审批/死信重投）与 DSH 插件（cordis.patch.yml + lib，四个 gateway_* 工具 + 侧边栏）共享同一核心
• R2 增强：WAL/journal 崩溃恢复（GW_WAL=1）、每任务独立 workspace（可 git worktree）、危险命令/注入/路径穿越拦截、密钥脱敏
• R1 能力：dsh-task-board v3 自助接单桥（读板→安全校验→领单→网关执行→回写 done/failed+execution+evidence，409 乐观锁重试、SSE 降级）

快速开始

npm test               # 164 断言全绿（含真实 LLM 200、WAL、看板接单、安全对抗、压测）
npm run live-llm       # 严格验证：真实 planner+reviewer+merger，证据落 evidence/live-llm/

# 终端 1：中心网关 + 面板
npm run server         # http://127.0.0.1:4180/panel
# 终端 2/3：两类节点
npm run node-native
npm run node-adapter

# 一键演练（均默认动态端口 + 干净内存态，可并发运行）
npm run demo           # 真实 LLM 编排，子任务跨 native+adapter，rework→pass→merge
npm run stress         # 200 任务/并发16：无重复领取、无丢失
npm run chaos          # 200 任务 + native 掉线 5s 故障注入
npm run recovery-demo  # WAL 崩溃恢复演示
npm run board-claim    # 从 dsh-task-board 单轮接单（Host 未启动则优雅退出）

本地 CLI 探测与远端接入

node src/cli-live.js doctor          # 扫描本机 agent CLI（codex/claude/gemini/qwen…）与大模型 key，打印接入命令
node src/cli-live.js doctor --json   # 机器可读输出

• 任意本地 CLI 秒变节点：--adapt cli --cli <可执行名> --cli-args "-p {prompt}"（{prompt} 占位符，缺省把 prompt 作为末参数）。Windows 下自动穿透 npm 的 .cmd 跳板定位真实 exe/js 直启。
• 远端机器接入：① 本机 HOST=0.0.0.0 GW_NODE_TOKEN=<强token> npm run server；② 远端装 Node ≥20 并拷贝本目录；③ 远端执行 GATEWAY_URL=http://<局域网IP>:4180 GW_NODE_TOKEN=<token> node src/cli-nodes.js native --name Remote_Worker。面板「连接 Agent / 节点」卡片底部有按当前 IP 生成的可复制命令（来自 /api/info）。
• 连接自愈：网关重启后节点收到 404 会自动重注册，无需人工重启。

环境变量

变量	默认	说明
GW_NODE_TOKEN	dev-token-change-me	节点鉴权 token（生产必改）
PORT / HOST	4180 / 127.0.0.1	网关监听
GW_NODE_TOKEN	—	节点侧 token
GW_WAL	0	=1 开启 WAL/journal 崩溃恢复
GW_WORKTREE / GW_REPO_ROOT	0	=1 每任务独立 git worktree
GW_LLM_STRICT	0	=1 时 demo 遇真实 LLM 失败直接报错（默认诚实回退）
GW_BREAKER	1	=0 关闭执行失败熔断
GW_FAIL_STREAK	1	连续执行失败多少次触发熔断（0 关闭）
GW_COOLDOWN_MS	60000	熔断基础冷却时长；连续失败按 ×2 指数升级
GW_COOLDOWN_MAX_MS	600000	熔断冷却上限
DSH_TASKBOARD_URL	http://127.0.0.1:32566/api/dsh-task-board/v3	看板 Host API

真实 LLM key 从 DSH_GATEWAY_ENV_FILE / D:\work_doubao\.env.live / 项目 .env.live / 环境变量读取，永不进日志/面板/导出。

DSH 插件形态

dsh plugin --profile desktop add link:<本目录绝对路径>

注册 gateway_status / gateway_run / gateway_board / gateway_nodes 四工具与侧边栏「调度网关」面板； 插件只是同一 HTTP API 的薄封装，与 standalone 共享一套核心。

已在本机实测挂载成功（配置合成 + 入口加载验证通过，见 docs/PLUGIN-MOUNT.md）； 由于本机 Desktop 自带 pnpm 11 与 profile 的 store v10 不匹配，dsh plugin add 会报 ERR_PNPM_UNEXPECTED_STORE，按 PLUGIN-MOUNT.md 的 pnpm 10 等价步骤操作即可。

文档

• docs/ARCHITECTURE.md：架构与协议
• docs/IMPLEMENTATION.md：实现细节与验证方式
• docs/ADR.md：关键决策记录
• docs/MERGE-REPORT.md：四模型合并来源与历史问题修复清单
• docs/SELF-ASSESSMENT.md：诚实自评

诚实标注

• 真实：deepseek-v4-flash 全部 HTTP 调用（live-llm/demo/测试 J 段，均 200 证据）；adapter-cmd 真实子进程；adapter-http 真实大模型 worker；stress/chaos 真实多进程压测
• 回退：真实 LLM 输出多次未通过结构校验时，demo 默认回退确定性计划/评审（打印警告，GW_LLM_STRICT=1 可严格化）；live-llm 始终严格
• 占位：SSH/Hermes 远端执行器协议已预留未接；原生 codex adapter 需本机装 codex CLI