# ARCHITECTURE — scheduler-gateway-merged

## 1. 总览

```
┌──────────────────────────────────────────────┐
│ 中心网关 / 调度层 (server)                     │
│ REST: /api/tasks /api/assign /api/pipeline    │
│       /api/nodes /api/status /api/export      │
│       /api/tasks/:id/approve /api/deadletter  │
│ SSE:  /api/events      面板: /panel           │
│ 节点协议: /node/register|heartbeat|poll|result│
│ store(内存+落盘) scheduler(能力感知)          │
│ orchestrator(真实LLM P→W→R→M)  WAL(可选)      │
└──────────────┬────────────────┬───────────────┘
               │ 统一 NODE 协议 (x-node-token)   │
        ┌──────▼───────┐      ┌──────────────────▼─────────┐
        │ native 直连节点 │      │ adapter 兼容转化层节点       │
        │ 原生讲协议      │      │ cmd / http(真实LLM) / codex │
        └───────────────┘      └────────────────────────────┘
```

## 2. 统一内部协议（gw-node/1）

PULL 长轮询模型（节点可在 NAT 后）：

| 消息 | 方向 | 说明 |
|---|---|---|
| register | 节点→网关 | nodeId/kind/capabilities/maxConcurrency/cost；错误 token 401 |
| heartbeat | 节点→网关 | 8s 一次，带 inFlight/completed；30s 不见判掉线 |
| claim(poll) | 节点→网关 | 长轮询 25s；网关按能力+负载原子派发 |
| execute | 网关→节点 | poll 响应携带任务全文（prompt 只走 stdin） |
| result | 节点→网关 | ok/输出/证据/执行器，或 error（触发重试/死信） |
| health/node | 客户端 | /api/status + /api/nodes |

## 3. 两类连接形态

- **native**：src/node-runtime.js + nativeExecute，确定性内置 worker（不冒充 LLM），独立临时工作区
- **adapter**：makeAdapterExecute(kind) 把外部执行器翻译成协议：cmd 白名单子进程 / http 任意 OpenAI 兼容端点 / codex CLI

## 4. 调度层（src/scheduler-core.js + src/store.js）

- 队列：优先级→创建时间；依赖满足才出队；审批门未过不出队
- 能力感知：任务 capabilities 必须被节点全覆盖；候选按 负载率→成本→历史完成数 排序
- 并发：每节点 maxConcurrency 槽；claim 在 store mutex 内原子完成，结构上杜绝重复领取
- 重试/死信：失败按 attempts 指数退避重投（排除刚失败节点）；超 maxAttempts 进死信，面板可重投
- 弹性：节点掉线立即把其在途任务重投队列，被其它节点接管

## 5. R2 增强（崩溃恢复 + 安全）

- src/wal.js（合并自 fjord doubao-hard）：JSONL journal，先写后 apply，幂等键去重，重放重建 in-flight；GW_WAL=1 启用
- src/recovery.js：启动时 recoverInFlight → 重投队列（claim 未 settle），recovery-demo 一键演示
- src/security.js（基础版 + nexus ai-hard 的 SecurityGuard）：路径白名单、危险命令、prompt 注入（大小写混淆/角色劫持/嵌套反引号）、密钥脱敏
- 执行隔离：每任务独立 workspace；GW_WORKTREE=1 时每任务独立 git worktree，失败回退普通目录并记录

## 6. R1 能力（dsh-task-board 自助接单）

src/taskboard/：board-client（GET/PUT + If-Match 头+体内 revision 双保险、409 有界重试、SSE watch 指数退避、故障注入钩子）+ claim-settle（todo/backlog→running→done/failed + execution/evidence，幂等）+ sync 桥（安全校验→网关执行→回写）。

## 7. 双形态

- standalone：npm run server → 同一套 store/scheduler/orchestrator + 自带 /panel
- DSH 插件：cordis.patch.yml + lib/index.js（四个 defineTool）+ lib/client.js；薄封装同一 HTTP API

## 8. 安全与鉴权

- 所有 /node/* 校验 x-node-token（恒定时间比较），错误 401；TLS 可开（GW_TLS）
- 出站 JSON 全量 redact（key/token/password/secret 字段替换）
- spawn 一律参数数组；prompt 只走 stdin；危险关键词/注入拦截在自动领取与执行前双重把关