CAPA子代理隔离:如何防止研究型Agent继承git push等危险工具
CAPA子代理隔离:如何防止研究型Agent继承git push等危险工具
CAPA 是一个面向 AI 编码代理(Cursor、Claude Code、Codex、Windsurf、GitHub Copilot 等 30+ 工具)的能力管理器与 MCP 网关,用一个 capabilities.yaml 统一管理 skills、tools、rules、sub-agents 和 MCP servers。本文讲 CAPA 的子代理隔离(Sub-agent Isolation)机制:让研究型 Agent 只能调用白名单内的只读工具,从网关层面彻底杜绝它继承 git push、删除云端资源等危险工具的可能。
为什么研究型 Agent 不能拥有 git push?
多 Agent 协作很常见:一个主 Agent 负责开发与提交,若干子 Agent 各司其职,比如"研究型 Agent"只做资料检索、代码阅读和调研。
问题在于工具继承。如果所有 Agent 都连接同一个 MCP 网关,那么任何子 Agent 都能看到并调用项目里声明的全部工具——包括 shell 这类能执行 git push、rm、云端 API 调用的命令工具。一个本该"只读"的研究型 Agent,一旦跑偏或被注入恶意指令,就拥有和你主 Agent 一样的破坏能力。
CAPA 的解法是:给每个子代理一个经过过滤的独立 MCP 端点,只暴露 capabilities.yaml 中显式声明给它的工具,其余调用直接拒绝。这就是"最小权限"在 Agent 工具链上的落地。
CAPA 子代理隔离原理:每个 sub-agent 一个过滤端点
CAPA 作为本地 MCP 网关运行时,每个项目有主端点,每个子代理另有专属端点:
- 主 Agent 端点:
/{projectId}/mcp—— 暴露项目全部工具 - 子 Agent 端点:
/{projectId}/agents/{agentId}/mcp—— 只暴露该子代理tools列表中的工具
路由定义见 mcp-http-routes.ts,端点路径格式一目了然。
子代理的工具白名单解析逻辑在 mcp-handler.ts 的 getAgentAllowedToolIds 中:它读取 capabilities.subagents 里对应条目,把 tools 字段引用的每个工具解析为完整工具名,构成一个"允许集合"。不在集合中的工具,既不会出现在 tools/list 返回里,调用时也会被拒绝——双重保险。
四行配置完成子代理隔离:capabilities.yaml 的 subagents
在 capabilities.yaml 中声明 subagents,隔离即刻生效。以"研究型 Agent"为例:
subagents:
- id: researcher
description: 研究型 Agent。仅做资料检索与代码阅读,不做任何写操作。
skills:
- web-research
tools:
- brave.search # 只读搜索工具
- docs.query # 只读文档查询工具
instructions: |
你只做调研。禁止执行 shell 命令、禁止 git 写操作。
关键字段说明(完整字段定义见 capabilities.ts):
| 字段 | 说明 |
|---|---|
id |
唯一标识,同时用作 MCP 注册名 capa-{id} 和代理文件名 |
description |
角色描述;Cursor 会依据它自动判断何时委派任务 |
skills |
引用的 skill ID,来自顶层 skills 数组 |
tools |
白名单核心:只允许子代理调用这些工具 |
providers |
可选,限定该子代理生效的提供方(如 [claude-code, cursor]) |
instructions |
追加到代理文件正文的角色约束 |
tools 支持三种等价写法:裸 ID(search_cdk_docs)、server.tool 限定名(aws-iac.validate_cfn)、@server.tool 形式,任选易读的一种。详细字段与校验规则见 capabilities-schema.md。
capa install 如何自动完成子代理隔离接线
执行 capa install 后,安装管线中的 install-subagents 任务(install-subagents.ts)自动完成三件事:
- 注册过滤端点:为每个子代理生成端点 URL
http://localhost:5912/{projectId}/agents/{id}/mcp,并写入提供方 MCP 配置(Claude Code 写入.mcp.json的capa-{id}条目,注册逻辑见 mcp-client-manager.ts)。 - 写代理定义文件:生成
.claude/agents/{id}.md(Claude Code)或.cursor/agents/{id}.md(Cursor),把 skills 和 instructions 渲染进去。 - 清理旧条目:从配置中移除的子代理会被自动反注册,其 MCP 条目和代理文件一并删除,不会出现"幽灵权限"。
不同提供方对子代理 MCP 的建模不同(如 Cursor 采用按文件委派而非独立条目),差异细节见 mcp-client-manager.ts 中的 supportsSubAgentEntries 判断。
运行时拦截:一次越权调用如何被拒绝
隔离不是靠提示词"求"Agent 守规矩,而是网关层的硬拦截。当子代理端点收到调用时,mcp-handler.ts 先校验工具名是否在白名单中,未通过则直接返回:
Tool "git_push" is not available on this sub-agent endpoint (researcher). Use the main capa endpoint to access all tools.
同时该次越权尝试会被 ToolCallTracer 记入活动日志——在 Web UI 的项目活动流中能看到这是一次被拒绝的调用,便于审计。即使子代理"知道"主端点 URL,它配置的也只是自己的 capa-{id} 端点,正常委派链路里根本触达不到全量工具。
子代理最小权限配置三原则
- 白名单从最小开始:研究型 Agent 先只给搜索、查询类工具;确认需要再逐个加,而不是一开始给一堆。
- 危险工具绝不进
tools:shell、git push、资源创建/删除类工具只留给主 Agent 或专门的部署 Agent。 - 用
providers收窄范围:某子代理只在特定提供方运行就显式声明,避免在不需要的工具里注册出多余端点。
另外 capa install 会在安装时校验引用:subagents 里写错工具 ID 会立即告警,不会静默漏配出"看起来有、实际没有"的白名单。
小结
CAPA 的子代理隔离把"权限控制"从提示词层面下沉到 MCP 网关层面:一份 capabilities.yaml 声明白名单,capa install 自动把每个子代理接到专属过滤端点,运行时越权调用被硬拒绝并留痕。研究型 Agent 从此天然"没有" git push,而不是"不敢"用它。
核心源码索引: