Metadata-Version: 2.4
Name: sheetspec
Version: 0.1.1
Summary: Contract-based validation for spreadsheets created by AI agents.
Project-URL: Homepage, https://github.com/helloo1568/SheetSpec
Project-URL: Repository, https://github.com/helloo1568/SheetSpec
Project-URL: Issues, https://github.com/helloo1568/SheetSpec/issues
Project-URL: Changelog, https://github.com/helloo1568/SheetSpec/blob/main/CHANGELOG.md
Author: SheetSpec Contributors
License: MIT
License-File: LICENSE
Keywords: ai-agent,contract-testing,data-quality,excel,mcp,xlsx
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.11
Requires-Dist: jinja2<4,>=3.1.6
Requires-Dist: mcp<2,>=1.28
Requires-Dist: openpyxl<4,>=3.1.5
Requires-Dist: pydantic<3,>=2.13
Requires-Dist: pyyaml<7,>=6.0.3
Requires-Dist: typer<1,>=0.27
Description-Content-Type: text/markdown

# SheetSpec

[![CI](https://github.com/helloo1568/SheetSpec/actions/workflows/test.yml/badge.svg)](https://github.com/helloo1568/SheetSpec/actions/workflows/test.yml)
[![PyPI](https://img.shields.io/pypi/v/sheetspec.svg)](https://pypi.org/project/sheetspec/)
[![Python](https://img.shields.io/pypi/pyversions/sheetspec.svg)](https://pypi.org/project/sheetspec/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

> **Contract-based validation for spreadsheets created by AI agents.**

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

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

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

![Agent Gate Demo](docs/agent-gate-demo.gif)

![SheetSpec Architecture](docs/architecture.svg)

![Validation Report Preview](docs/validation-report-preview.svg)

## 为什么需要它？

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

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

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

## 60 秒体验

需要 Python 3.11–3.14 和 [uv](https://docs.astral.sh/uv/)。

```bash
uv sync
uv run python examples/create_demo.py
```

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

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

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

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

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

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

预期结果：

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

生成可分享的 HTML 报告：

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

## Agent Gate

```mermaid
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 的安全边界。

## 契约示例

```yaml
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

```bash
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
```

退出码：

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

## MCP

SheetSpec 提供本地 STDIO MCP Server：

```bash
uv run sheetspec mcp
```

示例配置：

```json
{
  "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 目录后，使用以下工作流：

```text
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](THIRD_PARTY_NOTICES.md)。

开发与安全文档：

- [贡献指南](CONTRIBUTING.md)
- [版本记录](CHANGELOG.md)
- [安全策略](SECURITY.md)

```text
License: MIT
```
