@moonquake2004/dsh-doctor 0.2.7 → 0.3.1

package/README.md

@@ -69,6 +69,8 @@ With `--envelope` (doctor-contract mode): `0` = all pass · `1` = any WARN · `2
 
 ## Related community tools
 
+> **dsh-doctor/v1 vocabulary r5 compatible** — drafted by [@ciceroyang](https://github.com/ciceroyang) (ciceroyang/dsh-doctor), reviewed by [@sjh9714](https://github.com/sjh9714) (dsh-win32) and [@moonquake2004](https://github.com/moonquake2004) ([#1719](https://github.com/deepseek-ai/deepseek-harness/discussions/1719)). Our `node`/`pnpm` checks emit the vocabulary names with r5 semantics (pass/warn/fail/skip; `summary.skip` always present).
+
 - [zoahdev/dsh-plugin-doctor](https://github.com/zoahdev/dsh-plugin-doctor) — pre-publish plugin bundle health checks (manifest/patch/entry/files/build/pack+fresh-profile install) plus a `profile-shadow` tripwire for host-shadowing (author/CI side). Complementary to this tool's user-side profile/session/env diagnostics; its `profile-shadow` and our P5 flag the same host-shadowing precondition from two sides.
 - [boyin111-1/dsh-doctor](https://github.com/boyin111-1/dsh-doctor) — sibling offline diagnostic, cross-verified against the same broken fixtures.
 
@@ -126,6 +128,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

@@ -64,6 +64,8 @@ node dsh-doctor.mjs --no-catalog         # 不拉远程目录（只用内置副
 
 ## 相关社区工具
 
+> **dsh-doctor/v1 词汇表 r5 兼容** —— 起草 [@ciceroyang](https://github.com/ciceroyang)（ciceroyang/dsh-doctor），审阅 [@sjh9714](https://github.com/sjh9714)（dsh-win32）与 [@moonquake2004](https://github.com/moonquake2004)（[#1719](https://github.com/deepseek-ai/deepseek-harness/discussions/1719)）。我们的 `node`/`pnpm` 检查按 r5 语义输出词汇名（pass/warn/fail/skip；`summary.skip` 常驻）。
+
 - [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 交叉验证。
 
@@ -119,6 +121,16 @@ The `dsh-doctor/v1` envelope (`--json --envelope`) is the machine-readable form
 
 目录检查的结果在 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

@@ -51,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';
 
@@ -108,12 +108,19 @@ function resolveProfile(name) {
 }
 
 /* ================= env ================= */
+/** v1 词汇表 r5（#1719）node 语义：pass = 满足 ^22.19.0 || >=24.0.0（root package.json engines），其余 warn——无民间 fail 阈值。 */
+function nodeInSupportedRange(v) {
+  const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec(String(v));
+  if (!m) return false;
+  const major = Number(m[1]); const minor = Number(m[2]);
+  return (major === 22 && minor >= 19) || major >= 24;
+}
 function checkEnv() {
   if (!wants('env')) return;
   const find = (cmd) => { for (const w of process.platform === 'win32' ? ['where'] : ['which']) { const r = spawnSync(w, [cmd]); if (r.status === 0) { const p = String(r.stdout).split(/\r?\n/)[0].trim(); if (p) return p; } } return null; };
   for (const cmd of ['node', 'pnpm', 'zstd']) {
     const p = find(cmd);
-    report('env', `E1-${cmd}`, !!p, p ? `${cmd}: ${p}` : `${cmd} 不在 PATH（${cmd === 'node' ? '创建会话会失败 #1270' : cmd === 'pnpm' ? 'dsh plugin 不可用' : '会话日志解压不可用'}）`, p ? undefined : `安装 ${cmd} 或加入 PATH`);
+    report('env', `E1-${cmd}`, !!p, p ? `${cmd}: ${p}` : `${cmd} 不在 PATH（${cmd === 'node' ? '创建会话会失败 #1270' : cmd === 'pnpm' ? 'dsh plugin 不可用（corepack 可恢复：corepack enable pnpm）' : '会话日志解压不可用'}）`, p ? undefined : (cmd === 'pnpm' ? 'corepack enable pnpm 或安装 pnpm 后加入 PATH' : `安装 ${cmd} 或加入 PATH`));
   }
   const envFile = join(HOME, '.env');
   if (existsSync(envFile)) {
@@ -121,7 +128,13 @@ function checkEnv() {
     report('env', 'E2-env', !isDir, isDir ? `${envFile} 是目录，dsh 启动会报 failed to load .env: EISDIR（#71）` : `${envFile} 正常`, isDir ? '删除或改名该目录' : undefined);
   }
   const nv = spawnSync('node', ['-e', 'console.log(process.version)']);
-  if (nv.status === 0) report('env', 'E3-node', true, `node ${String(nv.stdout).trim()}`, undefined);
+  if (nv.status === 0) {
+    const version = String(nv.stdout).trim();
+    const supported = nodeInSupportedRange(version);
+    report('env', 'E3-node', supported,
+      supported ? `node ${version}（满足 ^22.19.0 || >=24.0.0，root package.json engines）` : `node ${version} 不在支持范围（^22.19.0 || >=24.0.0）——会话日志读取等能力受限`,
+      supported ? undefined : '升级 node 到 ^22.19.0 或 >=24.0.0（root package.json engines，见 #2259）');
+  }
 
   // E4：node-pty 原生模块完整性（#1219：pty.node 缺失 → dsh web 启动失败）
   const ptyDirs = [];
@@ -217,7 +230,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; }
@@ -739,42 +762,61 @@ function scanAllSessions() {
 const REMOTE_CATALOG_URL = 'https://raw.githubusercontent.com/moonquake2004/dsh-doctor/main/plugin/checks.json';
 const CATALOG_TTL_MS = 6 * 60 * 60 * 1000; // 6h：新检查最长 6h 内自动生效
 const catalogSeverity = new Map(); // catalog 检查 id → severity（'error' | 'warn'）
+// v1 词汇表 r5 对齐（#1719）：E1-pnpm 缺失=warn（corepack 可恢复）、E3-node 越界=warn（EBADENGINE 语义）——均不翻退出码
+catalogSeverity.set('E1-pnpm', 'warn');
+catalogSeverity.set('E3-node', 'warn');
 
 function bundledCatalog() {
   const p = new URL('./checks.json', import.meta.url);
   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) {
@@ -1004,10 +1046,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)}`); }
@@ -1043,7 +1118,7 @@ async function run() {
   if (jsonOut && process.argv.includes('--envelope')) {
     // v1 契约信封（dsh doctor 规格，zoahdev/doctor 对齐）：status 小写 + 退出码 0/1/2
     const st = (r) => (!r.ok ? (catalogSeverity.get(r.id) === 'warn' ? 'warn' : 'fail') : 'pass');
-    const summary = { pass: 0, warn: 0, fail: 0 };
+    const summary = { pass: 0, warn: 0, fail: 0, skip: 0 }; // skip 常驻（v1 词汇表 r5：#1719），当前无平台作用域检查所以恒为 0
     const checks = results.map((r) => { summary[st(r)]++; return { name: r.id, status: st(r), detail: r.detail }; });
     const exitCode = summary.fail > 0 ? 2 : summary.warn > 0 ? 1 : 0;
     console.log(JSON.stringify({
@@ -1083,4 +1158,4 @@ async function run() {
 // 直接执行（CLI：根目录薄封装、plugin 本体、npm bin 均可）；被 import（测试/宿主）时不自动运行
 if (process.argv[1] && /^dsh-doctor(\.mjs)?$/.test(basename(process.argv[1]))) run();
 
-export { loadCatalog, bundledCatalog, validCatalog, expandPath, globCount, checkCatalog };
+export { loadCatalog, bundledCatalog, validCatalog, expandPath, globCount, checkCatalog, nodeInSupportedRange };

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.7",
-  "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.1",
+  "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"
   }
-}
+}