@luolingp/request-doctor 0.12.6 → 0.12.9

package/docs/01-/350/275/257/344/273/266/351/234/200/346/261/202/350/247/204/346/240/274/350/257/264/346/230/216.md

@@ -2,7 +2,7 @@
 
 **产品名称**：request-doctor（请求急救员）
 **产品标识**：request-doctor
-**版本**：0.12.6
+**版本**：0.12.9
 
 ---
 

package/docs/02-/350/275/257/344/273/266/350/256/276/350/256/241/350/257/264/346/230/216.md

@@ -1,7 +1,7 @@
 # 软件设计说明
 
 **产品名称**：request-doctor（请求急救员）
-**版本**：0.12.6
+**版本**：0.12.9
 **编制依据**：GB/T 8567-2006《计算机软件文档编制规范》6.2
 
 ---

package/docs/03-/350/275/257/344/273/266/346/265/213/350/257/225/346/212/245/345/221/212.md

@@ -1,7 +1,7 @@
 # 软件测试报告
 
 **产品名称**：request-doctor（请求急救员）
-**版本**：0.12.6
+**版本**：0.12.9
 **编制依据**：GB/T 8567-2006《计算机软件文档编制规范》6.6；GB/T 8566-2007 验证与确认过程
 
 ---
@@ -62,8 +62,8 @@
 | `test/client-half.test.mjs` | 5 | 客户端半：模块身份、注入声明、apply 注册、组件能渲染 |
 | `test/diagnostics.test.mjs` | 3 | 快照可选写入：不配置不写盘、突发合并、坏路径不致命 |
 | `test/restart-notice.test.mjs` | 3 |
-| `test/verdict-report.test.mjs` | 19 | why 与 list：判定、理由、环境摘要、自动扫描、分组排序 | 缺导出判为需要重启；其它失败不误判；多次累积不覆盖 |
-| **合计** | **180** | **全部通过** |
+| `test/verdict-report.test.mjs` | 29 | why 与 list：判定、理由、环境摘要、自动扫描、分组、缺口、按形态给建议 | 缺导出判为需要重启；其它失败不误判；多次累积不覆盖 |
+| **合计** | **190** | **全部通过** |
 
 执行结果：
 
@@ -108,6 +108,7 @@
 | FR-4.9 建完必须核对 | `verify-roundtrip.test.mjs` — 建完必能验过 | 通过 |
 | FR-4.10 不可核对不算失败 | `env-verify.test.mjs` — 目标不可读记为未核对 | 通过 |
 | FR-4.11 坏垫片能被发现 | `verify-roundtrip.test.mjs` — 手工破坏的垫片验不过 | 通过 |
+| FR-7.5 共同缺口要点出 | `verdict-report.test.mjs` — 同一符号缺两次即汇总，按涉及数排序 | 通过 |
 | FR-7.4 why 能解释判定 | `verdict-report.test.mjs` — 五种情形各有用例 | 通过 |
 | FR-4.13 需要重启要说明 | `restart-notice.test.mjs` — 缺导出归入重启提示 | 通过 |
 | FR-4.12 不用占位 | `compat-env.test.mjs` — 装真实旧版本；旧版本也没有则拒绝 | 通过 |
@@ -213,4 +214,4 @@
 
 ### 7.2 分文件执行结果
 
-31 个测试文件逐个单独执行，每个都有用例且全部通过，不存在因导入失败而静默跳过的文件。用例数分布：compat.test.mjs 17、plugin.test.mjs 15、compat-env.test.mjs 14、classify.test.mjs 13，其余按职能分散，合计 180。
+31 个测试文件逐个单独执行，每个都有用例且全部通过，不存在因导入失败而静默跳过的文件。用例数分布：compat.test.mjs 17、plugin.test.mjs 15、compat-env.test.mjs 14、classify.test.mjs 13，其余按职能分散，合计 190。

package/docs/04-/345/256/211/350/243/205/351/203/250/347/275/262/350/257/264/346/230/216.md

@@ -1,7 +1,7 @@
 # 软件安装部署说明
 
 **产品名称**：request-doctor（请求急救员）
-**版本**：0.12.6
+**版本**：0.12.9
 **编制依据**：GB/T 8567-2006《计算机软件文档编制规范》6.7
 
 ---

package/docs/05-/347/224/250/346/210/267/346/211/213/345/206/214.md

@@ -1,7 +1,7 @@
 # 软件用户手册
 
 **产品名称**：request-doctor（请求急救员）
-**版本**：0.12.6
+**版本**：0.12.9
 **编制依据**：GB/T 8567-2006《计算机软件文档编制规范》6.5
 
 ---
@@ -208,9 +208,15 @@ dsh-hyper-tools@0.1.0：incompatible
   declares @deepseek-ai/dsh-llm ^0.1.5-rc.1
   缺符号：offloadRequestImagesWithPolicy
   环境：真实旧版本 3 个（需重启）：@deepseek-ai/dsh-llm, @deepseek-ai/schemastery, @deepseek-ai/cosmokit
-  结论：要修得先让它要的东西能被提供；缺符号时本插件会尝试装入插件声明的旧版本。
+  结论：它要的旧版本已经装好，重启 DSH 后重新扫描即可生效。
 ```
 
+结论那一行按环境形态给，三种情况不同：
+
+- 已装入真实旧版本 → 只差重启
+- 环境为空 → 下一轮扫描会尝试装入，也可直接 `/doctor install <包名>`
+- 只有薄垫片且不缺符号 → 环境已按现行实现转发，仍装不上就重试
+
 判定为兼容但界面里装不上时，它也会告诉你该走 `/doctor install`。查不到这个插件时会列出已经审计过的插件名。
 
 想先看全貌：
@@ -232,4 +238,20 @@ dsh-hyper-tools@0.1.0：incompatible
 
 需要处理的排在前面，兼容的排在后面。
 
+多个插件缺同一个符号时会单独点出来：
+
+```
+先修这个：2 个插件都缺 offloadRequestImagesWithPolicy（a, b）
+```
+
+这种情况修一次能同时解开几个插件，所以值得先处理。
+
+需要处理时列表末尾会给一句能照做的事：
+
+```
+修复会在下一轮扫描时自动尝试；想立刻重试：/doctor install <包名>
+```
+
+全部兼容时不会出现这句。
+
 列表里只留环境提示的前半句，完整内容用 `/doctor why` 看。

package/docs/06-/350/275/257/344/273/266/350/264/250/351/207/217/345/272/246/351/207/217/346/212/245/345/221/212.md

@@ -1,7 +1,7 @@
 # 软件质量度量报告
 
 **产品名称**：request-doctor（请求急救员）
-**版本**：0.12.6
+**版本**：0.12.9
 **度量标准**：GB/T 45717-2025《信息技术 软件测量 软件质量测量 自动化的源代码质量测度》
 **度量工具**：`tools/quality-measure.mjs`（本仓库自带，可复现）
 

package/docs/quality-report.json

@@ -1,20 +1,20 @@
 {
   "standard": "GB/T 45717-2025 信息技术 软件测量 软件质量测量 自动化的源代码质量测度",
-  "generatedAt": "2026-10-29T15:40:53.188Z",
+  "generatedAt": "2026-10-29T15:51:31.395Z",
   "scope": {
     "files": 31,
-    "totalLines": 5131,
-    "sourceLines": 3720,
-    "commentLines": 939
+    "totalLines": 5180,
+    "sourceLines": 3754,
+    "commentLines": 949
   },
   "measures": {
-    "commentDensity": 25.24,
-    "duplicationPercent": 4.94,
-    "functionCount": 387,
+    "commentDensity": 25.28,
+    "duplicationPercent": 4.9,
+    "functionCount": 393,
     "maxComplexity": 10,
     "maxFunctionLines": 59,
     "maxFileLines": 500,
-    "averageComplexity": 3.85
+    "averageComplexity": 3.86
   },
   "limits": {
     "maxComplexity": 10,

package/lib/verdict-report.js

@@ -1,6 +1,9 @@
 import { linesText } from './text-lines.js';
 
 // 已经在扫的时候，告诉用户等一下，而不是报「没有结果」。
+// 有插件需要处理时给出的动作提示。诊断必须配一句能照做的事。
+const NEXT_STEP = '修复会在下一轮扫描时自动尝试；想立刻重试：/doctor install <包名>';
+
 const BUSY_TEXT = '正在扫描，几秒后再执行 /doctor list 就能看到结果。';
 
 // 最近一轮审计的清单。没扫过就是空数组。
@@ -42,7 +45,7 @@ function reportLines(hit) {
   for (const reason of hit.reasons ?? []) lines.push(`  ${reason}`);
   if ((hit.missing ?? []).length > 0) lines.push(`  缺符号：${hit.missing.join(', ')}`);
   if (hit.environment !== undefined) lines.push(`  环境：${hit.environment}`);
-  lines.push(advice(hit.verdict));
+  lines.push(advice(hit));
   return lines;
 }
 
@@ -53,9 +56,20 @@ function missingText(name, audited) {
 }
 
 // 结论后面跟一句能直接照做的话。
-function advice(verdict) {
-  if (verdict === 'compatible') return '  结论：可以装。装不上就是管理器那边的检查没过，用 /doctor install 走本插件的路径。';
-  return '  结论：要修得先让它要的东西能被提供；缺符号时本插件会尝试装入插件声明的旧版本。';
+//
+// 环境形态决定下一步：旧版本已经装好的只差重启，没环境的等下一轮扫描，
+// 兼容的则要去走安装路径——三种情况给同一句话等于没说。
+function advice(hit) {
+  if (hit.verdict === 'compatible') return '  结论：可以装。装不上就是管理器那边的检查没过，用 /doctor install 走本插件的路径。';
+
+  const environment = hit.environment ?? '';
+  if (environment.includes('真实旧版本')) {
+    return '  结论：它要的旧版本已经装好，重启 DSH 后重新扫描即可生效。';
+  }
+  if (environment.includes('薄垫片') && (hit.missing ?? []).length === 0) {
+    return '  结论：环境已按现行实现转发，若仍装不上用 /doctor install <包名> 重试。';
+  }
+  return '  结论：下一轮扫描会尝试装入插件声明的旧版本；也可直接 /doctor install <包名> 重试。';
 }
 
 // /doctor list 的入口：没有扫描结果就先扫一轮。
@@ -83,6 +97,13 @@ export function formatList(deps) {
   const lines = [`已审计 ${audited.length} 个插件：`];
   if (broken.length > 0) pushGroup(lines, `需要处理 ${broken.length} 个`, broken, width);
   if (fine.length > 0) pushGroup(lines, `可以直接用 ${fine.length} 个`, fine, width);
+
+  // 几个插件被同一个符号卡住时，修一次能全解开，值得单独点出来。
+  if (broken.length > 0) {
+    const gap = gapSummary(broken);
+    if (gap !== undefined) lines.push('', `先修这个：${gap}`);
+    lines.push('', NEXT_STEP);
+  }
   lines.push('', '用 /doctor why <包名> 看某个插件的完整理由。');
   return { kind: 'success', text: linesText(lines) };
 }
@@ -100,6 +121,34 @@ function rowOf(item, width) {
   return `${name}  ${item.verdict}${where}`;
 }
 
+// 哪些符号是多个插件共同缺的。
+//
+// 一个符号被两个以上插件需要、又都不在运行时里，这是最值得先处理的事：
+// 修一次能同时解开好几个插件，用户不必逐个 /doctor why 去拼出这件事。
+export function commonGaps(audited) {
+  const owners = new Map();
+  for (const item of audited ?? []) {
+    for (const symbol of item.missing ?? []) {
+      const list = owners.get(symbol) ?? [];
+      list.push(item.name);
+      owners.set(symbol, list);
+    }
+  }
+
+  const gaps = [];
+  for (const [symbol, names] of owners) {
+    if (names.length >= 2) gaps.push({ symbol, plugins: names });
+  }
+  return gaps.sort((a, b) => b.plugins.length - a.plugins.length);
+}
+
+// 把共同缺口说成一句话；没有时返回 undefined。
+export function gapSummary(audited) {
+  const gaps = commonGaps(audited);
+  if (gaps.length === 0) return undefined;
+  const first = gaps[0];
+  return `${first.plugins.length} 个插件都缺 ${first.symbol}（${first.plugins.join(', ')}）`;
+}
 // 列表里只用环境的摘要：把包名列表整段丢掉，超长再截。
 //
 // 「真实旧版本 3 个（需重启）：@deepseek…」把冒号和半截包名挤在一起，读起来别扭；

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luolingp/request-doctor",
-  "version": "0.12.6",
+  "version": "0.12.9",
   "description": "自动修复客户端引起的请求失败，并让版本不匹配的 DSH 插件能装上、能跑起来。",
   "keywords": [
     "dsh-plugin",