跳转到内容
tool-bridge

挂载与使用 Context

Context 把文档、对象和知识命名空间挂到能力树中。它不是固定的“六方法存储接口”：每个 provider 可以只实现自己真正支持的动词，~help 只披露实际能力。

Capability 驱动，而不是假设全功能

Section titled “Capability 驱动，而不是假设全功能”

Context 可能提供：list、get、search、write、update、delete。这些 handler 全部可选：

  • 没有任何写 handler 的 provider 自动只读；
  • readOnly 挂载可以进一步隐藏并拒绝一个原本可写 provider 的写动作；
  • search 可能不存在，semantic search 还需要额外 capability；
  • 调用未披露的动词会得到 invalid_argument，不会假装成功。

什么时候选择 Context

Section titled “什么时候选择 Context”

适合：文档、提示词、配置片段、知识库对象，以及需要命名路径、metadata、version 和分页列表的内容。附件和设备产物通常直接使用Store，无需先建 namespace。

不适合：低延迟关系型查询、强事务工作流、任意大规模文件同步，或需要把对象当可执行工具的场景。工具调用应使用 tool/MCP/HTTP；Agent Skill 包可考虑 skillhub。

前置条件

Section titled “前置条件”
  • 当前 SK 对目标路径有 register，且 registerPaths 允许；
  • 数据面读取需要目标路径 read，写入需要 write；
  • S3 或带凭证的 Plugin provider 需要 system/secret:admin 才能绑定 authRef；
  • 宿主必须装配对应对象存储或 Plugin export。

路径权限与 SecretStore 引用的完整规则分别见权限、SK 与可见性和密钥、出站身份与安全边界。

使用宿主对象存储

Section titled “使用宿主对象存储”

标准 Node 实例使用已验证的 S3 后端。平台挂载使用 storage provider，创建时固定当时的 active backendId；之后切换默认后端不会移动这个 Context。也可以用 --backend-id <id> 显式选择，详见存储后端管理：

Terminal window
tb ctx mount ctx/team-notes \
  --provider storage \
  --prefix team-notes/ \
  --description "团队文档"

如果只希望调用方读取：

Terminal window
tb ctx mount ctx/public-handbook \
  --provider storage \
  --prefix handbook/ \
  --read-only

平台没有注入 ObjectStore 时，该 provider 会返回 unavailable；这不是靠修改节点配置可以修复的问题，需要部署者补齐宿主能力。

挂载 S3-compatible 存储

Section titled “挂载 S3-compatible 存储”

凭证文件示例：

{
  "accessKeyId": "...",
  "secretAccessKey": "..."
}

保存凭证并挂载：

Terminal window
tb secret set --name docs-s3 < s3-credential.json


tb ctx mount ctx/docs \
  --provider s3 \
  --endpoint https://s3.example.com \
  --bucket docs \
  --region auto \
  --prefix knowledge/ \
  --auth-ref docs-s3

endpoint、bucket、region、prefix 是非敏感配置；access key 和 secret key 必须留在 SecretStore。挂载会在权限检查之后验证配置和必要的上游连通性。

读写与并发控制

Section titled “读写与并发控制”

先查真实命令：

Terminal window
tb help ctx/docs
tb ctx ls ctx/docs

读取：

Terminal window
tb ctx cat ctx/docs handbook/getting-started.md

写入或整体替换：

Terminal window
tb ctx put ctx/docs handbook/getting-started.md \
  --file ./getting-started.md \
  --content-type text/markdown \
  --meta owner=docs-team

部分更新只适用于披露 update 的 provider：

Terminal window
tb ctx patch ctx/docs handbook/getting-started.md \
  --meta reviewed=yes

响应中的 version 可用于乐观并发。更新重要对象时传 --if-version <version>；版本不匹配返回 conflict，调用方应重新读取并合并，而不是盲目覆盖。

搜索只在该 namespace 披露 search 时使用：

Terminal window
tb ctx search ctx/docs "deployment"

这与根级 tb search 不同：前者搜索 Context 条目，后者搜索全树可调用工具。

二进制与可选直传

Section titled “二进制与可选直传”

标准 Node S3 adapter 当前没有 presigner，平台 Context 不披露 direct-upload。不能因为后端是 S3 或 R2，就假设 tb ctx upload 一定可用。普通文档继续使用 tb ctx put；独立二进制产物使用Store relay 上传。

仅当自定义 provider 在运行时明确披露 direct-upload 和 create_upload 时，才使用以下流程：

Terminal window
tb help ctx/docs
tb ctx upload ctx/docs photos/shot.jpg --file ./shot.jpg

该能力默认拒绝覆盖同名 entry；只有明确要替换时才加 --force。返回 URL 与签名 headers 是短期 bearer，应按原样执行且不记录。CLI 返回稳定 node:// URI。浏览器直传还需要对象服务正确配置 CORS；未实现的 capability 不能靠添加 CORS 开启。

大对象与 $ref

Section titled “大对象与 $ref”

小对象通常内联在 content 中；超过宿主阈值时，Get 可以返回 { "$ref": "..." }。该 URL 是短期能力：可能是对象存储预签名 URL，也可能是网关的 ~ref 中转。

  • 不要把 $ref 作为永久地址保存；
  • 不要转发给无关身份；
  • 过期后重新执行 Get；
  • 不要假设所有部署都直接暴露 R2/S3 URL。

成功证据

Section titled “成功证据”
  1. tb help ctx/docs 只列 provider 实际能力；
  2. tb ctx ls 和 cat 能读取测试对象；
  3. 可写 provider 的 put 返回 URI/version，随后 cat 内容一致；
  4. 披露 direct-upload 时，默认上传能创建对象、同名上传返回 conflict，只有显式 --force 才覆盖；
  5. read-only 节点不披露写动词，写请求被拒；
  6. 受限 SK 能读指定 namespace，但看不到其他 Context；
  7. tb secret ls 不返回 S3 明文。

如果你要把这套验证编进 Agent 或客户端，按从 ~help 到调用读取 namespace 的真实命令与 schema。

常见失败

Section titled “常见失败”
现象 处理
unknown cmd provider 没有该 capability；重新读取节点 ~help
写操作 403 缺 write，或节点以 readOnly 挂载
S3 挂载要求 authRef 先写 SecretStore，并使用 JSON 凭证对象
unavailable 对象存储未装配、Secret 无法解析或上游不可达；按错误来源处理
conflict ifVersion 已过期；重新读取后合并
Search 不存在 该 Context provider 未实现 search；不要与根级工具 Search 混淆
ctx upload 不可用 namespace 未披露 direct-upload，或对象存储没有 presign 能力
上传 conflict 同名 entry 已存在；只有明确要替换时才重新执行并加 --force
$ref 失效 URL 已过期或节点已卸载；重新 Get

卸载与数据回滚

Section titled “卸载与数据回滚”
Terminal window
tb ctx unmount ctx/docs
tb tree ctx --depth 2

卸载移除树节点，不等于删除外部 bucket 或其中对象。先确认数据保留策略，再决定是否在对象存储侧清理。S3 凭证也不会自动删除；确认没有其他挂载引用后，才能执行：

Terminal window
tb secret rm docs-s3

迁移 provider 时建议先以新路径只读挂载并比对 List/Get，再启用写入、切换调用方，最后卸载旧节点。不要把切换、删数据和删凭证压成一次操作。

下一步

Section titled “下一步”