WPS Office 全家桶 v5.3.5 ✅

🏗️ 四引擎智能识别：自动检测用户电脑已安装的软件，按 WPS → MS Office → LibreOffice → 纯Python 顺序选择最合适的引擎 ✨ 纯Python模式增强 v4.8：排序、筛选、图表、公式、统计、条件格式、数据验证、合并单元格、命名区域 — 跨平台全部支持 🔄 自动重试：WPS 卡住时自动重试 3 次，不用手动重启 ⚡ 硬件自适应：自动检测 CPU 内存，动态调整超时和线程，不拖累电脑 📚 文档模板 + 最佳实践 + 故障排除：代码生成3个即用模板 + 10个最佳实践案例 + 统一故障排除大章 📬 Skill 更新提醒：自动检查新版本，7天提醒一次，保持最新 🆕 文件大小明确限制：单文件 < 50MB 直接处理，> 50MB 有分片建议 🔬 Excel 智能分析 v4.6：6命令合并为 1 个统一入口（--action 参数路由） 📊 数据图表生成器 v4.6：基于数据特征自动推荐图表类型 + 生成图表嵌入 Excel 🌐 文档翻译 v4.6：Word/Excel/PPT 专业翻译（支持多模型降级） 🎙️ 会议纪要 v4.5：音频 → ASR 转写 → LLM 摘要 → Word（支持降级链） 🏥 COM 健康检查 v4.5：WPS/MS Office 状态检测 + 残留进程清理 🧮 公式解释器 v4.7：Excel 公式 → 自然语言解释（反向 NL2Formula，纯本地实现） 📝 Markdown 转换 v4.7：MD → Word/PPT（保留标题层级，纯本地实现） 📑 长文档排版 v4.7：统一入口 long-document --action（8命令合并），性能优化（分批+单次保存+进度回调） ✉️ 邮件智能回复 v4.8：模板匹配 + LLM 个性化回复（纯本地，多模型降级） 📊 周报/月报生成 v4.8：关键点 → 结构化 Word 报告（模板 + 可选 LLM 润色） 🤖 AI 统一入口 v4.9：wps ai --action 统一 9 大 AI 功能入口（新增续写/改写/扩写） 🌉 llm_bridge 桥接层 v4.9：统一模型层，白名单探测 cn-llm-router，零配置多模型调用 📋 模板市场 v4.9：50+ 内置模板（公文/合同/简历/标书/报告/会议），支持用户沉淀和分享 💬 NL2Formula 多轮澄清 v4.9：歧义检测 → 槽位填充 → 反向验证，公式生成更精准 ⏰ 定时任务 v5.0：schtasks/crontab 注册管理，周报/月报/数据刷新一键定时 👁️ 目录监听 v5.0：轮询监听 + YAML规则 + 大文件自动分片 + LibreOffice并发控制 📊 稳定性中心 v5.0：SQLite埋点统计 + 引擎健康度 + 全局engine-info + 引擎偏好配置 🏥 COM自愈 v5.0：三步自愈（regsvr32 → 修复安装 → 手动指引），每步记录日志 💬 对话式查询 v5.0：NL2SQL式意图解析 + 查询计划生成 + 连续追问，Top20关键词模板降级 🔗 编排引擎桥接 v5.0：白名单探测 multi-agent-orchestrator，命中注册流水线模板，未装本地串行降级 ☁️ kingdoc 桥接 v5.1：白名单探测+配置预检+subprocess 上传金山文档，difflib 差异检查 🔄 跨引擎 IO v5.1：条件格式/数据验证 JSON 中间格式，WPS↔纯 Python 保真往返 📋 纪要要素化 v5.1：三段式结构（待办清单+决策记录+风险异议）+ 说话人标注 📑 公文一键排版 v5.2：GB/T 9704 规则库约束 + 结构识别套版，支持红头预留位与联合行文，处理前自动备份 🔒 批量水印与打码 v5.2：文字/图片水印（平铺/对角线，批量目录）；敏感信息双轨识别（身份证/手机号/银行卡/邮箱）+ 黑色矩形覆盖 + 打码清单 🔍 跨文档检索 v5.2：本地 TF-IDF 零依赖索引，跨文档找内容问答，命中返回文件+段落+跳转，可选 embedding 与 zwjh 记忆桥接 🔗 合同审查改互链 v5.2：裁撤重复合同审查模块，完整审查请安装 contract-review（互链引导，无代码依赖） 📧 建议反馈：有更好建议？邮箱：njskills@agent.qq.com

🚀 分钟上手

1. 检查环境

python scripts/wps_test.py

2. 查看当前引擎 + 硬件

python scripts/wps_excel.py engine-info

3. 创建文件

python scripts/wps_word.py create --title "测试文档"
python scripts/wps_excel.py create --name "预算表" --sheets "收入,支出"
python scripts/wps_ppt.py create --title "推广方案"

4. 检查更新

python scripts/wps_excel.py check-update

5. 生成模板（代码生成，无二进制文件）

python templates/generate_templates.py --dir ./output

⚡ 硬件自适应

🔧 功能矩阵

✅（回退）= 原生引擎不支持时，自动回退到纯 Python 实现

📂 文档模板（代码生成，零二进制文件）

模板通过纯 Python 代码动态生成，无需分发二进制文件。首次运行需安装 python-docx、openpyxl、python-pptx。

⚠️ 文件限制速查

🔧 故障排除大章（v4.5 合并，统一索引）

统一索引表

🚫 避坑详解（20+ 条）

🥇 高频问题（TOP 10）

❌ 坑 1：WPS 没安装就调用 WPS 功能

症状：win32com.com_error 或 "WPS 未安装"
排查：
  1. 运行 python scripts/wps_excel.py engine-info 检查当前引擎
  2. 如果显示 PURE 或 LIBREOFFICE，说明 WPS 不可用
  3. 安装 WPS Office 2019+ 后重启电脑

❌ 坑 2：纯 Python 模式下写公式，打开 Excel 显示 #NAME?

症状：公式写入后打开显示 #NAME? 错误
排查：
  1. openpyxl 写的是公式字符串，打开时需 Excel/WPS 重新计算
  2. 解决：按 Ctrl+Alt+F9 强制重新计算
  3. 或切换到 WPS 模式自动计算

❌ 坑 3：中文路径编码错误

症状：UnicodeEncodeError 或 FileNotFoundError
排查：
  1. 避免中文路径：D:\docs\report.docx ✅
  2. 路径加引号："D:\中文\报告.docx" ✅
  3. 使用 raw string：r"D:\中文\报告.docx" ✅

❌ 坑 4：大文件内存溢出

症状：MemoryError 或程序卡死
排查：
  1. 先运行 python scripts/wps_word.py info --file big.docx 查看大小
  2. < 50MB 直接处理
  3. > 50MB 拆分处理：分 Sheet/Section
  4. 硬件自适应会自动延长超时

❌ 坑 5：WPS 卡住无响应

症状：操作超时（30s/60s/120s）
排查：
  1. Skill 已自动重试 3 次（等 1s → 2s → 4s）
  2. 仍失败则：任务管理器 → 结束 WPS 进程
  3. 反复出现：pip install --upgrade pywin32

❌ 坑 6：COM 对象残留

症状：第二次调用报 "RPC 服务器不可用"
排查：
  1. Worker 已内置自动释放（每次操作后调用 release_wps）
  2. 手动清理：任务管理器 → 结束 kwps.exe
  3. 避免频繁创建/销毁 Worker，使用 stdin/stdout 协议

❌ 坑 7：PPT 添加幻灯片失败

症状：纯Python模式不支持添加幻灯片
排查：
  1. 添加幻灯片、插入内容、主题应用仅 WPS 支持
  2. 替代方案：用 pure_create_ppt 创建时指定 slides_content 一次生成多页
  3. 或安装 WPS Office

❌ 坑 8：openpyxl 读取公式为 None

症状：读取含公式的单元格返回 None
排查：
  1. openpyxl 默认读取缓存值（data_only=True）
  2. 如果从未在 Excel 中打开计算，缓存值为 None
  3. 解决：先在 WPS 中打开保存一次，或改用公式计算

❌ 坑 9：sort 命令排序错乱

症状：排序结果不对
排查：
  1. 确保第一行是表头（不参与排序）
  2. 列名参数 column 需与表头完全一致（区分大小写）
  3. 多列排序时注意优先级顺序

❌ 坑 10：filter 筛选返回空结果

症状：筛选条件正确但返回空
排查：
  1. 条件 column 值需与表头完全一致
  2. 数值比较时 value 必须是字符串（"--value": "5000"）
  3. 检查是否有隐藏空格，使用 trim

🥈 中频问题

⚠️ 坑 11：LibreOffice 转换失败

症状：Word 转 PDF 报错
排查：先检查 LibreOffice 是否加入 PATH；避免中文路径；确保文件未损坏

⚠️ 坑 12：generate_templates.py 报 ImportError

症状：缺少 python-docx / openpyxl / python-pptx
排查：pip install python-docx openpyxl python-pptx

⚠️ 坑 13：_worker 启颈慢

症状：首次调用需2-3秒
排查：正常！Worker 启动时检测硬件和引擎

⚠️ 坑 14：MS Office 模式下功能缺失

症状：纯Python能做的MS Office不行
排查：MS Office COM 接口并非全功能，部分自动回退到纯Python

⚠️ 坑 15：多 Sheet 引用公式失效

症状：=SUM(1月:12月!B2) 不计算
排查：openpyxl 写公式不支持 3D 引用，改用 stats 命令或逐 Sheet 运算

🥉 低频但重要

⚡ 坑 16：macOS 上 WPS 部分功能不可用

症状：Mac 版 WPS COM 不支持某些操作
排查：回退到纯Python模式（WPS_ENGINE=PURE）

⚡ 坑 17：xlsm 文件宏丢失

症状：保存后宏功能失效
排查：openpyxl 不支持宏，xlsm 文件请用 WPS/MS Office 模式

⚡ 坑 18：批量操作时 WPS 弹出对话框

症状：WPS 弹窗阻断自动化
排查：弹窗需手动点击；建议在无人值守时关闭 WPS 弹窗

⚡ 坑 19：文件被占用

症状：PermissionError
排查：关闭占用文件的程序（WPS/Excel/Word），等待 3-5 秒后重试

⚡ 坑 20：Windows 长路径限制

症状：Windows 默认最大路径 260 字符
排查：启用 Windows 长路径支持，或使用短路径

📋 常见问题 FAQ（Q&A）

Q1：我应该选择哪个引擎？

不用选！Skill 自动检测。运行 python scripts/wps_excel.py engine-info 查看。如果强行切换，可以设置环境变量 WPS_ENGINE=PURE 强制使用纯 Python。

Q2：WPS 版本有要求吗？

• WPS Office 2019+ 或 WPS 365
• 安装后必须重启电脑
• 32/64 位均可

Q3：纯 Python 模式和 WPS 模式有什么区别？

Q4：文件太大怎么办？

Skill 硬件自适应会自动延长超时（最高 5 倍）。 建议：< 50MB 直接处理；> 50MB 先分片处理（拆分 Sheet/Section）。 批量操作时单次建议 ≤ 50 个文件。

Q5：Linux 上能用吗？

✅ 能用！安装 LibreOffice 即可：

sudo apt install libreoffice  # Ubuntu/Debian

支持格式转换（Word/Excel/PPT → PDF）； 公式、排序、筛选、图表也能用纯 Python 模式。

Q6：WPS 卡住怎么办？

Skill 会自动重试 3 次。如果仍然失败：

1. 打开任务管理器 → 结束 WPS 进程
2. 重新运行命令
3. 如果反复出现，尝试：pip install --upgrade pywin32

Q7：纯 Python 模式如何安装依赖？

pip install python-docx openpyxl python-pptx

Q8：模板文件在哪里？如何获取？

模板通过代码生成，不包含二进制文件。安装依赖后运行：

python templates/generate_templates.py --dir ./output

即可生成 3 个模板：report_template.docx、budget_template.xlsx、business_ppt_template.pptx

Q9：如何批量转换格式？

# 单个文件
python scripts/wps_word.py export --file report.docx --format pdf

# 批量转换（使用 format_converter.py）
python scripts/format_converter.py batch --input-dir ./docs --input-format docx --output-format pdf

Q10：如何同时处理多个 Sheet？

# 查看所有 Sheet
python scripts/wps_excel.py info --file Sales.xlsx

# 为每个 Sheet 添加数据（逐 Sheet 调用）
python scripts/wps_excel.py input --file Sales.xlsx --sheet Q1 --data '[["A",100]]'
python scripts/wps_excel.py input --file Sales.xlsx --sheet Q2 --data '[["B",200]]'

# 添加新 Sheet
python scripts/wps_excel.py add-sheet --file Sales.xlsx --sheet Q4 --headers '["产品","价格"]' --data '[["X",300]]'

Q11：排序/筛选/图表操作总是失败？

纯 Python 模式下这些功能 100% 支持。

1. 确保已安装：pip install openpyxl
2. 文件不能正在被占用（关闭 WPS/Excel）
3. 第一行必须是表头（列名）
4. 列名参数需与表头完全一致

Q12：如何提交反馈？

python scripts/wps_feedback.py email  # 打开邮件客户端（自动附带系统信息）

或直接发邮件到：njskills@agent.qq.com

Q13：纯 Python 模式下公式何时计算？

openpyxl 写入公式字符串，打开文件时由 Excel/WPS 计算。 如果需要立即计算，请使用 WPS 模式或 MS Office 模式。

Q14：文件被占用怎么办？

关闭占用文件的程序（WPS/Excel/Word），等待 3-5 秒后重试。 或使用自动重试（Skill 已内置 3 次重试）。

Q15：哪些功能在纯 Python 模式下不可用？

v4.8 新增条件格式、数据验证、合并单元格、命名区域支持，纯Python模式覆盖度显著提升。

• 添加幻灯片（add-slide）
• 幻灯片插入内容（insert）
• 幻灯片主题（theme）
• VBA/宏操作

替代方案：安装 WPS Office 或 MS Office 获取完整功能。

🏆 最佳实践（10 个案例）

🚨 错误速查手册 v3.1（15个错误ID）

E001-E010：用户可自助解决

E011-E015：需要进一步排查

⚠️ 能力边界说明

🔗 CLI 命令速查（由 registry.json 自动导出）

v5.3.0 起，全部能力收敛到统一入口 python scripts/wps，原 47 个脚本仍可单独调用（100% 兼容）。运行 python scripts/wps --list 查看完整动态清单。

统一入口用法

python scripts/wps --list                                  # 一屏列出全部命令与一句话用途
python scripts/wps word create --title 测试 --filepath ./a.docx
python scripts/wps office --app word --action create --title 测试
python scripts/wps excel engine-info --json                # 机器可读输出
python scripts/wps convert --input 报告.docx --output-format pdf
python scripts/wps --json <任意命令> [参数]                 # 固定四字段 {ok,error_id,elapsed,data}

命令一览（一页表）

其余脚本可直接 python scripts/wps <脚本名> [参数] 调用；--json 适用于全部命令。

📊 版本兼容矩阵

⚠️ = 部分功能受限（纯Python模式），❌ = 对应引擎不可用

⚠️ 安全须知

✅ 五道防线保障安全：

1. 引擎自检：启动时自动检测可用引擎，崩溃自动重启
2. 路径校验：safe_path() 全面校验，拒绝非法路径和特殊字符
3. 错误中文化：所有错误 ID 提供详细中文说明和操作步骤
4. 数据零上传：所有处理在本地完成，不上传任何内容到互联网
5. 显式 Opt-in（v4.6.1 引入）：外部服务（ASR/LLM）仅在用户显式指定 method 时调用，auto 模式仅使用本地引擎

📝 注意事项：

• 批量操作时，桌面会创建 WPS_Backup 文件夹保存副本
• macOS 上 WPS 不支持所有功能
• 纯 Python 模式下格式设置有限，复杂排版建议安装 WPS
• 所有文件操作在本地进行，不会联网
• LibreOffice Headless 模式下不支持实时预览
• Skill 每 7 天自动检查更新，不会频繁打扰
• 模板为纯代码生成，不包含二进制文件，更安全可靠
• v4.7 新增公式解释器、MD 转换均为纯本地实现，不读取外部凭证或 API Key

更新日志