数据结构

概述

本章定义 OASP 协议中使用的所有通用数据结构。这些数据结构被多个事件共享。

基础请求/响应结构

BaseRequest

所有请求的基础结构。

interface BaseRequest {
  requestId: string;       // UUID v4 格式的请求 ID
  documentUri: string;     // 文档 URI，格式为 file:///path/to/document
  timestamp: number;       // 请求发起时间（Unix 毫秒时间戳）
}

BaseResponse

所有成功响应的基础结构。

interface BaseResponse {
  requestId: string;       // 对应请求的 ID
  success: true;
  data: object;            // 具体的返回数据
  timestamp: number;       // 响应时间（Unix 毫秒时间戳）
  duration?: number;       // 操作耗时（毫秒）
}

ErrorResponse

错误响应结构。

interface ErrorResponse {
  requestId: string;       // 对应请求的 ID
  success: false;
  error: {
    code: string;          // 错误码，见错误处理章节
    message: string;       // 错误消息
    details?: object;      // 附加详情（可选）
  };
  timestamp: number;
  duration?: number;
}

---

选区相关

SelectionInfo

选区位置信息。

interface SelectionInfo {
  isEmpty: boolean;        // 选区是否为空
  type: SelectionType;     // 选区类型
  start?: number;          // 开始位置（字符偏移）
  end?: number;            // 结束位置（字符偏移）
  text?: string;           // 选中的文本内容
}

SelectionType

选区类型枚举。

type SelectionType =
  | "NoSelection"          // 无选区
  | "InsertionPoint"       // 光标（无选中内容）
  | "Normal";              // 正常选区（有选中内容）

---

文本格式

TextFormat

文本格式定义：字体格式收敛到 WordFont，styleName（Word 样式）为独立关注点。

interface TextFormat {
  font?: WordFont;       // 字体格式，见 #wordfont
  styleName?: string;    // Word 内置样式名（如 "Heading 1"），经 styleBuiltIn 应用
}

样式优先级

当 styleName 与 font 同时存在时，font 优先级更高。处理顺序：先应用 styleName 指定的样式，再用 font 覆盖。

styleName 的宿主口径

styleName 经 Word.js range.styleBuiltIn 应用（内置样式需去空格 PascalCase："Heading 1" → Heading1），未命中再回退 range.style。中文 / 非英文宿主必须走 styleBuiltIn（range.style = "Heading 1" 会抛 InvalidArgument），故 styleName 的可靠应用实际需 WordApi 1.3。

WordFont

Word 字体格式。整段（TextFormat.font）与表格单元格（CellFormat.font）复用同一结构。所有字段可选，未提供的属性保持原样。对齐 Word.js Word.Font，双端零映射。

interface WordFont {
  bold?: boolean;                  // 粗体                          [WordApi 1.1]
  italic?: boolean;                // 斜体                          [1.1]
  underline?: UnderlineStyle;      // 下划线样式（见下）            [1.1]
  size?: number;                   // 字号（磅）                    [1.1]
  name?: string;                   // 字体名称                      [1.1]
  color?: string;                  // 文字颜色（十六进制 #RRGGBB 或色名） [1.1]
  highlightColor?: string | null;  // 高亮色（见下；null = 清除）   [1.1]
}

requirement set 与降级

文本字体全部字段经 Word.js range.font（Word.Font），统一 WordApi 1.1，几乎所有宿主满足、无访问器抬平。用于表格单元格时经 cell.body.font，因 TableCell / TableCell.body 访问器门槛升至 WordApi 1.3（与 CellFormat 其余字段同档，不额外抬高）。宿主不满足时按事件定义走反应式 3016 API_NOT_SUPPORTED。

highlightColor ≠ color（桌面端预置色吸附）

highlightColor 取值为十六进制 #RRGGBB 或 Word 预置色名（如 "Yellow"），null 表示清除高亮。⚠️ 桌面版 Word 仅支持 15 个预置高亮色（Yellow / Lime / Turquoise / Pink / Blue / Red / DarkBlue / Teal / Green / Purple / DarkRed / Olive / Gray / LightGray / Black），传任意 #RRGGBB 会被吸附到最近的预置色——故 highlightColor 不是自由 RGB（与 color 不同）；需精确可控时建议直接传上述 15 个预置色名。

UnderlineStyle

Word 下划线样式枚举（对齐 Word.js Word.UnderlineType，PascalCase，双端零映射）。列出全部可 SET 值，排除仅回读的 Mixed 与已废弃的 Hidden / DotLine。

type UnderlineStyle =
  | "None"
  | "Single" | "Word" | "Double" | "Thick"
  | "Dotted" | "DottedHeavy"
  | "DashLine" | "DashLineHeavy" | "DashLineLong" | "DashLineLongHeavy"
  | "DotDashLine" | "DotDashLineHeavy" | "TwoDotDashLine" | "TwoDotDashLineHeavy"
  | "Wave" | "WaveHeavy" | "WaveDouble";

与 /ppt 的 ShapeFontUnderlineStyle 有意不同

本枚举 PascalCase、对齐 Word.js Word.UnderlineType；/ppt 的 ShapeFontUnderlineStyle 对齐 office.js PowerPoint。二者服务不同宿主 API、字面量不同（虚线 Word 为 DashLine、PPT 为 Dash），有意不复用。

---

PPT 文本格式（/ppt）

以下结构服务于 ppt:update:textBox、ppt:insert:text 与 ppt:insert:shape。字体属性统一收敛到 PptFont，整框级与 run 级复用同一结构。每个属性标注其最低 PowerPointApi requirement set；宿主不满足时按事件定义走反应式 3016 API_NOT_SUPPORTED 处理。

PptFont

PPT 文字字体格式。整框级（TextBoxUpdates.font / TextInsertOptions.font / ShapeInsertOptions.font）与 run 级（PptTextRun.font）共用本结构。所有字段可选，未提供的属性保持原样。

interface PptFont {
  size?: number;                       // 字号（磅）           [1.4]
  name?: string;                       // 字体名称             [1.4]
  color?: string;                      // 文字颜色（十六进制） [1.4]
  bold?: boolean;                      // 粗体                 [1.4]
  italic?: boolean;                    // 斜体                 [1.4]
  underline?: ShapeFontUnderlineStyle; // 下划线样式           [1.4]
  strikethrough?: boolean;             // 删除线               [1.8]
  doubleStrikethrough?: boolean;       // 双删除线             [1.8]
  superscript?: boolean;               // 上标                 [1.8]
  subscript?: boolean;                 // 下标                 [1.8]
  allCaps?: boolean;                   // 全大写               [1.8]
  smallCaps?: boolean;                 // 小型大写             [1.8]
}

字段	类型	requirement set	说明
size	number	1.4	字号（磅）
name	string	1.4	字体名称
color	string	1.4	文字颜色（十六进制，如 #FF0000）
bold	boolean	1.4	粗体
italic	boolean	1.4	斜体
underline	ShapeFontUnderlineStyle	1.4	下划线样式（17 值枚举，见下）
strikethrough	boolean	1.8	删除线
doubleStrikethrough	boolean	1.8	双删除线
superscript	boolean	1.8	上标
subscript	boolean	1.8	下标
allCaps	boolean	1.8	全大写
smallCaps	boolean	1.8	小型大写

requirement set 与降级（全或无）

每个属性标注其最低 PowerPointApi requirement set。当前宿主不满足本次请求所含属性的最高 requirement set 时，承载该 PptFont 的事件按反应式 3016 API_NOT_SUPPORTED 整体失败（全或无，不做部分应用），错误 details.requiredApiSet 标注所需版本。调用方据此降级——例如仅发送 1.4 属性以适配低版本宿主。此处理与握手无关：版本握手 ≠ 运行时能力，能力不足在操作期反应式处理。

上表 1.4 / 1.8 分档为文本框（textRange.font）语境。 PptFont 复用于 ppt:update:tableFormat 的表格单元格时，因 office.js TableCell.font 访问器门槛为 1.9，会把底层属性整体抬平到 1.9（单一门槛，无需按属性取 max）；且单元格无 run 级（office.js 未暴露单元格内字符区间寻址），PptFont 仅作用于整格。详见该事件的版本门槛说明。

ShapeFontUnderlineStyle

PPT 下划线样式枚举（17 值，PowerPointApi 1.4）。线缆值即 office.js ShapeFontUnderlineStyle 枚举字面量，双端零映射。

type ShapeFontUnderlineStyle =
  | "None" | "Single" | "Double" | "Heavy"
  | "Dotted" | "DottedHeavy"
  | "Dash" | "DashHeavy" | "DashLong" | "DashLongHeavy"
  | "DotDash" | "DotDashHeavy" | "DotDotDash" | "DotDotDashHeavy"
  | "Wavy" | "WavyHeavy" | "WavyDouble";

与 Word 的 UnderlineStyle 有意不同

/word 的 UnderlineStyle 是 18 值 PascalCase（对齐 Word.js Word.UnderlineType）；PPT 的 ShapeFontUnderlineStyle 是 17 值 PascalCase（对齐 office.js PowerPoint 的同名枚举）。二者对齐不同宿主 API、字面量不同（如虚线 Word 为 DashLine、PPT 为 Dash），故不复用——这是有意的跨命名空间差异，非命名不一致。

PptTextRun

run 级局部格式：对文本框内一段字符区间单独设置字体。

interface PptTextRun {
  start: number;    // 区间起始字符下标（0 基，UTF-16 code unit）
  length: number;   // 区间字符数（UTF-16 code unit）
  font: PptFont;    // 应用到该区间的字体格式
}

PptParagraphStyle

段落级格式（当前仅项目符号）。同样以字符区间寻址：区间接触到的段落整体应用。

interface PptParagraphStyle {
  start: number;               // 区间起始字符下标（0 基，UTF-16 code unit）
  length: number;              // 区间字符数（UTF-16 code unit）
  bulletFormat: BulletFormat;  // 应用到区间所在段落的项目符号格式
}

字符区间口径（start / length）

• start 为 0 基字符下标、length 为字符数，二者均以 UTF-16 code unit 计（= JavaScript 字符串语义；emoji / 代理对算 2 个单位）。
• 计数对齐文本框的最终文本完整内容，含段落分隔符 \r 与软换行 \v（这些字符占下标）。双端须以同一口径计算 offset。
• 与 text 替换并存时的口径：当同一次 ppt:update:textBox 请求既提供 updates.text（整框内容替换）又提供 runs / paragraphs 时，内容替换先于格式应用，start / length 一律对齐替换后的新文本（不是替换前的旧内容）；未提供 updates.text 时则对齐文本框现有内容。因此 text.length 指该次生效的最终文本长度。
• 越界（start < 0 或 start + length > text.length，此处 text.length 即上条所指最终文本长度）按 4002 INVALID_PARAM 处理。
• runs / paragraphs 在同一次请求内按数组顺序应用，后者覆盖先者的重叠区间。

BulletFormat

项目符号格式。对齐 office.js paragraphFormat.bulletFormat，仅含下列可写属性。

interface BulletFormat {
  visible?: boolean;   // 是否显示项目符号                      [1.4]
  type?: BulletType;   // 项目符号类型（无/编号/非编号）        [1.10]
  style?: string;      // 编号 / 符号样式，对齐 office.js 枚举  [1.10]
}

type BulletType = "None" | "Numbered" | "Unnumbered" | "Unsupported";

字段	类型	requirement set	说明
visible	boolean	1.4	显示 / 隐藏项目符号
type	BulletType	1.10	无 / 编号 / 非编号列表
style	string	1.10	具体编号或符号样式，取值对齐 office.js bullet 样式枚举（如 ArabicNumeralPeriod / RomanUppercasePeriod / SimplifiedChinesePeriod 等 40+ 值）

office.js 硬限制

bulletFormat 没有 character（自定义符号字符）、字体、颜色属性——协议不提供这些字段。type / style（真正的编号列表）需 PowerPointApi 1.10；visible（显示 / 隐藏）仅需 1.4。

为何 style 用 string 而 underline 用完整枚举（有意的不对称）

协议对宿主枚举有两种收敛策略，按集合大小与稳定性择一，非随意：

• 小而封闭的集合 → 就地全枚举（如 ShapeFontUnderlineStyle 的 17 值）：值少、稳定、可在协议层做类型校验与提示，收益高、维护成本低。
• 大而易变的宿主枚举 → 直通 string（style 对应 office.js bullet 样式，40+ 值且随宿主版本增补）：就地全枚举会让协议文档与一个庞大且演进中的宿主枚举强耦合、易过时。故 style 定义为对齐 office.js 样式字面量的直通字符串，由宿主在应用时校验；非法值按 4002 INVALID_PARAM 处理，与 underline 非枚举值的失败口径一致。

即：两者都是"零映射对齐宿主枚举"，只是承载形态按集合规模分档——这是一致的抽象原则，不是遗漏。

ParagraphHorizontalAlignment

段落 / 表格单元格水平对齐枚举（7 值，PowerPointApi 1.9）。线缆值即 office.js ParagraphHorizontalAlignment 枚举字面量，双端零映射。

type ParagraphHorizontalAlignment =
  | "Left" | "Center" | "Right" | "Justify"
  | "JustifyLow" | "Distributed" | "ThaiDistributed";

TextVerticalAlignment

文本 / 表格单元格垂直对齐枚举（6 值，PowerPointApi 1.9）。线缆值即 office.js TextVerticalAlignment 枚举字面量，双端零映射。

type TextVerticalAlignment =
  | "Top" | "Middle" | "Bottom"
  | "TopCentered" | "MiddleCentered" | "BottomCentered";

---

样式相关

StyleInfo

文档样式信息。

interface StyleInfo {
  name: string;            // 样式名称（本地化名称）
  type: StyleType;         // 样式类型
  builtIn: boolean;        // 是否为内置样式
  inUse: boolean;          // 是否在文档中使用
  description?: string;    // 样式描述（仅当请求 detailedInfo=true 时返回）
}

关于 description 字段

description 字段仅在 word:get:styles 请求中设置 detailedInfo=true 时返回。 此功能依赖 WordApi BETA，在部分环境中可能不可用。

StyleType

样式类型枚举。

type StyleType =
  | "Paragraph"            // 段落样式
  | "Character"            // 字符样式
  | "Table"                // 表格样式
  | "List";                // 列表样式

---

文档统计

DocumentStructureResult

文档结构统计。

interface DocumentStructureResult {
  sectionCount: number;    // 章节数量
  paragraphCount: number;  // 段落数量
  tableCount: number;      // 表格数量
  imageCount: number;      // 图片数量
  tables?: TableSummary[]; // 表格清单（可选，用于"重新发现"现有表格）
}

interface TableSummary {
  tableId: string;            // 临时索引（详见 word:insert:table 稳定性说明）
  rowCount: number;           // 表格行数（未合并状态）
  columnCount: number;        // 表格列数（未合并状态）
  precedingHeading?: string;  // 表格前最近的标题文本，便于 AI 通过启发式定位
}

tables 字段为可选

旧 Add-In 版本可能不返回 tables；调用方应做存在性判断。如缺省，可退化为按 tableCount 配合 tableId = "table-{i}" 推断（仅在文档结构未变更时可靠）。

DocumentStatsResult

文档字数统计。

interface DocumentStatsResult {
  characterCount: number;           // 字符数（不含空格）
  characterCountWithSpaces: number; // 字符数（含空格）
  wordCount: number;                // 单词数
  paragraphCount: number;           // 段落数
  pageCount?: number;               // 页数（可选）
}

---

替换内容

ReplaceContent

替换操作的内容定义。

interface ReplaceContent {
  text?: string;           // 替换文本
  images?: ImageData[];    // 替换图片（可插入多张）
  format?: TextFormat;     // 文本格式（最高优先级）
  styleName?: string;      // Word 样式名（仅在 format 未提供时使用）
}

格式优先级

• format（最高优先级）：包含 format.font（字体）和 format.styleName
• styleName（仅在 format 未提供时使用）
• 默认保持选区原有格式

---

图片相关

ImageData

图片数据定义。

interface ImageData {
  base64: string;          // Base64 编码的图片数据
  mimeType?: string;       // MIME 类型，如 "image/png"
  width?: number;          // 宽度（像素或点）
  height?: number;         // 高度（像素或点）
  altText?: string;        // 替代文本
}

---

表格相关

TableInsertOptions

表格插入选项。

interface TableInsertOptions {
  rows: number;            // 行数（>= 1）
  columns: number;         // 列数（>= 1）
  data?: string[][];       // 初始数据（二维数组）
  style?: string;          // 表格样式名称
  insertLocation?: TableInsertLocation;  // 插入位置，默认 "End"
}

type TableInsertLocation =
  | "Start"    // 文档开头
  | "End"      // 文档末尾（默认）
  | "Before"   // 当前选区/光标之前
  | "After"    // 当前选区/光标之后
  | "Replace"; // 替换当前选区

CellFormat

表格单元格格式属性。可由 word:update:tableCell 等事件复用，承载单元格的对齐、字体与底色等可视样式。所有字段均为可选——未传字段保持原状，便于增量更新。

interface CellFormat {
  horizontalAlignment?: "Left" | "Centered" | "Right" | "Justified";  // 对应 Word.Alignment
  verticalAlignment?: "Top" | "Center" | "Bottom";                    // 对应 Word.VerticalAlignment
  backgroundColor?: string;   // 背景色（十六进制，如 "#4472C4"）— 对应 cell.shadingColor
  font?: WordFont;            // 单元格字体格式（整刷，见下），见 #wordfont
}

命名对齐 Office.js

对齐枚举值刻意与 Word JavaScript API 的 Word.Alignment / Word.VerticalAlignment 完全一致（注意 Centered / Justified 是过去分词形），便于 Add-In 直接 cast 不做映射。

字体收敛为 WordFont（整刷语义）

单元格字体统一走 WordFont（fontColor 已并入 font.color；单元格因此获得 underline / highlightColor 等全部 7 属性）。font 经 Word.js cell.body.font 应用，作用于整个单元格 body、覆盖单元格内所有段落与 Run 的字体——这是 Word.js 的固有行为（对 Body.font 赋值即整体套用），不是协议保留的灵活度。

requirement set

CellFormat 全字段有效门槛 WordApi 1.3：TableCell / TableCell.body、cell.shadingColor、horizontalAlignment / verticalAlignment 均为 1.3。font 的字体属性本身是 1.1，经单元格访问器（cell.body.font）抬至 1.3，与本结构其余字段同档、不额外抬高。

单元格内边距

Word JavaScript API 的单元格内边距是表级 API（Word.Table.setCellPadding），无法逐单元格设置。如需调整内边距，请通过 word:update:tableFormat.styleOptions.cellPadding 在表级配置。

该结构仅 /word 命名空间引用（对齐 Word.js：UnderlineStyle 18 值 PascalCase 对齐 Word.UnderlineType、Word.Alignment 的 Centered / Justified）。/ppt 的 ppt:update:tableFormat 有意不复用本结构，改用 PptFont + ParagraphHorizontalAlignment / TextVerticalAlignment（对齐 office.js PowerPoint、17 值 PascalCase 下划线、Center / Justify）——与 underline 枚举同理，服务不同宿主 API、零映射，跨命名空间不复用。

---

PPT 相关

SlideElement

幻灯片元素信息。

interface SlideElement {
  id: string;              // 元素 ID
  type: SlideElementType;  // 元素类型
  position: {
    left: number;          // 左边距（点）
    top: number;           // 上边距（点）
    width: number;         // 宽度（点）
    height: number;        // 高度（点）
  };
  text?: string;           // 文本内容（如适用）
  zIndex: number;          // 层级
}

SlideElementType

幻灯片元素类型。

type SlideElementType =
  | "TextBox"              // 文本框
  | "Shape"                // 形状
  | "Image"                // 图片
  | "Table"                // 表格
  | "Chart"                // 图表
  | "SmartArt"             // SmartArt 图形
  | "Video"                // 视频
  | "Audio";               // 音频

ShapeType

形状类型（常用）。

type ShapeType =
  | "Rectangle"            // 矩形
  | "RoundedRectangle"     // 圆角矩形
  | "Circle"               // 圆形
  | "Oval"                 // 椭圆
  | "Triangle"             // 三角形
  | "Diamond"              // 菱形
  | "Pentagon"             // 五边形
  | "Hexagon"              // 六边形
  | "Line"                 // 直线
  | "Arrow"                // 箭头
  | "Star"                 // 星形
  | "TextBox";             // 文本框

标识符不透明性

幻灯片元素与幻灯片标识符——SlideElement.id、各 chart 事件的 elementId、以及 ppt:get:slideOoxml / ppt:insert:slidesOoxml 的 slideId——都是服务端分配的不透明字符串。消费方不得解析、推断或依赖其内部结构与格式，只能将其作为整体令牌原样回传。

这是规范层约束，独立于实现：实现可自由更换内部 id 生成方式（例如整页 round-trip 后改用稳定 UUID 并写入 OOXML cNvPr/@name），只要同一对象在其生命周期内返回稳定、可回传的标识符即可——协议不绑定任何具体格式。

---

Excel 相关

RangeInfo

Excel 范围信息。

interface RangeInfo {
  address: string;         // 范围地址，如 "Sheet1!A1:C3"
  rowCount: number;        // 行数
  columnCount: number;     // 列数
  worksheet: string;       // 所属工作表名称
}

CellValueType

单元格值类型。

type CellValueType =
  | "String"               // 字符串
  | "Number"               // 数字
  | "Boolean"              // 布尔值
  | "Date"                 // 日期
  | "Error"                // 错误值
  | "Empty";               // 空值

---

图表相关

跨命名空间通用图表数据结构。供 PPT (ppt:insert:chart / ppt:get:chart / ppt:update:chart) 与未来 Excel (excel:insert:chart 等) 共用。

ChartType

图表类型总枚举，命名与 Excel.ChartType 保持一致，便于消费方直接 cast。ChartType 在数据形状上分两类，ChartData 据此采用 discriminated union 表达。

// 分类型图表：X 轴是离散标签，Y 是数值
type CategoricalChartType =
  | "ColumnClustered"      // 簇状柱形图
  | "ColumnStacked"        // 堆积柱形图
  | "BarClustered"         // 簇状条形图
  | "Line"                 // 折线图
  | "LineMarkers"          // 带标记折线图
  | "Pie"                  // 饼图
  | "Doughnut"             // 圆环图
  | "Area"                 // 面积图
  | "Radar";               // 雷达图

// 散点型图表：每个数据点自带 (x, y) 数对
type ScatterChartType = "Scatter";

type ChartType = CategoricalChartType | ScatterChartType;

CategoricalSeries

分类型图表的单条数据系列（柱形/折线/饼图等使用）。

interface CategoricalSeries {
  name: string;            // 系列名称（图例显示）
  values: number[];        // Y 数值数组，长度需 = CategoricalChartData.categories.length
  color?: string;          // 系列颜色（hex，如 "#4472C4"），缺省使用主题色
}

ScatterSeries

散点型图表的单条数据系列。

interface ScatterSeries {
  name: string;            // 系列名称
  points: ScatterPoint[];  // 数据点数组（≥1）
  color?: string;          // 系列颜色（hex），缺省使用主题色
}

interface ScatterPoint {
  x: number;               // X 坐标（连续数值轴）
  y: number;               // Y 坐标
}

ChartData

图表的逻辑数据与展示选项（不含几何位置）。ChartData 是 discriminated union，由 chartType 字段决定具体形状：

type ChartData = CategoricalChartData | ScatterChartData;

interface CategoricalChartData {
  chartType: CategoricalChartType;     // 9 个分类型枚举之一（不含 "Scatter"）
  categories: string[];                // X 轴离散标签（如 ["Jan","Feb","Mar"]）
  series: CategoricalSeries[];         // 数据系列（≥1）
  title?: string;                      // 图表标题
  showLegend?: boolean;                // 是否显示图例，默认 true
  showDataLabels?: boolean;            // 是否显示数据标签，默认 false
}

interface ScatterChartData {
  chartType: "Scatter";                // 字面量
  series: ScatterSeries[];             // 数据系列（≥1）；X 由 series[].points[].x 提供，无 categories
  title?: string;
  showLegend?: boolean;
  showDataLabels?: boolean;
}

为什么用 discriminated union

ChartType 在数据形状上不一致：分类型图表用 categories + series.values（X 是离散标签），散点图用 series.points（X 是连续数值，每个点自带 (x,y)）。把它们硬塞进同一个 schema（如让 categories 在 Scatter 时存数字字符串）会让 LLM 在 MCP 工具 schema 里看不到这个隐式约束。Discriminated union 让 LLM 一选定 chartType，schema 就自动限定可填字段。

JSON Schema 落地建议使用 oneOf + discriminator: { propertyName: "chartType" }；Pydantic / FastMCP 使用 Annotated[Union[...], Field(discriminator="chartType")]。

数据维度校验

• CategoricalChartData：每个 CategoricalSeries.values 长度必须等于 categories.length，否则返回 3015 INVALID_CHART_DATA
• ScatterChartData：每个 ScatterSeries.points 长度 ≥ 1，x/y 必须为有限数（非 NaN / Infinity），否则返回 3015 INVALID_CHART_DATA

---

通用枚举

InsertLocation

插入位置枚举。

type InsertLocation =
  | "Before"               // 在目标之前
  | "After"                // 在目标之后
  | "Start"                // 在目标开头
  | "End"                  // 在目标末尾
  | "Replace";             // 替换目标

---

脚本执行

{namespace}:run:script（excel:run:script / word:run:script / ppt:run:script）是封装层逃生舱：调用方下发一段 JS 源码，AddIn 注入宿主 RequestContext 后按 Office.js 语义直接执行，回传返回值与日志。定位、执行语义、超时、大小限制、安全模型、非原子性与错误映射统一见通用约定 · 脚本执行。三命名空间的请求与结果结构完全相同，故在此共享。

有意的跨命名空间「相同」（非命名不一致）

RunScriptRequest / ScriptResult 是宿主无关的执行信封——承载「一段代码 + 其产出」，宿主差异（Excel / Word / PowerPoint 各自的对象模型）全部落在脚本内部的 context 上、不进入信封。故它与 BaseRequest / BaseResponse 同属传输层，三命名空间应当共享同一结构；这与 WordFont ≠ PptFont（宿主语义层实体、有意零映射对齐各自宿主）方向相反、各自适用。后人不应将其拆成三份 per-namespace 结构。

RunScriptRequest

interface RunScriptRequest {
  requestId: string;
  documentUri: string;
  timestamp?: number;
  script: string;                    // 待执行 JS 源码；以 async 函数体语义执行，可用 return 返回结果
  args?: Record<string, unknown>;    // 注入脚本的参数，脚本内经全局 `args` 读取；必须可 JSON 序列化
  timeoutMs?: number;                // 执行超时（毫秒）；缺省取「脚本执行」档默认值（60000），无硬上限
}

ScriptResult

run:script 成功响应的 data。

interface ScriptResult {
  result: unknown;          // 脚本 return 的值，已序列化为纯 JSON；无返回值时为 null
  logs: string[];           // 脚本内 console.* 的输出，按调用顺序
  durationMs: number;       // 脚本执行耗时（毫秒）
  logsTruncated: boolean;   // 日志是否因超限（见 conventions#run-script）被截断
}