dsh-deepseek-balance-widget 2.3.0 → 2.3.2

package/AI_BALANCE_SETUP_GUIDE.md

@@ -0,0 +1,151 @@
+# AI 余额插件 · 智能体配置引导教程
+
+> 本文件供**智能体（AI 助手）**在聊天中读取。当用户说"帮我配置 MiMo / DeepSeek 余额"时，智能体应先完整读完本文件，再按对应章节一步步引导用户，不要跳过任何步骤。
+
+---
+
+## 0. 智能体的职责与边界
+
+你是这个 dsh 插件的"配置向导"。你的任务：
+
+1. 读完整份教程，理解两平台的差异（MiMo 用 Cookie，DeepSeek 用 API Key）。
+2. 引导用户用浏览器开发者工具抓取请求（cURL / 请求头）。
+3. 从用户粘贴的内容里**精准提取**鉴权凭证。
+4. 把凭证**写入本机** `~/.dsh/ai-balances.json`（Windows 实际路径：`C:\Users\<用户名>\.dsh\ai-balances.json`）。
+5. 验证余额能读到。
+6. 提醒用户**彻底重启 dsh** 让凭证生效。
+
+**边界（务必遵守）：**
+- 你**不能**替用户登录任何平台，也**不能**跨域抓取 Cookie（浏览器同源策略 + 隐私限制）。
+- 所有数据只写在本机 `~/.dsh/ai-balances.json`，**不上传**任何外部服务器。
+- 写文件前必须先读取现状，用精确的方式修改，**绝不能删除或破坏其他已有条目**（尤其 `deepseek` 这条）。
+
+---
+
+## 1. 通用步骤：如何抓取浏览器请求（两种方法）
+
+无论哪个平台，第一步都是让用户从浏览器里把"带鉴权信息的请求"复制给你。
+
+### 方法 A：Copy as cURL（推荐，信息最全）
+1. 在浏览器打开对应平台的余额/控制台页面并**保持登录**。
+2. 按 `F12` 打开开发者工具 → 切到 **Network（网络）** 标签。
+3. 按 `F5` 刷新页面，让请求重新发出。
+4. 在过滤框输入关键词（见各平台章节），找到目标请求。
+5. 右键该请求 → **Copy（复制）** → **Copy as cURL (bash)**。
+6. 把复制出来的那一长串（以 `curl 'https://...` 开头）直接粘贴到对话里发给我。
+
+### 方法 B：只复制请求头（轻量）
+若用户不愿贴整段 cURL，可在 Network 里点开目标请求 → 切到 **Headers（标头）** → 找到 `Cookie:`（MiMo）或 `Authorization:`（DeepSeek）那一行 → 只复制该请求头的完整内容。
+
+> 提醒用户：cURL / 请求头里含有登录凭证，**只发给我（本机 AI），不要发到任何公开/外部聊天**。
+
+---
+
+## 2. MiMo（小米）配置
+
+- **平台网址**：`https://platform.xiaomimimo.com/#/console/balance`
+- **鉴权方式**：**登录 Cookie**（MiMo 余额接口只对登录 Cookie 开放，API Key 查不到余额）。
+- **抓取关键词**：在 Network 过滤框输入 `api` 或 `balance`，找域名是 `platform.xiaomimimo.com` / `api.xiaomimimo.com` 的请求。
+
+### 提取 Cookie
+- 若用户贴的是 cURL：找其中 `-H 'Cookie: ...'` 或 `--cookie '...'` 部分，提取 `Cookie:` 之后、`'` 之前的完整内容。
+- 若用户贴的是请求头：直接取其 `Cookie:` 整行内容。
+- Cookie 是一长串 `key=value; key2=value2; ...`，原样保留，不要截断。
+
+### 写入格式
+目标文件：`~/.dsh/ai-balances.json`（JSON 数组）。找到或新增一条 MiMo 记录：
+
+```json
+{
+  "id": "mimo",
+  "label": "MiMo（小米）",
+  "kind": "mimo",
+  "apiKey": "",
+  "cookie": "<这里放提取到的完整 Cookie 字符串>",
+  "enabled": true
+}
+```
+
+> 注意 `id` 用 `mimo`，插件据此识别。若数组里已有 `id:"mimo"` 的条目，只更新它的 `cookie` 字段，保留其他字段。
+
+### 备注
+- MiMo 的 Cookie 约 **1–7 天**过期，过期后余额会显示 401。届时需要重新走一遍本流程更新 Cookie。
+- 若提取后余额仍报"失败"，把插件弹窗里显示的原始响应片段发给我，我再精确适配字段。
+- MiMo 余额接口常见返回字段（插件弹窗里会显示中文标签）：
+  - `giftBalance` → 赠送余额
+  - `cashBalance` → 现金余额
+  - `frozenBalance` → 冻结余额
+  - `overdraftLimit` → 透支额度
+  - `remainingOverdraftLimit` → 剩余透支额度
+  - `code` / `message` → 状态码 / 消息
+  - 若还有未识别的字段，会保持原样显示。
+
+---
+
+## 3. DeepSeek 配置
+
+- **平台网址**：`https://platform.deepseek.com/`（控制台）
+- **鉴权方式**：**API Key**（即 `Authorization: Bearer sk-...` 凭证）。DeepSeek 余额接口 `https://api.deepseek.com/user/balance` 用 Bearer 鉴权。
+- **抓取关键词**：在 Network 过滤框输入 `user` 或 `balance`，找域名是 `api.deepseek.com` / `platform.deepseek.com` 的请求。
+
+### 提取 API Key
+- 若用户贴的是 cURL：找其中 `-H 'Authorization: Bearer sk-...'` 部分，提取 `sk-` 开头的完整密钥。
+- 若用户贴的是请求头：直接取 `Authorization: Bearer sk-...` 中 `sk-` 开头部分。
+- 完整密钥形如 `sk-xxxxxxxxxxxxxxxx`，**一字不差**原样保留。
+
+### 写入格式
+目标文件：`~/.dsh/ai-balances.json`（JSON 数组）。找到或新增一条 DeepSeek 记录：
+
+```json
+{
+  "id": "deepseek",
+  "label": "DeepSeek",
+  "kind": "deepseek",
+  "apiKey": "<这里放提取到的 sk-... 密钥>",
+  "enabled": true
+}
+```
+
+> `id:"deepseek"` 是固定项，插件默认就有，且**不能被移除**。若已存在，只更新 `apiKey` 字段。
+> 如果用户机器上 DeepSeek 的密钥已经配置在 dsh 的 `.credentials.yaml`（`DEEPSEEK_API_KEY`）里，可把 `apiKey` 写成字符串 `"__credentials__"`，插件运行时会自动从环境变量解析，无需把明文写进本文件。
+
+---
+
+## 4. 写入目标文件的操作要点
+
+- 路径（Windows）：`C:\Users\<用户名>\.dsh\ai-balances.json`
+- 它是一个 **JSON 数组**，形如 `[ {深度条目}, {其他条目} ]`。
+- 修改步骤：
+  1. 用 Read 读取该文件，确认当前内容（若文件不存在，说明用户还没初始化，先创建 `[]` 再追加）。
+  2. 用 Edit / Write 精确修改对应 `id` 的条目，**不要改动其他条目**。
+  3. 写回后再次 Read 确认 JSON 合法、结构完整。
+- 不要写入任何多余字段；`cookie` 和 `apiKey` 只填当前平台需要的那个，另一个留空字符串或省略均可。
+
+---
+
+## 5. 验证
+
+写入后，任选一种方式验证余额能读到：
+
+- **方式一（插件侧）**：让用户彻底重启 dsh，打开插件弹窗，看对应平台是否显示余额数字。
+- **方式二（直接请求）**：
+  - DeepSeek：`curl -s https://api.deepseek.com/user/balance -H "Authorization: Bearer <sk-密钥>"`，看返回 `balance_infos`。
+  - MiMo：`curl -s https://platform.xiaomimimo.com/api/v1/balance -H "Cookie: <Cookie>"`，看返回余额字段。
+- 若返回 401 / 404 / 失败：说明凭证过期或提取有误，引导用户重抓。
+
+---
+
+## 6. 收尾提醒
+
+配置写入成功后，务必告诉用户：
+
+> **必须彻底重启 dsh**（命令行 `Ctrl+C` 停掉 `dsh web` 或关闭桌面端窗口，再重新启动），浏览器刷新不会重新加载插件凭证。重启后打开插件弹窗即可看到余额。
+
+---
+
+## 附：常见坑
+
+- **MiMo 用 API Key 查不到余额**：MiMo 余额接口只对登录 Cookie 开放，必须用 Cookie，不能用 API Key。
+- **Cookie 过期**：MiMo 登录态会过期，余额变 401 时重新走第 2 章。
+- **别删 deepseek 条目**：它是插件默认项，删了会导致 DeepSeek 余额消失。
+- **JSON 写坏**：写文件前后都要 Read 校验，确保数组闭合、逗号正确。

package/README.md

@@ -20,11 +20,13 @@
 需要：已安装 dsh（可用 `dsh web`）。
 
 ```bash
-dsh plugin --profile web add dsh-deepseek-balance-widget
+dsh plugin --profile web add dsh-deepseek-balance-widget@2.3.1
 ```
 
 从 npm 拉取安装，dsh 自动注册到 `dsh.profile.bundles`，完成后**重启 `dsh web`** 即可。
 
+> 务必带版本号 `@2.3.1`。不带版本号的 `add` 会按 npm 的 `latest` tag 安装，该 tag 可能被旧版本抢回去，导致装到老版本。
+
 也可以直接对 AI 说：
 
 > 帮我用 npm 安装 dsh-deepseek-balance-widget 插件。
@@ -47,6 +49,37 @@ AI 会接管全部：问 API Key / 引导获取平台 Cookie → 写入本机
 
 凭据保存在你本机的 `~/.dsh/ai-balances.json`，不随插件分发、不上传。
 
+## 更新
+
+最新稳定版为 **`2.3.1`**。无论你当前是哪个旧版本，都推荐升级到它。
+
+### 方式一：弹窗一键更新（推荐，已装用户）
+
+1. 打开余额弹窗，底部会显示版本号；有新版本时显示 `vX → v2.3.1 更新`。
+2. 点击「**检查更新**」，插件会自动从 npm 拉取并安装最高版本。
+3. 安装完成后**必须彻底重启 `dsh web`**（关掉 `dsh web` 进程 / 退出桌面端再重开，**仅刷新浏览器页面无效**）才能加载新版本。
+
+> 弹窗的「检查更新」会跳过 `latest` tag，直接安装 npm 上 semver 最高的版本，所以即使有人把 `latest` 改低了也能升到最新。
+
+### 方式二：命令行强制更新（最稳妥，适合卡住或装不上的情况）
+
+```bash
+dsh plugin --profile web add dsh-deepseek-balance-widget@2.3.1
+```
+
+带版本号可绕过缓存 / 镜像源不同步 / `latest` 被抢低等问题，一步到位。
+
+### 方式三：手动更新（命令行更新失败时兜底）
+
+```bash
+cd ~/.dsh/profiles/web
+npm install dsh-deepseek-balance-widget@2.3.1   # 若目录内有 pnpm-lock.yaml 则用 pnpm add
+# 验证磁盘上确实变了
+cat node_modules/dsh-deepseek-balance-widget/package.json | grep '"version"'
+```
+
+确认输出 `2.3.1` 后，**彻底重启 `dsh web`** 即可。
+
 ## 卸载
 
 ```bash

package/README_EN.md

@@ -20,11 +20,13 @@ A multi-provider AI balance widget for the dsh web sidebar. **DeepSeek** is buil
 Requires: dsh installed (with `dsh web` working).
 
 ```bash
-dsh plugin --profile web add dsh-deepseek-balance-widget
+dsh plugin --profile web add dsh-deepseek-balance-widget@2.3.1
 ```
 
 Installed from npm and auto-registered by dsh. **Restart `dsh web`** and the balance button appears in the sidebar.
 
+> Always include the version `@2.3.1`. A bare `add` follows npm's `latest` tag, which may be hijacked by older versions and silently install an outdated release.
+
 Or just tell your AI:
 
 > Install the dsh-deepseek-balance-widget plugin for me via npm.
@@ -47,6 +49,37 @@ The AI takes care of everything: asks for your API key / guides you through gett
 
 Credentials are stored locally in `~/.dsh/ai-balances.json`; nothing is shipped with the plugin and nothing is uploaded.
 
+## Update
+
+The latest stable release is **`2.3.1`**. Upgrade to it regardless of which older version you currently have.
+
+### Method 1: One-click from the popover (recommended for installed users)
+
+1. Open the balance popover; the footer shows the version. When a newer one exists it reads `vX → v2.3.1 更新`.
+2. Click "**检查更新**" (Check for update). The plugin pulls and installs the highest semver version from npm automatically.
+3. After install you **must fully restart `dsh web`** (stop the `dsh web` process / quit the desktop app and reopen — **refreshing the browser tab is not enough**) for the new version to load.
+
+> The popover's "Check for update" skips the `latest` tag and installs the highest semver version on npm, so it still reaches latest even if someone lowers the `latest` tag.
+
+### Method 2: Force update from the command line (most reliable if stuck)
+
+```bash
+dsh plugin --profile web add dsh-deepseek-balance-widget@2.3.1
+```
+
+Pinning the version bypasses cache / mirror desync / a hijacked `latest` tag in one step.
+
+### Method 3: Manual update (fallback when the command-line update fails)
+
+```bash
+cd ~/.dsh/profiles/web
+npm install dsh-deepseek-balance-widget@2.3.1   # use `pnpm add` if a pnpm-lock.yaml exists in this dir
+# verify the on-disk version actually changed
+cat node_modules/dsh-deepseek-balance-widget/package.json | grep '"version"'
+```
+
+Once it prints `2.3.1`, **fully restart `dsh web`**.
+
 ## Uninstall
 
 ```bash

package/lib/client.js

@@ -280,8 +280,13 @@ window.__ModuleLoader__.load({
      *  dsh restart re-executes client.js, resetting all variables (including updateSuccessUntil),
      *  which makes the success message disappear and restores the normal version check button. */
     const UPDATE_SUCCESS_MS = Number.MAX_SAFE_INTEGER;
-    /** Absolute path to the AI-setup guide file the chat AI should read before guiding the user. */
-    const AI_GUIDE_FILE = "D:/deepseek harness内置余额显示功能/main program/dsh-deepseek-balance-widget/AI_BALANCE_SETUP_GUIDE.md";
+    /**
+     * Fixed path to the AI-setup guide file that the host copies from the
+     * plugin package into the user's ~/.dsh directory at startup. Using this
+     * space-free, home-relative path avoids the "cannot read / glob failed"
+     * errors dsh chat AIs hit when the workspace path contains spaces.
+     */
+    const AI_GUIDE_FILE = "~/.dsh/AI_BALANCE_SETUP_GUIDE.md";
     /** Prompt copied to the chat when the user asks the AI to configure MiMo Cookie. */
     const MIMO_COOKIE_GUIDE_PROMPT = `请先读取文件 ${AI_GUIDE_FILE}，按里面「MiMo（小米）」章节的流程一步步引导我配置，最后把凭证写入本机插件。`;
     /** Prompt copied to the chat when the user asks the AI to configure DeepSeek balance. */

package/lib/index.js

@@ -1,5 +1,5 @@
 import { launchEnvironmentOf } from "@deepseek-ai/dsh-launch-environment";
-import { readFile, writeFile, stat } from "node:fs/promises";
+import { readFile, writeFile, stat, mkdir, copyFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { dirname, resolve } from "node:path";
 import { homedir } from "node:os";
@@ -567,16 +567,27 @@ async function runPackageUpdate() {
   const target = versionInfo.latest;
   const pm = await detectPackageManager();
   const isWin = process.platform === "win32";
-  const cmd = isWin ? (pm === "pnpm" ? "pnpm.cmd" : "npm.cmd") : pm;
+  const cmd = isWin ? (pm === "pnpm" ? "pnpm" : "npm") : pm;
   const args = pm === "pnpm"
     ? ["add", `dsh-deepseek-balance-widget@${target}`]
     : ["install", `dsh-deepseek-balance-widget@${target}`];
   return new Promise((resolve) => {
-    const child = spawn(cmd, args, {
-      cwd: UPDATE_CWD,
-      shell: isWin,
-      env: { ...process.env, NPM_CONFIG_FUND: "false", NPM_CONFIG_AUDIT: "false" }
-    });
+    let child;
+    if (isWin) {
+      // Avoid Node.js DEP0190: spawn with shell:true and a separate args array is deprecated.
+      // Build a single command string and let cmd.exe parse it; hide the console window.
+      const quotedArgs = args.map((a) => `"${a.replace(/"/g, '\\"')}"`).join(" ");
+      child = spawn("cmd.exe", ["/d", "/s", "/c", `${cmd} ${quotedArgs}`], {
+        cwd: UPDATE_CWD,
+        windowsHide: true,
+        env: { ...process.env, NPM_CONFIG_FUND: "false", NPM_CONFIG_AUDIT: "false" }
+      });
+    } else {
+      child = spawn(cmd, args, {
+        cwd: UPDATE_CWD,
+        env: { ...process.env, NPM_CONFIG_FUND: "false", NPM_CONFIG_AUDIT: "false" }
+      });
+    }
     let stdout = "";
     let stderr = "";
     child.stdout.on("data", (chunk) => { stdout += String(chunk); });
@@ -584,13 +595,26 @@ async function runPackageUpdate() {
     child.on("error", (error) => {
       resolve({ ok: false, output: stdout + stderr, error: String(error?.message ?? error) });
     });
-    child.on("close", (code) => {
+    child.on("close", async (code) => {
       const output = (stdout + "\n" + stderr).trim();
-      if (code === 0) {
-        resolve({ ok: true, output: output.slice(-800) });
-      } else {
+      if (code !== 0) {
         resolve({ ok: false, output, error: `${pm} ${args.join(" ")} exited with code ${code}` });
+        return;
       }
+      // Verify the on-disk version actually changed so the user can't be misled into
+      // restarting dsh when the install silently wrote to a different location.
+      try {
+        const installedPkgPath = resolve(UPDATE_CWD, "node_modules", "dsh-deepseek-balance-widget", "package.json");
+        const installedPkg = JSON.parse(await readFile(installedPkgPath, "utf8"));
+        if (installedPkg.version !== target) {
+          resolve({ ok: false, output, error: `installed version mismatch: expected ${target}, found ${installedPkg.version}` });
+          return;
+        }
+      } catch (verifyError) {
+        resolve({ ok: false, output, error: `update appeared to succeed but could not verify installed version: ${String(verifyError?.message ?? verifyError)}` });
+        return;
+      }
+      resolve({ ok: true, output: output.slice(-800) });
     });
   });
 }
@@ -890,6 +914,20 @@ async function queryPlatformUsage(token, month, year) {
  * @param {import("@deepseek-ai/cordis").Context} ctx - plugin context.
  */
 function apply(ctx) {
+  // Copy the AI setup guide to a fixed, space-free location so any chat AI
+  // launched from dsh can read it without being tripped up by spaces in the
+  // workspace path or by the file not being shipped in the npm tarball.
+  (async () => {
+    try {
+      const guideSrc = resolve(PLUGIN_ROOT, "AI_BALANCE_SETUP_GUIDE.md");
+      const dshDir = resolve(homedir(), ".dsh");
+      const guideDest = resolve(dshDir, "AI_BALANCE_SETUP_GUIDE.md");
+      await stat(guideSrc);
+      await mkdir(dshDir, { recursive: true });
+      await copyFile(guideSrc, guideDest);
+    } catch {}
+  })();
+
   ctx.effect(() => {
     const dispose = ctx.webServer.register({
       kind: "prefix",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-deepseek-balance-widget",
-  "version": "2.3.0",
+  "version": "2.3.2",
   "type": "module",
   "description": "Multi-provider AI balance widget for the dsh web sidebar: a live, auto-refreshing balance pill plus a detail popover listing DeepSeek and any added providers (MiMo etc.). Keys are stored per-machine in ~/.dsh/ai-balances.json and resolved from the local credential seam, never hardcoded.",
   "keywords": [
@@ -26,7 +26,8 @@
     "README.md",
     "README_EN.md",
     "LICENSE",
-    "scripts"
+    "scripts",
+    "AI_BALANCE_SETUP_GUIDE.md"
   ],
   "engines": {
     "node": ">=18"