dsh-request-doctor 0.14.6 → 0.15.1

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.14.6
+**版本**：0.15.1
 
 ---
 

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.14.6
+**版本**：0.15.1
 **编制依据**：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.14.6
+**版本**：0.15.1
 **编制依据**：GB/T 8567-2006《计算机软件文档编制规范》6.6；GB/T 8566-2007 验证与确认过程
 
 ---
@@ -62,6 +62,8 @@
 | `test/client-half.test.mjs` | 11 | 客户端半：模块身份、注入声明、apply 注册、组件能渲染 |
 | `test/diagnostics.test.mjs` | 3 | 快照可选写入：不配置不写盘、突发合并、坏路径不致命 |
 | `test/restart-notice.test.mjs` | 3 |
+| `test/skip-log.test.mjs` | 4 | 未修复失败按类别归并：同类别计数、按频次排序、留最后一条 |
+| `test/give-up-advice.test.mjs` | 5 | 不重试的类别各有可照做的建议，未知类别不编造 |
 | `test/allow-route.test.mjs` | 4 | 授权路由：路径声明、坏请求体 400、空 spec 200 失败、正常放行 |
 | `test/install-remote.test.mjs` | 2 | 远程安装的前置拒绝：非注册表名、缺 profile，均不触网 |
 | `test/install-branches.test.mjs` | 4 | 安装分支：已存在就地修、非注册表名、缺 profile、授权被拒 |
@@ -70,7 +72,7 @@
 | `test/panel-blocked.test.mjs` | 7 | 冲突判定：审计兼容却被拒装、清单形状解析、给 allow 动作 |
 | `test/panel-briefs.test.mjs` | 6 | 界面摘要：按名索引、只送可见行、缺数据不抛、不污染诊断 |
 | `test/verdict-report.test.mjs` | 29 | why 与 list：判定、理由、环境摘要、自动扫描、分组、缺口、按形态给建议 | 缺导出判为需要重启；其它失败不误判；多次累积不覆盖 |
-| **合计** | **232** | **全部通过** |
+| **合计** | **241** | **全部通过** |
 
 执行结果：
 
@@ -224,7 +226,7 @@
 
 ### 7.2 分文件执行结果
 
-37 个测试文件逐个单独执行，每个都有用例且全部通过，不存在因导入失败而静默跳过的文件。用例数分布：compat.test.mjs 17、plugin.test.mjs 15、compat-env.test.mjs 14、classify.test.mjs 13，其余按职能分散，合计 232。
+39 个测试文件逐个单独执行，每个都有用例且全部通过，不存在因导入失败而静默跳过的文件。用例数分布：compat.test.mjs 17、plugin.test.mjs 15、compat-env.test.mjs 14、classify.test.mjs 13，其余按职能分散，合计 241。
 ## 8 覆盖率实测
 
 用 Node 自带的 `--experimental-test-coverage` 跑一遍，作为「分支有没有被真的走一遍」的证据。这不替代对断言质量的判断，只说明哪些代码从未被执行。

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.14.6
+**版本**：0.15.1
 **编制依据**：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.14.6
+**版本**：0.15.1
 **编制依据**：GB/T 8567-2006《计算机软件文档编制规范》6.5
 
 ---

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.14.6
+**版本**：0.15.1
 **度量标准**：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-29T16:44:26.413Z",
+  "generatedAt": "2026-10-29T16:51:53.560Z",
   "scope": {
-    "files": 36,
-    "totalLines": 5412,
-    "sourceLines": 3906,
-    "commentLines": 1001
+    "files": 38,
+    "totalLines": 5472,
+    "sourceLines": 3946,
+    "commentLines": 1013
   },
   "measures": {
-    "commentDensity": 25.63,
-    "duplicationPercent": 4.96,
-    "functionCount": 415,
+    "commentDensity": 25.67,
+    "duplicationPercent": 4.98,
+    "functionCount": 421,
     "maxComplexity": 10,
     "maxFunctionLines": 57,
     "maxFileLines": 500,
-    "averageComplexity": 3.83
+    "averageComplexity": 3.81
   },
   "limits": {
     "maxComplexity": 10,

package/lib/diagnostics.js

@@ -3,6 +3,7 @@
 // 管三件事：各项修复计数、最近若干条事件、可选的快照文件。单独拎出来是因为组合根要
 // 关心的是"怎么修"，不该顺带管状态怎么记。
 import { writeFileSync } from 'node:fs';
+import { createSkipLog } from './skip-log.js';
 
 // 最近事件留多少条给 /doctor 看
 const MAX_LOG = 30;
@@ -21,6 +22,7 @@ export function createDiagnostics(input) {
     last: [],
   };
   const diagnostics = { versionScan: null };
+  const skipped = createSkipLog();
   let pending;
 
   const snapshot = () => ({
@@ -73,5 +75,5 @@ export function createDiagnostics(input) {
     writeNow();
   };
 
-  return { record, scheduleWrite, writeNow, flush, scanError, stats, diagnostics, snapshot };
+  return { record, scheduleWrite, writeNow, flush, scanError, stats, skipped: () => skipped.read(), diagnostics, snapshot };
 }

package/lib/give-up-advice.js

@@ -0,0 +1,18 @@
+// 不重试的失败怎么向用户交代。
+//
+// TLS 证书、本机权限、配额、内容策略这些重试一百次也不会变，所以不重试是对的。
+// 但「不重试」不等于「不解释」：用户需要知道这次是谁的问题、接下来自己能做什么。
+
+const ADVICE = {
+  tls: '证书校验没过。换掉中间代理的自签证书，或让系统信任该根证书；重试不会有帮助。',
+  'local-blocked': '本机权限、路径或磁盘空间不足。先把缺的权限或空间补上，重试才有意义。',
+  quota: '额度或频率到上限了。等额度恢复再发请求；这不是插件或网络的问题。',
+  policy: '内容被服务方的策略拦下了。改写提问再发；重试会得到同样的结果。',
+  image: '图片需要走转存才能发送。换一张图，或让客户端先完成转存。',
+};
+
+// @param {string} kind - 分类结果里的 kind。
+// @returns {string|undefined} 一句话建议；没有对应建议时返回 undefined。
+export function adviceFor(kind) {
+  return ADVICE[kind];
+}

package/lib/model-repair.js

@@ -10,6 +10,7 @@
 // - 无进展：压缩/修历史连续两轮都没让问题前进，就不再无限重试。
 import { classifyModelFailure, computeDelay } from './classify.js';
 import { cancellableSleep } from './sleep.js';
+import { adviceFor } from './give-up-advice.js';
 
 // 每个策略分到的预算倍数。鉴权类的重试更贵（要换凭据），给的次数更少。
 const STRATEGY_BUDGET = { auth: 'auth', 'history-repair': 'history', compact: 'normal' };
@@ -152,7 +153,7 @@ export function createModelRepair(input) {
     if (payload.signal?.aborted || lifetime.signal.aborted) return downstream;
 
     const decision = classifyModelFailure(payload.failure);
-    if (!decision.clientCaused || decision.strategy === 'skip') return downstream;
+    if (!decision.clientCaused || decision.strategy === 'skip') return skipOut(decision, downstream, record);
 
     const key = `${payload.turn}:${payload.step}:${payload.provider}:${decision.kind}`;
     // 同一处只放一个重试进去。并发的那几个直接让下游收场，避免重试互相叠加。
@@ -165,7 +166,17 @@ export function createModelRepair(input) {
     }
   }
 
-  // 依次过三关：本地修复成不成、还有没有进展、预算还剩不剩。
+  
+// 不重试的失败也要留痕：用户得知道这次是谁的问题、接下来能做什么。
+function skipOut(decision, downstream, record) {
+  if (decision.strategy === 'skip') {
+    const note = adviceFor(decision.kind) ?? '这类失败重试也不会变，跳过修复';
+    record('skip', decision.kind + ': ' + note);
+  }
+  return downstream;
+}
+
+// 依次过三关：本地修复成不成、还有没有进展、预算还剩不剩。
   async function attempt(key, payload, decision, downstream) {
     if (!(await prepare(decision, payload))) {
       stats.modelSkips += 1;

package/lib/skip-log.js

@@ -0,0 +1,27 @@
+// 本次会话里没救回来的失败。
+//
+// 日志是流式的，翻起来费事。这里按类别归并，只留每类最后一条与出现次数，
+// 让「刚才那次为什么没救回来」能一眼看到。
+
+const MAX_KINDS = 12;
+
+// 可读的汇总对象：add 记账，read 取回按次数排序的列表。
+export function createSkipLog() {
+  const entries = new Map();
+  return {
+    add(detail) {
+      const kind = String(detail).split(':')[0].trim();
+      const previous = entries.get(kind);
+      entries.set(kind, {
+        kind,
+        note: String(detail),
+        count: (previous?.count ?? 0) + 1,
+        at: new Date().toISOString(),
+      });
+      while (entries.size > MAX_KINDS) entries.delete(entries.keys().next().value);
+    },
+    read() {
+      return [...entries.values()].sort((a, b) => b.count - a.count);
+    },
+  };
+}

package/package.json

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