同步 Agent Skill 接入指南与运行时验收契约

llmdoc/cli/agent-skill-integration.mdx

@@ -40,12 +40,16 @@ code:
 
 ## Agent 运行时流程
 
-先按 `target + profile + identity` 确定本次任务的认证上下文。每个不变的上下文在同一 task/session 内只用 `tb whoami --json` 验证一次;切换 target、profile 或 identity 后才重新验证,输出中只能出现打码 SK。CLI reference 与专题说明按需渐进加载,不作为首次调用的固定前置步骤。
+先按 `target + profile + identity` 确定本次任务的认证上下文。每个不变的上下文在同一 task/session 内只用 `tb whoami --json` 验证一次;切换 target、profile 或 identity 后才重新验证,输出中只能出现打码 SK。必须检查其 `authenticated` 与 `status`：命令可正常退出但返回 `authenticated:false`，不能据退出码认定认证成功。CLI reference 与专题说明按需渐进加载,不作为首次调用的固定前置步骤。主 Skill 保留目标选择、最短调用流程与授权边界;发现、设备、数据、管理与恢复细节由任务信号触发加载。
+
+区分两种帮助:本机 CLI 参数不确定时用 `tb <command> --help`;目标实例的节点/工具契约不确定时用
+`tb help <path> --json` 获取 `~help`。不能把 `tb help store` 当成本机 Store 子命令手册,也不能用本机
+CLI 存在某个子命令推断目标实例支持对应 capability。
 
 随后选择最短的适用路径:
 
 - **Fast path:** 当前 runtime 的完整命令 path、schema、`effect:read` 和 `confirm:false` 均已知时,直接 `tb call`,不重复 search、help 或 feedback 预查。
-- **Discovery path:** 能力未知时先 `tb search --json`。结果唯一、字段信息足够且确认是无副作用只读调用时直接 call;Search capability 不存在时才逐级使用 `tb tree`、`tb ls`。字段缺失、命中歧义、路径陌生或历史上易失败,以及任何写入、破坏性或需确认操作,才下钻工具级 `~help`,以 `cmds[].path`、schema、effect、confirm 和 scope 决定调用方式与确认边界。
+- **Discovery path:** 广泛探索能力时用 compact 的 `tb search <query> --json`;已准备选择工具并调用时用 `tb search <query> --schemas --json`,在同一轮请求 full 结果。`--json` 只改变输出格式,不会隐式下载 schema。full 结果唯一、实含本次所需字段且确认是无副作用只读调用时直接 call;不能从 compact 结果猜参数。Search capability 不存在时才逐级使用 `tb tree`、`tb ls`;空结果或 partial 不等于 capability 不存在。字段缺失、命中歧义、路径陌生或历史上易失败,以及任何写入、破坏性或需确认操作,才下钻工具级 `~help`,以 `cmds[].path`、schema、effect、confirm 和 scope 决定调用方式与确认边界。
 - **Recovery path:** call 失败、超时、schema 合法但结果异常或上游行为不一致时,优先消费 CLI 随错误附带的 hint/feedback。只 `get` 最相关的一条;没有有效提示,或为了提交新反馈而去重时,才 `feedback ls`。应用已验证 workaround 后通常最多安全复验一次,副作用结果未知时不自动重试。
 
 设备命令还必须区分运行时 capability metadata 与调用 policy：`delivery:realtime|mailbox|both` 描述命令能
@@ -55,15 +59,29 @@ code:
 Agent 在同步失败后再发第二条请求猜测 enqueue；completed（包括设备业务错误）和 unknown 都不入队，unknown
 还固定不可重试。effect/confirm 与用户授权边界不因 delivery 改变。
 
-能力未知时先 `tb search --json`，唯一命中且 metadata 足够才 `search → call --delivery fallback`，否则按
-既有规则下钻 help。返回 mailbox operation identity 后默认结束当前同步流程，不启动固定间隔轮询；只有
+能力未知且准备调用时先 `tb search <query> --schemas --json`，唯一命中且 metadata 足够才
+`search → call --delivery fallback`，否则按既有规则下钻 help。full search 不保证所有 capability 字段
+都存在，联邦结果仍可能缺 `delivery`；离线调用依赖它时必须读取具体命令 help，不能从 full 标记推断支持。
+显式 `--delivery`（包括 realtime）的 CLI JSON 返回 `{delivery:'mailbox',operation}` 或
+`{delivery:'realtime',result}`；未显式传 delivery 时才直接输出结果原值。CLI 不暴露 HTTP status/header；
+Mailbox 使用 `operation` 中的 `deviceId`、`operationId` 与 `state`，不能把入队当成执行完成。
+返回 mailbox operation identity 后默认结束当前同步流程，不启动固定间隔轮询；只有
 用户目标当下确实需要状态/终态时，按需做一次 `tb device op get <deviceId> <operationId>`。后续
 claim/complete 是设备侧协议，不计入 Agent 工具调用预算，也不由 Agent 模拟。
 
-调用结果若含 `store://default/...`，它只是对象身份：Agent 用 `tb store stat/get` 读取当前 owner 的对象，
+调用结果若含 `store://default/...`，它只是对象身份,不是访问凭证：Agent 用 `tb store stat/get` 读取当前 owner 的对象，
 只有用户明确要求把文件交给外部受众时才用 `tb store share` 创建短期 bearer，并把成功输出当 secret
-立即交付；用完可 `revoke-share`。普通设备产物不要求搜索或挂载 Context，只有明确 author 到命名语义
-entry 时才用 `tb ctx upload`。
+立即交付；用完可 `revoke-share`。普通设备产物不要求搜索或挂载 Context。需要 author 命名语义 entry
+时才选择 Context：内联文本/JSON 用 `tb ctx put`，二进制只有目标 runtime 广告 `create_upload` 时才用
+`tb ctx upload`。标准 Node S3 后端当前不广告 Context direct-upload，不能把 CLI 子命令存在写成该部署
+能力已可用。Store 与 Context 的身份、owner 和 namespace 不互换，不能把 Store 上传当成 Context entry
+已写入；具体边界见 [Default Store](../store/default-store.mdx) 与 [存储后端](../store/storage-backends.mdx)。
+
+管理任务使用对应 `tb` 子命令，先读当前状态/schema 再执行已授权变更。`tb config update` 只保存
+desired revision，`apply` 后还须核对 appliedRevision/effective/state；部署配置保存后也须以执行器的
+实际状态与任务结果判断是否完成。revision 冲突需要重新比较用户意图与新状态，不能静默重读后覆盖。
+存储后端的 add/test/activate、凭证轮换和数据迁移是不同动作；activate 只影响新对象，不能宣称旧对象
+已迁移。稳定管理约束分别以 [受管理配置](../hosts-deploy/managed-configuration.mdx) 和存储后端文档为准。
 
 正常只读调用不强制 `feedback ls/get`。只有 `~help` 已嵌入高相关条目,或路径陌生、历史上易失败时才在调用前读取相关 feedback。已有条目确实帮助恢复时可投票;新问题或已验证解法先去重,并且只在已获得外部写入授权时提交。vote/submit 均不阻塞成功结果;没有授权就不写 feedback,也不为完成本次调用临时扩大权限。
 
@@ -72,9 +90,11 @@ entry 时才用 `tb ctx upload`。
 性能预算以目标已验证后的 CLI 往返数计算:
 
 - 已知只读路径为一次 `call`。
-- 未知只读能力为 `search + call`;首次使用某个认证上下文最多再加一次 `whoami`。
+- 未知只读能力的最短执行路径为 `search --schemas + call`;首次使用某个认证上下文最多再加一次
+  `whoami`。主动选择 compact 探索后若尚缺 schema，追加 full search 或工具级 help 是必要的契约获取，
+  不得为了往返预算猜参数。
 - 已知设备路径为一次 `call --delivery fallback`；未知能力的最短路径为
-  `search + call --delivery fallback`。首次认证仍只按上文可多一次 `whoami`，mutating/confirm 命令仍可
+  `search --schemas + call --delivery fallback`。首次认证仍只按上文可多一次 `whoami`，mutating/confirm 命令仍可
   按需多一次 help 与用户确认。
 - operation 状态读取与 enqueue 解耦：只有确有当前结果需求时才增加一次 `device op get`，不把“直到终态”
   的固定 polling 往返写进 Agent 默认预算。
@@ -103,23 +123,35 @@ entry 时才用 `tb ctx upload`。
 - 权限、404 可见性、错误码或安全边界变化;
 - Agent 推荐工作流不再能从运行时自描述完成。
 - `tb store` 命令、`store://` 结果或 Store/Context 选择语义变化。
+- 配置/部署 desired 与 applied 状态、revision 冲突、后端身份与激活规则变化；管理 reference 要同步，
+  不能以请求被接受代替生效证据。
 - `delivery` discovery、`tb call --delivery`、`tb device op`、operation 状态或 Mailbox 重试/轮询边界变化；
   CLI 与公开 Skill 必须同轮联动，不能出现 CLI 已统一 invoke 而 Skill 仍教两步 call/enqueue 的漂移。
 
 只更新 Skill 中稳定的流程与边界,不复制版本号或动态 catalog。公共教程若展示安装或连接步骤,也要同步评估;面向开发 agent 的内部实现细节仍留在本仓库 llmdoc。
 
 ## 验收
 
-在 Skill 仓库至少验证 `npx --yes skills add . --list`,输出必须只发现预期的 `tool-bridge` skill。再做三个隔离前向测试:
+在 Skill 仓库至少验证 `npx --yes skills add . --list`,输出必须只发现预期的 `tool-bridge` skill。再做隔离前向测试，至少覆盖:
 
 1. 已知只读路径在 target 已验证后直接 `call`,并断言没有冗余 discovery、help 或 feedback 命令。
-2. 未知只读能力覆盖 `search --json → call`;首次 target 可在前面出现且只出现一次 `whoami`。
+2. 未知只读能力覆盖 `search <query> --schemas --json → call`;首次 target 可在前面出现且只出现一次 `whoami`。
+   另以 compact fixture 断言 `search --json` 不提供 schema 时不会猜参数调用；`whoami` 返回
+   `authenticated:false` 时不能继续业务调用。
 3. 用确定性的首次失败覆盖 `call failure → attached feedback get → 安全复验`,并断言无反馈写入授权时不执行 vote/submit。
 4. 已知 mailbox-capable path 覆盖单次 `call --delivery fallback`，断言无第二条 enqueue 请求、不固定轮询；
    只有测试目标要求当前终态时才允许随后出现一次 `device op get`。
-5. 未知 mailbox 能力覆盖 `search --json → call --delivery fallback`；分别以 completed 业务错误、
+5. 未知 mailbox 能力覆盖 `search <query> --schemas --json → call --delivery fallback`；分别以 completed 业务错误、
    `not_dispatched`、unknown 与 `result_unknown`/claimed-expired fixture 断言只有明确未分发会入队，其余不
    自动 retry。真实跨层 fixture 的 discovery + invoke + claim + complete + get 共五次 HTTP，其中后三步
    的 claim/complete 属设备协议，get 只在当前结果确有需要时发生。
+   另以 full search 缺 `delivery` 的 fixture 断言先补具体命令 help；根据当前 CLI 的 delivery/operation
+   输出判断入队与后续状态，不依赖未输出的 HTTP 状态码或响应头。
+   CLI fixture 应以最终 stdout 建模，并经真实 SDK 适配或独立源码核验 delivery wrapper，不能直接用
+   HTTP body 代替 CLI 输出。
+6. Store 产物保持 `store://` 身份，读取使用 Store 命令；未明确请求对外分享时不创建 bearer。命名 entry
+   任务选择 Context，runtime 未广告 `create_upload` 时不尝试二进制直传，也不把 Store 上传冒充 entry 写入。
+7. 管理 fixture 区分保存与生效：desired 保存成功但 pending/failed 时不能报告已应用；revision 冲突不能
+   自动覆盖；后端 activate 成功不能报告已有对象已迁移。
 
 异常测试不能只在 prompt 里写"可能失败";若 Agent 首次调用自然成功,只证明成功路径,必须通过无真实资源的可控故障注入重测。测试还应断言恢复通常不超过一次 workaround retry,且副作用不明时不重试。最后以 Skill 仓库 GitHub Actions 的 discovery 校验为远端证据。

llmdoc/meta.json

@@ -15,7 +15,7 @@
       "validatedRevision": "2b45dc99c607f59351d214845fe8e0c6b912f478"
     },
     "cli/agent-skill-integration.mdx": {
-      "validatedRevision": "2b45dc99c607f59351d214845fe8e0c6b912f478"
+      "validatedRevision": "02fca70d0d4ccca088fc4c44a908243b96eda5aa"
     },
     "cli/argument-contract.mdx": {
       "validatedRevision": "2b45dc99c607f59351d214845fe8e0c6b912f478"