@prd-improve/cli 1.2.0 → 2.0.0

package/dist/skill/prd-improve-forge/SKILL.md

@@ -59,7 +59,7 @@ description: Use when the user wants to write, refine, or structure a PRD for a
 
 **closeout 触发词集合**:"收尾" / "交付收口" / "closeout" / "上线了把 PRD 收口" / "把 X 收口" / "标记 shipped" / "close out" / "mark shipped" / "post-delivery wrap-up"
 
-#### 1.2 (白板模式)识别功能主类型
+#### 1.2a (白板模式)识别功能主类型
 
 从用户输入中提取特征,判定功能类型并决定加载哪份 checklist:
 
@@ -72,12 +72,47 @@ description: Use when the user wants to write, refine, or structure a PRD for a
 
 若识别不出或跨多类型 → 仅依赖模板自身的 [必填] 字段驱动追问,并在 open_questions 加一条"功能类型不明,可能需要定制 checklist"。
 
+#### 1.2b (白板模式)识别正交维度
+
+在 1.2a 之外,再扫描一遍「横切关注点」信号,**可命中 0-N 个维度**,与功能类型独立叠加:
+
+| 信号关键词 / 场景 | 维度 | checklist 文件 |
+|---|---|---|
+| 外部 API / 第三方 / 调另一(微)服务 / SDK / webhook / 回调 / 消息队列 / 异步任务 / 超时 / 重试 / 降级 / 兜底 / 离线 / 网络异常 | 集成接缝 | `checklists/dimensions/integration-seam.md` |
+| 计数器 / 次数 / 重试上限 / 配额 / 额度 / 剩余次数 / 状态切换 / 开关 / 生命周期 / 状态机 / 流转 / 耗尽 / 达上限 / 锁定 / 冷却 / 倒计时 | 状态机·计数器 | `checklists/dimensions/state-machine-counter.md` |
+
+- 维度与功能类型**正交**:一个 batch-import 也可能同时命中集成接缝,两类清单叠加加载。
+- 与 1.2a 不同,**维度识别不出就不挂载**(不兜底、不强加 open_question),宁缺毋滥。
+- 命中多个维度时,各自的「精选 P0」按 §1.2b 表自上而下顺序追加。
+
+#### 1.3 (白板模式)体量分流:全量 vs 轻模式
+
+判定本次是否走**轻模式**(只问核心段,跳过结构性模块):
+
+**轻模式判据**(任两项命中即建议,由用户一票确认/否决):
+- 预计验收标准 ≤ 8 条
+- 单页交互或无 UI
+- 不引入新实体(纯行为 / 展示 / 文案改动)
+- 用户明示「小功能 / 快速过 / 别整太重」
+
+命中 → 向用户确认:「这个 feature 体量不大,建议走轻模式:只问核心边界(目标 / 范围 / 验收 / 待定问题),跳过实体、状态机、业务规则等结构段,需要时随时补。可以吗?」
+
+**轻模式执行差异**(全量模式不变):
+- **第 3 步追问**:只走 P0,1-2 轮、≤ 10 题封顶;checklist 仍加载但只取 P0 行
+  - 命中的正交维度仍贡献其「精选 P0」(轻模式最不该跳的高 ROI 边界),但纳入 ≤10 题总封顶统一计数(精选 P0 优先于 feature-type 的非 Top 行)
+- **第 4 步填充**:核心段 = `meta / background_and_goals / users_and_roles(可单条)/ in_scope / out_of_scope / acceptance_criteria / open_questions`;其余 7 模块(`entities / main_flow / state_permissions / business_rules / scenarios / edge_cases / ui_interaction`)写**显式空数组** `[]`,`data_and_api` 四子数组留空。在第一个空模块上方加一行注释 `# lite 模式略过,需要时可后补`(只加一次,不逐模块重复)
+- **命中维度的硬约束落点**:第 3 步精选 P0 若问出硬约束(计数器上限 / 接缝失败行为 / 超时阈值等),落到 `acceptance_criteria`(可验收条款)或 `open_questions`(未定项),**不因 business_rules / edge_cases / data_and_api 在轻模式为空而丢弃**;若注入后 AC 将 > 8 条(即下方「中途升级」同一阈值)→ 转全量补 business_rules / edge_cases
+- **收尾知会**:明示「轻模式产物,prd validate 可过(out_of_scope 为空仅 warning);后续 feature 长大可随时全量补段」
+
+**中途升级**:问询中发现判据失效(冒出新实体 / 验收膨胀到 >8)→ 明示转全量,补问对应结构段。轻模式与 1.2a 末「类型不明」分支正交,可叠加。
+
 ### 第 2 步:强制加载资源
 
 **必须读完以下三份文件再开始追问:**
 
 1. `templates/prd.yaml` — 骨架结构、字段定义、标记约定
 2. `checklists/<type>.md` — 该类型功能的边界追问清单
+   - 命中的每个正交维度:额外加载 `checklists/dimensions/<dim>.md`(相对路径同 feature-type 清单)
 3. `examples/import-history-prds.prd.yaml` — 金标准范例(仅参考结构,**不照抄具体值**)
 
 **资源定位协议(跨平台路径自适应,按顺序尝试):**
@@ -119,10 +154,13 @@ description: Use when the user wants to write, refine, or structure a PRD for a
 - 有选项的题给选项(`A / B / C / D / 其他`),不要开放题
 - 每轮结束做"已确认的关键决策"摘要,让用户确认或修正
 - 用户说"够了"或"直接生成"即停止,未答问题进 `open_questions`
+- **正交维度的精选 P0 注入**:dimension 清单挂载时,**只把它的「精选 P0」(≤3 题)注入当轮追问**;其余 P0/P1/P2 降为「可选补问」——仅当用户对该维度深入、或精选 P0 回答暴露更多边界时才展开。feature-type 清单仍走全量 P0。
+- **多维度重叠去重**:多维度命中时各取精选 P0 顺序追加;若与 feature-type 的 P0 语义重叠,保留 feature-type 版本,维度版跳过避免重复问。
+- **AC priority 按测试赋值**:收集到验收标准时,按规则 9 的 launch-blocker 测试逐条定 must / should / could,**不要默认 must**;可顺带问「这条不达标会不会拦住上线?」帮 PM 自己分级。
 
 **追问数量与优先级**(优先级冲突时按以下顺序让步):
 
-1. **P0 必须问完**(checklist 中所有 P0,通常 5-10 题,跨 1-2 轮) — 不可裁剪,P0 未答完不进 P1
+1. **P0 必须问完**(feature-type checklist 中所有 P0,通常 5-10 题,跨 1-2 轮) — 不可裁剪,P0 未答完不进 P1;**正交维度只注入其精选 P0(≤3),见上「正交维度的精选 P0 注入」,不适用本条**
 2. **P1 按预算挑选**(剩余轮次内挑 6-10 题最相关的) — 用户表现配合就多问,显疲态就跳过
 3. **P2 仅当用户积极时问**(2-3 题点缀)— 用户说"够了"立即停止,P2 未答的全进 `open_questions` 标 `non_blocking`
 
@@ -141,6 +179,7 @@ description: Use when the user wants to write, refine, or structure a PRD for a
 - **可删**:完成填写后的 `[必填] / [选填] / [PM 填] / [CLI 管] / [机器读]` 任务标记注释(这些是给写作者看的脚手架,定稿后无信息量)
 - 长文本用 YAML block style `|`(如 `background`、大段 `rule`)
 - ID 前缀严格遵守:EN / S / R / SC / E / UI / AC / Q / DC / API / PC / SEC
+- **填完 `acceptance_criteria` 做规则 9 的 calibration 复盘**:自算 must / should / could 分布,must 占压倒比例时逐条用 launch-blocker 测试复核并向 PM 提降级建议(不擅改)。
 
 **具体决策值必须来自用户**。用户没说的,放进 `open_questions`,不要代为决策。
 
@@ -162,9 +201,10 @@ description: Use when the user wants to write, refine, or structure a PRD for a
 生成完毕后告诉用户:
 
 1. 文件路径
-2. 模块规模(各段填了多少条)
+2. 模块规模(各段填了多少条);**AC priority 分布(N must / M should / K could)**——若 must 占压倒比例且未复盘,提示 PM 按 launch-blocker 测试(规则 9)再过一遍
 3. blocking 级 open_questions 的数量和清单
 4. 建议下一步:回答 blocking → `prd validate` → `prd freeze`
+5. 若下游走 superpowers 执行链:freeze 后用 `prd export <slug> --out docs/specs/YYYY-MM-DD-<slug>-design.md` 生成 spec 骨架(需求段自动填好,只需续写方案评估 / 架构 / 验证清单等工程段),续写完进 writing-plans;之后需求若变更,先改 prd.yaml 再 `prd export <slug> --out <同路径> --force` 重导(会覆盖,注意保留人工续写段)
 
 ### 第 7 步:refresh 工作流
 
@@ -274,9 +314,11 @@ AI 在 7.4 完成后,**必须输出**:
 3. 当前会话上下文 — closeout 紧跟实施时
 4. 全部缺位 → 退化为纯逐条问询:AI 只当记录员,逐条念 Q 问用户
 起草不出的标"未找到决议"。as-built 核对(8.3)同此分级。
+- **跨 feature 核查**:检查该 Q 是否已被**后续 feature** 解决(线索:同仓后续 PRD 的 resolution/正文、dev-log 中后续批次记录)——单 feature 证据流程不保证发现,批量收口时由编排者在各 agent prompt 里显式喂线索
 
 #### 8.2 PM 逐条拍板(复用 7.5 范式)
 每条 Q:**采纳草稿 / 改写 / 显式 carry-over(填 deferred_to)**。
+拍板后逐条执行 `prd resolve <slug> <qid> --text "<决议>"`(已决)或 `prd resolve <slug> <qid> --defer "<去向>"`(carry-over)。CLI 自动写 resolved_at、保注释、长文本块标量;改判已决的加 `--force`。**不要手编 yaml**(CLI 不可用时才降级行级编辑,注意块标量缩进与防重跑)。
 - 无论哪种,拍板即写 `resolved_at: "<今天 YYYY-MM-DD>"`(CLI 门禁的收口痕迹要求)
 - 判定口径:resolution 非空 ⇒ 已决(起草期残留的 deferred_to 占位可保留,CLI 按此口径忽略);resolution 空 + deferred_to 非空 ⇒ carry-over
 - carry-over 必须是 PM 显式决定,不可拿起草期 deferred_to 占位充数
@@ -305,9 +347,13 @@ working/CHANGELOG.md 不存在 → 先创建(`# Changelog` + `## [Unreleased]`
 #### 8.6 refresh 联动(shipped 之后再迭代)
 refresh 一个已 shipped 的 feature 时:working 的 `lifecycle.status` 回 `"draft"`、删除 `shipped_at` / `landed_commit` 两行(上一轮交付事实由 frozen 链 + manifest 承载,不丢)。这是 `prd freeze` shipped 守卫指引的路;CLI 的 `prd refresh` 命令是索引报告,不修改 yaml。
 
+#### 8.7 批量收口变体(N feature 一轮)
+
+N 个 feature 同时收口时:每 feature 派一个 8.1 证据提取 agent 并行起草(prompt 附跨 feature 线索)→ 全表一轮拍板(按 feature 分组列决议草稿带证据指针,用户一次过)→ 逐 feature 执行 8.3-8.5。实测 9 feature 30 条决议 1 轮交互即可完成。
+
 ---
 
-## 硬规则(8 条,违反即为 Skill 执行错误)
+## 硬规则(9 条,违反即为 Skill 执行错误)
 
 ### 规则 1:不照抄范例的具体占位值
 
@@ -500,6 +546,33 @@ refresh 模式下,**因 PRD 删除 / 修改 + refers_to 引用关系**而产生
 
 **与 7.5「批量接受」的边界**:批量接受只限**同一类同一字段**的变化(如"批量接受 12 处自动考核相关字段的删除"),**不跨字段联动**;refers_to 反向图中的"被引用字段"必须单独逐条决策。
 
+### 规则 9:AC priority 分级纪律(防 must 通胀)
+
+每条验收标准的 `priority` 很容易被习惯性填成 `must`,导致 **must 通胀**——当几乎所有 AC 都是 must,MoSCoW 优先级信号失效,`prd context` 的 Must Build 清单按 priority 过滤等于没过滤,排期 / 砍范围时无从取舍。
+
+**launch-blocker 测试(逐条赋值的判定锚点):**
+
+- `must` = 不达标就**不能发版 / 要回滚**(launch-blocker)
+- `should` = **能发版**,但是已知且可接受的缺口
+- `could` = 锦上添花,可以悄悄砍掉
+
+**坏例子**(真实 dogfood):
+```
+81 AC = 68 must / 13 should / 0 could(84% must)
+→ 几乎全是 must,排期取舍时无从下手,MoSCoW 等于没分级
+```
+
+**好例子**:逐条过 launch-blocker 测试,真正阻塞上线的才留 must,其余降 should / could(范例 `examples/import-history-prds.prd.yaml` 的 6 must / 3 should / 1 could 即此测试的产物,不是凑出来的配比)。
+
+**calibration 复盘(草拟完全部 AC 后做一次):**
+1. 自算 must / should / could 三数。
+2. 当 must 占压倒比例(可参照范例 ~60% 作软触发线,**非门槛**)时,逐条用 launch-blocker 测试复核 must 项,把「失败也照样能发版」的挑出来。
+3. 向 PM 提降级建议,**由 PM 拍板,AI 不擅自改 priority**(沿用硬规则总则:具体决策值来自用户)。
+
+**不设硬配额**:AC 条数 ≠ 工作量,数字配额可被「拆 1 条 must 成 2 条 should」规避;**launch-blocker 测试本身才是锚点**,~60% 只是触发复盘的软参考,不作 pass/fail 门槛。
+
+**轴区分**:must / should / could(这条该不该**发**)与第 3 步追问的 P0 / P1 / P2(这个问题该不该**问**)是正交两轴——一条 P0 问题(必须问)的答案,既可能落成 must AC 也可能落成 should AC。别把「P0 问题」机械等同「must AC」(这正是通胀的隐性推手)。
+
 ---
 
 ## 未回答问题的去向
@@ -641,13 +714,22 @@ refresh 模式下,**因 PRD 删除 / 修改 + refers_to 引用关系**而产生
 | **ChatGPT / Custom GPT** | SKILL.md 作为 system prompt;三个子目录上传为 knowledge |
 | **Codex / Antigravity** | SKILL.md 内容放 system prompt / rules;子目录放项目根 |
 
-**核心工作流不变**:识别模式 + 类型 → 加载资源 → (长材料先摘要) → 分轮追问 / refresh diff → 严格遵守 8 条硬规则 → 输出到 `.prd/features/<slug>/working/prd.yaml`(白板)或就地更新 + CHANGELOG append(refresh),或决议回填 + `prd closeout`(closeout)。
+**核心工作流不变**:识别模式 + 类型 → 加载资源 → (长材料先摘要) → 分轮追问 / refresh diff → 严格遵守 9 条硬规则 → 输出到 `.prd/features/<slug>/working/prd.yaml`(白板)或就地更新 + CHANGELOG append(refresh),或决议回填 + `prd closeout`(closeout)。
 
 ---
 
 ## 版本与维护
 
-**当前版本:** SKILL.md v0.3 · 对应 schema_version v0.3(closeout mode added 2026-06-12)
+**当前版本:** SKILL.md v0.11 · 对应 schema_version v0.3(resolve command + batch closeout 2026-06-12 + v0.6 正交维度层 + v0.7 priority 分级纪律 + v0.8 source_materials 可移植性 + v0.9 data_and_api.applies_to 注释准确化 + v0.10 轻模式×维度落点指引 + v0.11 performance applies_to 校验对齐(EN-* 强制,模板注释同步))
+
+**变更历史:**
+- v0.10 — 轻模式 × 命中维度的硬约束落点指引:精选 P0 问出的硬约束落 acceptance_criteria / open_questions(不因结构段轻模式为空而丢弃),撑不进 AC 即触发中途升级;两份 dimension 清单挂载协议同步补轻模式落点。修协议冲突
+- v0.9 — data_and_api.applies_to 注释逐行准确化:data/api/security 明确 EN-* only + 校验失败提示;performance 明确不做引用校验
+- v0.8 — source_materials.url 注释提示可移植路径(仓库相对 / PRD 章节锚点,避免本机绝对路径)+ 范例演示;推广 v1.21 as_built.evidence 同款提示
+- v0.7 — 加规则 9(AC priority 分级纪律):launch-blocker 测试 + calibration 复盘,防 must 通胀;template priority 注释收紧
+- v0.6 — 加正交维度层(1.2b 维度识别 + integration-seam/state-machine-counter 两份 dimension + 精选 P0 注入协议)
+- v0.5 — 加轻模式体量分流(1.3) + 第 6 步 superpowers 执行链 handoff(prd export)
+- v0.4 — resolve command + batch closeout 2026-06-12
 
 **支持的 checklist 类型:**
 - [x] `batch-import` (批量导入)
@@ -655,9 +737,14 @@ refresh 模式下,**因 PRD 删除 / 修改 + refers_to 引用关系**而产生
 - [ ] `permission` (权限,规划中)
 - [ ] `notification` (通知,规划中)
 
+**支持的 dimension 维度(正交,与上面类型叠加):**
+- [x] `integration-seam`(集成接缝)
+- [x] `state-machine-counter`(状态机·计数器)
+
 **何时需要更新本 Skill:**
 
-1. **新功能类型出现** → 添加新 checklist 文件,本 SKILL.md 第 1 步的识别表加一行
+1. **新功能类型出现** → 添加新 checklist 文件,本 SKILL.md §1.2a/§1.2b 的识别表加一行
+   - **先判它是「功能类型」还是「正交维度」**:功能类型 = 与其他类型**互斥**,答「这个 feature *是* 什么」(批量导入、审批流)→ 放 `checklists/` 根 + §1.2a 表;正交维度 = 可与任意类型**叠加**,答「这个 feature *涉及* 什么横切关注点」(有外部依赖、有计数器)→ 放 `checklists/dimensions/` + §1.2b 表 + 必带「精选 P0」(≤3)。
 2. **模板 schema 升级** → 同步升级 schema_version,检查所有 checklist 引用的字段是否还存在
 3. **反复踩同一个坑** → 在"硬规则"段新增一条并给坏例子 / 好例子
 4. **触发不准** → 修改 frontmatter 的 description,连续观察 2 周

package/dist/skill/prd-improve-forge/checklists/batch-import.md

@@ -147,6 +147,7 @@
 
 → 答案落到 `acceptance_criteria` / `data_and_api.security_constraints`
 
+- 判定每条 AC 的 priority 时套用 SKILL.md 规则 9 的 launch-blocker 测试(不达标就不能发版=must),别默认全填 must。
 - **[P0]** 怎么判断一次任务"成功"?需要达到多少成功率阈值?
 - **[P1]** 开发需要哪些日志 / 指标来排查问题?
 - **[P1]** 测试需要哪些固定数据样例来做回归?

package/dist/skill/prd-improve-forge/checklists/dimensions/integration-seam.md

@@ -0,0 +1,131 @@
+# 集成接缝 · 边界追问维度清单(正交维度)
+
+> 本清单是「正交维度」,与功能类型清单(如 batch-import)叠加使用——一个功能可同时是某类型 + 命中本维度。
+> 由 PRD Skill 在检测到「外部依赖 / 网络接缝」信号时自动加载。
+> **挂载协议:只把「精选 P0(≤3 条,单条可含 2-3 个子问)」注入当轮追问;其余 P0/P1/P2 为可选补问。**
+> 所有答案最终落到 prd.yaml 对应模块,Skill 不要凭空生成答案。
+> **轻模式例外**:精选 P0 的硬约束落点改为 `acceptance_criteria` / `open_questions`(对应结构段在轻模式为空)。
+> 追问执行协议(每轮 ≤3-5 题、P0 先、有选项给选项、答不上转 open_questions)沿用 batch-import.md 的「使用原则」段;本维度额外只注入精选 P0。
+
+---
+
+## 触发加载条件
+
+当功能描述中出现以下特征之一,Skill 应加载本维度清单:
+
+- 关键词:外部 API / 第三方 / 调另一个(微)服务 / SDK / webhook / 回调 / 消息队列 / MQ / 异步任务 / 超时 / 重试 / 降级 / 兜底 / 离线 / 网络异常 / 不可达。
+- 功能依赖一个**不由本模块掌控的运行时**(支付网关、短信、AI 推理、对象存储、地图、推送、登录第三方)。
+- 跨进程 / 跨服务 / 跨网络的读写。
+- 有「在线/离线」「连通/不可达」状态切换。
+- 典型功能:接入支付、AI 能力调用(带超时)、第三方登录、消息推送、文件传对象存储、跨服务数据同步、离线表单提交。
+
+---
+
+## Q 清单(按 prd.yaml 模块归类)
+
+### 1. 接缝清单与契约
+
+→ `entities` / `data_and_api.api_constraints`
+
+- **[P0]** 本功能依赖哪些外部接缝?逐个列出(服务名 / 用途 / 同步 or 异步)。
+- **[P0]** 每个接缝的「成功响应」长什么样?字段契约是否固定?
+- **[P1]** 契约由谁拥有 / 可能怎么变?是否版本化?
+- **[P2]** 是否有 mock / sandbox 环境供测试?
+
+### 2. 失败模式枚举
+
+→ `edge_cases` / `scenarios`
+
+- **[P0]** 每个接缝可能怎么失败?(超时 / 5xx / 4xx / 限流 429 / 部分成功 / 返回体畸形或字段缺失 / 连接失败)
+- **[P0]** 每种失败本功能怎么表现?(报错 / 重试 / 降级 / 静默 / 入队补偿)
+- **[P1]** 「返回 200 但 body 语义是失败」怎么识别?
+- **[P1]** 区分「可恢复 / 不可恢复」失败的依据?
+
+### 3. 超时·重试·幂等
+
+→ `business_rules` / `data_and_api.performance_constraints`
+
+- **[P0]** 每个接缝的超时阈值?(秒)
+- **[P0]** 失败是否重试?重试次数 / 退避策略?(与状态机·计数器维度的计数器联动)
+- **[P0]** 重试 / 重复提交是否幂等?幂等键是什么?
+- **[P1]** 重试期间用户看到什么?
+
+### 4. 降级与兜底
+
+→ `business_rules` / `scenarios`
+
+- **[P0]** 接缝不可用时本功能能否降级运行?降级形态?(只读 / 缓存 / 本地暂存 / 排队后补 / 直接拒绝)
+- **[P1]** 降级态如何恢复?自动重连还是用户手动?
+- **[P1]** 降级期间产生的数据如何与恢复后对账?
+
+### 5. 跨状态组合枚举
+
+→ `edge_cases` / `ui_interaction`
+
+- **[P0]** 把「连通性状态 × 业务错误类型」做成组合表,逐格定义展示与行为——防文案与按钮/行为打架、防某组合是死代码(反面教材:离线 × 识别失败 → 标题「识别失败」但只有「保存本地」按钮)。
+- **[P1]** 每个组合的文案 / 可用操作 / 默认动作是否自洽?
+- **[P2]** 有没有「理论上不可能但代码里能进」的组合?(死分支审计)
+
+### 6. 接缝处鉴权与安全
+
+→ `data_and_api.security_constraints`
+
+- **[P0]** 接缝鉴权方式?token / 密钥怎么存、谁能访问?
+- **[P0]** token / 凭证过期时本功能怎么处理?(自动刷新 / 报错 / 重新授权)
+- **[P1]** 接缝传输的数据是否含敏感字段?加密 / 脱敏?
+- **[P2]** 第三方回调如何验签防伪造?
+
+### 7. 可观测与排查
+
+→ `acceptance_criteria` / `data_and_api.performance_constraints`
+
+- **[P0]** 接缝调用失败时,排查需要哪些日志 / trace?(请求 ID / 接缝名 / 耗时 / 错误码)
+- **[P1]** 接缝健康度有无监控 / 报警?(失败率 / P99 延迟阈值)
+- **[P2]** 是否需要熔断 / 限流保护本功能不被拖垮?
+
+---
+
+## 精选 P0(Top 3 必问)
+
+挂载时只把这 3 条注入当轮追问;其余 P0 / P1 / P2 为可选补问。
+
+1. **逐接缝答**:每个外部接缝失败时(超时 / 报错 / 不可达),本功能怎么表现——报错、重试、还是降级兜底?(别笼统说「会处理」)
+2. 超时阈值、重试次数与退避、幂等键——三件各定多少?
+3. 「连通性 × 错误类型」组合表——逐格定义展示与行为,排查有没有文案-行为打架或死分支。
+
+---
+
+## 常见答案池
+
+| 主题 | 常见选项 |
+|---|---|
+| 失败处理 | 报错中断 / 自动重试 / 降级兜底 / 本地暂存补偿 / 静默忽略 |
+| 降级形态 | 只读缓存 / 本地暂存排队 / 切手动 / 直接拒绝 + 提示 |
+| 重试策略 | 不重试 / 固定次数 / 指数退避 / 用户手动重试 |
+| 幂等键 | 业务唯一键 / 客户端生成 UUID / 服务端去重窗口 / 不保证 |
+| 凭证过期 | 自动刷新 / 报错重新授权 / 静默失败 |
+
+---
+
+## Top 5 最易被漏掉的问题
+
+本维度按挂载协议默认只注入「精选 P0(≤3)」;**一旦本维度被追问深入**(精选 P0 暴露出更多边界),这 5 个是最不该漏的补问点。届时用户答不上来转入 `open_questions`(精选 P0 相关项 `severity: blocking`,其余 `non_blocking`):
+
+1. **「返回 200 但语义失败」**——只判 HTTP 码会漏。
+2. **跨状态组合的死分支 / 文案打架**——离线 × 错误态这类(真实反面教材)。
+3. **幂等**——重试 / 重复点击造成重复副作用。
+4. **凭证过期路径**——happy path 之外几乎总被忘。
+5. **降级态恢复后的数据对账**——暂存数据怎么回流。
+
+---
+
+## 本清单的演化约定
+
+发现新场景或遗漏时:
+
+1. 先写入本文件对应分类,并标 P0 / P1 / P2
+2. 若有新选项,同步更新「常见答案池」
+3. 如果某 P1 问题频繁被用户答不上来,升级为 P0
+4. 本清单是「正交维度」——如果发现某类集成场景(如「消息队列专项」)与通用接缝差异过大,拆出独立维度清单(如 `checklists/dimensions/message-queue.md`)
+
+当前版本:v0.1 · dimension(正交维度)· 与 templates/prd.yaml (schema_version v0.3) 对齐

package/dist/skill/prd-improve-forge/checklists/dimensions/state-machine-counter.md

@@ -0,0 +1,130 @@
+# 状态机 · 计数器 · 边界追问维度清单(正交维度)
+
+> 本清单是「正交维度」,与功能类型清单叠加使用。
+> 由 PRD Skill 在检测到「计数器 / 上限 / 状态机 / 生命周期」信号时自动加载。
+> **挂载协议:只把「精选 P0(≤3 条,单条可含 2-3 个子问)」注入当轮追问;其余 P0/P1/P2 为可选补问。**
+> 所有答案最终落到 prd.yaml 对应模块,Skill 不要凭空生成答案。
+> **轻模式例外**:精选 P0 的硬约束落点改为 `acceptance_criteria` / `open_questions`(对应结构段在轻模式为空)。
+> 追问执行协议(每轮 ≤3-5 题、P0 先、有选项给选项、答不上转 open_questions)沿用 batch-import.md 的「使用原则」段;本维度额外只注入精选 P0。
+
+---
+
+## 触发加载条件
+
+当功能描述中出现以下特征之一,Skill 应加载本维度清单:
+
+- 关键词:计数器 / 次数 / 重试上限 / 配额 / 额度 / 限额 / 剩余次数 / 状态切换 / 开关 / 生命周期 / 状态机 / 流转 / 耗尽 / 达上限 / 锁定 / 冻结 / 冷却 / 倒计时。
+- 功能里有「计数到 N 触发某行为」(N 次失败锁定、剩余 X 次、限免 3 次)。
+- 实体有多个状态且状态间有合法 / 非法转移。
+- 有需要 reset 的累加值。
+- 典型功能:登录失败 N 次锁定、重试上限耗尽切降级(ai-fallback 反面教材)、限免次数、审批状态流转、订单生命周期、倒计时 / 冷却、开关 toggle。
+
+---
+
+## Q 清单(按 prd.yaml 模块归类)
+
+### 1. 计数器清单与归零
+
+→ `entities` / `business_rules`
+
+- **[P0]** 列出所有计数器 / 累加值:名字 / 初值 / 上限(MAX) / 单位。
+- **[P0]** **每个计数器在每个事件上精确怎么变**——画 transition×mutation 表(事件 → +1 / -1 / reset / 不变)。别留给实现者发挥(反面教材:onRetry 该 +1、reset 还是不动,两实现者各错一种)。
+- **[P0]** 每个计数器的 reset 触发点是什么?(成功 / 切换模式 / 跨会话 / 定时 TTL / 永不)
+- **[P1]** 计数器在哪一层持久化?(内存 / 本地存储 / 服务端)
+
+### 2. 上限与耗尽行为
+
+→ `business_rules` / `scenarios` / `edge_cases`
+
+- **[P0]** 达上限 / 耗尽时发生什么?(锁定 / 降级 / 拒绝 / 切手动 / 仅提示)
+- **[P0]** 耗尽是「>= MAX」还是「> MAX」触发?(差一错防线)
+- **[P1]** 耗尽后如何解除?(冷却等待 / 管理员解锁 / 自动恢复 / 永久)
+- **[P1]** 接近上限时是否提前提示?(还剩 1 次)
+
+### 3. 边界值
+
+→ `edge_cases`
+
+- **[P0]** 边界值行为:计数 = 0、= MAX-1、= MAX、= MAX+1 分别怎样?
+- **[P1]** 计数能否为负 / 溢出?防御措施?
+- **[P2]** 上限 N 是否可配?改 N 后存量计数怎么算?
+
+### 4. 状态机转移
+
+→ `entities.lifecycle_states` / `state_permissions` / `main_flow`
+
+- **[P0]** 列出所有状态 + 合法转移表(from → to,触发事件)。
+- **[P0]** 非法转移如何处理?(报错 / 静默忽略 / 断言不可能发生)
+- **[P1]** 每个状态下哪些操作可用?(对齐 state_permissions)
+- **[P1]** 是否有终态(不可再转出)?
+
+### 5. 并发与一致性
+
+→ `business_rules` / `edge_cases` / `data_and_api.data_constraints`
+
+- **[P0]** 计数器 / 状态在并发下是否原子?(同时两次失败会不会丢计数)
+- **[P1]** 多端 / 多标签页下计数与状态如何同步?
+- **[P1]** 计数与状态是否可能不一致?(计数到 MAX 但状态没锁)如何避免?
+
+### 6. 持久化与恢复
+
+→ `edge_cases` / `scenarios`
+
+- **[P0]** 刷新 / 重启 / 重新登录后,计数与状态保留还是重置?
+- **[P1]** 跨设备是否共享?(服务端计数)
+- **[P2]** 计数是否有过期 / TTL?(失败计数 24h 后清零)
+
+### 7. 验收与可观测
+
+→ `acceptance_criteria`
+
+- **[P0]** 「连续 N 次失败触发锁定」这类规则,验收用例怎么写?(必须含恰好 N、N-1、N+1 三个点)
+- **[P1]** 排查需要哪些日志?(每次计数变更的事件 + 前后值)
+
+---
+
+## 精选 P0(Top 3 必问)
+
+挂载时只把这 3 条注入当轮追问;其余 P0 / P1 / P2 为可选补问。
+
+1. **transition×mutation 表(计数器表 + 状态转移表,分开画)**:① 计数器表——每个计数器在每个事件(成功 / 失败 / 重试 / 取消 / 超时…)上 +1 / -1 / reset / 不变;② 状态转移表——每个状态 × 事件 → 目标状态(from × event → to)。两张表都写死,别留给实现者(反面教材:ai-fallback onRetry 两实现者各错一种)。
+2. 达上限 / 耗尽 / 非法转移时的精确行为 + 触发用 `>=` 还是 `>`(差一错)。
+3. 刷新 / 重启 / 并发下,计数与状态是否保留且一致?
+
+---
+
+## 常见答案池
+
+| 主题 | 常见选项 |
+|---|---|
+| 事件对计数器 | +1 / -1 / reset 归零 / 不变 |
+| reset 触发点 | 成功时 / 切换模式时 / 跨会话 / 定时 TTL / 永不 |
+| 耗尽行为 | 锁定 / 降级 / 拒绝 / 切手动 / 仅提示 |
+| 耗尽解除 | 冷却等待 / 管理员解锁 / 自动恢复 / 永久 |
+| 计数持久化 | 仅内存 / 本地存储 / 服务端 |
+| 非法转移 | 报错 / 静默忽略 / 断言不可能 |
+
+---
+
+## Top 5 最易被漏掉的问题
+
+本维度按挂载协议默认只注入「精选 P0(≤3)」;**一旦本维度被追问深入**(精选 P0 暴露出更多边界),这 5 个是最不该漏的补问点。届时用户答不上来转入 `open_questions`(精选 P0 相关项 `severity: blocking`,其余 `non_blocking`):
+
+1. **重试操作该不该动计数器**——最经典(反面教材本体)。
+2. **`>=` vs `>` 的差一错**——第 N 次还是第 N+1 次触发。
+3. **并发下计数丢失 / 计数与状态不一致**。
+4. **刷新 / 重启后计数是否保留**——决定持久化层。
+5. **reset 的全部触发点**——常只想到「成功」漏了「切换 / 超时」。
+
+---
+
+## 本清单的演化约定
+
+发现新场景或遗漏时:
+
+1. 先写入本文件对应分类,并标 P0 / P1 / P2
+2. 若有新选项,同步更新「常见答案池」
+3. 如果某 P1 问题频繁被用户答不上来,升级为 P0
+4. 本清单是「正交维度」——如果发现某类状态机场景(如「审批流专项」)与通用状态机差异过大,拆出独立维度清单(如 `checklists/dimensions/approval-flow.md`)
+
+当前版本:v0.1 · dimension(正交维度)· 与 templates/prd.yaml (schema_version v0.3) 对齐

package/dist/skill/prd-improve-forge/examples/import-history-prds.prd.yaml

@@ -49,6 +49,11 @@ meta:
       url: ""
       excerpt: "聊到了格式识别、重复 slug 冲突、失败回报等关键边界问题"
       captured_at: "2026-04-18"
+    - type: "old_prd"
+      title: "旧版批量上传 PRD（迁移前）"
+      url: "docs/prd/legacy-import-v1.md#批量上传"
+      excerpt: "旧 PRD 已定义批量上传的基本流程，本期在其上补全失败回报与重复 slug 处理"
+      captured_at: "2026-04-10"
 
   lifecycle:
     version: "working"
@@ -474,7 +479,7 @@ acceptance_criteria:
     priority: "could"
     verification_method: "手工用例"
 
-
+# shipped 后：各题 resolution 为现状权威（正文条款保留设计时态，阅读以 resolution 优先）。
 open_questions:
   - id: "Q-1"                 # -- 待确认问题
     question: "AI 解析用哪个模型?自托管还是调外部 API?预算限制是什么?"

package/dist/skill/prd-improve-forge/templates/prd.yaml

@@ -63,10 +63,10 @@ meta:
   owner: ""                   # [必填][PM 填] 该功能的 PM 负责人（姓名或邮箱）
   tags: []                    # [选填][PM 填][机器读] 标签列表，用于 CLI 搜索过滤，如 ["import", "migration"]
   created_at: ""              # [必填][PM 填] PRD 首次建立日期，格式 YYYY-MM-DD
-  source_materials:           # [选填][PM 填] 原始材料列表，对齐后端 source_material 模型；填写时每个条目都是一个对象
+  source_materials:           # [选填][PM 填] 原始材料列表，对齐后端 source_material 模型；每个条目一个对象。url 优先填 URL / 仓库相对路径 / PRD 章节锚点，避免本机绝对路径（/Users/…、C:\…）——换机 / 共享即失效
     - type: ""                #   来源类型：meeting_notes（会议纪要）/ chat（聊天摘录）/ old_prd（旧 PRD）/ ai_dialog（AI 对话）/ wiki / other
       title: ""               #   材料标题
-      url: ""                 #   URL 或本地路径（可留空）
+      url: ""                 #   URL / 仓库相对路径 / PRD 章节锚点（可留空）
       excerpt: ""             #   关键摘录文本（可留空）
       captured_at: ""         #   采集日期 YYYY-MM-DD（可留空）
 
@@ -245,19 +245,19 @@ data_and_api:
   data_constraints:           # [选填][PM 填] 数据层约束列表
     - id: "DC-1"              # -- 数据约束。编号 DC-1 / DC-2 / ...
       text: ""                #   约束内容，如"单文件 ≤ 10MB"、"title 长度 1-200"
-      applies_to: []          # -- 作用对象。作用于 EN-*（实体）的 ID 或字段名
+      applies_to: []          # -- 作用对象。必须是已声明 EN-* 实体 ID;自由文本(字段名)/S-/R- 均校验失败,细节写进 text
   api_constraints:            # [选填][PM 填] 接口层约束列表
     - id: "API-1"             # -- 接口约束。编号 API-1 / API-2 / ...
       text: ""                #   约束内容：幂等性、超时时间、返回格式、错误码规约
-      applies_to: []          # -- 作用对象。作用于 EN-*（实体）的 ID 或接口名
+      applies_to: []          # -- 作用对象。必须是已声明 EN-* 实体 ID;自由文本(接口名)/S-/R- 均校验失败,细节写进 text
   performance_constraints:    # [选填][PM 填] 性能期望列表
     - id: "PC-1"              # -- 性能约束。编号 PC-1 / PC-2 / ...
       text: ""                #   约束内容，如"列表首屏 ≤ 2s"、"关键操作响应 ≤ 500ms"
-      applies_to: []          # -- 作用对象。作用于 EN-*（实体）的 ID 或场景名
+      applies_to: []          # -- 作用对象。EN-* 实体 ID(校验:必须指向已定义实体,同 data/api/security)
   security_constraints:       # [选填][PM 填] 权限、审计、脱敏、合规、防滥用等
     - id: "SEC-1"             # -- 安全约束。编号 SEC-1 / SEC-2 / ...
       text: ""                #   约束内容
-      applies_to: []          # -- 作用对象。作用于 EN-*（实体）的 ID 或字段名
+      applies_to: []          # -- 作用对象。必须是已声明 EN-* 实体 ID;自由文本(字段名)/S-/R- 均校验失败,细节写进 text
 
 
 # =============================================================================
@@ -269,7 +269,7 @@ data_and_api:
 acceptance_criteria:
   - id: "AC-1"                # -- 验收标准。[必填][PM 填][机器读] 编号 AC-1 / AC-2 / ... 递增
     criterion: ""             # [必填][PM 填] 验收条件，陈述性、可判断通过 / 不通过
-    priority: "must"          # [必填][PM 填][机器读] must（必须实现，未通过不能上线）/ should（建议实现）/ could（锦上添花）。context.md 的 Must Build 清单按此过滤
+    priority: "must"          # [必填][PM 填][机器读] launch-blocker 测试:不达标就不能发版/要回滚=must;能发版但有已知缺口=should;锦上添花可砍=could。别默认全填 must（见 SKILL.md 规则 9）。context.md 的 Must Build 清单按此过滤
     verification_method: ""   # [必填][PM 填] 如何验证：手工用例 / 演示 / 自动化测试 / 日志核查
     refers_to: []             # -- 引用对象。[选填][PM 填][机器读] 支持 S-*（范围项）/ SC-*（场景）/ R-*（业务规则）/ E-*（异常）/ DC-*（数据约束）/ PC-*（性能约束）/ SEC-*（安全约束）的 ID 列表
 
@@ -279,6 +279,7 @@ acceptance_criteria:
 # -----------------------------------------------------------------------------
 # 用途：悬而未决的问题清单。
 # 冻结前所有 blocking 级问题必须被回答，否则 CLI 校验会失败。
+# shipped 后：各题 resolution 为现状权威（正文条款保留设计时态，阅读以 resolution 优先）。
 # =============================================================================
 open_questions:
   - id: "Q-1"                 # -- 待确认问题。[必填][PM 填][机器读] 编号 Q-1 / Q-2 / ... 递增

package/dist/validators/references.js

@@ -80,6 +80,8 @@ function collectRefs(data) {
         ["data_constraints", "data_and_api.data_constraints"],
         ["api_constraints", "data_and_api.api_constraints"],
         ["security_constraints", "data_and_api.security_constraints"],
+        // v2.0 housekeeping — performance 与三兄弟对称,applies_to 强制 EN-*。
+        ["performance_constraints", "data_and_api.performance_constraints"],
     ];
     if (dao) {
         for (const [k, label] of strongDao) {

package/dist/validators/references.js.map

@@ -1 +1 @@
-{"version":3,"file":"references.js","sourceRoot":"","sources":["../../src/validators/references.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"references.js","sourceRoot":"","sources":["../../src/validators/references.ts"],"names":[],"mappings":"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"}

package/dist/workspace.d.ts

@@ -9,12 +9,14 @@ export interface ManifestFeatureEntry {
     landed_commit?: string;
 }
 export interface Manifest {
-    schema_version: string;
+    /** manifest 文件自身格式轴(v1.23 起;旧文件的 schema_version 字段由 writeManifest 写回时迁移) */
+    manifest_format_version: string;
     workspace_name: string;
     created_at: string;
     cli_version: string;
     features: ManifestFeatureEntry[];
 }
+export declare const MANIFEST_FORMAT_VERSION = "v0.1";
 interface ManifestRead {
     ok: true;
     data: Manifest;
@@ -33,4 +35,9 @@ export declare function readManifest(manifestPath: string): ManifestRead | Manif
  * freeze 的 nextAutoVersion 内部仍会再过滤一次,所以收敛安全。
  */
 export declare function listExistingVersions(frozenDir: string): string[];
+/**
+ * manifest 统一写盘(v1.23 F1):确保新格式轴字段在位 + 迁移删除遗留 schema_version 键。
+ * 三写点(init/freeze/closeout)共用;throw 由调用方现有 try/catch 接住。
+ */
+export declare function writeManifest(manifestPath: string, data: Manifest): void;
 export {};

package/dist/workspace.js

@@ -2,8 +2,9 @@
  * Workspace 共享 util:manifest 读取 + 版本号格式 + 已存在版本列表。
  * 由 init / freeze / context / diff 共用,集中维护 Manifest 类型。
  */
-import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 export const VERSION_REGEX = /^v\d+\.\d+(\.\d+)?$/;
+export const MANIFEST_FORMAT_VERSION = "v0.1";
 /**
  * 读取并基本验证 .prd/manifest.json。
  * features 必须是数组;返回的 data 类型为 Manifest,元素结构由 ManifestFeatureEntry 保证。
@@ -34,4 +35,14 @@ export function listExistingVersions(frozenDir) {
         .map((d) => d.name)
         .filter((v) => VERSION_REGEX.test(v));
 }
+/**
+ * manifest 统一写盘(v1.23 F1):确保新格式轴字段在位 + 迁移删除遗留 schema_version 键。
+ * 三写点(init/freeze/closeout)共用;throw 由调用方现有 try/catch 接住。
+ */
+export function writeManifest(manifestPath, data) {
+    const out = { ...data };
+    out.manifest_format_version = out.manifest_format_version ?? MANIFEST_FORMAT_VERSION;
+    delete out.schema_version;
+    writeFileSync(manifestPath, JSON.stringify(out, null, 2) + "\n", "utf8");
+}
 //# sourceMappingURL=workspace.js.map