spreadsheet-kit MCP

agent-spreadsheet

agent-spreadsheet 是面向 Agent 电子表格操作的工具交互服务。

它为 Agent 提供安全、可检查且节省令牌的方式来读取、分析、修改、验证和运营 Excel 工作簿，无需退而求其次，使用脆弱的 UI 自动化。

如果你希望 Agent 像操作真实系统一样处理电子表格，而不是充当只能看截图的木偶，这就是你需要的技术栈。

---

本项目是什么

agent-spreadsheet 在三个层面提供统一的电子表格交互层：

层面	二进制文件 / 软件包	模式	最适合
命令行工具	agent-spreadsheet / asp	无状态文件 + 常驻会话	单次运行的流水线，或保留多轮工作簿编辑状态
MCP 服务	agent-spreadsheet-mcp	有状态	多轮 Agent 会话、工作簿缓存、分叉 / 重算工作流
TypeScript SDK	agent-spreadsheet-sdk	库	应用集成——驱动服务端规范的 /v1 路由，或通过嵌入式 WASM 引擎完全在进程内运行（无需服务）

WASM 构建（agent-spreadsheet-wasm）是 SDK 的本地运行时，并非独立的产品形态：JS 和 TypeScript 代码面向同一个对象模型，执行基底（服务端还是嵌入式引擎）则是可配置的选项。

在 0.16 中，这些层面共用常驻的 Rust 文档 / 求值器运行时和 32 项操作注册表。显式原生会话会自动启动一个由私有日志支持的主机。SDK/WASM 和真正的 just-bash 会话会在内存中保留历史；XLSX 导出保存的是文档快照，而非可重启的会话日志。持续编辑 / 重算 / 读取循环无需进行 XLSX 序列化，也无需重复载入求值器。请参阅运行时保证与限制以及 SDK/just-bash 示例。

支持的工作簿模式：

• .xlsx / .xlsm — 读取 + 写入
• .xls / .xlsb — 仅用于发现 / 读取的工作流

由 Formualizer 提供支持

默认的进程内计算采用 Formualizer——一个以 Rust 编写、采用宽松许可（MIT/Apache-2.0）的电子表格引擎：支持公式解析、依赖图重算、400 多个 Excel 函数、动态数组，以及专为 Agent 打造的确定性求值。无需 Excel COM 或无头 LibreOffice。仍可选择集成 LibreOffice，但 Formualizer 是发布关键后端。

正是这个原生引擎，让本项目能够提供大多数面向 Agent 的电子表格工具都无法做到的功能：重算实际工作簿，追踪哪些单元格发生了变化以及原因，并验证结果——而不只是读取缓存值或盲目修改。

如果你要在自己的产品中嵌入电子表格逻辑，而不是让 Agent 驱动工作簿，请直接使用 Formualizer（Rust、Python、JS/WASM）。

---

Agent 为何使用 agent-spreadsheet

专为工具调用而设计，而不只是面向人类

• 确定性的 JSON 契约
• 直接从命令行工具中发现架构和示例
• 明确的分页和紧凑输出模式
• 机器可读的警告和错误封装

安全地修改，而非盲目修改

• 先试运行的工作流
• 无状态输出模式与覆盖安全性
• 基于事件溯源的会话编辑
• 用于证明下游结果的验证界面
• 在对工作簿进行高风险更改前分析结构影响

了解电子表格，而非通用文件编辑

• 区域检测
• 了解表格和页脚的追加辅助工具
• 模板行 / 行带克隆
• 专用于公式的替换与诊断
• 命名范围的 CRUD 操作
• 重算 + 差异比较 + 证明工作流

出色的 Agent 使用体验

• 支持旧别名的嵌套命令组
• 节省令牌的读取
• 精确单元格检查与布局检查
• 为 Agent 通常容易出错的重复性工作提供工作流辅助工具

---

新增内容 / 这套工具栈的独特之处

当前功能远不止简单的“读取一些单元格”。主要功能现在包括：

• 以 asp 作为主要 CLI，并保留 agent-spreadsheet 作为兼容别名
• 分组验证：通过 asp verify proof 和 asp verify diff 实现
• 预览优先的工作流辅助工具，用于：
  • write append
  • write clone-template-row
  • write clone-row-band
• 具有解析策略诊断的公式安全批处理工作流
• 单元格 / 布局 / 导出 / 导入检查界面
• 命名范围管理（write name define|update|delete）
• 仅替换公式（write formulas replace）
• 基于事件溯源的会话编辑，支持日志、分支、撤销 / 重做、分叉、应用和物化
• SheetPort 清单生命周期管理 + 执行，用于契约驱动的电子表格自动化

---

安装

Shell 安装脚本

curl -fsSL https://raw.githubusercontent.com/PSU3D0/agent-spreadsheet/main/install.sh | sh

安装脚本会将预构建 CLI 下载到 ~/.local/bin，并创建 asp 命令。使用 ASP_VERSION=0.16.0 固定版本，设置 ASP_INSTALL_DIR 选择其他安装位置，或传入 --mcp 同时安装 MCP 服务：

curl -fsSL https://raw.githubusercontent.com/PSU3D0/agent-spreadsheet/main/install.sh | sh -s -- --mcp

npm

npm i -g agent-spreadsheet

这会通过预构建的原生二进制文件同时安装 asp（主要命令）和 agent-spreadsheet（兼容别名）。无需安装 Rust 工具链。

cargo-binstall

cargo binstall agent-spreadsheet

几秒钟即可安装预构建 CLI。

Cargo

cargo install agent-spreadsheet --features recalc --bin asp --bin agent-spreadsheet

这会从源代码构建 CLI。默认包含 Formualizer（原生 Rust 重算引擎）。

mise

mise use -g "ubi:PSU3D0/agent-spreadsheet[exe=asp]"

# Homebrew
brew install psu3d0/tap/agent-spreadsheet

MCP 服务

cargo install agent-spreadsheet-mcp

Docker

# Read-only / slim
docker pull ghcr.io/psu3d0/agent-spreadsheet-mcp:latest

# Write + recalc + screenshots
docker pull ghcr.io/psu3d0/agent-spreadsheet-mcp:latest-full

JavaScript SDK

npm i agent-spreadsheet-sdk

预构建二进制文件

从 GitHub Releases 下载原始二进制文件和归档文件。

发布的原生资产包括：

• Linux x86_64
• Linux arm64
• macOS x86_64
• macOS arm64
• 0.16 版不提供 Windows 原生二进制文件；原生发布验证面向 Linux 和 macOS

---

从这里开始：核心工作流

1) 读取单元格前，先了解工作簿

# What sheets are here?
asp read sheets data.xlsx

# What regions/tables/parameter blocks does this sheet contain?
asp read overview data.xlsx "Model"

# What named items are available?
asp read names data.xlsx

# Read a structured region as a table
asp read table data.xlsx --sheet "Model"

2) 精确检查 Agent 所需的内容

# Raw values for exact ranges
asp read values data.xlsx Model A1:C20

# Detail-view for targeted cells (value / formula / cached / style triage)
asp read cells data.xlsx Model B2 D10:F12

# Layout-aware rendering for a bounded range
asp read layout data.xlsx Model --range A1:H30 --render both

# Export a bounded range to csv or grid json
asp read export data.xlsx Model A1:H30 --format csv --output model.csv

3) 执行安全的无状态编辑 → 重算 → 证明 → 差异比较循环

asp workbook copy data.xlsx /tmp/draft.xlsx
asp write cells /tmp/draft.xlsx Inputs "B2=500" "C2==B2*1.1"
asp workbook recalculate /tmp/draft.xlsx
asp verify proof data.xlsx /tmp/draft.xlsx --targets Summary!B2,Summary!B3 --named-ranges
asp verify diff data.xlsx /tmp/draft.xlsx --details --limit 50

一个典型的标签模式查找示例：

asp analyze find-value data.xlsx "Net Income" --mode label --label-direction below

4) 修改工作簿前，预览结构风险

asp analyze ref-impact data.xlsx --ops @structure_ops.json --show-formula-delta

此操作特意设为只读。它会显示偏移范围、绝对引用警告、令牌数量，以及可选的前后公式示例。

5) 使用工作流辅助工具，而不是重新编写行处理逻辑

# Stateless batch writes
asp write batch transform data.xlsx --ops @ops.json --dry-run
asp write batch style data.xlsx --ops @style_ops.json --dry-run

# Append rows into a detected region or table, respecting footer rows when present
asp write append data.xlsx --sheet Revenue --table-name RevenueTable --from-csv rows.csv --header --dry-run

# Clone one template row with preview-first planning
asp write clone-template-row data.xlsx --sheet Inputs --source-row 8 --after 8 --count 3 --dry-run

# Clone a contiguous row band repeatedly
asp write clone-row-band data.xlsx --sheet Forecast --source-rows 12:16 --after 16 --repeat 4 --dry-run

6) 编辑过程变复杂时，使用有状态会话

asp session start --base data.xlsx --workspace .
asp session op --session <id> --ops @edit.json --workspace .
asp session apply --session <id> <staged_id> --workspace .
asp session materialize --session <id> --output result.xlsx --workspace .

需要完整的历史记录和分支时：

asp session log --session <id> --workspace .
asp session fork --session <id> scenario-a --workspace .
asp session undo --session <id> --workspace .
asp session redo --session <id> --workspace .
asp session checkout --session <id> <op_id> --workspace .

7) 使用 SheetPort 将工作簿接口转化为契约

# Discover candidate ports from workbook structure
asp sheetport manifest candidates model.xlsx

# Validate or normalize a manifest
asp sheetport manifest validate manifest.yaml
asp sheetport manifest normalize manifest.yaml

# Bind-check a workbook against a manifest
asp sheetport bind-check model.xlsx manifest.yaml

# Execute the manifest with JSON inputs
asp sheetport run model.xlsx manifest.yaml --inputs @inputs.json

---

CLI 概览

主要 CLI 是 asp。

agent-spreadsheet 仍作为兼容别名提供，因此以下两种写法都有效：

asp read sheets data.xlsx
agent-spreadsheet read sheets data.xlsx

推荐的命令组

• asp read ...
• asp analyze ...
• asp write ...
• asp workbook ...
• asp verify ...
• asp session ...
• asp sheetport ...

旧版别名

在适用情况下，旧版扁平命令仍会被规范化为新的嵌套命令形式。这让旧版提示词、文档和自动化脚本的迁移更加轻松。

CLI 内置可发现性

当 Agent 不确定载荷格式时，可以直接询问工具：

asp operations                  # CLI-supported runtime subset
asp registry --all              # complete host-independent registry + schemas
asp schema read_cells
asp example read_cells
asp schema write batch transform
asp example write batch transform
asp schema session op transform.write_matrix
asp example session op transform.write_matrix

规范机器调用使用与其他界面相同的注册表和分发器。asp schema <canonical-op> 和 asp example <canonical-op> 会展示原生适配器契约：resource_id 以及用于验证的 baseline_resource_id 不会列为必需 JSON 字段，因为 --bind 和 --baseline 会注入临时资源。与主机无关的 asp registry --all 保持不变。

asp op read_cells --bind data.xlsx --json '{"sheet_name":"Sheet1","selection":{"kind":"range","ranges":["A1:C10"]}}'
asp op verify_workbook --baseline base.xlsx --bind current.xlsx --json '{}'
echo '{"action":"schema"}' | asp op sheetport_manifest

--bind 读取当前工作簿，而 --baseline 仅为 verify_workbook 提供第二个工作簿。规范可变 CLI 调用必须且只能指定一个持久化目标：--output <path> 写入新文件，或 --in-place 原子替换绑定的文件；纯预览不会持久化任何内容，也不能使用这两个选项。无状态 CLI 可发现性中有意不包含持久化的分叉、检查点、暂存和历史记录操作。这是一个核心设计原则：界面应当向 Agent 自我说明。

---

命令系列

read — 提取与检查

命令	用途
asp read sheets <file>	列出工作表及其摘要元数据
asp read overview <file> <sheet>	检测区域、表头和方向
asp read values <file> <sheet> <range> [range...]	提取精确 A1 区域的原始值
asp read export <file> <sheet> <range>	将有界区域导出为 csv 或 grid json
asp read cells <file> <sheet> <target> [target...]	检查精确单元格／区域的值／公式／缓存／样式快照
asp read page <file> <sheet> ...	按确定性方式分页读取工作表，并提供 next_start_row
asp read table <file> ...	以确定性方式结构化读取表格／区域，并提供 next_offset
asp read names <file>	命名区域、命名公式和表格项目
asp read workbook <file>	工作簿级元数据
asp read layout <file> <sheet>	感知布局的渲染，包含列宽、合并单元格、边框和可选的 ascii 输出

这些功能对 Agent 为何重要

Agent 很少需要“整个电子表格”。它们需要：

• 正确的区域
• 正确的页面
• 正确的单元格
• 足够理解意图的布局信息

因此，读取界面结合了区域检测、结构化读取、详细检查和显式续读。

---

analyze — 搜索、诊断与影响分析

命令	用途
asp analyze find-value <file> <query>	按值或标签语义搜索
asp analyze find-formula <file> <query>	在公式中搜索文本
asp analyze formula-map <file> <sheet>	按复杂度／频率汇总公式
asp analyze formula-trace <file> <sheet> <cell> <precedents|dependents>	追踪依赖关系，并支持续读
asp analyze scan-volatiles <file>	查找易变公式
asp analyze sheet-statistics <file> <sheet>	密度和类型统计
asp analyze table-profile <file>	表头／类型／基数分析
asp analyze ref-impact <file> --ops @structure_ops.json	在不进行更改的情况下，预检结构编辑的影响

这为何重要

无头电子表格自动化的优势在于能够说明后果，而不只是执行更改。ref-impact、formula-trace 和分组诊断都是其中的一部分。

---

write — 安全修改与工作流辅助工具

命令	用途
asp write cells <file> <sheet> ...	直接快捷编辑单元格
asp write import <file> <sheet> ...	将网格 JSON 或 CSV 导入工作簿区域
asp write append ...	在区域或表格中追加行，并识别页脚
asp write clone-template-row ...	先预览规划，再克隆一行模板
asp write clone-row-band ...	重复克隆多行模板区域
asp write formulas replace ...	在工作表或区域中仅查找并替换公式
`asp write name define	update
asp write batch transform ...	无状态转换管道
asp write batch style ...	无状态样式编辑
asp write batch formula-pattern ...	类似自动填充的公式应用
asp write batch structure ...	行／列／工作表／复制／移动等结构修改
asp write batch column-size ...	列宽操作
asp write batch sheet-layout ...	冻结窗格、缩放、页面设置、打印区域
asp write batch rules ...	数据验证与条件格式

安全模型

大多数修改命令都支持严格的模式选项：

• --dry-run
• --in-place
• --output <PATH>

这对 Agent 很重要，因为它支持：

• 预演规划
• 非破坏性执行
• 明确控制覆盖行为

公式维护

公式修改现已成为一项一等功能：

asp write formulas replace data.xlsx Sheet1 --find '$64' --replace '$65' --dry-run
asp write formulas replace data.xlsx Sheet1 --find 'Sheet1!' --replace 'Sheet2!' --range A1:Z100 --output fixed.xlsx

命名区域维护

asp write name define data.xlsx RevenueInput 'Inputs!$B$2'
asp write name update data.xlsx RevenueInput 'Inputs!$B$2:$B$4' --in-place
asp write name delete data.xlsx RevenueInput --in-place

---

workbook — 文件级工作流

命令	用途
asp workbook create <path>	创建新工作簿
asp workbook copy <source> <dest>	用于编辑工作流的安全复制
asp workbook recalculate <file>	通过配置的后端重新计算公式

---

verify — 验证事实，而非凭感觉

命令	用途
asp verify proof <baseline> <current>	验证目标差异，并区分新增、已解决和既有错误
asp verify diff <original> <modified>	以摘要优先的方式对工作簿差异分组，并可选提供分页详情

验证为何重要

大多数电子表格自动化工具到“编辑已应用”就止步了。

agent-spreadsheet 更进一步：

• 目标单元格是否按预期发生了变化？
• 工作簿是否引入了新错误？
• 哪些变化是直接编辑导致的，哪些是重新计算带来的连带变化？
• 总体上发生了哪些变化？这些变化是否经过分组，便于 Agent 理解？

这一验证层是本项目成为可靠 Agent 基础设施而非实用脚本的重要原因。

---

session — 基于事件溯源的有状态编辑

session 功能适用于复杂到无法通过单次无状态写入完成的工作流。

会话能提供什么

• 持久化编辑状态
• 暂存的试运行操作
• 比较并交换式应用语义
• 日志与可重放性
• 分支／切换／分叉工作流
• 撤销／重做／检出
• 明确将更改物化回工作簿文件

规范流程

asp session start --base model.xlsx --workspace .
asp session op --session <id> --ops @ops.json --workspace .
asp session apply --session <id> <staged_id> --workspace .
asp session materialize --session <id> --output result.xlsx --workspace .

历史记录与分支

asp session log --session <id> --workspace .
asp session branches --session <id> --workspace .
asp session fork --session <id> experiment-b --workspace .
asp session switch --session <id> experiment-b --workspace .
asp session undo --session <id> --workspace .
asp session redo --session <id> --workspace .
asp session checkout --session <id> <op_id> --workspace .

如果你需要可重复性、可审计性和多步骤安全保障，请使用会话。

---

sheetport — 将电子表格接口转化为可执行契约

SheetPort 是一种工作流接口，可将工作簿的输入／输出转化为明确的机器契约。

清单生命周期

asp sheetport manifest candidates model.xlsx
asp sheetport manifest schema
asp sheetport manifest validate manifest.yaml
asp sheetport manifest normalize manifest.yaml

绑定检查与运行

asp sheetport bind-check model.xlsx manifest.yaml
asp sheetport run model.xlsx manifest.yaml --inputs @inputs.json --freeze-volatile

如果你希望工作簿不再像一个不透明的文件，而更像一个已声明的服务接口，请使用此功能。

---

面向 Agent 的输出契约

规范与紧凑形状

所有命令默认使用 JSON。许多命令还支持：

--shape canonical
--shape compact

策略：

• 规范会保留完整且稳定的架构
• 紧凑会在契约允许的情况下移除包装层噪声，同时保留续接字段和命令特定语义

形状策略：

• **规范（默认）：**保留完整的响应架构。
• **range-values：**在规范和紧凑模式下都返回稳定的 values: [...] 封装。
• **range-values 默认编码：**使用密集 JSON（dense.encoding = "dense_v1"），包含 dictionary 和游程编码的 row_runs。
• **range-values --include-formulas：**在密集模式下包含稀疏公式坐标（dense.formulas），或在显式 json 格式下包含矩阵。
• read-table 和 sheet-page：紧凑模式会保留当前分支和续接字段（next_offset、next_start_row）。
• **formula-trace 紧凑模式：**省略每层的 highlights，同时保留 layers 和 next_cursor。

确定性分页循环

# sheet-page continuation
asp read page data.xlsx Sheet1 --format compact --page-size 200
asp read page data.xlsx Sheet1 --format compact --page-size 200 --start-row 201

# read-table continuation
asp read table data.xlsx --sheet "Sheet1" --table-format values --limit 200 --offset 0
asp read table data.xlsx --sheet "Sheet1" --table-format values --limit 200 --offset 200

sheet-page 机器契约

• 读取载荷字段前，先检查顶层 format。
• format=full：读取顶层 rows，以及可选的 header_row 和 next_start_row。
• format=compact：读取 compact.headers、compact.header_row、compact.rows，以及可选的 next_start_row。
• format=values_only：读取 values_only.rows，以及可选的 next_start_row。
• 如果存在顶层 next_start_row，则始终根据它继续分页。
• 全局 --shape compact 会保留当前的 sheet-page 分支；不会扁平化 sheet-page 载荷。

机器续接示例：

1. 请求第 1 页，不使用 --start-row。
2. 如果存在 next_start_row，则使用 --start-row <next_start_row> 再次调用 sheet-page。
3. 当省略 next_start_row 时停止。

自描述载荷

当 Agent 不确定要发送什么时，请求架构或示例：

asp schema write batch rules
asp example write batch rules
asp schema session op structure.insert_rows
asp example session op structure.insert_rows

批量载荷示例

所有批量载荷都使用顶层封装对象。大多数命令要求使用 {"ops":[...]}；column-size-batch 优先使用 {"sheet_name":"...","ops":[...]}，也接受在 {"ops":[...]} 中为每个操作单独指定 sheet_name。

transform-batch 载荷（@transform_ops.json）

• 最简：{"ops":[{"kind":"fill_range","sheet_name":"Sheet1","target":{"kind":"range","range":"B2:B4"},"value":"0"}]}
• 高级：{"ops":[{"kind":"replace_in_range","sheet_name":"Sheet1","target":{"kind":"region","region_id":1},"find":"N/A","replace":"","match_mode":"contains","case_sensitive":false,"include_formulas":true}]}

style-batch 载荷（@style_ops.json）

• 最简：{"ops":[{"sheet_name":"Sheet1","target":{"kind":"range","range":"B2:B2"},"patch":{"font":{"bold":true}}}]}
• 高级：{"ops":[{"sheet_name":"Sheet1","target":{"kind":"cells","cells":["B2","B3"]},"patch":{"number_format":"$#,##0.00","alignment":{"horizontal":"right"}},"op_mode":"merge"}]}

write batch 公式模式载荷（@formula_ops.json）

• 最简：{"ops":[{"sheet_name":"Sheet1","target_range":"C2:C4","anchor_cell":"C2","base_formula":"B2*2"}]}
• 高级：{"ops":[{"sheet_name":"Sheet1","target_range":"C2:E4","anchor_cell":"C2","base_formula":"B2*2","fill_direction":"both","relative_mode":"excel"}]}
• relative_mode 的有效值：excel、abs_cols、abs_rows

structure-batch 载荷（@structure_ops.json）

• 最简：{"ops":[{"kind":"rename_sheet","old_name":"Summary","new_name":"Dashboard"}]}
• 高级：{"ops":[{"kind":"copy_range","sheet_name":"Sheet1","dest_sheet_name":"Summary","src_range":"A1:C4","dest_anchor":"A1","include_styles":true,"include_formulas":true}]}

column-size-batch 负载（@column_size_ops.json）

• 最简（首选）：{"sheet_name":"Sheet1","ops":[{"range":"A:A","size":{"kind":"width","width_chars":12.0}}]}
• 高级（首选）：{"sheet_name":"Sheet1","ops":[{"target":{"kind":"columns","range":"A:C"},"size":{"kind":"auto","min_width_chars":8.0,"max_width_chars":24.0}}]}
• 也接受（统一格式）：{"ops":[{"sheet_name":"Sheet1","range":"A:A","size":{"kind":"width","width_chars":12.0}}]}

sheet-layout-batch 负载（@layout_ops.json）

• 最简：{"ops":[{"kind":"freeze_panes","sheet_name":"Sheet1","freeze_rows":1,"freeze_cols":1}]}
• 高级：{"ops":[{"kind":"set_page_setup","sheet_name":"Sheet1","orientation":"landscape","fit_to_width":1,"fit_to_height":1}]}

rules-batch 负载（@rules_ops.json）

• 最简：{"ops":[{"kind":"set_data_validation","sheet_name":"Sheet1","target_range":"B2:B4","validation":{"kind":"list","formula1":"\"A,B,C\""}}]}
• 高级：{"ops":[{"kind":"set_conditional_format","sheet_name":"Sheet1","target_range":"C2:C10","rule":{"kind":"expression","formula":"C2>100"},"style":{"fill_color":"#FFF2CC","bold":true}}]}

write batch formula-pattern 会清除受影响公式单元格的缓存结果；运行 workbook recalculate 以刷新计算值。

公式解析策略

支持公式的命令支持：

--formula-parse-policy fail|warn|off

• fail — 中止
• warn — 继续并附加分组诊断信息
• off — 静默跳过

这样，Agent 可以根据工作流，在严格性与推进进度之间做出选择。

CLI 参考摘录

• read values <file> <sheet> <range> [range...] [--format dense\|json\|values\|csv] [--include-formulas]
• read cells <file> <sheet> <target> [target...] [--include-empty]
• read page <file> <sheet> --format <full|compact|values_only> [--start-row ROW] [--page-size N]
• workbook create <path> [--sheets Inputs,Calc,...] [--overwrite]
• analyze find-value <file> <query> [--sheet S] [--mode value\|label] [--label-direction right\|below\|any]
• write batch transform <file> --ops @ops.json (--dry-run\|--in-place\|--output PATH)

公式写入路径来源信息（write_path_provenance）

公式写入命令会输出可选的来源元数据，便于排查问题：

• written_via：写入路径（edit、transform_batch、apply_formula_pattern）
• formula_targets：公式写入影响的工作表/单元格或工作表/范围目标

调试对比工作流：

1. 通过两条路径应用相同的公式目标。
2. 对比响应中的 write_path_provenance.written_via 和 formula_targets。
3. 使用 inspect-cells 和 recalculate 对比结果行为。

财务演示的初始默认设置

• 显式设置标签列（通常为 A 列）的宽度（约 24–36 个字符），以防内容被截断。
• 按语义类型应用一致的数字格式：
  • 货币："$"#,##0.00_);[Red]("$"#,##0.00)
  • 百分比：0.0%
  • 整数/计数：#,##0
• 标题布局稳定后，应用 sheet-layout-batch 冻结窗格。

JSON 输出默认采用紧凑格式；使用 --quiet 可抑制警告。 当前不支持全局 --output-format csv；请使用命令专属的 CSV 选项，例如 read table --table-format csv。

---

MCP 服务快速入门

MCP 接口是 agent-spreadsheet 的有状态服务版本。

适用于以下场景：

• 在多次调用之间缓存工作簿
• 使用分支生命周期，而非无状态地替换文件
• 多轮 Agent 工作流
• 截图和更丰富的服务端编排

Claude Code / Claude Desktop

添加到 ~/.claude.json 或项目的 .mcp.json：

{
  "mcpServers": {
    "spreadsheet": {
      "command": "agent-spreadsheet-mcp",
      "args": ["--workspace-root", "/path/to/workbooks", "--transport", "stdio"]
    }
  }
}

Docker

{
  "mcpServers": {
    "spreadsheet": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/workbooks:/data",
        "ghcr.io/psu3d0/agent-spreadsheet-mcp:latest-full",
        "--transport", "stdio"
      ]
    }
  }
}

:latest 是只读精简镜像（已禁用写入/分支/重新计算工具）；:latest-full 包含写入工具和重新计算功能（基于 LibreOffice）。

HTTP 模式

agent-spreadsheet-mcp --workspace-root /path/to/workbooks
# -> http://127.0.0.1:8079  (POST /mcp, and the canonical route under /v1)

同一进程还会提供一个纯规范 HTTP 路由，供不支持 MCP 的程序化客户端使用：

路由	用途
POST /v1/op/{operation}	运行规范操作；请求体为规范输入对象，响应为规范信封
GET /v1/operations	此进程经过运行时筛选的操作发现结果
GET /v1/registry	完整的规范注册表投影及错误架构
GET /v1/artifacts/{handle}	获取由 screenshot_sheet 生成的 artifact:sha256:<hex> 句柄对应的字节

curl -sS -X POST http://127.0.0.1:8079/v1/op/list_workbooks -d '{}'

规范错误会返回规范错误信封，状态码根据错误代码映射而来（400 表示请求无效，404 表示操作／资源未知，409 表示修订冲突，500 表示操作失败，501 表示功能不可用）。与 /mcp 一样，/v1 不提供身份验证；默认绑定到环回地址是安全边界。请参阅 docs/architecture/canonical-http-route.md。

配置

每项设置都可通过 CLI 标志（agent-spreadsheet-mcp --help）、环境变量或配置文件键（--config file.yaml）指定。CLI 优先于配置文件。

变量	默认值	描述
SPREADSHEET_MCP_WORKSPACE	.	包含电子表格文件的工作区根目录
SPREADSHEET_MCP_WORKBOOK	无	将服务锁定到单个工作簿路径
SPREADSHEET_MCP_EXTENSIONS	xlsx,xlsm,xls,xlsb	允许的工作簿扩展名列表，以逗号分隔
SPREADSHEET_MCP_ENABLED_TOOLS	所有工具	将执行范围限制为指定的工具名称（以逗号分隔）
SPREADSHEET_MCP_TRANSPORT	http	要启用的传输方式（http 或 stdio）
SPREADSHEET_MCP_HTTP_BIND	127.0.0.1:8079	使用 http 传输方式时的 HTTP 绑定地址
SPREADSHEET_MCP_RECALC_ENABLED	false	启用写入／重新计算工具（默认使用原生 Formualizer 后端）
SPREADSHEET_MCP_RECALC_BACKEND	auto	重新计算后端首选项：auto、formualizer 或 libreoffice
SPREADSHEET_MCP_MAX_CONCURRENT_RECALCS	2	LibreOffice 实例的最大并发数
SPREADSHEET_MCP_VBA_ENABLED	false	启用 VBA 内省工具（只读）
SPREADSHEET_MCP_ALLOW_OVERWRITE	false	允许 save_fork 覆盖原始工作簿文件
SPREADSHEET_MCP_CACHE_CAPACITY	5	内存中保留的工作簿最大数量
SPREADSHEET_MCP_TOOL_TIMEOUT_MS	30000	工具请求超时时间，单位为毫秒
SPREADSHEET_MCP_MAX_RESPONSE_BYTES	1000000	最大响应大小，单位为字节
SPREADSHEET_MCP_MAX_PAYLOAD_BYTES	65536	截断前工具载荷的最大字节数
SPREADSHEET_MCP_MAX_CELLS	10000	截断前每个工具载荷的最大单元格数
SPREADSHEET_MCP_MAX_ITEMS	500	截断前每个工具载荷的最大项目数
SPREADSHEET_MCP_OUTPUT_PROFILE	token_dense	工具响应的输出配置（token_dense 或 verbose）
SPREADSHEET_MCP_SLIM_SURFACE	true	仅使用规范路由器；设为 false 可添加旧版 0.13 工具名称
SPREADSHEET_MCP_SCREENSHOT_DIR	<workspace_root>/screenshots	写入截图 PNG 文件的目录
SPREADSHEET_MCP_PATH_MAP	无	路径映射 INTERNAL=CLIENT，用于在响应中包含客户端可见路径（以逗号分隔；适用于 Docker 卷挂载）

将任何超时／限制变量（TOOL_TIMEOUT_MS、MAX_RESPONSE_BYTES、MAX_PAYLOAD_BYTES、MAX_CELLS、MAX_ITEMS）设为 0，即可禁用相应限制。

---

MCP 工具接口

默认 MCP 路由器根据规范操作注册表生成。具备写入能力的基线提供 27 项操作：17 项发现／读取／分析操作和 10 项写入／生命周期操作。具备相应能力的部署可添加 screenshot_sheet、sheetport_manifest、execute_sheetport 和 inspect_vba，最多提供 31 项操作。19 项规范操作为只读。

每项工具都使用注册表描述符定义的封闭输入架构，并返回规范的 schema_version / operation / resource_id / revision_id / data 信封。revision_id 标识资源完整的可观察状态，而不仅仅是工作簿单元格内容的字节；重新计算、求值／来源状态或生命周期元数据都可能在未编辑内容的情况下使其递增。客户端必须使用最新响应信封中的版本进行比较并交换、游标和新鲜度判断，而不能自行计算或保留内容哈希。静态 MCP 注解会报告描述符的最坏情况风险；描述则会指出具体操作的风险。close_workbook 不在其中，因为缓存淘汰属于运行时管理。

完整的操作列表和契约，请参阅规范操作接口。若要在一个兼容窗口内添加旧版 0.13 名称，请设置 SPREADSHEET_MCP_SLIM_SURFACE=false；在兼容模式下，共享名称使用旧版架构和信封，且只注册一次。

JS SDK

agent-spreadsheet-sdk 是面向应用的集成层，也是 JS/TS 代码应使用的唯一接口。

它提供生成的规范便捷方法、旧版输入别名、保持不变的规范信封，以及类型化的能力错误。完整的 31 项操作清单提供架构和方法，而可用性始终取决于所选的实时后端。

后端是配置选项，并非独立 API：

• MCP 后端 — 连接到正在运行的 agent-spreadsheet-mcp 服务（共享状态、分叉、多客户端）
• 嵌入式 WASM 后端 — 引擎在进程内直接处理工作簿字节，无需服务或文件系统（浏览器、Node、无服务器环境）。此仓库中的 agent-spreadsheet-wasm crate 是该后端的构建产物；它是 SDK 的内部依赖，而非供你直接使用的包。

安装：

npm i agent-spreadsheet-sdk

后端状态：MCP 后端已稳定，可通过实时工具发现（或显式的 supportedOperations 列表）协商操作；嵌入式 WASM 后端根据其生成绑定的 operations() 描述符确定支持情况，并在 CI 中针对真实的 wasm-bindgen Node 包进行测试。

---

重新计算后端

公式重新计算采用可插拔设计。

后端	方式	默认	适用场景
Formualizer	原生 Rust 引擎	是	快速的默认重新计算，无需外部依赖
LibreOffice	无头 soffice	Docker :latest-full / 显式构建	最大兼容性和截图工作流

功能说明：

• 默认启用 recalc-formualizer
• recalc-libreoffice 可用于基于 LibreOffice 的构建
• 即使没有重新计算功能，读取和许多写入流程仍可正常工作；只有重新计算操作本身需要后端

---

Docker 镜像

发布于 ghcr.io/psu3d0/agent-spreadsheet-mcp：

镜像	大小	重新计算	适用场景
latest	~15 MB	否	只读分析和轻量级 Agent 部署
latest-full	~800 MB	是	写入 + 重新计算 + 截图

示例：

# Read-only
docker run -v /path/to/workbooks:/data -p 8079:8079 ghcr.io/psu3d0/agent-spreadsheet-mcp:latest

# Write + recalc
docker run -v /path/to/workbooks:/data -p 8079:8079 ghcr.io/psu3d0/agent-spreadsheet-mcp:latest-full

---

工作区布局

agent-spreadsheet/
├── crates/
│   ├── agent-spreadsheet/        # shared engine + asp / agent-spreadsheet CLI
│   ├── agent-spreadsheet-mcp/        # MCP server adapter
│   └── agent-spreadsheet-wasm/   # experimental WASM-facing wrapper
├── npm/
│   ├── agent-spreadsheet/      # npm CLI wrapper
│   └── agent-spreadsheet-sdk/    # JS SDK
├── docs/                       # architecture and design docs
├── benchmarks/                 # scenario budget regression harnesses
└── .github/workflows/          # CI, release, docker builds

软件包职责

软件包	职责
agent-spreadsheet	共享引擎和 CLI 二进制文件
agent-spreadsheet-mcp	有状态 MCP 传输层和服务接口
agent-spreadsheet-wasm	面向 WASM 的字节／会话封装
agent-spreadsheet	CLI 二进制文件的 npm 封装
agent-spreadsheet-sdk	用于 MCP/WASM 风格集成的 JS SDK

---

架构说明

核心理念：

• 一个语义核心，供 CLI、MCP、会话和面向 WASM 的工作共享
• 区域检测，实现结构感知
• 高效利用 Token 的默认设置，避免 Agent 过度读取电子表格
• 将验证作为一等功能，而非事后补充
• 工作流辅助工具，用于处理电子表格 Agent 反复难以应对的常见修改

高效利用 Token 的工作流参考：

建议步骤：

1. 发现工作簿和工作表
2. 检测区域／类似表格的结构
3. 仅检查所需的确切区域或单元格
4. 使用 dry-run 或会话暂存来修改
5. 按需重新计算
6. 验证证明并审查分组差异

---

开发

# Build everything
cargo build --release

# Run formatting, lint, and tests
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

本地迭代 MCP：

WORKSPACE_ROOT=/path/to/workbooks ./scripts/local-docker-mcp.sh

或者让 MCP 客户端直接指向本地二进制文件：

{
  "mcpServers": {
    "spreadsheet": {
      "command": "./target/release/agent-spreadsheet-mcp",
      "args": ["--workspace-root", "/path/to/workbooks", "--transport", "stdio"]
    }
  }
}

---

延伸阅读

• CLI 包 README：npm/agent-spreadsheet
• 核心 crate README：crates/agent-spreadsheet
• MCP crate README：crates/agent-spreadsheet-mcp
• JS SDK README：npm/agent-spreadsheet-sdk
• WASM 封装 README：crates/agent-spreadsheet-wasm
• 打包／版本管理说明：docs/PACKAGING.md
• 启发式方法和区域检测：docs/HEURISTICS.md
• 重新计算架构：docs/RECALC.md

---

许可证

Apache-2.0