夜雨聆风
前言
日常办公中，批量处理 Word、Excel、PPT 文档总是耗时又繁琐？比如批量生成报告、修改几十份文档的格式、提取表格数据…… 今天给大家推荐一款我初步开发的开源工具 —— OfficeCLI Python，一款专为 Office 文档设计的命令行工具，无需打开 Office 软件，用简单指令就能完成创建、读取、修改、查询等全流程操作，尤其适合开发者和需要自动化办公的场景。
目前工具的基础功能已稳定可用，但部分功能（如模板合并、视频音频添加、部分导入导出功能）仍在优化中，可能存在报错，欢迎大家体验反馈，一起完善～
一、工具核心亮点
OfficeCLI Python 主打「轻量、高效、灵活」，核心特性如下：
- 多格式全覆盖：完美支持 Word（.docx）、Excel（.xlsx）、PowerPoint（.pptx）三大常用格式；
- 完整 CRUD 操作：从创建空白文档到删除元素，从查看内容到修改属性，文档操作全流程支持；
- CSS 风格路径选择器：像定位网页元素一样定位文档内容，比如 /slide[1]/shape[2] 直接选中第 1 张幻灯片的第 2 个形状；
- 模板与批量处理：基于 Jinja2 模板引擎，支持批量生成文档；可通过批处理文件执行多条命令，效率翻倍；
- 强大公式引擎：内置 195+ 个 Excel 公式函数，涵盖数学、财务、统计、字符串等 10 大类别，满足数据计算需求；
- AI 与实时预览：支持 MCP 服务器供 AI Agent 集成，内置 Flask 实时预览服务器，修改内容即时可见；
- JSON 输出与扩展：支持 JSON 格式输出，方便与其他程序集成；提供技能 / 插件系统，可自定义扩展功能；
- 属性自动纠正：基于编辑距离的拼写纠错，不小心输错属性名也能自动修正，降低使用门槛。
二、安装指南（Python 3.9+）
工具依赖 Python 3.9 及以上版本（已测试 3.9-3.13 版本），推荐两种安装方式：
1. 从源码安装（推荐，可编辑）
# 进入项目目录cd officecli-python# 基础开发模式安装（国内用户建议用清华源加速）pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple --trusted-host pypi.tuna.tsinghua.edu.cn# 安装所有可选依赖（含实时预览、开发测试工具）pip install -e ".[all]"
2. 手动安装依赖
如果不需要源码编辑，可直接安装依赖包：
# 核心依赖（必装）pip install python-docx openpyxl python-pptx lxml Jinja2 click# 可选依赖（按需安装）pip install flask# 实时预览服务器pip install pytest pytest-cov# 开发/测试
3. 验证安装
安装完成后，执行以下命令验证是否成功：
# 查看版本（输出：officecli, version 0.1.0 即为成功）officecli --version# 查看帮助文档（了解所有可用命令）officecli --help
三、快速入门：10 分钟上手核心操作
以下是最常用的文档操作示例，复制命令到终端即可执行（注意替换文件名和参数）：
1. 创建文档
# 创建空白 Word 文档（指定标题+中文区域设置，自动适配宋体）officecli create report.docx --title "月度报告" --locale zh-CN# 创建空白 Excel 工作簿officecli create data.xlsx --title "销售数据"# 创建空白 PPT（指定布局，强制覆盖已有文件）officecli create slides.pptx --title "Q4 演示" --layout "Title Slide" --force# 创建最小化空白文档（不含默认内容）officecli create blank.pptx --minimal
2. 查看文档内容
# 纯文本查看 Word 文档officecli view report.docx text# 查看文档统计信息（段落数、字符数等）officecli view report.docx stats# 查看 PPT 大纲结构officecli view slides.pptx outline# 生成 HTML 预览文件（方便浏览器查看）officecli view slides.pptx html -o preview.html# Excel 列过滤查看（只看姓名、金额、日期列）officecli view data.xlsx text --cols "姓名,金额,日期"
3. 修改与操作元素
# 1. 设置属性：修改 Word 段落格式（加粗+14号字体）officecli set report.docx /p[1] --prop bold=true --prop font-size=14pt# 2. 添加元素：给 Word 文档添加带格式的段落officecli add report.docx / --type paragraph \--prop text="加粗标题" --prop bold=true --prop font-size=18pt# 3. 添加表格：给 Excel 添加3行4列表格，设置单元格值officecli add data.xlsx /sheet[1] --type table --prop rows=3 --prop cols=4officecli set data.xlsx /sheet[1]/cell[A1] --prop value="合计"# 4. 移动与交换：移动 PPT 幻灯片位置，交换两个段落officecli move slides.pptx /slide[3] --to / --index 1officecli swap report.docx /p[1] /p[5]# 5. 删除元素：删除 Word第3个段落，Excel第5行（向上移位）officecli remove report.docx /p[3]officecli remove data.xlsx /sheet[1]/row[5] --shift up
4. 查询与批量操作
# 用 CSS 选择器查询：查找所有加粗段落、所有图片officecli query report.docx"paragraph[bold=true]"officecli query report.docx picture# 批量执行命令：创建批处理文件 commands.txt，写入以下内容# create output.docx --title "批量报告"# add output.docx / --type paragraph --prop text="第一节"# add output.docx / --type paragraph --prop text="第二节"# 执行批处理文件officecli batch commands.txt
四、功能详情与注意事项
1. 支持的核心命令（完整列表见文末）
命令 | 功能描述 |
create | 创建空白文档（.docx/.xlsx/.pptx） |
view | 查看文档内容（文本、统计、大纲、HTML 预览等） |
get/set | 获取元素、设置元素属性（字体、颜色、值等） |
add/remove | 添加元素（段落、表格、图片等）、删除元素 |
move/swap | 移动元素位置、交换两个元素 |
query | CSS 风格查询文档元素 |
batch | 批处理命令执行 |
merge | 合并文档或应用模板（待完善，部分场景可能失效） |
watch/mcp | 启动实时预览服务器、AI 集成服务器 |
2. 已支持的添加元素类型（部分）
- Word（.docx）：支持段落、表格、图片、超链接、页眉页脚、水印、目录等 44 种元素；
- Excel（.xlsx）：支持工作表、数据行、图表、数据透视表、条件格式、冻结窗格等 34 种元素；
- PowerPoint（.pptx）：支持幻灯片、文本框、图片、动画、切换效果、演讲者备注等 23 种元素（视频 / 音频 / 3D 模型未完全测试）。
3. 注意事项（重要！）
目前工具仍在迭代优化中，以下功能可能存在报错，建议谨慎使用：
- 模板合并（merge 命令）：部分场景下无法将数据合并到模板文档，需后续修复；
- 导入功能（import 命令）：从 CSV 导入 Excel 可能报错 “PK cannot be used in worksheets”；
- 保存与打开（save/open 命令）：另存为新文件、用默认程序打开文档可能失败；
- 部分高级元素（视频、音频、3D 模型）：添加功能未完全测试，兼容性待验证。
大部分基础操作（创建、查看、修改、删除、查询、批量处理）已稳定可用，日常办公场景可放心使用。
五、常用场景与进阶用法
1. AI Agent 集成
# 启动 MCP JSON-RPC 服务器，供 AI Agent 调用officecli mcp --port 3001# AI 生成格式化报告示例officecli create ai_report.docx --title"AI 分析报告"officecli add ai_report.docx / --typeparagraph --prop text="执行摘要"officecli add ai_report.docx / --typetable --prop rows=5 --prop cols=3# 生成数据表格
2. 自动化 / CI 管道
# 验证文档结构是否合法（适合批量质检）officecli validate report.docx# 从模板批量生成带日期的报告officecli merge template.docx --data @report_data.json -o report_$(date+%Y%m%d).docx# 提取 Excel 单元格数据并输出为 JSON（供其他程序使用）officecli --json get data.xlsx /sheet[1]/cell[A1] > cell_value.json
3. 文档批处理
# 批量替换所有文档中的“公司A”为“公司B”
officecli set document.docx / --find "公司A" --replace "公司B"
# 统一格式化所有段落（微软雅黑+11号字体）
officecli set document.docx /paragraph --prop font-name=微软雅黑 --prop font-size=11pt
# 提取文档中所有图片并保存
officecli query document.docx picture | jq '.[].path'
六、命令参考与路径选择器语法
1. 核心命令速查表
命令 | 核心功能 |
create | 创建空白文档 |
view | 查看文档内容（text/annotated/outline/stats/html/pdf 等） |
get/set | 获取元素、设置属性 |
add/remove | 添加、删除元素 |
move/swap | 移动、交换元素 |
query | CSS 风格元素查询 |
batch | 批处理命令 |
dump | 导出文档结构为 JSON |
merge | 合并文档 / 模板（待完善） |
validate | 验证文档结构 |
watch | 实时预览服务器 |
mcp | AI 集成服务器 |
2. 路径选择器语法（常用示例）
路径表达式 | 含义 |
/ | 文档根元素 |
/paragraph[1] | 第一个段落 |
/table[2]/row[3]/cell[1] | 第 2 个表格的第 3 行第 1 个单元格 |
/sheet[1]/cell[A1] | 第 1 个工作表的 A1 单元格 |
/sheet[1]/range[A1:D10] | 第 1 个工作表的 A1:D10 单元格范围 |
/slide[1] > shape | 第 1 张幻灯片的直接子形状（不包含嵌套形状） |
/section[1]/header | 第一个节的页眉 |
七、依赖说明
包名 | 版本要求 | 用途 |
python-docx | ≥1.0.0 | 读写 .docx 文件 |
openpyxl | ≥3.1.0 | 读写 .xlsx 文件 |
python-pptx | ≥1.0.0 | 读写 .pptx 文件 |
lxml | ≥4.9.0 | XML 处理 |
Jinja2 | ≥3.1.0 | 模板合并 |
click | ≥8.1.0 | CLI 框架 |
flask（可选） | ≥3.0.0 | 实时预览服务器 |
最后
OfficeCLI Python 是一款开源工具，源码地址：https://github.com/jiangnanboy/officecli-python
