能力树、路径与节点

tool-bridge 不把所有工具塞进一个扁平列表，而是把工具、上下文、设备和远端服务组织成一棵树。路径既是人类理解能力的命名空间，也是运行时发现和权限判断的共同边界。

本页适合第一次设计树结构、规划团队命名空间或排查“为什么某个身份看不到节点”的读者。如果你只想立即运行网关，先完成5 分钟本地启动；如果你已经知道目标路径并要调用它，直接阅读从 ~help 到调用。

一棵按路径组织的能力树

下面是一棵示例树，不代表任何实例的默认内容：

/
├── tools/
│   ├── search
│   └── docs
├── ctx/
│   └── knowledge
├── device/
│   └── build-01
└── teams/
    └── analytics

它同时表达三件事：

• tools/docs 与 tools/search 属于同一个工具命名空间；
• device/build-01 来自一台反向连接的设备；
• teams/analytics 可以是一棵远端 HTBP 树在本地的挂载点。

路径按 / 分段。scope glob 也按完整路径段匹配：* 匹配一段，** 匹配零段或多段。不要把路径当作普通字符串前缀，否则容易把 tools/a 与 tools/ab 错误地视为同一范围。

路径同时承担三种职责

组织

目录把相关能力聚合在一起。推荐先按责任域或团队划分第一层，再按来源或用途细分，例如：

tools/research/*
tools/engineering/*
ctx/product-docs/*
device/ci/*
teams/data-platform/*

避免把上游产品名、调用协议和团队归属全部混在同一级，也不要频繁改动已经分发给 Agent 的公共路径。

发现

调用者从父路径的 ~help 或 ~tree 进入，只会看到当前 SK 可见的部分。树不是管理员视角的全局静态目录，而是对身份裁剪后的投影。

tb tree --depth 2
tb help tools
tb help tools/docs

实际子节点、工具名和 schema 必须以目标实例返回的 ~help 为准。

授权

SK scope 直接落在同一条路径上，例如只允许读取和调用 tools/research 子树：

tb sk create \
  --owner agent:researcher \
  --scope 'tools/research/**:read,call'

** 可以匹配零段，因此这条规则同时覆盖挂载点本身和后代。权限还要结合 action、deny 与 registerPaths 判断，完整规则见权限、SK 与可见性。

节点是统一投影，不是统一实现

两个节点在树上都能提供 ~help 和调用入口，不代表它们的上游实现相同。节点可能来自远端 MCP、声明式 HTTP、进程内 Plugin、本地对象存储、设备 WebSocket 或另一棵 tool-bridge。

当前协议中的 NodeKind 包括：

kind	用途
directory	组织子节点，不直接代表一个上游工具源
mcp	挂载 Streamable HTTP MCP Server
http	挂载声明式 HTTP 工具定义
builtin	网关的系统控制面模块
context	提供对象、文档或知识内容的 Context namespace
device	由反向连接设备代写和承载的节点
remote	另一棵 HTBP 树的本地挂载点
tool	Plugin 或 SDK 本地 Provider 投影的工具节点
skillhub	Agent Skill 的存储与发布节点

这张表用于理解类型，不应被当作实例节点清单。NodeKind 可能随版本演进，某个实例是否装配对应能力仍应从运行时 ~help 判断。

Node、Provider 与 Export 的关系

可以把三者理解为：

• Node：调用者在树上看到的路径与描述；
• Provider：节点背后真正列出和执行工具、读写 Context 的实现；
• Export：一个 Plugin 暴露的某个独立工具或 Context 表面。

一个 Plugin 可以有多个 exports；挂载时需要选择 export，但最终调用者只面对挂载后的节点路径。内置 integration catalog 的精确 exports、凭证字段和 mountConfig 是动态构建产物，应查询 system/catalog，不要从公共文档复制一份静态 provider 表。

Virtualize 只改变投影视图

挂载 MCP 或工具 Provider 时，可以隐藏、重命名、加前缀或改写工具描述：

tb tool mount tools/docs \
  --kind mcp \
  --url https://mcp.example.com/mcp \
  --prefix docs_ \
  --hide internal_debug

Virtualize 改变的是 tool-bridge 对调用者投影的名称和说明，不会改变上游服务的真实身份。客户端应读取挂载路径的 ~help，不能假设投影名等于上游原名。

设计一棵可维护的树

建议遵循以下约束：

1. 先按权限边界切分：需要不同 SK 的能力不要勉强挤进同一路径；
2. 给稳定用途命名：tools/research 通常比带版本号或临时项目名的路径更耐用；
3. 把密钥留在 SecretStore：路径和节点描述不能包含 token、账号或私有 URL 参数；
4. 为设备保留明确前缀：每个长驻设备使用稳定且唯一的 deviceId/path；
5. 为联邦使用独立子树：远端团队的树放在 teams/<name> 一类边界下，更容易授权和排障；
6. 用运行时检查结果：创建或挂载后，分别用 Admin 与目标受限 SK 运行 tb tree 和 tb help。

成功证据

• tb tree <prefix> 的结构符合预期；
• 目标节点 ~help 能列出实际工具或 Context 命令；需要确认可选 capability 时，目标路径 ~describe 返回真实能力表；
• 受限 SK 只能看到授权子树；
• virtualize 后的名称在 ~help 与实际调用中一致。

常见误区

把目录当成工具

目录可能只用于组织。应继续读取该路径的 ~help 或 ~tree，找到真正可调用的节点。

用管理员看到的树训练所有 Agent

Admin 视图包含普通 Agent 无权访问的路径。每个客户端都应使用自己的 SK 做运行时发现。

在静态配置里维护另一份工具清单

挂载、权限、provider schema 与反馈都会变化。静态清单很快与运行时分叉，应让 Agent 从 ~help 获取当前契约。

下一步

• 阅读从 ~help 到调用，把树转化成可靠调用流程；
• 阅读权限、SK 与可见性，按路径设计最小权限；
• 选择内置集成、MCP或Context创建第一个业务节点。