jcc_hyper_tool

面向 Hyperliquid 永续合约的命令行工具：

• 只读 /info 查询：配置、行情、盘口、K 线、持仓、挂单、成交等
• 签名 /exchange：限价 / 触发单 / bracket 等下单与撤单，以及 HTTP 轮询 watch orders
• 网格策略（strategy grid）：在价格区间内批量铺限价
• 本地 JSON 状态（默认 ~/.jcc_hyper_tool/trade-state.json；根或子命令 --state-file 可改路径；根 --no-state 可关闭挂单类命令的读写）：state reconcile / state cancel-open，跟踪 bracket / grid 意图，并在入场视为成交后再推进 TP/SL
• LLM 顾问（advise）：DeepSeek 推理接口 + K 线与持仓上下文 → 结构化动作（wait / open_with_bracket / close_position / cancel_all）；默认 dry-run，真下单时经子命令既有 YES / --assume-yes 流程；用户偏好写入同文件 userProfile（advisor profile）

私钥仅通过环境变量提供，请勿写入仓库或配置文件；变量名、何时必填与安全注意见 环境变量。

按场景整理的「复制即用」指令集见 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 习惯一致）。

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。

从源码参与开发

在克隆下来的仓库根目录：

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。 | | DEEPSEEK_API_KEY | advise 必填：DeepSeek OpenAI 兼容 /v1/chat/completions。勿提交到仓库。 | | DEEPSEEK_MODEL | 可选：覆盖默认模型 ID（默认 deepseek-v4-pro；若 DeepSeek 调整命名可改此项）。 |

钱包私钥（签名 / --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 | | DEEPSEEK_API_KEY / DEEPSEEK_MODEL | advise：API 密钥；可选模型覆盖 |

示例（勿照抄私钥值）

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 提供 测试网 / 预览环境，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 — 请使用一次性密钥，勿复用主网私钥。

若既不传 --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 … 子命令同用会报错）。

只读查询

• 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 提示。

示例（仅用默认窗口，无需时间参数）：

jcc_hyper_tool perp kline BTC --interval 5m
jcc_hyper_tool perp kline ETH --interval 1d

示例（5m，显式时间戳）：

jcc_hyper_tool perp kline BTC --interval 5m \
  --start-time 1704067200000 --end-time 1704153600000

示例（1d，显式时间戳）：

jcc_hyper_tool perp kline ETH --interval 1d \
  --start-time 1704067200000 --end-time 1735689600000

示例（HIP-3 deployer:ASSET，默认 1h 窗口）：

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）。

交易

官方 HTTP 接口说明见 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 意图（详见 本地状态与对账）。
  • 示例：
    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，见 本地状态与对账）。默认 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（默认 perp + 各 builder dex），在 oid 集合或 payload 变化时打印 JSON 行。选项：--poll-ms、--coin、--full。

策略

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。

LLM 顾问（advise）

使用 DeepSeek OpenAI 兼容接口（环境变量 DEEPSEEK_API_KEY，可选 DEEPSEEK_MODEL，默认模型 deepseek-v4-pro）。拉取当前 coin 的 5m / 1h / 1d K 线与 clearinghouse 持仓，拼成结构化上下文；模型只允许输出 JSON 动作（经 Zod 校验，失败会自动重试最多 2 次）。--max-sz 为强制硬顶；价格相对 mid 偏离超过 profile / 默认 3% 的限价会被拒绝。

动作枚举：wait | open_with_bracket | close_position | cancel_all。执行时通过 spawnSync 调本包 jcc_hyper_tool 子命令，继承现有 --live / --assume-yes / YES 与 dry-run 语义。open_with_bracket、cancel_all 需要可写 trade-state.json（勿与根 --no-state 同用）。close_position 的 market 在实现上为 IOC + 相对 mid 的激进限价（近似市价减仓）。

会话留痕目录（默认 ~/.jcc_hyper_tool/advisor-log/<uuid>.json）包含 reasoning_content（仅落盘；按 DeepSeek 要求不会回传到下一轮的 messages）。

export DEEPSEEK_API_KEY='sk-…'
# 交互 REPL（默认）：模型回合后输入自然语言 / show / execute / quit
jcc_hyper_tool advise --coin BTC --max-sz 0.002

# 单轮
jcc_hyper_tool advise --coin BTC --max-sz 0.002 --note "manual note" --once

# 单轮后立刻走执行分支（仍可 dry-run，不加 --live 则子命令亦 dry-run）
jcc_hyper_tool advise --coin BTC --max-sz 0.002 --auto

# 用户风险偏好写入 trade-state（与 intents 并存；reconcile / cancel-open 不改此块）
jcc_hyper_tool advisor profile set --risk conservative --max-sz 0.005 --notes "short swing"
jcc_hyper_tool advisor profile show
jcc_hyper_tool advisor profile clear

K 线条数默认 48 / 48 / 30，可用 --bars5m / --bars1h / --bars1d 覆盖。

实战：单边 / 双边网格、定时补单、一键撤销

（默认 state 路径与 state cancel-open 等行为与下文 本地状态与对账 一致。）

本 CLI 不会替你自动「成交后在对侧按价差补单」；典型做法是：用脚本读行情或读 state + 你自己的步长公式，算出新的区间后再调一次 strategy grid --live。下面用 ST 表示你的 coin；/path/to/state.json 在示例里显式写出，若你使用默认 state 文件，可省略所有 --state-file（见上文全局选项）。

1）按某一价格区间挂网格（单次）

理解 --bias：

| 模式 | --bias | 行为 | | ------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 双边 / 居中对称 | symmetric（默认） | 区间下半挂 买、上半挂 卖（恰好落在中点时约定为买，见源码 annotateGridSides）。一般让区间包住「现价 ± 带宽」。须 upper > lower 且 grids ≥ 1。 | | 单边只做买 | long | 每一档都是 买（例如只在下方接货）。 | | 单边只做卖 | short | 每一档都是 卖（例如只在上方出货）。 |

先 dry-run（无需私钥）看 prices 与 action：

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、小单、一次性密钥）：

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 已从环境注入为例）：

* * * * * /usr/bin/jcc_hyper_tool state reconcile --state-file /you/trade-state.json >>/tmp/jcc-reconcile.log 2>&1

也可以用 while sleep 60 的循环脚本做「守护进程」式轮询；把对账 + 定价 + 补挂写进函数即可：

#!/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：先拉取并合并默认 perp 与各 perpDexs builder 账簿的 openOrders（与 HIP-3 挂单一致），再与 state 中的 oid 求交，只对仍在挂单列表里的 oid 发撤单。

预览（不 POST /exchange 撤单；仍会按规则 GC 精简本地文件）：

jcc_hyper_tool state cancel-open
jcc_hyper_tool state cancel-open --state-file ./trade-state.json

真实撤单（需私钥；默认终端输入 YES；cron / 脚本可慎用 --assume-yes）：

jcc_hyper_tool state cancel-open --live
jcc_hyper_tool state cancel-open --state-file ./trade-state.json --live --assume-yes

只针对某条 intent：

jcc_hyper_tool state cancel-open --state-file ./trade-state.json --intent <意图UUID> --live

撤单成功后同样会做一次 GC，终态 intent 会从文件里删掉，事件一并收缩，避免 state 无限长大。

本地状态与对账

默认使用 ~/.jcc_hyper_tool/trade-state.json；根 --state-file 或各子命令 --state-file 可覆盖。--no-state 时 order place / order tpsl / strategy grid 不写 state；order bracket 与 state 子命令不可用 --no-state。工具在本地 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（默认 perp + 各 builder dex）与 clearinghouseState（仓位） → 推进 bracket/grid 状态机 → 默认只输出 dry-run 计划；加 --live 则在确认后真实下单 / 撤单（需私钥；可用 --assume-yes 跳过交互）。--intent <id> 可只处理一条意图。写回前会 GC 终态意图。 | | state cancel-open | 从 state 收集 oid，与 合并后的 openOrders（默认 perp + 各 builder dex）求交后按 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。

示例

# 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。

校验与测试

仓库内跑静态检查与单元测试：

npm run lint && npm run typecheck && npm run test

手工烟测（与上文示例一致，需已能在终端执行 jcc_hyper_tool）：

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 测试网 与 一次性私钥 手动验证。