办公文档三件套（Word / Excel / PDF）

一句话：在你自己的电脑上处理 Word、Excel、PDF——不联网、不上传、不需要 API Key。

30 秒看懂

它不会做的：联网调 AI（改写润色、录音转写）、专业排版。
扫描件（图片 PDF）：能渲染成图片交给"能看图的 AI"读出文字（ocr_helper.py），但识别质量取决于模型，本套件不含内置 OCR 引擎。
原因见「能力边界」。

💰 收费说明（只有云端体检收费）

什么时候走云端（付费）/ 什么时候留在本地（免费）

> 按需选用，不强行推荐：能本地做完的，直接本地做完；需要可归档结论或本机装不了环境时，再说明云端体检可选（0.99 元/次）。是否使用由你决定。

付款界面从哪来（官方口径）：SkillHub 的 Pay Skill 设计就是「在 AI 智能体内直接完成支付、无需跳出界面」——
收银界面由支付宝官方买家组件（@alipay/agent-payment）渲染并弹出，就是那个「Agent 支付体验助手」窗口：
金额 / 订单号 / 「点此授权」/ 二维码。
我们的脚本只负责调起官方组件（pay 里跑官方 alipay-bot），不自己造收银台；同时把同一份收银信息
（金额 / 订单号 / 链接 / 二维码）也贴到对话里，保证在"弹不出官方窗口"的宿主里照样能付：

支付宝 AI 付 · 待你授权付款
  金额：¥0.99    订单号：2026…
  支付链接：https://u.alipay.cn/_…
  二维码：![支付宝收款码 ¥0.99](file:///…/payment-confirm-….png)
  · 现在还没扣钱：你在支付宝确认授权后才扣 ¥0.99
  · 不打算付就直接关掉，订单会自己失效，不产生费用

> 完整流程：跑 probe（不扣钱）拿到 402 账单 → 跑 pay → 官方组件弹收银界面（或看对话里的付款卡）→
> 你授权付款 → 跑 complete 取回结果。

调用顺序（四步，请按顺序执行）

> 助手请注意：不要跳步，也不要自己另写请求代码——统一调用本包脚本，否则订单对不上。
>
> 第 1 步若报「有未完成的账单」：说明上一次的账单还挂着（防串单）。没付款就执行 node scripts/office-doc-suite-paid.mjs reset 清理；
> 已付款就用 complete --out-shake-no <订单号> 取结果，不要重新下单。过期账单会被自动清理。

• 入参不全时服务端把缺项写进 402 响应体（input_ready=false）——先补齐再付，避免白付。
• 依赖：node >= 18；付款需官方 CLI：npx -y @alipay/agent-payment@latest install。
• 数据流向：只发你提交的文本/摘要（发送前把身份证/手机号/银行卡/邮箱换成占位符），文件本体不上传；脚本不接触任何密钥。

什么时候用这个 Skill

该用：
- 手上是 .docx / .xlsx / .pdf / .doc / .xls，要生成、改、合并、拆分、转换
- 表格要排序、筛选、算合计、写活公式、出图表，或发出去前想查一遍有没有公式错误
- Word 要自动目录、页眉页脚页码，或要把 Markdown 转成 Word
- PDF 要加水印，或要把身份证 / 手机号 / 银行卡 / 邮箱打码（对外发送前必做）
- 要工作报告、月度预算、合同、简历的现成模板

不该用：
- 需要 AI 改写、录音转写、云端检索 → 换联网型 Skill（那类功能会把文档送出本机）
- 扫描件（图片 PDF）里的文字 → 本套件读不到，先做 OCR
- 专业排版（艺术字、复杂图表排版）→ 用 Word / WPS

🗣️ 对 AI 怎么说（照抄就能用）

不用记命令，直接用日常话说；命中下面任一句式，AI 就会用本套件：

说不清也没关系：直接说「我这份表要发给客户前检查一下」，它会先跑 health 体检再给结论。

✨ 效果速览（不用看图，三行看懂每项能力会产出什么）

① 表格：合并 → 活公式 → 排序 → 筛选 → 出图 → 体检

体检（health）会直接告诉你这样的结论：

1) 公式错误残留: 0
2) 缓存值可能过期: 4        → 用 Excel/WPS 打开重算一次
3) 公式内硬编码数字: 2      → 建议改成引用「假设单元格」
4) 编号类字段被存成数字: 1  → 列「身份证号」3 个疑似 → 跑 protect
结论: ❌ 建议修完再交付

② PDF：对外发送前的标准动作

③ Word：让文档像正式文件

> 三张演示图（真实产物渲染）放在仓库的 docs/images/ 下；部分页面不显示图片时的替代方案就是上面这三张表。

📦 安装（装一次就行）

# 一键安装全部（推荐）
python scripts/setup_check.py install

# 或手动装
pip install python-docx openpyxl PyPDF2    # 必需：Word / Excel / PDF 基础
pip install pymupdf                         # 可选：PDF 转图片、加页码、水印、打码
pip install pycryptodome                    # 可选：解密 AES 加密的 PDF
pip install xlrd                            # 可选：转旧版 .xls → .xlsx

> Windows：路径直接粘贴完整路径即可，如 D:\文档\报告.pdf（含空格时用双引号包住）。
> 旧版文件：.xls 装 xlrd 后用 convert_legacy.py 自动转 .xlsx；.doc 装了 LibreOffice 会自动转，没装会提示你另存。

🔧 能力清单

Word（docx_tool.py + word_advanced.py）

常用：保真替换（只改字不动格式）｜批量替换（一次替换多组）｜生成文档｜转纯文本
进阶：自动目录｜页眉页脚与页码｜标题分页｜Markdown 转 Word｜读取大纲

Excel（xlsx_tool.py + xlsx_pro.py）

常用：读取｜统计（合计 / 平均 / 最大 / 最小）｜生成带合计的报表｜多文件合并
进阶：排序｜条件筛选｜活公式｜图表｜公式体检｜编号类型保护

PDF（pdf_tool.py + pdf_redact.py + ocr_helper.py）

常用：合并｜拆分｜提取文字｜转图片｜加页码｜加密 / 解密｜查看信息
进阶：敏感信息打码（真删文字层）+ 打码清单｜文字水印（对角 / 平铺 / 整目录批量）｜扫描件渲染成图片交给 AI 视觉识别

交付前盘点（checkup_report.py）

一句话：把一批文件（Excel / Word / PDF，支持整个目录）一次体检完，出一份可交付报告（Markdown，可选 PDF 与 JSON）。
每份文件按类型自动选体检项：Excel 查公式错误/缓存值/硬编码/编号精度，Word 查标题层级，PDF 查敏感信息（扫描件会标注"读不到文字"）。

模板（templates/gen_templates.py）

工作报告（含数据指标表与下期计划表）｜月度预算（收入 / 支出 / 汇总三表，自带公式）｜合同（九条通用条款 + 签署表）｜简历（六段式骨架）

旧格式（convert_legacy.py）

.xls → .xlsx（纯本地自动转）｜.doc → .docx（装了 LibreOffice 自动转）

⌨️ 常用命令（按使用频率排序，够用就行）

# 表格
python scripts/xlsx_tool.py stats 表.xlsx -col 销售额
python scripts/xlsx_tool.py merge a.xlsx b.xlsx -o 合并.xlsx
python scripts/xlsx_pro.py health 表.xlsx
python scripts/xlsx_pro.py sort 表.xlsx -o 排序.xlsx -col 销售额 -desc
python scripts/xlsx_pro.py filter 表.xlsx -o 筛选.xlsx -col 销售额 -op ge -value 10000

# PDF
python scripts/pdf_tool.py merge 1.pdf 2.pdf -o 合集.pdf
python scripts/pdf_tool.py split 合集.pdf -pages 1-3,5 -o 拆分目录
python scripts/pdf_redact.py redact 合同.pdf -o 脱敏.pdf --mode black
python scripts/pdf_redact.py watermark 合同.pdf -o 水印.pdf -text "内部资料"

# Word
python scripts/docx_tool.py replace-batch 模板.docx -o 成品.docx -pairs "【姓名】=>张三|【部门】=>市场部"
python scripts/word_advanced.py toc 方案.docx -o 方案-目录.docx

# 模板 / 自检
python templates/gen_templates.py --dir ./out
python scripts/self_test.py

<details>
<summary>📖 完整命令参考（点开看全部参数）</summary>

Word 基础 python scripts/docx_tool.py

create out.docx -title "周报" -body "内容1|内容2" -table "A,B|1,2"
replace in.docx -o out.docx -find "旧" -replace "新"
replace-batch in.docx -o out.docx -pairs "旧1=>新1|旧2=>新2"
totext in.docx -o out.txt

Word 增强 python scripts/word_advanced.py

outline 方案.docx
toc 方案.docx -o 方案-目录.docx -levels 3
header 方案.docx -o 终稿.docx -header "XX公司" -footer "第 X 页 / 共 Y 页"
pagebreak 方案.docx -o 分页版.docx -level 1
md2docx 说明.md -o 说明.docx

Excel 基础 python scripts/xlsx_tool.py

read data.xlsx [-sheet 表名]
stats data.xlsx -col 销售额
report data.xlsx -o 报表.xlsx -cols 销售额,目标 -sum 销售额
merge a.xlsx b.xlsx -o merged.xlsx

Excel 增强 python scripts/xlsx_pro.py

sort  表.xlsx -o 排序.xlsx -col 列名 [-desc]
filter 表.xlsx -o 筛选.xlsx -col 列名 -op eq|ne|gt|ge|lt|le|contains -value 值
formula 表.xlsx -o 活公式.xlsx -col 新列名 -tpl "=ROUND({销售额}/{目标}*100,1)"
chart 表.xlsx -o 图.xlsx -x 分类列 -y 数值列 [-kind auto|bar|line|pie]
health 表.xlsx
protect 表.xlsx -o 修复.xlsx -cols 身份证号,手机号

PDF 基础 python scripts/pdf_tool.py

merge a.pdf b.pdf -o 合集.pdf
split in.pdf -pages 1-3,5 -o 拆分目录
extract in.pdf -o out.txt [-pages 2-4]
toimage in.pdf -o 图片目录 [-dpi 150]
page-num in.pdf -o out.pdf
protect in.pdf -o out.pdf -pwd 密码
decrypt in.pdf -o out.pdf -pwd 密码
info in.pdf

PDF 水印打码 python scripts/pdf_redact.py（需 pymupdf）

scan 合同.pdf
redact 合同.pdf -o 脱敏.pdf --mode black|blur|star
watermark 合同.pdf -o 水印.pdf -text "内部资料" -mode diagonal|tile [-opacity 0.35] [-color gray|red]
batch D:\合同目录 -o D:\输出 -text "样本" -mode tile

模板 python templates/gen_templates.py

--list                 # 列出全部模板
--dir ./output         # 生成全部
--dir ./output --only 工作报告,月度预算   # 只生成指定

旧格式 python scripts/convert_legacy.py

convert_legacy.py 老表格.xls -o 新表格.xlsx
convert_legacy.py auto 老文档.doc

</details>

🧭 任务路由（AI 判断用哪个工具）

🔁 三步工作法（每个任务都照这个来）

① 动手前（STOP）—— 三件事没确认就不要开始
1. 依赖就绪：python scripts/setup_check.py check 全 ✅
2. 路径正确：文件真实存在、用完整路径、是新格式（老格式先转）
3. 不覆盖原文件：-o 一定指向新文件

> 结果明显不对劲（数字错乱、格式丢失、中文变方块）→ 先跑 python scripts/self_test.py（85 项断言，20–60 秒），
> 几分钟就能分清是环境问题还是代码问题，别靠猜。

② 动手时：照「常用命令」跑，参数不确定就查上面的完整命令参考。

③ 交付前（CHECKPOINT）—— 跑完不等于做完
1. 输出文件存在、大小非 0
2. 内容抽查：Excel 跑 health；Word 跑 outline；PDF 跑 scan（敏感信息应无命中）
3. 原文件没被动过

🚫 别这么用（都是实测踩过的坑）

⚠️ 能力边界（先看这条，避免白折腾）

依赖与外部条件（最容易卡住的地方，写全了）

> 国内网络提示：服务端域名是海外域名（Cloudflare）。若出现 402 拿不到 / 支付校验被拦，
> 先确认该域名没有被代理软件的 fake-ip 改成保留地址（例如解析成 198.18.x.x 会导致
> 官方收银 CLI 拒绝付款）。建议把它加入代理的直连/fake-ip-filter 白名单后再试。

一句话记住：普通文字、表格、合并拆分，以及排序 / 筛选 / 公式 / 图表 / 打码 / 水印 / 目录 / 模板，本套件都能干；
遇到 .xls 先转、遇到 .doc 先转、遇到扫描件先 OCR、遇到 AI 类需求换工具。

🩺 出问题了

python scripts/self_test.py            # 全量 85 项断言，20–60 秒
python scripts/self_test.py --quick    # 快速版（只用必需依赖，秒级）
python scripts/self_test.py --keep     # 保留临时产物便于人工检查

自检会在临时目录造"脏数据"（身份证写成数字、达成率写成活公式、带敏感信息的 PDF、带合并单元格的报表、缺标题样式的 docx）逐条验证，
并把历史踩过的坑固化成断言，例如：排序后公式引用不得错位、筛选必须保留表头、
体检不得把 ROUND(x,1) 误报成硬编码、打码后文字层不能残留敏感信息、水印中文不能变方块、
含合并单元格的表排序不能崩、失败必须非零退出。
设 ODS_REAL_SAMPLES=<真实文件目录> 还可让它顺带跑一遍真实文件（xlsx/docx/pdf）。

退出码契约（写脚本 / 用 Agent 串流程时按这个判断成败）：

网络失败怎么办：云端体检的 probe/pay/complete 不自动重试——因为重试可能重复下单。
失败时脚本会原样打印官方 CLI 的报错；确认原因后用同一个 --session-id 重跑（同一订单幂等，不会重复扣费），
订单状态不明时先 complete 查单，不要重新下单。

常见报错对照：

❓ 常见问题（FAQ）

Q1. 会破坏原文件吗？
不会。所有命令都输出到新文件；原文件只读。涉及重写（排序/筛选/打码）时也保留原文件不动。

Q2. 打码安全吗？对方能还原吗？
PDF 文字层里的原文会被真正删除（不是盖一层黑框），还原不出来；同时会生成打码清单 CSV 说明删了什么。
但图片 / 扫描件里的文字打码无效——那需要先 OCR 定位，本套件做不到。

Q3. 排序会丢格式吗？
会丢一部分。openpyxl 重写文件时不保留图片、条件格式、数据透视表等高级对象（竞品同样如此）。
重要文件请先备份，或只对数据区做排序。

Q4. 公式列为什么排不了序 / 筛不出结果？
Excel 公式在文件里只有"上次计算结果"被缓存，openpyxl 读到的是公式文本。
脚本会自动改用缓存值，并在从没被 Excel 算过时明确告诉你（此时请先用 Excel/WPS 打开保存一次）。

Q5. 我的表有合并单元格 / 标题行占第 1 行，能用吗？
能。1.7.2 起：排序会跳过合并行并告知行号（不会崩），表头会自动跳过合并标题行和空行找到真实表头。

Q6. 表头是数字（比如 1.0）怎么办？
直接 -col 1.0 即可，列名已做两侧归一化（1.0 与单元格里的 1 视为同一列）。

Q7. 扫描件 PDF 能处理吗？
不能取到文字：extract/scan/redact 都会明确提示"无文字层，需先 OCR"，不会假装成功。

Q8. .doc / .xls 打不开？
先跑 convert_legacy.py：.xls 需要 pip 装 xlrd；.doc 需要本机装 LibreOffice（没装会明确提示你另存为 .docx）。

Q9. 能批量吗？
能：Word 批量替换（replace-batch）、Excel 多文件合并（merge）、PDF 多文件合并、PDF 整目录批量水印（batch）。

Q10. 断网能用吗？
能。本地功能完全离线；只有云端文档体检（0.99 元/次）需要访问商家服务端。

Q11. 为什么命令返回了 0 却有错误提示？
不会有这种事了。1.7.2 起统一退出码契约（见上面表格）：失败一律非零退出，Agent/CI 不会再误判成功。

Q12. 能处理多大的文件？
没有硬限制，但受内存约束：openpyxl 全量加载，几十万行的表会很慢。超大表建议先用 Excel 拆列/筛选，或只处理需要的列。

Q13. 生成的目录是空的？
TOC 域要在 Word/WPS 里"更新域"（F9）才显示页码；另外正文段落必须套用「标题 1/2/3」样式，否则没有可收录的标题（脚本会提示）。

Q14. 支持 WPS 吗？
支持。产物是标准 .docx / .xlsx / .pdf，WPS 与 Office 都能打开；目录/页码域在 WPS 里同样可更新。

Q15. 用本地功能会收费吗？
不会，也不会弹出任何付款提示。排序、筛选、打码、水印、目录、模板、自检这些都在你自己电脑上跑，不经过付款链路。
只有「云端文档体检」那一步是 0.99 元/次。
什么时候才需要付费：要一份能拿出去/可归档的正式结论，或本机装不了 Python 与依赖时，可选云端文档体检（0.99 元/次）；只是自己看一眼、改文件 → 本地免费做完即可（见上面「什么时候走云端」表）。

Q16. 付款会自己弹出来吗？
会——由支付宝官方买家组件弹（那个「Agent 支付体验助手」窗口：金额 / 订单号 / 点此授权 / 二维码）。
官方对 Pay Skill 的设计就是"在 AI 智能体内直接完成支付、无需跳出界面"；我们的脚本只负责调起官方组件（pay 跑 alipay-bot），不自己造收银台。
同时脚本会把同一份收银信息（金额、订单号、可点链接、二维码图片）贴到对话里，兜底那些弹不出官方窗口的宿主。
两种入口任选一种付款即可；没授权就不会扣钱。

Q17. 扫描件（图片 PDF）能读吗？
能，走 ocr_helper.py：把每页渲染成 PNG，交给能看图的 AI 读出文字（不用装 tesseract，这也是竞品的做法）。
本机如果装了 tesseract，ocr_helper.py read 会直接出文本。
命令：python scripts/ocr_helper.py render 扫描件.pdf -o 页面图/ → 把图交给模型读 → 文字贴回来继续处理。

Q19. 云端体检的「凭证」是什么？能干嘛？
付款并执行 complete 后，会自动在 体检凭证/ 目录生成三个文件：云端体检凭证-<订单号>.json、.md、.pdf。
凭证里含订单号、时间、金额、结论与问题清单，以及服务端返回原文的 SHA-256 指纹——订单号可在支付宝账单核对金额与时间，
指纹可校验原文有没有被改动（原文同时存在 JSON 的 serverResponseRaw 字段里）。适合归档、交接、对外说明。
想先看样式：node scripts/office-doc-suite-paid.mjs cert --demo（不付款也能生成一份示例凭证）。
Q18. 一批文件要挨个体检，有没有省事的办法？
有：python scripts/checkup_report.py 资料/ -o 体检报告.md --pdf——
一次扫完整个目录（Excel 查公式错误/编号精度、Word 查标题层级、PDF 查敏感信息），
出一份能直接发给同事或客户的报告（Markdown + PDF），还可以 --json 给程序用。

✅ 质量保证（已实测）

Windows + Python 3.13 + 真实 Office 文件，实测记录：

• 回归用例：test-prompts.json（含旧格式转换、扫描件边界、合并单元格、数字表头、缺标题样式等真实形态）。
• 1.7.2 修复的 8 类缺陷（均由真实文件或对抗测试复现）：合并单元格排序崩溃、缺 Heading 样式崩溃、
  数字表头匹配失败、失败却返回 0、非 PDF 抛英文堆栈、表头行探测、支付脚本吞掉收银台输出、默认编码乱码。
• 工作流：执行前 STOP（依赖 / 路径 / 不覆盖）+ 交付前 CHECKPOINT（存在 / 抽查 / 原文件未动）。

🧩 电脑装不了 Python 库？用「零依赖模式」

公司电脑不让装包、机器离线、Python 太老——以前这些情况就用不了。现在有条兜底路子：
no_dep.py 只用 Python 自带的东西，一个库都不用装也能干活。

python scripts/no_dep.py check                          # 先看看哪些能用、哪些不能用

python scripts/no_dep.py docx-text 报告.docx             # 把 Word 里的文字提取出来
python scripts/no_dep.py docx-replace 模板.docx -find "【姓名】" -replace "张三" -o 新.docx
python scripts/no_dep.py xlsx-sheets 台账.xlsx           # 这个 Excel 里有哪几张表
python scripts/no_dep.py xlsx-csv 台账.xlsx -o 台账.csv   # 导成 CSV（Excel 打开不乱码）
python scripts/no_dep.py xlsx-merge 华东.xlsx 华南.xlsx -o 汇总.csv
python scripts/no_dep.py pdf-info 合同.pdf               # 一共几页、有没有加密
python scripts/no_dep.py pdf-text 合同.pdf               # 尽量把文字抠出来

一句话记住：能读、能导出、能替换文字；但改不了格式，也写不回 Excel。

> 中文不会乱码：导出的 CSV 带 BOM，Excel/WPS 直接打开就是正常中文。

🆘 报错了看这里（错误码对照表）

出问题时，提示里会带一个编号，长这样：

❌ 错误 [ODS-E03] 找不到列 '销售'
   处理: 可用列: ['姓名', '金额', '日期']

想知道这个编号什么意思，直接问它：python scripts/error_codes.py ODS-E03（--codes 列出全部编号）。
编号只增不改，所以以前见过的报错永远查得到。

核心原则

1. 本地运行：数据不上传（隐私是底线）
2. 保真处理：不破坏原文件，必要时先备份
3. 可重复：每次操作都有明确输出，你知道改了什么
4. 中文优先：中文提示、中文报错修复建议、老文件自动转换

合规声明

• 仅处理用户提供的文档，不采集 / 上传任何数据（云端复核除外，且仅发送你主动提交的片段）
• 打码能力用于去除文档中的身份证 / 手机号 / 银行卡 / 邮箱等个人信息
• 涉及版权内容（他人 PDF / 文档）仅限个人合法使用