dsh-hyperliquid 0.2.0 → 0.4.0

package/lib/review.d.ts

@@ -0,0 +1,3 @@
+export interface ReviewRecord { id: string; coin: string; oid: string | number | null; time: number | null; px: number | null; size: number | null; isBuy: boolean | null; gross: number | null; fee: number | null; feeToken: string; net: number | null; reference: number | null; slippageBps: number | null; closedSize: number | null; reason: string; sessionId: string | null; flags: string[]; source: string }
+export declare function fundingWindow(client: any, address: string, startTime: number, endTime: number): Promise<{rows: any[]; status: string; pages: number}>
+export declare function reviewLedger(payload: any, coin?: string): { records: ReviewRecord[]; orders: any[]; duplicates: number; fees: Record<string, number>; gross: number | null; tradingNet: number | null; funding: number | null; net: number | null; closeCount: number; missingReasons: number; unmatched: number; gaps: number; unsupported: number }

package/lib/review.js

@@ -0,0 +1,79 @@
+/** Evidence over a bounded history window; missing fields remain unknown. No balance inference. */
+const numeric = (value) => value == null || value === '' || !Number.isFinite(Number(value)) ? null : Number(value)
+const key = (row) => row?.oid == null || !row.coin ? null : `${row.coin}:${String(row.oid)}`
+const core = (coin) => typeof coin === 'string' && coin.trim().length > 0 && !coin.startsWith('#') && !coin.includes(':') && !coin.startsWith('@') && !coin.includes('/')
+export async function fundingWindow(client, address, startTime, endTime) {
+  const rows = [], seen = new Set(); let cursor = startTime, partial = false
+  for (let page = 0; page < 12; page++) {
+    const result = await client.info('userFunding', { user: address, startTime: cursor, endTime })
+    if (!Array.isArray(result)) throw Error('资金费历史响应无效')
+    const valid = result.filter((row) => Number.isFinite(Number(row.time)) && Number(row.time) >= cursor && Number(row.time) <= endTime && row.delta?.type === 'funding')
+    if (valid.length !== result.length) partial = true
+    for (const row of valid) {
+      const id = `${row.time}:${row.hash ?? ''}:${row.delta.coin}:${row.delta.usdc}`
+      if (!seen.has(id)) { seen.add(id); rows.push(row) }
+    }
+    if (result.length < 500) return { rows, status: partial ? 'partial' : 'complete', pages: page + 1 }
+    const last = Math.max(...valid.map((row) => Number(row.time)))
+    if (!Number.isFinite(last) || last <= cursor) return { rows, status: 'partial', pages: page + 1 }
+    // Inclusive boundary: repeat the final timestamp and deduplicate, avoiding lost peers.
+    cursor = last
+  }
+  return { rows, status: 'partial', pages: 12 }
+}
+export function reviewLedger(payload, coin = '') {
+  const orders = (payload.orders ?? []).filter((row) => !coin || row.coin === coin)
+  const allFills = (payload.fills ?? []).filter((row) => !coin || row.coin === coin)
+  const byOrder = new Map(orders.filter((row) => key(row)).map((row) => [key(row), row]))
+  const seen = new Set(), records = []; let duplicates = 0
+  for (const [index, fill] of allFills.entries()) {
+    const id = fill.tid != null ? `${fill.coin}:${fill.tid}` : payload.mode === 'paper' && fill.oid ? `${fill.coin}:${fill.oid}` : `unidentified:${index}`
+    if (seen.has(id)) { duplicates++; continue } seen.add(id)
+    const order = byOrder.get(key(fill)), pnl = numeric(fill.closedPnl ?? fill.realized), fee = numeric(fill.fee)
+    const feeToken = String(fill.feeToken ?? '').trim()
+    const px = numeric(fill.px), size = numeric(fill.sz), buy = typeof fill.isBuy === 'boolean' ? fill.isBuy : fill.side === 'B' ? true : fill.side === 'A' ? false : null
+    const reference = numeric(fill.referencePx ?? order?.referencePx)
+    const reason = fill.reason || order?.reason || ''
+    const closed = numeric(fill.closedSize) ?? (buy != null && numeric(fill.startPosition) != null && Math.sign(Number(fill.startPosition)) !== (buy ? 1 : -1) ? Math.min(Math.abs(Number(fill.startPosition)), size ?? 0) : /^Close/.test(fill.dir ?? '') ? size : null)
+    const eligible = core(fill.coin) && feeToken === 'USDC'
+    const net = eligible && pnl != null && fee != null ? pnl - fee : null
+    const flags = []
+    if (!order) flags.push('unmatched-order')
+    if (px == null || px <= 0) flags.push('missing-price')
+    if (size == null || size <= 0) flags.push('missing-size')
+    if (numeric(fill.time) == null) flags.push('missing-time')
+    if (buy == null) flags.push('missing-side')
+    if (!reason || /^(session:|tool$|chat$|order$)/.test(reason)) flags.push('missing-reason')
+    if (fee == null || !feeToken) flags.push('missing-fee')
+    if (pnl == null) flags.push('missing-pnl')
+    if (fill.tid == null && payload.mode !== 'paper') flags.push('missing-trade-id')
+    records.push({ id, coin: fill.coin, oid: fill.oid ?? null, time: numeric(fill.time), px, size, isBuy: buy, gross: pnl, fee, feeToken, net,
+      reference, slippageBps: reference && reference > 0 && px && buy != null ? (buy ? px - reference : reference - px) / reference * 10_000 : null,
+      closedSize: closed, reason: flags.includes('missing-reason') ? '' : reason, sessionId: fill.sessionId ?? order?.sessionId ?? null, flags, source: payload.mode })
+  }
+  const reconciled = orders.map((order) => {
+    const fills = records.filter((row) => key(row) && key(row) === key(order))
+    const filled = fills.reduce((sum, row) => sum + (row.size ?? 0), 0)
+    const expected = numeric(order.origSz ?? order.sz), tolerance = Math.max(1e-8, (expected ?? 0) * 1e-6)
+    const status = fills.some((row) => row.flags.includes('missing-size')) ? 'missing-size' : /filled/i.test(order.status ?? '') && expected != null && Math.abs(filled - expected) > tolerance ? 'size-gap'
+      : expected != null && filled > expected + tolerance ? 'excess-fill' : fills.length ? 'matched' : 'no-fill-in-window'
+    return { coin: order.coin, oid: order.oid ?? null, status, filled, expected, exchangeStatus: order.status ?? 'unknown', reason: order.reason ?? '' }
+  })
+  const supported = records.filter((row) => core(row.coin))
+  const fees = {}; for (const row of records) if (row.fee != null && row.feeToken) fees[row.feeToken] = (fees[row.feeToken] ?? 0) + row.fee
+  const supportedScope = !coin || core(coin)
+  const gross = supportedScope ? supported.reduce((sum, row) => sum + (row.gross ?? 0), 0) : null
+  const tradingNet = !supportedScope || supported.some((row) => row.net == null) ? null : supported.reduce((sum, row) => sum + row.net, 0)
+  const fundingRows = (payload.funding ?? []).filter((row) => core(row.delta?.coin) && (!coin || row.delta.coin === coin))
+  const funding = supportedScope && payload.coverage?.fundingStatus === 'complete' && fundingRows.every((row) => numeric(row.delta.usdc) != null)
+    ? fundingRows.reduce((sum, row) => sum + Number(row.delta.usdc), 0) : null
+  const closes = supported.filter((row) => row.closedSize > 0)
+  return { records, orders: reconciled, duplicates, fees, gross, tradingNet, funding,
+    net: tradingNet != null && funding != null ? tradingNet + funding : null,
+    closeCount: closes.length,
+    missingReasons: records.filter((row) => row.flags.includes('missing-reason')).length,
+    unmatched: records.filter((row) => row.flags.includes('unmatched-order')).length,
+    gaps: reconciled.filter((row) => ['size-gap', 'excess-fill'].includes(row.status)).length,
+    unsupported: records.length - supported.length,
+  }
+}

package/lib/risk-settings.js

@@ -1,3 +1,4 @@
+import { canonicalMarketCoin } from './market-symbol.js'
 /** Validate the user-editable trading limits before they reach either guard. */
 export function normalizeRiskSettings(input) {
   if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error('交易设置无效')
@@ -5,7 +6,7 @@ export function normalizeRiskSettings(input) {
   if (Object.keys(input).some((key) => !allowed.includes(key)) || allowed.some((key) => !(key in input))) throw new Error('交易设置字段无效')
   const coins = typeof input.allowedCoins === 'string' ? input.allowedCoins.split(',') : input.allowedCoins
   if (!Array.isArray(coins)) throw new Error('允许交易的币对无效')
-  const allowedCoins = [...new Set(coins.map((coin) => String(coin).trim()).filter(Boolean))]
+  const allowedCoins = [...new Set(coins.map((coin) => canonicalMarketCoin(coin)).filter(Boolean))]
   if (!allowedCoins.length || allowedCoins.length > 100 || allowedCoins.some((coin) => coin.length > 32 || !/^[A-Za-z0-9:_-]+$/.test(coin))) {
     throw new Error('允许交易的币对无效')
   }

package/lib/scan.js

@@ -0,0 +1,91 @@
+/**
+ * dsh-hyperliquid — market radar (市场雷达). Scans the most liquid tradable perps (core + USDC HIP-3)
+ * for a few plain, verifiable signals and returns the top few of each with the data time, so the
+ * agent opens a conversation with something concrete instead of a questionnaire.
+ * Kept deliberately small (codex review): ~20 markets, cached, no OI-anomaly claims without a baseline.
+ * @module lib/scan
+ */
+
+import { closedCandles } from './indicators.js'
+
+const num = (value) => value == null || value === '' || !Number.isFinite(Number(value)) ? null : Number(value)
+
+/**
+ * Pure part: rank markets by signal. `ranges` maps coin → { high, low, bars } of the last closed 1h bars.
+ * @returns {{ funding, movers, premium, levels }} top entries per signal
+ */
+export function rankSignals(markets, ranges = {}, { top = 3 } = {}) {
+  const rows = markets.map((m) => {
+    const ctx = m.ctx ?? {}
+    const mark = num(ctx.markPx), prev = num(ctx.prevDayPx), oracle = num(ctx.oraclePx), funding = num(ctx.funding)
+    return { coin: m.name, kind: m.kind, mark, change24h: mark && prev ? mark / prev - 1 : null,
+      fundingApr: funding == null ? null : funding * 24 * 365, premium: mark && oracle ? mark / oracle - 1 : null, volume: num(ctx.dayNtlVlm) }
+  }).filter((row) => row.mark != null)
+  const pick = (list, score) => list.filter((row) => score(row) != null).sort((a, b) => Math.abs(score(b)) - Math.abs(score(a))).slice(0, top)
+  const levels = rows.map((row) => {
+    const range = ranges[row.coin]
+    if (!range || !(range.high > range.low)) return null
+    const toHigh = range.high / row.mark - 1, toLow = row.mark / range.low - 1
+    const side = toHigh <= toLow ? 'high' : 'low'
+    return { ...row, side, distance: Math.min(Math.abs(toHigh), Math.abs(toLow)), high: range.high, low: range.low, bars: range.bars, broken: row.mark > range.high || row.mark < range.low }
+  }).filter(Boolean).sort((a, b) => (Number(b.broken) - Number(a.broken)) || a.distance - b.distance).slice(0, top)
+  return {
+    funding: pick(rows, (row) => row.fundingApr),
+    movers: pick(rows, (row) => row.change24h),
+    premium: pick(rows.filter((row) => row.kind === 'hip3' || Math.abs(row.premium ?? 0) > 0.001), (row) => row.premium),
+    levels,
+  }
+}
+
+const cache = new Map()
+
+/** Live part: pick the liquid tradable perps, read their last 20 closed 1h bars, rank. Cached 60s. */
+export async function scanMarkets(remote, { limit = 20, minVolumeUsd = 1_000_000 } = {}) {
+  const network = remote.cfg?.network, client = remote.client
+  const assertCurrent = () => { if (remote.cfg?.network !== network || remote.client !== client) throw new Error('网络已切换，请重新扫描') }
+  const key = `${network}:${limit}:${minVolumeUsd}`
+  const hit = cache.get(key)
+  if (hit && Date.now() - hit.at < 60_000) return hit.result
+  const catalog = await remote.marketCatalog()
+  assertCurrent()
+  // HIP-3 contexts normally arrive over the websocket; when the catalog has none, read each dex once.
+  const missing = [...new Set(catalog.markets.filter((m) => m.kind === 'hip3' && m.tradable && !m.ctx).map((m) => m.name.split(':')[0]))]
+  const filled = new Map()
+  await Promise.all(missing.map(async (dex) => {
+    try {
+      const [meta, ctxs] = await client.info('metaAndAssetCtxs', { dex })
+      for (const [index, asset] of (meta?.universe ?? []).entries()) if (ctxs?.[index]) filled.set(asset.name, ctxs[index])
+    } catch { /* that dex simply stays out of this scan */ }
+  }))
+  assertCurrent()
+  if (filled.size) catalog.markets = catalog.markets.map((m) => !m.ctx && filled.has(m.name) ? { ...m, ctx: filled.get(m.name) } : m)
+  // Core perps dominate volume; reserve a quarter of the slots for HIP-3 (indices, stocks, commodities).
+  const liquid = (kind) => catalog.markets.filter((m) => m.kind === kind && m.tradable && num(m.ctx?.dayNtlVlm) >= minVolumeUsd)
+    .sort((a, b) => num(b.ctx.dayNtlVlm) - num(a.ctx.dayNtlVlm))
+  const hip3 = liquid('hip3').slice(0, Math.floor(limit / 4))
+  const markets = [...liquid('perp').slice(0, limit - hip3.length), ...hip3]
+  const ranges = {}
+  await Promise.all(markets.map(async (m) => {
+    try {
+      const { candles } = await remote.candles({ coin: m.name, interval: '1h' })
+      // Closed bars only: the forming bar is not part of the range it might be breaking.
+      const rows = closedCandles(candles, { interval: '1h' }).rows.slice(-20)
+      if (rows.length >= 20) ranges[m.name] = { high: Math.max(...rows.map((r) => r.h)), low: Math.min(...rows.map((r) => r.l)), bars: rows.length }
+    } catch { /* one market's candles must not sink the scan */ }
+  }))
+  assertCurrent()
+  const result = { ...rankSignals(markets, ranges), scanned: markets.length, observedAt: catalog.ctxObservedAt ?? catalog.observedAt ?? Date.now(), network }
+  cache.set(key, { at: Date.now(), result })
+  return result
+}
+
+export function scanText(result) {
+  const pct = (v, d = 2) => v == null ? '—' : `${v >= 0 ? '+' : ''}${(v * 100).toFixed(d)}%`
+  const lines = [`市场雷达 · 扫描 ${result.scanned} 个可交易永续（成交额最大的核心永续，另留 1/4 名额给成交额最大的 HIP-3）· 数据时间 ${new Date(result.observedAt).toISOString().slice(0, 16)}Z`]
+  if (result.levels.length) lines.push('贴近/突破 20 根 1h 区间：' + result.levels.map((r) => `${r.coin} ${r.broken ? (r.mark > r.high ? '已上破' : '已下破') : `距${r.side === 'high' ? '高点' : '低点'} ${(r.distance * 100).toFixed(2)}%`}（区间 ${r.low}–${r.high}）`).join('；'))
+  if (result.funding.length) lines.push('资金费极值（年化）：' + result.funding.map((r) => `${r.coin} ${pct(r.fundingApr, 1)}${r.fundingApr > 0 ? '（多头付费）' : '（空头付费）'}`).join('；'))
+  if (result.movers.length) lines.push('24h 涨跌最大：' + result.movers.map((r) => `${r.coin} ${pct(r.change24h)}`).join('；'))
+  if (result.premium.length) lines.push('标记价相对预言机：' + result.premium.map((r) => `${r.coin} ${pct(r.premium, 3)}`).join('；'))
+  lines.push('下一步：只挑 1 个与用户偏好最匹配的机会，用 hyper_market candles/indicators 核实，再用 hyper_chart 画出区间和 long/short 头寸框给用户看；雷达只是线索，不是交易信号。')
+  return lines.join('\n')
+}

package/lib/signing.js

@@ -213,3 +213,61 @@ export async function addressFromPrivateKey(privateKey) {
   const hash = c.keccak256(pub.slice(1))
   return '0x' + c.bytesToHex(hash.slice(-20))
 }
+
+// ── user-signed actions (EIP-712 "HyperliquidSignTransaction" domain) ──
+// Field lists and order follow the official Python SDK (utils/signing.py); the main wallet signs them.
+export const SEND_ASSET_TYPES = [
+  { name: 'hyperliquidChain', type: 'string' },
+  { name: 'destination', type: 'string' },
+  { name: 'sourceDex', type: 'string' },
+  { name: 'destinationDex', type: 'string' },
+  { name: 'token', type: 'string' },
+  { name: 'amount', type: 'string' },
+  { name: 'fromSubAccount', type: 'string' },
+  { name: 'nonce', type: 'uint64' },
+]
+/** The SDK signs user actions on chain 0x66eee; hyperliquidChain inside the message prevents replay across networks. */
+export const USER_SIGNATURE_CHAIN_ID = '0x66eee'
+
+/**
+ * A `sendAsset` action (move collateral between perp dexes / spot) and its EIP-712 payload.
+ * @returns {{ action, typed: { domain, types, value } }}
+ */
+export function buildSendAsset({ destination, sourceDex, destinationDex, token, amount, nonce, isMainnet = true }) {
+  const action = { type: 'sendAsset', signatureChainId: USER_SIGNATURE_CHAIN_ID, hyperliquidChain: isMainnet ? 'Mainnet' : 'Testnet',
+    destination, sourceDex, destinationDex, token, amount, fromSubAccount: '', nonce }
+  const value = Object.fromEntries(SEND_ASSET_TYPES.map(({ name }) => [name, action[name]]))
+  return {
+    action,
+    typed: {
+      domain: { name: 'HyperliquidSignTransaction', version: '1', chainId: parseInt(USER_SIGNATURE_CHAIN_ID, 16), verifyingContract: '0x0000000000000000000000000000000000000000' },
+      types: { 'HyperliquidTransaction:SendAsset': SEND_ASSET_TYPES },
+      value,
+    },
+  }
+}
+
+/** EIP-712 digest + secp256k1 signature for a single-struct payload of string / uint / bool / address fields. */
+export async function signTypedDataLocal(privateKey, { domain, types, value }) {
+  const c = await loadCrypto()
+  const [primary, fields] = Object.entries(types)[0]
+  const encode = (type, item) => {
+    if (type === 'string') return c.hashText(String(item))
+    if (type === 'bool') return u256be(item ? 1 : 0)
+    if (type === 'address') { const out = new Uint8Array(32); out.set(addressBytes(item), 12); return out }
+    if (/^uint\d+$/.test(type)) return u256be(item)
+    throw new Error(`unsupported EIP-712 field type ${type}`)
+  }
+  const typeHash = c.hashText(`${primary}(${fields.map((f) => `${f.type} ${f.name}`).join(',')})`)
+  const structHash = c.keccak256(concat(typeHash, ...fields.map((f) => encode(f.type, value[f.name]))))
+  const domainHash = c.keccak256(concat(c.hashText('EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)'),
+    c.hashText(domain.name), c.hashText(domain.version), u256be(domain.chainId), encode('address', domain.verifyingContract)))
+  const digest = c.keccak256(concat(new Uint8Array([0x19, 0x01]), domainHash, structHash))
+  const priv = c.hexToBytes(privateKey)
+  if (priv.length !== 32) throw new Error('钱包私钥格式错误（需要 32 字节 hex）')
+  const sig = c.sign(digest, priv)
+  const recovery = typeof sig.recovery === 'number' ? sig.recovery : sig.v - 27
+  const rHex = c.bytesToHex(typeof sig.r === 'bigint' ? u256be(sig.r) : sig.r).padStart(64, '0').slice(-64)
+  const sHex = c.bytesToHex(typeof sig.s === 'bigint' ? u256be(sig.s) : sig.s).padStart(64, '0').slice(-64)
+  return { r: '0x' + rHex, s: '0x' + sHex, v: 27 + recovery }
+}

package/lib/skill.js

@@ -10,8 +10,8 @@ export function registerHyperSkill(skills) {
   if (typeof skills?.register !== 'function') return null
   return skills.register({
     name: 'hyperliquid-trading',
-    description: '分析 Hyperliquid 实时行情、账户和风险，并在 DSH 交易会话中安全决策、下单、撤单和对账。',
-    whenToUse: '讨论当前交易台、Hyperliquid 市场、持仓、订单、paper 或 testnet/live 交易时使用。',
+    description: '交易副手：用 Hyperliquid 实时数据分析、规划、执行、对账与复盘，积累和迭代交易员的策略库；说明可交易市场、白名单、HIP-3 保证金等能力边界。',
+    whenToUse: '讨论当前交易台、Hyperliquid 市场、持仓、订单、策略、复盘、paper 或 testnet/live 交易时使用。',
     source: 'bundled',
     path: fileURLToPath(skillUrl),
     content,

package/lib/store.js

@@ -9,14 +9,19 @@ import { readFileSync, writeFileSync, renameSync, mkdirSync, existsSync, rmSync,
 import { dirname, join } from 'node:path'
 import { randomUUID, createHash } from 'node:crypto'
 import { canonicalMarketCoin } from './market-symbol.js'
+import { normalizePaperCosts } from './workspace-settings.js'
 
 const PAPER_START_USD = 100_000
 const WORKSPACE_DEFAULTS = Object.freeze({
   interval: '15m', bookGrouping: 'full', chartTab: 'chart', tapeTab: 'book', bottomTab: 'positions', indicators: ['volume'], maLines: [],
-  priceScale: 'normal', chartRanges: {}, chartLayers: { orders: true, fills: true, drawings: true },
+  priceScale: 'normal', chartType: 'candles', chartRanges: {}, chartLayers: { orders: true, fills: true, drawings: true },
   layout: { sessionsWidth: 232, chatWidth: 480, sessionsCollapsed: false, deskCollapsed: false, chatCollapsed: false },
 })
 
+/** Drawings per chart (session + coin, all intervals); the pan budget is verified at this size. */import { emptyJournal } from './journal.js'
+
+export const MAX_CHART_MARKS = 100
+
 export class HyperStore {
   constructor(dataDir, paperNetwork = 'testnet') {
     this.dataDir = dataDir
@@ -255,8 +260,9 @@ export class HyperStore {
   }
 
   addChartMark(mark) {
-    const related = this.listChartMarks(mark.sessionId, mark.coin, mark.interval)
-    if (related.length >= 30) throw new Error('当前图表最多保留 30 条标注，请先删除旧线')
+    // The chart shows a coin's drawings from every interval, so the cap counts them all.
+    const related = this.listChartMarks(mark.sessionId, mark.coin)
+    if (related.length >= MAX_CHART_MARKS) throw new Error(`当前图表最多保留 ${MAX_CHART_MARKS} 条标注，请先删除旧线`)
     const marks = mark.shared ? this.#shared() : this.#marks(mark.sessionId)
     if (marks.length >= 300) throw new Error('当前会话最多保留 300 条图表标注，请先删除旧线')
     const saved = { ...mark, id: randomUUID(), createdAt: Date.now() }
@@ -328,16 +334,68 @@ export class HyperStore {
     return JSON.parse(JSON.stringify(this.paper))
   }
 
+  paperCosts() {
+    const file = join(this.dataDir, 'paper-costs.json')
+    return normalizePaperCosts(existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : undefined)
+  }
+  setPaperCosts(input) {
+    const costs = normalizePaperCosts(input)
+    this.#writeJson(join(this.dataDir, 'paper-costs.json'), costs)
+    return costs
+  }
+  /** Signing set on the desk (signer, web3Account, tradingAddress); overrides plugin config, no restart. */
+  walletSettings() { return this.#readJson(join(this.dataDir, 'wallet-settings.json'), null) }
+  saveWalletSettings(settings) { this.#writeJson(join(this.dataDir, 'wallet-settings.json'), { ...settings, at: Date.now() }); return settings }
+
+  /** Whether a session's current turn was started by an alert (see lib/turn-origin.js); survives a plugin reload. */
+  setAlertOrigin(sessionId, alert) {
+    const rows = { ...this.#readJson(join(this.dataDir, 'turn-origin.json'), {}), [sessionId]: { alert: Boolean(alert), at: Date.now() } }
+    // Only cleared rows are pruned: a live alert origin stays until a human message retires it.
+    const cleared = Object.entries(rows).filter(([, row]) => !row.alert).sort((a, b) => b[1].at - a[1].at).slice(0, 500)
+    const kept = Object.fromEntries([...Object.entries(rows).filter(([, row]) => row.alert), ...cleared])
+    this.#writeJson(join(this.dataDir, 'turn-origin.json'), kept)
+  }
+  alertOrigin(sessionId) { const row = this.#readJson(join(this.dataDir, 'turn-origin.json'), {})[sessionId]; return row ? row.alert === true : undefined }
+
+  /** Custody mode chosen on the desk: 'managed' (全托管) or 'assisted' (半托管); null = not chosen yet. */
+  custody() {
+    const saved = this.#readJson(join(this.dataDir, 'custody.json'), null)
+    return saved?.mode === 'managed' || saved?.mode === 'assisted' ? saved.mode : null
+  }
+  saveCustody(mode) { this.#writeJson(join(this.dataDir, 'custody.json'), { mode, at: Date.now() }); return mode }
+
+  /** The trader's journal (profile, strategy book, trade/review log); see lib/journal.js. */
+  journal() {
+    const saved = this.#readJson(join(this.dataDir, 'journal.json'), null)
+    return saved && typeof saved === 'object' && Array.isArray(saved.strategies) && Array.isArray(saved.entries)
+      ? { profile: saved.profile ?? {}, strategies: saved.strategies, entries: saved.entries } : emptyJournal()
+  }
+  saveJournal(journal) { this.#writeJson(join(this.dataDir, 'journal.json'), journal); return journal }
+
+  indicatorTemplates() { return this.#readJson(join(this.dataDir, 'indicator-templates.json'), []) }
+  saveIndicatorTemplate(template) {
+    const rows = this.indicatorTemplates()
+    if (!rows.some((row) => row.id === template.id) && rows.length >= 20) throw Error('最多保存 20 个指标模板')
+    const next = { ...template, id: template.id || randomUUID(), updatedAt: Date.now() }
+    this.#writeJson(join(this.dataDir, 'indicator-templates.json'), [...rows.filter((row) => row.id !== next.id), next])
+    return next
+  }
+  removeIndicatorTemplate(id) {
+    this.#writeJson(join(this.dataDir, 'indicator-templates.json'), this.indicatorTemplates().filter((row) => row.id !== id))
+  }
+
   /**
    * Fill a paper order against the given mid with a simple slippage model.
    * @returns the fill record
    */
-  paperFill({ coin, isBuy, sz, px, time = Date.now(), reason = 'order', sessionId = null }) {
+  paperFill({ coin, isBuy, sz, px, time = Date.now(), reason = 'order', sessionId = null, feeBps = 0, referencePx = null, slippageBps = null }) {
     const szNum = Number(sz)
     const pxNum = Number(px)
     if (!Number.isFinite(szNum) || szNum <= 0) throw new Error('paper: 无效数量')
     if (!Number.isFinite(pxNum) || pxNum <= 0) throw new Error('paper: 无效价格')
     const notional = szNum * pxNum
+    if (!Number.isFinite(feeBps) || feeBps < 0 || feeBps > 100) throw Error('paper: 无效手续费')
+    const fee = notional * feeBps / 10_000
     const pos = this.paper.positions[coin] ?? { size: 0, entryPx: pxNum, leverage: this.paper.leverageByCoin?.[coin] ?? 1 }
     const signed = isBuy ? szNum : -szNum
     const prevSize = pos.size
@@ -360,11 +418,13 @@ export class HyperStore {
       pos.size = newSize
       this.paper.positions[coin] = pos
     }
-    this.paper.usd += realized // realized PnL settles into cash; margin tracked conceptually
+    this.paper.usd += realized - fee
     // sessionId: the trading conversation whose decision produced this fill.
-    const fill = { coin, isBuy, sz: szNum, px: pxNum, notional, realized, time, reason, sessionId }
+    const fill = { oid: `paper-${randomUUID()}`, coin, isBuy, sz: szNum, px: pxNum, notional, realized, closedPnl: realized,
+      fee, feeToken: 'USDC', netPnl: realized - fee, feeBps, referencePx, slippageBps,
+      closedSize: Math.min(Math.abs(prevSize), Math.sign(prevSize) !== Math.sign(signed) ? szNum : 0), startPosition: prevSize, time, reason, sessionId }
     this.paper.fills.unshift(fill)
-    if (this.paper.fills.length > 200) this.paper.fills.length = 200
+    if (this.paper.fills.length > 5000) this.paper.fills.length = 5000
     this.#writeJson(this.paperFile, this.paper)
     this.recordEvent('paper.fill', fill)
     return fill
@@ -373,7 +433,7 @@ export class HyperStore {
   paperOrderRecord(order) {
     const row = { ...order, time: Date.now(), status: 'filled' }
     this.paper.orders.unshift(row)
-    if (this.paper.orders.length > 200) this.paper.orders.length = 200
+    if (this.paper.orders.length > 5000) this.paper.orders.length = 5000
     this.#writeJson(this.paperFile, this.paper)
     this.recordEvent('paper.order', row)
   }

package/lib/studies.d.ts

@@ -0,0 +1,13 @@
+export interface IndicatorSettings {
+  rsi: { period: number; lower: number; upper: number }
+  macd: { fast: number; slow: number; signal: number }
+  bollinger: { period: number; multiplier: number }
+  stochastic: { period: number; smoothK: number; smoothD: number; lower: number; upper: number }
+  adx: { period: number; smoothing: number }
+}
+export type StudyKey = 'sma20' | 'sma60' | 'ema20' | 'ema50' | 'basis' | 'upper' | 'lower' | 'rsi14' | 'macd' | 'signal' | 'histogram' | 'atr14' | 'vwap' | 'stochK' | 'stochD' | 'adx' | 'plusDI' | 'minusDI' | 'obv'
+export declare const INDICATOR_IDS: string[]
+export declare const DEFAULT_INDICATOR_SETTINGS: IndicatorSettings
+export declare function normalizeIndicatorSettings(input?: unknown): IndicatorSettings
+export declare function computeStudies(candles: readonly {t: number; o: number; h: number; l: number; c: number; v: number}[], input?: IndicatorSettings): Record<StudyKey, Array<{ time: number; value: number }>>
+export declare function studyDefinitions(input?: IndicatorSettings): Array<[string, StudyKey, string]>

package/lib/studies.js

@@ -0,0 +1,157 @@
+/** Shared chart/agent study definitions. All values are derived from the supplied candle window. */
+export const INDICATOR_IDS = ['volume', 'sma20', 'sma60', 'ema20', 'ema50', 'bollinger20', 'rsi14', 'macd', 'atr14', 'vwap', 'stochastic', 'adx', 'obv']
+export const DEFAULT_INDICATOR_SETTINGS = {
+  rsi: { period: 14, lower: 30, upper: 70 }, macd: { fast: 12, slow: 26, signal: 9 },
+  bollinger: { period: 20, multiplier: 2 }, stochastic: { period: 14, smoothK: 3, smoothD: 3, lower: 20, upper: 80 },
+  adx: { period: 14, smoothing: 14 },
+}
+export function normalizeIndicatorSettings(input = {}) {
+  if (!input || typeof input !== 'object' || Array.isArray(input) || Object.keys(input).some((key) => !Object.hasOwn(DEFAULT_INDICATOR_SETTINGS, key))) throw Error('指标参数无效')
+  const result = {}
+  for (const [section, defaults] of Object.entries(DEFAULT_INDICATOR_SETTINGS)) {
+    const supplied = input[section] ?? {}
+    if (typeof supplied !== 'object' || Array.isArray(supplied) || Object.keys(supplied).some((key) => !Object.hasOwn(defaults, key))) throw Error('指标参数字段无效')
+    const values = { ...defaults, ...supplied }
+    for (const [key, value] of Object.entries(values)) {
+      if (typeof value !== 'number' || !Number.isFinite(value)) throw Error(`${section}.${key} 必须为数值`)
+      if (key === 'multiplier') { if (value <= 0 || value > 10) throw Error('布林带倍数必须大于 0 且不超过 10') }
+      else if (key === 'lower' || key === 'upper') { if (value < 0 || value > 100) throw Error('指标阈值必须为 0–100') }
+      else if (!Number.isInteger(value) || value < 1 || value > 500) throw Error('指标周期必须为 1–500 的整数')
+    }
+    if ('lower' in values && values.lower >= values.upper) throw Error('指标下阈值必须小于上阈值')
+    result[section] = values
+  }
+  if (result.macd.fast >= result.macd.slow) throw Error('MACD 快线周期必须小于慢线周期')
+  return result
+}
+function nullableSma(values, period) {
+  return values.map((_, i) => {
+    if (i < period - 1) return null
+    const window = values.slice(i - period + 1, i + 1)
+    return window.some((value) => value == null) ? null : window.reduce((sum, value) => sum + value, 0) / period
+  })
+}
+function rma(values, period) {
+  let prior = null, seed = []
+  return values.map((value) => {
+    if (value == null) return null
+    if (prior == null) { seed.push(value); if (seed.length < period) return null; prior = seed.reduce((sum, item) => sum + item, 0) / period }
+    else prior = (prior * (period - 1) + value) / period
+    return prior
+  })
+}
+export function studyDefinitions(input) {
+  const p = normalizeIndicatorSettings(input)
+  return [
+    ['sma20', 'sma20', 'SMA20'], ['sma60', 'sma60', 'MA60'], ['ema20', 'ema20', 'EMA20'], ['ema50', 'ema50', 'EMA50'],
+    ['bollinger20', 'basis', `BOLL ${p.bollinger.period} × ${p.bollinger.multiplier}`], ['bollinger20', 'upper', 'BOLL upper'], ['bollinger20', 'lower', 'BOLL lower'],
+    ['rsi14', 'rsi14', `RSI${p.rsi.period}`], ['macd', 'macd', p.macd.fast === 12 && p.macd.slow === 26 && p.macd.signal === 9 ? 'MACD' : `MACD ${p.macd.fast}/${p.macd.slow}/${p.macd.signal}`], ['macd', 'signal', 'Signal'], ['macd', 'histogram', 'Hist'],
+    ['atr14', 'atr14', 'ATR14'], ['vwap', 'vwap', 'VWAP (UTC HLC3)'], ['stochastic', 'stochK', `Stoch %K ${p.stochastic.period}/${p.stochastic.smoothK}`], ['stochastic', 'stochD', `Stoch %D ${p.stochastic.smoothD}`],
+    ['adx', 'adx', `ADX ${p.adx.period}/${p.adx.smoothing}`], ['adx', 'plusDI', '+DI'], ['adx', 'minusDI', '-DI'], ['obv', 'obv', 'OBV'],
+  ]
+}
+function points(rows, values) {
+  return values.flatMap((value, index) => value == null || !Number.isFinite(value)
+    ? [] : [{ time: Math.floor(rows[index].t / 1000), value }])
+}
+
+function sma(values, period) {
+  let sum = 0
+  return values.map((value, index) => {
+    sum += value
+    if (index >= period) sum -= values[index - period]
+    return index >= period - 1 ? sum / period : null
+  })
+}
+
+function ema(values, period) {
+  const result = Array(values.length).fill(null)
+  const alpha = 2 / (period + 1)
+  let seed = []
+  let prior = null
+  for (let i = 0; i < values.length; i += 1) {
+    const value = values[i]
+    if (value == null) continue
+    if (prior == null) {
+      seed.push(value)
+      if (seed.length < period) continue
+      prior = seed.reduce((total, current) => total + current, 0) / period
+    } else prior = value * alpha + prior * (1 - alpha)
+    result[i] = prior
+  }
+  return result
+}
+
+export function computeStudies(candles, input) {
+  const settings = normalizeIndicatorSettings(input)
+  const rows = candles.filter((row) => Number.isFinite(row.c) && row.c > 0 && Number.isFinite(row.t))
+  const closes = rows.map((row) => row.c)
+  const mean = sma(closes, settings.bollinger.period)
+  const ema12 = ema(closes, settings.macd.fast)
+  const ema26 = ema(closes, settings.macd.slow)
+  const macd = ema12.map((value, index) => value == null || ema26[index] == null ? null : value - ema26[index])
+  const signal = ema(macd, settings.macd.signal)
+  const deviation = mean.map((value, index) => value == null ? null : Math.sqrt(
+    closes.slice(index - settings.bollinger.period + 1, index + 1).reduce((total, close) => total + (close - value) ** 2, 0) / settings.bollinger.period,
+  ))
+  const rsi = Array(rows.length).fill(null)
+  let gain = 0; let loss = 0
+  for (let i = 1; i < rows.length; i += 1) {
+    const delta = closes[i] - closes[i - 1]
+    const up = Math.max(delta, 0); const down = Math.max(-delta, 0)
+    if (i <= settings.rsi.period) { gain += up; loss += down }
+    else { gain = (gain * (settings.rsi.period - 1) + up) / settings.rsi.period; loss = (loss * (settings.rsi.period - 1) + down) / settings.rsi.period }
+    if (i === settings.rsi.period) { gain /= settings.rsi.period; loss /= settings.rsi.period }
+    if (i >= settings.rsi.period) rsi[i] = loss === 0 ? gain === 0 ? 50 : 100 : 100 - 100 / (1 + gain / loss)
+  }
+  const point = (values) => points(rows, values)
+  const atr = Array(rows.length).fill(null)
+  let rangeSum = 0
+  for (let i = 1; i < rows.length; i += 1) {
+    const range = Math.max(rows[i].h - rows[i].l, Math.abs(rows[i].h - rows[i - 1].c), Math.abs(rows[i].l - rows[i - 1].c))
+    if (i <= 14) rangeSum += range
+    if (i === 14) atr[i] = rangeSum / 14
+    if (i > 14) atr[i] = (atr[i - 1] * 13 + range) / 14
+  }
+  // UTC sessions, HLC3 weighted by base volume. A partial first day is omitted.
+  let day = -1, weighted = 0, volume = 0, complete = false
+  const vwap = rows.map((row) => {
+    const nextDay = Math.floor(row.t / 86_400_000)
+    if (nextDay !== day) {
+      // After the first observed day, the exchange can legitimately skip empty
+      // midnight bars (e.g. closed HIP-3 markets); the next available bar starts it.
+      complete = day >= 0 || row.t % 86_400_000 === 0
+      day = nextDay; weighted = 0; volume = 0
+    }
+    if (!Number.isFinite(row.v) || row.v < 0) return null
+    weighted += (row.h + row.l + row.c) / 3 * row.v
+    volume += row.v
+    return complete && volume > 0 ? weighted / volume : null
+  })
+  const rawK = rows.map((row, index) => {
+    if (index < settings.stochastic.period - 1) return null
+    const window = rows.slice(index - settings.stochastic.period + 1, index + 1)
+    const low = Math.min(...window.map((bar) => bar.l)), high = Math.max(...window.map((bar) => bar.h))
+    return high === low ? null : 100 * (row.c - low) / (high - low)
+  })
+  const stochK = nullableSma(rawK, settings.stochastic.smoothK)
+  const stochD = nullableSma(stochK, settings.stochastic.smoothD)
+  const tr = rows.map((row, i) => i === 0 ? null : Math.max(row.h - row.l, Math.abs(row.h - rows[i - 1].c), Math.abs(row.l - rows[i - 1].c)))
+  const plus = rows.map((row, i) => { if (!i) return null; const up = row.h - rows[i - 1].h, down = rows[i - 1].l - row.l; return up > down && up > 0 ? up : 0 })
+  const minus = rows.map((row, i) => { if (!i) return null; const up = row.h - rows[i - 1].h, down = rows[i - 1].l - row.l; return down > up && down > 0 ? down : 0 })
+  const atrDm = rma(tr, settings.adx.period), plusRma = rma(plus, settings.adx.period), minusRma = rma(minus, settings.adx.period)
+  const di = (values) => values.map((value, i) => value == null || atrDm[i] == null ? null : atrDm[i] === 0 ? 0 : 100 * value / atrDm[i])
+  const plusDI = di(plusRma), minusDI = di(minusRma)
+  const dx = plusDI.map((value, i) => value == null || minusDI[i] == null ? null : value + minusDI[i] === 0 ? 0 : 100 * Math.abs(value - minusDI[i]) / (value + minusDI[i]))
+  let balance = 0
+  const obv = rows.map((row, i) => { if (i) balance += Math.sign(row.c - rows[i - 1].c) * row.v; return balance })
+  return {
+    stochK: point(stochK), stochD: point(stochD), adx: point(rma(dx, settings.adx.smoothing)), plusDI: point(plusDI), minusDI: point(minusDI), obv: point(obv),
+    sma20: point(sma(closes, 20)), basis: point(mean), sma60: point(sma(closes, 60)), ema20: point(ema(closes, 20)), ema50: point(ema(closes, 50)),
+    upper: point(mean.map((value, index) => value == null ? null : value + settings.bollinger.multiplier * deviation[index])),
+    lower: point(mean.map((value, index) => value == null ? null : value - settings.bollinger.multiplier * deviation[index])),
+    rsi14: point(rsi), macd: point(macd), signal: point(signal),
+    histogram: point(macd.map((value, index) => value == null || signal[index] == null ? null : value - signal[index])),
+    atr14: point(atr), vwap: point(vwap),
+  }
+}