dsh-llm-workbuddy 0.1.4 → 0.1.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dengkun Zhang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -92,33 +92,53 @@ CLI 会把依赖写进 profile 并把 `dsh-llm-workbuddy` 追加到 `dsh.profile
 
 ## 安装代理（先决条件，第三方）
 
-插件只提供模型路由与登录；真正的协议转换由 **workbuddy2api** 完成。请单独安装并
-启动它（以 127.0.0.1:8787 为例）：
+插件只提供模型路由与登录；真正的协议转换由 **workbuddy2api**（第三方开源项目）完成。
+它**不在本插件包里**，需要单独安装并启动在 `127.0.0.1:8787`。分两种情况：
+
+### 全新机器 / 标准安装（任何能跑 Python 的机器）
+
+别人或你自己在**新机器**上用 npm 版插件时，按以下 3 步装代理：
 
 ```sh
-# 1. 安装 uv（本机 Python 工具）
+# 1. 安装 uv（本机 Python 工具，若已装可跳过）
 curl -LsSf https://astral.sh/uv/install.sh | sh
 
 # 2. 拉取 workbuddy2api 主分支源码
 git clone https://github.com/hawklithm/workbuddy2api.git
 cd workbuddy2api
 
-# 3. 启动代理（先完成下方「登录」后再请求）
+# 3. 启动代理（监听 127.0.0.1:8787；先完成下方「登录」后再真正调用模型）
 uv run python -u -m codebuddy_proxy --desensitize \
   --session-file ~/.codebuddy-session.json \
   --log-file ~/.codebuddy-proxy.jsonl
-# 监听 http://127.0.0.1:8787
 ```
 
-> 仓库根目录也有 `start-workbuddy.sh` 脚本（面向仓库本地开发），发布版插件不依赖它。
+> 之后任何时候想重启代理，就在 `workbuddy2api` 目录里重跑上面第 3 条命令。
+> 若提示 `address already in use`，先停掉旧代理：
+> `lsof -tiTCP:8787 -sTCP:LISTEN | xargs kill`，再重跑。
+
+### 本仓库本地开发（可选快捷方式）
+
+仓库根目录提供 `start-workbuddy.sh`，它会用仓库固定的 `main` 分支源码 + 本地
+`.tools/uv` 工具链 + 仓库内的 `.workbuddy/session.json` 启动代理。它**不随 npm
+包发布**，仅面向本仓库开发时方便：
 
-验证：
+```sh
+cd /path/to/dsh-workbuddy
+./start-workbuddy.sh
+```
+
+### 验证代理是否真的能用
 
 ```sh
 curl http://127.0.0.1:8787/health    # {"status":"ok","authenticated":true,...}
 curl http://127.0.0.1:8787/v1/models # 模型列表（含 glm-5.2 / deepseek-v4-pro ...）
 ```
 
+> ⚠️ `/health` 只证明**代理进程活着**，不能证明模型能真正出字（代理进程指向旧
+> 路径/文件缺失时 `/health` 仍返回 `authenticated: true`，但所有模型请求 500）。
+> 想确认"模型真能用"，用右下角胶囊的 **🔍 诊断** 按钮，它会真实发一次模型请求。
+
 > 登录态过期时 `authenticated` 变回 `false`，重跑登录即可，代理无需重启
 > （会话按请求读取）。
 
@@ -174,6 +194,7 @@ Web 登录后终端脚本也读得到同一份会话。
 |---|---|
 | `GET /api/workbuddy/status` | 读取会话文件（默认 `~/.codebuddy-session.json`，或配置的 `sessionFile`）的 `auth.expiresAt` 判断会话是否有效，并 `fetch` 代理 `/health` 判断 `proxyUp`；返回 JSON：`{ sessionFile, authenticated, expiresAt, account, proxyUp, tokenValid, loginScriptAvailable }`；非 GET 返回 405 |
 | `POST /api/workbuddy/login` | 若已有有效会话则直接返回 `alreadyLoggedIn`；否则用系统 `python3` `spawn` 包内 `login_workbuddy.py --session-file <sessionFile>`，从子进程 stdout 解析出 `authUrl` 立即返回 `{ authUrl, pending:true }`（设备流在后台继续，前端轮询 status 感知完成）；非 POST 返回 405 |
+| `POST /api/workbuddy/diagnose` | **一键诊断**：真实探测健康状态，返回 `{ ok, session, health, chat, loginScriptAvailable, restartCommand }`。与 `/status` 不同，它除了探 `/health`，还会**真实发一次最小模型请求**（`chat.chatWorking`），能戳穿"胶囊显示成功但模型全 500"的假象；`ok:false` 时附带 `restartCommand`（自动区分本地 monorepo 布局与标准安装）；非 POST 返回 405 |
 
 > 会话文件与登录脚本路径的解析顺序：
 > 1. 配置里显式指定的 `sessionFile` / `loginScript`；
@@ -186,6 +207,9 @@ Web 登录后终端脚本也读得到同一份会话。
 - 启动时在 `document.body` 末尾挂一个 `position:fixed` 的胶囊（右下角）。
 - 每 **5 秒** `GET /api/workbuddy/status`；点「登录」后加快到每 **2 秒**轮询、
   最多 30 次，直到 `authenticated:true`。
+- 胶囊里有个 **🔍 诊断** 按钮：点它 `POST /api/workbuddy/diagnose`，弹出一个面板
+  显示**真实健康状态**（登录、会话文件、代理进程、登录令牌、模型能否出字），
+  发现问题时附带**可复制的重启命令**（一键复制到终端执行）。
 - 状态映射：
   - `authenticated && proxyUp` → 🟢 绿，显示 `WorkBuddy · <昵称>`
   - 否则 → 🔴 红，显示「登录」按钮；`proxyUp` 为 false 时额外提示 `代理未运行`
@@ -262,6 +286,7 @@ DSH 的 `dsh.client` 机制只要求 `package.json` 里：
 | 右下角没有胶囊 | `dsh web` 没重启加载新 bundle → 重启 `dsh web`；或 `curl /plugins/dsh-llm-workbuddy/client.js` 应返回 200 |
 | 胶囊一直 `…`（加载中） | `GET /api/workbuddy/status` 失败 → 确认 `dsh web` 在跑、端口正确 |
 | 胶囊红 + `代理未运行` | workbuddy2api 代理没起或挂了 → 按「安装代理」章节启动 |
+| 胶囊显示登录成功但模型用不了 | 典型的"代理进程活着但指向旧路径/文件缺失"假象（`/health` 仍显示 ok）。点胶囊 **🔍 诊断**，看 `模型出字` 是否失败；按面板给出的重启命令重启代理 |
 | 点「登录」没反应 / 按钮灰 | `loginScriptAvailable:false` → 包内 `login_workbuddy.py` 缺失或系统无 `python3`；检查安装 |
 | 新标签页打开后登录完成，胶囊仍是红 | 会话文件（默认 `~/.codebuddy-session.json`）未刷新或 `expiresAt` 已过期 → 刷新页面或重跑登录 |
 | 启动 `dsh web` 报 `EPERM ... cordis.yml` | `.dsh` 所在系统卷受保护（`/System/Volumes/Data` 带 `protect`）。解决：`sudo chown -R $(whoami) /Users/jiyunyang/.dsh`，或 `export DSH_HOME=$HOME/dsh-home` 后重新 `dsh plugin --profile web add` 并把插件链接进新 home |
@@ -284,8 +309,8 @@ DSH 的 `dsh.client` 机制只要求 `package.json` 里：
 
 | 路径 | 作用 |
 |---|---|
-| `lib/index.js` | Cordis 插件主体：LLM 适配器 `WorkBuddyAdapter` + `/api/workbuddy/*` 路由注册 |
-| `lib/client.js` | 零依赖浏览器小部件（状态胶囊 + 登录流程），被 `dsh.client` 注入 |
+| `lib/index.js` | Cordis 插件主体：LLM 适配器 `WorkBuddyAdapter` + `/api/workbuddy/*` 路由（status / login / **diagnose**） |
+| `lib/client.js` | 零依赖浏览器小部件（状态胶囊 + 登录流程 + **🔍 诊断**），被 `dsh.client` 注入 |
 | `login_workbuddy.py` | 设备流登录脚本（随包发布，被后端路由用系统 `python3` spawn） |
 | `cordis.patch.yml` | 本包的 Cordis bundle 挂载声明（`id: llm-workbuddy`） |
 | `package.json` | 包元数据、`dsh.client` 浏览器入口声明、`llm-workbuddy` peer 依赖 |

package/lib/client.js

@@ -105,11 +105,15 @@ function runWidget() {
       html += '<button class="wb-btn" id="wb-login"' + disabled + ">" +
         (busy ? "登录中…" : "登录") + "</button>";
     }
+    // 诊断按钮始终显示，便于随时自查真实健康状态。
+    html += '<button class="wb-btn wb-diagnose" id="wb-diagnose" title="一键诊断">🔍</button>';
     if (!status.proxyUp) html += '<span class="wb-warn">代理未运行</span>';
     html += "</div>";
     host.innerHTML = html;
     var btn = host.querySelector("#wb-login");
     if (btn) btn.addEventListener("click", onLogin);
+    var dg = host.querySelector("#wb-diagnose");
+    if (dg) dg.addEventListener("click", onDiagnose);
   }
 
   function refresh() {
@@ -151,6 +155,63 @@ function runWidget() {
       });
   }
 
+  /** 一键诊断：真实探测代理健康，必要时给出可复制的重启命令。 */
+  function onDiagnose() {
+    var panel = document.getElementById("wb-diagnose-panel");
+    if (panel) { panel.remove(); return; }
+    var el = document.createElement("div");
+    el.id = "wb-diagnose-panel";
+    el.style.cssText =
+      "position:fixed;right:12px;bottom:44px;z-index:2147483647;width:340px;max-height:340px;overflow:auto;" +
+      "background:#0f172a;color:#e2e8f0;border:1px solid #334155;border-radius:8px;" +
+      "padding:10px;font:12px/1.5 system-ui,sans-serif;box-shadow:0 6px 20px rgba(0,0,0,.5);";
+    el.innerHTML = '<div class="wb-dg-title" style="font-weight:700;margin-bottom:6px">WorkBuddy 诊断中…</div>' +
+      '<div class="wb-dg-body" style="white-space:pre-wrap;word-break:break-word;color:#94a3b8">正在探测…</div>';
+    document.body.appendChild(el);
+
+    fetch("/api/workbuddy/diagnose", { method: "POST" })
+      .then(function (r) { return r.json(); })
+      .then(function (d) {
+        if (!d) throw new Error("空响应");
+        var title = d.ok ? "✅ 一切正常" : "⚠️ 发现问题";
+        var lines = [];
+        lines.push("登录状态: " + (d.session && d.session.authenticated ? "有效" : "无效"));
+        lines.push("会话文件: " + (d.session && d.session.file ? "存在" : "缺失"));
+        lines.push("代理进程: " + (d.health && d.health.proxyUp ? "在运行" : "未运行"));
+        lines.push("登录令牌: " + (d.health && d.health.tokenValid ? "有效" : "无效"));
+        lines.push("模型出字: " + (d.chat && d.chat.chatWorking ? "正常" : "失败"));
+        if (d.chat && d.chat.chatError) lines.push("出字错误: " + d.chat.chatError);
+        var html = '<div class="wb-dg-title" style="font-weight:700;margin-bottom:6px">' + title + '</div>' +
+          '<div class="wb-dg-body" style="white-space:pre-wrap;word-break:break-word">' + lines.map(esc).join("\n") + "</div>";
+        if (!d.ok && d.restartCommand) {
+          html += '<div style="margin-top:8px;font-weight:700">重启命令（复制到终端执行）：</div>' +
+            '<pre style="background:#1e293b;border-radius:6px;padding:8px;font-size:11px;overflow:auto;white-space:pre-wrap">' +
+            esc(d.restartCommand) + "</pre>" +
+            '<button class="wb-btn" id="wb-copy-cmd">复制重启命令</button>';
+        }
+        el.innerHTML = html;
+        var copy = document.getElementById("wb-copy-cmd");
+        if (copy) {
+          copy.addEventListener("click", function () {
+            navigator.clipboard.writeText(d.restartCommand).then(function () {
+              copy.textContent = "已复制 ✓";
+              setTimeout(function () { copy.textContent = "复制重启命令"; }, 1500);
+            });
+          });
+        }
+      })
+      .catch(function (err) {
+        el.innerHTML = '<div class="wb-dg-title" style="font-weight:700;color:#f87171">诊断失败</div>' +
+          '<div class="wb-dg-body">' + esc(String(err && err.message || err)) + "</div>";
+      });
+  }
+
+  function esc(s) {
+    return String(s == null ? "" : s).replace(/[&<>"']/g, function (c) {
+      return { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c];
+    });
+  }
+
   refresh();
   timer = setInterval(refresh, POLL_MS);
 }

package/lib/index.js

@@ -762,11 +762,87 @@ async function probeProxy(baseURL) {
 }
 
 /**
- * Register `GET /api/workbuddy/status` and `POST /api/workbuddy/login` on the
- * DSH web server. The login route spawns `login_workbuddy.py`, parses the
- * device-flow `authUrl` it prints to stdout, and returns it so the browser
- * can open it in a new tab. The widget then polls `/status` until the session
- * file appears and reports `authenticated: true`.
+ * Probe whether the proxy can actually complete a chat completion, not just
+ * answer `/health`. `/health` reflects the proxy process alone — it stays
+ * `authenticated: true` even when the process points at a deleted/old path
+ * and every model request fails with `[Errno 2] No such file or directory`.
+ * Sending one minimal request is the only probe that catches that class of
+ * "capsule shows green but models are all down" false positive.
+ * @returns `{ chatWorking, chatError? }` where `chatWorking` is true only
+ * when the proxy returned a non-streamed completion.
+ */
+async function probeChatWorking(baseURL) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 15000);
+  try {
+    const endpoint = `${baseURL.replace(/\/v1\/?$/, "")}/v1/chat/completions`;
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        model: "hy3",
+        messages: [{ role: "user", content: "ping" }],
+        max_tokens: 4,
+        stream: false,
+      }),
+      signal: controller.signal,
+    });
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      return { chatWorking: false, chatError: `HTTP ${response.status}${text ? `: ${text.slice(0, 200)}` : ""}` };
+    }
+    const body = await response.json().catch(() => null);
+    const content = body?.choices?.[0]?.message?.content;
+    if (typeof content === "string" && content.length > 0) {
+      return { chatWorking: true };
+    }
+    return { chatWorking: false, chatError: "代理返回了空响应" };
+  } catch (error) {
+    return { chatWorking: false, chatError: String(error?.message ?? error) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * The restart command shown by the diagnose route. It adapts to two layouts:
+ * - Local monorepo dev: the plugin sits inside a `dsh-workbuddy/` checkout with
+ *   `start-workbuddy.sh` two levels up — use the workspace-local script.
+ * - Standard install (any other machine): no `start-workbuddy.sh`, so show the
+ *   upstream README command for running the workbuddy2api proxy via uv.
+ */
+function diagnoseRestartCommand() {
+  const workspaceRoot = resolve(PLUGIN_DIR, "..", "..");
+  const localScript = resolve(workspaceRoot, "start-workbuddy.sh");
+  if (existsSync(localScript)) {
+    return [
+      "# 检测到本机 monorepo 布局（dsh-workbuddy/），用仓库脚本重启代理",
+      "# 停掉旧代理（若 8787 被占用）",
+      "lsof -tiTCP:8787 -sTCP:LISTEN | xargs kill",
+      "",
+      "# 重启代理（脚本路径自动定位到本仓库）",
+      `cd ${workspaceRoot} && ./start-workbuddy.sh`,
+    ].join("\n");
+  }
+  return [
+    "# 用 workbuddy2api 代理（标准安装）重启：",
+    "# 停掉旧代理（若 8787 被占用）",
+    "lsof -tiTCP:8787 -sTCP:LISTEN | xargs kill",
+    "",
+    "# 拉取并运行代理（详见 README「安装代理」）",
+    "git clone https://github.com/hawklithm/workbuddy2api.git && cd workbuddy2api",
+    "uv run python -u -m codebuddy_proxy --desensitize \\",
+    "  --session-file ~/.codebuddy-session.json --log-file ~/.codebuddy-proxy.jsonl",
+  ].join("\n");
+}
+
+/**
+ * Register `GET /api/workbuddy/status`, `POST /api/workbuddy/login`, and
+ * `POST /api/workbuddy/diagnose` on the DSH web server. The login route spawns
+ * `login_workbuddy.py`, parses the device-flow `authUrl` it prints to stdout,
+ * and returns it so the browser can open it in a new tab. The widget then
+ * polls `/status` until the session file appears and reports
+ * `authenticated: true`.
  */
 function registerWorkbuddyRoutes(ctx, config) {
   // Delay registration until the webServer service exists. The plugin keeps
@@ -843,6 +919,34 @@ function registerWorkbuddyRoutes(ctx, config) {
         res.end(JSON.stringify({ authUrl, pending: true }));
       },
     }));
+    webCtx.effect(() => webServer.register({
+      kind: "exact",
+      path: "/api/workbuddy/diagnose",
+      async handler(req, res) {
+        if (req.method !== "POST") {
+          res.writeHead(405, { "content-type": "application/json" });
+          res.end(JSON.stringify({ error: "method not allowed" }));
+          return;
+        }
+        // Real health: probe /health AND actually complete a chat. /health
+        // alone stays green even when the proxy points at a deleted path and
+        // every model request 500s — the exact "capsule green but models dead"
+        // false positive the diagnose button exists to surface.
+        const session = readSessionStatus(sessionFile);
+        const health = await probeProxy(baseURL);
+        const chat = await probeChatWorking(baseURL);
+        const ok = Boolean(health.proxyUp && health.tokenValid && session.authenticated && chat.chatWorking);
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify({
+          ok,
+          session: { file: session.sessionFile, authenticated: session.authenticated, expiresAt: session.expiresAt },
+          health,
+          chat,
+          loginScriptAvailable: existsSync(loginScript),
+          restartCommand: ok ? null : diagnoseRestartCommand(),
+        }));
+      },
+    }));
   });
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-llm-workbuddy",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "WorkBuddy (via the local workbuddy2api proxy) LLM provider adapter for DeepSeek Harness, with a Web login-status widget",
   "type": "module",
   "main": "lib/index.js",
@@ -17,7 +17,11 @@
   ],
   "repository": {
     "type": "git",
-    "url": ""
+    "url": "git+https://github.com/zdk119746/dsh-llm-workbuddy.git"
+  },
+  "homepage": "https://github.com/zdk119746/dsh-llm-workbuddy#readme",
+  "bugs": {
+    "url": "https://github.com/zdk119746/dsh-llm-workbuddy/issues"
   },
   "dsh": {
     "bundle": {