dsh-llm-workbuddy 0.1.2 → 0.1.4

package/README.md

@@ -42,7 +42,8 @@
 ```
 
 - **后端路由**（`lib/index.js` 的 `registerWorkbuddyRoutes`）运行在 `dsh web` 的
-  HTTP 服务上，通过 Cordis 的 `ctx.webServer` 注册，headless profile 下自动跳过。
+  HTTP 服务上，通过 Cordis 的 `webServer` 服务注册（用 `ctx.get("webServer")`
+  探测，`webServer` 不列入 `inject`），headless profile 下自动跳过。
 - **前端胶囊**（`lib/client.js`）是零依赖的原生浏览器 JS，由 DSH 的 `dsh.client`
   双端机制在 `window.__DSH_BOOT__` 中注入，serve 于
   `/plugins/dsh-llm-workbuddy/client.js`。
@@ -163,13 +164,16 @@ Web 登录后终端脚本也读得到同一份会话。
 
 ### 后端路由（`lib/index.js`）
 
-插件在 `apply(ctx, config)` 里通过 `ctx.webServer.register(...)` 注册两条路由
-（headless profile 无 `webServer`，自动跳过）：
+插件在 `apply(ctx, config)` 里用 `ctx.get("webServer")` 探测 HTTP 服务（不在
+`inject` 里，headless profile 无 `webServer` 时返回 `undefined`、自动跳过），
+然后通过 `webServer.register({ kind: 'exact', path, handler })` 注册两条精确
+路由，并用 `ctx.effect` 包裹以便热重载自动清理。HTTP 方法过滤在 handler 内自行
+判断（`req.method`），因为路由 API 本身不含方法字段：
 
 | 方法 + 路径 | 行为 |
 |---|---|
-| `GET /api/workbuddy/status` | 读取会话文件（默认 `~/.codebuddy-session.json`，或配置的 `sessionFile`）的 `auth.expiresAt` 判断会话是否有效，并 `fetch` 代理 `/health` 判断 `proxyUp`；返回 JSON：`{ sessionFile, authenticated, expiresAt, account, proxyUp, tokenValid, loginScriptAvailable }` |
-| `POST /api/workbuddy/login` | 若已有有效会话则直接返回 `alreadyLoggedIn`；否则用系统 `python3` `spawn` 包内 `login_workbuddy.py --session-file <sessionFile>`，从子进程 stdout 解析出 `authUrl` 立即返回 `{ authUrl, pending:true }`（设备流在后台继续，前端轮询 status 感知完成） |
+| `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 |
 
 > 会话文件与登录脚本路径的解析顺序：
 > 1. 配置里显式指定的 `sessionFile` / `loginScript`；
@@ -186,6 +190,29 @@ Web 登录后终端脚本也读得到同一份会话。
   - `authenticated && proxyUp` → 🟢 绿，显示 `WorkBuddy · <昵称>`
   - 否则 → 🔴 红，显示「登录」按钮；`proxyUp` 为 false 时额外提示 `代理未运行`
 
+> **关于 UI 挂载位置（临时做法说明）**
+>
+> 当前状态胶囊用 `position:fixed` 直接注入 `document.body`。DSH 官方的 UI
+> 组合机制是 **slot 系统**（`@deepseek-ai/dsh-client-ui-slots`，`ctx.slots.register`
+> 注册 React 组件进声明的 slot）。按官方「组合优先、不要假设/覆盖其他插件内部实现」
+> 的原则，理想做法是注册进官方 slot，而非直接改产品外壳。
+>
+> 评估结论：**当前 shell 声明的 slot 里没有专门的「右下角状态位」**；最接近的
+> `sidebar.footer.action`、`conversation.session.header.actions`、
+> `conversation.input.overlay` 都是 **React 组件位**，迁移意味着要把本插件从
+> 「零依赖原生 JS」改造成 **React + 构建流程**，并依赖 shell 暴露 `ctx.slots`
+> 服务。因此现阶段保留 DOM 注入（机制允许），**待官方 shell 提供合适的状态胶囊
+> slot 后再迁移**。以下是已知的迁移路径（供后续参考）：
+>
+> ```js
+> ctx.slots.inject("sidebar.footer.action", () => ctx.slots.register({
+>   name: "sidebar.footer.action",
+>   id: "workbuddy-status",
+>   locale: NS,
+>   inject: () => ({ /* 轮询句柄 / 登录回调 */ })
+> }, WorkBuddyStatusPill /* React 组件 */));
+> ```
+
 ### 为什么不需要构建
 
 DSH 的 `dsh.client` 机制只要求 `package.json` 里：

package/lib/index.js

@@ -38,7 +38,11 @@ import { MAX_TIMER_DELAY_MS, idleWatchdog, timeoutOf } from "@deepseek-ai/dsh-ti
 
 /** Plugin identity (Cordis convention). */
 export const name = "llm-workbuddy";
-export const inject = ["llm", "webServer"];
+// `llm` is a hard requirement (the adapter must always register). `webServer`
+// is optional — headless profiles have no HTTP surface, so it must NOT be in
+// `inject` (that would make the whole plugin PENDING forever in headless).
+// We probe it at the use site instead. See cordis-tutorial/03-services.md.
+export const inject = ["llm"];
 
 /** The single provider route this plugin owns. */
 export const PROVIDER = "workbuddy";
@@ -765,58 +769,80 @@ async function probeProxy(baseURL) {
  * file appears and reports `authenticated: true`.
  */
 function registerWorkbuddyRoutes(ctx, config) {
-  if (ctx.webServer === undefined) return; // headless profile: no HTTP surface
-  const baseURL = config_baseURL();
-  const { sessionFile, loginScript } = resolveLoginPaths(config);
-  ctx.webServer.register({
-    path: "/api/workbuddy/status",
-    exact: true,
-    methods: ["GET"],
-    async handler(_req, res) {
-      const session = readSessionStatus(sessionFile);
-      const proxy = await probeProxy(baseURL);
-      res.writeHead(200, { "content-type": "application/json" });
-      res.end(JSON.stringify({
-        ...session,
-        ...proxy,
-        loginScriptAvailable: existsSync(loginScript),
-      }));
-    },
-  });
-  ctx.webServer.register({
-    path: "/api/workbuddy/login",
-    exact: true,
-    methods: ["POST"],
-    async handler(_req, res) {
-      if (!existsSync(loginScript)) {
-        res.writeHead(503, { "content-type": "application/json" });
-        res.end(JSON.stringify({ error: "login_workbuddy.py not found" }));
-        return;
-      }
-      // Existing session is fine; no need to re-run the flow.
-      const existing = readSessionStatus(sessionFile);
-      if (existing.authenticated) {
+  // Delay registration until the webServer service exists. The plugin keeps
+  // `webServer` OUT of `inject` so headless profiles (no HTTP surface) still
+  // load — but a synchronous `ctx.get("webServer")` probe at apply time races
+  // the webserver plugin's own mount and can observe the service before it is
+  // provided, silently dropping the routes. `ctx.inject` runs this callback
+  // only once webServer is available, and skips it entirely when the service
+  // never appears (headless), preserving the original intent.
+  ctx.inject(["webServer"], (webCtx) => {
+    const webServer = webCtx.webServer;
+    const baseURL = config_baseURL();
+    const { sessionFile, loginScript } = resolveLoginPaths(config);
+    // The register() call returns a disposer. Wrapping it in ctx.effect ties
+    // it to the plugin fiber so config hot-edit / reload cleans the routes up
+    // instead of leaking them (a leaked route makes a duplicate re-register
+    // throw). Method filtering must be done inside the handler — the route API
+    // only accepts `{ kind, path, handler }`.
+    webCtx.effect(() => webServer.register({
+      kind: "exact",
+      path: "/api/workbuddy/status",
+      async handler(req, res) {
+        if (req.method !== "GET") {
+          res.writeHead(405, { "content-type": "application/json" });
+          res.end(JSON.stringify({ error: "method not allowed" }));
+          return;
+        }
+        const session = readSessionStatus(sessionFile);
+        const proxy = await probeProxy(baseURL);
         res.writeHead(200, { "content-type": "application/json" });
-        res.end(JSON.stringify({ alreadyLoggedIn: true, authUrl: null, ...existing }));
-        return;
-      }
-      // login_workbuddy.py is dependency-free (stdlib only), so we invoke it
-      // directly with the system Python — no uv runtime required.
-      const args = ["-u", loginScript, "--session-file", sessionFile];
-      const child = spawn("python3", args, { env: { ...process.env, PYTHONUNBUFFERED: "1" } });
-      let stdout = "";
-      let authUrl = null;
-      child.stdout.on("data", (chunk) => {
-        stdout += chunk.toString();
-        const m = stdout.match(/https?:\/\/\S+/);
-        if (m && authUrl === null) authUrl = m[0];
-      });
-      child.stderr.on("data", () => {});
-      // The device flow blocks until login or timeout; we hand back the URL
-      // immediately and let the widget poll /status for completion.
-      res.writeHead(200, { "content-type": "application/json" });
-      res.end(JSON.stringify({ authUrl, pending: true }));
-    },
+        res.end(JSON.stringify({
+          ...session,
+          ...proxy,
+          loginScriptAvailable: existsSync(loginScript),
+        }));
+      },
+    }));
+    webCtx.effect(() => webServer.register({
+      kind: "exact",
+      path: "/api/workbuddy/login",
+      async handler(req, res) {
+        if (req.method !== "POST") {
+          res.writeHead(405, { "content-type": "application/json" });
+          res.end(JSON.stringify({ error: "method not allowed" }));
+          return;
+        }
+        if (!existsSync(loginScript)) {
+          res.writeHead(503, { "content-type": "application/json" });
+          res.end(JSON.stringify({ error: "login_workbuddy.py not found" }));
+          return;
+        }
+        // Existing session is fine; no need to re-run the flow.
+        const existing = readSessionStatus(sessionFile);
+        if (existing.authenticated) {
+          res.writeHead(200, { "content-type": "application/json" });
+          res.end(JSON.stringify({ alreadyLoggedIn: true, authUrl: null, ...existing }));
+          return;
+        }
+        // login_workbuddy.py is dependency-free (stdlib only), so we invoke it
+        // directly with the system Python — no uv runtime required.
+        const args = ["-u", loginScript, "--session-file", sessionFile];
+        const child = spawn("python3", args, { env: { ...process.env, PYTHONUNBUFFERED: "1" } });
+        let stdout = "";
+        let authUrl = null;
+        child.stdout.on("data", (chunk) => {
+          stdout += chunk.toString();
+          const m = stdout.match(/https?:\/\/\S+/);
+          if (m && authUrl === null) authUrl = m[0];
+        });
+        child.stderr.on("data", () => {});
+        // The device flow blocks until login or timeout; we hand back the URL
+        // immediately and let the widget poll /status for completion.
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify({ authUrl, pending: true }));
+      },
+    }));
   });
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-llm-workbuddy",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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",