Office Toolkit — Office 文件工具箱

> v1.5.0 | 读取·创建·转换·编辑 | 四管道路由 | 验证: 2026-07-11

定位声明

> Office Toolkit 是离线批处理工具箱，专注「文件进、文件出」的批量读写 / 创建 / 转换。
> - ✅ 覆盖 PDF（读取 / 抽取）
> - ✅ 跨平台：读取功能仅需 Python，macOS / Linux 可运行
> - ✅ 零外部服务依赖：纯 Python，无需常驻任何编辑器进程
> - ✅ 批处理 / 自动化：适合「把 N 个文件批量转换 / 抽取」的脚本活
> - ✅ 离线编辑已有 XLSX：改单元格/公式、行列插删（openpyxl，纯本地无 Office）
> - ✅ 离线编辑已有 DOCX：改文本/段落（stdlib，零依赖，自动备份）
> - ❌ 不做实时协作编辑：不打开你正看的文档做所见即所得修改
> - ❌ 不接入在线文档：不直接读写云端协作文档
>
> 与「实时编辑类 Office skill」互补不重叠：本工具解决离线、批量、无依赖；实时编辑类解决你正在看的某文档要改某句话的交互场景。

平台兼容性

> Office→PDF 转换依赖 Windows COM 自动化，需要 Microsoft Office 或 WPS Office 专业版（个人版不注册 COM 服务器，会失败回退 MSO）。

路由表 — 四管道模式

加载规则： 只读取用户当前任务对应的参考文件，不要全部加载。一次只走一个管道。

> 遇到错误？ 加载 references/troubleshooting.md 查看错误码对照表和常见问题解答。
> 想避开常见坑？ 加载 references/anti-patterns.md 查看「不该怎么做」的反模式清单。
> 第一次用？ 加载 references/workflow.md 查看 3 个完整端到端流程演示。

什么时候用本工具？

> 以下典型场景适用本工具：

> 什么时候不用本工具？
> - 要改正在看的文档里某句话 → 用「实时编辑类 skill」（本机实时协作编辑类工具）
> - 要读写腾讯文档/金山文档 → 用对应云文档 skill
> - 要做在线协作 → 本工具是离线批处理，不做实时协作

能力矩阵

> 状态图例： ✅ 已验证 = 已通过自动化或人工验证；— = 不适用；❌ = 不支持。

环境依赖

基础（零额外安装）

• Python 3.11+（zipfile、xml.etree.ElementTree、subprocess、json、csv）
• pdftotext（Git Bash / MSYS2 内置）
• 支持： PDF读取、DOCX/XLSX/PPTX读取、DOCX/XLSX基础创建、XLSX→CSV/JSON

可选 pip 安装

系统软件（仅 PDF 转换需要）

• Microsoft Office 2016+ 或 WPS Office 专业版（个人版不注册 COM 自动化服务器，转 PDF 会失败并优雅回退 MSO）
• WPS ProgID: kwps.Application / KWPP.Application / KET.Application（需专业版才可用）
• MSO ProgID: Word.Application / PowerPoint.Application / Excel.Application（全版本通用，基础 ProgID 无版本号）
• 代码自动检测，默认 MSO 优先 → 回退 WPS（见 references/convert.md 候选表）：遍历该格式所有已知候选 ProgID，取首个能真实实例化的；WPS 候选失败不影响 Office 路径

其他可选库: reportlab(PDF创建), python-docx(DOCX创建), docx2pdf(DOCX→PDF), pdf2docx(PDF→DOCX)

> 更多坑与约束见下方「关键技术警告」（ElementTree 命名空间）与「已知限制」（XLSX 中文字体）。

关键技术警告

> Python 3.13+ ElementTree 命名空间 Bug (已验证)
>
> ElementTree.iter('{namespace}tag') 在 Python 3.13+ 对 OOXML 命名空间处理不稳定，
> 可能返回空结果。所有 XML 解析必须使用 tag.endswith('}localname') 方式匹配。
>
> 正确写法:
> python > for elem in root.iter(): > if elem.tag.endswith('}row'): > ... >
> 错误写法:
> python > for elem in root.iter(f'{NS}row'): # 可能返回空! > ... >

质量验证

• 自动化用例（test_p0.py，随包不发布）：覆盖 XLSX 创建（公式 / 13 财务色系 / 跨表引用 / IF 公式转义）、读取回环（XLSX·DOCX·PPTX）、XLSX→CSV·JSON、EDIT 管道改单元格与行列插删，全部 PASS。
• 人工验证：DOCX / PPTX / XLSX→PDF 的 COM 自动化在 WPS 与 Microsoft Office 2019 双引擎实测通过。
• 发布包不含测试文件，用户安装版本不携带测试代码。

已知限制

• DOCX/XLSX stdlib 创建仅支持纯文本/数值，无样式表格图片
• PPTX 创建必须用 python-pptx（WPS 要求 47 个内部文件，stdlib 不可行）
• PDF→DOCX 转换质量低，建议两步法: pdftotext + create_docx
• PDF 扫描件无法提取文字，需 OCR
• Office→PDF 转换仅限 Windows + WPS/MS Office
• XLSX 中文字体：stdlib 手写必须设 宋体/微软雅黑 + charset=134（推荐 openpyxl 避坑）

性能预期（文档大小承载）

基于 stdlib（zipfile + ElementTree 全量解析）的预测：

> ElementTree 是全量解析（非流式），内存开销约为原始 XML 的 5-10 倍。
> 日常文档（报告/表格/PPT）完全够用；超大 XLSX 建议切换 openpyxl 流式模式。

变更记录