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
• 逐仓自动加保证金（risk isolated-top-up）：在 state reconcile 每轮开头评估逐仓持仓强平距离，必要时 updateIsolatedMargin；配置写入 userProfile.isolatedTopUp（默认关闭）
• LLM 顾问（advise）：DeepSeek 推理接口 + K 线与持仓上下文 → 结构化动作（wait / open_with_bracket / close_position / cancel_all）；默认 dry-run，真下单时经子命令既有 YES / --assume-yes 流程；用户偏好写入同文件 userProfile（advise profile）
• 跟单模式（copy）：跟踪指定 leader 钱包的永续仓位变化，按比例驱动 follower 调仓；支持 轮询（copy run）与 WebSocket 按 fill 跟单（copy watch）；独立 copy-state.json（不与 grid/advise 的 trade-state 混用）

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

按场景整理的「复制即用」指令集见 Manual.md（README 侧重完整说明，Manual 侧重实际命令）。

安装与运行

需要 Node.js 20+。安装发布包或按你的方式把 CLI 放进 PATH 后，终端中应能直接执行 jcc_hyper_tool（同包还提供 jcc_hyper_daemon，见 守护进程（定时循环））。

本文档中所有命令示例一律写作 jcc_hyper_tool …，与是否从 npm 全局安装、npm link 或其它包装方式无关；子命令与参数相同。

守护进程（定时循环）

网格、LLM 自动交易（advise） 与 跟单（copy） 应各跑一个 jcc_hyper_daemon，不要混在同一进程（分开 state 文件，避免持仓/挂单互相撤改）。若 advise 使用 open_with_bracket，还需另起一个 state reconcile daemon 指向同一份 advise state（入场成交后挂 TP/SL；仅跑 advise 不会自动挂保护腿）。详见 Manual.md → 定时循环。

jcc_hyper_daemon 按固定间隔 spawn 一次 jcc_hyper_tool；子命令写在 -- 之后。

# 网格：对账 / 补单 / 逐仓加保证金（可 30–120s）
jcc_hyper_daemon --mode grid --interval 60 --state-file ~/.jcc_hyper_tool/grid-state.json -- \
  state reconcile --live --assume-yes

# 自动交易：advise 单轮 + 自动执行（间隔 ≥ 300s，建议 900s+）
jcc_hyper_daemon --mode advise --interval 900 --state-file ~/.jcc_hyper_tool/advise-state.json -- \
  advise --coin xyz:CL --max-sz 2 --once --auto --live --assume-yes

# 跟单（轮询）：每 N 秒跑一次 copy run（建议 5–60s）
jcc_hyper_daemon --mode copy --interval 10 --state-file ~/.jcc_hyper_tool/copy-state.json -- \
  copy --leader 0xLEADER --ratio 0.2 --coins BTC,xyz:CL --live --assume-yes

# 跟单（WebSocket）：常驻 copy watch；子进程内 WS 跟 fill + 可选定期 reconcile
jcc_hyper_daemon --mode copy-watch --state-file ~/.jcc_hyper_tool/copy-state.json -- \
  copy watch --leader 0xLEADER --ratio 0.2 --coins BTC --live --assume-yes

jcc_hyper_daemon --once -- config print

选项摘要：

• -i, --interval <seconds>：周期间隔，默认 60；advise 子命令至少 300 秒（copy watch 子进程常驻时 interval 仅影响 daemon 外层 spawn 频率，一般配合 --mode copy-watch 使用 --interval 0 或较长间隔；推荐直接运行 copy watch 而非高频 respawn）。
• --mode grid|advise|copy|copy-watch：约束子命令类型，防止 grid / advise / copy 混用。
• --once（daemon 层）：守护进程只跑一轮子命令后退出；长期 advise 循环不要加此项。
• advise --once（子命令层）：每次 spawn 的 advise 只问模型一次后退出；与 daemon 循环配合使用（见 Manual.md → 自动交易守护进程）。
• --jcc-bin <path>：显式指定 jcc_hyper_tool 可执行文件。

userProfile / advise profile：偏好写在 trade-state.json 同一文件的 userProfile 字段里，不是单独配置文件；网格与 advise 可各用不同 state 路径，但 profile 须写入该 daemon 使用的 --state-file。审计日志在 advisor-log/，与 profile 无关。

收到 SIGINT / SIGTERM 时守护进程会立即退出。

从源码参与开发

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

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 调整命名可改此项）。 | | JCC_HYPER_COPY_STATE_FILE | 可选：跟单 state 默认路径（copy … 子命令）；未设时默认 ~/.jcc_hyper_tool/copy-state.json。与 grid/advise 的 trade-state.json 分开。 | | JCC_KLINE_SOURCE | 可选：K 线来源 hl（直连 Hyperliquid，默认）或 public（内网 Hub 缓存）。同 --kline-source。 | | JCC_KLINE_API_BASE | 可选：public 源 API 根地址（默认 http://192.168.66.249:3000）。 | | JCC_KLINE_STALE_ACTION | 可选：public 滞后/失败时的策略：fallback_hl（默认，回退 HL）|warn|reject|use。 | | JCC_KLINE_MAX_STALENESS_5M | 可选：5m K 线最大允许滞后（毫秒，默认 360000 = 6 分钟）。 |

钱包私钥（签名 / --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 密钥；可选模型覆盖 | | JCC_HYPER_COPY_STATE_FILE | copy：跟单 state 路径（默认 copy-state.json） | | JCC_KLINE_SOURCE / JCC_KLINE_API_BASE | K 线 Hub（public）或直连 HL（hl） | | JCC_KLINE_STALE_ACTION / JCC_KLINE_MAX_STALENESS_5M | Hub 滞后策略与 5m 最大滞后（默认 fallback + 6min） |

示例（勿照抄私钥值）

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、info、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；若指定 --kline-source public（或 JCC_KLINE_SOURCE=public），改从内网 Hub GET /v1/api/public/kline/list 拉取（字段会映射为与 HL 兼容的 o,h,l,c,v,t,T）。Hub 数据滞后超过阈值时，默认 fallback_hl 回退直连 HL。

• K 线源：--kline-source hl|public、--kline-api-base、--kline-stale-action fallback_hl|warn|reject|use（默认 fallback_hl）；也可写入 userProfile 或环境变量（见上表）。
• 必填：--interval（如 5m、1h、1d）。public 源仅支持：5m、15m、30m、1h、4h、1d、1w、1M。
• 时间范围：
  • 不传 --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% 的限价会被拒绝；**open_with_bracket / order bracket 还须满足 Hyperliquid 最低名义价值 $10（limit_px × sz，上下文含 min_order_sz 参考）。

动作枚举：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 的激进限价（近似市价减仓）；持仓大于 --max-sz 时按 cap 部分平仓，不再整单拒绝。

一轮 advise = 一次模型调用 → 一个动作；模型返回 wait 则不下单。--auto 会在通过护栏后自动执行该动作（仍可用不加 --live 做 dry-run）。

反同质化护栏（CLI 或 userProfile，详见 Manual）：

• --min-confidence / minConfidenceToExecute：低于阈值不执行；--auto 且未配置时默认 0.55。
• --limit-jitter-pct / limitPriceJitterPct：限价随机微偏移（仍须在 mid 偏离带宽内）。
• --sl-entry-shift <0-1> / bracketSlEntryShift：bracket 入场向模型止损平移（1 = 以原 SL 价挂限价单，TP/SL 等量平移；未成交无仓）。
• --execute-cooldown-sec / executeCooldownSec：同 coin + 同动作类型冷却；open_with_bracket 另按 side（buy/sell）区分；记录写在 state 的 adviseExecuteHistory（--live 成功后更新，键如 ${coin}:open_with_bracket:sell）。
• defaultMinSz / minSzByCoin（advise profile set --min-sz / --coin-min COIN=size）：开仓数量下限，与 HL $10 名义价值检查叠加（例如 xyz:CL 设 --coin-min xyz:CL=1 可禁止 0.15 等小 fractional 仓）。

风险偏好（userProfile.risk）

写入 trade-state.json → userProfile.risk，未设置时默认为 balanced。三种风格会联动 盈亏比护栏、止损宽度、ATR 动态 TP/SL 与 分批止盈；可用 advise profile info / jcc_hyper_tool info 查看合并 profile 后的实际生效值（含单项覆盖）。

| 维度 | conservative | balanced（默认） | aggressive | |------|------------------|----------------------|----------------| | 定位 | 趋势型：宽 TP、高 R:R、耐心埋伏 | 标准埋伏主路径 | 短线：更宽止损 %、更低 R:R | | 最低盈亏比（minRewardRiskRatio） | 2.5 : 1 | 2 : 1 | 1.5 : 1 | | SL 距 entry 上限（maxSlPctFromEntry） | 1.2% | 2% | 3% | | ATR TP/SL（atrTpslEnabled 默认开，1h/5m ATR） | 1h：×2 SL / ×8 TP，封顶 2.5×ATR | 1h：×2 SL / ×6 TP，封顶 2.5×ATR | 5m：×1.5 SL / ×3 TP，封顶 2×ATR | | 分批止盈（scaleOutEnabled） | 默认开（首 TP 平约 50%） | 默认关 | 默认关 | | 典型用法 | 商品/趋势品种、长 TTL 埋伏 | 通用自动交易 | 高波动、快进快出 |

说明：

• 固定 SL% 写入 system prompt 并参与硬护栏；启用 ATR 合并时（默认），护栏会取 max(固定%, ATR 管线上限)，并为 anti-sweep、sl-entry-shift 留余量，避免「ATR 拉宽止损却被固定 % 卡死」。
• open_with_bracket（scalp 槽） 不论 risk，执行前 ATR 均用 5m ×1.5 SL / ×2.5 TP；scalp 不分批止盈。
• 各字段均可单独覆盖，例如 --risk conservative 同时 profile set 里设 maxSlPctFromEntry、atrSlMult 等；详见 Manual.md → 风险偏好。

jcc_hyper_tool advise profile set --state-file ~/.jcc_hyper_tool/advise-state.json \
  --risk conservative

会话留痕目录（默认 ~/.jcc_hyper_tool/advisor-log/<uuid>.json）包含 reasoning_content（仅落盘；按 DeepSeek 要求不会回传到下一轮的 messages）。这不是 profile 文件——偏好仍在 trade-state.json → userProfile。

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 --once --auto

# v2 提示词：预计算指标模式（节省 token，指标值精确）
jcc_hyper_tool advise --coin BTC --max-sz 0.002 --context-version precomputed_indicators --once

# 用户风险偏好写入 trade-state 的 userProfile（与 intents 同文件；reconcile / cancel-open 不改此块）
jcc_hyper_tool advise profile set --state-file ~/.jcc_hyper_tool/advise-state.json \
  --risk balanced --min-confidence 0.6 --limit-jitter-pct 0.002 --sl-entry-shift 1 --execute-cooldown-sec 1800
jcc_hyper_tool advise profile show --state-file ~/.jcc_hyper_tool/advise-state.json
jcc_hyper_tool advise profile info --state-file ~/.jcc_hyper_tool/advise-state.json
jcc_hyper_tool info --state-file ~/.jcc_hyper_tool/advise-state.json
jcc_hyper_tool advise profile clear --state-file ~/.jcc_hyper_tool/advise-state.json

K 线条数默认 65 / 65 / 65（满足 EMA60 需 ≥61 根），可用 --bars5m / --bars1h / --bars1d 覆盖。周线默认关闭；启用方式：advise profile set --bars1w 65（未传 CLI --bars1w 时自动读取 profile），或单次运行 --bars1w 65。显式 --bars1w 0 可覆盖 profile 关闭周线。

多周期时间对齐（仅 public Hub 源）：拉取 5m/1h/1d(/1w) 后校验各周期最后一根 K 线 closeTime 是否在允许差内——默认 5m↔1h：6 分钟，1h↔1d：1 小时，1d↔1w：1 天。不对齐时按 klineStaleAction 处理（默认 fallback_hl 全量改拉 HL）。--dump-kline / 模型 payload 中的 kline_meta.alignment 可查看各对差距。

K 线数据源（advise 与 perp kline 共用）：默认 hl 直连 Hyperliquid；多客户端可改 public 走内网 Hub（数据仍源自 HL，但可集中分发）。public 模式下若最后一根 K 线收盘时间落后当前超过阈值（5m 默认 6 分钟），按 klineStaleAction 处理——默认 fallback_hl 自动改拉 HL，并 stderr 警告。配置优先级：CLI > 环境变量 > userProfile > 内置默认。

# 持久化到 advise state（daemon 推荐）
jcc_hyper_tool advise profile set --state-file ~/.jcc_hyper_tool/advise-state.json \
  --kline-source public --kline-stale-action fallback_hl

# 单次覆盖
jcc_hyper_tool advise --coin xyz:CL --max-sz 2 --kline-source public --once

advise profile info / jcc_hyper_tool info 的 「K 线数据源」 分区会显示当前生效配置。--dump-kline 输出含 kline_meta（各周期来源、滞后毫秒、是否 fallback）。

Prompt 上下文版本（--context-version）：控制发送给模型的 K 线和技术指标格式。

| 版本 | 说明 | |------|------| | raw_kline（默认，v1） | 原始 K 线 OHLCV 全量数据；模型自行分析 EMA/MACD/RSI/布林带等指标。兼容旧版行为。 | | precomputed_indicators（v2） | 服务端使用 trading-signals 库预计算技术指标（EMA 排列、MACD、RSI、布林带、ATR、量价），输出结构化中文摘要替代大部分 K 线数据；仅保留精简 5m/1h/1d K 线（与 v1 相同根数，仅 h/l/o/c/v 五字段）供波浪/缠论多周期联立、K 线形态和量价配合分析。大幅节省 token（约 75%）且指标值精确。 |

v2 模式下，模型 §1 分析框架会从「从裸 K 线计算指标」变为「解读预计算指标摘要并做综合判断」。相比 v1 额外提供的对数收益率衍生指标（ATR%、历史波动率、价格 Z-Score）让模型可以从跨价格量级可比的角度判断波动率环境和价格极端程度。

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

（默认 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 无限长大。

运行中调整网格间距（修改 state 文件）

网格运行期间，可以直接编辑 state 文件调整间距、范围或档数，无需重新运行 strategy grid 命令。

找到 state 文件中对应 grid intent，修改以下字段并新增 "regenerateGrid": true：

{
  "kind": "grid",
  "id": "xxx-xxx-xxx",
  "lower": 87.0,
  "upper": 93.0,
  "grids": 12,
  "bias": "symmetric",
  "orderSz": 0.01,
  "regenerateGrid": true,
  "legs": [...]
}

| 可改字段 | 含义 | |---------|------| | lower | 网格下界价格 | | upper | 网格上界价格 | | grids | 档位数（正整数） | | bias | symmetric（双边）/ long（只做多）/ short（只做空） | | orderSz | 每档挂单数量 |

保存后，下一次 reconcile 检测到 regenerateGrid: true 会：

1. 用新的 lower/upper/grids/bias 重新计算每条腿的价格
2. 保留已成交（filled）腿的历史记录
3. 自动撤销价格不在新网格中的活单（OID 仍在簿上的）
4. 新 pending 腿在下一次 reconcile 时挂单

注意：不要手动编辑 legs[].px 或 legs[].oid——让 regenerateGrid 自动重建更安全。修改前建议备份 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：与该意图相关的事件日志（逐仓加保证金事件使用虚拟 intentId _risk）。
• userProfile（可选）：顾问偏好 + isolatedTopUp 风控参数；reconcile / cancel-open 不删此块。
• adviseExecuteHistory（可选）：advise --live 成功执行后的冷却记录（键为 ${coin}:${action}；open_with_bracket 为 ${coin}:open_with_bracket:${side}）。
• 写入：先写同目录临时文件再 rename，尽量原子化；跨进程（例如 advise + reconcile 两个 daemon 共用 --state-file）通过 ${stateFile}.lock 互斥，默认最多等待 30s、每 50ms 重试；reconcile 写回时会保留 advise 刚更新的 adviseExecuteHistory / userProfile。重复对账依赖 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> 可只处理一条意图（逐仓评估也仅针对该 intent 的 coin）。写回前会 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。

逐仓自动加保证金（risk isolated-top-up）

当网格或 bracket 产生逐仓持仓且 mark 与强平价距离偏紧时，可在 state reconcile 每轮开头（grid/bracket 动作之前）自动调用 Hyperliquid updateIsolatedMargin 追加 USDC 保证金。

适用范围（代码硬约束）

| 场景 | 行为 | |------|------| | 全仓（leverage.type === "cross"） | 跳过 | | 无持仓（\|szi\| === 0） | 跳过 | | 逐仓 + 有持仓 | 评估是否加仓 |

加多少（目标驱动）

1. 计算当前安全距离：distancePct = |mark − liq| / mark × 100
2. 若 distancePct >= safeDistancePct（默认 8%）→ 不加
3. 否则算拉到安全距离所需 USDC：neededUsd ≈ gapPx × |szi| × safetyFactor（默认 safetyFactor = 1.10）
4. 可加仓池：withdrawable − reserveUsd（默认 reserveUsd = 100，留给网格挂单）
5. 钱够 → 加 neededUsd；不够 → 加 availableToAdd（partial）；若 partial 后不足 minPartialUsd（默认 20） → 只记日志、不加

配置（写入 trade-state.json → userProfile.isolatedTopUp，默认 enabled: false）：

{
  "userProfile": {
    "isolatedTopUp": {
      "enabled": true,
      "safeDistancePct": 8,
      "safetyFactor": 1.1,
      "reserveUsd": 100,
      "minTopUpUsd": 5,
      "minPartialUsd": 20,
      "maxSingleTopUpUsd": 5000,
      "maxDailyTopUpUsd": 20000,
      "cooldownSec": 300
    }
  }
}

CLI

# 启用并设置保留金（写入 state 文件 userProfile）
jcc_hyper_tool risk isolated-top-up configure --enable --reserve-usd 100 --state-file ./trade-state.json

# 仅预览本轮评估（不 POST /exchange）
jcc_hyper_tool risk isolated-top-up plan --state-file ./trade-state.json

# 与 grid 对账一起跑（dry 会在 dryPlan 里列出 isolated_top_up / isolated_top_up_skip）
jcc_hyper_tool state reconcile --state-file ./trade-state.json

# 真实加保证金（与 grid live 共用一次 YES / --assume-yes）
jcc_hyper_tool state reconcile --state-file ./trade-state.json --live --assume-yes

daemon 示例（仅 grid daemon；与 advise 分开进程，见 守护进程）：

jcc_hyper_daemon --mode grid --interval 60 -- state reconcile --state-file ~/.jcc_hyper_tool/grid-state.json --live --assume-yes

输出：state reconcile JSON 的 dryPlan / actionsExecuted 含 isolated_top_up 或 isolated_top_up_skip；事件类型 isolated_margin_top_up_executed / _skipped / _failed 写入 events。

注意：withdrawable 为账户级；同地址多 coin 多 daemon 会共享可加仓池。加保证金成功后不会立刻 refetch 全量仓位；下轮 reconcile 用新 liquidationPx 验证效果。

跟单模式（copy / copy-trade）

跟踪指定 leader 钱包在 Hyperliquid 永续上的净仓位变化，驱动 follower（本 CLI 配置的钱包）按比例调仓。与 grid / advise 独立 state 文件（默认 ~/.jcc_hyper_tool/copy-state.json），勿与 trade-state.json 混用。

设计细节见 Manual.md → 跟单模式。

三种运行方式

| 方式 | 命令 | 驱动 | 适用 | |------|------|------|------| | 轮询（Phase 1） | copy run / copy plan | HTTP clearinghouseState 快照 | 简单、可 cron / --mode copy daemon | | Mirror TP/SL（Phase 2） | 同上 + --tpsl-mode mirror | 轮询 + leader openOrders | 镜像 leader 保护单 | | WebSocket（Phase 3） | copy watch | userFills 实时 + 可选 reconcile | 低延迟、按 fill 精确跟随 |

必填与风控

• --leader <0x…>、--ratio <n>（如 0.2 = 20%）
• --coins BTC,xyz:CL 或显式 --all-coins（避免无意全跟）
• 常用风控：--min-usd、--max-usd-per-coin、--max-usd-total、--skip-if-margin-low、--slippage-bps
• --start-mode wait_for_change（默认：不追仓，只跟 leader 后续变化）| sync_now（启动即同步到 leader × ratio）
• --reduce-only（默认）：减仓/平仓强制 reduce-only；反向时先平后开

TP/SL

| --tpsl-mode | 行为 | |-------------------|------| | local（默认） | follower 自行预挂 SL（--preplace-sl）；不依赖 leader 是否设保护 | | mirror | 解析 leader TP/SL trigger 单并镜像到 follower（--require-sl 时 leader 无 SL 则拒绝开仓） |

子命令

| 子命令 | 作用 | |--------|------| | copy / copy run | 执行一轮（默认 dry-run；--live 真下单） | | copy plan | 只输出本轮计划 | | copy status | leader/follower 快照、目标仓位、dedupe 状态 | | copy watch | WebSocket 常驻；leader 每笔 fill → 按比例跟单 |

copy watch 额外选项：

• --reconcile-interval-sec <n>（默认 60）：兜底轮询 copy run，修正漂移并同步 mirror TP/SL；0 关闭
• --fill-coalesce-ms <n>：同币种 fill 合并窗口（默认 0）
• --max-processed-fills-per-coin <n>：fill 幂等 ring buffer（默认 500）

示例

export HYPERLIQUID_PRIVATE_KEY='0x……'   # follower 钱包；--live 必填

# 预览计划（不下单）
jcc_hyper_tool copy plan \
  --leader 0xLEADER --ratio 0.2 --coins BTC,xyz:CL

# 轮询跟单（单次）
jcc_hyper_tool copy run \
  --leader 0xLEADER --ratio 0.2 --coins BTC \
  --live --assume-yes \
  --state-file ~/.jcc_hyper_tool/copy-state.json

# WebSocket 低延迟（Ctrl+C 退出）
jcc_hyper_tool copy watch \
  --leader 0xLEADER --ratio 0.2 --coins BTC \
  --tpsl-mode mirror --reconcile-interval-sec 60 \
  --live --assume-yes

# daemon：轮询
jcc_hyper_daemon --mode copy --interval 10 \
  --state-file ~/.jcc_hyper_tool/copy-state.json -- \
  copy --leader 0xLEADER --ratio 0.2 --coins BTC --live --assume-yes

copy-state 与 trade-state

• copy-state.json：leader/follower 快照、baseline、dedupe、mirror 快照、processedFillKeysByCoin（WS fill 幂等）
• 不要与 grid / advise 的 trade-state.json 共用；跟单 daemon 使用 --mode copy 或 --mode copy-watch

风险与局限

• 跟单存在时间差与滑点；无法 100% 复刻 leader 成交价
• wait_for_change 启动时不追已有仓位；sync_now 会立即同步，请配合 --max-entry-deviation-pct 等护栏
• mirror 模式下 leader 保护单异常（多套 TP/SL、与仓位不一致）时，工具会 best-effort 选取 positionTpsl 最接近仓位规模的一套
• 任何 --live 请先在 testnet + 一次性密钥验证

校验与测试

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

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