@zan_team/cli 0.0.3 → 0.0.6-beta.0

package/README.md

@@ -1,47 +1,27 @@
 # ZAN CLI
 
-ZAN CLI 是面向开发者、自动化脚本和 AI Agent 的统一命令行入口，提供安全认证、ZAN Project 管理与套餐用量查询、动态多链发现、EVM 与 Hyperliquid 只读查询，以及稳定的机器可读输出。
-
-> 当前状态：认证、Project、套餐用量、Network、EVM 与 Hyperliquid 只读查询已经实现。npm 包尚未发布，当前请使用源码构建方式运行。示例中的 `example.com` 地址仅为配置占位符。
+ZAN CLI 是面向开发者、自动化脚本和 AI Agent 的统一命令行入口，提供安全认证、ZAN Project 管理与套餐用量查询、EVM / Solana / Hyperliquid 查询、助记词与钱包管理、本地签名、Solana 交易与 Trading Boost 加速，以及稳定的机器可读输出。
 
 ## 快速开始
 
 ### 环境要求
 
 - Node.js 22 或更高版本。
-- 从源码构建时需要 pnpm 10。
+- 可用的系统凭据库：macOS Keychain、Windows Credential Manager 或 Linux Secret Service。
+
+macOS / Windows 需要安装 CLI 的可选原生凭据库依赖，安装时请保留 optional dependencies。通过命令行子进程传递秘密的备用凭据库实现已禁用；Linux 支持原生或通过 stdin 传入秘密的 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 服务，无需配置服务地址。
+下文命令中的 `<project-id>`、`<solana-address>` 等是占位符，执行前请替换为实际值并去掉尖括号。
 
 ### 登录
 
@@ -69,8 +49,7 @@ zan project active
 ```
 
 `project create` 不会自动切换当前 Project。使用返回或列表中的 Project ID 执行
-`project use`；CLI 会同时拉取该 Project 的 Network/Endpoint 列表并建立本地
-加密缓存。
+`project use` 将其设为默认项目。
 
 ### 查看当前项目用量
 
@@ -88,11 +67,18 @@ 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。使用 Solana 时：
+
+```sh
+zan solana networks
+zan settings set network solana-testnet
+```
+
+Solana 支持 `solana-testnet` 和 `solana-mainnet`。EVM 与 Solana 的默认 Network 分开保存。
 
 ### 第一次查询
 
@@ -108,6 +94,15 @@ zan evm data balance 0x0000000000000000000000000000000000000000
 zan evm rpc eth_blockNumber
 ```
 
+Solana 查询示例：
+
+```sh
+zan solana rpc getSlot
+zan solana data balance <solana-address>
+```
+
+余额查询无需导入钱包。导入助记词、转账及加速的完整流程见[钱包与签名](#钱包与签名)和[Solana 交易与加速](#solana-交易与加速)。
+
 ### 脚本和 AI Agent
 
 自动化调用应显式关闭交互并使用 JSON 输出：
@@ -117,17 +112,17 @@ zan \
   --json \
   --no-interactive \
   --project <project-id> \
-  --network base-mainnet \
+  --network <network-id> \
   evm rpc eth_blockNumber
 ```
 
-成功结果写入 stdout，失败结果写入 stderr。脚本还应检查进程退出码。
+成功结果写入 stdout，失败结果写入 stderr。Solana 交易提交遇到失败或结果不确定时，还会在 stdout 保留交易结果；脚本应同时检查退出码，见[自动化与 JSON 输出](#自动化与-json-输出)。
 
 ## 完整使用指南
 
 ### 安装与升级
 
-npm 包发布后：
+安装或升级到最新版本：
 
 ```sh
 npm install --global @zan_team/cli
@@ -135,18 +130,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 +161,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 覆盖。
-
-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；所有认证重试最多一次，不会循环。
+- `auth login` 登录 ZAN 账号；`--device-code` 适用于无浏览器或远程终端。
+- `--force` 替换当前登录状态。
+- `auth status` 显示本地保存的邮箱、认证状态、过期时间和授权范围；
+  `--verify` 向 ZAN 验证登录状态并更新这些信息。
+- `auth logout` 退出登录并清理本地登录凭据、项目缓存及项目 API Key。
 
-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 +181,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 +193,7 @@ zan --json --no-interactive usage
 ```
 
 默认查询当前 Project，选择优先级为 `--project` > `ZAN_PROJECT` > 本地设置。
-无需 Network，不读取 Endpoint 缓存或测试 Key 覆盖，也不会导出 API Key。
+无需选择 Network，也不会导出 API Key。
 未选择 Project 时，交互终端会提示选择；非交互调用返回 `SETUP_REQUIRED`。
 
 输出示例：
@@ -265,7 +214,7 @@ Status: VALID / service ON
 ```
 
 `keyUsage` 是当前项目 Key 的累计消耗及单 Key 限额；`plan` 是所属账号共享的
-Node Service 套餐，余额与控制台使用相同口径：本地套餐读取履约用量，双百套餐读取资源包余额，包含有效加油包。
+Node Service 套餐，余额与控制台使用相同口径，包含有效加油包。
 两者的统计范围不同，不能用单 Key 累计消耗减套餐总量。用量有计量延迟。
 
 对应的 `--json` 输出示例：
@@ -303,9 +252,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 与本地设置
 
@@ -315,16 +263,18 @@ JSON 直接返回 `{ project, keyUsage, plan }`，额度字段为十进制整数
 zan evm networks
 zan evm networks --search base
 zan evm networks --refresh
+zan solana networks
+zan solana networks --search testnet
 ```
 
-网络列表不要求原生币元数据完整。后端提供有效 EVM 网络、Chain ID 和 HTTPS
-Endpoint 时，即使 `nativeCurrency` 缺失也可以展示和执行普通 RPC；币种列显示
-`-`，JSON 中省略 `nativeCurrency`。`evm balance` 需要币种和精度，缺失时会提示
-补齐服务端配置，也可以通过 `evm rpc eth_getBalance` 查询原始单位。
+Solana 查询、交易与加速使用当前 Project 的 RPC Key；配置了 Key 覆盖值时使用该覆盖值。
+无需另建 Solana Project 或导出 Key 才能使用 CLI。
+
+网络列表中的币种显示为 `-` 时，仍可使用 `evm rpc` 查询。
+`evm data balance` 需要币种信息；信息缺失时可用 `evm rpc eth_getBalance`
+查询以最小单位表示的余额。
 
-未使用 `--refresh` 时，CLI 优先解密复用本地缓存，不会为了每条 EVM 命令重复
-请求 Project 详情或 Network 列表。缓存缺失、密钥缺失或密文校验失败时会自动
-重新拉取；RPC Endpoint 返回 HTTP 401/403 时会刷新一次并重试一次。
+CLI 会缓存网络列表。需要获取最新列表时使用 `--refresh`。
 
 查看或清理当前 Project 的缓存：
 
@@ -333,72 +283,55 @@ zan project cache status
 zan project cache clear
 ```
 
-缓存文件使用 AES-256-GCM 加密，独立随机密钥保存在系统凭据库。不同环境和
-Project 使用不同缓存文件与密钥。普通设置文件仍只保存 Project ID 和 Network
-ID，不保存 Endpoint 或 API Key。
-
-#### RPC API Key 覆盖
+#### 应用 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 Key 时，可以直接拉取到 `.env`：
+未选择项目时会提示选择；非交互模式请使用 `--project <project-id>`。
+此命令无需选择 Network。
 
-```sh
-zan project rpc-key pull
-```
+CLI 会尝试将 `.env` 加入 `.gitignore`；已有生效规则时不重复修改。若文件已被 Git
+跟踪，或忽略规则检查、更新失败，仍会写入并提示风险，JSON 输出中包含 `warnings`。
+提交代码前请确认 `.env` 不在暂存区，也不要将其打包或上传。
 
-命令写入当前工作目录中固定的 `ZAN_API_KEY`：已存在时替换，缺少时追加，文件
-不存在时创建。API Key 按环境和 Project ID 独立保存在系统凭据库（macOS Keychain
-等），与 Endpoint 缓存的加密密钥、手动覆盖值分别存储。`pull` 优先使用手动覆盖值，
-否则直接读取所选 Project 已保存的 API Key，不需要读取网络缓存或请求后端。
+如需为当前项目指定其他 RPC API Key，可使用隐藏输入：
 
-首次缺失时，CLI 请求该 Project 的网络列表，从首个可识别的 RPC 地址提取 API Key
-并保存到系统凭据库；现有后端接口通过地址携带 Key。刷新网络列表时同步更新保存的
-API Key，服务端不再返回可识别 Key 时移除旧记录。`zan project cache clear` 会同时
-清理当前项目保存的 API Key；退出登录会清理当前环境各项目的 Key 和覆盖值。
-
-API Key 属于所选 Project，不要求选择 Network。未选择 Project 时，交互终端会
-列出项目供选择，非交互模式需使用 `--project <id>` 或先执行 `zan project use <id>`。
-命令不接受 Key、stdin、变量名
-或输出路径，也不会在人工输出、JSON 输出、错误或日志中包含 Key。新文件及更新
-后的文件在 POSIX 系统上使用 `0600` 权限，并通过文件锁和原子替换写入；符号链接
-或非普通 `.env` 会被拒绝。
+```sh
+zan project rpc-key set
+zan project rpc-key status
+zan project rpc-key clear
+```
 
-`pull` 会确保 `.env` 被 Git 忽略：已有生效规则（包括父目录、通配符和全局规则）时
-不修改 `.gitignore`，否则在当前目录的 `.gitignore` 末尾追加 `/.env`。尚未初始化 Git
-仓库的目录也支持此行为，不会自动创建项目仓库。此检查使用本机 Git；Git 不可用时会提示风险。
+`set --stdin` 支持从标准输入读取 Key。已配置的覆盖值优先用于 RPC 请求及 `pull`；
+`clear` 清除覆盖值后恢复使用项目默认 Key。凭据保存在系统凭据库中。
 
-若 `.env` 已被 Git 跟踪，或无法检查、更新忽略规则，命令仍写入 Key，并在终端提示
-误提交 Key 的风险；JSON 结果通过 `warnings` 返回同样的提示。已跟踪时可执行
-`git rm --cached -- .env` 取消跟踪，并在提交前检查暂存内容；CLI 不会自动修改 Git
-索引，忽略规则也不能清除历史提交中的内容。其他环境配置文件不会被修改。
-写入后，任何拥有当前目录读取权限的进程或 Agent 都可能读取这个明文
-文件；“不泄露”保证只覆盖该命令自身的参数、输出、错误和日志边界。
+#### 默认 Project 和 Network
 
-管理默认 Project 和 Network：
+管理默认选择：
 
 ```sh
 zan settings get project
 zan settings get network
+zan settings get solanaNetwork
 zan settings show
 zan settings set project <project-id>
 zan settings set network <network-id>
 zan settings clear network
+zan settings clear solanaNetwork
 zan settings clear
 ```
 
+`network` 表示 EVM 默认 Network，`solanaNetwork` 表示 Solana 默认 Network。
+`settings set network solana-testnet` 会自动更新 Solana 默认值；设置 EVM Network 不会覆盖它。
+显式传入的 `--network` 或 `ZAN_NETWORK` 必须与命令所属链匹配。
+
 Project 和 Network 的选择优先级：
 
 ```text
@@ -411,7 +344,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`，不会显示选择器。
@@ -459,11 +392,9 @@ printf '["0x0000000000000000000000000000000000000000","latest"]' \
 ~/.zan-cli/config.yaml
 ```
 
-`~` 由操作系统用户目录 API 解析。该文件是个人 CLI 策略，与环境配置文件、
-`ZAN_ENV` 及所选 ZAN 后端环境无关；`ZAN_HOME` 不会改变它的位置，所有环境
-读取同一个文件。
+该文件位于当前用户的主目录，对所有项目生效；`ZAN_HOME` 不改变此路径。
 
-YAML schema 支持两个顶层属性，分别控制 Raw JSON-RPC 和 Hyperliquid Info 方法：
+YAML schema 支持三个顶层属性，分别控制 EVM Raw JSON-RPC、Hyperliquid Info 和 Solana Raw JSON-RPC 方法：
 
 ```yaml
 allowedRpcMethods:
@@ -476,21 +407,26 @@ allowedHyperliquidInfoMethods:
   - meta
   - activeAssetData
   - userFills
+allowedSolanaRpcMethods:
+  - getSlot
+  - getBalance
+  - getAccountInfo
+  - getTransaction
 ```
 
-条目是精确且大小写敏感的方法名（1–128 字符，匹配 `^[A-Za-z][A-Za-z0-9_.-]*$`），不允许重复，最多 256 条。不支持通配、前缀或正则。空列表会拒绝所有 Raw RPC 方法。文件必须是单个 YAML 文档且不超过 64 KiB；注释允许，重复键、别名、自定义标签和合并键会被拒绝。
+条目是精确且大小写敏感的方法名（1–128 字符，匹配 `^[A-Za-z][A-Za-z0-9_.-]*$`），不允许重复，最多 256 条。不支持通配、前缀或正则。空列表会拒绝对应类别的所有 Raw 方法。文件必须是单个 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` 或 `zan solana rpc` 时，若配置文件不存在，CLI 会创建默认查询方法列表。已有文件不会被升级覆盖；修改后在下一次调用生效。
 
-旧版本生成、只有 `allowedRpcMethods` 的配置文件继续兼容：CLI 在内存中使用默认的 Hyperliquid Info 允许列表，不会自动改写用户文件。若要限制 Info 调用，请显式加入 `allowedHyperliquidInfoMethods`；空列表会拒绝所有 Info 方法。已有配置不会自动补入新增加的 `hl_*` JSON-RPC 方法，需要使用时请手动加入 `allowedRpcMethods`。
+旧版本配置继续兼容：缺少 `allowedHyperliquidInfoMethods` 或 `allowedSolanaRpcMethods` 时，对应命令使用默认允许列表，不会自动改写用户文件。可显式加入对应属性限制方法；空列表拒绝该类 Raw 调用。已有配置不会自动补入新增加的 `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
 
@@ -525,7 +461,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`，请改用十六进制地址。
@@ -546,7 +482,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。
@@ -568,6 +504,233 @@ zan evm logs \
 
 当前版本返回原始日志，不执行 ABI 解码或分页。
 
+### Solana 查询
+
+登录并选择 Project 后，设置 Solana Network：
+
+```sh
+zan settings set network solana-testnet
+zan inspect --family solana
+```
+
+常用查询无需本地钱包：
+
+```sh
+zan solana data balance <solana-address>
+zan solana data tokens <owner-address>
+zan solana account <solana-address>
+zan solana tx <transaction-signature>
+zan solana tx status <transaction-signature>
+zan solana block <slot>
+zan solana fees
+```
+
+`data tokens` 同时查询 SPL Token 和 Token-2022 账户。余额中的 lamports 和代币原始数量使用精确十进制字符串，避免大整数精度丢失。`fees` 返回近期优先费采样，单位为 micro-lamports / CU，不能直接当作整笔交易费用。
+
+余额、代币和账户查询支持 `--commitment processed|confirmed|finalized`，默认 `confirmed`；交易和区块查询支持 `confirmed|finalized`。
+
+Raw JSON-RPC 的位置参数同样必须是合法 JSON：
+
+```sh
+zan solana rpc getSlot
+zan solana rpc getBalance '"<solana-address>"' '{"commitment":"confirmed"}'
+```
+
+也可通过 `--stdin` 读取一个 JSON 参数数组，不能同时传位置参数。
+`allowedSolanaRpcMethods` 控制 Raw 查询；即使加入允许列表，`sendTransaction`、`requestAirdrop` 和 `simulateTransaction` 仍不能通过 `solana rpc` 执行。交易模拟使用 `solana tx simulate`，提交使用下面的交易命令。内置查询命令使用固定只读方法，不受允许列表影响。
+
+### 钱包与签名
+
+钱包操作在本地完成，无需登录或选择 Project / Network。交互提示使用英文，秘密通过终端隐藏输入，保存在系统凭据库中。
+
+#### 导入助记词与派生账户
+
+导入 BIP39 助记词无需指定链，同一来源可派生 EVM 和 Solana 账户：
+
+```sh
+zan settings wallet add main --mnemonic
+zan settings wallet list
+zan settings wallet use main
+```
+
+在隐藏输入提示中一次性输入完整助记词，所有单词放在同一行，单词之间用空格分隔，全部输入完成后按 Enter。使用 `--mnemonic --stdin` 时也使用同样的单行格式。
+CLI 检查单词数量（12、15、18、21 或 24）、BIP39 词表和校验和。交互输入无效时显示英文错误原因并让用户重新输入，可按 Ctrl+C 取消；stdin 输入无效时返回错误，不进入交互重试。错误不会回显助记词。
+默认导入第一个账户（Account 1，index 0），不显示账户选择。CLI 会预览两条链的公开地址和派生路径，确认后保存助记词；后续需要新增账户时使用 `wallet derive`。
+如原钱包使用了 BIP39 passphrase，导入时增加 `--passphrase-prompt`，在隐藏提示中输入。
+
+从已保存助记词添加第二个账户：
+
+```sh
+zan settings wallet derive main --index 1 --alias trading
+zan settings wallet use trading --chain solana
+```
+
+`--index` 从 0 开始，`1` 表示 Account 2。默认派生路径为 EVM 的 `m/44'/60'/0'/0/<index>` 和 Solana 的 `m/44'/501'/<index>'/0'`。
+已有钱包地址使用其他路径时，可通过 `--evm-path` / `--solana-path` 指定；自定义路径不能与 `--index` 同用，Solana 路径每一级须使用带 `'` 的加固派生。导入后请核对地址与原钱包一致。
+
+`wallet use <alias>` 为别名包含的链设置默认账户，`--chain solana` 或 `--chain evm` 只修改一条链。默认账户分别保存。
+
+#### 导入单链私钥
+
+也可运行 `zan settings wallet add <alias>`，按英文提示选择导入方式，或显式指定：
+
+```sh
+zan settings wallet add evm-wallet --chain evm
+zan settings wallet add solana-wallet --chain solana
+zan settings wallet add solana-file --keypair-file /path/to/keypair.json
+```
+
+Solana 私钥支持 Base58 编码的 64 字节 secret key，或包含 64 个字节整数的 JSON keypair 文件。
+`--stdin` 从标准输入读取秘密；使用 `--stdin` 时省略 `--mnemonic` 和 `--chain` 会沿用 EVM 私钥格式。不要将真实助记词、passphrase 或私钥放入命令参数、聊天或日志。
+
+#### 消息与 EVM 交易签名
+
+使用默认账户或指定别名签署消息：
+
+```sh
+zan sign "Hello ZAN"
+zan sign "Hello ZAN" --account main
+zan solana sign "Hello ZAN" --account main
+```
+
+`zan sign` 使用 EVM EIP-191，`zan solana sign` 使用 Solana Ed25519。消息默认按 UTF-8 编码；`--hex` 按十六进制字节解释。消息签名无需网络连接，也不会广播交易。
+
+签署交易前需选择 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 trading
+```
+
+删除一个派生账户不会删除其他账户仍引用的助记词来源。
+
+### Solana 交易与加速
+
+#### SOL 转账
+
+先导入钱包、登录并选择 Project，再在测试网尝试转账。发送方需要测试网 SOL 支付金额和网络费用：
+
+```sh
+zan --network solana-testnet solana transfer \
+  --to <recipient-address> --amount 0.01 --account main --wait
+```
+
+CLI 准备交易、模拟并预览收款方、金额、指令和费用，确认后才本地签名并提交。取消确认不会签名或发送。
+金额使用 SOL 十进制表示，最多 9 位小数，不接受科学计数法。
+默认使用普通 RPC；加速需要显式选择付费模式。
+
+`--wait` 等待 `confirmed`，可用 `--commitment finalized` 等待最终确认；不加 `--wait` 时提交后返回。
+`--wait-timeout <ms>` 控制总等待时间，默认 60000；全局 `--timeout` 控制单次请求超时。
+默认执行模拟和 RPC preflight，`--skip-preflight` 显式跳过两者。
+
+#### 通用交易：构建、检查、模拟、签名和提交
+
+选择目标 Solana Network 后，可从指令文件构建交易，或使用外部生成的 Base64 交易文件：
+
+```sh
+zan settings set network solana-testnet
+zan solana tx build --instructions-file instructions.json --account main --out unsigned.base64
+zan solana tx inspect --file unsigned.base64
+zan solana tx inspect --file unsigned.base64 --online
+zan solana tx simulate --file unsigned.base64
+zan solana tx sign --file unsigned.base64 --account main --out signed.base64
+zan solana tx send --file signed.base64 --wait
+```
+
+`instructions.json` 的格式如下；将占位符替换为程序文档或 SDK 生成的地址与指令数据：
+
+```json
+{
+  "version": 0,
+  "instructions": [
+    {
+      "programAddress": "<program-address>",
+      "accounts": [
+        { "address": "<account-address>", "isSigner": false, "isWritable": true }
+      ],
+      "dataBase64": "<canonical-base64>"
+    }
+  ],
+  "lookupTableAddresses": []
+}
+```
+
+支持 `"legacy"` 和 `0` 两种版本；地址查找表使用 v0。CLI 不内置 SPL 转账、Swap 或 Anchor 指令编码，应使用对应程序的 SDK 生成数据。
+构建时也可用 `--payer <address>` 替代 `--account`，无需本地钱包。
+
+基本检查和 `tx sign` 离线完成，无需登录或 RPC。使用地址查找表时，`inspect --online` 可解析完整账户；离线检查可能不完整。
+签名只添加当前账户的签名，保留原消息、已有签名和 blockhash；多签交易需逐个签署必需账户。
+`tx send` 要求全部签名有效，可提交外部已签名交易，无需本地钱包。
+模拟成功仅表示本次模拟通过。已有签名在本地校验，结果标记 `signatureVerificationScope: local`；未签名或部分签名交易会标记未完成全部签名验证。发送给 RPC 的模拟副本会清除全部签名，保留原消息，原交易文件保持不变，避免模拟时披露可广播的交易。
+
+生成的 Base64 文件附带公开的 `<file>.metadata.json`，记录关联网络和交易有效期信息；移动文件时请一起保留。输出文件已存在时不会覆盖。
+外部交易文件不会被自动改写、补指令或刷新 blockhash。
+
+#### Trading Boost：Tips 与 Points
+
+加速仅支持 `solana-mainnet`。先查看当前 Project 和 Network 的能力说明：
+
+```sh
+zan --network solana-mainnet solana boost status
+```
+
+| 模式 | 选择参数 | 额外费用 |
+| --- | --- | --- |
+| 普通 RPC（默认） | `--boost rpc` 或省略 | 无加速费用，仍支付网络费用 |
+| Tips | `--boost tips --tip-sol 0.0003` | 钱包支付 SOL tip，最低及默认值为 0.0003 SOL |
+| Points | `--boost points --tier standard\|turbo\|prime` | 每次提交对应 1 / 3 / 5 Points，仍支付网络费用 |
+
+选择一种模式发送：
+
+```sh
+# Tips
+zan --network solana-mainnet solana transfer \
+  --to <recipient-address> --amount 0.01 --account main \
+  --boost tips --tip-sol 0.0003 --region sg --wait
+
+# Points
+zan --network solana-mainnet solana transfer \
+  --to <recipient-address> --amount 0.01 --account main \
+  --boost points --tier turbo --wait
+```
+
+Tips 的区域可选 `sg`（默认）、`global`、`hk`、`de`、`us`；Points 使用 `global` 路由。
+Points 未指定 tier 时，交互模式提示选择；非交互模式必须显式指定。
+当前 CLI 不提供 Points 余额、过期时间和权限的确定查询，`boost status` 中的 unknown / unavailable 不表示余额为零，实际权限和额度由服务校验。
+
+已有交易也可通过 `tx send --boost points --tier turbo` 提交。
+使用 Tips 时须在签名前准备 tip，例如 `tx build --boost tips`；外部已签名交易必须已包含足额 tip，否则拒绝发送。Points 不会删除交易中已有的 SOL tip。
+`--anti-mev` 可在构建或转账签名前加入保护账户；外部已签名交易须预先包含该账户才能使用此选项。
+模拟、费用查询和确认查询仍使用普通 RPC。付费提交不保证加速或 Anti-MEV 效果，链上确认也不代表已取得加速回执。
+
+#### 交易结果与恢复
+
+结果区分 `submitted`、`confirmed`、`finalized`、`failed`、`expired`、`unknown`。
+等待超时或网络中断时，按结果中的 `recoveryCommand` 查询；它固定本次 Project、Network 和签名：
+
+```sh
+zan --project <project-id> --network <original-network-id> solana tx status <transaction-signature>
+```
+
+示例中的网络应与原交易一致。`unknown` 表示执行结果尚未确定，不能据此重新转账；历史查询暂未找到也不能证明未执行。
+CLI 不会自动重签、切换加速模式或发送替代交易。确认期间第一次 Ctrl+C 会保留已知签名和结果，退出码仍为 130。
+
 ### 自动化与 JSON 输出
 
 推荐的自动化调用形式：
@@ -582,11 +745,21 @@ 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 错误。
+- Solana 交易提交返回 `failed` / `expired` / `unknown` 时，stdout 还保留交易结果和恢复命令。前两者退出码为 7，`unknown` 为 6 且不可自动重试；不要仅凭 stdout 有结果判断成功。
 - JSON 模式不输出进度提示。
 - 非交互模式不读取交互输入、不打开浏览器。
-- 显式的 `evm rpc --stdin` 仍会读取作为命令数据的 stdin。
+- 显式的 `evm rpc --stdin`、`solana rpc --stdin` 和钱包导入 `--stdin` 仍会读取作为命令数据的 stdin。
+
+自动化提交 Solana 交易必须使用 `--yes` 明确授权本次广播。例如，已确认网络、收款方、金额和账户后：
+
+```sh
+zan --json --no-interactive --project <project-id> --network solana-testnet \
+  solana transfer --to <recipient-address> --amount 0.01 --account main --yes --wait
+```
+
+签名授权不等于广播授权。Agent 应在用户授权的范围内使用 `--yes`；Points 模式还必须指定 `--tier`。
 
 错误示例：
 
@@ -608,9 +781,10 @@ zan --json --no-interactive --project <project-id> usage
 ```sh
 zan inspect
 zan --json --no-interactive inspect
+zan inspect --family solana
 ```
 
-获取从真实命令树生成的 Agent Manifest：
+获取 Agent 可读取的命令说明：
 
 ```sh
 zan agent manifest
@@ -619,14 +793,15 @@ zan --json --no-interactive agent manifest
 
 Agent 可用 `inspect` 检查本地状态；`ready: false` 需结合实际命令判断。
 例如缺少 Network 不影响已登录且已选择 Project 的 `usage` 查询。
+`inspect --family solana` 检查 Solana 的就绪状态；余额查询无需钱包，本地消息签名和离线交易签名无需登录或 Network。
 
 ### Agent Skill
 
-项目提供 [zan-cli Skill](skills/zan-cli/SKILL.md)，包含实际 CLI 的调用约定、
-Project/Network 选择、套餐与 Key 用量、EVM/Hyperliquid 查询、RPC Key 拉取及钱包签名指引。
-`skills/` 随 npm 包发布；安装 CLI 后仍需将技能目录放入 Agent 的发现路径。
+CLI 随附 zan-cli Skill，包含命令使用说明、
+Project/Network 选择、套餐与 Key 用量、EVM / Solana / Hyperliquid 查询、RPC Key 拉取、助记词派生、钱包签名及 Solana 交易与 Trading Boost 指引。
+安装 CLI 后，使用以下命令将 Skill 安装到 Agent 可发现的位置。
 
-npm 包发布后，安装 CLI 并选择 Agent 安装技能：
+选择 Agent 和安装范围：
 
 ```sh
 npm install -g @zan_team/cli
@@ -661,8 +836,7 @@ zan skills install --agent codex --global
 zan skills install --agent claude-code --global
 ```
 
-安装目录中的 `.zan-cli-install.json` 记录版本和文件摘要，重复执行且内容未变时
-返回 `unchanged`。升级会替换完整目录并移除旧版本不再提供的资源。已有目录未经
+重复执行且内容未变时返回 `unchanged`。升级会更新技能目录。已有目录未经
 本命令管理，或文件被手动修改、增加、删除时，默认保留原内容并提示冲突。
 先备份自己的修改，再用 `--force` 显式替换整个 `zan-cli` 技能目录：
 
@@ -670,20 +844,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 补全
 
@@ -705,56 +866,30 @@ zan completions fish
 |    `3` | 认证、凭据库或必要设置缺失                 |
 |    `4` | Project、Network、ENS 名称或查询资源不存在 |
 |    `5` | 限流                                       |
-|    `6` | 网络错误                                   |
-|    `7` | JSON-RPC 错误                              |
+|    `6` | 网络错误或 Solana 提交结果不确定            |
+|    `7` | JSON-RPC 错误或 Solana 交易失败、过期        |
 |    `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 不会因此自动重复创建请求。
+读取请求遇到限流、临时网络错误或服务端明确标记的临时错误时，可结合 `retryable` 重试。参数错误、认证拒绝和资源不存在不应自动重试。Solana 提交结果不确定时先查询原签名，不自动重试广播或重新支付。
 
-同名 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` 只应在用户明确需要展示受保护结果字段时使用。
+- 不要在聊天、问题反馈、日志或版本控制中包含助记词、passphrase、私钥、API Key、登录凭据及含凭据的 RPC 地址。
+- 仅在应用直接调用 ZAN API 时使用 `project rpc-key pull`，并妥善保管生成的 `.env`。
+- 助记词、私钥和 API Key 使用隐藏输入或 stdin 传入；passphrase 使用隐藏提示，不要将真实值写在命令参数中。
+- 自定义 EVM RPC 允许列表可能开放写操作；执行前确认方法及参数的影响。
+- 分享签名、已签名交易或查询结果前，确认其用途及接收方。
+- 自动化调用使用 `--json --no-interactive`，同时检查退出码和风险警告。
 
 ### 常见问题
 
 **返回 `SETUP_REQUIRED`**
 
-检查服务地址、当前 Project 和 Network：
+检查当前 Project、Network 和本地凭据状态：
 
 ```sh
 zan settings show
@@ -787,35 +922,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 及项目归属；用量查询不支持他人拥有的项目。