copilot-spaces

Copilot Spaces

使用 Copilot Spaces 将精选的项目特定上下文引入对话。Space 是一个共享的仓库、文件、文档和指令集合，使 Copilot 的响应基于团队的实际代码和知识。

可用工具

MCP 工具（只读）

工具	用途
mcp__github__list_copilot_spaces	列出当前用户可访问的所有空间
mcp__github__get_copilot_space	按所有者和名称加载空间的完整上下文

通过 gh api 的 REST API（完整 CRUD）

Spaces REST API 支持创建、更新、删除空间以及管理协作者。MCP 服务器仅暴露读操作，因此写操作请使用 gh api。

用户空间：

方法	端点	用途
POST	/users/{username}/copilot-spaces	创建空间
GET	/users/{username}/copilot-spaces	列出空间
GET	/users/{username}/copilot-spaces/{number}	获取空间
PUT	/users/{username}/copilot-spaces/{number}	更新空间
DELETE	/users/{username}/copilot-spaces/{number}	删除空间

组织空间： 相同模式，路径为 /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”
• 用户希望答案基于特定项目文档、代码或标准
• 用户询问“有哪些可用的 spaces？”或“为 X 找一个 space”
• 用户需要入职上下文、架构文档或团队特定指导
• 用户希望遵循 Space 中定义的结构化工作流（模板、检查清单、多步骤流程）

工作流

1. 发现 Spaces

当用户询问有哪些可用的 spaces，或者你需要找到正确的 space 时：

调用 mcp__github__list_copilot_spaces

这将返回用户可访问的所有 spaces，每个 space 包含 name 和 owner_login。向用户展示相关匹配项。

要筛选特定用户的 spaces，将 owner_login 与用户名匹配（例如，“显示我的 spaces”）。

2. 加载 Space

当用户指定了某个 space，或者你已确定正确的 space 时：

调用 mcp__github__get_copilot_space，参数为：
  owner: "组织或用户"    （列表中的 owner_login）
  name: "Space 名称"      （精确的 space 名称，区分大小写）

这将返回 space 的完整内容：附带的文档、代码上下文、自定义指令以及其他精选材料。使用此上下文来指导你的回答。

3. 追踪线索

Space 内容通常引用外部资源：GitHub Issue、仪表板、仓库、讨论或其他工具。主动使用其他 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. 筛选/展示与用户组织或兴趣相关的 spaces
3. 提供加载任何感兴趣 space 的选项

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

用户：“使用安全 space，我们对秘密扫描的政策是什么？”

操作：

1. 调用 mcp__github__get_copilot_space，使用适当的所有者和名称
2. 在 space 内容中找到相关策略
3. 基于实际内部文档回答

示例 4：Space 作为工作流引擎

用户：“使用 PM Weekly Updates space 写我的周报”

操作：

1. 调用 mcp__github__get_copilot_space 加载 space。它包含模板格式和逐步指令。
2. 遵循 space 的工作流：从关联的 initiative 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 中的确切名称。
• Spaces 可以由用户或组织拥有。始终提供 owner 和 name。
• Space 内容可能很大（20KB+）。如果作为临时文件返回，使用 grep 或 view_range 查找相关部分，而不是一次性读取所有内容。
• 如果找不到 space，建议列出可用的 spaces 以找到正确的名称。
• Spaces 会随着底层仓库的变化自动更新，因此上下文始终是最新的。
• 某些 spaces 包含自定义指令，这些指令应指导你的行为（编码标准、首选模式、工作流）。将其视为指令而非建议。
• 写操作（使用 gh api 创建/更新/删除）需要 user PAT 作用域。如果在写操作时收到 404，请运行 gh auth refresh -h github.com -s user。
• 资源更新替换整个数组。要添加资源，请包含所有现有资源以及新资源。要移除资源，请在数组中包含 { "id": 123, "_destroy": true }。