dsh-whale-widget 0.1.0

package/README.md

@@ -0,0 +1,121 @@
+# DSH 小鲸鱼余额挂件（DeepSeek Balance Whale Widget）
+
+DeepSeek Harness（DSH）Web 界面右下角的常驻余额挂件：本地小鲸鱼气泡图 + DeepSeek API 余额，每次打开界面自动启用。本项目是标准 DSH 插件包，可通过 `dsh plugin` 安装/卸载。
+
+## 特性
+
+- 🐋 常驻自启：随 DSH Web 界面每次打开自动出现（标准 DSH bundle 插件）
+- 💰 余额：60 秒自动刷新 + 点击手动刷新；余额变化时数字**滚动动画**；瞬时网络抖动自动沿用最近余额不报错
+- 🖱️ 拖拽 + **四边四分之一吸附**（左/右/上/下，角落可组合）
+- 🔄 左吸附时整体**水平镜像翻转**（文字同步反向、带动画）
+- 🧸 **按压 Q 弹**玩偶效果（按压时底部坐标不变）
+- 🎚️ 悬停显示大小调节按钮（0.6–1.4 倍，尺寸记忆）
+- 📐 随浏览器窗口自动缩放；文字位置/字号与图片联动
+
+## 目录结构
+
+```text
+dsh-whale-widget/
+├── package.json          # DSH bundle 插件元数据
+├── README.md             # 本文件
+├── cordis.patch.yml      # 插件挂载声明
+├── lib/
+│   └── index.js          # 宿主侧插件本体
+├── assets/
+│   └── DSniang02.png     # 小鲸鱼气泡图
+└── whale-widget-prompt.md # 完整规格/维护提示词
+```
+
+## 安装
+
+### 方式 A：本地开发安装（当前项目）
+
+在项目根目录（`DeepSeek-Balance-Whale-Widget-main`）执行：
+
+```powershell
+dsh plugin --profile web add link:.\dsh-whale-widget
+```
+
+说明：
+
+- `dsh plugin` 会把参数转发给 pnpm，并在成功后自动把 `dsh-whale-widget` 加入 `dsh.profile.bundles`
+- 使用 `link:` 会在 profile 的 `node_modules` 里链接到当前源码目录，方便继续改代码
+- 安装完成后重启 `dsh web`，再 F5 刷新浏览器
+- **如果之后移动了源码目录**，必须重新到新的项目根目录执行一次：
+  ```powershell
+  dsh plugin --profile web add link:.\dsh-whale-widget
+  ```
+  因为 `link:` 记录的是源目录的绝对路径；移动后旧链接会失效。若提示已存在/冲突，可先 `dsh plugin --profile web remove dsh-whale-widget` 再重新 add。
+
+### 方式 B：发布到 npm 后安装
+
+如果你把这个包发布到 npm：
+
+```powershell
+cd dsh-whale-widget
+npm publish
+```
+
+然后任意机器上安装：
+
+```powershell
+dsh plugin --profile web add dsh-whale-widget
+```
+
+## 卸载
+
+```powershell
+dsh plugin --profile web remove dsh-whale-widget
+```
+
+## 从旧手动安装升级
+
+如果你之前按旧方式手动安装过（复制 `whale-balance.mjs` + 改 `cordis.patch.yml`），先清理：
+
+```powershell
+$web = "$env:USERPROFILE\.dsh\profiles\web"
+
+Remove-Item "$web\whale-balance.mjs" -ErrorAction SilentlyContinue
+Remove-Item "$web\DSniang02.png" -ErrorAction SilentlyContinue
+```
+
+然后编辑 `$web\cordis.patch.yml`，删除这段旧补丁：
+
+```yaml
+- insert:
+    - id: whale-balance-widget
+      name: ./whale-balance.mjs?v=1
+```
+
+如果里面只有这段，直接改成：
+
+```yaml
+[]
+```
+
+清理后再执行上面的安装命令。
+
+## 验证
+
+```powershell
+dsh --profile web --dump-config | Select-String -Pattern "whale"
+
+curl http://127.0.0.1:3080/dsh-whale/image.png
+curl http://127.0.0.1:3080/dsh-whale/balance.json
+```
+
+- `/dsh-whale/image.png` → 200 `image/png`
+- `/dsh-whale/balance.json` → 200，含 `{"ok":true,"totalBalance":...,"currency":"CNY"}`
+- 浏览器 F5 后右下角出现挂件
+
+## 常见问题
+
+- **挂件不出现**：确认 `dsh plugin add` 成功；`dsh --profile web --dump-config` 里能看到 `dsh-whale-widget`；重启 `dsh web` 后 F5。
+- **图片不显示**：确认 `assets/DSniang02.png` 在插件包内，且没有把旧文件放在 profile 里占用了同名路由。
+- **余额报「未配置 DEEPSEEK_API_KEY」**：去 DSH 配置凭据。
+- **本地开发改了代码不生效**：使用 `link:` 安装时，修改源码后重启 `dsh web`（ESM 模块缓存）；如果用已发布版本，需要 `npm publish` 新版本后 `dsh plugin --profile web update dsh-whale-widget`。
+- **自定义图片**：必须是 1026×1026、气泡几何一致（中心 455,247、长轴 710、纵轴 430），否则按 `whale-widget-prompt.md` 调整文字定位参数。
+
+## 开发与维护
+
+完整规格、视觉参数、架构结论和生成提示词见 `whale-widget-prompt.md`。修改文字位置、颜色、动画、吸附逻辑时参考该文件。

package/cordis.patch.yml

@@ -0,0 +1,15 @@
+# ============================================================================
+# dsh-whale-widget —— DSH bundle patch
+# ============================================================================
+# 这是插件的"挂载声明"。DSH 启动时按 bundle 层栈叠加各插件 patch，
+# 本文件会把鲸鱼余额挂件插入 Web profile 的配置树。
+#
+# 安装方式（不再需要手工复制/手工改 profile patch）：
+#   dsh plugin --profile web add dsh-whale-widget
+# 或本地开发安装：
+#   dsh plugin --profile web add link:<本目录绝对路径>
+# ============================================================================
+
+- insert:
+    - id: dsh-whale-widget
+      name: dsh-whale-widget

package/lib/index.js

@@ -0,0 +1,627 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// Package root: lib/index.js -> package root. This keeps the bundle relocatable
+// when installed as a normal DSH npm plugin (node_modules or a local link).
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+
+// DSH home: used for the widget size memory file, since node_modules may be
+// read-only or cleaned on update.
+const DSH_HOME = process.env.DSH_HOME || path.join(os.homedir(), '.dsh')
+
+// Resolve the whale image relative to the package first, so the bundle works
+// no matter where it is installed. Legacy absolute paths remain as harmless
+// fallbacks for older manual installs.
+const IMAGE_CANDIDATES = [
+  path.join(PACKAGE_ROOT, 'assets', 'DSniang02.png'),
+  path.join(PACKAGE_ROOT, 'DSniang02.png'),
+  'D:/TestBox/deepseek/DSniang02.png',
+  'D:/TestBox/deepseek/skin/DSniang02.png',
+]
+
+// Size memory file: prefer writable DSH home locations, then legacy fallbacks.
+const SIZE_FILE_CANDIDATES = [
+  path.join(DSH_HOME, '.dshw-size.json'),
+  path.join(DSH_HOME, 'profiles', 'web', '.dshw-size.json'),
+  'D:/TestBox/deepseek/.dshw-size.json',
+  'D:/TestBox/deepseek/skin/.dshw-size.json',
+]
+
+const BALANCE_URL = 'https://api.deepseek.com/user/balance'
+const BALANCE_TTL_MS = 25000
+
+const JSON_HEADERS = {
+  'Content-Type': 'application/json; charset=utf-8',
+  'Access-Control-Allow-Origin': '*',
+  'Cache-Control': 'no-store',
+}
+
+const WIDGET_JS = `(function () {
+if (window.__dshWhaleWidget) return
+window.__dshWhaleWidget = true
+
+var MIN_SCALE = 0.6
+var MAX_SCALE = 1.4
+var STEP = 0.1
+var CLICK_SQ = 9
+var REFRESH_MS = 60000
+var CHANGE_MS = 900
+var ANIM_MS = 700
+var FETCH_TIMEOUT_MS = 25000
+var BALANCE_URL = '/dsh-whale/balance.json'
+var SIZE_URL = '/dsh-whale/size.json'
+var IMG_URL = '/dsh-whale/image.png'
+
+var css = [
+  '.dshwv-root{position:fixed;right:0;bottom:0;--dshw-scale:1;--dshw-base:clamp(96px,calc(min(196px,min(100vw,100vh) * 0.22) * var(--dshw-scale)),292px);width:var(--dshw-base);height:var(--dshw-base);cursor:grab;touch-action:none;user-select:none;-webkit-user-select:none;z-index:9999;font-family:inherit;transition:left .16s ease,top .16s ease,transform .3s ease}',
+  '.dshwv-root.dshwv-left{transform:scaleX(-1)}',
+  '.dshwv-root.dshwv-dragging{cursor:grabbing;transition:none}',
+  '.dshwv-body{position:absolute;left:0;top:0;width:100%;height:100%;transform-origin:50% 100%;transition:transform .22s cubic-bezier(.34,1.56,.64,1)}',
+  '.dshwv-img{width:var(--dshw-base);height:var(--dshw-base);display:block;pointer-events:none;-webkit-user-drag:none;user-select:none}',
+  '.dshwv-text{position:absolute;left:44.346%;top:25.5%;transform:translate(-50%,-50%);text-align:center;color:#536ba9;line-height:1.18;white-space:nowrap;--dshw-u:calc(var(--dshw-base) / 1026);pointer-events:none;transition:transform .3s ease}',
+  '.dshwv-root.dshwv-left .dshwv-text{transform:translate(-50%,-50%) scaleX(-1)}',
+  '.dshwv-label{font-size:calc(var(--dshw-u) * 68);font-weight:600;letter-spacing:.06em}',
+  '.dshwv-amount{font-size:calc(var(--dshw-u) * 119);font-weight:800;line-height:1.05}',
+  '.dshwv-hint{font-size:calc(var(--dshw-u) * 54);color:#9fb0d9;letter-spacing:.02em}',
+  '.dshwv-size{position:absolute;top:4px;right:4px;display:flex;gap:4px;opacity:0;transition:opacity .15s ease;z-index:2}',
+  '.dshwv-root:hover .dshwv-size{opacity:1}',
+  '.dshwv-size button{width:20px;height:20px;border:none;border-radius:50%;background:rgba(83,107,169,.85);color:#fff;font-size:13px;line-height:1;padding:0;cursor:pointer;display:flex;align-items:center;justify-content:center;user-select:none}',
+  '.dshwv-size button:hover{background:#536ba9}'
+].join('\\n')
+
+var styleEl = document.createElement('style')
+styleEl.textContent = css
+document.head.appendChild(styleEl)
+
+var root = document.createElement('div')
+root.className = 'dshwv-root'
+
+var img = document.createElement('img')
+img.className = 'dshwv-img'
+img.src = IMG_URL
+img.alt = 'DeepSeek 余额'
+img.draggable = false
+
+var sizeBox = document.createElement('div')
+sizeBox.className = 'dshwv-size'
+function makeBtn(text, title, delta) {
+  var b = document.createElement('button')
+  b.type = 'button'
+  b.textContent = text
+  b.title = title
+  b.addEventListener('pointerdown', function (e) { e.stopPropagation() })
+  b.addEventListener('click', function (e) { e.stopPropagation(); adjust(delta) })
+  return b
+}
+sizeBox.appendChild(makeBtn('-', '缩小', -STEP))
+sizeBox.appendChild(makeBtn('+', '放大', STEP))
+
+var textBox = document.createElement('div')
+textBox.className = 'dshwv-text'
+var labelEl = document.createElement('div')
+labelEl.className = 'dshwv-label'
+labelEl.textContent = 'DeepSeek 余额'
+var amountEl = document.createElement('div')
+amountEl.className = 'dshwv-amount'
+var hintEl = document.createElement('div')
+hintEl.className = 'dshwv-hint'
+textBox.appendChild(labelEl)
+textBox.appendChild(amountEl)
+textBox.appendChild(hintEl)
+
+var body = document.createElement('div')
+body.className = 'dshwv-body'
+body.appendChild(img)
+body.appendChild(sizeBox)
+body.appendChild(textBox)
+root.appendChild(body)
+document.body.appendChild(root)
+
+// Position model: the widget is ALWAYS expressed in left/top px (so edge snaps
+// animate smoothly via the CSS transition on both sides — switching to
+// right/auto cannot transition and flashes). The anchor info (h/v + offsets)
+// lives in state and is used by settle() to recompute coordinates on window
+// resize and size changes, keeping the widget glued to its anchored edge.
+var state = {
+  scale: 1,
+  h: 'right',
+  hOff: 0,
+  v: 'bottom',
+  vOff: 0,
+  left: 0,
+  top: 0,
+  balance: null,
+  currency: null,
+  status: 'loading',
+  message: ''
+}
+var busy = false
+var settleTimer = null
+var drag = null
+var shown = null
+var animId = null
+
+function clamp(v, lo, hi) { return v < lo ? lo : (v > hi ? hi : v) }
+function viewport() {
+  return {
+    w: window.innerWidth || document.documentElement.clientWidth || 1280,
+    h: window.innerHeight || document.documentElement.clientHeight || 800
+  }
+}
+function fmt(balance, currency) {
+  var num = Number(balance)
+  var fixed = isFinite(num) ? num.toFixed(2) : '--'
+  return currency === 'CNY' ? '¥ ' + fixed : fixed + ' ' + currency
+}
+function animateAmount(from, to, currency, duration) {
+  if (animId) cancelAnimationFrame(animId)
+  if (from === null || !isFinite(from)) from = to
+  if (from === to) {
+    shown = to
+    amountEl.textContent = fmt(to, currency)
+    return
+  }
+  var startTime = null
+  function step(ts) {
+    if (startTime === null) startTime = ts
+    var t = Math.min(1, (ts - startTime) / duration)
+    var eased = 1 - Math.pow(1 - t, 3)
+    var val = from + (to - from) * eased
+    amountEl.textContent = fmt(val, currency)
+    if (t < 1) {
+      animId = requestAnimationFrame(step)
+    } else {
+      animId = null
+      shown = to
+      amountEl.textContent = fmt(to, currency)
+    }
+  }
+  animId = requestAnimationFrame(step)
+}
+function render() {
+  var amount, hint
+  if (state.status === 'loading') {
+    amount = shown !== null ? fmt(shown, state.currency) : '…'
+    hint = '加载中…'
+  } else if (state.status === 'error') {
+    amount = shown !== null ? fmt(shown, state.currency) : '--'
+    hint = state.message ? state.message.slice(0, 14) : '获取失败 · 点击重试'
+  } else {
+    amount = shown !== null ? fmt(shown, state.currency) : (state.balance !== null ? fmt(state.balance, state.currency) : '--')
+    hint = state.status === 'changing' ? '加载中…' : '点击刷新'
+  }
+  amountEl.textContent = amount
+  hintEl.textContent = hint
+}
+function express() {
+  root.style.right = 'auto'
+  root.style.bottom = 'auto'
+  root.style.left = state.left + 'px'
+  root.style.top = state.top + 'px'
+  root.classList.toggle('dshwv-left', state.h === 'left')
+}
+function settle() {
+  var vp = viewport()
+  var w = root.offsetWidth || root.getBoundingClientRect().width || 0
+  var h = root.offsetHeight || root.getBoundingClientRect().height || 0
+  if (drag && drag.active) {
+    // mid-drag resize: keep the pointer-follow position, just clamp into view
+    state.left = clamp(state.left, 0, Math.max(0, vp.w - w))
+    state.top = clamp(state.top, 0, Math.max(0, vp.h - h))
+    express()
+    return
+  }
+  if (state.h === 'right') {
+    state.left = Math.max(0, vp.w - w - state.hOff)
+  } else if (state.h === 'left') {
+    state.left = state.hOff
+  } else {
+    state.left = clamp(state.left, 0, Math.max(0, vp.w - w))
+  }
+  if (state.v === 'bottom') {
+    state.top = Math.max(0, vp.h - h - state.vOff)
+  } else if (state.v === 'top') {
+    state.top = state.vOff
+  } else {
+    state.top = clamp(state.top, 0, Math.max(0, vp.h - h))
+  }
+  express()
+}
+function refresh(manual) {
+  if (busy) return
+  busy = true
+  if (manual || state.balance === null) { state.status = 'loading'; render() }
+  var ctrl = null
+  var timer = null
+  try {
+    ctrl = new AbortController()
+    timer = setTimeout(function () { try { ctrl.abort() } catch (err) {} }, FETCH_TIMEOUT_MS)
+  } catch (err) {}
+  fetch(BALANCE_URL, { cache: 'no-store', signal: ctrl ? ctrl.signal : undefined })
+    .then(function (r) { return r.json() })
+    .then(function (data) {
+      if (data && data.ok) {
+        var nb = Number(data.totalBalance)
+        var nc = String(data.currency || 'CNY')
+        var changed = state.balance !== null && (nb !== state.balance || nc !== state.currency)
+        var currencyChanged = state.currency !== null && nc !== state.currency
+        state.balance = nb
+        state.currency = nc
+        state.message = ''
+        if (changed && !currencyChanged) {
+          if (!manual) {
+            state.status = 'changing'
+            animateAmount(shown, nb, nc, ANIM_MS)
+            if (settleTimer) clearTimeout(settleTimer)
+            settleTimer = setTimeout(function () {
+              settleTimer = null
+              if (state.status === 'changing') { state.status = 'ok'; render() }
+            }, CHANGE_MS)
+          } else {
+            animateAmount(shown, nb, nc, ANIM_MS)
+            state.status = 'ok'
+            render()
+          }
+        } else {
+          if (animId === null) shown = nb
+          state.status = 'ok'
+          render()
+        }
+      } else {
+        state.status = 'error'
+        state.message = (data && data.error) ? String(data.error) : '获取失败'
+        render()
+      }
+    })
+    .catch(function () {
+      state.status = 'error'
+      state.message = '获取失败'
+      render()
+    })
+    .finally(function () {
+      busy = false
+      if (timer) clearTimeout(timer)
+    })
+}
+function adjust(delta) {
+  var next = Math.round(Math.min(MAX_SCALE, Math.max(MIN_SCALE, state.scale + delta)) * 10) / 10
+  state.scale = next
+  root.style.setProperty('--dshw-scale', String(next))
+  try {
+    fetch(SIZE_URL, { method: 'PUT', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ scale: next }) })
+  } catch (err) {}
+  settle()
+}
+var SQUISH = 'scaleY(0.88) scaleX(1.05)'
+function pressDown() {
+  body.style.transform = SQUISH
+}
+function pressUp() {
+  body.style.transform = 'scaleY(1) scaleX(1)'
+}
+function onPointerDown(e) {
+  if (e.button !== 0) return
+  try { root.setPointerCapture(e.pointerId) } catch (err) {}
+  var vp = viewport()
+  var rect = root.getBoundingClientRect()
+  drag = { active: true, startX: e.clientX, startY: e.clientY, origLeft: rect.left, origTop: rect.top, w: rect.width, h: rect.height, moved: false, vp: vp }
+  root.classList.add('dshwv-dragging')
+  pressDown()
+}
+function onPointerMove(e) {
+  if (!drag || !drag.active) return
+  var dx = e.clientX - drag.startX
+  var dy = e.clientY - drag.startY
+  if (dx * dx + dy * dy >= CLICK_SQ) drag.moved = true
+  // Keep the pre-drag flip orientation while dragging (state.h/v stay as they
+  // were); on release endDrag() recomputes the anchors and settle() flips the
+  // class with a smooth transition instead of reverting instantly.
+  state.left = clamp(drag.origLeft + dx, 0, Math.max(0, drag.vp.w - drag.w))
+  state.top = clamp(drag.origTop + dy, 0, Math.max(0, drag.vp.h - drag.h))
+  express()
+}
+function endDrag(e, clickAllowed) {
+  if (!drag || !drag.active) return
+  drag.active = false
+  pressUp()
+  root.classList.remove('dshwv-dragging')
+  try {
+    if (root.hasPointerCapture && root.hasPointerCapture(e.pointerId)) root.releasePointerCapture(e.pointerId)
+  } catch (err) {}
+  if (clickAllowed && !drag.moved) { refresh(true); return }
+  var dx = e.clientX - drag.startX
+  var dy = e.clientY - drag.startY
+  var left = clamp(drag.origLeft + dx, 0, Math.max(0, drag.vp.w - drag.w))
+  var top = clamp(drag.origTop + dy, 0, Math.max(0, drag.vp.h - drag.h))
+  var centerX = left + drag.w / 2
+  var centerY = top + drag.h / 2
+  if (centerX < drag.vp.w / 4) {
+    state.h = 'left'
+    state.hOff = 0
+  } else if (centerX > drag.vp.w * 3 / 4) {
+    state.h = 'right'
+    state.hOff = 0
+  } else {
+    state.h = null
+    state.hOff = left
+  }
+  if (centerY < drag.vp.h / 4) {
+    state.v = 'top'
+    state.vOff = 0
+  } else if (centerY > drag.vp.h * 3 / 4) {
+    state.v = 'bottom'
+    state.vOff = 0
+  } else {
+    state.v = null
+    state.vOff = top
+  }
+  state.left = left
+  state.top = top
+  settle()
+}
+root.addEventListener('pointerdown', onPointerDown)
+root.addEventListener('pointermove', onPointerMove)
+root.addEventListener('pointerup', function (e) { endDrag(e, true) })
+root.addEventListener('pointercancel', function (e) { endDrag(e, false) })
+window.addEventListener('resize', function () {
+  settle()
+})
+
+var rect0 = root.getBoundingClientRect()
+state.left = rect0.left
+state.top = rect0.top
+express()
+render()
+fetch(SIZE_URL, { cache: 'no-store' })
+  .then(function (r) { return r.json() })
+  .then(function (d) {
+    if (d && typeof d.scale === 'number' && d.scale >= MIN_SCALE - 0.1 && d.scale <= MAX_SCALE + 0.1) {
+      state.scale = d.scale
+      root.style.setProperty('--dshw-scale', String(d.scale))
+      settle()
+    }
+    refresh(false)
+  })
+  .catch(function () { refresh(false) })
+setInterval(function () { refresh(false) }, REFRESH_MS)
+})()`
+
+const name = 'dsh-whale-widget'
+const inject = ['webServer', 'credentials']
+
+function apply(ctx) {
+    let imageBytes = null
+    let balanceCache = null
+    let balanceInFlight = null
+
+    function loadImage() {
+      if (imageBytes) return imageBytes
+      for (const p of IMAGE_CANDIDATES) {
+        try {
+          const bytes = fs.readFileSync(p)
+          if (bytes && bytes.length > 0) {
+            imageBytes = bytes
+            return bytes
+          }
+        } catch (err) {}
+      }
+      throw new Error('whale image not found')
+    }
+
+    async function fetchBalance() {
+      let cred
+      try {
+        cred = await ctx.credentials.resolve('DEEPSEEK_API_KEY')
+      } catch (err) {
+        return { ok: false, code: 'NO_KEY', error: '凭据读取失败: ' + String((err && err.message) || err).slice(0, 160) }
+      }
+      if (!cred) {
+        return { ok: false, code: 'NO_KEY', error: '未配置 DEEPSEEK_API_KEY' }
+      }
+      let lastErr = null
+      for (let attempt = 0; attempt < 2; attempt++) {
+        let res
+        try {
+          res = await fetch(BALANCE_URL, {
+            headers: { Authorization: 'Bearer ' + cred.value },
+            signal: AbortSignal.timeout(20000),
+          })
+        } catch (err) {
+          lastErr = err
+          if (attempt === 0) await new Promise((r) => setTimeout(r, 500))
+          continue
+        }
+        if (!res.ok) {
+          lastErr = new Error('HTTP ' + res.status)
+          if (res.status < 500) break
+          if (attempt === 0) await new Promise((r) => setTimeout(r, 500))
+          continue
+        }
+        let data
+        try {
+          data = await res.json()
+        } catch (err) {
+          return { ok: false, code: 'PARSE', error: '余额接口返回不是合法 JSON' }
+        }
+        const info = data && Array.isArray(data.balance_infos) ? data.balance_infos[0] : null
+        if (!info || info.total_balance === undefined) {
+          return { ok: false, code: 'SHAPE', error: '余额接口返回结构异常' }
+        }
+        return {
+          ok: true,
+          totalBalance: Number(info.total_balance),
+          currency: String(info.currency || 'CNY'),
+          updatedAt: new Date().toISOString(),
+        }
+      }
+      const transient = !(lastErr && /^HTTP 4\d\d/.test(lastErr.message))
+      return {
+        ok: false,
+        code: 'HTTP',
+        transient: transient,
+        error: '余额接口请求失败: ' + String((lastErr && lastErr.message) || lastErr).slice(0, 200),
+      }
+    }
+
+    function getBalance() {
+      const now = Date.now()
+      if (balanceCache && now - balanceCache.at < BALANCE_TTL_MS) {
+        return Promise.resolve(balanceCache.payload)
+      }
+      if (balanceInFlight) return balanceInFlight
+      balanceInFlight = fetchBalance()
+        .then((payload) => {
+          if (payload.ok) {
+            balanceCache = { at: now, payload }
+            return payload
+          }
+          if (payload.transient && balanceCache) {
+            // transient network/API blip: keep serving the last known balance
+            return { ...balanceCache.payload, stale: true, error: payload.error }
+          }
+          if (!payload.transient) console.error('[whale-balance]', payload.code, payload.error)
+          return payload
+        })
+        .catch((err) => ({
+          ok: false,
+          code: 'ERROR',
+          error: '余额服务异常: ' + String((err && err.message) || err).slice(0, 200),
+        }))
+        .finally(() => {
+          balanceInFlight = null
+        })
+      return balanceInFlight
+    }
+
+    function readSizeConfig() {
+      for (const p of SIZE_FILE_CANDIDATES) {
+        try {
+          const parsed = JSON.parse(fs.readFileSync(p, 'utf8'))
+          if (parsed && typeof parsed.scale === 'number') return { scale: parsed.scale }
+        } catch (err) {}
+      }
+      return null
+    }
+
+    function writeSizeConfig(scale) {
+      const body = JSON.stringify({ scale: scale, updatedAt: new Date().toISOString() })
+      for (const p of SIZE_FILE_CANDIDATES) {
+        try {
+          fs.writeFileSync(p, body, 'utf8')
+          return { ok: true, scale: scale }
+        } catch (err) {}
+      }
+      return { ok: false, error: '无法持久化挂件尺寸' }
+    }
+
+    function readBody(req) {
+      return new Promise((resolve, reject) => {
+        const chunks = []
+        let size = 0
+        req.on('data', (c) => {
+          size += c.length
+          if (size > 8192) {
+            reject(new Error('body too large'))
+            req.destroy()
+            return
+          }
+          chunks.push(c)
+        })
+        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')))
+        req.on('error', reject)
+      })
+    }
+
+    const disposers = []
+
+    disposers.push(ctx.webServer.register({
+      kind: 'exact',
+      path: '/dsh-whale/image.png',
+      handler: (req, res) => {
+        try {
+          const bytes = loadImage()
+          res.writeHead(200, {
+            'Content-Type': 'image/png',
+            'Cache-Control': 'public, max-age=3600',
+            'Content-Length': String(bytes.length),
+          })
+          res.end(bytes)
+        } catch (err) {
+          res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' })
+          res.end('whale image unavailable: ' + String((err && err.message) || err))
+        }
+      },
+    }))
+
+    disposers.push(ctx.webServer.register({
+      kind: 'exact',
+      path: '/dsh-whale/balance.json',
+      handler: async (req, res) => {
+        try {
+          const payload = await getBalance()
+          res.writeHead(200, JSON_HEADERS)
+          res.end(JSON.stringify(payload))
+        } catch (err) {
+          res.writeHead(200, JSON_HEADERS)
+          res.end(JSON.stringify({ ok: false, code: 'ERROR', error: String((err && err.message) || err).slice(0, 200) }))
+        }
+      },
+    }))
+
+    disposers.push(ctx.webServer.register({
+      kind: 'exact',
+      path: '/dsh-whale/size.json',
+      handler: async (req, res) => {
+        if (req.method === 'PUT' || req.method === 'POST') {
+          try {
+            const body = await readBody(req)
+            const parsed = JSON.parse(body)
+            const scale = typeof parsed.scale === 'number' ? parsed.scale : null
+            if (scale === null) {
+              res.writeHead(400, JSON_HEADERS)
+              res.end(JSON.stringify({ ok: false, error: 'missing scale' }))
+              return
+            }
+            const result = writeSizeConfig(scale)
+            res.writeHead(result.ok ? 200 : 500, JSON_HEADERS)
+            res.end(JSON.stringify(result))
+          } catch (err) {
+            res.writeHead(400, JSON_HEADERS)
+            res.end(JSON.stringify({ ok: false, error: String((err && err.message) || err) }))
+          }
+          return
+        }
+        res.writeHead(200, JSON_HEADERS)
+        res.end(JSON.stringify(readSizeConfig() || {}))
+      },
+    }))
+
+    disposers.push(ctx.webServer.register({
+      kind: 'exact',
+      path: '/dsh-whale/widget.js',
+      handler: (req, res) => {
+        res.writeHead(200, {
+          'Content-Type': 'application/javascript; charset=utf-8',
+          'Cache-Control': 'no-store',
+        })
+        res.end(WIDGET_JS)
+      },
+    }))
+
+    disposers.push(ctx.webServer.tapIndex((html) => {
+      if (html.indexOf('/dsh-whale/widget.js') !== -1) return html
+      const tag = '<script defer src="/dsh-whale/widget.js"></script>'
+      if (html.indexOf('</body>') !== -1) return html.replace('</body>', tag + '</body>')
+      return html + tag
+    }))
+
+    ctx.effect(() => () => {
+      for (const d of disposers) {
+        try { d() } catch (err) {}
+      }
+    })
+  }
+
+export { name, inject, apply }

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "dsh-whale-widget",
+  "version": "0.1.0",
+  "description": "DSH Web 界面右下角的 DeepSeek 余额小鲸鱼挂件",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "balance",
+    "widget"
+  ],
+  "type": "module",
+  "main": "lib/index.js",
+  "files": [
+    "lib",
+    "assets",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "license": "MIT"
+}