1实现原理 · 为什么它能做到

与 docx/pptx 同哲学：按任务选工具——带公式/格式的创建编辑走 openpyxl，批量数据走 pandas，快速浏览走 markitdown，读『公式+值』模型必须双次 load_workbook。

skills/xlsx/SKILL.md

| **Read** a model (formulas *and* values) | two `load_workbook` passes — see gotchas

双载原理在 gotchas 明说：'`data_only=True` yields cached values with the formulas gone; the default yields formula strings with no values. One pass cannot give you both.'——openpyxl 单次加载拿不到公式+值。

核心工程事实：openpyxl 只写公式字符串不带缓存值，凡含公式文件交付前必须 recalc.py——它驱动 LibreOffice 以 StarBasic 宏重算并原地重写文件，返回带 status/errors_found 的 JSON 契约。

skills/xlsx/SKILL.md

openpyxl writes formulas as strings with **no cached values**. Until you recalculate, every formula cell reads back as `None` to anything reading cached values

recalc.py 内嵌 Basic 宏 'Sub RecalculateAndSave() … ThisComponent.calculateAll() ThisComponent.store()'，在临时 LO profile 里跑；'JSON with an `error` key instead of a `status` means nothing was recalculated, and only that case exits non-zero'——退出码语义被显式警告。

公式可移植性被当作交付质量：LO 实现的函数子集<Excel，写不进 _xlfn. 前缀或不支持的函数会变成 #NAME? 烤进交付文件，所以有一张『能用/需前缀/禁用』三档函数清单。

skills/xlsx/SKILL.md

LibreOffice implements fewer functions than Excel, and one it cannot evaluate becomes a literal `#NAME?` baked into the file you deliver.

细则：Excel-2007 时代函数（SUMIFS/INDEX/MATCH/IFERROR/SUMPRODUCT）免前缀；TEXTJOIN/CONCAT/IFS/SWITCH/MAXIFS/MINIFS 需 _xlfn. 前缀；XLOOKUP/XMATCH/SORT/FILTER/UNIQUE/SEQUENCE 禁用（spill 数组无元数据会静默截断到左上角且 recalc 报 0 错）。

『绿色 recalc ≠ 公式正确』被显式化：误差范围错、引错行的公式照样 0 错通过，要求先写 2-3 条公式抽验值再铺网格。

skills/xlsx/SKILL.md

**A green recalc proves your formulas *evaluate*, not that they are *right*.**

配套纪律：'Zero formula errors. Never ship while `recalc.py` reports `errors_found`' + 'Use formulas, never hardcoded results' + 'An error you introduced looks exactly like one you inherited'（自证清白法：用 data_only=True 读原件对比）。

外链引用（'[1]Returns Analysis'!$B$2）被识别为高危：openpyxl 重存会丢缓存值、LO 再解析会失败并删除全部链接——recalc.py 检测到外链直接拒跑，需先拷值或 --force 接受损失。

skills/xlsx/SKILL.md

if you re-save it with openpyxl and then recalculate. Such a formula reads `='[1]Returns Analysis'!$B$2`

recalc.py 的 external_links_at_risk() 扫描 xl/externalLinks/ 与公式中的 EXTERNAL_REF_RE 模式，返回 at_risk 单元格清单；'`recalc.py` refuses to run in that state — copy those cells' values out of the original before you save over them'。

交付物纪律成体系：专业字体、每条假设/硬编码数字留注释或邻格并注明出处、自建待填工作簿要带 legend+示例行、改既有文件只写它的输入格且不动公式、按用户字面规格做。

skills/xlsx/SKILL.md

**Follow the user's spec literally.** Exact tab names, exact column headers, and the formula they spelled out. A redesign that computes something else fails, however elegant.

还有 'Document every assumption and hardcoded number where the reader will see it' 与 'Find its designated input cells first…write only there, and leave every existing formula untouched.'

2核心能力

01创建/编辑带公式与格式的工作簿（openpyxl），含 .xlsm keep_vba/.xltx/.csv/.tsv 处理

02公式重算验证闭环：recalc.py 驱动 LibreOffice，JSON 报 status/total_formulas/total_errors/error_summary

03批量数据进出与清洗（pandas read_excel/to_excel）

04快速浏览（markitdown，sheet 级文本转储）

05公式可移植性治理：Excel-2007 时代函数优先 / _xlfn. 前缀表 / 禁用现代数组函数清单

06外链引用风险评估与拒跑保护（external_links_at_risk / --force）

07财务模型格式惯例：硬编码输入蓝/公式黑/跨表绿/跨文件红/关键假设黄，$#,##0 与百分比/倍数/年份格式

08编辑既有文件惯例匹配：找输入格、只写那里、不动公式；自建待填模板带 legend 与示例行

3外部依赖

Kind	Dependency / Endpoint
package	openpyxl / pandas / markitdown（pip，预装声明，import 失败才装）
cli	LibreOffice soffice（recalc 引擎，经 scripts/office/soffice.py 包装，适配无头沙箱）
cli	gtimeout（可选，recalc 超时保护）

4管控建议与判定依据

建议配套管控措施

面向 Agent

分级或逐次授权，建议在沙箱运行

面向管理者

审批流程、可回滚、全程审计

判定依据（文件路径与关键语句摘要）

scripts/: 执行本地脚本或命令: recalc.py（自带 python）→ 经 soffice.py 启动 LibreOffice headless 执行内嵌 Basic 宏（cal
本地工作目录: 文件读写与工件输出: recalc 原地重写工作簿（-env:UserInstallation 临时 LO profile 在 tempdir）

审计说明： 。运行自带 python 脚本 + 本地 LibreOffice 做公式重算与文件改写，无网络外发（仅 import 失败时的条件 pip 回退到 PyPI）、无凭证读取。注意点：① recalc 会『原地重写』交付文件且依赖 LO 无头执行（含内嵌 Basic 宏——宏内容自包含、仅 calculateAll+store）；② 处理含宏 .xlsm/不可信工作簿时，文档解析暴露面在 openpyxl/LibreOffice（宿主需自行评估版本与沙箱）；③ 外链文件场景 recalc 拒跑是数据保护设计而非故障。整体为本地表格工程技能，无外联风险。

5第二遍独立确认

[ok] recalc JSON 契约与退出码语义 — 代码返回 dict 含 status/errors_found 等键；main 中 'sys.exit(1 if "error" in result else 0)' 与 SKILL 'only that case exits non-zero' 一致。
[ok] 外链拒跑机制 — external_links_at_risk() 扫描 xl/externalLinks/ 并匹配 EXTERNAL_REF_RE，SKILL 所述 'refuses to run in that state' 有代码对应（force 分支）。
[ok] LibreOffice 宏重算 — RECALCULATE_MACRO 内嵌 'Sub RecalculateAndSave() … ThisComponent.calculateAll() ThisComponent.store()'，经临时 profile 执行。
[ok] 共享 office/ 工具树 — xlsx/scripts/office 与 docx、pptx 的对应目录 diff 零差异（同一文件副本）。
[ok] 网络/凭证零命中 — 脚本无网络调用、无 env/token 读取；pip 仅条件回退。
[ok] 夸大检查 — description 'Use this skill any time a spreadsheet file is the primary input or output' 覆盖 open/read/edit/create/convert/clean 均在正文有路线；'Do NOT trigger when…Google Sheets API integration' 负面边界明确。

6结论

公式重算工程化：openpyxl 无缓存值这一核心缺陷被 recalc.py+LO 宏闭环解决，且 JSON 契约让模型能自证交付。

函数兼容三档清单（免前缀/_xlfn./禁用）直接防止交付 #NAME? 或静默截断的坏文件。

外链数据保护：检测→拒跑→拷值→--force 阶梯，防『重存即丢链』事故。

交付纪律完整（零公式错误/假设留痕/spec 字面执行/既有文件只写输入格），像把严谨建模师的习惯写成规则。

财务模型惯例内置，可直接用于结构化建模交付。

适合： 适合在受管环境里做表格『建模级』工作：带公式的财务模型、报表自动化、批量数据清洗成表、模板套用；recalc 门禁 + 外链保护尤其适合『交付即要用 Excel/Sheets 打开计算』的严肃场景。

不适合： 不适合无 LibreOffice 的环境（验证闭环不可用）；不适合只做一次性数据查看/转换的轻任务（markitdown/pandas 即可，流程偏重）；不适合与外部 Excel 文件强链接的工作簿编辑（风险高，需拷值流程）；不适合不能接受专有许可的组织。

Install Agent-Ready

① Verified Mirror 2026-09-09

Option A · Direct DownloadDownload xlsx.tar.gz

sha256: d680b3f18f0c671a…

Option B · Copy Guide for Agent

install.json

agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。

② Upstream GitHub

GitHub Repo ↗

Pinned to commit 41bbe19d1a.