# 按症状排查(Troubleshooting) 本文件是**按你看到的现象**组织的入口,不是按主题。其他文档回答"这个功能怎么设计的", 这里回答"我看到 X,该怎么办"。 **为什么要有这个文件**(PITFALLS §25「形式门禁全绿,不代表文档说了实话」的另一半):本仓库的 PITFALLS 里每一条坑都写了**现象**(条数见该文件头,别在这里写死),文档索引却只按**主题**组织("何时查 ROADMAP")。于是把症状变成主题 需要有人**已经知道答案**——而那正是最不需要看文档的人。一句"额度那栏一直是空的"在按主题的 索引里无处落脚,只能靠全文搜索碰运气。所以症状在这里有一等公民的地位:有稳定症状码、能被 doctor 报出来、能双向钉住。 > **给 agent**:每条症状都有一个稳定的症状码(`quota-empty`、`needs-login`…),也出现在 > `npm run doctor --json` 的 `symptoms` 字段里。先跑 doctor 拿到症状码,再用下表跳到对应条目。 > 症状码的真源是 `src/host/codes.ts` 的 `SYMPTOM`,本文件的条目与之由 > `test/doctor.test.mjs` 双向钉住——**症状码出现在这里却没进 `SYMPTOM`(或反之),门禁即红**。 **先分清是哪一半的问题**(决定去哪找日志):本插件是 Host 半边 + 浏览器半边,登录/节流/注册 失败在 Host(看 `dsh web` 终端 stdout 或 `$DSH_HOME/logs/sensenova-login-*.json`),面板渲染 问题在浏览器 bundle(多数被当数据渲染成面板文本,不进 F12)。详见 [SETUP.md](./SETUP.md) §7。 --- ## A. 额度 / 积分栏 ### A1. 额度栏是空的或显示"不可用" {#a1-额度栏是空的或显示不可用} `quota-empty` 按这个顺序查(快照接口 `GET /api//snapshot` 一次就能看到前两层): 1. **账号登录了吗** —— 面板「积分额度」tab 顶部。若显示登录表单,先填一次账号密码。 快照里 `auth.configured` 为 `false` 即未登录。 2. **快照有没有报错** —— `auth.error` / `quotaError.code`: - `not_configured` → 从没登录过,回到第 1 步; - `refresh_rejected` / `jwt_expired` → 令牌死了,见 [B1](#b1-面板反复要求重新登录); - `config_error` → 配置问题,见 [C3](#c3-面板顶部报配置错误); - `console_error` → 商汤控制台没应答,通常下一轮轮询自愈;持续出现查网络。 3. **结构漂移了吗** —— 快照带 `shapeWarnings` 说明控制台返回的字段变了(如改名)。对照 [SENSENOVA-API.md](./SENSENOVA-API.md) 核对字段——这是"接口变更"的第一信号,不是"暂无数据"。 根因与判别见 [PITFALLS.md](./PITFALLS.md) §12(shape 漂移检测)。 ### A2. 「可看图」一行缺失 / 清单为空 {#a2-可看图一行缺失} - **缺整行** → 没有 API key,模型目录没拉(`catalogAvailable: false`)。在面板「接入 API → API Key」 粘贴 `sk-` Key 保存,或在用户级 env 配 `SENSENOVA_API_KEY`。下一轮 poll 自动亮起,无需重启。 - **行在但清单空** → 商汤当前确实没有模型声明 `input_modalities` 含 `image`(2026-09 起每个模型条目都带 该字段)。对照 catalog 里各模型的 `input_modalities` 实际值。 ## B. 登录 / 模型接入 / 出图 ### B1. 面板反复要求重新登录 {#b1-面板反复要求重新登录} `needs-login` · `login-refused` refresh_token 被吊销(或已过期)且环境里已无密码可自动续期。面板**不会**静默显示旧数据,会明确 要求重登。处置:在面板表单填一次账号密码。设计见 [AUTH.md](./AUTH.md);refresh token 每次刷新 都会被轮换、只存 access token 的后果见 [PITFALLS.md](./PITFALLS.md) §5。 被拒分三类,别一概重试(重试只会把错密码撞成锁号——[PITFALLS.md](./PITFALLS.md) §6): | 面板说的 | 含义 | 怎么做 | |---|---|---| | 账号锁定 / 限频(带倒计时) | **时间型** | 等平台窗口;插件已按平台声明的窗口计时,**别手动重试** | | 账号或密码不正确 / 需验证码 | **凭据型** | 插件**完全不自动重试**,重填正确账号密码 | | `invalid_grant` 之类 | refresh 已死 | 重填一次(回到本节开头) | ### B2. 模型列表里没有商汤模型 {#b2-模型列表里没有商汤模型} `provider-missing` 1. 面板「接入 API」里的 **provider 开关**打开了吗(默认关)? 2. Host 有 `llm` 服务吗?快照 `llm.providerRegistered` 为 `false` 而开关为 `true` 时,看 Host 日志里 peer 加载失败——按本插件的降级纪律,**该模块缺席、面板照常用**,不是整个面板失效 ([ARCHITECTURE.md](./ARCHITECTURE.md) §5.2)。 3. **用 doctor 确认磁盘上的生效值**(开关存在状态文件,不在任何配置或路由上): ```powershell npm run doctor # 每个 profile 的 provider / draw 生效值 npm run doctor:json # 机器读,含 symptoms 症状码 ``` 出现 `state-unreadable` 症状码 → 见 [C2](#c2-状态文件读不出来或开关对不上)。 provider 注册与撤回的热生效设计见 [PROVIDER-HOT-RELOAD.md](./PROVIDER-HOT-RELOAD.md)。 ### B3. 某个模型没出现 / 出图工具没挂上 {#b3-某个模型没出现或出图工具没挂上} `tool-or-model-missing` - **出图工具**:开关与模型偏好保存后当场重新应用注册,工具在同一会话内随即挂载/卸载,无需重启 ([README](../README.md)「出图工具」节)。仍看不到工具时看面板那一行说明: 无 tools 服务或 peer 加载失败时工具**静默缺席**(不是 bug);peer 的注册不返回 disposer 时 工具在但不可热切换,重启 Host 后才换成新值。 - **单个模型没出现**:在「语言模型」卡的勾选清单里被取消推送了。清单是**允许清单**,空=不过滤; 想"一个都不推"要用哨兵值,语义见 [PROVIDER-HOT-RELOAD.md](./PROVIDER-HOT-RELOAD.md) §6。 ### B4. 对话中途报「本轮运行失败」,错误体带 HTTP 499 {#b4-对话中途报本轮运行失败错误体带-http-499} 错误体形如 `{"code":"client_request_aborted_error","message":"client has aborted request"}`(HTTP 状态 499)。 这是**上游**(小浣熊网关 / 商汤推理链路)返回的错误,插件与 DSH 宿主只是转显:插件源码不生成它 (全源码无 499/abort 逻辑),「本轮运行失败」是宿主的通用轮次文案。判定链与证据归档在 [ROADMAP.md](./ROADMAP.md) §6.1.9。处置: 1. **偶发一次** → 直接重发即可(网关内部取消,常见于上游推理慢被网关掐断); 2. **频发** → 抓响应头 `x-request-id` + 时间点,向小浣熊反馈; 3. **刚点过「停止」** → 那是正常中止,不是故障; 4. 卡住超过 5 分钟后报错 → 是本地流空闲超时(`TIMEOUT`,可重试类),与 499 不同源。 是否在宿主侧给 499 加自动重试纠正,见 [ROADMAP.md](./ROADMAP.md) §7 的候选行(未排期,先观察复现率)。 ### B5. 小浣熊扫码登录打不开确认页(面板报 404) {#b5-小浣熊扫码登录打不开确认页} 面板「小浣熊」tab 点「微信扫码登录」,二维码出来了、手机也能扫,但**确认页打不开**,或面板直接说 「上游的扫码确认页打不开(404)」。小浣熊提供方还挂着一行 `not_configured`。 这是**上游缺页,不是本机问题**:`POST /api/iam/v1/auth/mp/qrcode` 仍然正常发码,但它回的 `scan_path` 指向的 `/login/mp` 在 xiaohuanxiong.com 上是 Next.js 的 404 页。官方桌面客户端的二维码 指向的也是同一页(客户端「能用」靠的是它已经持有的登录态,不是另一条扫码通道)。复测记录与判读见 [ROADMAP.md](./ROADMAP.md) §6.1.10。 处置: 1. **现在就要用模型** → 走面板「接入 API」(Token Plan)那一侧;两者是不同认证域,Token Plan 的 API Key 不能当小浣熊登录态用,反过来也一样。 2. **等上游修** → 上游恢复后回到「小浣熊」tab 重新扫码即可,不需要改配置或重装。 3. **已经登过、只是过期** → 同样卡在上游缺页,先按第 1 步过渡。 `not_configured` 那一行不是第二个故障:它是「开关开着、本机还没有小浣熊凭据」的既有状态, 扫码成功后会自动消失(`switch ON + no token` 时 publisher 会干净卸载,见 [PITFALLS.md](./PITFALLS.md) §45)。 ## C. 装了改了却不生效 / 状态对不上 ### C1. 改了代码但面板没变 {#c1-改了代码但面板没变} `stale-code` **Host 半边(`index.ts` / `sensenova-auth.ts` / `token-store.ts` 等)只在 DSH 启动时加载一次。** 改完必须**完全退出 DSH(含托盘)再启动**;只改浏览器半边(`src/client/`)刷新页面即可。 自查在跑的是不是新代码——看快照有没有 `auth` 字段: ```powershell (Invoke-RestMethod http://127.0.0.1:19387/api/dsh-connect-sensenova-token-plan/snapshot).auth ``` 没有 `auth`(而是 `totals`/`recent` 之类)→ **跑的还是旧代码**,重启。完整说明见 [SETUP.md](./SETUP.md) §4;这条坑的两个 profile 变体见 [PITFALLS.md](./PITFALLS.md) §8 与 §22 (本机可能同时有桌面版与 `dsh web` 在跑,用的不是同一份代码、也不是同一个 profile)。 > 源码改了但产物没重建也会这样:改 `src/` 后要 `npm run build` 并把 `lib/`、`client.js` 与源码 > **一并提交**(ADR-005;CI 的 `build-freshness` 门禁就是钉这一条)。 ### C2. 状态文件读不出来或开关对不上 {#c2-状态文件读不出来或开关对不上} `state-unreadable` `doctor` 报 `unreadable state: xxx.json`,或"面板明明开了、doctor 却说不通": - **写侧版本护栏**:状态文件带 `version`,本构建只认自己那几个版本;磁盘上是**更新的版本**时 **拒绝覆盖**(裁定见 [ADR.md](./ADR.md) ADR-006)。这是保护不是故障——通常是升级中途。 - **别手改这些 JSON**:用面板开关改(它走原子写 + 版本校验)。 - **profile 分段**:状态在 `$DSH_HOME/state///`,取不到 profile 名时才退回 `$DSH_HOME/state//`。doctor 会把两者都列出来;同一台机器跑着两个 profile 时,别看错那一份 ([PITFALLS.md](./PITFALLS.md) §23)。 ### C3. 面板顶部报配置错误 {#c3-面板顶部报配置错误} `config-error` 配置面(`cordis.patch.yml`)里的端点类字段不是合法 http(s) 绝对地址时,插件在**挂载时**就报 `config_error`(而不是第一次轮询才变成莫名的网络错误)。对照 [SETUP.md](./SETUP.md) §3 的字段表, 改后重装/重载 Host。另一个坑:嵌套的 `auth:` 块会被**静默忽略**,端点字段必须是 patch 行的 **顶层键**([AGENTS.md](../AGENTS.md) 红线 3 曾因此打到真平台)。 --- ## D. 面板打不开 / 找不到入口 ### D1. 用局域网 IP 打开时面板报 forbidden {#d1-用局域网-ip-打开时面板报-forbidden} 面板路由只服务回环名(`localhost` / `127.0.0.1` / `::1`)。用 `http://172.19.0.199:3080/` 这类地址 打开时,`Host` 头就是那个 IP,栅栏回 `403`,响应体写明被拒的主机名与修法 (`code: host_not_admitted`、`fix` 字段),面板上显示为「面板是从本插件不提供服务的地址打开的」。 - **要在这台机器上从局域网访问**:把该主机名追加进 `cordis.patch.yml` 的 `allowedHosts` (`allowedHosts: ["172.19.0.199"]`),重载 Host 生效;只增不替,回环默认项保留。 - **不要**为了省事关掉栅栏:它挡的是 DNS rebinding(`Origin` 与 `Host` 会一致的那种)与跨站写请求, 面板与会话共用同一个浏览器信任边界。 - 字段说明见 [SETUP.md](./SETUP.md) §3,裁定见 [ADR.md](./ADR.md) ADR-018。 ### D2. 装完了找不到入口 {#d2-装完了找不到入口} 面板是 **Plugins 页里的内联插件卡**,不在侧边栏、也不是独立页面。按这个顺序查: 1. 装上了没有:`dsh plugin --profile list` 里有 `dsh-connect-sensenova-token-plan`; 2. 打开 DSH 的 **Plugins** 页,找名为「商汤模型接入」的卡(三个 tab:积分额度 / 接入 API / 小浣熊); 3. 卡里先显示登录表单——填一次账号密码,「积分额度」tab 才有数。 装完必须**完全退出 DSH(含托盘)再启动**,Host 半边只在启动时加载一次(见 [SETUP.md](./SETUP.md) §4)。 桌面版与 `dsh web` 用的是**不同 profile**,装在 web profile 里而打开桌面版是看不到的 ([PITFALLS.md](./PITFALLS.md) §8 与 §22)。 --- ## 还有别的问题? - 想知道**为什么**会有某个设计(不只是怎么办):[PITFALLS.md](./PITFALLS.md)(现象→根因→修法, 条数见该文件头)、[ARCHITECTURE.md](./ARCHITECTURE.md)(结构与数据流)。 - 想改配置字段:[SETUP.md](./SETUP.md) §3;想对接协议:[AUTH.md](./AUTH.md)、 [API.md](./API.md)。 - 找不到对应症状?本文件由症状码(`src/host/codes.ts` 的 `SYMPTOM`)钉住,新增/改名时两处一起改, 门禁会拦下只改一处的情况。