Feedback 与管理员 Note

tool-bridge 不只让调用者拿到当前身份的真实契约，也允许把验证过的经验留在具体能力旁边。Feedback 记录使用者经验，管理员 Note 表达长期约束；两者都会进入后续发现流程，但都不是权限或审计系统。

底层的表示协商、完整命令路径直连与错误处理见从 ~help 到调用；本页聚焦如何把 Search、Feedback 和管理员 Note 接进该循环。

进入协作环节前

tree / search → 节点 help → 工具 schema → 查看 feedback
              → 最小调用 → 提交经验证的经验

开始前应已完成发现与调用循环，知道如何读取当前身份的树、节点索引和工具 schema。本页不再重复基础协议，只讨论搜索索引和协作数据如何进入该循环。

宿主启用全局 Search 时：

tb search "create document"

结果只包含当前身份可读且可调用的工具，并会回读节点做权限与工具表复核。但 Search 仍是派生索引，可能因宿主未启用而不存在。找不到结果时继续从 tree 和父路径 help 导航。

想在结果里直接看到命中工具的 inputSchema 时，加 --schemas：

tb search "create document" --schemas

默认搜索返回 compact（含 JSON 模式）；--schemas 在同一次请求中选择 detail: full，也适用于 --json。大结果集下输出会更长。

Context 自己的 tb ctx search 是另一种能力：它搜索 namespace 内的内容，并且只有该 provider 声明 Search 时存在。

搜索目前仅支持 keyword，按查询词覆盖率排序，不做翻译或同义词扩展。用 --path-prefix 收窄命名空间，用 --effect read 查找声明为只读的工具；effect 来自结构化 metadata，不能凭描述猜测。

tb search "document" --effect read --matching all
tb search "document" --federation recursive --json

递归搜索需要 search:federated capability。结果中的 source 与 partial 表达来源和未完整完成的部分；partial 不等于所有远端都搜索成功。索引还有节点与快照预算，找不到时继续用 tree / help 验证权威命令。

tb feedback ls tools/docs/search

列表只给摘要；需要完整 detail 时：

FEEDBACK_ID=fb_replace_with_real_id
tb feedback get tools/docs/search "$FEEDBACK_ID"

得分靠前的条目也会自动进入该路径 ~help。它们适合记录上游限制、正确参数组合、速率限制、权限前置或已验证的规避方式。

不应记录：SK/token、用户数据、完整敏感 payload、临时 incident 对话、未经验证的猜测。

tb feedback submit tools/docs/search \
  --title "先确认索引范围" \
  --detail "该上游默认只索引公开文档；私有空间需要额外授权。"

其他身份可以投票或撤回自己的票：

FEEDBACK_ID=fb_replace_with_real_id
tb feedback vote tools/docs/search "$FEEDBACK_ID" up
tb feedback vote tools/docs/search "$FEEDBACK_ID" clear

Feedback 权限落在目标路径：读取需要 read；提交和投票还需要 call；管理员删除需要 admin。根路径不接受 Feedback。

用不同身份验证这些 action 与 404 可见性时，按权限、SK 与可见性签发受限 SK。

Feedback 是低频、非权威协作数据；它服务于经验沉淀，不承担事务、审计、审批或强一致排名。不要把投票计数当作可靠的控制状态。

管理员可给路径设置较稳定的说明：

tb note set tools/docs/search \
  "生产调用前必须确认 workspace；不得搜索未授权私有空间。"

Note 会进入 ~help，适合组织政策、长期前置条件或迁移通知；Feedback 适合使用者验证出的经验并可投票。两者都不能保存 secret。

读取与删除：

tb note get tools/docs/search
tb note rm tools/docs/search

现象	处理
Search 404	宿主未启用全局 Search；改用 tree/help
工具节点 help 没有完整 schema	节点级默认是索引；下钻 `<node>/<tool>/~help`，或用 `--schemas` 一次取回整节点
Feedback 提交 404	目标路径不可见、悬空或是根路径
Feedback 提交 403	有 read 但没有 call
Feedback 被默认隐藏	净分低；管理员可用 `tb feedback ls <path> --hidden` 检查
调用失败但旧 Feedback 不适用	读取时间和实例契约，提交经验证的新条目，不盲从排名
Note 更新失败	set/rm 需要管理员权限；服务端校验是权威

投错票可以 clear；错误 Feedback 由管理员删除：

FEEDBACK_ID=fb_replace_with_real_id
tb feedback vote tools/docs/search "$FEEDBACK_ID" clear
tb feedback rm tools/docs/search "$FEEDBACK_ID"

错误 Note 用 tb note rm 移除。节点卸载后不要依赖其 Feedback 作为独立知识库；真正稳定的组织知识应进入受版本管理的文档，Feedback 只保留能力附近的短经验。