xlsx-for-ai

xlsx-for-ai

简称：xfa——一个真正的 CLI 命令（xfa <file>、xfa samples、xfa --version），也是提示词中的简写（例如“使用 xfa 读取此文件”）。它与 xlsx-for-ai 使用相同的入口点；名称与内部的 xfa_* / XFA_* 品牌一致。

值经验证，结构得以保留，支持最大 100MB 的文件

为大模型 Agent 处理电子表格提供关键的可靠性保障。端到端读取、写入、比较、验证和分析 .xlsx 文件，同时保留合并单元格、公式、命名区域、条件格式、数据透视表和图表。

xlsx-for-ai 让 Claude 能可靠处理真实场景中的 Excel 文件。四十多种工具覆盖了 pandas 风格沙箱容易忽略的结构：合并单元格、命名区域、含结果的公式、条件格式、数据透视表、切片器、图表、批注、数据验证、超链接、跨工作表拓扑结构、外部链接、窗体控件、VBA 宏、文档属性和保护设置。完整性检查（xlsx_validate）会标记其他读取器默默掩盖的损坏。托管的重新计算引擎会在内部计算提供的值——服务流程中不使用第三方公式引擎。

在 Claude Code 中，只需一条命令：

claude plugin install xlsx-for-ai --marketplace senoff/xlsx-for-ai

然后运行 /reload-plugins（或重启 Claude Code），打开 /mcp，选择 plugin:xlsx-for-ai:spreadsheets 并登录一次。需要 Claude Code 2.1.292 或更高版本（如果版本较旧，请运行 claude update）。有关该插件的更多信息，请参阅下方的 Claude Code plugin。

**在 Claude 应用（claude.ai）中：**在连接器目录 claude.ai/directory 中找到 xlsx-for-ai，然后点击 Connect。

npm 包（适用于 Claude Code、Cursor、Claude Desktop 等）：

npm install -g xlsx-for-ai

全局安装会将 xlsx-for-ai-mcp 二进制文件放到 PATH 中——下方的标准配置会指向它。固定版本的全局安装启动很快（仍需联网，因为文件由托管服务读取）；有新版本发布时，可运行 npm install -g xlsx-for-ai@latest 升级。

从 1.5.x 升级？ 这是一次架构重构，而不只是功能更新：npm 包中不再包含繁重的本地引擎。所有渲染都在服务端完成。cursor-reads-xlsx 别名仍可使用。请参阅下方的 Migration。

---

MCP 配置

在 Agent 运行时中将服务添加为 xfa（这样“使用 xfa 读取此文件”就能正确解析）。首次运行需要登录一次。在编辑器或桌面应用中，首次请求会返回登录链接和短代码：打开链接并批准，然后再次提出请求。也可以先在终端运行 xlsx-for-ai login（请参阅首次登录）。旧版本创建的密钥目前仍可使用。之后即使这一点发生变化，登录链接也会出现在相同的位置，因此无需提前做任何操作。

Claude Code

全局安装会自动在 ~/.claude.json 中注册 xfa MCP 服务——无需额外操作：

npm install -g xlsx-for-ai

如果环境跳过安装脚本（--ignore-scripts、CI 或使用 sudo 安装），请手动注册：

claude mcp add xfa -- xlsx-for-ai-mcp

验证：在新的 Claude Code 会话中询问“你有哪些 MCP 工具？”——应该会显示 52 个 xlsx_* 工具，其中包括 xlsx_doctor（一次调用即可生成健康报告——遇到未知工作簿时，建议先试用它）。

然后运行 xfa samples（xlsx-for-ai samples 的简写），在当前工作目录中生成两个演示工作簿，并提供可直接粘贴的提示词供你尝试。

Claude Desktop

Claude Desktop 可以读取文件，但无法重新计算公式、精确读取超大型工作簿，也无法返回真正的 .xlsx 文件。xfa 服务可提供这些功能。安装过程不会修改 Claude Desktop，因此需要手动添加该服务。先安装软件包（npm install -g xlsx-for-ai），然后打开配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

（在 Claude Desktop 中，Settings → Developer → Edit Config 会打开该文件。）在 mcpServers 下添加 xfa，并保留已有的服务：

{
  "mcpServers": {
    "xfa": {
      "command": "xlsx-for-ai-mcp"
    }
  }
}

完全退出并重新打开 Claude Desktop。验证：询问“你有哪些 MCP 工具？”，确认 xfa 显示了 52 个 xlsx_* 工具。首次请求会返回登录链接和一组简短代码：打开链接并授权，然后再次提问。

Cursor

配置文件：~/.cursor/mcp.json

{
  "mcpServers": {
    "xfa": {
      "command": "xlsx-for-ai-mcp"
    }
  }
}

验证：打开 Cursor 设置 → MCP → 确认 xfa 显示了 52 个 xlsx_* 工具。

Continue

配置文件：~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "xfa",
      "command": "xlsx-for-ai-mcp"
    }
  ]
}

验证：重启 VS Code，打开 Continue 面板，并检查 MCP 服务列表。

Codex CLI

在命令行中传入 --mcp-server，或将其添加到 Codex 配置中：

{
  "mcpServers": {
    "xfa": {
      "command": "xlsx-for-ai-mcp"
    }
  }
}

验证：运行 codex --list-tools，确认列出了 52 个 xlsx_* 工具。

Zed

配置文件：~/.config/zed/settings.json

{
  "context_servers": {
    "xfa": {
      "command": {
        "path": "xlsx-for-ai-mcp"
      }
    }
  }
}

验证：打开 Zed 的助手面板，xlsx 工具应会显示在工具选择器中。

Windsurf

配置文件：~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "xfa": {
      "command": "xlsx-for-ai-mcp"
    }
  }
}

验证：打开 Windsurf → Cascade → 设置，确认 xfa 已列为活动 MCP 服务。

自定义 Agent / API

对于自定义 MCP 客户端，可执行文件为 xlsx-for-ai-mcp（stdio 传输）。在本地开发时，可通过 XLSX_FOR_AI_API 环境变量将 API 基础 URL 覆盖为 http://localhost:3000。

使用原始 HTTP API

MCP 客户端是最简单的方式，但每个工具也都是可从任何语言调用的普通 HTTP 端点，无需 SDK。通过 https://api.xlsx-for-ai.dev/oauth 上的 OAuth 设备流程（RFC 8628）登录（使用 resource=https://api.xlsx-for-ai.dev/mcp，端点为 /oauth/reg、/oauth/device/auth、/oauth/token），然后向 https://api.xlsx-for-ai.dev/api/v1/clients 发送带有 Authorization: Bearer <access token> 的 POST 请求，即可获得 { client_id, api_key }。调用任何工具时，使用 Authorization: Bearer <api_key>。过渡期间，早期版本发放的匿名密钥仍然有效。有关限制，请参阅费用说明。

# Legacy keyless registration (still accepted during the transition; new integrations
# should use the device-flow sign-in above), then convert report.xlsx to Markdown.
# Needs jq, and bash or zsh. The base64 body is passed to curl through a
# process-substitution fd and the token through a --config heredoc on stdin, which
# keeps both out of the argument list. -fsS --max-time makes curl fail loudly on an
# HTTP error or a hang; the guard line stops on a failed key issuance.
KEY=$(curl -fsS --max-time 30 -XPOST https://api.xlsx-for-ai.dev/api/v1/clients \
  -H 'Content-Type: application/json' \
  -d '{"client_version":"2.0.0","platform":"cli"}' | jq -r .api_key)
[ -n "$KEY" ] && [ "$KEY" != null ] || { echo "key issuance failed"; exit 1; }

curl -fsS --max-time 120 -XPOST https://api.xlsx-for-ai.dev/api/v1/tools/xlsx_convert \
  --data-binary @<(base64 < report.xlsx | tr -d '\n' | jq -Rs '{file_b64: ., to: "md"}') \
  -H 'Content-Type: application/json' \
  --config - <<CFG
header = "Authorization: Bearer $KEY"
CFG

文件过大或请求超出限制时，会返回带有 upgrade 字段的类型化 JSON 错误，其中会提供适用的方案（见下文）。

请求受到速率限制、超出限制或文件过大时，会返回带有 upgrade 字段（列出可选方案）的类型化 JSON 错误（{ "error": { "code", "message" } }）——完整约定请参阅 GET /api/v1/reference。

所有错误响应体的形状都完全一致：error.code 是稳定、可供机器读取的分支判断键；error.message 则是便于纠正问题的详细说明，会指出问题所在及应如何更改。部分代码会附带有文档说明的额外字段（例如，找不到工作表时的拒绝响应中会有 available_sheets，付费墙拒绝响应中会有 upgrade），但线上不会提供更细分的错误子类型字段；服务端只会在内部审计中保留更细致的归因信息。

转换操作可能会返回类型化的 501 错误。 xlsx_convert 仅使用服务端自有引擎转换 xlsx、xls、csv 和 json 输入。当该引擎拒绝转换这些输入之一时（例如，某些 to=csv 转换涉及 .xlsx 文件，其单元格使用了显示格式，或包含引擎无法精确复现且未缓存的公式；同一文件通常仍可通过 to=xlsx 或 to=json 转换），API 会返回 HTTP 501，其中 error.code 为 capability_gap，消息格式类似于“xlsx_convert isn't yet supported by our own engine for .xlsx files, and we don't fall back to a full-workbook recompute on this file type ...”。它不会悄悄回退到兼容性库。这不是客户端错误，也不是暂时性错误，因此重试同一个文件没有帮助。通过托管 MCP 连接器调用时，同样的拒绝会以 isError: true 的工具结果形式返回，并附带该消息。特殊格式（ods、xlsb、fods，以及作为写入目标的 xls/BIFF8）仍通过旧路径提供服务，不受影响。

同一套受控约定也通过两个只读路由提供——无需密钥即可了解整个 API：

• GET /api/v1/reference — 面向用户的完整 HTML 参考文档，涵盖全部 52 个公开稳定工具，包括上述入门指南。
• GET /api/v1/openapi.json — 版本化的 OpenAPI 3.1 约定，原样提供。可将代码生成工具、Postman 或 Scalar/Redoc 指向该地址。

Claude Code 插件

Claude Code 插件可将你的 Agent 连接到托管的 xlsx-for-ai 工具，用于处理电子表格文件和链接（.xlsx、.xlsm、.xls、.csv、.tsv、Google Sheet），并告知它们何时能派上用场：当答案取决于公式结果、已保存的值是否为最新，或需要交付可用的电子表格文件时。

claude plugin install xlsx-for-ai --marketplace senoff/xlsx-for-ai

这条命令会添加市场并安装插件。它需要 Claude Code 2.1.292 或更高版本；如果你的版本较旧，请先运行 claude update。

之后只需操作一次：运行 /reload-plugins（或启动 Claude Code），运行 /mcp，选择 plugin:xlsx-for-ai:spreadsheets 服务，然后在浏览器中登录。该插件连接到托管端点 https://api.xlsx-for-ai.dev/mcp（OAuth 登录），并请求完整的工具列表。

0.1.1 版本将插件 .mcp.json 中的服务键从 xlsx-for-ai 重命名为 spreadsheets，因此 /mcp 现在显示 plugin:xlsx-for-ai:spreadsheets，而不是 plugin:xlsx-for-ai:xlsx-for-ai。Claude Code 会从插件自己的 .mcp.json 读取该键，其他地方都不会读取。如果你使用的是 0.1.0，更新后请登录一次，因为服务名称已更改。

它的功能：

• 在会话开始时（启动、恢复、清除和压缩）输出一段简短文本，说明 xlsx-for-ai 工具何时有用、原因、如何从 Claude Code 移交文件，以及每个工具的名称。
• 将 Shopify 导出文件（产品、库存、系列、重定向、元字段）发送给 shopify_* 工具，生成可导入 Shopify 的文件（以及 Google、Amazon、eBay 和 UPS 信息源文件）。这些工具会处理你提供的文件并返回文件；你需要自行导入结果。
• 添加一个在涉及电子表格文件时适用的 spreadsheets 技能。
• 将 Claude Code 连接到托管服务。

它不会做什么：它不附带引擎。我们的计算、解析或转换代码都不会在你的机器上运行；唯一在本地运行的是用于输出会话开始文本文件的 cat。你提供给工具的文件会发送到托管服务（通过链接或一次性上传）。插件位于 claude-code-plugin/；会话开始文本由 scripts/plugin/generate-session-start.js 根据 claude-code-plugin/tool-manifest.json 生成，并通过测试确保两者一致。在 Windows 上，该钩子可在 Git Bash 或 PowerShell 中使用（两者都提供 cat）。

---

它的功能

tools/list 中注册了 52 个工具。工具描述有意写得详尽，让阅读对话记录的 Agent 无需额外文档，就能了解每个工具的用途以及何时使用。

分类 / 概览

工具	功能
xlsx_doctor	一次调用即可生成工作簿健康报告。 HIGH/MEDIUM/LOW 级别的问题（宏、外部链接、隐藏工作表、缺少元数据、大型图片）+ 快速信息 + 功能标志。检查未知工作簿时的首选调用。
xlsx_topology	一次调用即可了解工作簿概况：工作表 × 尺寸 × 公式 × 命名范围 × 表格 × 数据验证 × 超链接 × 合并单元格。
xlsx_list_sheets	列出所有工作表名称和元数据。读取前的快速初步调用。
xlsx_schema	推断每个工作表的列类型、可空标志、标题行和示例值。
xlsx_describe	对每个数值列执行 Pandas 风格的 .describe()——计数、均值、标准差、最小值、最大值、四分位数。
xlsx_workbook_views	UI 状态——冻结窗格、缩放、活动单元格、隐藏 / veryHidden 工作表、标签页颜色、活动标签页。
xlsx_properties	工作簿元数据——创建者、修改信息、公司、标题、自定义文档属性。

读取 / 写入

工具	功能
xlsx_read	读取工作簿 — 可输出文本、JSON 或 Markdown。保留公式、命名范围、布局和数据类型。也可通过 ID 读取实时 Google Sheet（source:"gsheets"），仅限读取，需提供只读 Google OAuth 令牌。
xlsx_read_handle	通过服务端句柄而非字节读取 — 适用于工作簿已上传、无需再次传输的会话流程。
xlsx_write	根据结构化规范创建或更新工作簿。支持多工作表、公式、命名范围和表格定义。
xlsx_data_clean	就地规范化杂乱数据 — 修剪空格、转换类型、删除重复行、修复明显的编码问题。返回清理后的副本和更改日志。采用另存为方式；绝不修改输入内容。
xlsx_diff	对两个工作簿进行语义差异比较 — 涵盖单元格级差异、公式更改和结构变化。输出结果确定。
xlsx_redact	分享前对工作簿中的 PII 进行脱敏。由服务端检测；返回脱敏副本和审计清单。
xlsx_convert	支持 25 种以上输入格式 / 16 种输出格式（csv、tsv、html、ods、xls、xlsb、dif、sylk、prn、txt、dbf、eth、json、markdown、xlsx 等）。对于 xlsx、xls、csv 和 json 输入，不会回退到兼容性引擎：如果我们的自有引擎无法处理，该调用会失败并返回带类型的 501 capability_gap。
xlsx_validate	完整性检查 — 使用服务端自有的 OOXML 引擎解析工作簿，并报告其是否可正常加载，同时提供各工作表的结构摘要。
xlsx_session_set_validations	配置会话级验证规则，供服务端应用于同一会话中的后续调用（例如，拒绝缺少必需列的行）。有状态 — 仅影响当前会话。

与 Pandas 对等（计算新聚合结果）

工具	功能
xlsx_filter	按条件（列 运算符 值）筛选行。返回匹配行，并可选择投影。
xlsx_aggregate	分组并聚合（sum / count / mean / min / max / median / std）。
xlsx_sort	按多个列排序，可为每列分别指定升序 / 降序。
xlsx_value_counts	生成列的频次表（Pandas .value_counts()）。
xlsx_pivot	根据原始数据计算新的数据透视表 — 形状与 Pandas pivot_table() 一致。
xlsx_eval	使用我们的自有重新计算引擎计算自由格式公式或重新计算单元格引用 — 不使用第三方公式引擎。若公式使用了我们尚未实现的函数，会如实返回“暂不支持”错误，绝不返回错误值。

结构保留 — 护城河（pandas 在读取时会丢弃以下所有内容）

工具	功能
xlsx_named_ranges	列出所有命名区域及其作用域、引用和数值预览。
xlsx_tables	列出 Excel ListObjects（表格），包括列标题、数据区域和汇总行。
xlsx_formulas	导出工作簿中的所有公式（单元格、工作表、公式文本、缓存值）。
xlsx_data_validations	列出单元格级别的数据验证规则（下拉列表、数值／日期范围、文本长度、自定义规则）。
xlsx_hyperlinks	列出超链接，并标注类型（外部／内部／mailto／未知）。
xlsx_conditional_formats	列出条件格式规则（色阶、数据条、图标集、基于公式的突出显示、前 N 项、重复值）。
xlsx_styles	数字格式、字体、填充和对齐方式，可按工作表汇总或按单元格详细列出。
xlsx_comments	同时列出旧版批注和串接讨论（多位作者，并解析显示名称）。
xlsx_protection	工作表锁定状态、单元格级别的锁定／隐藏标记，以及工作簿结构／窗口锁定状态。
xlsx_merged_cells	根据布局列出合并单元格，包括主单元格的值和类型启发式分类（标题／水平／垂直／块）。
xlsx_charts	图表规格（类型、标题、系列公式引用、坐标轴标题）——直接从大多数电子表格库会忽略的图表 XML 部件中读取。
xlsx_images	嵌入图片清单（格式、大小、工作表、锚定单元格）。
xlsx_pivot_tables	现有的数据透视表定义——位置、数据源、行／列／页／数据字段及其汇总函数。
xlsx_slicers_timelines	新版 Excel 筛选界面——切片器（绑定到表格／数据透视表）和时间线（带有选择状态的日期范围）。
xlsx_external_links	工作簿之间的引用及目标分类，并在路径可能因共享而失效时发出警告。
xlsx_print_settings	“Excel 会打印什么？”——打印区域、纸张大小、页边距、页眉／页脚、打印标题。
xlsx_form_controls	交互式控件——复选框、按钮、下拉列表、微调按钮、滚动条、列表框——包括关联单元格和范围。
xlsx_macros	VBA 宏是否存在、模块名称启发式分析和安全建议（根据政策，不会提取源代码）。

集成

工具	功能
xlsx_post_slack	将工作簿作为文件附件发布到 Slack 频道，并可附带消息。BYOA——Agent 提供用户的 Slack bot token（xoxb-…）；该 token 会转发给 Slack，绝不会持久化。使用 Slack 的外部上传流程。
xlsx_post_teams	将工作簿作为文件附件发布到 Microsoft Teams 频道的频道消息中，并可附带消息。BYOA——Agent 提供用户的 Microsoft Graph 访问令牌（JWT）；该令牌会转发给 Microsoft，绝不会持久化。使用 Graph 的 filesFolder + upload-session + post-message 流程。

完整性验证

工具	功能说明
xlsx_stamp	使用加密“完整性验证”印记为工作簿签名——将 Ed25519 签名声明（命名事实检查及其通过／失败／跳过状态，以及内容哈希）嵌入 docProps/custom.xml。保存时，印记会随文件保留；收件人之后可以验证印记，确认文件自签名后未遭篡改。仅用于事实证明——绝非表达主观意见的认可印章。
xlsx_verify_stamp	验证工作簿中嵌入的印记。返回：(a) Ed25519 签名对照已注册公钥是否有效；(b) 工作簿字节是否与签名声明中的哈希匹配；(c) 印记中完整的检查结果内容。这是三种不同的信任信号——签名完整性、内容完整性，以及最初证明的内容。
xlsx_receipt	附加 AI 生成回执——使用 Ed25519 签名的声明，描述调用方声明的 Agent 身份（名称、显示名称、身份 URL）、生成时间戳、内容哈希、可选的源文件哈希、可选的提示词哈希、可选的已调用 MCP 工具，以及可选的说明。诚实边界（至关重要）：服务对调用方声明的 agent.name 签名——不会验证调用方实际上是否就是该 Agent。加密身份绑定（为每个 Agent 签发签名密钥）属于 v1.1+ 的范围。
xlsx_verify_receipt	验证工作簿中嵌入的回执。返回与 xlsx_verify_stamp 相同的三种信任信号，以及调用方声明的 Agent 身份原文（不提供任何暗示已完成加密身份验证的 UI 功能）。可用于展示“此文件来自哪里？”——其依据是服务对调用方如实声明的签名。

修复器 — 外部引用损坏

工作簿会逐渐损坏。文件一旦移动，#REF! 就会沿所有依赖公式传播。Power Query 连接中嵌入了无法轮换的凭据。定义名称指向已不存在的外部工作簿。修复器工具系列可诊断这些问题并实施针对性修复——只读诊断、修复前模拟，以及在 Agent 不想逐一指定修复操作时使用的高级意图路径。

工具	功能说明
xlsx_healer_diagnose	外部引用损坏的结构化报告——损坏的外部引用、定义名称中的外部引用、嵌入凭据的 Power Query 连接、#REF! 传播图，以及多跳链。只读。
xlsx_healer_simulate	在应用前展示特定修复操作会产生哪些更改——结构与 xlsx_healer_cure 相同，但为只读。当 Agent 不确定是否继续时，可用于预览影响。
xlsx_healer_cure	应用一个特定修复操作（例如，移除损坏的外部引用、统一定义名称，或将 #REF! 传播替换为确定值）。采用另存为的方式；除非设置 confirm:true 且 mode:"in_place"，否则会保留源工作簿。
xlsx_healer_intent	高级意图路径——make-it-work、make-standalone、migrate——会将意图转换为合适的修复操作序列。适用于 Agent 知道目标但不知道该执行哪种操作的情况。

工具响应包含引用页脚和 _meta 块（工具名称、版本、层级、请求 ID、powered_by）。两者都会原样传递；不会删除任何内容。

---

工具

MCP 服务公开的全部 52 个工具（由 tools/list 生成）。用日常语言向 Agent 提出请求即可调用，也可以直接调用 API／CLI。

读取与探索

• xlsx_read — 按路径读取 .xlsx 文件，并返回渲染后的 Markdown／JSON／SQL 表示形式。也可读取实时 Google 表格：传入 source:"gsheets"、spreadsheet_id 和你提供的只读 Google OAuth 令牌（注入令牌——只读，不支持写入；服务不会签发或代管 Google 凭据）。输出格式与读取等效的 .xlsx 文件相同。
• xlsx_read_handle — 通过服务器端缓存句柄读取已通过分块上传流程上传到服务器的工作簿，无需重新传输字节。返回与 xlsx_read 相同的格式（text／json／markdown），但跳过 file_b64 往返传输。
• xlsx_validate — 检查本地 .xlsx 文件是否健全：使用服务器自有的 OOXML 引擎解析工作簿，并报告其能否正常加载（zip 文件被截断、容器已加密、没有工作表或工作表内容受损，均会导致检查失败），并提供逐工作表的结构摘要。

检查结构

• xlsx_charts — 列出本地 .xlsx 文件中的每个图表，包括类型（bar / line / pie / scatter / area / doughnut / radar / stock / surface / bubble）、标题、坐标轴标题和各系列的公式引用（图表获取数据的单元格范围）。通过 OOXML drawing 关系链标注工作表归属。

• xlsx_comments — 列出工作簿中的每条单元格批注，包括传统批注（黄色便笺，cell.note）和现代线程式批注（以多作者对话的形式单独存储在 OOXML zip 中）。每条记录包含：类型、工作表、单元格、作者、文本，以及任何回复线程。

• xlsx_conditional_formats — 列出工作簿中的每条条件格式规则，包括色阶、数据条、图标集、基于公式的突出显示、前 N 项、重复值 / 唯一值、包含文本、时间段、高于平均值。每条规则包含：范围、类型、运算符、公式、优先级、stopIfTrue。

• xlsx_data_validations — 列出工作簿中定义的每条单元格级数据验证规则（下拉列表、数值 / 日期上下限、文本长度上限、自定义公式）——即 Excel 对用户输入到单元格中的内容强制执行的约束。

• xlsx_describe — 按列提供类似 pandas df.describe() 的统计信息——数值列包含 count、nulls、unique、min / max / mean / std；并提供带纯度评分的 dtype。

• xlsx_external_links — 列出此文件依赖的每个外部工作簿引用——=[Budget.xlsx]Sheet1!A1 形式的公式。每个链接包含：目标路径（解码后）、分类（http / network share / absolute / relative）、从外部工作簿引用的工作表、缓存单元格值数量，以及定义名称引用。

• xlsx_form_controls — 列出工作簿中的每个表单控件（Check Box、Button、Drop-down、List Box、Option Button、Scroll Bar、Spinner、Label、Group Box），并提供关联单元格、当前值、下拉列表源范围，以及适用时的最小值 / 最大值 / 步长。

• xlsx_formulas — 提取本地 .xlsx 工作簿中的每个公式——单元格坐标（A1）、公式文本、缓存结果。提供 openpyxl 风格的只读元数据。

• xlsx_hyperlinks — 列出工作簿中的每个超链接，包括其锚点单元格、目标 URL / 锚点、显示文本、工具提示，以及类型分类（external / internal / mailto / unknown）。

• xlsx_images — 列出本地 .xlsx 文件中的每张嵌入图片，包括格式（png / jpg / gif / svg / bmp / tiff / emf / wmf）、字节大小、工作表归属和锚点单元格范围（图片浮动覆盖的单元格）。直接读取 xl/media/* 和 xl/drawings/*。

• xlsx_list_sheets — 列出本地 .xlsx 文件中的工作表名称、尺寸和可见性。

• xlsx_macros — 检查 xlsm / xlsb 工作簿是否包含 VBA 宏、vbaProject.bin 的大小，以及可能的模块名称（通过启发式 UTF-16LE 扫描识别 ThisWorkbook / Sheet / Module / Class / UserForm）。返回简短的安全建议，供 LLM 转达给用户。

• xlsx_merged_cells — 列出每个合并单元格区域，包括主单元格值、范围、跨度尺寸和类型启发式判断（"header" / "horizontal" / "vertical" / "block"）。Pandas 读取合并单元格时会忽略其关系——它会读取主单元格中的一个值，旁边则有三个空白单元格。xlsx_merged_cells 提供能识别布局的信息视图："A1:D1 是一个写着 Q4 2024 的单元格"，而不是四个单元格中有三个莫名其妙地为空。

• xlsx_named_ranges — 列出本地 .xlsx 工作簿中的所有定义名称（命名区域）——名称、作用域（工作簿或工作表）、类型（cell / range / formula）和引用。

• xlsx_pivot_tables — 列出本地 .xlsx 文件中所有已存在的数据透视表定义（即 Excel 用户已创建的数据透视表）。每个数据透视表包含：工作表、名称、位置范围、源范围（或命名区域 / 表引用）、行 / 列 / 页面字段，以及带有聚合函数（sum / count / average / max / min / product / stdDev / 等）的数据字段。

• xlsx_print_settings — 展示每个工作表“Excel 现在会打印什么”——打印区域、方向、纸张大小（A4 / Letter / Legal / Tabloid / 等）、缩放比例或 fitToPage、页边距、拆分为 Excel 的 L/C/R 区域的页眉 / 页脚、打印标题（每页重复的行 / 列）、手动分页符，以及 B&W / draft / centered 标记。

• xlsx_properties — 展示本地 .xlsx 文件的身份信息。核心信息：creator、last_modified_by、created/modified/lastPrinted 时间戳、title、subject、company、manager、keywords、category、description。应用程序信息：应用名称 + 版本、文档安全标签、超链接基址。自定义信息：用户定义的每条 Info > Properties 条目（Department、ReviewedBy、ApprovalRequired 等），包含类型标签和值。

• xlsx_protection — 展示本地 .xlsx 文件中的每项保护设置，让 Agent 了解可以和不可以编辑的内容。包括工作簿级别（lockStructure、lockWindows）、每张工作表（是否受保护？是否有密码？隐藏状态？）、每项操作的允许 / 禁止列表（formatCells、sort、insertRows、pivotTables 等），以及未锁定 / 隐藏单元格示例——当工作表处于只读状态时，用户实际可以输入内容的单元格。

• xlsx_schema — 推断本地 .xlsx 文件的列架构——类型、是否可为空、标题行、示例值。

• xlsx_slicers_timelines — 列出本地 .xlsx 文件中的每个切片器（交互式筛选按钮）和时间线（日期范围筛选可视化），并提供其标题、源绑定（表列或数据透视表）和时间线粒度（年 / 季度 / 月 / 日），以及当前所选日期范围。

• xlsx_styles — 展示单元格格式（数字格式、字体、填充、对齐方式），让 Agent 知道单元格看起来是什么样，而不只是读取其原始值。默认模式：按工作表汇总出现次数最多的前 N 种数字格式 / 字体 / 填充。详细模式（选择启用，上限为 1000 个单元格）：针对范围较小的查询提供逐单元格明细。

• xlsx_tables — 列出本地 .xlsx 工作簿中的每个 Excel ListObject（“套用表格格式”结构）——名称、工作表、范围、标题行 / 汇总行标记、列。

• xlsx_workbook_views — 展示本地 .xlsx 文件的 UI 状态——用户在 Excel 中打开文件时看到的内容。每张工作表包含：可见性（visible / hidden / veryHidden）、视图状态、缩放比例、活动单元格 + 选区、冻结窗格细分、网格线 / 行列标题 / 标尺 / RTL 标记、标签颜色。工作簿级别：Excel 打开时处于活动状态的工作表。 查询与分析

• xlsx_aggregate — 对本地 .xlsx 文件执行 pandas 风格的 df.groupby([cols]).agg({col: func})。支持的函数：sum / mean / min / max / count / count_distinct。

• xlsx_diff — 计算两个本地 .xlsx 文件之间的语义差异，包括单元格级别的变更、公式变更以及新增／删除的行。

• xlsx_eval — 使用自有重算引擎计算本地 .xlsx 文件中的 Excel 公式，风格类似 xlwings。

• xlsx_filter — 对本地 .xlsx 文件执行 pandas 风格的行筛选，谓词以 AND 组合：eq/ne/gt/gte/lt/lte/contains/in/is_null/not_null。

• xlsx_pivot — 对本地 .xlsx 文件执行 pandas 风格的 pivot_table()，将扁平表格重塑为二维矩阵：行是 index 的唯一值，列是 columns 的唯一值，单元格是对 values 的聚合结果。

• xlsx_sort — 对本地 .xlsx 文件执行 pandas 风格的 df.sort_values()，支持按多列排序，并为每列指定排序方向（asc/desc，默认 asc）。

• xlsx_topology — 一次调用即可查看工作簿概况。一次性返回工作表 × 维度 × 公式 × 命名区域 × 表格 × 数据验证 × 超链接 × 合并单元格，以及功能标志（宏 / 外部引用 / 数据透视表 / LAMBDA / 动态数组）。

• xlsx_value_counts — 对本地 .xlsx 文件中的单列执行 pandas 风格的 Series.value_counts()，统计每个唯一值，并按频次降序排列，同时提供百分比。

清理与修复

• xlsx_data_clean — 对本地 .xlsx 文件执行 AI 原生数据清理。扫描七种最常见的数据问题：NA 变体（N/A、NA、null、-）、合并单元格残留、类型转换错误（数字存为文本 / 日期存为序列号 / 前导零丢失）、末尾行噪声（页脚 / 汇总行）、表头不在首行（表头前有引导内容）、编码异常（UTF-8 被误解码为 CP1252 后产生乱码）以及重复列标题；可仅标记问题（诊断模式），也可应用确定性修复（执行模式）。

转换

• xlsx_convert — 通用电子表格格式转换器。可读取 25 种以上的任意输入格式（xlsx、xlsb、xlsm、xls、ods、fods、numbers、csv、tsv、dbf、lotus 1-2-3、quattro pro、sylk、dif、html、rtf 等），并导出为任意受支持的输出格式（xlsx、csv、json、md、html 等）。

写入（新建文件）

• xlsx_redact — 在分享或归档前，从本地 .xlsx 文件中删除个人身份信息和敏感值。
• xlsx_write — 根据结构化规范创建或更新本地 .xlsx 文件。

完整性与验证

• xlsx_healer_cure — 针对已诊断的工作簿执行一项指定的修复操作。操作包括：rename_move（重写引用路径）、pattern_bulk（按正则表达式批量重写引用）、source_deleted_freeze（将失效引用替换为缓存值）、source_deleted_redirect（指向替代文件）、source_deleted_localize（将外部源快照保存为本地副本）、permission_denied（移除凭据）、structure_changed（为移动的单元格重写公式）、format_change（扩展名更改后重新链接）、make_standalone（完全解除对所有外部文件的引用）。返回修复后的工作簿字节和回执。
• xlsx_healer_diagnose — 生成结构化诊断报告，列出工作簿中已失效或有失效风险的外部引用。返回五类发现：（1）无法解析的外部工作簿引用；（2）定义名称中的外部引用；（3）包含内嵌凭据的 Power Query 连接；（4）上游故障导致的 #REF! 传播映射；（5）多跳链（工作簿 → 工作簿 → 工作簿）。发现项包含 reference_id 键，后续修复操作会使用这些键。
• xlsx_healer_intent — 由目标驱动的修复。调用方声明一个 INTENT（make-it-work、make-standalone 或 migrate），而不是指定具体修复操作；Healer 会规划操作序列并执行。make-it-work：以最少改动消除错误。make-standalone：完全解除外部依赖（对每项外部依赖创建快照）。migrate：根据 from/to 前缀对重写所有引用。返回规划的操作、修复后的字节和无法执行的操作列表。
• xlsx_healer_simulate — 模拟工作簿外部引用在接收方端的可访问性。给定接收方可见的路径列表（accessible_paths），返回哪些引用在接收方端仍可解析，哪些会失效（以及原因）。只读；不会生成输出工作簿。
• xlsx_receipt — 为本地 .xlsx 文件附加 AI 生成回执——将加密证明嵌入 docProps/custom.xml，说明“此文件由此 Agent 于此时间针对这些输入生成”。返回的工作簿以 base64 格式存放在 _meta.file_b64 中；传入 out_path 可将其写入磁盘。
• xlsx_stamp — 使用“工作簿完整性验证”印章签署本地 .xlsx 文件——将加密证明嵌入 docProps/custom.xml，说明“此文件由这些工具生成，通过了这 N 项指定检查，在此时间签署，且此后未被篡改”。只包含事实性声明（绝不使用带有主观评价的认可印章）。返回的工作簿以 base64 格式存放在 _meta.file_b64 中；传入 out_path 可将其写入磁盘。
• xlsx_verify_receipt — 验证工作簿中嵌入的 AI 生成回执。返回签名是否有效、重新计算的内容哈希是否与回执中的哈希一致，以及调用方声明的完整内容（Agent 身份、生成时间戳、源文件哈希、提示词哈希、调用的 MCP 工具、描述）。
• xlsx_verify_stamp — 验证工作簿中嵌入的完整性验证印章。返回加密签名是否有效、工作簿字节是否与签署时一致（重新计算的哈希与印章中的哈希对比），以及印章中完整的检查结果内容。

集成

• xlsx_post_slack — 将本地 .xlsx 文件作为文件附件上传到 Slack 频道，可选择附加消息。
• xlsx_post_teams — 将本地 .xlsx 文件作为文件附件上传到 Microsoft Teams 频道，可选择附加消息。

会话

• xlsx_session_set_validations — 配置会话级数据验证规则，供服务端应用于同一会话中的后续调用（例如：拒绝缺少必需列的行、强制类别列使用枚举值、限定数值输入范围）。有状态——仅影响当前会话。

一次调用式压轴工具

• xlsx_doctor — 针对本地 .xlsx 文件的一键工作簿健康报告。扫描宏、外部工作簿引用、隐藏 / veryHidden 工作表、缺失的创建者元数据、大型嵌入图像，并标出有趣的功能标志（LAMBDA、动态数组、数据透视缓存、切片器、线程式批注）。按 HIGH / MEDIUM / LOW 对发现的问题排序。另含 quick_facts：工作表数量、公式、命名区域、合并单元格、超链接、数据验证、图像、文件大小。

---

函数

xlsx_eval 使用我们自己的重新计算引擎重新计算公式，目前可计算 350 多种 Excel 函数，以及 Google Sheets 独有的函数，并会随着开发持续增加。覆盖常见函数类别：数学与三角函数、统计、财务、日期与时间、文本、逻辑、查找与引用、信息和工程。完整的支持列表见 https://xlsx-for-ai.dev 的 Functions 部分。

引擎尚不支持的函数会如实返回“尚不支持”错误，而不会猜测结果。引擎不支持 WEBSERVICE、RTD 和 STOCKHISTORY 等访问工作簿外部数据的函数，因此重新计算无法访问工作簿之外的数据。

---

FP&A 工作流

xlsx-for-ai 专为处理实际财务电子表格的 Agent 打造。常见工作流：

预算与实际差异分析

xlsx_read → extract actuals and budget → agent computes variances → xlsx_write → deliver updated workbook

月末对账

xlsx_read (bank export) + xlsx_read (GL extract) → agent matches rows → xlsx_diff → audit trail of unmatched items

审计跟踪提取

xlsx_schema → identify change-log columns → xlsx_read with sheet filter → agent summarizes changes by author/date

多实体合并

xlsx_read × N entity files → agent aggregates → xlsx_write → consolidated workbook with intercompany eliminations noted

分享前的 PII 脱敏

xlsx_redact → strips SSNs, emails, employee IDs → redacted file safe for external distribution

这些工作流正是工具描述采用 FP&A 易读表述的原因：开发者为财务团队构建 Agent 时，Agent 的大模型会读取工具描述并正确选择工具，无需额外的提示词工程。

---

可靠性功能

• 确定性差异。 对于相同输入，xlsx_diff 会生成完全相同的输出，便于安全地进行版本控制，也可在 CI 中安全地进行断言。
• 带置信度的架构推断。 xlsx_schema 会在推断出的类型旁返回类型置信度分数。Agent 可根据置信度选择分支，而非盲目相信推测结果。
• 审计跟踪。 每次工具调用（无论成功或失败）都会在服务端记录时间戳、客户端 ID、端点、文件大小、延迟和错误类别。
• 强化输入验证。 每个上传的缓冲区都会经过 4 项引擎前置防护：防御 billion laughs XML 炸弹、剥离控制字符、限制工作表缓冲区上限（防御慢速 ZIP 炸弹），以及类型化错误链。所有防护均在 xlsx 引擎接触任何字节之前执行。
• Agent 可读的错误。 速率限制和验证错误会返回结构化 JSON，Agent 可以读取错误并智能地提示用户，而不只是显示状态码。

---

隐私

文件会通过 HTTPS 传输至 https://api.xlsx-for-ai.dev 并在内存中处理。单次请求处理结束后，不会保留文件。使用 Google 账号登录；电子邮件地址仅用于识别你的账号，不会存储密码。

完整的数据处理政策请参阅 PRIVACY.md。

---

费用

所有工具均包含在内。首次使用时只需登录一次（在编辑器中通过链接和代码登录，或在终端中运行 xlsx-for-ai login）。前 1,000 名注册用户每月可免费处理 500 个文件。之后注册的用户可免费处理 10 个文件，之后每年支付 $25，即可每月处理 10,000 个文件。使用 Google 账号登录。所有方案的文件大小限制相同：.xlsx 最大 100 MB，.xls 最大 100 MB，.csv 最大 200 MB。达到限制时，服务会在消息中提示这些限制。

---

许可证

npm 客户端（xlsx-for-ai，即本软件包）采用 MIT 许可证。托管 API 服务端（xlsx-for-ai-server）为专有软件——引擎 IP、渲染管线和语义差异算法均非开源。

---

架构

agent (Claude Code / Claude Desktop / Cursor / Continue / Zed / Windsurf / custom)
  └── MCP stdio
        └── xlsx-for-ai-mcp  (this package, ~200 lines)
              └── POST /api/v1/tools/<name>  →  api.xlsx-for-ai.dev
                    └── server-side engine (own OOXML/CSV engine, formula eval, schema inference, redaction)

要求： Node.js 22+。对于无法升级的用户，main 上的 1.5.x 版本线会继续维护。

---

首次运行时登录

xlsx-for-ai login

打印一个链接和一段短代码。在任意浏览器中打开链接，使用 Google 登录并批准，CLI 会将密钥保存到 ~/.xlsx-for-ai/config.json。在交互式终端中运行任何尚未保存密钥的命令时，都会自动启动相同的流程。运行 xlsx-for-ai login --force 可重新登录。

在编辑器或桌面应用中使用（无需终端）。 你无需事先运行任何内容。首次要求助手使用电子表格工具时，它会回复一个登录链接和一段短代码，而不是给出答案。在浏览器中打开链接，确认代码匹配，然后批准。之后再次提出请求即可正常使用，无需重启。如果你在批准前再次提出请求，会收到相同的链接和代码。如果链接过期（约 15 分钟）或你拒绝了它，下次请求时会收到新的链接。

没有可供你操作的屏幕的终端命令（例如脚本，或由其他程序运行的命令）。该命令会将链接和代码打印到错误流，并等待你批准，最长等待 60 秒。及时批准后，它会继续处理你的请求。如果你没有批准，它会停止并提示你先批准，再运行相同的命令。第二次运行会继续使用相同的代码，因此无需复制新代码；如果你在此期间已经批准，命令会立即完成。要更改等待时长，请设置 XFA_LOGIN_WAIT_SECONDS（例如 XFA_LOGIN_WAIT_SECONDS=120）。

在自动化运行（CI）中，以及任何设置了 XFA_NONINTERACTIVE=1 的运行中，程序不会等待，也不会启动登录。没有密钥时，命令会立即停止并说明原因。对于自动化运行，请先在有终端的计算机上登录一次，然后将 ~/.xlsx-for-ai/config.json 中的 api_key 值作为环境变量 XLSX_FOR_AI_KEY 传递给运行环境（请将其保存在密钥存储中）。同时存在该变量和已保存文件时，以该变量为准。

如果已保存的密钥被拒绝。 在编辑器或桌面应用中，下次请求会显示新的登录链接，并在你批准新密钥之前保留已保存的密钥。在终端中，运行 xlsx-for-ai login --force。

你可能看到的消息。 达到使用限额时，消息由服务本身提供。遇到 402 时，会显示相关消息和升级链接；遇到 429 时，会显示相关消息以及何时可以重试。501 表示该功能尚未实现，文件没有问题，重试也无济于事；终端命令遇到此错误时会以代码 5 退出（3 表示无法连接服务或服务发生故障，4 表示文件或链接问题，2 表示使用错误，1 表示其他问题）。

更新。 如果此安装无法自行更新（例如只读安装或容器），工具结果会提示有新版本，并提供更新命令。能够运行命令的助手可以代你更新；否则，请在终端中运行 npm install -g xlsx-for-ai@latest，然后重启应用。设置 XFA_NO_AUTO_UPDATE=1 可关闭自动更新和此通知。

链接不是文件。 此软件包只会读取保存在你计算机上的文件。如果你提供网页链接或 Google Sheets 链接，而不是文件路径，它会告知你这一点。请下载文件并提供其路径，或使用托管的 xlsx-for-ai 连接器，它可以直接打开链接。

在 Docker 中运行。 此镜像不再跳过登录。首次请求时会打印登录链接和代码。密钥存储在容器的 /home/node/.xlsx-for-ai 中，因此请在此处挂载卷以便在多次运行间保留密钥，例如 -v xfa-config:/home/node/.xlsx-for-ai。

4.1.0 之前的版本生成的密钥目前仍可使用。当服务将某个密钥标记为即将停用时，工具结果会以通俗文字说明；此处不承诺具体日期。

配置

存储在 ~/.xlsx-for-ai/config.json 中。首次运行时自动创建。此外，pending-login.json 会保存已发起但仍待你批准的登录（因此重新运行时会显示相同的代码）；登录完成或代码过期后，该文件会被删除。可以通过 XFA_CONFIG_DIR 移动此文件夹。

{
  "client_id": "<uuid>",
  "api_key": "<opaque>",
  "registered_at": "2026-05-05T00:00:00.000Z",
  "telemetry": false,
  "consent_version": 1
}

遥测采用自愿启用：

xlsx-for-ai --enable-telemetry
xlsx-for-ai --disable-telemetry
xlsx-for-ai --telemetry-status

隐私模式 — 所有账户均已关闭工作簿捕获（自 2026-10-14 起）。XFA_PRIVACY=strict 还会关闭工具生成文件的 60 分钟下载副本。请参阅 PRIVACY.md：

# Per-session flag (applies to all tool calls in the CLI invocation)
xlsx-for-ai --privacy=strict myfile.xlsx

# Environment variable (applies globally to all requests in the process)
XFA_PRIVACY=strict xlsx-for-ai myfile.xlsx

# In MCP server config (applies to all tool calls from the MCP server):
# Set XFA_PRIVACY=strict in your MCP server's env block

删除配置即可重置客户端 ID 和 API 密钥：

rm ~/.xlsx-for-ai/config.json

---

从 1.5.x 迁移

之前	现在
所有渲染均在本地进行	所有渲染均在服务端进行
xlsx-for-ai <file> CLI	相同 — 仍可使用
cursor-reads-xlsx	仍可使用 — 向后兼容别名
--list-sheets、--schema、--diff 等	已移至 MCP 工具（xlsx_list_sheets、xlsx_schema、xlsx_diff）
--export-redacted-workbook	已移至 xlsx_redact MCP 工具
笨重的 npm 安装包（约 50 MB）	轻量安装包（约 2 MB）；引擎仍在服务端
PII 检测、区域评分	已移至服务端；npm 包中不提供

~/.xlsx-for-ai/config.json 中的配置文件会原地扩展 — 保留现有的遥测许可设置。

---

安全

请参阅 SECURITY.md。所有文件内容都会通过 HTTPS 传输至 https://api.xlsx-for-ai.dev。文件仅在单次请求期间保留。