Sezzlee Excel

@sezzlee/excel-mcp

一个独立的 MCP 服务，默认读取本地 Excel 文件。选择启用写入后，会创建不可变的输出版本，而不会更改源文件。

读取 .xlsx、.xlsm 和 .csv 文件，并限制在单个文件夹内。沙箱、文档缓存、错误封装、游标编解码器和工具注册层均来自 @sezzlee/file-core。

文档：https://docs.sezzlee.app/docs/excel-mcp/introduction — 教程、任务指南，以及根据此软件包生成的工具、错误代码和限制参考。

快速入门

服务只接受一个参数：允许读取的文件夹的绝对路径。无法读取该文件夹之外的任何内容。

{
  "mcpServers": {
    "excel": {
      "command": "npx",
      "args": ["-y", "@sezzlee/excel-mcp", "/Users/me/sheets"]
    }
  }
}

使用 Claude Code：

claude mcp add excel -- npx -y @sezzlee/excel-mcp /Users/me/sheets

需要在 macOS（x64、arm64）、glibc Linux（x64、arm64）或 Windows x64 上使用 Node.js 22 或 24；文件访问通过原生模块完成，不提供 JavaScript 回退方案。

编写报告

追加 --write <relative-output-directory>，即可在工作簿根目录内启用写入。使用 prepare_edit 选择源文件，然后在 edit_workbook 中使用确切的版本。create_workbook 可以同时发布值和按顺序排列的外观更改。继续使用返回的版本，或从较早的保留版本创建分支。

创作功能支持可组合的数字、日期、时间、货币和百分比格式，以及字体、填充、边框、对齐方式、尺寸、冻结窗格、可见性、基本打印布局和安全的合并/取消合并操作。除非明确请求丢弃内容，否则合并操作会拒绝处理非锚点单元格中含有内容的情况。标量写入会保留类型；看起来像公式的文本仍会作为文本处理。

显式公式写入/填充支持普通 A1、混合/绝对引用、工作表引用和结构化表格引用。表格操作涵盖创建、重命名、更改表头、扩展/缩小、计算列、汇总行、筛选器以及转换为区域。新的表格样式为 SezzleeBlue 或 none；转换操作会拒绝处理受影响且样式或依赖项不受支持的情况。缩小表格时，除非明确请求清除，否则会保留被排除的值。

调整表格区域大小只会更改行范围，同时保留表头位置和宽度。结构性宽度更改应先使用明确的工作表列操作。如果已保存的筛选/排序条件需要进行不受支持的转换，操作会被拒绝。

批量作业可以在原子发布前，先为每个选定的输出按顺序完成外观/公式更改。失败的分组不会留下未完成的报告。独立分组会保留成功的输出并报告部分完成状态；内容相同的重试会复用持久化结果。

创作功能写入公式时不会伪造缓存结果，并会报告需要重新计算。使用单独的 calculate_workbook 工具来计算明确支持的公式子集，并将类型化缓存保存到新版本中。动态溢出数组和新的外部工作簿公式链接仍不属于此创作配置文件的支持范围。请参阅 Phase 5 验收 和 Phase 6 合约。

显式公式计算

在写入模式下，calculate_workbook({source: {filePath, versionId}}) 会根据实际输入重新计算所选工作簿。它会返回一个新的不可变版本、一份计算摘要以及最多 20 个单元格结果。较长的字符串结果和其他单元格仍可在已保存的工作簿中查看；响应会报告省略的内容。公式文本、支持的格式、表格以及无关的包部件均会保留。

bounded-excel-v1 引擎支持常规算术、百分比、串联和比较；SUM、AVERAGE、MIN、MAX、COUNT、COUNTA、COUNTBLANK、IF、IFERROR、AND、OR、NOT、SUMIF、COUNTIF、ABS、ROUND、ROUNDUP、ROUNDDOWN、精确 VLOOKUP、精确 MATCH 和标量 INDEX。引用包括矩形 A1 区域、带引号的引用／跨工作表引用、带工作表作用域的绝对静态名称，以及受支持的 Phase 5 结构化表格引用。日期保留工作簿的 1900/1904 数值序列系统。看起来像公式的字面文本仍会作为文本处理。

calculation.complete 表示是否已在此子集范围内计算所有公式；带类型的 Excel 错误也算作已计算结果。不支持的公式、循环和不可用的依赖项会分别提供诊断信息，且不会保留过时的缓存。cacheStatus 为 current 或 partial。保存的文件会保守地请求在电子表格应用中打开时执行完整重新计算；recalculationRequired: true 描述的是文件设置，并不表示成功的服务端计算结果来自旧缓存。后续的常规编辑会再次使公式缓存失效。

共享公式会报告为不可用，并清除缓存。数组／数据表组、迭代计算、按显示精度计算、R1C1 公式和不受支持的保留配置会被拒绝，且不会发布。易失函数、外部工作簿、UDF、动态数组、近似查找、通配符查找、公式定义的名称和相对名称锚点均不受支持。SUMIF 要求区域形状相同。本地化的日期／货币文本强制转换不属于数值文本子集。

计算限制为 128 个工作表、100,000 个已存储单元格、10,000 个公式单元格、10,000 个名称、8,192 个公式字符、每个扩展区域 100,000 个单元格、组合深度 128，以及 1,000,000 个工作步骤。达到限制时会保留源文件和所有已保留的输出。计算是在批量作业之后单独执行的版本操作；它不会改变该作业的原子发布边界。无需安装 Excel 或额外的运行时包。

专家报告编写

Phase 7 配置文件通过 create_workbook、prepare_edit、edit_workbook 和批量收尾操作组合下方操作。每项更改都会生成一个新的不可变 .xlsx；发生故障时不会发布部分版本。实施计划 和验收状态会区分实施与验证。

Family	操作与支持范围
名称和模板	define_name、delete_name、write_named_range。静态矩形 A1 目标、工作簿或工作表作用域、带引号的工作表名称，以及精确匹配的输入维度。替换时必须设置 overwrite:true；如果名称可能被引用，则拒绝删除。内置名称以及与表格或单元格名称冲突的名称均拒绝处理。
数据验证	set_validation、remove_validation。内联列表、整数／小数／日期／文本长度比较和自定义公式。日期边界使用工作簿序列值。这些是 Excel 交互式规则；服务不会在之后的每次值写入时强制执行这些规则。删除时，通过规则的完整范围，或通过 get_data_validations 报告的范围来选择一条已存储规则；替换时，通过规则完整的单个范围来选择。
条件格式	set_conditional_format、remove_conditional_format。比较／表达式规则、差异化字体／填充外观、显式优先级和 stopIfTrue。替换已占用的优先级时，必须明确指定。无关编辑会保留不受支持的扩展规则，不会悄悄转换这些规则。
内容	set_hyperlink、set_note、set_image 及对应的 remove_* 操作。现有的内部 A1／名称链接或不含凭据的 HTTPS 链接；纯文本旧式备注；带单元格锚点的嵌入式 PNG／JPEG。除非 display 明确替换现有单元格值，否则更改超链接时会保留该值；空白超链接单元格会将目标地址作为文本标签。删除未被共享的图像／图表时，也会删除未被引用的包内容。
图表	set_chart、remove_chart。柱形图、条形图、折线图和饼图；标题、放置位置以及显式类别／值范围。替换时会重建选定对象。会根据依赖项检查字面值来源缓存；公式来源不会生成虚构缓存，并会报告需要刷新。若对象存在不受支持的下游依赖项，则拒绝删除／替换。
数据透视表	set_pivot 会创建或显式刷新／替换真实的数据透视表、其专用缓存／记录和已保存结果。一个分类行字段；最多八个求和／计数／最小值／最大值度量。计数会统计非空值；数值度量会忽略非数值。源范围必须包含唯一的文本表头。公式和 ISO 日期单元格必须先显式转换为值／文本／序列值。共享缓存、高级数据透视表扩展和外部源不在刷新支持范围内。
保护	format_cells 接受 style.protection；protect_sheet 和 protect_workbook 用于设置工作表／结构保护。可选的旧式保护密码必须为 1 至 15 个可打印 ASCII 字符。这不是文件加密。继续操作时，必须先对每个锁定目标执行经过身份验证的 unprotect_workbook／unprotect_sheet 操作。仍拒绝强哈希、修订／窗口保护、加密、签名和启用宏文件的编辑。
定期报告	使用现有的版本固定批量作业 replace_values，再进行专家级完善。数据集较短时，会清除旧数据尾部；周期必须放在显式的命名文本目标中。相同作业会复用持久化的完成结果。公式计算仍是最终保护之前的独立不可变操作。
高级对象来源上限为 100,000 个单元格。图表最多包含 16 个系列，每个系列最多包含 10,000 个数据点；饼图只有一个系列。每张工作表最多包含 64 个数据透视表，每个数据透视表最多包含 10,000 个行分组、256 条数据验证规则、256 条条件规则，以及 4,096 条批注或作者创建的链接。每个工作簿最多包含 4,096 个命名目标。绘图最多包含 256 个锚定对象。嵌入图像大小上限为 5 MiB，像素数上限为 16,777,216，任一边的长度上限为 8,192 像素；嵌入媒体总大小上限为 20 MiB。现有的事务、输入、输出和单元格预算同样适用。

数据或来源发生更改时，会使受影响的图表缓存失效，并将受影响的数据透视缓存标记为无效且请求刷新。不相关的字面值来源缓存会保持不变。复制/移动、工作表操作和行/列更改会更新受支持的引用、区域和锚点；受影响的数据透视表、VML、扩展及其他不受支持的依赖配置文件会原子性地拒绝操作。保留未知部分并不意味着支持任意结构编辑。

读取是独立能力：现有工具可以检查名称、数据验证、条件格式、图像和图表，并读取已保存的数据透视结果单元格。此创作配置文件不会新增专用的数据透视表定义和旧式批注读取工具。宏绝不会执行。

独立的 Calc 检查涵盖值、数据透视表/缓存一致性、图表类型/系列、有效条件填充和规则顺序、链接、批注、图像及保护。Calc 在导出时不会保留 stopIfTrue；此使用方限制会单独报告。原始 .xlsx 标志会接受独立检查和架构验证。不声称通过桌面版 Excel UI 验收。

工具

数值文本强制转换仅适用于纯十进制或科学计数法字符串。需要使用其他转换配置文件的格式化数值、百分比、货币和日期文本均会报告为不受支持，包括直接传入 COUNT 的参数和数值条件。系统不会将其报告为编造的 Excel 错误，也不会用 IFERROR 隐藏。普通非数值文本仍遵循文档所述的 Excel 错误行为。

工具	功能
list_workbooks	列出根目录下可读取的文件；返回的 filePath 会原样传递给其他工具
describe_workbook	工作表及其类型（工作表或图表工作表）、已用区域、合并单元格、验证规则、表格、公式、图片和图表的数量，以及定义的名称
profile_sheet	有界类型和质量概况，以及可复用的列规格
read_sheet	将单元格区域作为紧凑网格读取：提取到上方的列标题和行数组
aggregate_sheet	分组摘要、日历和数值分桶、有界透视表、条件指标及精确百分位数
query_result	对保留的完整聚合快照进行精确筛选、列选择和稳定分页
find_in_sheet	值或公式与查询匹配的单元格；未指定工作表时，会搜索每个工作表
get_tables	Excel 表格：区域、标题行和汇总行、列名及列字母
get_data_validations	验证规则，每条存储的规则对应一个条目，并包含其区域
get_conditional_formats	以谓词形式表示的条件格式规则
get_merged_ranges	合并单元格区域
get_images	绘图和单元格内图片：绘图名称、锚点、替代文本、大小和扩展名。图表请使用 get_charts
get_charts	图表：类型、标题、坐标轴（包括次坐标轴、刻度和格式）、系列引用/数据点、趋势线、隐藏系列、数据透视表来源。包括图表工作表

所有参数、错误代码和限制均列于参考文档。

文本如何被读取为数字和日期

CSV 只包含文本，工作簿也可能将数字和日期存储为文本。read_sheet 和默认的 find_in_sheet 会按原样返回这些文本。aggregate_sheet 仅在指标或 where 操作数需要时，才将文本读取为数字或日期；它会根据范围内的所有值，逐列判断格式：小数和千位分隔符（1.234,50、1,234.50、1 234,50、1'234.50），以及斜线日期是日还是月在前。能正确读取最多值的分隔符或顺序胜出。如果胜出的格式会以不同方式读取某些值（1.234、01/02/2023），则该列存在歧义：这些值都不会被读取，并会有警告指出用于消除歧义的 columns 条目。括号表示会计负数、前导或尾随的 %（读取为比率）以及货币符号或代码都能识别；带点日期按日优先读取，土耳其语和英语月份名称也能识别。

以零开头或超过 15 位的数字串是标识符，除非 columns 将该列声明为数字，否则绝不会求和。如果某列的金额涉及多种货币，则会按原样求和并报告。每次调用中无法读取、比较或求和的值都会计入 warnings，并附上示例；readAs 会报告每列文本的读取方式。仅时间的数字格式（h:mm、hh:mm:ss AM/PM）会以 HH:mm:ss 返回；已用时格式 [h]、[m] 和 [s] 会返回 {"durationSeconds": number}，并且可按秒求和。

哪一行是标题行

如果调用未指定 headerRow，则会使用已声明表格或自动筛选器的标题行；如果没有，则使用已用区域前 20 行中，所有非空单元格均为文本、至少有两个此类单元格且没有单元格跨列合并的第一行，前提是其上方没有任何行包含数字、日期或其他非文本单元格；如果仍未找到，则使用第 1 行。标题位于数据上方，因此较低位置的纯文本数据行（例如只包含 --- 占位符的行）绝不会被当作标题行。响应会说明使用了哪种方式（headerRowSource：declared、scanned 或 default）。扫描始终覆盖整个已用区域，因此读取几行或单列的调用与读取整个工作表的调用会得到相同的标题行；即使调用者不知道列上方存在标题栏，也会跳过它。CSV 始终读取第 1 行。headerScan: true 会要求严格检测：如果有两行符合条件或没有任何行符合条件，则会拒绝。标题单元格若包含数字或布尔值，则会以其文本作为列名，因此可以用 "2008" 访问年份标题。

警告

响应中的 warnings 是由 { code, message, column? } 组成的列表。请根据 code 进行分支处理；message 面向用户，其措辞可能会变化。若警告针对某一列，column 表示该列的字母。

Code	触发条件
csv_preamble_ignored	sep= 行指定的分隔符与传入的分隔符不同
csv_blank_first_record	第一条 CSV 记录为空，并保留为标题
table_missing_names	声明的表格包含没有名称的列
header_row_mismatch	headerRow 与表格或自动筛选器声明的行不同
header_row_unnamed	headerRow 未命名任何列，而另一个顶部行包含列名
header_only_range	read_sheet 范围仅包含标题行
uncached_formulas	公式单元格没有缓存值
ambiguous_decimal	使用小数点和小数逗号读取时，值的结果不同
locale_separator_conflict	locale 读取出的值与该列自身标记所表示的数值不同
ambiguous_day_order	日期既可能按日优先读取，也可能按月优先读取
mixed_date_order	斜杠日期按月优先读取，而点分日期按日优先读取
distinct_lower_bound	经分析的列中，不同值的数量多于统计数量
no_majority_type	经分析的列中，没有任何类型占严格多数
identifier_text	经分析的列看起来是标识符，因此保留为文本
no_reusable_date_format	没有一种日期格式能读取经分析列中的所有日期
prefix_sample	分析结果仅描述前几行
columns_not_profiled	未分析 maxColumns 之后的列
mixed_units	某项指标将普通数字、分数或时长相加
mixed_currencies	某项指标将不同货币或未标注货币的金额相加
case_variant_groups	分组之间仅大小写或重音符号不同
uncomparable_cells	where 单元格无法与操作数进行比较
ungrouped_cells	无法读取用于分组的键对应的单元格
currencies_added	某列金额使用了不止一种货币
unread_numbers	文本单元格无法读取为数字，因此未计入总计
identifier_cells	单元格看起来是标识符，因此未计入总计
unread_booleans	单元格无法读取为布尔值，因此未计入布尔指标
derived_division_by_zero	某组中的派生指标除以零，因此该组的结果为 null

分组分析

日期以 yyyy-MM-dd 格式返回。日期和时间以 yyyy-MM-ddTHH:mm:ss.SSS 格式返回；如果源数据未存储时区，则结果不带时区。所有 Excel 日期单元格以及所有不带偏移量的 CSV 值都属于这种情况：它们是本地挂钟时间，添加 Z 会错误地表示为 UTC。带偏移量的值会保留其挂钟时间和偏移量（2019-12-31T23:40:00.000+03:00），并按其时间点排序。 groupBy 接受列名或封闭式变换。应用显式时间戳偏移后，日历分组使用 UTC。月份和季度键包含年份；周使用 ISO 周年；星期几从星期一 1 到星期日 7；小时从 0 到 23。普通列会保留其存储键，除非 columns 显式指定其类型，或某个指标或条件已需要以类型化方式读取同一列。读取单元格仍会返回其原始值。

数值 bins 是严格递增的边界，并单独设有下溢组和上溢组。区间包含下边界，不包含上边界。固定 width 使用可选的 origin（默认为零）；规范十进制运算会将 0.3 精确放在 0.1 边界上，而不会将前一个可表示值移入该分组。无法表示为互不相同的有限数值的边界将被拒绝。缺失键会形成 null 组；无法读取的派生键会计入 ungroupedRows，并在 warnings 中提供示例。

pivotBy 会将有界分组键转换为输出列，每个键和指标各对应一列。缺失的组合对于计数返回零，对于数值指标返回 null。分配密集结果之前会检查完整的行键数量 × 透视键数量 × 指标数量，即使输入中实际只包含其中少数几种组合也一样。上限为 10,000 个指标单元格。

median、p50、p90 和 percentile 使用精确的含端点线性插值（R7），与 Excel 的 PERCENTILE.INC 一致。百分位参数的取值范围为零到一，包含两端。相同指标选择所共用的样本只保留一次，整个调用的预算为 100 万个值。超出预算的请求将被拒绝，不会悄悄改为近似计算。每个指标都可以有自己的 where；这些条件会在调用的顶层筛选器之后以 AND 方式组合。counted、skipped 和 filtered 分别区分可用值、无法读取或缺失的值，以及被该指标条件排除的行。

groupingSets 会在一次扫描中，在主要结果旁添加独立的细分结果。每个集合都有自己的分组键和诊断信息，同时共享列读取和全局资源预算。compact 会减少重复的溯源信息，同时保留损失和歧义诊断。test/aggregate-analysis.spec.ts 中包含 2,000 行、15 列的商务回归测试，可在一个小于 8 KiB 的响应中检查总计，以及国家、类别、付款方式和 36 个月度细分结果。

指标的 round 会按 Excel 的 ROUND 规则将其数值结果舍入，遇到中点时远离零；排序使用未舍入的值。derived 会在聚合后，从每个组的指标计算最多四个值：分子和可选的分母各由若干 factor × metric 项求和得到，然后应用 scale 和 round。带有 scope: "total" 的项使用 maxGroups 之前所有组的指标总和，从而得到某个组占总量的比例；它只接受可加总的指标（count、countValues、countTrue、countFalse、sum）。分母为零时返回 null，并产生 derived_division_by_zero 警告。orderByDerived 可按其中一个派生值排序。pivotBy 不提供派生值。

请求的总范围指标会对各组进行带检查的补偿求和。无论是内联模式还是保留模式，若总计或中间派生计算结果不是有限值，调用都会因 numeric_overflow 被拒绝；不会发布任何保留标识符。缺失输入和零分母仍保持其 null 行为。只有被 scope: "total" 引用的指标才会计算跨组总计，因此未请求的总计不会导致有效的有限分组被拒绝。 inColumn 和 notInColumn 会保留单元格值属于或不属于另一个列的值的行。该列由 source 指定，可以来自同一文件或根目录下的其他文件中的工作表和列，并通过相同的权限检查打开。值的匹配方式与 eq 相同，不会去除空格；来源最多包含 100,000 个不同的值（maxSourceValues）。分别朝两个方向调用一次，即可得知一个列表中有哪些键，而另一个列表中缺少哪些键。这是筛选，不是联接：不会返回来源中的列。

继续处理完整的聚合结果

aggregate_sheet 已经会在现有处理预算内，对完整选定范围进行计算。默认的 resultMode: "inline" 保留现有响应：计算完成后，maxGroups 限制显示的分组数量。对于需要执行其他操作的大型细分，请传入 resultMode: "retained"。此选项明确且结果可预测；即使保留的结果很小，也会获得标识符，而普通的小型调用不会分配保留结果条目。

保留模式接受内联模式支持的所有聚合形态。数据透视表按每个分组一行进行存储，列顺序与内联数据透视表相同：分组键，然后是各数据透视键对应的指标（带有其 pivotKey），最后是派生指标。每个 groupingSets 条目都是一个独立结果，有自己的 resultId，并在响应中的 groupingSets 下列出，同时提供列、计数和预览行。主结果及其分组集要么一并准入，要么全部不准入。计算开始前会读取一次 inColumn/notInColumn 成员；如果这些成员来自其他文件，memberSourceVersions 会列出该文件捕获的指纹。完整计算仍使用现有的 SheetView、类型解释以及聚合状态／访问预算。失败时不会发布部分结果或标识符。不会更改工作簿，也没有代码执行 API。

返回的 resultId 标识所有已完成的结果行，这些行在响应字符串截断之前捕获，且不受 maxGroups 影响。query_result 可以按从 1 开始的位置选择原始结果列、应用以 AND 组合的精确标量相等筛选条件，并按原始聚合顺序读取分页结果。筛选会遍历完整的保留结果，不会重新打开、计算哈希或解析来源。相等比较区分大小写，不会去除空格、规范化、强制转换或按排名检索文本。存储的数值包含所请求的指标舍入；与内联模式一样，原始聚合顺序是在舍入之前确定的。此功能范围内不支持后续排序或重新聚合。

响应会区分以下范围：

Field	含义
sourceVersion, sourcePolicy	捕获的内容指纹和 snapshot 策略；源内容的编辑不会改变此结果
sheet, range, headerRow, scannedRows, matchedRows	原始源选择以及已完成的扫描／筛选计数
resultComplete, sampled	true 和 false：所选计算已完成，未进行抽样；这并不表示每个单元格都可用
totalRows	完整存储的结果行数，与预览无关
matchingRows, matchingSourceRows	所有匹配后续查询的结果行，以及这些结果行所代表的原始匹配源行
returnedRows, returnedMatchedRows	实际显示的结果行，以及这些结果行所代表的原始源行
offset, hasMore, nextOffset	匹配结果行中的分页位置和续页信息
preview	初始保留响应中为 true；后续分页中为 false
totalColumns	仅当预览只显示前面的列时才会提供；使用 query_result 的 columns 选择其余列
valueTruncation	按现有呈现规则缩短的显示单元格数量及其字符串限制

columnNumbers 将投影输出列映射回其原始的一基位置。 重复使用相同的 resultId、where 和 columns，并传入 nextOffset，直到 hasMore 为 false。 在此不可变结果和相同查询中，偏移量是确定的。更改筛选条件即定义了新查询，应从偏移量 0 开始。结果列的 counted、skipped、 filtered 以及单位／货币诊断描述完整存储的计算结果，即使分页仅投影较少的列或筛选较少的行也是如此。现有的 warnings、readAs、 columnStats、错误分布和未分组计数仍然可用；计算完成不会消除排除项、歧义或缺失的公式缓存。

所有权、生命周期与接纳

每个 createHandlers(root) 都拥有自己的存储。不可透传的随机标识符仅在该处理器实例及其已有的已配置根目录权限范围内有效。其他服务器实例即使使用相同的根目录，也无法读取这些标识符。除现有的实例范围外，没有租户、用户或会话授权层；共享同一服务器实例的主机也会共享该实例保留的结果。 元数据携带读取时报告的相对于根目录的 version.filePath，绝不会包含绝对路径。源文件变更或删除后，已接纳的快照仍可读取，直到过期；新的聚合会独立捕获当前源文件。

预算	上限与行为
完整结果	100,000 行、1,000,000 个单元格，以及 8 MiB 的已计量序列化数据；必须满足所有上限
每个实例的存储	四个有效结果，已计量序列化数据总计 16 MiB
生命周期	自接纳起绝对有效 15 分钟；读取不会续期
预览和分页	CallToolResult 序列化后不超过 16 KiB，包括元数据、封装和 JSON 转义；最多 maxGroups/maxRows，默认值为 50，最大值为 500
相等性输入	最多 16 个条件，每个字符串值最多 4,096 个字符

行值和所表示的源数量会逐步接纳，并在发布前计入元数据。这些序列化字节上限是计量上限，并不精确保证 JavaScript 堆或进程 RSS 的用量。行数、单元格和条目上限也限制了对象开销和查询工作量。源工作簿/缓存内存仍受其现有独立上限约束。

过期条目会在存储访问或接纳时删除，关闭服务器时会清空存储。空闲的过期分配可能保留到下次访问，但始终不会超出存储上限。没有磁盘存储、服务或后台计时器。容量耗尽时会返回 resource_limit 并保留有效结果；请等待过期、请求更少或更小的结果，或重启实例。未知、已过期、已清除及外部实例的标识符都会返回 result_unavailable，并提示通过重新运行保留结果的聚合来恢复。如果预览无法容纳所需元数据和一行数据，则会在接纳前失败。预览中的每个结果都会先保留一列，并在有行时保留一行；随后按顺序扩展为全部列，最后再按顺序增加行，因此宽透视表或大型主分组不会挤占分组集合的空间。如果后续行无法容纳，则会提供投影指导并失败，而不会返回无法推进的分页结果。每个响应仍会经过现有的 json() 构造函数、强制执行的 guard() 载荷检查，以及根目录脱敏错误封装。由于保留分配，aggregate_sheet 在其 MCP 注解中标记为非幂等；所有工具对源文件仍保持只读。

为什么现有限制仍然保留

分类依据是限制的执行点，而非常量的名称：

用途	现有示例和执行方式
处理／资源	原生的 50 MiB 工作簿和 16 MiB CSV 输入门槛；CSV 的 200 万单元格分词器上限；四项已解析文件缓存；OOXML 展开限制；aggregate 的 2000 万次单元格访问、10 万个分组、20 万个指标状态、100 万个精确样本／不同值，以及 1 万个密集数据透视表单元格
响应／上下文	maxGroups 对已完成的分组进行切片；搜索结果限制约束显示的匹配项，同时仍会统计完整搜索结果；512 个字符的单元格展示上限，以及 512 KiB 的输出文本负载保护
处理与响应／范围兼有	读取页面的单元格限制约束展示处理量和输出；配置文件的行／列／单元格上限会有意采样前缀；诊断／示例和图表数据点上限约束保留的报告状态和显示的详细信息

aggregate 执行是同步的，并通过访问次数和状态数量进行限制，而非新增墙钟时间期限。正则表达式有自己的工作线程、并发和超时限制，本次更改不影响这些限制。保留结果预算是额外限制，并不取代处理保护。这一区分遵循 context-mode 的先保留、后输出原则，但采用结构化的完整数值结果：文本片段无法证明完整总和，而 KV 缓存复用也不会减少新增响应内容占用的上下文。

可重复的 MCP 付费场景、独立预期值、外部语料库条目和命令位于 Excel 实验室 README。它会在不使用模型的情况下测量精确计数和序列化响应；不声称 Agent 能够成功完成任务，也不声称能节省令牌。未来的结果操作和写入能力已列入根目录的 路线图。 架构建议将当前各层映射到 Excel 的包、数据集和分析架构，指出一个已复现的派生总计溢出缺陷，并为现有工具的改进和可能新增的操作确定优先级。这些建议区分了审查发现和拟议行为；它们并非已实现的契约。

分析列并复用列解释

profile_sheet 默认抽样一个矩形前缀（1,000 行数据和 16 列），硬性上限为 5,000 行、64 列和 64,000 个单元格。它会报告抽样和省略的行数与列数。置信度是占主导的可读类型占非缺失抽样值的比例；它不是对未见数据的概率判断。每份分析都会报告格式、缺失数量、不同值数量、极值、常见值、不可读示例和标识符信号。每列的不同值追踪最多记录 1,000 个值；超过后，计数会变为下限，且报告的频次会明确标记为不完整。类型相同或含糊不清时，会保留为混合类型。

结果中的 columns 数组和 columnMode: "letter" 可直接传给其他表格工具。推荐的数字列始终包含 identifiers: "refuse"，因此即使前缀样本之外存在带前导零或较长的数字标识符，也仍会将其排除并计数。调用方明确指定的数字列仍采用此前默认值 identifiers: "read"。

推荐的日期方案会使用显式读取器检查每个抽样日期。如果不指定顺序的方案无法保留样本，则日优先列会采用 order: "dmy"，带点号的日期也会按日优先读取。月优先列则通过固定的数字模式指定，因为显式顺序也会改变样本之后带点号日期的解析顺序。如果单一显式方案无法表示观察到的混合格式，建议方案会保留文本类型并添加警告。后续不符合固定模式的值仍会保留原始值，并在类型化输出中计为不可读。调用方显式提供的日期规格会保留其格式和顺序。对于这些显式日期，readAs 和不可读诊断描述的是所请求的转换；推断类型、置信度和值分布仍描述观察到的样本。

read_sheet 会保留原始 values。显式指定 columns 并设置 includeTyped: true 时，它会添加一个并行的 typedValues 网格。缺失和不可读单元格只会在这个新增网格中变为 null；typed 诊断会区分两者，并提供数量有限的示例。未指定的列会保留原始类型。解释、区域设置和字面值列表会随游标传递；冲突选项会被拒绝。使用 columns 调用 find_in_sheet 时，会在这些列中搜索规范化值，返回原始 value 和 typedValue，并统计扫描到的非空单元格中的转换失败数量。不指定 columns 时，搜索会沿用原有的原始文本行为。

describe_workbook 中的 typedValues 能力描述的是单元格原生存储类型。CSV 会报告 false，因为其中的单元格都是文本；仍可显式进行类型化读取。已知文件和列可直接读取或聚合。列出文件、描述工作簿和分析数据，都是为了发现调用方尚不了解的信息。

区域设置、缺失值、布尔值和时长

CSV 解码支持显式指定 UTF-8/UTF-16、Windows-1251/1252/1254/1256、ISO-8859-9、Shift_JIS、GB18030、Big5 和 EUC-KR。绝不会猜测旧式编码，并会拒绝格式错误的多字节序列。分页游标会保留相同的编码选择。 第一条解码后的物理行如果恰好是 sep=X 或 "sep=X"，则声明使用逗号、分号、制表符或竖线作为分隔符。sep 关键字接受 ASCII 大小写变体；空白字符、其他分隔符以及后续相似内容仍视为普通数据。制表符必须是实际字符，不能是两个字符的写法 \t。选择表头以及统计记录、不规则行、空白行和类似公式的内容之前，会移除已识别的行。移除后，第一条记录是工作表第 1 行；语法错误仍报告物理文件行号，而 csv.lineBreak 包含声明行的行尾符。未显式指定分隔符时，csv.delimiterSource 为 "sep"。显式指定的 delimiter 优先，且来源仍为 "explicit"；如果声明与之冲突，会添加警告，但仍会移除该声明。首先执行 BOM 和严格解码检查。参见 CSV 配置方案。

显式指定的数字列可以提供 locale 和 numberingSystem，而不是小数和分组标记，例如 {"column":"Amount","type":"number","locale":"ar-EG","numberingSystem":"arab"}。十进制数字系统、本地分隔符、正负号和分组大小均根据运行时的 Intl 数据编译，包括印度式 3+2 分组。不支持的区域设置或数字系统会被拒绝。日期列接受固定的 format、显式的 order 或无歧义日期。显式指定的区域设置会提供公历月份名称，包括格式形式和独立形式，但不会决定日/月顺序：推断的斜杠和连字符日期根据列中的值确定顺序，而推断的点分隔日期在所有区域设置下都采用日优先约定。如果某个点分隔值只能按月优先解读，则推断结果有歧义；斜杠日期无论按哪种顺序都能解读时，点分隔日期仍按日优先处理。如果列中还包含会因推断出的月优先顺序而改变解读方式的点分隔日期，则 readAs 中不会包含该月优先顺序，并会发出警告。显式日期 order 也适用于点分隔日期；format 还会固定分隔符。区域设置指定的是文件的语言，而不是读取者的语言；如果使用该区域设置的分隔符会将某个值解读为与列自身标记不同的数字，警告中会指出该值。不支持非公历日历请求。省略区域设置会保留现有的确定性数字/日期推断行为，且绝不会选择主机区域设置。Unicode 十进制数字会被规范化，但带圈数字、罗马数字或任意兼容字符不会因此变成数值。

封闭的日期语法接受显式模式中的中文/日文 年 月 日、韩文 년 월 일 和俄文 г 标记，例如 yyyy년 M월 d일 或与 ru-RU 搭配的 d MMMM yyyy г.。这些完整标记形式不会自动推断。星期前缀、纪元和任意带引号的字面文本不属于支持的语法。

missingValues、trueValues 和 falseValues 是可配置列表，且支持按列覆盖。默认缺失标记为 N/A、NULL、-、— 和 #N/A。Null 和空白字符串始终视为缺失；missingValues: [] 会将其他标记保留为字面文本。存储的 Excel 错误仍是错误。真值标记为 true、yes、y、Evet 和 E；假值标记为 false、no、n、Hayır 和 H。调用方的列表会从另外两个列表的默认值中获取词项。只有当读取为布尔值或时长的值多于其他解读结果时，列才会读取为布尔值或时长，因此成绩 E 或零星的 100:30 不会导致整列重新读取。文本比较仍会匹配文本恰好是缺失标记的单元格：eq "N/A" 可查找 N/A。 匹配时会忽略大小写和重音，接受任意文字系统中配置的标记，并拒绝存在重叠的列表。数字 0 和 1 不会自动视为布尔值。countTrue、countFalse 和 trueRatio 基于有效布尔值进行计算；没有可读取的值时，比例为 null。 time 列会将 8:15 这样的时钟时间读取为 08:15:00。duration 列会将经过的小时数或固定的 ISO 日期／时间时长（例如 25:30 或 P1DT2H）读取为 {"durationSeconds":91800} 或 {"durationSeconds":93600}。日历年／月和闰秒会被拒绝。数值型时长指标以秒为单位，并报告该单位。自动读取时长要求列中有时长提示；纯时钟时间不会作为时长求和。百分比和千分比数量会作为分数处理，并附带单位元数据；货币标签会保留，不进行汇率换算。请参阅 CSV 配置文件操作指南以及仓库实验室中的可复现生成器／模糊测试说明。

命名表格和已保存的行可见性

read_sheet、profile_sheet、find_in_sheet 和 aggregate_sheet 接受 table: "Orders"。 该名称会选择工作簿中已声明的表格；sheetName 会限制查找范围。名称会进行 Unicode 折叠，遇到名称匹配不明确时会拒绝操作。所选范围为表格的数据主体，不包括表头和汇总行。列引用使用表格声明的名称，包括表头行处于隐藏状态时。表格不能与 range 或冲突的 headerRow 同时使用。没有声明数据行的表格，以及表头行／汇总行数量不受支持的表格，会被明确拒绝。已声明的主体即使仅包含空白单元格，仍可读取。

传入 visibleOnly: true 可省略已保存的隐藏行。这包括手动隐藏的行，以及作者应用 AutoFilter 后保存为隐藏状态的行。读取器使用这些已保存的标记，不会重新评估筛选条件。每个此类回答都会包含 visibility，其中有 basis: "savedHiddenRows"、hiddenRowsSkipped 和 filterCriteriaReevaluated: false，并在已声明相关 AutoFilter 范围时一并包含该范围。已保存但没有对应隐藏标记的条件不会移除行。Excel 中已保存的行可见性与筛选器定义是两种独立数据。

筛选后的读取会在 values 旁添加 rowNumbers，保留每行在工作表中的原始地址。游标会绑定 table 和 visibleOnly；省略的选项会沿用已有设置，冲突则会被拒绝。对于读取，hiddenRowsSkipped 统计已访问页面中的隐藏行；对于搜索和聚合，统计整个所选范围中的隐藏行；对于配置文件，则统计所选数据行中的隐藏行。配置文件的总数和抽样限制按符合条件的可见行计算；省略的隐藏行会单独报告。CSV 不支持表格元数据或隐藏行标记，因此 CSV 会拒绝 table 和 visibleOnly: true。

原生数字格式和富单元格值

原生数值单元格会保留其当前数字格式分段的含义。经过的 [h]、[m] 和 [s] 标记会返回秒数，包括负值和超过 24 小时的时长，不受工作簿日期系统影响。百分比格式会添加 unit: "fraction"，但不会缩放已存储的分数：0.25 仍为 0.25。显式货币标记会传递到聚合指标描述符中；含义不明确的货币符号会保留其符号标签。条件分段会先于标记解析进行选择，而带引号或转义的字面文本不会将普通数字变成日期或百分比。这是一个范围有限的语义读取器，而非完整的显示渲染器；不支持的格式语法会保留原生数值。这些规则遵循 Microsoft 的数字格式规范。

单元格内图片会返回包含可选 altText 和 decorative 字段的 imageId，而不是其 #VALUE! 兼容缓存。get_images 也会将其列出，包含 anchor: "inCell"、其源 cell 以及相同的媒体 ID。经过验证的富图片关系可以指向其他内部包路径；ID 在不同工作表和调用顺序之间保持稳定，不影响现有媒体 ID。绘图图片现在会保留其保存的替代文本。 支持的链接数据形状为 _linkedentity2：封闭的 linkedValue 对象包含保存的 displayText，以及（若存在）其实体 ID、区域设置和数字服务 ID。不会刷新任何链接提供方，不会下载外部图片，也不会展开嵌套属性包。 在应用显示限制之前，搜索会匹配完整的已保存替代文本或链接标签。 未知的富值类型会保留其存储的标量值，并附带明确标示不受支持的 richValue 说明； 引用的索引或关系链格式错误时，会以 corrupt_workbook 拒绝处理。 数组公式说明会保留锚点、声明的 ref、dynamic 标记以及可选的 collapsed 标记。缓存的溢出单元格会保留其值，并指向相同的数组锚点。读取器不会重新计算公式，也不会填充缺失的缓存。原生及由元数据支持的 #SPILL! 和 #CALC! 错误会附带说明，但不会猜测阻塞单元格或计算原因。固定的原始 XlsxWriter 和 Microsoft Open XML SDK 测试样例、独立 XML 验证器、许可证及经过验证的覆盖范围边界，均记录在 RICH_VALUE_SOURCES.md 中。

aggregate_sheet.errorDistribution 会在调用级和指标级筛选后，统计参与计算的不同原生错误单元格数量。重复指标、分组集和透视表不会增加同一物理单元格的计数。最多为 32 个代码各提供三个示例地址；其余或过长的代码会归入明确的 other 桶。数值、布尔值和极值指标会将 skippedErrors 报告为 skipped 的子集。存储的错误仍计入 countValues 和 countDistinct。 图片和受支持的链接值不会被归类为错误。

如何读取元数据

每个工具都通过 @sezzlee/ooxml-core 直接读取 OOXML 部件：单元格、数字格式、公式、超链接、合并区域和定义名称，以及数据验证、Excel 表格、条件格式、图片和冻结窗格。运行时不包含电子表格库。SheetJS 和 exceljs 是开发依赖：exceljs 用于写入测试样例，而单元格读取器会与 SheetJS 进行对照。 OOXML 部件由 @sezzlee/ooxml-core 自带的 XML 分词器以命名空间感知方式读取。匹配依据为 (namespace uri, local name)，不会查看文件中实际使用的前缀，因此在调用处，<x:dataValidation> 和 <dataValidation> 无法区分。关系会解析受支持的工作表、样式和共享字符串部件，包括带前缀的 .NET 输出，以及名为 sheet.xml 的工作表部件。目前要求工作簿根位于 xl/workbook.xml；不支持任意 OPC 工作簿根布局。

tool	source
get_data_validations	工作表部件，dataValidations/dataValidation。每条存储规则都是一个条目，不会与相同规则合并。范围直接取自 sqref，不会逐个打开单元格 — 覆盖整列的规则仍视为精确，因此 dataValidationRuleCountExact 始终为 true
get_tables	工作表 tableParts → 工作表关系文件 → xl/tables/*.xml。通过 colId 而非位置匹配 filterButton
get_conditional_formats	工作表 conditionalFormatting/cfRule。containsText 系列会解析为类型 + 运算符。cfvo type="formula" 阈值的表达式会保留在 formula 字段中
get_images	单元格 vm → 工作簿工作表元数据 → 富值结构和关系 → 单元格内图片的媒体文件。绘图图片使用工作表 drawing → 工作表关系文件 → xl/drawings/*.xml → a:blip r:embed → 绘图关系文件 → xl/media/*。会报告 twoCell、oneCell 和 absolute 所有锚点。只有双单元格锚点会获取 range；单单元格锚点会获取其左上角 cell 及以整像素为单位的尺寸，因为该尺寸覆盖的单元格取决于列宽；绝对锚点则只获取尺寸。get_charts 以相同方式放置图表
get_charts	工作表或图表工作表 drawing → 图表 / chartEx 框架 → xl/charts/*.xml，用于获取类型、标题、坐标轴（最小值/最大值/对数/数字格式）、系列引用和缓存点、趋势线及 pivotSource。每个元素都在其父元素下匹配，因此数据标签的 c:tx 永远不会被误认为系列名称。数字缓存以数字形式返回，文本缓存以文本形式返回，并带有缓存的 numberFormat；多级类别会保留其外层 levels。如果第一个绘图区未使用某个坐标轴，则该坐标轴为 secondary。c15:filtered*Series 下的系列会标记为 hidden。标记兼容性机制会选择一个 AlternateContent 分支。chartEx 会报告为 unsupported
describe_workbook 会将每个工作表的 kind 标记为 worksheet 或 chartsheet，并报告 chartCount。对于图表工作表，read_sheet、profile_sheet、aggregate_sheet、find_in_sheet 和 get_merged_ranges 会以 chart_sheet 拒绝请求，并将恢复操作指向 get_charts。未指定 sheetName 的调用会落在第一个可见的工作表上，绝不会落在图表工作表上；但 get_charts 除外，它会选择任意类型中第一个可见的工作表。数据透视表和迷你图仍不可读取。get_images 使用 kind: "chart" 时，仍会返回 unsupported_object_kind，并将请求指向 get_charts。

损坏文件的错误分为三个代码，彼此不能替代：not_a_workbook（不是 zip 存档，或 zip 中没有工作簿部分或工作表）、encrypted_workbook（OLE2/CFB 文件头——表示受密码保护或为旧版二进制文件）和 corrupt_workbook（存档已损坏：某个部分未通过 CRC-32 校验、本地文件头与中央目录不一致，或者某个部分不是格式良好的 XML 或有效的 UTF-8）。只有读取受损工作表的调用会拒绝该工作表，因此工作簿中的其他工作表仍可读取。CSV 由服务端自己的 RFC 4180 分词器拆分为记录；在引号外，CRLF、LF 和 CR 都会结束一条记录。引号格式错误会返回 corrupt_workbook，并指出错误及其所在行；这类错误绝不会被修复。internal_error 不带 recovery：没有已知的后续调用；假装有这样的调用，只会让 Agent 去修复一个实际完好的文件。

开发

pnpm turbo run build --filter=@sezzlee/excel-mcp
pnpm turbo run test --filter=@sezzlee/excel-mcp
pnpm turbo run check-types --filter=@sezzlee/excel-mcp

请通过 Turbo 运行测试，不要使用 pnpm --filter @sezzlee/excel-mcp test：单独使用 filter 会跳过 dependsOn: ["^build"]，而此包通过 exports.default → ./dist/index.js 解析 @sezzlee/file-core，所以单独使用 filter 可能会针对过期的 dist 运行测试。

对工具参数、错误代码或限制的更改会影响 apps/docs 中生成的参考文档；请运行 pnpm --filter @sezzlee/docs gen 并提交生成结果，否则 pnpm turbo run validate --filter=@sezzlee/docs 会失败。

批量作业契约

批量工具要求使用下文所述的显式写入模式。prepare_bulk_job 和 run_bulk_job 使用相同的作业描述符。依赖类型为 dependent 时，包含一个组 {steps, outputs}；独立类型为 independent 时，包含作业列表 jobs [{id, group}]。步骤按声明顺序执行，且只能引用较早步骤的 ID。缺少或重复的 ID、无效的后续步骤以及不安全的输出依赖关系，都会在发布前导致请求被拒绝。准备过程会对实际编辑器进行试运行，重新验证每个原始源，并返回精确的组标识；它不会授予授权，也不会冻结可变文件。

每个步骤都使用 kind。读取步骤会选择一个确切的源 {filePath, versionId}，该源通过 prepare_transfer 获取或来自保留的收据；并包含一个嵌套选择 {kind: records, sheetName, range, headerRow}。区域是闭合的，并且从正整数 headerRow 开始；命名表使用其声明的表头。CSV 值会保留为文本，除非 selection.columns 明确指定读取方式，例如 {column: Total, type: number, decimal: "."}。现有的完整选择、已保存缓存和显式行子集规则均适用。所有批量运算符都处理类型化值；它们不会计算公式或创建样式。

支持的步骤：

• 更新会使用 set [{column, value: {kind, value}}] 和传输式 where 条件来指定单元格。移除操作必须使用 clear 或 delete_rows；筛选会生成数据集，而不会隐藏或删除源行。
• keyed_update 和 upsert 会指定源步骤 ID 和目标步骤 ID，以及由 {sourceColumn, targetColumn} 组成的 keys/set 数组。键会保留类型、大小写、空白和 Unicode 规范化形式。默认情况下，缺失键和重复键会阻止操作。显式设置 missingKeys: skip 和 duplicates: first/last 可更改这些规则，并会计入数量。Upsert 必须为每个插入的目标字段提供映射。拒绝重新分配键。
• replace 会组合目标列表和替换数据集。使用 edit/replace_values 输出时，会清除整个旧尾部、保留格式并保留外部内容。标头和记录数都必须明确指定，包括空替换。
• append 会遵循声明的输入顺序和明确指定的输出列列表；名称不同时，必须先进行投影或重命名。缺失字段必须显式设置 missingColumns: blank。不会自动扩宽类型。
• join 支持 inner/left/full，必须明确指定左右键映射和输出列 {side, column, as}。重复项必须指定处理规则；manyToMany 必须显式声明，并且扩展量会在发布前受到限制。未匹配的外连接字段会使用带类型的空白值。
• deduplicate 必须指定键和 keep: first/last/drop_all/report/duplicates_only。report 会保留数据集并报告数量；duplicates_only 会生成实际的重复记录。缺失键必须显式指定保留或分组行为；默认会阻止操作。
• sort 是稳定的，并且必须为每列指定排序方向和空白值位置。混合类型必须显式指定 type_order，否则会拒绝操作。默认文本比较使用确定性的 UTF-16 顺序；区域设置排序需要使用可用的显式区域设置。
• project 会选择、重命名并排序字段，且会拒绝重复的输出名称。transform 支持类型化常量、trim、使用显式区域设置的大小写转换，以及现有的显式数字/日期/布尔值/文本读取约定。除非 onError 显式选择 blank 或 keep，否则转换错误会阻止操作；失败次数会计入统计。排除仅含时间/时长的输出和任意脚本。

输出可以是 new、edit 或 edit_workbook。new 输出会根据数据集步骤 ID 构建命名工作表；它是仅含数据的报告，不会携带无关的源文件部分。edit 会指定原始目标读取 ID 和最终输入数据集 ID。changed_values 会保留未修改的单元格、公式和受支持的包内容；物理行标识会保留。已保存值相同的单元格会保留现有公式。重新排序、筛选掉记录、删除记录的去重操作、标头更改和整个列表替换都需要显式使用 replace_values。此模式会有意写入声明列表中的值（包括已保存的公式结果），同时保留样式。保留公式的复制绝不会静默回退为仅写入值。edit_workbook 会合并同一个精确原始工作簿中不同工作表的编辑；写入前，同一工作表的更改会在单个数据集流水线中合并。

更改占用区域时必须显式指定 overwrite。将列表扩展到其声明范围之外的占用内容时，会拒绝操作。如果待删除的物理行在所选列之外还包含内容，则会拒绝删除，并且仍须通过 Phase 3 的结构依赖项保护机制。基本命名表会保留名称/列，并在替换或扩展行时更新其范围/筛选元数据。调整带汇总行的表格大小、更改表格列名称/宽度以及影响不受支持的依赖项时，会拒绝操作；请改用明确支持的结构编辑。公式缓存和图表/数据透视表刷新事实沿用 Phase 3 的行为，不声称会重新计算。 一个依赖组会先在内存中完整准备好，包括所有输出，然后由通用原生功能以不替换的方式发布整个目录。最终作业目录会同时包含所有工作簿及其完成清单。进程／系统故障后可能会留下内部 .pending-* 目录；它们绝不会被视为完成记录或返回的输出版本。原始文件和保留的输出均保持不可变。不会将逐个文件重命名的流程描述为原子组操作。重试时会先验证已提交的结果，再重新读取原始文件，因此即使原始文件随后发生变化，响应丢失／进程重启也不会导致再次追加或 upsert。首次提交前源文件发生变化时，需要重新进行精确选择。

独立作业有各自的提交边界，并会返回 complete／partial／failed／pending 状态，以及精确的每个作业输出和计数。重试会复用已完成的子作业，只尝试尚未完成的子作业。持久化状态中，已验证的完成状态优先于保留的失败状态。失败诊断会标明 current_attempt 还是 first_failed_attempt，以及该诊断是否已保留；诊断写入失败不会丢弃成功的独立输出。get_bulk_job 会验证每个输出的哈希，并拒绝损坏的完成记录。计数描述每个操作符的输入／输出数据量；连接扩展和重复项跳过不构成一个全局求和等式。清单中会保留详细的步骤计数，而不会保留完整源记录。

每个组的回执上限为 128 KiB。大型批次会返回已完成的子作业及 details: summary，其中包括其组作业 jobId 和输出／步骤计数；如需获取完整的已验证回执，请使用该子作业的 jobId 调用 get_bulk_job。较小的批次使用 details: full。接受重试前，会根据已存储的请求验证完成项清单。

作业防护配置文件有明确限制：每组 32 个步骤、16 个独立作业、每组 16 个输出、8 个源快照、每个数据集 100,000 条记录、256 列、每个数据集 1,000,000 个单元格、中间数据合计 2,000,000 个单元格、快照／文本预算合计 64 MiB、序列化键候选项 16 MiB、谓词／连接／排序访问次数 20,000,000 次、展开后的编辑变更 256 项、描述符 64 KiB，以及包含清单在内的输出组 50 MiB。旧版 128 次操作的编辑 API 保持不变；独立的批量展开上限会在内部强制执行。这些是拒绝处理的上限，不是吞吐量保证。实测正确性、规模和验收范围请参见 Phase 4 计划。

可选写入模式

默认仍为读取模式。若要启用写入，请指定工作簿根目录下一个已存在的输出目录：

mkdir -p /absolute/workbooks/out
sezzlee-excel /absolute/workbooks --write out

这会增加六个仅操作自身输出的工具、四个只读准备工具和一个只读状态工具。它们绝不会覆盖源文件或已有输出。单版本名称使用 SHA-256 内容版本；批量组使用不可变作业目录，其中包含内容寻址的工作簿和完成清单。相同请求会复用已验证的输出。所有写入模式工具共用每个服务一个准入槽位。

工具	行为
create_workbook	根据非空的有序命名工作表列表创建不可变的 .xlsx 文件。每个工作表可包含带有明确 A1 startCell 的矩形数据块。空工作表省略数据块。
calculate_workbook	根据确切的源版本计算受支持的公式子集，返回有界结果和诊断信息，并将带类型的缓存保存到新的不可变 .xlsx 文件中。
edit_workbook	原子化编辑确切的 .xlsx 版本：值、清除、工作表、范围和行/列，同时保留受支持的现有内容及依赖项。
create_workbook_version	验证并准备现有 .xlsx 文件的不可变副本，不更改工作表或单元格。可选的 expectedVersion 会拒绝已更改的源。复制外部工作簿不会使其符合 Phase 1 编辑条件。
prepare_transfer	从 .xlsx/.xlsm/CSV 中选择完整范围值、经过筛选/投影的记录或分组汇总。返回固定到版本的传输引用及计数，不返回数据集，也不写入文件。
prepare_edit	对确切源版本执行完整编辑的试运行，返回策略阻止项或就绪的保留配置文件，不发布内容。
transfer_data	在内部实现所选内容，并将其发布到新工作簿、新工作表或选定的自建工作表。若源已更改，或目标已被占用且未明确指定覆盖，则会拒绝；支持按位置或唯一表头映射。
prepare_bulk	分析确切的源/目标记录版本以执行键控更新或 upsert，返回有界键冲突和预计影响，不写入数据。完整执行请使用批量作业工具。

批量作业工具使用相同的显式写入模式：

工具	行为
prepare_bulk_job	验证所有有序步骤，并对每项输出执行试运行，不发布内容。
run_bulk_job	原子化提交一组依赖输出，或运行相互独立的分组，并明确报告部分成功且支持恢复后重试。
get_bulk_job	读取持久化的完成状态并验证输出哈希，不重新运行作业。

create_workbook 输入：

{
  "sheets": [
    {
      "name": "Expenses",
      "blocks": [
        {
          "startCell": "A1",
          "values": [
            [
              { "kind": "text", "value": "Item" },
              { "kind": "text", "value": "Amount" }
            ],
            [
              { "kind": "text", "value": "00123" },
              { "kind": "number", "value": 12.25 }
            ]
          ]
        }
      ]
    }
  ]
}

结果包含 kind: complete、version: { filePath, versionId }、source 和 sizeBytes。创建/编辑结果还包含 changes: { sheetsAdded, blocksWritten, cellsWritten }。结果绝不会回显所有单元格。对于 edit_workbook，将返回的版本作为 source 传入，然后传入 changes 数组，例如：

{
  "source": { "filePath": "out/<sha256>.xlsx", "versionId": "<sha256>" },
  "changes": [
    { "kind": "add_sheet", "name": "Income" },
    {
      "kind": "write_cells",
      "sheetName": "Expenses",
      "startCell": "B2",
      "overwrite": true,
      "values": [[{ "kind": "number", "value": 20 }]]
    },
    {
      "kind": "write_cells",
      "sheetName": "Expenses",
      "startCell": "A3",
      "values": [
        [
          { "kind": "text", "value": "Next" },
          { "kind": "number", "value": 30 }
        ]
      ]
    }
  ]
}

该请求中的每项操作都必须成功，版本才能发布。未设置 overwrite: true 时，已填充的目标单元格（包括内容为空的文本）会导致失败。在获准替换时，blank 会显式清空单元格；它不同于值为空的文本。重复的工作表名称会被拒绝。追加操作会写入明确指定的起始单元格；不会插入行，也不会移动总计。针对同一输出，必须基于同一源版本重试完全相同的编辑操作。系统不会隐式查找最新版本。

单元格类型包括文本、数字、布尔值、空白、日期和日期时间。文本会按原样保留，包括前导零和看起来像公式的字符串。可能丢失 Excel 精度的数字、不安全整数、非有限值和不支持的数量级都会被拒绝；长标识符应明确选择文本类型。日期范围为 1900-01-01 至 9999-12-31。日期时间为本地墙上时间，精确到秒，可选精度为毫秒，不带时区。ISO 日期单元格要求 Office 2010 或更高版本。可通过下方明确列出的 Phase 3 模式复制现有公式和格式。公式/样式编写、专家报告操作和受限计算详见上文的编写部分。

初始限制为：每个请求触及 1,000,000 个单元格，每个工作簿存储 1,000,000 个单元格，64 张工作表，128 个区块/更改，32 MiB 存储文本，以及 64 MiB 序列化输入。现有的 50 MiB 文件上限和 OOXML 包预算也适用。写入使用单独的原生输出能力，源读取则保留现有的原生沙箱。详情和验证证据：Phase 1、执行计划、Phase 0。

要进行批量键分析，请调用 prepare_bulk，传入包含精确 filePath/versionId 引用和选择对象的源与目标，以及 kind 为 keyed_update 或 upsert、包含 keys 和 set 映射的 operation。可从 prepare_transfer 或保留的回执中获取版本引用。每个映射都使用 sourceColumn/targetColumn，并填写完全匹配所选标题的名称。只能选择一种：从 headerRow 开始的闭合范围，或带有其声明的 headerRow 的命名表。源筛选条件、显式物理行子集、列投影和读取提示沿用传输语义；目标必须选择其完整的声明列表，且不得使用筛选条件、可见性限制、子集或投影。空白行不包含记录；冲突记录编号指所选非空记录中的一基位置，而非工作表行号。

键标识会保留单元格类型、大小写、空白字符和 Unicode 规范化形式。空白/空文本键和重复键会阻止处理任一输入，最多提供 8 个示例，并提供完整冲突数。显式读取提示可以转换源值；系统不会隐式规范化键。键列不能重新分配。更改已占用的值需要 overwrite: true；赋值相同的值会计为未更改。如果存在未匹配的源记录，upsert 要求为每个目标列提供映射。此专用工具仅接受 conflictPolicy: error；完整批量作业支持显式的 first/last 规则。现有的源值传输拒绝规则也同样适用：错误、不支持的值和缺失的公式缓存。

prepare_bulk 仍是专用的键分析工具：其验证类型为 keys_and_target_policy，且 executionAvailable 为 false。它本身不会验证每项变更所依赖的所有条件，也不会发布文件。完整执行由下方的 prepare_bulk_job/run_bulk_job 提供。返回前会再次检查两个源版本。受阻结果会指出目标策略阻止项，或受限的记录/标题/映射冲突。requestFingerprint 会绑定精确的源和规范化后的操作；它不授予任何授权。此专用准备流程允许每个输入最多包含 100,000 条记录、合计 1,000,000 个已选单元格、合计 32 MiB 文本、16 MiB 序列化键候选，以及 64 KiB 描述符。 每个读取结果都包含 version: {filePath, versionId}，即已解析的确切字节的 SHA-256。将其作为 source 传给 edit_workbook，或作为 expectedVersion 传给 prepare_edit，这样编辑就会应用于读取时的字节；如果文件自读取后发生变化，则会以 file_changed 拒绝操作。读取结果还会以编辑所需的形式标明目标：describe_workbook 的 definedNames 会提供 name、scope、sheetName，以及对于单个普通区域的 range，可用于 define_name/delete_name；get_charts 的 series data 会提供 sheetName 和 range，可用于 set_chart；get_images 会提供 remove_image 要选择的绘图名称；get_data_validations 的 ranges 可传给 remove_validation 的 ranges；get_conditional_formats 的 priority 可传给 remove_conditional_format。

从来源写入行

create_workbook block、write_cells 和 insert_rows 接受 source 而非 values，因此可以通过引用写入读取操作计算出的行，无需重新输入：

source.kind	写入的行
result	保留的 aggregate_sheet 结果；columns、where 和 offset 与 query_result 中相同，maxRows 最多可取整个结果
range、records、aggregate	prepare_transfer 对同一类型的选择，针对 filePath，如提供 versionId 则固定到该版本

写入的 block 以来源自身的标题行开头：result 或 aggregate 的列标签，或者 includeHeaders 为 true 时的 records 标题。header: [...] 会替换该行，或在 range、无标题来源上方添加一行，并且必须与所选宽度一致。值会按 transfer_data 写入的方式作为类型化单元格处理：数字仍为数字，空白仍为空白；如果分组列明确以 date 读取，或其指标报告 kindUsed: "date"，则保留的日期仍为日期。如果来源未选择任何行且没有标题，则会拒绝操作。每次请求中，每个来源文件只读取一次，并会在发布前再次检查；回执会列出 sources，其中包含每个 block 的位置、kind、version 或 resultId，以及行数和列数。如果某个字面量 block 中连续三行都重复了此服务器实例中某个保留结果的行，则会以写入这些行的 source 拒绝操作。

准备编辑时，调用 prepare_edit，并传入 filePath、可选的 expectedVersion 和完整的 changes 数组。此操作会使用与 edit_workbook 相同的编辑器进行试运行，包括检查占用情况、引用和预算，但不会发布更改。就绪结果会返回 source、requestFingerprint 和 profile（canonical_values 或 preserved_package）。将 source 和相同的 changes 发送给 edit_workbook；执行时会重新检查所有选定来源的版本。此指纹仅用于标识诊断信息，并非保留的授权令牌。 编辑请求中的每个工作表名称和 A1 地址都指向读取时的源工作簿；任何更改都不会看到其他更改的结果。编辑器先取消保护，然后添加和复制工作表（复制操作读取的是读取时的源工作簿），接着在其源坐标处更改内容和呈现，之后从下往上插入和删除行列，再写入插入行的内容，最后重命名、删除和重新排序工作表并设置保护。insert_rows 接受 count 或 values，以及可选的 startColumn；values 中的公式单元格会为其所在的插入行写入 {row}（B{row}*C{row}），其他地址均使用源坐标。若某种组合的结果取决于更改顺序，则会被阻止，prepare_edit 会指出每项受阻更改：修改另一个更改要删除的单元格（target_deleted）、复制或移动的单元格（overlapping_writes）、在同一位置插入或在已删除区段内插入（conflicting_structure），以及新建或重命名的工作表使用了源工作表或其他新工作表正在使用的名称（name_conflict）。如果某个工作表在同一请求中被重命名为所用的名称，则该工作表属于 unknown_sheet。prepare_edit 和编辑回执会返回位置：每个目标移动或重命名后的输出工作表及范围。

保留配置文件支持 write_cells 和 clear_contents；add_sheet、rename_sheet、reorder_sheet、copy_sheet 和 delete_sheet；copy_range 和 move_range；insert_rows、delete_rows、insert_columns 和 delete_columns。工作表操作使用 sheetName 标识（add 使用 name）；rename/copy 还需要 name，reorder 需要从 1 开始的位置，行列结构操作需要从 1 开始的 at 和 count，但 insert_rows 也可以携带 values。范围使用显式的闭合 A1 范围；copy/move 还需指定 targetSheet 和 startCell。目标位置已占用时，必须设置 overwrite: true。Clear 会保留单元格样式，不会移动单元格。至少须保留一个可见工作表。

复制操作要求指定 mode：values、formulas、formatting 或 all。Values 会复制字面值/已保存值；formulas 会复制现有公式和常量，但不复制源样式；formatting 会保留目标内容；all 会组合支持的内容和格式。完整工作表的 all 复制会复制其支持的表格/绘图/图表关系图；范围复制不会重复创建这些工作表级对象。可以复制完整的合并范围；部分合并、重叠范围以及部分相交的传入移动引用都会明确报错。copy_range/copy_sheet 可选的 from: {filePath, versionId} 用于选择另一个不可变工作簿。跨工作簿复制要求样式/主题配置文件匹配，且数字日历系统兼容；不支持的配置文件或外部命名/工作表绑定将被拒绝。不会回退到仅复制值的模式。

支持的常规 A1 公式、混合/绝对轴、作用域名称和从属范围会与结构性更改一并转换。受影响的不支持的结构化/外部/3D/溢出引用、共享/数组组编辑、富元数据或未知依赖项会导致整个事务被拒绝。公式不会被计算：更改后的工作簿会使过期缓存/计算链失效，并报告 editing.recalculationRequired、recalculated: false 和 refreshRequired。Values 模式下的已保存结果会明确计数。选择较早的保留版本，可撤销整个组合请求或分支；源文件和之前的输出保持不变。

编辑支持 Transitional .xlsx，包括受支持的非规范部件路径。不支持宏、加密、已启用的工作簿/工作表保护、写入保留、签名和 Strict 标记。无关部件的有效载荷会保留其原始字节；ZIP 容器字节可能发生变化。Phase 3 计划记录了各操作的限制和验收范围。 如需传输值，请调用 prepare_transfer，并传入 filePath 和 selection，然后将其返回的 transfer 对象原样传给 transfer_data。例如，selection {"kind":"records","headerRow":1,"selectColumns":["ID","Amount"]} 会按指定列顺序选择每条数据记录，即使先前的读取只显示了预览。显式指定子集时，使用 scope {"kind":"rows","rows":[2,4]}。目标 {"kind":"new","sheetName":"Export"} 会创建一个新工作簿；目标 kind 为 add_sheet 或 sheet 时，还必须提供与所选目标版本完全一致的 source。若要将表头映射到现有列表，请将 includeHeaders 设为 false，并使用目标映射 {"kind":"headers","headerRow":1}；startCell 用于指定目标起始行。

范围传输会保留明确请求的空白单元格，而不会按 usedRange 裁剪。CSV 以及看起来像日期或公式的字面文本都会保留为文本，除非列明确要求进行解释。公式单元格只会提供已保存的结果；简要回执会报告 cachedFormulas 和 recalculated: false。缺少公式缓存、错误、富值、时长、仅含时间的值，以及现有写入器无法安全表示的数字，都会导致明确失败。现有 .xlsx 传输目标现在使用保留编辑器；transfer_data 仍用于传输值，而 edit_workbook 提供公式和样式复制功能。描述符大小、扫描和输出预算会在发布前生效。有关完整的支持范围和证据，请参阅 Phase 2 实施与验证计划。