@xgent-ai/skills 0.6.0 → 0.7.1

package/skills/prd/SKILL.md

@@ -15,10 +15,11 @@ description: 用于撰写、修订、拆分或录入产品需求；仅评审用
 - **SPMS**(事实源):项目下的 `FR-N` / `NFR-N` 条目,带可断言的验收标准与场景预期状态。它们会进产品待办、排迭代、被拆成 Issue、被 Agent 领取修复、最终 `shipped`——**整条生命周期都挂在你写的这几条上**。用户只要文档或工具不可用时,如实交付未录入的文档。
 - **PRD 文档**(工作稿):`docs/PRD-<代号>.md`,评审的载体,也是下一步 `dev-plan` skill 的输入。
 
-**三条内容边界:**
+**内容边界:**
 
 - **产品与实现——PRD 回答 what / why / 怎样算做完。** 用户旅程、信息层级、交互反馈、视觉要求与 AI 的产品行为要设计清楚;技术方案、数据模型、端点设计、算法/模型选型、技术里程碑拆分属于 `dev-plan`。用户给定或已核实的平台技术约束写进「约束与前提」并标来源,不能据此自行扩写实现方案。即使用户要技术框架 / PoC PRD,也先写清要证明的假设、对外能力与成立判据,具体架构仍由开发计划承接。
 - **验收与测试——UAT 写不同用户场景下预期到达的状态及通过条件。** 前置条件、用户意图/业务动作、可观察结果、失败/降级状态属于 PRD;操作脚本、测试数据生成、探针、故障注入、测试工具及 TC 创建属于 `test-plan`。若评测台本身是用户要求的产品能力,定义它应提供什么报告、判定与证据,不展开用于验收该评测台的测试方案。
+- **开发验收要适配 AI Agent coding。** 用户角色与知识前提不等于招募真人;开发阶段的上手与业务场景应能由 Agent 按角色约束验证,不自行增加真人样本人数或满意度门槛。确需真人的效果指标单列公测/上线后验证;用户明确要求的真人验收门保留来源与阶段,不能用模拟冒充通过。
 - **时间边界——正文写终局,分期只在末尾。** §0–§6 用**全局视角**描述这块能力**做完之后**应该是什么样:目标写终局结果,需求条目写完整能力,一条都不许因为「这期做不完」提前砍掉或写小。**分期是交付节奏的建议,不是需求的裁剪**——所有期次安排收在最后一节(§7),等全局盘完之后一次给出。写正文时脑子里冒出「本期先只做…」,那句话属于 §7,不属于 §1/§3。
 
 每条需求都要能回答「谁在什么条件下做什么 → 应到达什么状态、满足什么判据」。数值阈值、明确枚举、存在/不存在、相等/不变都可断言;不为凑数字制造无依据的承诺。答不上来就标为开放问题,不许用漂亮话糊过去。
@@ -107,7 +108,7 @@ SPMS 的生命周期是 `产品线 → 产品 → 版本(Release) → 项目 →
 
 ```
 R1  新建 FR   → 全新能力,SPMS 内无同类
-R2  更新 FR-18 → 已存在(status=approved),本次补充验收标准第 3 条
+R2  更新 FR-18 → 已存在(status=approved),本次新增验收 FR-18/AC-3
 R3  已可用    → 平台已支持 (apps/xxx/src/...);建议撤回,待用户确认
 R4  待拍板    → 依赖「是否面向全员」的决策,已问
 ```
@@ -119,7 +120,7 @@ R4  待拍板    → 依赖「是否面向全员」的决策,已问
 - **目标**:这块能力**做完之后**要达成的**结果**(终局、满足 SMAR),不是要做的功能列表,也不是「首期做到哪」。3-5 条封顶;标清验收门槛、观察指标与 PoC 基线,不把建议值冒充现状或已验证的效果。
 - **非目标**:逐条列出并**给去向**。⚠️ **去向里不许出现「二期 / 后期再做」**——那是分期,不是非目标。凡属于这块能力终局蓝图之内的,一律写成 FR/NFR 进 §3,再到第 5 步排到靠后的期次去;非目标只留**真的不在这份 PRD 能力边界内**的东西(另立项 / 属于别的产品域 / 明确永远不做及理由 / 依赖的底座本身另立项)。**产品经理一半的价值在这张表上**——评审时会被问「那 X 呢」的,都要提前出现在这里。
 - **优先级分档**:本系统里 `priority`(紧急度) 与 `importance`(重要度) **正交**,别混为一谈;两个 MCP 都能写,**两个都要给**。
-- **依赖与前置**:依赖别的 App / 平台底座的,写明「未就绪则本条降级为 X / 推迟到 Y」,不要写成无条件承诺。
+- **依赖与前置**:只展开实际相关的外部系统、服务、数据、平台或合规前提,写清提供方、所需能力/数据、成立条件与依据、影响的需求及未就绪时的产品状态。时效、授权、可用性等只写影响验收的条件;未知且会改变产品语义的回到阻塞问题。交付推迟放 §7,不把外部依赖写成无条件承诺,也不扩写接口、库或架构选型。
 
 ## 第 4 步:逐条成文
 
@@ -129,29 +130,33 @@ R4  待拍板    → 依赖「是否面向全员」的决策,已问
 2. **先从用户视角写清问题,再写期望变化。** 问题陈述要说现在谁被什么阻碍、造成什么影响;不要把待做功能换个语序当成问题。
 3. **一条需求写它的完整能力,不写「本期版本」。** 需求是产品事实,不随交付节奏伸缩——验收标准要覆盖本 PRD 范围内这条能力**做完**该有的全部断言。「边界」写这份 PRD 的能力不含什么,可以指向已明确分工的其他 PRD,不等于整个产品永不做;「这期先不做」是分期边界,属于 §7。粒度仍按「一个用户可感知的能力」定,**不按期次切碎**:一条需求横跨两期是正常的,第 5 步会给它标终验期。
 4. **验收标准落在最高的可观察业务边界。** 每条 = 谁在什么条件下做什么 → 预期状态与通过判据。可用阈值、枚举、集合、相等/不变或明确的是/否;量化指标带作用域、规模/负载、分母/窗口等必要口径。优先断言用户或外部系统真能观察到的结果,不断言内部模块、表、函数或调用次数,不写测试过程。写不出可断言形式的,回第 1 步。
-5. **验收标准的物理格式(平台前端契约,别用 markdown)**:SPMS 把 `acceptanceCriteria` 按 `\n` 切行、trim、丢空行,渲染成圆点列表。**展示端一个字符都不剥**(剥 `- * • 1. 1)` 前缀只发生在 Web 编辑器保存时),所以经 MCP 写进去的前缀会**原样显示**。因此——**一行一条;不要写 `-`/`*`/`1.` 前缀(会显示成「• - xxx」);不要空行分段;不要表格/加粗/嵌套。** 唯一例外是跨期需求的 `[P1] ` 期次前缀(第 6 步),方括号不在剥离表里,写进去就是它。
+5. **验收用稳定标识引用,按平台格式导出。** PRD 每条需求维护「AC ID / 验收原文 / 期次」表,跨条目用 `FR-37/AC-1` 引用,不以第几行定位;编号的增删改、工作号回填及既有条目迁移见 [references/spms-mapping.md §5.2](references/spms-mapping.md#52-稳定验收标识与导出约定)。表随条目写入 `description`;`acceptanceCriteria` 只导出当前有效的验收原文,**纯文本一行一条,不带 AC ID、表格、加粗、列表前缀或空行**。跨期需求逐行加 `[P#] `,单期不加;期次在第 5 步确定后回填。平台展示端按换行拆分但不剥前缀,不要把 PRD 的表格直接塞入该字段。
 6. **PRD 正文(`description`)是完整 markdown**(markdown-it 渲染,标题/列表/表格/代码块都可以)。图片只支持 `![](xgent-attachment:<id>)` 引用且 MCP 无上传面 → **正文里不要放外链图**。
 7. **NFR 必须带 `category` + 作用域 + 可判断的质量门槛**。性能/容量用数值与条件,安全/易用性也可用明确状态或不变量;不把「安全」「美观」当判据。六档质量属性见 `references/spms-mapping.md`。
 8. **体验与 AI 要成为需求,平台硬约束也要有落点**。信息层级、主路径便捷性、视觉一致性、关键状态及适用的 AI 能力,写入相关 FR/NFR 并给验收条件,不只放在愿景里。多租户隔离、三语 i18n、列表服务端分页、业务错误、席位/计量口径、ACL 可见性等按宿主实际约束写,不默认「大家都知道」。
 9. **只持久化有价值的产品决策。** 会改变范围、领域语义或验收,或未来读者很可能重新争论的,记入「产品决策记录」:结论、未选方案、理由、影响需求。不把每轮问答都抄进去;模块/接口/架构/表结构等实现决策仍属于 dev-plan/架构决策,不进 PRD。
 10. **建立全链路可追溯关系**:原始诉求 → 问题/目标 → `S#` 场景 → FR/NFR → 验收标准 → `UAT-#` 预期状态。每个目标有需求承接,每条需求能指回目标/原始诉求,每个关键用户场景有明确状态与验收覆盖;有空白单元格就不算定稿。UAT 不要求 TC 已存在,由 test-plan 后续建立「验收/UAT → TC」映射。
 11. **不写实现方案或测试方法**(见开头边界)。
+12. **区分要求、约束与建议。** 已确认的验收承诺用「必须/不得」或明确结果句;约束注明来源、适用范围和产品影响;未采纳的提案标「建议·未纳入承诺」,不进入有效验收或分期范围。建议一旦确认采纳,转为相应 FR/NFR 与验收;影响定稿的未决选择仍按阻塞问题处理,不能靠「建议/可选」绕过。产品允许用户选择的行为可以是必须交付的能力,不要与未采纳建议混淆。
+13. **每条需求可独立理解。** 单独读取条目时,应能判断角色/权限、必要术语、行为边界、依赖成立条件、验收与相关 UAT 状态。写入 `description` 时带上必要定义、已定结论及相关场景的预期状态与判据,不能只留「同上/按讨论结果」或 PRD 章节号。外链和路径用于追溯依据,不替代关键结论;只补本条所需上下文,不复制整份 PRD。
 
 ## 第 5 步:分期交付建议(全局盘完之后才做)
 
 到这一步,PRD 正文(§0–§6)已经是一张**终局蓝图**。现在才第一次考虑「先上哪些、后上哪些」。**分期只改变交付顺序,不改变需求集合**——不许在这一步删需求、砍验收标准,或把一条需求改小;发现某条确实不该做,回第 3 步把它挪进非目标并给去向,而不是在分期表里让它消失。
 
+**期次编号固定写 `P1`、`P2`…**(P = Phase,`P1` 即第 1 期)。分期表、终验期、`[P#]` 前缀、交接说明以及下游 `dev-plan <PRD> P1` 都用同一写法;评审报告里的 `[P0]`–`[P3]` 是严重度,不是期次。
+
 1. **盘的是全局,不只是这份 PRD 新写的那几条。** 一张分期表要同时收进三类需求,既有需求用**真实 key**,未录入的新需求先用工作号并在创建后回填,逐条标出来源(既有 key 来自第 2 步的查重结果,必须是真查到的):
    - **本 PRD 新建**——第 6 步创建后回填的 `FR-N` / `NFR-N`;
-   - **既有需求·本次更新**——第 2 步命中的那些:只说明**本期要动它的哪几行验收**,不重述正文,更不新建一条并行的;若本次改变了它的终验期,在说明里点出来。
+   - **既有需求·本次更新**——第 2 步命中的那些:在分期表中只说明**本期要动它的哪些 AC ID**,不重述正文,更不新建一条并行的;若本次改变了它的终验期,在说明里点出来。
    - **既有需求·只作前置**——不属于本 PRD、但某一期必须等它先上才有意义的 key(别的 PRD / 别的项目)。写清依赖方向,**它们不归本 PRD 排期**,只出现在前置列。
 2. **一期 = 一个能独立交付的用户价值,不是一层技术栈。** 「P1 做后端、P2 做前端」不是分期,是任务拆解(那是 dev-plan 的活)。每期都要能回答:这期上线之后,**哪个角色多了什么以前做不到的事**;答不上来就把这期并掉或重新切。
-3. **每期给一条出口判据**,用这期覆盖到的验收标准行来写,措辞与 §3 原话一致,不另造说法。
+3. **每期给一条出口判据**,引用这期覆盖到的 AC ID 与 §3 验收原文,不另造说法。
 4. **每条需求都要落在分期表里,并标出「终验期」**——终验期 = **整条需求算完成**的那一期:
    - **单期需求**:终验期就是它唯一那一期。
-   - **跨期需求**(验收标准分散在两期以上):终验期 = **最后一期**,必须显式标出,并逐期写清「这期完成的是第几行验收」。跨期是正常的,**不要为了让每条都落在单期而把需求切碎**——粒度由「一个用户可感知的能力」决定,不由期次决定。
+   - **跨期需求**(验收标准分散在两期以上):终验期 = **最后一期**,必须显式标出,并逐期列出本期完成的 AC ID。跨期是正常的,**不要为了让每条都落在单期而把需求切碎**——粒度由「一个用户可感知的能力」决定,不由期次决定。
 5. **用分期承接 SMAR,不凭空指定开发日期。** 每期开发计划尽量控制在 **5–8 个 Milestone**;因同一用户流程/交付连续性不宜拆开时可到 **9–10 个**,必须说明连续性理由,**最多 10 个**。超过则建议拆成更多期;小范围可少于 5 个,不为凑数增任务。PRD 只给每期价值、覆盖范围、前置和计划规模建议,不预先编排 M1…Mn、实现任务或工期。具体拆解与数量由 dev-plan 核实,超出预算时反馈分期调整,保留完整需求与终验关系。
-6. **分期表定稿后回填两处并保持一致**:§3 每个条目的「分期」行、§7 的期次总览 / 分期矩阵 / 跨期终验登记。条目那一行是要抄进 SPMS `description` 的那份——**SPMS 里的读者看不到 PRD**,两处漂了就等于界面在说谎。
+6. **分期表定稿后回填并保持一致**:§3 每个条目的「分期」行及 AC 表的期次、§7 的期次总览 / 分期矩阵 / 跨期终验登记。条目与 AC 表都要写进 SPMS `description`——**SPMS 里的读者看不到 PRD**,两处漂了就等于界面在说谎。
 
 ## 第 6 步:写入 SPMS
 
@@ -160,6 +165,7 @@ R4  待拍板    → 依赖「是否面向全员」的决策,已问
 1. **`type` 必须先定死**。key 前缀在**创建时**按 `type` 分配(`functional`→`FR-N`,`non_functional`→`NFR-N`),序列是**租户级**的(不是项目级,所以编号跨项目连续)。**之后再改 `type`,key 不会跟着改**(平台契约)——建完再改就是永久错配。
 2. **`status` 一律 `draft`**。评审转 `reviewing`、批准转 `approved` 是**人**的动作,不是 Agent 该按的按钮(同 MCP「终态留给人」的既有姿势)。
 3. **建完立刻回填真实 key**:把 `R1 → FR-37` 写回 PRD 文档的追踪表**和 §7 的分期矩阵 / 跨期终验登记表**(第 5 步用工作号排的期,这时换成真实 key)。之后凡是指代需求实体/标题都一律用真实 key;`R#` 只作为原始诉求来源标识,仅出现在「承接」和 §6.1。
+   AC 引用同步由工作号改为真实需求 key,保留原 AC ID;写入或更新时从同一份 AC 表生成 `description` 中的表与 `acceptanceCriteria`,回读核对 ID、原文和期次的一一对应。
 4. **PRD 不创建 TC**。把关键用户场景、预期状态与验收条件随需求正文写入;若该需求已有 TC,只记录真实关联供 test-plan 查重承接,不补写步骤、不因缺 TC 阻止 PRD 定稿。用户同时要求测试计划时,在 PRD 成文后另按 test-plan 展开。
 5. **跨期需求必须在 SPMS 里自带终验声明。** PRD 文档在 SPMS 之外,而按下「转已上线」的人看的是**需求抽屉**。三处一起写,缺一处这条需求就会在某个界面上说谎:
    - **`description` 开头**固定一段(正文是 markdown,引用块会正常渲染):
@@ -184,6 +190,9 @@ R4  待拍板    → 依赖「是否面向全员」的决策,已问
    - R1…Rn 逐条有下场(新建 key / 更新 key / 已可用 / 显式排除并给去向),**一条都没吞**;
    - 六维推演有实质取舍与需求落点,产品满足 SMAR;适用的 UX/UI 与 AI 能力没有停在口号,范围仍在用户约束内;
    - 每条 FR 的验收标准 ≥1 条且**每条都能断言**;每条 NFR 有 `category` + 作用域 + 质量门槛;
+   - 要求、约束、建议含义明确,约束有来源与影响,未采纳建议没有混入验收或分期;实际依赖有成立条件、受影响需求及缺失时的产品状态;
+   - 脱离对话和整份 PRD 单读条目,角色、必要术语、边界、依赖、验收与相关 UAT 仍可理解;写入 `description` 的内容没有仅靠外部章节或「同上」才能解读的缺口;
+   - AC ID 在需求内唯一且未因增删或排序重编;追踪、UAT 与分期均引用有效 ID,停用项未混入导出;`description` 的 AC 表与 `acceptanceCriteria` 的原文、顺序、期次一致,后者无 AC ID 或 markdown;
    - 非目标表覆盖了所有「评审会被问到」的相邻功能,且**没有一条去向写着「二期 / 后期再做」**(那类应已成为 FR/NFR 并排进 §7 的靠后期次);
    - §0–§6 全篇按终局写,没有「本期先只做…」混进目标 / 行为 / 边界;
    - **每条需求(含本次更新的既有 key)在 §7 分期矩阵里都有一行,且都标了终验期**;跨期的另在 §7.3 登记,并在 SPMS 里三处齐:`description` 终验块 + `acceptanceCriteria` 逐行 `[P#]` 前缀 + 版本挂终验期;
@@ -196,12 +205,13 @@ R4  待拍板    → 依赖「是否面向全员」的决策,已问
    - 已录入需求用回填后的真实 FR/NFR key,未录入新需求明确标工作号;`R#` 只在「承接」与 §6.1 作原始诉求来源标识;
    - 引用的代码路径/既有能力都是本次真读过的(同 dev-plan 的「不虚构核实」)。
    - 阻塞 frontier 已清空,共同理解已获用户确认;仅剩的非阻塞开放问题都有默认/理由/负责人/解决节点。否则只能作为草稿,且未写入 SPMS。
-3. **汇报**给用户时,除了文档路径,单独列出:① **非阻塞开放问题**及默认/负责人/解决节点(若尚有阻塞问题,必须明说文档仅是草稿且未落库);② 调查中发现的、与用户假设**冲突的事实**;③ 你砍掉/推迟的范围(让用户有机会否决);④ **已写入 SPMS 的 key 清单**(FR/NFR)与本次回写的**项目基本信息段**(照第 0 步第 5 条的表);⑤ **待人工补**的字段(版本,以及评审后的状态流转——MCP 可写字段不列进这张清单);⑥ **分期建议**:每期交付什么用户价值、覆盖哪些 key、承接计划的 Milestone 预算及例外理由,并**逐条点名跨期需求的终验期**——「FR-38 首期完成后仍停在交付段,不得转已上线」这句话要出现在汇报里,不能只躺在文档里。
-4. **交给 dev-plan(PRD 与计划是多对多,没有固定映射)**:交接的单位是 **`FR-N`/`NFR-N` key 的集合**,不是整份文档——一份 PRD 可拆给多份计划,一份计划也可以捞起好几份 PRD 里的需求合并做。计划取它覆盖的那组 key 当 dev-plan 第 1 步的 `R1..Rn`,计划结尾的「需求 → 设计映射」表逐条指回 SPMS 实体。SPMS 侧的落点是 `plan_create(projectId, title, requirementKeys=[...])` → `PLAN-N`,正文写回走 `plan_update({content})`——`requirementKeys` 就是这层多对多关系的实体。
+3. **汇报**给用户时,除了文档路径,单独列出:① **非阻塞开放问题**及默认/负责人/解决节点(若尚有阻塞问题,必须明说文档仅是草稿且未落库);② 调查中发现的、与用户假设**冲突的事实**;③ 你砍掉/推迟的范围(让用户有机会否决);④ **已写入 SPMS 的 key 清单**(FR/NFR)与本次回写的**项目基本信息段**(照第 0 步第 5 条的表);⑤ **待人工补**的字段(版本,以及评审后的状态流转——MCP 可写字段不列进这张清单);⑥ **分期建议**:每期交付什么用户价值、覆盖哪些 key、承接计划的 Milestone 预算及例外理由,并**逐条点名跨期需求的终验期**——「FR-38 首期完成后仍停在交付段,不得转已上线」这句话要出现在汇报里,不能只躺在文档里;⑦ **下一步**:建议先用 `review-prd <PRD 路径>` 评审(可选);跳过评审或评审已通过时,用 `dev-plan <PRD 路径> P1` 出第 1 期计划,之后各期同理。命令按当前客户端的技能调用写法给出(如 Codex `$review-prd`、Claude Code `/review-prd`),路径填实际文件;仍有阻塞问题时只提示先拍板,不提示进入计划。
+4. **交给 dev-plan(PRD 与计划是多对多,没有固定映射)**:交接的单位是 **`FR-N`/`NFR-N` key 的集合**,不是整份文档——一份 PRD 可拆给多份计划,一份计划也可以捞起好几份 PRD 里的需求合并做。按期次交接时用 `dev-plan <PRD 路径> P<n>`,计划据 §7.2 取该期的 key 与 AC ID,并在计划头部记录来源 PRD 与期次。计划取它覆盖的那组 key 当 dev-plan 第 1 步的 `R1..Rn`,计划结尾的「需求 → 设计映射」表逐条指回 SPMS 实体。SPMS 侧的落点是 `plan_create(projectId, title, requirementKeys=[...])` → `PLAN-N`,正文写回走 `plan_update({content})`——`requirementKeys` 就是这层多对多关系的实体。
+   随需求 key 交接 AC ID、验收原文和期次映射,下游引用 `需求 key/AC ID`,不把平台展示行号当稳定标识。
    ⚠️ **一个 `PLAN-N` 只能挂同一项目的需求**:`requirementKeys` 里出现别的项目的 key 会被拒(报 `LIFECYCLE_MISMATCH`,平台契约)。跨项目的需求要合并做,只能一个项目一份计划,或先把需求迁到同一项目。
    ⚠️ **终验期必须随 key 一起交出去**:一份只覆盖 P1 的计划,里程碑全绿也**不代表**其中的跨期需求可以置「已上线」。交接说明里逐条写清「本计划完成后 FR-38 仍停在交付段,终验在 P2」——否则计划验收那一刻就会有人去点那个按钮。
    **怎么拆解是 dev-plan 的判断**(技术依赖、里程碑、可交付性);PRD 的 §7 分期给的是**产品侧信号**与**每期 5–8 个、连续性例外最多 10 个 Milestone 的计划规模要求**,不是技术任务表。调整期次时同步更新验收分配和终验声明,不能仅在计划中悄悄提前终验。
-   **交给 test-plan**:同一组需求 key + 逐行验收标准 + UAT 场景预期状态 + 外部前置;由它选择测试方法、补齐数据/步骤/工具、查重并创建 TC。PRD 可在尚无 TC 时独立成立。
+   **交给 test-plan**:同一组需求 key + AC ID/验收原文/期次映射 + UAT 场景预期状态 + 外部前置;由它选择测试方法、补齐数据/步骤/工具、查重并创建 TC。PRD 可在尚无 TC 时独立成立。
 
 ## 红线(任何情况下不违反)
 
@@ -226,7 +236,7 @@ R4  待拍板    → 依赖「是否面向全员」的决策,已问
 
 - **SPMS 接入**:MCP 工具 `mcp__xgent-pms__*`(`project_list`/`project_get`/`project_update`/`pms_search`/`requirement_*`)。契约与错误码见 `docs/pms-mcp.md`;字段/枚举/写面缺口速查见 `references/spms-mapping.md`。
 - **文档落盘**:PRD → `docs/PRD-<大写代号>.md`(代号按能力域取);下游开发计划 → `goal/<大写代号>.md`(dev-plan skill,模板 `goal/PLAN-TEMPLATE.md`)。**两侧代号互不绑定**——PRD : 计划是**多对多**(既拆也合),靠 `FR-N`/`NFR-N` key 串联(SPMS 侧即 `plan_create(requirementKeys)`,同项目内)。
-- **平台硬约束**(需求侧口径,该进 NFR 就进):多租户隔离(全表 `tenantId`);业务状态一律 200 + `{ok,data}`;列表服务端分页 `Page<T>`;三语 i18n(zh-CN/en/zh-TW);字典表 `sort` 规范;前端两步法(`impeccable` 设计 + 真浏览器验证)。
+- **平台硬约束**(需求侧口径,该进 NFR 就进):多租户隔离(全表 `tenantId`);业务状态一律 200 + `{ok,data}`;列表服务端分页 `Page<T>`;三语 i18n(zh-CN/en/zh-TW);字典表 `sort` 规范;前端两步法(`phoenix-ui` 设计 + 真浏览器验证)。
 - **已知坑来源**:当前 agent 提供的本项目记忆(若有,先看 `MEMORY.md` 索引)、根 `CLAUDE.md`、`goal/*-PROGRESS.md`。
 - **下游**:PRD 定稿后接 `dev-plan` skill 出开发计划,再由计划拆 Issue 进迭代;接 `test-plan` skill 将场景状态与验收条件展开为测试用例。
 

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

@@ -48,6 +48,7 @@
 | <创新性 / 先进性 / 可用性 / 便捷体验 / 美观 UI / AI 赋能> | <比现状或常规方案改善什么,不只罗列功能> | <约束内为何这样选;重要未选方案与理由> | <FR/NFR key> |
 
 > 六个维度都考虑,有实质落点的可合并;不适用则说明理由,不为了填表增加能力。具体推演见 product-quality.md。重要取舍记录在 §5.1,这里保留方向及关联,不重复决策全文。
+> 要求、约束和建议须区分:已确认承诺用「必须/不得」或明确结果句;约束在 §4 标来源与影响。尚未采纳的提案标「建议·未纳入承诺」,需求落点写「无」,不进入有效验收或 §7 范围;影响定稿的未决选择仍列 §5.2 阻塞问题。已采纳建议改写为需求,不继续用「可选」模糊承诺。
 
 ## 2. 领域语言、用户与场景
 
@@ -80,7 +81,7 @@
 
 | 入口/任务 | 默认信息与主操作 | 渐进展示与状态反馈 | 视觉要求及验收落点 |
 | --- | --- | --- | --- |
-| <主用户旅程的入口> | <用户首眼要理解什么、下一步做什么> | <哪些详情按需展开;成功/空/失败时的反馈及恢复> | <信息主次、排版/密度/视觉一致性、相关窗口要求;FR/NFR key 与验收行> |
+| <主用户旅程的入口> | <用户首眼要理解什么、下一步做什么> | <哪些详情按需展开;成功/空/失败时的反馈及恢复> | <信息主次、排版/密度/视觉一致性、相关窗口要求;需求 key/AC ID> |
 
 > 从首次使用、日常效率和异常恢复设计;美观须有可核对的要求,不只写「现代 UI」或可访问性。沿用宿主设计规范,不在这里指定 CSS/组件实现;无界面产品说明不适用。适用的 AI 能力在相关 FR 中明确触发、输出、用户控制、质量判据和降级状态。
 
@@ -89,6 +90,8 @@
 > 每条一小节。SPMS key 在创建后回填;**已录入的需求标题和实体引用必须使用真实 FR/NFR key**。未录入的新需求明确标工作号。`R#` 不是需求编号,只在「承接」和 §6.1 作原始诉求来源标识。
 > FR 与 NFR 分开成组（对应 SPMS 的「功能性 / 非功能性」分组）。
 > **每条按完整能力写**——验收标准覆盖本 PRD 范围内这条能力**做完**该有的全部断言,不写「本期版本」。「分期」行是 §7 定稿后回填的,不是写作时先定的。
+> 每条可独立理解:角色/权限、必要术语、约束、依赖和相关 UAT 的已定结论随条目写入 SPMS `description`,不只留「同上」、对话引用或 PRD 章节号;只补理解本条所需内容。
+> AC ID 在需求内稳定,跨条目用 `需求 key/AC ID` 引用。增删和排序不重编旧号,停用/替代关系记在表后;已有稳定 ID 沿用。编号、迁移及导出规则见 spms-mapping.md §5.2。期次列在 §7 定稿后回填,文档未录入时使用工作号。
 
 ### FR-<N> <标题（动宾短语，一眼看出用户能做什么）>
 
@@ -98,19 +101,20 @@
 - **背景**：<为什么需要这条，一两句>
 - **行为**：<谁在什么场景下能做什么。用户可感知的能力，不写实现。**按完整能力写**，不写「本期先只做…」>
 - **边界**：<本 PRD 能力范围不含什么,其他 PRD 的已明确分工可写去向;容易被误解的地方在这里说明。「这期先不做」写 §7>
-- **依赖**：<依赖别的 App/底座的写明；「未就绪则降级为 X」>
-- **验收标准**（→ SPMS `acceptanceCriteria`,一行一条、无 markdown 语法;断言用户/外部系统可观察的业务结果,不断言内部实现;**跨期需求逐行加 `[P#]` 前缀,单期需求不加**）：
+- **依赖**：<提供方及所需能力/数据;成立条件与依据;未就绪时本条的产品状态。无则写「无」>
+- **验收标准**（表随条目写入 `description`;`acceptanceCriteria` 按表序仅导出有效验收原文,纯文本一行一条,不带 AC ID 或表格;**跨期逐行加 `[P#]` 前缀,单期不加**）：
 
-```
-<角色>在<条件>下<业务动作>后，<预期状态 + 清晰判据;数值指标附必要口径>
-<边界条件：为空/超限/无权限时的行为>
-<可观测的落点：列表出现该行 / 通知送达 / 审计留痕>
-```
+| AC ID | 验收原文 | 期次 |
+| --- | --- | --- |
+| AC-1 | <角色>在<条件>下<业务动作>后，<预期状态 + 清晰判据;数值指标附必要口径> | <P#> |
+| AC-2 | <相关边界条件：为空/超限/无权限时的可观察结果> | <P#> |
+
+> 每格验收原文是一条无 markdown 的完整断言,不写内部实现或测试步骤。有停用项才在表后记录旧 ID、理由与替代 ID（若有）,不混入有效验收表。
 
 > **仅跨期需求**：这条抄进 SPMS `description` 的开头（SPMS 里的读者看不到 PRD，PRD 条目里也留一份）——
 > `> **分期与终验**：本需求跨 P1 / P2 交付，**终验期 = P2**。P1 完成后请停在交付段（已提交 / 可测试），**不要转「已上线」**——「已上线」是整条需求的验收，不是某一期的完工。`
 
-- **UAT 场景**：UAT-<#>；对应 S<#> / 验收第 <#> 行；预期状态与通过条件见 §6.3
+- **UAT 场景**：UAT-<#>；对应 S<#> / <需求 key>/AC-<#>；<角色与前置 → 业务动作 → 预期状态与通过条件;写本条所需内容,与 §6.3 同口径,随条目写入 `description`>
 
 ### NFR-<N> <标题（质量属性 + 约束对象）>
 
@@ -120,20 +124,23 @@
 - **分期**：<P#｜跨期写「P1 / P2，**终验期 P2**」>（§7 定稿后回填）
 - **重要度**：`critical|high|medium|low|none`
 - **约束**：<作用域与质量门槛。性能/容量带数值与条件,其他属性也可用明确状态或不变量;不写测试工具/步骤。示例阈值不能当成项目已确认承诺>
-- **验收标准**（同上格式，一行一条）：
+- **依赖**：<提供方及所需能力/数据;成立条件与依据;缺失时的产品状态。无则写「无」>
+- **验收标准**（同 FR 的 AC 表与导出规则）：
 
-```
-<可判断的结果/不变量;数值指标附作用域和必要条件>
-```
+| AC ID | 验收原文 | 期次 |
+| --- | --- | --- |
+| AC-1 | <可判断的结果/不变量;数值指标附作用域和必要条件> | <P#> |
 
-- **UAT 场景**：UAT-<#> …；覆盖 S<#> / 验收第 <#> 行
+- **UAT 场景**：UAT-<#>；覆盖 S<#> / <需求 key>/AC-<#>；<角色与前置 → 业务动作 → 预期状态与通过条件;与 §6.3 同口径,随条目写入 `description`>
 
 ## 4. 约束与前提
 
-- **用户给定的约束**：<来源明确,仅读过原话才加引号;技术选型作为已给定约束留在本节,不扩写实现设计>
-- **平台硬约束**：<多租户隔离 / 业务错误 200 / 列表服务端分页 / 三语 i18n / 席位与计量 / ACL 可见性——命中哪条写哪条，并说明对本期的具体影响>
+- **用户给定的约束**：<来源、适用范围及受影响需求;仅读过原话才加引号;技术选型作为已给定约束留在本节,不扩写实现设计>
+- **平台硬约束**：<多租户隔离 / 业务错误 200 / 列表服务端分页 / 三语 i18n / 席位与计量 / ACL 可见性——命中哪条写哪条,注明来源、适用范围与受影响需求>
 - **既有决策约束**：<相关 ADR/决策记录中对用户可观察行为的约束 + 出处;不抄实现方案。无则写「无」>
-- **前置依赖**：<某 App 或底座就绪与否，未就绪时的降级方案>
+- **前置依赖**：<提供方 → 所需能力/数据 → 成立条件与依据 → 影响的需求 → 未就绪时的产品状态>
+
+> 只展开实际相关的系统、服务、数据、平台或合规前提,不机械填全分类。授权、数据时效或服务可用性影响验收时写清条件;未知且影响语义的进阻塞问题,不虚构 SLA。交付推迟写 §7;库、接口和架构选择留给 dev-plan。
 
 ## 5. 产品决策与开放问题
 
@@ -160,7 +167,7 @@
 | 原始诉求 | 下场 | 落点 |
 | --- | --- | --- |
 | R1 <用户原话摘要> | 新建 | FR-37 |
-| R2 … | 更新既有 | FR-18（补验收标准第 3 条） |
+| R2 … | 更新既有 | FR-18（新增 FR-18/AC-3） |
 | R3′ … | 排到靠后期次 | FR-40（终局能力之内；§7 排在 P2） |
 | R3 … | 已可用 | <既有能力 + 路径>；建议撤回，待确认 |
 | R4 … | 显式排除 | 非目标 N2（另立项） |
@@ -171,8 +178,8 @@
 
 | 目标 | 场景 | 承接需求 | 验收落点 | UAT 场景 |
 | --- | --- | --- | --- | --- |
-| G1 | S1 | FR-37 | 验收第 1–2 行 | UAT-1 |
-| G2 | S2 / S3 | FR-38 / NFR-9 | 各条验收第 1 行 | UAT-2 / UAT-3 |
+| G1 | S1 | FR-37 | FR-37/AC-1、FR-37/AC-2 | UAT-1 |
+| G2 | S2 / S3 | FR-38 / NFR-9 | FR-38/AC-1、NFR-9/AC-1 | UAT-2 / UAT-3 |
 
 > 每个目标有需求承接,每条需求能指回目标/原始诉求,每个关键用户场景有预期状态与验收覆盖。任一格为空就不算定稿;不要求 TC 已存在。
 
@@ -180,41 +187,44 @@
 
 | UAT | 角色、前置与场景 | 用户意图/业务动作 | 预期状态 | 通过条件 | 需求与验收落点 |
 | --- | --- | --- | --- | --- | --- |
-| UAT-1 | <角色 + 初始状态;S1> | <业务动作,不写点击/调用脚本> | <结果是否可用、显示什么、允许的下一步、数据是否变化> | <无歧义的是/否、枚举、相等/不变或阈值与口径> | <FR/NFR key + 验收行> |
+| UAT-1 | <角色 + 初始状态;S1> | <业务动作,不写点击/调用脚本> | <结果是否可用、显示什么、允许的下一步、数据是否变化> | <无歧义的是/否、枚举、相等/不变或阈值与口径> | <需求 key/AC ID> |
 | UAT-2 | <相关的空数据/无权/冲突/取消/失败/AI 降级场景> | … | … | … | … |
 
+> 角色与知识前提是场景约束,不是招募要求。开发验收默认由 Agent 按这些约束验证,不自行增设真人样本数/满意度门槛;确需真人的指标单列公测或上线后验证,保留用户明确指定的验收阶段。具体模拟方法交下游计划。
+
 > 只展开影响本产品的状态,不机械全枚举;通过条件引用 §3 的同一口径,不另造门槛。这里不写账号准备、造数、执行步骤、测试工具、探针或注入方法;交 test-plan 再展开。已有 TC 可在交接中引用真实 key,PRD 不创建 TC。
 
 ## 7. 分期交付建议
 
 > **全篇唯一谈交付节奏的地方**——§0–§6 一律按终局写。分期只改变顺序，**不改变需求集合**：这里不删需求、不砍验收标准、不把需求改小。
-> 期次是产品侧建议,技术拆解由 dev-plan 判断。每期开发计划尽量控制在 **5–8 个 Milestone**,因交付连续性可为 **9–10 个**并说明理由,**最多 10 个**;小范围可更少,不凑数。这里只给规模预算,不列 M1…Mn 的实现任务或编造工期;实际超出时反馈拆期并同步完整终验关系。**「终验期」是整条需求何时算完成的口径**,不能只在下游计划里提前。
+> 期次统一写 `P1`、`P2`…(P = Phase,即第 1、2 期),与下游按期出计划的参数一致。期次是产品侧建议,技术拆解由 dev-plan 判断。每期开发计划尽量控制在 **5–8 个 Milestone**,因交付连续性可为 **9–10 个**并说明理由,**最多 10 个**;小范围可更少,不凑数。这里只给规模预算,不列 M1…Mn 的实现任务或编造工期;实际超出时反馈拆期并同步完整终验关系。**「终验期」是整条需求何时算完成的口径**,不能只在下游计划里提前。
 
 ### 7.1 期次总览
 
-| 期次 | 这期上线后，哪个角色多了什么以前做不到的事 | 出口判据（引用 §3 验收原话） | 前置 | 开发计划规模建议 |
+| 期次 | 这期上线后，哪个角色多了什么以前做不到的事 | 出口判据（AC ID + §3 验收原话） | 前置 | 开发计划规模建议 |
 | --- | --- | --- | --- | --- |
-| P1 | <一个能独立交付的用户价值；不是「先做后端」这类技术栈切法> | <这期覆盖到的验收标准行> | <无 / 等某底座就绪 / 等某既有 key 先上> | <5–8 个 Milestone;由 dev-plan 核实> |
+| P1 | <一个能独立交付的用户价值；不是「先做后端」这类技术栈切法> | <需求 key/AC ID + 验收原文> | <无 / 等某底座就绪 / 等某既有 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** | 只动这一行，正文不重述；本次未改变它原有的终验口径 |
+| FR-37 | 本 PRD 新建 | AC-1、AC-2 | — | **P1** | 单期完成 |
+| FR-38 | 本 PRD 新建 | AC-1 | AC-2、AC-3、AC-4 | **P2** | **跨期**；P1 完成后不得转「已上线」，见 §7.3 |
+| FR-18 | 既有 · 本次更新 | — | 新增 AC-3 | **P2** | 本表只列本次变更,其余有效验收沿用既有映射;本次未改变它原有的终验口径 |
 | NFR-9 | 本 PRD 新建 | — | 全部 | **P2** | 依赖 X 底座就绪 |
 | FR-41 | 既有 · 别的 PRD（`docs/PRD-B.md`） | 前置 | — | 不归本 PRD | P1 等它先上；本 PRD 不排它的期 |
 
 > **「来源」标签固定用这几种**：本 PRD 新建 / 既有 · 本次更新 / 既有 · 别的 PRD（只作前置） / 既有 · 别的项目（只作前置）。
 > 既有 key 必须是查重时**真命中**的（§6.1 有据），不许编造；未录入新需求用工作号并在创建后回填。只作前置的那些不占本 PRD 的终验期。
+> 同一行已有需求 key 时可简写 AC ID;跨行或交接时写完整的 `需求 key/AC ID`。与 §3 AC 表的期次同步,不按展示行号定位。
 
 ### 7.3 跨期需求终验登记（只列跨期的；没有就写「本期无跨期需求」）
 
-| 需求 | 涉及期次 | 各期完成哪几行验收 | **终验期** | 首期完成后的正确状态 |
+| 需求 | 涉及期次 | 各期完成的 AC ID | **终验期** | 首期完成后的正确状态 |
 | --- | --- | --- | --- | --- |
-| FR-38 | P1 / P2 | P1：第 1 行；P2：第 2–4 行 | **P2** | 停在「已提交 / 可测试」，**不转「已上线」** |
+| FR-38 | P1 / P2 | P1：AC-1；P2：AC-2、AC-3、AC-4 | **P2** | 停在「已提交 / 可测试」，**不转「已上线」** |
 
 > 每条跨期需求要在**三处**都说得一样，缺一处就会有界面在说谎：① 本表；② 该需求 SPMS `description` 开头的「分期与终验」块；③ `acceptanceCriteria` 逐行的 `[P1]` / `[P2]` 前缀。
 > 另：跨期需求的**版本（release）挂终验期那一版**（人工在 Web 补）——`releaseId` 是单值字段，挂首期会让版本报表把整条需求算成那一版已交付。
@@ -222,7 +232,8 @@
 
 ### 7.4 交给 dev-plan
 
-- 交接单位是 **`FR-N` / `NFR-N` key 的集合**，不是整份文档。**PRD : 计划多对多**——可拆给多份计划，也可与别的 PRD 的需求合并进同一份。
+- 交接单位是 **`FR-N` / `NFR-N` key 的集合**，不是整份文档。**PRD : 计划多对多**——可拆给多份计划，也可与别的 PRD 的需求合并进同一份。按期次出计划时以 `dev-plan <PRD 路径> P<n>` 交接，计划头部记录来源 PRD 与期次。
+- 随 key 交接 AC ID、验收原文与期次映射,计划按 `需求 key/AC ID` 引用;既有行号引用尚未同步的列明受影响文档,不宣称已迁移。
 - **终验期随 key 一起交出去**：逐条写明「本计划完成后 FR-38 仍停在交付段，终验在 P2」——只覆盖 P1 的计划里程碑全绿，也不代表跨期需求可以置「已上线」。
 - SPMS 侧落点 `plan_create(projectId, title, requirementKeys=[…])` → `PLAN-N`；⚠️ 一个 `PLAN-N` 只能挂**同一项目**的需求。
 - <若某条与另一份 PRD 的需求天然同批，点名：与 `docs/PRD-B.md` 的 FR-41 动同一块，建议合并一份计划>
@@ -230,7 +241,7 @@
 
 ### 7.5 交给 test-plan
 
-- 交接需求 key、逐行验收标准、§6.3 UAT 状态与前置依赖。测试计划负责测试方法、数据、步骤、工具、查重及 TC 创建;不得到测试阶段才补决定产品状态。
+- 交接需求 key、AC ID/验收原文/期次映射、§6.3 UAT 状态与前置依赖。测试计划按 `需求 key/AC ID` 引用,负责测试方法、数据、步骤、工具、查重及 TC 创建;不得到测试阶段才补决定产品状态。
 - <已有 TC 才列真实关联,无则写「尚未设计测试用例」;不把无 TC 写成 PRD 阻塞>
 
 ## 8. SPMS 落库结果
@@ -270,6 +281,10 @@
 | 决策只留在对话 | 结论有了,但后来人不知道为什么 | 在 §5.1 只记录会影响范围/语义/验收的产品决策 |
 | 阻塞问题伪装成默认 | 答案会改需求,但文档仍定稿/落库 | 保留在 frontier;未拍板只能交草稿,不写 SPMS |
 | 追踪链断了 | 目标无需求、场景无预期状态或验收 | 补齐 §6.2–6.3;无 TC 不影响 PRD 成立 |
+| 建议变成承诺 | 未采纳提案混入有效验收或分期范围 | 标明建议状态,确认采纳后才转为需求;阻塞选择不得绕过 |
+| 条目依赖外部上下文 | 只写「同上/按讨论结果」或 PRD 章节号 | 在条目中补必要定义、已定结论和相关 UAT 状态,随正文落库 |
+| 验收引用漂移 | 插入一行后 UAT/分期指向另一条验收 | 用稳定 AC ID,同步有效映射与停用关系;导出纯文本不带 ID |
+| 外部依赖是名称清单 | 只写「依赖某服务」却无成立条件 | 补提供方、所需能力/数据、成立条件与依据、影响需求和缺失时产品状态 |
 | 验收盯内部实现 | 断言表/函数/内部调用次数 | 改为用户或外部系统可观察的最高业务边界 |
 | 分期混进正文 | 目标/行为/边界里出现「本期先只做…」「二期再说」 | §0–§6 按终局写;所有期次安排收进 §7 |
 | 非目标当分期用 | 非目标去向写「二期 / 后期再做」 | 属于终局蓝图的挪回 §3 成为 FR/NFR,在 §7 排到靠后期次 |

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

@@ -57,11 +57,13 @@ Measurable 不等于每行硬塞数字。明确的枚举、结果集合、是/
 
 区分三类口径:产品验收门槛、上线后观察指标、PoC 比较基线。数值来自用户/既有约束则给来源;新提出的门槛标为产品提案并确认,不声称已实测,不把基线当效果承诺。
 
+**开发验收与真实用户验证分开。** 默认 AI Agent coding,开发阶段不自行要求招募真人、收集真人满意度或凑样本人数。将「新手也能用」写成角色、知识前提、可用资料与可观察完成状态,供下游按角色约束模拟验证。确需真人的可用性/效果指标单列公测或上线后验证,不默认作为开发里程碑退出条件;用户已明确要求的真人门槛保留来源、阶段与资源前置,不能擅自改为模拟。
+
 不用 Time-bound 为 AI 开发编造工期或发布日期。以独立用户价值切期,每期开发计划建议 5–8 个 Milestone;连续性例外可为 9–10 个并说明理由,最多 10 个。PRD 表达规模预算,dev-plan 核实并拆解;小任务可更少,超出则反馈拆期,不能删掉完整验收。已有外部日期约束仍须尊重,性能时延、超时、有效期和观察窗口也不能被删除。
 
 ## 5. UAT 写预期状态,不写测试程序
 
-每个重要用户场景写清「角色与前置状态 → 业务意图/动作 → 预期状态 → 清晰的通过条件」,关联真实需求 key 与验收行。只覆盖相关状态:成功、空数据、拒绝、重复/冲突、取消、失败/恢复、AI 不确定/降级。状态包括结果是否可用、显示的解释、允许的下一步和数据是否改变;不能只写一句提示文案。
+每个重要用户场景写清「角色与前置状态 → 业务意图/动作 → 预期状态 → 清晰的通过条件」,关联需求 key 与稳定 AC ID（未录入时用工作号,不以展示行号定位）。只覆盖相关状态:成功、空数据、拒绝、重复/冲突、取消、失败/恢复、AI 不确定/降级。状态包括结果是否可用、显示的解释、允许的下一步和数据是否改变;不能只写一句提示文案。
 
 以下为写法示例,不预设具体项目承诺:
 
@@ -72,6 +74,7 @@ Measurable 不等于每行硬塞数字。明确的枚举、结果集合、是/
 | 维护者,AI 给出资料建议 | 拒绝建议 | 正式资料和原始内容保持不变;建议不进入正式分发 |
 | 成员,已有本地内容 | 取消升级 | 原内容与选定版本不变;不显示升级成功 |
 | 成员,AI 增强不可用 | 搜索 | 可用基本结果且模式明确,用户仍可继续任务;不显示增强成功 |
+| 首次使用者,不掌握 Rust,仅有公开快速入门与示例 | 完成示例任务 | 获得可运行结果,不需自行编写或修改 Rust 源码;失败时提供可执行的恢复说明 |
 
 定稿检查三件事:每条需求有可判断的验收;每个关键用户场景有预期状态与通过条件;目标/场景/需求/验收/UAT 相互可追踪。此时无需已存在 TC。测试计划随后决定账号、数据、执行步骤、工具、故障模拟和完整覆盖,不能在写测试计划时才首次决定产品应到达什么状态。
 

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

@@ -8,15 +8,15 @@
 | --- | --- | --- |
 | §0 一句话 | `projects.summary`（概述） | `project_update`(FR-236);**整段覆盖,先 `project_get` 读现状** |
 | §1.1 问题陈述与现状 | `projects.background`（背景） | 同上 |
-| §2.2–2.3 用户与场景 | `projects.personas`（用户与场景） | 同上;§2.1 领域语言只留在 PRD 文档,不混入 `personas` |
+| §2.2–2.3 用户与场景 | `projects.personas`（用户与场景） | 同上;§2.1 领域语言不混入 `personas`,条目必需的定义随其写入 `description` |
 | §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 标签「验收标准」) | **纯文本,一行一条** |
+| 条目正文 | `requirements.description`（UI 标签「PRD 描述」) | 完整 markdown;含独立理解所需上下文与 AC 表（见 §5.2） |
+| 验收标准 | `requirements.acceptanceCriteria`（UI 标签「验收标准」) | 从 AC 表导出有效验收原文,**纯文本,一行一条,不带 AC ID**;跨期加 `[P#]` |
 | §6.3 UAT 场景预期状态 | **无独立字段** | 文档保留全局状态表,相关场景与判据写入对应需求 `description`;PRD 不创建 TC,由 test-plan 后续展开 |
 | §7 分期交付建议 | **无独立字段** | 分期本身只留在 PRD 文档;**跨期需求的终验声明**要落进该需求的 `description` 开头 + `acceptanceCriteria` 逐行 `[P#]` 前缀(见 §5),版本(release)人工挂**终验期**那一版 |
 | §8 SPMS 落库结果 | — | 记录本次真实写入的 key 与待人工补字段;有阻塞问题时改写「未写入」 |
@@ -117,6 +117,29 @@
 
 ⚠️ **平台行为**:需求抽屉里,只要**该需求已关联的 Issue 全部完成**、且状态落在交付段(开发中 / 已提交 / 可测试),就会浮出一条一键「转已上线」的绿色提示条。跨期需求首期只挂了首期的 Issue,**首期一完工按钮就亮了** —— 这就是误记发生的方式,而需求侧没有「已上线」之后的第二个终态(见 §2)。Agent 写不到终态,**能做的就是把终验声明写在他会看到的地方**。
 
+### 5.2 稳定验收标识与导出约定
+
+**本节是 PRD 写作约定,不是 SPMS 新增字段或平台分配的 key。** 每条需求的有效验收用「AC ID / 验收原文 / 期次」表维护,PRD 与该需求的 `description` 保留同一张表。需求内从 `AC-1` 递增,跨条目引用完整的 `FR-37/AC-1` 或 `NFR-9/AC-1`;工作稿先用 `WORK-F1/AC-1`,落库后只替换需求 key,不改 AC ID。
+
+- 增加验收用未用过的新号,插入或排序不重编旧号。纯措辞修正保留 ID;已确认的判定含义改变、拆分或合并则分配新号,在表后简记旧号的停用/替代关系及理由。停用号不复用、不参与当前验收或导出,并更新受影响的 UAT、分期及交接引用;需求语义变化仍走原有澄清与确认流程。
+- 既有条目已有稳定 ID 则沿用;没有时仅为本次涉及的需求补齐映射。先读当前完整验收与正文,为保留的每条验收分配 ID,同步本次维护范围内的行号引用;范围外已知下游引用列入交接待同步项,不宣称已迁移。无法确定旧引用指向哪条时先核对,不按新行号猜测。
+- 期次由 §7 确定后回填;AC 表只列有效验收,每项为一条无 markdown 的完整结果句。写库时按表序提取验收原文,跨期加对应 `[P#] `,单期只取原文,再以换行拼成 `acceptanceCriteria`。不导出表头、AC ID、停用说明或其他列,不另写一套验收措辞。
+- 更新 SPMS 前先读回现状,核对原文及映射有无他人修改;有不一致先核清,不能用旧 PRD 覆盖。写入后回读确认 `description` 表格与 `acceptanceCriteria` 一一对应。下游从表中找 ID 和原文,行号仅是当前展示位置。
+
+示例（仅说明映射格式,不预设项目承诺）:
+
+| AC ID | 验收原文 | 期次 |
+| --- | --- | --- |
+| AC-1 | 管理员完成安装后,应用出现在其导航中 | P1 |
+| AC-3 | 管理员取消配置变更后,原配置保持不变 | P2 |
+
+如 AC-2 已确认取消,在表后记录「AC-2 已停用:对应能力经确认移出本 PRD,见范围决策」,不把 AC-3 改成 AC-2。上述跨期示例导出为:
+
+```text
+[P1] 管理员完成安装后,应用出现在其导航中
+[P2] 管理员取消配置变更后,原配置保持不变
+```
+
 ## 6. 常用调用序列
 
 ```

package/skills/resolve-blocked/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: resolve-blocked
+argument-hint: "<计划路径/链接> [评审报告] [阻塞项/范围] [决策记录路径]"
+description: 用于解除开发计划中 Blocked/阻塞/待拍板事项；不用于从零写计划、整体评审或按计划实施。逐项讲清上下文，先查证再交互确认并给推荐，存 decisions 文档并回改计划。
+---
+
+# resolve-blocked · 逐项解除开发计划阻塞
+
+目标是让被阻塞的开发计划重新可实施：**列出全部阻塞事项，逐项讲清上下文；能用证据解除的自己查证，需要拍板的用交互问答获得用户确认，并附推荐方案与理由。** 结论存为独立决策记录，解决方式改进计划正文，按修订后的真实前置重判就绪状态。
+
+调用本技能即授权：写入计划同目录的决策记录，并修订计划中与已解除阻塞相关的内容。代码、PRD、评审报告和实施记录默认只读。用户明确要求仅聊天、只列清单或不改计划时遵循其要求。
+
+`references/` 相对本文件解析。仓库规则、技术栈和工具能力在运行时读取，不硬编码目标仓的路径或业务约定。回复语言跟随用户。
+
+## 边界
+
+- 从零写或重写计划用 `dev-plan`；评审计划整体质量用 `review-dev-plan`；落实评审报告的全部意见用 `apply-doc-review`。本技能只处理**阻塞实施**的事项；评审报告里的非阻塞问题保留给 `apply-doc-review`，不顺手改。
+- 不实施功能、不跑迁移/部署或有副作用的命令、不写外部系统。需要 spike、实测、外部账号或第三方答复才能解除的阻塞，本次只写清解除条件、负责人和最晚确认点，不伪装成已解除。
+- 计划里的陈述是待核实主张。“已核实”“用户已确认”须能在原文、代码或用户原话中找到依据，否则当作未决。
+- 若能找到 `dev-plan`，读取其 `SKILL.md` 的计划状态与红线部分及 `references/plan-skeleton.md`，据此判断各类结论落在计划哪一节；复杂架构取舍按需读 `references/architecture-quality.md`。找不到时按计划自身结构落点。用户自定义模板或历史计划不因章节名不同而强行迁移。
+
+## 1. 锚定输入与基线
+
+1. 定位计划。未指定且无法唯一确定时询问，不擅自挑一份相邻计划。读取适用的 `AGENTS.md`/`CLAUDE.md` 等规则、计划全文、计划关联的 PRD 与关键决策。只读到截断内容时补读后再引用。
+2. 计划是阻塞事项的事实源：评审意见通常已经 apply 进计划，不必默认查找评审报告。用户指定了报告时读取；否则只在需要时回读，例如某个阻塞项在计划中缺少来由或证据、顶部 `Blocked` 的理由在计划里找不到对应项、计划引用了某条评审结论。回读时用计划引用或同目录中「评审对象」指向本计划的报告，优先看其处置节里仍待决的项；多份候选无法确定时询问，不按文件时间猜选。报告中已处置的意见以计划当前内容为准，不重新当作阻塞。
+3. 记录基线：计划路径与内容 hash、代码 commit 与 dirty 状态、日期。
+4. 读取 [references/decisions-contract.md](references/decisions-contract.md) 确定决策记录路径。记录已存在说明不是第一轮，按下节「重复运行同一计划」续做：已确认的决定不重复提问，沿用已有 B-ID 续写。
+
+## 重复运行同一计划
+
+同一计划可多次运行本技能，直到 `Ready`。每次运行是一轮，在同一份决策记录续写，不另建文件：
+
+- 先读决策记录的处理轮次与阻塞总览，比较计划当前 hash 与上轮处理后版本。有变化时找出改动段落（用户改稿、评审处置或实施回写），核对已解除项的计划落点是否仍在；被删改或推翻的项重新打开并写明依据。
+- 上轮仍阻塞的项逐项核对解除条件是否已满足：外部答复、账号/配额、spike 或实测结果、用户补充的信息。满足则按本流程解除；未满足保持仍阻塞，不重复追问用户已明确要等的事项。用户上轮未作答或选择稍后决定的决策项，本轮重新给出上下文再问。
+- 计划新增或新暴露的阻塞分配未占用的 B-ID，与遗留项一起列入本轮总览，并标出哪些是新增、重开或遗留。
+- 计划、遗留项的解除条件和外部情况都没有变化时，只回复剩余阻塞及各自的解除条件，不改写计划或记录、不新增轮次，也不重复记 SDLC 事件。
+
+## 2. 收集并分类阻塞
+
+从计划中收集（dev-plan 骨架的常见位置，其他模板找等价内容）：
+
+- 顶部状态为 `Blocked` 时的定级理由，§11 风险/开放问题中「是否阻塞=是」的行；
+- 需求账本中状态为「阻塞」的 `NFR-*`/`A-*`，以及值为「未知」但会改变关键决策的数字；
+- 事实清单的 `[未核实·阻塞]` 与契约表的「未核实阻塞」，决策表/ADR 中状态为 `Blocked` 的项；
+- 「实施进度」的当前阻塞及状态为「阻塞」的里程碑；
+- 读取了评审报告时，其处置节中仍待决、且计划未体现的阻塞项。
+
+按根因去重，保留所有来源定位。另检查未标注却符合阻塞定义的事项（范围、安全、数据、外部契约或关键 NFR 未决），列为「疑似阻塞」，经用户确认后才纳入。
+
+每项分配 `B-01` 起的编号，并按解除方式分类：
+
+| 类型 | 判据 | 处理 |
+| --- | --- | --- |
+| 事实可查 | 答案在代码、配置、依赖、仓库文档或官方文档中 | 自行查证，不问用户 |
+| 需要决策 | 产品语义、范围/分期、权限与数据归属、外部契约、关键 NFR 数字、难回退的架构取舍、成本 | 查证后交互确认，附推荐 |
+| 外部依赖 | 需第三方答复、账号/配额、实测或 spike | 记录解除条件；仅在“先按假设推进还是等待”这类取舍上询问 |
+
+查证后类型可能改变：例如查到既有接口不支持分页，原本的事实项就变成“补分页还是改方案”的决策项。
+
+开始逐项处理前，先在聊天里给出阻塞总览：B-ID、事项、来源、阻塞的里程碑/任务、类型、计划处理方式。让用户一眼看清全貌和将要被问哪些问题。
+
+## 3. 逐项建立上下文
+
+对每一项（依赖链上游的先处理），在开口问之前把下面这些整理清楚：
+
+- **阻塞了什么**：受影响的需求、里程碑、任务，以及不解决时最晚在哪一步卡住。
+- **为什么阻塞**：缺的是哪条证据或哪个决定，计划原文怎么写的（带定位）。
+- **已核实事实**：亲自读到的代码/配置/文档行为，带 `路径:行号`。查到的事实若推翻了计划的前提，明确指出。
+- **约束**：用户原话、PRD、`C-*`、仓库规则中与此相关的要求。
+- **可选方案**（需要决策时 2–3 个真正可行且有实质差异的）：做法、对交付/风险/工作量/可回退性的后果，以及它需要计划改动哪些部分。
+- **推荐与理由**：选哪个，为什么。理由要扎根于本项的证据和约束——例如满足哪条需求、复用哪个已验证范式、哪个更容易回退、哪个把未知留到能验证的时点——而不是泛泛的“更好”。证据不足以支持推荐时直说，并说明还缺什么。
+
+事实可查的项查完即可解除，记下证据；查证无法完成（无访问权限、需运行环境）则转为外部依赖。
+
+## 4. 交互确认
+
+使用实际可用的交互问答工具（如 `AskUserQuestion`、`request_user_input_async`）；没有时在聊天中直接提问并等待。
+
+- 每次提问前，在聊天中先给出这批问题的完整上下文（上一步整理的内容），问题本身也要能独立读懂：写清阻塞的是什么、选项后果。推荐项放在第一位并在标签上注明“推荐”，描述里写推荐理由。允许用户自由回答。
+- 互不依赖的项可合并为一次提问（工具单次上限内）；后续选项依赖前一答案的，按顺序问，拿到答案后重新判断下游项的选项。
+- 只有用户的明确回答才算确认。“按你推荐的来”是确认，记录为“用户授权按推荐”；默认值、空回答、超时都不算。自由回答含义不清时追问一次。
+- 用户选择了非推荐方案时照其执行；若该选择与已核实事实冲突或引入新的阻塞，说明一次后果，记录用户的最终决定。
+- 用户中途停止或拒绝回答时，已确认的照常落地，其余保留为未决，不替用户默认决定。
+
+## 5. 写决策记录
+
+按 [references/decisions-contract.md](references/decisions-contract.md) 写入或续写 `<计划名>.decisions.md`：对象、处理轮次、阻塞总览、逐项记录（上下文、选项、推荐与理由、确认原话/证据、计划落点）、未解除阻塞、就绪结论。续写时追加本轮一行与各项的本轮结论，不改写前几轮的记录。由主 agent 单独写入，写后回读核对。
+
+## 6. 修订开发计划
+
+只把**已解除**的结论写进计划，按“事实前提 → 决策/契约 → 设计与任务 → 验证 → 状态”的顺序同步：
+
+- 需求账本：`A-*` 改为已解除或转写为 `C-*`/`R-*`；未知的 NFR 数字填入确认值，来源写“用户 YYYY-MM-DD 确认”或证据路径。
+- 事实/契约：`[未核实·阻塞]` 改为 `[已核实·足够]` 或 `[已核实·缺口]`，附证据与最小增量。
+- 决策表/ADR：写入选择、必要理由、未选备选和重新评估条件，状态改为 Accepted。
+- 受决策影响的接口、失败语义、迁移、§9 验证、里程碑任务与依赖一并修改；新增工作不预填完成，不改已有完成记录。
+- §11：已解除的行删除或改为不阻塞；未解除的保留并更新解除条件与最晚确认点。
+- 「实施进度」的当前阻塞与基线按事实更新；顶部状态按 dev-plan 标准重判：仍有影响范围、安全、数据、外部契约或关键 NFR 的未决项则保持 `Blocked`，前置都解决才是 `Ready`。
+
+计划只写最终结论，不写 B-ID、问答经过、“本次处理”这类过程信息，也不提本技能——这些留在决策记录里，否则会随实施过期并误导实施者。改前重读受影响段落，保留用户的并发修改；不改与阻塞无关的章节。
+
+## 7. 复核与交付
+
+1. 回读计划与决策记录：每个已解除项都能在计划中找到落点；搜索被推翻的旧说法，确认没有残留矛盾；需求 → 设计 → 里程碑 → 验收没有因修订断链；状态、§11 与「实施进度」一致。
+2. 计划采用 dev-plan 协议且脚本可用时，运行 `check_paths.sh <计划> <仓库根>` 与 `check_progress.sh <计划> <仓库根>`；不适用或缺失时人工核对并说明。
+3. 在决策记录的处理轮次中写入本轮计划修订后的 hash 和就绪结论。
+
+最终回复：决策记录与计划的链接、本轮已解除/新增或重开/仍阻塞的数量、计划状态变化，以及每个剩余阻塞的解除条件和负责人。写入失败时说明哪份文件未完成，不声称已保存。
+
+结尾先给一行明确判定：计划修订后的真实状态 **Ready** 或 **Blocked**，再给可直接复制的下一步命令：按当前客户端的技能调用写法（如 Codex `$resolve-blocked`、Claude Code `/resolve-blocked`），路径填实际文件。
+
+- **Ready**：`/goal 按 <计划路径> 开发`。
+- **Blocked**：继续 `resolve-blocked <计划路径>`，直至 Ready。逐项写明再次运行前要满足的条件：谁提供什么答复或证据、要完成的 spike/实测、待用户拍板的问题。剩余阻塞都在等外部条件时明说：条件满足前重跑不会改变结果。有不依赖阻塞的独立工作时一并列出。
+
+只给出建议命令，不自行开始实施。
+
+```text
+$resolve-blocked goal/LOGIN.md
+$resolve-blocked goal/LOGIN.md，参考 goal/LOGIN.review.md，只处理与 M2 相关的阻塞。
+$resolve-blocked goal/LOGIN.md，B-03 的供应商答复已到：<答复要点>。
+```
+
+## 项目状态回写
+
+若仓库已登记状态台账，或存在仓根 `.xgent-ai/sdlc/protocol.md`（兼容已有 `docs/project-status/protocol.md`；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按其格式新增本次事实记录并刷新受影响的状态页与必要索引；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。
+
+登记计划修订后的版本与就绪状态、决策记录路径及已解除/剩余阻塞；不把阻塞解除记成计划已实施。

package/skills/resolve-blocked/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "解除计划阻塞"
+  short_description: "逐项讲清计划阻塞，查证或交互确认并给推荐，可多次运行直至 Ready"
+  default_prompt: "使用 $resolve-blocked 处理指定开发计划中的阻塞事项：列出全部阻塞，逐项说明上下文，能查证的先查证，需要拍板的用交互问答附推荐方案与理由确认，将结论按轮次续写到计划同目录的 decisions 文档并修订计划；判定 Ready 或 Blocked，给出 /goal 或再次运行的下一步。"