@itpay/cli 2.0.3 → 2.0.5

package/docs/cli-reference/commands/cart/add.md

@@ -0,0 +1,86 @@
+# `itpay cart add`
+
+## 范围与意义
+
+把一个已发布 Catalog offer 或一个已准备的 Service Quote 加入 canonical server Cart。Catalog 服务行先进入 `services next`；Quote 行已经锁定输入和价格，可以与其他独立 Execution 的 Quote 一起结算。
+
+**上游：** `catalog list` 返回的 item/variant/offer，或 `services quote` 返回的 Quote ID。
+**下游：** `services next <id>`、继续 `cart add --quote`，或 `buy --cart`。
+
+## 语法与参数
+
+```bash
+itpay cart add --item <catalog_item_id> --variant <catalog_variant_id> --offer <offer_id>
+  [--quantity <n>] [--input <json>] [--host <host>] [--target <target>] [--json] [--local]
+
+itpay cart add --quote <service_quote_lock_id>
+  [--host <host>] [--target <target>] [--json]
+```
+
+Catalog 模式下 `--item`、`--variant`、`--offer` 必须成组且来自同一记录；`--quantity` 为正整数，`--input` 必须是 JSON object。Quote 模式只接受 `--quote`，不能混用 Catalog 字段、input 或 `--local`。Backend 校验 Quote 有效、未过期、未消费且属于当前设备/账号。
+
+未显式传 `--host` 时，CLI 根据 `--agent-type` 选择 Host；需要消息目标的 Host 还必须传 `--target`。所有参数在本地草稿写入或 HTTP 请求前完成基础校验。
+
+## 标准输出
+
+```json
+{
+  "status": "added",
+  "result": {
+    "cart_id": "<cart_id>",
+    "cart_item_id": "<line_id>",
+    "service_execution_id": "<optional_id>",
+    "title": "<title>",
+    "amount": "<amount> <currency>"
+  },
+  "instruction": "服务型项目已创建 Service Execution；先读取其当前步骤，不要直接进入普通 buy。",
+  "next": { "command": "itpay services next <service_execution_id> --json", "reason": "读取服务执行的当前步骤" },
+  "recovery": []
+}
+```
+
+输出只描述本次新增 line，不返回完整 Cart、全部 line、capability 列表、Service read model、client context 或重复 `agent_guidance`。普通项目没有 `service_execution_id`，instruction 要求先检查 canonical Cart，next 为：
+
+```json
+{
+  "command": "itpay cart next --json",
+  "reason": "检查 canonical Cart"
+}
+```
+
+显式 `--local` 使用独立合同：
+
+```json
+{
+  "status": "added_local",
+  "result": {
+    "catalog_item_id": "<item_id>",
+    "catalog_variant_id": "<variant_id>",
+    "offer_id": "<offer_id>",
+    "quantity": 1
+  },
+  "instruction": "仅写入本地兼容草稿，未验证目录、价格或服务合同；不要把它当作 canonical Cart。",
+  "next": { "command": "itpay cart show --local", "reason": "检查本地草稿" },
+  "recovery": []
+}
+```
+
+Quote 模式返回：
+
+```json
+{
+  "status": "quote_added",
+  "result": { "cart_id": "<cart_id>", "item_count": 3, "total": "<amount> <currency>" },
+  "instruction": "付费服务报价已加入同一 Cart；每个项目仍保持独立 Execution 和交付。",
+  "next": { "command": "itpay buy --cart <cart_id> --json", "reason": "确认项目齐全后创建一次合并付款" },
+  "recovery": [{ "command": "itpay cart show --json", "reason": "检查当前合并 Cart" }]
+}
+```
+
+## 异常处理
+
+缺少 ID、两种模式混用、非法 quantity、非 object JSON 和缺少 Host target 必须在任何写入/HTTP 前失败。目录不匹配、Quote 过期/跨身份/已消费或 Cart 已锁定由服务端事务拒绝，不得留下半成品 line。错误使用统一 envelope，recovery 指向 `services next`、`catalog list` 或当前 `cart show`。
+
+## Agent Type / Host
+
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种类型都写入真实 Agent Type。默认 Host 分别是 `codex`、`terminal`、`claude-code`、`terminal`、`plain-chat`。业务输出合同相同；此命令本身不显示二维码。

package/docs/cli-reference/commands/cart/clear.md

@@ -0,0 +1,53 @@
+# `itpay cart clear`
+
+## 范围与意义
+
+放弃未锁定的 canonical cart。`--local` 只清理本地句柄和草稿，不声称服务端资源已取消。
+
+**上游：** 用户明确放弃购物车。
+**下游：** `catalog list`。
+
+## 语法与参数
+
+```bash
+itpay cart clear [--local] [--json]
+```
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `--local` | 否 | 只清除本地草稿与恢复句柄；不请求或修改 Backend。 |
+| `--json` | 否 | 输出标准 JSON envelope。 |
+
+不带 `--local` 时只操作 canonical Cart。缺少 Cart 句柄会返回 `cart_handle_missing`，不会静默退化为本地清理。
+
+## 标准输出
+
+```json
+{
+  "status": "abandoned",
+  "result": { "cart_id": "<cart_id>", "server_abandoned": true },
+  "instruction": "canonical Cart 已放弃；Backend 已在同一事务中软删除 active lines，并取消其未付款 Service Execution。",
+  "next": { "command": "itpay catalog list --json", "reason": "仅在用户提出新需求时重新选择" },
+  "recovery": []
+}
+```
+
+本地清理返回：
+
+```json
+{
+  "status": "cleared_local",
+  "result": { "server_abandoned": false, "local_state_cleared": true },
+  "instruction": "仅清除了本地草稿和恢复句柄；Backend Cart、Checkout 和 Service Execution 均未改变。",
+  "next": { "command": "itpay catalog list --json", "reason": "仅在用户提出新需求时重新选择" },
+  "recovery": []
+}
+```
+
+## 异常处理
+
+已锁定 Cart 不可放弃时保留本地 Cart、line、execution 和 Checkout 句柄，返回 Backend 的错误 code（通常为 `cart_item_locked`）并引导 `itpay cart next --json`。不得通过清理本地状态伪装 Backend 已放弃。
+
+## Agent Type / Host
+
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 行为相同。

package/docs/cli-reference/commands/cart/index.md

@@ -0,0 +1,30 @@
+# `itpay cart`
+
+## 命令范围
+
+管理 canonical server Cart。Catalog line 可以创建 Service Execution；已准备好的 Service Quote 则通过 `cart add --quote` 加入 Cart。Cart 聚合交易，但不合并 Execution、候选归属或交付。
+
+**上游：** Catalog item、variant、offer 和服务输入。
+**下游：** Service Execution、Quote 聚合或 `buy`。
+
+## 子命令
+
+- [`cart add`](add.md)
+- [`cart next`](next.md)
+- [`cart remove`](remove.md)
+- [`cart show`](show.md)
+- [`cart clear`](clear.md)
+
+`--local` 只用于显式本地草稿兼容，不得用于 service-backed flow。直接运行 `itpay cart` 显示 help。
+
+## 语法、输出与异常
+
+```bash
+itpay cart --help
+```
+
+输出五个子命令及 canonical server cart 的说明，instruction 是未知状态先运行 `cart next`。未知子命令返回参数错误；不得因此清理本地 cart。
+
+## Agent Type / Host
+
+Cart 事实在 `codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 下相同；`add` 创建 client context 时记录真实 Agent Type 和 Host。

package/docs/cli-reference/commands/cart/next.md

@@ -0,0 +1,71 @@
+# `itpay cart next`
+
+## 范围与意义
+
+读取当前 canonical cart 对应的唯一首选动作。它不修改 cart。
+
+**上游：** `cart add` 或中断的 cart 流程。
+**下游：** 返回的 `services next`、`buy` 或 `catalog list`。
+
+## 语法与参数
+
+```bash
+itpay cart next [--json]
+```
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `--json` | 否 | 输出单个标准 JSON envelope；默认输出相同事实的简洁文本。 |
+
+命令读取本地保存的 canonical Cart ID，再通过签名 Agent Device session 读取该 Cart。它不接受 Cart ID 参数，也不修改 Cart。
+
+## 标准输出
+
+```json
+{
+  "status": "action_available",
+  "result": {
+    "cart_id": "<cart_id>",
+    "cart_status": "<status>",
+    "service_execution_id": "<service_execution_id>"
+  },
+  "instruction": "该 Cart 包含 service-backed line；继续 Service Execution，不要从 Cart 猜 capability。",
+  "next": {
+    "command": "itpay services next <service_execution_id> --json",
+    "reason": "读取服务端最新执行状态"
+  },
+  "recovery": []
+}
+```
+
+若存在尚未报价的 service-backed line，选择最后一条并返回 `services next`；不跳过 Execution 直接猜 capability。若所有服务行都已绑定 Quote，则返回 Cart 的 item count、总额和 `buy --cart`，允许一次 Checkout 支付多个独立任务。
+
+普通非 service-backed Cart 返回 `item_count`、金额和币种，下一步为：
+
+```text
+itpay buy --cart <cart_id> --json
+```
+
+空 Cart 返回 `cart_empty`，下一步为 `itpay catalog list --json`。
+
+## 异常处理
+
+本地没有 Cart 句柄时不访问 Backend：
+
+```json
+{
+  "status": "cart_handle_missing",
+  "result": {},
+  "instruction": "本地没有 canonical Cart 句柄；先恢复已有资源，不要创建重复 Cart。",
+  "next": { "command": "itpay next --json", "reason": "检查其他可恢复句柄" },
+  "recovery": [
+    { "command": "itpay services list --json", "reason": "从服务端恢复当前设备的执行" }
+  ]
+}
+```
+
+服务端 Cart 不存在、不可访问或 Backend 不可用时返回错误 envelope，不清理本地状态，也不创建替代 Cart。首选 recovery 是 `itpay services list --json`；没有可恢复执行时再运行 `itpay catalog list --json`。
+
+## Agent Type / Host
+
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 的业务字段、instruction 和 next 相同。本命令不产生二维码或 Host handoff。

package/docs/cli-reference/commands/cart/remove.md

@@ -0,0 +1,53 @@
+# `itpay cart remove`
+
+## 范围与意义
+
+从未锁定的 canonical cart 删除一个 line。删除不会影响已创建的 Checkout 或订单；如果该 line 是某个未付款 Service Execution 在 Cart 中的最后一个引用，Backend 会在同一事务中取消该 execution。
+
+**上游：** `cart show` 返回的 `cart_item_id`。
+**下游：** `cart next`。
+
+## 语法与参数
+
+```bash
+itpay cart remove [--line <cart_item_id>] [--json]
+itpay cart remove --local --variant <catalog_variant_id> --offer <offer_id> [--json]
+```
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `--line <cart_item_id>` | 否 | canonical Cart line；省略时使用当前 Backend URL 下最后保存的 line。 |
+| `--local` | 否 | 只修改显式本地草稿，不请求 Backend。 |
+| `--variant <catalog_variant_id>` | local 时是 | 与 `--offer` 一起标识本地草稿 line。 |
+| `--offer <offer_id>` | local 时是 | 与 `--variant` 一起标识本地草稿 line。 |
+| `--json` | 否 | 输出标准 JSON envelope。 |
+
+`--line` 不能与 `--local` 混用；`--variant/--offer` 只能与 `--local` 同用。参数在网络请求前完成校验。
+
+## 标准输出
+
+```json
+{
+  "status": "removed",
+  "result": {
+    "cart_id": "<cart_id>",
+    "cart_item_id": "<line_id>",
+    "remaining_item_count": 0
+  },
+  "instruction": "canonical Cart 已更新；最后一个 service-backed 引用由服务端一致性事务取消。",
+  "next": { "command": "itpay cart next --json", "reason": "检查剩余内容" },
+  "recovery": []
+}
+```
+
+显式本地草稿返回 `status: "removed_local"`，下一步固定为 `itpay cart show --local --json`，并明确说明它未验证服务端状态。
+
+## 异常处理
+
+quote/checkout 已锁定时返回 `cart_item_locked`，要求继续已有 Checkout；不得通过清本地状态假装服务端已删除。
+
+成功后 CLI 使用 Backend 返回的剩余 Cart 重新同步本地 line/execution 句柄。删除最后一行后，顶层 `itpay next --json` 必须回到 Cart，而不能路由到已经取消的 Service Execution。
+
+## Agent Type / Host
+
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 行为相同。

package/docs/cli-reference/commands/cart/show.md

@@ -0,0 +1,65 @@
+# `itpay cart show`
+
+## 范围与意义
+
+显示 canonical server cart 的紧凑摘要和 line 句柄。默认不展开完整 Service Execution。
+
+**上游：** cart 创建或恢复。
+**下游：** `cart next`、`cart remove` 或 `services next`。
+
+## 语法与参数
+
+```bash
+itpay cart show [--json] [--local]
+```
+
+默认只读取本地保存的 canonical Cart 句柄并调用服务端。`--local` 只查看显式本地兼容草稿，不发 HTTP，也不会把该草稿解释成 canonical Cart。
+
+## 标准输出
+
+```json
+{
+  "status": "shown",
+  "result": {
+    "cart_id": "<cart_id>",
+    "status": "<status>",
+    "amount": "<amount> <currency>",
+    "items": [{ "cart_item_id": "<id>", "title": "<title>", "quantity": 1, "service_execution_id": "<optional_id>" }]
+  },
+  "instruction": "使用 line 或 execution 句柄继续，不要使用内部 quote lock ID。",
+  "next": { "command": "itpay cart next --json", "reason": "取得当前首选动作" },
+  "recovery": []
+}
+```
+
+canonical 输出不得包含 Catalog variant/offer、line input、Service quote lock、完整 Service Execution 或重复 guidance。空 Cart 的 next 改为 `catalog list --json`。
+
+显式 local draft 返回 `shown_local` 或 `local_empty`：
+
+```json
+{
+  "status": "shown_local",
+  "result": {
+    "currency": "CNY",
+    "items": [
+      {
+        "catalog_item_id": "<item_id>",
+        "catalog_variant_id": "<variant_id>",
+        "offer_id": "<offer_id>",
+        "quantity": 1
+      }
+    ]
+  },
+  "instruction": "这是未验证的本地兼容草稿，只能用于明确的普通商品流程；不要把它当作 canonical Cart。",
+  "next": { "command": "itpay buy --json", "reason": "将普通本地草稿提交为 canonical Cart" },
+  "recovery": []
+}
+```
+
+## 异常处理
+
+没有 canonical 句柄时返回 `cart_handle_missing`，next 为 `catalog list --json`，recovery 可显式检查 `cart show --local --json`。服务端句柄过期或无权访问时保持不透明错误，recovery 指向 `services list` 和 Catalog；不得静默回退到 local draft。
+
+## Agent Type / Host
+
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 行为相同。

package/docs/cli-reference/commands/catalog/index.md

@@ -0,0 +1,26 @@
+# `itpay catalog`
+
+## 命令范围
+
+读取已发布的服务目录，帮助 Agent 发现可启动的通用服务。Catalog 只描述产品和入口，不执行服务、不创建购物车。
+
+**上游：** `readyz`。
+**下游：** [`catalog list`](list.md)，然后按目录中的 `service_id` 使用 `services start`。
+
+## 子命令
+
+- [`itpay catalog list`](list.md) - 列出当前已发布服务、用途、辅助能力、主服务和价格。
+
+直接运行 `itpay catalog` 时显示本页等价的简短 help，不请求 API。
+
+## 语法、输出与异常
+
+```bash
+itpay catalog --help
+```
+
+直接运行时输出子命令、用途和 `catalog list` 示例，instruction 是选择 `list`；不返回 Catalog 内容。未知子命令返回 Commander 参数错误和 `itpay catalog --help` recovery。
+
+## Agent Type / Host
+
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种支持类型的目录事实完全相同。instruction 可按 Agent Type 调整措辞，但不得改变服务排序、价格或可用能力。

package/docs/cli-reference/commands/catalog/list.md

@@ -0,0 +1,45 @@
+# `itpay catalog list`
+
+## 范围与意义
+
+列出当前 published Catalog。每个项目先说明用户真正购买的主服务，再说明免费或付费的辅助能力，避免把辅助消歧误称为最终服务。
+
+**上游：** `readyz`。
+**下游：** `services start <service_id>`。
+
+## 语法与参数
+
+```bash
+itpay catalog list [--json]
+```
+
+## 标准输出
+
+```json
+{
+  "status": "listed",
+  "result": {
+    "catalog_version": "<version>",
+    "services": [
+      {
+        "service_id": "<service_id>",
+        "title": "<product title>",
+        "description": "<what the user receives>",
+        "discovery": { "title": "<helper title>", "description": "<optional helper>", "free_quota": 3, "paid_price": "<optional price>" },
+        "primary_offer": { "title": "<offer title>", "description": "<deliverable>", "price": "<price>" }
+      }
+    ]
+  },
+  "instruction": "向用户解释主服务、辅助步骤和价格；得到用户意图后再启动对应 service_id。",
+  "next": { "command": "itpay services start <service_id>", "reason": "启动用户选择的服务" },
+  "recovery": []
+}
+```
+
+## 异常处理
+
+输出不得包含 snapshot、manifest 原文、compiled graph 或 Provider secret。服务为空时返回 `catalog_empty`，要求稍后重试，不猜服务 ID。
+
+## Agent Type / Host
+
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 使用同一产品内容；只允许排版不同。

package/docs/cli-reference/commands/checkout.md

@@ -0,0 +1,74 @@
+# `itpay checkout`
+
+## 范围与意义
+
+读取并恢复一笔已存在 Checkout 的公开展示状态。它不创建新 Checkout，也不把“用户说已付款”当作付款成功。
+
+**上游：** `buy` 或 `services checkout` 返回的 `checkout_id` 与 display token。
+**下游：** 继续授权/付款、读取关联 Service Execution，或结束等待。
+
+## 语法与参数
+
+```bash
+itpay checkout [--id <checkout_id>] [--token <display_token>]
+  [--host <host>] [--target <target>] [--json]
+```
+
+省略 `--id/--token` 时只能使用本机保存的一组完整句柄；不得把其他 Checkout 的 token 拼接使用。
+
+`--host` 默认由 `--agent-type` 决定。`--target` 为现有 IM Host 兼容参数；当前五种 Agent Type 不需要它。`--json` 输出机器可读合同，不内嵌二维码字符画或图片二进制。
+
+## 等待付款输出
+
+```json
+{
+  "status": "human_checkout_required",
+  "result": { "checkout_id": "<checkout_id>", "payment": "pending", "amount": "<amount> <currency>" },
+  "handoff": { "url": "<checkout_url>", "qr_local_path": "<host_optional_path>", "markdown": "<desktop_optional_markdown>" },
+  "instruction": "把当前 Host 的二维码和付款链接展示给用户，然后等待用户操作；不要创建新 Checkout。",
+  "next": { "command": "itpay checkout --id <checkout_id> --token <display_token>", "reason": "稍后查询同一笔 Checkout 状态" },
+  "recovery": []
+}
+```
+
+## 已完成输出
+
+```json
+{
+  "status": "completed",
+  "result": { "checkout_id": "<checkout_id>", "payment": "verified", "order_id": "<optional_order_id>", "service_execution_id": "<optional_id>" },
+  "instruction": "付款已确认，不要再次展示付款二维码。",
+  "next": { "command": "itpay services next <service_execution_id> --json", "reason": "读取履约状态" },
+  "recovery": []
+}
+```
+
+已完成状态不得请求 QR PNG、生成二维码、输出附件指令或建议 `pay`。如果 Checkout 包含一个 Service Execution，下一步读取该 execution；通用订单则读取 `order_id`。`refunded`、`failed`、`expired` 同样不生成 handoff，只返回服务端终态和可用恢复方向。
+
+## 异常处理
+
+token 缺失或不匹配时使用本机句柄恢复。只有请求的 Checkout 正是本机保存的 Service Checkout 时，才返回对应 `services checkout <service_execution_id> --resume --json`；否则返回 `services list`，不能把另一个 execution 的 token 拼上去，也不能跳到 cart 或新建付款。
+
+```json
+{
+  "status": "error",
+  "error": { "code": "checkout_unavailable", "message": "<missing_or_mismatched_handle>" },
+  "instruction": "使用同一笔 Checkout 的完整 checkout_id 与 display token；不要拼接不同 Checkout 的句柄。",
+  "next": null,
+  "recovery": [{ "command": "itpay services list --json", "reason": "查找当前设备可恢复的 Service Execution" }]
+}
+```
+
+## Agent Type / Host
+
+等待付款时：
+
+| Agent Type | Handoff |
+|---|---|
+| `codex-desktop` | `url, qr_local_path, markdown`；原样发送 Markdown。 |
+| `codex-cli` | `url, qr_local_path`；普通文本模式渲染终端二维码。 |
+| `claude-code-desktop` | `url, qr_local_path, markdown`；原样发送 Markdown。 |
+| `claude-code-cli` | `url, qr_local_path`；普通文本模式渲染终端二维码。 |
+| `workbuddy` | `url, qr_local_path, qr_image_url`；发送链接和可用附件。 |
+
+完成、退款或失效状态下五种 Agent Type 都只返回同一状态和下一步，不渲染二维码。

package/docs/cli-reference/commands/docs/index.md

@@ -0,0 +1,28 @@
+# `itpay docs`
+
+## 命令范围
+
+浏览 npm 包内置的 Agent 操作文档。它是运行时自助说明，不读取服务端业务数据。
+
+**上游：** CLI 安装。
+**下游：** 选择并读取一个 topic。
+
+## 子命令
+
+- [`docs list`](list.md) - 列出 topic
+- [`docs show`](show.md) - 显示完整 topic
+- [`docs search`](search.md) - 按关键词查 topic
+
+直接运行 `itpay docs` 只显示 help。
+
+## 语法、输出与异常
+
+```bash
+itpay docs --help
+```
+
+输出三个子命令的一行用途，instruction 是先 `list` 或按关键词 `search`。未知子命令只返回参数错误和本 help，不读取文档目录。
+
+## Agent Type / Host
+
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 使用同一文档源；topic 内容可以包含各类型专属 section。

package/docs/cli-reference/commands/docs/list.md

@@ -0,0 +1,51 @@
+# `itpay docs list`
+
+## 范围与意义
+
+按稳定 topic 名称列出 npm 包内置的 Agent 文档，只返回标题和一句用途，不加载完整内容，也不访问 Backend。
+
+**上游：** `install`，或 Agent 不确定应查看哪个流程。
+
+**下游：** 选择一个 topic 后执行 `docs show <topic>`。
+
+## 语法与参数
+
+```bash
+itpay docs list [--json]
+```
+
+`--json` 返回标准命令 envelope；无筛选、分页或网络参数。topic 按名称稳定升序排列。
+
+## 标准输出
+
+```json
+{
+  "status": "listed",
+  "result": {
+    "topics": [
+      {
+        "topic": "<topic>",
+        "title": "<title>",
+        "purpose": "<one-line purpose>"
+      }
+    ]
+  },
+  "instruction": "选择与当前步骤最接近的一个 topic；不要一次加载全部文档。",
+  "next": null,
+  "recovery": []
+}
+```
+
+列表不替 Agent 选择 topic，因此不返回含 placeholder 的假命令。选定后执行：
+
+```bash
+itpay docs show <topic> --json
+```
+
+## 异常处理
+
+随包文档目录缺失、文件损坏或合同字段不完整时返回 `docs_unavailable`，不暴露本地包路径；recovery 固定为重新安装当前 CLI 版本。
+
+## Agent Type / Host
+
+五种正式 Agent Type 返回相同结果。本命令没有 Host 渲染、设备登记或本地业务状态写入。

package/docs/cli-reference/commands/docs/search.md

@@ -0,0 +1,69 @@
+# `itpay docs search`
+
+## 范围与意义
+
+在内置 topic 的名称、标题、用途和 `search_terms` 中进行不区分大小写的包含搜索。它不搜索完整正文或业务数据。
+
+**上游：** Agent 知道问题关键词，但不知道稳定 topic。
+
+**下游：** 唯一匹配时直接 `docs show`；多匹配时由 Agent 选择一个。
+
+## 语法与参数
+
+```bash
+itpay docs search <query> [--json]
+```
+
+`query` 必须是非空关键词；`--json` 返回标准命令 envelope。
+
+## 唯一匹配
+
+```json
+{
+  "status": "matched",
+  "result": {
+    "query": "render-hosts",
+    "topics": [
+      {
+        "topic": "render-hosts",
+        "title": "Host Rendering And Interaction Requests",
+        "purpose": "<one-line purpose>"
+      }
+    ]
+  },
+  "instruction": "已唯一匹配；读取该 topic。",
+  "next": {
+    "command": "itpay docs show render-hosts --json",
+    "reason": "读取唯一匹配文档"
+  },
+  "recovery": []
+}
+```
+
+## 多匹配
+
+返回所有匹配 topic 的同样三字段摘要，`instruction` 要求只选择一个，`next` 为 `null`。CLI 不以文件顺序替 Agent 猜选项。
+
+## 无匹配
+
+```json
+{
+  "status": "no_match",
+  "result": {
+    "query": "<query>",
+    "topics": []
+  },
+  "instruction": "没有匹配文档；缩短关键词，或列出全部 topic。",
+  "next": {
+    "command": "itpay docs list --json",
+    "reason": "浏览稳定 topic"
+  },
+  "recovery": []
+}
+```
+
+空字符串返回 `docs_query_required`；随包文档损坏返回 `docs_unavailable`。
+
+## Agent Type / Host
+
+五种正式 Agent Type 行为相同。本命令不产生 Host handoff。