使用 Office JavaScript 库生成用于智能 Microsoft 365 Copilot 副驾驶®的 API 插件 (预览版)

2025-05-20

注意

本文中所述的开发功能目前为预览版。我们鼓励你尝试使用此功能，但不应在生产插件中使用此功能。以下是初始预览版期间的限制：

此功能仅针对 Windows 和 Office web 版上的 Office 启用。我们正在努力为 Mac 上的 Office 提供支持。
此功能仅适用于 Excel、PowerPoint 或 Word。我们正在努力为 Outlook 提供支持。

声明性代理的插件可以调用 Office JavaScript 库中的 API，以对 Office 应用程序中当前打开的 Office 文档的内容和元数据执行读取和写入作。此功能使 Copilot 能够以精确且无错误的方式处理 Office 文档，否则需要 Office 加载项。

Copilot 代理与 Office 外接程序框架的关系

Office 外接程序和声明性代理插件都调用 Office JavaScript 库中的 API，使用库的 Microsoft 365 扩展可以包括插件和/或加载项。最佳方法取决于扩展应启用的用户方案。

如果扩展应提供不需要向其传递参数的简单快速作，请仅包含带有自定义功能区按钮或菜单的外接程序，称为外接程序命令。
如果扩展需要仪表板体验、需要用户配置设置、需要显示有关 Office 文档内容的元数据，或者出于任何其他原因需要类似页面的体验，请包含具有任务窗格的外接程序。
如果扩展需要提供复杂的作，这些作需要在运行时传递参数或需要自然语言界面，请包含 Copilot 代理。

应用场景

以下是调用 Office JavaScript 库 API 的 Copilot 代理增强 Microsoft 365 扩展的值的一些选定方式。

内容分析： 代理可用于分析文档、演示文稿或电子表格的内容，并根据找到的内容采取作。示例如下。
- 代理 (RFP) 分析建议请求，然后从后端系统获取 RFP 中问题的答案。用户只需要求代理“填写你知道的问题答案”。
- 代理在文档本身或客户业务系统的其他位置分析文档或电子表格中的表，以查找必须执行某些作的内容。用户可能会要求代理“查看文档，查找我在审核列表中错过的任何项目”。
受信任的数据插入： 如果你向典型的 AI 引擎提出问题，它会结合它找到的信息并撰写答案;一个可能会引入不准确之处的过程。但是，基于加载项的 Copilot 代理可以插入来自受信任源的 原样数据 。例如：
- 请考虑一个代理，它允许将法律研究插入到Word，然后可以编辑它。一位用户问代理“在什么情况下，出租人可以单方面破坏印第安纳州的住宅空间租赁？”然后，代理从先例和法规中提取未更改的内容，并将其插入文档中。
- 请考虑管理数字资产清单的代理。在 Copilot 代理聊天中，用户询问“插入一张彩色照片表，其中包含每个照片的名称、下载次数及其大小（以兆字节为单位），按下载的大多数照片的顺序排序。然后，代理从记录系统提取此数据（保持不变），并将该表插入 Excel 电子表格中。

当代理与加载项结合使用时，将启用更多方案。将智能 Microsoft 365 Copilot 副驾驶® 代理与 Office 加载项一起为加载项提供至少两个好处：

Copilot 成为加载项功能的自然语言界面。
代理可以将参数传递给它调用的 JavaScript，当从按钮或菜单项调用外接程序中的函数命令时，这是不可能的。

了解如何使用外接程序是代理增强加载项的一种方式。当用户需要使用加载项执行多个步骤或任务来实现某个目标时，Copilot 的聊天界面可以简化加载项入门过程。例如，假设一家法律公司需要有一个关于它准备的每个租约必须回答的问题列表。创建此问题列表可能既耗时又费力。但是，系统可能会提示 Copilot 代理生成问题的第一个草稿列表，并使用 Office JavaScript 库将它们插入到Word文档中。

创建第一个 Office JavaScript 库插件

下面是为调用 Office JavaScript 库 API 的 Copilot 代理创建 API 插件的主要步骤。

确保满足先决条件
创建项目
配置清单
配置声明性代理
配置插件
创建 JavaScript 函数
复制项目配置文件
测试代理和插件
在代理中进行更改

先决条件

创建项目

首先创建基本声明性代理。

打开 Visual Studio Code。
在活动栏上 选择“Microsoft 365 代理工具包 ”。
选择 “创建新代理/应用”。
选择“ 声明性代理”。
选择“ 无作” 以创建基本声明性代理。
在 “工作区文件夹” 列表中，选择“ 默认文件夹 ”以将项目根文件夹存储在默认位置，或浏览到要在其中放置新代理项目的文件夹。
输入 Excel Agent 作为 应用程序名称 ，然后按 Enter。
项目将在新的Visual Studio Code窗口中打开。关闭原始Visual Studio Code窗口。

配置清单

以下步骤配置清单。

打开 appPackage 文件夹中的 manifest.json 文件。

需要使用清单架构的预览版本，因此请将 $schema 和 manifestVersion 属性替换为以下内容。

"$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",
"manifestVersion": "devPreview",

在清单的根目录中，添加以下授权属性。此属性授予代理读取和写入 Office 文档的权限。

"authorization": {
  "permissions": {
    "resourceSpecific": [
      {
        "name": "Document.ReadWrite.User",
        "type": "Delegated"
      }
    ]
  }
}

在清单的根目录中，添加以下 extensions 属性。关于此代码，请注意以下事项。
- 属性 requirements.scopes 确保代理仅在 Excel 中可用，而在其他 Office 应用程序中不可用。
- 中的 runtimes 对象配置 Office 用于运行代理调用的 Office JavaScript 库 API 的 JavaScript 运行时。
- 属性 code.script 指定 JavaScript 文件的 URL，该文件包含调用 Office JavaScript 库 API 的函数。同一文件包含 Office.actions.associate 方法的调用，用于将函数映射到作 ID。在后面的步骤中创建此文件。
- 属性 code.page 指定包含嵌入 <script> 标记的网页的 URL，该标记加载属性中 code.page 引用的文件。在后面的步骤中创建此文件。
- 运行时对象包括一个 actions 数组，其中包含一个作对象
- 属性的值 actions.id 与传递给调用的作 associateID 相同。
- 属性 actions.type 设置为 executeDataFunction，这是在 Copilot 调用时可以接受参数的类型。
```
"extensions": [
  {
    "requirements": {
      "scopes": [
        "workbook"
      ]
    },
    "runtimes": [
      {
        "id": "ContosoAgentRuntime",
        "type": "general",
        "code": {
          "page": "https://localhost:3000/commands.html",
          "script": "https://localhost:3000/commands.js"
        },
        "lifetime": "short",
        "actions": [
          {
            "id": "FillColor",
            "type": "executeDataFunction"
          }
        ]
      }
    ]
  }
]
```

清单 JSON 的参考文档位于 365 应用清单架构参考Microsoft。

配置声明性代理

在 appPackage 文件夹中打开文件declarativeAgent.json。

将其内容替换为以下代码。关于此 JSON，请注意以下事项：

actions.id此文件中的属性是在中指定的文件中所有函数的actions.file集合 ID。它通常不应与清单中的匹配 extensions.runtimes.actions.id ，该清单是特定作的 ID。
在后续步骤中创建在属性中指定的 actions.file 文件。

{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.4/schema.json",
  "version": "v1.4",
  "name": "Excel Agent",
  "description": "Agent for working with Excel cells.",
  "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
  "conversation_starters": [
    {
      "title": "Change cell color",
      "text": "I want to change the color of cell B2 to orange"
    }
  ],
  "actions": [
    {
      "id": "ExcelActions",
      "file": "Office-API-local-plugin.json"
    }
  ]
}

声明性代理的参考文档位于声明性代理架构 1.4 中，适用于智能 Microsoft 365 Copilot 副驾驶®。

配置插件

在 appPackage 文件夹中创建一个文件，并为其指定分配给 actions.filedeclarativeAgent.json 文件中属性的名称： Office-API-local-plugin.json。

将以下内容粘贴到文件中。关于此 JSON，请注意以下详细信息：

API 插件配置文件指定代理作意义上的插件函数，而不是 JavaScript 函数。它包括每个作的说明。它还为 Copilot 配置运行时。 (在前面的步骤中，在清单中为 Office 配置了运行时。)
必须与 functions.name 外接程序清单中的属性匹配 extensions.runtimes.actions.id ： FillColor。
数组 runtimes.run_for_functions 必须包含与相同的字符串 functions.name 或与其匹配的通配符字符串。
属性 runtimes.spec.local_endpoint 指定与字符串关联的 FillColor JavaScript 函数在 Office JavaScript 库（而不是某些 REST 终结点）中可用。

{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
  "schema_version": "v2.3",
  "name_for_human": "Excel Agent",
  "description_for_human": "Excel actions in agent",
  "namespace": "addInFunction",
  "functions": [
    {
      "name": "FillColor",
      "description": "FillColor changes a single cell location to a specific color.",
      "parameters": {
        "type": "object",
        "properties": {
          "Cell": {
            "type": "string",
            "description": "A cell location in the format of A1, B2, etc.",
            "default": "B2"
          },
          "Color": {
            "type": "string",
            "description": "A color in hex format, e.g., #30d5c8",
            "default": "#30d5c8"
          }
        },
        "required": [
          "Cell",
          "Color"
        ]
      },
      "returns": {
        "type": "string",
        "description": "A string indicating the result of the action."
      },
      "states": {
        "reasoning": {
          "description": "`FillColor` changes the color of a single cell based on the grid location and a color value.",
          "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
        },
        "responding": {
          "description": "`FillColor` changes the color of a single cell based on the grid location and a color value.",
          "instructions": "If there is no error present, tell the user the cell location and color that was set."
        }
      }
    }
  ],
  "runtimes": [
    {
      "type": "LocalPlugin",
      "spec": {
        "local_endpoint": "Microsoft.Office.Addin"
      },
      "run_for_functions": [
        "FillColor"
      ]
    }
  ]
}

API 插件的参考文档位于 api 插件清单架构 2.3 for 智能 Microsoft 365 Copilot 副驾驶®。

创建 JavaScript 函数

在项目的根目录中，创建名为 src 的文件夹，然后在其下创建名为 命令的子文件夹。
在命令文件夹中，创建一个名为 commands.ts 的文件，并为其提供以下内容。请注意有关此代码的以下详细信息。
- 函数 fillColor 将指定单元格的背景色设置为指定颜色。它从 Office JavaScript 库调用对象和方法，后者由你在后面的步骤中创建的文件加载到 JavaScript 运行时中。
- 方法的第一个参数associate必须与清单中的属性和 functions.name API 插件 JSON 中的属性完全匹配extensions.runtimes.actions.id。
- 参数 message 是由 Copilot 运行时传递到 Office 中的 JavaScript 运行时的对象。它是一个对象，它包含用户在自然语言提示中指定的单元格地址和颜色参数，例如“将单元格 C4 设置为绿色”。
```
async function fillColor(cell, color) {
  // @ts-ignore
  await Excel.run(async (context) => {
    context.workbook.worksheets.getActiveWorksheet().getRange(cell).format.fill.color = color;
    await context.sync();
  })
}
// @ts-ignore
Office.onReady((info) => {
  // @ts-ignore
  Office.actions.associate("FillColor", async (message) => {
    const { Cell: cell, Color: color } = JSON.parse(message);
    await fillColor(cell, color);
    return "Cell color changed.";
  })
});
```
在命令文件夹中，创建一个名为 commands.html 的文件，并为其提供以下内容。需要此文件，因为 JavaScript 文件无法直接加载到 Office 用于 Copilot API 插件的运行时类型中。相反，带有元素的 <script> HTML 文件会加载 JavaScript。请注意有关此文件的以下详细信息。
- 由于文件的唯一用途是加载其他文件，因此元素 <body> 为空。该文件没有 UI，永远不会向用户显示。
- 它 从Microsoft服务器加载文件office.js（即 Office JavaScript 库）。
- 它没有元素 <script> 来加载 commands.js 文件， (从) 创建的 commands.ts 转译，因为此 <script> 元素是在生成时由你在后续步骤中添加的文件添加的。
- 在服务器上生成并提供项目时，此 HTML 文件的 URL 与清单中属性的值 extensions.runtimes.code.page 匹配。请参阅本文前面的配置清单。
```
<html>

<head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />

    
    <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1.1/hosted/office.js"></script>
</head>

<body>
</body>

</html>
```

复制项目配置文件

Office 使用 Office 外接程序的基础结构来运行 Office JavaScript 库的 API 插件。在本地 Office API 插件的初始预览期间，没有适用于此类项目的代理工具包模板。因此，代理工具包用于开发 Office 加载项的某些文件需要添加到项目中。生成这些文件的最快方法是创建外接程序项目，将外接程序项目中所需的文件复制到此代理项目，然后进行少量编辑。

打开新的Visual Studio Code窗口。
在活动栏上 选择“Microsoft 365 代理工具包 ”。
选择 “创建新代理/应用”。
选择 “Office 加载项”。
选择 “任务窗格”。
在 “工作区文件夹” 列表中，选择“ 默认文件夹 ”以将项目根文件夹存储在默认位置，或浏览到要在其中放置新代理项目的文件夹。
输入任意字符串作为 应用程序名称 ，然后按 Enter。
项目将在新的Visual Studio Code窗口中打开。关闭新的Visual Studio Code窗口和从中创建了项目的窗口。
将以下文件从创建的外接程序项目的根目录复制到 API 插件项目的根目录中。复制文件后，删除加载项项目文件夹。
- babel.config.json
- package.json
- tsconfig.json
- webpack.config.js
注意

API 插件项目不需要这些文件的某些内容。在本部分中的剩余步骤中，只需对这些文件进行最小更改，以确保插件旁加载并正确运行。我们正在努力为调用 Office JavaScript 库 API 的插件开发代理工具包项目模板。
在 Visual Studio Code 中，打开 webpack.config.js 文件。

找到对象的定义 entry ，然后从中删除属性 taskpane 。完成后，属性 entry 应如下所示。

entry: {
  polyfill: ["core-js/stable", "regenerator-runtime/runtime"],
  commands: "./src/commands/commands.ts",
},

查找数组的定义 plugins 。顶部是加载项任务窗格的 new HtmlWebpackPlugin 调用。删除的此调用 new HtmlWebpackPlugin。完成后，整个 plugins 数组应如下所示。

plugins: [
  new CopyWebpackPlugin({
    patterns: [
      {
        from: "appPackage/assets/*",
        to: "assets/[name][ext][query]",
      },
      {
        from: "appPackage/manifest*.json",
        to: "[name]" + "[ext]",
        transform(content) {
          if (dev) {
            return content;
          } else {
            return content.toString().replace(new RegExp(urlDev, "g"), urlProd);
          }
        },
      },
    ],
  }),
  new HtmlWebpackPlugin({
    filename: "commands.html",
    template: "./src/commands/commands.html",
    chunks: ["polyfill", "commands"],
  }),
],

在 appPackage 文件夹中，有两个图像文件： color.png 和 outline.png。若要使用外接程序工具基础结构，需要移动这些文件。在 appPackage 文件夹中创建名为 assets 的子文件夹，并将这两个文件移到其中。
打开manifest.json，并更改和 outline 属性的值color以匹配其新位置。完成后，属性 icons 应如下所示。
```
"icons": {
    "outline": "assets/outline.png",
    "color": "assets/color.png"
},
```

测试代理和插件

在命令行界面 (CLI) 中，导航到 API 插件项目的根目录，然后运行 npm install。等待安装完成。
关闭所有 Office 应用程序。
在“Visual Studio Code”中，在活动栏上选择“Microsoft 365 代理工具包”，然后在“帐户”窗格中，确保登录的 Microsoft 365 帐户中启用了 Copilot 支持和上传自定义应用。
在“生命周期”窗格中选择“预配”。

除其他事项外，预配使用包 zip 文件在 appPackage 文件夹中创建生成文件夹。该文件包含代理和插件的清单和 JSON 文件。
在项目根目录中的 CLI 中，运行 npm run dev-server 以在 localhost 上启动服务器。

注意

如果系统提示删除旧证书和/或安装新证书，请同意这两个提示。

等待，直到在服务器窗口中看到类似于以下示例的行，指示已成功编译应用。此输出表示服务器正在运行并为文件提供服务。
```
webpack 5.99.8 compiled successfully in 1090 ms
```
测试的第一步取决于平台。
- 若要在 Windows 上的 Office 中进行测试，请打开 Excel，然后打开 (或创建工作簿) 。
- 若要在Office web 版进行测试，请在浏览器中导航到 https://excel.cloud.microsoft，然后打开 (或创建工作簿) 。
从功能区中打开 Copilot ，然后在“ Copilot ”窗格中选择汉堡控件。 Excel 代理 应位于代理列表中。 (可能需要选择“ 查看更多 ”以确保列出所有代理。) 如果未列出代理，请尝试以下一项或两项作。
- 等待几分钟，然后重新加载 Copilot。
- 当 Copilot 打开代理列表时，将光标放在 Copilot 窗口上，然后按 Ctrl+R。
选择 “Excel 代理”，选择“ 更改单元格颜色 ”对话启动器，然后在窗格底部的对话框中选择“ 发送 ”控件。几秒钟后，应会看到如下所示的确认提示。
选择 “确认 ”以响应确认提示。单元格的颜色应会更改。

提示

如果 Copilot 报告错误，请重复提示，但在提示符中添加以下句子：“如果收到错误，请向我报告错误的完整文本。
尝试在对话框中输入单元格和颜色的其他组合，例如“将单元格 G5 设置为天空的颜色”。

在代理中进行更改

预览期不支持 Office API 插件的实时重载和热重载。若要进行更改，请先关闭服务器，然后通过以下步骤卸载代理。

关闭服务器取决于运行服务器的窗口。
- 如果 Web 服务器在运行的同一命令提示符或Visual Studio Code终端npm run dev-server中运行，则提供窗口焦点并按 Ctrl+C。若要结束该过程，请选择“Y”以响应提示。
- 如果 Web 服务器在单独的窗口中运行，则在命令提示符、bash shell 或项目根目录中Visual Studio Code终端中运行 npm run stop。服务器窗口关闭。
按照手动清除缓存中的说明清除 Office 缓存。
打开 Teams，从活动栏中选择“ 应用 ”，然后选择 “应用 ”窗格底部的“管理应用 ”。
在应用列表中查找 Excel Agentdev 。
若要展开其行，请选择名称左侧的箭头。
选择行右端附近的垃圾桶图标，然后在提示符中选择“ 删除 ”。

进行更改，然后重复测试代理和插件中的步骤。

通过