sheetspec 0.1.1

Contract-based validation for spreadsheets created by AI agents.

SheetSpec

Contract-based validation for spreadsheets created by AI agents.

Agent 负责制作表格，SheetSpec 负责验证交付物是否通过已声明的验收规则。

SheetSpec 不是 Excel 聊天机器人，也不是数据清洗网站。它是一层独立、确定性、可复现的 Excel 交付门禁：

用户要求
  → 验收契约
  → Agent 创建/修改 Excel
  → SheetSpec 验收
  → 结构化返工问题
  → 重新验收
  → 通过后交付

为什么需要它？

Agent 可以生成一个“看起来正确”的工作簿，但文件成功保存不代表任务真正完成。隐藏问题可能包括：

• 缺少工作表或关键字段；
• 金额被写成文本；
• 订单编号重复；
• 某一行漏填公式；
• 同一计算列出现异常引用；
• 合计与明细之和不一致；
• Agent 修改了不应修改的模板区域。

SheetSpec 不会声称理解所有业务意图。它只验证用户明确声明的契约，并给出可以定位到工作表、单元格或区域的结果。

60 秒体验

需要 Python 3.11–3.14 和 uv。

uv sync
uv run python examples/create_demo.py

检查故意包含错误的工作簿：

uv run sheetspec check examples/sales-report-broken.xlsx \
  --spec examples/sales-report.spec.yaml \
  --format text

PowerShell 中检查命令的失败退出码：

uv run sheetspec check examples/sales-report-broken.xlsx `
  --spec examples/sales-report.spec.yaml `
  --format json

它会发现缺失月份、重复订单、两个硬编码金额、缺失汇总公式、异常公式和错误合计。修复后的工作簿使用同一份契约验收：

uv run sheetspec check examples/sales-report-fixed.xlsx \
  --spec examples/sales-report.spec.yaml \
  --format json

预期结果：

status: passed
checks: 12
passed: 12
errors: 0
warnings: 0

生成可分享的 HTML 报告：

uv run sheetspec report examples/sales-report-broken.xlsx \
  --spec examples/sales-report.spec.yaml \
  --output examples/validation-report.html

Agent Gate

flowchart LR
  A["用户描述要求"] --> B["draft_workbook_spec"]
  B --> C["用户确认契约"]
  C --> D["sheetspec lock"]
  D --> E["Agent 创建或修改 Excel"]
  E --> F["validate_workbook"]
  F -->|失败| G["读取 JSON 问题并返工"]
  G --> F
  F -->|通过| H["交付 Excel + 报告"]

契约锁保存规范化契约和可选基线工作簿的 SHA-256。它用于检测变更，不替代 Git、代码审查或 CI 的安全边界。

契约示例

version: "0.1"
name: 年度销售报表验收
baseline: sales-report-template.xlsx

checks:
  - id: required-sheets
    type: required_sheets
    sheets: [原始数据, 月度汇总]

  - id: order-id-unique
    type: unique_values
    sheet: 原始数据
    range: A2:A500

  - id: amount-formulas
    type: formulas_required
    sheet: 原始数据
    range: F2:F500

  - id: annual-total
    type: total_equals_sum
    sheet: 月度汇总
    total_cell: N2
    source_range: B2:M2
    tolerance: 0.01

  - id: protect-summary-header
    type: unchanged_ranges
    sheet: 月度汇总
    ranges: [A1:N1]
    compare: both

支持：

规则	用途
required_sheets	必要工作表
required_columns	必要字段
required_cells	关键单元格非空或精确值
no_blank_values	区域非空
unique_values	唯一值
allowed_values	枚举值
data_type	数字、文本、日期、布尔值或公式
formulas_required	必须使用公式
formula_consistency	相邻公式结构一致
total_equals_sum	合计等于源区域求和
unchanged_ranges	Agent 不得修改基线区域

CLI

sheetspec --version
sheetspec inspect report.xlsx --format json
sheetspec init report.xlsx --output report.spec.yaml
sheetspec lock report.spec.yaml --output report.spec.lock.json
sheetspec check report.xlsx --spec report.spec.yaml --format json
sheetspec diff before.xlsx after.xlsx --format json
sheetspec report report.xlsx --spec report.spec.yaml --output report.html
sheetspec mcp

退出码：

0  验收通过
1  存在 error
2  文件、契约或锁文件无效
3  内部错误

MCP

SheetSpec 提供本地 STDIO MCP Server：

uv run sheetspec mcp

示例配置：

{
  "mcpServers": {
    "sheetspec": {
      "command": "uv",
      "args": ["run", "sheetspec", "mcp"]
    }
  }
}

工具：

• inspect_workbook
• draft_workbook_spec
• validate_workbook
• compare_workbooks
• generate_validation_report

MCP 负责提供可调用工具，skills/sheetspec/SKILL.md 规定 Agent 什么时候必须调用，GitHub Actions 负责在仓库层面强制验收。

Agent Skill

将 skills/sheetspec/ 安装到 Agent 的 Skill 目录后，使用以下工作流：

inspect → draft/review → lock → create/edit → validate
→ repair ERROR → validate again → deliver

Skill 明确禁止：

• 为了通过验收而修改契约；
• 在验收过程中改写原始工作簿；
• 把公式缓存缺失说成计算已经验证；
• 在仍有 ERROR 时宣称交付完成。

技术边界

• 只读 .xlsx，不会自动修改用户工作簿；
• openpyxl 不会像 Excel 一样重新计算任意公式；
• 复杂公式、外部引用、VBA、Power Query 和数据透视语义不在 v0.1 范围；
• passed 只代表已声明规则全部通过，不代表整个业务模型绝对正确；
• 超过50MB的工作簿或超过10万个单规则单元格的区域会被拒绝；
• 默认最多返回500个问题，避免 Agent 上下文被大量重复错误占满。

Roadmap

• 0.2：可选 LibreOffice 重计算、JUnit/SARIF CI 输出、规则插件接口；
• 0.3：更多模板场景、交互式 MCP 报告和安全的有限自动修复；
• 长期：在保持确定性核心的前提下，为不同 Agent 提供更完整的交付工作流。

开源说明

SheetSpec 使用原创验收引擎，并依赖 openpyxl、Pydantic、PyYAML、Typer、Jinja2 和 MCP Python SDK。第三方许可证见 THIRD_PARTY_NOTICES.md。

开发与安全文档：

• 贡献指南
• 版本记录
• 安全策略

License: MIT