dsh-llm-workbuddy 0.1.16 → 0.1.17

package/CHANGELOG.md

@@ -4,6 +4,56 @@
 每次发版请同步 `package.json` 的 `version` 并打一个 `git tag`（如 `v0.1.13`），
 在 GitHub 创建 Release 时本文件即为更新说明来源。
 
+## [0.1.17] - 2026-09-11
+
+修复社区反馈的两个 issue（[#3](https://github.com/zdk119746/dsh-llm-workbuddy/issues/3)、
+[#4](https://github.com/zdk119746/dsh-llm-workbuddy/issues/4)）。
+
+### Fixed
+- **登录态永远判定为有效，且「登录」按钮无法恢复（issue #3）**。
+  代理（workbuddy2api）写入的 `~/.codebuddy-session.json` 里**没有
+  `auth.expiresAt`**，而插件把"字段缺失"当作"未过期"，于是：
+  `authenticated` 恒为 `true`、`POST /api/workbuddy/login` 恒返回
+  `alreadyLoggedIn`、诊断面板的「登录状态/登录令牌」恒显示"有效"；一旦 token
+  真失效，用户点登录没有任何反应，只能回终端手跑脚本。
+  现改为**多源推导过期时间**（按优先级）：
+  1. `auth.expiresAt`（本插件脚本写入；秒/毫秒自动归一化）；
+  2. `refreshToken` 的 JWT `exp`——代理会自动 refresh，所以 refreshToken 的
+     有效期才是会话真正的边界；
+  3. `accessToken` 的 JWT `exp`（解码 payload，不校验签名）；
+  4. `auth.expiresIn` + 会话文件 mtime（兜底，只会低估、不会高估）。
+  全部失败时返回 `expiryKnown: false` + `reloginRecommended: true`，
+  **不再假装有效**。`/status` 与诊断面板都会带上 `expiresAtSource` 说明来源。
+- **`authUrl` 永远为 `null`，点「登录」在新标签页打不开任何页面（issue #3 相关）**。
+  登录路由 `spawn` 后**立刻** `res.end()`，而设备流链接是子进程稍后才打印到
+  stdout 的，因此返回的 `authUrl` 恒为 `null`，Web 登录实际上从来没成功打开过
+  授权页。现改为等待链接出现（或脚本早退/15 秒超时）再应答，失败时返回结构化
+  `error`，前端弹窗提示而不是静默无反应。子进程 stdout 在应答后继续被 drain，
+  避免缓冲写满阻塞。
+- **「🎁 签到」必然 404，且每天写入一条失败记录（issue #4）**。
+  插件请求代理的 `/checkin-status` 与 `/checkin`，但 workbuddy2api **从未实现**
+  这两个端点（已核对 PyPI 2.0.0–2.0.4 与 `main` / `dsh` / `codex` 全部分支），
+  且 `autoCheckin` 默认 `true`，于是每天 10 点后必然失败一次并把失败结果持久化。
+  现改为**探测 + 优雅降级**：`/checkin-status` 返回 404/405 时判定该代理
+  **不支持签到**，隐藏签到入口、自动签到直接跳过（**不写任何状态**）。探测结果
+  缓存 30 分钟，`/status` 通过 `checkin.supported` 三态（`true`/`false`/`null`）
+  暴露给胶囊。代理补齐端点后入口会自动出现，无需升级插件。
+
+### Added
+- **🔑 重新登录（强制重登）**：`POST /api/workbuddy/login?force=1` 忽略本地会话
+  判定直接重跑设备流；胶囊**始终**提供该入口（不做条件显示），「判定错误 →
+  无法恢复」的耦合从此断开。
+
+### Changed
+- 诊断面板新增「令牌过期」（含来源）与重新登录提示；`login` 失败会弹窗说明原因。
+- **README 代理安装指引更正**：原先要求"必须用 GitHub 主分支源码、不能用 PyPI
+  2.0.3"，实测 PyPI **2.0.4**（2026-09-10 发布）已包含该登录修复（
+  `X-Product-Code` / `_enterprise_headers` / `X-Domain` 均在包内），且 GitHub
+  `main` 与 2.0.4 **内容完全一致**；而 2.0.3 确实缺少该修复。现改为推荐
+  `uv tool install -U workbuddy2api`（`>= 2.0.4`），源码方式作为等价备选。
+- 诊断面板的「重启命令」同步改为 `uv tool install` 方式。
+- README 补充「登录态判定」章节与签到依赖说明。
+
 ## [0.1.16] - 2026-09-10
 
 ### Fixed

package/README.md

@@ -62,13 +62,23 @@
 1. **代理必须独立安装并运行**：本插件**不打包**第三方代理 workbuddy2api。
    请在你的机器上单独安装并启动它（见下方「安装代理」），它把 WorkBuddy/CodeBuddy
    的私有协议转成标准 OpenAI chat-completions 格式。
-2. 代理必须跑在 **workbuddy2api 主分支源码**上，不能用 PyPI 的 2.0.3：
-   旧版缺少 `X-Product-Code` / Genie-IDE 等请求头，登录会在最后一步 401。
+2. 代理版本需 **`workbuddy2api >= 2.0.4`**（推荐直接从 PyPI 装，
+   见下方「安装代理」）：
+   - **2.0.3 及更早不可用**：缺少 `X-Product-Code` / Genie-IDE 等请求头与
+     企业认证头（`_enterprise_headers` / `X-Domain`），登录会在最后一步 401；
+   - **2.0.4 已包含该修复**（"修复登录账户轮询与企业认证 headers 传递"），
+     登录成功；GitHub `main` 当前与 2.0.4 内容一致，两者皆可。
 3. 登录使用**插件内置的 `login_workbuddy.py`**（本包自带，依赖系统 `python3`，
    纯标准库，Python 3.7+ 即可），**不需要**代理自带的 `--login`（VSCode platform
    会 401）。
 4. 插件装入 profile 后需要**重启 `dsh web`** 才能加载新的 bundle（包括本小部件）。
 
+> **关于「🎁 签到」**：该功能依赖代理提供 `/v1/checkin-status` 与 `/v1/checkin`
+> 转发。截至 `workbuddy2api` 2.0.4，**代理并未实现这两个端点**（任何分支/PyPI
+> 版本都没有）。插件会自动探测：探测到 404 时隐藏签到入口、并且不再每天自动
+> 尝试，因此不会产生无效的失败记录。若将来代理补齐了这两个端点，签到入口会
+> 自动重新出现，无需升级插件。
+
 ---
 
 ## 安装插件
@@ -102,24 +112,35 @@ CLI 会把依赖写进 profile 并把 `dsh-llm-workbuddy` 追加到 `dsh.profile
 
 ### 全新机器 / 标准安装（任何能跑 Python 的机器）
 
-别人或你自己在**新机器**上用 npm 版插件时，按以下 3 步装代理：
+别人或你自己在**新机器**上用 npm 版插件时，推荐直接用 PyPI 装（版本 `>= 2.0.4`）：
 
 ```sh
 # 1. 安装 uv（本机 Python 工具，若已装可跳过）
 curl -LsSf https://astral.sh/uv/install.sh | sh
 
-# 2. 拉取 workbuddy2api 主分支源码
-git clone https://github.com/hawklithm/workbuddy2api.git
-cd workbuddy2api
+# 2. 安装代理（PyPI，需 >= 2.0.4；2.0.3 及更早缺登录所需请求头）
+uv tool install -U workbuddy2api
 
 # 3. 启动代理（监听 127.0.0.1:8787；先完成下方「登录」后再真正调用模型）
+workbuddy2api --desensitize \
+  --session-file ~/.codebuddy-session.json \
+  --log-file ~/.codebuddy-proxy.jsonl
+```
+
+<details>
+<summary>或者：从 GitHub 源码运行（等价，main 与 2.0.4 内容一致）</summary>
+
+```sh
+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
 ```
+</details>
 
-> 之后任何时候想重启代理，就在 `workbuddy2api` 目录里重跑上面第 3 条命令。
-> 若提示 `address already in use`，先停掉旧代理：
+> 之后任何时候想重启代理，重跑上面第 3 条命令即可（用 `uv tool` 安装时直接跑
+> `workbuddy2api ...`）。若提示 `address already in use`，先停掉旧代理：
 > `lsof -tiTCP:8787 -sTCP:LISTEN | xargs kill`，再重跑。
 
 ### 本仓库本地开发（可选快捷方式）
@@ -161,12 +182,34 @@ curl http://127.0.0.1:8787/v1/models # 模型列表（含 glm-5.2 / deepseek-v4-
    解析它打印的设备流链接（`authUrl`）返回给前端；前端用 `window.open` 在**新标签页**
    打开该登录页。
 4. 在新标签页用 WorkBuddy / CodeBuddy 账号（腾讯账号）完成扫码/授权。
-5. 胶囊会自动从每 5 秒轮询加快到每 2 秒（最多 30 次），一旦检测到
-   `.workbuddy/session.json` 的 `auth.expiresAt` 未过期且含 `accessToken`，
-   就切回 🟢 绿态，显示账号昵称。
+5. 胶囊会自动从每 5 秒轮询加快到每 2 秒（最多 30 次），一旦会话的过期时间
+   （见下方「登录态判定」）显示仍有效且含 `accessToken`，就切回绿态，
+   显示账号昵称。
 
 整个过程**不需要离开浏览器、不需要回终端**。
 
+> **🔑 重新登录（强制重登）**：胶囊 **⚙️ → 🔑 重新登录** 会带 `?force=1` 调用
+> 登录接口，**忽略本地会话判定**直接重跑设备流。该入口**始终可用**：本地判定
+> 依赖从会话文件推导的过期时间，只是启发式（见下），token 被提前吊销时它仍会
+> 显示"有效"，此时普通「登录」只会拿到 `alreadyLoggedIn`。不做条件显示是为了
+> 避免"判定错误 → 无法恢复"的耦合；判定不可靠时 title 会提示"当前建议执行"。
+
+### 登录态判定（插件如何判断"是否已登录"）
+
+代理写入的 `~/.codebuddy-session.json` **没有 `expiresAt` 字段**，所以插件按以下
+优先级推导过期时间，而不是把"字段缺失"当作"永不过期"：
+
+| 优先级 | 来源 | 说明 |
+|---|---|---|
+| 1 | `auth.expiresAt` | 本插件自带 `login_workbuddy.py` 写入；秒/毫秒都会归一化 |
+| 2 | `refreshToken` 的 JWT `exp` | 代理会自动 refresh accessToken，因此 **refreshToken 的有效期才是会话真正的边界** |
+| 3 | `accessToken` 的 JWT `exp` | 解码 JWT payload（不校验签名，只读声明） |
+| 4 | `auth.expiresIn` + 会话文件 mtime | 兜底；只会低估有效期，不会高估 |
+
+若以上都无法得出结果，接口会返回 `expiryKnown: false` 并给出
+`reloginRecommended: true`（而不是假装有效）；`expiresAtSource` 会说明用的是
+哪一来源，🔍 诊断面板里也会显示。
+
 ### 方式 B（传统）：在终端手动跑
 
 使用本包内置的登录脚本（纯标准库，依赖系统 `python3`）：
@@ -197,10 +240,13 @@ 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 |
+| `GET /api/workbuddy/status` | 读取会话文件（默认 `~/.codebuddy-session.json`，或配置的 `sessionFile`），**多源推导**会话过期时间（`expiresAt` → refreshToken/accessToken 的 JWT `exp` → `expiresIn`+mtime）判断会话是否有效，并 `fetch` 代理 `/health` 判断 `proxyUp`；返回 `{ sessionFile, authenticated, expiresAt, expiresAtSource, expiryKnown, expired, tokenPresent, reloginRecommended, account, proxyUp, tokenValid, loginScriptAvailable, checkin: { supported, autoEnabled, handledToday, lastResult } }`；非 GET 返回 405 |
+| `POST /api/workbuddy/login` | 已有有效会话且未指定 `?force=1` 时直接返回 `alreadyLoggedIn`；否则用系统 `python3` `spawn` 包内 `login_workbuddy.py --session-file <sessionFile>`，等它打印出设备流链接后返回 `{ authUrl, pending:true }`（最长等 15 秒，超时/脚本早退返回 `{ error }`）；设备流在后台继续，前端轮询 status 感知完成。`?force=1` 强制重跑登录（见「🔑 重新登录」）；非 POST 返回 405 |
+| `POST /api/workbuddy/diagnose` | **一键诊断**：真实探测健康状态，返回 `{ ok, session, health, chat, loginScriptAvailable, restartCommand }`。与 `/status` 不同，它除了探 `/health`，还会**真实发一次最小模型请求**（`chat.chatWorking`），能戳穿"胶囊显示成功但模型全 500"的假象；`session` 里带 `expiresAtSource` / `expiryKnown` / `reloginRecommended`；`ok:false` 时附带 `restartCommand`（自动区分本地 monorepo 布局与标准安装）；非 POST 返回 405 |
 | `GET /api/workbuddy/usage` | **用量统计**：读取本地 token 用量台账（`$DSH_HOME/llm-workbuddy/usage.jsonl`），返回 `{ today, byModel, total }`（今日/按模型/累计的 input/output tokens、请求次数，以及**积分消耗 `credit`**）；非 GET 返回 405 |
+| `GET /api/workbuddy/checkin` | **签到状态**：返回 `{ supported, handledToday, lastResult, official }`；`supported` 为三态——`true`（代理有签到接口）/ `false`（探测到 404/405，代理未实现）/ `null`（尚未探测出结论）。探测结果缓存 30 分钟；非 GET/POST 返回 405 |
+| `POST /api/workbuddy/checkin` | **立即签到**：透传代理 `/v1/checkin`（幂等，官方对已签到返回业务拒绝）。代理未实现签到接口时返回 `{ ok:false, supported:false, message }` 且**不写入任何失败记录** |
+| `POST /api/workbuddy/refresh-models` | 清空模型发现缓存并重读代理 `/v1/models`，同时发布 `llm/adapters-updated` 让模型选择器立即重载；返回 `{ ok, announced, count, models }` |
 
 > 会话文件与登录脚本路径的解析顺序：
 > 1. 配置里显式指定的 `sessionFile` / `loginScript`；
@@ -214,8 +260,13 @@ Web 登录后终端脚本也读得到同一份会话。
 - 每 **5 秒** `GET /api/workbuddy/status`；点「登录」后加快到每 **2 秒**轮询、
   最多 30 次，直到 `authenticated:true`。
 - 胶囊外面只显示一个 **⚙️ 设置** 按钮（带 title「WorkBuddy 设置」）。点击展开菜单，
-  内含四个带明确 title 的操作：**🔍 诊断 / 📊 用量 / 🎁 签到 / 🔄 刷新模型**；
+  内含 **🔍 诊断 / 📊 用量 / 🎁 签到（按条件）/ 🔄 刷新模型 / 🔑 重新登录**；
   点击页面空白或选中某项后菜单自动收起。
+- **🎁 签到**：**仅当代理真的实现了签到接口时才出现**（`checkin.supported === true`）。
+  `workbuddy2api` 至今没有 `/v1/checkin-status` / `/v1/checkin`，此时入口不显示，
+  也不会每天自动尝试——避免"点了必然 404"和长期挂着的失败记录。
+- **🔑 重新登录**：**始终显示**，点击后带 `?force=1` 强制重跑设备流，忽略本地
+  会话判定（详见「登录态判定」）。
 - **🔍 诊断**：点它 `POST /api/workbuddy/diagnose`，弹出一个面板
   显示**真实健康状态**（登录、会话文件、代理进程、登录令牌、模型能否出字），
   发现问题时附带**可复制的重启命令**（一键复制到终端执行）。
@@ -318,8 +369,13 @@ DSH 的 `dsh.client` 机制只要求 `package.json` 里：
 | 胶囊一直 `…`（加载中） | `GET /api/workbuddy/status` 失败 → 确认 `dsh web` 在跑、端口正确 |
 | 胶囊红 + `代理未运行` | workbuddy2api 代理没起或挂了 → 按「安装代理」章节启动 |
 | 胶囊显示登录成功但模型用不了 | 典型的"代理进程活着但指向旧路径/文件缺失"假象（`/health` 仍显示 ok）。点胶囊 **🔍 诊断**，看 `模型出字` 是否失败；按面板给出的重启命令重启代理 |
-| 点「登录」没反应 / 按钮灰 | `loginScriptAvailable:false` → 包内 `login_workbuddy.py` 缺失或系统无 `python3`；检查安装 |
-| 新标签页打开后登录完成，胶囊仍是红 | 会话文件（默认 `~/.codebuddy-session.json`）未刷新或 `expiresAt` 已过期 → 刷新页面或重跑登录 |
+| 点「登录」没反应 / 按钮灰 | `loginScriptAvailable:false` → 包内 `login_workbuddy.py` 缺失或系统无 `python3`；检查安装。若返回了 `error`（脚本 15 秒内没打印授权链接、或退出码非 0），页面会弹出具体原因 |
+| 点「登录」弹出 `alreadyLoggedIn`，但 token 实际已失效 | 本地判定是启发式（会话文件可能没有 `expiresAt`）→ 用 **⚙️ → 🔑 重新登录** 强制重跑登录 |
+| 胶囊绿但所有模型 401 | accessToken/refreshToken 都已过期但判定未察觉 → **⚙️ → 🔑 重新登录**；或先 **🔍 诊断** 看「令牌过期」一行 |
+| 设置菜单里没有「🎁 签到」 | **正常现象**：该代理未实现 `/v1/checkin-status` / `/v1/checkin`（`workbuddy2api` 至今未提供），插件探测到 404 后自动隐藏入口并停止每日自动尝试 |
+| 设置菜单里的「🔑 重新登录」 | 该入口**始终可用**；判定结果不可靠时 title 会提示"当前建议执行" |
+| 新标签页打开后登录完成，胶囊仍是红 | 会话文件（默认 `~/.codebuddy-session.json`）未刷新或已过期 → 刷新页面或点「🔑 重新登录」 |
+| 代理版本报错 / 登录最后一步 401 | 代理过旧（< 2.0.4，缺 `X-Product-Code`、`_enterprise_headers` 等）→ `uv tool install -U workbuddy2api` 升级到 >= 2.0.4 |
 | 启动 `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 |
 | 模型请求 `TRANSPORT` 错误 | 代理未运行或端口不对（连接被拒绝） |
 
@@ -336,8 +392,13 @@ DSH 的 `dsh.client` 机制只要求 `package.json` 里：
   会透传给代理；若某模型平台侧只接受平台默认、忽略该参数，则退化为平台默认强度，不影响出字。
 - 代理未运行时，模型请求会以 `TRANSPORT` 错误快速失败（连接被拒绝）；但状态
   小组件本身不依赖代理——代理挂了它仍能显示「代理未运行」并允许触发登录。
-- 登录态有效期由 WorkBuddy 云端决定；过期后胶囊变红，重新点「登录」即可，
-  代理无需重启。
+- 登录态有效期由 WorkBuddy 云端决定。插件会尽力从会话文件推导过期时间
+  （见「登录态判定」），但**推导不出时只能标记为"未知"而不是失败**；真正的
+  失效检测以一次真实模型请求（🔍 诊断的「模型出字」）为准，恢复手段是
+  **🔑 重新登录**，代理无需重启。
+- **签到功能依赖代理实现 `/v1/checkin-status` 与 `/v1/checkin`**；截至
+  `workbuddy2api` 2.0.4（含 GitHub `main`、`dsh`、`codex` 各分支）均未提供，
+  因此默认不显示签到入口。代理侧补齐后无需升级插件，入口会自动出现。
 
 ---
 

package/lib/client.js

@@ -128,25 +128,36 @@ function runWidget() {
     }
     // 只外显一个设置按钮：点击展开诊断/用量/签到/刷新模型四个操作。
     html += '<span class="wb-settle">' +
-      '<button class="wb-setbtn" id="wb-settings" title="WorkBuddy 设置（诊断 / 用量 / 签到 / 刷新模型）">⚙️</button>';
+      '<button class="wb-setbtn" id="wb-settings" title="WorkBuddy 设置（诊断 / 用量 / 签到 / 刷新模型 / 重新登录）">⚙️</button>';
     if (menuOpen) {
-      // 签到按钮：✅ 今日已处理 / 🎁 今日未处理（点击立即领取；10 点后也会自动领取）。
+      var items =
+        '<button class="wb-item" id="wb-diagnose" title="一键诊断：真实探测登录、代理、令牌与模型出字状态">🔍 诊断</button>' +
+        '<button class="wb-item" id="wb-usage" title="用量统计：查看今日/累计 token 与积分消耗、按模型明细">📊 用量</button>';
+      // 签到按钮只在此代理真的实现了签到接口时出现。workbuddy2api 从未提供
+      // /checkin-status 与 /checkin，显示一个必然 404 的入口只会误导用户；
+      // supported 为 null 表示还没探测出结论（代理未启动等），此时保守隐藏。
       var ck = status.checkin;
-      var ckTitle = "今日还没签到（每天 10 点后自动领取）\n点击立即领取";
-      var ckIcon = "🎁";
-      var ckDisabled = "";
-      if (ck) {
+      if (ck && ck.supported === true) {
+        // ✅ 今日已处理 / 🎁 今日未处理（点击立即领取；10 点后也会自动领取）。
+        var ckTitle = "今日还没签到（每天 10 点后自动领取）\n点击立即领取";
+        var ckIcon = "🎁";
+        var ckDisabled = "";
         var ckMsg = ck.lastResult && ck.lastResult.message ? "\n" + ck.lastResult.message : "";
         ckTitle = ck.handledToday ? "今日已处理签到" + ckMsg : ckTitle;
         ckIcon = ck.handledToday && ck.lastResult && ck.lastResult.ok ? "✅" : "🎁";
         ckDisabled = ck.handledToday ? " disabled" : "";
+        items += '<button class="wb-item" id="wb-checkin" title="' + esc(ckTitle) + '"' + ckDisabled + '>' + ckIcon + " 签到</button>";
       }
-      html += '<span class="wb-menu">' +
-        '<button class="wb-item" id="wb-diagnose" title="一键诊断：真实探测登录、代理、令牌与模型出字状态">🔍 诊断</button>' +
-        '<button class="wb-item" id="wb-usage" title="用量统计：查看今日/累计 token 与积分消耗、按模型明细">📊 用量</button>' +
-        '<button class="wb-item" id="wb-checkin" title="' + esc(ckTitle) + '"' + ckDisabled + '>' + ckIcon + " 签到</button>" +
-        '<button class="wb-item" id="wb-models" title="刷新模型列表：从代理重读模型并让模型选择器立即重载">🔄 刷新模型</button>' +
-        "</span>";
+      items +=
+        '<button class="wb-item" id="wb-models" title="刷新模型列表：从代理重读模型并让模型选择器立即重载">🔄 刷新模型</button>';
+      // 强制重登入口**始终存在**：本地判定是从会话文件推导的启发式（代理写入
+      // 的 session.json 根本没有 expiresAt），token 在有效期内被吊销时判定仍是
+      // "有效"，此时普通「登录」只会拿到 alreadyLoggedIn。若把入口做成有条件的，
+      // "判定错误 → 无法恢复"的耦合就依然存在，所以这里不做条件渲染，只在
+      // 判定不可靠时用 title 提示"建议"。
+      items += '<button class="wb-item" id="wb-relogin" title="强制重新登录：忽略本地会话判定，重跑设备流登录' +
+        (status.reloginRecommended ? '（当前建议执行：本地判定不可靠）' : '') + '">🔑 重新登录</button>';
+      html += '<span class="wb-menu">' + items + "</span>";
     }
     html += "</span>";
     if (!status.proxyUp) html += '<span class="wb-warn">代理未运行</span>';
@@ -170,6 +181,8 @@ function runWidget() {
     if (ckBtn) ckBtn.addEventListener("click", function () { menuOpen = false; render(); onCheckin(); });
     var mdBtn = host.querySelector("#wb-models");
     if (mdBtn) mdBtn.addEventListener("click", function () { menuOpen = false; render(); onRefreshModels(); });
+    var rlBtn = host.querySelector("#wb-relogin");
+    if (rlBtn) rlBtn.addEventListener("click", function () { menuOpen = false; render(); onLogin(true); });
   }
 
   // 点击页面其它位置关闭设置菜单。
@@ -189,15 +202,27 @@ function runWidget() {
       .catch(function () { /* leave last known state on screen */ });
   }
 
-  function onLogin() {
+  /**
+   * 触发登录。`force` 为真时忽略本地会话判定，强制重跑设备流——用于
+   * 本地判定为"仍有效"但 token 实际已失效（被吊销）的场景，否则用户点了
+   * 登录只会拿到 alreadyLoggedIn，没有任何恢复手段。
+   */
+  function onLogin(force) {
     if (busy) return;
     busy = true;
     render();
-    fetch("/api/workbuddy/login", { method: "POST" })
+    fetch("/api/workbuddy/login" + (force ? "?force=1" : ""), { method: "POST" })
       .then(function (r) { return r.json(); })
       .then(function (data) {
         if (data && data.authUrl) {
           window.open(data.authUrl, "_blank", "noopener,noreferrer");
+        } else if (data && data.error) {
+          // e.g. no python3, or no URL within the timeout: surface it instead
+          // of silently doing nothing (the old "点了没反应" symptom).
+          busy = false;
+          render();
+          window.alert("WorkBuddy 登录失败：" + data.error);
+          return;
         }
         var i = 0;
         var tick = function () {
@@ -233,10 +258,19 @@ function runWidget() {
         var lines = [];
         lines.push("登录状态: " + (d.session && d.session.authenticated ? "有效" : "无效"));
         lines.push("会话文件: " + (d.session && d.session.file ? "存在" : "缺失"));
+        // 过期时间是多源推导出来的（代理写入的 session.json 没有 expiresAt），
+        // 把来源一并显示，便于判断"未知"到底是没探测到还是真的没写。
+        var exp = d.session && d.session.expiresAt;
+        lines.push("令牌过期: " + (exp
+          ? fmtExpiry(exp) + "（来源: " + ((d.session && d.session.expiresAtSource) || "?") + "）"
+          : "未知（无法从会话文件推导）"));
         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);
+        if (d.session && d.session.reloginRecommended) {
+          lines.push("提示: 建议点 ⚙️ → 🔑 重新登录（本地判定不可靠，可强制重跑登录）");
+        }
         var body = el.querySelector(".wb-panel-body");
         var html = '<div style="font-weight:700;margin-bottom:4px">' + esc(title) + '</div>' +
           '<div>' + lines.map(esc).join("\n") + "</div>";
@@ -351,6 +385,9 @@ function runWidget() {
     fetch("/api/workbuddy/checkin", { method: "POST" })
       .then(function (r) { return r.json(); })
       .then(function (d) {
+        // 代理没实现签到接口：刷新状态让入口按 supported 自行消失，
+        // 而不是留一个点了就报错的按钮。
+        if (d && d.supported === false) { refresh(); return; }
         btn.textContent = d && d.ok ? "✅" : "🎁";
         btn.title = (d && d.message) || "签到结果未知";
         refresh();

package/lib/index.js

@@ -17,7 +17,7 @@
  * to a shipped static catalog when the proxy is not running.
  */
 import { spawn } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, appendFileSync, openSync, truncateSync, writeSync, closeSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, appendFileSync, openSync, statSync, truncateSync, writeSync, closeSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import z from "@deepseek-ai/schemastery";
@@ -1051,6 +1051,8 @@ const CHECKIN_FILE_NAME = "checkin.json";
 const CHECKIN_INTERVAL_MS = 30 * 60_000;
 /** Request timeout for the proxy checkin endpoints. */
 const CHECKIN_TIMEOUT_MS = 10_000;
+/** How long the login route waits for the device-flow URL before giving up. */
+const LOGIN_URL_TIMEOUT_MS = 15_000;
 
 /** Resolve the checkin state file path (same convention as usageLedgerPath). */
 function checkinStatePath() {
@@ -1092,7 +1094,14 @@ function localDateStr(date = new Date()) {
 
 /**
  * Call a proxy checkin endpoint. `method` defaults to GET (status probe);
- * claiming passes "POST". Returns the parsed body or an error shape.
+ * claiming passes "POST". Returns the parsed body (with the HTTP status under
+ * `httpStatus`) or an error shape.
+ *
+ * `missing: true` marks the specific "this proxy does not implement the
+ * checkin API" case (HTTP 404/405 on the probe). It is kept distinct from a
+ * transport error because the two need opposite handling: a missing endpoint is
+ * permanent for the running proxy (hide the feature), a transport error is
+ * transient (retry later).
  */
 async function proxyCheckinCall(baseURL, path, method = "GET") {
   const controller = new AbortController();
@@ -1105,9 +1114,25 @@ async function proxyCheckinCall(baseURL, path, method = "GET") {
     });
     const body = await response.json().catch(() => null);
     if (!response.ok) {
-      return { error: `HTTP ${response.status} (${method} ${path})`, ...(body ? { body } : {}) };
+      const missing = response.status === 404 || response.status === 405;
+      return {
+        httpStatus: response.status,
+        error: `HTTP ${response.status} (${method} ${path})`,
+        ...(missing ? { missing: true } : {}),
+        // Body fields ride along both flattened and under `body`: the old shape
+        // kept them under `body`, and `runCheckinOnce` still reads
+        // `claim.body.detail` for its failure message.
+        ...(body !== null && typeof body === "object" ? body : {}),
+        ...(body !== null && typeof body === "object" ? { body } : {}),
+      };
     }
-    return body ?? { error: "empty response" };
+    // `httpStatus` rides along even on success so callers can classify the
+    // endpoint by HTTP status rather than by "did an error string appear".
+    // It must NOT be named `status`: the proxy's own checkin body already has a
+    // `status: "ok"` field that would clobber it when spread.
+    return body !== null && typeof body === "object"
+      ? { httpStatus: response.status, ...body }
+      : { httpStatus: response.status, error: "empty response" };
   } catch (error) {
     return { error: String(error?.cause?.message ?? error?.message ?? error) };
   } finally {
@@ -1115,6 +1140,53 @@ async function proxyCheckinCall(baseURL, path, method = "GET") {
   }
 }
 
+/**
+ * Cached answer to "does this proxy implement the checkin API at all?".
+ *
+ * workbuddy2api has never shipped `/checkin-status` / `/checkin` on any branch
+ * or PyPI release, so the plugin probes once (and then at most every
+ * {@link CHECKIN_CAPABILITY_TTL_MS}) and hides the feature instead of
+ * hammering a 404 and recording a fresh failure every day.
+ *
+ * `supported` is tri-state: `true` (endpoint answered, whatever the status),
+ * `false` (404/405 — the route does not exist), `null` (never probed, or the
+ * proxy was unreachable so the answer is genuinely unknown).
+ */
+const CHECKIN_CAPABILITY_TTL_MS = 30 * 60_000;
+let _checkinCapability = { supported: null, error: null, checkedAt: 0 };
+
+/** Last known checkin-support verdict, without touching the network. */
+function checkinCapability() {
+  return _checkinCapability;
+}
+
+/** Probe checkin support, reusing the cached verdict until it goes stale. */
+async function probeCheckinCapability(baseURL, options = {}) {
+  const { force = false } = options;
+  const cached = _checkinCapability;
+  if (!force && cached.checkedAt > 0 && Date.now() - cached.checkedAt < CHECKIN_CAPABILITY_TTL_MS) {
+    return cached;
+  }
+  const probe = await proxyCheckinCall(baseURL, "/checkin-status");
+  // Classify by HTTP status, not by the presence of an error string:
+  // - 404/405 → the route does not exist on this proxy (conclusive);
+  // - any other HTTP status (including 401/503 from an unauthenticated proxy)
+  //   proves the endpoint exists, so the feature stays offered;
+  // - no status at all → transport failure; the answer is unknown, and a
+  //   transient outage must never permanently hide the feature.
+  const supported = probe?.missing === true
+    ? false
+    : typeof probe?.httpStatus === "number"
+      ? true
+      : null;
+  _checkinCapability = {
+    supported,
+    error: supported === false ? probe.error : null,
+    checkedAt: Date.now(),
+  };
+  return _checkinCapability;
+}
+
 /** Whether an upstream claim rejection means "already claimed today". */
 function alreadyClaimedMessage(msg) {
   return typeof msg === "string" && /(已签到|已经签到|already)/i.test(msg);
@@ -1123,6 +1195,7 @@ function alreadyClaimedMessage(msg) {
 /**
  * Run one auto-claim pass. Idempotent per local calendar day:
  * - before `checkinAfterHour` (default 10:00) local time: no-op;
+ * - proxy does not implement the checkin API (404/405): no-op, no state change;
  * - already handled today (persisted state): no-op;
  * - official status says already checked in: mark handled, done;
  * - activity not open (no status data): mark handled so we stop retrying today;
@@ -1131,6 +1204,16 @@ function alreadyClaimedMessage(msg) {
  * @returns the resulting state snapshot, or undefined when skipped/in-flight.
  */
 async function runCheckinOnce(baseURL, config, logger) {
+  // Learn whether this proxy can check in at all *before* any gate: the verdict
+  // is what the widget uses to decide whether to offer the 「签到」 entry, so it
+  // must be populated on startup — and also when auto-claim is disabled, where
+  // this pass does nothing else. The probe is cached (30 min), so this is at
+  // most one cheap GET per scheduler tick.
+  const capability = await probeCheckinCapability(baseURL);
+  if (capability.supported === false) {
+    logger?.debug?.(`dsh-llm-workbuddy: checkin API unavailable on this proxy (${capability.error})`);
+    return undefined;
+  }
   if (!config.autoCheckin) return undefined;
   const now = new Date();
   if (now.getHours() < config.checkinAfterHour) return undefined;
@@ -1141,6 +1224,13 @@ async function runCheckinOnce(baseURL, config, logger) {
   runCheckinOnce._inFlight = true;
   try {
     const status = await proxyCheckinCall(baseURL, "/checkin-status");
+    // The probe can disagree with the cached verdict (older proxy, route added
+    // mid-flight): trust the live 404 and stop instead of recording a failure.
+    if (status?.missing === true) {
+      _checkinCapability = { supported: false, error: status.error, checkedAt: Date.now() };
+      logger?.debug?.(`dsh-llm-workbuddy: checkin API unavailable on this proxy (${status.error})`);
+      return undefined;
+    }
     const data = status?.upstream?.data;
     if (!data) {
       // Activity closed / proxy unreachable / not authenticated: stop for today.
@@ -1259,28 +1349,135 @@ function resolveLoginPaths(config) {
   return { sessionFile, loginScript };
 }
 
+/**
+ * Decode a JWT payload without verifying its signature. The session's tokens
+ * are issued by the WorkBuddy IdP and we only read claims (`exp`) to recover an
+ * expiry the writer omitted — never to trust the token. Returns null for an
+ * opaque (non-JWT) or malformed token.
+ */
+function decodeJwtPayload(token) {
+  if (typeof token !== "string") return null;
+  const parts = token.split(".");
+  if (parts.length !== 3) return null;
+  try {
+    const json = Buffer.from(parts[1].replace(/-/g, "+").replace(/_/g, "/"), "base64").toString("utf-8");
+    const claims = JSON.parse(json);
+    return claims !== null && typeof claims === "object" ? claims : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Normalize a numeric instant to epoch milliseconds. Values below this floor
+ * cannot be a millisecond epoch this century, so the writer must have used
+ * seconds (the IdP's own unit for JWT `exp`).
+ */
+function toEpochMs(value) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) return null;
+  return value < 1e11 ? Math.round(value * 1000) : value;
+}
+
+/** A JWT's `exp` claim, in epoch ms. Null when absent/opaque. */
+function jwtExpiresAt(token) {
+  return toEpochMs(decodeJwtPayload(token)?.exp);
+}
+
+/**
+ * Derive when the stored session actually stops working.
+ *
+ * The proxy (workbuddy2api) writes the IdP token payload verbatim, which has no
+ * `expiresAt` — judging "no expiresAt ⇒ still valid" made the login state
+ * permanently green. Sources are tried most authoritative first:
+ *
+ *   1. the **refresh** token's JWT `exp` — the proxy refreshes an expired access
+ *      token automatically, so the refresh token's lifetime is what really
+ *      bounds the session. Judging by the access token alone would turn the
+ *      capsule red while requests still succeed;
+ *   2. `auth.expiresAt` — written by this plugin's own login script (also the
+ *      access token's lifetime, hence below the refresh bound);
+ *   3. the **access** token's JWT `exp`;
+ *   4. `auth.expiresIn` counted from the session file's mtime — the last resort
+ *      for opaque tokens; the mtime is refreshed whenever the proxy re-writes
+ *      the session, so this can only under-estimate, never over-estimate.
+ *
+ * Yielding no instant at all means the validity is genuinely unknown
+ * (`source: null`) and must be reported as such rather than assumed valid.
+ */
+function resolveSessionExpiry(raw, sessionFile) {
+  const accessJwt = jwtExpiresAt(raw?.auth?.accessToken);
+  const refreshJwt = jwtExpiresAt(raw?.auth?.refreshToken);
+  const explicit = toEpochMs(raw?.auth?.expiresAt);
+
+  if (refreshJwt !== null) {
+    return { accessExpiresAt: accessJwt ?? explicit, refreshExpiresAt: refreshJwt, expiresAt: refreshJwt, source: "jwt-refresh" };
+  }
+  if (explicit !== null) {
+    return { accessExpiresAt: explicit, refreshExpiresAt: null, expiresAt: explicit, source: "expiresAt" };
+  }
+  if (accessJwt !== null) {
+    return { accessExpiresAt: accessJwt, refreshExpiresAt: null, expiresAt: accessJwt, source: "jwt" };
+  }
+
+  const expiresIn = raw?.auth?.expiresIn;
+  if (typeof expiresIn === "number" && Number.isFinite(expiresIn) && expiresIn > 0) {
+    try {
+      const fromMtime = Math.round(statSync(sessionFile).mtimeMs) + expiresIn * 1000;
+      return { accessExpiresAt: fromMtime, refreshExpiresAt: null, expiresAt: fromMtime, source: "expiresIn" };
+    } catch {
+      // fall through to "unknown"
+    }
+  }
+
+  return { accessExpiresAt: null, refreshExpiresAt: null, expiresAt: null, source: null };
+}
+
 /**
  * Read the local WorkBuddy session file and derive its validity. Returns a
  * normalized status object the Web widget polls. Never throws — missing or
  * malformed state is reported as `authenticated: false` so the UI can prompt.
+ *
+ * `expiresAt` is the instant that bounds the session (see
+ * {@link resolveSessionExpiry}); `expiryKnown: false` means no expiry could be
+ * derived, and `reloginRecommended` is the recovery hint the widget shows.
  */
 function readSessionStatus(sessionFile) {
-  if (!existsSync(sessionFile)) {
-    return { sessionFile: false, authenticated: false, expiresAt: null, account: null };
-  }
+  const empty = {
+    sessionFile: false,
+    authenticated: false,
+    expiresAt: null,
+    accessExpiresAt: null,
+    refreshExpiresAt: null,
+    expiresAtSource: null,
+    expiryKnown: false,
+    expired: false,
+    tokenPresent: false,
+    reloginRecommended: true,
+    account: null,
+  };
+  if (!existsSync(sessionFile)) return empty;
   try {
     const raw = JSON.parse(readFileSync(sessionFile, "utf-8"));
-    const expiresAt = raw?.auth?.expiresAt ?? null;
-    const now = Date.now();
-    const expired = expiresAt !== null && expiresAt <= now;
+    const tokenPresent = Boolean(raw?.auth?.accessToken);
+    const expiry = resolveSessionExpiry(raw, sessionFile);
+    const expired = expiry.expiresAt !== null && expiry.expiresAt <= Date.now();
     return {
       sessionFile: true,
-      authenticated: !expired && Boolean(raw?.auth?.accessToken),
-      expiresAt,
+      authenticated: tokenPresent && !expired,
+      expiresAt: expiry.expiresAt,
+      accessExpiresAt: expiry.accessExpiresAt,
+      refreshExpiresAt: expiry.refreshExpiresAt,
+      expiresAtSource: expiry.source,
+      expiryKnown: expiry.expiresAt !== null,
+      expired,
+      tokenPresent,
+      // The login button must stay a way out: no token, a passed expiry, or an
+      // expiry we cannot derive all mean "offer a re-login".
+      reloginRecommended: !tokenPresent || expired || expiry.expiresAt === null,
       account: raw?.account ?? null,
     };
   } catch {
-    return { sessionFile: true, authenticated: false, expiresAt: null, account: null };
+    return { ...empty, sessionFile: true };
   }
 }
 
@@ -1383,9 +1580,9 @@ function diagnoseRestartCommand() {
     "# 停掉旧代理（若 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 \\",
+    "# 安装/升级代理（需 >= 2.0.4；详见 README「安装代理」）",
+    "uv tool install -U workbuddy2api",
+    "workbuddy2api --desensitize \\",
     "  --session-file ~/.codebuddy-session.json --log-file ~/.codebuddy-proxy.jsonl",
   ].join("\n");
 }
@@ -1431,8 +1628,11 @@ function registerWorkbuddyRoutes(ctx, config, adapter, providersHandle) {
         const session = readSessionStatus(sessionFile);
         const proxy = await probeProxy(baseURL);
         // Checkin digest comes from the persisted state only — never block the
-        // 5s status poll with an upstream call.
+        // 5s status poll with an upstream call. Support comes from the cached
+        // capability verdict (also populated by the scheduler and the checkin
+        // route), so the widget can hide an entry this proxy cannot serve.
         const checkinState = readCheckinState();
+        const capability = checkinCapability();
         const today = localDateStr();
         res.writeHead(200, { "content-type": "application/json" });
         res.end(JSON.stringify({
@@ -1440,6 +1640,7 @@ function registerWorkbuddyRoutes(ctx, config, adapter, providersHandle) {
           ...proxy,
           loginScriptAvailable: existsSync(loginScript),
           checkin: {
+            supported: capability.supported,
             autoEnabled: config?.autoCheckin ?? true,
             handledToday: checkinState.handledDate === today,
             lastResult: checkinState.lastResult ?? null,
@@ -1461,9 +1662,20 @@ function registerWorkbuddyRoutes(ctx, config, adapter, providersHandle) {
           res.end(JSON.stringify({ error: "login_workbuddy.py not found" }));
           return;
         }
+        // `force` re-runs the device flow even when the stored session still
+        // looks valid. Status judgement is a heuristic (the proxy's session
+        // file carries no `expiresAt`), so the login button must never be a
+        // dead end when a token is wrong/revoked but still not-yet-expired.
+        let force = false;
+        try {
+          const url = new URL(req.url ?? "/", "http://127.0.0.1");
+          force = url.searchParams.get("force") === "1" || url.searchParams.get("force") === "true";
+        } catch {
+          // malformed URL: treat as non-forced
+        }
         // Existing session is fine; no need to re-run the flow.
         const existing = readSessionStatus(sessionFile);
-        if (existing.authenticated) {
+        if (existing.authenticated && !force) {
           res.writeHead(200, { "content-type": "application/json" });
           res.end(JSON.stringify({ alreadyLoggedIn: true, authUrl: null, ...existing }));
           return;
@@ -1473,17 +1685,55 @@ function registerWorkbuddyRoutes(ctx, config, adapter, providersHandle) {
         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];
+
+        // The device-flow URL is printed as soon as the flow starts (before the
+        // long poll for completion), but it is never available synchronously —
+        // answering immediately always returned `authUrl: null`, which the
+        // widget turned into "clicked login, nothing happened". Resolve on the
+        // first URL, on child exit, or on the timeout, whichever comes first.
+        const outcome = await new Promise((resolve) => {
+          let done = false;
+          const finish = (value) => {
+            if (done) return;
+            done = true;
+            clearTimeout(timer);
+            resolve(value);
+          };
+          // Bounded wait. This timer is deliberately NOT unref'd: it is the only
+          // thing guaranteeing the route answers even when nothing else holds
+          // the event loop open. It is cleared the moment the child answers, so
+          // it never outlives the request.
+          const timer = setTimeout(
+            () => finish({ authUrl: null, error: `登录脚本未在 ${Math.round(LOGIN_URL_TIMEOUT_MS / 1000)} 秒内输出授权链接（检查系统 python3 是否可用）` }),
+            LOGIN_URL_TIMEOUT_MS,
+          );
+          child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString();
+            const m = stdout.match(/https?:\/\/\S+/);
+            if (m) finish({ authUrl: m[0] });
+          });
+          child.stderr.on("data", () => {});
+          child.on("error", (error) => {
+            finish({ authUrl: null, error: `无法启动 python3：${String(error?.message ?? error)}` });
+          });
+          child.on("close", (code) => {
+            finish({
+              authUrl: null,
+              error: code === 0
+                ? "登录脚本已结束，但没有输出授权链接"
+                : `登录脚本异常退出（exit code ${code}）`,
+            });
+          });
+          // Keep the pipe drained so a chatty child cannot block on a full
+          // stdout buffer after we have answered.
+          child.stdout.resume();
+          child.unref?.();
         });
-        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(outcome.authUrl === null
+          ? { authUrl: null, pending: false, error: outcome.error }
+          : { authUrl: outcome.authUrl, pending: true }));
       },
     }));
     webCtx.effect(() => webServer.register({
@@ -1506,7 +1756,15 @@ function registerWorkbuddyRoutes(ctx, config, adapter, providersHandle) {
         res.writeHead(200, { "content-type": "application/json" });
         res.end(JSON.stringify({
           ok,
-          session: { file: session.sessionFile, authenticated: session.authenticated, expiresAt: session.expiresAt },
+          session: {
+            file: session.sessionFile,
+            authenticated: session.authenticated,
+            expiresAt: session.expiresAt,
+            expiresAtSource: session.expiresAtSource,
+            expiryKnown: session.expiryKnown,
+            refreshExpiresAt: session.refreshExpiresAt,
+            reloginRecommended: session.reloginRecommended,
+          },
           health,
           chat,
           loginScriptAvailable: existsSync(loginScript),
@@ -1563,8 +1821,14 @@ function registerWorkbuddyRoutes(ctx, config, adapter, providersHandle) {
           const state = readCheckinState();
           const upstream = await proxyCheckinCall(baseURL, "/checkin-status");
           const data = upstream?.upstream?.data ?? null;
+          // A 404/405 proves the running proxy has no checkin API at all; the
+          // widget hides the entry rather than offering a button that can only
+          // fail.
+          const supported = upstream?.missing === true ? false : true;
+          _checkinCapability = { supported, error: supported ? null : upstream.error, checkedAt: Date.now() };
           res.writeHead(200, { "content-type": "application/json" });
           res.end(JSON.stringify({
+            supported,
             handledToday: state.handledDate === localDateStr(),
             lastResult: state.lastResult ?? null,
             official: data === null ? null : {
@@ -1587,10 +1851,24 @@ function registerWorkbuddyRoutes(ctx, config, adapter, providersHandle) {
           return;
         }
         const claim = await proxyCheckinCall(baseURL, "/checkin", "POST");
+        if (claim?.missing === true) {
+          // Not a failure to report: this proxy simply has no checkin API
+          // (workbuddy2api never shipped one). Mark it unsupported so the UI
+          // hides the entry and stop writing failure records.
+          _checkinCapability = { supported: false, error: claim.error, checkedAt: Date.now() };
+          res.writeHead(200, { "content-type": "application/json" });
+          res.end(JSON.stringify({
+            ok: false,
+            supported: false,
+            message: `当前代理未实现签到接口（${claim.error}）`,
+          }));
+          return;
+        }
         const payload = claim?.upstream?.data;
         const ok = Boolean(payload) || alreadyClaimedMessage(claim?.upstream?.msg);
         const result = {
           ok,
+          supported: true,
           message: ok
             ? payload?.credit !== undefined
               ? `签到成功：+${payload.credit} 积分`
@@ -1620,6 +1898,28 @@ function config_baseURL() {
 
 // #endregion
 
+// #region internals (exported for tests)
+
+/**
+ * Internals exposed for the test suite only. They are not part of the plugin's
+ * public surface and may change without a major bump.
+ */
+export const __internals = {
+  readSessionStatus,
+  resolveSessionExpiry,
+  decodeJwtPayload,
+  runCheckinOnce,
+  probeCheckinCapability,
+  checkinCapability,
+  resetCheckinCapability: () => { _checkinCapability = { supported: null, error: null, checkedAt: 0 }; },
+  registerWorkbuddyRoutes,
+  // The routes read the module-level proxy URL that `apply()` commits, so a
+  // test that mounts them directly must point it somewhere first.
+  setBaseURL: (value) => { _baseURL = value; },
+};
+
+// #endregion
+
 // #region plugin
 
 /**

package/package.json

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