Spreadsheet Auditor

审计现有的 Excel 电子表格和财务模型，查找正确性缺陷 — 公式错误、损坏的引用、错误的范围、无法对账的合计以及数据质量风险。

`spreadsheet-auditor` 是一个便携的 [Agent Skill](https://agentskills.io/specification)，专为 **Claude 和 Codex** 设计（同时也是一款独立的命令行工具包），旨在回答一个问题：**“我能信任这个电子表格吗？”** 大多数电子表格工具帮助您*构建*工作簿。而这款工具则是*审计*您已有的工作簿 — 通常是您接手的文件 — 并生成一份按严重程度排序的报告，指出可能出错、脆弱或不一致的地方。它以确定性优先：内置的 Python 检查能生成候选问题，并提供准确的单元格位置和证据，因此您无需肉眼检查单元格来凭空猜测。 它被特意设计为**仅审计**模式：它只报告缺陷和可选的注释，绝不会静默重写、重新格式化或“修复”您的源工作簿。 ## 演示（60秒） ``` pip install "spreadsheet-auditor[all]" spreadsheet-auditor --demo --summary ``` 或者针对您自己的工作簿： ``` spreadsheet-auditor path/to/workbook.xlsx \ --out audit_report.md \ --json findings.json \ --annotated audit_annotated.xlsx ``` 完整的演示位于 [`examples/`](examples/) 目录中，包含一个生成器 ([`examples/make_demo.py`](examples/make_demo.py))、预设的工作簿， 以及随时可供检查的报告/JSON/HTML/带注释的输出结果。 ## 为什么使用它 - **发送前的模型审查** — 在 LBO/DCF/预算模型提交给投资委员会或交易对手之前降低风险。 - **“寻找错误”的调试** — 当某个数字看起来不对时，您需要的是确切的单元格，而不是猜测。 - **对接手模型的信任度评估** — 您没有构建它；检查它是否值得信赖。 - **CI / 批处理拦截** — 当提交的工作簿存在 Critical（严重）缺陷时，让流水线失败（参见 [`examples/github-actions/`](examples/github-actions/)）。 - **FP&A 和月末结账** — 在周期性工作簿中发现对账和范围错误。 ## 它能检测什么 | 类别 | 检查项 | |---|---| | 公式完整性 | 实时错误（`#REF!`、`#DIV/0!`、`#VALUE!`、`#N/A` 等）、损坏/删除的引用、对空白前置项的引用、循环引用、跨行/列的公式偏差、`IFERROR`/`IFNA` 错误掩盖 | | 硬编码与输入项 | 嵌入公式中的数字字面量、公式块内的硬编码塞入值 | | 范围 | 排除了相邻数据的聚合范围（差一错误）、包含小计/合计行的范围、同侪间不一致的聚合范围长度、合计中隐藏的行/列/工作表 | | 对账 | 与其组成部分不符的标称合计、无法交叉验证的行合计与列合计 | | 逻辑与结构 | 易变/脆弱的函数（`OFFSET`、`INDIRECT`、`NOW`、`RAND` 等）、整列引用 | | 数据清理 | 存储为文本的数字、键/标签中的首尾空格、重复的查找键、数据范围内的合并单元格 | | 财务（可选 HEUR） | 资产负债表平衡、收入/支出行的符号惯例、季度周期排序 | 每个检查结果都包含检测模式（`DET` 确定性 / `HEUR` 启发式）、 错误置信度级别（`Defect` 缺陷 / `Likely defect` 可能缺陷 / `Review` 待审查 / `Info` 信息）、 严重程度、证据以及建议的修复方法。完整规则列表： [`references/check_catalog.md`](references/check_catalog.md)。 预设缺陷基准测试发布于 [`benchmarks/seeded_defects_matrix.md`](benchmarks/seeded_defects_matrix.md)； 测试方法见 [`references/benchmark_methodology.md`](references/benchmark_methodology.md)。 ## 安装 ``` pip install spreadsheet-auditor # core + .xlsx/.xlsm/.csv audit pip install "spreadsheet-auditor[all]" # adds defusedxml, networkx, PyYAML ``` 对于本地开发： ``` git clone https://github.com/petehottelet/spreadsheet-auditor.git cd spreadsheet-auditor pip install -e ".[dev]" spreadsheet-auditor --healthcheck python -m pytest tests -q ``` 发布版本（带签名的源代码归档 + Claude/Codex 技能压缩包 + SHA-256 校验和）发布在 [发布页面](https://github.com/petehottelet/spreadsheet-auditor/releases)。 ## 运行 ``` # 终端中快速查看 spreadsheet-auditor model.xlsx # 以所有支持的格式写入 artifacts spreadsheet-auditor model.xlsx \ --out report.md \ --json findings.json \ --annotated annotated.xlsx spreadsheet-auditor model.xlsx --format html --out report.html spreadsheet-auditor model.xlsx --format sarif --out report.sarif # 对 CI 友好：单屏摘要 + 遇到 High 或更严重级别时非零退出 spreadsheet-auditor model.xlsx --summary --fail-on High # 内置 demo，提供 60 秒快速体验 spreadsheet-auditor --demo --summary ``` 请参阅 `spreadsheet-auditor --help` 获取完整的参数参考，包括 `--strict`、`--show-suppressed`、`--quiet`、`--config`、`--ignore`、 `--recalc-timeout` 和 `--healthcheck --json`。 ## 输出结果 - **Markdown 报告**：用于人工审查，按 `Confirmed`（已确认）/`Likely`（可能）/`Review`（待审查） 分类，方便对最严重的问题进行分类处理。 - **HTML 报告**：用于浏览器审查或与非技术审查人员分享 （独立运行，无需网络）。 - **JSON 检查结果**：用于重复运行、CI 和下游工具。根据 [`schemas/findings.schema.json`](schemas/findings.schema.json) 进行验证。每个检查结果 都包含一个稳定的 `fingerprint`，用于跨运行的差异对比以及基于指纹的 抑制处理。 - **SARIF 2.1.0**：用于 GitHub 代码扫描。参见 [`examples/github-actions/code-scanning.yml`](examples/github-actions/code-scanning.yml)。 - **带注释的工作簿副本**：在出现问题的单元格处添加批注（`--annotated`）。 源工作簿绝不会被修改。 ## 退出代码 | 代码 | 含义 | |---:|---| | 0 | 运行完成；没有达到或超过 `--fail-on` 设置的检查结果 | | 1 | 运行完成；存在达到或超过 `--fail-on` 设置的检查结果 | | 2 | 完成但存在覆盖限制（仅在使用 `--strict` 或 `--fail-on None` 时出现） | | 3 | 健康检查失败：缺少必需的依赖项 | | 4 | 预检/安全检查失败 | | 5 | 内部错误 | 良性的限制（没有重新计算引擎、缺少可选包）不会 导致正常运行失败。在 CI 中使用 `--strict` 可将其作为退出代码 `2` 呈现。 ## Agent Skill 用法 将发布版本中的 Claude/Codex zip 文件放入您的 Skills 文件夹，或者直接通过 [Cursor](https://cursor.com/) Skills 加载。向 agent 发送类似以下的请求： 该技能会将请求映射到内置的 CLI 调用，并直接展示检查结果。 ## 配置 可选的配置文件（JSON 或 YAML）控制范围、重要性、抑制规则、 性能限制以及触发的检查项。Schema： [`schemas/config.schema.json`](schemas/config.schema.json)。 示例： ``` scope: include_sheets: [Budget, Summary] headline_outputs: [Summary!C1, Summary!C2] materiality: absolute: 1000.0 relative: 0.001 finance: enabled: true # turn on the finance HEUR pack limits: max_formulas: 50000 timeout_seconds: 120 max_reported_findings: 200 checks: IFERROR_MASK: review # warn instead of error LITERAL_CONSTANT: off suppressions: - rule_id: BROKEN_REFERENCE range: Imports!A1:A100 reason: External feed populated at runtime; cells start empty. ``` ## 安全性 电子表格文件被视为不受信任的输入。宏会被记录清单但 绝不执行，外部链接会被记录清单但 绝不跟踪，重新计算在隔离的配置文件中以无头模式运行，原始工作簿 绝不会被覆盖。详情请参阅 [`SECURITY.md`](SECURITY.md) 和 [`references/limitations.md`](references/limitations.md)。 ## 限制 Excel 的特定行为通过 LibreOffice 进行近似模拟。依赖于具体数值的检查 （`TOTAL_MISMATCH`、`CROSS_FOOT_FAILURE`）需要重新计算 （LibreOffice/Calc）或由 Excel 写入的缓存值。动态数组、数据 表、Power Query/Data Model 和宏会被*记录清单但不会执行*。 完整列表： [`references/limitations.md`](references/limitations.md)。 Google Sheets：导出为 `.xlsx` 并对其进行审计。没有原生的 Sheets API 集成。配方请参阅 [`references/google_sheets.md`](references/google_sheets.md)。 ## 常见问题解答 **它会修复我的电子表格吗？** 不会。它报告带有 建议修复方法的候选缺陷；应用更改是一个单独且明确的步骤。 **这是会计或审计认证吗？** 不是。它标记可能的缺陷 和待审查项；它不认证业务、会计、税务或法律层面的 正确性。 **在没有安装 Excel 的情况下它能工作吗？** 可以。它使用 `openpyxl` 读取工作簿。LibreOffice 是可选的，仅用于刷新依赖于数值检查的缓存值。 **它支持 Google Sheets 吗？** 不直接支持。请导出为 `.xlsx` 并对其进行审计。 **如何处理误报？** 通过 `(rule_id, range, reason)` 或 `fingerprint` 忽略它们。必须提供原因；缺少原因的抑制规则将被忽略，并在报告的覆盖限制中特别指出。被抑制的检查结果 会保留在 JSON 负载中（可审计），但除非 传递了 `--show-suppressed` 参数，否则它们会在报告中隐藏。 ## 许可证 MIT。请参阅 [`LICENSE`](LICENSE)。 _{主题：电子表格审计、excel auditor、xlsx、xlsm、财务模型 审查、公式错误检查器、对账、交叉验证、范围检查、 循环引用检测、数据质量、openpyxl、python、CLI、agent skill、静态分析、claude、codex、FP&A、财务建模、fpna。}

标签：Excel, LNA, 公式检查, 数据质量, 聊天机器人, 财务审计, 逆向工具