插件是一个可安装包,可以包含 内置 或 自定义 技能、工具和代理。 Copilot 附带内置技能。 自定义技能由创建者创建。 将自定义技能打包到插件中时,用户可以安装它以扩展Copilot的功能。
Microsoft Copilot Cowork 支持通过 M365 应用包实现的可扩展性,该应用包与 Teams 应用、Copilot 代理和 Office 加载项使用的分发机制相同。可以使用以下方式扩展 Cowork:
- 技能:基于提示的工作流,可让 Cowork 掌握新的领域专业知识,例如财务分析、法律研究或 HR 工作流。
- 连接器:为同事提供对外部数据源和 API 的访问权限的远程服务器。
两者都打包在一个标准的 Microsoft 365 应用包中,并通过 Microsoft 365 App Store 分发。
Important
插件或技能管理和共享目前不支持Microsoft Purview 信息屏障(IB)。 在启用了 IB 的租户中,将在租户级别阻止嵌入知识文件上传。 这样可以防止受影响的插件和技能被上传或发布。
Microsoft 不会创建或维护任何持久索引、知识图(包括 Microsoft Graph)或包含 ISV 内容的数据库,无论是通过爬网、抓取、采集、批量导出、导入,还是任何其他方法(通过 API、MCP 服务器或其他方式)。 Microsoft可能会根据需要临时处理 ISV 内容以响应用户的实时查询,但不会在该会话持续时间之外保留 ISV 内容。 根据 ISV 的书面请求,Microsoft 将在 10 个工作日内删除其拥有或控制的任何 ISV 内容,并以书面形式证明此类删除。 在 Microsoft Copilot 和 Microsoft Copilot 对话助手中的企业数据保护中了解详细信息。
构建与发布<
创作和打包插件不同于发布到注册中心、管理员审批/分配、用户安装和服务登录。
- Work IQ Dev Tools 可以面向选定受众发布到注册中心。
- 与特定人员共同共享不需要管理员批准。
- 组织范围的共享需要管理员批准。
- 直接共享不是 Marketplace 提供项。
若要使插件更易于发现和管理,请浏览共享插件注册表。 插件注册表是常见的Microsoft Copilot基础结构,它允许发布一次插件,由用户发现,提供给受支持的Copilot体验,并由管理员集中管理。 在 插件中心了解详细信息。
注释
并非每个打包组件在 Cowork 中都有效。 现有插件可能不会自动迁移。
Prerequisites
使用此列表了解 Cowork 插件支持和需要的内容。
-
为 Copilot Cowork 构建插件
- 智能 Microsoft 365 Copilot 副驾驶® 许可证:Cowork 用户必需具备此许可证。
- 支持的管理员角色:使用 AI 管理员 或 全局管理员 进行 MCP 审批和租户许可。
-
开发工具
- Work IQ Dev Tools:用于打包、验证、预配、共享和发布请求。
- Microsoft 365 Agents Toolkit:用于智能体和应用开发和打包。
- 插件生成器(前代理生成器):创作环境;发布范围待确认。
- Cowork 上传:导入受支持的包,而不是完整的开发工作流。
-
有效的包格式:使用Microsoft 365应用包格式(
manifest.json带有agentSkills和agentConnectors声明)。 - 所需架构:遵循 声明性代理清单 1.9 标准。
-
发布方式
- 直接共享(通过 Work IQ Dev Tools 或
wiqd plugin share)。 - 组织上传(在 Microsoft 365 管理中心 中,选择代理>工具>注册表>上传)。
- Microsoft市场
- 直接共享(通过 Work IQ Dev Tools 或
-
许可和同意
- 每个用户需要智能 Microsoft 365 Copilot 副驾驶®许可证。
- MCP 注册和服务器链接插件需要管理员同意。
-
治理和访问
- 插件已托管。 若要查找它们,请在 Microsoft 365 管理中心 和 Microsoft Agent 365 中选择工具。
- 策略和发布者类别控制。 若要查找它们,请选择 代理>设置>代理和插件访问。
-
兼容性:遵循行业标准的
agentskills.io技能格式。
您将构建的内容
Cowork 插件是一个.zip包含以下内容的包:
my-extension.zip
├── manifest.json # M365 Unified App Manifest (v1.28)
├── color.png # 192×192 full-color app icon
├── outline.png # 32×32 outline icon
└── skills/ # Agent Skills (SKILL.md files)
├── skill-one/
│ ├── SKILL.md
│ └── references/ # Optional deep-dive docs
└── skill-two/
└── SKILL.md
技能采用 Agent Skills 开放标准——即 Claude Code、Visual Studio Code Copilot、Gemini CLI、Cursor、JetBrains Junie 和另外 30 多种 AI 工具支持的同一种格式。
选择起点
使用 wiqd CLI 构建您的插件。 CLI 会构建包,并使 manifest.json 与您的技能文件夹保持同步。它还会在上传之前运行平台自己的验证规则,然后预配和共享结果。 CLI 处于预览状态,因此其命令和生成的输出可能会在正式发布之前发生更改。 它生成的所有内容都是简单的 Microsoft 365 应用包,因此您仍然可以直接打开、编辑文件并对其进行版本控制。
仅在无法安装工具或需要构建自己的打包管道时,才手动装配包。 在这种情况下,本文中的 包格式参考 正是您需要的——它准确说明了 wiqd 会生成什么。
| 起点 | 执行此操作 | 首次打包时间 |
|---|---|---|
| 我从零开始 | 使用 wiqd 生成插件 | 约10分钟 |
| 我已经有一个 Claude Code 插件 | 转换 | 约5分钟 |
| 我无法安装工具,或只能编写自己打包的脚本 | 手动组装包 | 大约 30 分钟 |
使用 wiqd 构建插件
wiqd CLI 运行的生命周期与您手动执行的相同 - 创建、添加功能、验证、预配、打包和共享。 它生成的包已满足本文中的 验证规则 。
步骤 1:安装 wiqd 并登录
按照 wiqd 安装指南安装 wiqd CLI,该指南涵盖 Windows、macOS 和 Linux。 然后登录到您正在针对其进行开发的 Microsoft 365 租户,因为预配和共享都涉及该租户:
wiqd auth login --interactive
安装程序还注册 GitHub Copilot CLI 插件,因此您可以使用对话方式驱动相同的生命周期。 例如,可以说“创建名为 Triage Helper 的独立插件”或“验证我的插件。”。对话路径运行与本部分相同的命令。 在编写管道脚本或希望实现可重现的非交互式自动化时,请直接使用这些命令。
第 2 步:搭建插件并添加能力
创建插件容器,然后以任意组合添加所需的任何功能:
wiqd plugin create --name my-plugin
wiqd plugin add skill --name "Contract Analysis"
wiqd plugin add connector --name "Contoso Legal" --description "Case law and statutes over MCP" --url https://api.contoso.com/legal/mcp
add skill 生成 appPackage/skills/contract-analysis/SKILL.md 并将其注册到 agentSkills[]。
add connector 写入 agentConnectors[] 条目。 这两个命令在写入前都会强制执行平台的命名和大小上限,因此文件夹名称不匹配或长度过长的 id 不会写入清单。
在生成的 SKILL.md 中编写您的技能逻辑。 前言字段、渐进式加载模型和配套文件限制如步骤 1:创建您的第一个技能和步骤 2:添加参考资料(可选)中所述。
Important
wiqd plugin create 将包固定到 manifestVersion: "1.29",而本文中的手动编写示例使用 1.28。 这种差异对于连接器很重要。 在 1.28,mcpToolDescription 是必需的,并且它命名的文件必须包含在 ZIP 中。 在 1.29 版本中,agentConnectors[] 条目仅有 URL,且 mcpToolDescription 为可选项,因此 wiqd 生成的软件包绝不会触发那种上传失败。 wiqd 尚不构建连接器身份验证 - 如支持的身份验证类型中所述直接进行配置。
步骤 3:在构建过程中进行验证
持续验证,而不是组装包并希望上传通过:
wiqd plugin validate
wiqd plugin validate --mode deep
validate 是针对声明性代理范围的脱机静态检查。 仅限技能或仅限连接器的插件会通过该检查,因为没有可检查的内容,这是符合预期的——它检查的是你的构建流程,而不是全面覆盖。
validate --mode deep 先打包插件,然后根据上传使用的同一应用验证库验证生成的 .zip 插件。 这就是 ASKILL 代码 和连接器规则出现的地方。
步骤 4:预配资源、打包和共享
按顺序运行这三个命令:
wiqd plugin provision
wiqd plugin package
wiqd plugin share --scope users --email you@contoso.com
先运行 provision,因为它会编写 package 和 share 都依赖的环境文件。 使用 --scope users 与您列出的人员共享,或使用 --scope tenant 与组织中的所有人共享。 无论哪种方式,插件都会显示在 与我共享 中,位置位于 >>插件 下。 若要将其列在发现部分中,则由管理员上传包。 有关详细信息,请参阅 步骤 8:发布到你的租户。 若要删除 provision 创建的内容,请运行 wiqd plugin delete --env local --yes。
在合作伙伴中心中,公共应用商店提交仍需手动完成。 在步骤 9:向公众发布中了解详细信息。
可以在 发布或共享插件 和 使插件可用 中找到完整的发布方式和下一步指南。
将插件转移到另一台主机
若要在 Claude Code、Cursor 或任何其他智能体技能主机中使用您的技能,请导出项目,而不是手动复制文件夹:
wiqd plugin export --format claude-plugin
export 默认为 --format open-plugin,也接受 cursor-plugin。 它在 <path>/export/<format> 下写入一个未压缩的目录。
导入现有插件
如果您已经拥有带有技能和 MCP 服务器的 Claude Code 插件,则有两条转换路线。 您选择的路线取决于您是打算继续开发插件,还是仅发布当前已有的版本。
| 目标 | Use |
|---|---|
| 继续从 Microsoft 365 中开发、验证和发布该插件 | wiqd plugin import |
立即从现有 Claude 插件生成可发布的 .zip |
转换脚本 |
使用 wiqd 导入
wiqd plugin import 识别 Open Plugin、Claude 插件或 Cursor 插件源,并从中生成 wiqd 插件项目。 导入的插件将加入与您使用 wiqd plugin create 创建的插件相同的生命周期:
wiqd plugin import --path ./my-claude-plugin --privacy-url https://contoso.com/privacy --terms-url https://contoso.com/terms
--privacy-url 并且 --terms-url 仅在插件的第一次导入时是必需的。 如果源来自以前的 wiqd plugin export,则往返元数据已包含它们。
Important
导入的项目仅支持生命周期的只读部分——wiqd plugin validate、show 和 list。 它尚不能打包、预配或共享,因为导入不会生成这些步骤所需的本地部署文件。 这是一个已跟踪的差距。 有关当前状态,请检查 wiqd CLI 参考。 如果您现在需要一个可发布的包,请使用转换脚本。
使用转换脚本进行转换
转换脚本将 Claude 插件直接转换为可发布的 M365 包:
安装 CLI (需要版本 1.1.12 或更高版本) :
npm install -g @microsoft/m365agentstoolkit-cli验证版本:
atk --version导入您的插件:
atk import openplugin --path ./my-claude-plugin --output ./my-plugin-project \ --privacy-url https://contoso.com/privacy \ --terms-url https://contoso.com/terms
该命令读取插件的 .claude-plugin/plugin.json(或 .cursor-plugin/plugin.json)、skills/ 和 .mcp.json 目录,然后搭建一个 Agents Toolkit 项目,其中包含 appPackage/manifest.json、你的技能和生成的图标。
必须包括 --privacy-url 和 --terms-url ,因为插件清单没有等效字段,而 Microsoft 365 清单需要这两个字段。
注释
atk import openplugin在点前缀目录——.claude-plugin/plugin.json、.cursor-plugin/plugin.json或.plugin/plugin.json——中查找插件清单,且与.mcp.json并列。
Agent Plugins 1.0.0 规范将清单置于顶级 plugin.json,MCP 配置位于 mcp.json。 若要导入遵循 1.0.0 布局的插件,请将其清单移动到 .plugin/plugin.json 并重命名 mcp.json 为 .mcp.json。
将结果打包为可上传的包 .zip:
cd my-plugin-project
atk package --manifest-file ./appPackage/manifest.json \
--output-package-file ./appPackage/build/appPackage.zip \
--output-folder ./appPackage/build
注释
atk import openplugin 生成一个 devPreview 清单。 本文其他位置的清单示例面向架构 v1.28。 如果您要通过需要 v1.28 的渠道发布,在生成的 appPackage/manifest.json 中更新 manifestVersion 和 $schema。
导入内容
| 插件项目 | M365 等效 | 笔记 |
|---|---|---|
.claude-plugin/plugin.json |
manifest.json |
名称、说明和开发人员字段已映射;GUID 自动生成(确定性 UUID v5) |
skills/*/SKILL.md |
agentSkills[] 个条目 + skills/ 个文件夹 |
逐字复制 - 相同格式 |
.mcp.json 服务器 |
agentConnectors[] 条目 |
自动检测 URL 和身份验证类型 |
color.png / outline.png |
包中的图标 | 如果存在,则使用;如果缺少,则生成占位符 |
Important
对于从 .mcp.json 导入的每个连接器,生成的 authorization.referenceId 是从插件和服务器名称派生的占位符。 发布前将其替换为实际的 OAuth 客户端注册 ID。 有关详细信息,请参阅 支持的身份验证类型。
未转换的内容
Microsoft 365 清单尚不支持以下 Claude 插件功能:
| Claude 插件功能 | Status |
|---|---|
commands/ (斜杠命令) |
尚不支持 |
agents/ (子代理) |
尚不支持 |
hooks/ (事件处理程序) |
尚不支持 |
settings.json |
不適用 |
bin/ (可执行文件) |
不適用 |
导入选项
| 选项 | Description |
|---|---|
--path、-p |
Required. 包含 .claude-plugin/plugin.json、.cursor-plugin/plugin.json 或 .plugin/plugin.json 的插件目录 |
--output、-o |
目标项目文件夹 (默认值: ./<plugin-name>) |
--privacy-url |
developer.privacyUrl 用于生成的清单 |
--terms-url |
developer.termsOfUseUrl 用于生成的清单 |
--website-url |
developer.websiteUrl。 回退到 homepage,然后回退到 author.url |
--app-id |
覆盖为清单 id 生成的确定性 UUID v5 |
--default-auth-type |
Auto (默认值)、 None、 OAuthPluginVault或 ApiKeyPluginVault |
身份验证类型自动检测:
| Source | 默认身份验证类型 | 原因 |
|---|---|---|
| 外部 HTTPS URL | OAuthPluginVault |
大多数远程 API 需要身份验证 |
localhost 和非 HTTPS URL |
None |
本地开发服务器 |
如果自动检测结果与您的配置不匹配,请使用 --default-auth-type 覆盖该结果。
导出回插件目录
若要将智能体工具包项目移回插件目录(例如,保持 Claude Code 插件和 Cowork 包同步),请使用atk export openplugin:
atk export openplugin --path ./my-plugin-project \
--output ./my-claude-plugin --manifest-kind claude-plugin
| 选项 | Description |
|---|---|
--path、-p |
Required. Agents Toolkit 项目文件夹,其中包含 appPackage/manifest.json |
--output、-o |
目标插件目录(默认值:./<plugin-name>-openplugin) |
--manifest-kind |
open-plugin (默认值、写入 .plugin/plugin.json)、 claude-plugin或 cursor-plugin |
导出会将一个 x-microsoft-365-agents-toolkit 块写入生成的 plugin.json 中。 该块包含清单 id、开发人员 URL 和连接器设置,因此后续 atk import openplugin 会进行往返,不再需要 --privacy-url 或 --terms-url。
注释
x-microsoft-365-agents-toolkit 块特定于智能体工具包,默认 open-plugin 类型将清单写入 .plugin/plugin.json。
代理插件 1.0.0 使用顶级 plugin.json 数据,并在具有反向域命名空间的密钥下 extensions 携带特定于客户端的数据,因此其他客户端将忽略此块,而不是对此执行操作。 当目标是 Claude Code 或 Cursor 时,请使用 --manifest-kind claude-plugin 或 cursor-plugin。
旧版:PowerShell 转换脚本
在支持插件导入之前 atk ,转换使用仅限 Windows 的 PowerShell 脚本,该脚本仍可用作 转换脚本:
.\Convert-ClaudePluginToMOS3.ps1 -PluginPath ./my-claude-plugin -OutputPath ./output
改用 atk import openplugin。 它是跨平台的,支持 Cursor 和 Claude Code 源,并且可以导出回插件目录。
手动装配包
本部分是包格式参考:它逐字段准确描述使用 wiqd 构建插件生成的内容。 当无法安装工具或正在构建自己的打包管道时,请端到端地遵循它。 当您需要了解或调试生成的包时,可将其作为参考。
第 1 步:创建第一项技能
技能是包含 SKILL.md 文件的文件夹。 创建以下文件夹结构:
my-extension/
└── skills/
└── contract-analysis/
└── SKILL.md
使用 YAML 前言和 Markdown 正文编写 SKILL.md:
---
name: contract-analysis
description: |
Analyzes contracts for key terms, risks, and obligations.
Use when user asks to "review this contract", "find the liability clause",
"summarize the key terms", or "compare these two agreements".
license: MIT
metadata:
author: Contoso Legal Tech
version: "1.0"
---
# Contract Analysis
## What This Skill Does
Guides Cowork through systematic contract review, identifying:
- Key commercial terms (pricing, payment, renewal)
- Risk clauses (indemnification, limitation of liability, IP)
- Obligations and deadlines
- Non-standard or unusual provisions
## Workflow
1. Read the uploaded contract document
2. Extract and categorize all clauses
3. Flag risk areas with severity ratings
4. Generate a structured summary with recommendations
## Output Format
Present findings in a structured table:
| Clause | Category | Risk Level | Summary |
|--------|----------|------------|---------|
| Section 4.2-Indemnification | Risk | High | Unlimited indemnification for IP claims |
| Section 7.1-Term | Commercial | Low | 12-month auto-renewal with 30-day notice |
SKILL.md frontmatter 字段
必填字段:
| 领域 | 限制条件 | Description |
|---|---|---|
name |
1-64 个字符,kebab-case | 技能标识符 - 必须与文件夹名称完全匹配 |
description |
1-1024 个字符 | 何时使用此技能 - 包含触发短语 |
Important
- 文件夹名称必须与 frontmatter 中的
name字段匹配。 这种不匹配是导致技能运行失败的最常见原因。 - 插件列表
description字段不应包含将用户引导到外部市场购买订阅的行动号召。
| 文件夹路径 |
name 字段 |
有效? | 为什么 |
|---|---|---|---|
skills/contract-analysis/SKILL.md |
contract-analysis |
Yes | 文件夹和名称匹配 |
skills/contract-analysis/SKILL.md |
ContractAnalysis |
No | 名称使用 PascalCase 而不是匹配文件夹 |
skills/my-skill/SKILL.md |
contract-analysis |
No | 文件夹是 my-skill,但名称是 contract-analysis |
命名规则(kebab-case): 仅使用小写字母数字字符和连字符。 不要使用连续连字符,也不要使用前导或尾随连字符。
| 示例 | 有效? | Issue |
|---|---|---|
bond-relative-value |
Yes | 小写字母加连字符 |
fx-carry-trade |
Yes | 小写字母加连字符 |
email |
Yes | 单个单词,无需连字符 |
Bond_Relative_Value |
No | 下划线和大写字母 |
--my-skill-- |
No | 前导和尾随连字符 |
my--skill |
No | 连续连字符 |
步骤 2:添加参考资料 (可选)
对于复杂的技能,请保持主要 SKILL.md 精简,并将详细内容移动到子目录。 这些附加文件是配套文件。 技能会在需要时加载它们。
skills/
└── contract-analysis/
├── SKILL.md # Core workflow (~1,500-2,000 words ideal)
├── references/ # Deep-dive docs loaded on demand
│ ├── clause-taxonomy.md
│ └── risk-scoring.md
└── scripts/ # Executable utilities
└── extract-clauses.py
配套文件限制
每个技能最多可以包含 20 个配套文件(除 SKILL.md 之外的任何文件)。 对每个技能应用以下限制:
| Limit | Value |
|---|---|
| 最大配套文件数 | 20 |
| 每个配套文件的最大大小 | 5 兆字节 |
| 配套总大小上限 | 10 MB |
| 下载超时(所有配套) | 15 秒 |
配套文件规则
配套文件路径必须遵循以下规则:
- 仅使用相对路径(不使用绝对路径)。
- 没有路径遍历 (
..段) 。 - 文件名中没有反斜杠或空字节。
- 无隐藏文件(名称以
.开头)。 - 没有 Windows 保留名称(
CON、PRN、AUX、NUL、COM1-COM9、LPT1-LPT9)。 - 文件
SKILL.md本身不算作配套文件。 - 文件名必须使用安全字符:字母数字、连字符、下划线、点、空格和
!。
为了提高上下文窗口的效率,系统分三层加载技能:
| 层 | 加载时 | 目标大小 |
|---|---|---|
前言 (name + description) |
始终 - 启动时 | ~100 个令牌 |
SKILL.md 正文 |
技能触发时 | 少于 5,000 个令牌 (1,500-2,000 个单词) |
参考资料 (references/) |
由智能体按需执行 | 无限制 |
脚本 (scripts/) |
已执行,未加载到上下文中 | N/A |
在 SKILL.md 中显式注明子目录,以便代理知道它们的存在:
## Additional Resources
- **`references/clause-taxonomy.md`**-Full taxonomy of contract clause types
- **`references/risk-scoring.md`**-Risk scoring methodology and thresholds
- **`scripts/extract-clauses.py`**-Automated clause extraction utility
步骤 3:添加连接器 (可选)
如果扩展需要访问外部数据,请添加远程 MCP 服务器。 此步骤是可选的。 仅限技能包非常适合基于提示的工作流。
Tip
如果您的服务器按客户端控制工具可见性,或对传入流量进行归因,请参阅 识别发往您的服务器的 Cowork 流量,了解有关 Cowork 向您的服务器呈现的客户端身份的详细信息。
注释
Cowork 移动版不支持自定义插件。
连接器要求
| 要求 | Details |
|---|---|
| Transport | 可流式处理 HTTP (需要 HTTPS,TLS 1.2+) |
| Protocol | JSON-RPC 2.0 消息格式 |
| 工具探索 | 支持 tools/list 进行动态发现(推荐) |
| 工具执行 | 支持使用 tools/call 进行调用 |
| Availability | 建议为在应用商店发布的应用提供 99.9% 正常运行时间 SLA |
| 答复时间 | 每次工具调用少于 30 秒 |
工具设计准则
-
对于小型 API,每个操作一个工具(少于 15 个操作):
search_case_law、get_ruling、cite_precedent -
搜索 + 执行 适用于大型 API(50+ 操作):
search_actions+execute_action -
描述性名称:
get_bond_price,而不是getData - 丰富的输入架构:包括每个参数的说明 - 这是代理读取的内容
- 结构化输出:返回代理可以为用户设置格式的 JSON
- 文件输入:若要接受用户工作区中的文件,请使用 声明该参数。 在从 Cowork 工作区接受文件中了解详细信息。
描述您的连接器的工具 (mcpToolDescription)
remoteMcpServer连接器可以选择包含mcpToolDescription对象。 如果提供,其嵌套的 file 属性指向您打包在 .zip 内的工具说明 JSON 文件,并通过与包根目录的相对路径进行引用。 Cowork 从 MCP 服务器动态发现工具,并且不会使用此文件,即使它存在。
"remoteMcpServer": {
"mcpServerUrl": "https://api.contoso.com/legal/mcp",
"mcpToolDescription": {
"file": "./tools/contoso-legal-tools.json"
},
"authorization": {
"type": "OAuthPluginVault",
"referenceId": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u"
}
}
如果包含 tools/contoso-legal-tools.json,则被引用的文件(例如 mcpToolDescription)会描述连接器公开的工具,并且必须存在于 ZIP 包中。 打包插件时,将其与您的 manifest.json 和 skills/ 文件夹一起包含在内。
Tip
此要求适用于清单版本 1.28。
agentConnectors[]生成的软件包以 1.29 为目标,其中 wiqd plugin create 条目仅为 URL,mcpToolDescription 是可选的,而且没有容易被遗漏的工具说明文件。
支持的身份验证类型
| 身份验证类型 | 何时使用 | 用户体验 |
|---|---|---|
None |
公共或匿名 API、内部服务 | 透明 - 无身份验证提示 |
OAuthPluginVault |
OAuth 2.0 接口(建议用于生产环境) | 用户完成 OAuth 同意一次 |
ApiKeyPluginVault |
基于 API 密钥的服务 | 用户提供密钥一次 |
注释
- Cowork 尚不支持 API 密钥身份验证。
- 如果 MCP 服务器需要 API 密钥,请改用
OAuthPluginVault或动态客户端注册,或者公开一个接受None的终结点。
可以在 为业务线 API 构建插件 中找到一个参考模式,该模式通过受 Entra 保护的 MCP 终结点将 Co-work 连接到受 API 密钥保护的服务。
对于 OAuthPluginVault 和 ApiKeyPluginVault,referenceId 指向存储在 Microsoft 企业令牌存储中的凭据 - 机密永远不会出现在清单或技能文件中。 值 referenceId 是向 Agents Toolkit 注册 OAuth 客户端时创建的 OAuth 客户端注册 ID。
Important
注册 OAuth 客户端时,请将“组织中的谁可以使用”设置为 任何 Microsoft 365 组织,以确保插件可跨租户工作。
MCP 身份验证
若要使用 OAuth 或 ApiKey 进行身份验证,请参考在智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶® 的智能体中为 MCP 和 API 插件配置身份验证,以了解设置和配置详细信息。
动态客户端注册
如果 MCP 服务器支持动态客户端注册 (DCR) ,则可以从连接器定义中省略authentication配置,Cowork自动代表插件创建 OAuth 客户端。
注释
仅在 Cowork 中支持省略authentication配置。 Copilot 对话助手不支持此功能。 如果插件还需要在 Copilot 对话助手中工作,请按照OAuthPluginVault支持的身份验证类型中所述配置身份验证。
可以完全省略该 authorization 对象。 配置 MCP 服务器 URL,并由 Cowork 处理 OAuth 客户端:
"remoteMcpServer": {
"mcpServerUrl": "https://api.contoso.com/legal/mcp"
}
步骤 4:创建清单
在您的程序包根目录中创建 manifest.json 。 该示例使用清单版本 1.28;wiqd plugin create 则固定为 1.29,其中连接器条目仅为 URL。
{
"$schema": "https://developer.microsoft.com/json-schemas/teams/v1.28/MicrosoftTeams.schema.json",
"manifestVersion": "1.28",
"version": "1.0.0",
"id": "YOUR-GUID-HERE",
"developer": {
"name": "Contoso Legal Tech",
"websiteUrl": "https://contoso.com",
"privacyUrl": "https://contoso.com/privacy",
"termsOfUseUrl": "https://contoso.com/terms"
},
"name": {
"short": "Contoso Legal Tools",
"full": "Contoso Legal Tools for Copilot Cowork"
},
"description": {
"short": "Contract analysis, clause extraction, and legal research",
"full": "Comprehensive legal tools for Copilot Cowork including contract analysis, clause extraction, risk assessment, and legal research capabilities."
},
"icons": {
"color": "color.png",
"outline": "outline.png"
},
"accentColor": "#2B579A",
"agentSkills": [
{ "folder": "./skills/contract-analysis" }
]
}
若要添加连接器,请包括 agentConnectors:
{
"agentConnectors": [
{
"id": "contoso-legal-api",
"displayName": "Contoso Legal Database",
"description": "Access to case law, statutes, and regulatory databases",
"toolSource": {
"remoteMcpServer": {
"mcpServerUrl": "https://api.contoso.com/legal/mcp",
"mcpToolDescription": {
"file": "./tools/contoso-legal-tools.json"
},
"authorization": {
"type": "OAuthPluginVault",
"referenceId": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u"
}
}
}
}
]
}
在连接器配置中, referenceId 应为 OAuth 注册 ID。 如果包括 mcpToolDescription,则它 file 必须指向 ZIP 包中包含的工具说明 JSON 文件。
Important
v1.28 清单模式很严格:它在根级别设置 additionalProperties: false,因此模式中未定义的任何字段都将被拒绝。 标准 Teams 应用清单中有效的字段(如 packageName)会导致上传失败,并出现类似 Property 'packageName' has not been defined and the schema does not allow additional properties. 的错误。仅包含此处显示的字段。
步骤 5:添加图标
创建两个 PNG 图标:
| 图标 | 大小 | Purpose |
|---|---|---|
color.png |
192×192 像素 | 应用商店和应用列表中显示的全彩应用图标 |
outline.png |
32×32 像素 | 用于紧凑视图的单色轮廓图标 |
如果还没有图标, atk import openplugin 生成纯色占位符。 在应用商店提交之前替换它们。
步骤 6:打包
创建一个所有内容都位于根级别的 ZIP 文件。 (在 wiqd plugin provision 后,wiqd plugin package 生成此相同的结构。)
contoso-legal-tools.zip
├── manifest.json
├── color.png
├── outline.png
├── tools/
│ └── contoso-legal-tools.json # Referenced by mcpToolDescription (optional, connectors only)
└── skills/
└── contract-analysis/
├── SKILL.md
└── references/
└── clause-taxonomy.md
如果连接器包含 mcpToolDescription,请包括它引用的工具说明 JSON 文件。 不使用 mcpToolDescription的包(包括仅技能包)不需要 tools/ 文件夹。
Windows (PowerShell):
Compress-Archive -Path manifest.json, color.png, outline.png, tools, skills -DestinationPath contoso-legal-tools.zip
macOS/Linux:
zip -r contoso-legal-tools.zip manifest.json color.png outline.png tools/ skills/
使用 Microsoft 365 Agents Toolkit
atk package --manifest-file ./appPackage/manifest.json \
--output-package-file ./appPackage/build/appPackage.zip \
--output-folder ./appPackage/build
步骤 7:测试
若要测试应用,请按照 将应用上传到 Teams 中所述,将应用包上传到 Teams。
如果使用 wiqd 生成了插件,请改为运行 wiqd plugin provision - 它会为你向租户注册插件。 为了对手动装配的包进行个人测试,请使用 Microsoft 365 智能体工具包命令行接口旁加载该应用:
从
npm安装@microsoft/m365agentstoolkit-cli:npm install -g @microsoft/m365agentstoolkit-cli通过运行以下命令验证安装:
atk --version使用 Microsoft 365 工作帐户进行身份验证:
atk auth login登录到工作帐户并安装代理包。 将文件路径替换为你的 ZIP 包所在位置:
atk install --file-path "C:/Users/myuser/myPackage.zip" --scope Personal成功安装后会返回输出,其中包含您的帐户的
TitleId和AppId。保存这些 ID 以便在以后更新或卸载时使用。
有关详细信息,请参阅 Microsoft 365 Agents Toolkit 命令行界面。
步骤 8:发布到你的租户
在管理中心中上传包,以在发现部分中列出插件,组织中的任何人都可以在该部分中找到插件:
- 打开 M365 管理中心>管理应用>上传自定义应用。
- 选择省略号按钮 (...) >添加智能体。
- 上传您的
.zip包。 - 打开Cowork>源 & 技能>插件。 插件显示在“发现”部分。
wiqd plugin share 将插件置于 与我共享 中,而不是 发现。 使用它进行测试并有针对性地向特定人员推出。 管理中心上传是列出用于发现的插件。
步骤 9:向公众发布
对于面向公开分发的插件,请通过 Partner Center 将你的插件提交到 Microsoft 365 应用商店。 请参阅 为 智能 Microsoft 365 Copilot 副驾驶® 发布代理 了解详细信息。
针对本地 MCP 服务器测试连接器
连接器需要一个 HTTPS mcpServerUrl。 若要测试在计算机上运行的服务器,需要通过公共 HTTPS URL 公开它。
开发隧道提供一个为你终止 TLS 的中继。
devtunnel port create <tunnel> -p <port> --protocol http
Important
使用 --protocol http,而不是 https。
--protocol 标志描述隧道转发到的本地服务,而不是公共隧道 URL。 大多数本地 MCP 服务器使用纯 HTTP,因此,如果服务器提供的是 HTTP,却设置了 --protocol https,则通过隧道的每个请求都将返回 502 错误。 无论此标记如何,中继都会终止 TLS 并通过 HTTPS 提供公共 URL。
Troubleshooting
| 症状 | 原因 | 修复 |
|---|---|---|
每个隧道请求都会返回 502,并且本地服务器使用 HTTP 通信 |
devtunnel port create 是使用 --protocol https 运行的 |
使用 --protocol http 重新创建端口 |
即使本地服务器正在运行,隧道请求也会在 macOS 上返回502 |
服务器绑定到 0.0.0.0(仅 IPv4),但隧道连接到 localhost,而该地址会首先解析为 ::1(IPv6) |
将服务器绑定到 ::,以便它同时接受 IPv4 和 IPv6 连接 |
上传失败,并显示 Property '<field>' has not been defined and the schema does not allow additional properties |
清单包括一个 v1.28 架构不允许的字段(例如 packageName) |
删除该字段;v1.28 的架构使用 additionalProperties: false |
封装模式
选择适合您的扩展程序的模式:
仅限技能(无连接器)
最适合基于提示的工作流、文档分析和写作协助。
my-skills-pack.zip
├── manifest.json # agentSkills only, no agentConnectors
├── color.png
├── outline.png
└── skills/
├── skill-one/SKILL.md
└── skill-two/SKILL.md
技能 + 远程连接器
最适合数据分析、API 集成和企业系统。
my-data-skills.zip
├── manifest.json # agentSkills + agentConnectors
├── color.png
├── outline.png
├── tools/ # Tool-description file(s) for mcpToolDescription (optional)
│ └── my-connector.json
└── skills/
├── analysis-workflow/SKILL.md
└── reporting-workflow/SKILL.md
仅连接器(无自定义技能)
对于 Cowork 的内置技能已可使用的数据源,请使用此选项。
my-connector.zip
├── manifest.json # agentConnectors only, no agentSkills
├── color.png
├── outline.png
└── tools/ # Tool-description file(s) for mcpToolDescription (optional)
└── my-connector.json
已导入的 Claude Code 或 Cursor 插件
对于以 Cowork 为目标平台的现有 Claude 生态系统插件,请使用此选项。 若要继续在 Microsoft 365 中开发插件,请将其导入:
wiqd plugin import --path ./claude-plugin --privacy-url https://contoso.com/privacy --terms-url https://contoso.com/terms
要用当前状态下的插件生成可发布的 .zip,请使用转换脚本:
atk import openplugin --path ./claude-plugin --output ./my-plugin-project \
--privacy-url https://contoso.com/privacy \
--terms-url https://contoso.com/terms
技能创作最佳做法
遵循这些准则来创建能够稳定激活并产生一致结果的技能。
编写有效说明
description 字段决定智能体何时激活您的技能。 请具体说明:
# Good-specific trigger phrases, concrete scenarios
description: |
Analyzes bond relative value using Z-spreads, ASW spreads, and butterfly analysis.
Use when user asks to "analyze bond spreads", "compare bonds",
"rich-cheap analysis", "relative value", or "Z-spread calculation".
# Bad-vague, no trigger phrases
description: Provides bond analytics capabilities.
编写有效的工作流
- 具体说明。 包含触发短语:“当用户要求...”此描述是代理确定要激活的技能的方式。
- 按工作流结构组织。 对步骤编号。 每个步骤都应映射到一个具体的操作 (读取文件、调用工具、生成输出) 。
- 定义输出格式。 显示用户应期待的确切的表、列表或文档结构。 此定义显著提高了一致性。
-
按名称引用工具。 如果您的技能依赖于连接器工具,请明确写出其名称:“使用
search_case_law工具来……” -
保持主 SKILL.md 精简。 将详细参考资料移动到
references/子目录。 技能正文应该是工作流,而不是百科全书。
避免常见错误
-
不要在
SKILL.md文件中嵌入机密。 针对 API 凭据结合使用agentConnectors与身份验证。 - 不要重复内置技能。 构建前请先检查内置技能列表。
- 不要使技能太宽泛。 针对“合同分析”、“条款提取”和“法律研究”,特定技能比“一切按法律文件处理”表现得更好。
- 不要硬编码文件路径 或系统命令。 技能应能够在不同环境间迁移。
-
不要把一切放在 SKILL.md。 如果正文超过 ~3,000 字,请将详细内容移到
references/。
验证规则
提交包时,平台会在多个级别对其进行验证。 请在提交前修复这些错误,以免被拒绝。
若要在生成时(而不是在上传时)捕获它们,请运行 wiqd plugin validate --mode deep。 此命令会打包插件并在本地运行这些相同的规则。 了解更多信息,请参阅 步骤 3:边构建边验证。
清单级验证
| Code | 规则 | Severity |
|---|---|---|
| ASKILL-M001 |
folder 在每个 agentSkills 条目中都是必填项 |
错误 |
| ASKILL-M002 |
agentSkills 数组最多可以有 20 个项目 |
错误 |
| ASKILL-M003 |
folder 路径最多可以包含 256 个字符 |
错误 |
包级别验证
| Code | 规则 | 常见修补程序 | Severity |
|---|---|---|---|
| ASKILL-P001 | 清单中引用的文件夹存在于 ZIP 文件中 | 检查 ZIP 结构 | 错误 |
| ASKILL-P002 | 文件夹中包含一个SKILL.md文件 |
添加缺少的 SKILL.md |
错误 |
| ASKILL-P003 |
SKILL.md 在 --- 分隔符之间具有有效的 YAML frontmatter |
修复 YAML 语法 | 错误 |
| ASKILL-P004 | 前言元数据包括 name 字段 |
将 name: 添加到前言 |
错误 |
| ASKILL-P005 | 前言元数据包括 description 字段 |
将 description: 添加到前言 |
错误 |
| ASKILL-P006 |
name 匹配文件夹名称(最后一个路径段) |
重命名文件夹或修复 name: |
错误 |
| ASKILL-P007 |
name 是短横线命名法 |
使用 my-skill,而不是 MySkill 或 my_skill |
错误 |
| ASKILL-P008 | 数组中没有重复的 folder 值 |
删除重复项 | 错误 |
连接器验证
| 规则 | Severity |
|---|---|
每个连接器都需要一个id和一个displayName |
错误 |
所有连接器 id 值在清单中都必须是唯一的 |
错误 |
plugin 或 remoteMcpServer 中恰好一个 |
错误 |
mcpServerUrl 必须是有效的 HTTPS URL |
错误 |
如果存在 mcpToolDescription,则其 file 必须存在于 ZIP 中 |
错误 |
authorization.referenceId 必需,除非类型为 None |
错误 |
当类型为 None 时,不得出现 authorization.referenceId |
错误 |
配套文件验证
门户在上传和同步时验证配套文件(参考资料、脚本以及与 SKILL.md 一起的其他文件):
| 规则 | Severity |
|---|---|
每个技能最多 20 个配套文件(不包括 SKILL.md) |
错误 |
| 每个配套文件必须不大于 5 MB | 错误 |
| 每个技能的配套文件总数必须为 10 MB 或更小 | 错误 |
| 文件路径必须是相对的 (不能有绝对路径) | 错误 |
无路径遍历段 (..) |
错误 |
| 文件名中没有反斜杠或空字节 | 错误 |
没有隐藏文件(名称以.开头) |
错误 |
没有 Windows 保留名称(CON、PRN、AUX、NUL、COM1 - COM9、LPT1 - LPT9) |
错误 |
文件名必须仅使用安全字符(字母数字、连字符、下划线、点、空格、!) |
错误 |
跨平台兼容性
技能使用 Agent Skills 开放标准。 同一 SKILL.md 文件可在多种 AI 工具中使用:
| Platform | Compatibility |
|---|---|
| 克劳德密码 | 完全相同 SKILL.md 格式 |
| Claude.ai 项目 | 完全技能可作为项目文件上传 |
| VS Code /GitHub Copilot | 智能体模式下支持的 Full-Agent 技能 |
| Gemini CLI | 支持的完全智能体技能 |
| JetBrains Junie | 支持的完全智能体技能 |
| OpenAI 手本 | 支持的完全智能体技能 |
| Cursor | 支持的完全智能体技能 |
如果您正在为 Claude Code 和 Copilot Cowork 开发技能,请使用 wiqd 创作插件。 然后运行 wiqd plugin export --format claude-plugin 以生成 Claude Code 结构。 如果你更愿意从 Claude Code 插件结构开始——它是更完整的超集——其布局如下:
my-plugin/
├── .claude-plugin/
│ └── plugin.json # Claude plugin manifest
├── skills/
│ ├── skill-one/
│ │ ├── SKILL.md # Works in both Claude Code AND M365
│ │ └── references/
│ └── skill-two/
│ └── SKILL.md
└── .mcp.json # MCP server config (optional)
然后,当准备好发布到 Microsoft 365 App Store 时,将其导入 Microsoft 365,无论是使用wiqd plugin import还是使用转换脚本:
atk import openplugin --path ./my-plugin --output ./my-plugin-project \
--privacy-url https://contoso.com/privacy \
--terms-url https://contoso.com/terms
MCP 标注和确认管理
Copilot Cowork 读取你的服务器从 annotations 返回的工具上的标准 MCP tools/list 对象,并使用它来决定工具调用是否需要用户确认,以及在提示中显示什么标签。
可用字段
| 领域 | 类型 | Effect |
|---|---|---|
readOnlyHint |
bool |
false:在工具运行之前需要确认。 |
destructiveHint |
bool |
true:在工具运行之前需要确认。 |
title |
字符串 | 确认对话框中显示的用户可读标签。 缺失时回退为工具名称。 |
确认规则
如果 destructiveHint == true 或 readOnlyHint == false,则需要确认。
所有工具都必须已指定安全注释。 没有注释的工具视为破坏性工具,需要确认。 请参阅MCP 架构参考,了解更多信息。
MCP 示例
带有友好名称的破坏性操作:
{
"name": "send_email",
"description": "Send an email message.",
"annotations": {
"title": "Send Email",
"destructiveHint": true
},
"inputSchema": { ... }
}
自动运行的安全读取:
{
"name": "search_docs",
"annotations": {
"title": "Search Documents",
"readOnlyHint": true
}
}
现在可用的内容
- Microsoft工具 (Graph、Dataverse 和其他工具) 受 Cowork 的内置策略限制,而不考虑批注。
- 对于非 Microsoft MCP 服务器,正在逐步推出基于注解的确认。 现在设置提示是向后兼容的,随着推出范围的扩大,确认提示会出现,无需开发人员更改。
接受来自 Cowork 工作区的文件
连接器工具可以从用户的 Cowork 会话中获取文件作为输入 - 用户附加的文档、Cowork 保存的电子邮件附件或先前步骤生成的文件。 使用标准 JSON 架构关键字 (keyword) contentEncoding: base64 声明参数,Cowork 处理其余部分。 不需要特定于 Microsoft 的架构扩展,并且服务器的 API 图面不会更改。
Cowork 在调用服务器之前解析工作区文件并对其进行 base64 编码,因此文件字节永远不会进入代理的上下文。 智能体只看到并发出工作区文件路径。
注释
不要指示智能体自行将文件进行 Base64 编码并将 Blob 粘贴到工具调用中。 该方法将整个文件加载到模型的上下文中,并依赖模型精确再现该 blob。 它似乎适用于小型测试文件,但在真实文件上失败。
声明文件参数
带有 contentEncoding: base64 的字符串属性被识别为文件输入:
{
"name": "analyze_contract",
"description": "Extract key terms from a contract document.",
"annotations": {
"title": "Analyze Contract",
"readOnlyHint": true
},
"inputSchema": {
"type": "object",
"properties": {
"document": {
"type": "string",
"contentEncoding": "base64",
"description": "The contract file to analyze."
},
"jurisdiction": {
"type": "string",
"description": "Two-letter country code governing the contract."
}
},
"required": ["document"]
}
}
对于接受多个文件的工具,还可以识别此类字符串的数组:
"attachments": {
"type": "array",
"items": { "type": "string", "contentEncoding": "base64" },
"description": "Receipt images to attach to the expense line."
}
代理看到的内容
对于在 inputSchema.properties 顶层声明的文件参数,Cowork 会在面向模型的机构中使用单个 direct_attachment_file_paths 数组(Cowork 的内置工具使用的相同参数)替换它们,因此智能体已经知道如何填充它。 上述架构将作为以下形式呈现给智能体:
{
"type": "object",
"properties": {
"direct_attachment_file_paths": {
"type": "array",
"items": { "type": "string" },
"description": "Workspace file paths to attach."
},
"jurisdiction": { "type": "string" }
}
}
如果工具声明多个顶级文件参数,则所有这些参数都将折叠到该单个 direct_attachment_file_paths 数组中。 在调用时,Cowork 将解析后的文件按声明顺序扇回原始参数名称中。
嵌套文件参数
代理支持嵌套在对象或对象数组中的文件参数。 智能体以不同的方式处理此参数:智能体不会折叠它,而是在自己的位置中将其就地 重写到路径字符串中。 此方法将保留文件与其同级字段之间的关联。 例如,每个支出行对应一张收据:
"line_items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"amount": { "type": "number" },
"receipt": { "type": "string", "contentEncoding": "base64" }
}
}
}
智能体使用工作区路径填充 line_items[].receipt,Cowork 在转接呼叫之前就地交换每个路径以获取 base64 内容。
嵌套将遍历到 inputSchema 顶部下面的四个级别深度。
$ref 不会跟随指针——内联定义文件参数,而不是在 $ref 后面定义。
服务器接收的内容
服务器会收到一个普通的 tools/call,其中您的原始参数名称被填入了 base64 编码的内容:
{
"method": "tools/call",
"params": {
"name": "analyze_contract",
"arguments": {
"document": "JVBERi0xLjQKJcfsj6IKNSAwIG9iago8PC9MZW5...",
"jurisdiction": "US"
}
}
}
您的服务器不需要知道代理使用了基于路径的接口,并且不声明 contentEncoding: base64 参数的工具不受影响。
Limits
| Limit | Value |
|---|---|
| 每个工具调用的文件 | 8 |
| 每个文件的大小 | 150 MiB |
| 每个工具调用的总大小 | 150 MiB |
| 每个工具的数组文件参数 | 1(将其与任意数量的标量文件参数组合) |
| 最大嵌套深度 | 顶部下方 4 层 inputSchema |
超过文件计数或大小上限的调用将失败并出现工具错误,并且永远不会访问您的服务器。 在调整 API 大小及其超时,要考虑 150 MiB 上限:base64 会将有效负载增加大约是原始文件大小的三分之一,并且编码的内容在 JSON-RPC 请求正文中发送。
Recommendations
- 为人类阅读器描述参数。 智能体使用描述来确定哪个文件属于哪个参数。 例如,
"The signed contract PDF to analyze"比"file"效果更好。 - 在参数说明中声明你接受的格式。 Cowork 会传递用户所附加的任何内容。 验证您这边的内容类型,如果不可用,则返回清晰的工具错误。
- 设置批注。 接收文件并对其执行操作的工具通常不是只读的,因此它会提示确认。 在 MCP 批注和确认管理中了解更多信息。
- 保持文件参数内联。 不会重写 后面
$ref的参数或嵌套深度超过四个级别的参数。 您的服务器将在需要内容的位置接收一个路径字符串。 - 每个工具最多声明一个数组文件参数。 如果有两个或更多文件,Cowork 无法判断哪个文件属于哪个数组,并且调用失败并出现工具错误。 使用一个数组或多个标量参数,或使用标量和单个数组的组合。
- 对于仅支持标量的工具,预计会得到精确计数。 如果工具仅声明标量文件参数,则代理传递的文件数必须与声明的数目匹配。 在描述中清楚地标记可选文件参数,以免智能体少传或多传文件。
注释
这种机制早于模型上下文协议自己的文件输入工作,后者正在由 MCP 文件上传工作组标准化。 该标准落地后,Cowork 可能会添加对声明性文件输入的标准化形式的支持。 此处所述的 contentEncoding: base64 协定将继续有效。
识别到服务器的 Cowork 流量
如果您的 MCP 服务器按客户端限制工具可见性,或者您想对其接收到的流量进行归因,则可以识别来自 Cowork 的请求。 Cowork 在两个渠道上呈现稳定的软件标识:
| Channel | 显示位置 | Value |
|---|---|---|
User-Agent 请求标头 |
Cowork 发送到您的服务器的每个出站请求 | copilot-cowork/1.0 |
clientInfo 在 MCP initialize 握手中 |
仅 initialize 请求 |
{ "name": "copilot-cowork", "version": "<version>" } |
在 copilot-cowork 前缀上匹配
在任一渠道上匹配 copilot-cowork前缀,不区分大小写。 不匹配精确 copilot-cowork/1.0 字符串或特定 clientInfo.version字符串。 该版本跟踪客户端身份契约,并且预计会更改;前缀匹配可使 Gate 在版本变更时继续正常工作。
# Correct: case-insensitive prefix match
copilot-cowork
# Incorrect: exact match breaks when the version changes
copilot-cowork/1.0
为您的门槛选择合适的渠道
这两个渠道具有不同的范围,因此请选择与服务器强制执行其门槛的方式相匹配的渠道:
- 标头存在于
User-Agent每个请求中,包括tools/list和tools/call。 如果您按请求设置门槛或属性,此标头是关键。 -
clientInfo仅在握手上initialize发送。 如果在连接时按会话设置门槛,则可以在其中读取它,但不会在以后的请求中重复。
标识包含和不包含的内容
标识仅为软件命名。 这对于每个 Cowork 用户和连接都是一样的,它从不包含用户标识。 用户标识保留在连接器的身份验证配置定义的授权流中。
| 标识包括 | 标识不包括 |
|---|---|
稳定的软件名称 (copilot-cowork) 和合同版本 |
任何租户、用户、会话或对话标识符 |
| 每个请求和每个连接中的值都相同 | 每个连接器的限定符 |
由于没有每个连接器的限定符,因此当前无法使用此标识来判断哪个连接器进行了调用,也无法将已发布的 Microsoft 插件与指向相同 URL 的旁加载服务器分开。 如果需要这种区别,请通过连接器的授权配置而不是客户端标识强制实施。
常见问题
是否可以在 Claude Code 中使用 M365 包中的技能?
Yes. 技能文件夹包含标准智能体技能。 运行 wiqd plugin export --format claude-plugin 以生成 Claude Code 布局,或将技能文件夹复制到任何 Claude Code 项目中的 .claude/skills/。
是否需要远程连接器?
No. 仅限技能包非常适合基于提示的工作流。 仅当技能需要来自外部系统的实时数据时,才需要连接器。
插件技能与内置技能有何不同?
插件技能在 API 中显示来源为 "package"。 它们无法覆盖同名的内置技能。 管理员部署的包显示 isAdminDeployed: true。
IT 管理员可以控制哪些插件可用?
Yes. Standard M365 管理员控件适用:租户级允许/阻止列表、管理员管理的部署以及合规性策略。
如果吊销插件,会发生什么情况?
在下一个同步周期中,将从用户会话中删除该程序包中的技能和连接器。 活动对话不会中断,但新会话不具有包的功能。
每个包的最大技能数是多少?
二十(20)项技能(根据 ASKILL-M002)。 对于连接器,限制为每个包 10 个。
技能是否可以引用同一包中的连接器工具?
是的,他们应该这样做。 在您的 SKILL.md 工作流中明确命名工具(例如,“使用 search_case_law 工具来……”)。 代理在运行时连接它们。
我的插件工具是否可以接受 Cowork 工作区中的文件?
Yes. 使用 contentEncoding: base64 声明工具参数,Cowork 会在调用服务器之前将用户的工作区文件解析为 base64 内容。 模型传递的是文件路径,而不是文件内容,因此大型文件不会使用模型的上下文。 有关声明的详细信息和限制,请在接受来自 Cowork 工作区的文件中了解更多信息。
如何为包生成确定性 GUID?
wiqd plugin create 为你生成并固定应用 ID。 转换脚本使用基于你的插件名称生成的 UUID v5(基于 SHA-1),因此运行转换两次会产生相同的 GUID。 对于手动打包,请使用任何 GUID 生成器。 请务必在各个版本之间保持稳定。
应面向哪个清单版本?
如果您使用 wiqd 进行构建,则目标版本为 1.29,这将为您固定它。 在 1.29 中,agentConnectors[] 条目仅包含 URL,并且 mcpToolDescription 是可选的。 本文中手动创作的示例使用 1.28,这是 mcpToolDescription 所必需的,并且其命名的文件必须位于 ZIP 中。
atk import openplugin 使用基于你的插件名称生成的 UUID v5(基于 SHA-1)。 运行导入两次会生成相同的 GUID。 若要设置自己的 GUID,请传递 --app-id。 对于手动打包,请使用任何 GUID 生成器。 请务必在各个版本之间保持稳定。