---
title: "W07 工具说明：Python 读写 Excel"
---

# Python 读写 Excel

## 一、项目介绍

**它是什么。** 让智能体写一段 Python 脚本，用 pandas 读 CSV、清洗、汇总，用 openpyxl 写成带多个工作表和格式的 `.xlsx`，再读回文件核对数字。电脑上不需要装 Excel 或 WPS，生成的文件可以用 Excel、WPS 打开。它解决的问题是：手工整理多份表格费时、容易出错，而且过程留不下记录。这不是单一项目，涉及三个开源项目：

| 项 | Python | pandas | openpyxl |
| --- | --- | --- | --- |
| 是什么 | 编程语言与解释器 | 表格数据分析库 | 读写 `.xlsx` 文件的库 |
| 开发与维护 | Python 软件基金会（PSF）与核心开发者 | pandas 开发团队，NumFOCUS 赞助项目 | Eric Gazoni、Charlie Clark 等（openpyxl 文档署名） |
| 开源与许可证 | 开源，PSF 许可证 | 开源，BSD-3-Clause | 开源，MIT |
| 首次发布 | 1991 年 | PyPI 0.1，2009-12-25 | PyPI 1.1.0，2010-08-11 |
| 最新版本 | 3.14.8 与 3.13.16，均为 2026-09-30 | 3.0.6，2026-09-17 | 3.1.5，2024-06-28 |
| 仓库星数与最近提交 | python/cpython 约 7.8 万星；最近提交 2026-10-19 | pandas-dev/pandas 约 5 万星；最近提交 2026-10-18 | 不在 GitHub，托管在 Heptapod（foss.heptapod.net）；默认分支最近提交 2025-10-01 |

仓库数据为 2026-10 核查。

接入方式：**Python 库**。智能体用自己的“写文件”和“执行命令”两个内置工具完成全部工作，不需要加 MCP，也不需要专门的 Skill（可参考 Anthropic 的 xlsx Skill，见 5.8）。

**核心能力：**

- 读 CSV、Excel，按列清洗、换算单位、按月或季度汇总；
- 一个文件写多个工作表，设表头加粗、冻结首行、列宽、数字格式；
- 写入 Excel 公式文本；
- 读回文件，按单元格核对某个数。

**在同类工具里的位置：** pandas 是 Python 里做表格分析的通用库，读 `.xlsx` 时默认调用 openpyxl。要操作正在运行的 Excel 窗口，得用 xlwings 这类库或 [Computer Use](https://ai.lingnan.top/materials/2026-autumn/w07/tool-11-computer-use)，本课不用。

**国内网络：** 可用。清华、阿里云 PyPI 镜像国内访问正常，装 pandas、openpyxl 走镜像很快；python.org、npmmirror、华为云的 Python 安装包目录国内都能打开。

适合讲清楚一件事：智能体写的是代码，代码由你电脑上的 Python 运行，结果以文件形式留下来，可以复查。

## 二、官方链接

核查日期：2026-10。

| 项目 | 链接 | 版本与日期 |
| --- | --- | --- |
| Python 官网（Windows 下载页） | https://www.python.org/downloads/windows/ | 最新 3.14.8；3.13 系列最新 3.13.16；均为 2026-09-30 |
| Python 安装包国内镜像 | npmmirror：https://registry.npmmirror.com/-/binary/python/ ；华为云：https://repo.huaweicloud.com/python/ | 与 python.org 的 `ftp/python/` 目录同结构 |
| PyPI 国内镜像 | 清华：https://pypi.tuna.tsinghua.edu.cn/simple ；阿里云：https://mirrors.aliyun.com/pypi/simple/ | 装包首选 |
| Python Windows 使用文档 | https://docs.python.org/3/using/windows.html | 随版本更新 |
| pandas 官方文档 | https://pandas.pydata.org/docs/ | 3.0.6（PyPI 发布于 2026-09-17），要求 Python ≥ 3.11 |
| pandas 更新日志 | https://pandas.pydata.org/docs/whatsnew/index.html | — |
| pandas GitHub | https://github.com/pandas-dev/pandas | 查源码用，国内访问不稳定 |
| pandas PyPI | https://pypi.org/project/pandas/ | 有 Windows x64 预编译包，覆盖 Python 3.11–3.15 |
| openpyxl 官方文档 | https://openpyxl.readthedocs.io/ | 3.1.5 |
| openpyxl 源码仓库 | https://foss.heptapod.net/openpyxl/openpyxl | — |
| LibreOffice（重算公式用，可选） | https://www.libreoffice.org/download/download-libreoffice/ | 开源办公套件 |
| Anthropic xlsx Skill | https://github.com/anthropics/skills/tree/main/skills/xlsx | GitHub 国内访问慢、不稳定 |
| 价格 | 以上均为开源免费 | — |

## 三、能做什么、不能做什么

**能做：**

- 读 CSV、Excel（`.xlsx`）、按列清洗、换算单位、按月份或季度汇总。
- 一个文件写多个工作表（月度、季度均值、说明）。
- 表头加粗、冻结首行、调列宽、设数字格式（如保留一位小数）。
- 写入 Excel 公式文本（如 `=AVERAGE(B2:B10)`），用户在 Excel 里打开时会计算。
- 读回文件，按单元格或按行核对某个数，写出核对结果。

**不能做或要注意：**

- openpyxl 写进去的公式**不带计算结果**。用 pandas 或 `load_workbook(data_only=True)` 读回时，公式单元格是空值（`None`）。需要读回数字核对时，或在 pandas 里先算好再写入数值，或用 LibreOffice 重算一遍（5.6）。
- 不能操作正在运行的 Excel 窗口，也不能录宏、刷新数据透视表。
- 图表可以用 openpyxl 画，但样式有限；本课不展开。
- `.xls`（老格式）需要另装 `xlrd`，建议先在 Excel／WPS 里另存为 `.xlsx`。

**适合本课的任务：** 整理宏观月度数据（CPI、PPI、PMI、社融）、把多份 CSV 合并成一个带说明页的 Excel、给调查问卷导出数据做描述统计表。

## 四、安装与配置

### 4.0 前置依赖

| 端 | 需要什么 |
| --- | --- |
| Claude Code（Windows） | 一个 64 位 Python 3.11 及以上（推荐 3.13），再装 pandas 和 openpyxl |
| WorkBuddy | 自带 Python 环境，补装 pandas 即可 |
| 两端可选 | LibreOffice，只在需要重算公式时装 |

**推荐 Python 3.13 的理由：** pandas 3.0.6 支持 3.11–3.15；3.13 的传统安装包（`.exe`）没有被标记弃用，安装界面有“Add python.exe to PATH”勾选项，对初学者步骤最少；WorkBuddy 自带的 Python 也是 3.13 系列，两端版本一致，脚本行为差别小。也可以装 3.14，但 Python 官方文档写明传统安装包自 3.14 起弃用、3.16 起不再提供，官方推荐改用 Python install manager。

### 4.1 Claude Code 端

#### 首选：交给智能体装

在 Claude Code 里（项目文件夹下打开）粘贴：

```txt
请帮我在这台 Windows 电脑上准备 Python 读写 Excel 的环境，按下面顺序做，每一步把命令和输出给我看：
1. 先检查有没有可用的 64 位 Python 3.11 及以上：依次试 `py -0p`、`python --version`、`where python`。注意：如果 `python` 打开了微软应用商店或者 where 只找到 WindowsApps 下的 python.exe，那是 Windows 的占位快捷方式，不算装好了。
2. 如果没有，停下来告诉我，由我自己去 python.org 下载安装（下面我会说怎么装），你不要替我下载安装包或改系统 PATH。
3. 有 Python 后，用 `python -m pip install pandas openpyxl -i https://pypi.tuna.tsinghua.edu.cn/simple` 安装（用 python -m pip，不要直接用 pip；不要用 sudo、不要加 --break-system-packages）。如果清华镜像连不上，换 https://mirrors.aliyun.com/pypi/simple/ 再试。不要改用 pypi.org 官方源。
4. 装完自查：运行 `python -c "import sys, pandas, openpyxl; print(sys.version); print(sys.maxsize > 2**32); print(pandas.__version__, openpyxl.__version__)"`，第二行应为 True（64 位）。
5. 把用到的 Python 完整路径告诉我，之后运行脚本都用这一个。
遇到需要管理员权限、需要改系统设置或下载安装包时，停下来问我。
```

**它会请求的权限：**

| 请求 | 处理 |
| --- | --- |
| 运行 `py`、`python`、`where` 等查询命令 | 只读，可以允许 |
| 运行 `python -m pip install ...` | 会联网下载约 20 MB，看清包名是 pandas、openpyxl 后允许 |
| 运行 `winget install`、下载 `.exe`、改环境变量 | 拒绝，按下面“亲手做”自己装 |
| 写 `pip.ini` 或 `pip config set` | 这是改用户级 pip 配置。地址是清华或阿里云镜像（见下文“参考”）可以允许，其他地址拒绝 |

#### 要你亲手做的部分

1. **装 Python**（智能体不该替你运行安装包）：
   - 从国内镜像下载：打开 https://registry.npmmirror.com/-/binary/python/3.13.16/ （或华为云 https://repo.huaweicloud.com/python/3.13.16/ ），下载 `python-3.13.16-amd64.exe`，这就是 python.org 上的 **Windows installer (64-bit)**。不要选不带 `amd64` 的 32 位包，也不要选 `arm64`（除非你的电脑是 ARM 处理器）。如果这个版本目录打不开，回到上一级目录找 3.13 系列的最新版。
   - python.org 官方下载页 https://www.python.org/downloads/windows/ 国内也能打开，可作对照或备选。
   - 运行安装包，在第一页**勾选底部的 “Add python.exe to PATH”**，再点 “Install Now”。按官方文档，Install Now 装在用户目录，不需要管理员权限。
   - 装完关掉所有终端和 Claude Code，重新打开，PATH 才会生效。
2. **关掉应用商店的占位快捷方式**（如果 `python` 仍打开商店）：Windows 设置 → 应用 → 高级应用设置 → 应用执行别名，关掉 “python.exe” 和 “python3.exe” 两项。这是系统设置，自己点，不交给智能体。
3. **装 LibreOffice（可选）**：只在要读回公式结果时装，从官网下载安装；官网下载页会自动分配就近的下载镜像，如果下载慢，换个时间或换个网络再试。

#### 参考：手动命令（Windows 11 x64，PowerShell）

下面两种方式的下载源由 winget 和 Microsoft Store 决定。如果下载慢或失败，就改用上面的国内镜像手动下载。

方式一：winget 装传统安装包版本（ID 以 `winget search` 的结果为准）：

```powershell
winget search Python.Python
winget install -e --id Python.Python.3.13
```

方式二：官方推荐的 Python install manager（Microsoft Store ID 9NQ7512CXL7T），命令来自 Python 官方文档：

```powershell
winget install 9NQ7512CXL7T -e --accept-package-agreements --disable-interactivity
py install 3.13
```

装好后新开一个 PowerShell 窗口：

```powershell
python --version
python -m pip install pandas openpyxl -i https://pypi.tuna.tsinghua.edu.cn/simple
python -c "import pandas, openpyxl; print(pandas.__version__, openpyxl.__version__)"
```

长期使用国内镜像，写进用户级配置（会生成 `%APPDATA%\pip\pip.ini`），之后 `pip install` 不用每次加 `-i`：

```powershell
python -m pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
```

清华源连不上时改用阿里云：

```powershell
python -m pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
```

macOS：从上面的 npmmirror 或华为云镜像下载 macOS 安装包（`python-3.13.16-macos11.pkg`）；之后用 `python3 -m pip install pandas openpyxl -i https://pypi.tuna.tsinghua.edu.cn/simple`。Homebrew 默认从境外下载，不作首选。

#### Claude Code 在 Windows 上怎样运行 Python

按 Claude Code 官方文档（https://code.claude.com/docs/en/setup ）：

- 没装 Git for Windows 时，Claude Code 用 **PowerShell 工具**执行命令，`python 脚本.py` 在 PowerShell 里运行。
- 装了 Git for Windows 时，用 **Git Bash** 执行 Bash 工具，PowerShell 工具同时可用。Git Bash 里 C 盘路径以 `/c/` 开头（`C:\` 写成 `/c/`），`python` 同样要在 PATH 里。
- 两种情况下，智能体都是“用 Write 工具写 `.py` 文件 → 用 Bash／PowerShell 工具运行 → 读输出”。脚本运行在你的电脑上，不在云端。
- 中文输出乱码时，让它用 `python -X utf8 脚本.py` 运行，或在 PowerShell 里先设 `$env:PYTHONUTF8 = "1"`（Python 官方的 UTF-8 模式）。

建议在项目根目录的 `CLAUDE.md` 写一行，免得每次都要找 Python：

```txt
运行 Python 用 C:\Users\<你的用户名>\AppData\Local\Programs\Python\Python313\python.exe（以你电脑上 where python 的结果为准）。
```

Python 官方文档建议每个项目建一个虚拟环境（`python -m venv .venv`）。本课的小任务直接装进用户 Python 即可；如果项目文件夹在百度网盘、OneDrive 等同步目录里，不要把 `.venv` 放在里面，几万个小文件会拖慢同步。

### 4.2 WorkBuddy 端

#### 首选：交给智能体装

```txt
请检查你能用的 Python 环境里有没有 pandas 和 openpyxl：
1. 列出你能找到的 Python（包括 WorkBuddy 自带的 Python 和虚拟环境），给出完整路径和版本；
2. 用 `<python路径> -c "import importlib.util as u; print([(m, bool(u.find_spec(m))) for m in ['pandas','openpyxl']])"` 逐个检查；
3. 优先选 WorkBuddy 自带的虚拟环境，缺什么用 `<python路径> -m pip install <包名> -i https://pypi.tuna.tsinghua.edu.cn/simple` 补装，只装到 WorkBuddy 自己的环境，不用管理员权限，不改系统 Python；
4. 把最终选用的 Python 路径和 pandas、openpyxl 版本写进工作区的 python-env.md。
需要联网下载或需要权限时先告诉我。
```

**会看到什么：** WorkBuddy 一般能找到它自带的 Python（3.13 系列）、自带虚拟环境 `default`，以及你电脑上另装的 Python。`default` 里通常已有 openpyxl、缺 pandas；它会在 `default` 里执行 `python -m pip install pandas`，顺带装上 numpy，不需要管理员权限，然后按你的任务生成并读回 xlsx，整个过程几分钟。自带环境在 Windows 上一般位于 `%USERPROFILE%\.workbuddy\binaries\python\` 下（macOS 为 `~/.workbuddy/binaries/python/`），以 WorkBuddy 自己查到的路径为准。

**它会请求的权限：** 沙箱执行 `pip install` 时会请求访问镜像站，看清域名是 `pypi.tuna.tsinghua.edu.cn` 或 `mirrors.aliyun.com` 后允许。如果它没加 `-i`、请求的是 `pypi.org` 或 `files.pythonhosted.org`，让它改用清华镜像再装。

**WorkBuddy 内置的 xlsx 技能：** WorkBuddy 官方文档的“办公文档四件套”列出内置 `XLSX` 指令，用途是清洗表格、补公式、整理列、输出汇总。本课用自己写 Python 的方式，便于看到每一步代码。

#### 要你亲手做的部分

- 在弹出的网络或命令执行授权里点“允许”。
- 如果自带环境装不上，可以按 4.1 自己装 Python，再告诉 WorkBuddy 用那个 Python 的完整路径。

### 4.3 怎样确认装好了

在终端（或让智能体）运行：

```powershell
python -c "import sys, pandas, openpyxl; print(sys.version); print(sys.maxsize > 2**32); print(pandas.__version__, openpyxl.__version__)"
```

三行输出依次是 Python 版本（3.11 及以上）、`True`（64 位）、两个库的版本号。任何一行报 `ModuleNotFoundError`，说明包装到了别的 Python 里，见第六节。

## 五、使用教程：把月度 CPI／PPI／PMI CSV 整理成多工作表 Excel，再读回核对一个数

### 5.1 准备数据

在项目文件夹里放一个 `data/macro_monthly.csv`。可以从国家统计局数据库（https://data.stats.gov.cn/ ）导出，也可以用 AKShare 的 `macro_china_cpi` 等接口取真实数据（见 [AKShare 与 macro-data](https://ai.lingnan.top/materials/2026-autumn/w07/tool-08-akshare-macro-data)），或先用下面的示例练手。如果统计局数据库页面打不开或导不出，就用 AKShare 取，或先用示例数据。**以下数值为练习用示例，不是官方数据。**

```txt
月份,CPI同比%,PPI同比%,制造业PMI
2026-01,0.4,-2.1,49.8
2026-02,0.9,-2.0,50.1
2026-03,0.6,-1.9,50.4
2026-04,0.3,-1.8,49.9
2026-05,0.5,-1.6,49.7
2026-06,0.8,-1.5,50.2
2026-07,0.7,-1.4,49.6
2026-08,0.5,-1.3,49.8
2026-09,0.9,-1.2,50.0
```

从国家统计局导出的 CPI、PPI 常是“上年同月=100”的指数（如 100.9），同比涨幅 = 指数 − 100；PMI 本身是指数，50 为荣枯线。用 Excel 另存的 CSV 常是 GBK 编码，直接读会报 `UnicodeDecodeError`。

### 5.2 提示词（两端通用）

```txt
请用 Python（pandas + openpyxl）把 data/macro_monthly.csv 整理成 Excel，不要打开或调用 Excel 软件。
要求：
1. 把脚本写成 make_macro_xlsx.py 存在项目里，然后运行它；读 CSV 时先试 utf-8-sig，失败再试 gbk。
2. 如果 CPI、PPI 是“上年同月=100”的指数，换算成同比涨幅 %（指数−100），并在说明页写明。
3. 输出 output/macro_2026.xlsx，含三个工作表：
   - “月度”：月份、CPI同比%、PPI同比%、制造业PMI，月份写成 2026-01 这样的文本；
   - “季度均值”：按季度求三项均值，保留两位小数，季度均值在 pandas 里算好再写入数值，不写 Excel 公式；
   - “说明”：数据来源、单位、处理步骤。
4. 格式：每个工作表表头加粗、冻结首行、按内容调列宽；“月度”的数值保留一位小数。
5. 另写 check_macro_xlsx.py：读回 output/macro_2026.xlsx，列出工作表名，打印 2026-09 的 CPI同比%，并和 CSV 里同一行比较，一致输出“核对通过”，不一致输出两边的值。
6. 运行两个脚本，把关键输出贴给我，告诉我用的是哪个 Python。
不要安装 pandas、openpyxl 以外的包。
```

### 5.3 预期看到的工具调用

| 顺序 | Claude Code | WorkBuddy |
| --- | --- | --- |
| 1 | Read／Glob 读 CSV 前几行 | Read 读 CSV |
| 2 | Write 写 `make_macro_xlsx.py` | Write 写脚本 |
| 3 | PowerShell 或 Bash：`python make_macro_xlsx.py` | Bash：`<自带python> make_macro_xlsx.py` |
| 4 | Write 写 `check_macro_xlsx.py` | Write 写核对脚本 |
| 5 | 运行核对脚本，读输出 | 运行核对脚本 |
| 6 | 出错时 Edit 改脚本再运行 | 同左 |

智能体写的自检脚本也可能出错。例如它把均值四舍五入到 4 位后写入，又用 `1e-9` 的容差和未取整的均值比较，就会报“均值不一致”；把容差改为 `1e-4` 后通过。这类“脚本写错了而数据没错”的情况常见，看报错原文再判断。

### 5.4 产出文件

```txt
make_macro_xlsx.py
check_macro_xlsx.py
output/macro_2026.xlsx    工作表：月度、季度均值、说明
```

### 5.5 怎样验收

1. 核对脚本输出“核对通过”，且打印的 2026-09 CPI 与 CSV 第 10 行一致（示例数据为 0.9）。
2. 季度均值手算一个：示例数据 2026Q1 的 CPI 均值 = (0.4 + 0.9 + 0.6) / 3 = 0.63。
3. 用 Excel 或 WPS 打开文件，三个工作表都在，表头加粗、首行冻结。
4. 打开脚本看一眼：读的是不是你给的 CSV、有没有凭空写进数字。

用上面的示例数据，核对输出应类似：

```txt
工作表: ['月度', '季度均值', '说明']
2026-09 CPI: 0.9
       季度  CPI同比%  PPI同比%  制造业PMI
0  2026Q1    0.63   -2.00   50.10
1  2026Q2    0.53   -1.63   49.93
2  2026Q3    0.70   -1.30   49.80
```

### 5.6 公式的注意点

为了演示，在“月度”表末尾加一格公式 `=AVERAGE(B2:B10)`，用三种方式读回，结果如下：

| 读法 | 刚由 openpyxl 写出 | LibreOffice 重算后 |
| --- | --- | --- |
| `load_workbook(p)`（默认） | `=AVERAGE(B2:B10)`（公式文本） | 公式文本 |
| `load_workbook(p, data_only=True)` | `None` | `0.622222222222222` |
| `pd.read_excel` | 该行为 `NaN`，且在“月度”表多出一行空行和一行“CPI 均值（公式）” | 有数值 |

由此得到三条做法：

1. **要读回核对的数，在 pandas 里算好写数值**（上面提示词的写法）。
2. **要交给别人在 Excel 里改的表，才写公式**，并单独放在一个工作表或表格下方，别和原始数据混在同一张表里，否则 pandas 读回时会多出几行。
3. 写了公式又要读回结果，用 LibreOffice 无界面重算。

Windows（LibreOffice 默认安装路径；装在别处就改路径）：

```powershell
& "C:\Program Files\LibreOffice\program\soffice.exe" --headless --calc --convert-to xlsx --outdir recalc output\macro_2026.xlsx
```

macOS：

```txt
soffice --headless --calc --convert-to xlsx --outdir recalc output/macro_2026.xlsx
```

重算后的文件在 `recalc/` 里，再用 `data_only=True` 读。另外两条来自 Anthropic xlsx Skill 的提醒：用 `data_only=True` 打开后**不要保存**，否则所有公式会被替换成数值；`XLOOKUP`、`FILTER`、`UNIQUE` 等新函数 LibreOffice 算不出来，查找改用 `INDEX`/`MATCH`，排序筛选在 Python 里做。

### 5.7 参考脚本

用来对照智能体写的脚本，不必照抄。

```python
import sys, pandas as pd
from openpyxl import load_workbook
from openpyxl.styles import Font
from openpyxl.utils import get_column_letter

src, out = sys.argv[1], sys.argv[2]
try:
    df = pd.read_csv(src, encoding="utf-8-sig")
except UnicodeDecodeError:
    df = pd.read_csv(src, encoding="gbk")

df["月份"] = pd.to_datetime(df["月份"])
df["季度"] = df["月份"].dt.to_period("Q").astype(str)
q = df.groupby("季度")[["CPI同比%", "PPI同比%", "制造业PMI"]].mean().round(2).reset_index()
df["月份"] = df["月份"].dt.strftime("%Y-%m")
note = pd.DataFrame({"项目": ["数据来源", "单位", "处理"],
                     "说明": ["示例数据（非官方）", "CPI、PPI 为同比涨幅 %；PMI 为指数", "季度均值由 pandas 计算，保留两位小数"]})

with pd.ExcelWriter(out, engine="openpyxl") as w:
    df.drop(columns="季度").to_excel(w, sheet_name="月度", index=False)
    q.to_excel(w, sheet_name="季度均值", index=False)
    note.to_excel(w, sheet_name="说明", index=False)

wb = load_workbook(out)
for ws in wb.worksheets:
    for c in ws[1]:
        c.font = Font(bold=True)
    ws.freeze_panes = "A2"
    for i, col in enumerate(ws.columns, 1):
        ws.column_dimensions[get_column_letter(i)].width = max(len(str(c.value or "")) for c in col) * 2 + 2
for row in wb["月度"].iter_rows(min_row=2, min_col=2, max_col=4):
    for c in row:
        c.number_format = "0.0"
wb.save(out)
```

运行：`python make_macro_xlsx.py data/macro_monthly.csv output/macro_2026.xlsx`（`output` 文件夹要先存在）。

### 5.8 可参考的 Skill

Anthropic 的 xlsx Skill（https://github.com/anthropics/skills/tree/main/skills/xlsx ）把上面这些经验写成了规则：建表用 openpyxl、分析用 pandas；含公式的文件必须用其中的 `recalc.py`（调用 LibreOffice）重算并检查错误；读模型要分两次加载（公式一次、数值一次）。它默认“写公式而不写算好的数”，面向财务模型；本课任务以核对数字为主，所以 5.2 的提示词反过来要求在 pandas 里算好。把它放进 `.claude/skills/xlsx/` 或 `.workbuddy/skills/xlsx/` 可以直接被两端识别，但其中的 `recalc.py` 在 Windows 上要改成 LibreOffice 的安装路径。

## 六、常见问题与排错

| 现象 | 原因 | 处理 |
| --- | --- | --- |
| 输入 `python` 打开了微软应用商店 | Windows 的应用执行别名占位，没装 Python 或没加 PATH | 按 4.1 装 Python 并勾选 Add to PATH；在“应用执行别名”里关掉 python.exe、python3.exe |
| `'python' 不是内部或外部命令` | 安装时没勾选 Add to PATH，或装完没重开终端 | 重开终端；仍不行就重新运行安装包选 Modify 补上，或改用 `py` 命令 |
| `ModuleNotFoundError: No module named 'pandas'` | 电脑上有多个 Python，包装进了另一个 | 统一用 `python -m pip install`，并让智能体用同一个 Python 的完整路径运行脚本 |
| `ImportError: Missing optional dependency 'openpyxl'` | pandas 不自带 openpyxl | `python -m pip install openpyxl -i https://pypi.tuna.tsinghua.edu.cn/simple` |
| pip 下载很慢或 `ReadTimeoutError` | 默认连 pypi.org 官方源，官方源在境外，下载速度没有保证 | 加 `-i https://pypi.tuna.tsinghua.edu.cn/simple`，或换阿里云镜像；长期用 `pip config set` 写进配置（4.1） |
| python.org 下载安装包很慢 | 官方站在境外 | 改从 npmmirror 或华为云镜像下载同名安装包（4.1） |
| `Could not find a version that satisfies the requirement pandas` | Python 低于 3.11，或装成了 32 位 | 卸载后装 64 位 3.13；`print(sys.maxsize > 2**32)` 应为 True |
| `UnicodeDecodeError: 'utf-8' codec can't decode` | CSV 是 GBK 编码（Excel 另存的常见情况） | `pd.read_csv(..., encoding="gbk")`，或先试 `utf-8-sig` |
| 打印的中文变成乱码或 `UnicodeEncodeError` | 终端编码不是 UTF-8（Windows 常见） | `python -X utf8 脚本.py`，或 `$env:PYTHONUTF8="1"` |
| `PermissionError: [Errno 13]` 写 xlsx 时 | 文件正在 Excel／WPS 里打开，被锁定 | 关掉文件再运行 |
| 读回公式单元格是 `None` 或 `NaN` | openpyxl 写入的公式没有计算结果 | 在 pandas 里算好写数值，或用 LibreOffice 重算（5.6） |
| pandas 读回的表多出空行或“均值”行 | 公式或备注写在了数据表下方 | 公式、备注放到单独工作表 |
| 打开后数字是文本、不能求和 | CSV 里有千分位逗号、`%` 号或空格 | 让脚本先 `str.replace` 去掉再 `pd.to_numeric` |
| 月份变成 46023 这样的数字 | 日期以 Excel 序列号存储，或类型被改 | 写入前转成 `2026-01` 文本，或设置单元格日期格式 |
| WorkBuddy 装包时一直等待 | 沙箱在等你批准网络访问 | 看弹窗域名后点允许 |

## 七、费用、额度、隐私与安全

- Python、pandas、openpyxl、LibreOffice 均开源免费。智能体端消耗的是模型额度：检查环境、补装 pandas、生成并读回这样一轮，WorkBuddy 通常几分钟完成。
- 脚本在你的电脑上运行，数据不经过 Python 上传；但智能体读 CSV 前几行、读运行输出时，这些内容会发给所用的模型服务商（DeepSeek、腾讯混元等）。含个人信息、未公开数据的表格先脱敏，或只让它读列名和行数。
- 只从 PyPI 或可信镜像装包，包名看清楚（`pandas`、`openpyxl`），拼写相近的包可能是冒名包。
- 不需要 API Key。

## 八、与同类工具的一句对比

社区的 Excel MCP（haris-musa/excel-mcp-server，约 4,200 星，2026-10 核查）把“读单元格、写公式、建图表”包装成固定工具，智能体调用时看不到中间代码；Python 路线要先装 Python，但每一步都是可保存、可重跑、可复查的脚本，更适合本课讲“工具调用留下证据”。Stata、R 不在本课范围。

## 九、参考链接

| 内容 | 链接 |
| --- | --- |
| Python 最新版本与发布日期，64 位安装包下载 | https://www.python.org/downloads/windows/ |
| Install Now 装在用户目录、Add to PATH、传统安装包自 3.14 弃用、install manager 的 winget 命令 | https://docs.python.org/3/using/windows.html |
| pandas 3.0.6 发布日期、Python ≥ 3.11、Windows x64 预编译包 | https://pypi.org/project/pandas/ |
| openpyxl 版本与用法 | https://pypi.org/project/openpyxl/ 、https://openpyxl.readthedocs.io/ |
| Claude Code 在 Windows 上使用 PowerShell 工具或 Git Bash | https://code.claude.com/docs/en/setup |
| WorkBuddy 内置 XLSX 指令 | https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/WorkBuddy-Zero-Cost-Skill-Top-10/Office-Document-Suite |
| 公式无缓存值、需重算、`data_only=True` 保存会丢公式、LibreOffice 不支持的函数 | https://github.com/anthropics/skills/tree/main/skills/xlsx |
| Excel MCP | https://github.com/haris-musa/excel-mcp-server |
| Python UTF-8 模式 | https://docs.python.org/3/library/os.html#utf8-mode |