智能体通过 Chorus 的 MCP（Model Context Protocol）工具对 Chorus 进行操作。本页是这套工具 的分类指南：客户端如何连接、项目范围过滤如何工作、每个工具如何变为可见，以及智能体在各 阶段使用的高频工具。关于实体经历的各个状态以及各阶段如何交接，参阅 [生命周期参考](/zh/reference/lifecycle/)；关于评论、@提及与通知，参阅 [协作参考](/zh/reference/collaboration/)。 ## 端点与传输 Chorus 通过 **Streamable HTTP** 暴露单一的 MCP 端点： ```text POST https://chorus.example.com/api/mcp Authorization: Bearer cho_REDACTED ``` 该端点是**无状态的**。每个请求都用智能体密钥进行鉴权，并由一个全新的、每请求独立的服务器 实例处理，不存在服务器端会话，没有 `initialize` → 保活 → 过期的流程，也没有闲置超时。客户端 无需恢复任何“会话未找到”的状态；它只需在每个请求上带上密钥即可。由此有两个结论： - **权限按请求重新计算。** 在 UI 中修改某个智能体的权限，会在下一次调用时立即生效，无需重新 连接。 - **仅凭智能体密钥即决定工具列表。** `tools/list` 返回的工具集，是根据该密钥在本次请求时的有效权限 得出的。 在客户端的 MCP 配置中，将其配置为一个 `http` 类型的服务器。一个最小的 `.mcp.json` 配置块： ```json { "mcpServers": { "chorus": { "type": "http", "url": "https://chorus.example.com/api/mcp", "headers": { "Authorization": "Bearer cho_REDACTED" } } } } ``` 在 shell 中，`chorus mcp call ` 命令可用同一份智能体凭据调用上述任意工具，适合脚本与一次性调用，且无需消耗模型 token。参见 [chorus 命令行工具](/zh/reference/cli/)。 :::note MCP 传输会话与 Chorus 的**智能体会话**无关。智能体会话用于追踪蜂群模式下的子智能体，让你能看到它们的工作， 通过下文的会话工具创建与管理。 ::: ## 按项目过滤范围 跨多个项目工作的智能体，可以在 MCP 连接上发送范围请求头，把结果限定在 某些项目内：
| 请求头 | 值 | 效果 | | --- | --- | --- | | `X-Chorus-Project` | 单个项目 UUID，或多个以逗号分隔 | 将结果限制在这些项目内。 | | `X-Chorus-Project-Group` | 项目组 UUID | 将结果限制在该组内的所有项目。 |
不带任何请求头时，结果覆盖所有项目（默认行为）。当**两个**请求头同时出现时， `X-Chorus-Project-Group` 优先生效。只有 `chorus_get_my_assignments` 遵循这些请求头，它返回按项目分组、 限定在所选项目内的追踪器。`chorus_checkin` 的 `ideaTracker` **不**受请求头过滤，它始终返回该 智能体跨所有项目最近更新的想法（上限十条）。其他所有工具接受显式的 `projectUuid` 参数，不受请求头过滤。 ```json { "mcpServers": { "chorus": { "type": "http", "url": "https://chorus.example.com/api/mcp", "headers": { "Authorization": "Bearer cho_REDACTED", "X-Chorus-Project": "uuid-a,uuid-b" } } } } ``` ## 权限与工具可见性 工具可见性由一套细粒度的权限模型驱动：**5 类资源** （`idea`、`proposal`、`document`、`task`、`project`）× **3 种动作** （`read`、`write`、`admin`）= **15 个权限位**。每个受门控的工具声明**恰好一个**所需权限。 只有当智能体的有效权限集合包含该权限位时，受门控的工具才会出现在其 `tools/list` 中。 **公共工具没有任何门控，始终出现。** 智能体的有效集合是**角色预设**与在其之上叠加的任意**自定义权限**的并集：
| 预设 | 有效权限集合 | | --- | --- | | `developer_agent` | `*:read` + `task:write`（6 个位） | | `pm_agent` | `*:read` + `idea:write`、`proposal:write`、`document:write`、`task:write`、`project:write`（10 个位） | | `admin_agent` | 全部 15 个位（`*:read` + `*:write` + `*:admin`） |
可见不等于有权操作。一个工具可能可见，却仍在执行时拒绝某项操作，例如任务的执行状态 转换要求调用者是该任务的负责人，与谁能看到这个工具无关。 ## 项目访问权限 权限位决定智能体拥有哪些工具，**项目访问权限**决定它能在哪里使用这些工具。智能体以其所有者对每个 项目的访问权限行事（参阅[控制谁能看到项目](/zh/guides/project-access/)）；没有所有者的智能体只能 使用公开项目。每次调用都会同时执行这两项检查。 - **隐藏即不存在**。所有者无权访问的私有项目，以及其中的每个想法、提案、文档、任务和评论，都不会 出现在列表和搜索结果中，并且返回的“未找到”错误与查询不存在的 ID 时完全相同。 - **角色过低即禁止**。当所有者的角色过低时（例如查看者执行写操作，或编辑者在私有项目中执行仅限管理员的操作）， 调用会以禁止访问错误失败；读操作仍然可用。在所有者的角色改变之前，重试也无济于事。 - `chorus_get_project` 会报告项目的 `visibility` 以及调用者的 `accessLevel` （`viewer`、`editor` 或 `admin`）。 - `chorus_admin_create_project` 和 `chorus_admin_create_project_group` 接受 `visibility` （`public` 或 `private`）。所有者会成为所创建对象的管理员。在私有项目组中创建的项目是私有的。 - `chorus_admin_update_project_group` 可以更改项目组的 `visibility`，并一次管理一位显式项目组成员 （`memberAction`：`add`、`update` 或 `remove`，配合 `userUuid` 和 `role`）。 `chorus_admin_move_project_to_group` 用于移动项目或将其移出分组。更改项目组的 `visibility` 或移动项目时， 请先以 `preview: true` 调用该工具，获取访问权限变化和一个 `confirmationToken`，再携带该令牌重复同样 的更改。成员变更会直接生效，无需预览。 - 更改项目组的可见性或成员，要求所有者是项目组管理员。移动私有项目、移入或移出私有项目组，或会扩大任何人 访问权限的移动，需要管理员角色；其他移动需要编辑者角色。 - `chorus_search_mentionables` 接受可选的 `entityType` 和 `entityUuid`。从想法、提案、文档或任务中 发起提及时传入它们，就只会推荐能看到该实体的人。 - 项目成员以及已有项目的可见性在 Web 界面中管理；没有对应的 MCP 工具。 ## 工具类别
| 类别 | 门控 | 涵盖内容 | | --- | --- | --- | | **公共（Public）** | 无，始终可见 | 发现与读取（`chorus_get_*`、`chorus_list_*`、`chorus_search*`）、`chorus_checkin`、`chorus_get_my_assignments`、评论、细化回答、通知，以及 `chorus_create_tasks` 和 `chorus_update_task`。 | | **会话（Session）** | 无，始终可见 | 面向蜂群模式子智能体的智能体会话生命周期：`chorus_create_session`、`chorus_session_checkin_task` / `chorus_session_checkout_task`、`chorus_session_heartbeat`、`chorus_close_session`、`chorus_reopen_session`、`chorus_list_sessions`、`chorus_get_session`。 | | **开发者（Developer）** | `task:write` | 认领、释放、汇报任务，并提交任务以供验证。 | | **PM** | `idea:write`、`proposal:write`、`document:write`、`project:write` | 编写并推进想法、细化、提案、文档与引用。 | | **管理员（Admin）** | `*:admin`（项目/项目组的创建为 `project:write`） | 批准提案，验证/重开/关闭任务，标记验收标准，删除实体，管理项目与项目组。 |
:::caution `chorus_create_report` 看起来像公共工具（它没有 `pm_` 前缀）， 但它**受 `document:write` 门控**。只有持有该权限位的智能体才会看到它（`pm_agent` / `admin_agent` 预设，或添加了 `document:write` 自定义权限的开发者智能体）。不要把它当作 未门控的公共工具。 ::: `chorus_create_tasks` 与 `chorus_update_task` 是真正的公共工具：任何智能体都可以编辑任务的字段、 依赖与验收标准，但只有任务负责人才能把任务转为 `in_progress` 或 `to_verify`。 ## 高频工具 以下是具有代表性的一部分工具，附带输入、返回结构与所需权限。每个工具的完整契约，参见本页末尾的 说明。 ### chorus_checkin（公共） 建议在一次运行开始时调用。返回智能体的身份与所有者、其有效权限集合、按项目分组的想法追踪器， 以及通知摘要。`ideaTracker` 上限为最近更新的十条想法且跨所有项目，它**不**受上文过滤请求头 限制（如需被限定范围且无上限的追踪器，请用 `chorus_get_my_assignments`）。 ```text 输入：（无） 返回：{ agent: { uuid, name, permissions, owner }, ideaTracker: { : { name, ideas[] } }, notifications: { unread, recent[] } } ``` ### chorus_get_my_assignments（公共） 智能体完整的想法/任务追踪器，按项目分组。结构与 `chorus_checkin` 的 `ideaTracker` 相同，但 没有近期想法的数量上限，并额外带有一个关于未完成任务的 `taskTracker`。遵循过滤请求头。 ```text 输入：（无） 返回：{ ideaTracker: { : { name, ideas[] } }, taskTracker: { : { name, tasks[] } } } ``` ### chorus_claim_task（`task:write`） 认领一个 open 状态的任务，将其转为 `assigned` 并将调用者设为负责人。 ```text 输入：{ taskUuid } 返回：更新后的 Task ``` ### chorus_submit_for_verify（`task:write`，仅负责人） 提交任务以供人工验证，将其从 `in_progress` 转为 `to_verify`。 ```text 输入：{ taskUuid, summary? } 返回：更新后的 Task ``` ### chorus_pm_create_proposal（`proposal:write`） 创建一个**空的**提案容器，随后用 `chorus_pm_add_document_draft` 与 `chorus_pm_add_task_draft` 向其填充内容。当 `inputType` 为 `idea` 时，每个输入想法都必须是可交付项，主题（容器）想法会 被拒绝；请派生一个子想法并在其上创建提案。 ```text 输入：{ projectUuid, title, description?, inputType: "idea" | "document", inputUuids[], references?[] } 返回：创建的 Proposal（status: draft） ``` ### chorus_pm_add_task_draft（`proposal:write`） 向草稿提案追加一个任务草稿。验收标准是必需的，至少要有一个 description 非空的条目，否则调用 被拒绝。 ```text 输入：{ proposalUuid, title, description?, priority?, storyPoints?, acceptanceCriteriaItems: [{ description, required? }], // 必需，非空 dependsOnDraftUuids?[] } 返回：更新后的 Proposal ``` ### chorus_admin_verify_task（`task:admin`） 验证一个已提交的任务，将其从 `to_verify` 转为 `done`。若任务带有结构化验收标准，则所有**必需** 标准必须已被标记为 `passed`（通过 `chorus_mark_acceptance_criteria`），否则验证被阻止。 ```text 输入：{ taskUuid } 返回：更新后的 Task（当验收标准门控阻止时返回错误） ``` ## 受门控工具 → 所需权限矩阵 每个受权限门控的工具及其单一所需权限位。持有该权限位（通过预设或自定义权限）是该工具出现的 必要条件；工具执行时仍可能校验所有权、负责人或状态。
| 所需权限 | 工具 | | --- | --- | | `idea:write` | `chorus_claim_idea`、`chorus_release_idea`、`chorus_move_idea`、`chorus_pm_create_idea`、`chorus_edit_idea`、`chorus_pm_start_elaboration`、`chorus_pm_skip_elaboration` | | `idea:admin` | `chorus_pm_validate_elaboration`、`chorus_admin_delete_idea` | | `proposal:write` | `chorus_pm_create_proposal`、`chorus_pm_validate_proposal`、`chorus_pm_submit_proposal`、`chorus_pm_add_document_draft`、`chorus_pm_add_task_draft`、`chorus_pm_update_document_draft`、`chorus_pm_update_task_draft`、`chorus_pm_remove_document_draft`、`chorus_pm_remove_task_draft`、`chorus_pm_reject_proposal`、`chorus_pm_revoke_proposal`、`chorus_pm_assign_task` | | `proposal:admin` | `chorus_admin_approve_proposal`、`chorus_admin_close_proposal` | | `document:write` | `chorus_pm_create_document`、`chorus_pm_update_document`、`chorus_create_report`、`chorus_add_reference`、`chorus_update_reference`、`chorus_remove_reference` | | `document:admin` | `chorus_admin_delete_document` | | `task:write` | `chorus_claim_task`、`chorus_release_task`、`chorus_submit_for_verify`、`chorus_report_criteria_self_check`、`chorus_report_work` | | `task:admin` | `chorus_admin_verify_task`、`chorus_admin_reopen_task`、`chorus_admin_close_task`、`chorus_mark_acceptance_criteria`、`chorus_admin_delete_task` | | `project:write` | `chorus_admin_create_project`、`chorus_admin_create_project_group`、`chorus_admin_update_project_group`、`chorus_admin_delete_project_group`、`chorus_admin_move_project_to_group` |
:::note **权威、完整**的工具列表，是运行中服务器自身的 `tools/list` 响应（每个工具的实时自描述）。 本页是对这套工具的分类指南，而非对每个工具逐字节的转录。当某个自描述与本页不一致时，以服务器为准。 :::