Antigravity Excel Engine：面向 AI 智能体的双核 Excel 自动化引擎

面向自主智能体与数据管道的企业级、AI 原生 Excel 自动化引擎。

问题所在 • 核心功能 • 快速开始 • CLI 界面 • 对比矩阵 • 贡献指南

💡 为什么选择 Antigravity Excel Engine？

构建与 Microsoft Excel 交互的自主 AI 智能体（LangChain、AutoGen、CrewAI、MCP Sidecars）或机器人流程自动化，向来以脆弱著称：

• 💥 交互式冻结（0x8001010A）： 如果用户正在单元格中主动输入，经典 COM 库会立即以 RPC_E_SERVERCALL_RETRYLATER 崩溃。
• 💸 Token 上下文窗口耗尽： 向 LLM 发送冗长的 JSON 结构或原始矩阵会耗尽上下文窗口，并使推理成本成倍增加。
• 🧟 僵尸进程噩梦： 未处理的异常经常会在后台内存中留下隐藏、挂起的 EXCEL.EXE 进程，永久锁定文件。
• 🐢 OpenPyXL 盲区： 无头文件操作无法重新计算易失性公式，也无法实时评估活动电子表格。

Antigravity Excel Engine 通过自适应 双核运行时、自动 Token 压缩、自愈式 COM 锁恢复 以及有保证的 零泄漏进程生命周期，彻底消除了这些摩擦点。

🚀 核心功能

• 🔄 Dual-Core Hybrid Runtime: Seamlessly detects whether the target spreadsheet is currently open in Microsoft Excel.
  • 文件已打开？ 启用 实时 COM，实现实时重新计算、动态公式求值、可视化更新以及完整的 Ctrl+Z 撤销历史。
  • 文件已关闭？ 自动切换到 无头 OpenPyXL，以获得最大吞吐量和服务器级速度。
• 📉 75% LLM Token 压缩： 将表格数据打包成密集、规范化的 CSV 流，专为 LLM 提示上下文注入而设计，而非浪费性的 JSON 序列化。
• 🛡️ 自愈单元格守护者： 采用指数自适应退避，优雅地拦截交互式编辑状态，等待人工输入完成，而不是抛出 COM 错误。
• ⚡ 声明式原子映射： 在单个原子事务中更新值、公式、注释、RGB 样式、边框和列自动适应。
• 🔍 公式错误哨兵： 在保存或向智能体报告之前，自动审计区域中的求值错误（#VALUE!、#REF!、#DIV/0!、#N/A、#NAME?）。
• 🤖 带确定性 JSON 的 CLI： 原生命令行界面，带有 --json 标志，可零摩擦集成到智能体工作流和工具调用框架中。

🏗 双核架构

flowchart TD
    Agent[🤖 Autonomous AI Agent / Data Pipeline] --> Engine[Antigravity Excel Engine API]
    Engine --> Detector{Target Workbook Open in Excel?}
    
    Detector -- Yes --> COM[🚀 Live COM Engine\nwin32com.client]
    Detector -- No --> Headless[⚡ Headless Engine\nOpenPyXL]
    
    COM --> Guardian[🛡️ Self-Healing Backoff Guardian\n0x8001010A Auto-Recovery]
    Guardian --> LiveOps[Real-time Recalculation & Undo Support]
    
    Headless --> FastOps[High-Speed In-Memory File Processing]
    
    LiveOps --> Streamer[📉 Token-Optimized CSV Streamer\n-75% LLM Context Overhead]
    FastOps --> Streamer
    
    Streamer --> Agent

加载中

⚡ 快速开始

1. 安装

# Clone the repository
git clone https://github.com/FranciscoGrandon/antigravity-excel-engine.git
cd antigravity-excel-engine

# Install dependencies
pip install -r requirements.txt

2. 30 秒上手 Python API

from antigravity_excel_core import AntigravityExcelEngine

# Initialize (auto-detects Live COM vs Headless OpenPyXL)
engine = AntigravityExcelEngine(mode="auto", file_path="financial_model.xlsx")

# 1. Read token-optimized stream (ideal for LLM prompt context)
csv_stream = engine.get_range_as_csv("A1:D50")
print(csv_stream)

# 2. Apply declarative atomic updates with styles & formulas
engine.set_cells({
    "A1": {
        "value": "Total Revenue",
        "cellStyles": {"fontWeight": "bold", "backgroundColor": "#0E2E63", "fontColor": "#FFFFFF"}
    },
    "B1": {
        "formula": "=SUM(B2:B10)",
        "cellStyles": {"numberFormat": "$#,##0.00"}
    },
    "A2": {
        "value": "Autonomous Agent Note",
        "note": "Audited and verified by Antigravity Engine"
    }
}, autofit=True)

# 3. Audit for broken formulas
errors = engine.check_formula_errors("A1:B10")
if errors:
    print(f"⚠️ Formula errors found: {errors}")

# 4. Commit changes safely
engine.save()

🤖 面向 AI 智能体与管道的 CLI

每条命令都支持确定性 --json 输出，使其可直接兼容子智能体、bash 脚本和工具调用编排器：

# Inspect Excel environment and active workbooks
python antigravity_excel_cli.py status --json

# Extract range as token-dense CSV stream
python antigravity_excel_cli.py get-csv A1:D50 --file "data.xlsx" --json

# Apply batch cell updates from JSON payload with auto-fitting
python antigravity_excel_cli.py set-cells --input-file payload.json --autofit --json

# Audit formulas for evaluation anomalies
python antigravity_excel_cli.py check-errors A1:Z100 --file "model.xlsx" --json

📊 功能矩阵

🤝 贡献

非常欢迎贡献、问题报告和功能建议！在提交 Pull Request 之前，请查阅我们的 CONTRIBUTING.md 指南。

📄 许可证与作者

由 Francisco Grandón Vergara 自豪开发。
基于 MIT License 发布。