在终端里指挥 WPS Office 干活 — 真格式、真排版、76 条命令。
不是"所见即所猜"，是所见即所得。 不模拟文件格式，直接驱动真实的 WPS 引擎。
Disclaimer / 免责声明：wps-cli 是社区维护的非官方项目，与金山办公（Kingsoft Office）没有任何隶属、授权或赞助关系。"WPS"、"WPS Office" 是其各自所有者的商标。本项目通过调用本地已安装的 WPS Office COM 自动化接口工作，不分发、不修改、不打包 WPS 二进制。
如果你用 python-docx 生成过带中文的 Word 文档，大概经历过这样的时刻：
- 明明代码里设了"宋体"，打开文件一看变成了 Calibri
- 用英文字段名操作中文段落，排版永远对不齐，调个缩进像在开盲盒
- 表格合并单元格后边框消失、页眉页脚完全不听使唤
- openpyxl 写个公式，打开 Excel 公式罢工；条件格式更是千呼万唤出不来
这些库本质上是在解析和拼接 XML 文件格式，它们不知道"这个字体在 WPS 里实际渲染出来是什么样"，自然就无法保证最终效果。
wps-cli 走了另一条路：不模拟文件格式，而是通过 COM 自动化直接驱动你电脑上正在运行的 WPS Office 本体。
你设置"黑体三号加粗"，它就真的在 WPS 里执行一遍设置黑体三号加粗的操作。字体、间距、页码、目录、页眉页脚，每一个像素都和手动操作完全一致——因为本来就是同一个程序在干活。你调试时甚至可以盯着屏幕，看文档一步步"长出来"。
| 100% 格式保真 | 不是解析文件，是直接指挥 WPS 引擎干活 | 所见即所得，不是所见即所猜 |
| AI Agent 原生支持 | 所有命令支持 --json 输出，统一 schema |
天生适配 LLM Agent 和自动化流水线 |
| 一把梭四件套 | Writer / Calc / Impress / PDF，76 条命令 | 办公自动化一个工具全搞定 |
系统要求：Windows 10/11 · WPS Office 2019+ · Python 3.10+
pip install wps-cli# 验证安装
wps doctor国内网络环境推荐使用清华源加速：
pip install wps-cli -i https://pypi.tuna.tsinghua.edu.cn/simple
用三行命令，让 budget.xlsx 自动生成图表 + 提取数据 + 导出 PDF：
# Step 1: 一行命令，自动打开 Excel 插入柱状图
wps calc chart-create budget.xlsx --data "A1:C10" --type bar --title "2026年销售趋势"
# Step 2: 提取汇总数据，结构化 JSON 喂给下游脚本或 LLM
wps calc cell-get budget.xlsx C12 --json
# → {"success": true, "command": "calc.cell_get", "data": {"ref": "C12", "value": 285600}}
# Step 3: 一键导出 PDF，格式与 WPS 手动导出完全一致
wps export convert budget.xlsx pdf三行命令，Excel 进去，图表 + 结构化数据 + PDF 出来 — 没有 GUI 点击，没有格式丢失。
wps
├── writer Word 文档
│ ├── new / info
│ ├── replace / count
│ ├── table-insert / table-get
│ ├── image-insert
│ ├── page-setup
│ ├── style-apply
│ ├── merge ★ 模板合并：{{key}} 占位符替换
│ ├── view ★ 语义视图：summary / issues / outline / annotated / stats
│ ├── validate ★ 文档验证：拼写/链接/字段完整性
│ ├── refresh ★ 刷新字段：TOC / PAGE / 交叉引用
│ ├── formfield-* ★ 表单域：list / get / set
│ ├── contentcontrol-* ★ 内容控件：list / set
│ ├── get ★ 路径定位：/section[1]/paragraph[3]
│ └── export-pdf
├── calc Excel 表格
│ ├── new / info
│ ├── sheet-list
│ ├── cell-get / cell-set / cell-range / cell-formula
│ ├── chart-create
│ ├── sort
│ ├── view ★ 语义视图：summary / issues / sheets
│ ├── validate ★ 文档验证
│ ├── refresh ★ 刷新公式 / 透视表
│ ├── conditional-format-* ★ 条件格式
│ ├── data-validation-* ★ 数据验证
│ ├── sparkline-add ★ 迷你图
│ ├── get ★ 路径定位：/sheet["Sheet1"]/cell["A1"]
│ └── export-csv
├── impress PPT 演示
│ ├── new / info
│ ├── slide-list / slide-add / slide-delete
│ ├── text-set / text-get / image-insert
│ ├── view ★ 语义视图：summary / issues / slides
│ ├── validate ★ 文档验证
│ ├── refresh ★ 刷新链接
│ ├── get ★ 路径定位：/slide[1]/shape[2]
│ └── export-pdf
├── pdf PDF 处理
│ ├── info
│ ├── merge / extract-pages / split
│ └── watermark
├── export 格式转换
│ ├── convert
│ └── batch
├── resident ★ 驻留模式：保持 COM 进程存活，加速连续操作
│ ├── start / stop / status / sessions
│ └── open / close
├── mcp ★ MCP 服务器：供 AI Agent 通过 JSON-RPC 调用
│ ├── serve / install / status
├── batch ★ 批量命令：JSON 数组批量执行
├── dump ★ 文档序列化：生成可重放 batch JSON
├── install ★ AI 工具集成：自动安装 SKILL.md 和 MCP 配置
│ ├── skill / mcp / all-tools
├── version 版本信息
└── doctor 环境诊断
| 全局选项 | 说明 |
|---|---|
--json / -j |
结构化 JSON 输出（适合 AI Agent / 管道） |
JSON 输出统一为：
{
"success": true,
"command": "calc.cell_get",
"data": { "...": "..." }
}错误时：
{
"success": false,
"command": "calc.cell_set",
"error": {
"type": "ValidationError",
"message": "...",
"code": 50,
"suggestion": "...",
"context": { "...": "..." }
}
}| 退出码 | 含义 |
|---|---|
| 0 | 成功 |
| 1 | 通用错误 |
| 10 | WPS 未安装或未检测到 |
| 11 | 会话管理错误 |
| 20 | 文件操作失败 |
| 21 | 文件不存在 |
| 30 | COM 调用失败 |
| 40 | 不支持的格式 |
| 50 | 参数校验失败 |
| 60 | 操作超时 |
| 61 | 批量操作部分失败 |
wps-cli 是一个标准的 Claude Code Skill — 安装后 Claude Code 可在你需要操作办公文档时自动加载全部 76 条命令的知识。
pip install wps-cli # Step 1: 安装 CLI
wps install all-tools -t claude # Step 2: 安装 Skill + MCP 到 Claude Code
# Step 3: 重启 Claude Code，然后直接说"帮我生成一份销售报告 xlsx"安装后 Claude Code 自动获得以下能力：
| 你说 | Claude Code 自动执行 |
|---|---|
| "把这份合同模板填上客户信息" | wps writer merge 模板合并 |
| "分析这个 Excel 销售数据做个柱状图" | wps calc chart-create 图表创建 |
| "把这三个 PDF 合并成一个" | wps pdf merge PDF 合并 |
| "把所有 docx 转成 PDF" | wps export batch 批量转换 |
| "检查这个文档有没问题" | wps writer validate 文档诊断 |
skills/wps-cli/
├── SKILL.md # 入口：决策树 + 核心概念 + 使用须知
└── references/
├── commands.md # 76 条命令完整速查表
├── patterns.md # 8 大常见使用模式（模板填充/报表/批量转换…）
├── mcp.md # MCP 服务器配置与 27 个工具列表
└── json-schema.md # JSON 输出格式、错误 Schema、退出码语义
wps install 可一键安装到 Claude Code / Cursor / VS Code / Windsurf / Codex / Hermes / MiniMax / OpenCode / NanoBot / ZeroClaw / OpenClaw。
/plugin marketplace add jjchen17/wps-cli
/plugin install wps-cli内置 MCP (Model Context Protocol) 服务器，将全部文档操作能力通过 JSON-RPC 2.0 over stdio 暴露给 AI Agent：
wps mcp serve # 启动 MCP stdio 服务器
wps mcp install --target claude # 一键注册到 Claude Code
wps mcp status # 检查注册状态支持 Claude Code、Cursor、VS Code Copilot 等所有兼容 MCP 协议的 AI 工具。
设计借鉴：此功能设计参考了 iOfficeAI/OfficeCLI (Apache 2.0) 的 MCP 集成方案。
使用 {{key}} 占位符实现"AI 设计一次模板，代码填充 N 次"：
wps writer merge template.docx -o output.docx --data '{"name":"张三","date":"2026-06-07"}'覆盖段落、表格单元格、页眉页脚中的占位符，保持原有格式不变。
设计借鉴：此功能设计参考了 iOfficeAI/OfficeCLI (Apache 2.0) 的 Template Merge Engine。
保持 COM 进程存活，连续操作性能提升 5-10x（避免每次启动 WPS + 重复 Open/Close 文档）：
wps resident start --port 9123 # 启动后台 HTTP 服务
wps resident open report.docx --type writer # 打开文档
wps resident sessions # 查看活跃会话
wps resident stop # 停止服务零外部依赖，使用 stdlib http.server 实现。
设计借鉴：此功能设计参考了 iOfficeAI/OfficeCLI (Apache 2.0) 的 Resident 模式。
统一 1-based 路径语法精确访问文档元素，无需了解 COM API 细节：
wps writer get doc.docx "/section[1]/paragraph[3]" # Word：第1节第3段
wps calc get data.xlsx '/sheet["Sheet1"]/cell["C12"]' # Excel：Sheet1 的 C12
wps calc get data.xlsx '$Sheet1:A1' # Excel 风格简写
wps impress get pres.pptx "/slide[1]/shape[2]" # PPT：第1张第2个形状设计借鉴：此功能设计参考了 iOfficeAI/OfficeCLI (Apache 2.0) 的路径定位语法。
一键获取文档结构摘要或检测潜在问题：
wps writer view report.docx summary # 标题/表格/图片结构概览
wps writer view report.docx issues # 检测：图片无alt、公式错误等
wps writer view report.docx outline # 纯大纲视图AI Agent 可通过诊断实现"编辑 → 诊断 → 修复 → 再诊断"的自愈工作流。
设计借鉴：此功能设计参考了 iOfficeAI/OfficeCLI (Apache 2.0) 的 L1 Read 层和
view issues命令。
wps-cli 默认开启以下加固，避免常见的 Office 自动化滥用路径：
- 强制禁用宏自动执行：所有
Documents.Open/Workbooks.Open/Presentations.Open调用均设置AutomationSecurity = msoAutomationSecurityForceDisable，阻止Auto_Open/Document_Open类宏在打开文档时被触发。 - 公式注入防护：
calc cell-formula拒绝包含SHELL/DDE/DDEAUTO/EXEC/CALL/REGISTER/HYPERLINK等危险函数的公式；calc cell-set拒绝以=开头的值，避免二次公式注入。 - 路径边界限制：所有命令的文件参数都会经过路径校验，禁止 UNC 路径与符号链接；
export batch的 glob 模式禁止使用绝对路径，匹配结果必须落在当前工作目录之下。 - 页码内存炸弹防护：
pdf extract-pages的页码范围有上限，避免1-999999这类输入耗尽内存。 - 错误信息脱敏：JSON 错误响应中的本地路径会被替换为
<path>，用户主目录会被替换为~，避免日志/Agent 上下文泄露文件系统结构。
详见 SECURITY.md。
CLI 层 (Typer)
│
▼
业务层 (Service)
│
▼
COM 后端层 (Backend)
│
▼
WPS Office 桌面端
三层解耦：CLI 层只做参数解析和输出格式化，业务层通过抽象接口调用后端，后端层封装 COM 细节，可替换为 LibreOffice / WebOffice。
git clone https://github.com/jjchen17/wps-cli.git
cd wps-cli
pip install -e ".[dev]" -i https://pypi.tuna.tsinghua.edu.cn/simple
pytestsrc/wps_cli/
├── cli/ # CLI 命令层 (Typer) — 含 MCP/Install/Resident 子命令
├── mcp/ # MCP 服务器 (JSON-RPC 2.0 over stdio)
├── services/ # 业务层 (Writer/Calc/Impress/PDF/Export + 模板引擎/路径解析/诊断)
├── backends/ # COM 后端层 (抽象基类 + WPS 实现)
└── utils/ # 工具函数
详见 CONTRIBUTING.md。
欢迎提交 Issue 或发送邮件至 948881912@qq.com。