Создавайте плагины для Copilot Cowork

  • Применяется к: Microsoft Copilot

Microsoft Copilot Cowork поддерживает расширяемость с помощью пакетов приложений M365 — того же механизма распространения, который используется приложениями Teams, агентами Copilot и надстройками Office. Вы можете расширить возможности Cowork с помощью:

  • Навыки: рабочие процессы на основе запросов, которые обучают Cowork новой экспертизе в предметной области, такой как финансовый анализ, юридические исследования или рабочие процессы отдела кадров.
  • Соединители: удаленные серверы, предоставляющие Cowork доступ к внешним источникам данных и API.

Оба компонента упакованы в один стандартный пакет приложений Microsoft 365 и распространяются через магазин приложений Microsoft 365.

Important

Информационные барьеры Microsoft Purview (IB) в настоящее время не поддерживаются для управления подключаемыми модулями или навыками и их совместного использования. В клиентах, где включено это решение, отправка внедренных файлов базы знаний блокируется на уровне клиента. Это предотвращает загрузку или публикацию затронутых плагинов и навыков.

Корпорация Майкрософт не создает и не поддерживает какие-либо постоянные индексы, графы знаний (включая Microsoft Graph) или базы данных, содержащие содержимое независимых поставщиков программного обеспечения, путем сканирования, извлечения, сбора данных, массового экспорта, загрузки данных или любым другим методом (через API, сервер MCP или иным способом). Microsoft может временно обрабатывать содержимое ISV по мере необходимости для реагирования на запрос пользователя в режиме реального времени, но не сохраняет содержимое ISV за пределами этого сеанса. По письменному запросу независимого поставщика программного обеспечения корпорация Майкрософт удаляет все Содержимое независимого поставщика программного обеспечения, находящееся в ее владении или под контролем, в течение 10 рабочих дней и подтверждает такое удаление в письменной форме. Дополнительные сведения см. в статье Защита корпоративных данных в Microsoft Copilot и Microsoft Copilot Chat.

Что вы будете строить

Подключаемый модуль 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

Навыки используют открытый стандарт навыков агента— тот же формат, который поддерживается Claude Code, Visual Studio Code Copilot, Gemini CLI, Cursor, JetBrains Junie и более чем 30 другими инструментами ИИ.

Выберите начальную точку

Создайте свой плагин с помощью wiqd CLI. Интерфейс командной строки создает структуру пакета и синхронизирует manifest.json и папки навыков. Он также выполняет собственные правила валидации платформы перед отправкой, затем подготавливает и публикует результат. CLI находится в предварительной версии, поэтому его команды и сгенерированные выходные данные могут измениться до того, как он станет общедоступным. Все, что он генерирует, представляет собой простой пакет приложений Microsoft 365, поэтому вы по-прежнему можете открывать, редактировать и управлять версиями файлов напрямую.

Собирайте пакет вручную, только если вы не можете установить инструментарий или создаете свой собственный конвейер упаковки. В этом случае вам понадобится справочник по формату пакета , приведенный в этой статье, — он точно описывает, что wiqd производит.

Начальная точка Сделай это Время до первого пакета
Я начинаю с нуля Создание плагина с помощью wiqd около 10 минут
У меня есть подключаемый модуль Claude Code Преобразовать около 5 минут
Я не могу установить инструментарий или пишу свой собственный сценарий упаковки Сборка пакета вручную около 30 минут

Создание плагина с помощью wiqd

Интерфейс командной строки wiqd выполняет те же операции жизненного цикла, что и вы в противном случае выполнили бы вручную: создание, добавление возможностей, проверка, подготовка, упаковка и публикация. Создаваемый пакет уже удовлетворяет правилам проверки , описанным в этой статье.

Шаг 1: Установите wiqd и войдите в систему

Установите Wiqd CLI, следуя руководству по установке Wiqd, которое охватывает Windows, macOS и Linux. Затем войдите в клиент Microsoft 365, в котором вы ведете разработку, так как и подготовка ресурсов, и публикация затрагивают ваш клиент:

wiqd auth login --interactive

Установщик также регистрирует CLI-плагин GitHub Copilot, чтобы вы могли управлять тем же жизненным циклом в диалоговом режиме. Например, вы можете сказать: «Создать отдельный подключаемый модуль с именем 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. Поля в разделе frontmatter, модель прогрессивной загрузки и ограничения на сопутствующие файлы совпадают с описанными в разделах Шаг 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, чтобы предоставить доступ всем в вашей организации. В любом случае плагин появляется в разделе Мне предоставлен доступ в Cowork>Источники & Навыки>Плагины. Чтобы вместо этого он появился в разделе Рекомендуемые, администратор отправляет пакет в систему. Дополнительные сведения см. в разделе Шаге 8. Публикация в клиенте. Чтобы удалить то, что создал provision, запустите wiqd plugin delete --env local --yes.

Публикация в общедоступном Store по-прежнему выполняется вручную в Partner Center. Дополнительные сведения см. в разделе Шаг 9. Публикация для широкой публики.

Перенос плагина на другой узел

Чтобы использовать навыки в Claude Code, Cursor или любом другом узле навыков агента, экспортируйте проект, а не копируйте папки вручную:

wiqd plugin export --format claude-plugin

export по умолчанию имеет значение --format open-plugin и также принимает cursor-plugin. Команда записывает несжатый каталог в <path>/export/<format>.

Импортировать существующий плагин

Если у вас уже есть плагин Claude Code с навыками и серверами MCP, подходов к преобразованию два. Путь, который вы выберете, зависит от того, планируете ли вы продолжать разработку плагина или просто выпустить то, что уже готово.

Goal Использовать
Продолжить разработку, проверку и выпуск плагина для Microsoft 365 wiqd plugin import
Получить пригодный для публикации файл .zip из существующего плагина Claude прямо сейчас Скрипт преобразования

Импорт с помощью 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. Его пока нельзя упаковать, подготовить или предоставить к нему общий доступ, так как импорт не формирует локальные файлы развертывания, необходимые для выполнения этих шагов. Это известный недостаток. Чтобы узнать текущее состояние, см. справочник CLI wiqd. Если вам нужен готовый к публикации пакет уже сегодня, используйте скрипт преобразования.

Преобразуйте с помощью скрипта преобразования

Сценарий преобразования преобразует подключаемый модуль Claude непосредственно в публикуемый пакет M365:

  1. Установите интерфейс командной строки (требуется версия 1.1.12 или более поздняя):

    npm install -g @microsoft/m365agentstoolkit-cli

  2. Проверьте версию:

    atk --version

  3. Импортируйте подключаемый модуль:

    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 (или appPackage/manifest.json), skills/ и каталог .mcp.json вашего плагина, а затем создает каркас проекта Agents Toolkit, содержащего .cursor-plugin/plugin.json, ваши навыки и сгенерированные значки.

Необходимо включить --privacy-url и, --terms-url поскольку манифесты подключаемого модуля не имеют эквивалентных полей, а манифест Microsoft 365 требует обоих полей.

Примечание.

atk import openplugin Находит манифест плагина в каталоге с префиксом точки—.claude-plugin/plugin.json, .cursor-plugin/plugin.jsonили .plugin/plugin.json—рядом с .mcp.json. Спецификация подключаемых модулей агента 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 манифест. Примеры манифеста в других местах этой статьи предназначены для схемы версии 1.28. Если вы публикуете через канал, для которого требуется v1.28, обновите manifestVersion и $schema в созданном appPackage/manifest.json.

Что импортируется

Артефакт подключаемого модуля Эквивалент M365 Notes
.claude-plugin/plugin.json manifest.json Сопоставлены поля имени, описания и разработчика; GUID создан автоматически (детерминированный UUID версии 5)
skills/*/SKILL.md agentSkills[] записей + skills/ папок Копируется дословно — идентичный формат
Серверы .mcp.json Записи agentConnectors[] URL-адрес и тип аутентификации определяются автоматически
color.png / outline.png Иконки в пакете Используется, если имеется; если отсутствует, создаются заполнители

Important

Для каждого соединителя, импортированного из .mcp.json, сгенерированный authorization.referenceId представляет собой заполнитель, производный от имени плагина и сервера. Замените его реальным регистрационным идентификатором клиента OAuth перед публикацией. Подробнее см. в разделе Поддерживаемые типы аутентификации.

Что не преобразуется

Следующие функции подключаемого модуля Claude пока не поддерживаются в манифесте Microsoft 365:

Функция плагина Claude Status
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 Переопределите детерминированный UUID версии 5, сгенерированный для манифеста id
--default-auth-type Auto (по умолчанию), None, OAuthPluginVaultили ApiKeyPluginVault

Автоматическое определение типа аутентификации:

Source Тип аутентификации по умолчанию Reason
Внешние URL-адреса HTTPS OAuthPluginVault Для большинства удаленных API требуется проверка подлинности
localhost и URL-адреса, отличные от HTTPS 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
Option 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 специфичен для 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 стал поддерживать импорт плагинов, для преобразования использовался сценарий PowerShell, предназначенный только для Windows, который и сейчас доступен в качестве сценария преобразования:

.\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 и телом 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 |

Поля frontmatter в файле SKILL.md

Обязательные поля:

Field Constraints Description
name 1–64 символа, формат kebab-case Идентификатор навыка - должен точно совпадать с именем папки
description 1–1024 символа Когда использовать этот навык — включите фразы-триггеры

Important

  • Имя папки должно соответствовать полю name в frontmatter. Это несоответствие является наиболее распространенной причиной сбоев навыка.
  • Поля 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 МБ
Время ожидания загрузки (все сопутствующие файлы) 15 секунд

Правила сопутствующих файлов

Пути к сопутствующим файлам должны соответствовать следующим правилам:

  • Используйте только относительные пути (не абсолютные пути).
  • Нет сегментов, позволяющих выйти за пределы указанного пути (..).
  • Никаких обратных косых черт или нулевых байтов в именах файлов.
  • Нет скрытых файлов (имен, начинающихся с .).
  • Нет зарезервированных имен Windows (CON, PRN, AUX, NUL, COM1–COM9, LPT1–LPT9).
  • Сам файл SKILL.md не считается сопутствующим файлом.
  • В именах файлов необходимо использовать безопасные символы: буквы и цифры, дефисы, символы подчеркивания, точки, пробелы и !.

Чтобы контекстное окно оставалось эффективным, система загружает навыки в три слоя.

Слой При загрузке Размер целевой области
frontmatter (name + description) Всегда — при запуске ~100 токенов
Основная часть SKILL.md При срабатывании навыка Менее 5000 токенов (1500–2000 слов)
Справочники (references/) По запросу агента 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 на мобильных устройствах.

Требования к соединителям

Requirement Details
Transport HTTP с поддержкой потоковой передачи (требуется HTTPS, TLS 1.2+)
Protocol Формат сообщения JSON-RPC 2.0
Обнаружение инструментов Поддержка tools/list для динамического обнаружения (рекомендуется)
Запуск инструмента Поддержка tools/call для вызова
Availability Для публикуемых в магазине приложений рекомендуется SLA с доступностью 99,9 %
Время ответа Менее 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 API OAuth 2.0 (рекомендуется для использования в рабочей среде) Пользователь подтверждает согласие OAuth один раз
ApiKeyPluginVault Службы на основе ключей API Пользователь предоставляет ключ один раз

Примечание.

  • Поддержка проверки подлинности ключа API пока недоступна в Cowork.
  • Если вашему серверу MCP требуется ключ API, вместо этого используйте OAuthPluginVault или динамическую регистрацию клиентов либо предоставьте конечную точку, принимающую None.

В случае с OAuthPluginVault и ApiKeyPluginVaultreferenceId указывает на учетные данные, хранящиеся в хранилище токенов Microsoft Enterprise — секреты никогда не присутствуют в манифесте или файлах навыков. Значение referenceId — это регистрационный идентификатор клиента OAuth, создаваемый при регистрации клиента OAuth с помощью набора инструментов для создания агентов.

Important

При регистрации клиента OAuth укажите для параметра использования организацией значение Любые организации Microsoft 365, чтобы плагин работал в разных клиентах.

Проверка подлинности MCP

О том, как использовать OAuth или ApiKey для аутентификации, см. в статье Настройка проверки подлинности для плагинов MCP и API в агентах в Microsoft 365 Copilot, где рассматриваются подробности конфигурирования.

Динамическая регистрация клиента

Если ваш сервер MCP поддерживает динамическую регистрацию клиентов (DCR), вы можете пропустить authentication конфигурацию в определении соединителя, и Cowork автоматически создаст клиент OAuth от имени вашего плагина.

Примечание.

Пропуск authentication конфигурации поддерживается только в Cowork. В Copilot Chat это не поддерживается. Если подключаемый модуль также должен работать в Copilot Chat, настройте OAuthPluginVault проверку подлинности, как описано в разделе Поддерживаемые типы проверки подлинности.

Объект authorization можно полностью опустить. Настройте URL-адрес сервера MCP, и 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 должен указывать на JSON-файл с описанием инструмента, включенный в ZIP-пакет.

Important

Схема манифеста версии 1.28 является строгой: она задает additionalProperties: false в корне, поэтому любое поле, не определенное в схеме, отклоняется. Поля, допустимые в стандартных манифестах приложений Teams, например packageName, приводят к сбою отправки с ошибкой, такой как Property 'packageName' has not been defined and the schema does not allow additional properties. Включайте только показанные здесь поля.

Шаг 5: Добавьте значки

Создайте два значка в формате PNG:

Значок Size Purpose
color.png 192×192 пикселя Полноцветный значок приложения, отображаемый в магазине и списке приложений
outline.png 32×32 пикселей Одноцветный контурный значок для компактных представлений

Если у вас еще нет значков, 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 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:

  1. Установите @microsoft/m365agentstoolkit-cli из npm:

    npm install -g @microsoft/m365agentstoolkit-cli

  2. Проверьте установку, выполнив:

    atk --version

  3. Проверка подлинности с помощью рабочей учетной записи Microsoft 365:

    atk auth login

  4. Войдите в свою рабочую учетную запись и установите пакет агента. Замените путь к файлу местоположением вашего ZIP-пакета:

    atk install --file-path "C:/Users/myuser/myPackage.zip" --scope Personal

    При успешной установке вывод содержит TitleId и AppId для вашей учетной записи.

  5. Сохраните эти идентификаторы для дальнейшего использования при обновлении или удалении.

Дополнительные сведения см. в статье Интерфейс командной строки набора инструментов для создания агентов Microsoft 365.

Шаг 8. Публикация в клиенте

Отправьте пакет в центр администрирования, чтобы разместить свой плагин в разделе Рекомендуемые, где его сможет найти любой пользователь вашей организации:

  1. Откройте >Управление приложениями>Загрузить пользовательское приложение.
  2. Выберите кнопку с многоточием (...) >Добавить агент.
  3. Загрузите свой .zip пакет.
  4. Откройте Cowork>Источники & Навыки>Плагины. Ваш плагин отображается в разделе Discover.

wiqd plugin share помещает плагин в раздел Мне предоставлен доступ, а не в раздел Рекомендуемые. Используйте его для тестирования и целевого развертывания для конкретных пользователей. Чтобы он появился в раздел «Рекомендуемые», его нужно отправить в центр администрирования.

Шаг 9. Публикация для широкой публики

Если ваш плагин предназначен для распространения среди широкой публики, отправьте его в магазин приложений Microsoft 365 через Центр партнеров. Дополнительные сведения см. в статье Публикация агентов для Microsoft 365 Copilot.

Тестирование соединителя с локальным сервером MCP

Соединителям требуется mcpServerUrl протокола HTTPS. Чтобы протестировать сервер, работающий на вашем компьютере, необходимо сделать его доступным по общедоступному URL-адресу HTTPS. Туннель разработки предоставляет ретранслятор, который выполняет завершение TLS-соединения за вас.

devtunnel port create <tunnel> -p <port> --protocol http

Important

Используйте --protocol http, а не https. Флаг --protocol описывает локальную службу, которой туннель перенаправляет трафик, а не общедоступный URL-адрес туннеля. Большинство локальных серверов MCP используют простой HTTP, поэтому, если вы зададите --protocol https, но ваш сервер работает по HTTP, каждый запрос через туннель будет завершаться ошибкой 502. Ретранслятор завершает TLS и обслуживает общедоступный URL-адрес по протоколу HTTPS независимо от этого флага.

Troubleshooting

Симптом Причина Исправление
Каждый туннелированный запрос возвращает 502, а локальный сервер говорит по HTTP Команда devtunnel port create была выполнена с --protocol https Повторно создайте порт с помощью --protocol http
Туннелированные запросы возвращают 502 в macOS, даже если локальный сервер работает Сервер привязан к 0.0.0.0 (только IPv4), но туннель подключается к localhost, который сначала разрешается в ::1 (IPv6) Привяжите сервер к ::, чтобы он принимал и подключения IPv4, и подключения IPv6
Отправка завершается сбоем с ошибкой Property '<field>' has not been defined and the schema does not allow additional properties Манифест включает поле, недопустимое в схеме версии 1.28 (например, packageName) Удалите поле; в схеме версии 1.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

Используйте эту опцию для существующих плагинов экосистемы Claude, предназначенных для Cowork. Чтобы продолжить разработку подключаемого модуля в 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 файлах. Используйте agentConnectors с аутентификацией для учетных данных API.
  • Не дублируйте встроенные навыки. Перед созданием сверьтесь со встроенным списком навыков .
  • Не делайте навыки слишком общими. «Делает все с юридическими документами» хуже, чем конкретные навыки для «анализа контракта», «извлечения положений» и «изучения нормативной базы».
  • Не прописывайте жестко пути к файлам или системные команды. Навыки должны быть применимы в разных средах.
  • Не кладите все в SKILL.md. Если объем текста превышает ~3000 слов, переместите детальное содержимое в раздел references/.

Правила проверки

При отправке пакета платформа проверяет его на нескольких уровнях. Исправьте эти ошибки перед отправкой, чтобы избежать отклонения.

Чтобы перехватывать их в ходе разработки, а не при отправке, выполните wiqd plugin validate --mode deep. Эта команда упаковывает плагин и запускает те же правила локально. Подробнее см. в разделе Шаг 3. Проверка по ходу создания.

Проверка на уровне манифеста

Code Rule Severity
ASKILL-M001 folder является обязательной в каждой записи agentSkills Ошибка
ASKILL-M002 agentSkills Массив может содержать до 20 элементов Ошибка
ASKILL-M003 folder Путь может содержать до 256 символов Ошибка

Проверка на уровне пакета

Code Rule Вероятное решение Severity
ASKILL-P001 Папка, на которую ссылается манифест, существует в ZIP-архиве Проверьте структуру ZIP-архива Ошибка
ASKILL-P002 Папка SKILL.md содержит файл Добавить отсутствующий SKILL.md Ошибка
ASKILL-P003 SKILL.md содержит допустимый frontmatter на YAML между разделителями --- Исправьте синтаксис YAML Ошибка
ASKILL-P004 Frontmatter включает name поле Добавить name: к frontmatter Ошибка
ASKILL-P005 Frontmatter включает description поле Добавить description: к frontmatter Ошибка
ASKILL-P006 name Совпадает с именем папки (последний сегмент пути) Переименуйте папку или исправьте name: Ошибка
ASKILL-P007 name записано в формате kebab-case Используйте my-skill, а не MySkill или my_skill Ошибка
ASKILL-P008 В массиве нет повторяющихся folder значений Удаление дубликатов Ошибка

Проверка коннектора

Rule Severity
Для каждого разъёма требуются id и displayName Ошибка
Все значения id соединителей должны быть уникальными в манифесте Ошибка
Ровно один plugin или remoteMcpServer Ошибка
mcpServerUrl должен быть действительным URL-адресом HTTPS Ошибка
Если mcpToolDescription присутствует, его file должен находиться в ZIP-архиве Ошибка
authorization.referenceId является обязательным, если тип не None Ошибка
authorization.referenceId не должен присутствовать, если тип — None Ошибка

Проверка сопутствующих файлов

Портал проверяет сопутствующие файлы (справочные материалы, скрипты и другие файлы, загружаемые вместе с SKILL.md) при загрузке и синхронизации:

Rule Severity
Максимум 20 сопутствующих файлов для одного навыка (исключая SKILL.md) Ошибка
Размер каждого сопутствующего файла не должен превышать 5 МБ Ошибка
Общий размер сопутствующих файлов для каждого навыка не должен превышать 10 МБ Ошибка
Пути к файлам должны быть относительными (не абсолютными) Ошибка
Нет сегментов, позволяющих выйти за пределы указанного пути (..) Ошибка
Никаких обратных косых черт или нулевых байтов в именах файлов Ошибка
Нет скрытых файлов (имена, начинающиеся с .) Ошибка
Нет зарезервированных имен Windows (CON, PRN, AUX, NUL, COM1–COM9, LPT1–LPT9) Ошибка
В именах файлов должны использоваться только безопасные символы (буквы и цифры, дефисы, символы подчеркивания, точки, пробелы, !) Ошибка

Кроссплатформенная совместимость

Навыки используют открытый стандарт Agent Skills. Одни и те же SKILL.md файлы работают в нескольких инструментах ИИ:

Platform Compatibility
Код Клода Полностью идентичный SKILL.md формат
Проекты Claude.ai Полная — навыки можно отправлять как файлы проекта
VS Code / GitHub Copilot Навыки Full-Agent, поддерживаемые в режиме агента
Интерфейс командной строки Gemini Полная — навыки агентов поддерживаются
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, импортируйте его в 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 считывает стандартный объект MCP annotations в инструментах, которые возвращает ваш сервер, из tools/list, и использует его, чтобы решить, требуется ли подтверждение пользователем для вызова средства и какую метку показывать в запросе.

Доступные поля

Field Type Effect
readOnlyHint bool false: перед запуском средства требуется подтверждение.
destructiveHint bool true: перед запуском средства требуется подтверждение.
title string Удобочитаемая метка, отображаемая в диалоговом окне подтверждения. При отсутствии используется имя инструмента.

Правила подтверждения

Подтверждение требуется, если 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
  }
}

Что доступно сейчас

  • Инструменты Майкрософт (Graph, Dataverse и другие) ограничиваются встроенной политикой Cowork независимо от аннотаций.
  • Для сторонних серверов MCP подтверждение на основе аннотаций еще находится в процессе развертывания. Если настроить подсказки сейчас, это обеспечит прямую совместимость в будущем, и запросы на подтверждение будут появляться по мере развертывания, без необходимости вносить изменения со стороны разработчика.

Принятие файлов из рабочей области Cowork

Инструмент-соединитель может принимать в качестве входных данных файл из сеанса Cowork пользователя: документ, прикрепленный пользователем, вложение электронной почты, сохраненное Cowork, или файл, созданный на предыдущем шаге. Объявите параметр стандартным ключевым словом contentEncoding: base64 JSON Schema, и Cowork обработает остальное. Расширение схемы, специфичное для Майкрософт, не требуется, а интерфейс 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 МиБ
Суммарный размер на вызов инструмента 150 МиБ
Массив параметров файлов на инструмент 1 (объединяйте его с любым числом скалярных параметров файлов)
Максимальная глубина вложения 4 уровня ниже верхнего уровня inputSchema

Вызов, превышающий ограничение на количество или размер файлов, завершается ошибкой инструмента и не достигает сервера. Определяйте размер API и его тайм-ауты с учетом ограничения в 150 МиБ: Base64 увеличивает полезные данные примерно на треть по сравнению с размером необработанного файла, и закодированное содержимое отправляется в теле запроса JSON-RPC.

Recommendations

  • Описывайте параметр с расчетом на читателя-человека. Агент использует описание, чтобы определить, какой файл относится к какому параметру. Например, "The signed contract PDF to analyze" работает лучше, чем "file".
  • Указывайте принимаемые форматы в описании параметра. Cowork обрабатывает все файлы, прикрепленные пользователем. Проверяйте тип содержимого на своей стороне и возвращайте явную ошибку инструмента, если оно непригодно для использования.
  • Задавайте аннотации. Средство, которое получает файл и работает с ним, обычно не предназначено только для чтения, поэтому оно запрашивает подтверждение. Дополнительные сведения см. в статье Управление аннотациями и подтверждениями MCP.
  • Записывайте параметры файлов в строке. Параметр за $ref или вложенный глубже четырех уровней не переписывается. Сервер получит строку пути вместо содержимого, которое ожидает сервер.
  • Объявляйте не более одного параметра файла — массива на инструмент. Если их будет два или больше, Cowork не сможет определить, к какому массиву относится какой файл, и вызов завершится ошибкой инструмента. Используйте один массив, или несколько скалярных параметров, или сочетание скаляров и одного массива.
  • Точное число возможно только в инструментах со скалярными параметрами. Если ваш инструмент объявляет только скалярные файловые параметры, количество файлов, передаваемых агентом, должно соответствовать заявленному числу. Четко помечайте необязательные параметры файлов как таковые в их описаниях, чтобы агент не передавал слишком мало или слишком много данных.

Примечание.

Этот механизм появился раньше, чем собственная работа Model Context Protocol по приёму файлов, которую стандартизирует рабочая группа 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) и версия контракта Идентификатор клиента, пользователя, сеанса или беседы
Одно и то же значение в каждом запросе и при каждом подключении Квалификатор для каждого соединителя

Поскольку идентификатор не содержит признака конкретного соединителя, в настоящее время вы не можете использовать этот идентификатор для определения того, какой соединитель отправил вызов, или для отделения опубликованного плагина Майкрософт от неопубликованного сервера, указывающего на тот же URL-адрес. Если вам необходимо это различие, применяйте его с помощью конфигурации авторизации соединителя, а не с помощью идентификатора клиента.

Распространенные вопросы

Можно ли использовать навыки из пакета M365 в коде Claude?

Yes. Папки навыков содержат стандартные навыки агента. Выполните wiqd plugin export --format claude-plugin, чтобы создать макет Claude Code, или скопируйте папки навыков в .claude/skills/ в любом проекте Claude Code.

Нужен ли мне удаленный коннектор?

No. Пакеты, содержащие только навыки, хорошо подходят для рабочих процессов, основанных на промптах. Коннекторы нужны только в том случае, если для навыка требуются данные в режиме реального времени из внешней системы.

Чем навыки плагина отличаются от встроенных навыков?

В API навыки-плагины имеют источник "package". Они не могут переопределить встроенные навыки с тем же именем. Развернутые администраторами пакеты отображаютсяisAdminDeployed: true.

Могут ли ИТ-администраторы управлять тем, какие плагины доступны?

Yes. Применяются стандартные элементы управления администратора M365: списки разрешений и блокировок на уровне клиента, управление развертыванием со стороны администратора и политики соответствия.

Что произойдет при отзыве подключаемого модуля?

При следующем цикле синхронизации навыки и соединители из того пакета удаляются из сеанса пользователя. Активные беседы не прерываются, но в новых сеансах возможности пакета недоступны.

Какое максимальное количество навыков в пакете?

Двадцать (20) навыков (согласно ASKILL-M002). Для соединителей ограничение составляет 10 штук на упаковку.

Могут ли навыки ссылаться на инструменты соединителя из того же пакета?

Да, причем они должны это делать. Четко называйте инструменты в вашем рабочем процессе SKILL.md (например, "Используйте инструмент search_case_law, чтобы..."). Агент соединяет их во время выполнения.

Могут ли инструменты подключаемого модуля принимать файлы из рабочей области Cowork?

Yes. Объявите параметр инструмента с использованием contentEncoding: base64, и Cowork преобразует файл в рабочей области пользователя в содержимое в Base64, прежде чем вызывать ваш сервер. Модель передает пути к файлам, а не содержимое файлов, поэтому большие файлы не занимают контекст модели. Подробнее об объявлении и об ограничениях см. в разделе Принятие файлов из рабочей области Cowork.

Как мне создать детерминированный GUID для моего пакета?

wiqd plugin create создает и закрепляет идентификатор приложения. Сценарий преобразования использует UUID версии 5 (на основе SHA-1) из имени подключаемого модуля, поэтому при двойном запуске преобразования создается один и тот же идентификатор GUID. Для ручной упаковки используйте любой генератор GUID. Следите за тем, чтобы GUID оставался постоянным при смене версий.

На какую версию манифеста следует ориентироваться?

Выбирайте 1.29, если вы собираете с wiqd, который закрепляет её для вас. В версии 1.29 записи agentConnectors[] содержат только URL-адрес, а mcpToolDescription является необязательным. В написанных вручную примерах в этой статье используется версия 1.28, где mcpToolDescription является обязательным и файл, имя которого в нем указано, должен быть в ZIP-архиве. atk import openplugin использует UUID v5 (на базе SHA-1) на основе имени вашего плагина. При повторном выполнении импорта будет получен тот же GUID. Чтобы задать собственное значение, передайте --app-id. Для ручной упаковки используйте любой генератор GUID. Следите за тем, чтобы GUID оставался постоянным при смене версий.

  • Последнее обновление: