ai-project-manage-cli 3.0.4 → 3.0.6

package/template/skills/apm-propose/propose-instruction.md

@@ -0,0 +1,81 @@
+# proposal 工件：写作说明
+
+生成 **`proposal.md`** 时须建立 **「为何要做」**，并与后续 **`specs/`** 对齐：**Capabilities** 段落是 proposal 与 specs 之间的契约。
+
+**工件 DAG、单会话减少重复 Read**：见 **`.apm/skills/apm-propose/SKILL.md`**（「工件依赖」「单会话读取策略」）。
+
+---
+
+## 输出路径
+
+- 工作项目录：`.apm/workitems/<requirementId>/`
+- 写入：**`.apm/workitems/<requirementId>/proposal.md`**
+
+---
+
+## 依赖（写入前须 Read 完）
+
+| 文件 | 说明 |
+| --- | --- |
+| **`.apm/workitems/<requirementId>/prd.md`** | **唯一权威需求来源**；须全文阅读后再写 `proposal.md`。 |
+
+若工作项下尚无 **`prd.md`**：先在仓库根目录执行 **`apm get requirement <requirementId>`**，再 **Read**；仍缺失则**不得**生成 proposal（以 apm-propose **SKILL** 为准）。
+
+---
+
+## Instruction
+
+以 **`prd.md`** 为事实来源撰写变更提案（**Why**，不写实现细节；实现放在 `design.md`）。
+
+**篇幅**：精短，约 1～2 页等效内容均可。
+
+### 必含小节
+
+- **Why**：1～2 句话说明问题或机会——解决什么、为何是现在。
+- **What Changes**：要点列表，写清新增/修改/删除的能力；**破坏性变更**标注 **BREAKING**。
+- **Capabilities**：标明后续 **`specs/`** 要如何落文件——这是 proposal 与 specs 阶段的**契约**，填写前可检索仓库内既有能力文档（如 `.apm/product-capability-inventory/`）或相关 PRD/CAP 引用，避免与已有命名脱节。
+  - **New Capabilities**：新增能力，每一条对应本工作项下后续将新增的 **`specs/<kebab-name>.md`** 文件（例如 `user-auth`、`api-rate-limit`）。用 kebab-case 作文件名主干。
+  - **Modified Capabilities**：已有「规格层行为」将变更的能力（不仅是实现细节）。每条对应后续 **delta 规格**写法（可与 New 一样落在 `specs/<name>.md`，在文中标明相对既有行为的增量变更）。若无行为规格变化则留空或写「无」。
+- **Impact**：受影响的代码区域、API、依赖、系统或运维面。
+
+**注意**：Capabilities 里列出的每一项，都应在后续 **`specs/`** 中有可追溯对应（可一文件多条能力，但须在 specs 中写清）。
+
+---
+
+## Template（产出 `proposal.md` 时按此结构填空）
+
+小节标题可使用英文如下，或改为中文等价（如 **Why** → **背景与动机**，**What Changes** → **变更内容**，**Capabilities** → **能力范围**，**Impact** → **影响面**）。
+
+```markdown
+## Why
+
+<!-- 动机：解决什么问题？为何是现在？ -->
+
+## What Changes
+
+<!-- 具体变更要点；BREAKING 标注破坏性变更 -->
+
+## Capabilities
+
+### New Capabilities
+
+<!-- 每条对应后续 `specs/<kebab-name>.md` -->
+
+- `<name>`: <brief description>
+
+### Modified Capabilities
+
+<!-- 既有能力在规格层的行为变化；无则写 无 -->
+
+- `<existing-name>`: <what requirement behavior changes>
+
+## Impact
+
+<!-- 受影响代码、API、依赖、系统 -->
+```
+
+---
+
+## Unlocks
+
+完成并落盘 **`proposal.md`** 后，方可编写 **`design.md`** 与 **`specs/`**（二者仅依赖 proposal，可并行）。

package/template/skills/apm-propose/specs-instruction.md

@@ -0,0 +1,114 @@
+# specs 工件：写作说明（供 apm-propose 读取）
+
+在工作项目录下生成 **`specs/`** 内的规格文件，定义系统 **应做什么**，与 **`design.md`**（如何实现）区分。内容须可验证：**每条「需求」下须有至少一个「场景」**。
+
+**工件 DAG、单会话减少重复 Read**：见 **`.apm/skills/apm-propose/SKILL.md`**（「工件依赖」「单会话读取策略」）。
+
+---
+
+## 依赖（写入前须全文阅读）
+
+| 文件 | 说明 |
+| --- | --- |
+| **`.apm/workitems/<requirementId>/prd.md`** | 业务事实、约束、验收；**唯一权威需求来源**。 |
+| **`.apm/workitems/<requirementId>/proposal.md`** | **能力范围**（新增能力 / 变更能力）；每项能力须在 `specs/` 中有对应文档；文件名用**短横线小写**（如 `user-auth`、`data-export`）。 |
+
+若无 **`proposal.md`**，不得编写 specs。若无 **`prd.md`**，按 apm-propose **SKILL** 先执行 **`apm get requirement <requirementId>`** 再读。
+
+**不依赖** **`design.md`**：specs 可与设计文档并行撰写，但须与 **proposal 中的能力约定**、**prd** 一致。
+
+---
+
+## 输出位置
+
+- 根目录：**`.apm/workitems/<requirementId>/specs/`**
+- 文件组织（须与 **`propose-instruction.md`** 及 proposal 中的能力列表一致）：
+  - **常用**：一能力一文件 **`specs/<短横线名称>.md`**
+  - **也可**：**`specs/<短横线名称>/规格.md`**（同一工作项内择一风格，勿混用）
+
+---
+
+## 写作说明
+
+### 与 proposal 对齐
+
+按 **`proposal.md`「能力范围」**逐条落地：
+
+- **新增能力**：每个名称对应一个上述路径下的文件，以 **「新增需求」** 类内容为主。
+- **变更能力**：在对应文件中用 **变更需求 / 移除需求 / 重命名需求** 等章节描述相对旧行为的变化。若仓库有既有能力说明，可先阅读 **`.apm/product-capability-inventory/`** 或相关能力文档以核对名称，**不得**虚构 prd、proposal 未出现的能力。
+
+### 变更分块（均使用二级标题 `##`）
+
+可按需组合多个分块：
+
+| 二级标题 | 用途 |
+| --- | --- |
+| **新增需求** | 全新能力或新需求条款。 |
+| **变更需求** | 行为有变：须写入**修改后的完整段落**（从「### 需求：」到其下全部场景），禁止只贴片段，以免后续对账丢失上下文。 |
+| **移除需求** | 下线或废弃：每条须写 **原因**、必要时写 **迁移说明**。 |
+| **重命名需求** | 仅名称变化：写清 **原名称**、**新名称**。 |
+
+若整份文件均为新能力，可只保留 **新增需求** 分块。纯新增内容放在 **新增需求**，不要用 **变更需求** 代替。
+
+### 单条需求结构
+
+- 需求标题：`**### 需求：<名称>**`，其下为正文。
+- **措辞**：对行为约束用 **须、必须** 等明确用语，避免「尽量、可以」之类除非 prd 明确要求弱化。
+- 场景标题：`**#### 场景：<名称>**`（场景标题固定用 **四个井号**，勿用三个，以免与需求层级混淆）。
+- 场景正文建议采用：
+  - `- **当** …`
+  - `- **则** …`
+- **每条需求至少包含一个场景。**
+
+### 变更类特别注意
+
+若产品清单或仓库中已有该能力的旧规格，应先找到旧全文，再整体放入 **变更需求** 下改写，**保持标题与结构便于对照**。
+
+若只是补充新条款、不改变已有行为，在 **新增需求** 中增加条目，勿用 **变更需求**。
+
+### 可验证性
+
+每个 **场景** 都能对应测试或验收步骤；后续 **`tasks.md`** 中的 **需求编号** 可与 **需求 / 场景** 标题互相对照。
+
+---
+
+## 单文件模板示例
+
+```markdown
+## 新增需求
+
+### 需求：<需求名称>
+系统须 <规范性行为，一条或多句表述清楚>。
+
+#### 场景：<场景名称>
+- **当** <前置或触发条件>
+- **则** <预期结果>
+
+## 变更需求
+
+### 需求：<与既有需求同一标题>
+<!-- 此处放完整替换后的需求正文及全部场景 -->
+
+#### 场景：<场景名称>
+- **当** …
+- **则** …
+
+## 移除需求
+
+### 需求：<需求名称>
+**原因**：……  
+**迁移说明**：……
+
+## 重命名需求
+
+- **原名称：** …
+- **新名称：** …
+```
+
+按实际只保留需要的 `##` 分块；不需要的整块省略。
+
+---
+
+## 与后续工件的关系
+
+本目录与 **`design.md`** 均完成后，方可编写 **`.apm/workitems/<requirementId>/tasks.md`**。

package/template/skills/apm-propose/tasks-instruction.md

@@ -0,0 +1,90 @@
+# tasks 工件：写作说明（供 apm-propose 读取）
+
+生成 **`tasks.md`**：把实现工作拆成**可勾选、可追踪**的条款。后续 **apm-apply-change** 依赖 **`- [ ]` / `- [x]`** 勾选推进，格式须严格遵守。
+
+**工件 DAG、单会话减少重复 Read**：见 **`.apm/skills/apm-propose/SKILL.md`**（「工件依赖」「单会话读取策略」）。
+
+---
+
+## 依赖（写入前须 Read 完）
+
+| 文件 | 说明 |
+| --- | --- |
+| **`.apm/workitems/<requirementId>/prd.md`** | 范围与验收 |
+| **`.apm/workitems/<requirementId>/proposal.md`** | 动机与能力边界 |
+| **`.apm/workitems/<requirementId>/design.md`** | 如何做、模块与路径 |
+| **`.apm/workitems/<requirementId>/specs/`** | 须做什么、需求与场景 |
+
+若 **`design.md` 或 `specs/`**（至少一个规格文件）尚未就绪，**不得**编写 **tasks.md**。
+
+---
+
+## 输出路径
+
+**`.apm/workitems/<requirementId>/tasks.md`**
+
+---
+
+## 写作说明
+
+### 格式（须严格遵守）
+
+- **每一条待办必须是复选框**：行首 **`- [ ]`**（半角方括号、半角空格）。**不用** `- [ ]` 的行在实现阶段**无法被可靠追踪**。
+- **按主题分组**：使用带序号的二级标题，例如 **`## 1. 环境准备`**、**`## 2. 核心实现`**。
+- **任务编号**：组内序号 **`组号.序号`**，与描述同一行，例如 **`- [ ] 1.1 初始化数据模型`**、**`- [ ] 2.1 实现导出接口`**。
+- **粒度**：每项宜在一次会话内能做完；过粗则拆，过细可按模块合并。
+- **顺序**：按**技术依赖**排列（例如契约/数据先于接口/UI）。
+
+### 每条任务须带的元数据（缩进子列表）
+
+紧接在 **`- [ ]` 行下方**，用无序列表写出（便于人工与 Agent 对照）：
+
+| 字段 | 说明 |
+| --- | --- |
+| **需求编号** | 对应 **specs** 中 **### 需求：** 或 **#### 场景：** 的可识别标题/编号 |
+| **预期改动路径** | 计划修改或新增的文件/目录（可多条） |
+| **验证用例编号** | 可选；与测试或验收条目对应 |
+| **完成标准** | 可观察的完成判据（与 specs 场景可对照） |
+
+示例：
+
+```markdown
+## 1. 数据层
+
+- [ ] 1.1 新增合同状态字段
+  - **需求编号**：需求：合同状态同步（见 specs/contract.md）
+  - **预期改动路径**：`servers/be/prisma/schema.prisma` …
+  - **完成标准**：迁移可执行；已有合同默认状态正确
+```
+
+### 内容来源
+
+- **做什么、验收什么**：以 **specs** 为主，**prd** 补业务约束。
+- **改哪里、怎么迁**：以 **design** 为主，**预期改动路径**须与 design 中的模块划分**一致**；必要时 **SemanticSearch** 仓库以填路径。
+
+### 可验证性
+
+每条任务应有明确「做完」的样子；**完成标准** 应能让评审者或自己判断无需再猜。
+
+---
+
+## 模板示例
+
+```markdown
+## 1. <!-- 分组名称，如：准备 -->
+
+- [ ] 1.1 <!-- 简短任务说明 -->
+  - **需求编号**：…
+  - **预期改动路径**：…
+  - **验证用例编号**：（可选）…
+  - **完成标准**：…
+
+## 2. <!-- 分组名称，如：核心实现 -->
+
+- [ ] 2.1 …
+  - **需求编号**：…
+  - **预期改动路径**：…
+  - **完成标准**：…
+```
+
+---

package/template/skills/apm-refine/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: apm-refine
+description: 根据需求 ID 读取工作项 prd.md 与 reviews.xml，按「修订稿」标准结构（修订说明、背景与目标、范围、需求点、非功能、待确认/问题与局限等）润色并回写，再执行 apm refine 同步平台；当用户在对话中 @ 本技能或提出需求润色时使用。
+---
+
+# APM 需求润色（PRD 标准化）
+
+用户仅提供 **需求 ID**（workitem id）。**缺 ID 时索要，不猜测。**
+
+## 强制执行顺序（四步）
+
+### 步骤 1：读取 `prd.md` 与 `reviews.xml`
+
+1. 使用 **Read** 读取 **`.apm/workitems/<需求ID>/prd.md`**。
+2. 使用 **Read** 读取 **`.apm/workitems/<需求ID>/reviews.xml`**。
+
+**失败与缺省：**
+
+- 若 **`prd.md` 无法读取**（不存在、无权限等）：**终止**后续步骤，在最终对用户的说明中记录失败原因。
+- 若 **`reviews.xml` 无法读取**（不存在等）：**不终止**；视为**无评审意见**，仅基于当前 `prd.md` 做标准化与润色，不杜撰评审内容。
+
+### 步骤 2：润色为「标准需求文档」
+
+在**不向用户追问补充信息**的前提下完成（**禁止**为润色向用户发起对话式提问；材料中已写的 `reply` 与评审意见视为**补充信息**可吸收。有歧义、缺信息、与 reviews 冲突等，**对材料未载明之事项**一律记入 **「问题与局限」** 或按条件写入 **「待确认」**，见 **[apm-refine-template.md](./apm-refine-template.md)** 与小节 3）。
+
+1. **综合 `reviews.xml`（若可读）**  
+   解析其中各条 `review` 的 `content`（对 prd 的改进点/问题）与 `reply`（已给出的处理意见）。将**可落实的**回复与结论吸收进正文；**未覆盖或仍模糊**的，写入 **「问题与局限」**；若原文或 `reply` 中**已标明**未决、「待定」等，则同时或单独写入 **「待确认」**。**不**停步询问用户。
+
+2. **落盘结构：标准「修订稿」模板（写入 `prd.md` 须遵循）**  
+   使用 **Read** 读取与 `SKILL.md` 同目录的 **[apm-refine-template.md](./apm-refine-template.md)**，按其中**修订稿骨架**与章节说明组织正文（默认全文润色形态）。执行本技能时**须**读取该文件，不以记忆代替。
+
+   **改动与边界（仍须满足）**  
+   - **修订说明**中的「本次合并的要点」须**分点**写清本次相对原文的变更与**范围边界**（影响面、不做的事）。若改动项多于 3 条，可在「修订说明」后续追加小节 **「相对原文的变更」** 继续分点罗列。  
+   - 全文润色时**不要机械留空标题**：无内容的章节可删除（如无非功能则不写该章），但**背景与目标 / 范围 / 需求说明**一般应完整可读。
+
+   **局部替换（不必强行铺满模板）**  
+   若本轮实质上只需替换若干段落：可在 `prd.md` 中保留未改章节，仅重写涉及段落为**修改后的完整段落**，并在 **修订说明**（或 **相对原文的变更摘要**）中用简短 bullet 说明相对原文改了什么。**对用户对话仍以步骤 5 表格为唯一输出**，不把局部稿粘贴到对话里。
+
+3. **「问题与局限」与「待确认」**  
+   触发条件见 **[apm-refine-template.md](./apm-refine-template.md)** 文末两节；凡触发「问题与局限」的情形须按该节撰写，**禁止**因上述情况向用户发起追问。
+
+### 步骤 3：回写 `prd.md`
+
+使用 **Write** 将**完整**润色后的正文写回 **第一步同一路径**：**`.apm/workitems/<需求ID>/prd.md`**（覆盖原文件）。
+
+### 步骤 4：执行 `apm refine <需求ID>`
+
+在**仓库/工作区根目录**执行：
+
+```bash
+apm refine <需求ID>
+```
+
+命令结束后将本步执行结果记入「步骤 5」表格对应行的**状态**（见下）。
+
+### 步骤 5：回复用户
+
+对用户可见回复 **仅限一张 Markdown 表格**，**仅填写步骤 1～4 每步的执行状态**。**不得**在表格外输出任何其他内容（不粘贴 prd 正文、不另写摘要或提示）。
+
+建议表头（每行「状态」仅填 **成功** / **失败** / **跳过**；失败时可加简短原因，如 `失败：文件不存在`）：
+
+| 步骤 | 状态 |
+|------|------|
+| 1. 读取 `prd.md` 与 `reviews.xml` |  |
+| 2. 润色为「标准需求文档」 |  |
+| 3. 回写 `prd.md` |  |
+| 4. 执行 `apm refine <需求ID>` |  |
+
+---
+
+## 内部编排要点
+
+**通读 prd → Read [apm-refine-template.md](./apm-refine-template.md) →（若有）解析 reviews 与 reply → 按修订稿骨架写入 → 写回 `prd.md` → `apm refine`。**
+
+唯 **对用户可见** 的回复遵守上文「步骤 5」的表格约束。

package/template/skills/apm-refine/apm-refine-template.md

@@ -0,0 +1,47 @@
+# APM 需求「修订稿」落盘模板
+
+由 **`apm-refine`** 技能引用：润色并写回 `.apm/workitems/<需求ID>/prd.md` 时，按下列骨架组织正文。
+
+文中 **「补充信息」** 指 **`reviews.xml`** 中的评审意见与 `reply`（及评审记录中已写明的事实），不单指对话里的用户发言。
+
+---
+
+# [需求标题]（修订稿）
+
+**修订说明**（可选，但在依据评审合并或全文润色时**建议必备**）
+
+- 基于评审日期 / 评审记录：简要一句（若有可溯源的 review id、模型名可写）
+- 本次合并的要点：1～3 条 bullet（写清相对原文合并了什么、边界在哪）
+
+---
+
+## 背景与目标
+
+（合并原文与补充信息中明确补充/修正的表述）
+
+## 范围
+
+- **包含**：
+- **不包含**：（若补充信息或原文中明确收窄/排除）
+
+## 需求说明
+
+### 需求点 1：[名称]
+
+（将原文与补充信息合并后的**可执行描述**写清：角色、场景、规则、口径、边界）
+
+### 需求点 2：…
+
+## 非功能与约束（若有）
+
+（性能、权限、兼容、埋点等——仅当原文或补充信息涉及）
+
+## 待确认（可选；整节省略）
+
+仅当**原文、`reviews` 的 reply 或评审记录中**明确留下未拍板事项、或写明「待定」「再议」等时列出：
+
+- [ ] （未决口径摘要）— 用户原话或简要归纳
+
+## 问题与局限（按条件出现；与「待确认」区分）
+
+**待确认**承载「材料里用户/评审已标明的未决项」。本节承载润色过程中发现的：**评审缺失或 XML 不可解析、reviews 与 prd 冲突、关键口径无法从现有材料唯一确定**等；**禁止**为此向用户追问，仅列事实与风险。

package/template/skills/apm-review/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: apm-review
-description: 根据需求 ID 读取工作项 prd.md，对照代码做需求评审；评审立场依可见代码而定（仅前台 / 仅后台 / 全栈）；提交到评论的正文用 Markdown 拉出层次与重点，业务白话、避免代码与工程术语；结合代码交付面过滤与现状无关的空头边界质疑，当用户在对话中 @ 本技能时使用。
+description: 根据需求 ID 读取工作项 prd.md，对照代码做需求评审；评审立场依可见代码而定（仅前台 / 仅后台 / 全栈）；正文须结论先行、短句拆分，易懂且不整段复述 PRD（见 apm-review-reference.md）；业务白话、避免代码与工程术语；结合代码交付面过滤与现状无关的空头边界质疑，当用户在对话中 @ 本技能时使用。
 ---
 
 # APM 需求评审（对照代码）
 
 用户仅提供 **需求 ID**（workitem id）。缺 ID 时索要，不猜测。
 
-**评审规范与评审模板**（受众与用语、立场与范围、书写约束、正文示例等）见同目录 **[apm-review-reference.md](./apm-review-reference.md)**；执行本技能时须按该文件撰写评审正文。
+**评审规范与评审模板**（受众与用语、**易懂且不冗余的正文结构**、立场与范围、书写约束、待确认类问题的写法、正文示例等）见同目录 **[apm-review-reference.md](./apm-review-reference.md)**；执行本技能时须按该文件撰写评审正文，**每条缺陷均须结论先行、要点用短列表拆分，禁止大段复述 `prd.md`**。凡正文含须产品拍板的条目，待确认问题宜 **一句一点、并给出具体选项**（见 reference 中「待确认 / 歧义项：好问题的写法」）。
 
 ## 强制执行顺序（三步）
 
@@ -18,7 +18,7 @@ description: 根据需求 ID 读取工作项 prd.md，对照代码做需求评
 
 ### 步骤 2：撰写评审、落盘、推送、清理
 
-1. 使用 **Read** 读取 [apm-review-reference.md](./apm-review-reference.md)（与 `SKILL.md` 同目录），并依其中规范对照代码撰写 **Markdown 评审正文**：**只写确实存在的问题**；用「需求背景 / 需求范围 / 交互与功能要求第 X 节 / 非目标」等文档自有结构**点名条款**，不先单独铺一节「对用户意图的理解」。撰写前须完成代码检索并锁定本轮**评审立场**（见 reference 中「评审立场」），正文内容与措辞须与该立场一致，**不得超越可见范围下断定**。
+1. 使用 **Read** 读取 [apm-review-reference.md](./apm-review-reference.md)（与 `SKILL.md` 同目录），并依其中规范对照代码撰写 **Markdown 评审正文**：**只写确实存在的问题**；用「需求背景 / 需求范围 / 交互与功能要求第 X 节 / 非目标」等文档自有结构**点名条款**（半句锚定即可），不先单独铺一节「对用户意图的理解」，**不写与 `prd-review` 类似的整条「需求描述」复述**。撰写前须完成代码检索并锁定本轮**评审立场**（见 reference 中「评审立场」），正文内容与措辞须与该立场一致，**不得超越可见范围下断定**。
 2. 使用 **Write** 将正文写入**临时文件**，路径建议使用**绝对路径**，例如 `/tmp/apm-review-<需求ID>.md`（避免与相对 cwd 混淆）。
 3. 在项目根目录下执行：`apm comment <需求ID> --file=<临时文件绝对路径> --model=<评论使用的模型名称>`。
 4. 命令结束后 **删除临时文件**（**Delete** 工具或 `rm`），无论命令成功或失败都尽量清理（失败时保留文件仅供用户排错——技能默认仍删除，若需保留应在表格备注中说明）。
@@ -35,4 +35,4 @@ description: 根据需求 ID 读取工作项 prd.md，对照代码做需求评
 | 2. 评审与 comment | 成功 / 失败 | 临时文件路径（已删可写「已清理」）；`apm comment` 退出情况或 API 返回摘要；**建议**注明本轮评审立场（仅前台 / 仅后台 / 全栈） |
 | 3. 清理临时文件 | 成功 / 失败 | — |
 
-内部编排：**通读 prd → 检索并对照与需求相关的代码 → 判定本轮可见范围（仅前台 / 仅后台 / 全栈）并选定评审立场 → 将技术发现改写为业务白话 → 只输出有问题之处**；唯**对用户输出**遵守上表约束。
+内部编排：**通读 prd → 检索并对照与需求相关的代码 → 判定本轮可见范围（仅前台 / 仅后台 / 全栈）并选定评审立场 → 将技术发现改写为业务白话 → 按 reference「易懂且不冗余」组织每条缺陷（结论先行、短列表）→ 只输出有问题之处**；唯**对用户输出**遵守上表约束。

package/template/skills/apm-review/apm-review-reference.md

@@ -15,7 +15,31 @@
 - **像真人写的**：自然段落或简短条目均可；**禁止**行政腔、教程腔套话，例如「请先确认」「建议补一句」「会上拍板」「建议各方对齐」等指向「写作动作」的提示——只陈述**文档里哪里不顺、会导致什么后果**。
 - **直入问题**：不写「对用户意图的理解」这类总起段；意图若与某条缺陷强相关，**并入该条一句带过**即可。
 - **只写有内容的条目**：某类问题不存在则**整段不写**；**禁止**用「未发现矛盾」「未见明显问题」「在已对照范围内无……」等否定句凑篇幅。若通读后没有可写问题：正文可仅为一两句说明「按当前正文暂无新增评审意见」，**仍不写**空洞分类标题。
-- **Markdown 结构与可读性（写入评论的正文）**：平台讨论区按 Markdown 渲染。正文宜用 **`##` 二级标题**按条拆分（标题里点明文档位置），条内可用 **「要点 / 后果」** 或等价两项列表；**关键短语加粗**，必要时用 `---` 分隔大段，避免「一整块纯叙述」难以扫读。结构服从内容：**没有问题则不硬凑条目**。
+- **Markdown 结构与可读性（写入评论的正文）**：平台讨论区按 Markdown 渲染。正文宜用 **`##` 二级标题**按条拆分（标题里点明文档位置），条内结构须遵守下文 **「易懂且不冗余：每条缺陷怎么写（强制执行）」**；**关键短语加粗**，必要时用 `---` 分隔大段。结构服从内容：**没有问题则不硬凑条目**。
+
+## 易懂且不冗余：每条缺陷怎么写（强制执行）
+
+目标：**产品与业务方一眼能懂**，读起来不累；同时**不像 `prd-review` 那样为每条重复「需求描述」**，不把 PRD 整段抄进评论。
+
+### 必须遵守的顺序（每个 `##` 缺陷块内）
+
+1. **`##` 标题**：简短；带上文档锚点（章节名、小节编号或「第 X 条」）+ 问题关键词即可。
+2. **结论先行（单独一行）**：紧接着标题，**单独一行**写 **一句完整人话**，说明「哪里不对劲 / 和文档期望差什么」。读者只读这一句也应大致明白。**禁止**把结论藏在「要点」末尾或挤在长句宾语里。
+3. **文档锚点（半句，可并入结论或单独一行）**：用 **半句** 指向 PRD（例如「对应 … 第 X 条」），**不写**需求全文复述，**不**单独起一节「需求原文」「需求点摘要」。
+4. **要点**：用 **嵌套列表** 拆成多条短句（建议 2～4 条），**一条只说一件事**；说明「页面上 / 流程里实际怎样」「相对文档缺了什么」。单条避免多个「；」连环转折。
+5. **后果**：**优先一行**写完（谁会误判、验收不好勾、有何业务风险）；确有需要再补第二句。**禁止**与结论重复同一句话换说法凑字数。
+6. **待产品拍板**（仅当需要决策时）：紧跟该缺陷块，用已有规范 **一句一点 + 具体选项**（见「待确认 / 歧义项」）；不写「建议对齐」类空话。
+
+### 篇幅与句式（写入评论前自检）
+
+- **结论**：控制在 **约 35 字以内为宜**（复杂项可到一句半），能用「谁 / 在哪 / 缺什么」就不要用「未见……谈不上……」一串评审腔。
+- **每条缺陷块**：除「待产品拍板」外，**整块以偏短为宜**；宁可多拆一条 `##`，也不要单条塞成一长段散文。
+- **禁止**：以复述 PRD 段落代替分析；以「原则性表述」「无法闭环」等抽象收尾代替具体后果。
+
+### 与 `prd-review` 类模板的区别（避免冗余）
+
+- **不要**：为每条缺陷先写一大段「需求描述」再写评论（那是冗余来源）。
+- **只要**：标题或结论里的 **半句锚点** + **要点**里的针对性事实，让读者需要时可回去翻 `prd.md`。
 
 ## 评审立场（依可见代码）
 
@@ -34,6 +58,7 @@
 ## 立场：专业评审，而非复述原文
 
 - `prd.md` 可能口语化、不完整；正文用**清晰、可决策**的语言（业务名词与文档对齐），**对准具体条款**写缺口或风险。
+- **对准条款 ≠ 复述条款**：用章节名、「第 X 条」或半句转述定位即可；**禁止**把 PRD 某节全文或大段复制进评论后再点评（易与 `prd-review` 式「需求描述」同级冗余）。
 - **禁止**空洞表态（例如「技术上都能做」）；谈可行性须**建立在已读相关代码与模块边界之上**（且不超过上文「评审立场」准许的范围），说明与**现有能力划分、数据含义、产品约定**的关系及**后续改版成本**，用语落在「需求若坚持某种表述会带来何种**产品规则或协作上的代价**」，而非教人怎么写代码。
 
 ## 评审范围
@@ -59,6 +84,19 @@
 
 ## 书写约束（针对写入文件的评审正文）
 
+### 待确认 / 歧义项：好问题的写法
+
+当正文需要列出「须产品拍板」的条目时，优先写成**可一句决策**的问题，避免开放式空话。可参考下列特点（与具体业务无关，重结构与粒度）：
+
+| 特点 | 说明 |
+| --- | --- |
+| **一句一点** | 每条只对应一个决策主题；需要并列澄清时在一条内用分号串起同一主题下的子维度（入口形态；失败提示），不把多件不相干的事塞进同一句。 |
+| **选项具体** | 用「是 A、B 还是 C」或并列短语给出可选方案，让读者能勾选一个答案或组合答复；避免单独出现「需明确交互形态」而无备选答案。 |
+| **对齐文档缺口** | 指向 PRD 尚未写死的规则（入口、类型口径、端侧兼容、异常反馈等），便于对方按条回复，减少来回追问。 |
+
+**反例**：「预览相关交互建议再和产品对齐一下。」（无选项、无锚点）  
+**正例**：「预览入口：文件列表单独『预览』按钮，还是点击文件名即预览；展示载体：弹窗、抽屉或新标签页，需定一种默认。」（一句内同一主题，且给出可选集合）
+
 - 每条问题须说清「指向文档哪一句 / 哪一节」+「会卡在哪」。篇幅上**优先简洁**：段落式宜控制在**两三句话量级**；若采用 **Markdown 分条**，每条下的「要点 / 后果」也各自保持简短，**禁止**为套模板而重复空话。
 - 引用需求文档用章节名、小节编号或口语转述条款；**不写**代码或工程标识符，技术边界用「评论受众与用语」中的白话改写。
 - **简洁优先**：宁可少写几条，也不要为显得「全面」而重复或空话。
@@ -68,22 +106,32 @@
 
 ## 评审模板（写入临时文件的正文示例，结构仅供参考）
 
-按问题组织，**每条尽量点明文档位置**（章节名、小节编号、列表要点均可）。可读性要求高时优先采用 **Markdown 分条 + 要点/后果**（见上文「正文形态与语气」）。
+按问题组织；**每条缺陷**采用「结论先行 + 短要点 + 短后果」（见上文「易懂且不冗余」）。以下为推荐骨架。
 
-**示例（标题 + 要点/后果 + 加粗）：**
+**示例（结论先行 + 嵌套要点）：**
 
 ```markdown
-## 「需求范围」第三条：主链路落在哪一屏没说死
+## 「交互与功能要求」第 2 条：单笔回款与批量核销上限不一致
 
-- **要点**：……
-- **后果**：……
+**结论**：单笔回款入账时，没有看到和批量核销一致的「不得超过节点剩余应收」校验，两条路可能一个能超额、一个不能。
+
+- **要点**
+  - 批量核销（含预览）里，分配是按履约期次和节点的剩余应收封顶的。
+  - 单笔新增回款在界面上校的是日期等规则，没有像批量那样按节点剩余应收封顶。
+- **后果**：同一笔钱走不同入口，合规边界可能不一致，验收「同一套上限规则」时不好勾选。
+
+**待产品拍板**：若允许超额，需约定是统一禁止、单独权限还是二次确认（文中未写死）。
 
 ---
 
-## 「交互与功能要求」第 4 节：类型认定规则缺失
+## 「需求范围」第三条：主链路落在哪一屏没说死
+
+**结论**：文档没说清主链路默认从哪一屏进入，研发和验收可能对「做到哪算完成」各有一套理解。
 
-- **要点**：……
+- **要点**
+  - …
+  - …
 - **后果**：……
 ```
 
-（以上为示例：实际只保留**本轮确有依据**的条目；没有问题则不硬写。）
+（以上为示例：实际只保留**本轮确有依据**的条目；没有问题则不硬写；不需要决策时可删「待产品拍板」整段。）