Arezzo

Arezzo

用于 Google Docs API 操作的确定性编译器。

你无法通过自行构造 batchUpdate 请求来安全地修改 Google 文档。该 API 使用 UTF-16 代码单元，并会导致索引级联偏移——在位置 50 插入 10 个字符后，批次中所有后续索引都会出错。只要有一次计算错误，文档就会在没有任何错误提示的情况下被悄然损坏。

Arezzo 会将语义意图编译为正确的请求序列。告诉它你想做什么；索引计算交给它处理。

面向 AI Agent（MCP 工具）

Arezzo 通过 Model Context Protocol 提供三个工具：

read_document(document_id)
  → Returns the document's structural map: headings with hierarchy,
    named ranges, tables, section boundaries. Call this before editing
    so you know what addresses are available.

edit_document(document_id, operations)
  → Compiles operations into correct batchUpdate requests and executes
    them. Handles UTF-16 arithmetic, cascading index shifts, and
    OT-compatible request ordering. Supported operations: insert/delete/
    replace text, formatting (bold, italic, headings, links), tables,
    lists, images, headers/footers, footnotes, named ranges.

validate_operations(document_id, operations)
  → Compile-only dry run. Returns the compiled requests for inspection
    without executing. Use before edit_document when uncertain.

操作格式

{
  "type": "insert_text",
  "address": {"heading": "Revenue Analysis"},
  "params": {"text": "New paragraph content.\n"}
}

地址模式：

• {"heading": "Section Name"} — 按标题文本定位
• {"named_range": "range_name"} — 按命名范围定位
• {"bookmark": "bookmark_id"} — 按书签 ID 定位
• {"start": true} — 文档开头
• {"end": true} — 文档结尾
• {"index": 42} — 绝对 UTF-16 索引

操作类型： insert_text、delete_content、replace_all_text、replace_section、 update_text_style、update_paragraph_style、insert_bullet_list、 insert_table、insert_table_row、insert_table_column、 delete_table_row、delete_table_column、insert_image、 create_header、create_footer、create_footnote、 create_named_range、replace_named_range_content、insert_page_break

推荐工作流

read_document → edit_document → (if structural changes) read_document → edit_document

编辑前务必先读取。插入结构元素（表格、页眉、页脚）后，再次读取以获取新元素的索引，然后再向其中添加内容。

安装

pip install arezzo
arezzo init

arezzo init 会引导你完成 Google OAuth 设置，并为你的 MCP 客户端写入平台配置文件。

设置

前提条件： 一个已启用 Google Docs API 的 Google Cloud 项目，以及一个 OAuth 2.0 客户端 ID（桌面应用类型）。

arezzo init

向导会：

1. 将你的 credentials.json 复制到 ~/.config/arezzo/
2. 运行 OAuth 授权流程（浏览器会打开一次）
3. 为 Claude Code、Cursor 和 VS Code 生成配置文件

对于 Claude Desktop，arezzo init 会打印配置块，供你手动添加。

平台配置

运行 arezzo init 后，配置文件会写入你的项目目录：

Claude Code / Cursor（.mcp.json）：

{
  "mcpServers": {
    "arezzo": {
      "command": "arezzo"
    }
  }
}

VS Code（.vscode/mcp.json）：

{
  "servers": {
    "arezzo": {
      "type": "stdio",
      "command": "arezzo"
    }
  }
}

Claude Desktop（macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "arezzo": {
      "command": "arezzo"
    }
  }
}

Arezzo 的存在意义

Google Docs 的 batchUpdate API 使用 UTF-16 代码单元和绝对索引位置。每次插入或删除字符，都会使所有后续索引发生偏移。在包含多项修改的批次中，每个请求的索引都必须考虑同一批次中之前每个请求的影响。

要正确处理这些操作，需要：

• 计算 UTF-16 长度（不能用 Python 的 len()——代理对的计数方式不同）
• 对同类型修改按逆序执行（从后向前删除）
• 分两阶段编译（先修改内容，再修改格式）
• 跟踪多步操作中的级联偏移

Arezzo 会以确定性的方式处理这些操作。相同输入总会产生相同输出。不需要推理，不需要猜测，也不会出现“通常能用”的情况。

架构

semantic operation
    ↓
arezzo.parser.parse_document()    — build heading/range/bookmark indexes
    ↓
arezzo.address.resolve_address()  — semantic reference → document index
    ↓
arezzo.operations.*               — operation → batchUpdate request(s)
    ↓
arezzo.index.sort_requests()      — OT-compatible mutation ordering
    ↓
correct batchUpdate request sequence

引擎是一个纯函数：compile_operations(doc, operations) → requests。确定性执行，无副作用，不调用 API。

MCP 服务（arezzo.server）将引擎与 Google Docs API I/O 以及行为指导字段（next_step、present_to_user、document_reality）封装在一起。

许可证

MIT — Convergent Methods, LLC