scheduler-gateway/docs/PHASE-2-P1-PLATFORM.md

调度网关第二阶段统一开发任务书（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 已完成，直接在此基础上开发）

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 可用且脱敏。
• 结构化日志字段齐全。

回归验收

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 拼接、动态代码执行或不受限文件路径。

七、交付物格式（每个模型必须提交）

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、伪造凭据等安全路径均有拒绝证据。
• 现有面板、插件、看板桥、团队编排未被破坏。
• 文档、测试数字与代码实际状态一致。