# 调度网关第二阶段统一开发任务书（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、伪造凭据等安全路径均有拒绝证据。 - 现有面板、插件、看板桥、团队编排未被破坏。 - 文档、测试数字与代码实际状态一致。