AI-PPT Agent 的能力边界：Office.js 说了算

Agent 能做什么，不取决于我们想加什么工具，而取决于 Office.js 在当前宿主上支持什么。Requirement set 碎片化、平台天花板、API 模型演进——这些才是 AI-PPT 能力边界的真正约束。

核心问题：Office.js 能力是 Agent 能力的上限

我们设计了双读（结构+视觉）、20+ 工具、视觉验证，但每一个能力都绑在 Office.js 上：

read_slide_context：遍历 shapes、读 text/fill/position，依赖 PowerPointApi 1.4 的 shape 模型
read_slide_visual：slide.getImageAsBase64() 依赖 1.8，且 iPad 只支持到 1.1，根本拿不到截图
insert_textbox、set_shape_fill_color 等：>= 1.4
set_selected_text：依赖 selection API，>= 1.5
set_slide_background_color：依赖 1.10 的 SlideBackgroundFill 模型。1.10 下推荐 setSolidFill(options)，旧宿主可能仍有 setSolidColor(color)；当前实现会先尝试 setSolidFill，失败则 fallback 到 setSolidColor，两种 API 都不可用时返回明确错误

Agent 在 iPad 上调用 set_slide_background_color 会失败，在 LTSC 2024 上拿不到 read_slide_visual，在零售版 2021 上背景色可能因 API 模型不匹配而静默失败。不先搞清楚 Office.js 的能力边界，Agent 就会「试了再说」、乐观报告成功，损害用户信任。

Requirement Set 碎片化：平台天花板

微软用 requirement sets（1.1～1.10）区分 API 可用性，各平台天花板不同：

平台	最高支持
Web / Windows M365 / Mac	1.10
Windows 零售版 2021+	1.9
Windows LTSC 2024	1.5
iPad	仅 1.1

1.4 引入 shape 管理（add/move/size/fill/text），1.5 引入 selection，1.8 引入 getImageAsBase64 和 table，1.10 引入 slide background 新模型。Agent 的工具必须按「最小 requirement set」映射。实际流程是：前端每轮探测 Office.context.requirements.isSetSupported('PowerPointApi', '1.1'～'1.10')，写入 slide_context.capabilities 随请求发给后端；Planner（LLM）在 prompt 中看到 capabilities，被要求只 emit 宿主支持的工具；前端在 Planner 返回后用 filterToolCallsByCapability 再过滤一轮，Executor 执行前再校验，不支持则返回明确的 unsupported by host 或 unsupported by requirement set，绝不乐观成功。

能力门控：知其所能、避其所不能

我们做了三件事：

工具与 set 的映射表：TOOL_MIN_SET_POLICY 维护 13 个 Office 工具的最小 set（如 set_slide_background_color: '1.10'）。注意：read_slide_visual、read_slide_context、crop_transparent_pixels、run_officejs_script 及远程工具目前未纳入映射，read_slide_visual 在 iPad（1.1）上可能被 Planner emit 后于执行阶段才失败，是已知缺口。
运行时探测：每轮交互前端探测 1.1～1.10 支持情况，以及 shapeSelectSupported、cropTransparentPixelsSupported、visualExport.requirementSetOk 等，写入 slide_context.capabilities，随请求发给后端；prompt 要求模型遵守这些能力标志。
视觉验证顺序：先执行 Office 修改，再调用 read_slide_visual；否则「操作尚未完成就判定失败」会误报

能力门控不是「锦上添花」，而是在 Office.js 碎片化下的生存策略。没有它，Agent 会在注定失败的 API 上浪费 turn、甚至虚假完成。

API 模型演进与文档坑

1.10 的 slide background 从旧模型迁移到 SlideBackgroundFill，setSolidColor 与 setSolidFill 的差异可能导致文档与实现不一致。当前实现已支持两种 API 的 fallback；< 1.10 宿主通过 setSlideBackgroundColor 能力标志明确返回 unsupported，不做静默失败。

微软的 requirement set 主表有时会搞混 1.5 和 1.6 的简短描述，应以各 set 的专门页面为准。文档不一致是常态，工程上要编码验证、回归测试。

对齐 Claude Code？先过 Office.js 这道关

Claude Code 有 Read/Write/Edit/Bash/Skills，能力边界是文件系统和 shell。AI-PPT 的能力边界是 Office.js：我们想加「跨页复制」「批量应用版式」，得看 Office.js 有没有对应 API、在目标宿主上是否可用。run_officejs_script 是逃逸口，但脚本能调用的仍是 Office.js，不能突破宿主的能力天花板。

要让 Agent 更有能力，第一优先级是吃透 Office.js 的能力边界：哪些 API 在哪些 set 引入、各平台支持到哪、文档与实现有哪些坑。在此基础上，能力门控、工具映射、明确失败，才是 Agent 能稳定工作的前提。Skills、多页扩展，都是后续；Office.js 能力问题不解决，Agent 再聪明也会在 API 边界上反复踩坑。

附录：终端与虚拟输入层（今日修复）

任务窗格用类终端作为 Agent 交互入口，终端基于 xterm.js 叠加虚拟输入层。今日修复了换行时重绘残影：\r\x1b[2K 只清除当前屏幕行，输入换行时上一行残留。修复方式：行尾追加/退格时改用增量写入，避免整行重绘。详见 apps/ppt-addin-web/src/modules/ai-ppt-terminal.js。

若你在做 Office Add-in 或 AI Agent 与宿主 API 的集成，Office.js 能力边界是绕不开的课题。参考 docs/ops/ppt-officejs-capability-research-2026-03.md，欢迎在 OUTBIRD GitHub 讨论。