问【教程】使用Microsoft 365 Agents Toolkit快速开发Office加载项（下）

快乐小子新

Lv.2潜力创作者

五、调试与运行

5.1 在 Excel / PowerPoint / Word 中侧加载

Agents Toolkit 提供了内置的调试配置，支持从 VS Code 直接启动 Office 桌面版进行调试：

在 VS Code 中按 Ctrl+Shift+D 打开运行和调试面板

在下拉菜单中选择目标平台：

Excel Desktop (Edge Chromium)

PowerPoint Desktop (Edge Chromium)

Word Desktop (Edge Chromium)

按 F5 启动调试

项目构建后，Office 桌面版会自动打开，Home 功能区会出现一个包含两个按钮的选项卡：

Show Taskpane：打开插件的任务窗格

Perform an action：在文档中执行预设操作

提示：在 Windows 上侧加载后，加载项同时可在 Office 网页版（如 https://excel.cloud.microsoft/）中使用，无需额外配置。如果这是你首次在计算机上侧加载 Office 加载项（或超过一个月未操作），系统可能会提示删除旧证书和/或安装新证书，请同意相关提示。

5.2 在 Outlook 中侧加载

确保 Outlook 客户端为经典版（Classic Outlook for Windows），新版 Outlook 存在已知 bug

确保 Microsoft 365 开发租户中的账号也是桌面 Outlook 中的邮箱账号

在 VS Code 的运行和调试下拉菜单中选择 Outlook Desktop (Edge Chromium)

按 F5 启动调试

Outlook 打开后，打开任意邮件，Home 功能区会出现加载项按钮

5.3 停止调试

# 在 VS Code 终端中运行
npm run stop

注意：关闭服务器窗口并不能可靠地停止服务器，关闭 Office 应用也不能可靠地让 Office 卸载加载项。请务必使用 npm run stop 命令。

5.4 Microsoft 365 Agents Playground 的使用

Microsoft 365 Agents Playground（原称 Teams App Test Tool）是一个集成在 Agents Toolkit 中的本地沙盒测试环境。它的核心价值在于：开发者无需配置 Microsoft 365 开发租户、无需设置 Ngrok 隧道、无需进行 Teams 应用注册，即可在本地模拟界面测试插件和机器人的交互。

启动 Playground 的步骤：

确保已安装 Agents Toolkit 扩展，并已使用 Agents Toolkit 创建了一个项目

在 VS Code 中按 Ctrl+Shift+D 打开运行和调试面板

在下拉菜单中选择"在 Microsoft 365 Agents Playground 中调试"（Debug in Microsoft 365 Agents Playground）

Agents Playground 会在网页中打开，呈现一个类似 Teams 聊天的界面

在消息输入区域中，你可以与机器人进行对话，或触发消息扩展命令

Playground 支持的主要功能：

搜索命令：在消息扩展中输入关键字，Playground 会发送 composeExtension/query 调用请求并显示搜索结果

操作命令：通过自适应卡片或静态参数列表创建对话框，提交后 Playground 发送 composeExtension/submitAction 调用请求

链接展开：输入 URL，Playground 触发 composeExtension/queryLink 调用请求，呈现自适应卡片

注意事项：

Playground 目前仅支持桌面端和 Web 客户端

在 Playground 中触发消息扩展的用户体验可能与 Teams 中略有不同

某些高级功能（如搜索结果的网格布局、嵌入式 Web 视图对话框等）在 Playground 中暂不支持

六、Office.js 核心开发实战

在实际开发中，手写 Office.js 代码往往需要反复查阅 API 文档、调试异步逻辑，过程较为繁琐。完整的 API 参考文档见：https://learn.microsoft.com/zh-cn/javascript/api/office

6.1 初始化与上下文

所有 Office API 调用都必须在 Office.onReady 之后进行：

Office.onReady((info) => {
  if (info.host === Office.HostType.Excel) {
    console.log("Excel 插件已就绪");
  }
});

6.2 Excel 插件示例：创建图表

async function createChart() {
  await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const range = sheet.getUsedRange();
    range.load("address");

    const chart = sheet.charts.add(
      Excel.ChartType.lineStacked,
      range,
      Excel.ChartSeriesBy.columns
    );
    chart.title.text = "销售趋势分析";
    chart.legend.position = Excel.ChartLegendPosition.right;

    await context.sync();
  });
}

6.3 Word 插件示例：替换文档内容

async function replaceText() {
  await Word.run(async (context) => {
    const body = context.document.body;
    const searchResults = body.search("{{员工姓名}}", { matchCase: false });
    searchResults.load("items");

    await context.sync();
    searchResults.items.forEach((item) => {
      item.insertText("张三", "Replace");
    });
    await context.sync();
  });
}

6.4 性能优化要点

合并 context.sync() 调用：避免在循环中频繁同步，将多个操作合并为一次同步

精确加载属性：使用 load("values") 而非加载全部属性

分片处理大数据：超过 1 万行数据时，按批次读取和处理

版本兼容性检测：使用 Office.context.requirements.isSetSupported 检查 API 可用性，提供降级方案

七、加载项作为 Copilot 技能：AI 时代的扩展方向

这是 Agents Toolkit 在加载项开发上最具前瞻性的能力。通过"声明式代理 + 加载项操作"模板，开发者可以同时创建一个 Copilot 代理和一个任务窗格加载项，代理能够直接操作文档内容。

7.1 工作流程

用户在 Copilot 中用自然语言发出指令 → Copilot 调用代理 → 代理通过加载项的后端逻辑读写文档

这使得加载项的交互入口从"点击按钮"扩展为"对话指令"，打开了全新的产品可能性。

7.2 创建带 Copilot 操作的加载项

在 VS Code 的 Agents Toolkit 中：

选择 Create a new app > Office Add-in

在功能列表中选择 Create a declarative agent with Office Add-in actions

指定工作区文件夹和项目名称

执行 npm install 安装依赖

按 F5 启动调试，Office 桌面版自动打开并加载应用

7.3 MCP 协议支持

Agents Toolkit 仓库中包含 MCP Server 子包，表明微软正在将 Model Context Protocol（模型上下文协议）纳入其工具链。MCP 协议为 AI 模型提供标准化的上下文接口，使加载项能够以结构化的方式向 AI 暴露能力。这意味着未来的 Office 插件不仅可以通过按钮触发，还可以被 AI 直接调用。

开发者可以通过 MCP 服务器将外部服务（如 GitHub、数据库、内部 API）集成到 Copilot 代理中，让代理在对话中直接调用这些服务的能力。

八、共享与发布

使用 Agents Toolkit 开发完成后，最直接的分享方式就是共享清单文件。具体操作分为两步：

第一步，打包项目。

在项目根目录下运行 npm run build 命令，构建完成后，dist 文件夹中会生成所有前端文件。然后使用 Agents Toolkit 的打包命令将应用打包为可分发的格式。如果你使用的是统一清单（JSON 格式），打包后会生成一个 .zip 文件，其中包含 manifest.json 和所有前端资源。

第二步，侧加载到 Office。

用户获取到 manifest 文件（或 .zip 包）后，在 Office 应用中点击"插入"选项卡 → "获取加载项" → "从我的计算机加载"，选择 manifest 文件即可完成加载。插件会立即出现在功能区中，无需应用商店审核，也不需要管理员权限。这种方式特别适合开发阶段的快速测试、团队内部试用以及企业内部分发。

发布渠道：

Microsoft AppSource：面向全球用户发布

Teams 应用商店：借助 Teams 生态分发

CI/CD 自动化：Agents Toolkit 内置了对 GitHub Actions 和 Azure DevOps 的支持，CLI 工具提供了 atk provision、atk deploy、atk validate、atk package、atk publish 等完整的命令链

综合杂谈圈

2026-06-13 04:23:10

6 +1

问 【教程】使用Microsoft 365 Agents Toolkit快速开发Office加载项（下）