# 调度网关后续发展开发说明书

**文档版本**：1.0  
**编写日期**：2026-09-09  
**适用版本**：scheduler-gateway-epoch 6.0.0  
**文档目的**：把当前可演示、可验收的调度网关原型，演进为可长期运行、可扩展、可审计的团队式 AI 执行平台。

## 1. 项目定位

本项目的核心不是“再接几个模型”，而是提供一个统一执行平面：

```text
用户目标
  -> 计划拆解
  -> 能力路由
  -> 多节点执行
  -> 产物归档
  -> 自动审查/返工
  -> 合并交付
  -> 全程可观测、可追责、可重放
```

建议将产品定位为：**面向开发、研究、运营和自动化任务的 AI 团队调度网关**。

## 2. 当前状态判断

### 2.1 已具备能力

- 中心网关、任务队列、优先级、依赖、审批门、重试、死信和节点掉线重投。
- `native`、`adapter`、命令行、HTTP LLM、Codex 等多种执行器接入方式。
- 统一 `gw-node/1` 节点协议，支持注册、心跳、长轮询和结果回报。
- 真实 LLM 驱动的拆解、路由、执行、评审、返工和合并流程。
- 运行证据：计划、路由、执行、评审、产物索引、审计和最终结果。
- 单机控制台、SSE、产物下载、任务看板桥和 DSH 插件薄封装。
- WAL 可选恢复、任务工作区隔离、危险命令和提示词注入基础拦截、密钥脱敏。
- 离线演示、真实模式和确定性测试夹具。

### 2.2 当前主要短板

1. **持久化仍偏单机文件**：主状态是 JSON 文件，WAL 是 JSONL，适合原型和单实例，不适合多实例、高并发和复杂查询。
2. **认证模型单一**：节点主要依赖共享 token，缺少用户、租户、角色、权限和密钥轮换。
3. **调度器是单进程中心模型**：没有明确的 leader、分布式锁、跨实例幂等和队列分片机制。
4. **可观测性不足以支撑生产运维**：已有审计和证据文件，但缺少结构化日志、指标、trace、告警和容量看板。
5. **执行器能力不均衡**：SSH/Hermes 仍是预留能力，Codex 依赖本机环境，外部 CLI 的生命周期和资源限制还需要平台化。
6. **任务契约还不够标准化**：输入、输出、产物、验收标准、超时、预算和权限边界需要统一 schema。
7. **控制台与后端耦合较重**：多个面板入口、轮询和文件读取逻辑并存，后续应统一 API 和前端状态模型。
8. **文档和版本信息存在历史痕迹**：README 中部分测试数字和版本描述需要与当前代码、当前验收结果统一。

### 2.3 发展原则

- 先稳定任务生命周期，再增加模型和节点类型。
- 先建立可审计的数据模型，再扩大自动化权限。
- 默认安全、默认可回放、默认诚实标注 REAL/OFFLINE/fixture。
- 核心调度逻辑与 HTTP、面板、插件解耦。
- 所有新能力都必须有离线测试、故障测试和真实运行证据。

## 3. 目标架构

```text
                    ┌────────────────────────────┐
                    │ Web / DSH / Open API       │
                    └─────────────┬──────────────┘
                                  │
                    ┌─────────────▼──────────────┐
                    │ API / Auth / Tenant Layer   │
                    └─────────────┬──────────────┘
                                  │
        ┌─────────────────────────▼─────────────────────────┐
        │                 Orchestration Service              │
        │ plan / route / execute / review / rework / merge   │
        └──────────────┬───────────────────────┬─────────────┘
                       │                       │
              ┌────────▼────────┐     ┌──────▼─────────┐
              │ Scheduler       │     │ Policy/Budget  │
              │ queue/lease/DLQ  │     │ auth/cost/risk │
              └────────┬────────┘     └──────┬─────────┘
                       │                       │
              ┌────────▼─────────────────────▼────────┐
              │ PostgreSQL / Redis / Object Storage    │
              │ task state / events / locks / artifacts│
              └──────────────────┬─────────────────────┘
                                 │
             ┌───────────────────▼───────────────────┐
             │ Node Gateway Protocol gw-node/1       │
             └───────┬───────────┬───────────┬───────┘
                     │           │           │
                native       HTTP LLM     CLI/SSH
```

## 4. 分阶段路线

### 阶段 A：生产化基线（优先级 P0，建议 2-4 周）

目标：让单机版本可稳定部署、可恢复、可诊断。

#### A1. 统一配置与启动

- 新增 `config` 模块，统一读取环境变量、配置文件和命令行参数。
- 启动时输出脱敏后的配置摘要、协议版本和数据目录。
- 增加 `gateway check`：检查 Node、目录权限、端口、密钥、TLS、外部 CLI 和任务看板。
- 将 `server`、`team panel`、节点进程的默认端口和数据目录统一配置。

#### A2. 任务生命周期加固

- 为任务状态建立显式状态机，禁止任意字段直接修改状态。
- 增加 `queued/running/succeeded/failed/canceled/expired/dead` 的状态转换校验。
- 为 claim、settle、retry、cancel、approve 增加幂等键。
- 每个任务记录 `leaseId`、`leaseExpiresAt`、`attemptNo`、`executorId` 和 `traceId`。
- 增加任务超时、节点心跳超时、回调重试和回调签名。

#### A3. 持久化替换方案

- 短期：保留 JSON/WAL，但把写入、恢复和清理封装在 `repository` 接口后面。
- 默认数据库：PostgreSQL；本地开发可使用 SQLite 或当前文件存储。
- 产物与证据不放数据库大字段，统一写对象存储或本地 artifact root，数据库保存 metadata 和 hash。
- 数据库表至少包括：`tasks`、`task_attempts`、`nodes`、`runs`、`events`、`artifacts`、`audit_logs`、`dead_letters`、`api_keys`。

#### A4. 可观测性

- 结构化 JSON 日志：每条日志必须带 `timestamp/requestId/runId/taskId/nodeId/stage`。
- 指标：任务吞吐、排队时长、执行时长、成功率、重试率、死信数、节点在线率、LLM token、429/5xx、预算熔断次数。
- 为每次编排建立 trace：`plan -> route -> execute -> review -> merge`。
- 增加 `/healthz`、`/readyz`、`/metrics`。

#### A5. P0 验收标准

- 进程异常退出后，任务不会重复执行或永久丢失。
- 同一幂等请求重复提交只产生一个任务。
- 任务超时、节点掉线、回调失败均可在控制台和审计中定位。
- 不配置 LLM key 时，REAL 模式明确失败，OFFLINE 模式不触网。
- 现有测试全部通过，并新增数据库 repository、幂等和恢复测试。

### 阶段 B：平台化能力（优先级 P1，建议 4-8 周）

目标：从单机工具升级为多用户、多项目、多节点平台。

#### B1. 身份与权限

- 引入用户、组织、项目三个层级。
- 支持 OIDC/OAuth2 登录；服务间使用短期 token 或 mTLS。
- 权限至少分为：查看任务、创建任务、审批任务、管理节点、查看敏感证据、管理预算。
- 节点 token 支持创建、禁用、过期和轮换，禁止长期使用默认 token。

#### B2. 任务模板和策略

- 把任务 schema 固化为版本化 JSON Schema。
- 支持任务模板：编码、研究、写作、数据处理、发布、审核。
- 支持策略字段：允许的节点、最大成本、最大时长、网络权限、文件权限、是否需要人工确认。
- 将 `SecurityGuard` 升级为策略引擎：输入检查、工具白名单、路径范围、出站域名和高风险动作审批。

#### B3. 节点与执行器平台

- 节点注册信息增加版本、运行环境、地区、资源、能力版本和健康探针。
- 外部 CLI 统一为 executor adapter 接口：启动、取消、超时、日志、产物、退出原因。
- 实现 SSH 节点时使用短期凭据、固定工作目录、命令白名单和主机指纹校验。
- 增加节点 drain：不再接收新任务，但允许在途任务完成。
- 增加节点标签和亲和性调度，例如 `gpu`、`windows`、`private-network`、`coding`。

#### B4. 事件与实时状态

- SSE 继续支持浏览器；同时提供 WebSocket 或消息队列订阅接口。
- 事件必须有序列号、事件类型、聚合对象、版本号和重放位置。
- 控制台统一使用 `/api/v1`，旧接口保留兼容期。

#### B5. P1 验收标准

- 不同项目之间任务、节点、产物和审计完全隔离。
- 用户无法访问无权限的产物和密钥字段。
- 节点可在不中断已有任务的情况下升级或下线。
- 任务模板可复用，且模板升级不破坏历史运行记录。

### 阶段 C：规模化与生态（优先级 P2，建议 2-3 个月）

目标：支持多实例、高并发和外部系统集成。

- 调度器拆分为 API、编排、执行调度、节点接入、通知等独立服务。
- 使用 Redis Streams、NATS 或同类消息系统承载派发和事件；数据库保留权威状态。
- 引入 leader election 或基于数据库的租约，保证同一任务只由一个调度者推进。
- 任务队列按租户、优先级、能力和区域分片。
- 增加预算中心、模型路由、供应商健康评分和跨供应商故障转移。
- 增加插件 SDK、Webhook、CLI SDK、Python 客户端和任务模板市场。
- 支持归档策略、数据保留期、审计导出、合规删除和证据 hash 校验。
- 建立容量压测：1 万任务、100 节点、持续 1 小时，目标是无重复领取、无永久丢失、P99 排队和执行延迟可接受。

## 5. 建议的代码重构顺序

当前 `src/server.js`、`src/store.js` 和 `src/team/orchestrate.js` 承担的职责较多，建议按以下顺序拆分，避免一次性重写：

1. `src/domain/`：任务、运行、节点、事件、状态机和错误码。
2. `src/application/`：创建任务、领取、结算、重试、编排、审批等用例。
3. `src/adapters/http/`：REST、SSE、面板静态资源和请求校验。
4. `src/adapters/storage/`：file、WAL、SQLite、PostgreSQL repository。
5. `src/adapters/executors/`：native、http-llm、cli、codex、ssh。
6. `src/platform/`：配置、日志、metrics、trace、密钥和健康检查。

原则：先让旧入口调用新的 application service，再删除旧逻辑；每次只迁移一个用例。

## 6. 核心数据契约建议

### 6.1 任务

```json
{
  "id": "task_xxx",
  "schemaVersion": 1,
  "projectId": "project_xxx",
  "runId": "run_xxx",
  "title": "任务标题",
  "prompt": "任务目标",
  "acceptance": ["可检验标准"],
  "capabilities": ["coding", "worker"],
  "policy": {
    "maxAttempts": 3,
    "timeoutMs": 600000,
    "maxCost": 10,
    "requiresApproval": false
  },
  "state": "queued",
  "attemptNo": 0,
  "lease": null,
  "result": null,
  "createdAt": "2026-09-09T00:00:00.000Z"
}
```

### 6.2 执行尝试

每次执行必须单独记录，不覆盖历史：

```text
attemptId / taskId / nodeId / executor
startedAt / finishedAt / durationMs
exitCode / outcome / errorCode
inputHash / outputHash / artifactIds
tokenUsage / cost / retryReason
```

### 6.3 产物

产物记录应包含路径、大小、媒体类型、SHA-256、来源任务、是否权威、创建时间和访问策略。禁止只依赖文件名判断权威产物。

## 7. API 演进建议

保留现有接口作为兼容层，新增版本化接口：

```text
POST   /api/v1/projects
GET    /api/v1/projects/:id
POST   /api/v1/runs
GET    /api/v1/runs/:id
POST   /api/v1/runs/:id/cancel
POST   /api/v1/runs/:id/approve
GET    /api/v1/runs/:id/events
GET    /api/v1/tasks/:id
POST   /api/v1/tasks/:id/retry
POST   /api/v1/tasks/:id/amend
GET    /api/v1/artifacts/:id
GET    /api/v1/audit
```

所有写接口建议支持：

- `Idempotency-Key`。
- `X-Request-Id`。
- 统一错误格式 `{code, message, requestId, details}`。
- 分页、过滤、排序和时间范围查询。
- 明确的权限检查和审计记录。

## 8. 测试与质量门禁

每次合并至少执行以下层级：

1. **单元测试**：状态机、调度排序、能力匹配、租约、重试、路径监牢、脱敏。
2. **契约测试**：节点协议、任务 schema、插件 API、看板 API。
3. **集成测试**：数据库、WAL 恢复、真实 HTTP worker、外部 CLI fixture。
4. **故障测试**：节点掉线、进程崩溃、重复回报、429、超时、磁盘写失败、回调失败。
5. **安全测试**：越权、路径穿越、命令注入、提示词注入、密钥泄漏、恶意安装源。
6. **性能测试**：吞吐、P95/P99 延迟、并发节点、事件订阅、恢复时间。
7. **真实模式验收**：REAL、OFFLINE、fixture 三种结果必须明确标识，不混淆证据。

质量门禁建议：测试失败禁止发布；安全扫描和密钥扫描失败禁止发布；没有 migration、回滚方案和变更说明禁止生产升级。

## 9. 发布与运维

- 建议使用 Docker/Windows 服务包装器统一启动网关、节点和控制台。
- 生产环境必须显式配置数据目录、日志目录、TLS、节点 token、LLM key 和备份策略。
- 发布采用 `major.minor.patch`，协议变更单独提升 `gw-node` 协议版本。
- 数据库变更必须有向前 migration 和回滚说明。
- 每个版本保存：构建信息、依赖版本、配置摘要、测试报告、压测报告和安全报告。
- 至少保留一份可恢复备份，并定期演练从备份恢复任务、审计和产物索引。

## 10. 第一批开发任务清单

### P0-01：任务状态机

新增状态转换表和统一 service，替换直接写 `task.state` 的路径；补齐非法转换、重复结算和取消竞态测试。

### P0-02：Repository 抽象

定义 `TaskRepository`、`NodeRepository`、`EventRepository`、`ArtifactRepository` 接口；先实现 `FileRepository`，保证现有行为不变。

### P0-03：幂等与租约

为创建、claim、settle、retry 增加幂等键和租约字段；模拟重复请求、节点重启和延迟回报。

### P0-04：统一配置和健康检查

实现 `gateway check`、`/healthz`、`/readyz`，启动时拒绝不安全的生产默认配置。

### P0-05：结构化日志与 metrics

不改变业务流程，先为 server、scheduler、orchestrator、executor 加 request/run/task/node 关联字段。

### P1-01：用户和项目隔离

引入 projectId，所有任务、运行、节点、产物和审计查询强制带项目边界。

### P1-02：凭据轮换与权限

节点 token、LLM provider key、插件访问权限统一纳入凭据管理和审计。

### P1-03：执行器生命周期

统一启动、取消、超时、日志、产物和资源限制接口，优先改造 CLI 和 HTTP worker。

## 11. 暂不建议优先做的事情

- 暂不优先增加更多模型品牌；在模型数量增加前先完成 provider 抽象、预算和故障转移。
- 暂不优先做复杂大屏；当前控制台应先补齐筛选、错误定位、权限和运行详情。
- 暂不直接重写全部编排器；先用 application service 包住现有实现，再逐段迁移。
- 暂不把所有证据塞进数据库；大文件应使用对象存储或文件存储，数据库保存索引和 hash。
- 暂不开放无策略的任意 shell/SSH；远端执行必须和权限、网络、审计、取消机制一起交付。

## 12. 完成定义

当满足以下条件时，项目可以从“原型”进入“内部生产试用”：

- 单实例连续运行 7 天，无任务永久丢失和重复终态。
- 进程、节点、LLM provider、数据库和磁盘故障均有恢复或明确失败结果。
- 用户、项目、节点、任务、产物和审计边界可验证。
- 关键指标、日志和 trace 能定位一次失败的完整链路。
- P0 任务全部完成，P0/P1 测试门禁纳入自动化发布流程。
- README、架构文档、API 文档和验收数字与代码实际状态一致。

**建议的下一步**：先实施 P0-01、P0-02、P0-03。它们决定后续数据库、多实例、权限和远程节点能否平稳演进。