scheduler-gateway/docs/IMPLEMENTATION.md

IMPLEMENTATION — scheduler-gateway-merged

目录结构

src/
  cli-live.js        统一 CLI：server/node-*/live-llm/demo/chaos/stress/recovery-demo/board-claim/status
  server.js          中心网关（REST+SSE+节点长轮询+鉴权+WAL 透传+panel）
  store.js           任务/节点/审计/死信/事件总线（mutex 串行化 + 防抖落盘 + WAL 钩子）
  scheduler-core.js  调度原语：pickNode/claimForNode/settleResult/requeueDead/depsReady
  protocol.js        gw-node/1 协议常量 + 注册校验 + 恒定时间 token 比较
  orchestrator-live.js 真实 LLM P→W→R→M 编排（rework≤2 轮，LLM 失败诚实回退）
  llm.js             真实 chat 调用 + 渐进式 JSON 提取 + 结构化校验重试
  live-llm.js        严格验证脚本（planner+reviewer+merger → evidence/live-llm/）
  node-runtime.js    GatewayNode：注册/心跳/长轮询/执行/回报
  nodes/             native 启动器 + executors(native/cmd/http/codex) + adapter
  panel.js           单文件 HTML 面板（任务/节点/日志/指派/审批/死信重投/导出）
  security.js        基础安全函数 + SecurityGuard（注入/危险/脱敏/路径白名单）
  wal.js             JSONL journal（幂等键、事件流、recoverInFlight）—— 合并自 fjord
  recovery.js        崩溃恢复：WAL 重放重投 + recovery-demo —— 合并自 fjord
  worktree.js        每任务独立工作区（可 git worktree）
  taskboard/         看板客户端 + 领单/回写 + 接单桥 —— 合并自 fjord(R2)/epoch(R2)
lib/                 DSH 插件半：index.js(4 工具) + client.js（薄封装同一 HTTP API）
cordis.patch.yml     DSH 插件注册补丁
test/                live-suite.mjs（A-N 段 164 断言）+ mock-board-server.js

验证方式（全部实测）

命令	结果	说明
npm test	164 断言 EXIT=0	A LLM / B 协议 / C 存储 / D 调度 / E-I 服务器+双节点+故障+安全 / J 真实 LLM 200 / K WAL+恢复 / L 看板接单(含 409 风暴+SSE+接单桥) / M 安全对抗 / N 压测(40任务/8并发)
npm run live-llm	EXIT=0	真实 planner+reviewer+merger 全部 200，证据落盘
npm run demo	EXIT=0	真实 LLM 编排跨 native+adapter 节点，评审轨迹 rework→pass，merger 合并
npm run stress	EXIT=0	200 任务/并发16：done 200、未完成 0、重复领取 0、246 task/s
npm run chaos	EXIT=0	200 任务 + native 掉线 5s：done 192 + 注入死信 8、未完成 0、重复领取 0
npm run recovery-demo	EXIT=0	claim 未 settle ×2 恢复重投，已 settle 任务不受影响
npm run board-claim --once	EXIT=0	看板 Host 未启动时优雅失败；有 Host 时单轮接单

关键实现取舍

1. port 0 = 动态端口（修复）：原 fjord 实现 opts.port || 4180 把 0 当 falsy，导致测试/多实例抢占 4180（与 nexus EADDRINUSE 同源）。已改为显式判 undefined。
2. 一键命令内存态（修复）：demo/stress/chaos/board-claim 默认 persist:false + 动态端口，避免污染 state/ 文件导致计数错乱（实测 stress 曾出现 done 202>200）。
3. LLM 输出健壮性（修复）：extractJson 由「首括号→末括号」改为渐进式括号匹配（容忍尾随解释文本），实测修复 planner 反复失败；reviewer verdict/score 归一化；重试 3→4 + hint。
4. LLM 失败诚实回退：demo 默认 GW_LLM_STRICT!=1 时回退确定性计划/评审并打印警告；live-llm 始终严格。
5. 看板 mutator 语义（修复）：doubao-hard board-client 要求 mutator 返回修改后 doc，v2-hard claim-settle 返回 true → 合并时已对齐，否则 PUT body 变 true 导致 409 风暴。
6. LLM 测试偶发红（修复）：套件 J 段真实调用最多重试 3 次退避，网络抖动不再误报；无 key 时降级为真实网络尝试断言。

已知边界

• SSH/Hermes 远端执行器：协议层预留（adapter 可扩展 kind），未接真实远端
• codex adapter 需本机装 codex CLI；adapter-http 已验证真实大模型
• 看板接单桥需 dsh-task-board Host 运行于 127.0.0.1:32566（可 DSH_TASKBOARD_URL 覆盖）
• GW_WORKTREE=1 需要 workspace-repo 是 git 仓库（失败自动回退普通目录）