@whyshu/ba 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,85 @@
-# Temporary Holding Version
+# @whyshu/ba · DSH 币安账户面板
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+DSH（DeepSeek Harness）插件：在**左侧栏**增加一个「币安账户」入口，点击后由**主视图**展示：
+
+- 现货资产：非零余额、可用/锁定、现价、USDT 估值、总估值
+- 合约持仓：钱包余额、未实现盈亏、可用余额，以及每个非零持仓（方向/数量/开仓价/标记价/未实现盈亏/杠杆）
+- 行情看板：自选币对最新价、24h 涨跌、24h 成交额（无需 API Key）
+
+全部**只读**。API Key 只保存在 dsh 宿主进程（Node 侧），浏览器拿不到。
+
+## 安装
+
+**从 npm 安装（推荐；npx dsh / 其他机器）**——在 dsh 的 Plugins 面板安装包名：
+
+```text
+@whyshu/ba
+```
+
+或使用 `plugin_manager`：
+
+```text
+install_bundle target = @whyshu/ba
+registry = https://registry.npmjs.org
+```
+
+**本地开发安装**（改 `src/` / `dist/` 即时生效，宿主侧改动仍需重启 dsh）：
+
+```text
+install_bundle target = /Users/Chester/Whyshu/whyshu-ba
+```
+
+安装后左侧栏出现图标；点击进入面板。首次打开若未配置 Key，会显示配置引导。
+
+## 配置 API Key
+
+1. 币安 → 账户 → **API 管理** → 新建 API，权限只勾 **「启用读取」**（务必禁用提现、交易）。
+2. 建议同时开启 **IP 白名单**。
+3. 写入本机文件（权限 600，不入仓库、不进日志）：
+
+```bash
+mkdir -p ~/.dsh/argent && chmod 700 ~/.dsh/argent
+cat > ~/.dsh/argent/ba.env <<'EOF'
+BINANCE_API_KEY=你的只读 Key
+BINANCE_API_SECRET=你的 Secret
+BINANCE_PROXY=http://127.0.0.1:7890
+BINANCE_SYMBOLS=BTCUSDT,ETHUSDT,SOLUSDT,BNBUSDT
+EOF
+chmod 600 ~/.dsh/argent/ba.env
+```
+
+- `BINANCE_PROXY` 可选；本机直连 `api.binance.com` 不通时必须配（本机 ClashX 为 `http://127.0.0.1:7890`）。
+- `BINANCE_SYMBOLS` 可选，决定行情看板的币对。
+- 插件**每次请求都重读该文件**：改 Key / 代理后点面板里的「刷新」即可，无需重启 dsh。
+
+## 端点（宿主侧，只读）
+
+| 端点 | 说明 |
+| --- | --- |
+| `GET /api/whyshu-ba/health` | 版本、是否已配置 Key、是否启用代理、自选币对 |
+| `GET /api/whyshu-ba/ping` | 客户端 bundle 自检信标 |
+| `GET /api/whyshu-ba/overview` | 面板总览（行情 + 现货 + 合约；各段独立失败） |
+
+## 文件
+
+```
+src/index.js     宿主插件：注册 /api/whyshu-ba/* 端点
+src/binance.mjs  币安只读数据层：签名、代理隧道、现货/合约/行情
+dist/client.js   浏览器 bundle（手写维护，无需构建）：main + sidebar.panellist
+locale/*.json    插件管理器的标题/描述（zh/en）
+icon.svg         插件图标
+cordis.patch.yml bundle patch（insert id=whyshu-ba）
+```
+
+## 排查
+
+- **面板报「请求超时 / fetch failed」**：直连被墙 → 配 `BINANCE_PROXY`。
+- **报 401 / -2015**：Key 无效、未开现货读取权限，或本机时间偏差过大。
+- **面板显示「还没有配置币安 API Key」**：宿主没读到 `~/.dsh/argent/ba.env`，检查路径与权限。
+- **左侧栏没有图标**：确认 bundle 已安装并启用；`/api/whyshu-ba/health` 的 `clientPingAt` 为空说明浏览器端 bundle 没加载，刷新页面。
+
+## 安全
+
+- 只读：不调用下单 / 划转 / 提现接口。
+- Key 仅在宿主进程读取与签名；`/overview` 响应只含计算结果，不含 Key/Secret。
+- 不要把 `ba.env` 提交进任何仓库。

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# whyshu-ba bundle patch：只注册一行宿主插件。
+#   宿主：只读端点 /api/whyshu-ba/*（币安 Key 只在宿主进程，不下发浏览器）
+#   客户端：dist/client.js 在左侧栏注册面板入口（id=binance）+ 主视图面板（main slot, key=binance）
+- insert:
+    - id: whyshu-ba
+      name: '@whyshu/ba'

package/dist/client.js

@@ -0,0 +1,548 @@
+/**
+ * whyshu-ba · 客户端（dsh browser bundle 格式，手写维护，无需构建）
+ *
+ * 形态：左侧栏一个面板入口（sidebar.panellist, id=binance），
+ *       点击后由主视图（main slot, key=binance）渲染币安面板：
+ *       现货资产 / 合约持仓 / 行情看板 —— 全部只读。
+ *
+ * 数据来自宿主端点 `/api/whyshu-ba/*`（API Key 只在宿主进程，浏览器拿不到）。
+ * id 必须是整包名（与 package.json#name 一致），否则客户端拒绝加载。
+ */
+window.__ModuleLoader__.load({
+  id: '@whyshu/ba',
+  factory(require) {
+    const React = require('react')
+    const h = React.createElement
+    const { useCallback, useEffect, useRef, useState } = React
+
+    const NS = 'whyshu-ba'
+    const PANEL_ID = 'binance'
+    const API = '/api/whyshu-ba'
+    const REFRESH_MS = 30000
+    const ENV_PATH = '~/.dsh/argent/ba.env'
+
+    /* ───────────────────────── 文案（zh 必填 + en 基线） ───────────────────────── */
+
+    const zh = {
+      panel: '币安账户',
+      title: '币安账户',
+      subtitle: '现货资产 · 合约持仓 · 行情看板（只读）',
+      readOnly: '只读',
+      refresh: '刷新',
+      refreshing: '刷新中…',
+      updated: '更新于',
+      autoRefresh: '每 30 秒自动刷新',
+      loading: '正在读取币安数据…',
+      retry: '重试',
+      kpiSpot: '现货估值',
+      kpiWallet: '合约钱包余额',
+      kpiUnrealized: '未实现盈亏',
+      kpiAvailable: '合约可用余额',
+      spotTitle: '现货资产',
+      spotHint: '按现价折算 USDT，仅显示非零余额',
+      spotAsset: '资产',
+      spotTotal: '数量',
+      spotFree: '可用',
+      spotLocked: '锁定',
+      spotPrice: '现价',
+      spotValue: '估值 (USDT)',
+      futuresTitle: '合约持仓',
+      futuresPositions: '持仓明细',
+      posSymbol: '合约',
+      posSide: '方向',
+      posSize: '数量',
+      posEntry: '开仓价',
+      posMark: '标记价',
+      posPnl: '未实现盈亏',
+      posLeverage: '杠杆',
+      marketTitle: '行情看板',
+      marketSymbol: '币对',
+      marketPrice: '最新价',
+      marketChange: '24h 涨跌',
+      marketVolume: '24h 成交额',
+      long: '多',
+      short: '空',
+      emptySpot: '没有非零现货余额',
+      emptyPositions: '没有持仓',
+      emptyMarket: '暂无行情数据',
+      setupTitle: '还没有配置币安 API Key',
+      setupIntro: '行情看板已在工作；配置只读 Key 后即可显示现货资产与合约持仓。',
+      setupStep1: '币安 → 账户 → API 管理 → 新建 API，只勾选「启用读取」，务必禁用提现与交易。',
+      setupStep2: '把 Key / Secret 写入本机文件（权限 600，不入仓库、不进日志）：',
+      setupStep3: '保存后回到这里点「刷新」，无需重启 dsh。',
+      setupHint: '建议单独建一个只读 Key，并开启 IP 白名单。代理仅在直连不通时需要。',
+      setupPath: '文件位置',
+      errTitle: '数据读取失败',
+      errProxyHint: '网络不通：在 ba.env 里配置 BINANCE_PROXY（本机可用 http://127.0.0.1:7890）后重试。',
+      errKeyHint: 'Key 无效或无读取权限：确认只读 Key、现货读取权限，并检查服务器时间。',
+      errRegionHint: '当前地区被限制访问，请检查代理节点。',
+      footnote: '只读面板 · 每 30 秒自动刷新 · API Key 只在 dsh 宿主进程使用',
+      proxyOn: '代理已启用',
+      proxyOff: '直连',
+      noValue: '—',
+    }
+
+    const en = {
+      panel: 'Binance account',
+      title: 'Binance account',
+      subtitle: 'Spot assets · futures positions · market board (read-only)',
+      readOnly: 'Read-only',
+      refresh: 'Refresh',
+      refreshing: 'Refreshing…',
+      updated: 'Updated',
+      autoRefresh: 'Auto-refresh every 30s',
+      loading: 'Loading Binance data…',
+      retry: 'Retry',
+      kpiSpot: 'Spot value',
+      kpiWallet: 'Futures wallet',
+      kpiUnrealized: 'Unrealized PnL',
+      kpiAvailable: 'Futures available',
+      spotTitle: 'Spot assets',
+      spotHint: 'Valued in USDT at the latest price; zero balances hidden',
+      spotAsset: 'Asset',
+      spotTotal: 'Amount',
+      spotFree: 'Free',
+      spotLocked: 'Locked',
+      spotPrice: 'Price',
+      spotValue: 'Value (USDT)',
+      futuresTitle: 'Futures positions',
+      futuresPositions: 'Open positions',
+      posSymbol: 'Symbol',
+      posSide: 'Side',
+      posSize: 'Size',
+      posEntry: 'Entry',
+      posMark: 'Mark',
+      posPnl: 'Unrealized PnL',
+      posLeverage: 'Lev.',
+      marketTitle: 'Market board',
+      marketSymbol: 'Pair',
+      marketPrice: 'Last',
+      marketChange: '24h change',
+      marketVolume: '24h volume',
+      long: 'Long',
+      short: 'Short',
+      emptySpot: 'No non-zero spot balances',
+      emptyPositions: 'No open positions',
+      emptyMarket: 'No market data',
+      setupTitle: 'Binance API key is not configured yet',
+      setupIntro: 'The market board already works. Add a read-only key to show spot assets and futures positions.',
+      setupStep1: 'Binance → Account → API Management → Create API, enable only "Enable Reading"; disable withdrawals and trading.',
+      setupStep2: 'Write the key and secret into a local file (mode 600, never committed or logged):',
+      setupStep3: 'Save, then click Refresh here. No dsh restart is needed.',
+      setupHint: 'Prefer a dedicated read-only key with an IP allowlist. A proxy is needed only when direct access is blocked.',
+      setupPath: 'File',
+      errTitle: 'Could not load data',
+      errProxyHint: 'Network unreachable: set BINANCE_PROXY in ba.env (this machine can use http://127.0.0.1:7890) and retry.',
+      errKeyHint: 'Invalid key or missing read permission: verify the read-only key, spot reading permission, and host time.',
+      errRegionHint: 'This region is restricted; try another proxy node.',
+      footnote: 'Read-only · auto-refresh every 30s · API key stays in the dsh host process',
+      proxyOn: 'proxy on',
+      proxyOff: 'direct',
+      noValue: '—',
+    }
+
+    /* ───────────────────────── 格式化 ───────────────────────── */
+
+    const pad2 = (n) => (n < 10 ? '0' + n : String(n))
+
+    function fmtNum(value, maxFrac = 8) {
+      const n = Number(value)
+      if (!Number.isFinite(n)) return '—'
+      if (n === 0) return '0'
+      const abs = Math.abs(n)
+      const frac = abs >= 1000 ? 2 : abs >= 1 ? Math.min(maxFrac, 4) : Math.min(maxFrac, 6)
+      return n.toLocaleString('en-US', { maximumFractionDigits: frac })
+    }
+
+    function fmtPrice(value) {
+      const n = Number(value)
+      if (!Number.isFinite(n) || n <= 0) return '—'
+      const frac = n >= 1000 ? 2 : n >= 1 ? 4 : 6
+      return n.toLocaleString('en-US', { maximumFractionDigits: frac })
+    }
+
+    function fmtUsd(value) {
+      const n = Number(value)
+      if (!Number.isFinite(n)) return '—'
+      return '$' + n.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })
+    }
+
+    function fmtPct(value) {
+      const n = Number(value)
+      if (!Number.isFinite(n)) return '—'
+      return (n > 0 ? '+' : '') + n.toFixed(2) + '%'
+    }
+
+    function fmtCompact(value) {
+      const n = Number(value)
+      if (!Number.isFinite(n)) return '—'
+      if (Math.abs(n) >= 1e9) return (n / 1e9).toFixed(2) + 'B'
+      if (Math.abs(n) >= 1e6) return (n / 1e6).toFixed(2) + 'M'
+      if (Math.abs(n) >= 1e3) return (n / 1e3).toFixed(2) + 'K'
+      return n.toFixed(2)
+    }
+
+    /** 24 小时制：14:05:09 */
+    function fmtTime(iso) {
+      const d = iso instanceof Date ? iso : new Date(iso || Date.now())
+      if (Number.isNaN(d.getTime())) return ''
+      return pad2(d.getHours()) + ':' + pad2(d.getMinutes()) + ':' + pad2(d.getSeconds())
+    }
+
+    function toneClass(value) {
+      const n = Number(value)
+      if (!Number.isFinite(n) || n === 0) return ''
+      return n > 0 ? ' wba-pos' : ' wba-neg'
+    }
+
+    function errorHint(message, t) {
+      const text = String(message || '')
+      if (/timeout|超时|ECONN|ENOTFOUND|EAI_AGAIN|socket hang up|fetch failed/i.test(text)) return t('errProxyHint')
+      if (/401|403|451|-2015|invalid api-key|signature|permission|apikey/i.test(text)) return t('errKeyHint')
+      if (/restricted|region|451/i.test(text)) return t('errRegionHint')
+      return ''
+    }
+
+    /* ───────────────────────── 样式（只注入一次；全部用 dsh 主题 token） ───────────────────────── */
+
+    const CSS = `
+.wba-root{display:flex;flex-direction:column;height:100%;min-height:0;color:var(--dsw-alias-label-primary);
+  font:14px/1.55 var(--dsw-font-family,-apple-system,BlinkMacSystemFont,"Segoe UI","PingFang SC","Microsoft YaHei",sans-serif)}
+.wba-head{display:flex;align-items:flex-start;gap:12px;padding:16px 22px 10px;flex-wrap:wrap}
+.wba-head-main{display:flex;align-items:center;gap:10px;min-width:0}
+.wba-head-actions{display:flex;align-items:center;gap:10px;margin-left:auto;flex-wrap:wrap}
+.wba-title{font-size:16px;font-weight:600;line-height:1.3}
+.wba-sub{font-size:12px;color:var(--dsw-alias-label-secondary);margin-top:1px}
+.wba-chip{border:1px solid var(--dsw-alias-border-l2);border-radius:999px;padding:1px 8px;font-size:11px;
+  color:var(--dsw-alias-label-secondary);white-space:nowrap}
+.wba-time{font-size:12px;color:var(--dsw-alias-label-secondary);white-space:nowrap}
+.wba-btn{border:1px solid var(--dsw-alias-border-l2);background:transparent;color:var(--dsw-alias-label-primary);
+  border-radius:8px;padding:4px 12px;font:12px/1.4 inherit;cursor:pointer;white-space:nowrap}
+.wba-btn:hover{background:rgba(127,127,127,.10)}
+.wba-btn:disabled{opacity:.55;cursor:default}
+.wba-body{flex:1 1 auto;min-height:0;overflow:auto;padding:6px 22px 28px;display:flex;flex-direction:column;gap:12px}
+.wba-card{background:var(--dsw-alias-bg-layer-1);border:1px solid var(--dsw-alias-border-l1);border-radius:12px;padding:12px 14px;min-width:0}
+.wba-card-head{display:flex;align-items:baseline;gap:8px;margin-bottom:8px;flex-wrap:wrap}
+.wba-card-title{margin:0;font-size:13px;font-weight:600}
+.wba-card-sub{font-size:11px;color:var(--dsw-alias-label-secondary)}
+.wba-kpis{display:grid;grid-template-columns:repeat(auto-fit,minmax(150px,1fr));gap:10px}
+.wba-kpi{background:var(--dsw-alias-bg-layer-1);border:1px solid var(--dsw-alias-border-l1);border-radius:12px;padding:10px 14px}
+.wba-kpi b{display:block;font-size:22px;line-height:1.2;font-weight:600;font-variant-numeric:tabular-nums}
+.wba-kpi span{display:block;font-size:11px;color:var(--dsw-alias-label-secondary);margin-top:2px}
+.wba-table{display:flex;flex-direction:column;min-width:0}
+.wba-tr{display:grid;gap:10px;align-items:center;padding:6px 2px;border-bottom:1px dashed var(--dsw-alias-border-l1)}
+.wba-tr:last-child{border-bottom:0}
+.wba-th{font-size:11px;color:var(--dsw-alias-label-secondary);padding-bottom:4px;border-bottom:1px solid var(--dsw-alias-border-l1)}
+.wba-cell{min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font-variant-numeric:tabular-nums}
+.wba-cell.wba-name{font-weight:600}
+.wba-cell.wba-num{text-align:right}
+.wba-cell.wba-total{font-weight:600}
+.wba-pos{color:var(--dsw-alias-state-success-primary)}
+.wba-neg{color:var(--dsw-alias-state-error-primary)}
+.wba-dim{color:var(--dsw-alias-label-secondary)}
+.wba-note{font-size:12px;color:var(--dsw-alias-label-secondary);background:rgba(127,127,127,.07);border-radius:10px;padding:10px 12px}
+.wba-note b{color:var(--dsw-alias-label-primary)}
+.wba-empty{padding:16px 2px;text-align:center;color:var(--dsw-alias-label-secondary);font-size:12px}
+.wba-loading{padding:40px 0;text-align:center;color:var(--dsw-alias-label-secondary);font-size:13px}
+.wba-err{margin:0;padding:12px 14px;border-radius:12px;border:1px solid var(--dsw-alias-state-error-primary);
+  background:rgba(248,113,113,.10);font-size:13px;white-space:pre-wrap;word-break:break-word}
+.wba-err-hint{margin-top:6px;font-size:12px;color:var(--dsw-alias-label-secondary)}
+.wba-setup h3{margin:0 0 6px;font-size:14px}
+.wba-setup p{margin:6px 0;font-size:13px}
+.wba-setup ol{margin:8px 0 8px 18px;padding:0;font-size:13px}
+.wba-setup li{margin:4px 0}
+.wba-code{background:var(--dsw-alias-bg-base);border:1px solid var(--dsw-alias-border-l1);border-radius:8px;
+  padding:8px 10px;font:12px/1.6 ui-monospace,SFMono-Regular,Menlo,monospace;white-space:pre-wrap;word-break:break-all}
+.wba-foot{font-size:11px;color:var(--dsw-alias-label-secondary);padding:0 2px 4px;display:flex;gap:10px;flex-wrap:wrap}
+`
+
+    function injectCss() {
+      try {
+        if (typeof document === 'undefined' || !document.head) return
+        if (document.getElementById('whyshu-ba-css')) return
+        const style = document.createElement('style')
+        style.id = 'whyshu-ba-css'
+        style.textContent = CSS
+        document.head.appendChild(style)
+      } catch { /* noop */ }
+    }
+
+    /* ───────────────────────── 小部件 ───────────────────────── */
+
+    /** 左侧栏图标：原创「三根向上蜡烛」图形，跟随主题色。 */
+    function BinanceIcon(props) {
+      const size = (props && props.size) || 20
+      return h('svg', {
+        width: size, height: size, viewBox: '0 0 24 24', fill: 'none',
+        'aria-hidden': true, style: { display: 'block', flex: '0 0 auto' },
+      },
+        h('rect', { x: 4, y: 11, width: 3.2, height: 7, rx: 1, fill: 'currentColor', opacity: 0.55 }),
+        h('rect', { x: 10.4, y: 7, width: 3.2, height: 11, rx: 1, fill: 'currentColor', opacity: 0.8 }),
+        h('rect', { x: 16.8, y: 3.5, width: 3.2, height: 14.5, rx: 1, fill: 'currentColor' }),
+        h('path', { d: 'M4.5 20.5h15', stroke: 'currentColor', strokeWidth: 1.4, strokeLinecap: 'round' }))
+    }
+
+    function Kpi(props) {
+      return h('div', { className: 'wba-kpi' },
+        h('b', { className: props.tone ? toneClass(props.tone).trim() : '' }, props.value),
+        h('span', null, props.label))
+    }
+
+    /** 通用表格：cols 为 grid-template-columns；rows 为二维数组；首列左对齐，其余右对齐。 */
+    function Table(props) {
+      const rows = props.rows || []
+      if (!rows.length) return h('div', { className: 'wba-empty' }, props.empty || '')
+      const cellClass = (index, extra) => 'wba-cell ' + (index === 0 ? 'wba-name' : 'wba-num') + (extra || '')
+      return h('div', { className: 'wba-table' },
+        h('div', { className: 'wba-tr wba-th', style: { gridTemplateColumns: props.cols } },
+          props.head.map((label, i) => h('span', { key: i, className: cellClass(i) }, label))),
+        rows.map((row, ri) => h('div', { key: ri, className: 'wba-tr', style: { gridTemplateColumns: props.cols } },
+          row.map((cell, ci) => h('span', { key: ci, className: cellClass(ci, cell && cell.toneClass ? ' ' + cell.toneClass : '') },
+            cell && cell.node !== undefined ? cell.node : String(cell === undefined || cell === null ? '—' : cell))))))
+    }
+
+    function toneCell(value, formatter) {
+      return { toneClass: toneClass(value).trim(), node: h('span', null, formatter(value)) }
+    }
+
+    function SetupCard(props) {
+      const t = props.t
+      return h('div', { className: 'wba-card wba-setup' },
+        h('h3', null, t('setupTitle')),
+        h('p', null, t('setupIntro')),
+        h('ol', null,
+          h('li', null, t('setupStep1')),
+          h('li', null, t('setupStep2'))),
+        h('div', { className: 'wba-note' }, t('setupPath') + ': ', h('b', null, ENV_PATH)),
+        h('div', { className: 'wba-code' },
+          'BINANCE_API_KEY=...\nBINANCE_API_SECRET=...\nBINANCE_PROXY=http://127.0.0.1:7890'),
+        h('p', { className: 'wba-dim' }, t('setupStep3')),
+        h('p', { className: 'wba-dim' }, t('setupHint')))
+    }
+
+    function ErrorsCard(props) {
+      const t = props.t
+      return h('div', { className: 'wba-card' },
+        h('div', { className: 'wba-card-head' }, h('h3', { className: 'wba-card-title' }, t('errTitle'))),
+        props.errors.map((e, i) => {
+          const hint = errorHint(e.message, t)
+          return h('div', { key: i, className: 'wba-err', style: i ? { marginTop: 8 } : undefined },
+            '[' + e.section + '] ' + e.message,
+            hint ? h('div', { className: 'wba-err-hint' }, hint) : null)
+        }))
+    }
+
+    /* ───────────────────────── 主面板 ───────────────────────── */
+
+    function BinancePanel(props) {
+      const t = (props && props.t) || ((key) => key)
+      const [data, setData] = useState(null)
+      const [error, setError] = useState(null)
+      const [loading, setLoading] = useState(true)
+      const [fetchedAt, setFetchedAt] = useState(null)
+      const alive = useRef(true)
+
+      const load = useCallback(async () => {
+        setLoading(true)
+        try {
+          const res = await fetch(API + '/overview', { cache: 'no-store' })
+          const body = await res.json().catch(() => null)
+          if (!alive.current) return
+          if (!res.ok || !body || body.ok !== true) {
+            const message = (body && (body.message || body.error)) || ('HTTP ' + res.status)
+            setError(String(message))
+            return
+          }
+          setData(body.data)
+          setError(null)
+          setFetchedAt(new Date())
+        } catch (e) {
+          if (alive.current) setError(String((e && e.message) || e))
+        } finally {
+          if (alive.current) setLoading(false)
+        }
+      }, [])
+
+      useEffect(() => {
+        alive.current = true
+        load()
+        const timer = setInterval(load, REFRESH_MS)
+        return () => { alive.current = false; clearInterval(timer) }
+      }, [load])
+
+      const head = h('div', { className: 'wba-head' },
+        h('div', { className: 'wba-head-main' },
+          h(BinanceIcon, { size: 24, active: true }),
+          h('div', null,
+            h('div', { className: 'wba-title' }, t('title')),
+            h('div', { className: 'wba-sub' }, t('subtitle')))),
+        h('div', { className: 'wba-head-actions' },
+          h('span', { className: 'wba-chip' }, t('readOnly')),
+          fetchedAt ? h('span', { className: 'wba-time' }, t('updated') + ' ' + fmtTime(fetchedAt)) : null,
+          h('span', { className: 'wba-time' }, t('autoRefresh')),
+          h('button', { type: 'button', className: 'wba-btn', onClick: load, disabled: loading },
+            loading ? t('refreshing') : t('refresh'))))
+
+      if (!data && loading) {
+        return h('div', { className: 'wba-root' }, head, h('div', { className: 'wba-loading' }, t('loading')))
+      }
+      if (!data && error) {
+        return h('div', { className: 'wba-root' }, head,
+          h('div', { className: 'wba-body' },
+            h('div', { className: 'wba-err' }, error,
+              errorHint(error, t) ? h('div', { className: 'wba-err-hint' }, errorHint(error, t)) : null),
+            h('div', null, h('button', { type: 'button', className: 'wba-btn', onClick: load }, t('retry')))))
+      }
+
+      const body = []
+      if (error) {
+        body.push(h('div', { key: 'soft-err', className: 'wba-err' }, error))
+      }
+      if (data && !data.configured) body.push(h(SetupCard, { key: 'setup', t }))
+      if (data && data.errors && data.errors.length) body.push(h(ErrorsCard, { key: 'errors', t, errors: data.errors }))
+
+      const spot = data && data.spot
+      const futures = data && data.futures
+      if (spot || futures) {
+        const kpis = []
+        if (spot) kpis.push(h(Kpi, { key: 'spot', label: t('kpiSpot'), value: fmtUsd(spot.totalUSDT) }))
+        if (futures) {
+          kpis.push(h(Kpi, { key: 'wallet', label: t('kpiWallet'), value: fmtUsd(futures.totalWalletBalance) }))
+          kpis.push(h(Kpi, { key: 'upnl', label: t('kpiUnrealized'), value: fmtUsd(futures.totalUnrealizedProfit), tone: futures.totalUnrealizedProfit }))
+          kpis.push(h(Kpi, { key: 'avail', label: t('kpiAvailable'), value: fmtUsd(futures.availableBalance) }))
+        }
+        body.push(h('div', { key: 'kpis', className: 'wba-kpis' }, kpis))
+      }
+
+      if (spot) {
+        const rows = (spot.rows || []).map((r) => [
+          r.asset,
+          fmtNum(r.total),
+          fmtNum(r.free),
+          fmtNum(r.locked),
+          r.priceUSDT ? fmtPrice(r.priceUSDT) : '—',
+          r.valueUSDT === null ? '—' : fmtUsd(r.valueUSDT),
+        ])
+        body.push(h('div', { key: 'spot', className: 'wba-card' },
+          h('div', { className: 'wba-card-head' },
+            h('h3', { className: 'wba-card-title' }, t('spotTitle')),
+            h('span', { className: 'wba-card-sub' }, t('spotHint')),
+            h('span', { className: 'wba-card-sub', style: { marginLeft: 'auto' } }, t('kpiSpot') + ' ' + fmtUsd(spot.totalUSDT))),
+          h(Table, {
+            cols: '1.1fr .9fr .9fr .9fr .9fr 1.1fr',
+            head: [t('spotAsset'), t('spotTotal'), t('spotFree'), t('spotLocked'), t('spotPrice'), t('spotValue')],
+            rows: rows,
+            empty: t('emptySpot'),
+          })))
+      }
+
+      if (futures) {
+        const posRows = (futures.positions || []).map((p) => [
+          p.symbol,
+          p.side === 'LONG' ? t('long') : t('short'),
+          fmtNum(Math.abs(p.positionAmt)),
+          fmtPrice(p.entryPrice),
+          fmtPrice(p.markPrice),
+          toneCell(p.unrealizedProfit, (v) => (v > 0 ? '+' : '') + fmtUsd(v)),
+          p.leverage ? p.leverage + '×' : '—',
+        ])
+        body.push(h('div', { key: 'futures', className: 'wba-card' },
+          h('div', { className: 'wba-card-head' },
+            h('h3', { className: 'wba-card-title' }, t('futuresTitle')),
+            h('span', { className: 'wba-card-sub' }, t('futuresPositions')),
+            h('span', { className: 'wba-card-sub', style: { marginLeft: 'auto' } },
+              t('kpiWallet') + ' ' + fmtUsd(futures.totalWalletBalance))),
+          h(Table, {
+            cols: '1fr .55fr .9fr .9fr .9fr 1.1fr .6fr',
+            head: [t('posSymbol'), t('posSide'), t('posSize'), t('posEntry'), t('posMark'), t('posPnl'), t('posLeverage')],
+            rows: posRows,
+            empty: t('emptyPositions'),
+          })))
+      }
+
+      if (data && data.tickers && data.tickers.length) {
+        const tickerRows = data.tickers.map((k) => [
+          k.symbol,
+          fmtPrice(k.lastPrice),
+          toneCell(k.priceChangePercent, fmtPct),
+          fmtCompact(k.quoteVolume) + ' USDT',
+        ])
+        body.push(h('div', { key: 'market', className: 'wba-card' },
+          h('div', { className: 'wba-card-head' }, h('h3', { className: 'wba-card-title' }, t('marketTitle'))),
+          h(Table, {
+            cols: '1fr 1fr 1fr 1fr',
+            head: [t('marketSymbol'), t('marketPrice'), t('marketChange'), t('marketVolume')],
+            rows: tickerRows,
+            empty: t('emptyMarket'),
+          })))
+      } else if (data && !(data.errors || []).some((e) => e.section === 'market')) {
+        body.push(h('div', { key: 'market-empty', className: 'wba-card' },
+          h('div', { className: 'wba-card-head' }, h('h3', { className: 'wba-card-title' }, t('marketTitle'))),
+          h('div', { className: 'wba-empty' }, t('emptyMarket'))))
+      }
+
+      if (data) {
+        body.push(h('div', { key: 'foot', className: 'wba-foot' },
+          h('span', null, t('footnote')),
+          h('span', null, data.proxy ? t('proxyOn') : t('proxyOff'))))
+      }
+
+      return h('div', { className: 'wba-root' }, head, h('div', { className: 'wba-body' }, body))
+    }
+
+    /** 兜底错误边界：数据形状异常时显示错误卡片，而不是把整个 slot 弄崩。 */
+    class PanelBoundary extends React.Component {
+      constructor(props) { super(props); this.state = { error: null } }
+      static getDerivedStateFromError(error) { return { error } }
+      render() {
+        if (this.state.error) {
+          const message = String((this.state.error && this.state.error.message) || this.state.error)
+          return h('div', { className: 'wba-root' },
+            h('div', { className: 'wba-body' },
+              h('div', { className: 'wba-err' }, '面板渲染失败 / panel render failed: ' + message)))
+        }
+        return this.props.children
+      }
+    }
+    function BinancePanelSafe(props) {
+      return h(PanelBoundary, null, h(BinancePanel, props))
+    }
+
+    /* ───────────────────────── 注册 ───────────────────────── */
+
+    const name = 'whyshu-ba-client'
+    const inject = ['slots', 'locale']
+
+    function apply(ctx) {
+      try {
+        ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'whyshu-ba: dictionaries')
+      } catch (e) {
+        console.warn('[whyshu-ba] 语言字典注册失败:', (e && e.message) || e)
+      }
+      const t = ctx.locale.bind(NS)
+      injectCss()
+      // 自检信标：宿主 /health 会回报 clientPingAt ⇒ 能区分"bundle 没加载"与"加载了但没显示"
+      try { fetch(API + '/ping?from=client').catch(() => {}) } catch { /* noop */ }
+
+      // ⛔ 永不抛出：注册失败只影响这个面板，不能让 web boot 报 "entry did not activate"
+      try {
+        ctx.slots.inject('main', () => ctx.slots.register({
+          name: 'main',
+          key: PANEL_ID,
+          locale: NS,
+        }, BinancePanelSafe))
+        ctx.slots.inject('sidebar.panellist', () => ctx.slots.register({
+          name: 'sidebar.panellist',
+          id: PANEL_ID,
+          order: 20,
+          locale: NS,
+          label: () => t('panel'),
+        }, BinanceIcon))
+      } catch (e) {
+        console.warn('[whyshu-ba] 面板注册失败（不影响 dsh）:', (e && e.message) || e)
+      }
+    }
+
+    return { name, inject, apply }
+  },
+})

package/icon.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="Binance account panel">
+  <rect x="8" y="30" width="10" height="20" rx="3" fill="currentColor" opacity="0.55"/>
+  <rect x="26" y="18" width="10" height="32" rx="3" fill="currentColor" opacity="0.8"/>
+  <rect x="44" y="8" width="10" height="42" rx="3" fill="currentColor"/>
+  <path d="M10 58h44" stroke="currentColor" stroke-width="4" stroke-linecap="round"/>
+</svg>

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Binance account panel",
+    "description": "Adds a left sidebar entry that opens a read-only panel with Binance spot assets, futures positions, and market board. The API key stays in the dsh host process."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "币安账户面板",
+    "description": "在左侧栏增加一个入口，点击后在主视图展示币安现货资产、合约持仓与行情看板（只读）。API Key 只保存在 dsh 宿主进程，不下发浏览器。"
+  }
+}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@whyshu/ba",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "DSH 左侧栏币安面板：主视图展示现货资产、合约持仓与行情看板（只读，API Key 仅宿主侧）",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.2.0"
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "dsh-plugin",
+    "cordis",
+    "binance",
+    "spot",
+    "futures",
+    "portfolio"
+  ],
+  "exports": {
+    ".": "./src/index.js",
+    "./client": "./dist/client.js",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg"
+  },
+  "files": [
+    "src/",
+    "dist/",
+    "locale/",
+    "icon.svg",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true
+    },
+    "plugin": {
+      "displayName": "币安账户面板"
+    }
+  }
+}

package/src/binance.mjs

@@ -0,0 +1,385 @@
+/**
+ * whyshu-ba · 币安只读数据层（宿主侧）
+ *
+ * 设计红线：
+ *  - API Key / Secret **只在宿主进程**读取与签名，永不回传浏览器；
+ *  - 只读：只调用 GET 行情/账户/持仓接口，不调用任何下单/划转/提现接口；
+ *  - 每次请求都重新读 `~/.dsh/argent/ba.env`，改 Key / 代理无需重启 dsh；
+ *  - 代理可配（默认读 BINANCE_PROXY，其次 HTTPS_PROXY），未配置时直连。
+ *
+ * 配置（~/.dsh/argent/ba.env，权限 600）：
+ *   BINANCE_API_KEY=...
+ *   BINANCE_API_SECRET=...
+ *   BINANCE_PROXY=http://127.0.0.1:7890      # 可选；本机直连 api.binance.com 不通时必须配
+ *   BINANCE_SYMBOLS=BTCUSDT,ETHUSDT,SOLUSDT  # 可选，行情看板自选币对
+ */
+import { createHmac } from 'node:crypto'
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import http from 'node:http'
+import https from 'node:https'
+import tls from 'node:tls'
+
+export const SPOT_BASE = 'https://api.binance.com'
+export const FUTURES_BASE = 'https://fapi.binance.com'
+export const ENV_FILE = join(homedir(), '.dsh', 'argent', 'ba.env')
+export const DEFAULT_SYMBOLS = ['BTCUSDT', 'ETHUSDT', 'SOLUSDT', 'BNBUSDT']
+const TIMEOUT_MS = 12000
+const RECV_WINDOW = 5000
+
+/** 币安接口返回的业务错误（code/msg）；与网络错误分开，便于前端提示。 */
+export class BinanceError extends Error {
+  constructor(message, { status = 0, code = 0 } = {}) {
+    super(message)
+    this.name = 'BinanceError'
+    this.status = status
+    this.code = code
+  }
+}
+
+/** 极简 KEY=VALUE 解析（只支持注释、空行、单/双引号），不引依赖。 */
+export function parseEnvText(text) {
+  const out = {}
+  for (const raw of String(text || '').split(/\r?\n/)) {
+    const line = raw.trim()
+    if (!line || line.startsWith('#')) continue
+    const eq = line.indexOf('=')
+    if (eq <= 0) continue
+    const key = line.slice(0, eq).trim()
+    let value = line.slice(eq + 1).trim()
+    if (value.length >= 2) {
+      const q = value[0]
+      if ((q === '"' || q === "'") && value[value.length - 1] === q) value = value.slice(1, -1)
+    }
+    if (key) out[key] = value
+  }
+  return out
+}
+
+/** 读设置：进程环境变量优先，其次 env 文件。envFile 可传（测试用隔离路径）。 */
+export function loadSettings(envFile = ENV_FILE) {
+  let file = {}
+  try {
+    if (existsSync(envFile)) file = parseEnvText(readFileSync(envFile, 'utf8'))
+  } catch { /* 读不到就按未配置处理 */ }
+  const pick = (name) => {
+    const raw = process.env[name] !== undefined ? process.env[name] : file[name]
+    return typeof raw === 'string' && raw.trim() ? raw.trim() : ''
+  }
+  const symbols = pick('BINANCE_SYMBOLS')
+    .split(',')
+    .map((s) => s.trim().toUpperCase())
+    .filter((s) => /^[A-Z0-9]{5,20}$/.test(s))
+  const proxy = pick('BINANCE_PROXY')
+    || process.env.HTTPS_PROXY || process.env.https_proxy
+    || process.env.HTTP_PROXY || process.env.http_proxy
+    || ''
+  return {
+    apiKey: pick('BINANCE_API_KEY'),
+    apiSecret: pick('BINANCE_API_SECRET'),
+    proxy,
+    symbols: symbols.length ? symbols : DEFAULT_SYMBOLS,
+    envFile,
+  }
+}
+
+export function hasCredentials(settings) {
+  return Boolean(settings && settings.apiKey && settings.apiSecret)
+}
+
+/**
+ * 通过 HTTP 代理建立到目标主机的 CONNECT 隧道。
+ * @param {string} proxy 代理 URL（http://host:port）
+ * @param {URL} target 目标 URL
+ * @param {number} timeoutMs 超时
+ * @returns {Promise<import('node:net').Socket>} 已连通的裸 TCP socket
+ */
+function openTunnel(proxy, target, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    let proxyUrl
+    try { proxyUrl = new URL(proxy) } catch { reject(new Error('BINANCE_PROXY 不是合法 URL: ' + proxy)); return }
+    if (proxyUrl.protocol !== 'http:') { reject(new Error('只支持 http:// 代理，收到: ' + proxyUrl.protocol)); return }
+    const port = target.port || '443'
+    const host = target.hostname
+    const req = http.request({
+      host: proxyUrl.hostname,
+      port: proxyUrl.port || 80,
+      method: 'CONNECT',
+      path: host + ':' + port,
+      headers: { host: host + ':' + port },
+      agent: false,
+      timeout: timeoutMs,
+    })
+    const fail = (e) => { try { req.destroy(e) } catch { reject(e) } }
+    req.on('timeout', () => fail(new Error('代理连接超时: ' + proxyUrl.host)))
+    req.on('error', (e) => reject(new Error('代理连接失败 ' + proxyUrl.host + ': ' + e.message)))
+    req.on('connect', (res, socket) => {
+      if (res.statusCode !== 200) {
+        socket.destroy()
+        reject(new Error('代理 CONNECT 返回 ' + res.statusCode))
+        return
+      }
+      resolve(socket)
+    })
+    req.end()
+  })
+}
+
+/**
+ * GET 一个 JSON（带代理/超时）；HTTP 非 2xx 或币安 {code,msg} 抛 BinanceError。
+ * 超时是**整段硬超时**：DNS / CONNECT / TLS / 响应任一环节卡住都会按时失败。
+ * @param {string} url
+ * @param {{headers?: Record<string,string>, proxy?: string, timeoutMs?: number}} [opts]
+ */
+export async function requestJson(url, opts = {}) {
+  const target = new URL(url)
+  const timeoutMs = opts.timeoutMs || TIMEOUT_MS
+  const headers = { accept: 'application/json', 'user-agent': 'whyshu-ba/0.1 (dsh plugin)', ...(opts.headers || {}) }
+
+  let tunnel = null
+  let agent = null
+  let req = null
+  let timer = null
+  let settled = false
+
+  const cleanup = () => {
+    if (timer) { clearTimeout(timer); timer = null }
+    if (agent) { try { agent.destroy() } catch { /* noop */ } }
+    if (tunnel && tunnel.destroyed === false) { try { tunnel.destroy() } catch { /* noop */ } }
+    if (req && req.destroyed === false) { try { req.destroy() } catch { /* noop */ } }
+  }
+
+  return new Promise((resolve, reject) => {
+    const finish = (fn, value) => {
+      if (settled) return
+      settled = true
+      cleanup()
+      fn(value)
+    }
+    const fail = (e) => finish(reject, e instanceof BinanceError ? e : new Error((e && e.message) || String(e)))
+
+    timer = setTimeout(() => {
+      fail(new Error('请求超时（' + timeoutMs + 'ms）' + (opts.proxy ? '，代理 ' + opts.proxy : '')))
+    }, timeoutMs)
+
+    ;(async () => {
+      try {
+        if (opts.proxy) tunnel = await openTunnel(opts.proxy, target, timeoutMs)
+        if (settled) return
+        if (tunnel) {
+          // 走代理：自定义 Agent 把 CONNECT 后的裸 socket 包成 TLS。
+          agent = new https.Agent({ keepAlive: false, maxSockets: 1 })
+          agent.createConnection = (options) => tls.connect({ socket: tunnel, servername: options.host })
+        }
+        if (settled) return
+        req = https.request({
+          host: target.hostname,
+          port: target.port || 443,
+          path: target.pathname + target.search,
+          method: 'GET',
+          headers: { ...headers, host: target.hostname, connection: 'close' },
+          agent: agent || false,
+        }, (res) => {
+          const chunks = []
+          res.on('data', (c) => chunks.push(c))
+          res.on('end', () => {
+            const text = Buffer.concat(chunks).toString('utf8')
+            let body
+            try { body = text ? JSON.parse(text) : {} } catch { body = undefined }
+            if (res.statusCode >= 200 && res.statusCode < 300) {
+              finish(resolve, body)
+              return
+            }
+            const msg = body && (body.msg || body.message) ? String(body.msg || body.message) : text.slice(0, 200)
+            finish(reject, new BinanceError('HTTP ' + res.statusCode + ': ' + msg, { status: res.statusCode, code: body && typeof body.code === 'number' ? body.code : 0 }))
+          })
+          res.on('error', fail)
+        })
+        req.on('error', fail)
+        req.end()
+      } catch (e) {
+        fail(e)
+      }
+    })()
+  })
+}
+
+/**
+ * 批量 symbols 参数：币安**要求原样**的 JSON 数组（`["A","B"]`），
+ * 百分号编码会被 `Illegal characters found in parameter 'symbols'` 拒绝。
+ */
+function symbolsParam(symbols) {
+  return JSON.stringify([...new Set(symbols)])
+}
+
+/** 公开行情：24h ticker 批量查询（无需鉴权）；整批失败时逐个降级。 */
+export async function fetchTickers24h(symbols, settings) {
+  if (!symbols || !symbols.length) return []
+  const normalize = (r) => ({
+    symbol: String(r.symbol || ''),
+    lastPrice: Number(r.lastPrice || 0),
+    priceChangePercent: Number(r.priceChangePercent || 0),
+    highPrice: Number(r.highPrice || 0),
+    lowPrice: Number(r.lowPrice || 0),
+    quoteVolume: Number(r.quoteVolume || 0),
+  })
+  try {
+    const rows = await requestJson(SPOT_BASE + '/api/v3/ticker/24hr?symbols=' + symbolsParam(symbols), { proxy: settings.proxy })
+    if (!Array.isArray(rows)) throw new BinanceError('行情返回格式异常')
+    return rows.map(normalize)
+  } catch (batchError) {
+    // 自选里混了不存在的币对时整批会失败：逐个取，成功的留下。
+    const settled = await Promise.all(symbols.map(async (symbol) => {
+      try {
+        const one = await requestJson(SPOT_BASE + '/api/v3/ticker/24hr?symbol=' + encodeURIComponent(symbol), { proxy: settings.proxy })
+        return one && one.symbol ? normalize(one) : null
+      } catch { return null }
+    }))
+    const rows = settled.filter(Boolean)
+    if (!rows.length) throw batchError
+    return rows
+  }
+}
+
+/** 公开行情：批量现价（用于资产折 USDT）；整批失败时逐个降级。 */
+export async function fetchPrices(symbols, settings) {
+  if (!symbols || !symbols.length) return new Map()
+  try {
+    const rows = await requestJson(SPOT_BASE + '/api/v3/ticker/price?symbols=' + symbolsParam(symbols), { proxy: settings.proxy })
+    const map = new Map()
+    if (Array.isArray(rows)) for (const r of rows) map.set(String(r.symbol || ''), Number(r.price || 0))
+    return map
+  } catch {
+    // 某些资产没有 USDT 现货对（或已下线）会让整批失败：逐个取，失败的跳过。
+    const map = new Map()
+    await Promise.all([...new Set(symbols)].map(async (symbol) => {
+      try {
+        const one = await requestJson(SPOT_BASE + '/api/v3/ticker/price?symbol=' + encodeURIComponent(symbol), { proxy: settings.proxy })
+        if (one && one.price) map.set(String(one.symbol || symbol), Number(one.price))
+      } catch { /* 无对应交易对：该资产估值留空 */ }
+    }))
+    return map
+  }
+}
+
+/** 签名 GET（现货/合约共用）。 */
+async function signedGet(base, path, params, settings) {
+  const search = new URLSearchParams({
+    ...params,
+    recvWindow: String(RECV_WINDOW),
+    timestamp: String(Date.now()),
+  }).toString()
+  const signature = createHmac('sha256', settings.apiSecret).update(search).digest('hex')
+  return requestJson(base + path + '?' + search + '&signature=' + signature, {
+    proxy: settings.proxy,
+    headers: { 'X-MBX-APIKEY': settings.apiKey },
+  })
+}
+
+/** 现货账户：余额 + 现价折 USDT。 */
+export async function fetchSpot(settings) {
+  const account = await signedGet(SPOT_BASE, '/api/v3/account', {}, settings)
+  const balances = Array.isArray(account.balances) ? account.balances : []
+  const rows = balances
+    .map((b) => {
+      const free = Number(b.free || 0)
+      const locked = Number(b.locked || 0)
+      return { asset: String(b.asset || ''), free, locked, total: free + locked }
+    })
+    .filter((b) => b.asset && b.total > 0 && b.total > 1e-12)
+
+  const pairs = rows
+    .filter((b) => b.asset !== 'USDT')
+    .map((b) => b.asset + 'USDT')
+  let prices = new Map()
+  if (pairs.length) {
+    try { prices = await fetchPrices(pairs, settings) } catch { /* 无对应现货对的币种不估值 */ }
+  }
+  const valued = rows.map((b) => {
+    const priceUSDT = b.asset === 'USDT' ? 1 : (prices.get(b.asset + 'USDT') || 0)
+    return { ...b, priceUSDT, valueUSDT: priceUSDT ? b.total * priceUSDT : null }
+  }).sort((a, b) => (b.valueUSDT || 0) - (a.valueUSDT || 0))
+  const totalUSDT = valued.reduce((sum, b) => sum + (b.valueUSDT || 0), 0)
+  return {
+    totalUSDT,
+    canTrade: Boolean(account.canTrade),
+    accountType: String(account.accountType || ''),
+    rows: valued,
+  }
+}
+
+/** U 本位合约：账户余额 + 非零持仓。 */
+export async function fetchFutures(settings) {
+  const [account, positions] = await Promise.all([
+    signedGet(FUTURES_BASE, '/fapi/v2/account', {}, settings),
+    signedGet(FUTURES_BASE, '/fapi/v2/positionRisk', {}, settings),
+  ])
+  const rows = (Array.isArray(positions) ? positions : [])
+    .map((p) => {
+      const amt = Number(p.positionAmt || 0)
+      return {
+        symbol: String(p.symbol || ''),
+        side: amt > 0 ? 'LONG' : amt < 0 ? 'SHORT' : 'FLAT',
+        positionAmt: amt,
+        entryPrice: Number(p.entryPrice || 0),
+        markPrice: Number(p.markPrice || 0),
+        unrealizedProfit: Number(p.unRealizedProfit || p.unrealizedProfit || 0),
+        leverage: Number(p.leverage || 0),
+        liquidationPrice: Number(p.liquidationPrice || 0),
+        marginType: String(p.marginType || ''),
+      }
+    })
+    .filter((p) => p.symbol && p.positionAmt !== 0)
+  return {
+    totalWalletBalance: Number(account.totalWalletBalance || 0),
+    totalUnrealizedProfit: Number(account.totalUnrealizedProfit || 0),
+    totalMarginBalance: Number(account.totalMarginBalance || 0),
+    availableBalance: Number(account.availableBalance || 0),
+    positions: rows,
+  }
+}
+
+/**
+ * 面板总览：行情总是有（公开接口）；账户/持仓在配好 Key 后才有。
+ * 各段独立失败：一段报错不影响其他段。
+ * @param {ReturnType<typeof loadSettings>} [settingsIn]
+ */
+export async function fetchOverview(settingsIn) {
+  const settings = settingsIn || loadSettings()
+  const configured = hasCredentials(settings)
+  const errors = []
+  const mark = (section, e) => {
+    const message = e instanceof BinanceError ? e.message : String((e && e.message) || e)
+    errors.push({ section, message })
+  }
+
+  let tickers = []
+  try {
+    tickers = await fetchTickers24h(settings.symbols, settings)
+  } catch (e) {
+    mark('market', e)
+  }
+
+  let spot = null
+  let futures = null
+  if (configured) {
+    try { spot = await fetchSpot(settings) } catch (e) { mark('spot', e) }
+    try { futures = await fetchFutures(settings) } catch (e) { mark('futures', e) }
+  }
+
+  // 行情按自选顺序返回（币安接口不保证顺序）
+  const bySymbol = new Map(tickers.map((k) => [k.symbol, k]))
+  const ordered = settings.symbols.map((s) => bySymbol.get(s)).filter(Boolean)
+
+  return {
+    at: new Date().toISOString(),
+    configured,
+    proxy: Boolean(settings.proxy),
+    symbols: settings.symbols,
+    tickers: ordered.length ? ordered : tickers,
+    spot,
+    futures,
+    errors,
+  }
+}

package/src/index.js

@@ -0,0 +1,84 @@
+/**
+ * whyshu-ba · 宿主侧插件
+ *
+ * 只做两件事：
+ *  1. 注册本地只读端点 `/api/whyshu-ba/*`（币安 Key 只在宿主进程使用，不下发浏览器）；
+ *  2. 由 bundle 的客户端部分（dist/client.js）在左侧栏注册一个面板入口（id=binance），
+ *     点击后在主视图渲染 `main` slot 的币安面板。
+ *
+ * 红线：只读（只打行情/账户/持仓 GET 接口）；接口异常只返回错误 JSON，不阻塞 dsh 启动。
+ */
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { ENV_FILE, fetchOverview, hasCredentials, loadSettings } from './binance.mjs'
+
+/** 每次都读盘：重装后 version 仍能反映当前磁盘版本 */
+function pkgVersion() {
+  try {
+    return JSON.parse(readFileSync(join(dirname(dirname(fileURLToPath(import.meta.url))), 'package.json'), 'utf8')).version || '0.0.0'
+  } catch { return '0.0.0' }
+}
+
+/** 客户端 bundle 是否真的被加载过（区分"bundle 没加载" vs "加载了但没显示"） */
+const CLIENT_PING = { at: null, ua: '' }
+
+const json = (res, code, body) => {
+  res.writeHead(code, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' })
+  res.end(JSON.stringify(body))
+}
+
+async function handle(req, res) {
+  const url = new URL(req.url || '/', 'http://localhost')
+  if (req.method !== 'GET') return json(res, 405, { ok: false, error: 'method_not_allowed' })
+
+  try {
+    if (url.pathname === '/api/whyshu-ba/health') {
+      const settings = loadSettings()
+      return json(res, 200, {
+        ok: true,
+        version: pkgVersion(),
+        configured: hasCredentials(settings),
+        proxy: Boolean(settings.proxy),
+        symbols: settings.symbols,
+        envFile: ENV_FILE,
+        clientPingAt: CLIENT_PING.at,
+        clientUa: CLIENT_PING.ua,
+      })
+    }
+    if (url.pathname === '/api/whyshu-ba/ping') {
+      const at = new Date().toISOString()
+      const ua = String((req.headers && req.headers['user-agent']) || '').slice(0, 80)
+      Object.assign(CLIENT_PING, { at, ua })
+      return json(res, 200, { ok: true })
+    }
+    if (url.pathname === '/api/whyshu-ba/overview') {
+      return json(res, 200, { ok: true, data: await fetchOverview() })
+    }
+    return json(res, 404, { ok: false, error: 'not_found' })
+  } catch (e) {
+    return json(res, 502, {
+      ok: false,
+      error: 'upstream_error',
+      message: String((e && e.message) || e).slice(0, 300),
+    })
+  }
+}
+
+export const name = 'whyshu-ba'
+export const inject = ['webServer']
+
+export function apply(ctx) {
+  // ⛔ 永不抛出：插件激活失败会让整个 web boot 报 "entry did not activate"。
+  try {
+    if (!ctx || !ctx.webServer || typeof ctx.webServer.register !== 'function') {
+      console.error('[whyshu-ba] 未拿到 webServer 服务，跳过端点注册（面板会显示 404，但 dsh 正常启动）')
+      return
+    }
+    ctx.effect(() => ctx.webServer.register({ kind: 'prefix', path: '/api/whyshu-ba', handler: handle }), 'whyshu-ba: read-only binance endpoints')
+    console.log(`[whyshu-ba] 已注册 /api/whyshu-ba/*（v${pkgVersion()}，只读，币安 Key 仅在宿主侧使用）`)
+  } catch (e) {
+    console.error('[whyshu-ba] 端点注册失败（不影响 dsh 其他功能）:', (e && e.message) || e)
+  }
+}