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. 发现 Space

当用户询问有哪些可用的 space，或你需要找到合适的 space 时：

Call mcp__github__list_copilot_spaces

这会返回用户可访问的所有 space，每个都带有 name 和 owner_login。向用户展示相关匹配项。

要筛选特定用户的 space，请将 owner_login 与用户名匹配（例如 "show me my spaces"）。

2. 加载 Space

当用户指定某个 space，或你已确定合适的 space 时：

Call mcp__github__get_copilot_space with:
  owner: "org-or-user"    (the owner_login from the list)
  name: "Space Name"      (exact space name, case-sensitive)

这会返回该 space 的完整内容：附加的文档、代码上下文、自定义指令以及任何其他精心整理的材料。使用此上下文为你的回答提供依据。

3. 顺藤摸瓜

Space 内容通常会引用外部资源：GitHub issue、仪表板、仓库、讨论或其他工具。主动使用其他 MCP 工具获取这些资源，以收集完整上下文。例如：

• 某个 space 引用了某个计划的跟踪 issue。使用 issue_read 获取最新评论。
• 某个 space 链接到项目看板。使用项目工具检查当前状态。
• 某个 space 提到某个仓库的总体规划。使用 get_file_contents 阅读它。

4. 回答或执行

加载后，根据 space 包含的内容来使用它：

如果 space 包含参考资料（文档、代码、标准）：

• 回答有关项目架构、模式或标准的问题
• 生成遵循团队约定的代码
• 利用项目专属知识调试问题

如果 space 包含工作流指令（模板、分步流程）：

• 按定义逐步遵循工作流
• 从工作流指定的来源收集数据
• 按工作流定义的格式生成输出
• 在每个步骤后展示进度，以便用户进行引导

5. 管理 Space（通过 gh api）

当用户想要创建、更新或删除 space 时，使用 gh api。首先，从列表端点中找到 space 编号。

更新 space 的指令：

gh api users/{username}/copilot-spaces/{number} \
  -X PUT \
  -f general_instructions="New instructions here"

同时更新名称、描述或指令：

gh api users/{username}/copilot-spaces/{number} \
  -X PUT \
  -f name="Updated Name" \
  -f description="Updated description" \
  -f general_instructions="Updated instructions"

创建新 space：

gh api users/{username}/copilot-spaces \
  -X POST \
  -f name="My New Space" \
  -f general_instructions="Help me with..." \
  -f visibility="private"

附加资源（替换整个资源列表）：

{
  "resources_attributes": [
    { "resource_type": "free_text", "metadata": { "name": "Notes", "text": "Content here" } },
    { "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：用户想要查找 Space

用户："我们团队可以使用哪些 copilot space？"

操作：

1. 调用 mcp__github__list_copilot_spaces
2. 筛选/展示与用户组织或兴趣相关的 space
3. 主动提出加载他们感兴趣的任何 space

示例 3：基于上下文的问题

用户："使用 security space，我们关于密钥扫描的策略是什么？"

操作：

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 的工作流：从附加的 initiative 议题中提取数据，收集指标，逐节起草内容。
3. 使用其他 MCP 工具获取该 space 引用的外部资源（跟踪议题、仪表盘）。
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="updated 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 }。