能力树与权限

能力发现、意图分类、分级权限控制与子智能体能力子树二级扩展

能力树（Capability Tree）是 Crab Claw 的工具管理核心与唯一权威来源——所有下游消费者（提示词构建、意图路由、策略引擎、技能绑定、前端展示）均从树派生，不允许绕过树直接注入工具。

为什么需要能力树

单一真相源

所有工具元数据集中管理，权限、意图、审批、技能绑定统一从树派生，消除多处定义导致的不一致。

智能意图路由

6 级意图层级自动匹配工具范围，用户说"你好"不会触发文件删除工具，说"重构代码"才激活编程工具集。

子智能体隔离

通过能力子树（SubTree）实现子智能体工具的精确隔离——媒体工具不出现在编程智能体中，反之亦然。

动态扩展

支持运行时动态注册 Argus 视觉工具、远程 MCP 工具、本地 MCP 插件，无需重启即可扩展能力。

三层架构

shell

能力树 (Capability Tree)     ← 单一真相源，定义所有工具 7 维元数据
  ↓
工具注册 (Tool Registry)     ← 运行时工具定义，LLM 可调用
  ↓
技能绑定 (Skill Binding)     ← SKILL.md 为工具注入领域知识
能力树 (Capability Tree)     ← 单一真相源，定义所有工具 7 维元数据
  ↓
工具注册 (Tool Registry)     ← 运行时工具定义，LLM 可调用
  ↓
技能绑定 (Skill Binding)     ← SKILL.md 为工具注入领域知识

完整树结构

shell

DefaultTree() (sync.Once 单例)
├── runtime/               ← Shell 执行
│   └── bash
├── fs/                    ← 文件系统
│   ├── read_file
│   ├── write_file
│   ├── list_dir
│   └── apply_patch
├── web/                   ← 网页工具
│   ├── web_search
│   └── web_fetch
├── ui/                    ← 浏览器与画布
│   ├── browser
│   └── canvas
├── memory/                ← 记忆系统
│   ├── memory_search
│   └── memory_get
├── system/                ← 系统管理
│   ├── cron
│   ├── gateway
│   └── nodes
├── messaging/             ← 频道消息
│   └── message
├── sessions/              ← 会话管理
│   ├── sessions_list / sessions_history / sessions_send
│   ├── sessions_spawn / session_status / agents_list
│   └── search_skills / lookup_skill
├── ai/                    ← AI 生成
│   └── image
├── media/                 ← 媒体与邮件
│   ├── send_media
│   └── send_email
├── meta/                  ← 元工具
│   ├── capability_manage
│   └── report_progress
│
├── subagents/             ← 子智能体入口（主智能体可见）
│   ├── spawn_coder_agent
│   ├── spawn_media_agent
│   ├── spawn_argus_agent
│   ├── spawn_agent
│   └── handoff_to_agent
│
├── subagent_trees/        ← 子智能体能力子树（二级扩展）
│   ├── subagent_trees/media/
│   │   ├── trending_topics   [scope=media]
│   │   ├── content_compose   [scope=media]
│   │   ├── media_publish     [scope=media]
│   │   └── social_interact   [scope=media]
│   └── subagent_trees/coder/
│       ├── propose_plan      [scope=coder]
│       └── report_heartbeat  [scope=coder]
│
├── composed/              ← 组合工具（技能编译产物）
│   └── skill_*            ← SKILL.md 编译生成
│
└── dynamic/               ← 动态工具（运行时注册）
    ├── argus_*            ← Argus 桌面自动化工具
    ├── remote_*           ← 远程 MCP 工具
    └── mcp_*              ← 本地 MCP 插件工具
DefaultTree() (sync.Once 单例)
├── runtime/               ← Shell 执行
│   └── bash
├── fs/                    ← 文件系统
│   ├── read_file
│   ├── write_file
│   ├── list_dir
│   └── apply_patch
├── web/                   ← 网页工具
│   ├── web_search
│   └── web_fetch
├── ui/                    ← 浏览器与画布
│   ├── browser
│   └── canvas
├── memory/                ← 记忆系统
│   ├── memory_search
│   └── memory_get
├── system/                ← 系统管理
│   ├── cron
│   ├── gateway
│   └── nodes
├── messaging/             ← 频道消息
│   └── message
├── sessions/              ← 会话管理
│   ├── sessions_list / sessions_history / sessions_send
│   ├── sessions_spawn / session_status / agents_list
│   └── search_skills / lookup_skill
├── ai/                    ← AI 生成
│   └── image
├── media/                 ← 媒体与邮件
│   ├── send_media
│   └── send_email
├── meta/                  ← 元工具
│   ├── capability_manage
│   └── report_progress
│
├── subagents/             ← 子智能体入口（主智能体可见）
│   ├── spawn_coder_agent
│   ├── spawn_media_agent
│   ├── spawn_argus_agent
│   ├── spawn_agent
│   └── handoff_to_agent
│
├── subagent_trees/        ← 子智能体能力子树（二级扩展）
│   ├── subagent_trees/media/
│   │   ├── trending_topics   [scope=media]
│   │   ├── content_compose   [scope=media]
│   │   ├── media_publish     [scope=media]
│   │   └── social_interact   [scope=media]
│   └── subagent_trees/coder/
│       ├── propose_plan      [scope=coder]
│       └── report_heartbeat  [scope=coder]
│
├── composed/              ← 组合工具（技能编译产物）
│   └── skill_*            ← SKILL.md 编译生成
│
└── dynamic/               ← 动态工具（运行时注册）
    ├── argus_*            ← Argus 桌面自动化工具
    ├── remote_*           ← 远程 MCP 工具
    └── mcp_*              ← 本地 MCP 插件工具

工具组总览

工具组	工具数	说明	典型工具
runtime	1	Shell 执行	bash
fs	4	文件系统操作	read_file, write_file, list_dir, apply_patch
web	2	网页搜索与抓取	web_search, web_fetch
ui	2	浏览器控制与画布	browser, canvas
memory	2	记忆读写	memory_search, memory_get
system	3	系统管理	cron, gateway, nodes
messaging	1	频道消息发送	message
sessions	8	会话与子智能体管理	sessions_list, search_skills 等
ai	1	图像生成	image
media	2	文件投递与邮件	send_media, send_email
meta	2	元工具	capability_manage, report_progress
subagents	5	子智能体入口	spawn_agent, handoff_to_agent
合计	33+	静态工具 + N 动态工具	—

7 维元数据

能力树中每个工具节点携带完整的 7 维元数据：

维度	字段	说明
Runtime	Owner, EnabledWhen, SubAgentScope	运行时归属和启用条件
Prompt	Summary, SortOrder	提示词摘要和排序权重
Routing	MinTier	最低意图层级门槛
Perms	MinSecurityLevel, FileAccess, ApprovalType	安全级别和审批类型
Skills	Bindable	是否允许技能绑定
Display	Icon, Title, Verb	前端显示元数据
Policy	PolicyGroups	策略分组（如 group:media_agent）

意图分类（6 级）

智能体根据用户消息自动分类意图层级，每个层级决定可访问的工具范围：

意图层级	说明	可用工具示例	典型触发
`greeting`	问候/闲聊	无工具，纯对话	"你好"、"今天怎么样"
`question`	信息查询	web_search, memory_search	"什么是技能系统"
`task_light`	轻量只读任务	read_file, list_dir, web_fetch	"读取这个文件"
`task_write`	写入任务	write_file, bash, spawn_agent	"创建一个文件"
`task_delete`	删除任务	bash(rm), 文件删除	"删除这个目录"
`task_multimodal`	多模态复杂任务	全部工具（含 browser, argus）	"批量处理图片"

层级越高，可访问的工具越多，需要的审批也越严格。

审批类型（5 种）

审批类型	说明	触发场景	用户交互
`none`	无需审批	文件读取、网页搜索、记忆查询	静默执行
`plan_confirm`	计划确认	写入文件、创建定时任务、发布内容	消息频道一键确认
`exec_escalation`	执行提权	Shell 命令、系统管理、内容发布	弹窗确认
`data_export`	数据导出	文件发送、邮件发送	确认导出目标
`mount_access`	挂载访问	访问工作区外的文件路径	确认挂载路径和权限

审批请求通过当前活跃的消息频道（如 Telegram、飞书、终端）发送给用户确认。

子智能体能力子树（二级扩展）

设计理念

传统方案中子智能体工具是"暗工具"——不在能力树中注册，无法审计、无权限检查、技能系统不可见。Crab Claw 通过嵌入式子树分支解决这一问题：在 DefaultTree() 单例内创建子分支，而非独立树实例。

SubAgentScope 隔离机制

通过 SubAgentScope 字段实现工具的作用域隔离：

Scope 值	含义	工具归属
`""` (空)	标准工具	主智能体可见
`"media"`	媒体专属工具	仅媒体子智能体内可用
`"coder"`	编程专属工具	仅编程子智能体内可用

隔离规则：

主智能体的 AllStaticTools()、ToolsForTier()、BindableTools() 等 10 个派生方法自动排除 SubAgentScope 非空的工具
子智能体通过 ToolsForAgentScope(scope) 查询自己的专属工具
ScopedToolSummaries(scope) 返回 scope 工具 + 共享标准工具，用于子智能体提示词构建
DisplaySpecs() 和 Lookup() 包含所有工具（前端展示和直接查找不过滤）

统一注入接口

所有子智能体类型通过同一个 SubAgentToolProvider 接口注入工具：

shell

SubAgentToolProvider 接口
  ├─ AgentType()     → "media" / "coder"
  ├─ SubTreeGroupID() → "subagent_trees/media"
  ├─ ToolDefs()      → LLM 工具定义列表
  └─ ExecuteTool()   → 工具执行分派
SubAgentToolProvider 接口
  ├─ AgentType()     → "media" / "coder"
  ├─ SubTreeGroupID() → "subagent_trees/media"
  ├─ ToolDefs()      → LLM 工具定义列表
  └─ ExecuteTool()   → 工具执行分派

注册流程：

启动阶段：RegisterSubAgentTree(provider) 注册到全局注册表
运行时注入：SubAgentTreeFor(agentType) 查找 → ToolDefs() 获取工具列表
意图过滤旁路：子智能体工具通过预构建 set 旁路保留，不被标准白名单过滤

扩展新类型

添加新子智能体类型只需 4 步：

tree_migrate.go 中添加子树分组节点和工具节点（7 维元数据 + SubAgentScope）
子系统代码实现 SubAgentToolProvider 接口（4 个方法）
server.go boot 阶段调用 RegisterSubAgentTree(provider)
运行测试验证

# 查看完整能力树
crabclaw skills codegen --status

# 在聊天中使用
> 诊断工具 bash 的能力树状态
> 列出所有子智能体子树
# 查看完整能力树
crabclaw skills codegen --status

# 在聊天中使用
> 诊断工具 bash 的能力树状态
> 列出所有子智能体子树

支持的诊断操作：

操作	说明
`list_groups`	列出所有工具组
`list_tools`	列出指定组的工具
`describe_tool`	查看工具详细 7 维元数据
`diagnose`	诊断工具绑定状态和意图匹配
`subtrees`	查询所有子智能体子树分支

subtrees 查询示例

json

{
  "subtrees": [
    {
      "agent_type": "media",
      "group_id": "subagent_trees/media",
      "tool_count": 4,
      "tool_names": ["trending_topics", "content_compose", "media_publish", "social_interact"],
      "registered": true
    },
    {
      "agent_type": "coder",
      "group_id": "subagent_trees/coder",
      "tool_count": 2,
      "tool_names": ["propose_plan", "report_heartbeat"],
      "registered": true
    }
  ]
}
{
  "subtrees": [
    {
      "agent_type": "media",
      "group_id": "subagent_trees/media",
      "tool_count": 4,
      "tool_names": ["trending_topics", "content_compose", "media_publish", "social_interact"],
      "registered": true
    },
    {
      "agent_type": "coder",
      "group_id": "subagent_trees/coder",
      "tool_count": 2,
      "tool_names": ["propose_plan", "report_heartbeat"],
      "registered": true
    }
  ]
}

相关文档：编程子智能体 · 媒体智能体 · 技能系统 · 安全与审批

能力树与权限

为什么需要能力树

三层架构

完整树结构

工具组总览

7 维元数据

意图分类（6 级）

审批类型（5 种）

子智能体能力子树（二级扩展）

设计理念

SubAgentScope 隔离机制

统一注入接口

扩展新类型

动态工具注册

Argus 桌面自动化工具

远程 MCP 工具

本地 MCP 插件

能力树自省

subtrees 查询示例