# CLI Doctor for DeepSeek Harness(左侧边栏插件) 把 CLI Doctor 装进 DSH 的左侧边栏:点一下「一键诊断当前状态」,就在面板里看到本机 CLI 工具链的版本现状、 依赖耦合和升级风险。诊断调用仓库根目录的只读检查器 `bin/check.js --json --no-update`,**不执行任何升级**。 - 插件包名:`dsh-cli-doctor` - 侧边栏入口 id:`cli-doctor`(顺序 30,在 Plugins、Schedules 之后) - 运行面:Host 半体(`src/host/index.js`,注册 `/api/cli-doctor/*`)+ 浏览器半体(`lib/client.js`,注册侧栏 slot) - 运行时依赖:无(client bundle 只 require `react` / `react/jsx-runtime`) - 契约:`CONTRACT.md` v2(随包发布;2026-11-06 增补优先于 v1 正文) - 与 Codex 侧栏插件互不影响:本目录自包含,不改动 `plugin.json`、`mcp.json`、`codex-server.js`、 `dashboard/**` 等任何 Codex 适配文件 ## v2 行为(当前批次) - **结果缓存**:诊断结果由 Host 保存为快照(含 checkedAt / mode / elapsedMs / 摘要), 写入 `/state.json`;Host 重启后 `GET /snapshot` 仍能恢复上次结果,面板打开即显示。 - **过期自动检查**:打开面板时,若没有快照或快照超过 `staleAfterHours`(默认 12 h)且 `autoCheck` 为真,客户端自动触发**一次**可取消的 full 诊断;同一次面板生命周期内只自动触发一次。 设置环境变量 `CLI_DOCTOR_AUTO_CHECK=0` 可关闭该行为(`/snapshot.cache.autoCheck` 会如实透出)。 - **可取消**:诊断进行中面板出现「取消」按钮,调用 `POST /api/cli-doctor/check/cancel`; Host 向检查器进程组发 SIGTERM,5 s 后 SIGKILL(Windows 用 `taskkill /T /F`), 所有等待该次运行的请求收到 `500 {"error":"cancelled"}`,且**取消不会覆盖已有快照**。 - **两档检查**:`?mode=full`(默认,`--json --no-update`,约 60–70 s)与 `?mode=fast`(`--json --fast --no-update`,约 9–11 s;npm/pip/rust 的 latest 为 null), 响应与面板都会标注 mode,fast 结果不会被当成最终升级结论。 - **共享请求(不再是 409)**:已有诊断在跑时,新的 `POST /check` 会 attach 到同一次运行, 两个请求都返回 200、`checkedAt` 相同、只 spawn 一个检查器进程(`cache:"attached"`、`shared:true`)。 - **历史**:每次成功诊断只保存摘要(≤ 1 KB),`GET /history?limit=N`(默认 20,上限 100)返回新→旧列表。 - **只读边界(永久)**:只检查、只生成建议命令供用户自行复制执行;**不执行升级、不接管包管理器、 不提供「交给 Agent 执行升级」入口**。面板的升级命令只能复制,插件不会运行它。 - **主题与可访问性**:状态色使用 `var(--dsw-alias-*, 回退值)` 主题 token;自动检查/取消用 `aria-busy` / `aria-live` 表达;结果区仍是唯一滚动容器(`data-dsh-cli-doctor-scroll`),表头固定。 ## 面板操作(第二批-1) ### 复制诊断报告(Markdown / JSON)给 AI 诊断完成后,面板表头出现两个动作: | 动作 | 内容 | |---|---| | **复制报告**(主) | AI 友好的 Markdown:标题、基本信息(插件版本 / 生成时间 / 检查时间 / 档位 / 耗时 / 范围 / 数据状态)、汇总计数(含依赖冲突与待核验)、按生态的**可行动工具明细**(当前/目标版本、状态、建议、升级命令、依赖影响摘要、备注)、依赖冲突与待核验明细、已是最新工具、跳过/降级说明、状态语义、只读说明、数据来源 | | **复制原始 JSON**(次) | `check.js` 原始报告 `JSON.stringify(report, null, 2)`,不加工,可直接交给脚本或 AI 解析 | - 复制成功后表头显示「已复制」,约 2 秒后自动消失;复制**不发网络请求、不修改报告**。 - Markdown 里升级命令一律标注「本插件不执行,仅供人工核对」,文档中没有任何执行升级的诱导。 - 剪贴板不可用或被拒绝时**不报错**:面板内会出现只读 `