copilot-spaces

Copilot Spaces

使用 Copilot Spaces 將精選的專案特定上下文帶入對話中。Space 是一個共享的儲存庫、檔案、文件和指示集合，讓 Copilot 的回應基於團隊實際的程式碼和知識。

可用工具

MCP 工具（唯讀）

工具	用途
mcp__github__list_copilot_spaces	列出目前使用者可存取的所有 space
mcp__github__get_copilot_space	根據擁有者和名稱載入 space 的完整上下文

透過 gh api 的 REST API（完整 CRUD）

Spaces REST API 支援建立、更新、刪除 space 以及管理協作者。MCP 伺服器僅暴露讀取操作，因此寫入操作請使用 gh api。

使用者 Space：

方法	端點	用途
POST	/users/{username}/copilot-spaces	建立 space
GET	/users/{username}/copilot-spaces	列出 space
GET	/users/{username}/copilot-spaces/{number}	取得 space
PUT	/users/{username}/copilot-spaces/{number}	更新 space
DELETE	/users/{username}/copilot-spaces/{number}	刪除 space

組織 Space： 相同模式，路徑為 /orgs/{org}/copilot-spaces/...

協作者： 在 .../collaborators 端點新增、列出、更新和移除協作者

權限範圍要求： PAT 需要 read:user 進行讀取，user 進行寫入。使用 gh auth refresh -h github.com -s user 新增。

注意： 此 API 已可使用，但尚未納入公開 REST API 文件。可能需要 copilot_spaces_api 功能旗標。

何時使用 Spaces

• 使用者提到「Copilot space」或要求「載入 space」
• 使用者希望答案基於特定專案文件、程式碼或標準
• 使用者問「有哪些 space 可用？」或「找一個關於 X 的 space」
• 使用者需要入門上下文、架構文件或團隊特定的指引
• 使用者想要遵循 Space 中定義的結構化工作流程（範本、檢查清單、多步驟流程）

工作流程

1. 探索 Spaces

當使用者詢問有哪些 space 可用，或你需要找到正確的 space 時：

呼叫 mcp__github__list_copilot_spaces

這會回傳使用者可存取的所有 space，每個 space 包含 name 和 owner_login。向使用者呈現相關的匹配項目。

若要篩選特定使用者的 space，請比對 owner_login 與使用者名稱（例如「顯示我的 space」）。

2. 載入 Space

當使用者指定某個 space，或你已識別出正確的 space 時：

呼叫 mcp__github__get_copilot_space，參數為：
  owner: "org-or-user"    （來自清單的 owner_login）
  name: "Space Name"      （確切的 space 名稱，區分大小寫）

這會回傳 space 的完整內容：附加的文件、程式碼上下文、自訂指示以及其他精選資料。使用這些上下文來形成你的回應。

3. 跟隨線索

Space 內容通常會參考外部資源：GitHub issues、儀表板、儲存庫、討論區或其他工具。主動使用其他 MCP 工具擷取這些資源，以取得完整的上下文。例如：

• Space 參考了一個追蹤議題的 issue。使用 issue_read 取得最新留言。
• Space 連結到一個專案看板。使用專案工具檢查目前狀態。
• Space 提到某個儲存庫的主計畫。使用 get_file_contents 讀取它。

4. 回答或執行

載入後，根據 space 內容的類型來使用：

如果 space 包含參考資料（文件、程式碼、標準）：

• 回答關於專案架構、模式或標準的問題
• 產生遵循團隊慣例的程式碼
• 使用專案特定知識除錯

如果 space 包含工作流程指示（範本、逐步流程）：

• 按照定義的工作流程逐步執行
• 從工作流程指定的來源收集資料
• 以工作流程定義的格式產出結果
• 在每個步驟後顯示進度，讓使用者可以引導方向

5. 管理 Spaces（透過 gh api）

當使用者想要建立、更新或刪除 space 時，使用 gh api。首先，從列表端點找到 space 編號。

更新 space 的指示：

gh api users/{username}/copilot-spaces/{number} \
  -X PUT \
  -f general_instructions="新的指示"

同時更新名稱、描述或指示：

gh api users/{username}/copilot-spaces/{number} \
  -X PUT \
  -f name="更新後的名稱" \
  -f description="更新後的描述" \
  -f general_instructions="更新後的指示"

建立新的 space：

gh api users/{username}/copilot-spaces \
  -X POST \
  -f name="我的新 Space" \
  -f general_instructions="幫我處理..." \
  -f visibility="private"

附加資源（會取代整個資源列表）：

{
  "resources_attributes": [
    { "resource_type": "free_text", "metadata": { "name": "筆記", "text": "這裡的內容" } },
    { "resource_type": "github_issue", "metadata": { "repository_id": 12345, "number": 42 } },
    { "resource_type": "github_file", "metadata": { "repository_id": 12345, "file_path": "docs/guide.md" } }
  ]
}

刪除 space：

gh api users/{username}/copilot-spaces/{number} -X DELETE

可更新的欄位： name、description、general_instructions、icon_type、icon_color、visibility（"private"/"public"）、base_role（"no_access"/"reader"）、resources_attributes

範例

範例 1：使用者要求載入 Space

使用者：「載入 Accessibility copilot space」

動作：

1. 呼叫 mcp__github__get_copilot_space，參數 owner 為 "github"，name 為 "Accessibility"
2. 使用回傳的上下文回答關於無障礙標準、MAS 等級、合規流程等問題

範例 2：使用者想要尋找 Spaces

使用者：「我們團隊有哪些 copilot spaces 可用？」

動作：

1. 呼叫 mcp__github__list_copilot_spaces
2. 篩選/呈現與使用者組織或興趣相關的 space
3. 提議載入他們感興趣的任何 space

範例 3：基於上下文的問題

使用者：「使用 security space，我們對 secret scanning 的政策是什麼？」

動作：

1. 使用適當的 owner 和 name 呼叫 mcp__github__get_copilot_space
2. 在 space 內容中找到相關政策
3. 根據實際的內部文件回答

範例 4：Space 作為工作流程引擎

使用者：「使用 PM Weekly Updates space 寫我的每週更新」

動作：

1. 呼叫 mcp__github__get_copilot_space 載入 space。它包含範本格式和逐步指示。
2. 遵循 space 的工作流程：從附加的追蹤 issue 拉取資料、收集指標、草擬每個章節。
3. 使用其他 MCP 工具擷取 space 參考的外部資源（追蹤 issue、儀表板）。
4. 在每個章節後顯示草稿，讓使用者審閱並補足缺口。
5. 以 space 定義的格式產出最終結果。

範例 5：以程式方式更新 Space 指示

使用者：「更新我的 PM Weekly Updates space，加入新的寫作指南」

動作：

1. 呼叫 mcp__github__list_copilot_spaces 並找到 space 編號（例如 19）。
2. 呼叫 mcp__github__get_copilot_space 讀取目前的指示。
3. 根據要求修改指示文字。
4. 推送更新：

gh api users/labudis/copilot-spaces/19 -X PUT -f general_instructions="更新後的指示..."

提示

• Space 名稱區分大小寫。請使用 list_copilot_spaces 回傳的確切名稱。
• Space 可由使用者或組織擁有。務必同時提供 owner 和 name。
• Space 內容可能很大（20KB 以上）。如果回傳為暫存檔，請使用 grep 或 view_range 尋找相關區段，而非一次讀取全部。
• 如果找不到 space，建議列出可用的 space 以找到正確名稱。
• Space 會隨著底層儲存庫的變更自動更新，因此上下文永遠是最新的。
• 某些 space 包含自訂指示，應引導你的行為（編碼標準、偏好的模式、工作流程）。請將這些視為指令，而非建議。
• 寫入操作（用於建立/更新/刪除的 gh api）需要 user PAT 範圍。如果寫入操作收到 404，請執行 gh auth refresh -h github.com -s user。
• 資源更新會取代整個陣列。若要新增資源，請包含所有現有資源加上新資源。若要移除資源，請在陣列中加入 { "id": 123, "_destroy": true }。