Uniproud BRD 转操作手册助手

将大型业务需求文档（BRD）重构为标准化、面向用户的操作手册。执行视角转换（系统描述→用户操作）、消除模糊表述、执行前后文一致性逻辑审计、100%精准还原底层计算公式，并保留图文关联，输出 Markdown + Word 双格式。

适用场景

• 用户提供 BRD / 需求文档 / 业务规格书，要求转为操作手册
• 用户提到"转操作手册"、"生成用户手册"、"BRD转文档"等意图
• 输入为 Word (.docx) 格式的大型文档（通常 100-200 页）

环境依赖

必需依赖

• Python 3.12+：用于运行自动化脚本
• python-docx 库：用于读写 Word 文档（pip install python-docx）

可选依赖

• 正则表达式支持：Python 内置 re 模块，用于文本分析
• JSON 处理：Python 内置 json 模块，用于数据序列化

安装方式

# 安装 python-docx
pip install python-docx

# 验证安装
python -c "import docx; print('python-docx installed successfully')"

工作流程

严格执行四步法，每步完成后再进入下一步：

第一步：元数据提取与逻辑审计

1. 读取 BRD 文档当前章节全文。
2. 提取当前章节定义的所有核心业务对象（如：服务包名称、下拉菜单选项、接口系统名称），构建当前章节的《基础业务字典》。
3. 检查当前章节是否存在以下逻辑漏洞：
   - 概念未定义先使用：后文出现的套餐或功能名称在前文的下拉选项或字典中未包含。
   - 前后文编号错乱：同一功能点或附加项在业务描述段落与后文系统对接段落中的编号不一致。

第二步：结构提取

1. 解析目录结构与功能清单。
2. 输出包含审计预警的《操作手册大纲映射表》，格式如下：

3. 等待用户确认大纲后再进入第三步。

第三步：图文定位

手动方式

1. 逐一识别 BRD 中的图片、流程图、原型图、截图。
2. 建立图片索引表：

3. 在操作手册对应位置插入占位符：[图片占位符：描述该图所需截取的界面或流程]

自动化方式（推荐）

1. 使用 python-docx 提取文档中的所有嵌入图片：
   python from docx import Document doc = Document('BRD.docx') for rel in doc.part.rels.values(): if "image" in rel.reltype: image_data = rel.target_part.blob # 保存图片文件
2. 通过文本分析定位图片引用：
   - 查找"图X.X"、"图X"、"见图"、"如图"等模式
   - 分析上下文确定图片类型（流程图、界面截图、原型图等）
3. 生成图片索引表 image_index.json，包含：
   - 图片编号、估算页码、图片类型
   - 描述、上下文、操作手册目标位置
   - 对应的源图片文件名
4. 在操作手册对应位置插入占位符

图片定位注意事项

• 自动化方式基于文本引用匹配，准确率有限，需人工确认
• 图片类型判断依赖上下文关键词（如"流程"、"界面"、"原型"）
• 建议在自动化提取后，人工审核图片索引表

第四步：内容重构

按照标准模版（见 references/output-template.md），逐个模块将业务需求重写为操作步骤。

• 按功能模块逐个输出。
• 每个模块完成后标记进度。
• 全部完成后生成 .md 和 .docx 文件。

硬性约束

1. 视角转换：严禁直接抄录BRD原文。必须将"系统应支持用户修改订单"转换为"用户点击'修改'按钮，进入订单编辑页面"。
2. 消除含糊词：严禁使用"根据实际情况填写"、"等等"、"相关操作"等模糊表述。必须明确具体字段和动作。
3. 公式100%还原：严禁对任何底层的成本计算公式、数学模型、计提逻辑或乘数因子进行文字概括（例如：严禁将具体的工时乘积公式简写为“+工时成本”）。必须完整、精确地保留原始文档中的所有数字、参数变量和计算路径。
4. 冲突处理协议：
   - 编号错乱处理：若发现同一附加项在后文系统对接时的编号与前文定义不一致，输出操作手册时必须修正为正确的定义编号，并在对应段落末尾加注：[逻辑审计提示：原始BRD中此处编号错误，已自动更正]。
   - 概念未定义处理：若后文使用了前文主字典中未包含的业务概念或套餐名称，必须在手册对应位置输出高亮标注：[业务语义待澄清：套餐/功能XX在前文市场细分中未定义，请业务方核对]。
5. 防止截断与遗漏：
   - 遇到篇幅过长时，优先确保当前模块的完整性。
   - 单个回复无法完全输出时，在文末标注：[当前模块未完，请回复"继续"以生成下一章节：XX模块]。
6. 图文关联：必须保留原文档中的图片索引关系，严禁直接丢弃图片信息。
7. 完整性：保持业务逻辑100%完整，不遗漏任何功能模块。

输出方式

完成全部内容重构后：

1. 将完整操作手册写入 操作手册.md。
2. 使用 Python 脚本将 .md 转换为 .docx（使用 python-docx 库）。
3. 通过 deliver_attachments 工具将两份文件交付给用户。

MD 转 DOCX 脚本

from docx import Document
from docx.shared import Pt
from docx.oxml.ns import qn
import re

# 统一字体配置
FONT_CN = '微软雅黑'  # 中文字体
FONT_EN = '微软雅黑'  # 英文字体
FONT_SIZE_BODY = Pt(11)
FONT_SIZE_H1 = Pt(18)
FONT_SIZE_H2 = Pt(14)
FONT_SIZE_H3 = Pt(12)
FONT_SIZE_TABLE = Pt(10)

def set_run_font(run, font_size=FONT_SIZE_BODY, bold=False):
    """统一设置run的中英文字体"""
    run.font.name = FONT_EN
    run.font.size = font_size
    run.bold = bold
    r = run._element
    rPr = r.get_or_add_rPr()
    rFonts = rPr.get_or_add_rFonts()
    rFonts.set(qn('w:eastAsia'), FONT_CN)
    rFonts.set(qn('w:ascii'), FONT_EN)
    rFonts.set(qn('w:hAnsi'), FONT_EN)

def add_formatted_text(paragraph, text):
    """添加带格式的文本（支持加粗）"""
    parts = re.split(r'\*\*(.*?)\*\*', text)
    for i, part in enumerate(parts):
        if not part:
            continue
        run = paragraph.add_run(part)
        set_run_font(run, bold=(i % 2 == 1))

def process_table(doc, table_lines):
    """处理表格"""
    if not table_lines:
        return
    rows = []
    for line in table_lines:
        cells = [cell.strip() for cell in line.split('|') if cell.strip()]
        if cells:
            rows.append(cells)
    if not rows:
        return
    num_cols = len(rows[0])
    table = doc.add_table(rows=len(rows), cols=num_cols)
    table.style = 'Table Grid'
    for i, row_data in enumerate(rows):
        row = table.rows[i]
        for j, cell_text in enumerate(row_data):
            if j < num_cols:
                cell = row.cells[j]
                p = cell.paragraphs[0]
                p.clear()
                run = p.add_run(cell_text)
                set_run_font(run, FONT_SIZE_TABLE)
                if i == 0:
                    run.bold = True
    doc.add_paragraph()

def md_to_docx(md_path, docx_path):
    with open(md_path, 'r', encoding='utf-8') as f:
        md_content = f.read()

    doc = Document()

    style = doc.styles['Normal']
    style.font.name = FONT_EN
    style.font.size = FONT_SIZE_BODY
    style.paragraph_format.space_after = Pt(6)
    style.paragraph_format.line_spacing = 1.5

    for i in range(1, 4):
        heading_style = doc.styles[f'Heading {i}']
        heading_style.font.name = FONT_EN
        heading_style.font.bold = True
        if i == 1:
            heading_style.font.size = FONT_SIZE_H1
        elif i == 2:
            heading_style.font.size = FONT_SIZE_H2
        elif i == 3:
            heading_style.font.size = FONT_SIZE_H3

    lines = md_content.split('\n')
    in_table = False
    table_lines = []

    for line in lines:
        line = line.rstrip()
        if not line:
            if in_table and table_lines:
                process_table(doc, table_lines)
                table_lines = []
                in_table = False
            continue
        if '|' in line and line.strip().startswith('|'):
            in_table = True
            if re.match(r'^\|[-|\s]+\|$', line.strip()):
                continue
            table_lines.append(line)
            continue
        if in_table and table_lines:
            process_table(doc, table_lines)
            table_lines = []
            in_table = False
        if line.startswith('# '):
            p = doc.add_heading(line[2:].strip(), level=1)
            for run in p.runs:
                set_run_font(run, FONT_SIZE_H1, bold=True)
        elif line.startswith('## '):
            p = doc.add_heading(line[3:].strip(), level=2)
            for run in p.runs:
                set_run_font(run, FONT_SIZE_H2, bold=True)
        elif line.startswith('### '):
            p = doc.add_heading(line[4:].strip(), level=3)
            for run in p.runs:
                set_run_font(run, FONT_SIZE_H3, bold=True)
        elif line.strip().startswith('- **'):
            p = doc.add_paragraph(style='List Bullet')
            add_formatted_text(p, line.strip()[2:])
        elif line.strip().startswith('- '):
            p = doc.add_paragraph(style='List Bullet')
            run = p.add_run(line.strip()[2:])
            set_run_font(run)
        elif line.strip().startswith('  - '):
            p = doc.add_paragraph(style='List Bullet 2')
            run = p.add_run(line.strip()[4:])
            set_run_font(run)
        elif line.strip().startswith('[图片占位符') or line.strip().startswith('[逻辑审计提示') or line.strip().startswith('[业务语义待澄清'):
            p = doc.add_paragraph()
            p.style = doc.styles['Intense Quote']
            run = p.add_run(line.strip())
            set_run_font(run, bold=True)
        elif line.strip():
            p = doc.add_paragraph()
            add_formatted_text(p, line.strip())

    if table_lines:
        process_table(doc, table_lines)

    doc.save(docx_path)

if __name__ == '__main__':
    md_to_docx('操作手册.md', '操作手册.docx')

实际执行时，根据文档复杂度调整脚本，确保格式正确。

## 自动化方案（推荐）

对于大型文档（100+页），推荐使用自动化脚本方案，可显著提升效率和一致性。

### 依赖环境
- Python 3.12+
- python-docx 库（用于读写 Word 文档）

### 自动化工作流程

#### 第一步：文档结构提取
1. 使用 python-docx 读取 BRD 文档，提取所有段落、标题、表格和图片信息
2. 生成 `brd_structure.json` 文件，包含文档的完整结构数据
3. 提取目录大纲，生成 `chapter_mapping.json`

#### 第二步：元数据提取与逻辑审计（自动化）
1. 逐章分析文本，使用正则表达式提取业务对象：
   - 服务包名称（如：OM-无忧、POG-畅行）
   - 下拉菜单选项（如：政府及其他-GO）
   - 接口系统名称（如：TOOL、OES、CPO）
   - 字段名称、计算公式、编号代码
2. 构建全局业务字典 `business_dictionary.json`
3. 自动检查逻辑漏洞：
   - 编号不一致检测（对比【编号】与"附加项编号"表述）
   - 概念未定义检测（对比后文出现的术语与前文字典）

#### 第三步：结构提取与大纲映射
1. 基于章节映射表，自动生成功能模块提取
2. 统计每个章节的图片引用数量
3. 输出《操作手册大纲映射表》`outline_mapping_table.json`

#### 第四步：图文定位
1. 使用 python-docx 提取所有嵌入图片，保存到 `images/` 目录
2. 通过文本分析定位图片引用（查找"图X.X"、"见图"等模式）
3. 生成图片索引表 `image_index.json`
4. 在操作手册对应位置插入占位符

#### 第五步：内容重构
1. 读取每个章节的完整文本
2. 应用视角转换规则：
   - "系统应支持用户" → "用户可以"
   - "系统需要" → "用户需要"
   - "系统支持" → "用户可以"
3. 消除含糊词：
   - "根据实际情况填写" → "请填写具体信息"
   - "等等" → "等"
4. 生成完整的操作手册 Markdown 文件

#### 第六步：格式转换与交付
1. 使用内置的 MD 转 DOCX 脚本生成 Word 文档
2. 通过 deliver_attachments 工具交付两个文件

### 自动化脚本清单

以下脚本已验证可用，可直接复用：

1. **read_brd.py** — 文档结构提取
   - 输入：BRD .docx 文件
   - 输出：brd_structure.json（段落、标题、表格、图片信息）

2. **extract_outline.py** — 大纲提取
   - 输入：brd_structure.json
   - 输出：chapter_mapping.json（章节索引映射）

3. **chapter_analysis.py** — 逐章分析
   - 输入：chapter_mapping.json、brd_structure.json
   - 输出：chapter_analysis.json（业务对象+逻辑审计）、business_dictionary.json

4. **generate_outline_mapping.py** — 大纲映射表生成
   - 输入：chapter_mapping.json、chapter_analysis.json
   - 输出：outline_mapping_table.json

5. **image_analysis.py** — 图片分析
   - 输入：BRD .docx 文件、brd_structure.json
   - 输出：image_index.json、images/ 目录（提取的原始图片）

6. **generate_manual.py** — 操作手册生成
   - 输入：chapter_mapping.json、brd_structure.json
   - 输出：操作手册.md

7. **md_to_docx.py** — 格式转换
   - 输入：操作手册.md
   - 输出：操作手册.docx

### 自动化方案优势
- **效率提升**：大型文档可在几分钟内完成转换，无需多轮交互
- **一致性保证**：所有章节应用相同的转换规则
- **可复用性**：脚本可保存并用于后续类似文档
- **完整审计**：自动化的逻辑检查覆盖所有章节

### 自动化方案注意事项
- 自动化转换后仍需人工审校，特别是成本计算公式部分
- 图片定位基于文本引用匹配，可能不够精确，需人工确认
- 对于特别复杂的业务逻辑，可能需要手动调整

## 注意事项

### 通用注意事项
- 大型文档（100+页）需多轮输出，务必保证每个模块完整性。
- 如果 BRD 中包含表格数据，转换为操作手册时保留关键字段表格
- 遇到逻辑冲突或定义模糊时，必须严格执行《冲突处理协议》，通过特定标识块向用户预警。
- 流程图描述应转为分步骤操作指引，而非直接引用流程图
- 对于权限相关的描述，明确列出角色-权限矩阵

### 自动化方案注意事项
- 自动化转换后仍需人工审校，特别是成本计算公式部分，确保数学模型完整还原
- 图片定位基于文本引用匹配，可能不够精确，需人工确认图片索引表
- 对于特别复杂的业务逻辑，可能需要手动调整自动化生成的文本
- 建议在自动化转换后，人工审核操作手册的整体结构和逻辑连贯性
- 自动化脚本可保存并复用，建议在项目目录中保留脚本文件