Office Toolkit
📖 技能介绍
name: office-toolkit slug: office-toolkit-ela displayName: Office Toolkit version: 1.5.1 description: "Office 文件离线批处理工具箱，专注「文件进、文件出」：读取 / 创建 / 转换 / 编辑 PDF·DOCX·PPTX·XLSX。读取零依赖（纯 Python，跨平台）；XLSX 创建支持公式与 13 种财务配色（蓝=输入 / 黑=公式 / 绿=跨表引用）；格式转换支持 WPS 与 Microsoft Office 双引擎（→PDF / →CSV / →JSON）。适用于批量、离线、自动化的 Office 文件处理。" license: MIT visibility: public metadata: requires: bins: - python3 optionalBins: - pdftotext pipDeps: - python-pptx==1.0.2 - openpyxl==3.1.5 - pywin32==312 platforms: - windows notes: "读取功能跨平台(Python stdlib)；Office→PDF 转换仅限 Windows + WPS/MS Office"
Office Toolkit — Office 文件工具箱
v1.5.0 | 读取·创建·转换·编辑 | 四管道路由 | 验证: 2026-07-11
定位声明
Office Toolkit 是离线批处理工具箱，专注「文件进、文件出」的批量读写 / 创建 / 转换。 - ✅ 覆盖 PDF（读取 / 抽取） - ✅ 跨平台：读取功能仅需 Python，macOS / Linux 可运行 - ✅ 零外部服务依赖：纯 Python，无需常驻任何编辑器进程 - ✅ 批处理 / 自动化：适合「把 N 个文件批量转换 / 抽取」的脚本活 - ✅ 离线编辑已有 XLSX：改单元格/公式、行列插删（openpyxl，纯本地无 Office） - ✅ 离线编辑已有 DOCX：改文本/段落（stdlib，零依赖，自动备份） - ❌ 不做实时协作编辑：不打开你正看的文档做所见即所得修改 - ❌ 不接入在线文档：不直接读写云端协作文档
与「实时编辑类 Office skill」互补不重叠：本工具解决离线、批量、无依赖；实时编辑类解决你正在看的某文档要改某句话的交互场景。
平台兼容性
| 功能 | Windows + WPS/MSO | macOS / Linux |
|---|---|---|
| 读取 PDF/DOCX/PPTX/XLSX | ✅ | ✅（仅需 Python） |
| 创建 DOCX/XLSX（纯文本） | ✅ | ✅（stdlib） |
| 创建 PPTX | ✅ python-pptx | ✅ python-pptx |
| 转换 →PDF（COM 自动化） | ✅ | ❌ |
| 转换 XLSX→CSV/JSON | ✅ | ✅（stdlib） |
Office→PDF 转换依赖 Windows COM 自动化，需要 Microsoft Office 或 WPS Office 专业版（个人版不注册 COM 服务器，会失败回退 MSO）。
路由表 — 四管道模式
| 管道 | 用户意图 | 触发词 | 加载 |
|---|---|---|---|
| READ 读取 | 打开/查看/阅读 PDF/DOCX/PPTX/XLSX | "打开""看看""读取""查看" | references/read.md |
| CREATE 创建 | 新建/生成/写出 DOCX/XLSX/PPTX | "新建""创建""生成""做一个" | references/create.md |
| CONVERT 转换 | 格式转换 →PDF/→CSV/→JSON/→TXT | "转换""导出""另存为""转PDF" | references/convert.md |
| EDIT 编辑 | 修改已有 XLSX/DOCX：XLSX改单元格/公式/行列插删；DOCX改文本/段落（备份原文件） | "修改""改""编辑""更新单元格""插入行""删除列""替换文本" | XLSX→references/edit.md；DOCX→references/docx_edit.md |
加载规则： 只读取用户当前任务对应的参考文件，不要全部加载。一次只走一个管道。
遇到错误？ 加载
references/troubleshooting.md查看错误码对照表和常见问题解答。 想避开常见坑？ 加载references/anti-patterns.md查看「不该怎么做」的反模式清单。 第一次用？ 加载references/workflow.md查看 3 个完整端到端流程演示。
什么时候用本工具？
以下典型场景适用本工具：
| 典型需求 | 本工具能力 | 说明 |
|---|---|---|
| 批量将 10 个 Excel 转为 PDF 交付 | 批量 XLSX→PDF | 循环调用 office_to_pdf()，自动重试 + 清理 |
| 从 PDF 表格提取结构化数据 | PDF→结构化数据 | read_pdf() 提取文字，pdf_to_markdown() 保留表格 |
| 从零创建含公式的成绩表 / 报价单 | 从零创建 XLSX | create_xlsx() + 公式单元格，13 种财务配色样式 |
| 将 Word 文档转为 PDF 交付客户 | DOCX→PDF | COM 自动化，WPS 或 MSO 均可 |
| 读取包含多个工作表的 Excel | 多 Sheet 读取 | read_xlsx(path, sheet_index='all') |
| 将 Excel 导出为 CSV/JSON 供其他系统使用 | XLSX→CSV/JSON | 纯 stdlib，不依赖 Office |
| 修改已有 Excel：改某格数值/公式、插入或删除行列 | 编辑已有 XLSX | edit_xlsx()(openpyxl)，纯本地，自动备份原文件 |
| 修改已有 Word 文档中的文本内容 | 编辑已有 DOCX | edit_docx_text()(stdlib)，零依赖，自动备份原文件 |
| 从零生成 PPT 汇报文稿 | 创建 PPTX | create_pptx() + python-pptx |
| 文件无法打开 / 转换报错 / 进程无响应 | 排查问题 | 先看 troubleshooting.md，再查 anti-patterns.md |
什么时候不用本工具？ - 要改正在看的文档里某句话 → 用「实时编辑类 skill」（本机实时协作编辑类工具） - 要读写腾讯文档/金山文档 → 用对应云文档 skill - 要做在线协作 → 本工具是离线批处理，不做实时协作
能力矩阵
| 格式 | 读取 | 创建(stdlib) | 创建(库) | 公式 | 样式 | 编辑已有 | 转换出 |
|---|---|---|---|---|---|---|---|
| ✅ pdftotext | ❌ | reportlab/fpdf2 | — | — | — | →TXT/→DOCX | |
| DOCX | ✅ unzip+XML | ✅ 已验证 | python-docx | — | — | ✅ stdlib | →PDF ✅COM(WPS+MSO) |
| PPTX | ✅ unzip+XML | ❌ 结构复杂 | python-pptx ✅ 已验证 | — | ✅ | — | →PDF ✅COM(WPS+MSO) |
| XLSX | ✅ unzip+XML | ✅ 已验证 | openpyxl ✅ 已验证 | ✅ SUM/AVG/IF等 | ✅ 13位财务色系 | 编辑已有✅(openpyxl) | →CSV/→JSON/→PDF ✅COM(WPS+MSO) |
状态图例：
✅ 已验证= 已通过自动化或人工验证；—= 不适用；❌= 不支持。
环境依赖
基础（零额外安装）
- Python 3.11+（
zipfile、xml.etree.ElementTree、subprocess、json、csv） pdftotext（Git Bash / MSYS2 内置）- 支持： PDF读取、DOCX/XLSX/PPTX读取、DOCX/XLSX基础创建、XLSX→CSV/JSON
可选 pip 安装
| 库 | 用途 | 安装命令 |
|---|---|---|
python-pptx |
PPTX 创建 | pip install python-pptx==1.0.2 |
openpyxl |
XLSX 创建（推荐） | pip install openpyxl==3.1.5 |
pywin32 |
COM 自动化转 PDF（仅 Windows） | pip install pywin32==312 |
系统软件（仅 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 全量解析）的预测：
| 格式 | 舒适范围 | 极限边界 | 瓶颈 |
|---|---|---|---|
| 500MB+ | ~2GB | pdftotext 是 C 程序，几乎无上限 | |
| DOCX | ~10MB | ~30MB | ElementTree 内存 ≈ XML ×5-10 |
| XLSX | ~5MB / ~2万行 | ~15MB / ~6.5万行 | 超 2 万行建议 openpyxl read_only |
| PPTX | ~50MB / ~200页 | ~100MB | 每 slide XML 较小，整体可控 |
| COM转换 | 取决于 Office | ~100MB+ | 瓶颈在 COM 调用超时 |
ElementTree 是全量解析（非流式），内存开销约为原始 XML 的 5-10 倍。 日常文档（报告/表格/PPT）完全够用；超大 XLSX 建议切换 openpyxl 流式模式。
变更记录
| 版本 | 日期 | 变更 |
|---|---|---|
| 1.5.1 | 2026-07-23 | 发布主页清理：优化描述、移除内部测试/评审内容、变更记录精简为公开版 |
| 1.5.0 | 2026-07-11 | 新增 DOCX 编辑能力、DOCX 排版规范工具、DOCX 模板骨架 |
| 1.4.5 | 2026-07-07 | OOXML 关系文件修复、Office/WPS 进程残留三层防护、多 Sheet 支持、反模式文档、端到端工作流演示 |
🤖 AI 评测
这是一个功能全面、文档详尽的 Office 工具箱，支持 PDF、Word、Excel、PPT 的读取和转换，批量处理能力强，新手也能快速上手。文档质量好，遇到问题有据可查。适合需要离线批量处理 Office 文件的用户。不过它依赖 Windows 系统才能发挥全部能力，非 Windows 用户功能受限；另外处理超大文件或包含复杂样式的文档时可能遇到兼容性问题，使用前建议做好文件备份。
