{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}

Xlsx

创建、读取、编辑 Excel .xlsx 工作簿和 CSV。

Skill 元数据
来源内置（默认安装）
路径skills/productivity/xlsx
版本1.1.0
作者Nous Research
许可证MIT
平台linux, macos, windows
标签excel, spreadsheet, xlsx, csv, openpyxl, productivity
相关 skilldocx、pdf、powerpoint

参考：完整 SKILL.md

INFO

以下是 Hermes 在触发该 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。

Xlsx Skill

用 Python 和 openpyxl 处理 Excel .xlsx 工作簿：构建带样式、公式和图表的多表工作簿，检查或 dump 既有文件，编辑单元格和结构，以及与 CSV 互转。所有辅助脚本是打印 JSON、用显式 UTF-8 I/O 的 argparse CLI。

何时使用

  • 创建 .xlsx 报告：多表、数字格式、样式、合并单元格、冻结窗格、自动筛选、条件格式、图表、数据验证下拉、原生 Excel 表、定义名、超链接、单元格备注、工作表保护。
  • 读工作簿：表清单、以 JSON 或 CSV dump 数据、列出公式 vs 缓存值、备注、定义名、表。
  • 编辑既有文件：设单元格、追加行、插入/删除行/列（经 xlsx_restructure.py 引用感知）、复制/重命名表、表、名、备注、保护。
  • 经 LibreOffice 无头重算公式（xlsx_recalc.py）。
  • CSV 互操作，带类型推断和非 UTF-8 编码。
  • 不用于旧版 .xls 二进制格式（先用 LibreOffice 转换：soffice --headless --convert-to xlsx old.xls）。

前置条件

  • Python 3.10+，带 openpyxl（pip install openpyxl）。无需其他第三方包；其余均为标准库。
  • 可选：LibreOffice（soffice）用于无头重算或格式转换。

运行方式

用 terminal 工具从本 skill 的 scripts/ 目录运行辅助脚本（每个脚本支持 --help）：

python scripts/xlsx_create.py spec.json report.xlsx   # 从 JSON 规格构建
python scripts/xlsx_read.py report.xlsx --sheets      # 清单
python scripts/xlsx_read.py report.xlsx --json --sheet Data
python scripts/xlsx_read.py report.xlsx --formulas
python scripts/xlsx_edit.py report.xlsx --sheet Data --set B2=42 --recalc
python scripts/xlsx_restructure.py report.xlsx --sheet Data --insert-rows 3:2
python scripts/xlsx_recalc.py report.xlsx
python scripts/csv_to_xlsx.py data.csv out.xlsx --encoding utf-8
python scripts/xlsx_to_csv.py report.xlsx out.csv --sheet Data

用 write_file 写 JSON 规格，用 read_file 或直接从 stdout 检查脚本 JSON 输出。

快速参考

任务命令
从规格创建工作簿xlsx_create.py spec.json out.xlsx
表名 + 尺寸xlsx_read.py f.xlsx --sheets
以 JSON dump 表xlsx_read.py f.xlsx --json --sheet S
以 CSV dump 表xlsx_read.py f.xlsx --csv --out d.csv
列出公式 + 缓存值xlsx_read.py f.xlsx --formulas
设单元格 / 公式xlsx_edit.py f.xlsx --set "A1==SUM(B:B)"
追加一行xlsx_edit.py f.xlsx --append '[1,"x",true]'
插入 2 行，引用不移动xlsx_edit.py f.xlsx --insert-rows 3:2
插入 2 行，引用移动xlsx_restructure.py f.xlsx --insert-rows 3:2
删除一列，引用移动xlsx_restructure.py f.xlsx --delete-cols B
创建原生表xlsx_edit.py f.xlsx --add-table Sales:A1:C9
表内追加--table-append 'Sales=["West",5]'
列出表xlsx_edit.py f.xlsx --list-tables
定义名--define-name "Rates='Data'!$B$2:$B$9" / --delete-name Rates / xlsx_read.py f.xlsx --names
超链接--hyperlink "A1=https://example.com|Docs"
单元格备注--note "B2=Check this|Reviewer"；用 xlsx_read.py f.xlsx --notes 读
保护工作表（见常见陷阱）--protect your-password --unlock B2:B9
经 LibreOffice 重算xlsx_recalc.py f.xlsx
复制 / 重命名表--copy-sheet Src:New --rename-sheet Old:New
打开时强制重算xlsx_edit.py f.xlsx --recalc
CSV -> 带样式 xlsxcsv_to_xlsx.py in.csv out.xlsx
xlsx -> CSVxlsx_to_csv.py f.xlsx out.csv --encoding utf-8

流程

  1. 创建：写 JSON 规格（schema 见 xlsx_create.py --help 及其 docstring）。每个表支持 rows（标量或带样式单元格对象）、稀疏 cells 覆盖、column_widths、row_heights、merges、freeze_panes、autofilter、conditional_formats（cell_is 规则和色阶）、charts（来自单元格范围的柱/折线/饼）、validations（列表下拉）、tables（带样式名的原生 Excel 表）和 protection。工作簿级 defined_names 把名映射到引用。单元格对象还接受 hyperlink 和 note。类型化值：JSON 数字/bool 直接通过；日期用 {"value": "2026-01-31", "type": "date"}。数字格式是 Excel 格式串：货币 "$#,##0.00"、百分比 "0.0%"、日期 "yyyy-mm-dd"。
  2. 公式：在规格中设 "formula": "SUM(B2:B9)"，或编辑器中 --set "C1==SUM(A:A)"。写公式时加 "full_calc_on_load": true（规格）或 --recalc（编辑器）；这设工作簿 fullCalcOnLoad 标志，使 Excel/LibreOffice 打开时重算一切。openpyxl 本身从不求值公式。
  3. 读取：--sheets 看清单（名、尺寸、合并范围、图表数、表、保护、定义名），--json/--csv 看数据，--formulas 把每个公式串与其缓存结果配对，--notes 看单元格备注，--names 看定义名。缓存结果仅在文件上次由真实电子表格应用保存时存在；openpyxl 新鲜产出的文件在那里返回 null。要无头物化结果，运行 xlsx_recalc.py file.xlsx（用 LibreOffice；soffice 缺失时打印 {"recalculated": false, ...} 并退出 0），再用 --data-only 重载。
  4. 编辑：xlsx_edit.py 先应用重命名/复制，再做结构性行/列变更，然后 --set/--append。它原地编辑，除非给 --out——需要原件就先复制文件。
  5. 重构：对有公式、合并、表或筛选的表做插入/删除，用 xlsx_restructure.py 而非 xlsx_edit.py。它重写所有表上的公式引用（绝对 $ 引用、范围、跨表引用），移动合并、自动筛选、冻结窗格、验证和条件格式范围、表引用、定义名和行/列尺寸，然后打印 JSON 报告，含 not_shifted 列表。规则与限制：references/restructuring.md。
  6. CSV 互操作：csv_to_xlsx.py 逐单元格推断 int/float/bool/ISO 日期并给标题行加样式；xlsx_to_csv.py 写 ISO 日期，空单元格写空串。两者默认 UTF-8，接受 --encoding（如 Excel 友好 BOM 用 utf-8-sig，旧版 Windows 导出用 cp1252）。

转换为 PDF

LibreOffice 无头转换（也适用于单表 CSV 导出）：

soffice --headless --convert-to pdf report.xlsx --outdir out/
soffice --headless --convert-to csv report.xlsx --outdir out/  # 仅第 1 表

只有第一个表进 CSV；其他表用 xlsx_to_csv.py --sheet NAME。若 soffice 缺失，安装 LibreOffice 或把文件不转换地交给用户。

常见陷阱

  • openpyxl 不计算。 公式结果只能经 load_workbook(path, data_only=True) 获得，且仅当文件先前由 Excel/LibreOffice 保存。否则得到 None。
  • xlsx_edit.py 插入/删除不移动引用（原生 openpyxl 行为）。用 xlsx_restructure.py，它会移动——但即使它也不能移动图表锚点、图像或条件格式 RULE 公式；读其 JSON 报告的 not_shifted 列表和 references/restructuring.md。
  • 工作表保护不是安全。 --protect 设标准 xlsx 工作表保护哈希：它只对守规矩的应用发"别编辑"信号，仅此而已。任何人都能通过编辑 zip 的 XML 或在 LibreOffice 中取消勾选来剥离它。绝不要为保密性或完整性依赖它；它不加密任何东西。
  • data_only=True 后保存会静默丢弃所有公式（缓存值替换它们）。除非那就是目标，否则绝不这样保存工作簿。
  • 加载剥离图表/图像：openpyxl 不往返图表，因此编辑带图表的工作簿再保存会丢图表。编辑后重新加图表，或避免重存带图表文件。
  • CSV locale 陷阱：总是传显式编码（脚本已做），记住欧洲 CSV 常用 ; 分隔符和小数逗号——用 --delimiter ';'，并预期 "12,5" 这类字符串保持字符串。
  • 日期是 datetime：Excel 把日期存为序列号；openpyxl 返回 datetime/date 对象。这里 dump 发 ISO 字符串。
  • 表名上限 31 字符，拒绝 [ ] : * ? / \。

验证

  • 创建后：xlsx_read.py out.xlsx --sheets，确认表名、尺寸、合并范围和图表数符合意图。
  • 用 --json dump 数据并对照源值。
  • 编辑后：重新 dump 触及范围；若写了公式，确认 --formulas 列出它们且 --recalc 已应用。
  • xlsx_restructure.py 后：读其 JSON 报告，再跑 --formulas 和 --sheets，确认引用和范围落在预期处。
  • 完整视觉检查：在 LibreOffice 打开 soffice --headless --convert-to pdf out.xlsx 并检查 PDF。