สร้างปลั๊กอินสําหรับ Copilot Cowork

Microsoft Copilot Cowork รองรับการขยายความสามารถผ่านแพคเกจแอป M365 ซึ่งเป็นกลไกการแจกจ่ายเดียวกันกับที่ใช้โดยแอป Teams, ตัวแทน Copilot และ Add-in ของ Office คุณสามารถขยาย Cowork ด้วย:

• ทักษะ: เวิร์กโฟลว์แบบยึดตามพร้อมท์ที่สอนความเชี่ยวชาญด้านโดเมนใหม่ของ Cowork เช่น การวิเคราะห์ทางการเงิน การวิจัยทางกฎหมาย หรือเวิร์กโฟลว์ HR
• ตัวเชื่อมต่อ: เซิร์ฟเวอร์ระยะไกลที่ทำให้ Cowork เข้าถึงแหล่งข้อมูลภายนอกและ API ได้

ทั้งสองรายการถูกรวมบรรจุไว้ด้วยกันในแพ็กเกจแอป Microsoft 365 มาตรฐาน และเผยแพร่ผ่าน Microsoft 365 App Store

Microsoft จะไม่สร้างหรือดูแลรักษาดัชนีถาวร กราฟองค์ความรู้ (รวมถึง Knowledge Graph) รวมถึง Microsoft Graph หรือฐานข้อมูลใด ๆ ที่มีเนื้อหาของ ISV ไม่ว่าจะได้มาจากการรวบรวมข้อมูลจากเว็บไซต์ การดึงข้อมูล การเก็บรวบรวมข้อมูล การส่งออกข้อมูลจำนวนมาก การนำเข้าข้อมูล หรือวิธีการอื่นใด (ผ่าน API, MCP server หรือช่องทางอื่นๆ) Microsoft อาจประมวลผลเนื้อหา ISV ชั่วคราวตามที่จำเป็นเพื่อตอบสนองต่อการสอบถามแบบเรียลไทม์ของผู้ใช้ แต่จะไม่เก็บเนื้อหา ISV ไว้เกินระยะเวลาของเซสชันนั้น เมื่อ ISV ร้องขอเป็นลายลักษณ์อักษร Microsoft จะลบเนื้อหา 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

Skills ใช้มาตรฐานเปิด Agent Skills ซึ่งเป็นรูปแบบเดียวกันกับที่ Claude Code, Visual Studio Code Copilot, Gemini CLI, Cursor, JetBrains Junie และเครื่องมือ AI อื่น ๆ อีกกว่า 30 รายการรองรับ

เลือกจุดเริ่มต้นของคุณ

สร้างปลั๊กอินของคุณด้วย wiqd CLI CLI จะสร้างโครงแพ็กเกจและทำให้ manifest.json และโฟลเดอร์ทักษะของคุณซิงค์กัน นอกจากนี้ยังเรียกใช้กฎการตรวจสอบความถูกต้องของแพลตฟอร์มก่อนที่คุณอัปโหลด จากนั้นเตรียมใช้งานและแชร์ผลลัพธ์ CLI อยู่ในช่วงพรีวิว ดังนั้นคำสั่งและผลลัพธ์ที่สร้างขึ้นอาจเปลี่ยนแปลงได้ก่อนการเปิดให้ใช้งานทั่วไป ทุกอย่างที่สร้างเป็นแพคเกจแอป Microsoft 365 ธรรมดา ดังนั้นคุณยังคงสามารถเปิด แก้ไข และจัดการเวอร์ชันของไฟล์ได้โดยตรง

ประกอบแพ็กเกจซอฟต์แวร์ด้วยตนเองเฉพาะเมื่อคุณไม่สามารถติดตั้งเครื่องมือ หรือเมื่อคุณกำลังสร้างไปป์ไลน์บรรจุภัณฑ์ของคุณเอง ในกรณีนั้น ข้อมูลอ้างอิงเกี่ยวกับรูปแบบแพ็กเกจ ในบทความนี้คือสิ่งที่คุณต้องการ—โดยอธิบายไว้อย่างชัดเจนว่า wiqd สร้างอะไรขึ้นมาบ้าง

สร้างปลั๊กอินด้วย wiqd

wiqd CLI ทำงานตามวงจรการทำงานเดียวกันกับที่คุณต้องทำด้วยตนเอง—สร้าง เพิ่มความสามารถ ตรวจสอบ จัดเตรียม ประกอบแพ็กเกจ และแชร์ แพ็กเกจที่สร้างขึ้นเป็นไปตามกฎการตรวจสอบความถูกต้องในบทความนี้อยู่แล้ว

ขั้นตอนที่ 1: ติดตั้ง wiqd และลงชื่อเข้าใช้

ติดตั้ง wiqd CLI โดยทําตามคําแนะนําการติดตั้ง wiqd ซึ่งครอบคลุม 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และลงทะเบียนappPackage/skills/contract-analysis/SKILL.mdในagentSkills[] add connectorเขียนรายการ agentConnectors[] ทั้งสองคำสั่งบังคับใช้การตั้งชื่อและข้อจำกัดด้านขนาดของแพลตฟอร์มก่อนเขียน ดังนั้นชื่อโฟลเดอร์ไม่ตรงตามข้อกำหนดหรือ id ที่ยาวเกินจะไม่ไปถึงไฟล์กำกับ

เขียนตรรกะทักษะของคุณใน SKILL.md ที่สร้างขึ้น เขตข้อมูล frontmatter แบบจําลองการโหลดแบบก้าวหน้า และขีดจํากัดของไฟล์ที่มาด้วยเหมือนกับที่อธิบายไว้ใน ขั้นตอนที่ 1: สร้างทักษะแรกของคุณและขั้นตอนที่ 2: เพิ่มเอกสารอ้างอิง (ไม่บังคับ)

ขั้นตอนที่ 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>Sources & Skills>Plugin หากต้องการให้แสดงอยู่ในส่วน ค้นพบ แทน ผู้ดูแลระบบจะอัปโหลดแพ็กเกจ เรียนรู้เพิ่มเติมใน ขั้นตอนที่ 8: เผยแพร่ไปยังเทนเนนต์ของคุณ เมื่อต้องการเอาสิ่งที่ provision สร้างออก ให้เรียกใช้คำสั่ง wiqd plugin delete --env local --yes

การส่งไปยังร้านค้าสาธารณะยังคงเป็นกระบวนการที่ดำเนินการด้วยตนเองใน Partner Center เรียนรู้เพิ่มเติมในขั้นตอนที่ 9: เผยแพร่ไปยังสาธารณะ

นำปลั๊กอินไปยังโฮสต์อื่น

หากต้องการใช้ Skills ของคุณใน Claude Code, Cursor หรือโฮสต์ Agent Skills อื่น ๆ ให้ส่งออกโปรเจ็กต์แทนการคัดลอกโฟลเดอร์ด้วยตนเอง:

wiqd plugin export --format claude-plugin

exportค่าเริ่มต้นเป็น --format open-plugin และ ยังยอมรับcursor-plugin ระบบจะเขียนไดเรกทอรีที่ไม่บีบอัดไว้ภายใต้ <path>/export/<format>

นำเข้าปลั๊กอินที่มีอยู่

หากคุณมีปลั๊กอิน Claude Code พร้อมทักษะและเซิร์ฟเวอร์ MCP อยู่แล้ว คุณจะมีเส้นทางการแปลงสองเส้นทาง เส้นทางที่คุณเลือกขึ้นอยู่กับว่าคุณวางแผนที่จะพัฒนาปลั๊กอินต่อไปหรือเพียงแค่เผยแพร่เวอร์ชันเท่าที่มีอยู่

นำเข้าด้วย wiqd

wiqd plugin import ตรวจพบแหล่งที่มาของ Open Plugin, Claude plugin หรือ Cursor plugin และสร้างโปรเจ็กต์ปลั๊กอิน 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 ก่อนหน้า เมตาดาต้าไปกลับก็มีข้อมูลเหล่านั้นอยู่แล้ว

แปลงด้วยสคริปต์การแปลง

สคริปต์การแปลงแปลงปลั๊กอิน Claude โดยตรงให้เป็นแพ็กเกจ M365 ที่สามารถเผยแพร่ได้:

1. ติดตั้ง CLI (ต้องใช้เวอร์ชัน 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 (หรือ .cursor-plugin/plugin.json), .mcp.json และ skills/ ของปลั๊กอิน จากนั้นสร้างโครงการ Agents Toolkit แบบโครงร่างซึ่งมี appPackage/manifest.json ทักษะของคุณ และไอคอนที่สร้างขึ้น

คุณต้องรวม --privacy-url และ --terms-url เนื่องจากไฟล์ manifest ของปลั๊กอินไม่มีเขตข้อมูลที่เทียบเท่า และไฟล์ manifest ของ Microsoft 365 จำเป็นต้องใช้ทั้งสองอย่าง

แพ็กเกจผลลัพธ์ลงในไฟล์ที่สามารถอัปโหลดได้ .zip:

cd my-plugin-project
atk package --manifest-file ./appPackage/manifest.json \
  --output-package-file ./appPackage/build/appPackage.zip \
  --output-folder ./appPackage/build

สิ่งที่นําเข้า

สิ่งที่ไม่ถูกแปลง

คุณลักษณะปลั๊กอิน Claude ต่อไปนี้ยังไม่ได้รับการสนับสนุนในไฟล์ Manifest ของ Microsoft 365:

ตัวเลือกการนำเข้า

การตรวจหาชนิดการรับรองความถูกต้องอัตโนมัติ:

หากการตรวจหาอัตโนมัติไม่ตรงกับการตั้งค่าของคุณ ให้ใช้ --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

การส่งออกจะเขียนบล็อก x-microsoft-365-agents-toolkit ลงใน plugin.json ที่สร้างขึ้น บล็อกดังกล่าวมีไฟล์กำกับ id URL ของนักพัฒนา และการตั้งค่าตัวเชื่อมต่อ ดังนั้นเมื่อใช้atk import openplugin ในภายหลัง ก็สามารถแปลงไปกลับได้โดยไม่ต้องใช้ --privacy-url หรือ --terms-url อีกครั้ง

แบบดั้งเดิม: สคริปต์การแปลง PowerShell

ก่อนที่ atk จะรองรับการนำเข้าปลั๊กอิน การแปลงจะใช้สคริปต์ PowerShell ที่ทำงานได้เฉพาะบน Windows ซึ่งยังคงมีให้ใช้งานในชื่อ สคริปต์การแปลง:

.\Convert-ClaudePluginToMOS3.ps1 -PluginPath ./my-claude-plugin -OutputPath ./output

ใช้ atk import openplugin แทน รองรับหลายแพลตฟอร์ม รองรับทั้ง Cursor และแหล่งข้อมูล Claude Code และสามารถส่งออกกลับไปยังไดเรกทอรีปลั๊กอินได้

ประกอบแพ็กเกจด้วยมือ

ส่วนนี้คือข้อมูลอ้างอิงรูปแบบแพคเกจ: จะอธิบายอย่างละเอียดว่า Build a plugin with 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 |

ฟิลด์ frontmatter ใน SKILL.md

เขตข้อมูลที่จําเป็น:

กฎการตั้งชื่อ (kebab-case): ใช้เฉพาะอักขระตัวอักษรและตัวเลขพิมพ์เล็ก รวมถึงเครื่องหมายยัติภังค์ เท่านั้น อย่าใช้เครื่องหมายยัติภังค์หลายตัวติดกัน และอย่าใช้เครื่องหมายยัติภังค์ขึ้นต้นหรือลงท้าย

ขั้นตอนที่ 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) ขีดจํากัดต่อไปนี้ใช้ได้ต่อทักษะ:

กฎสำหรับไฟล์ประกอบ

พาธของไฟล์ประกอบต้องเป็นไปตามกฎต่อไปนี้:

• ใช้เส้นทางสัมพัทธ์เท่านั้น (ไม่มีเส้นทางสัมบูรณ์)
• ไม่มีการส่งผ่านพาธ (เซกเมนต์ ..)
• ไม่มีแบ็กสแลชหรือไบต์ null ในชื่อไฟล์
• ไม่มีแฟ้มที่ซ่อนอยู่ (ชื่อที่ขึ้นต้นด้วย .)
• ไม่มีชื่อที่สงวนไว้ของ Windows (CON, PRN, AUX, NUL, COM1–COM9, LPT1–LPT9).
• ไฟล์ SKILL.md เองไม่นับว่าเป็นไฟล์ประกอบ
• ชื่อไฟล์ต้องใช้อักขระที่ปลอดภัย ได้แก่ ตัวอักษรและตัวเลข ยัติภังค์ ขีดล่าง จุด ช่องว่าง และ !

เพื่อให้หน้าต่างบริบทมีประสิทธิภาพ ระบบจะโหลดทักษะในสามเลเยอร์:

อ้างอิงไดเรกทอรีย่อยอย่างชัดเจนใน 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 ระยะไกล ขั้นตอนนี้เป็นทางเลือก แพ็กเกจที่มีเฉพาะทักษะทำงานได้ดีสำหรับเวิร์กโฟลว์ที่อิงพรอมป์ต์

ข้อกําหนดของตัวเชื่อมต่อ

แนวทางการออกแบบเครื่องมือ

• เครื่องมือหนึ่งรายการต่อการดําเนินการสําหรับ API ขนาดเล็ก (น้อยกว่า 15 การดําเนินการ): search_case_lawget_rulingcite_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 รวมไว้พร้อมกับโฟลเดอร์ skills/ และ manifest.json ของคุณเมื่อคุณทำแพคเกจปลั๊กอิน

ชนิดการรับรองความถูกต้องที่รองรับ

คุณสามารถค้นหารูปแบบอ้างอิงที่เชื่อมต่อ Cowork กับบริการที่ป้องกันด้วยคีย์ API ผ่านจุดสิ้นสุด MCP ที่ป้องกันโดย Entra ใน สร้างปลั๊กอินสําหรับ API สายงานธุรกิจ

สําหรับ OAuthPluginVault และ ApiKeyPluginVault, referenceId ชี้ไปยังข้อมูลประจําตัวที่จัดเก็บไว้ใน Microsoft Enterprise Token Store - ความลับจะไม่ปรากฏในไฟล์แมนิเฟสต์หรือไฟล์สกิล ค่าreferenceIdคือ ID การลงทะเบียนไคลเอ็นต์ OAuth ที่คุณสร้างขึ้นเมื่อคุณลงทะเบียนไคลเอ็นต์ OAuth ด้วย Agents Toolkit

การตรวจสอบสิทธิ์ MCP

เมื่อต้องการใช้ OAuth หรือ ApiKey สำหรับการรับรองความถูกต้อง โปรดดู กำหนดค่าการรับรองความถูกต้องสำหรับปลั๊กอิน MCP และ API ในเอเจนต์ใน Microsoft 365 Copilot สำหรับรายละเอียดเกี่ยวกับการตั้งค่าและการกำหนดค่า

การลงทะเบียนลูกค้าแบบไดนามิก

หากเซิร์ฟเวอร์ MCP ของคุณรองรับการลงทะเบียนไคลเอ็นต์แบบไดนามิก (DCR) คุณสามารถละเว้นการกำหนดค่า authentication จากคำจำกัดความของตัวเชื่อมต่อได้ และ Cowork จะสร้างไคลเอ็นต์ OAuth ในนามของปลั๊กอินของคุณโดยอัตโนมัติ

คุณสามารถละเว้น authorization วัตถุได้ กําหนดค่า URL เซิร์ฟเวอร์ MCP ของคุณและ Cowork ดูแลไคลเอ็นต์ OAuth:

"remoteMcpServer": {
  "mcpServerUrl": "https://api.contoso.com/legal/mcp"
}

ขั้นตอนที่ 4: สร้าง manifest

สร้าง manifest.json ที่โฟลเดอร์รากของแพ็กเกจของคุณ ตัวอย่างใช้ไฟล์ manifest เวอร์ชัน 1.28 แต่ในตัวอย่างนี้ wiqd plugin create pins 1.29 แทน โดยที่รายการตัวเชื่อมต่อเป็น URL-only

{
  "$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 ถ้าคุณรวม mcpToolDescriptionfile ของมันจะต้องชี้ไปยังไฟล์ JSON คำอธิบายเครื่องมือที่รวมอยู่ในแพ็กเกจ ZIP

ขั้นตอนที่ 5: เพิ่มไอคอน

สร้างไอคอน PNG สองไอคอน:

ถ้าคุณยังไม่มีไอคอน atk import openplugin จะสร้างตัวยึดตำแหน่งสีทึบ แทนที่ค่าเหล่านั้นก่อนส่งขึ้นสโตร์ Store

ขั้นตอนที่ 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 Agents Toolkit:

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 Agents Toolkit

ขั้นตอนที่ 8: เผยแพร่ไปยังเทนเนนต์ของคุณ

อัปโหลดแพคเกจในศูนย์การจัดการเพื่อแสดงรายการปลั๊กอินของคุณในส่วน Discover ซึ่งทุกคนในองค์กรของคุณสามารถค้นหาได้:

1. เปิด >จัดการแอป>อัปโหลดแอปแบบกำหนดเอง
2. เลือกปุ่มจุดไข่ปลา (...) >เพิ่มเอเจนต์
3. อัปโหลดแพ็กเกจของคุณ .zip
4. เปิด Cowork>แหล่งข้อมูลและทักษะ>. ปลั๊กอินของคุณจะปรากฏในส่วน ค้นพบ

wiqd plugin share จะวางปลั๊กอินไว้ใน แชร์กับฉัน แทนที่จะเป็น ค้นพบ ใช้สำหรับการทดสอบและการทยอยเปิดตัวแบบกำหนดเป้าหมายแก่บุคคลที่ระบุ การอัปโหลดในศูนย์การจัดการจะทำให้ปลั๊กอินถูกแสดงในรายการเพื่อให้ค้นพบได้

ขั้นตอนที่ 9: เผยแพร่ไปยังสาธารณะ

สําหรับปลั๊กอินที่มีไว้สําหรับการเผยแพร่ต่อสาธารณะ ให้ส่งปลั๊กอินของคุณไปยัง Microsoft 365 App Store ผ่าน Partner Center เรียนรู้เพิ่มเติมใน การเผยแพร่เอเจนต์สำหรับ Microsoft 365 Copilot

ทดสอบตัวเชื่อมต่อกับเซิร์ฟเวอร์ MCP ภายในเครื่อง

ตัวเชื่อมต่อต้องใช้ HTTPS mcpServerUrl หากต้องการทดสอบเซิร์ฟเวอร์ที่ทำงานอยู่บนเครื่องของคุณ คุณจำเป็นต้องเปิดให้เข้าถึงผ่าน URL HTTPS สาธารณะ Dev tunnels มีบริการรีเลย์ที่ทำหน้าที่สิ้นสุดการเชื่อมต่อ TLS ให้คุณ

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

Troubleshooting

รูปแบบบรรจุภัณฑ์

เลือกรูปแบบที่เหมาะกับส่วนขยายของคุณ:

ทักษะเท่านั้น (ไม่มีตัวเชื่อมต่อ)

เหมาะสำหรับเวิร์กโฟลว์ที่ยึดตามพรอมป์ต์ การวิเคราะห์เอกสาร และความช่วยเหลือในการเขียน

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 หรือเคอร์เซอร์ที่นำเข้า

ใช้ตัวเลือกนี้สําหรับปลั๊กอินระบบนิเวศ 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

แนวทางปฏิบัติที่ดีที่สุดในการสร้าง Skill

ปฏิบัติตามหลักเกณฑ์เหล่านี้เพื่อสร้างทักษะที่ทำงานได้อย่างน่าเชื่อถือและสร้างผลลัพธ์ที่สอดคล้องกัน

เขียนคำอธิบายที่มีประสิทธิภาพ

ฟิลด์ 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 ถ้าเนื้อความของคุณเกิน ~3,000 คํา ย้ายเนื้อหาโดยละเอียดไปยังreferences/

กฎการตรวจสอบความถูกต้อง

เมื่อคุณส่งแพ็กเกจของคุณ แพลตฟอร์มจะตรวจสอบความถูกต้องของแพ็กเกจในหลายระดับ แก้ไขข้อผิดพลาดเหล่านี้ก่อนส่งงานเพื่อหลีกเลี่ยงไม่ให้ถูกปฏิเสธ

หากต้องการตรวจพบข้อผิดพลาดเหล่านั้นระหว่างการสร้าง แทนที่จะรอจนถึงตอนอัปโหลด ให้เรียกใช้ wiqd plugin validate --mode deep คําสั่งนี้จะแพคเกจปลั๊กอินและเรียกใช้กฎเดียวกันนี้ภายในเครื่อง เรียนรู้เพิ่มเติมในขั้นตอนที่ 3: ตรวจสอบเมื่อคุณสร้าง

การตรวจสอบระดับไฟล์กำกับ

การตรวจสอบระดับแพ็กเกจ

การตรวจสอบความถูกต้องของตัวเชื่อมต่อ

การตรวจสอบไฟล์ประกอบ

พอร์ทัลจะตรวจสอบไฟล์ประกอบ (เอกสารอ้างอิง สคริปต์ และไฟล์อื่นๆ ที่อยู่ร่วมกับ SKILL.md) ในระหว่างการอัปโหลดและการซิงค์

ความเข้ากันได้ข้ามแพลตฟอร์ม

ทักษะใช้มาตรฐานเปิดของทักษะเอเจนต์ ไฟล์เดียวกัน SKILL.md ใช้ได้กับเครื่องมือ AI หลายตัว:

หากคุณกําลังพัฒนาทักษะสําหรับทั้ง Claude Code และ Copilot Cowork ให้เขียนปลั๊กอินด้วย wiqd จากนั้น เรียกใช้ wiqd plugin export --format claude-plugin เพื่อสร้างเค้าโครง Claude Code หากคุณต้องการเริ่มต้นจากโครงสร้างปลั๊กอินโค้ด Claude ซึ่งครอบคลุมมากกว่า เค้าโครงคือ:

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 App Store โดยใช้ 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 และใช้เพื่อตัดสินใจว่าการเรียกใช้เครื่องมือต้องการการยืนยันจากผู้ใช้หรือไม่ และควรแสดงป้ายชื่อใดในพร้อมท์

เขตข้อมูลที่พร้อมใช้งาน

กฎการยืนยัน

จําเป็นต้องมีการยืนยันถ้า 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 โดยไม่คำนึงถึงคำอธิบายประกอบ
• สำหรับเซิร์ฟเวอร์ MCP ที่ไม่ใช่ของ Microsoft การยืนยันที่ขับเคลื่อนด้วยแอนโนเทชันกำลังทยอยเปิดตัว การตั้งค่าคำแนะนำในตอนนี้รองรับความเข้ากันได้ในอนาคต และพร้อมท์ยืนยันจะแสดงขึ้นเมื่อการเผยแพร่ขยายวงกว้างขึ้น โดยนักพัฒนาไม่ต้องแก้ไขใดๆ

ยอมรับไฟล์จากพื้นที่ทํางานของ Cowork

เครื่องมือตัวเชื่อมต่อสามารถรับไฟล์จากเซสชัน Cowork ของผู้ใช้เป็นข้อมูลป้อนเข้า ได้แก่ เอกสารที่ผู้ใช้แนบ ไฟล์แนบอีเมลที่ Cowork บันทึกไว้ หรือไฟล์ที่ขั้นตอนก่อนหน้าสร้างขึ้น ประกาศพารามิเตอร์ด้วยคําสําคัญ contentEncoding: base64 JSON Schema มาตรฐานและ Cowork จัดการส่วนที่เหลือ ไม่จําเป็นต้องใช้ส่วนขยาย Schema เฉพาะสําหรับ Microsoft และพื้นผิว API ของเซิร์ฟเวอร์ของคุณจะไม่เปลี่ยนแปลง

Cowork ประมวลผลไฟล์พื้นที่ทำงานและเข้ารหัสเป็น Base64 ก่อนที่จะเรียกใช้เซิร์ฟเวอร์ของคุณ ดังนั้นไบต์ของไฟล์จะไม่เข้าสู่บริบทของเอเจนต์ เอเจนต์จะเห็นและส่งออกเฉพาะพาธไฟล์ของพื้นที่ทำงานเท่านั้น

ประกาศพารามิเตอร์ไฟล์

คุณสมบัติสตริงที่มี 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 จะกระจายไฟล์ที่แก้ไขแล้วกลับไปเป็นชื่อพารามิเตอร์เดิมของคุณตามลำดับการประกาศ

พารามิเตอร์ไฟล์แบบซ้อนกัน

เอเจนต์รองรับพารามิเตอร์ไฟล์ที่ซ้อนกันภายในอ็อบเจ็กต์หรืออาร์เรย์ของอ็อบเจ็กต์ เอเจนต์จัดการพารามิเตอร์นี้แตกต่างกัน: แทนที่จะยุบมัน เอเจนต์จะเขียนมันใหม่ ณ ตำแหน่งเดิม ให้เป็นสตริงพาธที่ตำแหน่งของมันเอง แนวทางนี้คงความเชื่อมโยงระหว่างไฟล์กับเขตข้อมูลอื่นที่อยู่ในระดับเดียวกันไว้ ตัวอย่างเช่น คุณจะได้รับใบเสร็จ 1 ใบต่อค่าใช้จ่ายแต่ละรายการ:

"line_items": {
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "amount": { "type": "number" },
      "receipt": { "type": "string", "contentEncoding": "base64" }
    }
  }
}

เอเจนต์จะเติมพาธพื้นที่ทำงานลงใน line_items[].receipt และ Cowork จะแทนที่แต่ละพาธด้วยเนื้อหา base64 ณ ตำแหน่งเดิมก่อนส่งต่อการเรียก

มีการไล่ตรวจสอบการซ้อนลึกลงไป 4 ระดับใต้ระดับบนสุดของ inputSchema $ref ระบบจะไม่ติดตามพอยน์เตอร์—กำหนดพารามิเตอร์ไฟล์แบบอินไลน์แทนที่จะกำหนดไว้หลัง $ref

สิ่งที่เซิร์ฟเวอร์ของคุณได้รับ

เซิร์ฟเวอร์ของคุณได้รับ tools/call ตามปกติ โดยมีชื่อพารามิเตอร์ดั้งเดิมของคุณที่มีเนื้อหาซึ่งเข้ารหัสแบบ base64:

{
  "method": "tools/call",
  "params": {
    "name": "analyze_contract",
    "arguments": {
      "document": "JVBERi0xLjQKJcfsj6IKNSAwIG9iago8PC9MZW5...",
      "jurisdiction": "US"
    }
  }
}

เซิร์ฟเวอร์ของคุณไม่จําเป็นต้องทราบว่าตัวแทนใช้อินเทอร์เฟซตามเส้นทาง และเครื่องมือที่ไม่ประกาศ contentEncoding: base64 พารามิเตอร์จะไม่ได้รับผลกระทบ

ขีดจํากัด

การเรียกใช้ที่เกินจำนวนไฟล์หรือขีดจำกัดขนาดจะล้มเหลวด้วยข้อผิดพลาดของเครื่องมือและจะไม่เข้าถึงเซิร์ฟเวอร์ของคุณ กำหนดขนาดให้ API และการตั้งค่าการหมดเวลาของคุณโดยคำนึงถึงขีดจำกัด 150 MiB: base64 จะทำให้เพย์โหลดมีขนาดใหญ่ขึ้นประมาณหนึ่งในสามเมื่อเทียบกับขนาดไฟล์ดิบ และเนื้อหาที่เข้ารหัสจะถูกส่งในเนื้อหาคำขอ JSON-RPC

คำแนะนำ

• อธิบายพารามิเตอร์สําหรับผู้อ่านที่เป็นมนุษย์ เอเจนต์ใช้คำอธิบายเพื่อตัดสินใจว่าไฟล์ใดควรอยู่ในพารามิเตอร์ใด ตัวอย่างเช่น "The signed contract PDF to analyze" ทํางานได้ดีกว่า "file".
• ระบุรูปแบบที่คุณยอมรับ ในคําอธิบายพารามิเตอร์ Cowork ส่งต่อทุกอย่างที่ผู้ใช้แนบมา ตรวจสอบชนิดเนื้อหาฝั่งของคุณและส่งกลับข้อผิดพลาดของเครื่องมือที่ชัดเจนหากไม่สามารถใช้งานได้
• ตั้งค่าคำอธิบายประกอบ เครื่องมือที่รับไฟล์และดำเนินการกับไฟล์นั้นมักจะไม่ใช่แบบอ่านอย่างเดียว จึงพร้อมท์ให้ยืนยัน เรียนรู้เพิ่มเติมใน การจัดการคำอธิบายประกอบและการยืนยันของ MCP
• เก็บพารามิเตอร์ไฟล์แบบอินไลน์ พารามิเตอร์ที่อยู่หลัง $ref หรือซ้อนลึกเกินสี่ระดับจะไม่ถูกเขียนซ้ำ เซิร์ฟเวอร์ของคุณจะได้รับสตริงเส้นทางในตำแหน่งที่คาดว่าจะเป็นเนื้อหา
• ประกาศพารามิเตอร์ไฟล์แบบอาร์เรย์ได้สูงสุดหนึ่งรายการต่อเครื่องมือ เมื่อมีสองไฟล์ขึ้นไป Cowork ไม่สามารถบอกได้ว่าไฟล์ใดเป็นของอาร์เรย์ใด และการเรียกใช้ล้มเหลวโดยมีข้อผิดพลาดเกี่ยวกับเครื่องมือ ใช้หนึ่งอาร์เรย์ หรือพารามิเตอร์สเกลาหลายรายการ หรือการผสมของสเกลาและอาร์เรย์เพียงหนึ่งรายการ
• สำหรับเครื่องมือที่มีเฉพาะพารามิเตอร์สเกลาร์ ให้กำหนดจำนวนไฟล์ที่แน่นอน หากเครื่องมือของคุณประกาศเฉพาะพารามิเตอร์ไฟล์แบบค่าเดียวเท่านั้น จำนวนไฟล์ที่เอเจนต์ส่งผ่านต้องตรงกับจำนวนพารามิเตอร์ที่ประกาศไว้ ระบุให้ชัดเจนในคำอธิบายว่าพารามิเตอร์ไฟล์ใดเป็นตัวเลือก เพื่อไม่ให้เอเจนต์ส่งพารามิเตอร์น้อยหรือมากเกินไป

ระบุปริมาณการใช้งานของ Cowork ไปยังเซิร์ฟเวอร์ของคุณ

ถ้าเซิร์ฟเวอร์ MCP ของคุณควบคุมการมองเห็นเครื่องมือตามไคลเอ็นต์ หรือคุณต้องการระบุที่มาของทราฟฟิกที่ได้รับ คุณสามารถจดจำคำขอที่มาจาก Cowork ได้ Cowork นําเสนออัตลักษณ์ซอฟต์แวร์ที่เสถียรบนสองแชนเนล:

ตรงกับคำนำหน้า 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 ทุกรายและทุกการเชื่อมต่อ และไม่เคยมีข้อมูลระบุตัวตนของผู้ใช้อยู่ด้วย ข้อมูลประจำตัวผู้ใช้ยังคงอยู่ในโฟลว์การให้สิทธิ์ที่กำหนดไว้สำหรับการกำหนดค่าการรับรองความถูกต้องของตัวเชื่อมต่อของคุณ

เนื่องจากไม่มีตัวระบุเฉพาะของแต่ละตัวเชื่อมต่อ ขณะนี้คุณจึงไม่สามารถใช้ข้อมูลประจำตัวนี้เพื่อบอกได้ว่าตัวเชื่อมต่อใดเป็นผู้เรียก หรือเพื่อแยกปลั๊กอิน Microsoft ที่เผยแพร่แล้วออกจากเซิร์ฟเวอร์ที่โหลดแบบไซด์โหลดซึ่งชี้ไปยัง URL เดียวกัน หากคุณต้องการแยกความแตกต่างนั้นออกจากกัน ให้บังคับใช้ผ่านการกำหนดค่าสิทธิ์การเข้าถึงของตัวเชื่อมต่อ แทนที่จะใช้ข้อมูลประจำตัวไคลเอนต์

คําถามทั่วไป

ฉันสามารถใช้ทักษะจากแพคเกจ M365 ใน Claude Code ได้หรือไม่?

ใช่ โฟลเดอร์ทักษะประกอบด้วย Agent Skills มาตรฐาน เรียกใช้คำสั่ง wiqd plugin export --format claude-plugin เพื่อสร้างเค้าโครงของ Claude Code หรือคัดลอกโฟลเดอร์ทักษะไปยัง .claude/skills/ ในโครงการ Claude Code ใดก็ได้

ฉันจําเป็นต้องมีตัวเชื่อมต่อระยะไกลหรือไม่

ไม่ แพ็กเกจที่มีเฉพาะทักษะทำงานได้ดีสำหรับเวิร์กโฟลว์ที่อิงพรอมป์ต์ ตัวเชื่อมต่อจำเป็นเฉพาะเมื่อทักษะของคุณต้องใช้ข้อมูลสดจากระบบภายนอก

ทักษะปลั๊กอินแตกต่างจากทักษะในตัวอย่างไร?

ทักษะปลั๊กอินปรากฏขึ้นพร้อมซอร์ส "package" ใน API พวกเขาไม่สามารถเขียนทับทักษะในตัวที่มีชื่อเดียวกันได้ แพคเกจที่ปรับใช้โดยผู้ดูแลระบบแสดงisAdminDeployed: true.

ผู้ดูแลระบบ IT สามารถควบคุมปลั๊กอินที่พร้อมใช้งานได้หรือไม่

ใช่ ใช้การควบคุมการดูแลระบบมาตรฐานของ M365 ได้แก่ รายการอนุญาต/บล็อกในระดับผู้เช่า การปรับใช้ที่ผู้ดูแลระบบจัดการ และนโยบายการปฏิบัติตามข้อกำหนด

จะเกิดอะไรขึ้นหากปลั๊กอินถูกเพิกถอน

ในรอบการซิงค์ถัดไป ทักษะและตัวเชื่อมต่อจากแพคเกจนั้นจะถูกลบออกจากเซสชันของผู้ใช้ การสนทนาที่ใช้งานอยู่จะไม่ถูกขัดจังหวะ แต่เซสชันใหม่จะไม่สามารถใช้ความสามารถของแพ็กเกจได้

จํานวนทักษะสูงสุดต่อแพคเกจคืออะไร

ยี่สิบ (20) ทักษะ (ต่อ ASKILL-M002) สําหรับตัวเชื่อมต่อ ขีดจํากัดคือ 10 ต่อแพคเกจ

ทักษะสามารถอ้างอิงเครื่องมือคอนเน็กเตอร์จากแพคเกจเดียวกันได้หรือไม่?

ใช่ และพวกเขาควรทำเช่นนั้น ตั้งชื่อเครื่องมืออย่างชัดเจนในเวิร์กโฟลว์ SKILL.md ของคุณ (ตัวอย่างเช่น "ใช้เครื่องมือ search_case_law เพื่อ...") เอเจนต์เชื่อมต่อสิ่งเหล่านั้นในขณะทำงาน

เครื่องมือปลั๊กอินของฉันสามารถยอมรับไฟล์จากพื้นที่ทํางานของ Cowork ได้หรือไม่?

ใช่ ประกาศพารามิเตอร์เครื่องมือด้วย contentEncoding: base64 และ Cowork จะแปลงไฟล์พื้นที่ทำงานของผู้ใช้เป็นเนื้อหา Base64 ก่อนที่จะเรียกใช้เซิร์ฟเวอร์ของคุณ โมเดลจะส่งผ่านเส้นทางของไฟล์ ไม่ใช่เนื้อหาไฟล์ ดังนั้นไฟล์ขนาดใหญ่จะไม่ใช้บริบทของโมเดล สําหรับรายละเอียดการประกาศและขีดจํากัด เรียนรู้เพิ่มเติมใน ยอมรับไฟล์จากพื้นที่ทํางานของ Cowork

ฉันจะสร้าง GUID แบบเชิงกําหนดสําหรับแพคเกจของฉันได้อย่างไร

wiqd plugin create สร้างและตรึง ID แอปให้คุณ สคริปต์การแปลงใช้ UUID v5 (ซึ่งอิงตาม SHA-1) โดยใช้ชื่อปลั๊กอินของคุณ ดังนั้นเมื่อรันการแปลงสองครั้ง คุณจะได้ GUID เดิม หากจัดทำแพ็กเกจด้วยตนเอง ให้ใช้เครื่องมือสร้าง GUID ใดก็ได้ ตรวจสอบให้แน่ใจว่ายังคงเสถียรอยู่เสมอในเวอร์ชันต่างๆ

ควรกำหนดเป้าหมายเวอร์ชัน manifest ใด

เป้าหมาย 1.29 ถ้าคุณกำลังสร้างด้วย wiqd ซึ่งปักหมุดให้คุณ ในเวอร์ชัน 1.29 agentConnectors[] รายการจะมีเฉพาะ URL เท่านั้น และ mcpToolDescription เป็นตัวเลือก ตัวอย่างที่เขียนขึ้นเองในบทความนี้ใช้เวอร์ชัน 1.28 ซึ่งจำเป็นต้องมี mcpToolDescription และต้องรวมไฟล์ที่ระบุไว้ใน ZIP ด้วย atk import openplugin ใช้ UUID v5 (ตาม SHA-1) จากชื่อปลั๊กอินของคุณ การนำเข้าซ้ำสองครั้งจะได้ GUID เดียวกัน หากต้องการกำหนดค่าเอง ให้ระบุ --app-id หากจัดทำแพ็กเกจด้วยตนเอง ให้ใช้เครื่องมือสร้าง GUID ใดก็ได้ ตรวจสอบให้แน่ใจว่ายังคงเสถียรอยู่เสมอในเวอร์ชันต่างๆ

ข้อมูลที่เกี่ยวข้อง

• ภาพรวมของ Cowork
• ใช้ Cowork
• จัดการ Cowork สําหรับองค์กรของคุณ
• จัดการปลั๊กอินสําหรับ Cowork
• การอ้างอิง CLI ของปลั๊กอิน wiqd