@gordon.gan/specflow 1.8.0-beta → 1.8.2-beta

package/prompts/document/map/fix.md

@@ -0,0 +1,8 @@
+# 章节填充：fix
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造

package/prompts/document/map/frontend-architecture.md

@@ -0,0 +1,35 @@
+# 章节填充：frontend-architecture（前端架构设计）
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown（含 Mermaid 架构图）
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造
+
+## 前端架构章节硬规则（frontend-dev-guide 目录分层 + README §1.7 架构图规范）
+
+1. **目录分层必须给「职责 + 不放什么」边界**：
+   ```
+   pages/         # 路由级页面：只做组合与数据装配，不放业务逻辑
+   components/    # 可复用 UI 组件：只做渲染，不直接发请求（容器层负责）
+   hooks/         # 可复用逻辑：状态与副作用封装，不放页面专属逻辑
+   services/      # 数据访问层：封装 API 调用，统一错误处理与缓存
+   utils/         # 纯函数工具：无副作用，不依赖框架
+   types/         # 类型定义与契约（DTO/VO），与后端契约对齐
+   ```
+   每层都要写「这一层**不放什么**」——反AI决策 #1（不做决策）在目录层面的体现。
+
+2. **模块化/Monorepo 决策必须给结论 + 理由**：单仓 vs Monorepo、包如何划分、共享代码如何复用。禁止只罗列利弊不选边。
+
+3. **工程化配置给工具 + 版本**：ESLint（+ 版本）/ Prettier / Husky（pre-commit lint-staged）/ TypeScript 等级（L1/L2/L3，README §1.4）/ CSS 决策树（Tailwind/CSS Modules/styled-components 选哪个，为什么）。禁止「用 ESLint 和 Prettier」这种空话。
+
+4. **架构图必须有图 + 文字（README §1.7 门禁）**：
+   - Mermaid 组件图/容器图（```mermaid block），展示目录层之间、前后端之间的依赖方向。
+   - 图后逐节点说明职责/边界/「不放什么」，禁止只复述节点名。
+   - 纯前端变体（frontend-0to1）不画后端容器，只画前端层与 API 边界。
+
+5. **与 state-management 的衔接**：本章只给数据流总览（方向与归属的骨架），细述交 state-management 章节。交叉引用保持一致（R5）。
+
+6. **项目约定优先**：若项目已有目录规范/工程化约定（docs/ 或 IDE rules），以其为准并显式引用；未发现则标注「未发现项目规约」。
+
+> 优先级：项目约定 > SpecFlow guidance > LLM。项目禁令不得被通用规则覆盖。

package/prompts/document/map/goal.md

@@ -0,0 +1,8 @@
+# 章节填充：goal
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造

package/prompts/document/map/impact.md

@@ -0,0 +1,8 @@
+# 章节填充：impact
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造

package/prompts/document/map/implementability.md

@@ -0,0 +1,9 @@
+# 章节填充：implementability
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造
+- 涉及项目规约/DB/API/前端约束时，遵循「项目约定 > SpecFlow guidance > LLM」优先级

package/prompts/document/map/migration-guide.md

@@ -0,0 +1,36 @@
+# 章节填充：migration-guide（代码迁移指南）
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown（含 checklist）
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造
+
+## 迁移指南章节硬规则（frontend-dev-guide 场景四 · 代码迁移）
+
+1. **逐模块 checklist 必须可勾选**：
+   ```
+   - [ ] 模块 A（src/pages/auth）：
+         - 步骤 A1：xxx（改完自测通过，验收：y）
+         - 步骤 A2：xxx
+   - [ ] 模块 B（src/services）：
+         - 步骤 B1：xxx
+   ```
+   每个模块列可勾选步骤 + 每步验收标准。禁止笼统「迁移 auth 模块」。
+
+2. **自动化迁移脚本（codemod）**：给出工具（如 jscodeshift / eslint 自动修复 / 正则批量替换）与规则示例。能自动化的给脚本，不能的显式标「需人工」。
+
+3. **常见陷阱「现象 + 原因 + 解法」三段式**：
+   ```
+   ### 陷阱 1：迁移后首屏白屏
+   - 现象：xxx
+   - 原因：xxx（如 Vite 下 __dirname 不可用）
+   - 解法：xxx（如用 import.meta.url）
+   ```
+   禁止只写「注意兼容性」。
+
+4. **迁移顺序保证中间态可运行（f4 §5.3 双构建双运行）**：先迁依赖 → 再迁基础层（utils/services）→ 再迁页面 → 最后清理旧代码。每一步结束系统可构建可运行（新旧代码共存策略、双构建/双运行方案）。
+
+5. **培训计划**：分享/Slide 大纲、代码示例对照（新旧 API 对比表）、最佳实践文档链接。
+
+> 优先级：项目约定 > SpecFlow guidance > LLM。项目禁令不得被通用规则覆盖。

package/prompts/document/map/mvp-boundary.md

@@ -0,0 +1,8 @@
+# 章节填充：mvp-boundary
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造

package/prompts/document/map/non-goals.md

@@ -0,0 +1,8 @@
+# 章节填充：non-goals
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造

package/prompts/document/map/ops.md

@@ -0,0 +1,33 @@
+# 章节填充：ops（运维运营方案）
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造
+
+## 运维运营章节硬规则（SRE 四金信号 + PRR/Launch + DORA，见 f1-0to1.md §2.6）
+
+1. **监控必须覆盖四金信号（SRE）**：延迟（Latency）/ 流量（Traffic）/ 错误（Errors）/ 饱和度（Saturation）。每个信号给出指标名、采集方式、阈值、告警对象。缺一即不完整。前端侧补 RUM + CWV（LCP/FID/CLS）。
+
+2. **上线检查清单逐项带证据（PRR 精神）**：
+   ```
+   - [ ] 可观测性：监控/日志/告警已配置（证据：监控面板链接 + 最近一次告警演练记录）
+   - [ ] 回滚：回滚方案已演练（证据：回滚演练记录 + 时间）
+   - [ ] 备份：数据备份已启用且可恢复（证据：RTO/RPO + 最近一次恢复演练）
+   - [ ] 依赖：外部依赖（DNS/证书/第三方）已就绪（证据：证书有效期 + 依赖清单）
+   - [ ] 文档：runbook/值班手册已更新（证据：文档链接）
+   ```
+   每一项必须有「证据」，空证据 → 视为未完成。
+
+3. **告警与值班**：告警分级（P0/P1/P2）、升级路径、响应时限、值班轮换（on-call）。on-call 与告警阈值需匹配（避免告警疲劳）。
+
+4. **备份恢复**：数据备份策略（全量/增量频率）、RTO/RPO 目标、恢复演练频率。无数据库/无状态服务需显式写「不涉及」。
+
+5. **安全基线**：密钥管理（不用环境变量明文存密钥）、CSP、HTTPS 强制、防火墙/访问控制、审计日志。按项目形态取舍并写明理由。
+
+6. **成本控制**：资源规模预估、预算告警、用量治理（闲置资源回收）。按团队规模取舍。
+
+7. **DORA 度量**：部署频率/变更前置时间/MTTR/变更失败率的目标值与度量方式，作为持续改进依据。
+
+> 优先级：项目约定 > SpecFlow guidance > LLM。项目禁令不得被通用规则覆盖。

package/prompts/document/map/performance.md

@@ -0,0 +1,32 @@
+# 章节填充：performance（性能方案）
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造
+
+## 性能章节硬规则（frontend-dev-guide 性能 KPI + README §1.3 + 反AI决策 #2）
+
+1. **优化必须带数字（前后对比）**：每一项优化给出「优化前 → 优化后」的具体数字（体积 KB、耗时 ms、Lighthouse 分数），并注明测量工具与口径。禁止只写「用 React.memo + useMemo」（反AI决策 #2）。
+
+2. **CWV 指标给目标值（README §1.3 KPI 表）**：
+   | 指标 | 目标 | 测量工具 |
+   |------|------|---------|
+   | LCP | < 2.5s | Lighthouse / Web Vitals |
+   | FID | < 100ms | Web Vitals |
+   | CLS | < 0.1 | Web Vitals |
+   | TTI | < 3.5s | Lighthouse |
+   | Bundle (JS gzip) | < 200KB | bundle-analyzer |
+   | Lighthouse Score | > 90 | Lighthouse |
+   目标值必须给到数字，禁止「越快越好」。
+
+3. **打包与体积**：bundle 分析结论、代码分割/懒加载方案（路由级/组件级）、依赖体积审计（是否有可替换的大依赖）。
+
+4. **渲染性能**：列表渲染优化（虚拟滚动/增量渲染）、重渲染控制（memo/useMemo 的实际收益，用数字说明）、避免不必要的响应式更新。
+
+5. **缓存策略**：HTTP 缓存（Cache-Control/ETag）、CDN、请求合并与防重复请求、接口数据缓存（SWR 等）。
+
+6. **测量口径明确**：在哪测（设备/网络模拟）、用什么工具、测什么页面（关键路径），保证数字可复现（README §1.3 门禁）。
+
+> 优先级：项目约定 > SpecFlow guidance > LLM。项目禁令不得被通用规则覆盖。

package/prompts/document/map/poc-demo.md

@@ -0,0 +1,25 @@
+# 章节填充：poc-demo（PoC Demo）
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造
+
+## PoC 章节硬规则（F5 预研/选型 · 验证假设而非做功能）
+
+1. **PoC 只验证「最不确定的风险点」**：PoC 不是做功能 demo。先回答「这个技术最大的不确定性是什么」（性能？兼容？DX？生态？），PoC 就为验证它而生。禁止把 PoC 范围写成一个小型生产系统。
+
+2. **边界必须明确（验证什么 / 不验证什么）**：写清楚「本 PoC 验证 X，**不**验证 Y（Y 留待生产期）」。没有「不验证什么」的 PoC 边界 = 没有边界。
+
+3. **判据可证伪**：每个验证点给**可量化的成功/失败判据**（如「QPS ≥ 1000」「冷启动 < 2s」「可无障碍接入现有登录」）。判据可证伪，验证才有意义；「感觉还行」不算判据。
+
+4. **文档只写 PoC 设计/边界/判据/结论**，**不写实现代码**：可运行的 demo 代码另行落库（指定仓库/目录路径即可），本文档是方案文本产物，不是代码仓库。
+
+5. **已知限制与未验证项 ≥1 条**：诚实列出 PoC 没覆盖到的场景/数据量/边界（如「未测百万级数据」「未验证 IE 兼容」）。这直接决定选型结论的适用范围。
+
+6. **生产化差距必写**：PoC 结论之后，说明「从 PoC 到生产还差什么」——性能余量、健壮性、监控、安全、团队维护成本。禁止「PoC 通过了就可以上生产」。
+
+7. **结论承接选型**：PoC 结论（验证通过/失败/部分通过）要能被 tech-selection 章节引用，作为评估矩阵里「验证证据」的输入。
+
+> 优先级：项目约定 > SpecFlow guidance > LLM。项目禁令（如「禁止做某方案 PoC」）不得被通用规则覆盖。

package/prompts/document/map/regression.md

@@ -0,0 +1,8 @@
+# 章节填充：regression
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造

package/prompts/document/map/reproduce.md

@@ -0,0 +1,8 @@
+# 章节填充：reproduce
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造

package/prompts/document/map/requirement.md

@@ -0,0 +1,8 @@
+# 章节填充：requirement
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造

package/prompts/document/map/research.md

@@ -0,0 +1,25 @@
+# 章节填充：research（技术调研报告）
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown（含对比表格）
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造
+
+## 技术调研章节硬规则（F5 预研/选型 · 反AI决策精神）
+
+1. **候选方案 ≥2 个**：列出全部被认真评估的候选（含「被否掉的」——说明否掉的理由，这是预研的价值）。禁止只调研一个然后硬推。
+
+2. **对比维度表必须同列可比**：表格行为候选、列为同一组维度（成熟度/性能/社区/学习成本/许可…），**禁止不同候选用不同维度**（那是"定制对比"，等于没比）。每个格子给事实或「未验证」标注，不写空话。
+
+3. **社区活跃度必须给数字**：GitHub Star 数 / open issue 数 / Release 频率（近 12 个月）/ 最近 release 时间 / 维护者响应。数字要给到能支撑结论的粒度；「社区活跃」不给数字 = 拍脑袋。
+
+4. **团队匹配度有依据**：团队现有技能栈、迁移学习成本（给个估计：多少天/多少人）、长期维护意愿。禁止「团队能学会」这种空话。
+
+5. **兼容性与约束**：浏览器/Node/现有技术栈/许可证（MIT/Apache/商业授权）的匹配；与项目红线（如「禁止引入消息队列」）冲突时要显式标出。
+
+6. **调研结论喂给后续**：明确「哪些问题留待 PoC 验证」「哪些数据留待 Benchmark 测量」，让 poc-demo/benchmark 章节承接（交叉引用，禁各写各的）。
+
+7. **优先候选**：给一个明确的优先候选方向（不一定是最终结论——最终结论在 tech-selection，这里给「值得深入验证的方向」）。
+
+> 优先级：项目约定 > SpecFlow guidance > LLM。项目禁令不得被通用规则覆盖。

package/prompts/document/map/root-cause.md

@@ -0,0 +1,8 @@
+# 章节填充：root-cause
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造

package/prompts/document/map/signoff.md

@@ -0,0 +1,9 @@
+# 章节填充：signoff
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造
+- 涉及项目规约/DB/API/前端约束时，遵循「项目约定 > SpecFlow guidance > LLM」优先级

package/prompts/document/map/state-management.md

@@ -0,0 +1,23 @@
+# 章节填充：state-management（状态管理）
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造
+
+## 状态管理章节硬规则（frontend-dev-guide 数据流方法论）
+
+1. **状态归属逐条列出（字段级）**：每条状态写清「字段名 → 存放位置（局部 state / 全局 store / URL 参数 / 服务端）→ 来源（用户输入/接口/派生）」。禁止笼统「状态放 store」。
+
+2. **禁止「全部放 store」（反AI决策 #1）**：明确哪些状态**不该**进全局 store——页面局部 UI 状态（折叠/展开/输入草稿）、与路由绑定的状态放 URL。给出「进 store 的标准」（跨页面共享/多组件消费/需持久化）。
+
+3. **Store 结构按域拆分**：全局 store 按业务域拆分模块（如 auth/cart/theme），模块内只含该域状态与 action。禁止一个巨型 store 装所有状态。
+
+4. **数据流方向必须单向**：action → reducer/store → selector → view → action。异步请求的 loading/error 归属要写明（是 store 字段还是局部状态），并给出竞态处理（请求序号/AbortController）。
+
+5. **持久化与恢复**：需要持久化的状态给存储介质（localStorage/URL/服务端）与恢复时机；SSR/Hydration 场景要写明首屏一致性与「水合闪烁」处理。
+
+6. **缓存与防重复请求**：服务端状态缓存策略（SWR/React Query 或自建）、失效时机、避免同一接口多处重复请求。
+
+> 优先级：项目约定 > SpecFlow guidance > LLM。项目禁令不得被通用规则覆盖。

package/prompts/document/map/tech-selection.md

@@ -0,0 +1,29 @@
+# 章节填充：tech-selection（技术方案评估 / 技术选型）
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造
+
+## 技术评估章节硬规则（借鉴 approval 技术方案评估）
+
+1. **选型五元组表格**：方向/选定方案/备选/选择理由/来源——前端、后端、数据库与缓存、基础设施至少四行。禁止只写「用 React」。
+2. **决策评审表**：每个关键决策给 决策/选定方案/备选方案/理由/影响评估/状态。来源=用户确认优先；绿场缺选型时强制。
+3. **风险与权衡**：列出技术风险（复杂度/依赖/性能/成本），给缓解措施或接受理由。
+4. **目标与非目标**：明确本章方案的 Goals 与 Non-Goals（不做什么）。
+5. **现状与约束**：用可读中文归纳现状与硬约束（含「本迭代禁止…」类红线）；禁止代码腔堆砌。
+6. **设计质量评估**：检查过度设计（YAGNI）——是否合理扩展性 vs 不必要的复杂度。
+7. **优先级**：项目约定 + 用户确认 > SpecFlow guidance > LLM。
+
+## 预研/选型模式（F5 fullstack-poc · 本要点出现时启用）
+
+当大纲含 **TS4（综合评估矩阵）**，即当前是预研/选型场景（有候选方案横向对比），追加以下硬规则：
+
+1. **综合评估矩阵（得分表）**：候选方案 × 评估维度（成熟度/性能/社区/团队匹配/成本/许可…）的二维表，每格给 1–5 分，每列给**权重**，末尾给**加权总分**。矩阵必须有得分与权重，禁止「候选 A 略优于 B」这类无分数的结论。
+2. **一句话立场（反AI决策 #1）**：推荐结论必须有一句话讲清「本项目**不**适用什么 / 什么条件下不选」——只列功能清单不算有立场。
+3. **证据引用**：矩阵得分尽量引用 research（调研）/ poc-demo（验证）/ benchmark（实测数据）的证据，标注来源章节，禁止自说自话。
+4. **风险与回退**：推荐方案的失败代价 + 回退路径 + 替代方案。
+
+> 非预研场景（0to1/approve 等，无 TS4 要点）保持 1–7 规则即可，不需要评估矩阵。

package/prompts/document/map/test-strategy.md

@@ -0,0 +1,24 @@
+# 章节填充：test-strategy（测试策略 · 前端金字塔）
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造
+
+## 测试策略章节硬规则（F1 §2.2 + 前端金字塔）
+
+1. **分层测试矩阵（T1）**：逐层（单元/集成/E2E/契约）写清——测什么、用什么工具/框架、可验证目标（覆盖率或用例数）、与哪个验收标准/场景对应。禁止「写单元测试」空话。
+
+2. **测试环境与数据（T2）**：测试环境地址、测试数据准备（fixture/seed/工厂）、Mock 说明（接口 Mock/第三方 Mock）。
+
+3. **与验收标准映射（T3）**：每条验收标准（GWT）对应到至少一个测试层级，形成可追踪矩阵。
+
+4. **前端测试金字塔（T4）**：单元 60% / 组件 30% / E2E 10% 的投入比例；组件测试方式写明——Snapshot + 交互（render + fireEvent/userEvent 断言行为），关键组件/页面覆盖率目标。
+
+5. **回归测试范围（T5）**：明确回归清单覆盖受影响面（对应 impact 章节），列出受影响功能与对应回归用例。
+
+6. **工具版本具体**：框架 + 断言库 + 运行器给具体版本（如 Vitest + Testing Library），禁止「用 Jest」。
+
+> 优先级：项目约定 > SpecFlow guidance > LLM。项目禁令不得被通用规则覆盖。

package/prompts/document/map/ui-design.md

@@ -0,0 +1,21 @@
+# 章节填充：ui-design（前端/UI 设计 · 扩展状态机/路由守卫/埋点/浏览器兼容）
+
+你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
+- kind=narrative|mixed 的要点 → 产出叙述 Markdown
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
+- **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造
+
+## 前端章节硬规则（借鉴 approval frontend-guidance + README §1.2/§1.4）
+
+1. **总则必须写明**：Surface、Framework、Styling/设计系统、State、UI kit、FE testing、本迭代页面、项目约定（路径或「未发现」）、IDE skills/rules（路径或「未发现」）、**本迭代不选/不适用（至少 1 条）**、本迭代不涉及。
+2. **G5 页面/路由清单**：必须给出本迭代页面/路由清单 + 栈五元组。禁止只写「用 React」。
+3. **G6 空态/加载/错误**：每个关键 `Page · <短名>` 必须写清空态、加载、错误三项（文案或行为），并标明依赖的接口编号。成功态/无权限按需。
+4. **每页填空表**：目的/路由/组件树/依赖接口/字段级状态/请求时机/五态/边界（README §1.2 结构模板）。
+5. **交互状态机（UI5）**：仅复杂交互页（多步表单/向导/可逆流程）用 `stateDiagram-v2`；每状态写明 UI 表现与迁移条件（含异常分支）；简单页写「不涉及」。禁止把简单页面硬画成状态机。
+6. **路由守卫/懒加载（UI6）**：有权限/登录态要求的路由必须给守卫方案（守卫逻辑/重定向/动态 import 分块）。禁止只说「加守卫」。
+7. **埋点（UI7）**：仅 design 或项目约定点名时写——页面曝光事件 + 参数、关键点击事件 + 参数。否则省略。
+8. **浏览器兼容策略（UI8）**：兼容结论必须具体到版本 + 降级手段（如「Safari 16.4 以下无 :has()，用 JS 降级」），禁止「支持最新浏览器」式空话（README §1.4 门禁）。内部系统=最新 2 版；对外 C 端=iOS Safari 14+ / Android Chrome 90+；政务金融=IE11（如必需）全量 polyfill。
+9. **IDE skills/rules 扫描**：读 `.cursor` / `.claude` / `.agents` 下与组件/状态/表单/测试/a11y/样式相关的 rules 与 skills，落地到页面设计（解析路径后 Read，禁止 invoke skill）。
+10. **优先级**：项目约定 + IDE 落地文档 > SpecFlow 骨架 > LLM。

package/prompts/document/outline/general.md

@@ -0,0 +1,46 @@
+# Outline 生成（Pass 1）— 通用
+
+你是文档大纲设计专家。基于【全局输入摘要】与【场景 Profile 约束】，生成一份结构化的文档大纲。
+
+## 前置：工程数据源扫描 + 信息缺口询问（必须先做）
+
+生成大纲前，先按 `prompts/document/shared/grounding.md` 执行：
+1. **扫描工程数据源**：只读与场景相关的数据源（OpenAPI/proto、DDL/ORM、路由/组件树、package.json、git diff 等），提取事实（接口字段/表列/依赖版本/组件名）。
+2. **汇总信息缺口并一次性询问**：提取不到的关键信息（验收标准/非目标/权衡偏好/灰度策略等）→ 形成编号清单一次性问用户；拿到答案或"按默认判断"后再生成大纲。
+3. **事实进大纲**：能确定的契约实体（接口/表/决策）进入大纲 `entities` 注册表并冻结名称；推断内容标注来源。
+
+## 输入
+- 全局输入摘要（含各段 id 与实体候选）
+- 场景 Profile：必选章 / 候选章（含 when 条件）/ 禁止章
+- 工程数据源提取的事实摘要（接口/表/组件/依赖）
+- 用户对信息缺口的确认结果
+
+## 输出（JSON，符合 outline schema）
+```json
+{
+  "profile": "<profile-id>",
+  "chapters": [
+    {
+      "id": "<chapter-id>",
+      "title": "<章节标题>",
+      "optional": false,
+      "points": [
+        { "id": "P1", "text": "要点描述", "required": true, "kind": "mixed", "references": ["I1"], "source_segments": ["seg-design-01"] }
+      ]
+    }
+  ],
+  "entities": [
+    { "id": "I1", "frozen": "scheduler.SubmitStepResult", "standalone": false }
+  ],
+  "decisions": ["D1", "D2"]
+}
+```
+
+## 硬规则
+1. **章节约束**：必选章全含；候选章按 when 条件与输入取舍；禁止章绝不出现。
+2. **要点 kind**：引用了实体的要点 → `mixed` 或 `entity`；纯论述 → `narrative`。有 `references` 时 kind 不能是 `narrative`。
+3. **references**：要点引用的实体 id 必须在 `entities` 注册表里。
+4. **实体完整性**：注册表里每个实体必须被至少一个要点 `references` 引用（除非 `standalone: true`，仅供全局决策引用）。
+5. **source_segments**：要点尽量标注来源段 id（来自全局摘要的段 id）。
+6. **每要点引用 ≤3 个实体**。
+7. **要点数量**：每章 2-5 个要点，覆盖该章必须覆盖的维度。

package/prompts/document/review/ai-review.md

@@ -0,0 +1,57 @@
+# AI Review（Pass 3）— 通用长文档审查
+
+你是独立审查者，审查一份**分片生成**的方案文档。你与生成者是分离的——以"挑错"为目标，不替生成者辩护。
+
+## 输入
+- 大纲（outline.yaml）
+- 各章填充（chapters/*.md）
+- 契约实体（entities.json）
+- 依赖摘要与约束清单
+
+## 审查维度（R1–R14）
+- R1 跨章命名：同一实体在 § 各章/大纲/实体区用同一规范名，无「暂定/实现时」
+- R2 决策落地：大纲 decisions 每项在对应章有具体行为
+- R3 实体↔正文：大纲实体注册表每个实体有实质内容；无孤儿实体
+- R4 深度均衡：同批/同依赖链的章节深度可比，无「一章详、一章 stub」
+- R5 交叉引用：引用用稳定 id（P*/I*/T*），目标存在
+- R6 图文一致：时序/流程图与相邻正文一致
+- R7 契约完整：listed 接口/表满足字段/成功/失败示例/错误表
+- R8 枚举闭合：status/enum 集合明确闭合，无「等」
+- R9 分支闭合：提到的重试/取消/超时/回滚路径有结论或 [待 refine 澄清]
+- R10 UI↔API 对齐：uiInScope 时 §UI 字段与接口对齐；空态/加载/错误齐
+- R11 多场景一致：各 Profile 章节覆盖与该场景匹配
+- R12 stub 清除：无 TODO/待补充/仅占位
+- R13 结论一致：可实施性/就绪结论与章节深度匹配
+- R14 大纲要点覆盖：每个 kind=narrative|mixed 要点对应小节存在且有实质内容（非 stub）
+
+## 输出（JSON，符合 review-result schema）
+```json
+{
+  "schema": "specflow.document.review/v1",
+  "change": "<id>",
+  "reviewed_at": "<iso>",
+  "reviewer": "ai",
+  "verdict": "pass | fail | pass_with_waivers",
+  "summary": "发现与修复概况",
+  "findings": [
+    {
+      "id": "F1",
+      "severity": "critical | important | minor",
+      "category": "cross_part_naming",
+      "message": "I3 在 §2 与 04.5 命名不一致",
+      "target": "entity | narrative | mixed",
+      "chapter": "api-design",
+      "status": "open | fixed | waived",
+      "waiver_reason": "仅 minor 可 waived，必须写明理由"
+    }
+  ],
+  "part_hashes": [{ "id": "api-design", "sha256": "<sha256>" }]
+}
+```
+
+## 规则
+1. critical/important 必须 fixed 或升级人工；只有 minor 可 waived（须 waiver_reason）
+2. findings 每条带 target（decision 9）：entity → 改 entities.json；narrative → 改 chapters/<id>.md；mixed → 两者
+3. part_hashes 为**审查时刻**各章 sha256（由引擎在审查后计算，作为防篡改基线；引擎自身修复记入 `post_review_repairs`，不算篡改）
+4. verdict：全 fixed → pass；仅 minor waived → pass_with_waivers；任一 critical/important open → fail
+5. **闭环核对（重要）**：对 packet 中「上一轮 findings」逐条核实——若对应章节已含 `<!-- review-fix -->` 注记且问题已解决，标 `status=fixed`，**不要重复报告同一问题**；仅报告仍未解决或修复不完整的项

package/prompts/document/shared/grounding.md

@@ -0,0 +1,84 @@
+# 工程数据源提取 + 信息缺口询问（grounding 通用指引）
+
+> 本文件是**所有章节生成前**的强制前置步骤，也是"数据源提取 → 缺口询问"的质量链核心。
+> 原则：**事实从工程数据源提取，意图向用户询问，推理由你完成**。禁止用 LLM 编造工程事实。
+
+## 一、为什么必须做（质量链）
+
+```
+工程数据源（事实）→ 信息缺口询问（意图）→ 大纲（结构）→ 逐章填充（推理）→ lint/review（校验）
+```
+
+- lint/review 只能保证**格式正确**；只有"数据源提取 + 缺口询问"才能保证**内容正确**。
+- 接口字段少一个、表结构差一列、路由写错——方案文档就失去"可直接交给后端/测试执行"的价值。
+
+## 二、双层提取：引擎确定性提取 + Agent 按需补取
+
+**第一层（引擎确定性，无需 Agent 操作）**：`specflow techdoc run` 会自动扫描工程中的
+OpenAPI（`openapi.yaml`/`swagger.json` 等）、proto3（`*.proto`）、SQL DDL（`schema.sql`/`migration` 等），
+**确定性**解析出契约实体（接口 method/path/字段/错误码、表名/字段/DDL 原文），并作为
+「工程契约候选」注入大纲生成——LLM 只能原样引用这些 frozen 名，禁止改名/编造。
+
+**第二层（Agent 按需补取）**：引擎未覆盖的数据源，由你在生成前主动扫描补取（见下表），
+并按「事实 vs 推理」分级使用。
+
+## 三、工程数据源清单（第二层 · 按场景按需取用，禁止一次性全读）
+
+| 数据源 | 提取什么 | 优先场景/章节 |
+|---|---|---|
+| OpenAPI / Swagger / proto / 现有路由文件 | 接口签名、DTO 字段、错误码、http_path | api-design / compat-migration |
+| DDL / ORM schema / migration 文件 | 表结构、字段、索引、外键 | data-model / migration |
+| 组件树 / 路由表 / 状态管理 store / 样式文件 | 页面清单、组件结构、状态流 | ui-design / component-design / state-management |
+| package.json / 依赖清单 / 构建配置 | 技术栈、依赖版本、框架 | tech-selection / migration / 0to1 |
+| 现有 docs / README / conventions | 团队约定、既有术语、命名规范 | 所有章节（约定优先） |
+| 配置文件（环境/部署/CI） | 环境拆分、部署拓扑、密钥策略 | deploy / ops |
+| 测试文件 / 覆盖率报告 | 已有测试面、回归范围 | test-strategy / regression |
+| git diff / 变更文件列表 | **本次改动的真实影响面** | impact / root-cause / bugfix |
+
+> **按需加载**：只读当前章节涉及的数据源，禁止一次性读全部（token 暴涨 + 注意力稀释）。
+
+## 三、事实 vs 推理 分级（必须遵守）
+
+| 类型 | 定义 | 处理方式 |
+|---|---|---|
+| **事实（fact）** | 工程里已有的：接口字段、表列、路由、依赖版本、组件名 | **必须从工程数据源提取**，禁止 LLM 编造 |
+| **意图（intent）** | 用户/业务的目标、验收标准、非目标、权衡偏好、灰度策略 | **向用户询问**，禁止猜测 |
+| **推理（reasoning）** | 方案权衡、架构分析、迁移步骤、测试设计 | **由你基于事实+意图推导**，可自由发挥但须可溯源 |
+
+## 四、信息缺口清单（一次性询问，禁止逐章打断）
+
+**流程**：
+1. 扫描工程数据源 + 读用户输入，提取能确定的事实。
+2. 汇总**仍然缺失的关键信息** → 形成"信息缺口清单"。
+3. **一次性**向用户询问（列成编号清单），拿到答案后再生成；不要每章都问。
+
+**常见缺口（按场景）**：
+
+| 场景 | 典型必须询问的缺口 |
+|---|---|
+| 0to1 / feature | 验收标准、MVP 边界、非目标、技术栈约束、部署目标环境 |
+| bugfix | 复现环境/频率、影响用户范围、修复优先级、是否有回归基线 |
+| poc | 决策判据、候选范围、时间盒、成功标准 |
+| migration | 升级目标版本、灰度策略、回滚要求、兼容期限 |
+| approve | 审批人/签字要求、风险容忍度 |
+
+**询问格式**：
+```text
+已从工程中提取：<已确定的事实摘要，一两行>
+以下关键信息缺失，请确认（可逐条回答或直接说"按你的默认判断"）：
+1. <缺口 1>
+2. <缺口 2>
+```
+
+## 五、与现有机制的衔接
+
+- **反偷懒 lint 不替代缺口询问**：lint 只禁 TODO/含糊词；被 lint 拦住后"硬编一个"是错误路径——应先问用户。
+- **detect 场景确认复用同一模式**：场景不确定时已经会向用户确认；本节把确认范围扩展到**章节级信息缺口**。
+- **产物标记**：若用户明确表示"按默认判断"，在对应章节标注「此处为用户默认判断，非工程确认」，保证可审计。
+
+## 六、前端场景补充（资深前端视角）
+
+- 接口契约：**字段名、类型、错误码必须与后端/OpenAPI 对齐**，禁止"前后端各写一套"。
+- 组件/页面：组件名、路由路径、状态 store 名应来自工程；页面清单可与用户核对。
+- 性能：基准数值必须来自实测（或标注"待实测"），禁止编造 LCP/包体数字。
+- 依赖升级：当前版本/目标版本来自 package.json；升级理由与收益向用户确认。