@luolingp/request-doctor 0.16.11 → 0.16.13

package/README.md

@@ -182,4 +182,15 @@ DSH 升级后，旧插件可能只认 `0.2.1-rc.2`，而你现在是 `0.2.1-rc.3
 
 ## License
 
-MIT
+MIT
+## 维护者检查
+
+仓库里自带三个脚本，改完东西依次跑：
+
+```bash
+npm test              # 单元与集成测试
+npm run check:quality # 代码质量门禁（复杂度、重复率、注释密度、文件长度）
+npm run check:docs    # 文档与实现是否还对得上
+```
+
+`check:docs` 会核对：需求条目是否都有覆盖行、报告引用的测试是否存在、设计说明的模块清单是否与 `lib/` 一致、六份文档版本号、质量报告数字、路由与命令是否写进文档。它随包发布，也可以在解压后的包里直接跑。

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.16.11
+**版本**：0.16.13
 
 ---
 

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.16.11
+**版本**：0.16.13
 **编制依据**：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.16.11
+**版本**：0.16.13
 **编制依据**：GB/T 8567-2006《计算机软件文档编制规范》6.6；GB/T 8566-2007 验证与确认过程
 
 ---

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.16.11
+**版本**：0.16.13
 **编制依据**：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.16.11
+**版本**：0.16.13
 **编制依据**：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.16.11
+**版本**：0.16.13
 **度量标准**：GB/T 45717-2025《信息技术 软件测量 软件质量测量 自动化的源代码质量测度》
 **度量工具**：`tools/quality-measure.mjs`（本仓库自带，可复现）
 

package/docs/quality-report.json

@@ -1,6 +1,6 @@
 {
   "standard": "GB/T 45717-2025 信息技术 软件测量 软件质量测量 自动化的源代码质量测度",
-  "generatedAt": "2026-10-29T17:32:43.272Z",
+  "generatedAt": "2026-10-29T17:42:30.275Z",
   "scope": {
     "files": 41,
     "totalLines": 5538,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luolingp/request-doctor",
-  "version": "0.16.11",
+  "version": "0.16.13",
   "description": "自动修复客户端引起的请求失败，并让版本不匹配的 DSH 插件能装上、能跑起来。",
   "keywords": [
     "dsh-plugin",
@@ -33,7 +33,8 @@
     "cordis.patch.yml",
     "locale",
     "icon.svg",
-    "docs"
+    "docs",
+    "tools"
   ],
   "engines": {
     "node": ">=20"
@@ -50,5 +51,10 @@
         "@deepseek-ai/dsh-client-ui-plugin-manager"
       ]
     }
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "check:quality": "node tools/quality-measure.mjs --threshold",
+    "check:docs": "node tools/doc-check.mjs"
   }
-}
+}

package/tools/doc-check.mjs

@@ -0,0 +1,131 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// 文档与实现对一遍。持续改动之后，文档最容易悄悄过期：
+// 报告里写着不存在的用例、设计说明漏了新模块、质量报告的数字停在旧版本。
+//
+// 用法：node tools/doc-check.mjs [--json]
+// 退出码非 0 表示有对不上的地方。
+
+// 默认查脚本所在仓库；发布包被解到别处时用 --root 指定。
+const rootArg = process.argv.indexOf('--root');
+const root = rootArg >= 0 && process.argv[rootArg + 1] !== undefined
+  ? process.argv[rootArg + 1]
+  : join(fileURLToPath(import.meta.url), '..', '..');
+const read = (path) => readFileSync(join(root, path), 'utf8');
+const asJson = process.argv.includes('--json');
+
+const problems = [];
+
+// 1) 需求条目是否都在覆盖矩阵里出现。
+const requirements = read('docs/01-软件需求规格说明.md');
+const report = read('docs/03-软件测试报告.md');
+const requirementIds = [...requirements.matchAll(/^- (FR-[\d.]+[a-z]?)/gm)].map((match) => match[1]);
+for (const id of requirementIds.filter((value) => !report.includes(value))) {
+  problems.push(`需求 ${id} 在测试报告里没有对应的覆盖行`);
+}
+
+// 2) 报告里引用的测试文件是否真的存在；反过来，测试是否都被登记。
+// 测试目录不随包发布：没有就跳过与用例相关的检查，而不是崩掉。
+const testDir = join(root, 'test');
+const testFiles = existsSync(testDir) ? readdirSync(testDir).filter((name) => name.endsWith('.test.mjs')) : [];
+  // 没有测试目录（发布包里就是这样）时，逐条比对没有意义。
+  if (testFiles.length > 0) {
+  const claimed = new Set([...report.matchAll(/`test\/([\w.-]+\.test\.mjs)`/g)].map((match) => match[1]));
+  for (const name of claimed) {
+    if (!testFiles.includes(name)) problems.push(`报告引用了不存在的测试文件 test/${name}`);
+  }
+  for (const name of testFiles.filter((value) => !claimed.has(value))) {
+    problems.push(`测试文件 test/${name} 未在报告中登记`);
+  }
+  
+  }
+// 3) 设计说明的模块清单与 lib 目录双向比对。
+const design = read('docs/02-软件设计说明.md');
+const documented = new Set([...design.matchAll(/^\| `((?:lib\/)?[\w.-]+\.js)`/gm)].map((match) => match[1]));
+const realModules = [
+  ...readdirSync(join(root, 'lib')).filter((name) => name.endsWith('.js')).map((name) => `lib/${name}`),
+  'index.js',
+  'client.js',
+];
+for (const name of realModules.filter((value) => !documented.has(value))) {
+  problems.push(`设计说明未登记模块 ${name}`);
+}
+for (const name of documented) {
+  if (!realModules.includes(name)) problems.push(`设计说明登记了不存在的模块 ${name}`);
+}
+
+// 4) 六份文档的版本号要与 package.json 一致。
+const version = JSON.parse(read('package.json')).version;
+for (const name of readdirSync(join(root, 'docs')).filter((file) => file.endsWith('.md'))) {
+  const found = /\*\*版本\*\*：([\d.]+)/.exec(read(`docs/${name}`))?.[1];
+  if (found !== undefined && found !== version) problems.push(`docs/${name} 版本 ${found}，应为 ${version}`);
+}
+
+// 5) 质量报告的实测表要与机器可读结果一致。
+//
+// 报告里有两张表都用「注释密度」这类标签：前面一张是定义（第三列是文字），
+// 后面一张才是实测。所以先把实测表切出来，再在表内按行比对，避免匹配到定义表。
+const measured = JSON.parse(read('docs/quality-report.json'));
+const qualityDoc = read('docs/06-软件质量度量报告.md');
+const tableStart = qualityDoc.indexOf('| 度量项 | 实测值 | 限值 | 判定 |');
+const measuredTable = tableStart < 0 ? '' : qualityDoc.slice(tableStart).split(/\r?\n\r?\n/)[0];
+
+const expected = [
+  ['文件数', String(measured.scope.files)],
+  ['总行数', String(measured.scope.totalLines)],
+  ['源代码行数', String(measured.scope.sourceLines)],
+  ['注释行数', String(measured.scope.commentLines)],
+  ['注释密度', `${measured.measures.commentDensity}%`],
+  ['重复率', `${measured.measures.duplicationPercent}%`],
+  ['函数数', String(measured.measures.functionCount)],
+  ['最大圈复杂度', String(measured.measures.maxComplexity)],
+  ['最长函数', `${measured.measures.maxFunctionLines} 行`],
+  ['最长文件', `${measured.measures.maxFileLines} 行`],
+];
+
+if (measuredTable === '') {
+  problems.push('质量报告里找不到实测表');
+} else {
+  for (const [label, value] of expected) {
+    const row = measuredTable
+      .split(/\r?\n/)
+      .find((line) => line.replace(/\*/g, '').startsWith(`| ${label} |`));
+    if (row === undefined) {
+      problems.push(`质量报告实测表缺少「${label}」`);
+      continue;
+    }
+    const cell = row.split('|')[2].replace(/\*/g, '').trim();
+    if (cell !== value) problems.push(`质量报告「${label}」为 ${cell}，实测 ${value}`);
+  }
+}
+
+// 6) 每条界面路由和每个命令都要写进文档。
+const manual = read('docs/05-用户手册.md');
+const sources = [
+  read('index.js'),
+  read('client.js'),
+  ...realModules.filter((name) => name.startsWith('lib/')).map((name) => read(name)),
+].join('\n');
+
+const routes = new Set([...sources.matchAll(/'(?:\/doctor\/[a-z]+)'/g)].map((match) => match[0].slice(1, -1)));
+for (const route of routes) {
+  if (!manual.includes(route) && !design.includes(route)) problems.push(`路由 ${route} 未写进文档`);
+}
+for (const name of new Set([...sources.matchAll(/sub === '(\w+)'/g)].map((match) => match[1]))) {
+  if (!manual.includes(`/doctor ${name}`)) problems.push(`命令 /doctor ${name} 未写进用户手册`);
+}
+
+if (asJson) {
+  console.log(JSON.stringify({ ok: problems.length === 0, problems }, null, 2));
+} else if (problems.length === 0) {
+  console.log(
+    `文档与实现一致：需求 ${requirementIds.length} 条、测试 ${testFiles.length} 个、模块 ${realModules.length} 个、版本 ${version}`,
+  );
+} else {
+  for (const problem of problems) console.log(`- ${problem}`);
+  console.log(`\n共 ${problems.length} 处不一致`);
+}
+
+process.exit(problems.length === 0 ? 0 : 1);

package/tools/quality-measure.mjs

@@ -0,0 +1,257 @@
+// 源代码质量度量，对应 GB/T 45717-2025。
+//
+// 只算不需要执行代码就能得到的指标：规模、注释密度、圈复杂度、重复率、函数与文件长度。
+// 带 --threshold 时任一项超限就以非零码退出，可以当门禁。
+import { readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, extname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+// 限值：函数超过十来个分支就很难穷举测试，注释不到源码一成说明意图没写清，
+// 重复率超过百分之五基本是复制粘贴而不是抽象。
+const LIMITS = {
+  maxComplexity: 10,
+  maxFunctionLines: 60,
+  maxFileLines: 500,
+  minCommentDensity: 10,
+  maxDuplicationPercent: 5,
+};
+
+// 只看产品代码。
+function collectSources(root) {
+  const files = [];
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+      const path = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (['test', 'tools', 'docs'].includes(entry.name)) continue;
+        walk(path);
+        continue;
+      }
+      if (extname(entry.name) === '.js' || extname(entry.name) === '.mjs') files.push(path);
+    }
+  };
+  walk(root);
+  return files;
+}
+
+// 字符串字面量换成占位，免得里面的内容被当成代码。
+function stripLiterals(line) {
+  return line
+    .replace(/`(?:\\.|[^`\\])*`/g, '``')
+    .replace(/'(?:\\.|[^'\\])*'/g, "''")
+    .replace(/"(?:\\.|[^"\\])*"/g, '""');
+}
+
+// 圈复杂度。一个 switch 的所有分支只算一次判断——那是查表，不是判定树。
+function cyclomatic(block) {
+  const text = block.split('\n').map((line) => stripLiterals(line).replace(/\/\/.*$/, '')).join('\n');
+  const switches = (text.match(/\bswitch\s*\(/g) ?? []).length;
+  const cases = (text.match(/\bcase\s+/g) ?? []).length;
+  const patterns = [/\bif\s*\(/g, /\bfor\s*\(/g, /\bwhile\s*\(/g, /\bcatch\s*\(/g, /\?\?/g, /\?\./g, /&&/g, /\|\|/g];
+  let count = 1 + switches;
+  for (const pattern of patterns) count += (text.match(pattern) ?? []).length;
+  count += Math.max(0, cases - switches);
+  return count;
+}
+
+// 找出函数声明和它们的花括号范围。
+function findFunctions(lines) {
+  const found = [];
+  const isDeclaration = (line) =>
+    /^\s*(?:export\s+)?(?:async\s+)?function\s+[A-Za-z_$][\w$]*\s*\(/.test(line)
+    || /^\s*(?:export\s+)?const\s+[A-Za-z_$][\w$]*\s*=\s*(?:async\s*)?\([^)]*\)\s*=>\s*\{/.test(line)
+    || /^\s*[A-Za-z_$][\w$]*\s*\([^)]*\)\s*\{/.test(line);
+
+  for (let index = 0; index < lines.length; index += 1) {
+    if (!isDeclaration(lines[index])) continue;
+    let depth = 0;
+    let started = false;
+    for (let scan = index; scan < lines.length; scan += 1) {
+      const code = stripLiterals(lines[scan]).replace(/\/\/.*$/, '');
+      for (const char of code) {
+        if (char === '{') {
+          depth += 1;
+          started = true;
+        } else if (char === '}') {
+          depth -= 1;
+        }
+      }
+      if (started && depth === 0) {
+        found.push({ startLine: index + 1, endLine: scan + 1, body: lines.slice(index, scan + 1) });
+        break;
+      }
+    }
+  }
+  return found;
+}
+
+// 去掉嵌套函数的行：外层函数的编排逻辑不该为内层的工作背复杂度。
+function ownLines(fn, all) {
+  const nested = all.filter((other) => other !== fn && other.startLine > fn.startLine && other.endLine < fn.endLine);
+  if (nested.length === 0) return fn.body;
+  const covered = new Set();
+  for (const other of nested) {
+    for (let line = other.startLine; line <= other.endLine; line += 1) covered.add(line);
+  }
+  return fn.body.filter((_, offset) => {
+    const line = fn.startLine + offset;
+    return line === fn.startLine || line === fn.endLine || !covered.has(line);
+  });
+}
+
+// 量一个文件。
+function measureFile(path) {
+  const lines = readFileSync(path, 'utf8').split('\n');
+  let commentLines = 0;
+  let blankLines = 0;
+  let inBlock = false;
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (inBlock) {
+      commentLines += 1;
+      if (line.includes('*/')) inBlock = false;
+      continue;
+    }
+    if (line.startsWith('/*')) {
+      commentLines += 1;
+      if (!line.includes('*/')) inBlock = true;
+      continue;
+    }
+    if (line.startsWith('//')) {
+      commentLines += 1;
+      continue;
+    }
+    if (line === '') blankLines += 1;
+  }
+  const functions = findFunctions(lines);
+  return {
+    path: relative(ROOT, path),
+    totalLines: lines.length,
+    sourceLines: lines.length - blankLines - commentLines,
+    commentLines,
+    functions: functions.map((fn) => {
+      const own = ownLines(fn, functions);
+      return { startLine: fn.startLine, lines: own.length, complexity: cyclomatic([fn.body[0], ...own].join('\n')) };
+    }),
+  };
+}
+
+// 归一化一行，用于比较重复。
+function normalize(line) {
+  return stripLiterals(line).replace(/\/\/.*$/, '').replace(/\s+/g, ' ').trim();
+}
+
+// 一行算不算「逻辑行」。注释、导入、纯标点、对象字段和正则遍历惯用法都不算：
+// 它们重复是因为语言和数据结构本来如此，不是因为有人复制粘贴。
+function isLogicLine(line) {
+  if (line.length < 30) return false;
+  if (line.startsWith('*') || line.startsWith('/*') || line.startsWith('//')) return false;
+  if (line.startsWith('import ') || line.startsWith('export {') || line.startsWith('} from')) return false;
+  if (/^[)}\];,]+$/.test(line)) return false;
+  if (/^[A-Za-z_$][\w$]*:\s*[^(){}]*,$/.test(line)) return false;
+  if (/^while \(\(match = /.test(line)) return false;
+  return true;
+}
+
+// 重复率。
+function duplication(files, contents) {
+  const seen = new Map();
+  let total = 0;
+  let repeated = 0;
+  for (const file of files) {
+    for (const raw of contents.get(file).split('\n')) {
+      const line = normalize(raw);
+      if (!isLogicLine(line)) continue;
+      total += 1;
+      const count = seen.get(line) ?? 0;
+      seen.set(line, count + 1);
+      if (count > 0) repeated += 1;
+    }
+  }
+  return total === 0 ? 0 : (repeated / total) * 100;
+}
+
+const files = collectSources(ROOT);
+const contents = new Map(files.map((file) => [file, readFileSync(file, 'utf8')]));
+const measured = files.map(measureFile);
+const duplicatePercent = duplication(files, contents);
+
+const allFunctions = measured.flatMap((file) => file.functions.map((fn) => ({ file: file.path, ...fn })));
+const sourceLines = measured.reduce((sum, file) => sum + file.sourceLines, 0);
+const commentLines = measured.reduce((sum, file) => sum + file.commentLines, 0);
+const density = sourceLines === 0 ? 100 : (commentLines / sourceLines) * 100;
+
+const violations = [];
+for (const fn of allFunctions) {
+  if (fn.complexity > LIMITS.maxComplexity) {
+    violations.push({ measure: '圈复杂度', file: fn.file, line: fn.startLine, value: fn.complexity, limit: LIMITS.maxComplexity });
+  }
+  if (fn.lines > LIMITS.maxFunctionLines) {
+    violations.push({ measure: '函数长度', file: fn.file, line: fn.startLine, value: fn.lines, limit: LIMITS.maxFunctionLines });
+  }
+}
+for (const file of measured) {
+  if (file.totalLines > LIMITS.maxFileLines) {
+    violations.push({ measure: '文件长度', file: file.path, line: 1, value: file.totalLines, limit: LIMITS.maxFileLines });
+  }
+}
+if (density < LIMITS.minCommentDensity) {
+  violations.push({ measure: '注释密度', file: '(总体)', line: 0, value: Number(density.toFixed(2)), limit: LIMITS.minCommentDensity });
+}
+if (duplicatePercent > LIMITS.maxDuplicationPercent) {
+  violations.push({ measure: '重复率', file: '(总体)', line: 0, value: Number(duplicatePercent.toFixed(2)), limit: LIMITS.maxDuplicationPercent });
+}
+
+const report = {
+  standard: 'GB/T 45717-2025 信息技术 软件测量 软件质量测量 自动化的源代码质量测度',
+  generatedAt: new Date().toISOString(),
+  scope: { files: files.length, totalLines: measured.reduce((sum, f) => sum + f.totalLines, 0), sourceLines, commentLines },
+  measures: {
+    commentDensity: Number(density.toFixed(2)),
+    duplicationPercent: Number(duplicatePercent.toFixed(2)),
+    functionCount: allFunctions.length,
+    maxComplexity: allFunctions.reduce((max, fn) => Math.max(max, fn.complexity), 0),
+    maxFunctionLines: allFunctions.reduce((max, fn) => Math.max(max, fn.lines), 0),
+    maxFileLines: measured.reduce((max, f) => Math.max(max, f.totalLines), 0),
+    averageComplexity: allFunctions.length === 0 ? 0 : Number((allFunctions.reduce((s, fn) => s + fn.complexity, 0) / allFunctions.length).toFixed(2)),
+  },
+  limits: LIMITS,
+  violations,
+};
+
+// --out 让工具自己写文件：用 shell 重定向容易被写成非 UTF-8，中文会变成乱码。
+const outIndex = process.argv.indexOf('--out');
+if (outIndex > 0 && process.argv[outIndex + 1] !== undefined) {
+  const json = JSON.stringify(report, null, 2) + String.fromCharCode(10);
+  writeFileSync(process.argv[outIndex + 1], json, 'utf8');
+  console.log('已写入 ' + process.argv[outIndex + 1]);
+} else if (process.argv.includes('--json')) {
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+} else {
+  const rows = [
+    ['度量项', '实测值', '限值'],
+    ['文件数', String(files.length), '—'],
+    ['总行数', String(report.scope.totalLines), '—'],
+    ['源代码行数', String(sourceLines), '—'],
+    ['注释行数', String(commentLines), '—'],
+    ['注释密度（%）', String(report.measures.commentDensity), `≥ ${LIMITS.minCommentDensity}`],
+    ['重复率（%）', String(report.measures.duplicationPercent), `≤ ${LIMITS.maxDuplicationPercent}`],
+    ['函数数', String(report.measures.functionCount), '—'],
+    ['平均圈复杂度', String(report.measures.averageComplexity), '—'],
+    ['最大圈复杂度', String(report.measures.maxComplexity), `≤ ${LIMITS.maxComplexity}`],
+    ['最长函数（行）', String(report.measures.maxFunctionLines), `≤ ${LIMITS.maxFunctionLines}`],
+    ['最长文件（行）', String(report.measures.maxFileLines), `≤ ${LIMITS.maxFileLines}`],
+  ];
+  for (const row of rows) console.log(row.join('\t'));
+  console.log('');
+  if (violations.length === 0) console.log('结论：全部度量项满足限值。');
+  else {
+    console.log(`结论：${violations.length} 项超限。`);
+    for (const v of violations) console.log(`  - ${v.measure} ${v.file}:${v.line} 实测 ${v.value}，限值 ${v.limit}`);
+  }
+}
+
+if (process.argv.includes('--threshold') && violations.length > 0) process.exit(1);