@xgent-ai/skills 0.3.0 → 0.5.0

package/skills/prd/references/prd-skeleton.md

@@ -1,6 +1,6 @@
 # PRD 骨架 · `docs/PRD-<代号>.md`
 
-`<尖括号>` 为占位;引用块是写作指引,**写完删掉指引**。示例里的 `docs/PRD-A.md` / `docs/PRD-B.md` 这类具体文件名也是占位——它们在本 repo 里没有对应文件,写作时替换成宿主 repo 的真实 PRD 名。全篇不出现技术方案(表/端点/库/里程碑)。
+`<尖括号>` 为占位;引用块是写作指引,**写完删掉指引**。示例里的 `docs/PRD-A.md` / `docs/PRD-B.md` 这类具体文件名也是占位——它们在本 repo 里没有对应文件,写作时替换成宿主 repo 的真实 PRD 名。全篇聚焦产品行为、体验与预期状态,不展开技术方案(表/端点/库/技术里程碑)或测试方法。用户只要文档时不要求落库;未录入的新需求用明确工作号,不能伪造 FR/NFR key。
 规模参考:**160–380 行**。范围(§1 目标/非目标)约占 1/4,需求条目(§3)约占 1/2;领域语言、场景与决策只留能改变理解的内容,不为凑篇幅扩写。
 
 **架构约定(全篇按此写)**:§0–§6 是**终局蓝图**——目标写终局结果,需求条目写完整能力,一条都不因「这期做不完」提前砍掉或写小。**交付节奏只出现在 §7**,等全局盘完之后一次给出,并逐条标出「终验期」= 整条需求算完成的那一期。跨期需求的终验期要在三处齐:§7.3、该需求 SPMS `description` 开头的终验块、`acceptanceCriteria` 逐行 `[P#]` 前缀。
@@ -25,9 +25,9 @@
 > 先从用户视角说清「谁正被什么阻碍、造成什么影响」,再写现状与为什么是现在。不要把待做功能换个语序当成问题。有数据放数据（多少人/多少次/多少时间）。
 > 调查中读到的现状带路径或出处，与用户假设冲突的地方在这里说清楚。
 
-### 1.2 目标（**终局**、可度量的结果，3–5 条封顶）
+### 1.2 目标（**终局**、符合 SMAR 的结果，3–5 条封顶）
 
-> 写这块能力**做完之后**要达成的结果，不是「首期做到哪」。分期在 §7。
+> 写这块能力**做完之后**要达成的结果，不是「首期做到哪」。检查 Specific / Measurable / Actionable / Reasonable;不用 T 编造开发日期。区分验收门槛、观察指标和 PoC 基线,数值注明来源或「待确认的产品提案」,补必要口径。分期在 §7。
 
 - G1 <结果句，带判据。例：租户管理员无需联系运维即可完成 X，全流程 ≤ 3 步>
 - G2 …
@@ -41,6 +41,14 @@
 > 这张表是评审的挡箭牌。凡会被问「那 X 呢」的，都要提前出现在这里。
 > ⚠️ **去向里不许出现「二期 / 后期再做」**——那是分期，不是非目标。凡属于这块能力终局蓝图之内的，写成 FR/NFR 进 §3，再到 §7 排到靠后的期次去。
 
+### 1.4 产品方向与价值取舍
+
+| 设计维度 | 产品选择与用户价值 | 边界/取舍及依据 | 需求落点 |
+| --- | --- | --- | --- |
+| <创新性 / 先进性 / 可用性 / 便捷体验 / 美观 UI / AI 赋能> | <比现状或常规方案改善什么,不只罗列功能> | <约束内为何这样选;重要未选方案与理由> | <FR/NFR key> |
+
+> 六个维度都考虑,有实质落点的可合并;不适用则说明理由,不为了填表增加能力。具体推演见 product-quality.md。重要取舍记录在 §5.1,这里保留方向及关联,不重复决策全文。
+
 ## 2. 领域语言、用户与场景
 
 ### 2.1 领域语言
@@ -53,7 +61,7 @@
 
 ### 2.2 用户与权限边界
 
-| 角色 | 是谁 | 本期关心什么 | 权限边界 |
+| 角色 | 是谁 | 要完成什么任务 | 权限边界 |
 | --- | --- | --- | --- |
 | <租户管理员 / 普通成员 / 学生 / 平台运营> | … | … | <能看到/操作什么,不能看到/操作什么> |
 
@@ -68,11 +76,19 @@
 | --- | --- | --- | --- | --- |
 | S1 | <前置> | <动作> | <用户/外部系统可观察结果> | <主路径/权限/租户/空数据/重复/超限/状态/前置,只选命中项> |
 
+### 2.4 用户体验与 UI 要求
+
+| 入口/任务 | 默认信息与主操作 | 渐进展示与状态反馈 | 视觉要求及验收落点 |
+| --- | --- | --- | --- |
+| <主用户旅程的入口> | <用户首眼要理解什么、下一步做什么> | <哪些详情按需展开;成功/空/失败时的反馈及恢复> | <信息主次、排版/密度/视觉一致性、相关窗口要求;FR/NFR key 与验收行> |
+
+> 从首次使用、日常效率和异常恢复设计;美观须有可核对的要求,不只写「现代 UI」或可访问性。沿用宿主设计规范,不在这里指定 CSS/组件实现;无界面产品说明不适用。适用的 AI 能力在相关 FR 中明确触发、输出、用户控制、质量判据和降级状态。
+
 ## 3. 需求条目
 
-> 每条一小节。SPMS key 在创建后回填;**需求标题和实体引用必须使用真实 FR/NFR key**。`R#` 不是需求编号,只在「承接」和 §6.1 作原始诉求来源标识。
+> 每条一小节。SPMS key 在创建后回填;**已录入的需求标题和实体引用必须使用真实 FR/NFR key**。未录入的新需求明确标工作号。`R#` 不是需求编号,只在「承接」和 §6.1 作原始诉求来源标识。
 > FR 与 NFR 分开成组（对应 SPMS 的「功能性 / 非功能性」分组）。
-> **每条按完整能力写**——验收标准覆盖这条能力**做完**该有的全部断言,不写「本期版本」。「分期」行是 §7 定稿后回填的,不是写作时先定的。
+> **每条按完整能力写**——验收标准覆盖本 PRD 范围内这条能力**做完**该有的全部断言,不写「本期版本」。「分期」行是 §7 定稿后回填的,不是写作时先定的。
 
 ### FR-<N> <标题（动宾短语，一眼看出用户能做什么）>
 
@@ -81,12 +97,12 @@
 - **分期**：<P#｜跨期写「P1 / P2，**终验期 P2**」>（§7 定稿后回填，与 §7.2 逐字一致）
 - **背景**：<为什么需要这条，一两句>
 - **行为**：<谁在什么场景下能做什么。用户可感知的能力，不写实现。**按完整能力写**，不写「本期先只做…」>
-- **边界**：<**永久**不含什么；容易被误解的地方在这里堵死。「这期先不做」不写这里，写 §7>
+- **边界**：<本 PRD 能力范围不含什么,其他 PRD 的已明确分工可写去向;容易被误解的地方在这里说明。「这期先不做」写 §7>
 - **依赖**：<依赖别的 App/底座的写明；「未就绪则降级为 X」>
 - **验收标准**（→ SPMS `acceptanceCriteria`,一行一条、无 markdown 语法;断言用户/外部系统可观察的业务结果,不断言内部实现;**跨期需求逐行加 `[P#]` 前缀,单期需求不加**）：
 
 ```
-<角色>在<条件>下<动作>后，<系统必须怎样，带数字>
+<角色>在<条件>下<业务动作>后，<预期状态 + 清晰判据;数值指标附必要口径>
 <边界条件：为空/超限/无权限时的行为>
 <可观测的落点：列表出现该行 / 通知送达 / 审计留痕>
 ```
@@ -94,7 +110,7 @@
 > **仅跨期需求**：这条抄进 SPMS `description` 的开头（SPMS 里的读者看不到 PRD，PRD 条目里也留一份）——
 > `> **分期与终验**：本需求跨 P1 / P2 交付，**终验期 = P2**。P1 完成后请停在交付段（已提交 / 可测试），**不要转「已上线」**——「已上线」是整条需求的验收，不是某一期的完工。`
 
-- **测试用例种子**：TC-<N> <一句话标题>；覆盖 S<#> / 验收第 <#> 行；<还需要几条覆盖什么>
+- **UAT 场景**：UAT-<#>；对应 S<#> / 验收第 <#> 行；预期状态与通过条件见 §6.3
 
 ### NFR-<N> <标题（质量属性 + 约束对象）>
 
@@ -102,18 +118,19 @@
 - **优先级**：`…`
 - **承接**：原始诉求 R<#> · 目标 G<#> · 场景 S<#…>
 - **分期**：<P#｜跨期写「P1 / P2，**终验期 P2**」>（§7 定稿后回填）
-- **约束**：<必须带数值与作用域。例：列表首屏 p95 < 300ms @ 单租户 1 万行；超限行为是分页而非截断>
+- **重要度**：`critical|high|medium|low|none`
+- **约束**：<作用域与质量门槛。性能/容量带数值与条件,其他属性也可用明确状态或不变量;不写测试工具/步骤。示例阈值不能当成项目已确认承诺>
 - **验收标准**（同上格式，一行一条）：
 
 ```
-<可度量的断言，含数字与测量条件>
+<可判断的结果/不变量;数值指标附作用域和必要条件>
 ```
 
-- **测试用例种子**：TC-<N> …；覆盖 S<#> / 验收第 <#> 行
+- **UAT 场景**：UAT-<#> …；覆盖 S<#> / 验收第 <#> 行
 
 ## 4. 约束与前提
 
-- **用户给定的约束**：<原话来源标注「用户原话」；这是 PRD 里唯一允许出现技术选型的地方>
+- **用户给定的约束**：<来源明确,仅读过原话才加引号;技术选型作为已给定约束留在本节,不扩写实现设计>
 - **平台硬约束**：<多租户隔离 / 业务错误 200 / 列表服务端分页 / 三语 i18n / 席位与计量 / ACL 可见性——命中哪条写哪条，并说明对本期的具体影响>
 - **既有决策约束**：<相关 ADR/决策记录中对用户可观察行为的约束 + 出处;不抄实现方案。无则写「无」>
 - **前置依赖**：<某 App 或底座就绪与否，未就绪时的降级方案>
@@ -130,9 +147,9 @@
 
 ### 5.2 开放问题
 
-| # | 类型 | 问题与影响 | 当前默认及理由 | 负责人 | 截止时间 |
+| # | 类型 | 问题与影响 | 当前默认及理由 | 负责人 | 解决节点 |
 | --- | --- | --- | --- | --- | --- |
-| Q1 | <阻塞/非阻塞> | <问题;不同答案会改变什么> | <非阻塞必填;阻塞项不得靠默认越过> | <谁跟进> | <YYYY-MM-DD> |
+| Q1 | <阻塞/非阻塞> | <问题;不同答案会改变什么> | <非阻塞必填;阻塞项不得靠默认越过> | <谁跟进> | <进入哪期计划前;已有外部日期则保留> |
 
 > **定稿的 PRD 不得保留阻塞问题。** 会改变用户/权限、范围、FR/NFR 类型、业务语义或验收的都是阻塞问题;尚有这类问题时,文档标「草稿·未落库」,§8 不得宣称已写入 SPMS。定稿时若没有非阻塞开放问题,写「无」。
 
@@ -150,26 +167,35 @@
 
 > 一条都不许吞。有空白单元格说明需求没梳理干净。
 
-### 6.2 目标/场景 → 需求 → 验收 → TC
+### 6.2 目标/场景 → 需求 → 验收 → UAT 状态
 
-| 目标 | 场景 | 承接需求 | 验收落点 | TC 种子 |
+| 目标 | 场景 | 承接需求 | 验收落点 | UAT 场景 |
 | --- | --- | --- | --- | --- |
-| G1 | S1 | FR-37 | 验收第 1–2 行 | TC-51 |
-| G2 | S2 / S3 | FR-38 / NFR-9 | 各条验收第 1 行 | TC-52 / TC-53 |
+| G1 | S1 | FR-37 | 验收第 1–2 行 | UAT-1 |
+| G2 | S2 / S3 | FR-38 / NFR-9 | 各条验收第 1 行 | UAT-2 / UAT-3 |
 
-> 每个目标有需求承接,每条需求能指回目标/原始诉求,每个关键场景有验收覆盖,每条 FR 都有 TC 种子。任一格为空就不算定稿。
+> 每个目标有需求承接,每条需求能指回目标/原始诉求,每个关键用户场景有预期状态与验收覆盖。任一格为空就不算定稿;不要求 TC 已存在。
+
+### 6.3 UAT 场景预期状态与验收条件
+
+| UAT | 角色、前置与场景 | 用户意图/业务动作 | 预期状态 | 通过条件 | 需求与验收落点 |
+| --- | --- | --- | --- | --- | --- |
+| UAT-1 | <角色 + 初始状态;S1> | <业务动作,不写点击/调用脚本> | <结果是否可用、显示什么、允许的下一步、数据是否变化> | <无歧义的是/否、枚举、相等/不变或阈值与口径> | <FR/NFR key + 验收行> |
+| UAT-2 | <相关的空数据/无权/冲突/取消/失败/AI 降级场景> | … | … | … | … |
+
+> 只展开影响本产品的状态,不机械全枚举;通过条件引用 §3 的同一口径,不另造门槛。这里不写账号准备、造数、执行步骤、测试工具、探针或注入方法;交 test-plan 再展开。已有 TC 可在交接中引用真实 key,PRD 不创建 TC。
 
 ## 7. 分期交付建议
 
 > **全篇唯一谈交付节奏的地方**——§0–§6 一律按终局写。分期只改变顺序，**不改变需求集合**：这里不删需求、不砍验收标准、不把需求改小。
-> **供参考、非约束**：期次边界不等于计划边界，一期落成一份计划、一份计划里的几个里程碑、还是与别的 PRD 的需求合并，由 dev-plan 按技术依赖判断。**唯独「终验期」不是建议**——那是「整条需求何时算完成」的事实。
+> 期次是产品侧建议,技术拆解由 dev-plan 判断。每期开发计划尽量控制在 **5–8 个 Milestone**,因交付连续性可为 **9–10 个**并说明理由,**最多 10 个**;小范围可更少,不凑数。这里只给规模预算,不列 M1…Mn 的实现任务或编造工期;实际超出时反馈拆期并同步完整终验关系。**「终验期」是整条需求何时算完成的口径**,不能只在下游计划里提前。
 
 ### 7.1 期次总览
 
-| 期次 | 这期上线后，哪个角色多了什么以前做不到的事 | 出口判据（引用 §3 验收原话） | 前置 |
-| --- | --- | --- | --- |
-| P1 | <一个能独立交付的用户价值；不是「先做后端」这类技术栈切法> | <这期覆盖到的验收标准行> | <无 / 等某底座就绪 / 等某既有 key 先上> |
-| P2 | … | … | P1 |
+| 期次 | 这期上线后，哪个角色多了什么以前做不到的事 | 出口判据（引用 §3 验收原话） | 前置 | 开发计划规模建议 |
+| --- | --- | --- | --- | --- |
+| P1 | <一个能独立交付的用户价值；不是「先做后端」这类技术栈切法> | <这期覆盖到的验收标准行> | <无 / 等某底座就绪 / 等某既有 key 先上> | <5–8 个 Milestone;由 dev-plan 核实> |
+| P2 | … | … | P1 | <同上;9–10 个须说明连续性理由> |
 
 ### 7.2 分期矩阵（每条需求都要有一行，含本次更新的既有 key）
 
@@ -182,7 +208,7 @@
 | FR-41 | 既有 · 别的 PRD（`docs/PRD-B.md`） | 前置 | — | 不归本 PRD | P1 等它先上；本 PRD 不排它的期 |
 
 > **「来源」标签固定用这几种**：本 PRD 新建 / 既有 · 本次更新 / 既有 · 别的 PRD（只作前置） / 既有 · 别的项目（只作前置）。
-> 既有 key 必须是查重时**真命中**的（§6.1 有据），不许编号；只作前置的那些不占本 PRD 的终验期。
+> 既有 key 必须是查重时**真命中**的（§6.1 有据），不许编造；未录入新需求用工作号并在创建后回填。只作前置的那些不占本 PRD 的终验期。
 
 ### 7.3 跨期需求终验登记（只列跨期的；没有就写「本期无跨期需求」）
 
@@ -200,19 +226,25 @@
 - **终验期随 key 一起交出去**：逐条写明「本计划完成后 FR-38 仍停在交付段，终验在 P2」——只覆盖 P1 的计划里程碑全绿，也不代表跨期需求可以置「已上线」。
 - SPMS 侧落点 `plan_create(projectId, title, requirementKeys=[…])` → `PLAN-N`；⚠️ 一个 `PLAN-N` 只能挂**同一项目**的需求。
 - <若某条与另一份 PRD 的需求天然同批，点名：与 `docs/PRD-B.md` 的 FR-41 动同一块，建议合并一份计划>
+- 每期计划承接 §7.1 的规模预算;拆解为 9–10 个 Milestone 时解释连续性,超过 10 个则反馈拆期。产品交互与预期状态已经定清,具体架构、任务与里程碑在计划期展开。
+
+### 7.5 交给 test-plan
+
+- 交接需求 key、逐行验收标准、§6.3 UAT 状态与前置依赖。测试计划负责测试方法、数据、步骤、工具、查重及 TC 创建;不得到测试阶段才补决定产品状态。
+- <已有 TC 才列真实关联,无则写「尚未设计测试用例」;不把无 TC 写成 PRD 阻塞>
 
 ## 8. SPMS 落库结果
 
-- **已写入**：FR-37 / FR-38 / NFR-9（均 `status=draft`）；TC-51 / TC-52 / TC-53；项目「基本信息」<列出本次经 `project_update` 回写的段>
+- **已写入**：FR-37 / FR-38 / NFR-9（均 `status=draft`）；项目「基本信息」<列出本次经 `project_update` 回写的段>
 - **跨期终验声明已写入**：FR-38（`description` 终验块 + `acceptanceCriteria` 逐行 `[P#]` 前缀）<无跨期需求则写「本期无跨期需求」>
 - **待人工补**（MCP 无写面）：
   - 各需求的 版本(release)；
   - **跨期需求的版本挂终验期那一版**：FR-38 → <终验期对应的版本名>；
   - 评审通过后由人把 `draft → reviewing → approved`。
 
-> 重要度(importance) / 负责人(ownerId) / 截止日期(dueDate) **MCP 可写**，建单时就一并给，不进这张清单。
+> 重要度(importance) / 负责人(ownerId) / 截止日期(dueDate) **MCP 可写**,不进人工补字段清单;负责人已明确才写,日期仅按用户/外部约束填写,不自动制造期限,更新时不清除未要求修改的值。
 
-> 若 §5.2 仍有阻塞问题,本节改写「未写入 SPMS」与阻塞原因,不得出现虚构 key。
+> 若 §5.2 仍有阻塞问题、用户只要文档或工具不可用,本节如实写「未写入 SPMS」与原因及可交接字段,不得出现虚构 key。
 ```
 
 ---
@@ -221,24 +253,30 @@
 
 | 毛病 | 症状 | 改法 |
 | --- | --- | --- |
-| 验收标准是愿望 | 「体验流畅」「性能良好」「操作便捷」 | 换成带数字的断言;种不出 TC 就是没想清楚 |
-| 需求变方案 | 出现表名/端点/库名/里程碑 | 挪到 dev-plan;PRD 只留「用户能做什么」 |
-| 粒度失控 | 一条需求要 30 个 Issue,或一条需求就是一个按钮 | 拆到「一个可感知能力、3–10 个 Issue」 |
+| 验收标准是愿望 | 「体验流畅」「性能良好」「操作便捷」 | 写清预期状态和可判断条件;数值须有口径,明确状态也可验收 |
+| 需求变方案 | 自行设计表/端点/库选型/技术里程碑 | 挪到 dev-plan;保留产品行为、体验与已给定约束 |
+| 粒度失控 | 一条需求混入多个独立能力,或一条需求就是一个按钮 | 按用户可感知且可独立验收的能力拆分,不估算 Issue 数 |
+| 产品只转录清单 | 没有六维推演或价值取舍,AI 只是多一个聊天入口 | 从主旅程寻找约束内的改进,采用的方向落实 FR/NFR 与验收 |
+| UI 只有形容词 | 只写「美观、现代」或只剩可访问性指标 | 补信息主次、主操作、视觉一致性与相关状态要求 |
+| UAT 变测试步骤 | 写测试账号/造数/点击脚本/探针/故障注入 | 保留场景、业务动作、预期状态与通过条件,方法交 test-plan |
+| AI 没闭环 | 不知道何时触发、谁确认,不可用时只报错 | 补价值、用户控制、质量判据、依赖与降级状态 |
+| SMAR 变口号 | 有功能名却无具体角色、结果或合理边界 | 对照 Specific / Measurable / Actionable / Reasonable,不凭空给日期 |
 | 非目标空着 | 只有 1-2 条或直接省略 | 把评审会被问的相邻功能全列出来 |
-| NFR 没数字 | 「要安全」「要快」 | 补 `category` + 数值 + 测量条件 |
+| NFR 没门槛 | 「要安全」「要快」 | 补 `category` + 作用域 + 可判断门槛;数值指标带必要条件 |
 | 编号错乱 | 需求标题/实体引用仍用 R1/R2,或与真实 key 混用 | 创建后回填 FR/NFR key;`R#` 只留在「承接」和 §6.1 作来源标识 |
 | 角色含糊 | 通篇「用户」 | 落到租户内具体角色,并写清权限边界 |
 | 领域词漂移 | 同一概念用多个词,或「账号/状态/任务」各自指多个东西 | 在 §2.1 选定规范词与定义,全篇统一 |
 | 场景只写主路径 | 权限/租户/空数据/重复/状态边界没人拍板 | 用少量高信息量 `S#` 压测真正有关的边界 |
 | 决策只留在对话 | 结论有了,但后来人不知道为什么 | 在 §5.1 只记录会影响范围/语义/验收的产品决策 |
 | 阻塞问题伪装成默认 | 答案会改需求,但文档仍定稿/落库 | 保留在 frontier;未拍板只能交草稿,不写 SPMS |
-| 追踪链断了 | 目标无需求、场景无验收、或 FR 无 TC | 补齐 §6.2,任一单元格为空都不定稿 |
+| 追踪链断了 | 目标无需求、场景无预期状态或验收 | 补齐 §6.2–6.3;无 TC 不影响 PRD 成立 |
 | 验收盯内部实现 | 断言表/函数/内部调用次数 | 改为用户或外部系统可观察的最高业务边界 |
 | 分期混进正文 | 目标/行为/边界里出现「本期先只做…」「二期再说」 | §0–§6 按终局写;所有期次安排收进 §7 |
 | 非目标当分期用 | 非目标去向写「二期 / 后期再做」 | 属于终局蓝图的挪回 §3 成为 FR/NFR,在 §7 排到靠后期次 |
 | 分期只盘自己 | 分期矩阵里只有本 PRD 新建的几条 | 把查重命中的既有 key、以及同期必须一起上的别的 key 一并列进来并标来源 |
 | 需求被期次切碎 | 一个可感知能力被拆成 FR-A(一期) / FR-B(二期) 两条 | 合回一条,在 §7.2 标成跨期并给终验期 |
 | 按技术栈分期 | 「P1 后端、P2 前端」 | 每期必须说清哪个角色多了什么以前做不到的事;说不清就并掉 |
+| 每期计划过大 | 建议超过 10 个 Milestone,或 9–10 个无理由 | 调整分期;尽量 5–8 个,连续性例外最多 10 个,具体拆解交 dev-plan |
 | 跨期需求没终验期 | 一条需求横跨两期,却没说哪一期算整条完成 | §7.3 登记 + `description` 终验块 + 验收行 `[P#]` 前缀,三处齐 |
 | 阶段完工当整条完成 | 首期 Issue 全绿就把需求转「已上线」 | 终验期未到不置终态;把终验声明写进需求正文,点按钮的人才看得见 |
 | 版本挂错期 | 跨期需求的 release 挂了首期 | 挂**终验期**那一版,否则版本报表提前把它算成已交付 |

package/skills/prd/references/product-quality.md

@@ -0,0 +1,89 @@
+# 产品推演、SMAR 与 UAT 状态验收
+
+写新 PRD、整体优化或评审时使用;局部修改只检查受影响部分。推演发生在共同理解确认之前,成文时只综合已确认的产品选择。
+
+## 1. 在约束内把产品推演充分
+
+先明确用户任务、现状阻碍、用户给定约束、宿主能力和本 PRD 的能力边界。沿「发现 → 理解 → 决策 → 完成任务 → 再次使用 / 异常恢复」走一遍主旅程,省掉无关环节,从以下六个维度寻找有价值的改进。
+
+| 维度 | 应推演的产品问题 | 成文落点 |
+| --- | --- | --- |
+| 创新性 | 除了照搬现状或参考产品,能否改变用户完成任务的方式,减少过去必须承担的判断或工作? | 与常规方案有实质差异的产品选择、价值与取舍 |
+| 先进性 | 当前生态或 AI 能力是否让新的使用方式成立?哪些只是声明,哪些已有行为证据? | 能力边界、准入条件与依赖;外部能力核到当前官方资料,不能将参考项目说明当成已支持 |
+| 可用性 | 关键角色能否完成完整任务?空数据、无权、依赖缺席、失败时仍能理解状态和下一步吗? | 完整 FR、相关 NFR、状态与恢复判据 |
+| 便捷体验 | 能否减少重复输入、记忆术语、切换入口和无价值确认?首次与高频使用是否都有合适路径? | 默认信息、最短业务路径、渐进展示、便捷性判据 |
+| 美观 UI | 信息主次、排版、密度、留白和视觉语言是否支持任务?各状态与不同窗口下是否保持清晰一致? | 信息层级、视觉原则与可核对要求;沿用宿主设计约束,不只写「现代、美观」 |
+| AI 赋能 | AI 能在哪个环节改善发现、理解、创作、决策或重复劳动?如何判断比基本路径更有价值? | 输入/输出、触发与用户控制、质量/成本边界、降级状态及验收 |
+
+六维是思考方向,不要求增加六组功能。对影响主旅程的选择比较有实质差异的候选,写清为什么选、牺牲什么、怎样算成立。将采用的方向落到目标、FR/NFR 和验收中;无 UI 或 AI 无适用价值时说明理由,不为填表添加界面或模型。
+
+终局始终在用户给定范围内。技术 PoC 要把重要假设及成立/不成立的判据推演透;完整产品要把用户任务推演透。不因技术 PoC 默认只需几个技术组件,也不把一个 PoC 扩成整个产品系列。
+
+## 2. 产品设计与实现设计的边界
+
+| PRD 要决定什么 | 下游计划再决定什么 |
+| --- | --- |
+| 用户按任务发现内容,理解匹配依据;增强不可用时仍可基本搜索 | 向量索引、检索算法、模型供应商、调用编排 |
+| 同一内容面向人和 Agent 提供不同的消费结果,证据不足时明确为空 | 内部编译阶段、数据模型、存储结构、服务接口拆分 |
+| 用户从出处一次跳转到原文被引段落,能辨认当前位置 | 前端组件、路由状态、焦点管理代码 |
+| 关键状态在首屏可见,主操作突出,详情按需展开,视觉遵守宿主规范 | CSS 数值、组件库选型、DOM 结构 |
+| 受控条件下响应达到门槛,失败后已有内容不丢失 | 压测工具、测试数据生成、故障注入脚本 |
+
+用户动作描述不等于测试步骤:「发布者确认发布后,版本可消费」是在定义产品行为;「登录测试账号、依次点击三个按钮、运行查询核对记录」是在设计怎么测。前者留 PRD,后者交 test-plan。
+
+已有外部契约或用户指定技术约束可以引用,注明来源和产品影响;不借这些约束自行决定内部实现。评测或诊断工具本身是交付能力时,写它应展示的结果、指标定义和证据,把验收它的测试方法留给下游。
+
+## 3. AI 赋能必须形成产品闭环
+
+在有价值的环节主动设计 AI 能力,不能满足于一个泛化聊天入口。每项采用的 AI 能力应回答:
+
+- **价值与触发**:谁为完成哪项任务,主动触发或在何种已授权条件下触发?替用户省掉什么工作,需要哪些有权使用的输入,得到什么输出?
+- **用户控制**:结果是建议、草稿、解释还是自动业务动作?用户如何理解依据、修改、采纳、拒绝或撤销?重要写入的授权与确认边界是什么?
+- **质量与不确定性**:怎样判断结果可用?无依据、低置信度、矛盾或未验证时显示什么?定义质量指标的口径,不把模型生成或读取成功当成业务成功。
+- **依赖与成本**:权限、预算、可用性不足时进入什么状态?辅助型 AI 保持基本任务可完成;AI 是核心能力时,明确等待、失败和可恢复条件,不假装仍能完成核心任务。
+
+这些是产品决策,不要求预先选择模型、提示词、RAG 管线或 Agent 框架。AI 不适用或被用户排除时,保留理由;不将「AI 开发」等同于「所有功能都需要运行时 AI」。
+
+## 4. 用 SMAR 检查目标与需求
+
+| 原则 | 必须能回答 | 不合格信号 |
+| --- | --- | --- |
+| Specific | 谁、在哪个场景、对象是什么、能力和权限到哪? | 通篇「用户」或「智能管理」,同一个状态有多种含义 |
+| Measurable | 到达什么可观察状态、按什么口径判断通过? | 「体验好」「准确」「安全」,只有数字没有作用域/分母 |
+| Actionable | 用户或授权主体能执行什么动作、获得什么可用结果? | 只有愿景/技术名词,没有可完成的任务 |
+| Reasonable | 价值、质量、成本、依赖是否与用户约束相容? | 承诺未知生态组合全部兼容、依赖不明仍无条件承诺、为了先进堆功能 |
+
+Measurable 不等于每行硬塞数字。明确的枚举、结果集合、是/否、相等/不变也可验收。性能和质量数值要附必要的负载、语料、样本或分母;指标有观察窗口时说明窗口和未知数据的处理,不在 PRD 展开采样脚本与执行步骤。
+
+区分三类口径:产品验收门槛、上线后观察指标、PoC 比较基线。数值来自用户/既有约束则给来源;新提出的门槛标为产品提案并确认,不声称已实测,不把基线当效果承诺。
+
+不用 Time-bound 为 AI 开发编造工期或发布日期。以独立用户价值切期,每期开发计划建议 5–8 个 Milestone;连续性例外可为 9–10 个并说明理由,最多 10 个。PRD 表达规模预算,dev-plan 核实并拆解;小任务可更少,超出则反馈拆期,不能删掉完整验收。已有外部日期约束仍须尊重,性能时延、超时、有效期和观察窗口也不能被删除。
+
+## 5. UAT 写预期状态,不写测试程序
+
+每个重要用户场景写清「角色与前置状态 → 业务意图/动作 → 预期状态 → 清晰的通过条件」,关联真实需求 key 与验收行。只覆盖相关状态:成功、空数据、拒绝、重复/冲突、取消、失败/恢复、AI 不确定/降级。状态包括结果是否可用、显示的解释、允许的下一步和数据是否改变;不能只写一句提示文案。
+
+以下为写法示例,不预设具体项目承诺:
+
+| 角色与前置 | 业务动作 | 预期状态与通过条件 |
+| --- | --- | --- |
+| 普通成员,没有可用证据 | 提问 | 明确无可靠内容,出处集合为空,无伪造回答;页面给出获取证据的下一步 |
+| 发布者,内容已通过本产品要求的检查 | 确认发布 | 该确切版本可消费;发布成功与兼容验证分别表达,不因发布而显示已验证 |
+| 维护者,AI 给出资料建议 | 拒绝建议 | 正式资料和原始内容保持不变;建议不进入正式分发 |
+| 成员,已有本地内容 | 取消升级 | 原内容与选定版本不变;不显示升级成功 |
+| 成员,AI 增强不可用 | 搜索 | 可用基本结果且模式明确,用户仍可继续任务;不显示增强成功 |
+
+定稿检查三件事:每条需求有可判断的验收;每个关键用户场景有预期状态与通过条件;目标/场景/需求/验收/UAT 相互可追踪。此时无需已存在 TC。测试计划随后决定账号、数据、执行步骤、工具、故障模拟和完整覆盖,不能在写测试计划时才首次决定产品应到达什么状态。
+
+## 6. 交付前按挑剔评审者的视角自审
+
+先读完成稿,逐项找反例并改正文,不把自审过程倾倒进 PRD:
+
+- 哪个关键任务仍要求用户自己补步骤或猜状态?是否只罗列功能,没有形成完整体验?
+- 创新/先进/AI 选择有什么具体收益和合理边界?是否只是换术语、跟风或加入口?
+- UI 是否只写可访问性门槛,却遗漏信息主次、视觉一致性和主路径便捷性?
+- 任意一条验收能否无歧义地判定通过/不通过?是否用测试动作替代了预期状态?
+- 是否把用户给定范围之外的能力硬塞进终局,或用分期删掉终局要求?
+- 每期是否有独立用户价值、计划规模预算和清晰终验期?是否将阶段完成冒充整条完成?
+
+仍有会改变产品语义的缺口则回到对应决策;已确认且符合约束的选择直接成文,不重复泛化访谈。

package/skills/prd/references/spms-mapping.md

@@ -12,12 +12,12 @@
 | §1.2 目标 | `projects.goal`（目标） | 同上;**Web 端是列表编辑器,一行一条** |
 | §1.3 非目标 | `projects.nonGoals`（非目标） | 同上;**一行一条**(去向写在同一行) |
 | §4 约束与前提 | `projects.constraints`（约束与前提） | 同上 |
-| §5.2 非阻塞开放问题 | `projects.openQuestions`（开放问题） | 同上;**一行一条**,格式 `Q1 [非阻塞] 问题;默认及理由;负责人;截止时间`;无则传 `null`;阻塞问题未解时不定稿/不回写项目 |
+| §5.2 非阻塞开放问题 | `projects.openQuestions`（开放问题） | 同上;**一行一条**,格式 `Q1 [非阻塞] 问题;默认及理由;负责人;解决节点`;已有外部日期则保留;无则传 `null`;阻塞问题未解时不定稿/不回写项目 |
 | §3 FR 条目 | `requirements`（`FR-N`) | `requirement_create` |
 | §3 NFR 条目 | `requirements`（`NFR-N`,带 `category`) | `requirement_create` |
 | 条目正文 | `requirements.description`（UI 标签「PRD 描述」) | 完整 markdown |
 | 验收标准 | `requirements.acceptanceCriteria`（UI 标签「验收标准」) | **纯文本,一行一条** |
-| TC 种子 | `test_cases`（`TC-N`) | `testcase_create(requirementKey=...)` |
+| §6.3 UAT 场景预期状态 | **无独立字段** | 文档保留全局状态表,相关场景与判据写入对应需求 `description`;PRD 不创建 TC,由 test-plan 后续展开 |
 | §7 分期交付建议 | **无独立字段** | 分期本身只留在 PRD 文档;**跨期需求的终验声明**要落进该需求的 `description` 开头 + `acceptanceCriteria` 逐行 `[P#]` 前缀(见 §5),版本(release)人工挂**终验期**那一版 |
 | §8 SPMS 落库结果 | — | 记录本次真实写入的 key 与待人工补字段;有阻塞问题时改写「未写入」 |
 | 开发计划(下游) | `plans`（`PLAN-N`)+ `plan_requirements` | dev-plan 阶段 `plan_create(requirementKeys)` / `plan_update({content})`。**PRD : 计划多对多**——可拆可合,关联键是 FR/NFR key;⚠️ **只能挂同项目的需求**,跨项目 key 报 `LIFECYCLE_MISMATCH`(平台契约) |
@@ -49,7 +49,7 @@
 | --- | --- | --- |
 | `importance` 重要度 | `critical\|high\|medium\|low\|none` | 与 `priority`(紧急度)**正交**,两个都该给 |
 | `ownerId` 负责人 | `project_get` 成员名册的 `memberId`;`null` 清除 | 只收本租户未撤销成员,否则 `VALIDATION_FAILED`。与「执行人」(由关联 Issue 派生)不是一回事 |
-| `dueDate` 截止日期 | ISO 8601(如 `2026-07-15`);`null` 或空串清除 | 格式不对是 `VALIDATION_FAILED`。需求池按日期范围筛选用 |
+| `dueDate` 截止日期 | ISO 8601(如 `2026-07-15`);`null` 或空串清除 | 格式不对是 `VALIDATION_FAILED`。仅按用户/外部日期约束填写,不为 SMART 的 T 自动造日期;更新时保留未要求改变的原值 |
 
 **仍然写不到的字段**——交付时单列一张「待人工补」清单:
 
@@ -77,7 +77,7 @@
 
 ```
 ✅ 管理员在「应用市场」点击安装后，应用 3 秒内出现在左侧导航
-✅ 非管理员访问该入口返回 403，且导航不显示该项
+✅ 无安装权限的成员不能安装应用，且导航不显示安装入口
 ✅ 已安装应用重复安装时提示「已安装」，不产生第二条记录
 
 ❌ - 管理员可以安装应用        → 行首 "-" 会原样显示成「• - 管理员…」
@@ -94,12 +94,14 @@
 
 ```
 ✅ [P1] 管理员在「应用市场」点击安装后，应用 3 秒内出现在左侧导航
-✅ [P2] 非管理员访问该入口返回 403，且导航不显示该项
+✅ [P2] 管理员安装应用后可配置成员入口，未授权成员不能进入该应用
 ```
 
 方括号**不在**剥离表(`- * • 1. 1)`)里,展示端本来也不剥 —— 所以这是**唯一不破坏「纯文本一行一条」契约**的标法。
 **单期需求不要加**,加了就是噪声。配套的两处见 §5.1。
 
+验收行描述场景预期状态与清晰判据,不写测试方法。上面示例只示范格式;权限边界等上线必要条件应随所在期用户价值一起满足,不能为了跨期示例而推迟必要权限保护。
+
 ### 5.1 跨期需求的终验声明(防「阶段交付被误记为整条完成」)
 
 一条需求跨两期交付时,**整条需求算完成的那一期叫「终验期」= 最后一期**。三处一起写,缺一处就会有界面在说谎:
@@ -129,10 +131,10 @@ requirement_get('FR-18')                    → 读某条全量（含验收标
 --- 用户确认后 ---
 requirement_create({projectId, title, type, category?, priority, status:'draft',
                     description, acceptanceCriteria})   → 返回体里拿真实 key
-testcase_create({projectId, title, requirementKey:'FR-37', preconditions?, steps, expected,
-                 priority?, status:'draft'})            → TC-N，result 默认 untested
 ```
 
+PRD 到需求写入为止;UAT 场景与验收标准交给 test-plan,由它查重并创建 TC,本阶段不调用 `testcase_create`。
+
 ## 7. 错误码与闸(照实报,别绕道)
 
 | 现象 | 含义 | 怎么办 |

package/skills/react/SKILL.md

@@ -6,11 +6,13 @@ description: >
   (2) writing or debugging `useEffect` — deciding whether an Effect is needed at all,
   (3) using `useState` for derived values, or syncing state between components,
   (4) diagnosing unnecessary re-renders, stale closures, or memoization problems,
-  (5) fixing data-fetching waterfalls, race conditions, or duplicate requests,
+  (5) fixing data-fetching waterfalls, race conditions, or duplicate requests, or using `use()` with Suspense,
   (6) optimizing paint, hydration, resource loading, or hot-path JavaScript,
-  (7) working with refs, composition, prop drilling, or controlled vs. uncontrolled components.
+  (7) working with refs, composition, prop drilling, or controlled vs. uncontrolled components,
+  (8) upgrading React 18 to 19 — removed APIs (`ReactDOM.render`, `findDOMNode`, string refs, legacy context), `forwardRef`, `defaultProps`, and tests (`test-utils`, `act`, StrictMode counts),
+  (9) forms and mutations with Actions — `useActionState`, `useFormStatus`, `useOptimistic`.
 license: MIT
-compatibility: React 18+ (React 19 for `use`, `Activity`, ref-as-prop)
+compatibility: React 18+ (React 19 for `use`, Actions, `Activity`, ref-as-prop)
 allowed-tools: Read Write Edit Glob Grep
 ---
 
@@ -25,9 +27,11 @@ Read ALL relevant references in the same turn, in parallel. Cite them when givin
 - [Effect patterns](references/effect-patterns.md): When you don't need an Effect, dependency rules, cleanup, subscriptions, `useSyncExternalStore`, one-time initialization
 - [Re-render optimization](references/rerender-optimization.md): `memo`/`useMemo`/`useCallback`, derived state, functional updates, lazy init, `useDeferredValue`, `startTransition`, `useEffectEvent`
 - [Component patterns](references/component-patterns.md): Refs, `useImperativeHandle`, custom hook rules, controlled vs. uncontrolled, composition over prop drilling, `flushSync`
-- [Data fetching](references/data-fetching.md): Parallelizing requests, Suspense boundaries, request deduplication, passive listeners, `localStorage` versioning
+- [Data fetching](references/data-fetching.md): Parallelizing requests, Suspense boundaries, `use()` and stable promise sources, request deduplication, passive listeners, `localStorage` versioning
 - [Rendering performance](references/rendering-performance.md): `content-visibility`, hydration mismatches, resource hints, script loading, SVG animation, `Activity`, `useTransition`
 - [JS performance](references/js-performance.md): Layout thrashing, `Set`/`Map` lookups, index maps, single-pass iteration, `toSorted`, `requestIdleCallback`
+- [Actions](references/actions.md): `<form action>`, `useActionState`, `useFormStatus`, `useOptimistic` — pending, error, and optimistic state for mutations
+- [React 19 migration](references/react19-migration.md): Upgrading from 18 — root API, `findDOMNode`, `forwardRef`, `defaultProps`, legacy context, string refs, propTypes, JSX transform, TypeScript types, `act`/`test-utils`, StrictMode test counts
 
 ## You Might Not Need an Effect
 
@@ -83,6 +87,22 @@ Need to respond to something?
 - Move `await` past early returns and behind cheap synchronous guards
 - One shared request per endpoint (SWR / React Query), not one per component instance
 - Every fetch effect needs an `ignore` flag or `AbortController`
+- Promises passed to `use()` come from a loader, cache, library, or Server Component — never created in render
+
+### Forms and mutations (React 19)
+
+- `<form action={fn}>` over `onSubmit` + `preventDefault`; `useActionState` over a loading/error reducer
+- Return expected errors from the action as state; thrown errors go to the error boundary
+- `useFormStatus` is imported from `react-dom` and only reads a parent `<form>`
+- Seed `useOptimistic` with confirmed state and call its setter inside an Action
+- After `await` inside an Action, wrap state updates in another `startTransition`
+
+### Upgrading to React 19
+
+- Run `npx codemod@latest react/19/migration-recipe` first; the upgrade PR changes API surface only
+- `forwardRef` still works — `ref` is a plain prop; convert opportunistically
+- `defaultProps` are ignored on function components but still work on class components
+- StrictMode still double-runs effects; what changed is `useMemo`/`useCallback` result reuse and double-invoked ref callbacks
 
 ### Performance
 
@@ -101,3 +121,5 @@ Need to respond to something?
 5. Are components defined at module scope?
 6. Are independent async calls parallelized?
 7. Are mutating array methods used on props or state?
+8. Is every promise passed to `use()` stable across renders?
+9. On React 19: are forms using Actions with errors returned as state, and are removed APIs (`findDOMNode`, string refs, legacy context, `test-utils`) gone?