Skill: adahuhu/prd-review-2 (version 0.1.0)

--- name: prd-review description: "PRD 内审 Skill，对齐《PRD 文档标准规范 v2.4》。支持从飞书文档自动读取内容，识别 A/B/C 类型，按分型检查清单逐项审核，输出评分+必填项校验+逻辑校验+补全建议的结构化评审报告。触发关键词：审核、审查、检查、评审、内审、review、帮我审、PRD。" agent_created: true --- # PRD 内审 Skill（v2.4 对齐版） ## Purpose 对跨境电商 SaaS 产品（ERP / SCM / WMS / LPS）的需求文档进行结构化内审。自动识别文档类型（A/B/C），按《PRD 文档标准规范 v2.4》对应检查清单逐项审查，输出包含必填项校验、评分、逻辑审查和补全建议的完整评审报告。 ## When to Use 触发此 Skill 当用户消息中包含以下任一关键词且意图为审查 PRD 文档： **触发关键词**（任意一个即可触发）： - 中文：`审核`、`审查`、`检查`、`评审`、`内审`、`帮我审` - 英文：`review`、`check`、`audit` **典型触发语**： - "帮我审核这个需求" - "审一下这份 PRD" - "review this PRD" - "需求评审：xxx" - "检查一下文档" - "内审用一下" ## 输入方式 支持三种输入： 1. **飞书文档链接** — 自动通过 lark-mcp 读取内容（推荐） 2. **本地文件路径** — 直接 Read 读取 3. **粘贴文本** — 用户直接贴入文档内容 **二审模式额外输入**： - 上次审核报告（飞书链接 / 文件路径 / 粘贴文本）— 用于对比修复情况 - 若未提供上次报告但 audit-history 中存在同文档记录，自动调取 ## 审核流程 ### Step 1: 读取文档内容 #### 1.1 飞书文档（通过 lark-mcp） 如果用户提供了飞书文档链接，需要通过 lark-mcp 读取内容。 **飞书 URL 格式识别：** - 知识库文档：`https://xxx.feishu.cn/wiki/xxxxxx` - 普通文档：`https://xxx.feishu.cn/docx/xxxxxx` - 从 URL 提取 token（最后一个 `/` 后面的部分） **读取方式（通过 Python 调用 lark-mcp）：** 使用以下 Python 代码读取飞书文档内容： ```python import subprocess, json LARK_MCP_CMD = ['/opt/homebrew/bin/lark-mcp', 'mcp', '-a', 'cli_a95bbdfcc4389cb2', '-s', [REDACTED_SECRET], '--token-mode', 'tenant_access_token', '-t', 'preset.doc.default,preset.base.default', '-l', 'zh'] def _call_lark(tool_name, arguments, timeout=15): """底层调用 lark-mcp，返回工具调用结果""" proc = subprocess.Popen( LARK_MCP_CMD, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE ) msgs = [ json.dumps({"jsonrpc":"2.0","id":1,"method":"initialize", "params":{"protocolVersion":"2024-11-05","capabilities":{}, "clientInfo":{"name":"prd-review","version":"2.3"}}}), json.dumps({"jsonrpc":"2.0","method":"notifications/initialized"}), json.dumps({"jsonrpc":"2.0","id":2,"method":"tools/call", "params":{"name": tool_name, "arguments": arguments}}), ] out, err = proc.communicate(input='\n'.join(msgs).encode() + b'\n', timeout=timeout) for line in reversed(out.decode().strip().split('\n')): try: r = json.loads(line) if r.get('id') == 2: content = r.get('result', {}).get('content', []) for c in content: if c.get('type') == 'text': return c['text'] return r.get('result', r) except: pass return None def read_feishu_doc(document_id): """读取飞书文档原始内容，返回结构化内容""" return _call_lark("docx_v1_document_rawContent", {"path": {"document_id": document_id}}) def resolve_wiki_node(wiki_token): """从知识库 token 解析出实际文档的 obj_token""" result = _call_lark("wiki_v2_space_getNode", {"params": {"token": wiki_token}}) if isinstance(result, str): try: data = json.loads(result) return data.get('node', {}).get('obj_token', wiki_token) except: pass return wiki_token def write_to_feishu(markdown_content, file_name="PRD内审报告"): """将 Markdown 导入为飞书文档""" return _call_lark("docx_builtin_import", {"data": {"markdown": markdown_content, "file_name": file_name}}) ``` **URL 解析规则：** - 知识库链接 `https://xxx.feishu.cn/wiki/ABCDEF` → `resolve_wiki_node("ABCDEF")` 获取 document_id - 普通文档 `https://xxx.feishu.cn/docx/ABCDEF` → 直接用 `ABCDEF` 作为 document_id #### 1.2 本地文件 直接使用 Read 工具读取文件内容。支持 .md、.txt、.docx（需 textutil 转换）。 #### 1.3 粘贴文本 用户直接贴入时，将文本内容作为审核对象。 ### Step 2: 检测是否为二审 在识别文档类型前，先检查用户输入是否包含**上次审核报告**： **触发条件**（满足任一即为二审模式）： - 用户同时提供了 PRD 文档 + 上次审核报告（两个文件/链接/文本） - 用户明确提到"二审""复审""修改后再审""重新审核""check fix" - audit-history 目录中存在该文档的上次审核记录（通过文档标题匹配） **如果是二审模式**： 1. 读取上次审核报告，提取所有已标记的问题列表（编号 + 级别 + 问题描述） 2. 对照本次 PRD 内容，逐条判定修复状态： | 状态 | 标记 | 判定规则 | |------|------|----------| | 已修复 | ✅ | 原问题在本次文档中已不存在或已有明确修改 | | 部分修复 | ⚠️ | 原问题有改善但未完全解决（如模糊词有补充但仍有个别遗漏） | | 未修复 | ❌ | 原问题在本次文档中仍然存在且未做任何修改 | | 变更较大 | 🔄 | 修复方向正确但引入了新的问题或改变了设计思路 | 3. 二审评分规则：仅对未修复（❌）和部分修复（⚠️）项继续扣分，已修复（✅）项恢复对应分数 4. 在报告顶部增加"二审对比"区块（见报告模板） 5. 同步更新 audit-history JSON 中的 `is_re_review: true` ### Step 3: 识别文档类型（A/B/C） 根据文档结构和内容特征自动判断： | 特征 | B 型（综合优化） | A 型（新功能） | C 型（紧急） | |------|-------------|---------------|-------------| | 标题含"优化""修复""改进" | ✅ 常见 | | ✅ 常见 | | 有"竞品分析"章节 | | ✅ 几乎必有 | | | 有"状态机"章节 | | ✅ 常见 | | | 有"用户场景"章节 | | ✅ 几乎必有 | | | 有"目标上线时间"且紧急 | | | ✅ | | 有"触发条件""来源"字段 | | | ✅ | | 篇幅 | 1-2 页 | 8-15 页 | <1 页 | | 有"业务流程"含流程图 | | ✅ | | **判断优先级**：有"触发条件"+"来源"+"目标上线时间"且篇幅短 → C 型 → 有"竞品分析"或"用户场景" → A 型 → 其他 → B 型。拿不准时标注"疑似 X 型"并说明理由。 ### Step 3.5: 类型分歧确认（有分歧时暂停） **触发条件**（满足任一即暂停）： 1. 聚合文档中某些子节被判断为不同类型（如 B 型文档中检测到疑似 A 型/C 型子节） 2. 文档标题特征与内容特征不一致（如标题写"优化"但某节含完整状态机和跨单据同步） 3. 单节内容的信息密度明显超出所属类型的典型篇幅（如 B 型某节 >3 页） **暂停后输出类型确认提示**： ``` ⚠️ **类型确认提示** 在审核过程中发现以下内容可能存在类型归档差异： | 子节 | Skill 判断 | 判断理由 | |------|-----------|----------| | 第 X 节 标题 | 疑似 A 型 | 理由：... | 请确认： - 如果确实是 A 型需求，建议拆分为独立 A 型文档后重新提交审核 - 如果认为属于 B 型需求，Skill 将按 B 型标准审核该节（不检查竞品分析、用户场景等 A 型专属项） - 跳过确认 → 先按当前判断输出审核报告，后续可在二审中调整 ``` **等待用户确认后的处理逻辑**： - 用户确认为 B 型 → 该子节按 B 型必检项审核，A 型专属项（A2-1~A2-4、A4、B1、B2）标记为 N/A - 用户确认为 A 型 → 建议拆分，当前仍按 A 型标准继续审核 - 用户选择跳过 → 保持 Skill 初始判断继续审核 **无分歧时**：直接进入 Step 4，不输出此提示。 ### Step 4: 加载对应检查标准 读取以下参考文件获取检查标准： - `references/checklist.md` — v2.3 分型检查清单（严重 / 重要 / 建议 / 逻辑校验）+ 评分规则 + 质量红线 - `references/spec.md` — v2.3 规范的结构要求和写作规范 - `references/domain-knowledge.md` — 跨境电商领域知识（按需） ### Step 5: 执行分型审核 按文档类型执行对应检查，同时进行评分计算和逻辑校验。 #### 4.1 结构与规范检查（严重 / 重要 / 建议） **严重级（必须修复，阻塞开发）：** - A1 文档完整性：背景/现状、功能描述清晰、数值具体、无模糊词 - **A1-1 背景检查 — 看内容不看标题**：以下任一情况均视为「背景/现状说明」已存在（✅）： - 有独立背景章节，标题含「背景」「需求背景」「业务背景」「项目背景」「现状」「现状与问题」「当前现状」「问题描述」「问题说明」等关键词 - 无独立标题，但章节开头 2-3 句话描述了「当前什么表现 + 产生了什么问题/影响」 - 内容中出现「目前」「当前」「现有」「现状」「由于」「为了解决」等表述，且有具体的问题描述 - 仅以下情况判为 ❌：完全没有任何背景/现状相关内容，直接从方案、功能描述、技术实现开始写 - **注意**：B 型聚合文档中，每个子需求不需要独立背景章节，文档开头或首个子节有总体背景即可。后续子节若直接描述方案但问题本身已在总体背景中涵盖，不扣分 - **A1-4 模糊词检查需上下文判定**：发现模糊词（适当、合理、若干、等、类似、尽量、必要时、优化、完善）时，检查同一句或相邻两句（下文 2 句内）是否有量化补充。有则视为已解释（✅），无则标记为问题（❌） - 示例 — ❌ 裸模糊词："系统支持**合理的**并发量限制"（无具体值） - 示例 — ✅ 已有补充："系统支持**合理的**并发量限制，默认上限 1000 QPS，超过后进入等待队列"（后文有具体值，不扣分） - A2 状态与数据（A 型重点）：状态机完整性、字段定义 - **A2-4 触发前置判定**：检查 A2-4（新增核心字段有字段定义）前，必须先判断是否属于「新增字段」： - ✅ 触发检查：文档明确提到「新增字段」「新增列」「新建字段」且该字段在现有系统中不存在、需定义业务含义 - N/A 不触发：数据同步/传输（已有字段从 A 推送到 B）、数据展示优化、数据格式调整、快照/缓存数据——这些场景没有新增字段，不要求字段定义表 - 判断依据：看数据流向。如果是「已有数据换个地方展示/同步」→ N/A；如果是「系统原来没有这个维度，现在要记录」→ 触发检查 - A3 影响范围（C 型重点，A 型按需）：影响评估、存量数据、C 型后续需求判断 - **B 型影响范围特殊规则**：B 型优化中影响范围为**建议项，不扣分**。当检测到涉及跨模块/跨系统/存量数据时，在报告「补全建议」中提示「建议补充影响范围」，但不计入评分。B 型规范原文标注「若不涉及可删除」，说明影响范围非 B 型必填结构 - A4 竞品分析（A 型有参考时）：是否完成、有无差异化说明 **重要级（应当修复）：** - B1 业务流程（A 型）：主流程、分支、异常、回滚 - B2 用户场景（A 型重点）：角色、典型场景 - **B2-2 特殊规则**：典型使用场景（时间线描述）为**建议项，不扣分**。缺失时在报告「补全建议」中提醒，不计入评分。B2-1（角色列出）和 B2-3（核心路径覆盖）仍为必检项 - B3 功能描述质量：动词开头、主语明确、异常场景 - B4 跨系统集成（按需） - B5 数据迁移（按需） - B6 非功能需求（按需） **建议级（建议改进）：** - C1 文档规范：术语统一、标题格式、原型链接 - C2 跨境电商领域专项：多币种、多平台、时区 #### 4.2 评分计算 根据检查结果计算评分： - 起始分 100，扣到 0 为止 - ❌ Fail：严重 -8 / 重要 -4 / 建议 -1 - ⚠️ Partial：严重 -4 / 重要 -2 / 建议 -0.5 - ✅ Pass 和 N/A：不扣分 - 总分四舍五入取整 **通过判定（同时满足两个条件才通过）：** 1. 质量红线：零违反 2. 分数：≥ 80 通过 / 60-79 有条件通过 / < 60 不通过 #### 4.3 逻辑校验 对所有文档类型执行以下逻辑校验（D 级）： | 编号 | 校验维度 | 关注点 | |------|----------|--------| | D1-1 | 前后一致性 | 前置条件与后续规则是否自洽 | | D1-2 | 字段依赖 | 同一字段在不同章节的定义是否一致 | | D1-3 | 流程闭环 | 操作流程是否有未处理的出口（缺少驳回/撤回路径等） | | D1-4 | 状态可达性 | 是否有不可达的孤立状态 | | D1-5 | 数据引用 | 引用的字段/枚举值是否有对应定义 | | D1-6 | 条件互斥 | 多个条件规则间是否有逻辑冲突 | | D1-7 | 边界值 | 数值/列表/分页是否定义了上下界和空值处理 | **逻辑校验原则：** - **不确定不给建议** — 如果业务背景不足以判断逻辑是否合理，标注"待确认"并说明需要向谁确认（如"需与业务侧确认该规则是否成立"），不猜测不做假设 - **区分结构问题与逻辑问题** — "缺少状态机"是结构问题（归 严重），"状态机中状态 A 无法到达状态 B 但文档声称可以"是逻辑问题（归 D 级） - **给出具体矛盾点** — 不说"逻辑可能有矛盾"，说"第 3 章写'提交后不可修改'，第 5.2 节写'支持提交后修改字段 X'" - **"待确认"项给出行动指引** — 标注建议确认方（如开发负责人/业务侧/测试）和具体确认问题（如"提交后是否允许修改字段？如允许则修正第 3 章，如不允许则删除第 5 章该场景"），让 PM 知道找谁、问什么、问完怎么改 #### 4.4 必填项校验清单 根据识别的文档类型，列出该类型所有**必检项**的逐项校验结果。目的：让 PM 一眼看到结构完整性的达标情况。 **输出格式**：仅列出标注为"必检"的项目，按章节顺序排列，标注 ✅/❌/N/A。 **各类型必检项汇总：** **B 型必检项：** - A1-1 背景/现状说明 - A1-2 功能描述清晰无歧义 - A1-3 数值有具体值 - A1-4 无模糊词 **A 型必检项：** - A1-1 背景/现状说明 - A1-2 功能描述清晰无歧义 - A1-3 数值有具体值 - A1-4 无模糊词 - A2-1 涉及状态流转已定义状态机 - A2-2 状态机包含完整字段 - A2-3 终态已标注 - A2-4 新增核心字段有字段定义 - A4-1 有参考时竞品分析已完成 - B1-1~B1-4 业务流程完整 - B2-1 目标用户/角色已列出 - B2-3 场景覆盖核心操作路径 - B3-1 功能描述动词开头 - B3-2 操作主语明确 - B3-3 异常场景已描述 **C 型必检项：** - A1-1 背景/现状说明 - A1-2 功能描述清晰无歧义 - A1-3 数值有具体值 - A1-4 无模糊词 - A3-1 影响范围已评估 - A3-2 存量数据处理方式已说明 - A3-3 已判断是否有后续正式需求 - B3-4 触发条件/复现路径已写 - B3-5 来源已明确 - B3-6 目标上线时间是具体时间点 **严重/重要 项标注修复工作量：** 每个 ❌ Fail 的 严重 和 重要 项需标注预估修复工作量，帮助 PM 排序优先级： | 工作量 | 标注 | 含义 | |--------|------|------| | 🟢 5分钟 | `轻量` | 替换词汇、补一句描述、删除冗余章节等 | | 🟡 30分钟 | `中等` | 补写一段流程、完善字段定义表格、补充异常场景等 | | 🔴 需协作 | `重度` | 需与开发/业务确认逻辑、需补充完整状态机、需跨团队对齐等 | 标注方式：在问题列表的修复建议列末尾追加 `[轻量]` / `[中等]` / `[重度]`。 #### 4.5 补全建议内容 对识别到的缺失项（❌ Fail），自动生成符合 v2.3 规范的补全文本，供 PM 直接复制使用。 **补全原则：** - **仅补结构性内容** — 如缺少状态机时生成操作驱动型状态机表格模板、缺少字段定义时生成字段表格模板、缺少流程图时生成文字版流程描述 - **不补业务决策内容** — 具体的业务规则、字段取值范围、操作权限等业务判断不应由 AI 代写 - **标注插入位置** — 明确说明应插入到文档的哪个章节 - **使用占位符** — 业务相关内容用 `[待填写：具体值]` 标注，提醒 PM 补充 **补全建议增加工作量预估：** 在每条补全建议前标注预估工作量，并在补全区域开头给出总工作量汇总： - `可直接复制` — 纯模板，无需填写业务内容（如已有的状态表格框架、章节标题结构） - `需填写业务内容` — 模板中有占位符需 PM 补充（如字段定义的具体值、流程的具体步骤） - `需协作确认` — 涉及业务判断或跨团队确认，需额外沟通（如数据迁移的回滚方案） 输出格式示例： ``` 补全汇总：共 X 处，预计 Y 分钟（可直接复制 Z 处 / 需填写业务内容 N 处 / 需协作确认 M 处） ``` **可自动补全的内容示例：** | 缺失项 | 补全内容 | |--------|----------| | 状态机 | 操作驱动型状态机表格（当前状态/执行操作/流转后状态/角色限制/说明），填入已知状态，未知用占位符 | | 字段定义 | 字段定义表格（字段名/业务含义/数据类型/取值范围/数据来源/更新时机），已知字段填入 | | 流程描述 | 基于功能描述推导的主流程文字版（步骤 1→2→3...），标注"需与业务确认"的部分 | | 影响范围 | 影响范围四维检查清单模板（涉及模块/存量数据/数据迁移/其他影响），逐项留空供填写 | | 异常场景 | 常见异常场景检查表（网络超时/权限不足/数据冲突/并发操作等），适配具体功能的模板 | ### Step 6: 生成审核报告 #### 报告分级输出规则 根据得分和红线状态调整报告**详略程度**（非删减区块）。核心评估信息（N/A 说明、逻辑校验、补全建议、亮点分析、总体建议）在任何级别均保留。 | 级别 | 条件 | 详略策略 | 适用场景 | |------|------|----------|----------| | **精简报告** | ≥90 分 且 零红线违反 | 评分明细合并进问题列表（不单独成章）；审核结论简化为一句话；二审对比仅展示修复率+分数变化 | 文档质量好，重点在确认 1-2 个遗留问题 | | **标准报告** | 60-89 分 且 零红线违反 | 评分明细独立成章；审核结论含放行策略和分档建议 | 有问题但不严重，PO 需做评审决策 | | **完整报告** | <60 分 或 有红线违反 | 所有区块完整输出，审核结论含打回理由；逻辑校验逐项展开；补全建议含完整模板 | 文档需大修，PO 需全面评估风险 | **所有级别均保留的区块**：文档信息、30秒速览、必填项（含 N/A 说明）、问题列表（含评分）、修改指引、修复清单、逻辑校验、补全建议、亮点分析、总体建议。 **精简报告的变化不是删区块，而是**： - 评分明细**并入**问题列表表格中（加一列「扣分」），不另起「评分详情」章节 - N/A 说明不压缩，每条 N/A 都注明具体原因（如「无状态流转，非审批流程」） - 补全建议、逻辑校验、亮点分析、总体建议缩减到必要维度但仍独立成章 > **设计原则**：精简的是「重复信息」（如评分明细独立成章再和问题列表重复），而非「评估信息」（如 N/A 原因、逻辑待确认项、结构缺失模板）。评估信息是 PO 和 PM 决策的依据，不能减。 #### 输出格式（完整版模板，实际按分级规则裁剪）： ```markdown # PRD 内审报告 ## 文档信息 - 文档标题： - 文档类型：☐ B 型 ☐ A 型 ☐ C 型 - 所属系统：ERP / SCM / WMS / LPS - 审核日期： - 审核依据：PRD 文档标准规范 v2.4 > [类型分歧提示（仅存在分歧时显示）：本文档中第 X 节被识别为疑似 A 型需求（理由：...），已与用户确认为 B 型需求，按 B 型标准审核该节。] --- ## 〇、30 秒速览 > 一句话结论：[ ✅ 通过 / ⚠️ 有条件通过（XX 分）/ ❌ 不通过 ] **得分：XX 分** | **严重 X 项** | **重要 X 项** | **建议 X 项** | **逻辑问题 X 项** **[低置信度提示（如有）：⚠️ 有 X 项低置信度问题，建议人工复核（编号列表）]** **必须修复（按优先级）：** 1. [编号] 一句话描述 — 第X章 — [轻量/中等/重度] 2. [编号] 一句话描述 — 第X章 — [轻量/中等/重度] 3. ... **放行建议：** - 🚫 开发前必修：X 项 [列出编号] - ⚠️ 提测前补齐：Y 项 [列出编号] - ✅ 可后补：Z 项 [列出编号] **补全工作：共 X 处，预计 Y 分钟** **[质量红线违反提示（如有）：❌ 红线项名称 — 说明]** --- ## 二审对比（仅二审模式显示） > 本次为二审，对比上次审核报告，检查修复情况。 **上次得分：XX 分 → 本次得分：XX 分（+X / -X）** | **修复率：X%（已修复 X / 总问题 X）** > 修复率 = 已修复 / (已修复 + 部分修复 + 未修复 + 变更较大) × 100% **修复明细：✅ 已修复 X 项 | ⚠️ 部分修复 X 项 | ❌ 未修复 X 项 | 🔄 变更较大 X 项** | 编号 | 级别 | 上次问题描述 | 修复状态 | 本次情况说明 | |------|------|-------------|----------|-------------| | A1-1 | 严重 | 缺少背景说明 | ✅ 已修复 | 第1章已补充背景与目标 | | A2-1 | 严重 | 状态机缺少终态标注 | ⚠️ 部分修复 | 已增加"已关闭"终态，但"已取消"状态仍缺少 | | B3-1 | 重要 | 功能描述未动词开头 | ❌ 未修复 | 第5.2节仍有 3 处名词短语开头 | | B1-3 | 重要 | 异常处理方案缺失 | 🔄 变更较大 | 已补充异常方案但改为"返回错误码"，需确认是否覆盖所有异常类型 | **二审结论：** [如：修复率 50%，分数提升 15 分。剩余 2 项建议在本周内补齐后可进入开发 / 修复率 80%，文档质量明显提升，建议放行] --- ## 审核范围 > 说明本报告覆盖的审核区域，避免争议。 | 区域 | 状态 | 说明 | |------|------|------| | 第 1 章 背景与目标 | ✅ 已审核 | | | 第 2 章 用户场景 | ✅ 已审核 | | | 第 3 章 竞品分析 | ✅ 已审核 / N/A 无此章节 | | | 第 4 章 业务流程 | ✅ 已审核 | | | 第 5 章 功能描述 | ✅ 已审核 | | | 第 6 章 权限 | ✅ 已审核 | | | 第 7 章 其他模块 | ✅ 已审核 / N/A 无此章节 | | | 附录/参考文档 | ⏭ 跳过 | 非 PRD 正文，不计入审核 | **说明**：文档共 X 章，已审核 Y 章，跳过 Z 章（非正文内容）。 --- ## 一、必填项校验清单 > 按文档类型列出所有必检项的结构完整性检查结果。 | 序号 | 编号 | 必填项 | 结果 | |------|------|--------|------| | 1 | A1-1 | 背景/现状说明 | ✅ | | 2 | A1-2 | 功能描述清晰无歧义 | ✅ | | ... | ... | ... | ... | **必填项通过率：X / Y（Z%）** --- ## 二、评分详情 ### 扣分明细 | 编号 | 级别 | 检查项 | 结果 | 扣分 | 原文 | 问题说明 | 置信度 | |------|------|--------|------|------|------|----------|--------| | A1-2 | 严重 | 功能描述清晰无歧义 | ⚠️ | -4 | > 支持多币种结算 | 第3章未明确具体币种 | 高 | | B3-1 | 重要 | 功能描述动词开头 | ❌ | -4 | > 汇率的查看和导出 | 第5.2节使用名词短语 | 高 | | C1-1 | 建议 | 术语全文统一 | ⚠️ | -0.5 | > 运费明细...物流费合计 | "运费"和"物流费"混用 | 高 | ### 同类问题聚合 > 将分布在多个章节的同类型问题合并展示，方便批量修改。 | 检查项 | 出现次数 | 涉及位置 | 扣分合计 | |--------|----------|----------|----------| | A1-4 模糊词 | 3 处 | 第2章"适当"、第3章"合理"、第5章"尽量" | -24 | | ... | ... | ... | ... | ### 分数汇总 | 项目 | 分值 | |------|------| | 起始分 | 100 | | 严重 扣分 | -X（N Fail + M Partial） | | 重要 扣分 | -X（N Fail + M Partial） | | 建议 扣分 | -X（N Fail + M Partial） | | **最终得分** | **XX 分** | ### 质量红线检查 > 红线按文档类型不同：B 型不包含影响范围，A 型不包含影响范围，C 型包含影响范围。 | 红线项 | 结果 | |--------|------| | 不缺少背景/现状说明 | ✅ / ❌ | | 功能描述清晰无歧义 | ✅ / ❌ | | ... | ... | --- ## 三、审核结论 **[ ✅ 通过 / ⚠️ 有条件通过（XX 分）/ ❌ 不通过 ]** [具体理由，1-2 句话说明。] ### 放行策略 将所有问题按阻塞程度分为三档，帮助审核人判断哪些修完即可放行： | 档位 | 含义 | 分类规则 | |------|------|----------| | 🚫 开发前必修 | 直接阻塞开发启动 | 所有 严重 ❌ Fail 项 + 质量红线违反项 | | ⚠️ 提测前补齐 | 不阻塞开发，但阻塞测试 | 严重 ⚠️ Partial 项 + 重要 ❌ Fail 项中影响测试用例的部分（如异常场景缺失、字段定义不清） | | ✅ 可后补 | 不阻塞当前迭代 | 重要 ⚠️ Partial 项 + 所有 建议 项 + 重要 中不影响核心逻辑的部分 | **放行建议：** | 档位 | 项数 | 编号 | |------|------|------| | 🚫 开发前必修 | X | A1-1, A2-1, ... | | ⚠️ 提测前补齐 | Y | B1-3, B3-1, ... | | ✅ 可后补 | Z | C1-1, B2-2, ... | **结论：** [如：修复 A1-1 和 A2-1 后即可进入开发，其余可在开发期间补齐 / 该文档不通过，需全面修订后重新提交] --- ## 四、问题列表（按严重程度） ### 严重级（必须修复） | 编号 | 检查项 | 原文 | 问题描述 | 位置 | 修复建议 | 关联影响 | 工作量 | |------|--------|------|----------|------|----------|----------|--------| | A1-1 | ... | > 原文片段 | ... | 第X章 | ... | 需同步检查第X.X节 | 🟢 轻量 | | A2-1 | ... | > 原文片段 | ... | 第X章 | ... | 需同步检查第X.X、X.X节 | 🔴 重度 | ### 重要级（应当修复） [同上格式，关联影响列可选，仅跨章节联动时填写] ### 建议级（建议改进） [同上格式，建议级不标注工作量和关联影响，原文列可选] --- ## 五、修改指引（按章节分组） > 按文档章节汇总所有问题，打开对应章节一次性修完。 ### 第 1 章 背景（X 个问题） | 编号 | 级别 | 原文 | 问题 | 修复建议 | |------|------|------|------|----------| | A1-4 | 严重 | > 系统会对前若干条数据进行... | 使用"若干"未量化 | 改为具体数值，如"前 100 条" | | ... | ... | ... | ... | ... | ### 第 3 章 业务流程（X 个问题） | 编号 | 级别 | 原文 | 问题 | 修复建议 | |------|------|------|------|----------| | B1-3 | 重要 | > （此处无原文，结构缺失） | 缺少异常处理方案 | 补充 API 超时和并发冲突的处理方案 | | ... | ... | ... | ... | ... | ### 第 5 章 功能描述（X 个问题） [同上格式] --- ## 六、逻辑校验 | 编号 | 校验维度 | 校验结果 | 说明 | 行动指引 | |------|----------|----------|------|----------| | D1-1 | 前后一致性 | ⚠️ 待确认 | 第3章"提交后不可修改"与第5.2节"支持提交后修改字段X"可能矛盾 | → 确认方：开发负责人。确认问题：提交后是否允许修改？如允许则修正第3章，如不允许则删除第5章该场景 | | D1-3 | 流程闭环 | ❌ 有遗漏 | 第4章"审核通过"路径完整，但缺少"审核驳回"后的数据归置说明 | → 直接补充第4章：驳回后数据回退到待提交状态，已填写的表单数据保留 7 天 | | ... | ... | ✅ / ⚠️ 待确认 / ❌ | ... | ... | --- ## 七、补全建议内容 > 以下内容可直接复制到 PRD 文档中使用，占位符 `[待填写：...]` 需替换为实际内容。 > > **补全汇总：共 X 处，预计 Y 分钟（可直接复制 Z 处 / 需填写业务内容 N 处 / 需协作确认 M 处）** ### 补全项 1：状态机（插入位置：第 4.2 节）| 需填写业务内容 | 约 15 分钟 ```markdown | 当前状态 | 执行操作 | 流转后状态 | 角色限制 | 说明 | |----------|----------|------------|----------|------| | [待填写] | [待填写] | [待填写] | [待填写] | [待填写] | ``` ### 补全项 2：字段定义（插入位置：第 4.3 节）| 需填写业务内容 | 约 10 分钟 ```markdown | 字段名 | 业务含义 | 数据类型 | 取值范围 | 数据来源 | 更新时机 | |--------|----------|----------|----------|----------|----------| | [待填写] | [待填写] | [待填写] | [待填写] | [待填写] | [待填写] | ``` --- ## 八、亮点分析 > 识别文档中值得推广的优秀实践，帮助团队沉淀方法论。 ### 亮点 1：[一句话标题] **位置**：第 X 章 **好在哪里**：[具体说明该做法为什么好，解决了什么问题] **适用场景**：[该做法适用于什么类型的 PRD / 什么业务场景] **推广建议**：☑ 建议作为团队最佳实践 / ☐ 可作为参考 / ☐ 仅本次文档适用 ### 亮点 2：[一句话标题] [同上格式] [如果没有值得推广的亮点，写"本文档未发现突出亮点"即可，不强行凑数] --- ## 九、总体建议 [综合改进方向，最多 3 条，按优先级排列] --- ## 十、修复清单 > 按编号逐项检查，修完一个勾一个。☐ = 未修复，☑ = 已修复。 | 状态 | 编号 | 级别 | 问题 | 章节 | 工作量 | |------|------|------|------|------|--------| | ☐ | A1-1 | 严重 | 缺少背景说明 | 第1章 | 🟡 中等 | | ☐ | A1-4 | 严重 | "适当"未量化 | 第2章 | 🟢 轻量 | | ☐ | B1-3 | 重要 | 缺少异常处理 | 第4章 | 🟡 中等 | | ☐ | C1-1 | 建议 | 术语不统一 | 全文 | 🟢 轻量 | ``` ### Step 7: 可选 — 回写飞书 如果需要将审核报告写回飞书文档，调用已定义的 `write_to_feishu(markdown_content, file_name)` 函数即可。 **飞书 Markdown 兼容性规则（回写时自动处理）：** 飞书 Markdown 渲染与标准 Markdown 有差异，写回飞书时需做以下转换： | 标准语法 | 飞书兼容 | 说明 | |----------|----------|------| | `> 引用块` | ✅ 支持 | 单行引用正常；嵌套引用不保证样式 | | `\| 表格 \|` | ✅ 支持 | 列宽不可控，长文本自动截断。列数建议 ≤ 6 | | `` ```代码块``` `` | ⚠️ 有限 | 需指定语言（如 `` ```markdown ``），不指定可能无语法高亮 | | `# ~###### 标题` | ✅ 支持 | 最多支持 H3 层级（###），H4 以下不渲染为标题样式 | | `- 无序列表` | ✅ 支持 | 嵌套不超过 3 层，4 层以上可能样式异常 | | `1. 有序列表` | ✅ 支持 | 同上 | | `**加粗**` / `*斜体*` | ✅ 支持 | | | `~~删除线~~` | ⚠️ 不支持 | 改为 `~~` 文本前加 `（已删除）` 标注 | | `<details><summary>` | ❌ 不支持 | 不使用 HTML 折叠，改为标题 + 说明文案 | | `[链接](url)` | ✅ 支持 | | | 表格内 `>` 引用 | ⚠️ 异常 | 原文列改为加粗引用前加 `「` 后加 `」`，如 **「原文片段」** | **回写时的格式调整策略**： 1. 报告标题保持 H1（`#`），章节标题用 H2（`##`），子节用 H3（`###`），避免 H4+ 2. 表格列数 ≤ 6，超宽内容拆分到下一行或缩写 3. 原文列（`>` 引用格式）改为 `「原文」` 加粗格式 4. 删除线改为文字标注 5. 代码块统一使用 `markdown` 语言标记 6. 补全建议中的代码块（状态机/字段模板）使用 `markdown` 语言标记，确保表格在飞书中正确渲染 **注意事项：** - Markdown 导入大小限制 20MB - 导入后生成的文档需要手动授权给相关人员查看 ### Step 8: 审核记录留存 每次审核完成后，将审核结果以 JSON 格式保存到 `{workspace}/.workbuddy/audit-history/` 目录，便于后续追踪 PM 质量趋势和文档迭代质量。 **文件命名**：`{文档标题简称}_{审核日期}.json`（如 `其他费用模块_2026-05-20.json`） **JSON 结构**： ```json { "meta": { "doc_title": "文档标题", "doc_type": "A/B/C", "system": "ERP/SCM/WMS/LPS", "review_date": "2026-05-20", "review_version": "v2.4", "is_re_review": false }, "score": { "total": 82, "critical_fail": 1, "critical_partial": 0, "major_fail": 2, "major_partial": 1, "minor_fail": 3, "minor_partial": 0 }, "mandatory": { "total": 10, "pass": 8, "rate": "80%" }, "quality_redline": { "violated": false, "items": [] }, "issues_summary": [ { "id": "A1-1", "level": "严重", "result": "Fail", "deduction": 8, "chapter": "第1章", "confidence": "高", "summary": "缺少背景说明" } ], "highlights": [ { "location": "第5章", "title": "异常场景覆盖全面", "recommendation": "团队最佳实践" } ], "release_strategy": { "before_dev": ["A1-1"], "before_test": ["B1-3", "B3-1"], "later": ["C1-1", "C1-2"] } } ``` **用途说明**（供后续扩展，当前仅留存）： - 按 PM 统计平均分和趋势，识别需要重点辅导的 PM - 按文档类型统计常见问题分布，优化检查清单权重 - 对比同一文档多次审核的分值变化，评估迭代质量 ## 审核原则 1. **引用原文** — 每个问题必须附上原文片段（使用 `> 引用格式`），审核人无需切换文件即可验证问题是否真实存在。原文过长时引用关键句，不超 3 行 2. **具体不笼统** — 不说"需补充细节"，说"第 3 章缺少异常处理场景：当 API 调用超时时系统的行为未定义" 3. **引用位置** — 每个问题标注对应章节位置 4. **给修复建议** — 不只说问题，给出具体的改法 5. **尊重约束** — C 型文档篇幅本身就短，不要按 A 型标准要求 6. **领域专业** — 充分利用跨境电商领域知识识别业务逻辑漏洞 7. **正面反馈** — 好的地方也要指出来，不只是挑错 8. **评分客观** — 每个扣分项必须有明确理由，不因主观感受扣分 9. **逻辑审慎** — 不确定的问题标注"待确认"并说明需向谁确认，不做猜测不做假设 10. **补全有边界** — 只补结构性模板，不代写业务决策内容 11. **PM 效率优先** — 同类问题聚合展示减少翻找、按章节分组方便批量修改、标注修复工作量帮助排优先级、补全内容可直接复制减少重复劳动 12. **模糊词需上下文判定** — 检查模糊词时，同一句或相邻两句（下文 2 句内）若已有具体数值、限定范围、操作条件等量化说明，则视为已解释，不标记为问题。只对"裸模糊词"（无任何量化补充）扣分 13. **标注关联影响** — 严重 和 重要 的修复可能引发其他章节的联动修改，必须在修复建议末尾标注"关联影响：需同步检查第 X.X 节"。例如"补充状态机"后，功能描述中引用状态流转的部分可能需要同步调整 14. **标注置信度** — 每个问题标注判断置信度： - **高** — 原文明确缺失或明显违规，无需业务背景即可确认 - **中** — 基于规范判断，需结合上下文理解，但大概率准确 - **低** — 涉及业务逻辑合理性判断，需人工复核确认 - 低置信度项须在问题说明末尾标注"⚠️ 建议人工复核"，帮助审核人聚焦精力 15. **类型分歧先确认** — 当检测到子节内容特征与文档主类型不一致时（如 B 型聚合文档中某节含完整状态机），暂停审核先请用户确认该节的实际类型归属。用户确认为当前类型后，仅按当前类型标准审核，不混用其他类型的检查项 ## Key Design Decisions (v2.4) 以下决策影响审核判断标准，必须严格遵守： | 编号 | 决策 | 审核含义 | |------|------|----------| | D-1 | 不单独写验收标准（AC） | **不要**检查 AC 章节，不要建议"应补充验收标准" | | D-2 | 功能清单是条件子模块（A 型） | 功能点 ≤5 个时不要求有功能清单 | | D-3 | 竞品分析无参考可删除 | 没有参考对象时，该章节应删除而非留空 | | D-4 | C 型极简但保留影响范围 | C 型不要求竞品分析、状态机，但影响范围必须评估 | | D-5 | B 型支持聚合 | 多个优化点可合并文档，不影响质量 | | D-6 | 写作规范内嵌模板 | 检查写作规范（动词开头、主语明确、可量化） | | D-7 | B 型影响范围不扣分 | B 型优化影响范围为建议项，检测到风险时提示但不扣分（规范原文「若不涉及可删除」） | | D-8 | 类型分歧先确认再审核 | 检测到子节类型与文档主类型不一致时，暂停审核请用户确认，避免误报 | | D-9 | B2-2 典型使用场景不扣分 | A 型用户场景中「典型使用场景」为建议项，缺失时在补全建议中提醒，不计入评分 | ## References - `references/checklist.md` — v2.3 分型检查清单（严重 / 重要 / 建议 / 逻辑校验）+ 评分规则 + 质量红线 - `references/spec.md` — v2.3 规范结构要求和写作规范 - `references/domain-knowledge.md` — 跨境电商 SaaS 领域知识库


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal:  | SkillSpector: suspicious (HIGH)