scheduler-gateway/docs/DEVELOPMENT-ROADMAP.md

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

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

1. 项目定位

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

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

建议将产品定位为：面向开发、研究、运营和自动化任务的 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. 目标架构

                    ┌────────────────────────────┐
                    │ 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 任务

{
  "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 执行尝试

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

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

6.3 产物

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

7. API 演进建议

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

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。它们决定后续数据库、多实例、权限和远程节点能否平稳演进。