外掛是一種可安裝的套件,可以包含 內建 或 自訂 的技能、工具和代理程式。 內建技能隨 Copilot 提供。 客製化技能是由製作者建立的。 當你將自訂技能打包進外掛後,使用者可以安裝它來擴充 Copilot 的功能。
Microsoft Copilot Cowork 透過 M365 應用程式套件 (與 Teams 應用程式、Copilot Agent 和 Office 增益集所使用的相同散發機制) 支援擴充性。您可以透過下列項目擴充 Cowork:
- 技能:以提示為基礎的工作流程,教授 Cowork 新領域的專業知識,如財務分析、法律研究或人力資源工作流程。
- 連接器:遠端伺服器,讓 Cowork 能夠存取外部資料來源和 API。
兩者都一併封裝在標準 Microsoft 365 應用程式套件中,並透過 Microsoft 365 應用程式商店散發。
Important
Microsoft Purview 資訊屏障(IB)目前尚未支援外掛或技能管理與分享。 在啟用 IB 的租用戶中,系統會在租用戶層級封鎖內嵌知識檔案上傳。 這可防止受影響的外掛程式和技能被上傳或發佈。
Microsoft 不會建立或維護任何持續性索引、知識圖 (包括 Microsoft Graph) 或包含 ISV 內容的資料庫,無論是透過編目、抓取、搜集、大量匯出、擷取,還是任何其他方法 (透過 API、MCP 伺服器或其他方式)。 Microsoft 可能會在必要時暫時處理 ISV 內容,以便回應使用者的即時查詢,但不會在該工作階段結束後保留 ISV 內容。 在收到 ISV 的書面要求後,Microsoft 會在 10 個工作天內刪除其所持有或控制的任何 ISV 內容,並以書面證明此等刪除。 如需詳細資訊,請參閱 Microsoft Copilot 與 Microsoft Copilot Chat 中的企業資料保護。
建置與發佈<
撰寫與打包外掛與發佈到登錄庫、管理員核准/指派、使用者安裝及服務登入是不同的。
- Work IQ 開發工具可以針對特定受眾發佈到登錄庫。
- 與特定人員共用 Cowork 不需要管理員批准。
- 全組織共用需要管理員核准。
- 直接分享不是市集中的提供項目。
為了讓外掛更容易被發現和管理,請探索共用外掛登錄檔。 外掛登錄是 Microsoft Copilot 的常見基礎架構,讓外掛可發布一次,使用者可發現,提供給受支援的 Copilot 體驗使用,並由管理員集中管理。 在 Plugin Hub 了解更多資訊。
備註
並非所有打包元件都能在 Cowork 中運作。 現有的外掛可能不會自動遷移。
Prerequisites
利用這份清單了解 Cowork 外掛支援和要求的是什麼。
-
為 Copilot Cowork 建置外掛
- Microsoft 365 Copilot 授權:Cowork 使用者需要此授權。
- 支援管理員角色:使用 AI 管理員 或 全域管理員 以取得 MCP 批准及租戶同意。
-
開發工具
- Work IQ 開發工具:用於打包、驗證、配置、分享及發佈請求。
- Microsoft 365 代理工具包:用於代理程式與應用程式的開發與打包。
- Plugin Builder(前稱 Agent Builder):創作環境;部署範圍仍在確認中。
- 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 是對 declarative-agent 介面進行的離線靜態檢查。 只有技能或只有連接器的外掛程式無需進行任何檢查即時通過驗證,這正是預期的結果 — 只是對建置迴圈所做的檢查,而非全面涵蓋。
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 來與您組織中的所有人共用。 無論哪種方式,外掛程式都會顯示在 Cowork>來源和技能>外掛程式下的與我共用中。 若要改為將其列在探索區段中,管理員可以上傳套件。 在 步驟 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 插件,那麼您有兩條轉換路線。 您選擇的路由取決於您是打算繼續開發外掛程式,還是僅發佈現有的版本。
| Goal | 使用 |
|---|---|
| 繼續開發、驗證和發佈 Microsoft 365 的外掛程式 | wiqd plugin import |
立即從現有的 Claude 外掛程式產生可發布的.zip |
轉換指令碼 |
使用 wiqd 匯入
wiqd plugin import 識別 Open Plugin、Claude 插件或游標插件來源,並從中產生 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) 、 .mcp.json和 skills/ 目錄,然後搭建包含 appPackage/manifest.json、您的技能和產生的圖示的 Agents Toolkit 專案。
您必須包含 --privacy-url 和 --terms-url ,因為外掛程式資訊清單沒有對等欄位,而 Microsoft 365 資訊清單需要這兩個欄位。
備註
atk import openplugin 在以點開頭的目錄中尋找外掛資訊清單——.claude-plugin/plugin.json、.cursor-plugin/plugin.json 或 .plugin/plugin.json——且與 .mcp.json 並列。
Agent 外掛程式 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 同等項目 | Notes |
|---|---|---|
.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 用戶端註冊識別碼。 深入了解支援的 驗證類型。
未轉換的內容
Microsoft 365 資訊清單尚未支援下列 Claude 外掛程式功能:
| Claude 外掛程式功能 | 狀態 |
|---|---|
commands/ (斜線指令) |
目前尚不支援 |
agents/ (次級代理人) |
目前尚不支援 |
hooks/ (事件處理器) |
目前尚不支援 |
settings.json |
不適用 |
bin/ (可執行檔) |
不適用 |
匯入選項
| Option | 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 | 預設驗證類型 | Reason |
|---|---|---|
| 外部 HTTPS URL | OAuthPluginVault |
大部分的遠端 API 都需要驗證 |
localhost 以及非 HTTPS 網址 |
None |
本機開發伺服器 |
如果自動偵測不符合您的設定,請使用 --default-auth-type 來覆寫。
匯出回外掛程式目錄
若要將 Agents Toolkit 專案移回外掛程式目錄 (例如,讓 Claude Code 外掛程式和 Cowork 套件保持同步),請使用atk export openplugin:
atk export openplugin --path ./my-plugin-project \
--output ./my-claude-plugin --manifest-kind claude-plugin
| Option | Description |
|---|---|
--path,-p |
Required. 包含 appPackage/manifest.json 的 Agents Toolkit 專案資料夾 |
--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 區塊是適用於 Agents Toolkit 的特定區塊,而預設的 open-plugin 類型會將資訊清單寫入 .plugin/plugin.json。
Agent Plugins 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
撰寫 SKILL.md,包含 YAML frontmatter 和 Markdown 內文:
---
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 欄位
必填欄位:
| Field | Constraints | 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): 只使用小寫字母數字和連字號。 請勿使用連續的連字號,也不要使用開頭或結尾的連字號。
| Example | 有效嗎? | 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 秒 |
隨附檔案規則
配套檔案路徑必須遵循下列規則:
- 僅使用相對路徑 (不使用絕對路徑) 。
- 沒有路徑周遊 (
..區段)。 - 檔案名稱中不要使用反斜線或 null 位元組。
- 沒有隱藏檔案(名稱以
.開頭)。 - 沒有 Windows 保留名稱 (
CON、PRN、AUX、NUL、COM1–COM9、LPT1–LPT9)。 - 檔案
SKILL.md本身不算為配套檔案。 - 檔案名稱必須使用安全字元: 英數字元、連字號、底線、點、空格和
!。
為了維持上下文視窗的效率,系統會分三層載入技能:
| 階層 | 載入時 | 目標尺寸 |
|---|---|---|
前置資訊 (name + description) |
永遠 - 在啟動時 | ~100 個權杖 |
SKILL.md 內文 |
技能觸發時 | 少於 5,000 個 Token (1,500-2,000 字) |
參考 (references/) |
根據 Agent 的需求 | Unlimited |
指令碼 (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
-
檔案輸入:若要接受來自使用者工作區的檔案,請使用
contentEncoding: base64宣告參數。 如需詳細資訊,請參閱從 Cowork 工作區接受檔案。
描述您的連接器工具 (mcpToolDescription)
remoteMcpServer連接器可以選擇性地包含mcpToolDescription物件。 提供時,其巢狀 file 屬性指向工具描述 JSON 檔案,您可以將其封裝在 .zip 內部,並透過套件根目錄的相對路徑進行參考。 Cowork 會從您的 MCP 伺服器動態探索工具,並且不會使用此檔案,即使該檔案存在也一樣。
"remoteMcpServer": {
"mcpServerUrl": "https://api.contoso.com/legal/mcp",
"mcpToolDescription": {
"file": "./tools/contoso-legal-tools.json"
},
"authorization": {
"type": "OAuthPluginVault",
"referenceId": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u"
}
}
如果您包含 mcpToolDescription,則參考的檔案 (例如 tools/contoso-legal-tools.json) 會描述連接器公開的工具,且必須存在於 ZIP 套件中。 封裝外掛程式時,請將其與 manifest.json 及 skills/ 資料夾一併加入。
Tip
此需求適用於資訊清單版本 1.28。
wiqd plugin create 產生的套件以 1.29 為目標,其中 agentConnectors[] 項目僅限 URL,mcpToolDescription 為選用,而沒有可忽略的工具描述檔。
支援的驗證類型
| 驗證類型 | 何時使用 | 用戶體驗 |
|---|---|---|
None |
公用或匿名 API、內部服務 | 透明 - 無驗證提示 |
OAuthPluginVault |
OAuth 2.0 API (建議用於生產) | 使用者只需完成一次 OAuth 同意 |
ApiKeyPluginVault |
以 API 金鑰為基礎的服務 | 使用者只需提供一次金鑰 |
備註
- Cowork 尚未支援 API 金鑰驗證。
- 如果 MCP 伺服器需要 API 金鑰,請改用
OAuthPluginVault或動態用戶端註冊,或是公開接受None的端點。
你可以在 Build a Plugin for a line-of-business API 的外掛中,找到一個參考模式,透過 Entra 保護的 MCP 端點將 Cowork 連接到 API 金鑰保護的服務。
對於 ApiKeyPluginVault 和 referenceId,OAuthPluginVault 會指向儲存在 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 Chat 不支援。 如果您的外掛程式也需要在 Copilot Chat 中運作,請依照支援的驗證類型中所述設定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 註冊識別碼。 如果您包含 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 圖示:
| Icon | Size | Purpose |
|---|---|---|
color.png |
192×192 像素 | 在市集和應用程式清單中顯示的全彩應用程式圖示 |
outline.png |
32×32 px | 精簡檢視的單色外框圖示 |
如果還沒有圖示,atk import openplugin 會產生純色預留位置。 在提交至市集之前,先加以取代。
步驟 6:封裝
建立根層級包含所有內容的 ZIP 檔案。 (wiqd plugin package 在 wiqd plugin provision 之後會產生相同的結構。)
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 代理工具包
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 Agents 工具組命令列介面來側載應用程式:
從
npm安裝@microsoft/m365agentstoolkit-cli:npm install -g @microsoft/m365agentstoolkit-cli執行以下命令來確認安裝:
atk --version使用您的 Microsoft 365 公司帳戶進行驗證:
atk auth login登入工作帳戶並安裝 Agent 套件。 以 ZIP 套件的位置取代檔案路徑:
atk install --file-path "C:/Users/myuser/myPackage.zip" --scope Personal成功安裝會傳回輸出,其中包含您帳戶的
AppId和TitleId。儲存這些 ID,以便日後更新或解除安裝時使用。
如需詳細資訊,請參閱 Microsoft 365 Agents 工具組命令列介面。
步驟 8:發佈至租用戶
在系統管理中心上傳套件,以在探索區段中列出外掛程式,組織中的任何人皆可以在其中找到該外掛程式:
- 開啟 M365 系統管理中心>管理應用程式>上傳自訂應用程式。
- 選取省略符號按鈕 (...) >新增 Agent。
- 上傳您的
.zip套件。 - 開啟 Cowork>原始檔和技能>外掛程式。 您的外掛程式會顯示在 Discover 區段中。
wiqd plugin share 將外掛置於 「與我共享 」而非 「探索」中。 使用它來進行測試,並針對特定使用者進行有針對性的推出。 系統管理中心上傳就是用來列出可供探索的外掛程式。
步驟 9:向公眾發佈
對於適用於公開散發的外掛程式,請透過合作夥伴中心將外掛程式提交至 Microsoft 365 應用程式市集。 如需詳細資訊,請參閱發佈適用於 Microsoft 365 Copilot 的 Agent。
針對本機 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 欄位決定 Agent 何時啟動您的技能。 具體說明:
# 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檔案中。 將agentConnectors與驗證搭配使用以取得 API 認證。 - 不要重複內建技能。 組建之前,請先檢查 內建技能清單 。
- 不要把技能範圍說得太廣。 「凡事都靠法律文件處理」的做法,比「合約分析」、「條款擷取」和「法律研究」等具體技能還要糟糕。
- 不要硬編碼檔案路徑 或系統指令。 技能應該可跨環境移植。
-
不要把所有東西都放進 SKILL.md。 如果您的內文超過 ~3,000 字,請將詳細內容移至
references/。
驗證規則
當您提交套件時,平台會在多個層級對其進行驗證。 提交前先修正這些錯誤,以避免遭到拒絕。
若要在建置時捕捉它們,而不是等到上傳時才發現它們,請執行 wiqd plugin validate --mode deep。 此命令會封裝外掛程式,並在本機執行這些同樣的規則。 若要深入了解,請參閱 步驟 3:在建置時驗證。
資訊清單層級驗證
| Code | 規則 | Severity |
|---|---|---|
| ASKILL-M001 |
folder 為每個 agentSkills 項目的必填欄位 |
錯誤 |
| ASKILL-M002 |
agentSkills 陣列最多可包含 20 個項目 |
錯誤 |
| ASKILL-M003 |
folder Path 最多可包含 256 個字元 |
錯誤 |
套件層級驗證
| Code | 規則 | 常見修正 | Severity |
|---|---|---|---|
| ASKILL-P001 | 資訊清單中參考的資料夾存在於 ZIP 中 | 檢查您的 ZIP 結構 | 錯誤 |
| ASKILL-P002 | 資料夾包含 SKILL.md 檔案 |
新增缺少的 SKILL.md |
錯誤 |
| ASKILL-P003 |
SKILL.md 在 --- 分隔符之間具有有效的 YAML 前置內容 |
修正 YAML 語法 | 錯誤 |
| ASKILL-P004 | Frontmatter 包含 name 欄位 |
將 name: 新增至前置資訊 |
錯誤 |
| ASKILL-P005 | Frontmatter 包含 description 欄位 |
將 description: 新增至前置資訊 |
錯誤 |
| ASKILL-P006 |
name 與資料夾名稱相符(最後路徑段) |
重新命名資料夾或修正 name: |
錯誤 |
| ASKILL-P007 |
name 是 kebab-case |
使用 my-skill 而不是 MySkill 或 my_skill |
錯誤 |
| ASKILL-P008 | 陣列中沒有重複 folder 的值 |
移除重複項目 | 錯誤 |
連接器驗證
| 規則 | Severity |
|---|---|
每個連接器都需要一個 id 和 displayName |
錯誤 |
所有連接器 id 值在資訊清單中都必須是唯一的 |
錯誤 |
必須是 plugin 或 remoteMcpServer 其中之一 |
錯誤 |
mcpServerUrl 必須是有效的 HTTPS URL |
錯誤 |
如果存在 mcpToolDescription,則其 file 必須存在於 ZIP 中 |
錯誤 |
authorization.referenceId 為必填,除非類型為 None |
錯誤 |
authorization.referenceId 在類型為 None 時不得存在 |
錯誤 |
配套檔案驗證
入口網站會在上傳和同步處理時驗證隨附檔案 (參考資料、指令碼以及其他與 SKILL.md 一起的檔案):
| 規則 | Severity |
|---|---|
每項技能最多 20 個隨附檔案 (不包括 SKILL.md) |
錯誤 |
| 每個配套檔案的大小必須為 5 MB 或更小 | 錯誤 |
| 每項技能的隨附檔案總大小必須為 10 MB 或更小 | 錯誤 |
| 檔案路徑必須是相對路徑 (不得有絕對路徑) | 錯誤 |
沒有路徑周遊區段 (..) |
錯誤 |
| 檔案名稱中不要使用反斜線或 Null 位元組 | 錯誤 |
沒有隱藏檔案 (名稱以 . 開頭) |
錯誤 |
沒有 Windows 保留名稱 (CON、COM1、PRN、AUX、NUL–COM9、LPT1–LPT9) |
錯誤 |
檔案名稱必須僅使用安全字元 (英數字元、連字號、底線、點號、空格、!) |
錯誤 |
跨平臺相容性
技能使用 Agent 技能開放標準。 相同的 SKILL.md 檔案可在多個 AI 工具上運作:
| Platform | Compatibility |
|---|---|
| 克勞德密碼 | 完全相同 SKILL.md 格式 |
| Claude.ai 專案 | 完整技能可以上傳為專案檔案 |
| VS Code / GitHub Copilot | Agent 模式支援的完整 Agent 技能 |
| Gemini CLI | 支援的完整 Agent 技能 |
| JetBrains Junie | 支援的完整 Agent 技能 |
| OpenAI 手冊 | 支援的完整 Agent 技能 |
| Cursor | 支援的完整 Agent 技能 |
如果您正在為 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 應用程式市集時,使用 wiqd plugin import 或轉換指令碼將其匯入 Microsoft 365:
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 會在伺服器從 tools/list 傳回的工具上讀取標準 MCP annotations 物件,並將其用於決定工具是否需要使用者確認,以及要在提示中顯示的標籤。
可用的欄位
| Field | 類型 | Effect |
|---|---|---|
readOnlyHint |
bool |
false:工具運行前需確認。 |
destructiveHint |
bool |
true:工具執行前需要確認。 |
title |
字串 | 確認對話方塊上顯示的人類看得懂的標籤。 如果沒有,則改用工具名稱。 |
確認規則
如果 readOnlyHint == false 出現 或 destructiveHint == true則需要確認。
所有工具都必須指定安全註釋。 沒有註釋的工具可視為具破壞性,需要確認。 如需詳細資訊,請參閱 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 Schema 關鍵字contentEncoding: base64聲明參數,Cowork 會處理其餘部分。 不需要 Microsoft 特定的結構描述擴充,且您伺服器的 API 介面也不會變更。
Cowork 會在呼叫您的伺服器之前解析工作區檔案並將其編碼為 Base64,因此檔案位元組永遠不會進入代理程式的上下文。 代理程式只會看到並輸出工作區檔案路徑。
備註
請勿指示代理程式自行對檔案進行 Base64 編碼,然後將編碼後的資料內容貼到工具呼叫中。 該方法會將整個檔案載入到模型的上下文中,並仰賴模型精確重現整個 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."
}
Agent 看到的內容
對於在 inputSchema.properties 頂層宣告的檔案參數,Cowork 會在面向模型的結構描述中,以單一的 direct_attachment_file_paths 陣列取代它們;這也就是 Cowork 內建工具所使用的同一個參數,因此代理程式已經知道如何填入其中的值。 上述結構描述以下方式呈現給 Agent:
{
"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 依宣告順序將解析後的檔案重新展開為原始參數名稱。
巢狀檔案參數
代理程式支援巢狀在物件或物件陣列中的檔案參數。 Agent 以不同的方式處理此參數:Agent 不加以摺疊,而是在原位置就地將其改寫為路徑字串。 此方法會保留檔案與其同層級欄位之間的關聯。 例如,每項費用明細各有一張收據:
"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 (將它與任意數量的純量檔案參數組合) |
| 巢狀深度上限 | 在 inputSchema 頂端以下 4 個層級 |
超過檔案數量或大小上限的請求會因工具錯誤而失敗,且永遠不會到達您的伺服器。 考慮 150 MiB 上限,調整 API 及其逾時:base64 會使承載比原始檔案大小膨脹約三分之一,而編碼後的內容會在 JSON-RPC 要求本文中傳送。
Recommendations
- 為人類讀者描述參數。 代理程式會使用描述來決定哪個檔案屬於哪個參數欄位。 例如,
"The signed contract PDF to analyze"的效果比"file"更好。 - 在參數描述中說明你接受的格式。 Cowork 會原樣傳遞使用者附加的任何內容。 驗證您這邊的內容類型,如果無法使用,則傳回明確的工具錯誤訊息。
- 設定註解。 接收檔案並對其執行操作的工具通常不是唯讀,因此會要求確認。 深入了解 MCP 註釋和確認管理。
- 使檔案參數維持行內顯示。 在 後
$ref面的參數或巢狀深度超過四個層級的參數,不會被重寫。 伺服器會收到其預期用來接收內容的路徑字串。 - 每個工具最多聲明一個陣列檔案參數。 使用兩個或多個檔案時,Cowork 無法判斷哪個檔案屬於哪個陣列,呼叫會因工具錯誤而失敗。 使用單一陣列、數個純量參數,或混合純量和單一陣列。
- 在僅傳回純量的工具上,預期會有精確計數。 如果您的工具只宣告純量檔案參數,則代理程式傳遞的檔案數目必須與宣告的檔案數目相符。 在描述中清楚標示選用檔案參數,以免 Agent 提供過少或過多。
備註
這種機制早於模型上下文協議自己的文件輸入工作,該工作正在由 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。 版本會追蹤用戶端身分識別合約,且預期會變更;前置詞比對確保您的閘道在版本變動後仍能正常運作。
# 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. 技能資料夾包含標準 Agent 技能。 執行 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 個。
skills 可以參考同一套件的連接器工具嗎?
是的,他們應該這樣做。 在您的SKILL.md工作流程中明確提及工具(例如「使用 search_case_law 工具來……」)。 代理程式會在執行階段連接它們。
我的外掛工具可以接受 Cowork 工作區的檔案嗎?
Yes. 使用 contentEncoding: base64聲明工具參數,Cowork 會在呼叫您的伺服器之前將使用者的工作區檔案解析為 base64 內容。 模型會傳遞檔案路徑,而非檔案內容,因此大型檔案不會佔用模型的上下文容量。 如需宣告詳細資料和限制,請參閱接受來自 Cowork workspace 的檔案以深入了解。
我該如何為我的套件產生一個確定性的 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。 若要自行設定,請傳入 --app-id。 針對手動封裝,請使用任何 GUID 產生器。 請務必在不同版本之間保持穩定。