@xgent-ai/skills 0.1.0 → 0.4.0

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

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

@@ -0,0 +1,150 @@
+# SPMS 需求落库速查
+
+本文所有字段/枚举/写面缺口均核自 SPMS 平台实现,当**平台契约**用。文中偶尔出现的 `apps/spms-server/...` 这类源码路径是**门户仓内的核实出处记录**——装到外部 repo 后本 repo 里没有这些文件,不要去读、不要去找;拿不准的以运行中的 SPMS MCP 面实际行为为准。
+
+## 1. PRD 各部分落到哪
+
+| PRD 章节 | SPMS 落点 | 怎么写 |
+| --- | --- | --- |
+| §0 一句话 | `projects.summary`（概述） | `project_update`(FR-236);**整段覆盖,先 `project_get` 读现状** |
+| §1.1 问题陈述与现状 | `projects.background`（背景） | 同上 |
+| §2.2–2.3 用户与场景 | `projects.personas`（用户与场景） | 同上;§2.1 领域语言只留在 PRD 文档,不混入 `personas` |
+| §1.2 目标 | `projects.goal`（目标） | 同上;**Web 端是列表编辑器,一行一条** |
+| §1.3 非目标 | `projects.nonGoals`（非目标） | 同上;**一行一条**(去向写在同一行) |
+| §4 约束与前提 | `projects.constraints`（约束与前提） | 同上 |
+| §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 标签「验收标准」) | **纯文本,一行一条** |
+| §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`(平台契约) |
+
+## 2. 枚举真值
+
+| 字段 | 取值 | 中文标签 |
+| --- | --- | --- |
+| `type` | `functional` / `non_functional` | 功能性 / 非功能性 |
+| `category`（**仅 NFR**,FR 留 null） | `performance` / `security` / `usability` / `reliability` / `compatibility` / `maintainability` | 性能 / 安全 / 易用性 / 可靠性 / 兼容性 / 可维护性 |
+| `status`（8 值） | `draft` → `reviewing` → `approved` → `in_dev` → `submitted` → `testable` → `shipped`,或 `rejected` | 草稿 / 评审中 / 已批准 / 开发中 / **已提交** / **可测试** / **已上线** / 已拒绝 |
+| `priority`（紧急度） | `urgent` / `high` / `medium` / `low` / `none` | 紧急 / 高 / 中 / 低 / 无 |
+| `importance`（重要度,**与 priority 正交**） | `critical` / `high` / `medium` / `low` / `none` | 关键 / 高 / 中 / 低 / 未评估 |
+| TC `status` | `draft` / `active` / `deprecated` | 草稿 / 可用 / 废弃 |
+| TC `result` | `untested` / `passed` / `failed` / `blocked` | 未测 / 通过 / 失败 / 阻塞 |
+
+**PRD 阶段一律建 `status=draft`**;`reviewing`/`approved` 是人的动作。
+
+⚠️ **`shipped`(已上线)就是需求侧的终点** —— 需求**没有**「已上线」之后的第二个人工终态(与 Issue 的不对称是平台刻意的),把需求转到它**本身就是那次需求级验收**,而且会通知需求作者。`submitted`(已提交) / `testable`(可测试) 是「交付中」段,跨期需求的首期完工应停在这里。Agent 写不到两个终态(`shipped` / `rejected` → `FINAL_STATE_FORBIDDEN`),所以**防误记只能靠把终验期写进需求正文**,让点按钮的人先看见。
+
+## 3. MCP 写面
+
+`requirement_create` / `requirement_update` 的 inputSchema:
+`projectId` · `title` · `type` · `category` · `priority` · `importance` · `status` · `description` · `acceptanceCriteria` · `ownerId` · `dueDate`(update 用 `key` 寻址)。
+
+**这三个曾经写不到、现在可以写**——不要再把它们列进「待人工补」:
+
+| 字段 | 写法 | 备注 |
+| --- | --- | --- |
+| `importance` 重要度 | `critical\|high\|medium\|low\|none` | 与 `priority`(紧急度)**正交**,两个都该给 |
+| `ownerId` 负责人 | `project_get` 成员名册的 `memberId`;`null` 清除 | 只收本租户未撤销成员,否则 `VALIDATION_FAILED`。与「执行人」(由关联 Issue 派生)不是一回事 |
+| `dueDate` 截止日期 | ISO 8601(如 `2026-07-15`);`null` 或空串清除 | 格式不对是 `VALIDATION_FAILED`。仅按用户/外部日期约束填写,不为 SMART 的 T 自动造日期;更新时保留未要求改变的原值 |
+
+**仍然写不到的字段**——交付时单列一张「待人工补」清单:
+
+| 字段 | UI 位置 | 备注 |
+| --- | --- | --- |
+| `releaseId` 版本 | 需求抽屉 | 单值字段,应与项目的 release 一致否则 UI 出告警;**跨期需求挂「终验期」那一版**——挂首期会让版本报表提前把整条需求算成已交付 |
+| 附件 | 需求抽屉 | MCP 只能读(`attachment_read`),不能传 |
+| 排期/点数 | Sprint 规划页 | 属规划期(`sprint_plan_items`),**不在 PRD 阶段做** |
+| 项目治理字段(名称/状态/负责人/团队/版本) | 项目抽屉 | `project_update` 只写基本信息七段;**无 `project_create`** |
+
+## 4. key 分配规则(建之前必须知道)
+
+- `FR-N` / `NFR-N` / `TC-N` 都是**租户级**序列(不是项目级)——编号跨项目连续,别指望 `FR-1` 是本项目第一条。
+- 前缀在**创建时**按 `type` 决定;**之后改 `type`,key 不会重写**(与 issue key 契约一致)。→ **建之前把 FR/NFR 判定定死**,建完再改类型就是永久错配。
+- key 创建后才知道 → PRD 草稿的 `R1..Rn` 是原始诉求追踪号,创建前也暂作工作号。**建完立刻回填真实 key**;之后凡是指代需求实体/标题都用 FR/NFR key,`R#` 只留在「承接」与原始诉求追踪表。
+- `*_create` **不幂等**:重复调用 = 重复需求 + 烧掉 key。建之前 `pms_search` + `requirement_list` 查重,写库前把清单摊给用户确认。
+
+## 5. 正文与验收标准的物理格式
+
+**`description`(PRD 描述)** —— markdown 全量渲染(平台统一的 markdown 渲染组件),标题/列表/**表格**/代码块都可用。
+图片只认 `![name](xgent-attachment:<id>)` 稳定引用,而 MCP 没有上传面 → **正文里不要放外链图**。
+
+**`acceptanceCriteria`(验收标准)** —— **不是 markdown**。展示端按 `\n` 切行、trim、丢空行,渲染成圆点列表,**一个字符都不剥**。
+⚠️ 剥列表前缀(`- * • 1. 1)` + 后随空白)只发生在 **Web 列表编辑器保存**那条路径上,**MCP 写进去的不经过它** —— 所以你写的任何前缀都会原样显示在界面上:
+
+```
+✅ 管理员在「应用市场」点击安装后，应用 3 秒内出现在左侧导航
+✅ 无安装权限的成员不能安装应用，且导航不显示安装入口
+✅ 已安装应用重复安装时提示「已安装」，不产生第二条记录
+
+❌ - 管理员可以安装应用        → 行首 "-" 会原样显示成「• - 管理员…」
+❌ 1. 管理员可以安装应用        → 同样原样显示（展示端不剥数字前缀）
+❌ **重要**：安装要快          → 加粗语法原样显示，且「快」不可断言
+❌ （空行分段）                → 空行被丢弃，分段无效
+```
+
+一行一条、无前缀符号、无空行、无 markdown 语法、每条可断言。
+
+### 唯一允许的前缀:跨期需求的 `[P#]` 期次标
+
+跨期需求(验收标准分散在两期以上)**逐行**加期次前缀,让 QA 一眼看出这期该验哪几行:
+
+```
+✅ [P1] 管理员在「应用市场」点击安装后，应用 3 秒内出现在左侧导航
+✅ [P2] 管理员安装应用后可配置成员入口，未授权成员不能进入该应用
+```
+
+方括号**不在**剥离表(`- * • 1. 1)`)里,展示端本来也不剥 —— 所以这是**唯一不破坏「纯文本一行一条」契约**的标法。
+**单期需求不要加**,加了就是噪声。配套的两处见 §5.1。
+
+验收行描述场景预期状态与清晰判据,不写测试方法。上面示例只示范格式;权限边界等上线必要条件应随所在期用户价值一起满足,不能为了跨期示例而推迟必要权限保护。
+
+### 5.1 跨期需求的终验声明(防「阶段交付被误记为整条完成」)
+
+一条需求跨两期交付时,**整条需求算完成的那一期叫「终验期」= 最后一期**。三处一起写,缺一处就会有界面在说谎:
+
+1. **`description` 开头**一段引用块(正文是 markdown,正常渲染):
+
+   ```
+   > **分期与终验**:本需求跨 P1 / P2 交付,**终验期 = P2**。P1 完成后请停在交付段(已提交 / 可测试),**不要转「已上线」**——「已上线」是整条需求的验收,不是某一期的完工。
+   ```
+
+2. **`acceptanceCriteria` 逐行 `[P#]` 前缀**(上一节)。
+3. **版本(release)挂终验期那一版**(人工在 Web 补,见 §3)。
+
+⚠️ **平台行为**:需求抽屉里,只要**该需求已关联的 Issue 全部完成**、且状态落在交付段(开发中 / 已提交 / 可测试),就会浮出一条一键「转已上线」的绿色提示条。跨期需求首期只挂了首期的 Issue,**首期一完工按钮就亮了** —— 这就是误记发生的方式,而需求侧没有「已上线」之后的第二个终态(见 §2)。Agent 写不到终态,**能做的就是把终验声明写在他会看到的地方**。
+
+## 6. 常用调用序列
+
+```
+project_list()                              → 拿 projectId（令牌白名单内）
+project_get(projectId)                      → 成员/迭代/计数/基本信息七段(summary,background,personas,
+                                              goal,nonGoals,constraints,openQuestions)
+project_update({projectId, summary, …})     → 回写基本信息七段(整段覆盖，先读后写；null 清空)
+requirement_list(projectId)                 → 看已有需求，校准粒度 + 查重
+pms_search(keyword)                         → 跨需求/Issue/TC 查重（上限 50 条，用具体词）
+requirement_get('FR-18')                    → 读某条全量（含验收标准/关联 Issue/附件）
+
+--- 用户确认后 ---
+requirement_create({projectId, title, type, category?, priority, status:'draft',
+                    description, acceptanceCriteria})   → 返回体里拿真实 key
+```
+
+PRD 到需求写入为止;UAT 场景与验收标准交给 test-plan,由它查重并创建 TC,本阶段不调用 `testcase_create`。
+
+## 7. 错误码与闸(照实报,别绕道)
+
+| 现象 | 含义 | 怎么办 |
+| --- | --- | --- |
+| `CAPABILITY_REQUIRED` | 令牌没有 `write` 能力 | 让用户在 SPMS「设置 → Agent 接入」重签带 write 的令牌(能力是签发时定死的,改不了) |
+| `PROJECT_NOT_ALLOWED` | 目标项目不在令牌白名单 | 白名单**可就地改签**(令牌列表页「项目」单元格),不必吊销重签 |
+| `PROJECT_NOT_FOUND` / `REQUIREMENT_NOT_FOUND` | 不存在,或跨租户(不泄露存在性) | 核对 projectId / key |
+| 403（需求写闸） | 需要 `spms:action:requirement.manage` **或**本项目 Lead | 报出缺什么,请用户授权;不要改去建 Issue 绕行 |
+| `FINAL_STATE_FORBIDDEN` | 想把需求写到 `shipped` / `rejected` —— 终态留给人 | 别绕道。要报的是「首期已交付,需求停在交付段,终验在 P2」,由人做需求级验收 |
+| `VALIDATION_FAILED` | 标题为空等 | 修入参 |
+| `429` / `503` | 令牌 rpm 超限 / 门户不可达(fail-closed) | 退避重试;503 时门户侧先恢复 |
+
+> 需求状态变更会通知需求作者 —— 别为了「整理」批量翻状态,会刷屏。