From b8529abed10cc3d9ac81b0c21c202087cc1d7811 Mon Sep 17 00:00:00 2001 From: Codex Date: Sun, 14 Jun 2026 15:33:10 +0000 Subject: [PATCH] docs: govern HWLAB requirements specs --- .../unidesk-oa/references/project-planning.md | 10 +- .../PJ2026-01/specs/PJ2026-01-HWLAB.md | 237 ++++++++++++------ .../PJ2026-01/specs/current-center.md | 58 ----- ...c-ieee-29148-requirements-spec-template.md | 124 +++++++++ 4 files changed, 291 insertions(+), 138 deletions(-) delete mode 100644 project-management/PJ2026-01/specs/current-center.md create mode 100644 project-management/templates/iso-iec-ieee-29148-requirements-spec-template.md diff --git a/.agents/skills/unidesk-oa/references/project-planning.md b/.agents/skills/unidesk-oa/references/project-planning.md index f634da7f..3377acbc 100644 --- a/.agents/skills/unidesk-oa/references/project-planning.md +++ b/.agents/skills/unidesk-oa/references/project-planning.md @@ -32,7 +32,11 @@ HWLAB Cloud M1 需要一个项目控制结构，避免局部 issue/PR 工作偏 不要把稳定需求的唯一副本放在 issue 评论里。长期有效的需求必须蒸馏到 `project-management/PJ2026-01`，再从 issue 链接过去。 不要把长证据正文放进项目管理目录。项目管理目录只承载规格、治理和阶段中心；长证据保留在 GitHub issue。 -所有 Markdown 正文、issue/PR 正文和评论中的 issue/PR 引用都必须写成 `[#](https://github.com///issues/)` 或 `[#](https://github.com///pull/)`，显示短号、链接目标保留完整 URL；不要显示裸长链接、裸井号编号或 `owner/repo` 加井号编号。`owner/repo#number` 只允许作为 CLI 命令参数 shorthand。 +规格文件和 GitHub issue 的引用规则分开处理： + +- `project-management/PJ2026-01/specs/*.md` 中，每个规格文件最多保留一个 GitHub issue 链接，即迁移来源表里的自身原 issue。 +- 规格文件引用其他规格时，使用同目录相对路径 Markdown 链接，例如 `[PJ2026-0101 硬件池](PJ2026-0101-hardware-pool.md)`；不要引用其他规格的 GitHub issue、证据 issue、PR 或裸 `#`。 +- GitHub issue/PR 正文和评论中的 issue/PR 引用必须写成 `[#](https://github.com///issues/)` 或 `[#](https://github.com///pull/)`，显示短号、链接目标保留完整 URL；不要显示裸长链接、裸井号编号或 `owner/repo` 加井号编号。`owner/repo#number` 只允许作为 CLI 命令参数 shorthand。 ## 当前 HWLAB issue 锚点 @@ -62,14 +66,14 @@ HWLAB Cloud M1 的长期文档放在 UniDesk 仓库内，并使用项目编号 ```text specs/PJ2026-01-HWLAB.md # L0 总规格，同时作为项目索引 -specs/stage-cloud-spec-20260601.md # 既有阶段材料 +specs/stage-cloud-spec-20260601.md # 既有阶段材料，同时承载阶段中心和非中心边界 specs/PJ2026-010N-*.md # L1 方向规格 specs/spec-governance.md # 编号、层级、回写与偏离规则 -specs/current-center.md # 当前中心和非中心边界 ``` 优先维护 L0 总规格作为入口索引。只有当某个部分具有独立生命周期和评审需要时才拆分到 L1、治理或阶段文件。 禁止在本目录新增 `evidence/` 或其他长证据目录；证据入口在 L0/L1 规格中引用 GitHub issue。 +禁止在规格文件正文链接证据 issue；只写“长证据保留在对应 GitHub 证据 issue”这类归属说明。证据 issue 的完整链接保留在 GitHub issue 正文或评论里。 每个长期规格文件最前面必须有修改历史表格，字段固定为： diff --git a/project-management/PJ2026-01/specs/PJ2026-01-HWLAB.md b/project-management/PJ2026-01/specs/PJ2026-01-HWLAB.md index 60cb7503..a816484c 100644 --- a/project-management/PJ2026-01/specs/PJ2026-01-HWLAB.md +++ b/project-management/PJ2026-01/specs/PJ2026-01-HWLAB.md @@ -4,10 +4,14 @@ | 版本 | 对应 commit id | 更新日期 | 变更说明 | | --- | --- | --- | --- | +| v0.8 | 待提交 | 2026-06-14 | 引用 ISO/IEC/IEEE 29148 需求规格模板。 | +| v0.7 | 待提交 | 2026-06-14 | 合并内部模块分工与规格索引，拆分全局原子需求并移除重复追踪章节。 | +| v0.6 | 待提交 | 2026-06-14 | 删除当前中心拆分文档，阶段中心口径统一回阶段规格。 | +| v0.5 | 待提交 | 2026-06-14 | 移除规格正文中的跨 issue 引用，跨规格关系改用相对路径链接。 | | v0.4 | b5d8cee438a3bd66ca440a25bf5a16d9081d9efa | 2026-06-14 | 将 issue/PR 引用显示改为短号 Markdown 链接，链接目标保留完整 URL。 | | v0.3 | b0cbe9b721b50e9fff4d350ee50ed2af03cf0405 | 2026-06-14 | 将 issue/PR 引用改为完整 GitHub URL，避免 Markdown 渲染时裸 # 编号失效。 | | v0.2 | b40a37ce771811cc97d74ef0909a7ce441161c6b | 2026-06-14 | 移除项目管理目录中的 evidence 文件，长证据保留在 GitHub issue。 | -| v0.1 | 37de91c653c055bf19ac271bdb687b54072639fa | 2026-06-14 | 从 [#1194](https://github.com/pikasTech/HWLAB/issues/1194) 迁移到 UniDesk 项目管理目录。 | +| v0.1 | 37de91c653c055bf19ac271bdb687b54072639fa | 2026-06-14 | 从原迁移 issue 迁移到 UniDesk 项目管理目录。 | ## 迁移来源 @@ -15,27 +19,11 @@ | --- | --- | | 原 issue | [#1194](https://github.com/pikasTech/HWLAB/issues/1194) | | 原标题 | PJ2026-01 HWLAB 总规格 | -| 原 URL | [#1194](https://github.com/pikasTech/HWLAB/issues/1194) | | 原状态 | open | | 原更新时间 | 2026-06-14T12:53:55Z | | 原 body SHA | 4868729f6e33eec813713e810700b510847164d799373edf01c8ff50126a04b6 | -## 项目规格索引 - -| 层级 | 文件 | 历史 issue | -| --- | --- | --- | -| 阶段规格 | [stage-cloud-spec-20260601.md](stage-cloud-spec-20260601.md) | [#644](https://github.com/pikasTech/HWLAB/issues/644) | -| L0 总规格 | [PJ2026-01-HWLAB.md](PJ2026-01-HWLAB.md) | [#1194](https://github.com/pikasTech/HWLAB/issues/1194) | -| L1 硬件池 | [PJ2026-0101-hardware-pool.md](PJ2026-0101-hardware-pool.md) | [#1203](https://github.com/pikasTech/HWLAB/issues/1203) | -| L1 Agent编排 | [PJ2026-0102-agent-orchestration.md](PJ2026-0102-agent-orchestration.md) | [#1204](https://github.com/pikasTech/HWLAB/issues/1204) | -| L1 HarnessRL | [PJ2026-0103-harness-rl.md](PJ2026-0103-harness-rl.md) | [#1205](https://github.com/pikasTech/HWLAB/issues/1205) | -| L1 客户端 | [PJ2026-0104-client.md](PJ2026-0104-client.md) | [#1206](https://github.com/pikasTech/HWLAB/issues/1206) | -| L1 用户管理 | [PJ2026-0105-user-management.md](PJ2026-0105-user-management.md) | [#1207](https://github.com/pikasTech/HWLAB/issues/1207) | -| L1 平台运维 | [PJ2026-0106-platform-ops.md](PJ2026-0106-platform-ops.md) | [#1208](https://github.com/pikasTech/HWLAB/issues/1208) | -| 治理规则 | [spec-governance.md](spec-governance.md) | [#1217](https://github.com/pikasTech/HWLAB/issues/1217) | -| 当前中心 | [current-center.md](current-center.md) | [#1218](https://github.com/pikasTech/HWLAB/issues/1218) | - -长证据不进入项目管理目录。硬件池证据保留在 [#1216](https://github.com/pikasTech/HWLAB/issues/1216)，Agent编排证据保留在 [#1223](https://github.com/pikasTech/HWLAB/issues/1223)；规格文件只引用证据 issue，不复制证据正文。 +长证据不进入项目管理目录。硬件池和 Agent编排 的长证据保留在各自的 GitHub 证据 issue；规格文件只描述证据归属，不复制证据正文，也不链接其他规格的 issue。 ## 正文 @@ -49,14 +37,14 @@ | 短名 | HWLAB | | 层级 | L0 总项目 | | 状态 | active / L0 需求规格锚点 | -| 长期面板 | [#645](https://github.com/pikasTech/HWLAB/issues/645) HWLAB 长期总面板 | -| 阶段规格 | [#644](https://github.com/pikasTech/HWLAB/issues/644) HWLAB Cloud SPEC / 云平台开发目标 20260601 | -| 阶段中心索引 | [#1218](https://github.com/pikasTech/HWLAB/issues/1218) HWLAB 当前中心索引：阶段主线与非中心边界 | -| 规格治理索引 | [#1217](https://github.com/pikasTech/HWLAB/issues/1217) HWLAB 规格治理索引：编号、层级、回写与偏离规则 | -| L1 划分 | 保持现有六方向：[#1203](https://github.com/pikasTech/HWLAB/issues/1203)、[#1204](https://github.com/pikasTech/HWLAB/issues/1204)、[#1205](https://github.com/pikasTech/HWLAB/issues/1205)、[#1206](https://github.com/pikasTech/HWLAB/issues/1206)、[#1207](https://github.com/pikasTech/HWLAB/issues/1207)、[#1208](https://github.com/pikasTech/HWLAB/issues/1208) | +| 长期面板 | HWLAB 长期总面板，仅作为 GitHub 导航面板，不作为规格正文来源 | +| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | +| 阶段规格 | [HWLAB Cloud SPEC / 云平台开发目标 20260601](stage-cloud-spec-20260601.md) | +| 规格治理索引 | [规格治理](spec-governance.md) | +| L1 划分 | 保持现有六方向：[硬件池](PJ2026-0101-hardware-pool.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md)、[平台运维](PJ2026-0106-platform-ops.md) | | 规格来源 | `project-management/PJ2026-01` 与迁移前 HWLabOA 阶段材料 | -本文采用中文 L0 需求规格模板：正文只保留稳定使命、范围、运行概念、系统边界、L1 分配、全局原子需求、验证矩阵和追踪关系。编号规则、层级职责、回写、偏离判定和交叉引用治理迁入 [#1217](https://github.com/pikasTech/HWLAB/issues/1217)；阶段主线和非中心边界迁入 [#1218](https://github.com/pikasTech/HWLAB/issues/1218)。 +本文采用 [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) 的 HWLAB 裁剪版：正文只保留稳定使命、范围、运行概念、系统边界、内部模块分工和全局原子需求。编号规则、层级职责、回写、偏离判定和交叉引用治理迁入 [规格治理](spec-governance.md)；阶段目标和阶段优先级由 [HWLAB Cloud SPEC](stage-cloud-spec-20260601.md) 承载。 ## 2. 目的和范围 @@ -78,8 +66,8 @@ HWLAB 的中心目标是把真实硬件资源、Agent 执行、Harness/RL 验收 - 无 L1 主责归属的孤立工具美化、旧门禁修补或无原入口验收的观测增强。 - 单个 PR、一次 CaseRun、一次 smoke、一次部署或阶段报告流水；这些属于 L3/L4 或报告，不属于 L0 需求规格正文。 - 具体实现设计、代码结构、临时运行面调试路径、原始日志堆叠和每日进展统计。 -- 编号、回写、偏离和管理流程全文；这些由 [#1217](https://github.com/pikasTech/HWLAB/issues/1217) 承载。 -- 当前阶段优先级和阶段主线全文；这些由 [#1218](https://github.com/pikasTech/HWLAB/issues/1218) 和 [#644](https://github.com/pikasTech/HWLAB/issues/644) 承载。 +- 编号、回写、偏离和管理流程全文；这些由 [规格治理](spec-governance.md) 承载。 +- 当前阶段优先级和阶段主线全文；这些由 [HWLAB Cloud SPEC](stage-cloud-spec-20260601.md) 承载。 ## 3. 运行概念 @@ -104,66 +92,161 @@ HWLAB 的中心目标是把真实硬件资源、Agent 执行、Harness/RL 验收 | 长期文档 | `project-management/PJ2026-01` 规格、实施方案、测试规格、阶段报告 | | 执行控制面 | HWLAB GitHub issue 树、PR、trace/session/job/run/case registry 证据 | -## 5. L1 方向树 +## 5. 内部模块分工与规格索引 -L1 划分保持现有六方向；本次整理不新增、不删除、不重命名 L1。 +L1 划分保持现有六个内部能力模块；本章同时作为内部模块分工和方向规格索引。 -| 编号 | 短名 | L1 规格 issue | 主责 | 上游依赖 | 下游支撑 | +| 编号 | 内部模块 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 | | --- | --- | --- | --- | --- | --- | -| PJ2026-0101 | 硬件池 | [#1203](https://github.com/pikasTech/HWLAB/issues/1203) | 板卡、探针、HWPOD node、设备注册、资源占用、设备健康、可用性 | [#1208](https://github.com/pikasTech/HWLAB/issues/1208) 平台运维 | [#1204](https://github.com/pikasTech/HWLAB/issues/1204) Agent编排、[#1205](https://github.com/pikasTech/HWLAB/issues/1205) HarnessRL、[#1206](https://github.com/pikasTech/HWLAB/issues/1206) 客户端 | -| PJ2026-0102 | Agent编排 | [#1204](https://github.com/pikasTech/HWLAB/issues/1204) | Code Agent、AgentRun、workspace、session、provider profile、任务生命周期、任务恢复 | [#1203](https://github.com/pikasTech/HWLAB/issues/1203) 硬件池、[#1208](https://github.com/pikasTech/HWLAB/issues/1208) 平台运维、[#1207](https://github.com/pikasTech/HWLAB/issues/1207) 用户管理 | [#1205](https://github.com/pikasTech/HWLAB/issues/1205) HarnessRL、[#1206](https://github.com/pikasTech/HWLAB/issues/1206) 客户端 | -| PJ2026-0103 | HarnessRL | [#1205](https://github.com/pikasTech/HWLAB/issues/1205) | harness、CaseRun、ioProbe、evidence、评估、回放、训练反馈、RL 闭环 | [#1203](https://github.com/pikasTech/HWLAB/issues/1203) 硬件池、[#1204](https://github.com/pikasTech/HWLAB/issues/1204) Agent编排、[#1208](https://github.com/pikasTech/HWLAB/issues/1208) 平台运维 | [#1206](https://github.com/pikasTech/HWLAB/issues/1206) 客户端、[#1207](https://github.com/pikasTech/HWLAB/issues/1207) 用户管理 | -| PJ2026-0104 | 客户端 | [#1206](https://github.com/pikasTech/HWLAB/issues/1206) | Web、CLI、HTTP API、SDK/IDE 插件、webhook、公开文档、兼容性、用户任务入口与结果获取 | [#1207](https://github.com/pikasTech/HWLAB/issues/1207) 用户管理、[#1204](https://github.com/pikasTech/HWLAB/issues/1204) Agent编排、[#1203](https://github.com/pikasTech/HWLAB/issues/1203) 硬件池、[#1205](https://github.com/pikasTech/HWLAB/issues/1205) HarnessRL、[#1208](https://github.com/pikasTech/HWLAB/issues/1208) 平台运维 | 用户入口和集成调用 | -| PJ2026-0105 | 用户管理 | [#1207](https://github.com/pikasTech/HWLAB/issues/1207) | 用户、注册登录、权限、API key、credit、usage、billing、admin、租户隔离 | [#1206](https://github.com/pikasTech/HWLAB/issues/1206) 客户端、[#1204](https://github.com/pikasTech/HWLAB/issues/1204) Agent编排、[#1205](https://github.com/pikasTech/HWLAB/issues/1205) HarnessRL、[#1208](https://github.com/pikasTech/HWLAB/issues/1208) 平台运维 | [#1206](https://github.com/pikasTech/HWLAB/issues/1206) 客户端、[#1204](https://github.com/pikasTech/HWLAB/issues/1204) Agent编排、[#1203](https://github.com/pikasTech/HWLAB/issues/1203) 硬件池、[#1205](https://github.com/pikasTech/HWLAB/issues/1205) HarnessRL | -| PJ2026-0106 | 平台运维 | [#1208](https://github.com/pikasTech/HWLAB/issues/1208) | CI/CD、git mirror、YAML-first、Secret 下发、rollout、observability、GC、平台发布 | 全部 L1 的发布/配置/观测需求 | [#1203](https://github.com/pikasTech/HWLAB/issues/1203) 硬件池、[#1204](https://github.com/pikasTech/HWLAB/issues/1204) Agent编排、[#1205](https://github.com/pikasTech/HWLAB/issues/1205) HarnessRL、[#1206](https://github.com/pikasTech/HWLAB/issues/1206) 客户端、[#1207](https://github.com/pikasTech/HWLAB/issues/1207) 用户管理 | +| PJ2026-0101 | 硬件池 | [PJ2026-0101 硬件池](PJ2026-0101-hardware-pool.md) | 板卡、探针、HWPOD node、设备注册、资源占用、设备健康、可用性 | [平台运维](PJ2026-0106-platform-ops.md) | [Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[客户端](PJ2026-0104-client.md) | +| PJ2026-0102 | Agent编排 | [PJ2026-0102 Agent编排](PJ2026-0102-agent-orchestration.md) | Code Agent、AgentRun、workspace、session、provider profile、任务生命周期、任务恢复 | [硬件池](PJ2026-0101-hardware-pool.md)、[平台运维](PJ2026-0106-platform-ops.md)、[用户管理](PJ2026-0105-user-management.md) | [HarnessRL](PJ2026-0103-harness-rl.md)、[客户端](PJ2026-0104-client.md) | +| PJ2026-0103 | HarnessRL | [PJ2026-0103 HarnessRL](PJ2026-0103-harness-rl.md) | harness、CaseRun、ioProbe、evidence、评估、回放、训练反馈、RL 闭环 | [硬件池](PJ2026-0101-hardware-pool.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[平台运维](PJ2026-0106-platform-ops.md) | [客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md) | +| PJ2026-0104 | 客户端 | [PJ2026-0104 客户端](PJ2026-0104-client.md) | Web、CLI、HTTP API、SDK/IDE 插件、webhook、公开文档、兼容性、用户任务入口与结果获取 | [用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[平台运维](PJ2026-0106-platform-ops.md) | 用户入口和集成调用 | +| PJ2026-0105 | 用户管理 | [PJ2026-0105 用户管理](PJ2026-0105-user-management.md) | 用户、注册登录、权限、API key、credit、usage、billing、admin、租户隔离 | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[平台运维](PJ2026-0106-platform-ops.md) | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md) | +| PJ2026-0106 | 平台运维 | [PJ2026-0106 平台运维](PJ2026-0106-platform-ops.md) | CI/CD、git mirror、YAML-first、Secret 下发、rollout、observability、GC、平台发布 | 全部 L1 的发布/配置/观测需求 | [硬件池](PJ2026-0101-hardware-pool.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md) | ## 6. 全局原子需求 -| ID | 需求 | 类型 | 主责 L1 | 验证方法 | -| --- | --- | --- | --- | --- | -| HWLAB-L0-REQ-001 | HWLAB 应提供真实硬件资源池，使任务能发现、分配、占用、释放并验证真实设备、probe、HWPOD node 和健康状态。 | 功能 | [#1203](https://github.com/pikasTech/HWLAB/issues/1203) 硬件池 | 测试、演示 | -| HWLAB-L0-REQ-002 | HWLAB 应提供 Agent 执行编排，使用户任务能进入受控 workspace/session/provider/runtime，并能跟踪、恢复、取消和归档结果。 | 功能 | [#1204](https://github.com/pikasTech/HWLAB/issues/1204) Agent编排 | 测试、演示 | -| HWLAB-L0-REQ-003 | HWLAB 应提供 Harness/RL 验收闭环，使真实硬件任务产出可审计 evidence、aggregate、评估、回放和训练反馈。 | 功能 | [#1205](https://github.com/pikasTech/HWLAB/issues/1205) HarnessRL | 测试、检查 | -| HWLAB-L0-REQ-004 | HWLAB 应提供统一客户端入口，使 Web、CLI、API、SDK/IDE plugin 和 Webhook 围绕同一任务模型、权限模型和结果模型协同演进。 | 功能 | [#1206](https://github.com/pikasTech/HWLAB/issues/1206) 客户端 | 测试、演示 | -| HWLAB-L0-REQ-005 | HWLAB 应提供多用户与运营管理，使身份、权限、API key、credit、usage、billing、admin 和租户隔离具有统一真相。 | 功能 | [#1207](https://github.com/pikasTech/HWLAB/issues/1207) 用户管理 | 测试、检查 | -| HWLAB-L0-REQ-006 | HWLAB 应提供平台交付与运维能力，使代码、配置、密钥、发布、入口、观测和清理通过受控入口维护。 | 支撑 | [#1208](https://github.com/pikasTech/HWLAB/issues/1208) 平台运维 | 检查、演示 | -| HWLAB-L0-REQ-007 | HWLAB 的用户可见能力关闭前必须经过真实入口验收；源码检查、PR 合并或构建通过不能单独作为关闭依据。 | 约束 | 全部 L1 | 检查 | -| HWLAB-L0-REQ-008 | HWLAB 的下级工作必须且只能有一个主责 L1；跨方向支撑通过关联方向和回写表达，不重复建树。 | 约束 | 全部 L1 | 检查 | -| HWLAB-L0-REQ-009 | HWLAB 的稳定需求、验证标准和长期结论应沉淀到 `project-management/PJ2026-01` 的对应规格文件；阶段报告和执行流水不得替代规格。 | 约束 | 全部 L1 | 检查 | +### 6.1 HWLAB-L0-REQ-001 硬件资源池 -## 7. 全局验证矩阵 +| 字段 | 内容 | +| --- | --- | +| ID | HWLAB-L0-REQ-001 | +| 需求 | HWLAB 应提供真实硬件资源池，使任务能发现、分配、占用、释放并验证真实设备、probe、HWPOD node 和健康状态。 | +| 类型 | 功能 | +| 主责模块 | [硬件池](PJ2026-0101-hardware-pool.md) | +| 职责划分 | 硬件池负责设备身份、能力声明、占用释放、健康和原始硬件事实；平台运维提供运行与发布支撑；Agent编排、HarnessRL 和客户端消费硬件池输出。 | +| 验证方法 | 测试、演示 | +| 验证入口 | HWPOD 工具、HWPOD 服务、AI 网关、CaseRun | +| 必需证据 | hwpod-id、spec、node health、probe、lease、raw hardware evidence | +| 接受标准 | 真实设备可被发现、绑定、执行、释放和审计。 | -| 需求 ID | 方法 | 原入口 | 必需证据 | 接受标准 | -| --- | --- | --- | --- | --- | -| HWLAB-L0-REQ-001 | 测试/演示 | HWPOD 工具、HWPOD 服务、AI 网关、CaseRun | hwpod-id、spec、node health、probe、lease、raw hardware evidence | 真实设备可被发现、绑定、执行、释放和审计。 | -| HWLAB-L0-REQ-002 | 测试/演示 | Web/CLI/API 提交 Agent 任务、AgentRun trace/result | runId、sessionId、workspace、provider profile、trace、artifact/result pointer | 任务生命周期可跟踪，异常可恢复或明确失败。 | -| HWLAB-L0-REQ-003 | 测试/检查 | CaseRun/Harness/ioProbe/replay | caseId、runId、traceId、aggregate、ioProbe samples/stats、evaluation/replay 输出 | evidence 可审计、可复验、可用于训练反馈。 | -| HWLAB-L0-REQ-004 | 测试/演示 | Cloud Web、hwlab-cli、HTTP API、SDK/Webhook sample | Web smoke、CLI smoke、API response、SDK/Webhook 示例 | 多客户端行为和错误语义一致。 | -| HWLAB-L0-REQ-005 | 测试/检查 | user-billing / auth / API key / usage / admin API | session、API key 摘要、preflight、usage record、credit ledger、admin 操作记录 | 用户和运营真相统一且可审计。 | -| HWLAB-L0-REQ-006 | 检查/演示 | CI/CD、git mirror、YAML render、Secret sync、rollout、observability、GC | PipelineRun、source commit、render、fingerprint、public health、logs/trace、GC summary | 平台发布和运行状态可控、可见、可恢复。 | -| HWLAB-L0-REQ-007 | 检查 | L1/L2/L3/L4 收口评论 | 原入口命令、lane/node、trace/session/job/run/URL、结果摘要 | 关闭证据来自真实入口。 | -| HWLAB-L0-REQ-008 | 检查 | issue 正文和回写评论 | 主责方向、关联方向、回写对象 | 每个非平凡工作只有一个主责 L1。 | -| HWLAB-L0-REQ-009 | 检查 | 项目管理规格文件、历史 issue、阶段报告链接 | 长期规格链接、报告链接、issue 引用 | 稳定需求不只存在于评论或日报中。 | +硬件资源池是 HWLAB 的物理事实源。该能力必须把板卡、probe、HWPOD node 和设备健康状态整理为稳定、可引用、可审计的资源模型，并确保上层任务拿到的是可执行的真实硬件，而不是临时脚本输出或不可复验的运行副本。 -## 8. 追踪关系 +### 6.2 HWLAB-L0-REQ-002 Agent 执行编排 -| L0 需求 | 主责 L1 | 关联 L1 | 规格 issue | -| --- | --- | --- | --- | -| HWLAB-L0-REQ-001 | PJ2026-0101 硬件池 | Agent编排、HarnessRL、客户端、平台运维 | [#1203](https://github.com/pikasTech/HWLAB/issues/1203) | -| HWLAB-L0-REQ-002 | PJ2026-0102 Agent编排 | 硬件池、HarnessRL、客户端、用户管理、平台运维 | [#1204](https://github.com/pikasTech/HWLAB/issues/1204) | -| HWLAB-L0-REQ-003 | PJ2026-0103 HarnessRL | 硬件池、Agent编排、客户端、用户管理、平台运维 | [#1205](https://github.com/pikasTech/HWLAB/issues/1205) | -| HWLAB-L0-REQ-004 | PJ2026-0104 客户端 | 用户管理、Agent编排、硬件池、HarnessRL、平台运维 | [#1206](https://github.com/pikasTech/HWLAB/issues/1206) | -| HWLAB-L0-REQ-005 | PJ2026-0105 用户管理 | 客户端、Agent编排、HarnessRL、硬件池、平台运维 | [#1207](https://github.com/pikasTech/HWLAB/issues/1207) | -| HWLAB-L0-REQ-006 | PJ2026-0106 平台运维 | 全部 L1 | [#1208](https://github.com/pikasTech/HWLAB/issues/1208) | -| HWLAB-L0-REQ-007 | 全部 L1 | [#1217](https://github.com/pikasTech/HWLAB/issues/1217) 治理索引 | [#1203](https://github.com/pikasTech/HWLAB/issues/1203) - [#1208](https://github.com/pikasTech/HWLAB/issues/1208) | -| HWLAB-L0-REQ-008 | 全部 L1 | [#1217](https://github.com/pikasTech/HWLAB/issues/1217) 治理索引 | [#1203](https://github.com/pikasTech/HWLAB/issues/1203) - [#1208](https://github.com/pikasTech/HWLAB/issues/1208) | -| HWLAB-L0-REQ-009 | 全部 L1 | 项目管理规格文件、[#1217](https://github.com/pikasTech/HWLAB/issues/1217)、[#1218](https://github.com/pikasTech/HWLAB/issues/1218)、[#644](https://github.com/pikasTech/HWLAB/issues/644)、[#645](https://github.com/pikasTech/HWLAB/issues/645) | [#1194](https://github.com/pikasTech/HWLAB/issues/1194)、[#1203](https://github.com/pikasTech/HWLAB/issues/1203) - [#1208](https://github.com/pikasTech/HWLAB/issues/1208) | +| 字段 | 内容 | +| --- | --- | +| ID | HWLAB-L0-REQ-002 | +| 需求 | HWLAB 应提供 Agent 执行编排，使用户任务能进入受控 workspace/session/provider/runtime，并能跟踪、恢复、取消和归档结果。 | +| 类型 | 功能 | +| 主责模块 | [Agent编排](PJ2026-0102-agent-orchestration.md) | +| 职责划分 | Agent编排负责任务生命周期、workspace、session、provider profile、恢复和归档；硬件池提供可执行资源；用户管理提供身份与权限；平台运维提供运行支撑。 | +| 验证方法 | 测试、演示 | +| 验证入口 | Web/CLI/API 提交 Agent 任务、AgentRun trace/result | +| 必需证据 | runId、sessionId、workspace、provider profile、trace、artifact/result pointer | +| 接受标准 | 任务生命周期可跟踪，异常可恢复或明确失败。 | -## 9. 引用和变更规则 +Agent 执行编排负责把用户意图转化为可追踪的受控执行。它必须明确任务状态、运行上下文、执行凭据、结果位置和异常收口，避免用户任务只存在于一次性进程、临时容器或无法恢复的日志片段中。 -- L1 划分变化必须更新本文档；本次整理未改变 L1 划分。 -- 编号、层级、主责、回写、偏离和交叉引用治理规则见 [#1217](https://github.com/pikasTech/HWLAB/issues/1217)。 -- 当前阶段主线、非中心边界和阶段计划见 [#1218](https://github.com/pikasTech/HWLAB/issues/1218) 与 [#644](https://github.com/pikasTech/HWLAB/issues/644)。 -- 长期导航见 [#645](https://github.com/pikasTech/HWLAB/issues/645)；[#645](https://github.com/pikasTech/HWLAB/issues/645) 不替代本规格。 -- 单次执行证据、CaseRun 日志、PR 流水和阶段报告不得堆入本规格正文，应写入对应 L1/L2/L3/L4 issue、证据索引或项目管理阶段报告。 -- 稳定规格最终应沉淀到 `project-management/PJ2026-01`；issue 保留执行状态、讨论、证据链接和交叉引用。 +### 6.3 HWLAB-L0-REQ-003 HarnessRL 验收闭环 + +| 字段 | 内容 | +| --- | --- | +| ID | HWLAB-L0-REQ-003 | +| 需求 | HWLAB 应提供 Harness/RL 验收闭环，使真实硬件任务产出可审计 evidence、aggregate、评估、回放和训练反馈。 | +| 类型 | 功能 | +| 主责模块 | [HarnessRL](PJ2026-0103-harness-rl.md) | +| 职责划分 | HarnessRL 负责 evidence、aggregate、评估、回放和训练反馈；硬件池提供原始硬件事实；Agent编排提供执行上下文；平台运维提供可观测和归档支撑。 | +| 验证方法 | 测试、检查 | +| 验证入口 | CaseRun、Harness、ioProbe、replay | +| 必需证据 | caseId、runId、traceId、aggregate、ioProbe samples/stats、evaluation/replay 输出 | +| 接受标准 | evidence 可审计、可复验、可用于训练反馈。 | + +HarnessRL 把一次硬件执行转化为可复验的验证与训练材料。它不得只记录 pass/fail，而要保留可解释的硬件输入、执行过程、采样数据、评估结论和回放入口，使失败分类和成功路径能够进入后续改进闭环。 + +### 6.4 HWLAB-L0-REQ-004 统一客户端入口 + +| 字段 | 内容 | +| --- | --- | +| ID | HWLAB-L0-REQ-004 | +| 需求 | HWLAB 应提供统一客户端入口，使 Web、CLI、API、SDK/IDE plugin 和 Webhook 围绕同一任务模型、权限模型和结果模型协同演进。 | +| 类型 | 功能 | +| 主责模块 | [客户端](PJ2026-0104-client.md) | +| 职责划分 | 客户端负责 Web、CLI、HTTP API、SDK/IDE 插件、webhook 和公开文档的一致入口；用户管理提供身份权限；Agent编排、硬件池、HarnessRL 和平台运维提供后端能力。 | +| 验证方法 | 测试、演示 | +| 验证入口 | Cloud Web、hwlab-cli、HTTP API、SDK/Webhook sample | +| 必需证据 | Web smoke、CLI smoke、API response、SDK/Webhook 示例 | +| 接受标准 | 多客户端行为和错误语义一致。 | + +统一客户端入口要求不同用户界面共享同一任务、权限、错误和结果语义。Web、CLI、API 和 SDK 可以有不同交互形态，但不能各自定义一套状态机、错误口径或结果读取路径。 + +### 6.5 HWLAB-L0-REQ-005 用户与运营管理 + +| 字段 | 内容 | +| --- | --- | +| ID | HWLAB-L0-REQ-005 | +| 需求 | HWLAB 应提供多用户与运营管理，使身份、权限、API key、credit、usage、billing、admin 和租户隔离具有统一真相。 | +| 类型 | 功能 | +| 主责模块 | [用户管理](PJ2026-0105-user-management.md) | +| 职责划分 | 用户管理负责身份、权限、API key、credit、usage、billing、admin 和租户隔离；客户端负责呈现入口；Agent编排、硬件池和 HarnessRL 消费用户与额度约束。 | +| 验证方法 | 测试、检查 | +| 验证入口 | user-billing、auth、API key、usage、admin API | +| 必需证据 | session、API key 摘要、preflight、usage record、credit ledger、admin 操作记录 | +| 接受标准 | 用户和运营真相统一且可审计。 | + +用户与运营管理定义平台多用户运行的业务事实。它必须保证用户身份、权限、额度、计量、账务和管理操作可以被统一查询和审计，避免同一用户或同一资源消费在不同入口出现不同真相。 + +### 6.6 HWLAB-L0-REQ-006 平台交付与运维 + +| 字段 | 内容 | +| --- | --- | +| ID | HWLAB-L0-REQ-006 | +| 需求 | HWLAB 应提供平台交付与运维能力，使代码、配置、密钥、发布、入口、观测和清理通过受控入口维护。 | +| 类型 | 支撑 | +| 主责模块 | [平台运维](PJ2026-0106-platform-ops.md) | +| 职责划分 | 平台运维负责 CI/CD、git mirror、YAML-first、Secret 下发、rollout、observability、GC 和平台发布；其他模块提供发布、配置和观测需求。 | +| 验证方法 | 检查、演示 | +| 验证入口 | CI/CD、git mirror、YAML render、Secret sync、rollout、observability、GC | +| 必需证据 | PipelineRun、source commit、render、fingerprint、public health、logs/trace、GC summary | +| 接受标准 | 平台发布和运行状态可控、可见、可恢复。 | + +平台交付与运维是所有内部模块持续运行的基础能力。它必须让源码、配置、密钥、部署、公开入口、运行观测和资源清理都有受控入口和可追踪证据，不能依赖手工热修、运行面反推或不可复现的命令序列。 + +### 6.7 HWLAB-L0-REQ-007 用户可见能力关闭验收 + +| 字段 | 内容 | +| --- | --- | +| ID | HWLAB-L0-REQ-007 | +| 需求 | HWLAB 的用户可见能力关闭前必须经过真实入口验收；源码检查、PR 合并或构建通过不能单独作为关闭依据。 | +| 类型 | 约束 | +| 主责模块 | 全部内部模块 | +| 职责划分 | 定义完成标准的主责模块负责原入口验收；关联模块提供必要上下游证据；执行 issue 负责记录命令、目标 lane/node 和结果摘要。 | +| 验证方法 | 检查 | +| 验证入口 | L1/L2/L3/L4 收口评论 | +| 必需证据 | 原入口命令、lane/node、trace/session/job/run/URL、结果摘要 | +| 接受标准 | 关闭证据来自真实入口。 | + +用户可见能力必须以用户真实入口或原始验收入口为关闭依据。代码层证据可以作为辅助材料，但不能替代 Web、CLI、API、CaseRun、AgentRun 或运行面入口的实际结果。 + +### 6.8 HWLAB-L0-REQ-008 单一主责 L1 + +| 字段 | 内容 | +| --- | --- | +| ID | HWLAB-L0-REQ-008 | +| 需求 | HWLAB 的下级工作必须且只能有一个主责 L1；跨方向支撑通过关联方向和回写表达，不重复建树。 | +| 类型 | 约束 | +| 主责模块 | 全部内部模块 | +| 职责划分 | 下级工作由定义完成标准的模块承担主责；其他模块只作为关联方向、上游依赖、下游支撑或回写对象出现。 | +| 验证方法 | 检查 | +| 验证入口 | issue 正文和回写评论 | +| 必需证据 | 主责方向、关联方向、回写对象 | +| 接受标准 | 每个非平凡工作只有一个主责 L1。 | + +单一主责规则用于防止同一工作在多个方向重复建树。跨模块协作通过依赖、支撑和回写表达，但验收标准和关闭责任只能落到一个主责模块。 + +### 6.9 HWLAB-L0-REQ-009 长期规格沉淀 + +| 字段 | 内容 | +| --- | --- | +| ID | HWLAB-L0-REQ-009 | +| 需求 | HWLAB 的稳定需求、验证标准和长期结论应沉淀到 `project-management/PJ2026-01` 的对应规格文件；阶段报告和执行流水不得替代规格。 | +| 类型 | 约束 | +| 主责模块 | 全部内部模块 | +| 职责划分 | L0 负责总使命、范围和全局约束；L1 负责对应模块的稳定需求和验收边界；L2/L3/L4 issue 保留执行状态、讨论、证据链接和关闭回写。 | +| 验证方法 | 检查 | +| 验证入口 | 项目管理规格文件、历史 issue、阶段报告链接 | +| 必需证据 | 长期规格链接、报告链接、issue 引用 | +| 接受标准 | 稳定需求不只存在于评论或日报中。 | + +长期规格沉淀要求把稳定要求、验收标准和可复用结论写回项目管理规格文件。阶段报告只描述阶段移动，GitHub issue 只承担执行控制面和证据锚点，不能成为长期规格正文的唯一来源。 diff --git a/project-management/PJ2026-01/specs/current-center.md b/project-management/PJ2026-01/specs/current-center.md deleted file mode 100644 index cf2d8512..00000000 --- a/project-management/PJ2026-01/specs/current-center.md +++ /dev/null @@ -1,58 +0,0 @@ -# HWLAB 当前中心索引：阶段主线与非中心边界 - -## 修改历史 - -| 版本 | 对应 commit id | 更新日期 | 变更说明 | -| --- | --- | --- | --- | -| v0.3 | b5d8cee438a3bd66ca440a25bf5a16d9081d9efa | 2026-06-14 | 将 issue/PR 引用显示改为短号 Markdown 链接，链接目标保留完整 URL。 | -| v0.2 | b0cbe9b721b50e9fff4d350ee50ed2af03cf0405 | 2026-06-14 | 将 issue/PR 引用改为完整 GitHub URL，避免 Markdown 渲染时裸 # 编号失效。 | -| v0.1 | 37de91c653c055bf19ac271bdb687b54072639fa | 2026-06-14 | 从 [#1218](https://github.com/pikasTech/HWLAB/issues/1218) 迁移到 UniDesk 项目管理目录。 | - -## 迁移来源 - -| 字段 | 内容 | -| --- | --- | -| 原 issue | [#1218](https://github.com/pikasTech/HWLAB/issues/1218) | -| 原标题 | HWLAB 当前中心索引：阶段主线与非中心边界 | -| 原 URL | [#1218](https://github.com/pikasTech/HWLAB/issues/1218) | -| 原状态 | open | -| 原更新时间 | 2026-06-14T12:52:18Z | -| 原 body SHA | 1818977dd433ec0ae8390773aed02967f61d1bb90ab30810af2c1337fc3ce5a8 | - -## 正文 - -上级总项目: [#1194](https://github.com/pikasTech/HWLAB/issues/1194) -关联阶段规格: [#644](https://github.com/pikasTech/HWLAB/issues/644) -关联面板: [#645](https://github.com/pikasTech/HWLAB/issues/645) -性质: 阶段中心索引，不是 L1 方向，不是 L2 课题，不重新定义 L1 划分。 -迁出来源: [#1194](https://github.com/pikasTech/HWLAB/issues/1194) 旧版“当前中心”章节 -迁出时间: 2026-06-14（北京时间） - -## 使用规则 - -- 本文档 保存阶段性主线、非中心边界和计划口径。 -- L0 规格只引用本文档，不在规格正文中展开阶段计划。 -- 阶段中心变化不等于 L1 划分变化；如确需改变 L1 方向树，必须先回到 [#1194](https://github.com/pikasTech/HWLAB/issues/1194) 按规格变更处理。 -- 阶段报告和当天进展不得写入 [#1194](https://github.com/pikasTech/HWLAB/issues/1194) 正文，应写到本文档 评论、[#644](https://github.com/pikasTech/HWLAB/issues/644) 或阶段报告中。 - -## 当前中心 - -- 当前主线一：硬件池优先，先保证真实板卡、探针、HWPOD node、设备注册、占用、健康和可用性可被下游稳定引用。 -- 当前主线二：Agent编排连接用户任务、workspace、session、provider profile、任务恢复和硬件池资源。 -- 当前主线三：HarnessRL 在真实硬件和 Agent 编排之上形成 CaseRun、ioProbe、evidence、评估、回放、训练反馈闭环。 -- 当前主线四：客户端和用户管理把平台能力对外开放为 Web/CLI/API/SDK、身份、权限、额度、计量和 admin 能力。 -- 当前支撑主线：平台运维通过 CI/CD、git mirror、YAML-first、Secret、rollout、observability 和 GC 保证各方向可持续交付。 - -## 当前非中心 - -- 无硬件池、Agent编排、HarnessRL、客户端、用户管理或平台运维归属的孤立工具美化。 -- 不解除明确 blocker 的旧门禁修补。 -- 无原入口验收的观测增强。 -- 只统计 issue/PR 数量、但不能说明对 L1 验收移动的阶段报告。 - -## 回写规则 - -- 阶段中心变化时更新本文档，并在 [#1194](https://github.com/pikasTech/HWLAB/issues/1194) 保持引用。 -- 如果阶段中心变化影响 L0 使命、范围、L1 方向树或全局需求，必须同步更新 [#1194](https://github.com/pikasTech/HWLAB/issues/1194)。 -- 具体执行进展只写入对应 L1/L2/L3/L4 issue 或本文档 评论，不写入 L0 规格正文。 - diff --git a/project-management/templates/iso-iec-ieee-29148-requirements-spec-template.md b/project-management/templates/iso-iec-ieee-29148-requirements-spec-template.md new file mode 100644 index 00000000..a6a70cb1 --- /dev/null +++ b/project-management/templates/iso-iec-ieee-29148-requirements-spec-template.md @@ -0,0 +1,124 @@ +# ISO/IEC/IEEE 29148 需求规格模板 + +## 来源和定位 + +本模板用于 UniDesk `project-management/` 下的 L0、L1、L2 需求规格文档。模板基线采用 ISO/IEC/IEEE 29148:2018 的需求工程分层思路，并结合 HWLAB 项目管理约束做轻量裁剪。 + +参考来源： + +- ISO/IEC/IEEE 29148:2018： +- IEEE 830-1998 已被替代的官方说明： +- ReqView 对 29148 模板族的说明： +- ReqView 的 29148 软件需求规格示例： + +使用原则： + +- 业务需求规格用于使命和商业目标，利益相关方需求规格用于用户和运营方诉求，系统需求规格用于跨硬件、软件、人员和流程的系统级要求，软件需求规格用于软件能力要求，运行概念文档用于描述主要运行场景。 +- HWLAB 的 L0、L1、L2 规格共用同一骨架，但粒度不同：L0 写使命、边界和全局需求；L1 写内部模块职责和验收边界；L2 写具体课题的交付物、阻塞项和验证计划。 +- 规格正文只写稳定需求、边界、职责、验证和必要追踪关系；阶段报告、执行流水、长日志、拉取请求过程和一次性证据放到 GitHub 议题、阶段报告或证据索引中。 +- 每条原子需求使用独立小节。信息表中必须包含主责、职责划分、验证入口、必需证据和接受标准；正文说明需求意图和边界。 + +## 文档骨架 + +```markdown +# <编号> <短名> 需求规格 + +## 修改历史 + +| 版本 | 对应提交标识 | 更新日期 | 变更说明 | +| --- | --- | --- | --- | +| v0.1 | 待提交 | <年-月-日> | 创建需求规格。 | + +## 迁移来源 + +| 字段 | 内容 | +| --- | --- | +| 原 GitHub 议题 | [#<编号>](https://github.com/<组织>/<仓库>/issues/<编号>) | +| 原标题 | <标题> | +| 原状态 | <打开或关闭> | +| 原更新时间 | <时间戳> | +| 原正文摘要标识 | <摘要标识> | + +## 正文 + +## <编号> <短名> 需求规格 + +## 1. 文档控制 + +| 字段 | 内容 | +| --- | --- | +| 编号 | <项目编号> | +| 短名 | <短名> | +| 层级 | L0、L1 或 L2 | +| 状态 | 有效、草案或归档 | +| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](<相对路径>) | +| 上级规格 | <相对路径链接；L0 可留空> | +| 阶段规格 | <相对路径链接；不适用时留空> | +| 规格治理索引 | <相对路径链接> | +| 规格来源 | <项目管理路径、历史材料或 GitHub 议题> | + +本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留稳定使命、范围、运行概念、系统边界、内部模块或课题分工、原子需求和验证口径。编号、层级职责、回写、偏离判定和交叉引用治理由规格治理文档承载。 + +## 2. 目的和范围 + +### 2.1 目的 + +<用一段话说明该规格服务的项目目标、用户目标或系统目标。> + +### 2.2 范围内 + +- <范围项> + +### 2.3 范围外 + +- <非目标或转交范围> + +## 3. 运行概念 + +1. <关键场景或运行步骤> + +## 4. 系统边界和接口 + +| 类别 | 内容 | +| --- | --- | +| 用户入口 | <网页端、命令行、应用接口、开发工具包等> | +| 上游系统 | <依赖来源> | +| 下游系统 | <输出消费方> | +| 验收入口 | <测试、演示、检查或分析入口> | +| 长期文档 | <规格、计划、测试规格、阶段报告> | +| 执行控制面 | <议题、拉取请求、跟踪记录、会话、任务、运行记录或案例登记> | + +## 5. 内部分工与规格索引 + +| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 | +| --- | --- | --- | --- | --- | --- | +| <项目编号> | <短名> | [<规格名>](<相对路径>) | <主责> | <依赖> | <支撑对象> | + +## 6. 原子需求 + +### 6.1 <需求编号> <需求短名> + +| 字段 | 内容 | +| --- | --- | +| 编号 | <需求编号> | +| 需求 | <系统或模块应当具备的能力或约束> | +| 类型 | 功能、约束、支撑、接口或质量 | +| 主责模块 | <相对路径链接或主责编号> | +| 职责划分 | <主责负责什么；关联模块负责什么；哪些内容不属于本需求> | +| 验证方法 | 测试、演示、检查或分析 | +| 验证入口 | <命令行、网页端、应用接口、案例运行、跟踪记录等原入口> | +| 必需证据 | <运行编号、跟踪编号、链接、日志摘要、报告链接等> | +| 接受标准 | <可判定的完成标准> | + +<正文说明该原子需求的意图、范围、边界和验收语义。正文不放执行流水和长证据。> + +## 7. 假设和风险 + +- <只写会影响需求或验证的稳定假设和风险。> + +## 8. 变更控制 + +- 稳定需求变化必须更新本文档。 +- 阶段计划和执行流水不得替代本文档。 +- 下级工作完成后按规格治理文档回写。 +```