核心心智模型

一棵按路径组织的能力树

在 tool-bridge 中，工具不是一个扁平列表。每项能力都挂在路径上：

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

路径同时承担三种职责：

• 组织：让相关能力形成可浏览、可搜索的局部空间；
• 发现：从任意层级读取只属于当前身份的帮助与子树；
• 授权：把 scope 落在路径前缀和动作上，而不是维护另一套孤立 ACL。

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

节点背后可以来自不同系统：MCP server、HTTP API、内置集成、对象存储、本地设备、Skillhub 或另一棵远端树。tool-bridge 统一的是对调用方可见的发现、权限和调用语义，并不要求所有 provider 使用同一种内部实现。

当前运行时包含这些节点种类：directory、mcp、http、builtin、context、device、remote、tool 和 skillhub。种类会随版本演进；不要用这份静态列表替代实例的 ~help。

先发现，再调用

每个可见路径都可能提供以下运行时入口：

• ~help：返回当前路径的说明、工具、参数与 schema；
• ~tree：浏览当前身份可见的子树；
• ~search：在启用搜索能力的宿主中查找工具；
• ~feedback：读取或提交附着在该路径上的使用经验；
• /~mcp：把当前身份可见的工具投影成 MCP server。

其中 ~search 等能力取决于宿主和配置。正确做法是先读取父路径的 ~help，再决定下一步，而不是假设所有实例都提供相同功能。

两种 HTTP 调用形状

直接向节点发送工具信封：

POST /tools/docs
Content-Type: application/json

{
  "tool": "search",
  "arguments": { "query": "tool-bridge" }
}

当路径已经指向一个具体工具时，也可以直接向该工具路径发送参数。究竟支持哪些形状、工具名和参数，以该路径的 ~help 和 JSON Schema 为准。

CLI、Dashboard 和 MCP 投影最终访问的是同一棵树和同一权限模型，因此它们不是不同的管理旁路。

一套应用语义，多种宿主

宿主	运行时适配	适合场景
Cloudflare Workers	KV、R2、D1、Durable Objects	边缘部署、低运维、设备长连接
Node / Docker	SQLite、本地对象存储、WebSocket	自托管、内网、本地闭环
Embedded SDK	由应用注入 store 与 provider	嵌入现有 Node 或 Workers 应用

业务真源位于宿主中立的应用层。宿主负责装配存储、长连接和平台能力，不应改变公开的路径、权限和调用语义。