@zan_team/cli 0.0.0-stage → 0.0.2

package/README.md

@@ -1,3 +1,805 @@
-# Temporary Holding Version
+# ZAN CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+ZAN CLI 是面向开发者、自动化脚本和 AI Agent 的统一命令行入口，提供安全认证、ZAN Project 管理与套餐用量查询、动态多链发现、EVM 与 Hyperliquid 只读查询，以及稳定的机器可读输出。
+
+> 当前状态：认证、Project、套餐用量、Network、EVM 与 Hyperliquid 只读查询已经实现。npm 包尚未发布，当前请使用源码构建方式运行。示例中的 `example.com` 地址仅为配置占位符。
+
+## 快速开始
+
+### 环境要求
+
+- Node.js 22 或更高版本。
+- 从源码构建时需要 pnpm 10。
+
+### 安装
+
+npm 包发布后可以全局安装：
+
+```sh
+npm install --global @zan_team/cli
+zan --help
+```
+
+当前请在已检出的源码目录中安装并构建：
+
+```sh
+pnpm install
+pnpm build
+node dist/cli.js --help
+```
+
+下文统一使用 `zan`。运行源码构建产物时，将 `zan` 替换为 `node dist/cli.js`。
+
+### 配置服务地址
+
+CLI 未显式配置服务地址时默认连接生产环境 `https://zan.top`。也可以通过
+环境变量覆盖 Auth/API Origin：
+
+```sh
+export ZAN_AUTH_BASE_URL=https://auth.example.com
+export ZAN_API_BASE_URL=https://api.example.com
+```
+
+上述 `example.com` 地址仅用于展示配置方式，不能直接使用。日常使用无需覆盖
+服务地址；内部环境地址和配置请通过授权渠道获取，不要写入公开文档或示例。
+
+### 登录
+
+交互式环境默认使用浏览器授权：
+
+```sh
+zan auth login
+```
+
+终端无法打开浏览器时使用 Device Flow：
+
+```sh
+zan auth login --device-code
+```
+
+CLI 会展示授权二维码、可直接打开的验证链接和一次性用户码。
+
+### 创建并选择 Project
+
+```sh
+zan project create --name cli-demo
+zan project list
+zan project use <project-id>
+zan project active
+```
+
+`project create` 不会自动切换当前 Project。使用返回或列表中的 Project ID 执行
+`project use`；CLI 会同时拉取该 Project 的 Network/Endpoint 列表并建立本地
+加密缓存。
+
+### 查看当前项目用量
+
+选好 Project 后即可查询套餐与 Key 用量：
+
+```sh
+zan usage
+zan --json --no-interactive usage
+```
+
+显示套餐名称、已用/总额度、剩余额度和过期时间，并单独显示 Key 的累计用量。
+仅查询用量时无需选择 Network；完整输出及字段含义见[套餐与 Key 用量](#套餐与-key-用量)。
+
+### 选择 Network
+
+```sh
+zan evm networks
+zan settings set network base-mainnet
+zan settings show
+```
+
+Network ID 由 `evm networks` 返回。不要自行猜测 Network ID。
+
+### 第一次查询
+
+查询原生代币余额：
+
+```sh
+zan evm data balance 0x0000000000000000000000000000000000000000
+```
+
+调用无参数 JSON-RPC 方法：
+
+```sh
+zan evm rpc eth_blockNumber
+```
+
+### 脚本和 AI Agent
+
+自动化调用应显式关闭交互并使用 JSON 输出：
+
+```sh
+zan \
+  --json \
+  --no-interactive \
+  --project <project-id> \
+  --network base-mainnet \
+  evm rpc eth_blockNumber
+```
+
+成功结果写入 stdout，失败结果写入 stderr。脚本还应检查进程退出码。
+
+## 完整使用指南
+
+### 安装与升级
+
+npm 包发布后：
+
+```sh
+npm install --global @zan_team/cli
+npm update --global @zan_team/cli
+zan version
+```
+
+从源码构建：
+
+```sh
+pnpm install
+pnpm typecheck
+pnpm test
+pnpm build
+node dist/cli.js version
+```
+
+维护者发布流程见 [发布指南](docs/releasing.md)，首次发布使用 `pnpm run release -- --version=0.0.1`。
+
+### 全局参数
+
+全局参数放在 `zan` 与子命令之间：
+
+| 参数                 | 作用                         |
+| -------------------- | ---------------------------- |
+| `--project <id>`     | 为本次调用选择 Project       |
+| `-n, --network <id>` | 为本次调用选择 Network       |
+| `--json`             | 输出机器可读 JSON            |
+| `--no-interactive`   | 禁止交互式提示               |
+| `--interactive`      | 允许交互式提示               |
+| `--quiet`            | 隐藏非必要进度               |
+| `--verbose`          | 输出详细诊断                 |
+| `--timeout <ms>`     | 设置请求超时                 |
+| `--no-color`         | 禁用 ANSI 颜色               |
+| `--color`            | 启用 ANSI 颜色               |
+| `--reveal`           | 允许显式展示受保护的结果字段 |
+
+运行 `zan --help` 或 `zan <command> --help` 查看当前命令帮助。
+
+### 认证
+
+```sh
+zan auth login
+zan auth login --device-code
+zan auth login --force
+zan auth status
+zan auth status --verify
+zan auth logout
+```
+
+- `auth login` 获取正式授权、校验服务端 Session，并在本地保存身份与过期时间。
+- `--device-code` 适用于无浏览器或远程终端，并会展示可扫码授权的二维码。
+- `--force` 替换当前本地 Session。
+- `auth status` 读取登录时保存的本地状态；`--verify` 向 ZAN 重新验证并刷新
+  Session 信息。默认输出仅包含邮箱、认证状态、当地时间（含时区）的过期时间和
+  scopes；`--json` 保留完整状态字段和 ISO 格式时间。旧登录状态执行一次
+  `auth status --verify` 补齐邮箱，之后普通 `auth status` 即可离线显示。
+- `auth logout` 撤销服务端 Token，并清理当前环境的本地凭据、Session、加密
+  Endpoint 缓存、缓存密钥和 RPC API Key 覆盖。
+
+Refresh Token、Access Token 和 Access Token 过期时间仅存入系统凭据库。
+不同 CLI 进程会复用剩余有效期超过 60 秒的 Access Token；需要续期时通过
+用户目录下按凭据 Profile 隔离的跨进程锁协调一次 Refresh Token 轮换。
+
+已认证的 Project 与 Network 请求遇到 Access Token 失效时，会静默刷新一次
+Token，并原样重放请求一次。重放会保留 method、path、body 和创建请求的幂等键，
+同时替换 Authorization 并为新的网络尝试生成新的 Request ID。若 Refresh
+Session 已过期、撤销，或新 Access Token 仍被拒绝，CLI 返回：
+
+```text
+AUTH_EXPIRED: Authentication has expired and could not be renewed.
+Hint: Run: zan auth login
+```
+
+Scope 不足继续返回 `AUTH_REQUIRED`，不会做无意义刷新。CLI 不会自动打开浏览器
+重新登录，避免打断脚本或 Agent；所有认证重试最多一次，不会循环。
+
+CLI 使用第一方账户权限 `account.profile:read`，不请求 `openid`、`profile`
+或 OIDC ID Token。固定授权范围还包括 `offline_access`、
+`node-service.projects:read`、`node-service.projects:create` 和
+`node-service.rpc:read`。
+
+`GET /v1/api/cli-oauth/authorize` 是浏览器 Redirect/PKCE 入口。Device
+Authorization、Token 与 Revoke 使用同一 `/v1/api/cli-oauth/**` 前缀。
+`ZAN_AUTH_BASE_URL` 与 `ZAN_API_BASE_URL` 只配置 origin，不附加协议路径。
+OAuth 与 Session JSON 接口使用统一响应 envelope；CLI 只在 envelope 成功后
+校验严格业务数据。`auth status --verify` 保存 `subject`、
+`displayName`、`email`、`scopes` 和 `expiresAt`，不传递、保存或显示 organization。
+兼容尚未返回邮箱的旧后端；账户未提供邮箱时显示 `not available`。
+
+### Project 管理
+
+```sh
+zan project list
+zan project get <project-id>
+zan project create --name <project-name>
+zan project use <project-id>
+zan project active
+```
+
+- Project 名称不保证唯一，选择和设置始终使用 Project ID。
+- `project use` 会先验证 Project、刷新并加密保存 Endpoint 缓存，再写入本地
+  默认设置；刷新失败时不会切换 Project。
+- 使用 `--project <id>` 可以只覆盖当前命令，不修改本地设置。
+- Project 与 Network API 使用统一响应 envelope，解包后的业务 DTO 仍执行
+  严格校验；创建接口固定为 `POST /v1/api/cli/createProject`。
+
+### 套餐与 Key 用量
+
+```sh
+zan usage
+zan --project <project-id> usage
+zan --json --no-interactive usage
+```
+
+默认查询当前 Project，选择优先级为 `--project` > `ZAN_PROJECT` > 本地设置。
+无需 Network，不读取 Endpoint 缓存或测试 Key 覆盖，也不会导出 API Key。
+未选择 Project 时，交互终端会提示选择；非交互调用返回 `SETUP_REQUIRED`。
+
+输出示例：
+
+```text
+Project: Production (project-1)
+Key: abcd...wxyz
+Key used (cumulative): 123 credits
+Key limit: 1,000 credits
+Key remaining: 877 credits
+
+Plan: Growth (shared across account projects)
+Plan used / total: 2,500 / 10,000 credits
+Plan remaining: 7,500 credits
+Expires: 2026-10-22T00:00:00Z
+Refreshes: 2026-10-01T00:00:00Z
+Status: VALID / service ON
+```
+
+`keyUsage` 是当前项目 Key 的累计消耗及单 Key 限额；`plan` 是所属账号共享的
+Node Service 套餐，余额与控制台使用相同口径：本地套餐读取履约用量，双百套餐读取资源包余额，包含有效加油包。
+两者的统计范围不同，不能用单 Key 累计消耗减套餐总量。用量有计量延迟。
+
+对应的 `--json` 输出示例：
+
+```json
+{
+  "project": {
+    "id": "project-1",
+    "name": "Production",
+    "type": "CHAIN_RPC",
+    "createdAt": "2026-07-24T08:00:00Z",
+    "tokenHint": "abcd...wxyz"
+  },
+  "keyUsage": {
+    "usedCredits": "123",
+    "limitCredits": "1000",
+    "remainingCredits": "877"
+  },
+  "plan": {
+    "name": "Growth",
+    "usedCredits": "2500",
+    "totalCredits": "10000",
+    "remainingCredits": "7500",
+    "expiresAt": "2026-10-22T00:00:00Z",
+    "refreshAt": "2026-10-01T00:00:00Z",
+    "status": "VALID",
+    "serviceStatus": "ON"
+  }
+}
+```
+
+JSON 直接返回 `{ project, keyUsage, plan }`，额度字段为十进制整数字符串，
+时间为 UTC ISO 8601。`keyUsage.limitCredits` 和 `remainingCredits` 为 `null`
+表示未设置单 Key 限额，仍受套餐余额限制；无订阅时 `plan` 为 `null`。
+`expiresAt` 是套餐到期时间，`refreshAt` 是当前权益周期刷新时间；未知时间为 `null`。
+耗尽时剩余量显示 `0`；已过期/关闭的套餐仍返回状态及到期时间，查询不会开通或续订套餐。
+
+本期仅支持当前登录账号拥有的 `CHAIN_RPC` Project；无权访问、他人拥有或不存在的
+项目统一返回 `PROJECT_NOT_FOUND`。后端需提供
+`GET /v1/api/cli/projects/{projectId}/usage`，沿用 `node-service.projects:read` Scope。
+
+### Network 与本地设置
+
+查看当前 Project 支持的 Network：
+
+```sh
+zan evm networks
+zan evm networks --search base
+zan evm networks --refresh
+```
+
+网络列表不要求原生币元数据完整。后端提供有效 EVM 网络、Chain ID 和 HTTPS
+Endpoint 时，即使 `nativeCurrency` 缺失也可以展示和执行普通 RPC；币种列显示
+`-`，JSON 中省略 `nativeCurrency`。`evm balance` 需要币种和精度，缺失时会提示
+补齐服务端配置，也可以通过 `evm rpc eth_getBalance` 查询原始单位。
+
+未使用 `--refresh` 时，CLI 优先解密复用本地缓存，不会为了每条 EVM 命令重复
+请求 Project 详情或 Network 列表。缓存缺失、密钥缺失或密文校验失败时会自动
+重新拉取；RPC Endpoint 返回 HTTP 401/403 时会刷新一次并重试一次。
+
+查看或清理当前 Project 的缓存：
+
+```sh
+zan project cache status
+zan project cache clear
+```
+
+缓存文件使用 AES-256-GCM 加密，独立随机密钥保存在系统凭据库。不同环境和
+Project 使用不同缓存文件与密钥。普通设置文件仍只保存 Project ID 和 Network
+ID，不保存 Endpoint 或 API Key。
+
+#### RPC API Key 覆盖
+
+需要临时替换当前 Project 的 RPC API Key 时，通过隐藏输入或 stdin 写入系统
+凭据库：
+
+```sh
+zan project rpc-key set
+printf '%s\n' "$TEST_RPC_API_KEY" \
+  | zan project rpc-key set --stdin
+zan project rpc-key status
+zan project rpc-key clear
+```
+
+覆盖值不会出现在命令参数、普通配置、Endpoint 缓存或命令输出中。启用覆盖后，
+RPC 401/403 不会自动换回服务端下发的 Key，便于稳定测试指定 Key。
+
+需要让当前目录中的应用使用当前 Project Key 时，可以直接拉取到 `.env`：
+
+```sh
+zan project rpc-key pull
+```
+
+命令写入当前工作目录中固定的 `ZAN_API_KEY`：已存在时替换，缺少时追加，文件
+不存在时创建。实际生效的测试覆盖 Key 优先，否则从加密 Endpoint 缓存中提取
+服务端下发的 Project Key；不要求选择 Network。命令不接受 Key、stdin、变量名
+或输出路径，也不会在人工输出、JSON 输出、错误或日志中包含 Key。新文件及更新
+后的文件在 POSIX 系统上使用 `0600` 权限，并通过文件锁和原子替换写入；符号链接
+或非普通 `.env` 会被拒绝。
+
+`pull` 只写 `.env`，不会修改其他环境配置文件。
+它不会检查 Git 跟踪状态或自动更新 `.gitignore`，请自行确保 `.env`
+不会被提交。写入后，任何拥有当前目录读取权限的进程或 Agent 都可能读取这个明文
+文件；“不泄露”保证只覆盖该命令自身的参数、输出、错误和日志边界。
+
+管理默认 Project 和 Network：
+
+```sh
+zan settings get project
+zan settings get network
+zan settings show
+zan settings set project <project-id>
+zan settings set network <network-id>
+zan settings clear network
+zan settings clear
+```
+
+Project 和 Network 的选择优先级：
+
+```text
+命令参数 > 环境变量 > 本地设置 > 交互选择
+```
+
+可用的环境变量：
+
+| 环境变量                 | 作用                                  |
+| ------------------------ | ------------------------------------- |
+| `ZAN_PROJECT`            | 默认 Project ID                       |
+| `ZAN_NETWORK`            | 默认 Network ID                       |
+| `ZAN_HOME`               | 覆盖 CLI 数据目录，主要用于隔离和测试 |
+| `ZAN_REQUEST_TIMEOUT_MS` | 默认请求超时                          |
+
+非交互模式下缺少命令所需的 Project 或 Network 时，CLI 返回 `SETUP_REQUIRED`，不会显示选择器。
+`usage` 只要求 Project；链上查询还需要 Network。
+
+### EVM 查询
+
+所有 EVM 查询只使用当前 Project 返回的受信 Endpoint。CLI 不接受用户传入任意 RPC URL。
+
+#### Raw JSON-RPC
+
+```sh
+zan evm rpc eth_blockNumber
+zan evm rpc eth_chainId
+```
+
+位置参数必须是合法 JSON。字符串必须保留 JSON 引号：
+
+```sh
+zan evm rpc eth_getBalance \
+  '"0x0000000000000000000000000000000000000000"' \
+  '"latest"'
+```
+
+复杂参数同样按位置传入：
+
+```sh
+zan evm rpc eth_call \
+  '{"to":"0x0000000000000000000000000000000000000000","data":"0x"}' \
+  '"latest"'
+```
+
+也可以显式从 stdin 读取一个 JSON 数组：
+
+```sh
+printf '["0x0000000000000000000000000000000000000000","latest"]' \
+  | zan evm rpc eth_getBalance --stdin
+```
+
+`--stdin` 与位置参数互斥。未指定 `--stdin` 时，`evm rpc` 不读取 stdin。
+
+`evm rpc` 可调用的方法由用户级允许列表控制，固定路径为：
+
+```text
+~/.zan-cli/config.yaml
+```
+
+`~` 由操作系统用户目录 API 解析。该文件是个人 CLI 策略，与环境配置文件、
+`ZAN_ENV` 及所选 ZAN 后端环境无关；`ZAN_HOME` 不会改变它的位置，所有环境
+读取同一个文件。
+
+YAML schema 支持两个顶层属性，分别控制 Raw JSON-RPC 和 Hyperliquid Info 方法：
+
+```yaml
+allowedRpcMethods:
+  - eth_blockNumber
+  - eth_chainId
+  - eth_call
+  - eth_getBalance
+  - hl_getLatestBlockNumber
+allowedHyperliquidInfoMethods:
+  - meta
+  - activeAssetData
+  - userFills
+```
+
+条目是精确且大小写敏感的方法名（1–128 字符，匹配 `^[A-Za-z][A-Za-z0-9_.-]*$`），不允许重复，最多 256 条。不支持通配、前缀或正则。空列表会拒绝所有 Raw RPC 方法。文件必须是单个 YAML 文档且不超过 64 KiB；注释允许，重复键、别名、自定义标签和合并键会被拒绝。
+
+第一次执行语法合法的 `zan evm rpc` 或 `zan hyperliquid info` 时，如果文件不存在，CLI 会自动创建它，并预填截至 2026-09-07 ZAN 文档中 113 条只读、模拟、诊断和过滤类 JSON-RPC 方法，以及 78 条 Hyperliquid Info 查询方法。默认内容只是创建模板：文件存在后，只有文件内容决定方法是否被允许，CLI 升级不会合并或覆盖已有文件。每次调用都会重新读取该文件，编辑后下一次调用立即生效。
+
+旧版本生成、只有 `allowedRpcMethods` 的配置文件继续兼容：CLI 在内存中使用默认的 Hyperliquid Info 允许列表，不会自动改写用户文件。若要限制 Info 调用，请显式加入 `allowedHyperliquidInfoMethods`；空列表会拒绝所有 Info 方法。已有配置不会自动补入新增加的 `hl_*` JSON-RPC 方法，需要使用时请手动加入 `allowedRpcMethods`。
+
+允许列表不保证所选 Network 或套餐支持某个方法；RPC 错误仍然是最终依据。诊断和跟踪类读取可能消耗更多额度。
+
+> **警告**：默认列表是只读的，但加入 `eth_sendRawTransaction`、`avax.issueTx`、`personal_*` 或 `admin_*` 等方法后，CLI 会在不做方法级安全校验或确认的情况下直接分发这些方法。CLI 仍不实现交易构造、签名或任意 Endpoint 选择，但用户提供的已签名 payload 可能产生链上副作用。
+
+方法不在允许列表中时，`zan evm rpc` 在认证、Project/Network 解析或任何网络请求之前即以 `INVALID_ARGS` 拒绝；文件损坏或权限不安全时返回 `SETUP_REQUIRED`。
+
+内置查询命令（`evm data balance`、`evm tx`、`evm receipt`、`evm block`、`evm gas`、`evm logs`）不受该文件影响，始终使用其固定的内部只读 RPC 方法。
+
+#### Hyperliquid
+
+选择 Project 中 `ecosystem` 为 `hyperliquid` 的 Network 后，可以直接调用 ZAN Hyperliquid 的两类只读接口。
+
+Hyperliquid JSON-RPC 方法仍使用通用的 `evm rpc` 命令，并发送到 Network Endpoint 的 `/evm` 路径：
+
+```sh
+zan evm rpc hl_getLatestBlockNumber
+zan evm rpc hl_getBlock '123456'
+```
+
+Hyperliquid Info 使用独立命令，并发送到同一 Endpoint 对应的 `/info` 路径。`payload` 必须是一个 JSON 对象，CLI 会把命令中的方法名写入请求体的 `type` 字段：
+
+```sh
+zan hyperliquid info meta
+zan hyperliquid info activeAssetData \
+  '{"user":"0x0000000000000000000000000000000000000000","coin":"ETH"}'
+```
+
+也可以从 stdin 读取对象，适合避免复杂内容进入 shell 历史：
+
+```sh
+printf '{"user":"0x0000000000000000000000000000000000000000"}' \
+  | zan hyperliquid info userFills --stdin
+```
+
+位置参数与 `--stdin` 互斥；payload 不能包含 `type`，也不能是数组、字符串或 `null`。成功结果按服务原样输出，可能包含账户相关信息，请谨慎保存日志。Info 方法由 `allowedHyperliquidInfoMethods` 精确控制，且必须是已选 Hyperliquid Network；CLI 不开放 Hyperliquid `/exchange` 写接口。
+
+#### 余额与 ENS
+
+```sh
+zan evm data balance 0x0000000000000000000000000000000000000000
+zan evm data balance 0x0000000000000000000000000000000000000000 --block latest
+zan --network base-mainnet evm data balance vitalik.eth
+```
+
+ENS 通过同一 Project 的 `ethereum-mainnet` Network 解析，然后在目标 Network 查询余额。如果 Project 不支持 `ethereum-mainnet`，请改用十六进制地址。
+
+#### 交易、回执与区块
+
+```sh
+zan evm tx <transaction-hash>
+zan evm receipt <transaction-hash>
+zan evm block latest
+zan evm block 17000000
+zan evm block 0x1036640
+```
+
+交易、回执或区块不存在时返回 `NOT_FOUND`。
+
+#### Gas
+
+```sh
+zan evm gas
+zan --json --network base-mainnet evm gas
+```
+
+结果包含当前 Gas Price；节点支持时还包含 Priority Fee。
+
+#### 日志
+
+`--from-block` 是必填参数，`--to-block` 默认是 `latest`：
+
+```sh
+zan evm logs --from-block latest
+zan evm logs \
+  --from-block 17000000 \
+  --to-block 17000100 \
+  --address 0x0000000000000000000000000000000000000000
+zan evm logs \
+  --from-block latest \
+  --topic 0x0000000000000000000000000000000000000000000000000000000000000000
+```
+
+当前版本返回原始日志，不执行 ABI 解码或分页。
+
+### 自动化与 JSON 输出
+
+推荐的自动化调用形式：
+
+```sh
+zan --json --no-interactive --project <project-id> --network <network-id> <command>
+```
+
+上例用于需要 Network 的链上命令；用量查询直接使用：
+
+```sh
+zan --json --no-interactive --project <project-id> usage
+```
+
+- 成功时，stdout 只包含一个完整 JSON 值。
+- 失败时，stderr 只包含一个完整 JSON 错误。
+- JSON 模式不输出进度提示。
+- 非交互模式不读取交互输入、不打开浏览器。
+- 显式的 `evm rpc --stdin` 仍会读取作为命令数据的 stdin。
+
+错误示例：
+
+```json
+{
+  "error": {
+    "code": "SETUP_REQUIRED",
+    "message": "A ZAN Network must be selected.",
+    "hint": "Run: zan settings set network <network-id>",
+    "retryable": false
+  }
+}
+```
+
+### 就绪检查与 Agent Manifest
+
+检查本地配置、凭据库和 Session：
+
+```sh
+zan inspect
+zan --json --no-interactive inspect
+```
+
+获取从真实命令树生成的 Agent Manifest：
+
+```sh
+zan agent manifest
+zan --json --no-interactive agent manifest
+```
+
+Agent 可用 `inspect` 检查本地状态；`ready: false` 需结合实际命令判断。
+例如缺少 Network 不影响已登录且已选择 Project 的 `usage` 查询。
+
+### Agent Skill
+
+项目提供 [zan-cli Skill](skills/zan-cli/SKILL.md)，包含实际 CLI 的调用约定、
+Project/Network 选择、套餐与 Key 用量、EVM/Hyperliquid 查询、RPC Key 拉取及钱包签名指引。
+`skills/` 随 npm 包发布；安装 CLI 后仍需将技能目录放入 Agent 的发现路径。
+
+npm 包发布后，安装 CLI 并选择 Agent 安装技能：
+
+```sh
+npm install -g @zan_team/cli
+
+# 当前业务项目：在该项目目录执行
+zan skills install --agent codex
+zan skills install --agent claude-code
+
+# 当前用户的所有项目
+zan skills install --agent codex --global
+zan skills install --agent claude-code --global
+```
+
+`--agent` 必填，可用值为 `codex`、`claude-code`。默认安装到当前工作目录，
+不会向上查找 Git 根目录；`--global` 安装到操作系统用户主目录。
+
+| Agent | 当前项目 | 用户全局 | 显式调用 |
+| --- | --- | --- | --- |
+| Codex | `.agents/skills/zan-cli` | `~/.agents/skills/zan-cli` | `$zan-cli` |
+| Claude Code | `.claude/skills/zan-cli` | `~/.claude/skills/zan-cli` | `/zan-cli` |
+
+目录规则分别遵循 [Codex](https://learn.chatgpt.com/docs/build-skills) 和
+[Claude Code](https://code.claude.com/docs/en/skills) 的技能文档。
+安装过程从当前 CLI 所在的 npm 包复制完整技能，不下载额外资源、不要求登录，
+也不修改 Agent 的其他设置。
+
+升级 CLI 后，对原 Agent 和安装范围再次运行同一安装命令即可更新：
+
+```sh
+npm install -g @zan_team/cli@latest
+zan skills install --agent codex --global
+zan skills install --agent claude-code --global
+```
+
+安装目录中的 `.zan-cli-install.json` 记录版本和文件摘要，重复执行且内容未变时
+返回 `unchanged`。升级会替换完整目录并移除旧版本不再提供的资源。已有目录未经
+本命令管理，或文件被手动修改、增加、删除时，默认保留原内容并提示冲突。
+先备份自己的修改，再用 `--force` 显式替换整个 `zan-cli` 技能目录：
+
+```sh
+zan skills install --agent codex --global --force
+```
+
+指向当前包内 Skill 的开发软链接会保留并返回 `linked`，其他软链接即使使用
+`--force` 也不会被覆盖。安装结果支持 `--json --no-interactive`，包含 Agent、
+范围、版本、绝对目标路径以及 `installed` / `updated` / `unchanged` / `linked` 状态。
+
+本地测试无需发布 npm；构建后在目标业务项目目录调用绝对路径：
+
+```sh
+# 在 CLI 仓库构建
+pnpm build
+
+# 在目标业务项目目录执行，将路径替换为实际 CLI 仓库路径
+node /absolute/path/to/zan-cli/dist/cli.js skills install --agent claude-code
+node /absolute/path/to/zan-cli/dist/cli.js skills install --agent codex
+```
+
+### Shell 补全
+
+```sh
+zan completions bash
+zan completions zsh
+zan completions fish
+```
+
+命令将补全脚本写到 stdout，由用户按当前 shell 的加载方式保存或执行。
+
+### 错误与退出码
+
+| 退出码 | 含义                                       |
+| -----: | ------------------------------------------ |
+|    `0` | 成功                                       |
+|    `1` | 内部错误                                   |
+|    `2` | 参数错误                                   |
+|    `3` | 认证、凭据库或必要设置缺失                 |
+|    `4` | Project、Network、ENS 名称或查询资源不存在 |
+|    `5` | 限流                                       |
+|    `6` | 网络错误                                   |
+|    `7` | JSON-RPC 错误                              |
+|    `8` | ZAN CLI API 错误                           |
+|  `130` | 用户中断                                   |
+
+只有限流、临时网络错误和服务端明确标记的临时错误适合自动重试。参数错误、认证拒绝和资源不存在不应自动重试。
+
+第一方 CLI Auth 服务通过 WebResult 返回业务错误时，CLI 只按服务端发布的
+精确错误码转换稳定错误语义：Device Flow 的等待、降速、拒绝和过期状态继续
+由轮询流程处理；授权拒绝返回 `AUTH_DENIED`，Refresh Session 失效返回
+`AUTH_EXPIRED`，Scope 不足返回 `AUTH_REQUIRED`，Project 不存在返回
+`PROJECT_NOT_FOUND`。未纳入安全映射的正式错误码和未知错误码统一降级为
+`ZAN_API_ERROR`；服务端原始错误码和 message 不进入人工或 JSON 输出。
+
+创建 Project 时，已发布的套餐错误（`W3S-019-5-B027` 至 `B032`）仍使用
+`ZAN_API_ERROR` 和退出码 `8`，但会明确提示免费套餐未配置、无领取资格、
+初始化中、初始化失败、已有套餐不可用或 Project 数量超限。只有初始化中
+标记为可重试；CLI 不会因此自动重复创建请求。
+
+同名 Project 已存在（`W3S-019-5-B033`）时，CLI 会明确提示重名，并建议换一个
+名称，或通过 `zan project list` 查找项目后执行 `zan project use <id>` 使用已有
+项目；此错误不可重试，仍使用 `ZAN_API_ERROR` 和退出码 `8`。
+
+已认证的 Project 与 Network 请求如果通过 HTTP 401 或已发布的 WebResult
+语义表明 Access Token 无效，会刷新一次 Access Token 并重放一次请求。第二次
+仍失败时返回 `AUTH_EXPIRED`，不会继续刷新。普通 HTTP 403 和 Scope 不足不会
+触发刷新。该行为不适用于 OAuth、Device Flow 或原始 EVM JSON-RPC 请求。
+
+### 安全注意事项
+
+- 对外文档、截图和问题反馈中不要包含内部开发、测试或预发域名、IP、端口及环境配置；
+  示例统一使用 `example.com` 等占位地址，分享命令输出前先检查并脱敏。
+- 不要把 Access Token、Refresh Token、Project Token 或完整 Endpoint 写入脚本、日志和普通配置。
+- 不要使用 `--verbose` 输出处理结果中的敏感字段。
+- 完整 RPC Endpoint 只在当前进程内解密使用；本地仅保存 AES-256-GCM 密文，
+  不进入命令输出、普通设置或错误信息。
+- 加密缓存主要防止配置文件、备份或日志意外泄露明文 Endpoint。它不能抵御已
+  同时取得本地文件和已解锁系统凭据库权限的恶意进程或系统管理员。
+- RPC API Key 覆盖值只通过隐藏输入或 stdin 写入系统凭据库，不要放入命令参数
+  或脚本源码。仅在应用确实需要时使用 `project rpc-key pull` 创建 `.env`，并确保
+  文件不进入版本控制、构建产物或日志。
+- 不要向 CLI 传入任意 RPC URL；Network 必须来自当前 Project。
+- 自动化应使用 `--json --no-interactive` 并分别解析 stdout、stderr 和退出码。
+- `--reveal` 只应在用户明确需要展示受保护结果字段时使用。
+
+### 常见问题
+
+**返回 `SETUP_REQUIRED`**
+
+检查服务地址、当前 Project 和 Network：
+
+```sh
+zan settings show
+zan project active
+zan evm networks
+zan inspect
+```
+
+**返回 `AUTH_REQUIRED` 或 `AUTH_EXPIRED`**
+
+```sh
+zan auth status --verify
+zan auth login
+```
+
+**ENS 无法解析**
+
+确认当前 Project 支持 `ethereum-mainnet`，或改用十六进制地址。
+
+**Raw RPC 字符串参数被拒绝**
+
+字符串参数必须是合法 JSON，例如使用 `'"latest"'`，不能直接传入 `latest`。
+
+**自动化流程出现交互提示**
+
+增加 `--no-interactive`，并显式提供命令所需参数；`usage` 只需 `--project`，
+链上查询还需 `--network`。
+
+**用量查询的 Key 数字与套餐数字不同**
+
+Key 是项目的累计用量，套餐余额由账号下的项目共享，与控制台按套餐类型读取的余额一致。
+`Key limit: Not set` 表示未设置单 Key 限额，仍受套餐余额约束。
+`PROJECT_NOT_FOUND` 时检查当前环境及项目归属；本期不支持查询他人拥有的共享项目。
+
+## 已实现能力
+
+- OAuth 2.1 PKCE 与 Device Flow 登录、刷新、验证和登出。
+- 系统凭据库、跨进程 Access Token 复用与 Refresh Token 安全轮换。
+- Project 管理、动态 Network 发现、加密 Endpoint 缓存与安全解析。
+- `zan usage` 查询当前 Project 的 Key 用量、共享套餐余额及到期时间。
+- Raw JSON-RPC、余额、ENS、交易、回执、区块、Gas 和日志查询。
+- 稳定 JSON 协议、退出码、统一脱敏、Agent Manifest 和 shell completions。
+- 单元、集成、CLI 黑盒、覆盖率和安装包冒烟测试。
+
+## 架构与安全
+
+命令层负责解析输入，认证、Session、Project、Network 和 EVM 查询由独立服务完成；HTTP、凭据库、文件存储、输出与错误映射位于可替换的基础设施边界。
+
+完整 Network Endpoint 仅在进程内以明文用于 RPC 调用；持久化时使用
+AES-256-GCM 加密，密钥由系统凭据库单独保存，不进入命令输出或普通设置。
+
+## 路线图
+
+- **Phase A**：认证、Session、设置、就绪检查、Agent Manifest 与 CLI 基础，已实现。
+- **Phase B**：Project 管理、选择与动态多链发现，已实现。
+- **Phase C**：动态多链 Endpoint、EVM 只读查询、ENS 与显式 stdin，已实现。
+- **后续阶段**：事件查询、钱包签名、支付、Webhook 与 MCP 集成。
+
+## 文档
+
+- [ZAN CLI 设计规格](docs/superpowers/specs/2026-07-23-zan-cli-design-spec.md)
+- [Phase A 设计](docs/superpowers/specs/2026-07-23-phase-a-cli-auth-foundation-design.md)
+- [Phase B 设计](docs/superpowers/specs/2026-07-24-phase-b-project-dynamic-multichain-design.md)
+- [Phase C 设计](docs/superpowers/specs/2026-07-24-phase-c-evm-readonly-queries-design.md)