document-xlsx

Document XLSX Skill - 快速参考

适用范围： 如果官方 Anthropic xlsx skill 可用，优先用它处理简单的创建/编辑、公式优先的财务模型、LibreOffice 重新计算（recalc.py）和公式错误扫描。本 skill 适用于以下专业场景：

• 原生图表、数据透视表、数据验证和条件格式
• Office Scripts、Microsoft Graph 和 xlwings 自动化
• 超大文件（write_only/read_only）
• 不可信工作簿的审计与清理

核心决策规则

• 先确定运行环境： 本地文件生成、云端工作簿自动化（Microsoft 365）、桌面版 Excel 自动化，或审计与清理。
• XlsxWriter 只能写入。 它无法打开或编辑现有的 .xlsx。要“编辑此工作簿”，请使用 openpyxl（或在 Node 中使用 ExcelJS）。在编辑任务中选择 XlsxWriter 会立即失败。
• 优先使用表格进行导出： 标题放在一行、创建一个命名的 Excel 表格、冻结标题行，并限定范围。表格自带自动筛选，因此对相同范围另行调用 autofilter() 会引发 OverlappingRange。
• 库负责写入公式；计算引擎负责计算公式。 openpyxl 不会计算公式；XlsxWriter 通常会写入占位缓存值 0 并请求重新计算，也可以接受显式提供的结果。非空缓存并不能证明已完成计算。保留公式，在目标引擎中重新计算，并在此之前独立计算所需的任何结果。参见 XlsxWriter 公式结果。
• 未来函数必须使用指定的 OOXML 拼写形式。 使用 openpyxl 时，请在写入器的未来函数列表中检查函数所需的前缀；openpyxl.utils.FORMULAE 不是兼容性测试。对于溢出公式，默认使用 XlsxWriter 的 write_dynamic_array_formula。如果不确定接收方的 Excel 版本，请优先使用 INDEX/MATCH 和嵌套的 IF。编写未来函数或数组函数，或读取缓存结果时，请加载 references/excel-formulas.md。
• 库的默认设置可能导致检查失效。请显式设置：
  • 对 Excel 输入检查，显式设置数据验证错误警告和 errorStyle="stop"；openpyxl 本身不会验证赋入的值。也要在代码中检查输入。
  • 如果未关闭 strings_to_formulas，XlsxWriter 会将以 = 开头的字符串转换为公式。
  • XlsxWriter 的 add_table 会发出警告并返回负代码，而不会抛出异常。
• 原生数据透视表： 使用 Office Scripts（Microsoft 365）或 xlwings（桌面版 Excel）。openpyxl 和 XlsxWriter 无法创建数据透视表。对于无头导出，请写入预先计算好的汇总表。
• 不可信工作簿： 使用 keep_links=False 和 keep_vba=False 加载，并在进行任何其他操作前运行 scripts/xlsx_audit.py。本 skill 从不编写或执行宏。
• 大文件： 安装 lxml，并使用 Workbook(write_only=True) / load_workbook(read_only=True)。两者都会流式处理，而不是构建完整树。只写工作簿只能保存一次（WorkbookAlreadySaved）。
• 格式上限： 每个工作表最多 1,048,576 行 × 16,384 列，由文件格式规定。请提前决定分页方式或多工作表布局。

快速参考

任务	工具	适用场景
新建以表格为先的导出	XlsxWriter (pandas/Polars)	包含表格、格式、原生图表和动态数组的报告
编辑现有工作簿	openpyxl	工作表、公式、表格、验证、保护
Node/TS 服务	ExcelJS	结构和样式。对于原生图表或数据透视表，请查阅已安装版本的文档，并测试所需的往返处理
Microsoft 365 工作簿	Office Scripts / Microsoft Graph Excel	原生数据透视表和表格；远程会话
桌面版 Excel 功能	xlwings	已安装 Excel 的计算机；不适用于无头 CI
分享前审计（门禁）	scripts/xlsx_audit.py	存在阻断性问题时返回非零退出码
文本/链接清理	scripts/xlsx_sanitize.py	为有风险的字符串添加可见的撇号；可选择移除外部链接部分。导出 CSV 时也要清理
可重复的导出	scripts/xlsx_export_report.py	将 CSV/JSON/Parquet 导出为以表格为先的 .xlsx；输入文本绝不会转换为公式

脚本和退出码

python3 scripts/xlsx_audit.py workbook.xlsx --format md       # gate
python3 scripts/xlsx_audit.py workbook.xlsx --report-only     # inventory; invalid input still exits 2
python3 scripts/xlsx_sanitize.py in.xlsx out.xlsx --strip-external-links
python3 scripts/xlsx_export_report.py data.csv report.xlsx --title "Sales"
python3 scripts/test_xlsx_sanitize.py                         # atomic output and alias rejection regressions

脚本	0	1	2
xlsx_audit.py	没有阻断性问题（启发式信号仍可能需要人工检查）	存在阻断性问题：缓存的错误值、缺少 _xlfn. 的较新函数、危险文本、外部链接部分、VBA	文件缺失、不是 zip 文件，或不是工作簿
xlsx_sanitize.py / xlsx_export_report.py	已写入	不适用	输入缺失或无法读取，或写入失败。不会留下不完整的输出文件

审计会报告但不会阻断的启发式信号：公式中的硬编码常量、隐藏或非常隐藏的工作表、HYPERLINK 公式、没有缓存值的公式。分享前请检查这些内容。审计是静态的：无法证明公式能正确计算（见下文的计算证据门禁）。

核心操作

以表格为先的导出（XlsxWriter）

import pandas as pd

with pd.ExcelWriter("report.xlsx", engine="xlsxwriter",
                    engine_kwargs={"options": {"strings_to_formulas": False}}) as writer:
    df.to_excel(writer, sheet_name="Sales", index=False, startrow=1)
    workbook, worksheet = writer.book, writer.sheets["Sales"]
    header_fmt = workbook.add_format({"bold": True, "bg_color": "#D9E2F3"})

    worksheet.write("A1", "Sales report")
    worksheet.freeze_panes(2, 0)
    # The table brings its own autofilter; a separate worksheet.autofilter() over the
    # same range raises OverlappingRange. Rows: header=1, data=2..len(df)+1, totals=len(df)+2.
    status = worksheet.add_table(1, 0, len(df) + 2, len(df.columns) - 1, {
        "name": "SalesTable",
        "style": "Table Style Medium 2",
        "total_row": True,
        "columns": [{"header": col, "header_format": header_fmt,
                     **({"total_function": "sum"} if col in ("qty", "total") else {})}
                    for col in df.columns],
    })
    if isinstance(status, int) and status < 0:   # XlsxWriter warns instead of raising
        raise ValueError("add_table rejected the table definition")

如果表格范围少了一行，合计行会悄然覆盖最后一行数据。请参见 references/excel-tables-structured-references.md。

安全编辑现有工作簿（openpyxl）

from openpyxl import load_workbook

wb = load_workbook("input.xlsx", keep_vba=False, keep_links=False)
ws = wb["Sales"]
ws["A1"] = "Sales report"
ws.freeze_panes = "A2"
wb.save("output.xlsx")

切勿使用 data_only=True 加载后再保存：这会将每个公式替换为其缓存值，或者替换为空。

已知限制和注意事项

• Google Sheets 和 LibreOffice 无法保留所有 Excel 功能。请在目标查看器中验证数据透视表、动态数组公式、保护和高级格式。

• 数据验证属于 UI 元数据；粘贴操作可能绕过验证或替换单元格规则。请将验证与保护及代码检查结合使用。请参见 openpyxl validation limits。

• 工作表和工作簿的保护密码只能起到威慑作用，并非加密。对于敏感数据，请使用文件级加密或平台访问控制。请参见 references/excel-security-protection.md。

• pandas.read_excel() 不会显示条件格式、验证、保护或图表。如需在审计时检查这些内容，请直接读取 OOXML 部分，或使用 openpyxl。

• 不同版本的库行为可能有所变化。依赖某项默认行为（例如验证或公式选项）之前，请针对已安装版本重新测试。

默认工作流

1. **创建：**选择运行时，从以表格为先的布局开始，并将输入、计算和输出分开。
2. 门禁：python3 scripts/xlsx_audit.py out.xlsx --format md 必须以 0 退出，然后对照 assets/spreadsheet-model-review-checklist.md 进行检查。
3. **交付：**清理导出的文本，检查外部链接，运行 Excel 的辅助功能检查器，并在 Excel 和目标次要查看器中打开文件。

应做 / 避免

记录假设及其值、单位、来源和日期；添加控制总计和检查单元格。隐藏工作表无法保护个人身份信息或机密信息。

计算证据门槛

在发布前定义计算约定：权威输入、预期公式或计算值、计算引擎、重新计算模式和控制总计。公式至关重要时，重新打开最终工作簿两次：

1. 显示公式，检查一致性。
2. 使用指定的计算引擎重新计算后，检查缓存结果和错误单元格（#REF!、#VALUE!、#DIV/0!、#NAME?、#N/A）。

如果没有可用的计算引擎，请将公式结果标记为未经验证，并提供独立计算的控制总计。空缓存和占位零都不能证明计算已完成；仅当缓存值是根据权威输入独立计算得出时，才提供这些值。

导航

参考

• references/excel-formulas.md - _xlfn. 前缀、溢出函数、数组公式、读回值
• references/excel-tables-structured-references.md - 表格范围计算、结构化公式
• references/excel-charts.md - 图表选择、引用设置、openpyxl 图表注意事项
• references/excel-formatting.md - 先确定类型再设置格式、条件格式规则、布局
• references/excel-data-validation.md - 强制下拉列表、命名列表、级联验证
• references/excel-pivot-tables.md - 原生数据透视表与预计算汇总
• references/excel-security-protection.md - 保护限制、加密、注入、链接
• references/excel-cloud-automation.md - Office Scripts、Microsoft Graph Excel、xlwings
• references/excel-accessibility-compliance.md - 无障碍、Section 508、EN 301 549 查询
• references/extraction-stack.md - 按任务分类的提取工具候选项，适用于 LLM/RAG 流程
• data/sources.json - 供应商和标准链接

资源

• assets/financial-report.md - 财务报表规则：关联报表、符号约定、检查单元格
• assets/data-dashboard.md - 仪表板布局注意事项（合并的 KPI 卡片、图表锚定、隐藏数据）
• assets/spreadsheet-model-review-checklist.md - 工作簿 QA 检查清单

相关技能

• ../document-pdf/SKILL.md - 根据电子表格数据生成 PDF
• ../ai-ml-data-science/SKILL.md - 数据分析和 dataframe 工作流
• ../data-sql-optimization/SKILL.md - 数据库到工作簿的处理流程

经验反馈循环

如果先前的决策或陷阱与当前任务相关，请查阅 learnings.consolidated.md（如果存在）；仅在需要了解历史记录或它是唯一可用选项时，才使用 learnings.md。否则跳过两者。

应用后，如果你遇到了值得记住的模式、值得避免的错误，或令你意外的领域事实，请通过 agents-skills-feedback-loop/scripts/append_learning.py 向 learnings.md 追加一条带日期的要点。不要修改 SKILL.md 本身。