Liuxinyu176
bbb364cd69
- 零第三方依赖，Node >=20 原生 ESM - 团队式编排引擎：拆解/路由/执行/审查/合并全真实 LLM - 阶段心跳、单一权威清单守卫、all-keys-failed 如实上报 - H4 会话视图/amend/watchdog 有界重试/产物区 artifacts.json - H5 零依赖三栏控制台
207 lines
12 KiB
Markdown
207 lines
12 KiB
Markdown
# 调度网关第二阶段统一开发任务书（P1 平台化）
|
||
|
||
**任务书版本**：1.0
|
||
**发布日期**：2026-09-10
|
||
**适用项目**：scheduler-gateway-epoch 6.0.0（P0 生产化基线已合并完成）
|
||
**执行方式**：四个模型同时执行同一份任务书
|
||
**阶段名称**：P1 平台化（多用户 / 任务模板 / 凭据与权限 / 执行器平台化）
|
||
|
||
## 一、任务目标
|
||
|
||
在 P0 生产化基线（状态机 / Repository / 幂等 lease / revision 乐观锁 / 事件持久化 /
|
||
回调 HMAC / 取消传播 / 死信加固 / 健康检查）全部完成并合入的基础上，把单机原型升级为
|
||
**多用户、多项目、可策略治理、执行器可平台化的运行平台**，同时保持现有 API、面板、
|
||
插件、看板桥与团队编排兼容。
|
||
|
||
1. 引入项目（projectId）边界：任务、运行、节点、产物、审计、死信查询强制带项目边界。
|
||
2. 引入身份与权限：节点 token 可创建/禁用/轮换，禁止长期使用默认 token；权限分级。
|
||
3. 引入任务模板与策略引擎：版本化 JSON Schema 的任务 schema、策略字段与检查。
|
||
4. 执行器平台化：节点注册元数据扩展，外部 CLI 统一 adapter 生命周期接口，节点 drain 与标签。
|
||
5. 统一 API v1 与可观测性：`/api/v1` 前缀、分页/过滤/排序、结构化日志与 metrics。
|
||
|
||
本阶段**不做**数据库强制迁移（FileRepository 保持默认可用，SQLite/PG 只留接口与文档）、
|
||
不做 SSH 真实接入（保留协议预留）、不重写团队编排器、不开发新模型适配器。
|
||
|
||
## 二、当前代码基线（P0 已完成，直接在此基础上开发）
|
||
|
||
```text
|
||
src/domain/errors.js 已知错误码 + GatewayError
|
||
src/domain/task-state-machine.js A：状态机（canTransition/transition/别名/终态）
|
||
src/domain/repositories.js B：Repository 接口 + 失败分类
|
||
src/adapters/storage/file-repository.js B+H：File/Event/DeadLetter Repository
|
||
src/application/task-service.js C/D/G/J/K：create/approve/settle/cancel/retryDead
|
||
src/application/callback.js I：回调 HMAC + 指数退避 + 幂等头
|
||
src/platform/config.js E：loadConfig/checkConfig/redactConfig
|
||
src/platform/health.js E：healthz/readyz
|
||
src/server.js 状态机/服务接缝；X-Request-Id；错误信封；SSE 补播；Idempotency-Key
|
||
src/scheduler-core.js claim lease / settle 校验 / 死信完整字段
|
||
src/node-runtime.js 回报携带 lease/attempt/revision；cancelLoop
|
||
test/phase1.mjs P0 专项 114 断言（并入 live-suite S 段）
|
||
P0-DELIVERY.md P0 交付报告（修改清单/迁移表/Repository/幂等语义/性能基线）
|
||
```
|
||
|
||
现有行为、接口、测试是兼容基线；除非本任务书明确要求，不得删除、改名或改变既有 API 语义。
|
||
|
||
## 三、统一技术约束（必须遵守）
|
||
|
||
- Node.js >= 20，原生 ESM，零第三方运行时依赖（本阶段同样不得引入第三方运行时依赖）。
|
||
- 只使用 ASCII 新增代码和注释；已有中文文件按原编码维护。
|
||
- 不得修改 `_archive`、`out`、`work`、`evidence` 中已有历史产物。
|
||
- 不得把密钥写入日志、测试快照、证据文件、任务结果、argv 或错误消息。
|
||
- 不得通过任意 `task.state = ...` 绕过状态机；新增路径一律走统一状态机/服务。
|
||
- 不得为了让测试通过而静默吞错、伪造 REAL 结果或扩大重试上限。
|
||
- 保留并扩展 REAL/OFFLINE/fixture 诚实标记。
|
||
- 生产默认配置不能依赖 `dev-token-change-me`；任一安全模式必须能拒绝不安全默认值。
|
||
- 所有新能力必须带离线测试、故障测试与真实运行证据；不得只新增函数不接入真实路径。
|
||
|
||
## 四、统一交付范围
|
||
|
||
### 任务 L：项目与租户边界（P1-01）
|
||
|
||
- 任务、运行、节点、产物、审计、死信全部引入 `projectId`；默认项目为 `default`（兼容旧数据）。
|
||
- 创建任务支持 `projectId`；列表/查询接口支持按项目过滤；跨项目操作必须拒绝或显式声明。
|
||
- 产物索引（artifacts 索引）携带 projectId，下载/访问校验项目边界。
|
||
- 审计记录追加 `projectId`；面板/导出可筛选。
|
||
- 保留 `persist:false` 内存测试模式与既有数据兼容（旧记录视为 default 项目）。
|
||
|
||
### 任务 M：身份、凭据与权限（P1-02）
|
||
|
||
- 节点 token 纳入凭据管理：支持创建/禁用/过期时间/轮换（`GET/POST /api/v1/nodes/:id/credentials` 或等价）。
|
||
- 服务间使用短期 token 或复用现有节点 token 机制扩展；**禁止长期使用默认 token**，
|
||
生产/安全模式检测到默认 token 直接拒绝启动或明确警告（已有 checkConfig 基础上扩展）。
|
||
- 权限至少分为：查看任务 / 创建任务 / 审批任务 / 管理节点 / 查看敏感证据 / 管理预算（可枚举枚举实现，
|
||
不要求完整 RBAC 引擎）。
|
||
- 管理节点 / 敏感证据等敏感操作必须有权限校验；无权限返回统一 403 错误信封。
|
||
- 密钥脱敏全面覆盖：错误、审计、状态、导出、日志均不得出现明文 token/key/password/secret。
|
||
|
||
### 任务 N：任务模板与策略引擎（P1-03a）
|
||
|
||
- 把任务输入固化为版本化 JSON Schema（`src/domain/task-schema.js` 或等价），提供校验函数
|
||
（字段类型/必填/regex/裁剪），非法任务创建请求以统一错误码（INVALID_ARGUMENT）拒绝。
|
||
- 支持任务模板：至少 4 个内置模板（coding / research / writing / data-processing），
|
||
每个模板含默认 prompt 骨架、默认 capabilities、默认策略。
|
||
- 支持策略字段（任务自带或模板带入）：`allowNodes`、`maxAttempts`、`timeoutMs`、`maxCost`、
|
||
`requiresApproval`、`allowNetwork`、`allowFiles`。
|
||
- `SecurityGuard`/安全检查升级为策略引擎：输入检查、路径范围、出站动作审批、
|
||
成本/时长熔断（超出 maxCost/maxAttempts 时任务进入 failed/dead 并审计）。
|
||
|
||
### 任务 O：执行器与节点平台化（P1-03b）
|
||
|
||
- 节点注册信息扩展：`version`、`os`、`region`、`resources`、`capabilitiesVersion`、`health`（健康探针时间戳）。
|
||
- 外部 CLI 执行器统一 adapter 生命周期接口：`start / cancel / checkTimeout / collectLog / collectArtifacts / exitReason`
|
||
（在现有 `src/nodes/*` 与 `src/team/installer.js` 之上封装，不破坏既有行为）。
|
||
- 节点 drain：标记 drain 节点不再接新任务，但允许在途任务完成；现有任务可重投到其它节点。
|
||
- 节点标签与亲和性：节点可打标签（如 gpu/windows/private-network/coding），任务策略中的
|
||
`allowNodes` / 标签匹配影响调度路由。
|
||
|
||
### 任务 P：统一 API v1 与可观测性（P1-04）
|
||
|
||
- 新增 `/api/v1/...` 版本化接口族（任务 CRUD、运行、事件、审计、节点、死信、健康），
|
||
旧 `/api/tasks` 等接口保留兼容期并在文档标注 deprecated。
|
||
- 所有 v1 列表接口支持 `page/pageSize`、`filter`、`sort`、时间范围。
|
||
- 写接口全面支持 `Idempotency-Key` 与 `X-Request-Id`（继承 P0 已实现的机制并拓展到新接口）。
|
||
- 结构化 JSON 日志：每条日志带 `timestamp / requestId / runId / taskId / nodeId / stage`。
|
||
- 新增 `/metrics`（进程/任务吞吐/排队时长/执行时长/成功率/重试率/死信数/节点在线率，简单计数器即可）。
|
||
- /healthz、/readyz 保持可用，/readyz 纳入新配置项检查。
|
||
|
||
### 任务 Q：补齐测试与验证脚本（P1-05）
|
||
|
||
新增/扩展测试，覆盖以上 L/M/N/O/P 每个任务：
|
||
|
||
- 项目边界：跨项目操作拒绝、默认项目兼容、产物下载越权拒绝。
|
||
- 凭据与权限：token 创建/禁用/轮换、过期 token 拒绝、默认 token 拒绝启动、越权 403。
|
||
- 模板与策略：模板校验、非法任务拒绝、策略熔断（超过 maxAttempts/maxCost 进 dead）、无权限操作拒绝。
|
||
- 节点平台：drain 不再派发新任务、标签亲和性路由、adapter 生命周期（cancel/超时/日志/产物）。
|
||
- 可观测：/metrics 计数器存在、结构化日志字段齐全、/readyz 对不安全默认值失败。
|
||
- 回归：P0 全部测试（npm test / test:conversation / e2e-team / recovery-demo / stress）保持通过。
|
||
|
||
## 五、明确不允许的实现结果
|
||
|
||
- 只新增 schema/字段但未接入真实任务/查询/调度路径。
|
||
- 用放宽断言、删除测试、无限重试来"制造全绿"。
|
||
- 把项目边界做成装饰性字段（查询仍可跨项目读到别项目数据）。
|
||
- token 权限校验形同虚设（任何 token 都可通过敏感操作）。
|
||
- 引入数据库/Redis/MQ 作为本阶段必须依赖，破坏零依赖模式。
|
||
- 修改归档文件或清理 evidence 掩盖回归。
|
||
- metrics/日志字段只是打印出来但没有真实指标聚合与导出。
|
||
|
||
## 六、完成验收标准
|
||
|
||
### 功能验收
|
||
|
||
- [ ] 项目边界生效：跨项目创建/查询/产物访问被拒绝或隔离。
|
||
- [ ] 节点 token 可管理（创建/禁用/轮换），默认 token 在生产/安全模式被拒绝。
|
||
- [ ] 权限分级生效：敏感操作无权限返回 403。
|
||
- [ ] 任务 schema 校验生效：非法请求 INVALID_ARGUMENT。
|
||
- [ ] 内置任务模板可创建对应任务；策略熔断生效。
|
||
- [ ] 节点 drain 与标签亲和性生效。
|
||
- [ ] /api/v1 可用，旧接口兼容期内仍工作。
|
||
- [ ] /metrics、/healthz、/readyz 可用且脱敏。
|
||
- [ ] 结构化日志字段齐全。
|
||
|
||
### 回归验收
|
||
|
||
```powershell
|
||
npm test
|
||
npm run test:conversation
|
||
npm run e2e-team
|
||
npm run recovery-demo
|
||
npm run stress
|
||
```
|
||
|
||
所有命令退出码为 0；若本机无真实 LLM key，真实 LLM 命令不得伪装成功，沿用 OFFLINE/fixture 方式。
|
||
|
||
### 性能验收
|
||
|
||
- 现有 stress 规模无重复领取、无永久丢失、无重复终态。
|
||
- 引入项目边界/schema 校验后，stress 吞吐下降不超过 10%；提供改造前后 baseline 对比。
|
||
|
||
### 安全验收
|
||
|
||
- 错误、审计、状态、导出、日志均无任何 key/token/password/secret 明文。
|
||
- 默认 token、越权、跨项目访问、伪造 lease 均有拒绝结果。
|
||
- 不引入新的 shell 拼接、动态代码执行或不受限文件路径。
|
||
|
||
## 七、交付物格式（每个模型必须提交）
|
||
|
||
```text
|
||
1. 修改文件清单
|
||
2. 实现摘要
|
||
3. 项目边界/权限/模板/策略设计说明
|
||
4. 新增接口说明（含 /api/v1 路由表）
|
||
5. 测试命令与实际结果
|
||
6. 未完成项和已知风险
|
||
7. 与其它模型合并时的冲突点
|
||
```
|
||
|
||
禁止只提交"已完成/测试通过"等无证据结论。
|
||
|
||
## 八、四模型协作规则
|
||
|
||
四个模型使用完全相同任务书，各自独立工作区/分支，禁止互相覆盖文件。为减少冲突，建议侧重
|
||
（验收标准对四模型完全相同，不以分工为由留下失败测试）：
|
||
|
||
- 模型 1：重点任务 L（项目边界）+ 任务 P 的 /api/v1 与旧接口兼容。
|
||
- 模型 2：重点任务 M（凭据与权限）+ 安全验收（防越权/脱敏/默认 token 拒绝）。
|
||
- 模型 3：重点任务 N（模板与策略引擎）+ 策略熔断 + 任务 O 的节点 drain/标签/亲和性。
|
||
- 模型 4：重点任务 O 的 executor adapter 生命周期 + 任务 Q（测试补齐）+ metrics/日志/readyz。
|
||
|
||
合并顺序建议：schema/错误码基座 → 项目边界 → 凭据权限 → 模板策略 → 节点平台 → v1 与可观测 → 全量回归。
|
||
|
||
## 九、给模型的执行指令
|
||
|
||
你正在参与 scheduler-gateway-epoch 第二阶段 P1 平台化开发。请严格按本任务书执行：先阅读
|
||
README、ARCHITECTURE、IMPLEMENTATION、ADR、P0-DELIVERY.md 与相关源码，确认 P0 基线行为后
|
||
再修改。你的目标是提交可合并代码，而不是写方案。保持 Node >=20、零第三方运行时依赖、
|
||
REAL/OFFLINE/fixture 诚实标记与现有 API 兼容（旧接口兼容期内不可破坏）。所有新能力必须
|
||
接入真实任务路径并补充离线/故障/安全测试。完成后运行对应测试，报告实际命令、退出码、
|
||
修改文件与剩余风险。不得修改归档目录，不得删除用户已有改动，不得泄漏任何密钥。
|
||
|
||
## 十、阶段完成定义
|
||
|
||
- 项目边界、凭据权限、模板策略、执行器平台、v1 API、可观测性全部接入真实路径。
|
||
- 全量回归（P0+P1 新测试）通过。
|
||
- 越权、跨项目、默认 token、伪造凭据等安全路径均有拒绝证据。
|
||
- 现有面板、插件、看板桥、团队编排未被破坏。
|
||
- 文档、测试数字与代码实际状态一致。
|