@moonquake2004/dsh-doctor 0.2.6 → 0.2.7

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.

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 }`——**未经你要求绝不改动你的安装**。

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 → 会话永久"运行中"）
@@ -455,6 +457,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 +477,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 ================= */
@@ -1019,6 +1048,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moonquake2004/dsh-doctor",
-  "version": "0.2.6",
+  "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.",
   "main": "lib/index.js",
   "files": [