运行时契约

本页是一张用于建立方向感的速查表。精确工具名、参数、schema 与可见路径必须以目标实例当前返回的 ~help 为准。

认证

HTTP 请求通常使用 Bearer SK：

Authorization: Bearer tbk_...

SK 明文只应在签发时出现一次。服务端持久化 hash；禁用、删除或过期的 SK 都视为失效。

发现

请求	含义	说明
GET /~help	根路径帮助	默认返回 Markdown
GET /<path>/~help	指定路径帮助	仅包含当前身份可见内容
GET /<path>/~tree	浏览子树	深度与形状由请求参数和权限约束
GET /<path>/~search	搜索能力	仅在宿主启用对应 capability 时存在
/<base>/~mcp	MCP 投影	暴露当前身份可见的工具面

~help 的内容协商：

Accept	返回形状
未指定或 text/markdown	适合人和通用 Agent 阅读的 Markdown
text/plain	紧凑 Help DSL
application/json	带 JSON Schema 的结构化 Help JSON

调用

向节点发送标准工具信封：

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

对应请求：

POST /tools/docs
Content-Type: application/json
Authorization: Bearer <scoped-sk>

具体工具路径也可以支持直接 POST。客户端不应猜测调用形状，应先读取目标路径的结构化 ~help。

权限动作

动作	典型含义
read	读取节点、对象、帮助或反馈
write	写入节点承载的数据
call	调用工具、提交或投票反馈
register	在允许的路径注册设备或能力
admin	管理节点、授权或执行高权限操作

规则按路径匹配，deny 优先。没有可见权限的资源表现为 404，以免泄漏树结构。

错误

公开错误使用稳定信封：

{
  "code": "ERROR_CODE",
  "message": "Human-readable summary",
  "retryable": false
}

• code 用于程序分支；
• message 用于安全的人类可读说明；
• retryable 表示在不改变请求意图时重试是否可能成功。

错误详情不得回显 SK、上游 token、敏感参数或内部凭证位置。

兼容性原则

• 忽略 Help DSL 中无法识别的新条目，避免客户端因增量扩展而崩溃；
• 使用 JSON Schema 校验参数，不把站点示例当作固定 schema；
• 升级 pre-launch 版本前阅读发布说明并备份状态；
• 如果静态文档与实例行为冲突，以对应版本代码和实例运行时契约为准。