office360 — Office 文件工具箱 (v2.1.0)

> v2.1.0 | 读取·创建·转换·编辑 | 四管道路由 | 验证: 2026-07-20
> 融合 v1.5.0 前身(轻量/工程化/Windows COM) 与 skills-office-v1(公式真重算/视觉 QA/全 PDF 能力) 两者优点。

5 分钟快速开始

下面三个完整工作流无需翻看其他文件，复制代码即可跑通。运行前先检查环境：

python scripts/env_check.py     # 一键诊断依赖，缺什么装什么

场景一：读取 Excel → 计算 → 写入新文件（零依赖，仅需 Python）

"""只有 Python 标准库就能跑：读原始成绩表，加总分和等级，写出新文件。"""
from openpyxl import load_workbook, Workbook

# 1. 读取
wb = load_workbook("原始成绩.xlsx")
ws = wb.active
old_data = [[cell.value for cell in row] for row in ws.rows]
wb.close()

# 2. 计算：追加"总分"和"等级"列
new_data = [old_data[0] + ["总分", "等级"]]  # 表头
for row in old_data[1:]:
    name, *scores = row[0], *(v for v in row[1:] if isinstance(v, (int, float)))
    total = sum(scores)
    grade = "A" if total >= 270 else "B" if total >= 240 else "C" if total >= 210 else "D"
    new_data.append(row + [total, grade])

# 3. 写入
out = Workbook(); out_ws = out.active
for r in new_data: out_ws.append(r)
out.save("成绩带等级.xlsx"); out.close()
print("✅ 成绩带等级.xlsx 已生成")

场景二：批量 Office 文件转 PDF（一条命令）

# 整个目录下所有 docx/xlsx/pptx 转为 PDF，自动硬边界/重试/失败汇总
python scripts/batch_convert.py ./文档/ ./输出/

# 单个文件
soffice --headless --convert-to pdf 报告.docx
# Windows 高保真转换可走 COM（批量和单个都支持）

场景三：创建带公式的 Excel → 重算 → 转 PDF（完整链路）

"""生成销售报表，含 SUM/IF 公式，LibreOffice 重算后导出 PDF。"""
from openpyxl import Workbook
wb = Workbook(); ws = wb.active
ws.append(["地区", "销售额", "目标"])
ws.append(["华东", 120, 100])
ws.append(["华北", 90, 100])
ws.append(["华南", 150, 100])
ws.append(["合计", "=SUM(B2:B4)", "=SUM(C2:C4)"])
ws.append(["达成率", "=IF(C5>0, B5/C5, 0)", ""])
wb.save("销售表.xlsx")
print("✅ 销售表.xlsx 已生成，含未重算公式")

# 重算公式（关键！不重算则下游读到空值）
python scripts/recalc.py 销售表.xlsx
# → 输出 JSON：status=success, total_formulas=3, total_errors=0

# 导出 PDF
soffice --headless --convert-to pdf 销售表.xlsx
# → 生成 销售表.pdf，B5=360, C5=300, B6=1.20 ✅

> 下一步： 需要更详细的 API 参数或管道细节时，浏览下方的「快速开始：选对管道」和 references/ 目录。

v2 相对前代的关键增强

快速开始：选对管道（触发决策）

用户一句话通常对应四条管道之一。先判断意图，再进对应 references/*：

> 管道不叠加：一个任务通常只走一条主管道。如「做表 → 重算 → 转 PDF」是 CREATE 起步、完成后接 CONVERT，仍按主意图选 CREATE。

编辑入口对照表（防混淆）

用户说“编辑/修改/更新”时，先按文件格式选入口，不要死记模块名：

> 记忆口诀：Excel 找 edit.md，Word 找 docx_edit.md，不用理解四个模块的完整划分。

端到端示例（一句话需求 → 落地）：
- 用户：「帮我把这份 Word 转成 PDF」
→ CONVERT：soffice --headless --convert-to pdf 文档.docx（Windows 可走 office_to_pdf COM）
- 用户：「做个带公式的销售表」
→ CREATE：create_xlsx(...)（含 SUM/IF）→ 收尾 python scripts/recalc.py 销售表.xlsx 真重算
- 用户：「提取这个扫描 PDF 的文字」
→ READ：先 pdftotext；若为空 → OCR（pytesseract + pdf2image，见 read.md 扫描件 OCR 段）
- 用户：「把表里 B2 改成 100」
→ EDIT：openpyxl 改单元格 → 自动 .bak 备份

端到端实战：含公式销售报表 → 真重算 → 转 PDF

> 把 CREATE → recalc → CONVERT 串成一条完整链路，覆盖复杂场景。下面以「生成带公式的销售表，算出合计/达成率，再导出 PDF」为例。

① CREATE — 生成带公式的工作表

from openpyxl import Workbook
wb = Workbook(); ws = wb.active
ws.append(["地区", "销售额", "目标"])
ws.append(["华东", 120, 100])
ws.append(["华北", 90, 100])
ws.append(["华南", 150, 100])
ws.append(["合计", "=SUM(B2:B4)", "=SUM(C2:C4)"])   # 公式字符串，尚未计算
ws.append(["达成率", "=IF(C5>0, B5/C5, 0)", ""])     # 公式字符串
wb.save("销售表.xlsx")

② RECALC（关键）— LibreOffice 无头真重算

create_xlsx 只写入公式字符串，非 Excel 程序读到的是空值。必须由 recalc.py 调用 LibreOffice 真正计算并写回数值：

python scripts/recalc.py 销售表.xlsx
# 重算后：B5=360, C5=300, B6=1.20（达成率）

③ CONVERT — 转 PDF

soffice --headless --convert-to pdf 销售表.xlsx   # 跨平台兜底
# Windows 高保真走 COM：python scripts/com_probe.py（探测可用后调用 office_to_pdf）

④ QA（可选）— 核对落盘值

pdftotext 销售表.pdf - | grep -E "360|300|120%"
# 命中即证明公式已真重算并写入 PDF

> 要点：recalc.py 是含公式 XLSX 的强制收尾步骤，否则下游读到空值。批量同理——每张表生成后都走一遍 recalc.py。

限制与前置依赖（用前必读）

把藏在代码里的限制显式列出，避免误用：

• 零依赖可用：读取 PDF/DOCX/XLSX/PPTX、创建基础 DOCX/XLSX/PPTX，仅需 python3（标准库）。
• 需 LibreOffice（soffice）：XLSX 公式真重算（recalc.py）、PPTX 视觉 QA、跨平台 →PDF 兜底转换。
• 仅 Windows 可用：原生高保真 →PDF 走 Office/WPS 的 COM 自动化（com_probe.py 探测）；macOS/Linux 不支持。
• 需 Tesseract + chi_sim：PDF 扫描件 OCR。
• 批量 / 大文件：单任务有明确硬边界，避免无限等待或资源耗尽；超限时脚本会自动拒绝或拆批，不再只是"建议"。
• 单次任务：最多处理 100 个文件 或总大小 ≤ 500MB（以先到为准）。
• 单个 XLSX 编辑：文件 > 15MB 时，改用 read_only / write_only 模式或分工作表处理。
• 单个 PDF/Office 转换：文件 > 100MB 或页数 > 500 页 时自动拆批。
• 单次外部进程调用：默认 300 秒 超时，超时会自动结束并返回可读错误。
• 超过上述任一阈值，脚本会抛出 ValueError 或自动拆批，而不是默默执行。
• 最小可用路径：只想读 / 创建基础文档 → 只装 python3；要全功能 → 装 LibreOffice + 下列 pip 依赖。

pip install python-pptx openpyxl python-docx pypdf pdfplumber reportlab pytesseract pdf2image
# 系统侧：LibreOffice、Poppler(pdftotext/pdftoppm)、Tesseract(+chi_sim)、qpdf/pdftk(可选)

异常速查（不用翻文档）

遇到报错时先查下表，大部分问题可秒定位：

> 完整排查流程见 references/troubleshooting.md。运行前推荐先跑 python scripts/env_check.py 确认环境。

运行稳定性保障

office360 将批量与特殊环境的处理从"手工建议"变成脚本级自动化，降低用户手动调整成本：

• 自动硬边界：batch_convert.py 对批量转换做 100 文件 / 500MB 总计 / 100MB 单文件 / 300 秒超时 自动拦截；超限时直接给出结构化错误，不会无限卡死。
• 自动重试：每个文件转换失败会重试 3 次；重试仍失败保留在汇总结果中，成功/失败一目了然。
• 环境先行：env_check.py 在运行前检查 Python 库、系统二进制、Windows COM 状态，并给出安装命令，避免报错后翻文档。
• 结构化错误：recalc.py、docx_edit.py、batch_convert.py 出错时统一返回 {error, suggestion}，明确"为什么失败"和"下一步怎么做"。

定位声明

> office360 是离线批处理工具箱，专注「文件进、文件出」的批量读写 / 创建 / 转换 / 编辑。
> - ✅ 覆盖 PDF（读取 / 抽取 / OCR / 表单 / 合并拆分 / 生成）
> - ✅ 跨平台：读取/创建/编辑功能仅需 Python，macOS / Linux / Windows 均可运行
> - ✅ 零外部服务依赖：纯 Python，无需常驻任何编辑器进程
> - ✅ 批处理 / 自动化：适合「把 N 个文件批量转换 / 抽取 / 改」的脚本活
> - ✅ 离线编辑已有 XLSX/DOCX：改单元格/公式/行列插删（自动备份原文件）
> - ✅ XLSX 公式真重算：LibreOffice 无头计算，导出文件自带计算值
> - ✅ PPTX 视觉 QA：自动检测版式问题
> - ❌ 不做实时协作编辑：不打开你正看的文档做所见即所得修改
> - ❌ 不接入在线文档：不直接读写云端协作文档

平台兼容性

> 依赖说明：只要装了 libreoffice，macOS/Linux 即可获得公式重算 + PDF 转换 + 视觉 QA；Windows 若装有 Office/WPS 则 COM 转 PDF 保真度更佳，否则同样走 LibreOffice。

路由表 — 四管道模式

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

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

能力矩阵

> 状态图例： ✅ 已验证 = 已通过验证；— = 不适用；❌ = 不支持。

环境依赖

基础（推荐安装，解锁重算/QA/PDF 能力）

• python3 3.11+
• libreoffice（或 soffice）：XLSX 公式真重算、PPTX 视觉 QA、PDF 跨平台转换兜底
• pdftotext（PDF 文本提取；macOS 可用 brew install poppler，Linux apt install poppler-utils）
• Python 库：openpyxl==3.1.5、python-pptx==1.0.2、pypdf、pdfplumber、reportlab、pytesseract、pdf2image、python-docx

Windows 可选：COM 自动化（保真度更高的 →PDF）

• pywin32==312 + 已安装 Microsoft Office 或 WPS Office 专业版（office_to_pdf() 自动探测引擎）

> 零依赖读取：即使不装 LibreOffice/Office，仅用 Python stdlib 也可读取全部四种格式（read.md）与创建基础 XLSX/DOCX、XLSX→CSV/JSON。

关键技术警告

> Python 3.13+ ElementTree 命名空间 Bug（已验证）
> ElementTree.iter('{namespace}tag') 在 Python 3.13+ 对 OOXML 命名空间处理不稳定，可能返回空结果。
> 所有 XML 解析必须使用 tag.endswith('}localname') 方式匹配（见 read.md/create.md 实现）。

核心增强一：XLSX 公式真重算（v2 关键）

背景：create_xlsx / edit_cell 写入的是 <f>公式</f><v></v>（值留空）。Excel/WPS 打开时会计算，但被 openpyxl（非 data_only）或 stdlib 读回时 <v> 为空——程序化下游会拿到空值。v2 统一在创建/编辑后调用重算，让文件自带计算值。

用法（创建或编辑含公式的 XLSX 后必做）：

python scripts/recalc.py <file.xlsx>

• 首次自动配置 LibreOffice StarBasic 宏 RecalculateAndSave（calculateAll → store → close）。
• 扫描所有单元格，检测 7 类错误：#VALUE! #DIV/0! #REF! #NAME? #NULL! #NUM! #N/A。
• 输出 JSON：status(success/errors_found)、total_errors、error_summary、total_formulas。
• Agent 据错误定位修复 → 再次 recalc，迭代至零错误。

无 LibreOffice 的回退：若环境无 libreoffice，改用 scripts/formula_check.py <file.xlsx> 做静态错误扫描（#REF! 等），并明确告知用户「公式值需由 Excel/WPS 打开时计算」。此回退不写回 <v>。

> CREATE 管道收尾：create_xlsx(...) 后若无 LibreOffice 会警告；建议始终 python scripts/recalc.py 输出.xlsx 收尾。
> EDIT 管道收尾：改了公式的单元格后同样调用 recalc.py（已自动 .bak 备份，可放心重算）。

核心增强二：PPTX 视觉 QA（v2 关键）

创建 PPTX 后，转换为图片做视觉检查，自动发现版式问题：

# 1) PPTX → PDF（LibreOffice 无头）
soffice --headless --convert-to pdf presentation.pptx
# 2) PDF → JPEG（每页一张）
pdftoppm -jpeg -r 150 presentation.pdf slide
# 生成 slide-1.jpg, slide-2.jpg ...

随后用子代理（subagent）逐张检查：占位符文本未替换、元素重叠、文本溢出、低对比度、字体未生效。发现问题 → 回到 create_pptx 修正 → 重新 QA。

PPTX 设计指引（避免通用 AI 丑版式）：
- 配色：每套演示固定 1 主色 + 1 辅色 + 中性灰，全篇统一（勿每页随机色）。
- 布局：优先「标题 + 要点列表」「双栏」「图标行」「半幅图」四类，避免满屏文字。
- 字体：中文用 微软雅黑/思源黑体；英文用 Arial/Calibri；标题 28–40pt，正文 18–24pt。
- 留白：正文框边距 ≥0.5 英寸，单页要点 ≤6 条。
- 一致性：同层级标题/正文字号、颜色必须一致。

核心增强三：PDF 全能力（v2 关键）

加载 references/read.md 与下方要点：

• OCR 扫描件：pdftotext 拿不到文字时，用 pytesseract + pdf2image（PDF→图片→识别）：
  python from pdf2image import convert_from_path import pytesseract pages = convert_from_path('scan.pdf', dpi=300) text = '\n'.join(pytesseract.image_to_string(p, lang='chi_sim+eng') for p in pages)
• 合并 / 拆分 / 旋转 / 加水印 / 加密：pypdf（PdfReader/PdfWriter）+ pdftk + qpdf。
• 生成 PDF：reportlab（程序化排版）或 weasyprint（HTML→PDF）。
• 填表：pypdf 读取/填写 AcroForm 字段（复杂表单建议先 pdf2image 转图人工核对字段坐标）。
• 文本/表格提取：pdfplumber（保留表格结构）或 pdftotext -layout。

转换 →PDF：双引擎择优

references/convert.md 的 office_to_pdf() 实现：
- Windows：优先 Microsoft Office COM（保真度高），WPS 候选失败自动优雅回退 MSO（_detect_engine() 真实 Dispatch 探测，取首个可用 ProgID）。
- 跨平台 / 无 Office：改用 LibreOffice 无头：
bash soffice --headless --convert-to pdf --outdir <outdir> <file>
- 决策规则：有 Office/WPS 且需最高保真 → COM；否则 → LibreOffice。两者输出均为标准 PDF，可继续走 PPTX 视觉 QA 或 PDF 文本提取。

各管道要点

• READ：见 references/read.md（PDF pdftotext；DOCX/XLSX/PPTX unzip+XML stdlib，零依赖；PDF 扫描件见上文 OCR）。
• CREATE：见 references/create.md（create_xlsx 模板骨架+13 财务色系+多 Sheet；create_docx stdlib/python-docx；create_pptx python-pptx）。XLSX 含公式须收尾 recalc.py；PPTX 须收尾视觉 QA。
• CONVERT：见 references/convert.md（XLSX→CSV/JSON stdlib；PDF→TXT；DOCX/PPTX/XLSX→PDF 双引擎；PDF→DOCX 两步法；MD/HTML/IMG→PDF）。
• EDIT：XLSX 见 references/edit.md（openpyxl 改单元格/公式/插删行列，默认 .bak 备份，改公式后 recalc.py）；DOCX 见 references/docx_edit.md（stdlib 文本/段落替换，自动 .bak 备份）。

测试记录（诚实声明）

> 标注说明：【自动】 = 自动化用例；【人工】 = 需在本机用 WPS/Office 打开验证。
> v2 在 v1.5.0 基础上新增/变更：

> 诚实边界：recalc.py / 视觉 QA / PDF 跨平台转换依赖 libreoffice；COM 转 PDF 依赖 Windows + Office/WPS。发布包不含测试文件，用户装到的版本不含测试。

已知限制

• DOCX/XLSX stdlib 创建仅支持纯文本/数值，无样式表格图片（用 python-docx/openpyxl 可破）。
• PPTX 创建必须用 python-pptx（WPS 要求 ~47 个内部文件，stdlib 不可行）。
• PDF→DOCX 转换质量低，建议两步法：pdftotext + create_docx。
• PDF 扫描件需 OCR（已支持 pytesseract）。
• Office→PDF：Windows 优先 COM；无 Office 时走 LibreOffice（保真度略低但可用）。
• XLSX 中文字体：stdlib 手写必须设 宋体/微软雅黑 + charset=134（推荐 openpyxl 避坑）。
• 公式真重算/视觉 QA/跨平台 PDF 均需 libreoffice。

性能预期

变更记录

参考文件索引

• references/read.md — 四种格式读取（含 PDF OCR 提示）
• references/create.md — 创建 XLSX/DOCX/PPTX（含公式与 13 财务色系；XLSX 收尾重算）
• references/convert.md — 转换（XLSX→CSV/JSON、→PDF 双引擎、PDF→TXT/DOCX、MD/HTML/IMG→PDF）
• references/edit.md — 编辑已有 XLSX（openpyxl，自动备份）
• references/docx_edit.md — 编辑已有 DOCX（stdlib，自动备份）
• references/anti-patterns.md — 反模式清单
• references/troubleshooting.md — 排错与错误码
• references/workflow.md — 3 个端到端流程
• scripts/recalc.py — XLSX 公式真重算 + 错误扫描（LibreOffice），返回结构化错误与建议
• scripts/formula_check.py — XLSX 公式静态错误扫描（无 LibreOffice 回退）
• scripts/com_probe.py — Windows COM 引擎自检
• scripts/env_check.py — 环境依赖一键诊断（Python 库 / 系统二进制 / COM 状态）
• scripts/batch_convert.py — 批量 Office → PDF 自动转换（硬边界 / 进度 / 重试 / 失败汇总）
• scripts/docx_edit.py / scripts/docx_format.py — DOCX 编辑与 GB/T 9704 排版
• scripts/version_check.py — 版本一致性校验
• templates/minimal_docx / templates/minimal_xlsx — 预验证骨架