jcc_hyper_tool 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JCC Dex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,394 @@
+# jcc_hyper_tool
+
+面向 Hyperliquid 永续合约的命令行工具：
+
+- **Phase 1**：只读 `/info` 查询
+- **Phase 2**：签名 `/exchange`（下单 / 撤单）+ HTTP 轮询 `watch`
+- **Phase 3**：基础 **grid** 策略（在价格区间内批量挂限价）
+- **Phase 4**：**本地 JSON 状态**（默认 **`~/.jcc_hyper_tool/trade-state.json`**；根或子命令 **`--state-file`** 可改路径；根 **`--no-state`** 可关闭挂单类命令的读写）+ **`state reconcile`** / **`state cancel-open`**，跟踪 bracket / grid 意图，并在入场视为成交后再推进 TP/SL
+
+私钥**仅**通过**环境变量**提供，请勿写入仓库或配置文件；变量名、何时必填与安全注意见 **[环境变量](#环境变量)**。
+
+按场景整理的「复制即用」指令集见 **[Manual.md](./Manual.md)**（README 侧重完整说明，Manual 侧重实际命令）。
+
+## 安装与运行
+
+需要 **Node.js 20+**。安装发布包或按你的方式把 CLI 放进 **PATH** 后，终端中应能直接执行 **`jcc_hyper_tool`**（同包还提供 **`jcc_hyper_daemon`**，见 **[守护进程（定时循环）](#守护进程定时循环)**）。
+
+**本文档中所有命令示例一律写作 `jcc_hyper_tool …`**，与是否从 npm 全局安装、`npm link` 或其它包装方式无关；子命令与参数相同。
+
+## 守护进程（定时循环）
+
+**`jcc_hyper_daemon`** 按固定间隔反复 **`spawn`** 一次 **`jcc_hyper_tool`**：每次子进程退出后等待 **`--interval`** 秒再运行下一轮。子命令与参数必须写在 **`--`** 之后（与 `git` 等工具的 pass-through 习惯一致）。
+
+```bash
+jcc_hyper_daemon --interval 60 -- state reconcile --state-file ~/.jcc_hyper_tool/trade-state.json
+jcc_hyper_daemon --once -- config print
+```
+
+选项摘要：
+
+- **`-i, --interval <seconds>`**：周期间隔，默认 `60`。
+- **`--once`**：只跑一轮子命令后退出（便于脚本自检）。
+- **`--jcc-bin <path>`**：显式指定 `jcc_hyper_tool` 可执行文件；否则读取环境变量 **`JCC_HYPER_TOOL_BIN`**，若也未设置，则用**当前 Node** 调起与本包一同发布的 **`cli/index.js`**（与是否把 `jcc_hyper_tool` 装入 PATH 无关）。
+
+收到 **`SIGINT` / `SIGTERM`** 时守护进程会立即退出。更详细的示例见 **[Manual.md → jcc_hyper_daemon](./Manual.md#jcc_hyper_daemon)**。
+
+## 从源码参与开发
+
+在克隆下来的仓库根目录：
+
+```bash
+npm ci
+npm test
+npm run lint
+```
+
+执行 `npm install` / `npm ci` 后，脚本 **`prepare` 会运行 `npm run build`**，生成 `dist/`。若你**尚未**把 CLI 安装到全局 PATH，可临时用下表调用（**`--` 后面的参数与正文示例中跟在 `jcc_hyper_tool` 后的内容一致**）：
+
+| 方式                     | 示例                                                                                                    |
+| ------------------------ | ------------------------------------------------------------------------------------------------------- |
+| **npx**（在任意目录）    | `npx jcc_hyper_tool perp meta`                                                                          |
+| **npm script**           | `npm run cli -- perp meta`                                                                              |
+| **默认测试网（script）** | `npm run cli:testnet -- perp meta`（等价于命令前加 `--network testnet`）                                |
+| **直接 node**            | `node dist/cli/index.js perp meta`                                                                      |
+| **npm link**             | 在仓库根目录执行 `npm link`，之后可在任意目录运行 `jcc_hyper_tool …`                                    |
+| **守护进程（开发）**     | `npm run daemon -- --interval 60 -- state reconcile --state-file ./x.json`（同 **`jcc_hyper_daemon`**） |
+
+若已安装但仍提示 **`jcc_hyper_tool: command not found`**，检查 PATH。若在仓库里用 **`npx`** 报 **`dist/cli/index.js` 不存在**，执行 **`npm run build`**（或重新安装以触发 `prepare`）。
+
+## 环境变量
+
+本 CLI **不会**自动读取项目里的 **`.env` 文件**；变量须由 shell、`direnv`、容器编排、CI 密钥管理等注入到进程环境（开发时也可在终端里 `export …`）。仓库根目录的 **`.env.example`** 仅作命名和用途示例，**不要**把真实私钥写入仓库或配置文件。
+
+### 网络与 API
+
+| 变量                                         | 说明                                                                                                                                                       |
+| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `JCC_HYPER_NETWORK`                          | 全局 **`--network`** 的默认值：`mainnet` 或 `testnet`。不传 CLI 且未设置时 **默认为 `mainnet`**。与 **[测试网](#测试网)** 行为一致。                       |
+| `JCC_HYPER_API_URL` 或 `HYPERLIQUID_API_URL` | 可选：覆盖 **`/info` / `/exchange` 所用 HTTP 源**（仅 **`https://` 或 `http://` 的 origin**，误写 `.../info` 会被规范成 origin）。同全局 **`--api-url`**。 |
+
+### 钱包私钥（签名 / `--live`）
+
+| 变量                                                        | 说明                                                                                                                                                                                                                                                                                                                                                                |
+| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `JCC_HYPER_WALLET_PRIVATE_KEY` 或 `HYPERLIQUID_PRIVATE_KEY` | **以太坊格式私钥**，用于 **EIP-712 签名**并调用 **`POST /exchange`**。任一存在即可；若两者都设置，**优先使用** `JCC_HYPER_WALLET_PRIVATE_KEY`。支持 `0x` 前缀或 64 位十六进制字符串（程序会规范为 `0x…`）。**必须**在下述场景前设置：**`--live`** 下单、撤单、对账里需要真上报、以及依赖签名的子命令。**Dry-run**（默认）**不访问 `/exchange`**，一般**无需**私钥。 |
+
+**安全**：勿将私钥写入 README、脚本仓库、cron 明文、`git` 历史或聊天；测试请用 **Hyperliquid 测试网 + 一次性密钥**（见 **[测试网](#测试网)**）。
+
+### 钱包地址（只读或约束）
+
+| 变量                                                | 说明                                                                                                                                                                                                                        |
+| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `JCC_HYPER_WALLET_ADDRESS` 或 `HYPERLIQUID_ADDRESS` | 可选：**`0x` + 40 位十六进制**。用于 **`/info` 账户类**查询（如 `positions`、`orders list`、`fills`、`watch orders`）在未设置私钥时指定「查谁」；也可与私钥同时设置，若与私钥推导地址不一致，程序会 **报错** 以防选错账户。 |
+
+### 一览（快速查阅）
+
+| 变量                                                       | 用途摘要                                |
+| ---------------------------------------------------------- | --------------------------------------- |
+| `HYPERLIQUID_PRIVATE_KEY` / `JCC_HYPER_WALLET_PRIVATE_KEY` | 签名与 **`--live`**；dry-run 通常不需要 |
+| `HYPERLIQUID_ADDRESS` / `JCC_HYPER_WALLET_ADDRESS`         | 可选账户地址；只读查询或与私钥交叉校验  |
+| `JCC_HYPER_NETWORK`                                        | 默认 `mainnet` \| `testnet`             |
+| `JCC_HYPER_API_URL` / `HYPERLIQUID_API_URL`                | 可选 API origin，同 **`--api-url`**     |
+
+### 示例（勿照抄私钥值）
+
+```bash
+export JCC_HYPER_NETWORK=testnet
+export HYPERLIQUID_PRIVATE_KEY='0x……'   # 或 JCC_HYPER_WALLET_PRIVATE_KEY
+jcc_hyper_tool wallet address
+jcc_hyper_tool order place --coin BTC --side buy --limit-px 1 --sz 0.001 --tif Gtc --live
+```
+
+## 测试网
+
+Hyperliquid 提供 **[测试网 / 预览环境](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api)**，API 源为 **`https://api.hyperliquid-testnet.xyz`**（与主网相同的 `/info`、`/exchange` 路径）。本 CLI 在指定 **`--network testnet`** 或环境变量 **`JCC_HYPER_NETWORK=testnet`**（见 **[环境变量](#环境变量) → 网络与 API**）时使用该端点。**`/exchange` 签名**走 HL 的测试环境（与 Python SDK 中 main / test 的区分一致），**不是主网**。
+
+- **示例**：  
+  `jcc_hyper_tool --network testnet perp meta`  
+  `jcc_hyper_tool --network testnet wallet address`
+- **网页端**（资金 / 行情）：[https://app.hyperliquid-testnet.xyz](https://app.hyperliquid-testnet.xyz) — 请使用**一次性密钥**，勿复用主网私钥。
+
+若既不传 `--network`，也未设置 `JCC_HYPER_NETWORK`，**默认为主网**。
+
+## 命令说明
+
+全局选项：`--network mainnet|testnet`、`--api-url <origin>`、`-v` / `--verbose`、**`--state-file <path>`**（覆盖默认 **`~/.jcc_hyper_tool/trade-state.json`**）、**`--no-state`**（本次调用中 **`order place` / `order tpsl` / `strategy grid`** 不写、不读 trade state；与 **`state …`** 子命令同用会报错）。
+
+### 只读查询（Phase 1）
+
+- `config print`、`wallet address`
+- `perp meta`、`perp mid <coin>`、`perp book <coin>`、**`perp kline <coin>`**（K 线 / OHLCV，见下）
+- `positions`、`orders list [--coin COIN]`、`fills`
+
+**`perp kline <coin>`** — 调用 `/info` 的 **`candleSnapshot`**，返回与 API 一致的 JSON（通常为数组；字段含 `t,T,s,i,o,h,l,c,v,n`，精度保持字符串形式）。
+
+- **必填**：**`--interval`**（如 `5m`、`1h`、`1d`）。
+- **时间范围**：
+  - **不传** **`--start-time` / `--end-time`**：自动使用「截止到当前时间」的**默认回看区间**（由周期决定，见下表）。
+  - **手动**：须**同时**传入 **`--start-time`** 与 **`--end-time`**（Unix **毫秒**正整数，且 `start-time` ≤ `end-time`）。只传其一会报错。
+- **默认回看（不传时间时，`endTime = 本地请求时刻`，`startTime = endTime − 回看长度）**：
+
+| 周期     | 默认回看                                                                                      |
+| -------- | --------------------------------------------------------------------------------------------- |
+| `5m`     | **24 小时**（约 288 根，适合看盘日内结构）                                                    |
+| `1h`     | **30 天**                                                                                     |
+| `1d`     | **365 天**                                                                                    |
+| 其余周期 | 代码内按粒度递增设定（如 `1m` 24h、`15m` 7d、`4h` 90d、`1w` 约 2 年等），避免单次请求根数过大 |
+
+- **允许的 interval**：`1m`、`3m`、`5m`、`15m`、`30m`、`1h`、`2h`、`4h`、`8h`、`12h`、`1d`、`3d`、`1w`、`1M`。
+- **全局选项**：**`--network`**、**`--api-url`**；加 **`-v`** 可在默认窗口模式下打印一行 stderr 提示。
+
+示例（**仅用默认窗口**，无需时间参数）：
+
+```bash
+jcc_hyper_tool perp kline BTC --interval 5m
+jcc_hyper_tool perp kline ETH --interval 1d
+```
+
+示例（**5m**，显式时间戳）：
+
+```bash
+jcc_hyper_tool perp kline BTC --interval 5m \
+  --start-time 1704067200000 --end-time 1704153600000
+```
+
+示例（**1d**，显式时间戳）：
+
+```bash
+jcc_hyper_tool perp kline ETH --interval 1d \
+  --start-time 1704067200000 --end-time 1735689600000
+```
+
+示例（**HIP-3** `deployer:ASSET`，默认 **1h** 窗口）：
+
+```bash
+jcc_hyper_tool perp kline xyz:CL --interval 1h
+```
+
+HIP-3 合约名称形如 `deployer:ASSET`（例如 `xyz:CL`）。调用 `/info` 的 `allMids` 时需要正确的 **`dex`**（部署方）；本 CLI 在 `perp mid` 中会从 `coin` 里 `:` 前缀推断（也可用 **`--dex`** 覆盖）。**REST 里的 `coin` 字符串可能与网页 URL 路径不一致** — 若接口返回 `null` 或异常，请用 `perp meta --dex xyz` 核对 `universe[].name`（例如 WTI 类原油在 API 快照里常为 `xyz:CL`，而非路径里的 `xyz:WTIOIL`）。
+
+### 交易（Phase 2）
+
+官方 HTTP 接口说明见 [Exchange endpoint](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint)。签名遵循 Python SDK 的 `action_hash` + phantom **EIP-712** `Agent`（链 ID `1337`，域名为 `Exchange`）。
+
+- **`jcc_hyper_tool order place`** — 构造**限价单** wire；默认输出 **dry-run** JSON（无需私钥、不访问交易所）。
+  - **`--live`** — 签名并 `POST /exchange`（需要私钥）。提交前须在终端输入 **`YES`**，除非使用 **`--assume-yes`**。
+  - **`--state-file <path>`**（可选）— 覆盖根默认路径；在未使用根 **`--no-state`** 时，会在本地写入 / 更新 **`single_limit`** 意图（详见 **Phase 4**）。
+  - 示例：  
+    `jcc_hyper_tool order place --coin ETH --side buy --limit-px 2000 --sz 0.01 --tif Gtc`
+
+- **`jcc_hyper_tool order tpsl`** — **触发类**止盈 / 止损（`--tpsl tp|sl`，wire 为 `t.trigger`）。必填：`--coin`、`--side`、`--sz`、`--trigger-px`、`--tpsl`。二选一：**`--is-market`**（触发后按市价成交）或 **`--limit-px`**（触发后限价），不可同时使用。默认 **仅减仓（reduce-only）**；**`--no-reduce-only`** 允许加仓（与 **`--grouping positionTpsl`** 互斥）。可选 **`--grouping na|normalTpsl|positionTpsl`**（默认 **`na`**）；**`positionTpsl`** 下 **`--sz 0`** 表示按仓位全量 TP/SL。另有：`--cloid`、**`--dex`**（HIP-3；省略时从 `--coin` 的 `deployer:` 前缀推断，与 `order place` 一致）、**`--live`**、**`--assume-yes`**、**`--state-file`**（写入 **`standalone_tpsl`**，见 Phase 4）。默认 dry-run；**`--live`** 行为类似 `order place`（除非 **`--assume-yes`** 否则需输入 **`YES`**）。**风险**：务必先 dry-run；**`--live`** 请仅在测试网 + 一次性密钥上初次验证。
+  - 测试网 dry-run（触发后市价）：  
+    `jcc_hyper_tool --network testnet order tpsl --coin BTC --side sell --sz 0.001 --trigger-px 95000 --tpsl sl --is-market`
+  - 测试网 dry-run（整仓 TP/SL，`sz=0`，`positionTpsl`）：  
+    `jcc_hyper_tool --network testnet order tpsl --coin BTC --side sell --sz 0 --trigger-px 94000 --tpsl sl --is-market --grouping positionTpsl`
+
+- **`jcc_hyper_tool order cancel`** — 默认 dry-run；**`--live`** 为真实撤单。
+
+- **`jcc_hyper_tool order bracket`** — 创建 **bracket** 意图（入场限价 → 仅在对账认为入场已成交后再挂 TP/SL），**须有可写的 state 路径**（默认文件或 **`--state-file`**）；**不可用 **`--no-state`**。保护腿默认 **reduce-only**。触发方式与单项 tpsl 类似：**`--is-market`** 或 **`--protection-limit-px`**（互斥）。随后对该意图执行一次 **`state reconcile`**（无 **`--live`** 则为 dry）。完整参数见下文 **Bracket（`order bracket`）\*\* 一节。
+
+- **`jcc_hyper_tool watch orders`** — 轮询 `openOrders`，在 oid 集合或 payload 变化时打印 JSON 行。选项：`--poll-ms`、`--coin`、`--full`。
+
+### 策略（Phase 3）
+
+**`jcc_hyper_tool strategy grid`** — 在 **`--lower`** 与 **`--upper`** 之间按 **`--grids`** 档均匀铺限价，每档 **`--order-sz`**。默认输出 **dry-run** JSON（含解析后的 `prices` 与 `action`）。**`--live`** 时签名并 POST `/exchange`，与 `order place` 类似（需私钥；除非 **`--assume-yes`** 否则输入 **`YES`**）。
+
+- **`--bias symmetric`**（默认）：区间中点**以下**价位为**买**，**以上**为**卖**；恰好落在中点时约定为**买**（文档化边界情况）。
+- **`--bias long`** / **`--bias short`**：每一档全部为买或全部为卖。
+- **`--tif`**、**`--reduce-only`**：含义与单笔 `order place` 相同。
+- **HIP-3**：可选 **`--dex`** 解析 `meta`；省略且 `coin` 形如 `deployer:ASSET` 时从前缀推断（与 `perp mid` 思路一致）。
+- **`--max-orders`**：可选，限制**本批次**包含的订单数量（从低价端起截断）。HL 对批量大小另有上限；网格过大可能失败或有风险 — 请从小 `grids` 与 dry-run 开始。
+
+Dry-run 示例：
+
+`jcc_hyper_tool strategy grid --coin ETH --lower 2000 --upper 2200 --grids 5 --order-sz 0.01 --bias symmetric --tif Gtc`
+
+- **`--state-file <path>`**（可选）— 覆盖根默认；未使用 **`--no-state`** 时写入网格意图；配合 **`--live`** 时尝试从响应解析 **oid** 写回各 **leg**，便于 **`state reconcile`**。
+
+---
+
+## 实战：单边 / 双边网格、定时补单、一键撤销
+
+（与 **Phase 4** 默认 state 路径、`state cancel-open` 行为一致，详见下文 **[本地状态与对账（Phase 4）](#本地状态与对账phase-4)**。）
+
+本 CLI **不会替你自动「成交后在对侧按价差补单」**；典型做法是：**用脚本读行情或读 `state` + 你自己的步长公式**，算出新的区间后再调一次 **`strategy grid --live`**。下面用 **`ST`** 表示你的 `coin`；**`/path/to/state.json`** 在示例里显式写出，若你使用默认 state 文件，可省略所有 **`--state-file`**（见上文全局选项）。
+
+### 1）按某一价格区间挂网格（单次）
+
+理解 **`--bias`**：
+
+| 模式                | `--bias`            | 行为                                                                                                                                                                                |
+| ------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **双边 / 居中对称** | `symmetric`（默认） | 区间**下半**挂 **买**、**上半**挂 **卖**（恰好落在中点时约定为买，见源码 **`annotateGridSides`**）。一般让区间包住「现价 ± 带宽」。须 **`upper` &gt; `lower`** 且 **`grids` ≥ 1**。 |
+| **单边只做买**      | `long`              | 每一档都是 **买**（例如只在下方接货）。                                                                                                                                             |
+| **单边只做卖**      | `short`             | 每一档都是 **卖**（例如只在上方出货）。                                                                                                                                             |
+
+先 **dry-run**（无需私钥）看 `prices` 与 `action`：
+
+```bash
+jcc_hyper_tool strategy grid --coin ST --lower 100 --upper 110 --grids 5 --order-sz 0.01 \
+  --bias symmetric --tif Gtc --state-file ./trade-state.json
+```
+
+测试网真实下单（务必 **先 dry、小单、一次性密钥**）：
+
+```bash
+jcc_hyper_tool --network testnet strategy grid --coin ST --lower 100 --upper 110 --grids 5 \
+  --order-sz 0.01 --bias long --tif Gtc --state-file ./trade-state.json --live
+```
+
+**`--max-orders N`** 可限制本批次只发前 N 档（从低价端起），适合与脚本分批发。
+
+### 2）「成交后在对侧」补网格：脚本 / cron 思路
+
+没有内置「每成交一格就 ±X 价格自动反手」的单一子命令，推荐循环或 **cron** 驱动的小脚本，每轮做四件事（顺序可按你策略调整）：
+
+1. **对账**（把已不在簿上的 leg 记成 filled 等，并推进 bracket/grid 摘要）：  
+   `jcc_hyper_tool state reconcile --state-file ./trade-state.json`  
+   若需真实补挂 bracket 腿，再加 **`--live`**（本 README 不展开策略细节；网格续挂主要用下一步）。
+2. **取参考价**：自己的 REST / `perp mid ST`，或从 **`state list --state-file ...`** 的 JSON 看当前各 intent 阶段（不保证含最新成交价，价源仍以 HL 为准）。
+3. **按你的规则算新区间**：例如「上次中枢 `mid`，买单成交后在对侧卖单挂在 `mid + step`」——在脚本里用任意语言实现 `lower/upper/grids`。
+4. **再发一批网格**（仅当你明确要加新单时）：  
+   `jcc_hyper_tool strategy grid ... --state-file ./trade-state.json --live`
+
+**cron** 示例（每分钟对账一次；按需改成你的路径与用户；**不要将私钥写进 crontab 明文**，用登录 shell 已从环境注入为例）：
+
+```cron
+* * * * * /usr/bin/jcc_hyper_tool state reconcile --state-file /you/trade-state.json >>/tmp/jcc-reconcile.log 2>&1
+```
+
+也可以用 **`while sleep 60`** 的循环脚本做「守护进程」式轮询；把对账 + 定价 + 补挂写进函数即可：
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+STATE="${JCC_TRADE_STATE:-$HOME/.jcc_hyper_tool/trade-state.json}"
+
+while true; do
+  jcc_hyper_tool state reconcile --state-file "$STATE"
+  # TODO: 用 perp mid / 自管价格 + 你的 step 算出 LOWER UPPER，再决定是否补单，例如：
+  # jcc_hyper_tool strategy grid --coin ETH --lower "$LOWER" --upper "$UPPER" \
+  #   --grids 5 --order-sz 0.01 --bias symmetric --tif Gtc --state-file "$STATE" \
+  #   --live --assume-yes
+  sleep 60
+done
+```
+
+**注意**：上面仅作结构示例；**`--assume-yes`** 跳过确认，务必在测试网或小资金上验证后再用于自动化。
+
+### 3）紧急情况：一键撤掉 state 里仍在簿上的单
+
+对已写入默认或指定 **trade-state** 里的 **`single_limit` / `standalone_tpsl` / `bracket` 各腿 oid / `grid` legs**，可用 **`state cancel-open`**：**先比对 openOrders**，只对**仍在挂单列表里**的 oid 发撤单。
+
+预览（不 POST **`/exchange` 撤单**；仍会按规则 **GC** 精简本地文件）：
+
+```bash
+jcc_hyper_tool state cancel-open
+jcc_hyper_tool state cancel-open --state-file ./trade-state.json
+```
+
+真实撤单（需私钥；默认终端输入 **`YES`**；cron / 脚本可慎用 **`--assume-yes`**）：
+
+```bash
+jcc_hyper_tool state cancel-open --live
+jcc_hyper_tool state cancel-open --state-file ./trade-state.json --live --assume-yes
+```
+
+只针对某条 intent：
+
+```bash
+jcc_hyper_tool state cancel-open --state-file ./trade-state.json --intent <意图UUID> --live
+```
+
+撤单成功后同样会做一次 **GC**，终态 intent 会从文件里删掉，事件一并收缩，避免 state 无限长大。
+
+---
+
+## 本地状态与对账（Phase 4）
+
+**默认**使用 **`~/.jcc_hyper_tool/trade-state.json`**；根 **`--state-file`** 或各子命令 **`--state-file`** 可覆盖。**`--no-state`** 时 **`order place` / `order tpsl` / `strategy grid`** 不写 state；**`order bracket`** 与 **`state`** 子命令不可用 **`--no-state`**。Phase 4 使用本地 JSON 保存「意图」与阶段变更，面向**任务可读**的追踪，而不是 HL 原始 payload 的完整镜像。
+
+### 状态文件结构
+
+- **`version`**：当前固定为 `1`。
+- **`intents`**：多条意图，键为意图 id（一般为 UUID）。类型包括：
+  - **`bracket`**：入场限价 + 成交后再挂 TP/SL（保护单默认 **reduce-only**）。
+  - **`grid`**：网格参数 + 每一档 **leg**（含 oid、阶段等）。
+  - **`single_limit`**：单笔限价（配合 `order place --state-file`）。
+  - **`standalone_tpsl`**：独立触发单（配合 `order tpsl --state-file`）。
+- **`events`**：与该意图相关的事件日志。
+- **写入**：先写同目录临时文件再 **`rename`**，尽量原子化；重复对账依赖 **`dedupeKeys`**（`plan:*` / `done:*`），避免在同一模式下重复生成同一类「拟执行动作」。
+
+未使用根 **`--no-state`** 时，**`order place` / `order tpsl` / `strategy grid`** 会默认写入默认 state 文件（或根 / 子命令 **`--state-file`** 指定路径）。**`--no-state`** 则完全不写、不读。
+
+### `state` 子命令（**`--state-file`** 可省略，与根默认路径一致）
+
+| 子命令                                | 作用                                                                                                                                                                                                                                                                           |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **`state reconcile`**                 | 读状态 → 拉 **openOrders** 与 **clearinghouseState（仓位）** → 推进 bracket/grid 状态机 → **默认只输出 dry-run 计划**；加 **`--live`** 则在确认后真实下单 / 撤单（需私钥；可用 **`--assume-yes`** 跳过交互）。**`--intent <id>`** 可只处理一条意图。写回前会 **GC** 终态意图。 |
+| **`state cancel-open`**               | 从 state 收集 oid，与 **`openOrders`** 求交后按 **coin / assetIndex** 批量撤单；默认 **dry** 只出计划；**`--live`** 真实撤单（**`--assume-yes`** 可非交互）。结束后 **GC** 本地 state。                                                                                        |
+| **`state list`**                      | 以任务可读方式列出全部意图摘要（阶段、下一步提示等）。                                                                                                                                                                                                                         |
+| **`state show <intentId>`**           | 单条意图的结构化详情 + 最近相关事件。                                                                                                                                                                                                                                          |
+| **`state events <intentId>`**         | 该意图的事件流；支持 **`--tail N`**、**`--newest-first`**。                                                                                                                                                                                                                    |
+| **`state request-cancel <intentId>`** | 为 **bracket** 打上「请求撤销入场」标记；后续 **`reconcile`** 在合适阶段尝试撤销仍在簿上的入场单。                                                                                                                                                                             |
+
+说明：**dry-run 对账**会为已展示的计划写入 **`plan:*`**，避免连续两次 dry-run 重复打印同一批动作；**`--live`** **不会**因有 **`plan:*`** 而跳过真实下单，成功后会记 **`done:*`** 并清除对应 **`plan:*`**。
+
+### Bracket（`order bracket`）
+
+实现「**入场成交后再挂 TP/SL**」，降低保护单过早触发带来的异常风险。
+
+- **须有可写 state**（默认文件或 **`--state-file`**）；不可用 **`--no-state`**。
+- **必填**：**`--coin`**、**`--side`**（buy/sell）、**`--limit-px`**（入场限价）、**`--sz`**、**`--tp`**（止盈触发价）、**`--sl`**（止损触发价）。
+- **保护腿**：**`--is-market`**（触发后市价）或 **`--protection-limit-px`**（触发后限价，TP/SL 共用该限价语义）；二者互斥。
+- **可选**：**`--tif`**、**`--reduce-only`**（入场腿）、**`--expires-in-ms`**（相对 TTL，超时进入过期分支）、**`--dex`**、**`--live`** / **`--assume-yes`**。
+- **流程**：先写入 bracket 意图，再对该 **intent id** 执行一次 **`reconcile`**（dry 或 live）。live 且有多步动作时通常会有一次确认（**`--assume-yes`** 可跳过）。
+
+### 与现有命令的组合
+
+- **`order place`**（默认写 state，除非 **`--no-state`**）：dry / live 都会维护 **`single_limit`**（路径为默认或显式 **`--state-file`**）；live 成功后尝试解析 **oid**。
+- **`order tpsl`**：同上 → **`standalone_tpsl`**。
+- **`strategy grid`**：同上 → **`grid`**；live 后为各 leg 绑定 **oid**。
+
+### 示例
+
+```bash
+# 1）创建 bracket 意图并 dry-run 对账（写入 plan:*，不向交易所下单）
+jcc_hyper_tool order bracket --coin BTC --side buy --limit-px 95000 --sz 0.01 \
+  --tp 98000 --sl 93000 --state-file ./trade-state.json --is-market
+
+# 2）任务可读列表
+jcc_hyper_tool state list --state-file ./trade-state.json
+
+# 3）只 reconcile 一条意图（dry-run）
+jcc_hyper_tool state reconcile --state-file ./trade-state.json --intent <意图UUID>
+
+# 4）真实执行对账产生的动作（务必先在测试网验证）
+jcc_hyper_tool state reconcile --state-file ./trade-state.json --live --assume-yes
+```
+
+### 风险与局限
+
+- 状态机依赖 **HTTP 快照**（挂单 + 仓位），与撮合最终结果可能有延迟；请以**交易所界面与官方 API**为准交叉核对。
+- 网格某一档「挂单消失」在 MVP 中倾向记为 **filled**；若实际为用户撤单，摘要不保证与主观语义完全一致。
+- 任何 **`--live`** 请先在 **testnet** + **一次性密钥**验证；优先 **dry-run**。
+
+---
+
+## 校验与测试
+
+仓库内跑静态检查与单元测试：
+
+```bash
+npm run lint && npm run typecheck && npm run test
+```
+
+手工烟测（与上文示例一致，需已能在终端执行 **`jcc_hyper_tool`**）：
+
+```bash
+jcc_hyper_tool --network testnet perp meta
+jcc_hyper_tool order place --network testnet --coin BTC --side buy --limit-px 1 --sz 0.001 --tif Gtc
+```
+
+单元测试中对网络请求使用 **mock**，不代表真实 HL 行为；端到端请使用 **Hyperliquid 测试网** 与 **一次性私钥** 手动验证。

package/dist/cli/confirm.d.ts

@@ -0,0 +1,2 @@
+export declare function requireStdinYes(prompt: string): Promise<void>;
+//# sourceMappingURL=confirm.d.ts.map

package/dist/cli/confirm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirm.d.ts","sourceRoot":"","sources":["../../src/cli/confirm.ts"],"names":[],"mappings":"AAEA,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBnE"}

package/dist/cli/confirm.js

@@ -0,0 +1,22 @@
+import readline from "node:readline";
+export async function requireStdinYes(prompt) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stderr,
+    });
+    try {
+        const line = await new Promise((resolve, reject) => {
+            rl.once("SIGINT", () => {
+                reject(Object.assign(new Error("^C"), { name: "SIGINT" }));
+            });
+            rl.question(prompt, resolve);
+        });
+        if (line.trim() !== "YES") {
+            throw new Error(`Aborted (expected exactly YES). Got: '${line}'`);
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
+//# sourceMappingURL=confirm.js.map

package/dist/cli/confirm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirm.js","sourceRoot":"","sources":["../../src/cli/confirm.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,eAAe,CAAC;AAErC,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,MAAc;IAClD,MAAM,EAAE,GAAG,QAAQ,CAAC,eAAe,CAAC;QAClC,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,CAAC,CAAC;IACH,IAAI,CAAC;QACH,MAAM,IAAI,GAAW,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACzD,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE;gBACrB,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;YAC7D,CAAC,CAAC,CAAC;YACH,EAAE,CAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC/B,CAAC,CAAC,CAAC;QAEH,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,KAAK,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,yCAAyC,IAAI,GAAG,CAAC,CAAC;QACpE,CAAC;IACH,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,KAAK,EAAE,CAAC;IACb,CAAC;AACH,CAAC"}

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":""}