@moonquake2004/dsh-doctor 0.2.0 → 0.2.3

package/checks.json

@@ -41,8 +41,9 @@
       "probe": {
         "type": "text-not-contains",
         "path": "{profile}/cordis.patch.yml",
-        "pattern": "^\\s*-\\s*name:\\s*['\"]?[^'\"\\n]*\\s[^'\"\\n]+",
-        "flags": "m"
+        "pattern": "^\\s*name:\\s*['\"]?[^'\"\\s]+[^'\"\\n]*\\s[^'\"\\n]+",
+        "flags": "m",
+        "required": false
       },
       "detailOk": "用户 patch 的 insert name 均无空格",
       "detailFail": "用户 patch 存在含空格的 insert name（Windows 下 spawn 参数解析会断，#1420 待实现 lint 的目录版）",

package/dsh-doctor.mjs

@@ -9,6 +9,7 @@
  *     P3  用户 patch 的 insert name 从 profile 锚点不可解析（#1197/#880）
  *     P4  file: 依赖指向不存在的目录（#1197：悬空 file: 链接）
  *     P5  profile 顶层 @deepseek-ai/* 与框架重复（#1486：双模块实例 → Symbol 不匹配）
+ *     P7  cordis.patch.yml 结构 lint（#1724：~ insert: 是 YAML null → parsePatchList 崩溃 → UI 打不开；tab 缩进/缺冒号同族）
  *   [session]
  *     S1  孤儿 tool_call（#1363：assistant tool_calls 无对应 tool 结果 → INVALID_REQUEST）
  *     S2  未闭合 turn（#466/#1265：turn/start 无 turn/end → 会话永久"运行中"）
@@ -25,6 +26,7 @@
  *     E4  node-pty 原生模块完整性（#1219：pty.node 缺失 → dsh web 启动失败）
  *     E5  存储 JSON 文件合法性（#1357：并发写 workspace.json 乱码 → 工作区列表消失）
  *     E6  锚点元检查（tripwire：S6 的 expandRow seq0+k、S7 的 session/end-seed、S10 的 sourceEventSeqs 是否仍在安装的 dsh-session 中）
+ *     E10 3080 Web 端口可用性（#1719：启动 dsh web 前检查；dsh web 自身占用=正常，其他程序占用=FAIL；DSH_DOCTOR_PORT 可覆盖）
  *     （P6 Windows 空格参数 lint，#1420 —— 待实现）
  *
  * 用法：
@@ -42,11 +44,12 @@
  * 退出码：0 = 全部通过；1 = 发现可修复问题（内置 + catalog severity=error）；warn 级失败不改退出码。
  */
 import { execFileSync, spawnSync } from 'node:child_process';
-import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
+import net from 'node:net';
 import { basename, delimiter as PATH_DELIM, dirname, join } from 'node:path';
 import { homedir } from 'node:os';
-import { pathToFileURL } from 'node:url';
+import { pathToFileURL, fileURLToPath } from 'node:url';
 
 const HOME = process.env.DSH_HOME || join(homedir(), '.dsh');
 const results = []; // { section, id, ok, detail, fix? }
@@ -185,6 +188,55 @@ function checkEnv() {
   }
 }
 
+/* ================= E10：Web 端口可用性（#1719 提案；启动 dsh web 前检查，避免 address in use） =================
+ * 本地 socket bind 探测（离线兼容）：端口空闲 → PASS；被 dsh web 实例占用 → PASS+提示
+ * （宿主自身或另一实例，正常）；被其他程序占用 → FAIL。
+ * 默认 3080，可用 DSH_DOCTOR_PORT 覆盖（测试/换端口）。
+ */
+function portOccupierInfo(port) {
+  try {
+    if (process.platform === 'win32') {
+      const r = execFileSync('netstat', ['-ano'], { encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 });
+      const m = new RegExp(`TCP\\s+[^\\s]+:${port}\\s+.*?LISTENING\\s+(\\d+)`).exec(r);
+      if (!m) return null;
+      return { pid: m[1], cmd: '', dsh: false };
+    }
+    const r = execFileSync('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN'], { encoding: 'utf8', maxBuffer: 4 * 1024 * 1024 });
+    const lines = r.trim().split('\n').slice(1).filter(Boolean);
+    if (!lines.length) return null;
+    const parts = lines[0].trim().split(/\s+/);
+    const cmd = parts[0] || '';
+    const pid = parts[1] || '';
+    let dsh = /dsh|deepseek/.test(cmd);
+    if (!dsh && pid) {
+      try { dsh = /dsh web|deepseek-ai/.test(execFileSync('ps', ['-p', pid, '-o', 'command='], { encoding: 'utf8' })); } catch { /* 无法识别则按非 dsh 处理 */ }
+    }
+    return { pid, cmd, dsh };
+  } catch { return null; }
+}
+
+function checkPort3080() {
+  return new Promise((resolve) => {
+    if (!wants('env')) { resolve(); return; }
+    const port = Number(process.env.DSH_DOCTOR_PORT || 3080);
+    const srv = net.createServer();
+    srv.unref();
+    let done = false;
+    const finish = (fn) => (...args) => { if (done) return; done = true; try { fn(...args); } catch { } resolve(); };
+    srv.on('error', finish((e) => {
+      if (e.code === 'EADDRINUSE') {
+        const info = portOccupierInfo(port);
+        if (info && info.dsh) report('env', 'E10-port-3080', true, `端口 ${port} 被 dsh web 实例占用（PID ${info.pid}）——宿主自身或另一实例，正常`, undefined);
+        else if (info) report('env', 'E10-port-3080', false, `端口 ${port} 被其他程序占用（PID ${info.pid}: ${info.cmd}），dsh web 启动会 address in use（#1719）`, `关掉占用进程，或让 dsh web 用别的端口`);
+        else report('env', 'E10-port-3080', true, `⚠ 端口 ${port} 被占用但无法识别占用者`, undefined);
+      } else {
+        report('env', 'E10-port-3080', false, `端口 ${port} 探测异常: ${e.message.slice(0, 60)}`, undefined);
+      }
+    }));
+    srv.listen(port, '127.0.0.1', finish(() => { srv.close(); report('env', 'E10-port-3080', true, `端口 ${port} 空闲`, undefined); }));
+  });
+}
+
 /* ================= profile ================= */
 function checkProfile(name) {
   if (!wants('profile')) return;
@@ -235,7 +287,8 @@ function checkProfile(name) {
     const out = new Set();
     if (!existsSync(patchPath)) return out;
     const text = readFileSync(patchPath, 'utf8');
-    for (const m of text.matchAll(/^\s*-\s*name:\s*['"]?([^'"\s]+)/gm)) out.add(m[1]);
+    // 真实格式：`- id:` 下缩进的 `name:` 行（无破折号）——2026-08-15 fixtures 发现旧正则从未匹配
+    for (const m of text.matchAll(/^\s*name:\s*['"]?([^'"\s]+)/gm)) out.add(m[1]);
     return out;
   })();
 
@@ -293,17 +346,54 @@ function checkProfile(name) {
   const dangling = Object.entries(deps).filter(([, spec]) => spec.startsWith('file:')).filter(([, spec]) => !existsSync(resolveFileSpec(spec)));
   if (dangling.length) report('profile', 'P4', false, `悬空 file: 依赖（#1197）: ${dangling.map(([n, s]) => `${n} (${s})`).join(', ')}`, '恢复目录或移除依赖');
   else report('profile', 'P4', true, 'file: 依赖完整', undefined);
-  // P5 顶层 @deepseek-ai/* 重复
+  // P5 顶层 @deepseek-ai/* 重复（#1486/#1697：hoisted 布局下同版本双实例 → 模块级 Symbol 不匹配）
+  // symlink 指向宿主同一份（#1697 的 link: workaround / pnpm file: 正常形态）= 单实例，放行
   const topDup = [];
   const topDir = join(dir, 'node_modules', '@deepseek-ai');
+  const hostScope = installAnchor ? join(installAnchor, '@deepseek-ai') : null;
   if (existsSync(topDir)) {
     for (const p of readdirSync(topDir)) {
       const fp = join(topDir, p);
+      let st;
+      try { st = lstatSync(fp); } catch { continue; }
+      if (st.isSymbolicLink() && hostScope) {
+        try {
+          const real = realpathSync(fp);
+          const hostPkg = join(hostScope, p);
+          if (existsSync(hostPkg) && realpathSync(hostPkg) === real) continue; // 宿主同一份
+        } catch { /* 无法解析 → 按独立副本处理 */ }
+      }
       if (existsSync(join(fp, 'package.json'))) topDup.push(p);
     }
   }
-  if (topDup.length) report('profile', 'P5', false, `profile 顶层存在 @deepseek-ai/* 重复（#1486 双实例风险）: ${topDup.join(', ')}`, '清理 profile node_modules 中与框架版本相同的 @deepseek-ai 包（pnpm install 后会重建，需在 doctor 中提醒）');
+  if (topDup.length) report('profile', 'P5', false, `profile 顶层存在 @deepseek-ai/* 重复（#1486/#1697 双实例风险，hoisted 布局会让同版本工具包互相遮蔽导致 Symbol 不匹配）: ${topDup.join(', ')}`, '清理 profile 顶层 node_modules/@deepseek-ai 中与宿主同名的独立副本（真实目录）；指向宿主的 link: symlink 是安全的（#1697 workaround）');
   else report('profile', 'P5', true, '无顶层 @deepseek-ai 重复', undefined);
+
+  // P7 patch YAML 结构 lint（#1724：~ insert: / 顶层映射+序列混排 / tab / 缺冒号 → parsePatchList 崩 → UI 打不开）
+  // 离线、零依赖的保守检查，覆盖已实测的崩溃机制：
+  //   1) ~ / null 等非法 insert 标记（~ 是 YAML null）
+  //   2) 顶层映射(key: value)与顶层序列(- xxx)混排 → js-yaml "document separator expected"
+  //   3) tab 缩进（YAML 硬错误）；4) insert 缺冒号
+  const yamlProblems = [];
+  const patchText = existsSync(patchPath) ? readFileSync(patchPath, 'utf8') : '';
+  if (patchText) {
+    const topLines = patchText.split('\n');
+    let hasTopMapping = false, hasTopSeq = false;
+    topLines.forEach((line, i) => {
+      if (!line.trim() || line.trim().startsWith('#')) return;
+      if (line.includes('\t')) yamlProblems.push(`第 ${i + 1} 行含制表符缩进（YAML 禁止 tab）`);
+      if (/^\s*(~|null|Null|NULL)\s*insert\s*:/.test(line)) yamlProblems.push(`第 ${i + 1} 行 "${line.trim()}" —— ~ 是 YAML null 字面量，应为 "- insert:"（#1724）`);
+      else if (/^\s*-\s*insert(\s|$)/.test(line) && !/^\s*-\s*insert\s*:/.test(line)) yamlProblems.push(`第 ${i + 1} 行 "${line.trim()}" —— "- insert" 缺冒号`);
+      // 顶层混排检测：col 0 的映射键 vs col 0 的序列项
+      if (!/^\s/.test(line)) {
+        if (/^[^\s#-][^:]*:\s/.test(line)) hasTopMapping = true;
+        if (/^-\s/.test(line)) hasTopSeq = true;
+      }
+    });
+    if (hasTopMapping && hasTopSeq) yamlProblems.push('顶层同时存在 key: value 映射与 - xxx 序列（js-yaml 报 "stream or a document separator is expected"，#1724 实测）');
+  }
+  if (yamlProblems.length) report('profile', 'P7', false, `cordis.patch.yml 结构错误（boot 会崩，UI 打不开 #1724）: ${yamlProblems.join('; ')}`, 'patch 必须是顶层纯列表（只有 - insert: / - id: 条目）：删掉顶层 key: value 行；~ 是 YAML null；缩进用空格不用 tab');
+  else report('profile', 'P7', true, 'cordis.patch.yml 结构正常（无 tab / 无 ~ insert / 无映射-序列混排）', undefined);
 }
 
 /* ================= session ================= */
@@ -707,10 +797,11 @@ export function runCatalogCheck(check, ctx) {
   }
 }
 
-/** 逐条执行目录检查，汇入统一 results 管线（src='catalog'）。 */
+/** 逐条执行目录检查，汇入统一 results 管线（src='catalog'）。尊重 --profile/--env/--session 收窄。 */
 function checkCatalog(ctx, catalog) {
   const platform = process.platform;
   for (const check of catalog.checks ?? []) {
+    if (!wants(check.section)) continue; // 与内置检查一致的 section 收窄
     const when = check.when ?? {};
     if (Array.isArray(when.os) && !when.os.includes(platform)) continue;
     if (check.section === 'profile' && !ctx.profileDir) continue; // profile 无效时跳过 profile 段
@@ -723,12 +814,79 @@ function checkCatalog(ctx, catalog) {
   }
 }
 
+/* ================= 层 B：版本检查与更新（v0.2.1） =================
+ * 检查 npm dist-tags.latest 是否比本地版本新（TTL 6h 缓存 + 离线回退 last-known-good）。
+ * 默认只提示；--update 手动执行更新；DSH_DOCTOR_AUTO_UPDATE=1 可用时自动更新。
+ * 诚实边界：cordis 启动时加载插件，更新后需重启 dsh web 才生效。
+ */
+const UPDATE_URL = 'https://registry.npmjs.org/@moonquake2004%2Fdsh-doctor';
+const UPDATE_TTL_MS = 6 * 60 * 60 * 1000;
+
+export function localVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8'));
+    return typeof pkg.version === 'string' ? pkg.version : '0.0.0';
+  } catch { return '0.0.0'; }
+}
+
+/** 返回 { current, latest, available }；latest=null 表示无法确认（离线且无缓存）。 */
+export async function checkForUpdate({ noRemote = false, fetchImpl, home = HOME } = {}) {
+  const current = localVersion();
+  if (noRemote || typeof fetchImpl !== 'function') return { current, latest: null, available: false };
+  const cachePath = join(home, '.cache', 'dsh-doctor', 'update.json');
+  const readCache = () => { try { const d = JSON.parse(readFileSync(cachePath, 'utf8')); return d && typeof d.latest === 'string' ? d : null; } catch { return null; } };
+  try {
+    const c = readCache();
+    if (c && Date.now() - statSync(cachePath).mtimeMs < UPDATE_TTL_MS) return { current, latest: c.latest, available: c.latest !== current };
+  } catch { /* 回退 */ }
+  try {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), 3000);
+    const res = await fetchImpl(UPDATE_URL, { signal: ac.signal });
+    clearTimeout(timer);
+    if (res && res.ok) {
+      const data = await res.json();
+      const latest = data?.['dist-tags']?.latest;
+      if (typeof latest === 'string') {
+        try { mkdirSync(dirname(cachePath), { recursive: true }); writeFileSync(cachePath, JSON.stringify({ latest, checkedAt: new Date().toISOString() })); } catch { /* 缓存失败不影响 */ }
+        return { current, latest, available: latest !== current };
+      }
+    }
+  } catch { /* 离线/超时 → last-known-good */ }
+  const stale = readCache();
+  if (stale) return { current, latest: stale.latest, available: stale.latest !== current };
+  return { current, latest: null, available: false };
+}
+
+/** 判断本模块是否安装在某个 profile 的 node_modules 下；返回 profile 目录或 null。 */
+export function profileDirOfModule() {
+  const here = fileURLToPath(new URL('.', import.meta.url));
+  const m = here.match(/(\/\.dsh\/profiles\/[^/]+)\/node_modules\//);
+  return m ? m[1] : null;
+}
+
+/** 执行更新（profile 内 pnpm install 刷新 file:/npm 依赖；可用 DSH_DOCTOR_UPDATE_CMD 覆盖命令）。 */
+export function runUpdate() {
+  const override = process.env.DSH_DOCTOR_UPDATE_CMD;
+  if (override) {
+    const r = spawnSync(override, { shell: true, stdio: 'inherit' });
+    return r.status === 0 ? '更新命令执行完成，请重启 dsh web 生效' : `更新命令失败（exit ${r.status ?? r.error?.message}）`;
+  }
+  const profileDir = profileDirOfModule();
+  if (profileDir) {
+    const r = spawnSync('pnpm', ['install'], { cwd: profileDir, stdio: 'inherit' });
+    return r.status === 0 ? `已更新 ${profileDir}，请重启 dsh web 使新版本生效` : `pnpm install 失败（exit ${r.status ?? r.error?.message}）`;
+  }
+  return '仓库 checkout 模式：请 git pull 后重新安装插件（file: 依赖指向仓库）';
+}
+
 /* ================= main ================= */
 const profileArg = (() => { const i = process.argv.indexOf('--profile'); return i >= 0 ? process.argv[i + 1] : 'web'; })();
 const sessionArg = (() => { const i = process.argv.indexOf('--session'); return i >= 0 ? process.argv[i + 1] : undefined; })();
 
 async function run() {
   try { checkEnv(); } catch (e) { report('env', 'E0', false, `env 检查异常: ${e.message.slice(0, 80)}`); }
+  try { await checkPort3080(); } catch (e) { report('env', 'E10-port-3080', false, `端口检查异常: ${e.message.slice(0, 60)}`); }
   try { checkProfile(profileArg); } catch (e) { report('profile', 'P0', false, `profile 检查异常: ${e.message.slice(0, 100)}`); }
   try { checkSession(sessionArg); } catch (e) { report('session', 'S0', false, `session 检查异常: ${e.message.slice(0, 100)}`); }
   try { scanAllSessions(); } catch (e) { report('session', 'S11', false, `全会话扫描异常: ${e.message.slice(0, 100)}`); }
@@ -745,10 +903,22 @@ async function run() {
     catalogMeta = { source: 'error', checks: 0, error: e.message.slice(0, 80) };
   }
 
+  // 层 B：版本检查与更新（--no-catalog 同时禁用网络检查；--update 手动更新；DSH_DOCTOR_AUTO_UPDATE=1 自动）
+  const noRemote = process.argv.includes('--no-catalog');
+  let updateInfo = { current: localVersion(), latest: null, available: false };
+  try {
+    updateInfo = await checkForUpdate({ noRemote, fetchImpl: typeof fetch === 'function' ? fetch : undefined });
+  } catch (e) {
+    updateInfo = { current: localVersion(), latest: null, available: false, error: e.message.slice(0, 60) };
+  }
+  if (process.argv.includes('--update') || (process.env.DSH_DOCTOR_AUTO_UPDATE === '1' && updateInfo.available)) {
+    updateInfo.applied = runUpdate();
+  }
+
   // 退出码只计内置失败 + catalog 中 severity=error 的失败；warn 失败提示但不改退出码
   const bad = results.filter((r) => !r.ok && catalogSeverity.get(r.id) !== 'warn');
   if (jsonOut) {
-    console.log(JSON.stringify({ ok: bad.length === 0, checks: results, catalog: catalogMeta }, null, 2));
+    console.log(JSON.stringify({ ok: bad.length === 0, checks: results, catalog: catalogMeta, update: updateInfo }, null, 2));
   } else {
     const sectionOrder = { env: 0, profile: 1, session: 2, catalog: 3 };
     const ordered = [...results].sort((a, b) => (sectionOrder[a.section] ?? 9) - (sectionOrder[b.section] ?? 9));
@@ -760,6 +930,11 @@ async function run() {
       console.log(` ${mark} [${r.id}] ${r.detail}${r.src === 'catalog' ? '  [目录]' : ''}`);
       if (!r.ok && r.fix) console.log(`     ↳ 修复: ${r.fix}`);
     }
+    if (updateInfo.available && !updateInfo.applied) {
+      console.log(`\n⚠ 新版本 ${updateInfo.latest} 可用（当前 ${updateInfo.current}）→ 运行 \`dsh-doctor --update\` 或 \`dsh plugin update\``);
+    } else if (updateInfo.applied) {
+      console.log(`\n✓ ${updateInfo.applied}`);
+    }
     console.log(`\n${bad.length === 0 ? '✓ 全部通过' : `✗ ${bad.length} 个问题`}（profile=${profileArg}，目录=${catalogMeta.source}，${catalogMeta.checks} 条）`);
   }
   process.exit(bad.length === 0 ? 0 : 1);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@moonquake2004/dsh-doctor",
-  "version": "0.2.0",
-  "description": "Offline diagnostic for DeepSeek Harness — 19 built-in checks across env/profile/session, plus a self-updating remote catalog of declarative pattern checks; 'Doctor' panel in the web UI settings.",
+  "version": "0.2.3",
+  "description": "Offline diagnostic for DeepSeek Harness — 19 built-in checks + self-updating catalog (Layer A) + self-update check (Layer B); 'Doctor' panel in web UI settings.",
   "main": "lib/index.js",
   "files": [
     "lib",