# Standardize Wiki Docs

> Use when converting wiki-exported requirement documents (containing docx, xlsx, md, images) into standardized templates (functional requirement docs + FAQ docs), with a gaps checklist for product managers to supplement missing information.

- Skill: `songsunny00/standardize-wiki-docs` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add songsunny00/standardize-wiki-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/songsunny00/standardize-wiki-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: songsunny00 (https://skillmd.com/u/songsunny00)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/songsunny00/standardize-wiki-docs

---


# 需求文档标准化整理

## 概述

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

## 使用方式

用户调用：`/standardize-wiki-docs`

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

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

## 处理流程

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

### 第一步：解析文档

1. 扫描目标目录，识别所有文件类型
2. 运行 `parse_docs.py` 将 docx/xlsx 转为可读文本：
   ```bash
   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原型/页面截图**：直接嵌入原图，附简短文字说明，**不用文字替代图片**
  ```markdown
  **原型截图**：
  ![页面名称](../相对路径/image1.png)
  > 页面说明：顶部查询区域，中部数据列表，底部分页控件
  ```
- **流程图/架构图/数据流图/表格截图**：既嵌入原图，也附上完整的文字化描述
  ```markdown
  **流程图**：
  ![流程名称](../相对路径/image2.png)

  **流程说明**：
  1. 用户填写信息 → 系统校验
  2. 校验通过 → 保存 → 生成编号
  3. 校验失败 → 提示错误 → 返回修改
  ```

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

### 第四步：生成 FAQ 文档

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

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

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

### 第五步：识别缺失信息

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

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

### 第六步：生成待补充清单

将所有缺失信息整理为 JSON，然后运行：
```bash
python .claude/skills/standardize-wiki-docs/generate_gaps.py "<JSON文件路径>" "<输出Excel路径>"
```

JSON 格式：
```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 文件损坏 | 跳过该文件，在待补充清单中记录 |
| 多版本文档内容冲突 | 以最新版本为准，在文档中标注版本来源 |
| 模板中某章节完全无对应内容 | 保留章节标题，内容填 `[待补充]`，加入待补充清单 |
| 需求文档路径下无子模块 | 将整个目录视为单个模块处理 |