生成第一个加载项作为 Copilot 技能

2025-06-10

在本文中，你将逐步完成构建一个简单的 Excel Copilot 代理的过程，该代理可以对 Excel 工作簿的内容执行作。该应用还包括 Excel 任务窗格加载项。

知识先决条件

基本了解智能 Microsoft 365 Copilot 副驾驶® 中的声明性代理。如果还不熟悉它们，我们建议执行以下作。
- 阅读声明性代理，了解智能 Microsoft 365 Copilot 副驾驶®概述。
- 完成从使用 Microsoft 365 代理工具包创建声明性代理开始的教程。

软件先决条件

使用 Microsoft 365 代理工具包创建声明性代理中列出的所有先决条件。
Microsoft 365 代理工具包。

Office 加载项入门

使用以下步骤创建基本 Excel 加载项。

按照使用 Microsoft 365 代理工具包创建 Office 外接程序项目中的说明，在 Microsoft 365 代理工具包中创建 Office 外接程序。 创建项目后停止。不要执行旁加载部分中的步骤。

注意

当系统提示为加载项命名时，请使用“Excel 外接程序 + 代理”。
项目将在新的Visual Studio Code窗口中打开。关闭原始Visual Studio Code窗口。
在命令提示符下或Visual Studio Code项目根目录中的终端中，运行 npm install。

旁加载并测试加载项

通过执行以下步骤测试加载项是否正常工作。
1. 选择“视图” |在 Visual Studio Code 中运行。在“运行和调试”下拉菜单中，选择“Excel Desktop (Edge Chromium) ”。
2. 按 F5。项目生成并打开节点开发服务器窗口。此过程可能需要几分钟时间。最终，Excel 将打开。
注意

如果这是您首次 (或一个多月) 首次旁加载 Office 加载项，则系统可能会提示删除旧证书和/或安装新证书。同意这两个提示。
1. 选择“主页”功能区上的“加载项”按钮，然后在打开的浮出控件中，选择加载项。
2. 带有“显示任务窗格”按钮的 Contoso 外接程序组将显示在“开始”功能区上。使用按钮打开加载项的任务窗格。
注意

如果出现 “加载时 WebView 停止” 提示，请选择“ 确定”。
1. 打开任务窗格后，选择“ 运行”。工作表中的单元格将更改为黄色。
2. 停止调试和卸载加载项，方法是关闭 Excel 并在命令提示符下运行npm run stop，或者在项目根目录中Visual Studio Code终端。
  
  重要
  
  由于 bug，目前在 Visual Studio Code 的 UI 中停止调试不起作用。此外，关闭 Excel 或手动关闭开发服务器窗口都不会可靠地关闭服务器或导致 Excel 取消获取加载项。必须运行 npm run stop。

添加 Copilot 声明性代理

使用以下步骤添加代理。

在清单文件中，进行以下更改。
1. 将以下对象添加到根目录。按照约定，它将放在“validDomains”属性的正下方。在后面的步骤中创建“declarativeAgent.json”文件。
```
"copilotAgents": {
  "declarativeAgents": [
    {
      "id": "ContosoCopilotAgent",
      "file": "declarativeAgent.json"
    }
  ]
},
```
2. 数组中 "extensions.runtimes" 有多个对象。找到其 "id" 为“CommandRuntime”的，并将其复制为数组中的其他运行时对象。
3. 对此附加的运行时对象进行以下更改。
  1. 将 "id" 从“CommandRuntime”更改为“CopilotAgentActionsRuntime”。
  2. 将其 "actions.id" 属性更改为“fillcolor”。这是在后续步骤中添加的函数的 ID。
  3. 将 "actions.type" 属性更改为“executeDataFunction”。
在名为 declarativeAgent.json的 appPackage 文件夹中创建文件。

将以下内容粘贴到文件中。 (在后面的步骤中创建此 JSON 中提到的 Excel-API-local-plugin.json 文件。)

{
     "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.4/schema.json",
     "version": "v1.4",
     "name": "Excel Add-in + 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": "localExcelPlugin",
             "file": "Excel-API-local-plugin.json"
         }
     ]
 }

在名为 Excel-API-local-plugin.json的 appPackage 文件夹中创建文件。

将以下内容粘贴到文件中。

{
     "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
     "schema_version": "v2.3",
     "name_for_human": "Excel Add-in + Agent",
     "description_for_human": "Add-in Actions in Agents",
     "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",
                 "allowed_host": ["workbook"]
             },
             "run_for_functions": ["fillcolor"]
         }
     ]
 }

打开 \src\commands\commands.ts 文件，并在其末尾添加以下代码。

async function fillcolor(cell, color) {
    await Excel.run(async (context) => {
         context.workbook.worksheets
             .getActiveWorksheet()
             .getRange(cell).format.fill.color = color;
         await context.sync();
     })
}

Office.onReady((info) => {
     Office.actions.associate("fillcolor", async (message) => {
         const {Cell: cell, Color: color} = JSON.parse(message);
         await fillcolor(cell, color);
         return "Cell color changed.";
     });
});

更新组合加载项和 Copilot 代理的项目配置文件

项目根目录中有一个名为 teamsapp.yaml 或 m365agents.yaml 的文件。将其内容替换为以下内容：

# yaml-language-server: $schema=https://aka.ms/teams-toolkit/v1.7/yaml.schema.json
# Visit https://aka.ms/teamsfx-v5.0-guide for details on this file
# Visit https://aka.ms/teamsfx-actions for details on actions
version: v1.7

environmentFolderPath: ./env

# Triggered when 'teamsapp provision' is executed
provision:
# Creates a Teams app
  - uses: teamsApp/create
    with:
     # Teams app name
     name: Contoso Agent ${{APP_NAME_SUFFIX}}
    # Write the information of created resources into environment file for
    # the specified environment variable(s).
    writeToEnvironmentFile:
     teamsAppId: TEAMS_APP_ID

# Build Teams app package with latest env value
  - uses: teamsApp/zipAppPackage
    with:
     # Path to manifest template
     manifestPath: ./appPackage/manifest.json
     outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
     outputFolder: ./appPackage/build
# Validate app package using validation rules
  - uses: teamsApp/validateAppPackage
    with:
     # Relative path to this file. This is the path for built zip file.
     appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
# Extend your Teams app to Outlook and the Microsoft 365 app
  - uses: teamsApp/extendToM365
    with:
     # Relative path to the build app package.
     appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
    # Write the information of created resources into environment file for
    # the specified environment variable(s).
    writeToEnvironmentFile:
     titleId: M365_TITLE_ID
     appId: M365_APP_ID

# Triggered when 'teamsapp publish' is executed
publish:
# Build Teams app package with latest env value
  - uses: teamsApp/zipAppPackage
    with:
     # Path to manifest template
     manifestPath: ./appPackage/manifest.json
     outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
     outputFolder: ./appPackage/build
# Validate app package using validation rules
  - uses: teamsApp/validateAppPackage
    with:
     # Relative path to this file. This is the path for built zip file.
     appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
# Apply the Teams app manifest to an existing Teams app in
# Teams Developer Portal.
# Will use the app id in manifest file to determine which Teams app to update.
  - uses: teamsApp/update
    with:
     # Relative path to this file. This is the path for built zip file.
     appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
# Publish the app to
# Teams Admin Center (https://admin.teams.microsoft.com/policies/manage-apps)
# for review and approval
  - uses: teamsApp/publishAppPackage
    with:
     appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
    # Write the information of created resources into environment file for
    # the specified environment variable(s).
    writeToEnvironmentFile:
     publishedAppId: TEAMS_APP_PUBLISHED_APP_ID
projectId: da53b0a2-1561-415e-919a-5b870bcd2f49

将上一步中粘贴的最后一行内容中的值 projectId 替换为新的随机生成的 GUID。
打开 \env.env.dev 文件，将以下行添加到文件末尾，紧跟在“ADDIN_ENDPOINT=”行后面。
```
TEAMS_APP_ID=
TEAMS_APP_TENANT_ID=
M365_TITLE_ID=
M365_APP_ID=
```

测试加载项和代理

关闭所有 Office 应用程序。
打开 Microsoft 365 代理工具包。
在“ 生命周期 ”窗格中，选择“ 预配”。除其他事项外，预配将执行以下作：
- 为添加到 .env.dev 文件的四行设置值。
- 使用包 zip 文件在 /appPackage 文件夹中创建 /build 文件夹。该文件包含代理和插件的清单和 JSON 文件。
在命令提示符或项目根目录中Visual Studio Code终端中，运行 npm run dev-server 以在 localhost 上启动服务器。等到在服务器窗口中看到应用编译成功的行。这意味着服务器正在运行并为文件提供服务。

注意

如果这是一个多月来首次在计算机上为 Office 加载项运行本地服务器，则系统可能会提示你删除旧证书和/或安装新证书。同意这两个提示。
测试的第一步取决于平台。
- 若要在 Windows 上的 Office 中进行测试，请打开 Excel。稍后，“ 显示任务窗格” 按钮将显示在 Contoso 外接程序组中 的“主页 ”功能区上。 (如果功能区上未显示，请选择功能区上的“ 加载项 ”按钮，然后在打开的浮出控件中选择 “Excel 外接程序 + 代理 ”应用。)
- 若要在 Office web 版中进行测试，请在浏览器中导航到 https://excel.cloud.microsoft.com/，然后创建新工作簿。
从功能区中打开 Copilot ，然后在“ Copilot ”窗格中选择汉堡控件。 Excel 外接程序 + 代理 应位于代理列表中。 (可能需要选择“ 查看更多 ”以确保列出所有代理。) 如果代理不是，请尝试以下一项或两项作。
- 等待几分钟，然后重新加载 Copilot。
- 打开 Copilot 到代理列表后，单击 Copilot 窗口上的光标，然后按 Ctrl+R。
列出代理后，将其选中。此时会打开 “Excel 加载项 + 代理 ”窗格。
选择“ 更改单元格颜色 对话”启动器，然后按窗格底部对话框中的 “发送 ”控件。选择 “确认 ”以响应确认提示。单元格的颜色应会更改。

提示

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

在加载项或代理中进行更改

预览版期间不支持合并的加载项和代理的实时重载和热重载。若要进行更改，请先关闭服务器，然后通过以下步骤卸载扩展。

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

进行更改，然后重复测试加载项和代理中的步骤。

疑难解答

请参阅对组合加载项和代理进行故障排除。

后续步骤

将 Copilot 代理添加到现有加载项

通过