← 回到学习笔记

2026 · 06 · 30 · 4649 字

AI编程实战之Python-office自动化办公

认识python-office开源项目的目录结构、功能分类和使用方法，并学习如何借助AI复用现有工具完成办公自动化任务。

学习目标

这篇笔记主要解决五个问题：

python-office 是什么，它适合处理哪些办公任务。
如何安装项目并确认环境是否可用。
怎样阅读项目目录、示例和 Skill 文档。
如何借助 AI 选择和调用已有功能。
使用批处理功能时，怎样保护原始文件并检查结果。

学习开源项目的重点，不是把全部源码逐行背下来，而是先理解项目能解决什么问题，再学会查找接口、阅读参数、运行示例和验证结果。

本文根据 2026 年 6 月的项目文档整理。开源项目仍在持续更新，函数名称、参数和目录结构可能发生变化，实际使用时应以当前版本的官方文档和源码为准。

一、什么是python-office

python-office 是一个面向办公自动化场景的 Python 开源项目。它将 Excel、Word、PDF、PPT、图片、文件、OCR 和视频等常见处理能力整理为可以直接调用的模块。

安装完成后，可以使用传统方式统一导入：

import office

新版本还把功能拆分为独立的 Skill，可以只导入当前任务需要的方法：

from office.skills.file import replace4filename

这种设计适合初学者从一个具体功能开始学习，也便于 AI 根据功能文档理解参数和生成调用代码。

开源并不等于所有使用场景都没有成本。项目代码可以按照仓库许可证使用，但 OCR、翻译、语音识别等功能如果依赖第三方接口，仍可能需要账号、网络服务或付费额度。正式使用前应查看具体模块的说明。

二、为什么要学习复用开源项目

面对办公需求时，可以选择自己从头编写程序，也可以复用已经存在的开源功能。

对于常见任务，复用项目通常有以下好处：

减少重复开发。
更快得到可以运行的初始版本。
可以参考已有测试和示例理解用法。
遇到问题时能够查看源码、Issue 和更新记录。
让 AI 基于明确接口生成代码，减少随意猜测。

但开源项目不是“装好就一定能用”。不同电脑上的 Python 版本、Office 软件、字体、文件格式和系统权限都可能影响结果。复用代码以后，仍然需要自己测试。

三、安装与环境准备

1. 创建独立环境

建议为练习项目创建虚拟环境，避免依赖与其他 Python 项目冲突。

在 PowerShell 中执行：

mkdir python-office-demo
cd python-office-demo
py -m venv .venv
.\.venv\Scripts\Activate.ps1

如果 PowerShell 阻止执行激活脚本，可以直接调用虚拟环境中的 Python，不必修改整个系统的执行策略：

.\.venv\Scripts\python.exe -m pip install --upgrade pip

2. 安装项目

使用 PyPI 安装：

python -m pip install -U python-office

网络较慢时，可以根据官方安装说明选择可信的 PyPI 镜像。例如：

python -m pip install -U python-office -i https://pypi.tuna.tsinghua.edu.cn/simple

安装后检查包信息：

python -m pip show python-office

再测试能否正常导入：

python -c "import office; print('python-office 导入成功')"

如果导入失败，应先确认当前终端里的 python 和安装依赖时使用的是同一个解释器：

python -c "import sys; print(sys.executable)"
python -m pip --version

四、认识项目目录

从代码仓库学习时，可以先关注下面几个目录：

python-office/
├── office/          # 传统模块与核心代码
├── skills/          # 独立功能及其说明
├── examples/        # 调用示例
├── tests/           # 测试代码
├── docs/            # 项目文档
└── README.md        # 项目概览与快速入门

项目当前的 Skill 覆盖 Excel、File、Image、Markdown、OCR、PDF、PPT、Tools、Video、WeChat 和 Word 等分类。

查找功能时，可以按下面的顺序进行：

在项目说明中确认是否已有对应模块。
打开分类目录，找到功能名称。
阅读功能目录中的 SKILL.md。
核对参数、返回值、依赖和示例。
使用测试文件运行最小示例。
成功后再放入自己的工作流程。

不要看到相似的函数名就直接处理正式文件。先读文档，再确认当前安装版本中是否确实存在该方法。

五、常见功能分类

1. 文件处理

文件模块适合处理：

批量替换文件名中的文字。
给文件名增加前缀或后缀。
把文件清单导出到 Excel。
按名称或类型查找文件。
对文件进行分组整理。

批量重命名和移动文件会直接改变目录结构，必须先使用副本测试。

2. Excel处理

Excel 模块可以用于：

合并多个 Excel 文件。
拆分工作表。
按列拆分数据。
在多个表格中查找指定内容。
将 Excel 转换为 PDF。

表格处理前要确认表头、合并单元格、公式、日期格式和空值。两个看起来相同的表格，内部结构可能并不一致。

3. PDF处理

PDF 模块包含转换、拆分、合并、加密和水印等功能。

PDF 转 Word 的效果会受到原文件类型影响。文字型 PDF 通常较容易处理；扫描型 PDF 本质上是图片，需要先经过 OCR，而且复杂表格和排版不一定能够完整还原。

4. 图片处理

图片模块可以完成压缩、添加水印、二维码识别和词云生成等任务。

压缩图片时应同时检查文件大小和清晰度。目标体积越小，通常意味着画质损失越明显，不能只看是否满足上传限制。

5. Word与PPT处理

项目提供 Word、PPT 的转换、合并和图片提取等功能。

这类功能经常受到操作系统、Office 或 WPS 版本、字体和文档结构影响。自动化可以处理规则明确的内容，但复杂排版仍需要人工检查，不能把“程序执行完成”当成“版式完全正确”。

六、实操一：批量替换文件名

假设测试目录中有以下文件：

旧项目-会议记录.docx
旧项目-费用明细.xlsx
旧项目-进度汇报.pptx

希望把文件名中的“旧项目”替换为“新项目”，可以参考项目当前 Skill 的调用方式：

from office.skills.file import replace4filename


replace4filename(
    path=r"D:\python-office-test",
    del_content="旧项目",
    replace_content="新项目",
)

运行前应做到：

把原目录复制一份，程序只处理副本。
检查目录中是否包含子目录或不应修改的文件。
确认替换后的名称不会发生重复。
先放入两三个文件试运行。
核对结果后再扩大处理范围。

批量任务最危险的地方不是程序报错，而是程序按照错误规则成功处理了全部文件。

七、实操二：搜索Excel中的内容

当多个 Excel 文件中都可能出现某个编号或关键词时，逐个打开搜索很慢。项目的 Excel Skill 中提供了 find_excel_data，可以作为跨表格检索的起点。

在使用前，应先打开当前版本对应的 SKILL.md，确认参数名称和结果格式。可以让 AI 协助阅读文档，但不要让 AI 猜接口。

向 AI 提需求时，可以这样描述：

我已经安装当前版本的 python-office。
请阅读 find_excel_data 的 SKILL.md 和示例，
帮我编写一个脚本，在 D:\报表副本 中搜索关键词“设备编号A1024”。

要求：
1. 不修改任何原始 Excel。
2. 输出命中的文件名、工作表和单元格位置。
3. 单个损坏文件不能导致整个任务中断。
4. 把错误记录到日志中。

生成代码后，使用少量脱敏表格进行测试。检查关键词完全匹配、模糊匹配、空单元格和公式单元格等情况是否符合预期。

八、实操三：压缩图片

项目文档提供了独立图片压缩 Skill。基本调用形式如下：

from office.skills.image import compress_image


compress_image(
    input_file="原图.jpg",
    output_file="压缩后.jpg",
    quality=30,
)

quality 的含义和有效范围应以当前 Skill 文档为准。不同图片格式、分辨率和画面内容的压缩结果不同，同一个参数不会让所有图片得到相同体积。

批量处理时，建议：

输出到新目录，不覆盖原图。
保留原始扩展名和文件名对应关系。
记录压缩前后的文件大小。
随机抽查文字、证件和截图的清晰度。
对透明 PNG 单独测试，避免透明背景发生变化。

九、怎样结合AI学习项目

AI 最适合帮助完成以下工作：

根据需求定位可能的模块。
解释 SKILL.md、示例和函数参数。
把单文件示例改为批量处理脚本。
根据完整报错分析依赖和路径问题。
为脚本补充日志、异常处理和结果统计。

可以采用下面的提问模板：

运行环境：
- Windows 11
- Python 3.12
- python-office 版本：请根据 pip show 的结果填写

目标：
- 说明输入目录、文件类型和期望输出

限制：
- 不覆盖原文件
- 先处理测试目录
- 失败文件写入日志
- 代码中的路径使用 pathlib

资料：
- 粘贴当前版本的 SKILL.md
- 粘贴官方示例
- 粘贴完整报错

AI 可以提高读代码和写初稿的速度，但最终接口是否存在、参数是否正确、输出是否可靠，仍要通过本地运行确认。

十、从示例到可长期使用的工具

官方示例通常用于说明函数怎样调用。要把示例变成日常工具，还需要补充：

输入检查：目录是否存在，文件格式是否正确。
输出隔离：结果保存到新目录，避免覆盖原文件。
异常处理：单个文件失败时记录原因并继续处理。
日志记录：记录开始时间、处理数量、失败清单和输出位置。
重复运行保护：避免再次处理已经生成的结果。
版本固定：记录 Python 和依赖版本，防止升级后接口变化。
结果复核：抽样打开输出文件，确认内容与格式。

可以用下面的命令保存当前环境：

python -m pip freeze > requirements.txt

以后重新安装时：

python -m pip install -r requirements.txt

这只能记录 Python 包版本，不能替代对 Office、字体和系统环境的说明。对环境要求较高的项目，还应单独写一份运行说明。

十一、使用开源项目时的注意事项

1. 查看许可证

下载、修改或分发开源代码前，要查看当前仓库根目录中的 LICENSE。README、PyPI 元数据与仓库页面偶尔可能显示不同信息，应以实际使用版本附带的许可证文件为准。

2. 保护敏感数据

合同、通讯录、财务表格和内部文件不应直接上传到不明确的数据服务。向 AI 提问或提交 Issue 时，应使用脱敏样例，并删除账号、密码、令牌和内部路径。

3. 尊重文件权限

PDF 加解密、文档处理和内容提取只能用于自己有权处理的文件，不绕过访问控制，不处理来源不明的数据。

4. 谨慎升级

不要在正式任务开始前临时升级全部依赖。先在测试环境验证新版本，再决定是否替换稳定环境。

十二、本篇小结

python-office 的学习价值，不只是提供一批办公函数，更重要的是展示了如何把常见需求整理为可以重复调用的工具。

这篇笔记可以归纳为四点：

先从真实、具体、规则明确的办公问题入手。
优先阅读项目文档和示例，再让 AI 协助理解与改造。
所有批量操作先使用副本和小样本测试，输出尽量与原文件隔离。
程序运行成功后仍要核对内容、格式和数量，不能省略人工复核。

学会查找、调用和验证开源功能以后，AI 就不只是帮我们临时写一段代码，而是能够协助把已有工具组合成更稳定的办公流程。

技术指导来自：Python4Office