# bizX402 Buyer Toolkit：AI 安装与调用规范

本文档供人类用户和 AI Agent 直接读取。目标是安装 `bizx402` CLI 与 `bizx402-mcp`，完成服务发现、报价、人工授权后的付费调用和结果查询。

## AI 必须遵守的安全规则

1. 可以执行安装、校验、`doctor`、搜索、描述和报价等只读步骤。
2. 不得索取、读取、记录、复制或传输用户私钥。
3. 不得把私钥放进命令参数、JSON、环境变量、MCP 配置、聊天消息或日志。
4. 需要配置 Signer 时必须停止，让用户本人在可信交互终端执行 `bizx402 signer import`。
5. 每次付费前必须向用户展示 `serviceRef`、`network`、`amountAtomic` 和 `maxAmountAtomic`，并等待用户明确确认。
6. 不得默认增加 `--yes`。只有用户已看到当前报价并明确要求非交互执行时才可使用；金额硬上限仍必须保留。
7. 只能读取用户明确授权的文件路径。MCP 必须通过 `--file-root` 限定可读目录。

## 当前环境

- Service Portal：`https://402demo.smallfishpte.com/`
- Marketplace API：`https://demo-api-1.smallfishpte.com`
- Toolkit 安装器：`https://demo-api-1.smallfishpte.com/downloads/bizx402/install.sh`
- 当前 Demo Toolkit：`0.1.0`
- 支持平台：macOS arm64 / amd64、Linux arm64 / amd64
- 当前 CLI 付款模式：EXACT
- Demo 支付网络：Base Sepolia
- Demo 支付资产：测试 USDC

安装器通过 `uname -s` 和 `uname -m` 自动选择发行包：

| 操作系统 / CPU | 安装器选择 |
| --- | --- |
| macOS Apple Silicon | `darwin_arm64` |
| macOS Intel | `darwin_amd64` |
| Linux arm64 / aarch64 | `linux_arm64` |
| Linux x86_64 / amd64 | `linux_amd64` |

Windows 当前不受 0.1.0 安装器支持，AI 不得在 Windows 上套用 Unix 安装命令。

产品版本和价格可能变化。必须先搜索和报价，不要长期写死本文示例中的 `@3` 或 `10000`。

## 1. 安装

不要直接使用 `curl | sh`。先下载并检查安装脚本：

```bash
curl -fsS https://demo-api-1.smallfishpte.com/downloads/bizx402/install.sh \
  -o /tmp/bizx402-install.sh
sed -n '1,240p' /tmp/bizx402-install.sh
sh /tmp/bizx402-install.sh
export PATH="$HOME/.local/bin:$PATH"
bizx402 version
bizx402 doctor
```

安装器会选择当前操作系统和 CPU 架构的发行包，并校验 SHA-256。安装后得到：

- `bizx402`：Buyer CLI
- `bizx402-mcp`：本地 stdio MCP Server

### 直接下载

如果不使用自动安装器，可以下载与系统匹配的发行包。每个压缩包都包含 `bizx402` 与 `bizx402-mcp`：

| 操作系统 / CPU | 下载地址 |
| --- | --- |
| macOS Apple Silicon | [bizx402_0.1.0_darwin_arm64.tar.gz](https://demo-api-1.smallfishpte.com/downloads/bizx402/releases/0.1.0/bizx402_0.1.0_darwin_arm64.tar.gz) |
| macOS Intel | [bizx402_0.1.0_darwin_amd64.tar.gz](https://demo-api-1.smallfishpte.com/downloads/bizx402/releases/0.1.0/bizx402_0.1.0_darwin_amd64.tar.gz) |
| Linux arm64 / aarch64 | [bizx402_0.1.0_linux_arm64.tar.gz](https://demo-api-1.smallfishpte.com/downloads/bizx402/releases/0.1.0/bizx402_0.1.0_linux_arm64.tar.gz) |
| Linux x86_64 / amd64 | [bizx402_0.1.0_linux_amd64.tar.gz](https://demo-api-1.smallfishpte.com/downloads/bizx402/releases/0.1.0/bizx402_0.1.0_linux_amd64.tar.gz) |

校验文件：[SHA256SUMS](https://demo-api-1.smallfishpte.com/downloads/bizx402/releases/0.1.0/SHA256SUMS)

手工安装时，先用 `SHA256SUMS` 校验下载文件，再解压并把两个二进制复制到 `$HOME/.local/bin`。不要根据聊天内容猜测或跳过校验。

若 `bizx402` 不在 PATH，请运行：

```bash
export PATH="$HOME/.local/bin:$PATH"
```

如需永久生效，由用户自行把这行加入当前 Shell 的配置文件。

## 2. 只读发现与报价

先运行：

```bash
bizx402 doctor
bizx402 services search 图片安全
```

从搜索结果读取最新 `serviceRef`，然后描述并报价。当前示例为：

```bash
bizx402 services describe image-guard-security-scan@3
bizx402 quote image-guard-security-scan@3
```

在继续付费前，向用户清楚展示：

- `serviceRef`
- 产品名称和输入要求
- `network`
- `asset` / `symbol`
- `amountAtomic`
- 将要使用的 `maxAmountAtomic`

当前 Demo Image Guard 曾验证为 `image-guard-security-scan@3`、Base Sepolia、`10000` atomic USDC（0.01 USDC）、JPEG/PNG 最大 8 MiB。必须以当前命令返回值为准。

## 3. 用户本人导入 Signer

AI 在这里停止，并要求用户在可信交互终端亲自运行：

```bash
bizx402 signer import
bizx402 signer status
```

私钥输入会隐藏，并只保存到操作系统 Keychain。CLI 不接受通过参数、JSON 或环境变量传入私钥；MCP Tool Schema 也不包含私钥。

用户还需要确保 `signer status` 返回的地址持有足够的 Base Sepolia 测试 USDC。不要向 Demo 地址转入主网资产。

## 4. 调用 Image Guard

再次确认最新 `serviceRef` 和报价。把文件路径替换为用户明确授权的本机 JPEG 或 PNG：

```bash
bizx402 call image-guard-security-scan@3 \
  --file file=./sample.png \
  --max-amount-atomic 10000
```

默认情况下 CLI 会显示支付内容并等待终端确认。`maxAmountAtomic` 是硬支出上限，必须与用户确认的上限一致。

Image Guard 是异步文件安全扫描，不是 OCR、物体识别或视觉问答。付费调用成功后：

1. 从返回 JSON 读取 `response.id`。
2. 轮询下列地址，直到 `terminal=true`：

```bash
curl -fsS https://tools.smallfishpte.com/v1/images/<response.id>
```

3. 读取最终 verdict。只有 CLEAN 内容才应继续下载或交给后续流程。

当前通用 Execution Worker 尚未为 CLI 自动完成这段 Provider 轮询。

## 5. MCP 配置

先查找二进制绝对路径：

```bash
command -v bizx402-mcp
```

把结果和用户批准的图片目录写入 MCP 客户端配置：

```json
{
  "mcpServers": {
    "bizx402": {
      "command": "/absolute/path/to/bizx402-mcp",
      "args": [
        "--file-root",
        "/absolute/path/to/approved-images"
      ],
      "env": {
        "BIZX402_BASE_URL": "https://demo-api-1.smallfishpte.com",
        "BIZX402_PROFILE": "default"
      }
    }
  }
}
```

绝对不要把私钥写进 MCP 配置。MCP Server 只按 Profile 从操作系统 Keychain 读取 Signer；文件解析后的真实路径必须位于 `--file-root` 内。

MCP 暴露五个固定工具：

- `search_services`
- `describe_service`
- `quote_service`
- `call_service`
- `get_order`

推荐的 Agent 调用顺序：

1. `search_services`
2. `describe_service`
3. `quote_service`
4. 向用户展示报价、网络和最大金额，等待明确批准
5. `call_service`
6. `get_order`
7. 若 Provider 是 Image Guard，再按 `response.id` 查询 Provider 异步状态

## 6. 当前能力边界

已支持：

- 服务搜索、描述和报价
- 版本化 `serviceRef`
- EXACT x402 付费调用
- 本地 Keychain Signer
- 订单查询
- 本地 stdio MCP
- Image Guard 文件参数与付费调用

尚未支持：

- CLI 的 BATCH 充值通道
- 远程 Streamable HTTP MCP 与 OAuth
- WalletConnect、硬件钱包、KMS/HSM 或远程 Signer
- Image Guard 的通用自动轮询
- OCR、物体分类或视觉问答

## 7. 完成标准

在没有付费授权时，AI 完成以下步骤即应停止：

- Toolkit 安装成功
- `bizx402 version` 返回版本号
- `bizx402 doctor` 表明 Catalog 可达
- 搜索、描述和报价成功
- 已向用户说明 Signer 导入方式和资金要求
- 未读取、请求或保存任何私钥

只有用户本人完成 Signer 导入并明确批准当前报价和金额上限后，AI 才能继续付费调用。