PPT Agent 能力门控：让 AI 不再盲目尝试

过去一周，OUTBIRD 的 PPT 插件与 AI Agent 迎来了一轮重要更新。其中最核心的改进，是让 PPT Agent 能够感知宿主环境的能力边界，在规划与执行时「知其所能、避其所不能」，而不是盲目尝试注定失败的 API 调用。

问题背景

PowerPoint Office.js Add-in 的 API 能力并非在所有平台、所有版本上一致。微软通过 requirement sets（如 PowerPointApi 1.4、1.5、1.10）来区分不同 API 的可用性：

Web / Windows M365：通常支持到 1.10
Windows 零售版 2021+：最高 1.9
Windows LTSC 2024：仅 1.5
iPad：仅 1.1

如果 Agent 在 iPad 上尝试调用 set_slide_background_color（依赖 1.10 的 SlideBackgroundFill 模型），会直接失败，但 Agent 可能仍会「乐观地」报告任务完成。这种「试了再说」的行为，会严重损害用户体验和信任。

解决方案：能力矩阵 + 工具门控

我们做了三件事：

1. 建立工具与 requirement set 的映射策略

在 claude-agent-ppt.js 中维护了一张 TOOL_MIN_SET_POLICY 表：

insert_textbox、set_shape_fill_color 等形状操作：≥ 1.4
set_selected_text：≥ 1.5（依赖 selection API）
set_slide_background_color：≥ 1.10（依赖新的背景模型）

Planner 在生成工具调用前，会先检查当前 host 的 isSetSupported("PowerPointApi", "x.y") 结果，只 emit 宿主支持的工具。

2. 运行时动态探测能力

每次与 Agent 交互时，前端会通过 Office.context.requirements.isSetSupported() 探测 1.1～1.10 各版本的支持情况，并将结果写入 slide_context.capabilities，随请求一起发给后端。后端 Planner 据此过滤工具列表，Executor 在执行前也会再次校验，若 host 不支持则返回明确的 unsupported by host 错误，而不是乐观成功。

3. 视觉验证顺序调整

原先的逻辑是：先做视觉检查，再执行 Office 操作。这会导致「操作尚未完成就判定失败」的误报。我们调整为：先执行 Office 操作，再执行视觉验证。这样只有在操作真正完成后，才用截图/OCR 等方式确认效果，避免 completion 阶段的虚假成功。

配套工作：支付、联调与文档

同期还完成了：

支付网关真实链路：移除 fallback 模拟，统一走真实微信支付；充值下限 0.1 元，支持 WECHAT_PAY_NATIVE_APP_ID 独立配置
Shadow 联调增强：移除 local-mac-shadow，统一使用 manifest.shadow.xml；支持 PPT_TEST_* 测试账号自动登录；新增 taskpane-standalone 独立调试入口
Orchestrator 工作目录覆盖：支持 OUTBIRD_EMPLOYEE_CWD_OVERRIDES 按虚拟员工配置工作目录
Office.js 能力调研文档：在 docs/ops/ppt-officejs-capability-research-2026-03.md 中整理了 PowerPoint requirement sets 1.1～1.10 的演进、各平台支持情况，以及工具与最小 set 的映射建议，供后续扩展参考

经验小结

能力感知优先于乐观重试：在跨平台 Add-in 场景下，先探测再调用，能显著减少无效尝试和用户困惑
文档驱动工程：把 requirement set 与工具映射写成文档，既方便团队对齐，也便于 CI 回归测试（如 1.10 host 上背景色应通过，<1.10 应明确返回 unsupported）
视觉验证的时机很重要：先 mutation 后 verification，才能正确反映「操作是否真的生效」

如果你也在做 Office Add-in 或 AI Agent 与宿主 API 的集成，欢迎交流。