songsunny00/standardize-wiki-docs

需求文档标准化整理

概述

将 Wiki 导出的混合格式需求文档（md、docx、xlsx、图片）阅读梳理后，按标准化模板输出结构化的功能需求文档和 FAQ 文档，并自动识别信息缺失部分生成待补充清单。

使用方式

用户调用：/standardize-wiki-docs

需要两个输入：

1. 需求文档路径：Wiki 导出的文档目录（如 WikiResource/V1.0.0/01-样本中心产品设计文档，也可以是整个版本目录如 WikiResource/V1.0.0）
2. 标准化模版路径：包含标准模板的目录（如 标准模版/）

如果用户未提供路径，逐一询问。

处理流程

digraph flow {
    rankdir=TB;
    "接收输入路径" -> "扫描目录结构";
    "扫描目录结构" -> "是版本目录还是模块目录?" [shape=diamond];
    "是版本目录还是模块目录?" -> "遍历所有子模块目录" [label="版本目录"];
    "是版本目录还是模块目录?" -> "处理单个模块" [label="模块目录"];
    "遍历所有子模块目录" -> "处理单个模块" [label="逐个"];
    "处理单个模块" -> "第一步：解析文档";
    "第一步：解析文档" -> "第二步：阅读理解";
    "第二步：阅读理解" -> "第三步：填充功能需求文档";
    "第三步：填充功能需求文档" -> "第四步：生成FAQ文档";
    "第四步：生成FAQ文档" -> "第五步：识别缺失信息";
    "第五步：识别缺失信息" -> "第六步：生成待补充清单";
    "第六步：生成待补充清单" -> "输出结果";
}

第一步：解析文档

1. 扫描目标目录，识别所有文件类型
2. 运行 parse_docs.py 将 docx/xlsx 转为可读文本：

   python .claude/skills/standardize-wiki-docs/parse_docs.py "<需求文档路径>" --latest
   

3. 脚本在目标目录下生成 _parsed/ 子目录
4. 对 .md 文件，直接用 Read 工具读取

优先级规则：

• 如果存在 converted_markdown/ 目录，优先读取其中的 md 文件作为主文档
• 同名多版本文档（如 PRD文档1014、1203），只读取最新版本（--latest 参数自动处理）
• docx 原文件作为补充参考

5. 图片批量识别（必须执行，不可跳过）：
   • 扫描目录下所有图片（png/jpg/jpeg/gif/bmp），包括 _parsed/images/（docx提取）、assets/、media/、converted_markdown/media/ 等子目录
   • 逐个用 Read 工具读取每张图片（Claude 多模态能力可直接查看图片）
   • 先判断图片类型，再按类型提取关键信息：
     • UI原型/页面截图：页面名称、主要功能区域、关键按钮和字段、交互入口
     • 流程图：流程节点、关键分支、起止点、流转方向
     • 数据流图/架构图：数据来源、流向、关键转换点
     • 表格截图：表头、关键字段、数据示例
   • 将识别结果写入 _parsed/images_recognized.md，每张图片记录：文件路径、图片类型、关键信息

第二步：阅读理解全部内容

必须完整阅读所有文档后再开始整理，包括 _parsed/images_recognized.md，建立全景理解：

• 系统包含哪些模块/功能
• 各模块的核心业务流程
• 涉及哪些角色和权限
• 字段规则和数据规则（重点关注 Excel 中的字段定义）
• UI 原型和交互流程（结合图片识别记录理解）
• 各功能的输入输出和异常处理

Excel 内容处理要点：

• 字段规则 Excel：逐行读取字段名、类型、必填/选填、校验规则、默认值等，完整填入功能需求文档的「数据规则」表格
• 送检单/导出模板 Excel：理解字段结构，提取为功能描述中的输入输出说明
• 测试用例 Excel：提取关键测试场景，填入验收标准

图片内容处理：结合 _parsed/images_recognized.md 理解UI布局、流程关系和数据流向

第三步：填充功能需求文档

读取标准模板 标准化模板-功能需求文档.md，按模板结构逐节填充：

| 模板章节 | 填充来源 | 填充要点 | |---------|---------|---------| | 文档元数据 | 原文档基本信息 | 文档ID按 REQ-[项目]-[编号] 格式生成，关键词从内容提取 | | §1 需求概述 | PRD 背景章节 | 提取问题描述、业务价值、目标用户 | | §2 功能总览 | PRD 功能列表 + 流程图 | 核心功能一句话列表、整体流程图 | | §3 功能详细说明 | PRD 功能描述 + 规则 + 异常 + 图片 | 按功能点组织，每个功能点包含5个子章节：功能描述、适用场景、操作流程（含UI截图）、业务规则（仅该功能特有的）、异常处理 | | §4 数据规则与权限 | 字段规则 Excel + PRD 权限章节 | 跨功能的公共数据规则表格、权限角色矩阵 | | §5 界面原型 | 图片识别结果 | 页面位置、交互说明、原型链接（具体截图已嵌入各功能点的操作流程中） | | §6 非功能性需求 | PRD 非功能章节 | 性能、兼容性、安全要求 | | §7 依赖关系 | 跨模块引用分析 | 前置依赖、影响范围 | | §8 验收标准 | 测试用例 Excel | 功能验收点、测试用例 | | §9 FAQ | 常见问题提取 | 从需求中提炼用户可能的问题 |

图片引用规则（按类型区分处理）：

• UI原型/页面截图：直接嵌入原图，附简短文字说明，不用文字替代图片

  **原型截图**：
  ![页面名称](../相对路径/image1.png)
  > 页面说明：顶部查询区域，中部数据列表，底部分页控件
  

• 流程图/架构图/数据流图/表格截图：既嵌入原图，也附上完整的文字化描述

  **流程图**：
  ![流程名称](../相对路径/image2.png)
  
  **流程说明**：
  1. 用户填写信息 → 系统校验
  2. 校验通过 → 保存 → 生成编号
  3. 校验失败 → 提示错误 → 返回修改
  

其他填充原则：

• 有内容就填，没有的标注 [待补充]
• 保持原文档的准确信息，不臆造内容
• Excel 表格数据要完整转录，不遗漏字段
• 图片识别的文字描述要标注 [来源：图片识别]，提醒产品经理校验

第四步：生成 FAQ 文档

读取标准模板 标准化模板-FAQ问答文档.md，从需求文档中提炼 FAQ：

FAQ 提取来源：

• 功能操作类：从功能描述中提炼"如何做XX"类问题
• 规则说明类：从业务规则中提炼"为什么XX"类问题
• 异常处理类：从异常场景中提炼"XX怎么办"类问题
• 字段说明类：从字段规则中提炼"XX字段是什么意思"类问题

FAQ 编号规则：FAQ-[模块缩写]-[序号]

第五步：识别缺失信息

对照标准模板，逐节检查是否有信息缺失：

必须检查的缺失项：

• 文档元数据中的空字段
• 需求概述中缺少的背景/价值/用户说明
• 功能流程中缺少的步骤或分支
• 数据规则表格中缺少的字段定义
• 权限规则中缺少的角色定义
• 异常处理中缺少的场景覆盖
• 非功能性需求中缺少的指标
• 验收标准中缺少的测试用例
• 界面原型中缺少的交互说明

第六步：生成待补充清单

将所有缺失信息整理为 JSON，然后运行：

python .claude/skills/standardize-wiki-docs/generate_gaps.py "<JSON文件路径>" "<输出Excel路径>"

JSON 格式：

[
  {
    "id": 1,
    "module": "所属模块",
    "section": "对应模板章节",
    "field": "缺失的具体字段/内容",
    "priority": "必填|建议补充|可选",
    "context": "当前已有的相关信息（帮助产品经理理解上下文）",
    "suggestion": "建议补充的方向或示例"
  }
]

输出文件

每个模块生成：

<模块目录>/
  _parsed/
    images_recognized.md     # 所有图片的识别记录（第一步生成）
    *.txt                    # docx/xlsx 解析结果
  _standardized/
    功能需求文档.md          # 按标准模板填充，含图片引用和文字描述
    FAQ问答文档.md           # 按标准模板生成的FAQ文档
    待补充清单_YYYYMMDD.xlsx  # 缺失信息清单

质量要求

• 完整性：Excel 中的每一行数据都要读取并整理，不能遗漏
• 准确性：保持原文档信息的准确性，不臆造不存在的内容
• 可追溯：图片识别的内容标注来源，方便产品经理校验
• 实用性：待补充清单要具体到字段级别，附带上下文，方便产品经理快速补充
• 标准化：严格按照标准模板的格式和结构输出

常见问题

| 问题 | 处理方式 | |------|---------| | 图片无法识别 | 在文档中标注 [图片无法识别，请人工补充]，并加入待补充清单 | | Excel 文件损坏 | 跳过该文件，在待补充清单中记录 | | 多版本文档内容冲突 | 以最新版本为准，在文档中标注版本来源 | | 模板中某章节完全无对应内容 | 保留章节标题，内容填 [待补充]，加入待补充清单 | | 需求文档路径下无子模块 | 将整个目录视为单个模块处理 |