Liuxinyu176
bbb364cd69
- 零第三方依赖，Node >=20 原生 ESM - 团队式编排引擎：拆解/路由/执行/审查/合并全真实 LLM - 阶段心跳、单一权威清单守卫、all-keys-failed 如实上报 - H4 会话视图/amend/watchdog 有界重试/产物区 artifacts.json - H5 零依赖三栏控制台
346 lines
17 KiB
Markdown
346 lines
17 KiB
Markdown
# 调度网关后续发展开发说明书
|
||
|
||
**文档版本**：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。它们决定后续数据库、多实例、权限和远程节点能否平稳演进。
|