@moonquake2004/dsh-doctor 0.2.6 → 0.3.0

package/README.md

@@ -74,6 +74,31 @@ With `--envelope` (doctor-contract mode): `0` = all pass · `1` = any WARN · `2
 
 
 
+## Symptom → check quick-start (dsh-diagnose alignment)
+
+If you're coming from a symptom (rather than from the machine), these are the checks to run first. Coverage is honest: ✅ = direct offline coverage, ⚠️ = partial (we see the log/profile effects, not the runtime internals), ❌ = gap (runtime-only, no offline probe today).
+
+| Symptom family | dsh-doctor checks | What they catch |
+|---|---|---|
+| session log corruption / can't resume | S1, S2, S6, S7, S8, S9, S10 | orphan tool calls, unclosed turns, seq gaps, end-seed replay, unknown event types, zstd single-frame, sourceEventSeqs drift |
+| oversized / cold-start stall | S11 | estimated materialization heap, corrupt-session quarantine |
+| boot failure (UI won't open) | P1–P10, E10 | dangling bundles, id collisions, patch syntax, host shadowing, adapter conflicts, client-service injects, port 3080 |
+| tool registry gaps (tools missing) | P1, P2, P8, P10, P9 | unresolved/conflicting/duplicated tool registrations, client-only service injects |
+| compaction / history unavailable | S10, S6, S8 | sourceEventSeqs not remapped after compaction |
+| agent-loop lifecycle (session stuck "running") | S2, S1, S6 | unclosed turns, orphan tool calls, broken seq |
+| llm retry storms | S6, S11, S2 | retry traffic effects on log integrity/size |
+| token metering off | S11, S1, S2 | metering derives from the event stream |
+| workflow script failures | P7, S6, S8, S1 | patch syntax (boot), workflow event integrity |
+| approval policy pending | S2, S1 | open turns / orphan calls from pending or rejected approvals |
+| credentials resolution | E2, E5, P4 | `.env` shape, storage JSON, `file:` links |
+| web internals | E10, P10, E5 | port, client half, workspace storage |
+| subagent depth | S11, S8 | session size, subagent event types |
+| sandbox denials | E4 | node-pty binary (infra only) — ❌ runtime policy not offline-checkable |
+| approval internals | S2 | ⚠️ runtime policy; only the turn-level effect |
+| credentials internals | E2, E5 | ⚠️ file-level only |
+
+The `dsh-doctor/v1` envelope (`--json --envelope`) is the machine-readable form of any of these runs, so a symptom tool can consume the verdict directly.
+
 ## Self-update check (v0.2.1, Layer B)
 
 The tool also watches its own npm version: each run compares the installed version against `dist-tags.latest` (same 6h TTL cache + offline fallback as the catalog). When a newer release exists it prints a notice and reports `update: { current, latest, available }` in JSON — it never touches your install without being asked.
@@ -101,6 +126,16 @@ The built-in 20 checks are compiled into the tool. The **catalog** is a second,
 
 Catalog check results are marked `src: "catalog"` in JSON output and `[目录]` in CLI output.
 
+## LLM observer (v0.3.0, Layer C)
+
+The third layer closes the loop between field signals and the catalog: **semi-automatic candidate-check proposals** from a diagnostics run, with a human certification gate. Design + details in [`docs/layer-c-observer.md`](docs/layer-c-observer.md).
+
+- `dsh-doctor --observe run.json` — cluster the fail/warn signals of a diagnostics run (a `--json` / `--envelope` output, or a directory of JSON files), then draft candidate checks in the catalog schema (deterministic, default `severity: warn`).
+- `--observe-llm "<cmd>"` (or `DSH_DOCTOR_LLM_CMD`) — enrich drafts with an LLM: `cmd` reads the prompt on stdin and writes a JSON reply on stdout. Replies are constrained to the closed probe vocabulary; any parse/schema violation silently falls back to the draft.
+- `--observe-apply proposals.json` — merge **validated** proposals into the local overlay `plugin/checks.local.json` (idempotent). The overlay runs in diagnostics until you certify the check, but is never distributed — certified checks belong in `plugin/checks.json`.
+
+Safety invariants: closed probe vocabulary (LLM output is data, never code), proposals default to `warn`, nothing auto-ships, and no external service is required (no `--observe-llm` = deterministic mode).
+
 ## Also installable as a dsh plugin
 
 The tool ships as a proper dsh bundle (`plugin/`), so you can run the same checks (20 built-in + catalog rules) from inside the web UI:

package/README.zh.md

@@ -67,6 +67,31 @@ node dsh-doctor.mjs --no-catalog         # 不拉远程目录（只用内置副
 - [zoahdev/dsh-plugin-doctor](https://github.com/zoahdev/dsh-plugin-doctor) —— 发布前插件 bundle 健康检查（manifest/patch/entry/files/build/pack+全新 profile 安装）+ 宿主遮蔽 `profile-shadow` 哨兵（作者/CI 侧）。与本工具的用户侧 profile/session/env 诊断互补；它的 `profile-shadow` 与我们的 P5 从两个方向标记同一个宿主遮蔽前置条件。
 - [boyin111-1/dsh-doctor](https://github.com/boyin111-1/dsh-doctor) —— 同生态位离线诊断兄弟实现，用同一批坏 fixture 交叉验证。
 
+## Symptom → check quick-start (dsh-diagnose alignment)
+
+If you're coming from a symptom (rather than from the machine), these are the checks to run first. Coverage is honest: ✅ = direct offline coverage, ⚠️ = partial (we see the log/profile effects, not the runtime internals), ❌ = gap (runtime-only, no offline probe today).
+
+| Symptom family | dsh-doctor checks | What they catch |
+|---|---|---|
+| session log corruption / can't resume | S1, S2, S6, S7, S8, S9, S10 | orphan tool calls, unclosed turns, seq gaps, end-seed replay, unknown event types, zstd single-frame, sourceEventSeqs drift |
+| oversized / cold-start stall | S11 | estimated materialization heap, corrupt-session quarantine |
+| boot failure (UI won't open) | P1–P10, E10 | dangling bundles, id collisions, patch syntax, host shadowing, adapter conflicts, client-service injects, port 3080 |
+| tool registry gaps (tools missing) | P1, P2, P8, P10, P9 | unresolved/conflicting/duplicated tool registrations, client-only service injects |
+| compaction / history unavailable | S10, S6, S8 | sourceEventSeqs not remapped after compaction |
+| agent-loop lifecycle (session stuck "running") | S2, S1, S6 | unclosed turns, orphan tool calls, broken seq |
+| llm retry storms | S6, S11, S2 | retry traffic effects on log integrity/size |
+| token metering off | S11, S1, S2 | metering derives from the event stream |
+| workflow script failures | P7, S6, S8, S1 | patch syntax (boot), workflow event integrity |
+| approval policy pending | S2, S1 | open turns / orphan calls from pending or rejected approvals |
+| credentials resolution | E2, E5, P4 | `.env` shape, storage JSON, `file:` links |
+| web internals | E10, P10, E5 | port, client half, workspace storage |
+| subagent depth | S11, S8 | session size, subagent event types |
+| sandbox denials | E4 | node-pty binary (infra only) — ❌ runtime policy not offline-checkable |
+| approval internals | S2 | ⚠️ runtime policy; only the turn-level effect |
+| credentials internals | E2, E5 | ⚠️ file-level only |
+
+The `dsh-doctor/v1` envelope (`--json --envelope`) is the machine-readable form of any of these runs, so a symptom tool can consume the verdict directly.
+
 ## 自更新检查（v0.2.1，层 B）
 
 工具也会盯着自己的 npm 版本：每次运行对比已装版本与 `dist-tags.latest`（与目录同样的 6h TTL 缓存 + 离线回退）。有新版时打印提示、JSON 里报 `update: { current, latest, available }`——**未经你要求绝不改动你的安装**。
@@ -94,6 +119,16 @@ node dsh-doctor.mjs --no-catalog         # 不拉远程目录（只用内置副
 
 目录检查的结果在 JSON 输出中标 `src: "catalog"`，CLI 输出标 `[目录]`。
 
+## LLM 观察者（v0.3.0，层 C）
+
+第三层把"现场信号 → 目录条目"的回路半自动化：从诊断运行产出**候选检查提案**，人做最后把关（认证门禁不变）。设计与细节见 [`docs/layer-c-observer.md`](docs/layer-c-observer.md)。
+
+- `dsh-doctor --observe run.json` —— 聚类诊断运行的 fail/warn 信号（`--json` / `--envelope` 输出，或含 JSON 的目录），按目录 schema 起草候选检查（确定性，默认 `severity: warn`）。
+- `--observe-llm "<cmd>"`（或 `DSH_DOCTOR_LLM_CMD`）—— 用 LLM 富化草稿：`cmd` 从 stdin 收 prompt，stdout 回 JSON。回复被封闭探测词表约束，任何解析/词表违规静默回退草稿。
+- `--observe-apply proposals.json` —— 把**校验通过**的提案并入本地覆盖层 `plugin/checks.local.json`（幂等）。覆盖层参与本地诊断直到你认证该检查，但永不随包分发——认证后的检查应进 `plugin/checks.json`。
+
+安全不变量：封闭探测词表（LLM 输出永远是数据、不是代码）、提案默认 warn、不自动上目录、不依赖任何外部服务（不带 `--observe-llm` 即确定性模式）。
+
 ## 也可作为 dsh 插件安装
 
 工具以标准 dsh bundle 形态发布（`plugin/`），可以在 web UI 里跑同样的检查（20 内置 + 目录规则）：

package/dsh-doctor.mjs

@@ -12,6 +12,8 @@
  *     P7  cordis.patch.yml 结构 lint（#1724：~ insert: 是 YAML null → parsePatchList 崩溃 → UI 打不开；tab 缩进/缺冒号同族）
  *     P8  adapter provider 注册冲突（#1904②：两 bundle 抢注同一 provider → boot 时 DUPLICATE_ADAPTER 崩溃）
  *     P9  ctx.settings 未声明 inject: ['settings']（#1904⑤：先于 settings 就绪激活 → namespace not registered）
+ *     P10 inject 引用客户端专属服务（#1947：@deepseek-ai/dsh-client-* 服务端永不提供 → Fiber 永久 PENDING → web boot 失败）
+ *     P11 已装 bundle 的 main 入口产物缺失（#1965：市场装未构建源码树 → ERR_MODULE_NOT_FOUND → boot 崩）
  *   [session]
  *     S1  孤儿 tool_call（#1363：assistant tool_calls 无对应 tool 结果 → INVALID_REQUEST）
  *     S2  未闭合 turn（#466/#1265：turn/start 无 turn/end → 会话永久"运行中"）
@@ -49,7 +51,7 @@ import { execFileSync, spawnSync } from 'node:child_process';
 import { closeSync, existsSync, lstatSync, mkdirSync, openSync, 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 { basename, delimiter as PATH_DELIM, dirname, join, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { pathToFileURL, fileURLToPath } from 'node:url';
 
@@ -215,7 +217,17 @@ function portOccupierInfo(port) {
     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 处理 */ }
+      try {
+        dsh = /dsh web|deepseek-ai|harness/.test(execFileSync('ps', ['-p', pid, '-o', 'command='], { encoding: 'utf8' }));
+      } catch { /* ps 不可用（权限/平台）→ 走 lsof 兜底 */ }
+      if (!dsh) {
+        try {
+          // 兜底：ps 命令串可能不含连续 "dsh web"（npx/pnpm 安装形态），改用 lsof 的 cwd/txt 路径识别 harness 安装。
+          // 只认真实安装签名（npx 缓存 / @deepseek-ai 包目录），避免把任意含 "dsh" 路径段的工作目录误判为 dsh。
+          const lsofP = execFileSync('lsof', ['-p', pid], { encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 });
+          dsh = /\.npm\/_npx\/|node_modules\/@deepseek-ai\//.test(lsofP);
+        } catch { /* 无法识别则按非 dsh 处理 */ }
+      }
     }
     return { pid, cmd, dsh };
   } catch { return null; }
@@ -455,6 +467,18 @@ function checkProfile(name) {
     report('profile', 'P8', true, '无 adapter provider 注册冲突', undefined);
   }
 
+  // 提取 bundle 构建产物里声明的全部 inject 依赖名（模块 inject + ctx.inject；bundle 可能混入内部模块的 inject）
+  const bundleInjectDecls = (all) => {
+    const declared = [];
+    for (const m of all.matchAll(/inject\s*=\s*\[([^\]]*)\]/gs)) {
+      declared.push(...[...m[1].matchAll(/['"]([^'"]+)['"]/g)].map((x) => x[1]));
+    }
+    for (const m of all.matchAll(/ctx\.inject\s*\(\s*\[([^\]]*)\]/g)) {
+      declared.push(...[...m[1].matchAll(/['"]([^'"]+)['"]/g)].map((x) => x[1]));
+    }
+    return declared.filter((v, i) => declared.indexOf(v) === i);
+  };
+
   // P9：ctx.settings/ctx.get('settings') 未声明 settings 依赖（#1904⑤：先于 settings 就绪激活 → namespace not registered）
   // 注意边界：sctx.settings 不算（sctx 是别的变量）；ctx.inject(["settings"], cb) 运行时声明算满足
   const injectIssues = [];
@@ -463,21 +487,36 @@ function checkProfile(name) {
     const all = files.map(readJs).join('\n');
     const usesSettings = /(?<![A-Za-z0-9_$])ctx\.(?:get\(\s*['"]settings['"]\s*\)|settings\b)/.test(all);
     if (!usesSettings) continue;
-    const declared = [];
-    // 收集全部 inject 声明（bundle 里可能混有内部模块的 inject；任一含 settings 即满足）
-    for (const m of all.matchAll(/inject\s*=\s*\[([^\]]*)\]/gs)) {
-      declared.push(...[...m[1].matchAll(/['"]([^'"]+)['"]/g)].map((x) => x[1]));
-    }
-    for (const m of all.matchAll(/ctx\.inject\s*\(\s*\[([^\]]*)\]/g)) {
-      declared.push(...[...m[1].matchAll(/['"]([^'"]+)['"]/g)].map((x) => x[1]));
-    }
-    const uniq = declared.filter((v, i) => declared.indexOf(v) === i);
+    const uniq = bundleInjectDecls(all);
     if (!uniq.includes('settings')) {
       injectIssues.push(`${b}（用 ctx.settings 但 settings 依赖未声明${uniq.length ? `，全部 inject: [${uniq.join(', ')}]` : '，未找到任何 inject 声明'}）`);
     }
   }
   if (injectIssues.length) report('profile', 'P9', false, `插件用 ctx.settings 但未声明 settings 依赖（#1904⑤：激活时 settings 可能未就绪 → namespace not registered）: ${injectIssues.join('; ')}`, '在插件代码加 export const inject = ["settings"]（或对可选服务做 undefined 处理）');
   else report('profile', 'P9', true, 'bundle 的 ctx.settings 用法均声明了 settings 依赖（模块 inject 或 ctx.inject）', undefined);
+
+  // P10：inject 引用客户端专属服务（@deepseek-ai/dsh-client-*）→ 服务端永不提供 → Fiber 永久 PENDING → web boot 失败（#1947）
+  const clientInjectIssues = [];
+  for (const [b, d] of bundleDirs) {
+    const all = collectJsFiles(d).map(readJs).join('\n');
+    const clientDeps = bundleInjectDecls(all).filter((n) => /^(@deepseek-ai\/)?dsh-client-/.test(n));
+    if (clientDeps.length) clientInjectIssues.push(`${b}（inject 引用客户端专属服务: ${clientDeps.join(', ')}）`);
+  }
+  if (clientInjectIssues.length) report('profile', 'P10', false, `插件 inject 引用客户端专属服务（服务端 cordis 树永不提供 → Fiber 永久 PENDING → web boot 失败，#1947）: ${clientInjectIssues.join('; ')}`, '客户端服务不能作为服务端插件依赖：把相关功能移到插件 client 半（package.json 的 dsh.client.inject），或删除该 inject');
+  else report('profile', 'P10', true, '无客户端专属服务注入', undefined);
+
+  // P11：已装 bundle 的 main 入口产物缺失（#1965：市场把未构建源码树当插件装 → ERR_MODULE_NOT_FOUND → boot 崩）
+  const entryIssues = [];
+  for (const [b, d] of bundleDirs) {
+    let main;
+    try { main = JSON.parse(readFileSync(join(d, 'package.json'), 'utf8')).main; } catch { continue; }
+    if (typeof main !== 'string' || !main.endsWith('.js')) continue;
+    if (!existsSync(join(d, main))) {
+      entryIssues.push(`${b}（main=${main} 但产物缺失——未构建的源码树，或装错了仓库根而非 monorepo 子包）`);
+    }
+  }
+  if (entryIssues.length) report('profile', 'P11', false, `已装 bundle 的 main 入口缺失（#1965：市场装源码不跑构建 → ERR_MODULE_NOT_FOUND → dsh web boot 崩溃）: ${entryIssues.join('; ')}`, '在插件目录跑构建（pnpm install && pnpm run build 产出 main 指向的文件），或改用打包好的 npm 包安装；monorepo 插件需装子包（dsh-market #18 同族）');
+  else report('profile', 'P11', true, '已装 bundle 的 main 入口产物均在', undefined);
 }
 
 /* ================= session ================= */
@@ -716,36 +755,52 @@ function bundledCatalog() {
   try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return { schemaVersion: 1, checks: [] }; }
 }
 
+/** 本地覆盖层（层 C 观察者 --observe-apply 写入）：合法则追加，非法/缺失 → []。 */
+function localOverlay(path) {
+  const p = path ?? fileURLToPath(new URL('./checks.local.json', import.meta.url));
+  try { const d = JSON.parse(readFileSync(p, 'utf8')); return validCatalog(d) ? d.checks : []; } catch { return []; }
+}
+
 function validCatalog(data) {
   return !!data && data.schemaVersion === 1 && Array.isArray(data.checks);
 }
 
-/** 拉取目录：新鲜缓存(≤TTL) → 远程(raw.githubusercontent，3s 超时) → 旧缓存(last-known-good) → 内置副本。 */
-async function loadCatalog({ noRemote = false, fetchImpl, home = HOME } = {}) {
+/** 拉取目录：新鲜缓存(≤TTL) → 远程(raw.githubusercontent，3s 超时) → 旧缓存(last-known-good) → 内置副本；末尾合并本地覆盖层。 */
+async function loadCatalog({ noRemote = false, fetchImpl, home = HOME, localPath } = {}) {
   const bundled = bundledCatalog();
-  if (noRemote || typeof fetchImpl !== 'function') return { checks: bundled.checks, source: 'bundled' };
-  const cachePath = join(home, '.cache', 'dsh-doctor', 'checks.json');
-  const readCache = () => { if (!existsSync(cachePath)) return null; try { const d = JSON.parse(readFileSync(cachePath, 'utf8')); return validCatalog(d) ? d : null; } catch { return null; } };
-  try {
-    const cached = readCache();
-    if (cached && Date.now() - statSync(cachePath).mtimeMs < CATALOG_TTL_MS) return { checks: cached.checks, source: 'cache' };
-  } catch { /* 回退 */ }
-  try {
-    const ac = new AbortController();
-    const timer = setTimeout(() => ac.abort(), 3000);
-    const res = await fetchImpl(REMOTE_CATALOG_URL, { signal: ac.signal });
-    clearTimeout(timer);
-    if (res && res.ok) {
-      const data = await res.json();
-      if (validCatalog(data)) {
-        try { mkdirSync(dirname(cachePath), { recursive: true }); writeFileSync(cachePath, JSON.stringify(data, null, 2)); } catch { /* 缓存写入失败不影响本次运行 */ }
-        return { checks: data.checks, source: 'remote' };
-      }
+  let base;
+  if (noRemote || typeof fetchImpl !== 'function') {
+    base = { checks: bundled.checks, source: 'bundled' };
+  } else {
+    const cachePath = join(home, '.cache', 'dsh-doctor', 'checks.json');
+    const readCache = () => { if (!existsSync(cachePath)) return null; try { const d = JSON.parse(readFileSync(cachePath, 'utf8')); return validCatalog(d) ? d : null; } catch { return null; } };
+    try {
+      const cached = readCache();
+      if (cached && Date.now() - statSync(cachePath).mtimeMs < CATALOG_TTL_MS) base = { checks: cached.checks, source: 'cache' };
+    } catch { /* 回退 */ }
+    if (!base) {
+      try {
+        const ac = new AbortController();
+        const timer = setTimeout(() => ac.abort(), 3000);
+        const res = await fetchImpl(REMOTE_CATALOG_URL, { signal: ac.signal });
+        clearTimeout(timer);
+        if (res && res.ok) {
+          const data = await res.json();
+          if (validCatalog(data)) {
+            try { mkdirSync(dirname(cachePath), { recursive: true }); writeFileSync(cachePath, JSON.stringify(data, null, 2)); } catch { /* 缓存写入失败不影响本次运行 */ }
+            base = { checks: data.checks, source: 'remote' };
+          }
+        }
+      } catch { /* 离线/超时 → 回退 */ }
     }
-  } catch { /* 离线/超时 → 回退 */ }
-  const stale = readCache();
-  if (stale) return { checks: stale.checks, source: 'cache-stale' };
-  return { checks: bundled.checks, source: 'bundled' };
+    if (!base) {
+      const stale = readCache();
+      base = stale ? { checks: stale.checks, source: 'cache-stale' } : { checks: bundled.checks, source: 'bundled' };
+    }
+  }
+  const local = localOverlay(localPath);
+  if (!local.length) return base;
+  return { checks: [...base.checks, ...local], source: base.source === 'bundled' ? 'bundled+local' : `${base.source}+local` };
 }
 
 function expandPath(tpl, ctx) {
@@ -975,10 +1030,43 @@ export function runUpdate() {
 }
 
 /* ================= main ================= */
+const flagValue = (name) => { const i = process.argv.indexOf(name); return i >= 0 ? process.argv[i + 1] : undefined; };
 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() {
+  // 层 C 观察者（--observe / --observe-apply）：独立子命令，跑完即退出，不执行常规检查
+  const observeArg = flagValue('--observe');
+  const observeApplyArg = flagValue('--observe-apply');
+  const llmCmd = process.argv.includes('--observe-llm') ? flagValue('--observe-llm') : process.env.DSH_DOCTOR_LLM_CMD ?? null;
+  if (observeArg || observeApplyArg) {
+    const { runObserver, applyProposals, writeLocalOverlay, readLocalOverlay } = await import('./observer.mjs');
+    try {
+      if (observeApplyArg) {
+        const raw = JSON.parse(readFileSync(resolve(observeApplyArg), 'utf8'));
+        const list = Array.isArray(raw) ? raw : raw.proposals ?? [];
+        const overlayPath = join(dirname(fileURLToPath(import.meta.url)), 'checks.local.json');
+        // 覆盖层只追加新提案（loadCatalog 会 base + local 合并），且对已存在覆盖层幂等
+        const existing = readLocalOverlay(overlayPath);
+        const { catalog: merged, applied, rejected } = applyProposals({ schemaVersion: 1, checks: existing }, list);
+        if (applied.length) {
+          writeLocalOverlay(overlayPath, {
+            schemaVersion: 1,
+            description: 'Layer C 观察者本地覆盖层——未认证提案，不随包分发；认证通过后请合并进 checks.json 并删除本文件。',
+            checks: merged.checks,
+          });
+        }
+        console.log(JSON.stringify({ ok: true, written: applied.length ? overlayPath : null, applied: applied.map((p) => p.id), rejected }, null, 2));
+        process.exit(0);
+      }
+      const res = await runObserver({ path: observeArg, existingChecks: bundledCatalog().checks, llmCmd });
+      console.log(JSON.stringify(res, null, 2));
+      process.exit(0);
+    } catch (e) {
+      console.error(`观察者失败: ${e.message}`);
+      process.exit(1);
+    }
+  }
   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)}`); }
@@ -1019,6 +1107,7 @@ async function run() {
     const exitCode = summary.fail > 0 ? 2 : summary.warn > 0 ? 1 : 0;
     console.log(JSON.stringify({
       schema: 'dsh-doctor/v1',
+      tool: 'dsh-doctor',
       generatedAt: new Date().toISOString(),
       profile: profileArg,
       exitCode,

package/observer.mjs

@@ -0,0 +1,325 @@
+/**
+ * Layer C — 半自动 LLM 观察者（MVP）
+ *
+ * 纯函数模块：从诊断运行现场信号 → 聚类 → 确定性草稿 →（可选）LLM 富化
+ * → 人审补全 → 校验合并进本地覆盖层。安全不变量见 docs/layer-c-observer.md：
+ *   1. 封闭探测词表（与引擎同表），LLM 输出永远是数据、永远不能成为代码；
+ *   2. 候选默认 severity=warn，不直接制造 error 告警；
+ *   3. --observe-apply 只合并校验通过的提案，且只写本地覆盖层，不自动进目录；
+ *   4. LLM 未配置/超时/输出非法 → 静默回退确定性草稿，工具不依赖外部服务。
+ *
+ * 用法（CLI 接线在 dsh-doctor.mjs）：
+ *   node dsh-doctor.mjs --observe run.json
+ *   node dsh-doctor.mjs --observe run.json --observe-llm "<cmd 读 stdin 写 stdout>"
+ *   node dsh-doctor.mjs --observe-apply proposals.json
+ */
+
+import { readFileSync, readdirSync, statSync, writeFileSync, mkdirSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { dirname, join, isAbsolute, resolve } from 'node:path';
+
+/** 封闭探测词表：type → 该类型必填参数（与 plugin/dsh-doctor.mjs 引擎原语一致）。 */
+export const PROBE_VOCABULARY = {
+  'command-exists': ['cmd'],
+  'path-exists': ['path'],
+  'path-is-dir': ['path'],
+  'path-is-file': ['path'],
+  'json-valid': ['path'],
+  'text-contains': ['path', 'pattern'],
+  'text-not-contains': ['path', 'pattern'],
+  'file-size-above': ['path', 'min'],
+  'glob-count': ['base', 'pattern'],
+  'file-writable': ['path'],
+};
+
+const SECTIONS = new Set(['env', 'profile', 'session', 'catalog']);
+const SEVERITIES = new Set(['error', 'warn']);
+
+/** 症状 → 探测词表提示映射（确定性草稿用；LLM 富化可改，但必须仍在词表内）。 */
+const PROBE_HINTS = [
+  { re: /json/i, type: 'json-valid', hint: '目标文件 JSON 合法性' },
+  { re: /path|which|command|命令|不在|未安装|executable|bin/i, type: 'command-exists', hint: '命令/可执行文件在 PATH' },
+  { re: /writ|可写|权限|属主|chown|sudo|readonly|只读/i, type: 'file-writable', hint: '文件可写性' },
+  { re: /patch|insert|yaml|yml|cordis/i, type: 'text-contains', hint: '文本模式匹配（patch/配置类）' },
+  { re: /port|端口|3080|listen/i, type: 'path-exists', hint: '路径存在性（端口/资源占位）' },
+  { re: /glob|文件数|count|recursive|目录/i, type: 'glob-count', hint: '目录递归文件计数' },
+];
+
+/** 从任意常见诊断输出形态抽取检查条目：数组 / {checks} / {results}。 */
+export function extractChecks(data) {
+  if (Array.isArray(data)) return data;
+  if (data && Array.isArray(data.checks)) return data.checks; // envelope（v1）与 plain JSON 都用 checks
+  if (data && Array.isArray(data.results)) return data.results;
+  return [];
+}
+
+/** 检查条目 → 状态：'pass' | 'fail' | 'warn' | 'unknown'（envelope 用 status，plain 用 ok）。 */
+export function checkStatus(c) {
+  if (typeof c.status === 'string') return ['pass', 'warn', 'fail'].includes(c.status) ? c.status : 'unknown';
+  if (c.ok === false) return 'fail';
+  if (c.ok === true) return 'pass';
+  return 'unknown';
+}
+
+/** 检查条目 → section（envelope 无 section 字段，按 id 前缀推断）。 */
+export function checkSection(c) {
+  if (typeof c.section === 'string' && SECTIONS.has(c.section)) return c.section;
+  const id = String(c.id ?? c.name ?? '');
+  if (/^E/i.test(id)) return 'env';
+  if (/^P/i.test(id)) return 'profile';
+  if (/^S/i.test(id)) return 'session';
+  if (/^C/i.test(id)) return 'catalog';
+  return 'env';
+}
+
+/** detail 归一化：小写、trim、去空白折叠、去尾标点。聚类键的一部分，保证同义症状合簇。 */
+export function normalizeDetail(text) {
+  return String(text ?? '')
+    .toLowerCase()
+    .trim()
+    .replace(/\s+/g, ' ')
+    .replace(/[.。!！?？;；,，:：]+$/g, '')
+    .trim();
+}
+
+/**
+ * 聚类：按 (section, 归一化 detail) 分簇 fail/warn 信号。
+ * 返回 [{ section, signature, count, examples: [原始 detail], statuses: Set }]
+ */
+export function clusterSignals(data) {
+  const clusters = new Map();
+  for (const c of extractChecks(data)) {
+    const st = checkStatus(c);
+    if (st !== 'fail' && st !== 'warn') continue;
+    const section = checkSection(c);
+    const detail = String(c.detail ?? c.name ?? c.id ?? '');
+    const sig = normalizeDetail(detail);
+    const key = `${section}|${sig}`;
+    if (!clusters.has(key)) {
+      clusters.set(key, { section, signature: sig, count: 0, examples: [], statuses: new Set() });
+    }
+    const cl = clusters.get(key);
+    cl.count++;
+    cl.statuses.add(st);
+    if (cl.examples.length < 3 && !cl.examples.includes(detail)) cl.examples.push(detail);
+  }
+  return [...clusters.values()].map((c) => ({ ...c, statuses: [...c.statuses] }));
+}
+
+/** signature → 短 slug（候选检查 id 用）。 */
+export function slugOf(signature, maxWords = 5) {
+  const words = signature.split(' ').filter(Boolean).slice(0, maxWords);
+  let slug = words.map((w) => w.replace(/[^a-z0-9]+/g, '-')).join('-').replace(/^-+|-+$/g, '');
+  if (!slug) slug = 'signal';
+  return slug.slice(0, 48);
+}
+
+/** 确定性草稿：症状 → 候选检查骨架（探测参数大概率不全，正是留给 LLM/人补全的点）。 */
+export function draftProposal(cluster, existingIds = [], seq = 0) {
+  const hint = PROBE_HINTS.find((h) => h.re.test(cluster.signature)) ?? { type: 'text-contains', hint: '文本模式匹配' };
+  const base = `${cluster.section}-${slugOf(cluster.signature)}`;
+  let id = `${base}-probe`;
+  let n = 0;
+  while (existingIds.includes(id)) id = `${base}-${++n + 1}-probe`; // 去重：追加序号
+  const p = {
+    id,
+    section: cluster.section,
+    severity: 'warn', // 安全不变量 2：候选默认 warn
+    title: `候选检查（观察者 #${seq + 1}）：${cluster.signature.slice(0, 48)}`,
+    discussion: null,
+    anchor: { package: null, symbol: null, train: null },
+    probe: skeletonProbe(hint.type),
+    detailOk: `通过（待补）——${hint.hint}`,
+    detailFail: `命中（待补）：${cluster.signature.slice(0, 80)}`,
+    fix: '待补：给出可执行修复建议',
+    proposedBy: 'observer',
+    proposedAt: new Date().toISOString(),
+  };
+  return p;
+}
+
+function skeletonProbe(type) {
+  switch (type) {
+    case 'command-exists': return { type, cmd: '' };
+    case 'path-exists':
+    case 'path-is-dir':
+    case 'path-is-file':
+    case 'json-valid':
+    case 'file-writable': return { type, path: '', required: false };
+    case 'text-contains':
+    case 'text-not-contains': return { type, path: '', pattern: '', flags: '', required: false };
+    case 'file-size-above': return { type, path: '', min: 0, required: false };
+    case 'glob-count': return { type, base: '', pattern: '', required: false };
+    default: return { type };
+  }
+}
+
+/** 提案校验：词表/必填参数/section/severity/id 唯一性。返回 { ok, errors[] }。 */
+export function validateProposal(p, existingIds = []) {
+  const errors = [];
+  if (!p || typeof p !== 'object') return { ok: false, errors: ['提案不是对象'] };
+  if (typeof p.id !== 'string' || !p.id.trim()) errors.push('id 缺失');
+  else if (existingIds.includes(p.id)) errors.push(`id 重复: ${p.id}`);
+  if (!SECTIONS.has(p.section)) errors.push(`section 非法: ${p.section}`);
+  if (!SEVERITIES.has(p.severity)) errors.push(`severity 非法: ${p.severity}`);
+  const t = p.probe?.type;
+  if (!PROBE_VOCABULARY[t]) errors.push(`probe.type 不在词表: ${t}`);
+  else {
+    for (const key of PROBE_VOCABULARY[t]) {
+      const v = p.probe[key];
+      if (v === undefined || v === null || v === '' || (typeof v === 'number' && Number.isNaN(v))) errors.push(`probe.${key} 缺失（${t} 必填）`);
+    }
+  }
+  if (p.probe?.type === 'file-size-above' && typeof p.probe.min !== 'number') errors.push('probe.min 必须为数字');
+  return { ok: errors.length === 0, errors };
+}
+
+/** LLM prompt：给定现场信号 + 现有目录（id 清单防撞），要求输出词表内 JSON。 */
+export function renderLLMPrompt(cluster, draft, existingChecks = []) {
+  const vocab = Object.keys(PROBE_VOCABULARY).join(', ');
+  return [
+    '你是 dsh-doctor 的候选检查起草助手（Layer C 观察者）。只输出一个 JSON 对象，不要任何多余文字。',
+    '',
+    `现场信号：section=${cluster.section}，命中 ${cluster.count} 次（${cluster.statuses.join('/')}）`,
+    `症状详情：${cluster.signature}`,
+    `示例：${cluster.examples.map((e) => JSON.stringify(e)).join(' ; ')}`,
+    '',
+    '输出 JSON 只能含这些键（全部可选，缺省回退草稿）：',
+    '  title, severity("error"|"warn"), probe({type 必须∈词表: ' + vocab + ', 及该类型必填参数}),',
+    '  detailOk, detailFail, fix, anchor({package,symbol,train} 或 null)',
+    '',
+    `现有目录检查 id（不得撞名）：${existingChecks.map((c) => c.id).join(', ') || '（空）'}`,
+    '',
+    `当前草稿（可全改，probe 参数必须填全才能被应用）：${JSON.stringify(draft, null, 2)}`,
+    '',
+    '只输出 JSON：',
+  ].join('\n');
+}
+
+/** LLM 回复富化：只采纳词表内字段；任何解析/校验失败 → 回退草稿并附原因。 */
+export function enrichDraft(draft, llmReply) {
+  if (!llmReply || typeof llmReply !== 'string') return { ...draft, llm: 'ignored: 无回复' };
+  let parsed;
+  try {
+    parsed = JSON.parse(llmReply.replace(/^```(?:json)?\s*|\s*```$/g, ''));
+  } catch {
+    return { ...draft, llm: 'ignored: LLM 输出非 JSON' };
+  }
+  if (typeof parsed !== 'object' || Array.isArray(parsed)) return { ...draft, llm: 'ignored: LLM 输出非对象' };
+  const out = { ...draft };
+  const reject = (why) => ({ ...draft, llm: `ignored: ${why}` });
+  // severity：词表内
+  if (parsed.severity !== undefined) {
+    if (!SEVERITIES.has(parsed.severity)) return reject(`severity 非法 (${parsed.severity})`);
+    out.severity = parsed.severity;
+  }
+  // probe：type 必须在词表，参数按词表必填收集（缺的保留原草稿值）
+  if (parsed.probe !== undefined) {
+    if (typeof parsed.probe !== 'object' || !PROBE_VOCABULARY[parsed.probe.type]) return reject(`probe.type 不在词表 (${parsed.probe?.type})`);
+    const merged = { ...draft.probe, ...parsed.probe };
+    out.probe = merged;
+  }
+  // 字符串字段
+  for (const key of ['title', 'detailOk', 'detailFail', 'fix']) {
+    if (typeof parsed[key] === 'string' && parsed[key].trim()) out[key] = parsed[key].trim();
+  }
+  // anchor：合法对象才采纳
+  if (parsed.anchor !== undefined) {
+    if (parsed.anchor === null) out.anchor = null;
+    else if (typeof parsed.anchor === 'object' && !Array.isArray(parsed.anchor)) {
+      out.anchor = { package: parsed.anchor.package ?? null, symbol: parsed.anchor.symbol ?? null, train: parsed.anchor.train ?? null };
+    } else return reject('anchor 非法');
+  }
+  return out;
+}
+
+/** 收集现有检查 id（供去重/防撞）。 */
+export function existingIdsOf(checks) {
+  return (checks ?? []).map((c) => c.id).filter(Boolean);
+}
+
+/**
+ * 观察入口：input = 诊断运行 JSON 对象 或 {path}（文件或含 JSON 的目录）。
+ * llmCmd 未给 → 跳过 LLM 步（确定性草稿 + prompt 照常输出）。
+ * 返回 { generatedAt, source, signals, clusters, proposals }。
+ */
+export async function runObserver({ input, path, existingChecks = [], llmCmd = null } = {}) {
+  const data = input ?? loadInput(path);
+  const clusters = clusterSignals(data);
+  const existing = existingIdsOf(existingChecks);
+  const proposals = [];
+  for (let i = 0; i < clusters.length; i++) {
+    const draft = draftProposal(clusters[i], [...existing, ...proposals.map((p) => p.id)], i);
+    let final = draft;
+    if (llmCmd) {
+      const reply = runLLM(llmCmd, renderLLMPrompt(clusters[i], draft, existingChecks));
+      final = enrichDraft(draft, reply);
+    } else {
+      final = { ...draft, prompt: renderLLMPrompt(clusters[i], draft, existingChecks) };
+    }
+    proposals.push(final);
+  }
+  return {
+    generatedAt: new Date().toISOString(),
+    source: typeof path === 'string' ? path : 'input-object',
+    signals: clusters.reduce((n, c) => n + c.count, 0),
+    clusters: clusters.map((c) => ({ section: c.section, signature: c.signature, count: c.count, examples: c.examples })),
+    proposals,
+  };
+}
+
+function loadInput(path) {
+  const p = resolve(path);
+  const st = statSync(p);
+  if (st.isDirectory()) {
+    const out = [];
+    for (const f of readdirSync(p)) {
+      if (!f.endsWith('.json')) continue;
+      try { out.push(JSON.parse(readFileSync(join(p, f), 'utf8'))); } catch { /* 非法 JSON 跳过 */ }
+    }
+    return { checks: out.flatMap(extractChecks) };
+  }
+  return JSON.parse(readFileSync(p, 'utf8'));
+}
+
+function runLLM(cmd, prompt) {
+  try {
+    const r = spawnSync(cmd, { input: prompt, encoding: 'utf8', shell: true, timeout: 30_000, maxBuffer: 4 * 1024 * 1024 });
+    if (r.status !== 0) return null;
+    return String(r.stdout ?? '').trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/** 校验并合并提案进目录对象（本地覆盖层/人工合并通用）。返回 { catalog, applied, rejected }。 */
+export function applyProposals(catalog, proposals) {
+  const base = catalog && Array.isArray(catalog.checks) ? catalog : { schemaVersion: 1, checks: [] };
+  const existing = existingIdsOf(base.checks);
+  const applied = [];
+  const rejected = [];
+  for (const p of proposals ?? []) {
+    const v = validateProposal(p, [...existing, ...applied.map((a) => a.id)]);
+    if (!v.ok) { rejected.push({ id: p?.id ?? '<无id>', errors: v.errors }); continue; }
+    applied.push(p);
+  }
+  return { catalog: { ...base, checks: [...base.checks, ...applied] }, applied, rejected };
+}
+
+/** 写本地覆盖层文件（--observe-apply 用）。 */
+export function writeLocalOverlay(filePath, catalog) {
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, JSON.stringify(catalog, null, 2) + '\n', 'utf8');
+}
+
+/** 读本地覆盖层（loadCatalog 合并用）；非法/缺失 → []。 */
+export function readLocalOverlay(filePath) {
+  try {
+    const d = JSON.parse(readFileSync(filePath, 'utf8'));
+    return Array.isArray(d.checks) ? d.checks : [];
+  } catch {
+    return [];
+  }
+}
+
+export { isAbsolute };

package/package.json

@@ -1,16 +1,17 @@
 {
   "name": "@moonquake2004/dsh-doctor",
-  "version": "0.2.6",
-  "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.",
+  "version": "0.3.0",
+  "description": "Offline diagnostic for DeepSeek Harness — 25 built-in + 5 catalog checks across env/profile/session (Layer A checks-as-data), self-update (Layer B), and a semi-automatic LLM observer (Layer C, --observe); Doctor panel in web UI settings.",
   "main": "lib/index.js",
   "files": [
-    "lib",
-    "client",
-    "dsh-doctor.mjs",
+    "README.md",
+    "README.zh.md",
     "checks.json",
+    "client",
     "cordis.patch.yml",
-    "README.md",
-    "README.zh.md"
+    "dsh-doctor.mjs",
+    "lib",
+    "observer.mjs"
   ],
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1"
@@ -47,4 +48,4 @@
   "bin": {
     "dsh-doctor": "./dsh-doctor.mjs"
   }
-}
+}