工具说明：Python 读写 Excel

一、项目介绍

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

仓库数据为 2026-10 核查。

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

核心能力：

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

在同类工具里的位置： pandas 是 Python 里做表格分析的通用库，读 .xlsx 时默认调用 openpyxl。要操作正在运行的 Excel 窗口，得用 xlwings 这类库或 Computer Use，本课不用。

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

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

二、官方链接

核查日期：2026-10。

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

能做：

• 读 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 前置依赖

推荐 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 里（项目文件夹下打开）粘贴：

请帮我在这台 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 完整路径告诉我，之后运行脚本都用这一个。
遇到需要管理员权限、需要改系统设置或下载安装包时，停下来问我。

它会请求的权限：

要你亲手做的部分

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 的结果为准）：

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

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

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

装好后新开一个 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：

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

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

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：

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

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

4.2 WorkBuddy 端

首选：交给智能体装

请检查你能用的 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 怎样确认装好了

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

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），或先用下面的示例练手。如果统计局数据库页面打不开或导不出，就用 AKShare 取，或先用示例数据。以下数值为练习用示例，不是官方数据。

月份,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 提示词（两端通用）

请用 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 预期看到的工具调用

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

5.4 产出文件

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、有没有凭空写进数字。

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

工作表: ['月度', '季度均值', '说明']
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)，用三种方式读回，结果如下：

由此得到三条做法：

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

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

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

macOS：

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 参考脚本

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

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、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 不在本课范围。

九、参考链接