# 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](docs/TEAM-ORCHESTRATION.md)）：

```powershell
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/<run>/<sid>/ 产物文件**评审，rework≤2，仍不达标如实 dead）、合并（out/<run>/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 降级）

## 快速开始

```powershell
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 探测与远端接入

```powershell
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 插件形态

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

注册 `gateway_status / gateway_run / gateway_board / gateway_nodes` 四工具与侧边栏「调度网关」面板；
插件只是同一 HTTP API 的薄封装，与 standalone 共享一套核心。
> **已在本机实测挂载成功**（配置合成 + 入口加载验证通过，见 [docs/PLUGIN-MOUNT.md](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/ARCHITECTURE.md)：架构与协议
- [docs/IMPLEMENTATION.md](docs/IMPLEMENTATION.md)：实现细节与验证方式
- [docs/ADR.md](docs/ADR.md)：关键决策记录
- [docs/MERGE-REPORT.md](docs/MERGE-REPORT.md)：**四模型合并来源与历史问题修复清单**
- [docs/SELF-ASSESSMENT.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