chore(backup): 保存新版预审开发前的代码与文档基线

2026-09-28 16:34:10 +08:00
parent b10093f9d8
commit 4d5a420671
37 changed files with 3890 additions and 10 deletions
@@ -0,0 +1,87 @@
+# 阶段 ① 需求与规格（Requirement & Spec）
+
+> **定义**：把用户意图变成一份"实现者（人或 agent）无需猜"的规格文档。规格完备的标志是：实现者不发明任何决策就能把改动做出来。
+> **输入**：需求描述 / issue / 用户反馈 / 变更请求。
+> **输出**：规格文档（按下方 7 段结构 + BR/E/AC 编号）。
+> **进入下一阶段（② 架构设计）**：六道完备性门全部通过。
+
+---
+
+## 1. 要求（Requirements）
+
+### 1.1 进入条件
+- 需求来源明确（谁提的、要解决什么问题、对哪些角色生效）。
+- 明确本轮范围 vs 明确不在本轮范围（out-of-scope 与 in-scope 同等重要）。
+- 单一交付面还是多交付面已确认（web / Electron 主进程 / 硬件网关 / 设置面板……每个交付面都会让规格多一段）。
+
+### 1.2 完成条件（DoD）
+- [ ] 七段结构齐全（多交付面则第 3 段重复），每个领域术语都进术语表
+- [ ] 每条业务规则 `BR-xx` 可测试（能说清"什么输入让它过、什么输入让它挂"）
+- [ ] 每条规则隐含的失败路径都有 `E-xx`，异常"用户可见消息 ↔ 后端错误码"绑定
+- [ ] 每条 `BR-xx` / `E-xx` 至少被一条 `AC-xx` 引用；验收含正常/异常/边界三类用例
+- [ ] 无阻塞当前迭代的未决问题（或已把阻塞规则移出范围）
+- [ ] 决策记录（Decision Record）已写明已定决策与被否掉的替代方案
+
+---
+
+## 2. 规则（Rules）
+
+| 编号 | 规则 |
+|---|---|
+| R-1.1 | 行为必须有 id：业务规则 `BR-01`…，异常场景 `E-01`…，验收标准 `AC-01`…。散文式描述不能进入规格。 |
+| R-1.2 | id 只追加不重排；规则废弃时标记 withdrawn 并保留编号（提交、测试、评审已引用旧 id）。编号按规格独立，不全局递增。 |
+| R-1.3 | 每条 `BR-*` 只对应**一个**实现点。一条规则要碰三条无关代码路径 = 它其实是三条规则。 |
+| R-1.4 | 每条 `E-*` 必须绑定"各受影响面展示给用户的消息"与"产生它的后端错误码"，前后端不能静默漂移。 |
+| R-1.5 | 每条 `AC-*` 用 `Given / When / Then` 三元组，且引用它覆盖的 `BR-*`/`E-*` id。无验收引用的规则/异常 = 未验证，阻塞进入实现。 |
+| R-1.6 | 未决定的事项显式标记（`needs-decision` / open question，带 owner 与期限），禁止用"貌似合理的编造值"填空。 |
+| R-1.7 | 截图/线框图只表达布局，不替代规则：不得用截图当 spec，除非它同时写清状态转换与权限。 |
+| R-1.8 | 反模式禁止：只写 happy path（§5/§6 才是实现风险所在）、把字段类型当业务规则（`BR-*` 描述系统**要决定什么**，不是**存什么**）、整段照抄他项目（可复用段清单，内容必须基于本目标事实重写）。 |
+
+---
+
+## 3. 输出规范
+
+### 3.1 规格文档结构（7 段；每多一个交付面，第 3 段重复一次 → 8/9 段）
+
+```text
+1. Requirement Overview      业务背景、in-scope / out-of-scope、受影响角色、术语表
+2. Data Model & Interface    新增/变更的表（列类型、可空性）、服务契约、公开端点（请求/响应形状）、枚举、消息/事件载荷
+   Contract
+3. Surface Specification     每个交付面：页面骨架、组件粒度、每个有状态视图的状态机、动作列表（含守卫权限）
+4. Business Rules            编号 BR-01…，每条一条可测试语句
+5. Exception Scenarios       编号 E-01…，触发条件 + 各面用户可见消息 + 后端错误码
+6. Acceptance Criteria       编号 AC-01…，按角色分组，Given/When/Then，覆盖正常/异常/边界
+7. Open Questions &          未决项（owner + needed-by）+ 已定决策与被否方案
+   Decision Record
+```
+
+> 参考模板：`vendor/better-harness/references/bootstrap/examples/frontend-web-spec.md`（前端表面）、`backend-service-spec.md`（多交付面）、`mobile-app-spec.md`（离线/权限/版本）。**复用结构，不复用表名/端点/阈值/角色名。**
+
+### 3.2 六道完备性门（任一不过，禁止进入实现）
+
+| 门 | 判定 |
+|---|---|
+| **Term gate 术语门** | 规则中每个领域术语都在术语表里 |
+| **Contract gate 契约门** | 表面展示/提交的每个字段都在 §2 里有类型，每个枚举值都列出 |
+| **Rule gate 规则门** | 每条 `BR-*` 可测试（评审者能说出"输入 X 通过、输入 Y 失败"） |
+| **Exception gate 异常门** | 每条规则隐含的失败路径都有 `E-*`；静默失败是规格缺陷，不是实现细节 |
+| **Coverage gate 覆盖门** | 每条 `BR-*`/`E-*` 至少被一条 `AC-*` 引用；验收含至少一个边界用例 |
+| **Decision gate 决策门** | 本轮范围内没有未决问题阻塞规则；要么移出范围，要么解决 |
+
+### 3.3 交付物清单
+- 规格文档（本地草稿放 `docs/plans/`，**不入库**，见 `.gitignore`；需入库的规格随 PR 放 `docs/` 对应目录，命名 `<日期>-<主题>-spec.md`）
+- （可选）给 UI 需求的面：指向 [04-ui-spec.md](04-ui-spec.md) 的表面规格拆分
+
+---
+
+## 4. 轻量路径（小改动）
+
+- 一行修复 / 文案 / 纯内部重构：规格可缩为 PR 描述中的"范围 + BR/AC 各 1-3 条"，但 id 与可追溯要求不变。
+- 无法写清验收标准的改动 = 规格未完成，不得进实现。
+
+---
+
+## 5. 相关文档
+
+- 阶段 ② [02-architecture.md](02-architecture.md)、阶段 ④ [04-ui-spec.md](04-ui-spec.md)
+- 规格→实现→验证的流程闭环定义见 [README.md](README.md) 全景
@@ -0,0 +1,88 @@
+# 阶段 ② 架构设计（Architecture Design）
+
+> **定义**：确定系统/改动的分层、模块边界、数据流、依赖方向与关键技术决策，让实现者知道"改哪里、往哪加、不能碰什么"。架构文档回答系统**为什么这样长**；详细设计（阶段 ③）回答**每个零件怎么做**。
+> **输入**：① 的规格文档（验收标准是架构的约束）。
+> **输出**：架构文档 + ADR（决策记录）+ 架构图。
+> **进入下一阶段（③ 详细设计）**：模块边界与关键决策已定案，无未决阻塞项。
+
+---
+
+## 1. 要求（Requirements）
+
+### 1.1 进入条件
+- 规格已过六道完备性门（见 [01-requirement.md](01-requirement.md) §3.2）。
+- 涉及跨模块/跨进程/硬件/网关/持久化的改动，必须走完整架构设计；纯单文件小改可走轻量路径。
+
+### 1.2 完成条件（DoD）
+- [ ] 分层与依赖方向明确：数据只能往哪个方向流、禁止哪些反向依赖
+- [ ] 每个模块有唯一 owner 与清晰职责；没有"第二份 owner"（同一概念不复制两处实现）
+- [ ] 关键决策以 ADR 形式记录（结论 + 被否方案 + 理由），决策号稳定（如 D1/D2）
+- [ ] 数据流/主链路（含失败路径）有图或文字描述，与现有架构基线（`docs/architecture/architecture-overview.md` 分层图）能对上
+- [ ] 风险与副作用边界已标注：哪些是高危操作（生产数据、硬件写、外发请求）、默认拒绝还是需审批
+- [ ] 架构不变量可被机器验证的部分列出（对应 lint/architecture test/契约测试）
+
+---
+
+## 2. 规则（Rules）
+
+| 编号 | 规则 |
+|---|---|
+| R-2.1 | **依赖单向**：renderer → preload → IPC handler → domain service → state / Pi runtime；service 不依赖 UI 层与宿主；禁止跨层绕行。本仓现状：`src/main/`（Electron 宿主：index/preload/app-menu/macos/update/host）· `packages/agent-sdk/`（服务主体，零 electron 导入）· `packages/web-ui/`（renderer SPA）· `packages/api/`（dk-api 契约）。 |
+| R-2.2 | **唯一 owner**：跨进程/跨模块的类型只在共享层定义一次，其余侧只 `import type`；禁止本地镜像同一契约。 |
+| R-2.3 | **架构不变量写入文档且可验证**：能用测试/静态检查强制的（模块边界、依赖方向、迁移追加、白名单），不许只写文档；验证不了的规则不写进"不可违背"清单。 |
+| R-2.4 | **决策要留痕**：架构层面的每个取舍写成 ADR（背景/决策/被否方案/影响），不搞口头决定。被否方案是决策记录的一部分。 |
+| R-2.5 | **分层不做多余抽象**：无第二调用方的接口不抽象；不为想象中的灵活性提前配置化（Karpathy 准则：最小代码解决当前问题）。 |
+| R-2.6 | **边界即安全**：跨进程 IPC、硬件写、外发请求、文件写入都有明确边界与校验点；高危路径默认拒绝或显式审批（见 [07-delivery.md](07-delivery.md) 高风险审批）。 |
+| R-2.7 | **架构图遵守作者契约**：用图时按下方 §3.2 的五类图规则（架构/工作流/时序/数据流/生命周期）绘制，只画验证过的事实，不画"可能"的关系。 |
+
+---
+
+## 3. 输出规范
+
+### 3.1 架构文档结构
+
+```text
+1. 概览（一屏）         一句话定位 + 分层图 + 本改动在哪个层
+2. 分层与模块边界       模块清单：职责 / owner / 依赖方向 / 禁止的反向依赖
+3. 数据模型与持久化     表/文件/状态的归属与迁移策略（追加式迁移，禁改历史）
+4. 关键流程             主链路 + 失败/恢复路径（任务运行、硬件发现、网关、升级等）
+5. 接口与集成点         跨进程契约、外部依赖（硬件协议、网关、云服务）、版本约束
+6. 风险与副作用边界     高危操作清单：触发条件 / 审批点 / 审计点 / 回滚
+7. 决策记录（ADR）      D1/D2…：决策 + 被否方案 + 影响
+8. 验证方式             架构不变量对应的测试/门禁
+```
+
+> 本仓已有基线：`docs/architecture/architecture-overview.md`（分层总览）+ `docs/architecture/codemap.md`（模块地图，头部统计由 `scripts/repo-stats.mjs` 生成）。新架构文档放在 `docs/architecture/`（入库基线）或 `docs/plans/`（本地草稿，不入库，见 `.gitignore`），并保持与基线一致；基线变更要同步。
+
+### 3.2 架构图规范（五类，摘要）
+
+| 图类型 | 结构规则 |
+|---|---|
+| Architecture | 一条从左到右主干 + 短垂直分支；6–12 个主组件；只按真实归属/信任/进程边界分组；外部角色画在系统边界外 |
+| Workflow | 泳道=职责/阶段，列=推进；happy path 单调；重试/异常走主走廊外 |
+| Sequence | 参与者按会话角色排序；消息拥有纵向顺序 |
+| Dataflow | 阶段=转换/保管；行=并行流；只标注数据契约与跨边界移动 |
+| Lifecycle | 主相位列 0..4；可恢复失败必须有真实回迁转换 |
+
+> 构图约定：图以 Mermaid / 文本图为主（见 `docs/architecture/flows.md`、`docs/release-process.md` 既有图例），只画代码检查证实的事实，不画"可能"的关系，并保证 lint/渲染校验可通过。
+
+### 3.3 交付物清单
+- 架构文档（含分层/边界/数据流/风险）
+- ADR（每个决策一个记录，可内嵌架构文档或独立 `docs/adr/`）
+- 架构图（适用时）
+- 架构不变量对应的机器验证清单（测试/静态检查名）
+
+---
+
+## 4. 轻量路径（小改动）
+
+- 单模块内、无跨进程/持久化/外部的改动：架构要求并入详细设计开头一小节（边界 + owner + 依赖方向），不单独成文。
+- 改动触碰 `packages/api/src/contracts.ts`（跨进程契约）、IPC、迁移、安全边界时，**必须**走完整架构设计。
+
+---
+
+## 5. 相关文档
+
+- 输入：阶段 ① [01-requirement.md](01-requirement.md)
+- 输出到：阶段 ③ [03-detailed-design.md](03-detailed-design.md)
+- 变更矩阵（架构文档随代码同步）：[05-implementation.md](05-implementation.md) §3.3
@@ -0,0 +1,79 @@
+# 阶段 ③ 详细设计（Detailed Design）
+
+> **定义**：把架构落到可实现的粒度——每个接口的签名与契约、数据结构与迁移、视图状态机、异常处理、边界条件。详细设计完成后，实现者不需要再做任何设计决策，只需照做。
+> **输入**：① 规格 + ② 架构（模块边界、owner、契约归属）。
+> **输出**：详细设计文档（接口/数据/状态机/异常/边界）+ 可落地的契约声明（类型定义、表结构草案）。
+> **进入下一阶段（④ UI Spec / ⑤ 实现）**：接口契约与数据契约已定案，边界与异常已覆盖。
+
+---
+
+## 1. 要求（Requirements）
+
+### 1.1 进入条件
+- 架构已定案（无阻塞性未决决策）。
+- 规格的 `BR-*`/`E-*`/`AC-*` 全部可映射到具体接口/数据/状态。
+
+### 1.2 完成条件（DoD）
+- [ ] 每个公开接口（函数/方法/事件/IPC 通道/硬件协议命令）有签名、入参校验规则、返回与错误语义
+- [ ] 每个数据结构（表/文件/状态对象）有字段、类型、可空性、owner；变更走追加式迁移且有守卫
+- [ ] 每个有状态视图/流程有状态机（状态全集 + 合法转换 + 每个状态的禁用手势）
+- [ ] 规格中每条 `E-*` 都能落到具体错误码 + 处理路径（重试/降级/回滚）
+- [ ] 边界条件显式列出：空输入、上限、并发、超时、权限缺失、版本不兼容
+- [ ] 所有契约与规格 id 可双向追溯（实现点 ↔ BR/E/AC）
+
+---
+
+## 2. 规则（Rules）
+
+| 编号 | 规则 |
+|---|---|
+| R-3.1 | **契约先行且单一**：接口与数据契约在详细设计中定案，实现只落契约不发明契约；跨进程契约只放共享层一处（G-1）。 |
+| R-3.2 | **入参显式校验**：每个对外接口（IPC、命令、硬件写入、外部请求）的入参都有校验（类型/枚举/边界），禁止裸用；"无入参"是唯一例外。通用校验器不得被滥用成"非空字符串检查"。 |
+| R-3.3 | **状态机完备**：状态全集含加载/空/错误/提交中等"非 happy path"状态；每个状态定义允许的动作与禁用手势。折叠状态机（如把 Loading 与 Submitting 合并成一个布尔）会丢失关键行为，禁止。 |
+| R-3.4 | **异常必有归属**：每条失败路径有明确处理语义（重试上限、降级、回滚、幂等）与错误码；静默失败是设计缺陷。 |
+| R-3.5 | **迁移只追加**：持久化结构变更只能追加带守卫的迁移（版本号递增 + 幂等守卫），禁止修改历史迁移；迁移只跑一次。 |
+| R-3.6 | **边界显式**：空输入、数量上限、并发/竞态、超时、凭据缺失、旧版本兼容等边界条件写成条目，不得留给实现时"顺手处理"。 |
+| R-3.7 | **单实现点**：一条规则/一个行为只有一个实现点（继承规格 R-1.3）；发现需要多处实现，回到规格拆分。 |
+| R-3.8 | **详细设计可评审**：设计文档要能被实现者之外的人评审出"漏了 X 状态/缺了 Y 错误码"，否则说明粒度还不够。 |
+
+---
+
+## 3. 输出规范
+
+### 3.1 详细设计文档结构
+
+```text
+1. 范围与本设计覆盖的规格 id     BR-xx / E-xx / AC-xx 清单（双向追溯表）
+2. 接口设计                      每个接口：签名 / 入参校验规则 / 返回 / 错误语义 / owner
+3. 数据设计                      表/文件/对象：字段、类型、可空性、owner、迁移草案（只追加）
+4. 状态机与流程                  有状态视图/流程的状态机表（状态 × 转换 × 动作 × 守卫）
+5. 异常与错误码                  错误码表：码 / 触发条件 / 用户可见消息 / 处理路径（重试/降级/回滚/幂等）
+6. 边界条件清单                  空输入 / 上限 / 并发 / 超时 / 权限 / 版本兼容
+7. 测试映射                      每个 AC-xx 对应的测试点（单测/集成/E2E 层级建议）
+8. 未决项                        遗留问题（owner + needed-by），或已解决的决策记录
+```
+
+### 3.2 契约声明（可落地的部分）
+- 类型定义：跨进程契约先写在 `packages/api/src/contracts.ts`（唯一事实源），宿主与各包只 `import type`；包内契约就近在包内共享层声明。
+- 数据结构草案：DDL/迁移骨架，标注幂等守卫。
+- 状态机表：Markdown 表格即可，复杂流程可配 sequence 图（见 [02-architecture.md](02-architecture.md) §3.2）。
+
+### 3.3 交付物清单
+- 详细设计文档（本地草稿 `docs/plans/`（不入库，见 `.gitignore`），需入库随 PR 放 `docs/` 对应目录）
+- 契约草案（类型/迁移/错误码表）
+- 测试映射表（为 ⑥ 验证做准备）
+
+---
+
+## 4. 轻量路径（小改动）
+
+- 单接口小改：契约 + 边界 + 测试映射合并为设计文档中的 2-3 小节。
+- 触碰共享契约、迁移、状态机、硬件协议：必须完整走详细设计。
+
+---
+
+## 5. 相关文档
+
+- 输入：阶段 ① [01-requirement.md](01-requirement.md)、阶段 ② [02-architecture.md](02-architecture.md)
+- UI 相关设计拆到：阶段 ④ [04-ui-spec.md](04-ui-spec.md)
+- 实现时按此设计编码：阶段 ⑤ [05-implementation.md](05-implementation.md)
@@ -0,0 +1,116 @@
+# 阶段 ④ UI Spec — UI 规则定义与约束规范
+
+> **定义**：定义每个交付面的 UI 行为与视觉约束，让 UI 实现者（人或 agent）不发明任何决策：页面骨架、组件粒度、状态机、动作权限由**表面规格（Surface Specification）** 规定；颜色/字号/间距/组件形态由**设计系统契约（DESIGN.md）** 规定。
+> **输入**：① 规格 §3（Surface Specification）+ ②/③ 的接口契约（UI 消费的字段）。
+> **输出**：表面规格 + DESIGN.md（含 token）+ i18n 约束。
+> **进入下一阶段（⑤ 实现）**：状态机、动作权限、设计 token、i18n 全部定案。
+
+> 适用判定：本阶段仅当改动拥有用户可见 UI（web 界面、Electron 窗口、设置面板、硬件设备界面）时强制；纯后端/网关/CLI 改动标记 `not applicable`。
+
+---
+
+## 1. 要求（Requirements）
+
+### 1.1 进入条件
+- 规格 §3 已定义交付面清单与每个面的消费字段（字段有类型、可空性、枚举值）。
+- 项目已有或需要建立视觉事实源（`DESIGN.md` / 主题变量 / 组件库）。
+
+### 1.2 完成条件（DoD）
+- [ ] 每个交付面有：页面骨架 + 组件粒度边界 + 完整状态机 + 动作×权限表
+- [ ] 每个 UI 提交/展示的字段能在规格 §2 找到（契约门）
+- [ ] 视觉 token（颜色/字号/间距/圆角/组件）有语义化来源，不出现临时发明的 `blue500` 类裸色
+- [ ] 全部 UI 文案走 i18n（本仓：`packages/web-ui/src/i18n/messages.ts`，zh-CN/en-US 双语），无硬编码用户可见字符串
+- [ ] 可访问性约束写明：对比度（WCAG AA）、focus-visible、颜色不单独承载状态、reduced-motion
+- [ ] 异常态（加载/空/错误/禁用/提交中）有明确视觉与文案定义（对应规格 `E-*`）
+
+---
+
+## 2. 规则（Rules）
+
+### 2.1 表面规格规则（Surface Specification）
+
+| 编号 | 规则 |
+|---|---|
+| R-4.1 | **骨架先行**：每个交付面先定页面骨架（区域划分），再定组件，禁止直接进入像素级布局。 |
+| R-4.2 | **组件粒度即所有权边界**：明确"哪个组件拥有哪个状态"（如筛选条是查询条件的唯一事实源、表格不持有选择集）。组件不得越界：表格不能清空选择，只能向拥有者发请求。 |
+| R-4.3 | **状态机完整**：`Idle/Loading/Ready/Empty/Error/Submitting` 等状态全列；`Loading`（骨架屏）与 `Submitting`（保留现有内容+禁用交互）是不同状态，不得合并。 |
+| R-4.4 | **动作×权限表**：每个动作列角色与禁用条件（如"Auditor 看到页面但没有动作控件，而非禁用按钮"）。 |
+| R-4.5 | **交互约束显式**：URL 持有可分享状态、筛选变更清空选择、选择集不跨页、破坏性操作需确认且写明数量——写成条目，不留给实现。 |
+| R-4.6 | **截图不是 spec**：图片可表达布局，但必须同时有规则、状态转换、权限（R-1.7 在 UI 层同样生效）。 |
+
+### 2.2 设计系统规则（DESIGN.md / 视觉 token）
+
+| 编号 | 规则 |
+|---|---|
+| R-4.7 | **视觉事实源唯一**：有 UI 的项目维护唯一的视觉 token 事实源（本仓现状：`packages/web-ui/src/theme/tokens.css`，语义 token + CSS 变量，经 `styles.css` `@import` 消费；若将来建根级 `DESIGN.md` 则与之对齐）；禁止在组件里临时发明颜色/间距/字号。 |
+| R-4.8 | **语义 token 优先**：token 用语义角色（`primary`/`surface`/`danger`），不用调色板名（`teal-500`）；组件 token 带状态（如 `button-primary-hover`、`text-input-focused`）。 |
+| R-4.9 | **token 可导出可防漂移**：token 能导出为 CSS 变量/主题，并用 lint/diff/单测检查漂移（本仓：`tokens.css` 变量 + `styles.test.ts` 等单测守卫；`useAppearance.ts` 归一化主题 id）；"文件存在"不等于"被使用"（G-3）。 |
+| R-4.10 | **可访问性硬约束**：正文与 focus 态满足 WCAG AA 对比度；错误/成功/选中状态不得只靠颜色表达；支持 reduced-motion；表单与错误态有明确指引。 |
+| R-4.11 | **不强推框架外规范**：后端/CLI/纯数据项目标记 `not applicable`，不套用视觉契约。 |
+
+### 2.3 i18n 规则
+
+| 编号 | 规则 |
+|---|---|
+| R-4.12 | 所有用户可见文案走 key 化翻译（本仓：`packages/web-ui/src/i18n/messages.ts`，扁平 key + `t(key, params?)`，key 按命名空间组织：`common.*`/`task.*`/`settings.*`/`shell.*`/`inspector.*`/`mode.*`）；禁止硬编码中文/英文串。 |
+| R-4.13 | 多语言文案与 UI 状态同步维护；新增文案必须同时补齐既有语言包。 |
+| R-4.14 | 设备端/子窗口界面不做 i18n 决策，文案由宿主统一注入（避免每窗口维护语言状态）。 |
+
+---
+
+## 3. 输出规范
+
+### 3.1 表面规格结构（每个交付面一份）
+
+```text
+Skeleton            页面骨架：区域划分与信息层级
+Component           组件粒度：组件清单 + 各自拥有的状态 + 不允许越界的边界
+Granularity
+State Machine       状态全集 + 合法转换 + 每个状态的禁用手势（表格或图）
+Actions & Guards    动作 × 角色 × 禁用条件（含"只读角色无控件而非禁用"）
+Interaction         交互约束：URL 状态、选择集规则、确认对话框、虚拟化/固定行高、截断策略
+Constraints
+```
+
+> 模板参考：`vendor/better-harness/references/bootstrap/examples/frontend-web-spec.md` 的 §3（复用结构，内容必须基于本仓事实）。
+
+### 3.2 DESIGN.md 结构
+
+```text
+frontmatter（机器可读）      colors / typography / rounded / spacing / components
+                            （顶层组，语义角色 + 组件状态 token，支持 {colors.primary} 引用）
+Markdown（人读）            Overview / Colors / Typography / Layout / Elevation & Depth /
+                            Shapes / Components / Do's and Don'ts
+                            + 可访问性（对比度、focus-visible、color-not-alone、reduced-motion）
+                            + 每个 token 的"何时用 / 何时不用 / 防止什么 agent 错误"
+```
+
+> 完整示例：`vendor/better-harness/case-studies/project-harness/design-md-complete-example.md`（结构性回退模板，数值必须替换为本仓已核实的来源）。若项目尚无 DESIGN.md：从现有代码/主题推断并标注"推断"，未决品牌决策标记 `needs-design-decision`，禁止编造。
+
+### 3.3 交付物清单
+- 每个交付面的表面规格
+- `DESIGN.md`（若建）或其缺失项清单；本仓现状：视觉 token 事实源为 `packages/web-ui/src/theme/tokens.css`（含证据分级：Present / Structured / Token-ready / Agent-ready / Aligned / Backstopped）
+- i18n key 清单（新增/变更）
+- UI 验收映射：表面规格的每条交互约束 ↔ 规格 `AC-xx` ↔ [06-validation.md](06-validation.md) 的测试点（组件/E2E）
+
+---
+
+## 4. UI 验证约束（预置，详见阶段 ⑥）
+
+- UI 验证分驱动平面（D0 进程内渲染树 → D1 浏览器自动化协议 → D2 附加运行中浏览器 → D3 OS 输入/无障碍 → D4 物理设备），选满足声明的最便宜平面，失败再升级。
+- **驱动与观察分离**：同一模型既驱动 UI 又目测自己的截图 = 无独立裁判，不能算 pass（`Self-reported success` 反模式）。截图基线只追加不覆盖。
+- 定位器禁止跨动作缓存（元素索引/坐标每次交互前重新读取）；降级顺序：语义选择器 → 文本/aria → 原始坐标，并记录最终落到哪一级。
+
+---
+
+## 5. 轻量路径（小改动）
+
+- 单组件样式调整：更新 DESIGN.md 对应 token + 表面规格的组件小节，不重写整份规格。
+- 触碰多交付面、状态机重构、主题切换：必须完整走本阶段。
+
+---
+
+## 6. 相关文档
+
+- 输入：阶段 ① [01-requirement.md](01-requirement.md) §3、阶段 ③ [03-detailed-design.md](03-detailed-design.md)
+- 验证：阶段 ⑥ [06-validation.md](06-validation.md)（UI 驱动平面与裁判分离约束）
@@ -0,0 +1,107 @@
+# 阶段 ⑤ 实现（Implementation）
+
+> **定义**：小步、可验证、范围受控地把设计变成代码。实现期的核心不是"写得多"，而是**每一步都有验证、每个改动都可追溯到请求、不越界、不留孤儿**。
+> **输入**：① 规格 + ② 架构 + ③ 详细设计（+ ④ UI Spec）。
+> **输出**：代码 + colocated 测试 + 变更同步（文档/契约）。
+> **进入下一阶段（⑥ 验证与质量门）**：编码规则满足、自测通过、变更矩阵已同步。
+
+---
+
+## 1. 要求（Requirements）
+
+### 1.1 进入条件
+- 规格完备性门、架构/详细设计决策均已定案（小改动走轻量路径也必须有范围 + 验收标准）。
+- 涉及 UI 的改动已有 ④ 的表面规格与 token。
+
+### 1.2 完成条件（DoD）
+- [ ] 每个提交只做一件事（Conventional Commits），变更可逐行追溯到请求范围
+- [ ] 新行为有 colocated 测试（与源码同目录 `*.test.ts`，vitest；E2E 在 `e2e/`，playwright。本仓测试体系见 `docs/architecture/testing-architecture.md`）
+- [ ] 无未使用 import/变量/函数（由本次改动产生的孤儿已清理；存量死代码只提不改，G-4）
+- [ ] 变更矩阵已同步（见 §3.3）：契约、文档、i18n、迁移、架构图
+- [ ] 本阶段自测（lint/typecheck/相关单测）全绿
+
+---
+
+## 2. 规则（Rules）
+
+### 2.1 编码行为
+
+| 编号 | 规则 |
+|---|---|
+| R-5.1 | **想清楚再写**：假设显式化；多种解释并存时先摆出来，不静默选择；不确定就停，说出困惑点，问。 |
+| R-5.2 | **最小代码**：解决当前问题的代码，不做投机抽象/灵活配置/为不可能场景写错误处理；200 行能解决的不要写 500 行。 |
+| R-5.3 | **外科手术式改动**：只碰必须碰的；不顺手"改进"相邻代码/注释/格式；不重构没坏的东西；风格跟随现有代码。 |
+| R-5.4 | **规模红线**：新文件 ≤500 行；既有大文件只减不增；新增依赖必须先评估体积与必要性（依赖红线见仓库约定）。 |
+| R-5.5 | **状态持久化白名单**：新增受管写入路径须进白名单并说明；禁止绕过既有持久化/校验路径自行写文件。 |
+| R-5.6 | **小步提交**：一个提交一个意图；变更混杂时先拆分再提交（见 `skills/builtin/dk-commit` 的提交规范）。 |
+
+### 2.2 安全与副作用（实现期强制）
+
+| 编号 | 规则 |
+|---|---|
+| R-5.7 | 所有副作用入口（文件写、命令执行、外发请求、硬件写、IPC）走统一受控路径，禁止平行执行路径。 |
+| R-5.8 | 项目目录写入/命令必须有归属校验 + 审计；凭据/配置保护区一律拒绝。 |
+| R-5.9 | 日志/输出禁止出现凭据任何片段（脱敏）；禁止 `nodeIntegration: true`、禁止绕过 preload/安全边界暴露主机能力。 |
+| R-5.10 | 高危动作（删除、生产数据、外发、发布）默认拒绝或显式审批，先于副作用发生，且留审计（详见 [07-delivery.md](07-delivery.md)）。 |
+
+### 2.3 契约与同步
+
+| 编号 | 规则 |
+|---|---|
+| R-5.11 | 跨进程/跨模块契约只在共享层一处定义（G-1），实现只落契约不发明契约。 |
+| R-5.12 | 每个对外接口入参显式校验（继承 R-3.2）。 |
+| R-5.13 | 实现点 ↔ 规格 id（BR/E/AC）双向可追溯：改一个行为必须同步它的验收/异常/契约。 |
+
+---
+
+## 3. 输出规范
+
+### 3.1 交付物
+- 源码改动（每行可追溯）
+- colocated 测试（新行为 + 修复回归）
+- 变更同步产物（契约/迁移/文档/i18n）
+
+### 3.2 提交规范（本仓沿用 `AGENTS.md` 规则 6 + Conventional Commits；生成建议见 `skills/builtin/dk-commit`）
+```text
+<type>(<scope>): <subject>        # subject 简洁中文，≤50 字
+                                   # 正文：英文完整内容 + `---` 分隔 + 中文完整内容
+                                   # （不复述 diff；主分支是 build）
+type: feat | fix | docs | refactor | test | chore | build
+```
+
+### 3.3 变更矩阵（改了什么，必须同步什么）
+
+| 变更 | 必须同步 |
+|---|---|
+| 跨进程契约 / IPC 通道 / 接口 | `packages/api/src/contracts.ts`（唯一入口）+ `docs/api/ipc-api-reference.md` + preload/handler 对齐（`src/main/ipc-alignment.test.ts` 拦截） |
+| 模块增删 / 职责变化 | `docs/architecture/codemap.md`（头部统计跑 `node scripts/repo-stats.mjs`，`docs-baseline.test.ts` 拦截）+ 架构文档 |
+| 数据结构 / 迁移 | 迁移文件（只追加，`packages/agent-sdk/src/state/migrations.ts`）+ `docs/architecture/data-model.md` |
+| UI 文案 / 状态机 / 组件 | i18n key（`packages/web-ui/src/i18n/messages.ts`）+ 视觉 token（`packages/web-ui/src/theme/tokens.css`）+ 表面规格 |
+| 主链路 / 安全边界 | `docs/architecture/flows.md` + 相关安全测试（tool-policy/tool-gate/redact） |
+| E2E 行为 / 运行方式 | E2E 测试与自动化文档（`docs/e2e/e2e-architecture-and-automation.md`）+ playwright |
+| 宿主形态 / 接入方式 | `docs/architecture/host-modes.md` |
+
+---
+
+## 4. 反模式（实现期高频错误，摘自 Karpathy 准则）
+
+- **先写后想**：不问假设、隐藏困惑、静默选一种解释。
+- **过度设计**：为单次使用写抽象、为没要求的场景加"灵活性"。
+- **顺手重构**：改 bug 时顺带"美化"周边代码 → diff 失控、评审失效。
+- **无验证前进**：写一大片再统一跑一次 → 失败定位成本爆炸。
+- **留下孤儿**：改动删掉了某函数/变量/import 却不清理由本次改动产生的悬空引用。
+
+---
+
+## 5. 轻量路径（小改动）
+
+- 一行修复/文案：单提交 + 最小测试，直接走本阶段规则不产额外文档。
+- 但 R-5.2~R-5.13 的安全/契约/同步规则对小改动同样强制。
+
+---
+
+## 6. 相关文档
+
+- 编码前确认设计：阶段 ③ [03-detailed-design.md](03-detailed-design.md)、阶段 ④ [04-ui-spec.md](04-ui-spec.md)
+- 自测通过后进入：阶段 ⑥ [06-validation.md](06-validation.md)
+- 提交与审查技能：`skills/builtin/dk-commit`、`skills/builtin/dk-review`
@@ -0,0 +1,106 @@
+# 阶段 ⑥ 验证与质量门（Validation & Quality Gates）
+
+> **定义**：用**最小且与最终改动相关**的检查验证结果：每个改动映射到覆盖其行为/不变量/风险的检查并实际执行；失败必须可复现、可定位、有因果诊断；修复后**同一检查**复验。验证在真实交付边界之外只算"局部证据"。
+> **输入**：⑤ 的实现产物（diff + 自测结果）+ ① 的验收标准（AC 映射）。
+> **输出**：验证记录（检查身份 + argv/cwd + 结果 + 覆盖的不变量）、审查结论。
+> **进入下一阶段（⑦ 交付与发布）**：全部质量门通过、审查无阻塞项。
+
+---
+
+## 1. 要求（Requirements）
+
+### 1.1 进入条件
+- 实现已满足 ⑤ 的 DoD（自测全绿、变更矩阵已同步）。
+
+### 1.2 完成条件（DoD）
+- [ ] 每个实质改动映射到最小且覆盖它的项目检查（单测/契约/集成/E2E/视觉/迁移/打包之一），并在最后一次编辑后运行
+- [ ] 验证失败按"复现 → 定位（可归因的诊断）→ 因果假设 → 最小 owner 修复"链处理；重试不加诊断 ≠ 修复证据
+- [ ] 修复后在最终状态上**重跑同一检查**（或记录等价性理由）
+- [ ] 评审（dk-review 四维）完成：正确性/一致性/安全/测试，无未解决的阻塞项
+- [ ] 门禁结果与最终修订绑定（不是"跑过"而是"这个 revision 过了"）
+
+---
+
+## 2. 规则（Rules）
+
+### 2.1 验证选择
+
+| 编号 | 规则 |
+|---|---|
+| R-6.1 | **相关验证**：最终改动必须被最小且直接覆盖其行为的检查验证；跑一个无关的大套件或陈旧结果不算（旧结果、全量套件、agent 一句"done"都不是验证证据）。 |
+| R-6.2 | **分层选择**：按"快/慢、便宜/昂贵"分层（lint/typecheck/单测 → 契约/集成 → E2E → 打包冒烟），agent 能按改动选择正确层；慢 e2e 本身不坏，坏的是它成为唯一反馈。 |
+| R-6.3 | **失败的顺序链**：`failure → reproduction → diagnosis → bounded repair`，缺一不可；一条重试就过了但没有诊断的修复，不构成修复证据。 |
+| R-6.4 | **修复后复验**：同一检查（或证明覆盖同一行为与范围的等价检查）在修复后的最终状态重跑；无失败无修复则记 `N/A` 并附相关验证结果。 |
+| R-6.5 | **验证是机器事实**：命令身份（argv/cwd）、fixture、修订号、结果、覆盖的不变量都要保留；CI 身份与本地等价性记录在案。 |
+
+### 2.2 质量门（Quality Gates）
+
+| 编号 | 规则 |
+|---|---|
+| R-6.6 | **机制强制优先于文档**：架构/安全/schema/迁移/生成物漂移等规则用测试与静态检查强制（architecture test、契约 diff、迁移 lint、生成物 drift check），只写进文档不算门禁。 |
+| R-6.7 | **门禁与修订绑定**：必须过的检查（lint/typecheck/单测/关键 E2E/构建）在合并前对最终修订全绿；绕过门禁必须有记录的理由。 |
+| R-6.8 | **测试断言真实行为**：测试断言行为与不变量，不只是冒烟（跑通≠通过）；live/真实设备用例必须有 skip 守卫，禁止依赖本机路径/凭据。 |
+| R-6.9 | **UI 验证裁判独立**：驱动与观察分离；同一模型驱动又目测自己的截图不算 pass（详见 [04-ui-spec.md](04-ui-spec.md) §4）。 |
+
+### 2.3 评审
+
+| 编号 | 规则 |
+|---|---|
+| R-6.10 | 评审顺序：正确性（边界/错误处理/并发/资源泄漏）→ 一致性（风格/命名/契约同步）→ 安全（注入面/密钥落日志）→ 测试（新行为有测试锁定）。 |
+| R-6.11 | 只报有证据的问题，按严重度分组（阻塞/建议/可选），每条带 `文件:行号` 与可执行建议；没有问题的维度明确说"未发现问题"。 |
+
+---
+
+## 3. 输出规范
+
+### 3.1 验证记录模板
+
+```text
+改动（diff/修订号）
+  检查清单：  检查身份 | 命令(argv/cwd) | 覆盖的不变量 | 结果 | 时间
+失败记录：    失败检查 → 复现步骤 → 诊断/日志身份 → 因果 → 修复 diff → 复验结果
+残余风险：    未覆盖范围、跳过守卫的用例、需人工确认项
+```
+
+### 3.2 验证分层建议（本仓）
+
+| 层 | 内容 | 触发 |
+|---|---|---|
+| L0 静态 | typecheck（`npm run typecheck`：tsc --noEmit + 双 tsconfig） | 每次提交 |
+| L1 单测 | 组件/工具/逻辑（vitest，colocated `*.test.ts`，`npm test`） | 每次提交 |
+| L2 契约/守卫 | 跨进程契约对齐（`src/main/ipc-alignment.test.ts`）、迁移守卫（`migrations.test.ts`）、架构守卫（`architecture-guardrails.test.ts`）、docs 基线 | 触碰共享层/迁移 |
+| L3 集成 | 主进程+渲染、宿主装配 | 主链路 |
+| L4 E2E | `npm run test:e2e`（playwright，需先构建） | 关键用户流/发布前 |
+| L5 打包冒烟 | `build/ci-local.ps1`（Windows）/ `build/ci-local.sh`（macOS/Linux）：干净安装+全量门禁+安装包+启动冒烟 | 发布前 |
+
+> 本仓测试体系单一事实源：`docs/architecture/testing-architecture.md`；E2E 执行线见 `docs/e2e/e2e-architecture-and-automation.md`。验证要求按此落地，发现矩阵缺口在阶段 ⑧ 反馈。
+
+### 3.3 交付物清单
+- 验证记录（含失败→修复→复验链）
+- 审查结论（dk-review 输出，阻塞项清零）
+- 测试覆盖增量说明（新增测试对应的 AC/BR/E）
+
+---
+
+## 4. 反模式
+
+- **陈旧/无关验证**：拿旧结果或全量套件当"这次改动"的证据。
+- **只重试不诊断**：失败重跑过了就提交，没有定位因果。
+- **修完不复验**：修复可见，但最终修订上没有任何同一检查的重跑。
+- **把本地测试当交付证据**：真实接受边界（CI/合并/发布）未被打开时，用 `Unobserved` 而非编造缺失的 PR/部署。
+- **裁判即选手**：模型目测自己生成/操作的 UI。
+
+---
+
+## 5. 轻量路径（小改动）
+
+- 一行修复：对应单测 + 全量 typecheck + 该模块相关测试，记录即可。
+- 任何改动都不得跳过 R-6.3/R-6.4（诊断与复验）与 R-6.7（门禁）。
+
+---
+
+## 6. 相关文档
+
+- 输入：阶段 ⑤ [05-implementation.md](05-implementation.md)、规格 [01-requirement.md](01-requirement.md) 的 AC
+- UI 验证细则：阶段 ④ [04-ui-spec.md](04-ui-spec.md) §4
+- 通过后进入：阶段 ⑦ [07-delivery.md](07-delivery.md)
@@ -0,0 +1,143 @@
+# 阶段 ⑦ 交付与发布（Delivery & Release）
+
+> **定义**：让当前结果在**真实交付边界**被接受——真实的评审、必需的 CI、合并、发布——且高风险动作有风险匹配的审批、副作用有可用的回滚/恢复路径。本地测试与 agent 一句"done"属于阶段 ⑥，不属于交付。
+> **输入**：⑥ 已通过的实现（验证记录 + 门禁结果 + 审查结论）。
+> **输出**：已接受的修订 + 构建/安装包 + 发布记录 + 审计。
+> **进入下一阶段（⑧ 学习与沉淀）**：交付边界接受完成、发布记录落档。
+
+---
+
+## 1. 要求（Requirements）
+
+### 1.1 进入条件
+- 阶段 ⑥ 全部质量门通过，无未解决阻塞项。
+
+### 1.2 完成条件（DoD）
+- [ ] 真实接受边界（合并/发布/部署）绑定到**当前修订**，有修订级决策证据（不是"跑过 CI"而是"这个 revision 合并了/发布了"）
+- [ ] 每个高风险动作（发布、删除、生产数据、外发、签名）在副作用**之前**获得所需审批并留审计
+- [ ] 实际副作用有风险匹配的回滚/恢复路径（回滚、恢复、重试、补偿、幂等重放、安全中止之一）且含 owner 与后置条件
+- [ ] 发布记录（版本、变更、产物、验证）落档
+
+---
+
+## 2. 规则（Rules）
+
+### 2.1 接受边界
+
+| 编号 | 规则 |
+|---|---|
+| R-7.1 | **真实边界证据**：把真实接受决策绑定到当前修订与目标分支/环境。本地测试、自测、agent 完成声明均不是交付证据；外部边界打不开时记 `Unobserved`，不编造缺失的 PR/部署。 |
+| R-7.2 | **合并路径**：改动经默认分支可比较的 diff 进入（分支/PR 或等价受控路径）；直接在默认分支开发、无可评审 base diff 属交付缺陷。 |
+| R-7.3 | **必需检查绑定**：合并前必需检查对最终修订全绿，且与本地命令一致或有明确差异说明。 |
+
+### 2.2 高风险审批
+
+| 编号 | 规则 |
+|---|---|
+| R-7.4 | 破坏性/特权/外部/不可逆/共享状态/凭据/发布/生产动作，在效果发生**前**取得所需的人或策略 owner 决策；安全拒绝 + 可用升级路径是正确的控制行为，不是失败。 |
+| R-7.5 | 高风险动作留审计：谁、何时、什么、批准人/策略、审计引用。 |
+| R-7.6 | 确认无高风险动作时记 `N/A`（须经检查证明），不允许无理由的 N/A 阻塞结果。 |
+
+### 2.3 回滚与恢复
+
+| 编号 | 规则 |
+|---|---|
+| R-7.7 | 每个实际副作用有风险比例匹配的回滚/恢复路径，且绑定到受影响资源/入口/owner/后置条件。 |
+| R-7.8 | 回滚/恢复须可验证（安全模拟、演练、可比的保留任务或实际恢复结果）；禁止仅为提高证据强度而执行破坏性回滚。 |
+| R-7.9 | 恢复路径对失败与超时也要可运行（清理不得只在成功路径执行）。 |
+
+---
+
+## 3. 输出规范
+
+### 3.1 发布流程（本仓）
+
+> 发布链唯一权威：`docs/release-process.md`（ci-local 门禁 / release.mjs / 四包发布 / pack-audit / install-acceptance / 签名 / OTA）；签名细节 `docs/release-signing.md`；本地最短路径 `docs/local-build-quickstart.md`。以下为阶段 ⑦ 在本仓的落地步骤，任一步非零即中止。
+
+```text
+Step 0  离线门禁（提交/合并/发布前必过）
+        Windows: build\ci-local.ps1 · macOS/Linux: build/ci-local.sh → run-local-ci.mjs 八步：
+        ① 删 release/ → ② npm ci 离线干净安装 → ③ npm run ci:check
+        （build:verify:runtime → vitest 全量 → build）→ ④ playwright E2E（不重构建）
+        → ⑤ electron-builder --publish never 打安装包 → ⑥ package:audit
+        （asar 禁 dist/mac-*、release/、.map/.d.ts/.ts；体积预算 140 MiB）
+        → ⑦ verify-packaged-app（extraResources 五件断言 + 真启动 5s 冒烟）
+        → ⑧ write-build-report（逐产物 SHA-256 → build-report + SHA256SUMS）
+
+Step 1  版本与变更（SDK 四包发布时）
+        node scripts/release.mjs --registry <内网源URL> [--bump patch|minor|major]
+          [--skip-publish] [--dry-run]
+        九步编排：install → build（拓扑序 api→agent-sdk→account→web-ui）
+        → sync-web-ui-dist（dist/renderer → packages/web-ui/dist，断言 index.html 字节一致）
+        → test → pack-audit → bump（四包+根 lockstep，dk-* 互引钉新版，再生 lockfile）
+        → publish-sdks.mjs 逐包 npm publish 内网源 → install-acceptance
+        → npm run package
+        日常验证用 --dry-run --skip-publish（shouldPublish 独立纯函数，零副作用有测试断言）
+
+Step 2  构建安装包 + 产物审计
+        npm run package = build + electron-builder --publish never + package:audit + pack:sdks
+        审计（scripts/pack-audit.mjs）：tarball 顶层 ⊆ {dist, bin, README, LICENSE, package.json}；
+        零测试产物；dk-account 防误发（registry 锁内网 GitLab）；公开三包无 /account/ 路径泄漏
+        安装验收（scripts/install-acceptance.mjs）：spawn dk-web → listening banner →
+        GET /health 200 + GET / 200 含 <div id="root"> + 入口 JS 200
+
+Step 3  签名与公证（对外发布 / CI 打 Git tag 触发）
+        build/sign-local.sh（mac/Linux）/ build/sign-local.ps1（Windows）→ run-signing-build.mjs
+        （仅 darwin/win32；保留 APPLE_*/CSC_* 变量且不设断网）
+        npm ci → build → electron-builder --config.forceCodeSigning=true → package:audit
+        → 验签：mac codesign --verify --deep --strict；win Get-AuthenticodeSignature 双件 Valid
+        → 有 APPLE_APP_SPECIFIC_PASSWORD 时 DMG 公证 + stapler 装订 → 冒烟 + 构建报告
+
+Step 4  OTA 更新（走 OTA 通道时）
+        npm run ota:manifest（scripts/ota/generate-manifest.mjs）：扫 release/ 安装包算 SHA-256
+        → scripts/ota/latest.json；强制单一版本、单平台唯一；缺平台填全 0（运行侧 A6 守卫拒绝）
+
+Step 5  发布记录落档
+        build-report + SHA256SUMS（产物校验值）· 版本与变更（release.mjs bump）·
+        验证摘要（⑥ 门禁结果绑定修订）· 审批人/审计引用（高风险动作）
+```
+
+> 合并/发布边界绑定：改动经默认分支（`build`）可比较的 diff 进入；必需检查（ci-local 全链）对最终修订全绿。本仓无 CHANGELOG/RELEASE_NOTES 文件，版本与变更由 `scripts/release.mjs` 编排。
+
+### 3.2 交付记录模板
+
+```text
+目标边界：    分支 / 环境 / 发布通道
+修订绑定：    合并/发布的 revision 与决策证据（PR 号 / 发布记录）
+高风险动作：  动作 | 审批人/策略 | 时间 | 审计引用
+回滚路径：    受影响资源 | 路径 | owner | 后置条件 | 验证方式
+验证摘要：    ⑥ 的门禁结果绑定
+残余风险：    未覆盖边界、需人工确认项
+```
+
+### 3.3 交付物清单
+- 合并/发布证据（绑定修订）
+- 构建产物 + 审计记录（build-report / SHA256SUMS / package:audit 结果）
+- 发布记录（版本/变更/验证/审批）
+- 回滚路径文档（高风险动作必填）
+
+---
+
+## 4. 反模式
+
+- **本地验证冒充交付**：只有本地测试支持交付声明。
+- **先斩后奏的审批**：效果发生了才补审批，或自查自批。
+- **回滚路径悬空**：有"看起来像回滚"的文件/命令，但连不上实际资源/修订/权限/后置条件（文件名匹配不算证据）。
+- **只走发布后自动化**：仅在推到默认分支/发布时跑的检查不算接受时验证。
+- **无边界的高危可达性**：默认路径能触达生产/凭据/破坏性命令而无边界。
+
+---
+
+## 5. 轻量路径（小改动）
+
+- 内部改动：合并路径 + 必需检查即可，无发布/回滚部分（记 N/A 需检查证明）。
+- 任何触达发布/生产/凭据的动作：审批与审计条款不可省略。
+
+---
+
+## 6. 相关文档
+
+- 输入：阶段 ⑥ [06-validation.md](06-validation.md)
+- 发布链唯一权威与签名：`docs/release-process.md`、`docs/release-signing.md`（本仓无 CHANGELOG/RELEASE_NOTES 文件，版本与变更由 `scripts/release.mjs` 编排）
+- 本地/CI 补充：`docs/local-build-quickstart.md`、`docs/ci-runner-setup.md`、`docs/architecture/reproducible-build-baseline.md`
+- 完成后进入：阶段 ⑧ [08-learning.md](08-learning.md)
@@ -0,0 +1,88 @@
+# 阶段 ⑧ 学习与沉淀（Learning & Capture）
+
+> **定义**：识别生命周期机会（重复工作、熵增维护、能力缺口），把被支持的改进沉淀为**最小的持久 owner**（文档/技能/记忆/检查），并让沉淀保持准确、长期有效（长期验证）。学习不只是在项目结束时做，而是每个任务闭环后都要做。
+> **输入**：①–⑦ 全程产生的摩擦、重复、缺口、成功过程。
+> **输出**：学习捕获（本流程文档/仓库 docs/skills/记忆/门禁）+ 后续验证契约。
+> **进入下一阶段（回到 ①，或项目收尾）**：捕获落档，owner 明确。
+
+---
+
+## 1. 要求（Requirements）
+
+### 1.1 进入条件
+- 本任务已交付（⑦ 完成）或中途出现明确重复/熵增信号。
+
+### 1.2 完成条件（DoD）
+- [ ] 已区分"一次性问题"与"可复用机会"：重复工作（≥2 个可比任务同样意图+同样摩擦/成本）才进循环工程
+- [ ] 被捕获的改进有：触发方式 / 稳定输入 / owner / 工具与权限 / 产物 / 验证器 / 停止规则
+- [ ] 覆盖面检查做过：已有能力（观察→内置→已配置→扩展→新建）优先于新建
+- [ ] 捕获产物同步到正确 owner：流程缺陷 → 本目录；代码事实 → 文档/测试；重复过程 → 技能/脚本
+- [ ] 长期验证方式已写明（可比后续结果 或 定期维护检查），未验证的效果不作宣称
+
+---
+
+## 2. 规则（Rules）
+
+| 编号 | 规则 |
+|---|---|
+| R-8.1 | **重复才算机会**：一次偶发不算；两次可比任务 + 可复现的摩擦/成本/成功过程才构成重复机会。当前一次交接只能产生"当前维度"的建议，不能证明复现。 |
+| R-8.2 | **最小 owner**：先查覆盖阶梯（已有机制 → 内置 → 已配置 → 扩展 → 新建），选择最小持久 owner；不默认新建 Skill/脚本。 |
+| R-8.3 | **可运行才算沉淀**：沉淀必须有触发、输入、验证器与停止规则，且被实际使用过（`Exercised`）；仅创建未使用 = 未沉淀。 |
+| R-8.4 | **不空置缺口**：观察到需求但无持久覆盖时，留下显式缺口条目（owner + 证据），不悄悄丢弃。 |
+| R-8.5 | **效果需长期证据**：只有在可比后续结果中观察到改进（且无护栏回归）才能宣称"有效"；同窗口验证只证明修复状态，不证明长期效果。 |
+| R-8.6 | **维护类机会需可判定**：熵增/过时（依赖、文档、命令、版本）必须有命名的资产/不变量、权威真相、可运行的检查（返回 clean/gap/needs-evidence），文件年龄/提交历史本身只是线索，不是判定。 |
+| R-8.7 | **流程本身可演进**：本流程文档的缺陷、反模式、新规则，经确认后回写（带版本与变更记录，见 [README.md](README.md) 变更记录）。 |
+
+---
+
+## 3. 输出规范
+
+### 3.1 学习捕获模板
+
+```text
+机会类型：   一次性修正 | 重复机会 | 熵增维护 | 能力缺口 | 无候选窗口
+证据：       可比任务（id/日期/摩擦点）或 资产+不变量+检查
+覆盖面检查： 观察 → 内置 → 已配置 → 扩展 → 新建（勾选已试层级）
+最小 owner： 文档/技能/脚本/门禁/记忆（+ 触发/输入/验证器/停止规则）
+验证方式：   可比后续结果 | 定期维护检查（权威真相 + owner + 频率）
+状态：      已捕获（Exercised）/ 缺口（证据 + owner）/ 无候选
+```
+
+### 3.2 捕获落点
+
+| 捕获类型 | 落点（本仓） |
+|---|---|
+| 流程/阶段缺陷 | 本目录对应阶段文档（带版本变更记录） |
+| 代码事实/架构决策 | `docs/architecture/`（architecture-overview / codemap / flows / data-model 等基线）、ADR |
+| 重复过程/命令 | 脚本、`scripts/`、技能（`skills/`） |
+| 测试缺口 | `docs/architecture/testing-architecture.md`（测试体系单一事实源） |
+| 长期记忆 | agent 记忆系统 / 项目 memory（本仓：`docs/memory/` 本地工作文档与记忆架构，不入库） |
+
+### 3.3 交付物清单
+- 学习捕获记录（模板一份，可并入交付总结）
+- 实际落地的捕获产物（文档/脚本/技能/门禁 + 使用证据）
+- 长期验证契约（谁、何时、怎么判 clean/gap）
+
+---
+
+## 4. 反模式
+
+- **一次事故当规律**：单个事件、命令 token、计数、文件名当重复证据。
+- **跳过覆盖阶梯**：已有机制没试就先新建 Skill/脚本。
+- **沉淀完就完**：创建后无触发、无验证器、无停止规则，也从没被用过。
+- **同窗宣称效果**：同一窗口的修复验证冒充"长期有效"。
+- **文件年龄当结论**：没和权威真相对比就宣布依赖/文档过时。
+
+---
+
+## 5. 轻量路径（小改动）
+
+- 小任务：在 PR 描述或交付总结里加一小节（机会类型 + 落点 + 验证方式）即可。
+- 重大发布/反复摩擦的项目：必须完整执行本阶段。
+
+---
+
+## 6. 相关文档
+
+- 输入：阶段 ⑦ [07-delivery.md](07-delivery.md) 及全程证据
+- 流程总览与变更记录：[README.md](README.md)
@@ -0,0 +1,84 @@
+# Project Process — DK Forge（pi-desktop）开发流程规范
+
+> **本文档是本仓库项目开发的强制流程**。做任何项目需求（新功能、修复、重构、UI 改动、IPC/契约变更、发布）时，都必须按本流程的阶段执行：进入每个阶段先读对应章节，满足**要求**、遵守**规则（Rule）**、按**输出规范**产出交付物，检查清单全过才算完成本阶段。
+
+- 版本：v1.2 · 2026-09-04
+- 适用范围：本仓库（`pi-desktop`，发布名 **DK Forge**）全部功能开发，包括 Electron 宿主（`src/main/`）、renderer SPA（`packages/web-ui/`）、服务主体与 SDK 包（`packages/agent-sdk` 等）、E2E 与发布。仓库硬约束以 `AGENTS.md` 为准，本文档是执行流程（不与其冲突）
+- 来源：本规范由既有工程规则体系沉淀提炼（spec-structure / Agent Work Loop / Software Fluency / DESIGN.md Contract / Harness Engineering，规则参考 `vendor/better-harness/`），并按本仓技术栈（Electron + Node.js + React + TypeScript strict ESM monorepo）与 `AGENTS.md` 既有约定适配（v1.1：清除上游仓库残留引用，对齐本仓目录/契约/测试/发布事实）
+- 语言约定：流程文档正文用中文；标识符、类型、API、命令、文件路径一律用英文
+
+---
+
+## 1. 流程全景（八个阶段）
+
+```text
+① 需求与规格 ─→ ② 架构设计 ─→ ③ 详细设计 ─→ ④ UI Spec ─→ ⑤ 实现
+                                                    │
+⑥ 验证与质量门 ←─────────────────────────────────────┘
+        │
+⑦ 交付与发布 ─→ ⑧ 学习与沉淀
+```
+
+| 阶段 | 文档 | 一句话定义 | 核心输出 |
+|---|---|---|---|
+| ① 需求与规格 | [01-requirement.md](01-requirement.md) | 把意图变成一份"实现者无需猜"的规格（scope + 规则 id + 验收标准） | 规格文档（BR/E/AC 编号） |
+| ② 架构设计 | [02-architecture.md](02-architecture.md) | 定分层、模块边界、数据流与关键技术决策 | 架构文档 + ADR + 架构图 |
+| ③ 详细设计 | [03-detailed-design.md](03-detailed-design.md) | 把架构落到可实现的接口、数据结构、状态机与异常处理 | 详细设计文档 + 接口/数据契约 |
+| ④ UI Spec | [04-ui-spec.md](04-ui-spec.md) | 定义每个交付面的 UI 规则与约束（骨架/状态机/动作权限 + 设计系统 token） | DESIGN.md / 表面规格 / i18n 约束 |
+| ⑤ 实现 | [05-implementation.md](05-implementation.md) | 小步、可验证、范围受控地把设计变成代码 | 代码 + colocated 测试 + 变更同步 |
+| ⑥ 验证与质量门 | [06-validation.md](06-validation.md) | 用最小且相关的检查验证最终改动，失败可诊断、修复后复验 | 测试/门禁/审查记录 |
+| ⑦ 交付与发布 | [07-delivery.md](07-delivery.md) | 在真实交付边界被接受，高风险有审批，可回滚 | 构建产物 + 发布记录 + 审计 |
+| ⑧ 学习与沉淀 | [08-learning.md](08-learning.md) | 识别重复工作与熵增，沉淀可复用改进并长期验证 | 学习捕获（docs/skills/memory） |
+
+> **规模适配**：小改动（一行修复、文案调整）不必产出全部文档——规格/设计可合并为短说明（见各阶段"轻量路径"）。但**要求与规则始终有效**，越级必须有理由并记录。
+
+---
+
+## 2. 全局规则（所有阶段适用）
+
+以下规则跨阶段生效，任何阶段不得违反：
+
+- **G-1 唯一事实源**：跨进程/跨模块的类型与契约只定义一处（本仓：`packages/api/src/contracts.ts`），宿主与各包只 `import type`，禁止本地镜像。文档不覆盖代码，代码与测试是运行时事实。
+- **G-2 可追溯**：一切行为、规则、异常、验收标准都有稳定 id（如 `BR-01`、`E-01`、`AC-01`）。id 只追加不重排；废弃时标记 withdrawn，保留编号。
+- **G-3 配置≠行为**：存在一个文件/命令/规则 ≠ 它被使用。任何"机制存在"的结论必须有打开的证据（被调用、被测试、被门禁执行）。
+- **G-4 不越界**：只做请求范围内的事；发现无关问题只提不改；改动逐行可追溯到本次请求。越界扩展必须显式批准并记录。
+- **G-5 小步可回滚**：一次只做可验证的一步；优先狭窄、可回滚的改动；`trash` 优于 `rm`。
+- **G-6 机械规则优先于文档规则**：能用 lint/typecheck/测试/CI 门禁强制的，不许只写进文档。
+- **G-7 文档随变更同步**：改了什么，必须同步改对应的架构/接口/流程文档（见 [05-implementation.md](05-implementation.md) 变更矩阵）。
+- **G-8 提交与评审规范**：Conventional Commits（规范见 `AGENTS.md` 规则 6；commit 生成见 `skills/builtin/dk-commit`）；PR 必须带测试，至少 1 人评审，主分支是 `build`。
+
+---
+
+## 3. 遵守机制（如何保证被遵守）
+
+1. **启动即读**：接手本仓的开发 agent（编码执行者）开工前先读本 `README.md` + 目标阶段文档。
+2. **阶段门禁**：每个阶段的"完成条件（DoD）"检查清单未全过，不得进入下一阶段；上一阶段的输出是本阶段的输入。
+3. **合并前审查**：PR 评审人按 [06-validation.md](06-validation.md) 的质量门核对，未过门禁的 PR 打回。
+4. **演进**：本流程本身也在 ⑧ 学习与沉淀 的范围内——流程缺陷、重复摩擦、新反模式，应更新对应文档（带版本号与变更记录）。
+
+---
+
+## 4. 文档索引
+
+| 路径 | 内容 |
+|---|---|
+| [01-requirement.md](01-requirement.md) | 需求与规格：7 段结构、BR/E/AC 编号、六道完备性门 |
+| [02-architecture.md](02-architecture.md) | 架构设计：分层/边界/数据流/决策记录、架构图规范 |
+| [03-detailed-design.md](03-detailed-design.md) | 详细设计：接口契约/状态机/异常/迁移/边界条件 |
+| [04-ui-spec.md](04-ui-spec.md) | UI Spec：表面规格（骨架/组件/状态机/权限）+ 设计系统（DESIGN.md） |
+| [05-implementation.md](05-implementation.md) | 实现：编码规则、规模红线、变更矩阵、自测 |
+| [06-validation.md](06-validation.md) | 验证与质量门：分层验证、失败诊断与复验、评审 |
+| [07-delivery.md](07-delivery.md) | 交付与发布：构建/签名/发布记录/回滚 |
+| [08-learning.md](08-learning.md) | 学习与沉淀：循环工程、知识捕获、长期验证 |
+| **templates/**（模板库） | 产品/文档模板：**[URD-Template.md](templates/URD-Template.md)**（用户需求文档模板，产品级需求描述，软件项目通用；[HTML 看板](templates/URD-Template.html)） |
+
+**快速开始**：新需求 → 读 [01-requirement.md](01-requirement.md)；涉及 UI → 同时读 [04-ui-spec.md](04-ui-spec.md)；改动进入实现前 → 过 [01-requirement.md](01-requirement.md) 的完备性门 + [03-detailed-design.md](03-detailed-design.md) 的契约检查；提交前 → 过 [06-validation.md](06-validation.md) 门禁。
+
+---
+
+## 变更记录
+
+- v1.3（2026-09-05）：新增 §4 模板库索引——`templates/URD-Template.md`（URD 模板，含使用说明/编号规则/章节结构）及其 HTML 看板；模板为软件项目产品级需求文档的通用起点（输入到阶段 ①）。
+- v1.2（2026-09-04）：阶段 ⑦ 发布流程按本仓真实编译打包链路重写——离线门禁（ci-local 八步）→ release.mjs 九步编排 → pack-audit/install-acceptance → sign-local 签名公证 → OTA manifest，全部对齐 `docs/release-process.md`。
+- v1.1（2026-09-04）：适配本仓（pi-desktop / DK Forge）事实——清除上游仓库残留（decokee-deck / Vue2 / `src/shared` / CONTRIBUTING 等引用），目录、契约、测试、发布与文档引用对齐 `AGENTS.md`。
+- v1.0（2026-08-16）：初始版本，基于既有工程规则体系建立八阶段流程。
@@ -0,0 +1,305 @@
+# URD 模板（User Requirements Document）
+
+> **定位**：URD（用户需求文档，与 PRD 等价）是**产品级**需求描述——定义"产品是什么、为谁服务、用户要完成哪些任务、每个功能如何被用户感知和使用"。它是软件项目**一切后续文档的输入**：阶段 ① 需求规格（BR/E/AC）、② 架构、③ 详细设计、④ UI Spec、测试用例，都必须能追溯到本文档的功能条目。
+> **适用**：本模板用于 DK Forge 及后续所有软件项目的产品需求文档撰写。
+> **用法**：复制本文件为 `<产品名>-URD-<版本>-<日期>.md`，按占位符 `<...>` 填写；删除不适用章节并记录删除理由；编号规则见第 0 节，不得破坏。
+
+---
+
+## 0. 使用说明与编号规则（写文档前先读；成稿后可删）
+
+### 0.1 文档关系
+```text
+商业/产品设想（PRD 草稿、口头想法）
+        │ 提炼、确认边界
+        ▼
+本 URD —— 用户可感知的功能需求（本文档）
+        │ 拆解为可实现的单点需求
+        ▼
+阶段①规格（BR/E/AC）→ ② 架构 → ③ 详细设计 → ④ UI Spec → 实现 → 测试
+```
+- URD 回答 **"用户要什么、为什么、长什么样、做到什么程度算好"**；
+- 阶段 ① 规格回答 **"这一版改动具体怎么实现、怎么验收"**；
+- URD 讲用户语言，不写内部实现（不写表结构、类名、IPC 通道）；确有底层约束须写"约束与假设"。
+
+### 0.2 编号规则（只追加、不重排、弃用标记 withdrawn）
+| 前缀 | 含义 | 示例 |
+|---|---|---|
+| `MOD-xx` | 模块编号 | `MOD-03` |
+| `FR-<模块简码>-<nn>` | 功能点编号（模块简码见 6.1 清单） | `FR-STU-04` |
+| `EX-<模块简码>-<nn>` | 功能点的异常/边界场景 | `EX-DASH-02` |
+| `NFR-xx` | 非功能需求 | `NFR-07` |
+| `SEC-xx` | 安全/权限需求 | `SEC-03` |
+| `AC-xx` | 端到端验收标准 | `AC-10` |
+| `OQ-xx` | 待决策/开放问题 | `OQ-04` |
+
+### 0.3 书写纪律（继承仓库阶段①规则）
+1. 每条功能点 = **一个用户可感知的行为**，写成"用户可验证"的描述；散文式一段话超过 5 行 → 拆成行为列表。
+2. 每个功能点必须写 **主流程**（happy path）与 **异常/边界**（用户会遇到的不顺路径），禁止只写 happy path。
+3. 写不动的先 `TBD` / `OQ-xx`（带 owner 与期限），禁止编造。
+4. 优先级统一 `P0`（MVP 必做）/ `P1`（近期待做）/ `P2`（远期）。
+5. 所有状态、权限、阈值是可配置项时写明"默认值 + 可配置范围"，不写死。
+
+---
+
+## 1. 文档控制
+
+### 1.1 文档信息
+| 项 | 内容 |
+|---|---|
+| 文档名称 | `<产品名> 用户需求文档（URD）` |
+| 文档编号 | `URD-<产品简称>-<版本>` |
+| 版本 / 日期 | `V<0.x> · <yyyy-mm-dd>` |
+| 产品名称 / 版本 | `<对外名称> V<目标版本>` |
+| 文档状态 | 草稿 / 评审中 / 已确认 / 已发布 |
+| 作者 / 评审人 | `<姓名或角色>` |
+| 维护位置 | `<仓库路径>` |
+
+### 1.2 历史记录
+| 日期 | 版本 | 作者 | 变更记录 |
+|---|---|---|---|
+| yyyy-mm-dd | V0.1 | xxx | 首次创建；<列出范围，如"第 1–3 章 + MOD-01" > |
+
+### 1.3 评审与分发
+| 角色 | 评审关注点 |
+|---|---|
+| 产品负责人 | 范围、优先级、验收标准是否符合商业意图 |
+| 设计（UI/UX） | 功能点的用户流程与界面要求是否可实现 |
+| 研发负责人 | 是否存在未定义边界或不可实现的约束 |
+| 测试负责人 | 每条功能点是否可验证、异常是否齐全 |
+| 市场/实施 | 话术与演示脚本是否与功能一致 |
+
+---
+
+## 2. 目的与范围
+
+### 2.1 文档目的
+> 一句话：本文档定义 `<产品名>` 的用户需求——`<它解决谁的什么问题，交付什么结果>`。
+说明：本文档的读者（产品/设计/研发/测试/市场）、文档如何被使用（培训材料？需求基线？）。
+
+### 2.2 产品定义
+| 项 | 内容 |
+|---|---|
+| 一句话结论 | `<产品做什么、为谁做、交付物>` |
+| 核心价值 | `<用户购买/使用它的理由，1–3 条>` |
+| 交付结果 | `<安装包/服务/平台等>` |
+
+### 2.3 目标范围（In Scope）
+- `<范围一：……>`
+- `<范围二：……>`
+
+### 2.4 非目标（Out of Scope）——与范围同等重要，逐条写明排除理由
+| 排除项 | 理由 | 可能时机 |
+|---|---|---|
+| `<明确不做的事>` | `<为什么本期不做>` | 后续版本 / 永不 |
+| `<例如：开放第三方市场>` | `<例如：首版只支持受控模板>` | V2+ |
+
+### 2.5 成功标准（产品级，一句话可判）
+- `<首个版本成功的硬性标志，如：不写代码的业务人员可在 60 分钟内发布一个可用 Agent>`
+
+---
+
+## 3. 参考文献
+| 文档/来源 | 版本/日期 | 与本文档的关系 |
+|---|---|---|
+| `<产品定义 PRD>` | V0.1 | 本文档的功能蓝本 |
+| `<代码功能事实：codewiki / docs 架构文档>` | 生成日期 | 现状能力基线 |
+| `<竞品/标准/协议>` | | 约束来源 |
+| `<阶段①规格草稿>` | | 已确认决策的回写来源 |
+
+---
+
+## 4. 术语、角色与成功标准
+
+### 4.1 术语表
+| 术语 | 定义（用户语言，可配图） |
+|---|---|
+| `<领域词，如 Agent / 面板 / Scope>` | `<一句话说清>` |
+
+### 4.2 用户角色
+| 角色 | 画像 | 主要任务 | 成功标准 | 常用模块 |
+|---|---|---|---|---|
+| `<角色>` | `<谁，技术背景>` | `<日常要完成什么>` | `<做到什么算好>` | MOD-xx |
+| 例：培训者 | 懂业务不写代码 | 制作并发布一个 Agent | 不改代码完成首版 | MOD-02/05 |
+
+### 4.3 角色 × 模块 关注矩阵（可选）
+| | MOD-01 | MOD-02 | MOD-03 | … |
+|---|---|---|---|---|
+| 角色 A | 使用 | 使用 | – | |
+| 角色 B | – | 审核 | 使用 | |
+
+---
+
+## 5. 产品概览与核心体验
+
+### 5.1 产品背景与目标
+`<为什么做这个产品；本版本要证明什么（如：证明某类用户能独立完成某闭环）。>`
+
+### 5.2 信息架构与模块关系
+```text
+一级入口/模块树（文字树或图）
+├── <模块一>
+│   ├── <子功能>
+└── ...
+```
+`<模块之间的依赖与数据走向一句话说明。>`
+
+### 5.3 核心用户流程（端到端）
+`<步骤表：用户从进入到完成一次价值闭环的全过程>`（例：安装 → 授权 → 首次运行 → 理解 → 协作）
+
+### 5.4 体验原则
+1. `<先给结果，再邀请对话>`（示例原则，按产品改写）
+2. `<每个结论可解释>`
+3. `<异常与关键选择集中呈现，普通状态不打扰>`
+4. `<任何能力可见、可停用、可替换>`
+5. ...
+
+### 5.5 交付面与平台约束
+| 交付面 | 说明 | 优先级 |
+|---|---|---|
+| `<桌面 Electron / Web / 移动 / 硬件>` | `<能力边界、离线、多端同步>` | P0/P1 |
+
+---
+
+## 6. 功能模块需求（本文档主体）
+
+### 6.1 模块清单与划分说明
+> 划分原则：按**用户任务闭环**划分模块（不是按技术层）；模块间尽量低耦合、每个模块有明确负责人与验收场景。
+| 模块 | 模块名 | 一句话职责 | 主要角色 | 简码 | 优先级 |
+|---|---|---|---|---|---|
+| MOD-01 | `<名称>` | `<为谁解决什么>` | | `<STU/DASH…>` | P0 |
+| MOD-02 | ... | | | | |
+
+> 模块依赖图（可选）：`MOD-02 依赖 MOD-01 的发布产物` 等。
+
+### 6.2 各模块详细需求
+> 每模块复制下面一节；模板中 MOD-xx 以 MOD-01 为例。
+
+#### MOD-01 `<模块名>`
+**模块概述**
+| 项 | 内容 |
+|---|---|
+| 目的 | `<该模块在用户任务闭环中的位置与作用>` |
+| 用户 | `<角色>` |
+| 入口 | `<从哪个一级入口/页面进入>` |
+| 依赖 | `<依赖哪些其他模块或外部系统>` |
+| 核心对象 | `<用户在该模块操作的对象：如 Agent、面板、版本>` |
+
+**功能点总览**
+| 编号 | 功能名称 | 用户可完成的任务 | 优先级 |
+|---|---|---|---|
+| FR-XXX-01 | `<名称>` | `<一句话用户价值>` | P0 |
+| FR-XXX-02 | ... | | P1 |
+
+**功能点详述**
+
+##### FR-XXX-01 `<功能名称>`（P0）
+- **功能描述**：`<该功能是什么；用户可用它完成什么；关键行为逐条列出，如：>`  
+  1. `<行为一>`  
+  2. `<行为二>`
+- **前置条件**：`<进入该功能前必须满足的条件，如已登录、已有数据源授权>`（无则写"无"）
+- **主流程**：
+  | 步骤 | 用户操作 | 系统响应 |
+  |---|---|---|
+  | 1 | `<操作>` | `<响应/界面变化>` |
+  | 2 | ... | |
+- **行为规则与边界**：
+  - `<规则/边界一：如"默认展示最近 7 天，可配置 1–90 天">`
+- **异常与边界场景**：
+  | 编号 | 场景 | 用户可见行为 | 后备方案 |
+  |---|---|---|---|
+  | EX-XXX-01 | `<如：数据源超时>` | `<提示什么>` | `<重试/降级显示陈旧数据并标注>` |
+- **UI 与交互要求**：`<布局要点、状态（空/加载/错误/正常）、交互手势、可访问性>`（详见阶段 ④ UI Spec）
+- **权限与安全**：`<该功能涉及的权限等级（见第 9 章 L0–L3）、确认点、审计>`（无则写"无额外要求"）
+- **验收要点**：`<该功能可验证的 3–6 条要点，对应第 11 章 AC>`：
+  - [ ] 要点一
+  - [ ] 要点二
+- **关联与备注**：`<关联功能点/引用文献/开放问题 OQ-xx>`（无则写"—"）
+
+##### FR-XXX-02 …（复制上面小节）
+
+---
+
+## 7. 数据与内容需求（若产品以数据/面板/内容为核心）
+### 7.1 数据类型与口径
+| 内容 | 用户要定义什么 | 系统如何使用 |
+|---|---|---|
+### 7.2 内容/数据生成规则
+### 7.3 展示与交互要求（数据面）
+
+---
+
+## 8. 非功能需求
+| 编号 | 类别 | 需求 | 目标/阈值 |
+|---|---|---|---|
+| NFR-01 | 性能 | `<首屏/操作响应>` | `<如 ≤2s>` |
+| NFR-02 | 可用性 | `<新用户无培训完成核心任务>` | `<如 ≤60 分钟>` |
+| NFR-03 | 可靠性与离线 | `<数据源/服务不可用时的降级>` | |
+| NFR-04 | 兼容性 | `<OS/浏览器/分辨率>` | |
+| NFR-05 | 可访问性 | `<键盘/读屏/对比度>` | |
+| NFR-06 | 国际化与本地化 | `<语言/时区/货币/格式>` | |
+| NFR-07 | 数据与隐私 | `<数据保留/删除/导出>` | |
+| NFR-08 | 可观测性 | `<日志/审计/用量统计>` | |
+| NFR-09 | 安装升级 | `<安装包、升级与回滚>` | |
+> 每行写清"可度量阈值"，无阈值 = 不可验收。
+
+---
+
+## 9. 安全、权限与信任
+### 9.1 用户可理解的动作等级
+| 等级 | 含义 | 产品行为 | 示例 |
+|---|---|---|---|
+| L0 查看 | 只读取和展示 | 授权后自动运行，留读取记录 | |
+| L1 准备 | 生成草稿不对外提交 | 可自动完成，用户可编辑 | |
+| L2 确认后执行 | 改变外部系统/通知他人 | 必须展示详情由用户确认 | |
+| L3 强确认 | 金钱/敏感/不可逆 | 二次确认或强身份验证，默认不批量 | |
+### 9.2 必须由产品层提供的能力（按产品改写）
+- `Scope 隔离 / 最小权限 / 凭证托管 / 执行确认 / 可撤销与熔断 / 全链路记录 / 发布前安全测试`
+### 9.3 信任界面要求
+- `<每个展示面与动作卡应呈现的信任信息：版本、数据时间、来源、权限等级、失败后果>`
+
+---
+
+## 10. MVP 范围与版本规划
+### 10.1 MVP 目标与样板场景
+| 目标 | 验证重点 | 最低闭环 |
+|---|---|---|
+### 10.2 P0 / P1 / P2 范围表
+| 产品/模块 | P0（MVP） | P1 | P2（明确不做入近期） |
+|---|---|---|---|
+### 10.3 推荐交付阶段
+| 阶段 | 产品结果 | 验收门 |
+|---|---|---|
+
+---
+
+## 11. 验收标准与产品指标
+### 11.1 端到端验收
+| 编号 | 验收标准（按角色、可执行） |
+|---|---|
+| AC-01 | `<Given/When/Then 或可执行描述>` |
+### 11.2 核心产品指标
+| 指标 | 定义 | 目标 |
+|---|---|---|
+| `<首次价值时间>` | `<定义>` | `<阈值>` |
+
+---
+
+## 12. 假设与待决策事项
+| 编号 | 事项 | V0.x 默认假设 | 需要的产品决策 | Owner | 期限 |
+|---|---|---|---|---|---|
+| OQ-01 | `<如：首端平台>` | `<默认>` | `<待决问题>` | | |
+> 未决事项不阻止开始原型，但进入正式排期前必须关闭。
+
+---
+
+## 附录
+### A. 功能点索引（全部 FR / EX 编号 → 模块位置，自动核对用）
+| 编号 | 功能 | 模块 | 优先级 | 状态（草稿/已确认/withdrawn） |
+|---|---|---|---|---|
+### B. 产品话术与演示脚本（可选）
+### C. 变更对照（本版相对上一版的增删）
+
+---
+
+> **模板维护**：本模板本身受仓库 ⑧ 学习与沉淀 约束——使用中发现结构缺陷，更新本文档并记入"变更记录"（放文末）。