Word 文档

.docx 创建、编辑、读取及视觉验证

概述

docx 技能涵盖 Word 文档的完整生命周期：从零创建、编辑现有文件、读取与分析、基于模板生成、修订管理，以及强制性视觉 QA 验证。该技能仅适用于 .docx 文件 — 不包括 PDF、电子表格、HWPX 或 Google Docs。

主要工具是 officecli，一个位于 PATH 上的命令行工具，可处理约 80% 的任务（add、set、remove、validate、query、track-change accept/reject）。对于 officecli 无法处理的任务 — 修订的创建、OMML 公式、批量模式匹配 — 该技能会回退到 scripts/ 中的 Python OOXML 脚本。

触发条件

快速参考

"~해줘" 用法示例

基于参考文件编辑

当用户说"按照 X.docx 的格式"、"匹配现有样式"、"基于模板"，或提供源文件时 — 始终从源文件开始。切勿从零重建。

工作流

1. 复制源文件： cp source.docx target.docx — 继承所有样式、边距、编号、页眉、页脚
2. 打开： officecli open target.docx — 守护进程启动；命令立即返回
3. 仅删除正文内容 — 保留 /styles、/numbering、/header、/footer
4. 使用现有样式名称添加新段落（例如 --prop style=Heading1）— 样式会自动应用

为什么这很重要

Pandoc 生成的和 Word 生成的文档具有特定的样式 ID（例如 Heading1、BodyText、FirstParagraph），这些 ID 对该文档来说是唯一的。添加同名的新样式会导致：

• officecli validate 报告重复样式 ID 错误
• Word/LibreOffice 渲染回退到默认设置
• 任务耗时增加 10 倍

模板优先级

1. 用户提供的源文件 — 一等模板
2. tests/fixtures/*.docx — 技能自带的预构建工作示例
3. officecli create 空白文件 — 仅在无其他选择时使用

# 正确做法：继承 Pandoc 样式
cp Assignment1.docx Assignment2.docx
officecli open Assignment2.docx
officecli remove Assignment2.docx "/body/p[1]"   # 删除旧正文（保留样式/页眉/页脚）
# ... 删除更多段落 ...
officecli add Assignment2.docx /body --type paragraph --prop text="New title" --prop style=Heading1
officecli close Assignment2.docx

# 错误做法：重新创建已存在的样式 -- validate 会失败
officecli add doc.docx /styles --type style --prop name=Heading1 --prop size=20pt ...

升级阶梯

当 officecli 无法完成任务时，按以下顺序升级：

升级信号

• officecli 显示 "silently ignored" → L2 (raw-set)
• 需要 OMML/MathML 公式 → L4（注入 <m:oMath> XML）
• 需要创建修订（officecli 只能接受/拒绝）→ L3 或 L4
• 批量查找/替换超过 100 个目标 → L3（docx_cli.py search/replace）
• Pandoc 生成的文档包含自定义样式 ID → 先使用"基于参考文件编辑"
• 任务在 L1+L2 后仍然失败 → 在放弃之前阅读相关的 references/*.md

核心工作流

执行模型

逐条执行命令。不要将所有命令写入 shell 脚本并作为单个块执行。OfficeCLI 是增量式的：每个 add、set 和 remove 都会立即修改文件并返回输出。

1. 逐条执行命令，然后查看输出。在继续之前检查退出码。
2. 非零退出码 = 立即停止并修复。不要在损坏状态上继续构建。
3. 在结构性操作后进行验证。添加样式、表格、图表或节之后，先运行 get 或 validate 再在其上继续构建。

读取与分析

officecli view doc.docx text                    # 完整文本提取
officecli view doc.docx text --max-lines 200    # 截断提取
officecli view doc.docx text --start 1 --end 50 # 范围提取
officecli view doc.docx outline                 # 结构：统计、标题、页眉/页脚
officecli view doc.docx annotated               # 每个 run 的样式/字体/大小，公式显示为 LaTeX
officecli view doc.docx stats                   # 段落数、样式/字体分布

元素检查

officecli get doc.docx /                        # 文档根节点（元数据、页面设置）
officecli get doc.docx /body --depth 1           # 列出正文子元素
officecli get doc.docx "/body/p[1]"              # 指定段落
officecli get doc.docx "/body/p[1]/r[1]"         # 指定 run
officecli get doc.docx "/body/tbl[1]" --depth 3  # 表格结构
officecli get doc.docx /styles                   # 样式定义
officecli get doc.docx "/styles/Heading1"        # 指定样式
officecli get doc.docx "/header[1]"              # 页眉/页脚
officecli get doc.docx /numbering                # 编号定义
officecli get doc.docx "/body/p[1]" --json       # 用于脚本的 JSON 输出

类 CSS 查询

officecli query doc.docx 'paragraph[style=Heading1]'            # 按样式
officecli query doc.docx 'p:contains("quarterly")'              # 按文本内容
officecli query doc.docx 'p:empty'                              # 空段落
officecli query doc.docx 'image:no-alt'                         # 无替代文本的图片
officecli query doc.docx 'p[align=center] > r[bold=true]'      # 复合选择器
officecli query doc.docx 'paragraph[size>=24pt]'                # 按大小
officecli query doc.docx 'field[fieldType!=page]'               # 按类型筛选字段

页眉与页脚

# 步骤 1：为封面页创建空页脚（自动启用 differentFirstPage）
officecli add doc.docx / --type footer --prop type=first --prop text=""

# 步骤 2：带有静态 "Page " 文本的默认页脚
officecli add doc.docx / --type footer --prop text="Page " \
  --prop type=default --prop align=center --prop size=9pt --prop font=Calibri

# 步骤 3：通过 raw-set 注入 PAGE 字段
# （footer[2] = 当首页页脚也存在时的默认页脚）
officecli raw-set doc.docx "/footer[2]" \
  --xpath "//w:p" \
  --action append \
  --xml '<w:r ...><w:fldChar w:fldCharType="begin"/></w:r>
         <w:r ...><w:instrText xml:space="preserve"> PAGE </w:instrText></w:r>
         <w:r ...><w:fldChar w:fldCharType="end"/></w:r>'

页脚索引规则：当同时添加了首页页脚和默认页脚时，默认页脚是 /footer[2]。如果没有首页页脚，默认页脚是 /footer[1]。始终使用 officecli get doc.docx "/footer[2]" 进行验证。

驻留模式（性能优化）

始终使用 open/close — 这是明智的默认做法。每条命令都无需重复文件 I/O。

officecli open doc.docx           # 一次性加载到内存（立即返回）
officecli add doc.docx ...        # 所有命令在内存中运行 -- 速度快
officecli set doc.docx ...
officecli close doc.docx          # 一次性写入磁盘

批处理模式

在单个 open/save 周期内执行多个操作：

cat <<'EOF' | officecli batch doc.docx
[
  {"command":"add","parent":"/body","type":"paragraph",
   "props":{"text":"Introduction","style":"Heading1"}},
  {"command":"add","parent":"/body","type":"paragraph",
   "props":{"text":"This report covers Q4 results.","font":"Calibri","size":"11pt"}}
]
EOF

批处理支持：add、set、get、query、remove、move、swap、view、raw、raw-set、validate。

子技能参考

更多细节存放在按需加载的伴随文件中：

决策流程

文档是否为学术论文（毕业论文、期刊、会议论文）？
  是 --> 阅读 officecli-academic-paper/SKILL.md
  否 --> 继续使用主技能

用户是否提供了要匹配的源文件？
  是 --> 基于参考文件编辑 + editing.md
  否 --> creating.md

Python OOXML 脚本

当 officecli 达到其极限时，该技能会回退到以下 Python 脚本：

参考材料

商务文档设计原则

标题层级

• H1：文档标题（每篇文档一个）
• H2：主要章节
• H3：H2 下的子章节
• 切勿跳级（H1 → H3 无效）。目录依赖正确的标题结构。

# 验证标题层级
officecli view report.docx outline

配色方案

切勿在单个文档中使用彩虹色、亮原色或超过 3 种强调色。

字体选择

排版规范

正文：11-12pt。标题递增：H1 = 最小 18pt（长文档推荐 20pt），H2 = 14pt 加粗，H3 = 12pt 加粗。正文行距 1.15x-1.5x。

内容到元素的映射

强制性验证

# 步骤 1：结构验证
officecli validate output.docx

# 步骤 2：视觉 PDF 验证
soffice --headless --convert-to pdf --outdir /tmp output.docx
# 打开/检查 PDF 以确认：格式、表格、图片、页眉/页脚

• 跳过 PDF 验证 = 未经验证的输出
• 如果 validate 报告错误，在交付文件之前修复它们

QA 检查清单

假设存在问题。你的工作就是找到它们。

问题检测

officecli view doc.docx issues
officecli view doc.docx issues --type format
officecli view doc.docx issues --type content
officecli view doc.docx issues --type structure

内容 QA

officecli view doc.docx text
officecli view doc.docx outline
officecli query doc.docx 'p:empty'
officecli query doc.docx 'image:no-alt'

# 检查残留占位符
officecli query doc.docx 'p:contains("lorem")'
officecli query doc.docx 'p:contains("placeholder")'

交付前检查清单

• 已设置元数据（标题、作者）
• 通过 raw-set 在页脚中注入了 PAGE 字段 — 使用 officecli get doc.docx "/footer[2]" --depth 3 验证
• 如果文档有封面页，已添加首页页脚
• 封面页内容至少填满页面的 60%
• 当文档有 3 个以上标题时包含目录
• 最后一页内容至少填满页面的 40%
• 标题层级正确（无跳级）
• 未使用空段落作为间距
• 所有图片都有替代文本
• 表格有表头行
• 文档通过 officecli validate 验证
• 无残留占位符文本

验证循环

1. 生成文档
2. 运行 view issues + view outline + view text + validate
3. 列出发现的问题（如果没有，更严格地再查一遍）
4. 修复问题
5. 重新验证 — 一个修复往往会产生另一个问题
6. 重复直到完整的一轮检查没有发现新问题

在至少完成一个"修复-验证"循环之前，不要宣布成功。

常见陷阱

已知问题

反模式（必须避免）

• 占位数据：输出中切勿留下 "Acme Corp"、"Alice Chen"、"Lorem ipsum"。如果用户未提供数据，询问用户。
• 页脚 PAGE 字段：通过 raw-set 设置页码时，XML 结构必须准确（fldChar/instrText/fldChar 序列）。
• 用空段落做间距：使用 spacing-after 属性。
• 手动项目符号字符（-、*）：使用 listStyle=bullet 或 listStyle=number。
• 手动字体 XML 注入：当 --prop font=... 足够时使用它。
• 忽略参考材料：如果 officecli 无法完成复杂任务，在放弃之前阅读 references/*.md 并检查 scripts/*.py。
• 重建现有样式：当用户提供源文件时，复制并修改 — 不要从零重建样式。

工具发现

在猜测之前始终从帮助中确认语法：

officecli --help
officecli help docx
officecli help docx add
officecli help docx set
officecli help docx query
officecli help docx add paragraph --json
officecli help docx set run --json

依赖项

前置条件检查

# 必需
python3 -c "import docx, lxml" || echo "MISSING: pip install python-docx lxml"

# 按需：LibreOffice
which soffice >/dev/null 2>&1 || echo "INFO: LibreOffice not installed"

# 按需：OfficeCLI
which officecli >/dev/null 2>&1 || echo "INFO: OfficeCLI not installed"