@zan_team/cli 0.0.2 → 0.0.5

package/README.md

@@ -1,47 +1,24 @@
 # ZAN CLI
 
-ZAN CLI 是面向开发者、自动化脚本和 AI Agent 的统一命令行入口，提供安全认证、ZAN Project 管理与套餐用量查询、动态多链发现、EVM 与 Hyperliquid 只读查询，以及稳定的机器可读输出。
-
-> 当前状态：认证、Project、套餐用量、Network、EVM 与 Hyperliquid 只读查询已经实现。npm 包尚未发布，当前请使用源码构建方式运行。示例中的 `example.com` 地址仅为配置占位符。
+ZAN CLI 是面向开发者、自动化脚本和 AI Agent 的统一命令行入口，提供安全认证、ZAN Project 管理与套餐用量查询、动态多链发现、EVM 与 Hyperliquid 查询、钱包管理与本地签名，以及稳定的机器可读输出。
 
 ## 快速开始
 
 ### 环境要求
 
 - Node.js 22 或更高版本。
-- 从源码构建时需要 pnpm 10。
+- 可用的系统凭据库：macOS Keychain、Windows Credential Manager 或 Linux Secret Service。
 
 ### 安装
 
-npm 包发布后可以全局安装：
+使用 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` 地址仅用于展示配置方式，不能直接使用。日常使用无需覆盖
-服务地址；内部环境地址和配置请通过授权渠道获取，不要写入公开文档或示例。
+CLI 默认连接 ZAN 服务，无需配置服务地址。
 
 ### 登录
 
@@ -69,8 +46,7 @@ zan project active
 ```
 
 `project create` 不会自动切换当前 Project。使用返回或列表中的 Project ID 执行
-`project use`；CLI 会同时拉取该 Project 的 Network/Endpoint 列表并建立本地
-加密缓存。
+`project use` 将其设为默认项目。
 
 ### 查看当前项目用量
 
@@ -88,11 +64,11 @@ zan --json --no-interactive usage
 
 ```sh
 zan evm networks
-zan settings set network base-mainnet
+zan settings set network <network-id>
 zan settings show
 ```
 
-Network ID 由 `evm networks` 返回。不要自行猜测 Network ID。
+将 `<network-id>` 替换为 `evm networks` 返回的 Network ID。
 
 ### 第一次查询
 
@@ -117,7 +93,7 @@ zan \
   --json \
   --no-interactive \
   --project <project-id> \
-  --network base-mainnet \
+  --network <network-id> \
   evm rpc eth_blockNumber
 ```
 
@@ -127,7 +103,7 @@ zan \
 
 ### 安装与升级
 
-npm 包发布后：
+安装或升级到最新版本：
 
 ```sh
 npm install --global @zan_team/cli
@@ -135,18 +111,6 @@ 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` 与子命令之间：
@@ -178,45 +142,14 @@ 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 覆盖。
+- `auth login` 登录 ZAN 账号；`--device-code` 适用于无浏览器或远程终端。
+- `--force` 替换当前登录状态。
+- `auth status` 显示本地保存的邮箱、认证状态、过期时间和授权范围；
+  `--verify` 向 ZAN 验证登录状态并更新这些信息。
+- `auth logout` 退出登录并清理本地登录凭据、项目缓存及项目 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`。
+登录凭据保存在系统凭据库中。CLI 会尝试自动续期；若提示 `AUTH_EXPIRED`，请重新执行
+`zan auth login`。非交互模式不会自动打开浏览器。
 
 ### Project 管理
 
@@ -229,11 +162,8 @@ zan project active
 ```
 
 - Project 名称不保证唯一，选择和设置始终使用 Project ID。
-- `project use` 会先验证 Project、刷新并加密保存 Endpoint 缓存，再写入本地
-  默认设置；刷新失败时不会切换 Project。
+- `project use` 验证项目并更新可用网络后，将其设为默认项目；失败时保留原选择。
 - 使用 `--project <id>` 可以只覆盖当前命令，不修改本地设置。
-- Project 与 Network API 使用统一响应 envelope，解包后的业务 DTO 仍执行
-  严格校验；创建接口固定为 `POST /v1/api/cli/createProject`。
 
 ### 套餐与 Key 用量
 
@@ -244,7 +174,7 @@ zan --json --no-interactive usage
 ```
 
 默认查询当前 Project，选择优先级为 `--project` > `ZAN_PROJECT` > 本地设置。
-无需 Network，不读取 Endpoint 缓存或测试 Key 覆盖，也不会导出 API Key。
+无需选择 Network，也不会导出 API Key。
 未选择 Project 时，交互终端会提示选择；非交互调用返回 `SETUP_REQUIRED`。
 
 输出示例：
@@ -265,7 +195,7 @@ Status: VALID / service ON
 ```
 
 `keyUsage` 是当前项目 Key 的累计消耗及单 Key 限额；`plan` 是所属账号共享的
-Node Service 套餐，余额与控制台使用相同口径：本地套餐读取履约用量，双百套餐读取资源包余额，包含有效加油包。
+Node Service 套餐，余额与控制台使用相同口径，包含有效加油包。
 两者的统计范围不同，不能用单 Key 累计消耗减套餐总量。用量有计量延迟。
 
 对应的 `--json` 输出示例：
@@ -303,9 +233,8 @@ JSON 直接返回 `{ project, keyUsage, plan }`，额度字段为十进制整数
 `expiresAt` 是套餐到期时间，`refreshAt` 是当前权益周期刷新时间；未知时间为 `null`。
 耗尽时剩余量显示 `0`；已过期/关闭的套餐仍返回状态及到期时间，查询不会开通或续订套餐。
 
-本期仅支持当前登录账号拥有的 `CHAIN_RPC` Project；无权访问、他人拥有或不存在的
-项目统一返回 `PROJECT_NOT_FOUND`。后端需提供
-`GET /v1/api/cli/projects/{projectId}/usage`，沿用 `node-service.projects:read` Scope。
+用量查询支持当前登录账号拥有的 `CHAIN_RPC` Project。无权访问或不存在的项目返回
+`PROJECT_NOT_FOUND`。
 
 ### Network 与本地设置
 
@@ -317,14 +246,11 @@ zan evm networks --search base
 zan evm networks --refresh
 ```
 
-网络列表不要求原生币元数据完整。后端提供有效 EVM 网络、Chain ID 和 HTTPS
-Endpoint 时，即使 `nativeCurrency` 缺失也可以展示和执行普通 RPC；币种列显示
-`-`，JSON 中省略 `nativeCurrency`。`evm balance` 需要币种和精度，缺失时会提示
-补齐服务端配置，也可以通过 `evm rpc eth_getBalance` 查询原始单位。
+网络列表中的币种显示为 `-` 时，仍可使用 `evm rpc` 查询。
+`evm data balance` 需要币种信息；信息缺失时可用 `evm rpc eth_getBalance`
+查询以最小单位表示的余额。
 
-未使用 `--refresh` 时，CLI 优先解密复用本地缓存，不会为了每条 EVM 命令重复
-请求 Project 详情或 Network 列表。缓存缺失、密钥缺失或密文校验失败时会自动
-重新拉取；RPC Endpoint 返回 HTTP 401/403 时会刷新一次并重试一次。
+CLI 会缓存网络列表。需要获取最新列表时使用 `--refresh`。
 
 查看或清理当前 Project 的缓存：
 
@@ -333,45 +259,38 @@ zan project cache status
 zan project cache clear
 ```
 
-缓存文件使用 AES-256-GCM 加密，独立随机密钥保存在系统凭据库。不同环境和
-Project 使用不同缓存文件与密钥。普通设置文件仍只保存 Project ID 和 Network
-ID，不保存 Endpoint 或 API Key。
+#### 应用 API Key
 
-#### RPC API Key 覆盖
-
-需要临时替换当前 Project 的 RPC API Key 时，通过隐藏输入或 stdin 写入系统
-凭据库：
+仅通过 CLI 查询数据时无需导出 API Key。应用需要直接调用 ZAN API 时，在应用目录执行：
 
 ```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
+zan project rpc-key pull
 ```
 
-覆盖值不会出现在命令参数、普通配置、Endpoint 缓存或命令输出中。启用覆盖后，
-RPC 401/403 不会自动换回服务端下发的 Key，便于稳定测试指定 Key。
+命令将所选项目的 API Key 写入当前目录 `.env` 的 `ZAN_API_KEY`：文件不存在时创建，
+变量已存在时替换，否则追加。其他变量和其他环境配置文件保持不变，终端不显示 Key。
+
+未选择项目时会提示选择；非交互模式请使用 `--project <project-id>`。
+此命令无需选择 Network。
+
+CLI 会尝试将 `.env` 加入 `.gitignore`；已有生效规则时不重复修改。若文件已被 Git
+跟踪，或忽略规则检查、更新失败，仍会写入并提示风险，JSON 输出中包含 `warnings`。
+提交代码前请确认 `.env` 不在暂存区，也不要将其打包或上传。
 
-需要让当前目录中的应用使用当前 Project Key 时，可以直接拉取到 `.env`：
+如需为当前项目指定其他 RPC API Key，可使用隐藏输入：
 
 ```sh
-zan project rpc-key pull
+zan project rpc-key set
+zan project rpc-key status
+zan project rpc-key clear
 ```
 
-命令写入当前工作目录中固定的 `ZAN_API_KEY`：已存在时替换，缺少时追加，文件
-不存在时创建。实际生效的测试覆盖 Key 优先，否则从加密 Endpoint 缓存中提取
-服务端下发的 Project Key；不要求选择 Network。命令不接受 Key、stdin、变量名
-或输出路径，也不会在人工输出、JSON 输出、错误或日志中包含 Key。新文件及更新
-后的文件在 POSIX 系统上使用 `0600` 权限，并通过文件锁和原子替换写入；符号链接
-或非普通 `.env` 会被拒绝。
+`set --stdin` 支持从标准输入读取 Key。已配置的覆盖值优先用于 RPC 请求及 `pull`；
+`clear` 清除覆盖值后恢复使用项目默认 Key。凭据保存在系统凭据库中。
 
-`pull` 只写 `.env`，不会修改其他环境配置文件。
-它不会检查 Git 跟踪状态或自动更新 `.gitignore`，请自行确保 `.env`
-不会被提交。写入后，任何拥有当前目录读取权限的进程或 Agent 都可能读取这个明文
-文件；“不泄露”保证只覆盖该命令自身的参数、输出、错误和日志边界。
+#### 默认 Project 和 Network
 
-管理默认 Project 和 Network：
+管理默认选择：
 
 ```sh
 zan settings get project
@@ -395,7 +314,7 @@ Project 和 Network 的选择优先级：
 | ------------------------ | ------------------------------------- |
 | `ZAN_PROJECT`            | 默认 Project ID                       |
 | `ZAN_NETWORK`            | 默认 Network ID                       |
-| `ZAN_HOME`               | 覆盖 CLI 数据目录，主要用于隔离和测试 |
+| `ZAN_HOME`               | 指定 CLI 数据目录                      |
 | `ZAN_REQUEST_TIMEOUT_MS` | 默认请求超时                          |
 
 非交互模式下缺少命令所需的 Project 或 Network 时，CLI 返回 `SETUP_REQUIRED`，不会显示选择器。
@@ -443,9 +362,7 @@ printf '["0x0000000000000000000000000000000000000000","latest"]' \
 ~/.zan-cli/config.yaml
 ```
 
-`~` 由操作系统用户目录 API 解析。该文件是个人 CLI 策略，与环境配置文件、
-`ZAN_ENV` 及所选 ZAN 后端环境无关；`ZAN_HOME` 不会改变它的位置，所有环境
-读取同一个文件。
+该文件位于当前用户的主目录，对所有项目生效；`ZAN_HOME` 不改变此路径。
 
 YAML schema 支持两个顶层属性，分别控制 Raw JSON-RPC 和 Hyperliquid Info 方法：
 
@@ -464,17 +381,17 @@ allowedHyperliquidInfoMethods:
 
 条目是精确且大小写敏感的方法名（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 升级不会合并或覆盖已有文件。每次调用都会重新读取该文件，编辑后下一次调用立即生效。
+首次调用 `zan evm rpc` 或 `zan hyperliquid info` 时，若配置文件不存在，CLI 会创建默认查询方法列表。已有文件不会被升级覆盖；修改后在下一次调用生效。
 
-旧版本生成、只有 `allowedRpcMethods` 的配置文件继续兼容：CLI 在内存中使用默认的 Hyperliquid Info 允许列表，不会自动改写用户文件。若要限制 Info 调用，请显式加入 `allowedHyperliquidInfoMethods`；空列表会拒绝所有 Info 方法。已有配置不会自动补入新增加的 `hl_*` JSON-RPC 方法，需要使用时请手动加入 `allowedRpcMethods`。
+旧版本生成、只有 `allowedRpcMethods` 的配置文件继续兼容：Hyperliquid Info 使用默认允许列表，不会自动改写用户文件。若要限制 Info 调用，请显式加入 `allowedHyperliquidInfoMethods`；空列表会拒绝所有 Info 方法。已有配置不会自动补入新增加的 `hl_*` JSON-RPC 方法，需要使用时请手动加入 `allowedRpcMethods`。
 
 允许列表不保证所选 Network 或套餐支持某个方法；RPC 错误仍然是最终依据。诊断和跟踪类读取可能消耗更多额度。
 
-> **警告**：默认列表是只读的，但加入 `eth_sendRawTransaction`、`avax.issueTx`、`personal_*` 或 `admin_*` 等方法后，CLI 会在不做方法级安全校验或确认的情况下直接分发这些方法。CLI 仍不实现交易构造、签名或任意 Endpoint 选择，但用户提供的已签名 payload 可能产生链上副作用。
+> **警告**：默认列表是只读的，但加入 `eth_sendRawTransaction`、`avax.issueTx`、`personal_*` 或 `admin_*` 等方法后，CLI 会在不做方法级安全校验或确认的情况下直接分发这些方法。Raw RPC 命令不会替用户签名，但提交已签名交易可能产生链上状态变更。
 
-方法不在允许列表中时，`zan evm rpc` 在认证、Project/Network 解析或任何网络请求之前即以 `INVALID_ARGS` 拒绝；文件损坏或权限不安全时返回 `SETUP_REQUIRED`。
+方法不在允许列表中时返回 `INVALID_ARGS`；配置文件损坏或权限不安全时返回 `SETUP_REQUIRED`。
 
-内置查询命令（`evm data balance`、`evm tx`、`evm receipt`、`evm block`、`evm gas`、`evm logs`）不受该文件影响，始终使用其固定的内部只读 RPC 方法。
+内置查询命令（`evm data balance`、`evm tx`、`evm receipt`、`evm block`、`evm gas`、`evm logs`）不受该文件影响，使用固定的只读 RPC 方法。
 
 #### Hyperliquid
 
@@ -509,7 +426,7 @@ printf '{"user":"0x0000000000000000000000000000000000000000"}' \
 ```sh
 zan evm data balance 0x0000000000000000000000000000000000000000
 zan evm data balance 0x0000000000000000000000000000000000000000 --block latest
-zan --network base-mainnet evm data balance vitalik.eth
+zan --network <network-id> evm data balance vitalik.eth
 ```
 
 ENS 通过同一 Project 的 `ethereum-mainnet` Network 解析，然后在目标 Network 查询余额。如果 Project 不支持 `ethereum-mainnet`，请改用十六进制地址。
@@ -530,7 +447,7 @@ zan evm block 0x1036640
 
 ```sh
 zan evm gas
-zan --json --network base-mainnet evm gas
+zan --json --network <network-id> evm gas
 ```
 
 结果包含当前 Gas Price；节点支持时还包含 Priority Fee。
@@ -552,6 +469,46 @@ zan evm logs \
 
 当前版本返回原始日志，不执行 ABI 解码或分页。
 
+### 钱包与签名
+
+添加钱包时通过终端隐藏输入私钥，私钥保存在系统凭据库中：
+
+```sh
+zan settings wallet add my-wallet
+zan settings wallet list
+zan settings wallet use my-wallet
+```
+
+使用当前钱包签署消息（EIP-191）：
+
+```sh
+zan sign "Hello ZAN"
+zan sign "Hello ZAN" --account my-wallet
+```
+
+签署交易前需选择 Project 和 Network。以下命令仅生成已签名交易，不广播：
+
+```sh
+zan evm tx sign --to <recipient-address> --value 0.01
+```
+
+可通过 `--nonce`、`--gas-limit`、`--max-fee-per-gas` 和 `--max-priority-fee-per-gas`
+指定交易字段，其中费用参数的单位为 Gwei。签名和已签名交易可能被用于授权或广播，
+请仅签署明确理解的内容。
+
+编码合约调用数据：
+
+```sh
+zan evm contract encode --method 'balanceOf(address)' \
+  --args '["0x0000000000000000000000000000000000000000"]'
+```
+
+删除已保存的钱包：
+
+```sh
+zan settings wallet remove my-wallet
+```
+
 ### 自动化与 JSON 输出
 
 推荐的自动化调用形式：
@@ -566,7 +523,7 @@ zan --json --no-interactive --project <project-id> --network <network-id> <comma
 zan --json --no-interactive --project <project-id> usage
 ```
 
-- 成功时，stdout 只包含一个完整 JSON 值。
+- 成功时，stdout 只包含一个完整 JSON 值；部分命令可能同时向 stderr 输出风险警告。
 - 失败时，stderr 只包含一个完整 JSON 错误。
 - JSON 模式不输出进度提示。
 - 非交互模式不读取交互输入、不打开浏览器。
@@ -594,7 +551,7 @@ zan inspect
 zan --json --no-interactive inspect
 ```
 
-获取从真实命令树生成的 Agent Manifest：
+获取 Agent 可读取的命令说明：
 
 ```sh
 zan agent manifest
@@ -606,11 +563,11 @@ Agent 可用 `inspect` 检查本地状态；`ready: false` 需结合实际命令
 
 ### Agent Skill
 
-项目提供 [zan-cli Skill](skills/zan-cli/SKILL.md)，包含实际 CLI 的调用约定、
+CLI 随附 zan-cli Skill，包含命令使用说明、
 Project/Network 选择、套餐与 Key 用量、EVM/Hyperliquid 查询、RPC Key 拉取及钱包签名指引。
-`skills/` 随 npm 包发布；安装 CLI 后仍需将技能目录放入 Agent 的发现路径。
+安装 CLI 后，使用以下命令将 Skill 安装到 Agent 可发现的位置。
 
-npm 包发布后，安装 CLI 并选择 Agent 安装技能：
+选择 Agent 和安装范围：
 
 ```sh
 npm install -g @zan_team/cli
@@ -645,8 +602,7 @@ zan skills install --agent codex --global
 zan skills install --agent claude-code --global
 ```
 
-安装目录中的 `.zan-cli-install.json` 记录版本和文件摘要，重复执行且内容未变时
-返回 `unchanged`。升级会替换完整目录并移除旧版本不再提供的资源。已有目录未经
+重复执行且内容未变时返回 `unchanged`。升级会更新技能目录。已有目录未经
 本命令管理，或文件被手动修改、增加、删除时，默认保留原内容并提示冲突。
 先备份自己的修改，再用 `--force` 显式替换整个 `zan-cli` 技能目录：
 
@@ -654,20 +610,7 @@ zan skills install --agent claude-code --global
 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
-```
+安装结果支持 `--json --no-interactive`。
 
 ### Shell 补全
 
@@ -696,49 +639,23 @@ zan completions fish
 
 只有限流、临时网络错误和服务端明确标记的临时错误适合自动重试。参数错误、认证拒绝和资源不存在不应自动重试。
 
-第一方 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 请求。
+创建 Project 时若提示名称重复，可更换名称，或执行 `zan project list` 查找已有项目。
+套餐不可用或项目数量达到上限时，请根据错误提示检查账号套餐及项目状态。
 
 ### 安全注意事项
 
-- 对外文档、截图和问题反馈中不要包含内部开发、测试或预发域名、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` 只应在用户明确需要展示受保护结果字段时使用。
+- 不要在聊天、问题反馈、日志或版本控制中包含私钥、API Key、登录凭据及含凭据的 RPC 地址。
+- 仅在应用直接调用 ZAN API 时使用 `project rpc-key pull`，并妥善保管生成的 `.env`。
+- 私钥和 API Key 使用隐藏输入或 stdin 传入，不要将真实值写在命令参数中。
+- 自定义 RPC 允许列表可能开放写操作；执行前确认方法及参数的影响。
+- 分享签名、已签名交易或查询结果前，确认其用途及接收方。
+- 自动化调用使用 `--json --no-interactive`，同时检查退出码和风险警告。
 
 ### 常见问题
 
 **返回 `SETUP_REQUIRED`**
 
-检查服务地址、当前 Project 和 Network：
+检查当前 Project、Network 和本地凭据状态：
 
 ```sh
 zan settings show
@@ -771,35 +688,4 @@ zan auth login
 
 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)
+`PROJECT_NOT_FOUND` 时检查项目 ID 及项目归属；用量查询不支持他人拥有的项目。