企业官网建设流程全解析

• 人工智能
• AI 应用
• 桌面应用
• AI Agent
• MCP 服务
• AI 技能

本文聚焦 genoffice 仓库中packages/pptx-ops的表格编辑 Op（operation）契约。它是一份"模型可调用"的命令词汇表——AI Agent（Claude Code、Codex、Cursor）与脚本通过统一的事务执行器runTxn向 .pptx 表格下发setTableCell、tableMerge、tableStructure、setTableStyle等指令，即可完成从单元格文字改写、行列增删、合并拆分，到行高列宽、单元格垂直对齐、乃至套用 PowerPoint 74 种内置样式与 8 种固定色预设的全部编辑需求。读完本文，你将掌握每个 Op 的字段语义、合法取值、典型 JSON 载荷、易错点，以及这些 Op 在源码层的验证与执行路径。

概述：表操作在 pptx-ops 中的定位

在 genoffice 的架构里，编辑 .pptx 不是直接操作 XML，而是通过一组规范化编辑 Op（canonical edit ops）完成。packages/pptx-ops/src/ops/registry.ts中的注释把它概括为"统一写契约的第一块切片"：模型是执行器的私有财产，Op 才是对外公开的契约。每个 Op 在规划阶段（validate）先做类型与取值校验，在执行阶段（apply）修改引擎模型，并返回一条带 before/after 的记录供事务日志使用。

表格相关的 Op 全部集中在 prompts/ops/table.md，对应的实现位于 ops/table-ops.ts。它们覆盖表格编辑的四大维度：

• 单元格内容：setTableCell重写单个单元格的文字与段落格式；
• 网格结构：tableMerge合并/拆分单元格，tableStructure增删行列；
• 几何尺寸：setTableRowHeight、setTableColWidth控制行高列宽（EMU 单位）；
• 整体外观：setTableCellAnchor设置单元格垂直对齐，setTableStyle套用样式预设、内置样式或逐项定制区域标志、底纹与边框。

这些文档不仅是给人看的参考，更是直接喂给模型的素材。op-docs.ts在导入期解析prompts/ops/*.md，生成OP_DOCS、opVocabulary()、opSignatureIndex()与opGuide()四个衍生视图：词汇表与签名索引告诉模型"有哪些 Op、长什么样"，load_guide按需加载整组文档（含字段表、示例、常见错误），而 Op 失败时的 Guided Error 会追加该 Op 的一行Usage签名，让模型在首次犯错时就能自纠。配套的测试（见 tests/）还断言文档必须与注册表完全同步、每个 JSON 示例都能通过干跑校验，确保文档不漂移。

目标寻址与坐标系

所有表格 Op 都使用统一的target:{slide, el}寻址，其中el是表格元素的 id（在大纲中类型为table）。row和col均从 0 开始计数。从resolveElement（registry.ts）的实现可以看到，目标解析失败时会抛出带完整候选列表的 Guided Error，例如no element "e_TABLE" on slide 0. Available: [...]——这是刻意的设计：引导性错误是契约而非风格选择，模型收到"缺什么 + 有哪些可用项"的信息后会自动修正，而面对一句光秃秃的失败信息只会盲目重试。

一个值得注意的例外是图表编辑：setChart虽然登记在同一个注册表中，但标记为(not-ai-callable)，模型不可直接调用，必须走拥有校验 Schema 的edit_chart工具。这是因为图表的 patch 载荷结构复杂，交给专门的工具入口更稳妥。

setTableCell：重写单个单元格文字

setTableCell用段落数组替换一个单元格的全部文本，签名与setText完全同构：

{row,col,paragraphs}

参数说明：

示例载荷：

{ "op": "setTableCell", "target": { "slide": 0, "el": "e_TABLE" }, "row": 0, "col": 0, "paragraphs": [{ "runs": [{ "text": "Metric", "bold": true }], "align": "center" }] }

底层行为：为什么"不重排样式"能继承格式

文档强调："Runs you do not restyle inherit the cell's current formatting, so plain{text}runs keep size, color and bold." 这句话的实现要点在 table-ops.ts 的apply分支：它先取出目标单元格(row, col)的现有段落cell.text.paragraphs，再通过applyEditParagraphs把新内容重建到当前段落之上——这与setText对形状的处理方式完全一致。调用方无法表达的 run/paragraph 属性（字号、颜色、字体、加粗、项目符号、主题链接）因此保留在单元格里，而不是回落到表格样式的默认值。

此外，编辑会话期间切换的段落级属性（项目符号、行距、段前段后距、RTL）会作为逐段 patch 直接应用到重建后的段落上，因为表格的setElementParagraphFormat是表级操作，不能用于单格。执行前，validate会检查row、col与paragraphs是否为期望类型；若单元格越界，editTableCellText返回失败，Op 抛出cell (r, c) does not exist on table "e_TABLE"的引导错误，其中明确报告失败的 (row, col)。

常见错误

• 把单元格文字直接传成字符串——它必须是段落数组；
• 行列越出网格——Op 会报出具体的 (row, col)。

tableMerge：合并与拆分单元格

{kind:"merge-right"|"merge-down"|"split",row,col}

将(row, col)处的单元格与其右侧或下方相邻单元格合并，或把已合并的单元格拆回其网格单元：

{ "op": "tableMerge", "target": { "slide": 0, "el": "e_TABLE" }, "kind": "merge-right", "row": 0, "col": 0 }

从 table-ops.ts 可以看到，apply调用 pptx-engine 的mergeTableCells，返回失败时抛出tableMerge: {kind} is not possible at ({row}, {col}) — check merge boundaries。关键行为：合并会触发幻灯片重解析（reparse），从而重新生成元素 id——因此该 Op 在返回记录after中携带存活的元素新 id，调用方据此保持选择状态。

常见错误

• 跨越已有合并边界进行合并——Op 会拒绝；请先kind:"split"拆开再合并。

tableStructure：行列的增删

{kind:"insert-row"|"delete-row"|"insert-col"|"delete-col",index,before?}

插入或删除一行/一列。插入默认插在index之后，除非before:true：

{ "op": "tableStructure", "target": { "slide": 0, "el": "e_TABLE" }, "kind": "insert-row", "index": 1 }

{ "op": "tableStructure", "target": { "slide": 0, "el": "e_TABLE" }, "kind": "delete-col", "index": 0 }

实现走editTableStructure（table-ops.ts），失败时错误信息tableStructure: {kind} at index {index} failed (merges crossing the boundary?)直接点出最常见的根因。与tableMerge相同，结构变更也会重解析幻灯片并报告存活元素的after.elementId。

常见错误

• 带合并单元格的表拒绝行列手术：先用tableMerge的kind:"split"拆开所有跨边界的合并。

setTableRowHeight 与 setTableColWidth：EMU 单位下的行高列宽

setTableRowHeight: {row,hEmu} setTableColWidth: {col,wEmu}

设置某行高度/某列宽度，单位为 EMU（表框会随之伸缩）：

{ "op": "setTableRowHeight", "target": { "slide": 0, "el": "e_TABLE" }, "row": 0, "hEmu": 457200 }

{ "op": "setTableColWidth", "target": { "slide": 0, "el": "e_TABLE" }, "col": 0, "wEmu": 2743200 }

关于 EMU 单位的实用换算

EMU（English Metric Unit）是 OOXML 的文档空间单位，1 英寸 = 914400 EMU。虽然这两个 Op 的字段签名要求整数 EMU，但整个 pptx-ops 体系在units.ts（ops/units.ts）中提供了带单位后缀的长度解析：2.54cm、1in、10mm、12pt、96px、914400emu都会被归一化为 EMU 整数（px 按每英寸 96 计算），适用于所有…Emu字段与几何键。常用换算速查：1 pt = 12700 EMU、1 cm = 360000 EMU、1 mm = 36000 EMU。示例中的457200即 36 pt（约 0.5 英寸）行高，2743200即 216 pt 列宽。底层由 pptx-engine 的setTableRowHeight/setTableColWidth执行，越界行/列会得到带具体编号的引导错误。

setTableCellAnchor：单元格内文字垂直对齐

{row,col,anchor:"top"|"middle"|"bottom"}

设置一个单元格内文字的垂直对齐方式：

{ "op": "setTableCellAnchor", "target": { "slide": 0, "el": "e_TABLE" }, "row": 0, "col": 1, "anchor": "middle" }

validate（table-ops.ts）会先检查row/col存在，再校验anchor必须是top/middle/bottom三者之一，否则抛出needs "anchor": top/middle/bottom。注意它只控制垂直方向；水平对齐（左/中/右）属于段落格式，由setTableCell的paragraphs[].align负责。

setTableStyle：整表样式控制的核心

setTableStyle是表格 Op 中字段最丰富、最容易出错的一个。它有三条互斥的用法路径：

{styleName} | {styleId?,firstRow?,lastRow?,firstCol?,lastCol?,bandRow?,bandCol?,keepFormatting?,shadingColor?,borderColor?,borderWidthPt?,borderPreset?}

三种典型载荷：

{ "op": "setTableStyle", "target": { "slide": 0, "el": "e_TABLE" }, "styleName": "zebraBlue" }

{ "op": "setTableStyle", "target": { "slide": 0, "el": "e_TABLE" }, "styleId": "Medium Style 2 - Accent 1", "firstRow": true, "bandRow": true }

{ "op": "setTableStyle", "target": { "slide": 0, "el": "e_TABLE" }, "firstRow": true, "borderPreset": "all", "borderColor": "#BFBFBF", "borderWidthPt": 1 }

三条路径的语义与优先级

从 table-ops.ts 的resolveTableStyle可以看清三条路径的完整语义：

1. styleName预设路径（优先级最高）：预设名映射到TABLE_STYLE_PRESETS（定义在 pptx-engine/src/table-edit.ts）。只要传了styleName，其余字段一律被忽略——文档明确警告"the preset is applied and the rest is ignored"。预设是固定颜色的自定义<a:tblStyle>定义，会被写进ppt/tableStyles.xml。为什么不用 PowerPoint 内置 GUID？因为内置样式跟随文件主题的强调色走——在一个橙色主题里选"深蓝表头"预设会得到橙色表头；固定色预设则保证按钮色板、本应用渲染和 PowerPoint 三方一致。lightGrid等网格类预设还会附加直接边框（内置样式机制只覆盖内部线条，外框必须用直接边框补画）。应用预设默认清除直接单元格格式，行为与 PowerPoint 样式库一致。

2. styleId内置样式路径：接受画廊名称（如"Medium Style 2 - Accent 1"）或 GUID。pptx-engine 的 table-style.ts 内置了官方 74 种 PowerPoint 内置表格样式的 GUID 映射表（含No Style, No Grid、Themed Style N - Accent N、Light/Medium/Dark Style N [- Accent N]等家族）。选择画廊样式时，默认清除直接单元格填充/边框以便样式显现；传keepFormatting: true则保留它们。区域强调标志（firstRow、bandRow、lastRow、firstCol、lastCol、bandCol）可在此路径上叠加。

3. 逐项定制路径：不传预设与styleId时，可以用shadingColor（每个单元格的填充）、borderColor+borderWidthPt+borderPreset（边框线）以及各区域布尔标志做细粒度调整。shadingColor为#RRGGBB或"none"，borderPreset为"all"（画全部边框线）或"none"（清空）。边框宽度单位为 pt，0 < pt <= 1584（源码中MAX_BORDER_WIDTH_PT = 1584是 PowerPoint 的线宽上限），换算时按EMU_PER_PT取整。

源码层的校验细节

validate阶段会做一系列精确校验：styleName未知时列出全部可用预设名；styleId必须是字符串且能解析为内置样式，否则列出 74 个内置样式名；shadingColor/borderColor必须是#RRGGBB（HEX_RE = /^#[0-9A-Fa-f]{6}$/）；borderWidthPt必须是有限数且0 < pt <= 1584；borderPreset只能是"all"或"none"。执行时若涉及预设的styleId/styleDefXml，会先通过ensureTableStylePart把自定义样式写入tableStyles.xml，再调用editTableStyle手术式地只替换<a:tblPr>与各单元格<a:tcPr>节点、保持其余字节不变（见 table-edit.ts 的设计哲学注释）。slides read命令可以查看某表格当前的style，用于编辑前侦查。

常见错误

• 传颜色名（如"blue"）——颜色必须是#RRGGBB；
• 把styleName与其它字段混用——预设生效，其余被忽略；
• 把内置样式名填进styleName——画廊名称和 GUID 要放styleId；
• 想重排单格文字——那是setTableCell配带样式的 runs，不是这个 Op。

setChart：为什么它不可由模型直接调用

{patch:ChartEdit} — use the edit_chart tool instead

setChart改变图表的类型、数据、颜色或元素，登记在注册表中但标记(not-ai-callable)：模型的词汇表和签名索引都不会出现它，必须走edit_chart工具——该工具以验证过的 Schema暴露同样的能力（table-ops.ts）。从实现看，首次编辑图表时会markChartEditable打标记（转换本身无损，确认一次后不再二次询问），随后editChartElement整体重写图表 part XML 与内嵌工作簿。文档标注此 Op 的目的是保持注册表与文档同步的完整性，而非供模型直接调用。

事务执行：表格 Op 如何被安全地应用

所有表格 Op 最终都通过runTxn（ops/executor.ts）在一个先规划后执行的事务中运行：

• 规划（plan）：整批 Op 先全部validate；每个 Op 还会先过assertXmlSafeStrings（拦截 XML 1.0 禁止的控制字符，如 PDF 提取文本常见的\u000B）与normalizeLengthUnits（把带单位的长度字符串归一为 EMU 整数）。dryRun: true时只返回校验通过的规划清单，不触碰文件。
• 执行（execute）：默认atomic隔离——先深拷贝快照，逐个apply，任何失败立即恢复快照并返回带Usage签名的引导错误，整批未动；per_op隔离则各 Op 独立，失败按索引收集跳过、成功保留。
• 身份加固：每个被改写的元素若缺少a16:creationId，执行器会为其铸造一个（幂等），使其持久 id 从cNvPr回退升级为可跨重排存活的 GUID。

对表格 Op 而言，tableMerge与tableStructure这类结构变更会重解析幻灯片并重新生成元素 id，因此它们的记录携带after.elementId；而setTableStyle的记录after携带的是解析后的样式编辑对象。测试（如 tests/table-style-borderwidth.test.ts、tests/executor-reject.test.ts）覆盖了样式字段校验与执行器拒绝路径，同时文档同步测试保证table.md与注册表严格一致、每个示例都能在夹具课件上干跑通过。

小结：一套可复制、可自纠的表格编辑契约

genoffice 的表格编辑能力浓缩为 7 个 Op：文字（setTableCell）、结构（tableMerge、tableStructure）、几何（setTableRowHeight、setTableColWidth、setTableCellAnchor）与外观（setTableStyle）。它们的共同特征是契约化：字段类型与取值范围在规划期就被严格校验，失败信息总是"指出问题 + 给出可用的候选 + 附上 Usage 签名"，让 AI Agent 无需常驻整份字段手册也能自我纠错。文档文件 prompts/ops/table.md 就是这份契约的单一事实来源——它既是人的参考手册，也是被op-docs.ts解析后直接注入模型提示的运行时数据，并被测试强制与实现保持同步。无论你是编写脚本批量调整演示文稿，还是为 Agent 设计表格编辑工具链，这套 Op 定义都是最值得直接复用的入口。

• 人工智能
• AI 应用
• 桌面应用
• AI Agent
• MCP 服务
• AI 技能