dsh-m 0.9.28 → 0.9.30

package/CHANGELOG.md

@@ -8,6 +8,21 @@ The full release history of dsh-m, maintained bilingually: **Chinese first, Engl
 
 ## 中文
 
+### 0.9.30 变更：修复 bin 符号链接静默 no-op（F2）+ 版本解析 realpath 第三源（F1）
+
+- **根因同源**：pnpm 生态里两类关键入口都是**符号链接**——`node_modules/.bin/dshm`（指向 lib/cli.js）与全局 shim `PNPM_HOME/dsh`（指向真实 bin.js）——而两处代码都在 realpath 之前做了路径身份判定。
+- **F2（自 v0.2.0 bin 入口引入以来潜在，本机 0.9.28 装机形态首次踩中并实证；🔴 bin 入口全命令静默 exit 0）**：cli.ts `invokedDirectly` 比较 `argv[1]`（链接路径）与 `import.meta.url`（node realpath 后的真实路径）永假，`dshm <任何命令>` 无输出直接退出。修复：比较前对 `argv[1]` 同样 realpath。新增 `tests/cli-bin-symlink.test.mjs`（经符号链接调用 --help 与 doctor --json 的复活验证，EPERM 环境照仓内先例 skip）。
+- **F1（0.9.29 装机验收实证）**：dsh-version.ts `readLauncherPackageVersion` 从 shim 位置直接向上三级找 package.json，落在 pnpm home 目录树上空走——宿主内纯 FS 版本解析在本机拓扑（`node PNPM_HOME/dsh web`）不可得，doctor 的 stale 判定降级、ping chip 被迫吃 spawn 回退。修复：判定 entry 形态后先 realpath 再上溯（本机实测解析得 0.2.0-rc.2）。新增 dsh-version.test.mjs shim 形态用例。
+- **验证**：专项 9/9（含两新用例）；全量 1079 pass / 0 fail / 0 skipped；typecheck 零错误。装机后预期：`dshm doctor`（bin 入口）可用；宿主 method 通路 runtimeVersion=0.2.0-rc.2、stale 判定复活（装机时农场 dsh 链接 0.1.7-rc.2 为现成 stale 形态，heal 后归零）。
+
+### 0.9.29 变更：profile 体检 Doctor——`dshm doctor` 上线（只读：农场测活 / 残留物清点 / 账实一致）
+
+- **动机**：dsh-m 至今没有诊断能力——know-how 014 的「每次 DSH 升级后重跑农场测活」是唯一现役周期必查项（曾 81 条悬空、230 行手工映射留档），know-how 023 实录「账实分裂」形态；本机实扫另发现 8 个空 scope 目录 + 12 个 `*.bak-*` 累积。学 dsh-market check.ts 的设计纪律（纯 FS 边界、三级严重度、unknown≠broken、误报记账、修复责任外移）落地 Day1 子集，选点裁决与对比详见 ADR-0010 与对比报告（2026-10-04）。
+- **新增**：`src/core/doctor.ts` 纯函数核心（无进程/无网络/无写入，任意时刻可安全调用）+ `/dshm` 新 method `doctor` + CLI `dshm doctor [--json]`（error 级发现 exit 1；HELP 同步）。三项检查：**农场测活**（`@deepseek-ai/*` 符号链祖先链遍历；悬空=error；dsh 伞包指向旧运行时 store=提示级——lockstep 店内非伞包版本不与 runtimeVersion 比较，防 cordis 等误报）、**残留物清点**（空 scope / 无 manifest 目录 / pnpm `*_tmp_*` / `*.bak-*`，全部零告警清单，「可见而非清理」）、**账实一致**（pin/实装/lock 三处核对，不一致=warning；lockfile 仅认 9.0 importers 形状，其余 unknown 不猜）。
+- **边界纪律（ADR-0010）**：runtimeVersion 仅用 `readLauncherPackageVersion` 纯 FS 通路（CLI 进程下为 null → stale 判定整体降级 unknown，绝不 spawn）；密钥红线只禁含密钥**配置文件**内容（包元数据 version 字段可读）；布局判定 workspace 声明优先（本机「hoisted 声明 + 仅 lock.yaml 的残留 .pnpm」并存形态实证）；双市场并存（dsh-m+dshmarket 同装）信息级呈现；doctor 永不修复，建议以文字给出。
+- **验收结算（2026-10-04 装机实测）**：farmChecked=236（精确命中评审实测值）/ 悬空 0 / 8 空 scope + 12 bak 入清单 / 账实 13:0 / 双市场信息级 / errors=0 → exit=0 / `--json` 可解析。宿主 method 信封正确但 runtimeVersion=null——**发版日新发现**：本机宿主经 pnpm 全局 shim 启动（`node ~/.local/share/pnpm/dsh web`），`readLauncherPackageVersion` 从 shim 三级上溯落空，stale 判定双通路降级（底层事实人工核对成立：农场 dsh 链接 0.1.7-rc.2 vs 运行时 0.2.0-rc.2；版本第三源列下一批）。另录既有 bug：`.bin/dshm` 符号链接静默 no-op（后经考古为 v0.2.0 起潜在、本机 0.9.28 装机形态首次踩中，见 0.9.30 条目——`invokedDirectly` 比较 symlink 路径与 realpath 永假，bin 入口全命令静默 exit 0；修复列 0.9.30 候选，期间用 `node …/dsh-m/lib/cli.js` 直达）。
+- **验证**：新增 `tests/doctor.test.mjs`（36 例：布局冲突并存/祖先链反空转/两级 targetVersion/降级路径/零告警清单/023 形态/link 协议/lock peer 后缀/CLI 子进程）+ `tests/doctor-api.test.mjs`（2 例：method 信封真跑 + 空 profile）；全量 1076 pass / 0 fail / 0 skipped。
+
 ### 0.9.28 变更：页大小档位去上游化——32/64/96 取代 24/48/96，默认 32
 
 - **动机**：24/48/96 是复刻 dsh-market 筛选面板（0.7.2）时带过来的上游血统数字。甄别后发现 96 早已被 dsh-m 内化为核心参数（`WITH_LATEST_MAX` 探测上限、精选区默认页、fast-open 快照判定基准），真正的上游痕迹只有 24——「砍 24、保 96」即去上游化与兼容性的交集。
@@ -283,6 +298,21 @@ The full release history of dsh-m, maintained bilingually: **Chinese first, Engl
 
 ## English
 
+### Fixed in 0.9.30 — bin symlink silent no-op (F2) + realpath third source for version resolution (F1)
+
+- **Shared root cause**: two critical pnpm-ecosystem entry points are **symlinks** — `node_modules/.bin/dshm` (→ lib/cli.js) and the global shim `PNPM_HOME/dsh` (→ the real bin.js) — while both code sites made path-identity decisions before realpath.
+- **F2 (latent since the bin entry shipped in v0.2.0; first hit and proven on this machine's 0.9.28 install shape; 🔴 every command via the bin entry silently exits 0)**: cli.ts `invokedDirectly` compared `argv[1]` (link path) against `import.meta.url` (node's realpath) — never equal, so `dshm <any command>` printed nothing and exited. Fix: realpath `argv[1]` before comparing. New `tests/cli-bin-symlink.test.mjs` (revival via symlinked --help and doctor --json; EPERM environments skip per repo precedent).
+- **F1 (proven at 0.9.29 install acceptance)**: dsh-version.ts `readLauncherPackageVersion` walked up three levels from the shim location, landing in the pnpm home tree — pure-FS version resolution was unreachable under this host topology (`node PNPM_HOME/dsh web`), degrading doctor's stale judgment and forcing the ping chip onto the spawn fallback. Fix: realpath the entry after the shape check, then walk (locally verified resolving 0.2.0-rc.2). New shim-shape case in dsh-version.test.mjs.
+- **Verification**: targeted 9/9 (two new cases); full suite 1079 pass / 0 fail / 0 skipped; typecheck clean. Post-install expectations: `dshm doctor` works via the bin entry; host method path reports runtimeVersion=0.2.0-rc.2 with stale judgment live (the farm's dsh link at 0.1.7-rc.2 is a ready-made stale form until healed).
+
+### Added in 0.9.29 — profile Doctor: `dshm doctor` (read-only: farm liveness / residue inventory / manifest-reality consistency)
+
+- **Motivation**: dsh-m had no diagnostics at all — know-how 014's "re-run farm liveness after every DSH upgrade" was the only standing periodic check (81 dangling links and a 230-line manual heal log), know-how 023 documented the manifest-reality split, and a live scan found 8 empty scope dirs + 12 `*.bak-*` files. Day1 subset adopting dsh-market check.ts's design disciplines (pure-FS boundary, three-tier severity, unknown≠broken, false-positive bookkeeping, repair responsibility shifted outward). See ADR-0010 and the comparison report (2026-10-04).
+- **Added**: `src/core/doctor.ts` pure-function core (no processes, no network, no writes — safe to call any time) + new `/dshm` method `doctor` + CLI `dshm doctor [--json]` (exit 1 on error-tier findings; HELP synced). Three checks: **farm liveness** (ancestor-chain walk over `@deepseek-ai/*` symlinks; dangling = error; dsh umbrella pointing at an old runtime store = info-tier — non-umbrella versions are never compared against the runtime version, avoiding cordis-style false positives), **residue inventory** (empty scope dirs / no-manifest dirs / pnpm `*_tmp_*` / `*.bak-*`, all zero-alarm lists, "visible rather than cleaned"), **manifest-reality consistency** (pin vs installed vs lockfile; mismatch = warning; only lockfileVersion 9.0 importers shape is parsed, anything else stays unknown).
+- **Boundary disciplines (ADR-0010)**: runtimeVersion comes only from the pure-FS `readLauncherPackageVersion` (null under the CLI → stale judgment degrades to unknown, never spawns); the secrets red line covers credential-bearing config files only (package metadata version fields are readable); layout detection is workspace-declaration-first (proven on the local "hoisted declaration + vestigial lock.yaml-only .pnpm" shape); dual-market coexistence (dsh-m + dshmarket installed together) surfaces as an informational fact; doctor never repairs — advice is text only.
+- **Acceptance anchors (to verify after install)**: first local run expects farmChecked ≈236 (0 means the walk short-circuited), 0 dangling, 8 empty scopes + 12 bak files listed, dual market flagged.
+- **Verification**: new `tests/doctor.test.mjs` (36 cases) + `tests/doctor-api.test.mjs` (2 cases); full suite 1076 pass / 0 fail / 0 skipped.
+
 ### Changed in 0.9.28 — page-size set de-upstreamed: 32/64/96 replaces 24/48/96, default 32
 
 - **Motivation**: 24/48/96 came bundled with the dsh-market filter-panel replica (0.7.2). On inspection, 96 has long been internalized as a dsh-m core parameter (`WITH_LATEST_MAX` probe cap, primary-zone default page, fast-open snapshot baseline); the only real upstream trace is 24 — "drop 24, keep 96" is exactly the intersection of de-upstreaming and compatibility.

package/docs/DESIGN.md

@@ -175,6 +175,7 @@ npm 安装 / GitHub 安装 / 升级 / 自升级 / 卸载是**同一个事务模
 - 工具前缀 `dshm_`，共 7 个：`dshm_search` / `dshm_list` / `dshm_install` / `dshm_uninstall` / `dshm_outdated` / `dshm_upgrade` / `dshm_restart`。Agent tools 运行于 Host 进程，与 Web GUI **共用 `host` namespace 缓存与 active config**；`dshm_search` 走服务端过滤（metadata-only，`withLatest=false`、limit ≤80），返回不含本地路径的短 summary。
 - 0.5.0：`dshm_search`/`dshm_install` 消费**合并市场**（§2.5）；category 参数接受精选 5 分类 + 任意社区分类 slug；summary 增加社区清单状态（条数/来源/是否 stale）；CLI 默认合并社区清单，`DSHM_COMMUNITY_CATALOG=0` 退出，缓存用 `cli/awesome/` 子目录。
 - CLI bin `dshm`：同名同义命令集（`dshm list|search|install|uninstall|outdated|upgrade|restart`），固定 `cli` namespace。`registry`/`search`/`outdated` 在清单不可用时打印配置/实际生效地址并 **exit 1**；`list` 仍列出已装并标记不可用；本地终端可显示完整路径。
+- 体检（Doctor，0.9.29）：`/dshm` method `doctor` + CLI `dshm doctor [--json]`（**不新增第 9 个 agent 工具**——工具描述是宿主 agent 常驻上下文，行为面代价大于收益）。纯 FS 只读（无进程/无网络/无写入，清单不可用照常工作），三项检查（农场测活/残留物清点/账实一致）+ 三级严重度 + unknown≠broken + 双市场信息级；runtimeVersion 仅 `readLauncherPackageVersion` 纯 FS 通路（CLI 下降级 unknown，禁 spawn 回退）。决策全记载见 [ADR-0010](./adr/0010-doctor-read-only-diagnostics.md)。
 - 本地 API：`POST /dshm` 单路由 method 分发；除 `ping` 外全部要求 JSON Content-Type + `trustedRestartRequest` host 等价同源防护；typed 错误映射 400/403/404/405/413/415/422/500；`registry-config-apply` 校验失败 422；清单不可用的 `registry`/`market` 仍返回 200 + 结构化状态。
 - 实现顺序：**GUI 先行，CLI 收尾**（核心逻辑同一层，CLI 是薄封装）。
 

package/lib/cli.js

@@ -7,12 +7,15 @@
  */
 import { installFromRegistry, listInstalledWithMeta, listMarket, uninstallPlugin, upgradePlugin, InstallGuardError, } from './core/market.js';
 import { togglePlugin as coreTogglePlugin } from './core/toggle.js';
+import { runDoctor } from './core/doctor.js';
+import { readLauncherPackageVersion } from './core/dsh-version.js';
+import { webProfileDir } from './core/env.js';
 import { loadRegistry } from './core/registry.js';
 import { COMMUNITY_CATEGORY_LABELS } from './core/community.js';
 import { scheduleRestart } from './core/restart.js';
 import { upgradeEffectLine } from './core/activation.js';
 import { pathToFileURL } from 'node:url';
-import { resolve } from 'node:path';
+import { realpathSync } from 'node:fs';
 /** 分类中文标签（0.7.0 Task 6；0.9.16 策展五桶）：精选策展桶本地表 + 社区已知标签单一事实源；未知 slug 原样。 */
 const CLI_CATEGORY_LABELS = {
     essentials: '装机必备',
@@ -130,6 +133,7 @@ const HELP = `dshm — DSH Marketplace（DSH 插件市场：精选策展 + 社
   dshm list                          列出 web profile 已装插件（含市场标注/可升级）
   dshm outdated                      检查已装插件的最新版本
   dshm registry                      查看收录清单来源与条目
+  dshm doctor [--json]               profile 体检（只读：农场测活 / 残留物清点 / 账实一致；error 级发现 exit 1）
 
 变更命令（必须 --yes）：
   dshm install --id <收录id> [--version 1.2.3] [--force]   （--force：确认兼容风险后跳过预检拦截）
@@ -401,6 +405,62 @@ async function runCliDispatch(argv, deps, io) {
             out(`✅ 已请求重启（via ${res.via}）。服务恢复后刷新页面即可。`);
             return 0;
         }
+        case 'doctor': {
+            // 体检（ADR-0010）：纯 FS 只读、不依赖 registry（清单不可用照常工作）。
+            // runtimeVersion 仅用 readLauncherPackageVersion 纯 FS 通路（CLI 进程下通常为 null
+            // → stale 判定降级 unknown，绝不 spawn）；errors>0 → exit 1。
+            const report = await runDoctor(webProfileDir(), readLauncherPackageVersion());
+            if (flags.json === true) {
+                out(JSON.stringify(report, null, 2));
+                return report.summary.errors > 0 ? 1 : 0;
+            }
+            const s = report.summary;
+            out(`profile 体检 · ${report.profileDir}`);
+            out(`布局 ${report.layout} · 运行时 ${report.runtimeVersion ?? '未解析（stale 判定降级 unknown，绝不 spawn）'} · 扫描于 ${report.scannedAt}`);
+            out(`农场 ${s.farmChecked}（悬空 ${s.farmDangling} · 指旧 ${s.farmStale}${report.runtimeVersion === null ? '（降级：未判定）' : ''}）` +
+                ` · 残留 ${s.residueCount} · 账实 ${s.accountChecked}（不一致 ${s.accountMismatched}） · errors ${s.errors} · warnings ${s.warnings}`);
+            const errs = report.findings.filter((f) => f.severity === 'error');
+            const warns = report.findings.filter((f) => f.severity === 'warning');
+            if (errs.length) {
+                out('\n❌ 错误（将阻止对应链接/包正常工作）：');
+                for (const f of errs) {
+                    out(`  • ${f.title}`);
+                    out(`    ${f.detail}`);
+                    out(`    → ${f.hint}`);
+                }
+            }
+            if (warns.length) {
+                out('\n⚠️  警告（确认异常但不阻止启动）：');
+                for (const f of warns) {
+                    out(`  • ${f.title}`);
+                    out(`    ${f.detail}`);
+                    out(`    → ${f.hint}`);
+                }
+            }
+            const stale = report.farm.filter((x) => x.state === 'stale-target').slice(0, 3);
+            if (stale.length) {
+                out('\n指向旧运行时 store（信息级，至多列 3 条，清单零告警）：');
+                for (const x of stale)
+                    out(`  • ${x.name} → ${x.targetVersion}`);
+            }
+            if (s.residueCount > 0) {
+                const kindCounts = new Map();
+                for (const x of report.residue)
+                    kindCounts.set(x.kind, (kindCounts.get(x.kind) ?? 0) + 1);
+                out(`\n残留物：${s.residueCount} 项只列不警（${[...kindCounts].map(([k, n]) => `${k} ${n}`).join(' · ')}；可见而非清理，全量见 --json）：`);
+                for (const x of report.residue.slice(0, 3))
+                    out(`  • [${x.kind}] ${x.path}${x.note ? `（${x.note}）` : ''}`);
+                if (s.residueCount > 3)
+                    out('  …');
+            }
+            for (const u of s.unknowns)
+                out(`ℹ️  ${u}`);
+            if (report.dualMarket)
+                out(`ℹ️  双市场并存：${report.dualMarket.join(' + ')} 同时在装（写侧互不知晓，排查时留意）。`);
+            if (errs.length === 0)
+                out('\n未发现 error 级问题。');
+            return errs.length > 0 ? 1 : 0;
+        }
         default: {
             err(`未知命令：${cmd}\n`);
             out(HELP);
@@ -414,7 +474,11 @@ const invokedDirectly = (() => {
     if (!entry)
         return false;
     try {
-        return import.meta.url === pathToFileURL(resolve(entry)).href;
+        // F2（0.9.28-0.9.29 实证）：pnpm 的 node_modules/.bin/dshm 是指向 lib/cli.js 的
+        // 符号链接——node 对入口做 realpath，import.meta.url 是真实路径而 argv[1] 仍是
+        // 链接路径，直接比较永假 → bin 入口全命令静默 exit 0。比较前同样 realpath。
+        const realEntry = realpathSync(entry);
+        return import.meta.url === pathToFileURL(realEntry).href;
     }
     catch {
         return false;

package/lib/core/doctor.js

@@ -0,0 +1,454 @@
+/**
+ * 体检（Doctor，ADR-0010）：对单个 profile 的只读健康检查。
+ *
+ * 纪律（照 dsh-market check.ts 学习所得，详见对比报告 §4）：
+ * - 纯文件系统分析：无进程派生、无网络请求、无文件写入/删除——任意时刻可安全调用。
+ *   版本解析只用 readLauncherPackageVersion 纯 FS 通路；resolveDshVersion 的
+ *   spawn `dsh --version` 回退为 doctor 禁区（CLI 下解析为 null 即降级，绝不 spawn）。
+ * - 三级严重度：error（断链或必然阻断启动）/ warning（确认异常但不阻止启动）/
+ *   结构化清单（只列不警，零告警渲染）；unknown≠broken——看不见的对象显式标
+ *   unknown 并沉默，不推断为损坏。
+ * - 每条 error/warning 必须含三要素：发生了什么（title）/ 为什么（detail）/ 现在怎么办（hint）。
+ * - 密钥红线：绝不读取或转储 cordis.patch.yml 等含密钥配置文件内容；报告只含
+ *   包名、路径、版本号等结构化事实（链接目标目录 package.json 的 version 字段
+ *   属包元数据，不在禁令内）。
+ * - 修复责任外移：doctor 永不写不删，修复建议以文字形态给出（ADR-0010 决定 5）。
+ */
+import { readdir, readFile, lstat, stat, readlink } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { parseDocument } from 'yaml';
+import { satisfies } from 'semver';
+import { dshHome } from './env.js';
+import { readProfileDeps, resolvePluginDir, readPkgJson } from './installed.js';
+// ---------- 布局探测（Task 1） ----------
+/**
+ * 判据与优先级（评审 R1.1 定案）：**workspace 声明优先**——pnpm-workspace.yaml 声明
+ * `nodeLinker: hoisted` 即判 hoisted，残留的 `.pnpm` 目录（如仅含 lock.yaml 的本机
+ * 实况形态）不推翻声明；isolated = 无 hoisted 声明且 `node_modules/.pnpm` 存在且
+ * **含包目录**（仅 lock.yaml 的残留形态不算）；其余 unknown。
+ * 任何读取/解析失败都走 unknown 分支，不抛异常（unknown≠broken）。
+ */
+export async function detectLayout(profileDir) {
+    const root = resolve(profileDir);
+    let wsText = null;
+    try {
+        wsText = await readFile(join(root, 'pnpm-workspace.yaml'), 'utf8');
+    }
+    catch {
+        wsText = null;
+    }
+    if (wsText !== null) {
+        try {
+            const doc = parseDocument(wsText);
+            const nodeLinker = doc.getIn(['nodeLinker'], true);
+            if (nodeLinker && typeof nodeLinker.toString === 'function' && nodeLinker.toString() === 'hoisted') {
+                return 'hoisted';
+            }
+        }
+        catch {
+            /* 坏 YAML 不构成任何判据，落 .pnpm 存在性判定 */
+        }
+    }
+    let entries;
+    try {
+        entries = await readdir(join(root, 'node_modules', '.pnpm'));
+    }
+    catch {
+        return 'unknown';
+    }
+    const hasPackageDir = entries.some((e) => !e.startsWith('.') && e !== 'lock.yaml');
+    return hasPackageDir ? 'isolated' : 'unknown';
+}
+// ---------- 农场测活（Task 2，know-how 014 的工具化） ----------
+/** pnpm 虚拟店目录名里的版本段：`@deepseek-ai+<pkg>@<ver>_<hash>`（targetVersion 第一级提取）。 */
+const STORE_VERSION_RE = /@deepseek-ai\+[^/\\]+@([^_/\\]+)_[0-9a-f]+(?:[\\/]|$)/;
+/** dsh 伞包：其版本即 DSH 运行时版本，是唯一可与 runtimeVersion 比较的农场成员。 */
+const DSH_UMBRELLA = '@deepseek-ai/dsh';
+/** 祖先链向上遍历的最大层数（防御病态深路径）。 */
+const MAX_ANCESTOR_LEVELS = 16;
+async function existsDir(path) {
+    try {
+        await stat(path);
+        return true; // stat 成功解析即存在（文件或目录皆算存活目标）
+    }
+    catch {
+        return false;
+    }
+}
+/** 从 targetDir 的 package.json 读 version（targetVersion 第二级提取；失败返回 null 不抛）。 */
+async function readTargetPkgVersion(targetDir) {
+    try {
+        const raw = JSON.parse(await readFile(join(targetDir, 'package.json'), 'utf8'));
+        return typeof raw?.version === 'string' && raw.version ? raw.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 农场测活：遍历 profile 可见范围内 `@deepseek-ai/*` 符号链接，判定悬空 / 指向旧运行时 store / 健康。
+ *
+ * - 遍历规则（评审 R1.2 定案）：从 profileDir 逐级向上至 DSH_HOME 边界，扫描每级
+ *   `node_modules/@deepseek-ai`——本机实况农场在 profile **父目录**的共享 hoisted 店，
+ *   不得以「工作区根」为限（否则 0 命中空转，farmChecked=0 是验收失败信号）。
+ * - stale 判定只对 dsh 伞包生效：lockstep 店内各核心包（cordis 4.x、dsh-tools 0.1.x…）
+ *   与运行时版本**不在同一命名空间**，逐包比较会把 cordis@4.0.1 误标 stale——误报纪律
+ *   （健康档误报代价 > 漏报）禁止；其余包 targetVersion 仅作信息呈现。stale-target 只进
+ *   farm 清单不产生 finding（提示级，ADR-0010 决定 4）。
+ * - runtimeVersion 为 null（CLI 通路纯 FS 解析不可得，绝不 spawn）→ 全部不判 stale、
+ *   unknowns 记一条聚合降级说明（unknown≠broken，评审 R1.3）。
+ * - targetVersion 两级提取（评审 R1.4）：目录名版本段优先 → 目标 package.json version；
+ *   两级皆失败置 null 并聚合计入 unknowns。
+ */
+export async function analyzeFarm(profileDir, layout, runtimeVersion) {
+    const farm = [];
+    const findings = [];
+    const unknowns = [];
+    let unresolvedVersionCount = 0;
+    // 祖先链层级收集：profileDir 起向上，含 DSH_HOME 边界（boundary 是祖先时）；越界或到根即止。
+    // 边界不可达的说明（执行评审 E1.6）：两生产通路的 profileDir 恒在 dshHome() 之下
+    // （CLI=env.ts webProfileDir()、method=host ctx.profile.dir，均无用户可控的目录入参），
+    // boundary 不可达仅限误用场景；此时上行至根由 MAX_ANCESTOR_LEVELS=16 有界兜底，
+    // 不会无限扫描，也不存在「止于起点」会误伤的合法非 DSH_HOME 用例（当前不存在该通路）。
+    const boundary = resolve(dshHome());
+    const levels = [];
+    let cur = resolve(profileDir);
+    for (let i = 0; i < MAX_ANCESTOR_LEVELS; i++) {
+        levels.push(cur);
+        if (cur === boundary)
+            break;
+        const parent = dirname(cur);
+        if (parent === cur)
+            break;
+        cur = parent;
+    }
+    for (const level of levels) {
+        const scopeDir = join(level, 'node_modules', '@deepseek-ai');
+        let names;
+        try {
+            names = await readdir(scopeDir);
+        }
+        catch {
+            continue; // 该级无 node_modules/@deepseek-ai，静默跳过（不是每一级都有）
+        }
+        for (const name of names) {
+            if (name.startsWith('.'))
+                continue;
+            const linkPath = join(scopeDir, name);
+            let isSymlink = false;
+            try {
+                isSymlink = (await lstat(linkPath)).isSymbolicLink();
+            }
+            catch {
+                continue;
+            }
+            if (!isSymlink)
+                continue; // 农场只关心符号链接；真实目录是物化安装，不在测活范围
+            const target = await readlinkSafe(linkPath);
+            if (target === null) {
+                // readlink 失败：链接本身不可读——按 unknown 计，不猜
+                unresolvedVersionCount += 1;
+                farm.push({ name, target: linkPath, state: 'healthy', targetVersion: null });
+                continue;
+            }
+            const resolvedTarget = resolve(dirname(linkPath), target);
+            const alive = await existsDir(resolvedTarget);
+            // targetVersion 两级提取
+            let targetVersion = null;
+            const m = STORE_VERSION_RE.exec(resolvedTarget);
+            if (m)
+                targetVersion = m[1];
+            if (targetVersion === null)
+                targetVersion = await readTargetPkgVersion(resolvedTarget);
+            if (targetVersion === null)
+                unresolvedVersionCount += 1;
+            let state = 'healthy';
+            if (!alive) {
+                state = 'dangling';
+            }
+            else if (runtimeVersion !== null &&
+                targetVersion !== null &&
+                `@deepseek-ai/${name}` === DSH_UMBRELLA &&
+                targetVersion !== runtimeVersion) {
+                state = 'stale-target';
+            }
+            farm.push({ name, target: resolvedTarget, state, targetVersion });
+            if (state === 'dangling') {
+                findings.push({
+                    check: 'farm-liveness',
+                    severity: 'error',
+                    title: `@deepseek-ai/${name} 符号链接悬空`,
+                    detail: `指向 ${resolvedTarget}，目标不存在（DSH 升级后旧 store 目录被拆的 know-how 014 形态；本链接已不能引导任何加载）`,
+                    hint: '重装该包（dshm upgrade / install），或按 know-how 014 的 heal 流程重指向新 store；体检不代执行',
+                });
+            }
+        }
+    }
+    if (runtimeVersion === null) {
+        unknowns.push('运行时版本未解析（纯 FS 通路不可得，绝不 spawn）——stale 判定整体降级为 unknown');
+    }
+    if (unresolvedVersionCount > 0) {
+        unknowns.push(`${unresolvedVersionCount} 条链接目标版本无法解析（目录名无版本段且目标 package.json 不可读），详见 farm 清单`);
+    }
+    return { farm, findings, unknowns };
+}
+/** readlink 包装：失败返回 null（不抛）。 */
+async function readlinkSafe(linkPath) {
+    try {
+        return await readlink(linkPath);
+    }
+    catch {
+        return null;
+    }
+}
+// ---------- 残留物清点（Task 3，#663「可见而非清理」纪律） ----------
+/** pnpm 暂存目录形态：`<name>_tmp_<pid>_<n>`（中断的更新留下的）。 */
+const TMP_DIR_RE = /^(.+)_tmp_\d+_\w+$/;
+/** profile 根备份文件形态：`*.bak-*`（本机实况 12 个累积）。 */
+const BAK_FILE_RE = /\.bak-/;
+/**
+ * 残留物清点：四类全部**结构化清单、零告警**（不产生任何 DoctorFinding——残留是
+ * 历史形态不是故障，告警只会训练用户无视清单；且删除正是常被进程句柄拒绝的操作，
+ * doctor 只清点不删除，ADR-0010 决定 5）。
+ *
+ * - `no-manifest` / `empty-scope`：node_modules 顶层（非点前缀）。空 scope 独立分类
+ *   不并入 no-manifest（本机实况 8 个；dsh-market 扫描器曾把它们误报 incomplete-package）。
+ * - `tmp-dir`：node_modules 顶层 + isolated 布局另扫 `.pnpm` 顶层**一层**（照 check.ts
+ *   有界策略不递归全店）。注意 .pnpm 内正常 store 目录（`foo@1.0.0`）本来就没有根级
+ *   package.json——no-manifest 检查绝不扫进 .pnpm，否则全店误报。
+ * - hoisted 布局不做 .pnpm 扫描，unknowns 记中性事实（本机 hoisted 下存在仅含
+ *   lock.yaml 的残留 .pnpm 目录属正常并存形态，不告警——评审 R1.9）。
+ * - `bak-file`：profile 根一层 `*.bak-*`（mtime 入 note）。
+ */
+export async function listResidue(profileDir, layout) {
+    const residue = [];
+    const unknowns = [];
+    const root = resolve(profileDir);
+    const nm = join(root, 'node_modules');
+    let top = [];
+    try {
+        top = await readdir(nm);
+    }
+    catch {
+        top = []; // 无 node_modules → 无残留可清点（不算 unknown）
+    }
+    for (const name of top) {
+        if (name.startsWith('.'))
+            continue;
+        if (TMP_DIR_RE.test(name)) {
+            residue.push({ kind: 'tmp-dir', path: join(nm, name), note: null });
+            continue;
+        }
+        const entryPath = join(nm, name);
+        let isDir = false;
+        try {
+            isDir = (await stat(entryPath)).isDirectory();
+        }
+        catch {
+            continue;
+        }
+        if (!isDir)
+            continue;
+        if (name.startsWith('@')) {
+            let inner;
+            try {
+                inner = await readdir(entryPath);
+            }
+            catch {
+                continue;
+            }
+            if (inner.length === 0)
+                residue.push({ kind: 'empty-scope', path: entryPath, note: null });
+            continue;
+        }
+        try {
+            await stat(join(entryPath, 'package.json'));
+        }
+        catch {
+            residue.push({ kind: 'no-manifest', path: entryPath, note: null });
+        }
+    }
+    if (layout === 'isolated') {
+        let pnpmEntries = [];
+        try {
+            pnpmEntries = await readdir(join(nm, '.pnpm'));
+        }
+        catch {
+            pnpmEntries = [];
+        }
+        for (const name of pnpmEntries) {
+            if (TMP_DIR_RE.test(name)) {
+                residue.push({ kind: 'tmp-dir', path: join(nm, '.pnpm', name), note: null });
+            }
+        }
+    }
+    else if (layout === 'hoisted') {
+        unknowns.push('hoisted 布局不扫 .pnpm 店（仅含 lock.yaml 的残留 .pnpm 目录属正常并存形态，不告警）');
+    }
+    else {
+        unknowns.push('布局未知，未扫 .pnpm 店');
+    }
+    let rootEntries = [];
+    try {
+        rootEntries = await readdir(root);
+    }
+    catch {
+        rootEntries = [];
+    }
+    for (const name of rootEntries) {
+        if (!BAK_FILE_RE.test(name))
+            continue;
+        const filePath = join(root, name);
+        try {
+            const s = await stat(filePath);
+            if (!s.isFile())
+                continue;
+            residue.push({ kind: 'bak-file', path: filePath, note: `mtime: ${s.mtime.toISOString()}` });
+        }
+        catch {
+            continue;
+        }
+    }
+    return { residue, unknowns };
+}
+/**
+ * 自建最小 lockfile 解析（评审 R1.8：仓内无可复用的 importers 解析导出——
+ * npm-integrity.ts 仅 integrity/overrides，profile-transaction 的 lock 解析为模块私有）。
+ * 仅认 lockfileVersion 9.0 实测形状 `importers.'.'.dependencies.{specifier,version}`；
+ * 其他版本 supported:false（全 null，unknown≠broken 不猜）。
+ */
+async function readLockImporters(lockPath) {
+    let text;
+    try {
+        text = await readFile(lockPath, 'utf8');
+    }
+    catch {
+        return { map: new Map(), supported: false }; // 无 lockfile → 全 null（unknown≠broken）
+    }
+    try {
+        const doc = parseDocument(text);
+        const lv = doc.getIn(['lockfileVersion'], true);
+        const lvStr = lv === undefined || lv === null ? '' : String(lv);
+        if (!lvStr.startsWith('9.'))
+            return { map: new Map(), supported: false };
+        const js = doc.toJS();
+        const depsObj = js?.importers?.['.']?.dependencies ?? {};
+        const map = new Map();
+        for (const [name, value] of Object.entries(depsObj)) {
+            // link: 依赖在 lock 里是 { specifier, link: true } 无 version → 自然落空（按契约置 null）
+            if (value && typeof value === 'object' && typeof value.version === 'string' && value.version) {
+                // pnpm lock v9 的 version 可带 peer 后缀：`0.9.28(@deepseek-ai/schemastery@3.18.4)`
+                // ——剥去括号后缀再入账（实机预演 2026-10-04 曾因此把 4 条三处一致的依赖误报账实分裂）
+                map.set(name, value.version.replace(/\([^)]*\)$/, ''));
+            }
+        }
+        return { map, supported: true };
+    }
+    catch {
+        return { map: new Map(), supported: false };
+    }
+}
+/** semver.satisfies 安全包装：任一侧非法（dist-tag / workspace 协议等）→ null（不可判定，不猜）。 */
+function satisfiesSafe(version, range) {
+    try {
+        return satisfies(version, range) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 账实一致：对 profile 每个依赖核对三处记账——package.json pin / node_modules 实装 /
+ * pnpm-lock 解析。不一致 = warning（确认异常但不阻止启动，ADR-0010 决定 4）。
+ * - pin 含 range 按 semver 范围判定，不做字串相等；
+ * - lockfile 解析不出（无记录 / 非 9.x / 无 lockfile）置 null 且**不计为不一致**（unknown≠broken）；
+ * - `link:` 依赖：pin 记原文、installed 取 link 目标 package.json version、lockfile 置 null，
+ *   一致性 = 目标可读（不比较 pin 文本与版本号）。
+ */
+export async function checkAccount(profileDir) {
+    const root = resolve(profileDir);
+    const deps = await readProfileDeps(root);
+    const lock = await readLockImporters(join(root, 'pnpm-lock.yaml'));
+    const account = [];
+    const findings = [];
+    for (const name of Object.keys(deps).sort()) {
+        const spec = deps[name];
+        const isLink = spec.startsWith('link:');
+        const dir = resolvePluginDir(root, name, spec);
+        let installed = null;
+        if (dir) {
+            const pkg = await readPkgJson(dir);
+            const v = pkg?.version;
+            if (typeof v === 'string' && v)
+                installed = v;
+        }
+        const lockfile = !isLink ? lock.map.get(name) ?? null : null;
+        let consistent = true;
+        if (isLink) {
+            consistent = installed !== null;
+        }
+        else if (installed === null) {
+            consistent = false; // pin 在而实装缺失（物化不完整）
+        }
+        else {
+            const pinOk = satisfiesSafe(installed, spec);
+            if (pinOk === false)
+                consistent = false;
+            if (lockfile !== null && lockfile !== installed)
+                consistent = false;
+        }
+        account.push({ name, pin: spec, installed, lockfile, consistent });
+        if (!consistent) {
+            findings.push({
+                check: 'account-reality',
+                severity: 'warning',
+                title: `${name} 账实分裂`,
+                detail: `pin=${spec} · 实装=${installed ?? '缺失'} · lock=${lockfile ?? '—'}（know-how 023 §6.2 形态：pnpm 非零退出可拦住 pin 写入，三处记账从此各说各话）`,
+                hint: '核验最近一次升级/安装事务的结果，或按 know-how 023 §6.2 处置；体检不代执行',
+            });
+        }
+    }
+    return { account, findings };
+}
+// ---------- 聚合（Task 5） ----------
+/**
+ * 体检聚合：三项检查 + 双市场信息级事实 → DoctorReport。
+ * runtimeVersion 由调用方注入（method 通路宿主内纯 FS 可得；CLI 通路 null 即降级），
+ * 原样透传进报告——两通路差异如实可见。布局 unknown 时显式标注扫描受限（不冒充健康）。
+ */
+export async function runDoctor(profileDir, runtimeVersion) {
+    const root = resolve(profileDir);
+    const layout = await detectLayout(root);
+    const farmR = await analyzeFarm(root, layout, runtimeVersion);
+    const residueR = await listResidue(root, layout);
+    const accountR = await checkAccount(root);
+    const unknowns = [...farmR.unknowns, ...residueR.unknowns];
+    if (layout === 'unknown')
+        unknowns.unshift('布局未知——扫描范围受限（unknown≠broken，不冒充健康）');
+    const deps = await readProfileDeps(root);
+    const dualMarket = Object.hasOwn(deps, 'dsh-m') && Object.hasOwn(deps, 'dshmarket') ? ['dsh-m', 'dshmarket'] : null;
+    const findings = [...farmR.findings, ...accountR.findings];
+    return {
+        schema: 'dsh-m/doctor/v1',
+        profileDir: root,
+        layout,
+        runtimeVersion,
+        scannedAt: new Date().toISOString(),
+        summary: {
+            errors: findings.filter((f) => f.severity === 'error').length,
+            warnings: findings.filter((f) => f.severity === 'warning').length,
+            farmChecked: farmR.farm.length,
+            farmDangling: farmR.farm.filter((x) => x.state === 'dangling').length,
+            farmStale: farmR.farm.filter((x) => x.state === 'stale-target').length,
+            residueCount: residueR.residue.length,
+            accountChecked: accountR.account.length,
+            accountMismatched: accountR.account.filter((a) => !a.consistent).length,
+            unknowns,
+        },
+        farm: farmR.farm,
+        residue: residueR.residue,
+        account: accountR.account,
+        findings,
+        dualMarket,
+    };
+}

package/lib/core/dsh-version.js

@@ -11,7 +11,7 @@
  * .pnpm 目录名多版本残留无判据——均不走。
  */
 import { dirname, join } from 'node:path';
-import { readFileSync } from 'node:fs';
+import { readFileSync, realpathSync } from 'node:fs';
 import { spawn } from 'node:child_process';
 import { dshArgv } from './dsh-cli.js';
 /** 从 `dsh --version` 输出提取 semver：容忍 v 前缀与前后散文，取首个命中。 */
@@ -26,10 +26,14 @@ export function parseDshVersionOutput(text) {
 export function readLauncherPackageVersion(input = {}) {
     try {
         const argv = dshArgv(input);
-        const entry = argv.args.length > 0 ? argv.args[argv.args.length - 1] : undefined;
+        let entry = argv.args.length > 0 ? argv.args[argv.args.length - 1] : undefined;
         // 与 dshArgv 同一判定：entry 必须长得像 launcher bin，否则是 CLI/PATH 模式
         if (!entry || !/[\\/](?:bin\.(?:js|ts)|dsh)$/.test(entry))
             return null;
+        // F1（0.9.29 装机验收实证）：pnpm 全局 shim（如 PNPM_HOME/dsh）是指向真实 bin.js
+        // 的符号链接——realpath 后再向上找 package.json，否则会在 pnpm home 目录树上
+        // 空走三级，宿主内纯 FS 解析落空（ping chip 被迫吃 spawn 回退）。
+        entry = realpathSync(entry);
         let dir = dirname(entry);
         for (let up = 0; up < 3; up++) {
             try {

package/lib/core/host-api.js

@@ -8,7 +8,8 @@
  * 顶层必须是非 null/非数组对象且有 method → typed method/业务错误映射 → 其他 500。
  */
 import { BOOT_ID, publicInstallStatus } from './dsh-cli.js';
-import { resolveDshVersion } from './dsh-version.js';
+import { resolveDshVersion, readLauncherPackageVersion } from './dsh-version.js';
+import { runDoctor } from './doctor.js';
 import { listInstalledWithMeta, listMarket, installFromRegistry, selfUpgrade, uninstallPlugin, upgradePlugin, InstallGuardError, } from './market.js';
 import { runProfileTransaction, TransactionError } from './profile-transaction.js';
 import { readInstalledPluginReadme } from './installed.js';
@@ -557,6 +558,14 @@ export function createApiDispatcher(ctx) {
                     payload = { registryState: snap.loaded, check };
                     break;
                 }
+                case 'doctor': {
+                    // 体检（ADR-0010）：纯 FS 只读，不依赖 registry（清单不可用时照常工作）。
+                    // runtimeVersion 只用 readLauncherPackageVersion 纯 FS 通路——resolveDshVersion 的
+                    // spawn 回退是 doctor 禁区（无进程派生约束；null 即降级，测试覆盖分工见计划 Task 6）。
+                    const report = await runDoctor(profile.dir, readLauncherPackageVersion());
+                    payload = { report };
+                    break;
+                }
                 default:
                     throw new ApiProtocolError(404, `未知 method: ${method}`);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-m",
-  "version": "0.9.28",
+  "version": "0.9.30",
   "description": "可自定义收录清单的 DSH 插件市场：收录、安装、卸载、升级一站完成，附 agent 工具与 dshm CLI。",
   "license": "MIT",
   "type": "module",