第 7 课：xlsx 技能系统

这一课的重点

xlsx 技能是整个项目的"灵魂"。没有它，AI 就不知道怎么正确生成 Excel 文件。这一课详细讲解这个技能的设计思路。

技能文件在哪？

code

agent/.claude/skills/xlsx/
├── SKILL.md      ← 技能主文件（289 行）
├── recalc.py     ← 公式重算脚本（178 行）
└── LICENSE.txt   ← 许可证

SKILL.md 讲了什么？

SKILL.md 可以分为五大块：

第一块：用途和能力

告诉 AI "你能做什么"：

code

用这个技能来：
  ✅ 创建带公式和格式的新 Excel 文件
  ✅ 读取和分析已有数据
  ✅ 修改已有文件（保留公式）
  ✅ 数据分析和可视化
  ✅ 公式重算和验证

第二块：核心规则——公式优先

这是最重要的一条规则：用 Excel 公式，不要用硬编码值。

python
# ❌ 错误做法：用 Python 算出结果再填进去
total = sum([100, 200, 300])  # Python 算出 600
sheet['B10'] = 600             # 硬编码 600

# ✅ 正确做法：用 Excel 公式
sheet['B10'] = '=SUM(B2:B9)'  # 让 Excel 自己算

为什么这么重要？

因为用户拿到 Excel 文件后，会修改里面的数据。如果你硬编码了 600，用户改了数据，总数还是 600——这就错了。但如果你写的是 =SUM(B2:B9)，用户改了数据，总数会自动更新。

code

用户修改了一个数字：

硬编码方式：               公式方式：
B2: 100 → 150            B2: 100 → 150
B3: 200                   B3: 200
B4: 300                   B4: 300
B10: 600 ← 还是600！错！  B10: =SUM(B2:B9) → 650 ✅

第三块：零公式错误

SKILL.md 严格要求：生成的 Excel 不能有任何公式错误。

常见的公式错误类型：

错误	意思	常见原因
`#REF!`	引用错误	删除了被引用的单元格
`#DIV/0!`	除以零	分母是空的或者零
`#VALUE!`	值错误	公式参数类型不对
`#N/A`	找不到值	VLOOKUP 找不到匹配项
`#NAME?`	名称错误	公式名拼错了

SKILL.md 告诉 AI：生成 Excel 后，一定要用 recalc.py 来验证。

第四块：财务模型颜色规范

如果生成的是财务类 Excel（预算表、财务模型等），SKILL.md 定义了专业的颜色规范：

code

颜色约定（华尔街标准）：

  🔵 蓝色文字 = 硬编码输入（用户可以改的数字）
  ⚫ 黑色文字 = 公式和计算结果（不要手动改）
  🟢 绿色文字 = 工作表内部链接
  🔴 红色文字 = 外部链接
  🟡 黄色背景 = 需要特别注意的假设条件

这是投行和咨询公司的标准做法。AI 学会了这个规范，生成的财务模型就很专业。

第五块：库的选择指南

SKILL.md 告诉 AI 什么时候用什么库：

code

选择 pandas 当你需要：
  ✅ 大规模数据处理
  ✅ 统计分析
  ✅ 简单的 CSV/Excel 读写
  ✅ 数据清洗和转换

选择 openpyxl 当你需要：
  ✅ 精确的格式控制（字体、颜色、边框）
  ✅ Excel 公式
  ✅ 多工作表
  ✅ 冻结表头、合并单元格
  ✅ 图表
  ✅ 保留已有文件的格式

实际中，AI 经常两个一起用：用 pandas 处理数据，用 openpyxl 精细排版。

recalc.py：公式验证脚本

这个脚本利用 LibreOffice 来重算 Excel 里的所有公式，然后检查有没有错误。

用法

python
python recalc.py output.xlsx [timeout_seconds]

工作原理

code

输入：AI 生成的 Excel 文件
  ↓
recalc.py 用 LibreOffice 打开文件
  ↓
LibreOffice 重算所有公式
  ↓
recalc.py 检查每个单元格有没有错误值
  ↓
输出 JSON 报告：

{
  "status": "success",         // 或 "errors_found"
  "total_errors": 0,
  "total_formulas": 42,
  "error_summary": {}
}

如果有错误：

code
{
  "status": "errors_found",
  "total_errors": 2,
  "total_formulas": 42,
  "error_summary": {
    "#REF!": {
      "count": 1,
      "locations": ["Sheet1!B5"]
    },
    "#DIV/0!": {
      "count": 1,
      "locations": ["Sheet1!C10"]
    }
  }
}

AI 看到这个报告后，就知道 B5 和 C10 的公式有问题，然后去修复。

AI 的自我纠错流程

python

第 1 次尝试：
  AI 写 Python → 生成 Excel → recalc.py 检查
  ↓
  发现 2 个公式错误
  ↓
第 2 次尝试：
  AI 修改代码 → 重新生成 Excel → recalc.py 检查
  ↓
  0 个错误！通过！

这就是为什么 maxTurns 设为 100 的原因——AI 需要足够的"调试空间"。

技能加载流程

和之前的教程类似：

python

query() 配置 settingSources: ['project']
  ↓
SDK 扫描 agent/.claude/ 目录
  ↓
发现 skills/xlsx/SKILL.md
  ↓
AI 在工作时调用 Skill 工具
  ↓
读取 SKILL.md，学会 Excel 生成的规范
  ↓
AI 按规范写 Python 代码

本课小结

xlsx 技能是 AI 的"Excel 操作手册"，289 行
核心规则：公式优先、零公式错误、专业颜色规范
recalc.py 用 LibreOffice 验证公式，确保没有 #REF! 等错误
AI 有自我纠错能力：生成 → 验证 → 发现错误 → 修复 → 再验证
pandas 做数据分析，openpyxl 做精细排版

课后练习

完整读一遍 agent/.claude/skills/xlsx/SKILL.md
手动运行一次 python recalc.py 某个excel文件.xlsx，看看输出
想一想：如果你要添加一个"图表生成"的规范，应该在 SKILL.md 里加什么内容？