@zan_team/cli 0.0.0-stage → 0.0.1

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@zan_team/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "Unified ZAN command-line interface for developers, automation, and AI agents",
+  "type": "module",
+  "bin": {
+    "zan": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/cli.ts",
+    "cli:local": "node scripts/zan-dev.mjs",
+    "cli:dev": "tsx scripts/run-cli-env.ts dev",
+    "cli:sit": "tsx scripts/run-cli-env.ts sit",
+    "cli:pre": "tsx scripts/run-cli-env.ts pre",
+    "cli:prod": "tsx scripts/run-cli-env.ts prod",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --coverage",
+    "test:unit": "vitest run tests/unit",
+    "test:integration": "vitest run tests/integration",
+    "test:cli": "pnpm build && vitest run tests/cli",
+    "test:package": "node scripts/package-manager.mjs build && node scripts/test-package.mjs",
+    "release": "tsx scripts/release.ts",
+    "release:major": "tsx scripts/release.ts --kind=major",
+    "release:minor": "tsx scripts/release.ts --kind=minor",
+    "release:patch": "tsx scripts/release.ts --kind=patch",
+    "release:beta": "tsx scripts/release.ts --kind=beta"
+  },
+  "dependencies": {
+    "commander": "^14.0.3",
+    "cross-keychain": "^1.1.0",
+    "qrcode-terminal": "^0.12.0",
+    "viem": "^2.56.3",
+    "yaml": "^2.9.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "@types/qrcode-terminal": "^0.12.2",
+    "@vitest/coverage-v8": "^4.0.18",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "packageManager": "pnpm@10.11.0",
+  "repository": "https://code.alipay.com/antchain-fe/zan-cli.git",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/skills/zan-cli/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: zan-cli
+description: 使用 ZAN CLI（zan / @zan_team/cli）完成登录、项目选择、套餐用量查询、按 ZAN 官方文档调用 RPC、签名和应用 API Key 配置。用户要求通过 ZAN 获取链上数据、查询项目额度、接入 ZAN API、管理钱包或排查 zan 调用时使用；不用于无关的区块链问答或普通代码开发。
+---
+
+# ZAN CLI
+
+通过 CLI 完成用户请求：确认登录有效，按任务选择项目与命令。套餐用量查询使用 `usage`；链上查询再选择 Network 并按 ZAN 文档组装调用；需要签名时选择签名方式。只有目标项目的应用代码需要直接调用 ZAN API 时，才额外将 API Key 安全写入该项目的 `.env`。
+
+仅通过 CLI 查询链上信息时，登录并选好 Project 和相应 Network 即可，CLI 会在内部取得和使用凭据，不依赖应用 `.env`。不要执行 `project rpc-key pull`，也不要为了查询创建或修改 `.env`。即使正在项目目录里工作，或代码只是调用 CLI，也不因此需要导出 Key。
+
+这套流程用于执行 ZAN 业务任务。仅查看帮助或列出能力时，不触发登录、项目创建、签名或 Key 写入。会话内已完成且仍有效的选择和授权可复用，不重复询问。
+
+## 选择运行入口
+
+- 已安装 npm 包时使用 `zan`，要求 Node.js 22 或以上。
+- 首次使用某个版本时运行 `zan --json --no-interactive agent manifest`，按需查看 `zan <command> --help`。以当前版本列出的命令和参数为准。
+
+## 调用约定
+
+自动化业务命令使用 `--json --no-interactive`，全局参数放在子命令之前：
+
+```sh
+zan --json --no-interactive --project <project-id> --network <network-id> evm rpc eth_blockNumber
+```
+
+成功结果直接在 stdout 输出一个 JSON 值，没有统一的 `data` 包装；失败读取退出码和 stderr 的 `error.code`、`message`、`hint`、`retryable`。登录授权期间 stderr 还可能输出授权提示事件，不应将整个登录 stderr 当作单个错误对象。
+
+## 1. 登录并验证有效性
+
+先运行 `zan --json --no-interactive inspect` 和 `zan --json --no-interactive auth status`。`inspect` 只是本地检查，`ready: false` 也可能正常退出；缺少 Project/Network 不妨碍登录和列出项目，缺少 Network 也不影响 `usage`。`auth status` 的 `authenticated: true` 只表示存在本地会话，不能据此认定登录未过期。
+
+1. 未登录：说明需要用户授权，进入 `auth login`。用户交互终端可用 `zan auth login`；Agent 使用 `zan --json --no-interactive auth login --device-code`，展示验证链接与用户码并等待本次授权完成。
+2. 已登录：检查 `expiresAt` 是否已过期。未过期或没有该字段时执行 `zan --json --no-interactive auth status --verify` 在线验证，不猜测有效性。
+3. 已过期、验证返回 `AUTH_EXPIRED` 或明确表示会话失效：重新登录，使用 `auth login --force`，Agent 场景加 `--device-code`。普通 `auth login` 可能复用失效的本地会话；`--force` 会替换会话并清理 Endpoint 缓存，后续重新选择项目，由 CLI 重新获取调用所需凭据，无需导出到 `.env`。
+4. 用户完成授权、命令成功后再继续。拒绝或超时则暂停依赖认证的步骤；网络异常或 scope 不足不等于登录过期，应按实际错误处理，不循环重登。
+
+## 2. 让用户选择 Project
+
+查询套餐用量时直接按下方“查询当前项目套餐用量”执行；需要链上调用时使用本节的项目与 Network 选择流程。
+
+执行 `zan --json --no-interactive project list`，展示项目名称与 ID，并提供“选择已有项目”或“创建新项目”的选择。不能仅因为有本地默认项目或只有一个项目就代替用户决定；用户在请求或当前会话中已明确选择时，核对列表后直接复用。
+
+用户选择创建时确定名称，执行 `project create --name <name>`，使用返回的 ID。不要未经选择自动创建项目。创建不会自动切换 Project。
+
+确定后执行 `project use <project-id>`，验证项目并建立加密 Endpoint 缓存；再执行 `--project <project-id> evm networks` 获取可用 Network。按用户指定的链、主网/测试网匹配实际 Network ID；有歧义再询问，不猜 ID。后续命令显式带所选 `--project`，链上调用同时带 `--network`，避免残留环境变量切换上下文。只有用户需要持久默认 Network 时才执行 `settings set network <id>`。
+
+凭据存储由 CLI 管理：包含服务端 API Key 的 Endpoint 数据保存在本地加密缓存中，缓存加密密钥保存在系统凭据库（macOS Keychain）。不要把这理解为必须先将 API Key 导出到文件，Agent 也不需要读取这些凭据。
+
+### 查询当前项目套餐用量
+
+用户明确请求“当前项目”的使用情况时，可直接复用当前 Project 设置，执行
+`zan --json --no-interactive usage`；指定项目时带 `--project <project-id>`。
+项目选择优先级为 `--project` > `ZAN_PROJECT` > 本地设置，结果中的 `project` 用于确认实际查询对象。
+无需重新选择项目、查询 Network、配置钱包或导出 Key，跳过下方 RPC 文档步骤。
+返回缺少项目的 `SETUP_REQUIRED` 时，运行 `project list` 让用户选择，再用
+`zan --json --no-interactive --project <project-id> usage` 查询，不必执行会拉取 Endpoint 的 `project use`。
+
+结果中的 `keyUsage` 为项目 Key 的累计消耗/限额，`plan` 为账号共享套餐的名称、
+已用/总量、剩余量、过期及刷新时间。额度是十进制字符串，单位 credits；不能把
+Key 累计用量当作共享套餐周期用量。无 Key 限额不代表套餐无限；`plan: null` 表示无订阅。
+`plan.expiresAt` 是套餐到期时间，`refreshAt` 是权益周期刷新时间，未知时间为 null，不能解释为永久有效。
+剩余为 0 表示该口径的额度已耗尽；订阅/服务状态仍需结合 `status`、`serviceStatus` 和到期时间判断。
+仅支持当前账号拥有的项目。查询失败按
+[用量查询排错](references/troubleshooting.md#用量查询)处理，不把失败或缺失字段当作零用量。
+
+## 3. 按官方文档组装命令
+
+调用 RPC 前先读 [文档到 CLI 的映射](references/rpc-workflow.md)，再检索并打开 [ZAN 官方文档](https://docs.zan.top) 中对应链和方法的页面。核对方法名、参数顺序与类型、单位、Network 支持情况和返回字段；当前会话已核对同一方法时可复用。CLI 的语法以当前 manifest / 帮助为准。不要把文档中的 curl 命令或完整 JSON-RPC 请求体直接当作 CLI 参数。
+
+如果工作需要消息或交易签名，先按 [钱包与签名](references/signing.md) 让用户选择 ZAN CLI 钱包模块或其他密钥/签名方式，再完成相应配置。普通只读查询不需要钱包。API Key 用于 ZAN API 访问，不是钱包私钥。
+
+## 4. 执行与排错
+
+执行组装后的命令获取数据。失败时先解释 CLI 的明确错误与解决办法，修复后再执行，不把空结果或失败当作成功。
+
+- 本地方法白名单拒绝：按 [白名单授权与其他错误](references/troubleshooting.md)，展示具体方法、用途和影响，请用户 approve 是否添加。只有明确批准后，才能向对应列表追加该方法并重试。
+- 服务端权限、认证、套餐额度、网络和参数错误：按同一参考文件分类处理。服务端权限不足不能通过扩大本地白名单解决。
+- 仅对可安全重放且 `retryable: true` 的操作做有限重试。创建项目、广播等有副作用的请求结果不明时先查询确认，不盲目重放。
+
+## 5. 仅在应用代码直接调用 API 时配置 Key
+
+纯 CLI 查询获得数据后即可交付，跳过本步骤。只有为目标项目编写或配置直接调用 ZAN API 的应用代码、需要应用自行读取 Key 时，才执行以下步骤；可在代码运行前完成。确认目标应用目录，不能把全局 npm 安装目录或临时目录当作业务项目。目录不明确时先询问。
+
+在目标应用目录执行：
+
+```sh
+zan --json --no-interactive --project <project-id> project rpc-key pull
+```
+
+该命令由 CLI 内部获取 Key 并写入当前目录的 `.env` 中固定的 `ZAN_API_KEY`，不要求 Network；会替换已有同名变量。不要读取、打印或手工复制 Key：禁止 `cat .env`、输出环境变量、读取凭据库或解密缓存，也不要让用户把 Key 粘贴到聊天。验证只看命令退出码与 `{ "file": ".env", "variable": "ZAN_API_KEY", "updated": true }`，不读回内容。Skill 规定 Agent 不读取 Key；这不是宣称 `.env` 在操作系统层面不可读取。
+
+后续所有需要 API Key 的应用代码，均在运行时从该 `.env` 加载 `ZAN_API_KEY`（例如服务端 `process.env.ZAN_API_KEY`），不要硬编码 Key 或带 Key 的完整 URL。按项目已有机制加载 `.env`；缺失时只报告变量名，禁止打印值或可能包含 Key 的请求 URL/headers。不要把它放进前端公开环境变量或浏览器 bundle；前端应用通过服务端读取并调用。确保 `.env` 被 Git 忽略且不提交；可提供只含 `ZAN_API_KEY=` 占位符的 `.env.example`。检查忽略和跟踪状态不需要读取 `.env` 内容。
+
+交付时报告实际 Project 和数据。用量查询分别说明 Key 累计用量与共享套餐余额、状态和到期时间；链上调用再补充 Network、所用方法和文档链接。仅执行了应用 Key 配置时才报告写入路径，不展示秘密值。任何必要步骤失败都明确说明未完成部分；纯 CLI 查询不以 `.env` 是否存在或是否写入作为完成条件。签名成功只表示生成签名，交易哈希不等同于上链确认。

package/skills/zan-cli/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "ZAN CLI"
+  short_description: "使用 ZAN CLI 管理项目、查询套餐用量和链上数据与执行授权签名"

package/skills/zan-cli/references/rpc-workflow.md

@@ -0,0 +1,33 @@
+# 根据 ZAN 文档组装 RPC
+
+## 查明方法与接口
+
+从 [ZAN API Instructions](https://docs.zan.top/reference/api-instructions) 和 [API Reference](https://docs.zan.top/reference) 进入用户目标链的具体方法文档。页面提供的 [llms.txt](https://docs.zan.top/llms.txt) 可用于定位方法；索引不可用时使用站内链接或 `site:docs.zan.top <链> <方法>` 搜索，再打开具体页面，不只依赖搜索摘要。
+
+核对接口属于 Node Service JSON-RPC、Hyperliquid Info 还是其他服务，记录参数顺序、必填项、JSON 类型、区块标签/编码、单位和响应字段。文档覆盖的接口可能多于当前 CLI：对照 manifest 确认支持，不假定所有文档中的 REST、WebSocket、Enhanced API 或 x402 流程都能用 `evm rpc` 调用。
+
+文档无法访问且没有已核实的对应资料时，说明无法确认的参数，请用户提供文档片段或稍后重试；不要猜测接口。文档示例中的地址和区块值仅作格式示例，不代替用户目标。
+
+## 将请求映射为 CLI 参数
+
+JSON-RPC 文档中的 `method` 对应 `evm rpc <method>`；`params` 数组的每个元素作为一个独立的 JSON 位置参数。CLI 内部填充 `jsonrpc` 和 `id`、解析 Project/Network Endpoint 并携带凭据，不传完整请求体、任意 RPC URL 或明文 API Key。
+
+使用 CLI 查询时不需要应用 `.env` 或 `ZAN_API_KEY` 环境变量。登录并选择 Project/Network 后直接调用，不执行 `project rpc-key pull`；本地凭据缺失或失效时按 CLI 错误修复认证或缓存，不能用导出 Key 到 `.env` 作为修复办法。
+
+例如，文档请求的 `method` 为 `eth_getBalance`、`params` 为 `["0x0000000000000000000000000000000000000000", "latest"]` 时，参数形状映射为：
+
+```sh
+zan --json --no-interactive --project <project-id> --network <network-id> evm rpc eth_getBalance '"0x0000000000000000000000000000000000000000"' '"latest"'
+```
+
+替换为用户指定地址，按目标链的实际方法文档确认适用性。复杂参数可通过 `--stdin` 传一个 JSON 数组，与位置参数互斥。大整数和十六进制数量遵守具体方法 schema，避免 JavaScript 数值精度丢失。
+
+已有专用命令覆盖请求时，可用 `evm data balance`、`evm tx <hash>`、`evm receipt`、`evm block`、`evm gas`、`evm logs`，但参数与结果含义仍以目标链文档为依据。`evm logs` 需要 `--from-block`，不自动分页或做 ABI 解码；ENS 解析要求同一 Project 支持 `ethereum-mainnet`。
+
+Hyperliquid 选择实际返回的 `ecosystem: hyperliquid` Network。JSON-RPC / `hl_*` 方法走 `evm rpc`；Info 使用 `hyperliquid info <method> [payload]`，CLI 把方法写入 `type`，payload 只传其余字段组成的 JSON 对象，或通过 `--stdin` 输入该对象。不要重复传 `type`，当前 CLI 不提供 `/exchange` 写接口。
+
+## 应用代码中的调用
+
+本节仅适用于项目应用代码直接调用 ZAN API。代码若只是通过 CLI 获取数据，继续使用 CLI 的凭据管理，不需要导出 Key。直接调用 API 的代码按对应文档组装接口及请求，在运行时从目标项目 `.env` 的 `ZAN_API_KEY` 读取认证值。Agent 不需要知道真实 Key：只编写读取变量的代码，由 CLI 的 `project rpc-key pull` 完成写入。不要为了复现文档示例把实际 Key 拼进 Agent 执行的 curl 参数或粘贴到文档网站的在线调试器。
+
+所选 Network 与文档的主网/测试网、生态和接口路径必须对应；URL 路径中的生态标识不一定等于 CLI Network ID。结果按文档解释单位、编码和不存在时的语义，不能把 RPC 调用成功当作业务结果符合预期。

package/skills/zan-cli/references/signing.md

@@ -0,0 +1,30 @@
+# 钱包与签名
+
+先从当前 manifest / 帮助确认命令可用。以下命令自动化调用时仍加 `--json --no-interactive`。
+
+## 先选择签名方式
+
+任务确实需要签名且用户尚未指定来源时，先询问：“使用 ZAN CLI 钱包模块，还是使用你已有的外部钱包/其他密钥签名方式？”用户已明确选择时直接沿用。不要因已有默认钱包而跳过这项选择，也不要把只读 RPC 查询变成签名任务。
+
+选择 ZAN CLI 钱包模块：
+
+1. 用 `zan --json --no-interactive settings wallet list` 展示别名、地址和活动状态，让用户选择已有账户或导入自己的钱包；不要读取私钥。
+2. 尚未配置时，引导用户在自己的交互终端执行 `zan settings wallet add <alias>` 并通过隐藏输入导入私钥。当前模块是本地私钥存储与签名，不是云端托管钱包，也不自动创建钱包或生成密钥。
+3. 用户完成设置后重新列出钱包确认别名/地址，按选择执行 `settings wallet use <alias>`，后续签名显式传 `--account <alias>`。有明确账户选择时无需再次确认。
+
+选择其他密钥/签名方式：使用用户指定的外部钱包、硬件钱包或已有签名流程，由用户或受控的签名程序处理密钥。只接收公开地址、签名或已签名交易等任务所需结果，不索要、读取或打印私钥，不擅自导入 ZAN 钱包模块。当前 `zan sign` / `zan evm tx sign` 使用模块内钱包，不能编造直接接收私钥的选项。外部方式尚不明确或不可用时，先询问具体方式，再继续依赖签名的步骤。
+
+## 公开命令与约束
+
+- `settings wallet list`：查看别名、地址和活动状态。
+- `settings wallet add <alias>`：由用户在终端隐藏输入私钥；非交互导入支持 `--stdin`，仅在已有安全输入来源时使用。不要让用户把私钥粘贴到聊天或命令参数中。
+- `settings wallet use <alias>` / `remove <alias>`：分别切换默认钱包或删除钱包及存储的 Key，按用户请求执行。
+- `sign <message> --account <alias>`：EIP-191 消息签名。默认签 UTF-8 文本，只有用户要求签原始字节时才用 `--hex`；输入需为偶数长度的 `0x` 十六进制字节。
+- `evm contract encode --method <signature> --args <json-array>`：编码 calldata，不执行合约调用。ABI 整数超过 JavaScript 安全整数范围时用十进制字符串传入，避免精度丢失。
+- `evm tx sign --to <address> --account <alias>`：本地生成已签名交易，返回 `rawTransaction` 与 `transactionHash`，不广播。需要实际选择的 Project/Network；缺少 nonce、gas 等参数时会在线查询。
+
+交易签名参数的单位：`--value` 为 ether，`--max-fee-per-gas` 与 `--max-priority-fee-per-gas` 为 gwei，`--gas-limit` 为 gas 数量。`--data` 接收十六进制 calldata。`--legacy` 使用 gasPrice 交易，此时 `--max-fee-per-gas` 用作 gasPrice。完整选项以当前 manifest 为准；若 `evm tx sign --help` 返回 `INTERNAL_ERROR`，可继续从 manifest 的 `evm tx sign` 条目读取参数，不要据此操作账户或凭据。
+
+执行签名前确定用户授权的账户、消息内容，或链、收款地址、金额及 calldata；信息已明确时无需重复确认。读取余额不授权签名，签名请求也不授权广播。只在用户明确要求广播且实际命令和策略支持时另行执行；不要为广播绕过方法允许列表。
+
+已签名交易可直接用于广播，按用户请求交付结果，避免额外记录或上传。区分“已编码”“已签名”“已广播”“已确认”，不能把生成的交易哈希当作上链证明。

package/skills/zan-cli/references/troubleshooting.md

@@ -0,0 +1,42 @@
+# 白名单授权与其他错误
+
+## 本地 RPC 方法白名单
+
+只有报错明确提到 `user allowlist`，且 hint 指向 `~/.zan-cli/config.yaml` 时，按本地方法白名单处理。当前错误码为 `INVALID_ARGS`，不能把所有 `INVALID_ARGS` 或所有 HTTP 403 都归为白名单问题。
+
+1. 核对 [ZAN 文档](https://docs.zan.top/reference) 确认具体方法及目标网络支持情况，读本地配置确定最小改动。配置不是 API Key 文件，可检查内容；不要读取 `.env` 或凭据库。
+2. 向用户展示准确方法名、所属列表、调用用途及是否有写入/广播等副作用。说明这是用户级、跨项目的持久配置，请用户 approve 是否追加这个具体方法；未批准或拒绝时不修改。已有针对同一方法的明确授权可复用，一般性的“完成查询”不等于批准扩大白名单。
+3. 批准后，JSON-RPC 方法只追加到 `allowedRpcMethods`；Hyperliquid Info 方法只追加到 `allowedHyperliquidInfoMethods`。保留其他方法、字段和注释，不用通配符，不重置为宽泛列表。当前 CLI 没有白名单管理子命令，编辑这个 YAML 文件即可，不编造 `zan ... allow` 命令。
+4. 配置只支持这两个顶层键，`allowedRpcMethods` 必须存在；方法精确匹配、区分大小写且不可重复，不支持 YAML alias 或自定义 tag。旧配置缺少 Info 列表时，运行时使用内置默认 Info 列表：不能直接新增一个仅含目标方法的 Info 列表，否则会意外收窄原有能力。应从当前安装版本取得完整默认列表并保留后追加；无法可靠获取时说明影响并让用户选择处理方式。
+5. 保持文件为普通文件及其私有权限（POSIX 目录 `0700`、文件 `0600`）；保存后下一次调用即生效，不需要重启。重试原命令，若仍失败则按新错误排查，不继续自动扩大白名单。
+
+用户允许的方法可能包含广播等写操作。批准加入白名单只是允许该方法通过本地检查，不自动授权构造或发送任意交易；执行仍限于用户确认的业务操作和参数。
+
+## 用量查询
+
+`usage` 调用 CLI 资源接口，不调用 RPC；无需 Network、方法白名单或 `.env`。
+
+- `SETUP_REQUIRED` 且 hint 要求选择 Project：列出项目，让用户选定后显式传 `--project`。
+- `PROJECT_NOT_FOUND`：核对 ID 和所有权；共享项目可能可列出但本期不能查询其所有者的套餐余额。
+- `AUTH_REQUIRED` / `AUTH_EXPIRED`：按认证流程判断登录或 Scope 问题，不通过导出 Key 修复。
+- `ZAN_API_ERROR`：保留脱敏错误并向用户说明服务异常；不能将接口失败视为没有套餐或余额为 0。
+
+若错误明确提示服务端依赖失败，向用户说明服务异常，保留不含秘密的错误信息，
+不反复重登；需要进一步排查时提供这些信息给服务支持。
+
+成功时 `plan: null` 才表示无订阅；Key 限额为 null 仅表示没有单 Key 限额。
+不要因为套餐过期、额度耗尽或无订阅而自动创建项目、领取套餐或续费。
+
+## 其他错误
+
+| 错误或现象 | 处理 |
+| --- | --- |
+| 未登录、会话过期或失效 | 返回主流程的登录步骤；失效会话使用 `auth login --force`，等待用户授权完成。 |
+| scope 不足、明确的服务端权限拒绝 | 说明缺失权限，引导账户授权或服务设置调整；不重复登录、不扩大本地白名单。 |
+| 服务端 API Key、来源/方法限制、套餐或额度问题 | 对照错误和 [ZAN Security Settings](https://docs.zan.top/docs/security-settings) 检查对应设置；服务端方法白名单与本地配置是两层限制，不擅自放宽服务端规则。 |
+| `SETUP_REQUIRED` | 按 hint 修复具体配置、Project/Network 或凭据库问题，不自动清空缓存、重置配置或新建项目。 |
+| 其他 `INVALID_ARGS` / RPC 参数错误 | 对照当前命令帮助及对应 ZAN 方法页面，修正 JSON 类型、顺序、必填参数和网络选择。 |
+| Project/Network/资源不存在 | 核对用户选定 ID、地址或哈希；缺少交易/回执不等于交易已失败。 |
+| `RATE_LIMITED` / `NETWORK_ERROR` / 临时服务错误 | 只对可安全重放且 `retryable: true` 的调用有限重试；遵守等待提示，持续失败则报告。 |
+
+CLI 已内置 Access Token 刷新及有限重放，不手动操作 Token。未知问题保留不含秘密的错误码、信息、hint 与执行上下文，给出有依据的下一步；不要把所有错误都归因于认证。只有实际成功获取数据后才报告结果。纯 CLI 查询不需要 `.env`，缺少该文件不是查询失败的原因；仅在任务需要应用代码直接调用 API 时，Key 写入失败才需要单独报告尚未完成应用配置。