Word 专业文档排版技能（word-formatter）

目的

对 WorkBuddy 产出（或用户提供）的 .docx 文档进行后期排版处理与图件管理，使其符合对应专业文档的排版规范；并在交付前输出合规校验清单。排版规则全部由 configs/*.json 配置驱动，脚本不含硬编码规则，便于按客户/文档类型扩展。

设计语言（客户交付型报告 · 严肃专业 · 极度克制）

统一遵循"严肃、专业、简洁"原则，全篇仅黑/白/灰三色，不使用任何彩色（含深蓝、深红等均禁用）：

• 配色：正文深灰 #1A1A1A、标题纯黑 #000000、注释灰 #595959；表格边框黑 #000000、图件节点浅灰填充 #F2F2F2 + 深灰描边 #404040。强调处一律用加粗或灰度层次区分，绝不用彩色，杜绝高饱和度与渐变。
• 字体层级：标题黑体加粗、正文宋体、注释灰色小字，三者字号与灰度分明。
• 表格：采用三线表（仅顶线 / 表头下细线 / 底线，无竖线、无内部横线）或全线表；表头加粗、行距均匀、无斑马纹、无彩色填充。
• 页眉页脚：统一生成页眉（报告类型，宋体 9pt 灰，右上角对齐，下方细线）与页脚页码（"第 N 页 共 M 页"，宋体 9pt 灰）。每类配置在 header_footer 块控制：header_text=报告类型、header_alignment:"right"、footer_mode:"page_of"。
• 封面页：排版时自动在文档最前插入封面（由 cover 块控制）——主标题居中（黑体 22pt 加粗）、可选副标题居中（如"（2025年度）"）、委托方（客户名称）居中、出具机构与报告日期置页面下方，末尾分页。样例中的客户/机构/日期为占位符（示例股份有限公司 /【尽调机构名称】/【报告日期】），调试时替换为真实信息即。
• 强制去色：排版默认 enforce_color=true，任何 stray 彩色（含深蓝/深红）一律按配置色（黑/深灰）覆盖，确保全篇只有黑灰白。

支持的文档类型与配置映射

上述五类均为客户交付型报告，无强制法定模板，按对应权威框架重建内容骨架，视觉统一为「黑/白/灰极度克制」的正式报告语言（宋体/黑体、三线表、统一页眉页脚）；每类均已附带一份含图件、端到端校验 0 不通过的样例。

关于内容骨架的权威依据：上述五类无强制法定模板，其章节骨架按对应权威框架（证监会尽调准则 / COSO 内控 / 税务风险管理指引 / 财政部管理会计指引）重建，非逐字照搬某机构既有模板；若需与某客户既有模板/VI 逐字逐格式一致，请提供其模板（字体/字号/行距/留白清单），本技能可据此固化专属 configs/client_xxx.json。

各类文档的详细排版规范要点见 references/formatting_standards.md（脚本无法覆盖的人工检查项也在其中）。

五类报告的关键指标速查

五类视觉指标完全一致（均继承「黑/白/灰极度克制」正式报告语言），差异仅在章节骨架与专属图件：①财务尽调含「财务尽调程序框架」流程图；②法律尽调含「股权架构图」；③综合风险含「风险评估流程(COSO)」+ 风险矩阵表；④财税风险含「财税风险评估流程」+ 税种风险矩阵表；⑤财务分析含「财务分析框架」流程图。各配置 JSON 的 structure 字段已写入推荐章节骨架，可直接作为写作模板。

工作流程

第 1 步：确定文档类型

根据用户描述或文档内容判断类型，选择对应配置文件。无法判断时询问用户。用户如有客户定制要求，先复制最接近的配置为新 JSON（如 configs/client_xxx.json）再修改，不要直接改动这些基础配置。

第 2 步：执行文本排版

# 使用技能提供的 Python 环境（首次需执行一次「环境准备」，后续只用此命令）
SKILL_DIR=~/.workbuddy/skills/word-formatter
PYBIN=$SKILL_DIR/.venv/bin/python3
$PYBIN $SKILL_DIR/scripts/format_docx.py <输入.docx> <配置.json> -o <输出.docx>

• 输出文件默认命名 原名_formatted.docx，永不覆盖原文件。
• 脚本处理内容：页面设置（纸张/页边距）、正文与各级标题样式（中西文字体、字号、行距、缩进、对齐、段前段后、颜色）、表格（字体统一 + 三线表/全线表边框 + 去填色）、全角空格清理。
• 颜色与表格由配置驱动：styles.*.color_rgb 控制各级文字颜色（仅黑/深灰，无任何彩色）；table.style 取值 three_line（三线表）或 full_line（全线表），脚本自动设置黑色边框、表头加粗、清除单元格填色与斑马纹。排版默认 enforce_color=true，任何 stray 彩色一律按配置色（黑/深灰）覆盖，确保全篇只有黑/白/灰。另按 header_footer 配置块统一生成页眉（报告标题）与页脚页码（第 N 页 共 M 页）。

第 3 步：图件处理（如需）

当文档包含或需要插入流程图、股权架构图、数据流向图、功能说明图、风险矩阵等图件时：

3a. 编写图件规格 JSON

创建一个 specs.json 数组，每项描述一个图件：

[
  {
    "target": "heading:二、数据处理流程",
    "caption": "数据处理流程",
    "engine": "structured",
    "direction": "LR",
    "nodes": [
      {"id":"A","label":"原始数据"},
      {"id":"B","label":"数据清洗"},
      {"id":"C","label":"分析建模"}
    ],
    "edges": [{"from":"A","to":"B"},{"from":"B","to":"C"}]
  },
  {
    "target": "placeholder:{{DIAGRAM:equity}}",
    "caption": "股权架构图",
    "engine": "structured",
    "direction": "TB",
    "nodes": [...],
    "edges": [...]
  }
]

target 支持三种模式：

• heading:<标题关键词> — 在包含该关键词的标题段落之后插入
• placeholder:<占位符> — 替换文档中包含该占位符的段落为图件
• append — 追加到文档末尾

engine 说明：

• structured（默认）— 纯 Python 离线渲染，始终可用，灰阶配色。适合流程图、股权架构树、数据流向图、风险矩阵等节点+连线型图件。
• mermaid — 使用 mermaid-cli 渲染，支持更丰富的语法（序列图、甘特图、ER 图等）。需要先安装 mermaid-cli（见下方"环境准备"）。

3b. 执行插入

SKILL_DIR=~/.workbuddy/skills/word-formatter
$SKILL_DIR/.venv/bin/python $SKILL_DIR/scripts/diagrams.py insert <排版后.docx> <specs.json> <配置.json> \
       -o <含图件.docx>

脚本自动完成：

• 按规格渲染每个图件为 PNG（默认灰阶，无彩色）
• 在指定位置插入图片 + 居中
• 自动添加分章编号图题（图1-1、图2-1 等）
• 统一重排所有图题编号并修正正文交叉引用（见图1-1 → 见图2-3）

3c. 识别已有图件（可选）

$PYBIN <skill_dir>/scripts/diagrams.py scan <docx>

输出 Markdown 清单：列出所有已嵌入图片的位置、宽度、图题。

第 4 步：合规校验

SKILL_DIR=~/.workbuddy/skills/word-formatter
$SKILL_DIR/.venv/bin/python $SKILL_DIR/scripts/validate_docx.py <最终文档.docx> <配置.json>

输出 Markdown 格式校验清单（通过/不通过/需人工复核三档），检查项含：

• 页面（纸张 A4、页边距）
• 字体/字号（Normal、各级标题、Note 与配置比对）
• 正文段落字体抽检（是否存在与规范不符的直接字体设置）
• 页眉页脚（页眉文字、页码域是否存在）
• 图件（图题存在性、宽度范围、居中、编号连续性、交叉引用可解析性）
• 表格样式（三线表无竖线、无填色/斑马纹）
• 配置中的 manual_checks 全部列为"需人工复核"项

将清单摘要呈现给用户，"不通过"与"需人工复核"项必须明确提醒用户。

第 5 步：呈现结果

用 present_files 展示最终 docx；在回复中给出：所用规范、已自动修正项、需人工复核项。

环境准备（首次使用）

# Python 环境（基础排版 + 图件渲染）
# 进入技能目录后一键安装：
cd ~/.workbuddy/skills/word-formatter
python3 -m venv .venv
.venv/bin/pip install python-docx matplotlib pillow

# Mermaid 可选后端（仅在使用 engine=mermaid 时需要）
cd ~/.workbuddy/binaries/node/workspace 2>/dev/null || mkdir -p ~/.workbuddy/binaries/node/workspace
cd ~/.workbuddy/binaries/node/workspace && npm install @mermaid-js/mermaid-cli

注意事项

• 目录（TOC）页码为 Word 域，python-docx 无法刷新。排版后提醒用户在 Word 中全选按 F9，或使用 LibreOffice：soffice --headless --convert-to docx（会刷新域，但可能轻微改变其他格式，需告知用户权衡）。
• 中文字体必须同时设置 w:eastAsia 属性（脚本已处理），否则中文字体不生效。
• 若文档使用直接格式（direct formatting）而非样式，脚本会在段落级覆盖；但复杂手工排版的文档建议先与用户确认再处理。
• 生成新文档时的最佳实践：让生成方直接使用规范的标题样式（Heading 1/2/3）+ 正文样式，再用本技能统一排版，效果远好于对无样式文档做后期修复。
• 图件渲染引擎：structured 引擎基于 matplotlib，离线可用，灰阶配色、支持中文黑体标签；mermaid 引擎效果更精美但依赖 Chromium（安装较重）。推荐默认使用 structured，仅在需要序列图/甘特图等复杂类型时切换 mermaid。
• 图题编号规则：按 Heading 1 分章编号（图1-1、图1-2…图2-1…）；正文中的交叉引用会随重编号同步修正。
• 图件宽度：各配置 JSON 的 figures.width_cm 控制默认宽度；单张图可在 spec 中通过 width_cm 覆盖。