dsh-deepseek-balance-widget 1.0.0

package/lib/index.js

@@ -0,0 +1,385 @@
+import { launchEnvironmentOf } from "@deepseek-ai/dsh-launch-environment";
+
+/** Plugin id; must match the cordis.patch.yml insert id. */
+const name = "deepseek-balance-widget";
+
+/** Services required before this plugin can mount its route. */
+const inject = ["webServer", "credentials"];
+
+/** DeepSeek official balance endpoint (OpenAI-compatible auth). */
+const BALANCE_URL = "https://api.deepseek.com/user/balance";
+
+/** DeepSeek Platform private usage endpoints (require a platform userToken). */
+const PLATFORM = "https://platform.deepseek.com";
+const USAGE_AMOUNT_URL = `${PLATFORM}/api/v0/usage/amount?month=__MONTH__&year=__YEAR__`;
+const USAGE_COST_URL = `${PLATFORM}/api/v0/usage/cost?month=__MONTH__&year=__YEAR__`;
+const PLATFORM_HEADERS = {
+  "x-app-version": "1.0.0",
+  Accept: "*/*",
+  Referer: "https://platform.deepseek.com/usage",
+  Origin: "https://platform.deepseek.com",
+  "User-Agent":
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.0.0 Safari/537.36"
+};
+
+/**
+ * Query the DeepSeek balance API for one key.
+ * @param {string} apiKey - the resolved DeepSeek API key.
+ * @returns the normalized envelope ({ ok, status, data }).
+ */
+async function queryBalance(apiKey) {
+  let response;
+  try {
+    response = await fetch(BALANCE_URL, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        Accept: "application/json"
+      }
+    });
+  } catch (error) {
+    return { ok: false, status: 0, error: `network: ${String(error?.message ?? error)}` };
+  }
+  const text = await response.text();
+  let data = null;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    data = { raw: text.slice(0, 512) };
+  }
+  return { ok: response.ok, status: response.status, data };
+}
+
+/**
+ * Resolve the DeepSeek key from the credential seam or launch environment.
+ * The credential seam reads THIS machine's own `$DSH_HOME/.credentials.yaml`
+ * (or the ambient environment), so every user queries with their own key and
+ * sees their own balance. Nothing is ever hardcoded in this plugin.
+ * @param {import("@deepseek-ai/cordis").Context} ctx - plugin context.
+ * @returns {Promise<string|undefined>} the key, or undefined when unset.
+ */
+async function resolveKey(ctx) {
+  if (ctx.credentials !== void 0) {
+    const hit = await ctx.credentials.resolve("DEEPSEEK_API_KEY");
+    if (hit !== void 0 && typeof hit.value === "string" && hit.value.length > 0) return hit.value;
+  }
+  const ambient = launchEnvironmentOf(ctx).get("DEEPSEEK_API_KEY");
+  if (ambient !== void 0 && typeof ambient.value === "string" && ambient.value.length > 0) return ambient.value;
+  return void 0;
+}
+
+/**
+ * Resolve the DeepSeek Platform session token (userToken) from the
+ * credential seam or launch environment. Required for the private
+ * usage/cost dashboard endpoints; an API key cannot authenticate them.
+ * @param {import("@deepseek-ai/cordis").Context} ctx - plugin context.
+ * @returns {Promise<string|undefined>} the token, or undefined when unset.
+ */
+async function resolvePlatformToken(ctx) {
+  if (ctx.credentials !== void 0) {
+    const hit = await ctx.credentials.resolve("DEEPSEEK_PLATFORM_TOKEN");
+    if (hit !== void 0 && typeof hit.value === "string" && hit.value.length > 0) return hit.value;
+  }
+  const ambient = launchEnvironmentOf(ctx).get("DEEPSEEK_PLATFORM_TOKEN");
+  if (ambient !== void 0 && typeof ambient.value === "string" && ambient.value.length > 0) return ambient.value;
+  return void 0;
+}
+
+/** @returns {Promise<{code:number,msg?:string,data?:any}|{error:string}>} a JSON-ish body. */
+async function fetchJson(url, token) {
+  let response;
+  try {
+    response = await fetch(url, {
+      method: "GET",
+      headers: { Authorization: `Bearer ${token}`, ...PLATFORM_HEADERS }
+    });
+  } catch (error) {
+    return { error: `network: ${String(error?.message ?? error)}` };
+  }
+  const text = await response.text();
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { error: `bad json (HTTP ${response.status})` };
+  }
+}
+
+/** Earliest year to scan for all-time spend (DeepSeek platform launched 2024). */
+const CUMULATIVE_START_YEAR = 2024;
+
+/** Per-month cost map ("YYYY-MM" -> CNY). Filled once on first request. */
+let monthlyCostMap = null;
+/** In-flight initial scan guard. */
+let monthlyInitPromise = null;
+
+/** Fetch one month's total cost from the cost endpoint. */
+async function monthCostOf(token, month, year) {
+  const url = USAGE_COST_URL.replace("__MONTH__", String(month)).replace("__YEAR__", String(year));
+  const resp = await fetchJson(url, token);
+  if (resp.error !== void 0) throw new Error(resp.error);
+  if (resp.code !== void 0 && resp.code !== 0) throw new Error(`platform ${resp.code}: ${resp.msg ?? "unknown"}`);
+  const raw = resp?.data?.biz_data;
+  const data = Array.isArray(raw) ? raw[0] : raw;
+  let total = 0;
+  if (data && Array.isArray(data.total) && data.total.length > 0) {
+    for (const modelEntry of data.total) {
+      for (const entry of modelEntry.usage ?? []) total += Number.parseFloat(entry.amount) || 0;
+    }
+  }
+  return Math.round(total * 100) / 100;
+}
+
+/** One-time full scan 2024-01..current month; fills monthlyCostMap. */
+async function ensureMonthlyMap(token) {
+  if (monthlyCostMap !== null) return;
+  if (monthlyInitPromise === null) {
+    monthlyInitPromise = (async () => {
+      const map = {};
+      const now = new Date();
+      for (let y = CUMULATIVE_START_YEAR; y <= now.getFullYear(); y++) {
+        const mEnd = y === now.getFullYear() ? now.getMonth() + 1 : 12;
+        for (let m = 1; m <= mEnd; m++) {
+          map[`${y}-${String(m).padStart(2, "0")}`] = await monthCostOf(token, m, y);
+        }
+      }
+      monthlyCostMap = map;
+    })();
+  }
+  try {
+    await monthlyInitPromise;
+  } finally {
+    monthlyInitPromise = null;
+  }
+}
+
+/**
+ * Sum the month map; upserts the running month's fresh cost when given.
+ * Past months are billing-final, so only the current month needs updating —
+ * this makes the cumulative figure effectively real-time at zero extra cost.
+ * @returns {number|null} rounded CNY total, or null before the map is ready.
+ */
+function cumulativeFromMap(key, value) {
+  if (monthlyCostMap === null) return null;
+  if (key !== void 0) monthlyCostMap[key] = value;
+  let total = 0;
+  for (const k of Object.keys(monthlyCostMap)) total += monthlyCostMap[k];
+  return Math.round(total * 100) / 100;
+}
+
+/**
+ * Fetch and normalize the current-month usage from the platform dashboard.
+ * @param {string} token - platform userToken.
+ * @param {number} month - 1..12.
+ * @param {number} year - e.g. 2026.
+ * @returns normalized envelope ({ ok, status, data }).
+ */
+async function queryPlatformUsage(token, month, year) {
+  const [amount, cost] = await Promise.all([
+    fetchJson(USAGE_AMOUNT_URL.replace("__MONTH__", String(month)).replace("__YEAR__", String(year)), token),
+    fetchJson(USAGE_COST_URL.replace("__MONTH__", String(month)).replace("__YEAR__", String(year)), token)
+  ]);
+
+  const failed = [amount, cost].find((r) => r.error !== void 0);
+  if (failed !== void 0) return { ok: false, status: 0, error: failed.error };
+
+  // Platform private endpoints answer { code, msg, data } — 40002/40003 = bad/expired session.
+  for (const r of [amount, cost]) {
+    if (r.code !== void 0 && r.code !== 0) {
+      return { ok: false, status: 401, error: `platform ${r.code}: ${r.msg ?? "unknown"}` };
+    }
+  }
+
+  const bizData = (resp) => {
+    const raw = resp?.data?.biz_data;
+    return Array.isArray(raw) ? raw[0] : raw;
+  };
+  const amountData = bizData(amount);
+  const costData = bizData(cost);
+  if (!amountData || !Array.isArray(amountData.days)) {
+    return { ok: false, status: 200, error: "amount response missing days" };
+  }
+
+  const isToken = (t) => typeof t === "string" && /TOKEN/i.test(t);
+  const isRequest = (t) => typeof t === "string" && /REQUEST|REQ_|_REQ|COUNT|CALLS?/i.test(t);
+
+  // Prefer biz_data.total (month aggregate); fall back to summing the days.
+  const usageEntries = () => {
+    const entries = [];
+    const collect = (modelEntries) => {
+      for (const modelEntry of modelEntries ?? []) {
+        for (const entry of modelEntry.usage ?? []) entries.push(entry);
+      }
+    };
+    if (Array.isArray(amountData.total) && amountData.total.length > 0) {
+      collect(amountData.total);
+    } else {
+      for (const day of amountData.days ?? []) collect(day.data);
+    }
+    return entries;
+  };
+
+  let tokens = 0;
+  let requests = 0;
+  for (const entry of usageEntries()) {
+    const v = Number.parseFloat(entry.amount) || 0;
+    if (isToken(entry.type)) tokens += Math.round(v);
+    else if (isRequest(entry.type)) requests += Math.round(v);
+  }
+
+  let costValue = 0;
+  const sumUsage = (modelEntries) => {
+    for (const modelEntry of modelEntries ?? []) {
+      for (const entry of modelEntry.usage ?? []) costValue += Number.parseFloat(entry.amount) || 0;
+    }
+  };
+  if (costData) {
+    // biz_data.total is the month aggregate; fall back to summing the days.
+    if (Array.isArray(costData.total) && costData.total.length > 0) {
+      sumUsage(costData.total);
+    } else {
+      for (const day of costData.days ?? []) sumUsage(day.data);
+    }
+  }
+  costValue = Math.round(costValue * 100) / 100;
+
+  // 今日数据：平台实时接口（by_api_key），按 [今日 0 点 GMT+8, 明日 0 点) 的小时桶求和。
+  // （月度接口的逐日明细滞后一天，今天的数据要查实时端点才能拿到。）
+  const TZ_SHANGHAI = 8 * 3600; // 秒
+  const shMidnightSec = Math.floor((Date.now() + TZ_SHANGHAI * 1000) / 86400000) * 86400 - TZ_SHANGHAI;
+  const todayStart = shMidnightSec;
+  const todayEnd = todayStart + 86400;
+  const todayKey = (ep) => `${PLATFORM}/api/v0/usage/by_api_key/${ep}?start=${todayStart}&end=${todayEnd}&tz=${TZ_SHANGHAI}`;
+  let todayCost = 0;
+  let todayTokens = 0;
+  let todayRequests = 0;
+  const [todayAmount, todayCostResp] = await Promise.all([
+    fetchJson(todayKey("amount"), token),
+    fetchJson(todayKey("cost"), token)
+  ]);
+  const tA = todayAmount?.data?.biz_data;
+  if (tA && Array.isArray(tA.series)) {
+    for (const series of tA.series) {
+      for (const bucket of series.buckets ?? []) {
+        const u = bucket.usage ?? {};
+        for (const k of Object.keys(u)) {
+          const v = Number.parseFloat(u[k]) || 0;
+          if (isToken(k)) todayTokens += Math.round(v);
+          else if (isRequest(k)) todayRequests += Math.round(v);
+        }
+      }
+    }
+  }
+  const tC = todayCostResp?.data?.biz_data;
+  if (tC) {
+    const seriesList = Array.isArray(tC.series)
+      ? tC.series
+      : Array.isArray(tC.data)
+        ? tC.data.flatMap((d) => d.series ?? [])
+        : [];
+    for (const series of seriesList) {
+      for (const bucket of series.buckets ?? []) todayCost += Number.parseFloat(bucket.cost) || 0;
+    }
+  }
+  todayCost = Math.round(todayCost * 100) / 100;
+
+  // 累计消费 = 全月份成本求和；当月数值用本次实时结果更新，过去月份账目已定。
+  const monthKey = `${year}-${String(month).padStart(2, "0")}`;
+  const cumulativeValue = cumulativeFromMap(monthKey, costValue);
+
+  return {
+    ok: true,
+    status: 200,
+    data: {
+      month,
+      year,
+      period: "本月",
+      apiKey: "API Key 全部",
+      totalSpend: `¥${costValue.toFixed(2)}`,
+      cumulativeSpend: cumulativeValue === null ? null : `¥${cumulativeValue.toFixed(2)}`,
+      todaySpend: todayCost.toFixed(2),
+      todayTokens: String(todayTokens).replace(/\B(?=(\d{3})+(?!\d))/g, ","),
+      todayRequests: String(todayRequests).replace(/\B(?=(\d{3})+(?!\d))/g, ","),
+      requestCount: String(requests).replace(/\B(?=(\d{3})+(?!\d))/g, ","),
+      tokens: String(tokens).replace(/\B(?=(\d{3})+(?!\d))/g, ",")
+    }
+  };
+}
+
+/**
+ * cordis plugin apply: register the balance route on the shared webserver.
+ * @param {import("@deepseek-ai/cordis").Context} ctx - plugin context.
+ */
+function apply(ctx) {
+  ctx.effect(() => {
+    const dispose = ctx.webServer.register({
+      kind: "prefix",
+      path: "/deepseek-balance",
+      handler: async (req, res) => {
+        const url = new URL(req.url ?? "/", "http://x");
+        if (req.method !== "GET" || url.pathname !== "/deepseek-balance") {
+          res.writeHead(404, { "content-type": "application/json; charset=utf-8" });
+          res.end(JSON.stringify({ ok: false, error: "not found" }));
+          return;
+        }
+        try {
+          const key = await resolveKey(ctx);
+          if (key === void 0) {
+            res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+            res.end(JSON.stringify({ ok: false, error: "DEEPSEEK_API_KEY 未配置（请在 ~/.dsh/.credentials.yaml 设置）" }));
+            return;
+          }
+          const result = await queryBalance(key);
+          // 入口不展示货币符号：把币种字段清空，任何版本的前端都不会拼出 ¥。
+          if (result.ok && Array.isArray(result.data?.balance_infos)) {
+            for (const info of result.data.balance_infos) info.currency = "";
+          }
+          res.writeHead(result.ok ? 200 : 502, { "content-type": "application/json; charset=utf-8" });
+          res.end(JSON.stringify(result));
+        } catch (error) {
+          res.writeHead(500, { "content-type": "application/json; charset=utf-8" });
+          res.end(JSON.stringify({ ok: false, error: String(error?.message ?? error) }));
+        }
+      }
+    });
+    return dispose;
+  }, "deepseek-balance-widget: route");
+
+  ctx.effect(() => {
+    const dispose = ctx.webServer.register({
+      kind: "prefix",
+      path: "/deepseek-usage",
+      handler: async (req, res) => {
+        const url = new URL(req.url ?? "/", "http://x");
+        if (req.method !== "GET" || url.pathname !== "/deepseek-usage") {
+          res.writeHead(404, { "content-type": "application/json; charset=utf-8" });
+          res.end(JSON.stringify({ ok: false, error: "not found" }));
+          return;
+        }
+        try {
+          const token = await resolvePlatformToken(ctx);
+          if (token === void 0) {
+            res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+            res.end(JSON.stringify({ ok: false, error: "DEEPSEEK_PLATFORM_TOKEN 未配置（请登录 platform.deepseek.com 后设置，用于实时用量统计）" }));
+            return;
+          }
+          const now = new Date();
+          // 首次请求做一次全月份扫描（之后只在内存里更新当月，零额外请求）。
+          try {
+            await ensureMonthlyMap(token);
+          } catch {
+            // 扫描失败时本轮累计值保持 null，客户端回退到快照；下轮重试。
+          }
+          const result = await queryPlatformUsage(token, now.getMonth() + 1, now.getFullYear());
+          res.writeHead(result.ok ? 200 : 502, { "content-type": "application/json; charset=utf-8" });
+          res.end(JSON.stringify(result));
+        } catch (error) {
+          res.writeHead(500, { "content-type": "application/json; charset=utf-8" });
+          res.end(JSON.stringify({ ok: false, error: String(error?.message ?? error) }));
+        }
+      }
+    });
+    return dispose;
+  }, "deepseek-balance-widget: usage route");
+}
+
+export { name, inject, apply };

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "dsh-deepseek-balance-widget",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "DeepSeek API balance widget for the dsh web sidebar: a live, auto-refreshing balance pill (balance / today spend / today tokens) with a detail popover (cumulative spend, monthly usage, request count). Every user sees only their own balance — keys are resolved per-machine from the local credential seam, never hardcoded.",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek",
+    "deepseek-harness",
+    "balance",
+    "usage",
+    "sidebar",
+    "widget"
+  ],
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "skills",
+    "README.md",
+    "README_EN.md",
+    "LICENSE",
+    "scripts"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/crazy-L118/dsh-deepseek-balance-widget"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime"
+      ],
+      "platform": "web"
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/dsh-credentials": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-launch-environment": "^0.0.1-rc.3"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    }
+  }
+}

package/scripts/install.ps1

@@ -0,0 +1,127 @@
+#Requires -Version 5.1
+<#
+.SYNOPSIS
+  Install dsh-deepseek-balance-widget into the local dsh web profile.
+
+.DESCRIPTION
+  By default this copies the plugin source (this repo) to
+  $DSH_HOME/custom-plugins/dsh-deepseek-balance-widget and installs it via
+  `dsh plugin --profile web add "file:..."`.
+
+  With -FromNpm it skips the copy and installs the published package straight
+  from the npm registry (`dsh plugin --profile web add dsh-deepseek-balance-widget`).
+
+  Either way it also registers the plugin in dsh.profile.bundles inside the
+  profile package.json.
+
+  Usage (Windows PowerShell):
+    powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1          # from local repo
+    powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1 -FromNpm # from npm registry
+#>
+[CmdletBinding()]
+param(
+  [switch]$FromNpm
+)
+$ErrorActionPreference = "Stop"
+
+$pluginName = "dsh-deepseek-balance-widget"
+
+$dshHome = if ($env:DSH_HOME) { $env:DSH_HOME } else { Join-Path $HOME ".dsh" }
+$customPluginsDir = Join-Path $dshHome "custom-plugins"
+$pluginDir = Join-Path $customPluginsDir $pluginName
+$profileDir = Join-Path $dshHome "profiles" "web"
+$profilePkg = Join-Path $profileDir "package.json"
+
+# 0. dsh on PATH?
+if (-not (Get-Command dsh -ErrorAction SilentlyContinue)) {
+  Write-Host "[error] 'dsh' not found on PATH. Install DeepSeek Harness first." -ForegroundColor Red
+  exit 1
+}
+
+# 1. web profile initialized?
+if (-not (Test-Path $profilePkg)) {
+  Write-Host "[error] web profile not found: $profilePkg" -ForegroundColor Red
+  Write-Host "        Run 'dsh web' (or 'dsh --profile web --help') once to initialize the profile, then re-run this script."
+  exit 1
+}
+
+# 2. copy plugin source (local mode only)
+if ($FromNpm) {
+  Write-Host "==> Installing from npm registry (no local copy)"
+} else {
+  $source = (Resolve-Path (Join-Path $PSScriptRoot "..")).Path
+  Write-Host "==> Copying plugin to $pluginDir"
+  New-Item -ItemType Directory -Force -Path $customPluginsDir | Out-Null
+  if (Test-Path $pluginDir) { Remove-Item -Recurse -Force $pluginDir }
+  Copy-Item -Recurse -Force -Path $source -Destination $pluginDir
+  Get-ChildItem -Force $pluginDir -ErrorAction SilentlyContinue |
+    Where-Object { $_.Name -in @("node_modules", ".git") } |
+    Remove-Item -Recurse -Force -ErrorAction SilentlyContinue
+}
+
+# 3. install via dsh plugin (pnpm add)
+if ($FromNpm) {
+  Write-Host "==> Installing into web profile: dsh plugin --profile web add $pluginName"
+} else {
+  $fileSpec = "file:" + ($pluginDir -replace "\\", "/")
+  Write-Host "==> Installing into web profile: dsh plugin --profile web add $fileSpec"
+}
+Push-Location $profileDir
+try {
+  if ($FromNpm) {
+    & dsh plugin --profile web add $pluginName
+  } else {
+    & dsh plugin --profile web add ("file:" + ($pluginDir -replace "\\", "/"))
+  }
+  if ($LASTEXITCODE -ne 0) { throw "dsh plugin add failed (exit code $LASTEXITCODE)" }
+} finally {
+  Pop-Location
+}
+
+# 4. register in dsh.profile.bundles (idempotent safety net).
+#    Modern dsh auto-registers any installed dependency that declares
+#    dsh.bundle after `dsh plugin add`, so this usually reports
+#    "Already registered". It only matters for older dsh versions or when
+#    the package was installed with raw pnpm/npm instead of `dsh plugin`.
+Write-Host "==> Registering in dsh.profile.bundles"
+$raw = [System.IO.File]::ReadAllText($profilePkg)
+$pattern = '"bundles"\s*:\s*\[[^\]]*?\]'
+$m = [regex]::Match($raw, $pattern)
+if (-not $m.Success) {
+  throw "Could not locate the dsh.profile.bundles array in $profilePkg. Please add `"$pluginName`" to it manually."
+}
+$arrayText = $m.Value
+if ($arrayText -match '"dsh-deepseek-balance-widget"') {
+  Write-Host "    Already registered, skipping."
+} else {
+  # Insert before the closing bracket; make sure there is a separating comma.
+  $newArrayText = $arrayText.Substring(0, $arrayText.Length - 1).TrimEnd()
+  if (-not $newArrayText.EndsWith(",")) { $newArrayText += "," }
+  $newArrayText += "`n      `"$pluginName`"]"
+  $raw = $raw.Substring(0, $m.Index) + $newArrayText + $raw.Substring($m.Index + $m.Length)
+  $utf8NoBom = New-Object System.Text.UTF8Encoding($false)
+  [System.IO.File]::WriteAllText($profilePkg, $raw, $utf8NoBom)
+  Write-Host "    + Added $pluginName to bundles"
+}
+
+# 5. install the AI skill (idempotent): local copy first, npm-installed fallback
+Write-Host "==> Installing AI skill"
+$skillSource = Join-Path $pluginDir "skills\dsh-deepseek-balance-widget\SKILL.md"
+if (-not (Test-Path $skillSource)) {
+  $skillSource = Join-Path $profileDir ("node_modules\" + $pluginName + "\skills\dsh-deepseek-balance-widget\SKILL.md")
+}
+if (Test-Path $skillSource) {
+  $skillDir = Join-Path $dshHome "skills\dsh-deepseek-balance-widget"
+  New-Item -ItemType Directory -Force -Path $skillDir | Out-Null
+  Copy-Item -Force $skillSource (Join-Path $skillDir "SKILL.md")
+  Write-Host "    + Skill ready at $skillDir (AI picks it up in new sessions)"
+} else {
+  Write-Host "    (no skill source found, skipping)"
+}
+
+Write-Host ""
+Write-Host "Installation complete. Next steps:"
+Write-Host "  1. Edit $dshHome\.credentials.yaml and add (if not already set):"
+Write-Host "       DEEPSEEK_API_KEY: sk-xxxx            # required - balance"
+Write-Host "       DEEPSEEK_PLATFORM_TOKEN: xxxx        # optional - live usage (userToken from platform.deepseek.com)"
+Write-Host "  2. Restart dsh web. The balance widget appears in the sidebar."

package/scripts/install.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# Install dsh-deepseek-balance-widget into the local dsh web profile.
+#
+# By default this copies the plugin source (this repo) to
+# $DSH_HOME/custom-plugins/dsh-deepseek-balance-widget and installs it via
+# `dsh plugin --profile web add "file:..."`.
+#
+# With --from-npm it skips the copy and installs the published package
+# straight from the npm registry.
+#
+# Either way it also registers the plugin in dsh.profile.bundles inside the
+# profile package.json.
+#
+# Usage:
+#   bash scripts/install.sh             # from local repo
+#   bash scripts/install.sh --from-npm  # from npm registry
+set -euo pipefail
+
+FROM_NPM=0
+if [ "${1:-}" = "--from-npm" ]; then FROM_NPM=1; fi
+
+PLUGIN_NAME="dsh-deepseek-balance-widget"
+DSH_HOME="${DSH_HOME:-$HOME/.dsh}"
+CUSTOM_PLUGINS="$DSH_HOME/custom-plugins"
+PLUGIN_DIR="$CUSTOM_PLUGINS/$PLUGIN_NAME"
+PROFILE_DIR="$DSH_HOME/profiles/web"
+PROFILE_PKG="$PROFILE_DIR/package.json"
+
+if ! command -v dsh >/dev/null 2>&1; then
+  echo "[error] 'dsh' not found on PATH. Install DeepSeek Harness first." >&2
+  exit 1
+fi
+
+if [ ! -f "$PROFILE_PKG" ]; then
+  echo "[error] web profile not found: $PROFILE_PKG" >&2
+  echo "        Run 'dsh web' (or 'dsh --profile web --help') once to initialize the profile, then re-run this script." >&2
+  exit 1
+fi
+
+if [ "$FROM_NPM" = "1" ]; then
+  echo "==> Installing from npm registry (no local copy)"
+else
+  SOURCE="$(cd "$(dirname "$0")/.." && pwd)"
+  echo "==> Copying plugin to $PLUGIN_DIR"
+  mkdir -p "$CUSTOM_PLUGINS"
+  rm -rf "$PLUGIN_DIR"
+  cp -R "$SOURCE" "$PLUGIN_DIR"
+  rm -rf "$PLUGIN_DIR/node_modules" "$PLUGIN_DIR/.git"
+fi
+
+echo "==> Installing into web profile"
+if [ "$FROM_NPM" = "1" ]; then
+  ( cd "$PROFILE_DIR" && dsh plugin --profile web add "$PLUGIN_NAME" )
+else
+  ( cd "$PROFILE_DIR" && dsh plugin --profile web add "file:$PLUGIN_DIR" )
+fi
+
+# Idempotent safety net: modern dsh auto-registers any installed dependency
+# that declares dsh.bundle after `dsh plugin add`, so this usually prints
+# "Already registered". It only matters for older dsh versions or when the
+# package was installed with raw pnpm/npm instead of `dsh plugin`.
+echo "==> Registering in dsh.profile.bundles"
+node - "$PROFILE_PKG" "$PLUGIN_NAME" <<'NODEEOF'
+const fs = require("fs");
+const pkgPath = process.argv[2];
+const pluginName = process.argv[3];
+const data = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+const profile = data.dsh && data.dsh.profile;
+const bundles = profile && Array.isArray(profile.bundles) ? profile.bundles : null;
+if (bundles === null) {
+  console.error("[error] dsh.profile.bundles not found in " + pkgPath +
+    " - add \"" + pluginName + "\" to it manually.");
+  process.exit(1);
+}
+if (bundles.includes(pluginName)) {
+  console.log("    Already registered, skipping.");
+} else {
+  bundles.push(pluginName);
+  fs.writeFileSync(pkgPath, JSON.stringify(data, null, 2) + "\n", "utf8");
+  console.log("    + Added " + pluginName + " to bundles");
+}
+NODEEOF
+
+# Install the AI skill (idempotent): local copy first, npm-installed fallback
+echo "==> Installing AI skill"
+SKILL_SRC="$PLUGIN_DIR/skills/dsh-deepseek-balance-widget/SKILL.md"
+if [ ! -f "$SKILL_SRC" ]; then
+  SKILL_SRC="$PROFILE_DIR/node_modules/$PLUGIN_NAME/skills/dsh-deepseek-balance-widget/SKILL.md"
+fi
+if [ -f "$SKILL_SRC" ]; then
+  mkdir -p "$DSH_HOME/skills/dsh-deepseek-balance-widget"
+  cp -f "$SKILL_SRC" "$DSH_HOME/skills/dsh-deepseek-balance-widget/SKILL.md"
+  echo "    + Skill ready at $DSH_HOME/skills/dsh-deepseek-balance-widget (AI picks it up in new sessions)"
+else
+  echo "    (no skill source found, skipping)"
+fi
+
+echo ""
+echo "Installation complete. Next steps:"
+echo "  1. Edit $DSH_HOME/.credentials.yaml and add (if not already set):"
+echo "       DEEPSEEK_API_KEY: sk-xxxx            # required - balance"
+echo "       DEEPSEEK_PLATFORM_TOKEN: xxxx        # optional - live usage (userToken from platform.deepseek.com)"
+echo "  2. Restart dsh web. The balance widget appears in the sidebar."