dsh-config-manager 0.1.69 → 0.1.71

package/lib/utils/patch-yaml.d.ts

@@ -0,0 +1,25 @@
+/** `!!js` 表达式的内存形态（与 DSH / cordis 的 `{__jsExpr}` 逐字同形）。 */
+export interface PatchJsExpr {
+    __jsExpr: string;
+}
+/** 与 cordis `isJsExpr` 同判据（`value instanceof Object && '__jsExpr' in value`）。 */
+export declare function isPatchJsExpr(value: unknown): value is PatchJsExpr;
+/** patch 文件的 YAML schema（= DSH 的 `entryListSchema` 同款）。 */
+export declare const PATCH_YAML_SCHEMA: import("js-yaml").Schema;
+/**
+ * 载入 patch 文档（任意 YAML 值）。
+ *
+ * 解析失败**抛出**（不吞）：调用方要么把它转成可见告警，要么拒绝覆盖写入 —— 两条路都好过
+ * 「当作空文档、把用户的整层配置抹掉」。
+ */
+export declare function loadPatchDocument(text: string): unknown;
+/** 写回 patch 文档：`{__jsExpr}` 还原成 `!!js`，其余按 DSH 的 schema 打印。 */
+export declare function dumpPatchDocument(value: unknown): string;
+/**
+ * 解析报错的**安全摘要**：只取首行。
+ *
+ * 为什么必须截断：js-yaml 的 `Error.message` 会在首行之后附带**出错处的源码片段**，而
+ * `cordis.patch.yml` 里可能内联字面量密钥（`!!js` 表达式旁会出现明文 token / API Key）。
+ * 这段摘要会流进启动日志、导出告警与浏览器回执 —— 片段一律不得带出去。
+ */
+export declare function describePatchYamlError(err: unknown): string;

package/lib/utils/patch-yaml.js

@@ -0,0 +1,62 @@
+/**
+ * `cordis.patch.yml` 的 YAML **方言**（issue #75）—— 宿主侧单一事实源。
+ *
+ * 为什么不能直接用 `yaml.load` / `yaml.dump`：这份文件不是普通 YAML。DSH 自己读它用的是
+ * 「JSON_SCHEMA + 一个自定义标量标签 `!!js`」的方言（`@deepseek-ai/dsh-app-boot`：
+ *   `const entryListSchema = yaml.JSON_SCHEMA.extend(JsExpr)`，其中
+ *   `JsExpr = new yaml.Type('tag:yaml.org,2002:js', { kind:'scalar', construct: (data) => ({ __jsExpr: data }), predicate: isJsExpr, represent: (data) => data['__jsExpr'] })`）
+ * —— `!!js` 承载的是**行内 JS 表达式**（真机例：`disabled: !!js (function(){ … })()`）。
+ *
+ * 缺省 schema 遇到 `!!js` 会直接抛 `unknown scalar tag !<tag:yaml.org,2002:js>`（js-yaml 5 实测）。
+ * 调用方若把它 catch 成「这一层没有 patch 行」，用户手写的整层配置就会在导出/同步/预览里凭空消失；
+ * 导入写回时更会把整份文件重写成「只剩本次导入的行」—— 这正是 issue #75 报告的数据丢失。
+ *
+ * 两个形状与 DSH 逐字对齐（**改这里等于改对外契约**，见 `docs/spec/bundle-format-v1.md`）：
+ *  - 载入：`!!js <源码>` → `{ __jsExpr: <源码> }`
+ *  - 写回：`{ __jsExpr: <源码> }` → `!!js <源码>`
+ * 判据与 cordis 的 `isJsExpr`（`value instanceof Object && '__jsExpr' in value`）一致，于是 bundle 里
+ * 存的 `raw` 既是普通 JSON（可安全过 `JSON.stringify` / 分区 JSON），又能还原成 DSH 认的表达式。
+ *
+ * 用 `JSON_SCHEMA`（而不是 js-yaml 的缺省 schema）是刻意的：**读法必须与 DSH 一致**，否则同一个文件
+ * 我们和 DSH 会看到不同的值（例：`~` 在 YAML 1.2 Core 下是 null，在 JSON_SCHEMA 下是字符串 `"~"`，
+ * 而 DSH 用的是后者 —— 导出的 raw 必须与 DSH 读到的相同）。
+ */
+import { JSON_SCHEMA, NOT_RESOLVED, defineScalarTag, dump, load } from 'js-yaml';
+/** 与 cordis `isJsExpr` 同判据（`value instanceof Object && '__jsExpr' in value`）。 */
+export function isPatchJsExpr(value) {
+    return typeof value === 'object' && value !== null && '__jsExpr' in value;
+}
+/** `tag:yaml.org,2002:js`（`!!js`）：只认显式标签，构造 `{__jsExpr}`，写回还原源码文本。 */
+const jsExprTag = defineScalarTag('tag:yaml.org,2002:js', {
+    resolve: (source, isExplicit) => (isExplicit ? { __jsExpr: source } : NOT_RESOLVED),
+    identify: isPatchJsExpr,
+    represent: (data) => String(data.__jsExpr),
+});
+/** patch 文件的 YAML schema（= DSH 的 `entryListSchema` 同款）。 */
+export const PATCH_YAML_SCHEMA = JSON_SCHEMA.withTags(jsExprTag);
+/**
+ * 载入 patch 文档（任意 YAML 值）。
+ *
+ * 解析失败**抛出**（不吞）：调用方要么把它转成可见告警，要么拒绝覆盖写入 —— 两条路都好过
+ * 「当作空文档、把用户的整层配置抹掉」。
+ */
+export function loadPatchDocument(text) {
+    return load(text, { schema: PATCH_YAML_SCHEMA });
+}
+/** 写回 patch 文档：`{__jsExpr}` 还原成 `!!js`，其余按 DSH 的 schema 打印。 */
+export function dumpPatchDocument(value) {
+    return dump(value, { schema: PATCH_YAML_SCHEMA });
+}
+/**
+ * 解析报错的**安全摘要**：只取首行。
+ *
+ * 为什么必须截断：js-yaml 的 `Error.message` 会在首行之后附带**出错处的源码片段**，而
+ * `cordis.patch.yml` 里可能内联字面量密钥（`!!js` 表达式旁会出现明文 token / API Key）。
+ * 这段摘要会流进启动日志、导出告警与浏览器回执 —— 片段一律不得带出去。
+ */
+export function describePatchYamlError(err) {
+    const raw = err instanceof Error ? err.message : String(err);
+    const firstLine = raw.split('\n', 1)[0] ?? '';
+    return firstLine.trim().slice(0, 200);
+}
+//# sourceMappingURL=patch-yaml.js.map

package/lib/utils/paths.d.ts

@@ -8,7 +8,11 @@ export declare function isAbsolutePath(p: string): boolean;
 /** ZIP 条目名安全检查（Zip Slip / 绝对路径 / 盘符 / NUL，规范 §19.1-2）。
  * 规则与 node:path 解耦：纯分段校验，跨平台无歧义。 */
 export declare function isPathSafe(entryName: string): boolean;
-/** 候选目录是否位于父目录之内（含等于父目录） */
+/** 候选目录是否位于父目录之内（含等于父目录）。
+ *
+ * 纯字符串语义（不碰文件系统）：两侧必须是**同一种拼写**，调用方若混用
+ * realpath 结果与原路径（Windows 8.3 短名、macOS `/var`→`/private/var`）会误判为越界 ——
+ * `path.relative` 不会折叠短名，务必先各自 realpath 再调用。 */
 export declare function isSameOrChild(p: string, parent: string): boolean;
 /**
  * 归一化并折叠 `.` / `..` 路径段（Reviewer B P0 修复）。
@@ -24,6 +28,11 @@ export declare function isReservedInternalRel(relPath: string): boolean;
 /**
  * 前缀批量映射（规范 §12）：把对象内所有字符串值中匹配 oldPrefix 的路径
  * 替换为 newPrefix（路径感知：必须落在段边界）。返回新对象（不改原对象）。
+ *
+ * **Windows 形状路径先折叠大小写再比较**（core-F4）：Windows 文件系统大小写不敏感，
+ * 用户手输 / 两台机器用户名大小写不同都会让 oldPrefix 与真实值只差大小写 —— 只做逐字比较
+ * 会让整条映射**静默失效**（目标机保留源机绝对路径，workspace.path 与会话 cwd 对不上）。
+ * POSIX 路径仍逐字比较（/home/Alice 与 /home/alice 是不同目录，不得误匹配）。
  */
 export declare function applyPrefixMappings(value: unknown, mappings: PathMapping[]): unknown;
 /** 对对象内所有字符串叶节点做变换（迭代式，保留非字符串原样；二进制 Uint8Array 视为叶子） */

package/lib/utils/paths.js

@@ -47,7 +47,11 @@ export function isPathSafe(entryName) {
         return false; // 目录穿越
     return true;
 }
-/** 候选目录是否位于父目录之内（含等于父目录） */
+/** 候选目录是否位于父目录之内（含等于父目录）。
+ *
+ * 纯字符串语义（不碰文件系统）：两侧必须是**同一种拼写**，调用方若混用
+ * realpath 结果与原路径（Windows 8.3 短名、macOS `/var`→`/private/var`）会误判为越界 ——
+ * `path.relative` 不会折叠短名，务必先各自 realpath 再调用。 */
 export function isSameOrChild(p, parent) {
     const rel = path.relative(parent, p);
     return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
@@ -109,9 +113,21 @@ export function isReservedInternalRel(relPath) {
     }
     return false;
 }
+/**
+ * Windows 语义路径（盘符 "C:/"、"C:\\"；UNC 以两个斜杠或两个反斜杠开头）。
+ *
+ * 判据是**路径形状**而不是 process.platform：映射的来源可能是另一台机器导出的 Windows 路径
+ * （跨平台导入时在 Linux/macOS 上处理），形状决定它在自己的文件系统上大小写不敏感。
+ */
+const WINDOWS_STYLE_PATH_RE = /^[a-zA-Z]:[\\/]|^[\\/]{2}/;
 /**
  * 前缀批量映射（规范 §12）：把对象内所有字符串值中匹配 oldPrefix 的路径
  * 替换为 newPrefix（路径感知：必须落在段边界）。返回新对象（不改原对象）。
+ *
+ * **Windows 形状路径先折叠大小写再比较**（core-F4）：Windows 文件系统大小写不敏感，
+ * 用户手输 / 两台机器用户名大小写不同都会让 oldPrefix 与真实值只差大小写 —— 只做逐字比较
+ * 会让整条映射**静默失效**（目标机保留源机绝对路径，workspace.path 与会话 cwd 对不上）。
+ * POSIX 路径仍逐字比较（/home/Alice 与 /home/alice 是不同目录，不得误匹配）。
  */
 export function applyPrefixMappings(value, mappings) {
     if (mappings.length === 0)
@@ -123,11 +139,16 @@ export function applyPrefixMappings(value, mappings) {
             if (oldNorm === '')
                 continue;
             const candidate = normalizePath(out);
-            if (candidate === oldNorm) {
+            // 只有两侧都是同一种大小写语义时才折叠：Windows 形状折叠，POSIX 保持逐字
+            const fold = WINDOWS_STYLE_PATH_RE.test(oldNorm) || WINDOWS_STYLE_PATH_RE.test(candidate);
+            const cmp = (v) => (fold ? v.toLowerCase() : v);
+            if (cmp(candidate) === cmp(oldNorm)) {
                 out = normalizePath(m.newPrefix);
                 continue;
             }
-            if (candidate.startsWith(oldNorm + '/')) {
+            // 段边界：先按**原串**切出等长头部再比较（折叠可能改变长度，避免切错位置）
+            const head = candidate.slice(0, oldNorm.length);
+            if (candidate.length > oldNorm.length && candidate[oldNorm.length] === '/' && cmp(head) === cmp(oldNorm)) {
                 const rest = candidate.slice(oldNorm.length); // 含前导 /
                 out = normalizePath(normalizePath(m.newPrefix) + rest);
             }

package/lib/utils/recursive-walk.js

@@ -15,19 +15,12 @@
  */
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { isSameOrChild } from './paths.js';
 /** 深度上限：防御病态目录树 / realpath 去重失效时的栈爆炸 */
 const MAX_DEPTH = 64;
 function normalizeSlashes(p) {
     return p.split(path.sep).join('/');
 }
-/** current 是否等于 base 或位于其下（win32 折叠大小写） */
-function isSameOrChild(current, base) {
-    const c = path.resolve(current);
-    const b = path.resolve(base);
-    const cl = process.platform === 'win32' ? c.toLowerCase() : c;
-    const bl = process.platform === 'win32' ? b.toLowerCase() : b;
-    return cl === bl || cl.startsWith(bl.endsWith(path.sep) ? bl : bl + path.sep);
-}
 async function realpathSafe(p) {
     try {
         return await fs.realpath(p);
@@ -44,6 +37,11 @@ async function realpathSafe(p) {
 export async function listRecursiveFollowingLinks(baseDir, homeDir) {
     const base = path.resolve(baseDir);
     const home = path.resolve(homeDir);
+    // 边界判定专用基准：realpath 展开 Windows 8.3 短名（`C:\Users\IUUUUU~1\…` → `C:\Users\iuuuuuuuu\…`）
+    // 与 macOS 的 `/var` → `/private/var`，而 path.resolve 保留原拼写。两侧必须同为 realpath 形态，
+    // 否则「home 内的目标」会被误判成越界 —— issue #37 的链接跟随在 windows/macos 全红即此因。
+    // realpath 失败（路径不存在）时退回原拼写，保持「目录不存在视为空」的既有语义。
+    const homeReal = (await realpathSafe(home)) ?? home;
     const paths = [];
     const skippedLinks = [];
     const unreadableDirs = [];
@@ -53,14 +51,15 @@ export async function listRecursiveFollowingLinks(baseDir, homeDir) {
     const rel = (abs) => normalizeSlashes(path.relative(home, abs));
     /** @returns 是否真的进入了该目录（false = 被边界/去重/IO 挡下） */
     const walk = async (dir, depth, viaLink) => {
-        if (!isSameOrChild(dir, home))
+        const real = await realpathSafe(dir);
+        if (!isSameOrChild(real ?? path.resolve(dir), homeReal))
             return false;
         if (depth > MAX_DEPTH) {
-            if (viaLink !== null)
-                skippedLinks.push({ path: viaLink, reason: 'too-deep' });
+            // 深度上限必须**可见**（cli-F2）：此前只对链接记 too-deep —— **普通目录**超深时整块内容
+            // 被裁掉却既不在 skippedLinks 也不在 unreadableDirs 里，备份照样报成功（issue #37 同类症状）。
+            skippedLinks.push({ path: viaLink ?? rel(dir), reason: 'too-deep' });
             return false;
         }
-        const real = await realpathSafe(dir);
         // 去重只针对**链接**：链接目标已经进过（自引用 / 两条链接指向同一处）→ 跳过。
         // 普通目录永远遍历（否则「真实目录 + 指向它的链接」会有一边被静默吞掉）。
         if (viaLink !== null && real !== null && visited.has(real)) {
@@ -108,7 +107,7 @@ export async function listRecursiveFollowingLinks(baseDir, homeDir) {
                 // 只对目录链接做这个检查会漏掉「skills/link.md → ~/外部文件」：
                 // 内容会被读进备份（T2-P3 实测就是这种文件链接，属真实越界读取）。
                 const target = await realpathSafe(abs);
-                if (target === null || !isSameOrChild(target, home)) {
+                if (target === null || !isSameOrChild(target, homeReal)) {
                     skippedLinks.push({ path: entryRel, reason: 'outside-home' });
                     continue;
                 }

package/lib/utils/session-format.d.ts

@@ -10,13 +10,46 @@ export declare const MAX_PROBED_SESSION_LOGS = 200;
 export declare function parseSessionFormatVersion(source: string): number | undefined;
 /** 从 `<node_modules>/@deepseek-ai/dsh-session/lib/index.js` 读格式常量；读不到 → undefined。 */
 export declare function readSessionFormatVersionAt(nodeModulesDir: string): number | undefined;
+/** pnpm 段名 → 版本（`…@<version>[_<peerHash>]`）；不是 dsh-session 段 → undefined。 */
+export declare function pnpmSessionEntryVersion(entryName: string): string | undefined;
+/** 从 startDir 起向上找最近的 `.pnpm` 存储目录；找不到 → undefined。 */
+export declare function findPnpmStore(startDir: string): string | undefined;
+/**
+ * pnpm 隔离布局下 dsh-session 的候选 node_modules 根（issue #74）。
+ *
+ * 为什么需要：pnpm 全局安装 DSH 时，installAnchor 落在
+ *   `<…>/node_modules/.pnpm/@deepseek-ai+dsh@<ver>_<hash>/node_modules/@deepseek-ai/dsh/package.json`
+ * 而它的同级 @deepseek-ai 下**没有** dsh-session（`dsh` 的 dependencies 里也没有它，只有
+ * dsh-session-projection / -reference），`dsh/node_modules` 同样不存在 —— 「同级目录拼路径」
+ * 在隔离布局下必然落空。真实的 dsh-session 在**同一 store 的另一个段**里：
+ *   `<store>/@deepseek-ai+dsh-session@<ver>_<hash>/node_modules/@deepseek-ai/dsh-session/lib/index.js`
+ *
+ * 多个版本共存时取「与本机 dsh 同版本」的那个（DSH 内部包按同一版本号一起发布）；
+ * 同版本多份（peer 哈希不同）等价，全试。**版本读不出来且不止一个候选 → 返回空（不猜）**：
+ * 体检宁可整体跳过，也不能拿另一份 dsh-session 的常量谎报本机格式。
+ */
+export declare function pnpmSessionFormatRoots(nodeModulesDir: string, dshVersion?: string): string[];
+/**
+ * 一个「同树」根展开成全部候选（顺序即真伪顺序）：
+ *   ① hoisted 同级 `<nm>/@deepseek-ai/dsh-session`
+ *   ② dsh 自己的嵌套 `<nm>/@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-session`
+ *   ③ pnpm 隔离 store（见 `pnpmSessionFormatRoots`）
+ */
+export declare function sessionFormatRoots(nodeModulesDir: string, dshVersion?: string): string[];
+/** 在一棵（含 pnpm 存储的）依赖树里读格式常量；读不到 → undefined（不猜）。 */
+export declare function readSessionFormatVersionInTree(nodeModulesDir: string, dshVersion?: string): number | undefined;
+/** 读一个 package.json 的 version（只读；不可读 / 不是非空字符串 → undefined）。 */
+export declare function readPackageVersionAt(packageJsonPath: string): string | undefined;
 /**
  * 按「@deepseek-ai/dsh/package.json 的路径」候选逐个找同树的会话格式常量。
  *
  * 顺序即真伪顺序（与 `resolveDshVersion` 同源）：installAnchor（拉起本宿主的那份运行时，
- * 桌面端在 app.asar 内）优先，其次该档案自己的依赖树。每处再试 hoisted 与 pnpm 嵌套两种布局。
+ * 桌面端在 app.asar 内）优先，其次该档案自己的依赖树。每处再试三种布局（见 `sessionFormatRoots`）。
+ *
+ * `tried` 可选：收集**所有尝试过的路径**（解析失败时由调用方写进日志——真机排查看的是这个，
+ * 而不是一句「解析不到」）。
  */
-export declare function resolveSessionFormatVersion(dshPackageJsonCandidates: readonly string[]): number | undefined;
+export declare function resolveSessionFormatVersion(dshPackageJsonCandidates: readonly string[], tried?: string[]): number | undefined;
 /** 体检输入：备份里 sessions 分区的条目（`data` 是归档内的原始字节）。 */
 export interface SessionFormatProbeFile {
     relativePath: string;

package/lib/utils/session-format.js

@@ -11,7 +11,7 @@
  * 不显示，用户看到的就是「对话消失」。高版本能读低版本（DSH 自带 V0→V4 迁移链），
  * 反向不可读，所以「桌面端（新）导出 → 旧 CLI 档案导入」必须在导入前说清楚。
  */
-import { existsSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { isSessionLogName, readLogHeaderFromBytes } from './session-log.js';
 /** DSH 会话包（相对 node_modules）。 */
@@ -47,17 +47,143 @@ export function readSessionFormatVersionAt(nodeModulesDir) {
         return undefined;
     }
 }
+/* ------------------------------- 布局展开：hoisted / dsh 嵌套 / pnpm 隔离（issue #74） */
+/** pnpm 隔离布局的存储目录名（`<node_modules>/.pnpm`）。 */
+const PNPM_STORE_DIR = '.pnpm';
+/**
+ * pnpm 段名前缀（`@deepseek-ai+dsh-session@<version>[_<peerHash>]`）。
+ * 末尾那个 `@` 是必须的：`@deepseek-ai+dsh-session-projection@…` 也以同名开头，但它**不是**我们要的包。
+ */
+const PNPM_SESSION_ENTRY_PREFIX = '@deepseek-ai+dsh-session@';
+/** 向上找存储目录的最大层数（隔离安装下锚点本身就在 store 段内，最多要爬 4 层）。 */
+const PNPM_UPWARD_LEVELS = 8;
+/** pnpm 段名 → 版本（`…@<version>[_<peerHash>]`）；不是 dsh-session 段 → undefined。 */
+export function pnpmSessionEntryVersion(entryName) {
+    if (!entryName.startsWith(PNPM_SESSION_ENTRY_PREFIX))
+        return undefined;
+    const rest = entryName.slice(PNPM_SESSION_ENTRY_PREFIX.length);
+    if (rest === '')
+        return undefined;
+    // semver 标识符里不含 '_'，pnpm 用它拼接 peer 后缀（如 @a@1.0.0_react@18.2.0）
+    const peerAt = rest.indexOf('_');
+    return peerAt === -1 ? rest : rest.slice(0, peerAt);
+}
+/** 从 startDir 起向上找最近的 `.pnpm` 存储目录；找不到 → undefined。 */
+export function findPnpmStore(startDir) {
+    let dir = startDir;
+    for (let level = 0; level < PNPM_UPWARD_LEVELS; level++) {
+        const candidate = join(dir, PNPM_STORE_DIR);
+        try {
+            if (statSync(candidate).isDirectory())
+                return candidate;
+        }
+        catch {
+            /* 这一层没有 .pnpm（或读不到）→ 继续向上 */
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return undefined;
+}
+/**
+ * pnpm 隔离布局下 dsh-session 的候选 node_modules 根（issue #74）。
+ *
+ * 为什么需要：pnpm 全局安装 DSH 时，installAnchor 落在
+ *   `<…>/node_modules/.pnpm/@deepseek-ai+dsh@<ver>_<hash>/node_modules/@deepseek-ai/dsh/package.json`
+ * 而它的同级 @deepseek-ai 下**没有** dsh-session（`dsh` 的 dependencies 里也没有它，只有
+ * dsh-session-projection / -reference），`dsh/node_modules` 同样不存在 —— 「同级目录拼路径」
+ * 在隔离布局下必然落空。真实的 dsh-session 在**同一 store 的另一个段**里：
+ *   `<store>/@deepseek-ai+dsh-session@<ver>_<hash>/node_modules/@deepseek-ai/dsh-session/lib/index.js`
+ *
+ * 多个版本共存时取「与本机 dsh 同版本」的那个（DSH 内部包按同一版本号一起发布）；
+ * 同版本多份（peer 哈希不同）等价，全试。**版本读不出来且不止一个候选 → 返回空（不猜）**：
+ * 体检宁可整体跳过，也不能拿另一份 dsh-session 的常量谎报本机格式。
+ */
+export function pnpmSessionFormatRoots(nodeModulesDir, dshVersion) {
+    const store = findPnpmStore(nodeModulesDir);
+    if (store === undefined)
+        return [];
+    let entries;
+    try {
+        entries = readdirSync(store).filter((name) => name.startsWith(PNPM_SESSION_ENTRY_PREFIX));
+    }
+    catch {
+        return [];
+    }
+    if (entries.length === 0)
+        return [];
+    let chosen;
+    if (typeof dshVersion === 'string' && dshVersion !== '') {
+        const exact = entries.filter((name) => pnpmSessionEntryVersion(name) === dshVersion);
+        if (exact.length > 0)
+            chosen = exact;
+        else if (entries.length === 1)
+            chosen = entries;
+        else
+            return [];
+    }
+    else if (entries.length === 1) {
+        chosen = entries;
+    }
+    else {
+        return [];
+    }
+    return chosen.sort().map((name) => join(store, name, 'node_modules'));
+}
+/**
+ * 一个「同树」根展开成全部候选（顺序即真伪顺序）：
+ *   ① hoisted 同级 `<nm>/@deepseek-ai/dsh-session`
+ *   ② dsh 自己的嵌套 `<nm>/@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-session`
+ *   ③ pnpm 隔离 store（见 `pnpmSessionFormatRoots`）
+ */
+export function sessionFormatRoots(nodeModulesDir, dshVersion) {
+    return [
+        nodeModulesDir,
+        join(nodeModulesDir, '@deepseek-ai', 'dsh', 'node_modules'),
+        ...pnpmSessionFormatRoots(nodeModulesDir, dshVersion),
+    ];
+}
+/** 在一棵（含 pnpm 存储的）依赖树里读格式常量；读不到 → undefined（不猜）。 */
+export function readSessionFormatVersionInTree(nodeModulesDir, dshVersion) {
+    for (const root of sessionFormatRoots(nodeModulesDir, dshVersion)) {
+        const version = readSessionFormatVersionAt(root);
+        if (version !== undefined)
+            return version;
+    }
+    return undefined;
+}
+/** 读一个 package.json 的 version（只读；不可读 / 不是非空字符串 → undefined）。 */
+export function readPackageVersionAt(packageJsonPath) {
+    try {
+        const parsed = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+        if (parsed === null || typeof parsed !== 'object')
+            return undefined;
+        const version = parsed.version;
+        return typeof version === 'string' && version !== '' ? version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/* ------------------------------------------------------------- 解析入口 */
 /**
  * 按「@deepseek-ai/dsh/package.json 的路径」候选逐个找同树的会话格式常量。
  *
  * 顺序即真伪顺序（与 `resolveDshVersion` 同源）：installAnchor（拉起本宿主的那份运行时，
- * 桌面端在 app.asar 内）优先，其次该档案自己的依赖树。每处再试 hoisted 与 pnpm 嵌套两种布局。
+ * 桌面端在 app.asar 内）优先，其次该档案自己的依赖树。每处再试三种布局（见 `sessionFormatRoots`）。
+ *
+ * `tried` 可选：收集**所有尝试过的路径**（解析失败时由调用方写进日志——真机排查看的是这个，
+ * 而不是一句「解析不到」）。
  */
-export function resolveSessionFormatVersion(dshPackageJsonCandidates) {
+export function resolveSessionFormatVersion(dshPackageJsonCandidates, tried = []) {
     for (const candidate of dshPackageJsonCandidates) {
         const nodeModulesDir = join(dirname(candidate), '..', '..');
-        const roots = [nodeModulesDir, join(nodeModulesDir, '@deepseek-ai', 'dsh', 'node_modules')];
-        for (const root of roots) {
+        // 本机 dsh 版本只用于在 pnpm store 的多个 dsh-session 之间挑同版本者；读不到就不挑（见上）。
+        const dshVersion = readPackageVersionAt(candidate);
+        for (const root of sessionFormatRoots(nodeModulesDir, dshVersion)) {
+            tried.push(root);
             const version = readSessionFormatVersionAt(root);
             if (version !== undefined)
                 return version;

package/lib/utils/session-health-scan.d.ts

@@ -12,7 +12,13 @@ export interface SessionHealthScanOptions {
     targetFormatVersion?: number;
     /** 本机工作区记录的 cwd 目录键（`projectKeyOf(path)`） */
     workspaceKeys?: ReadonlySet<string>;
-    /** 本机全部已知会话 id 的归一化键（父对话存在性判定） */
+    /**
+     * 本机全部已知会话 id 的归一化键（父对话存在性判定）。
+     *
+     * **不传 = 未知**（调用方没有本机会话全量清单）→ 采集器**自证**：用本次遍历到的全部单元 id
+     * 作为已知集合（见 `scanSessionHealth`），绝不伪造成「确知为空集」；传了就用调用方的
+     * （UI 侧 `parentRelations` 更权威：它连注册表里的会话一起算）。
+     */
     knownSessionIds?: ReadonlySet<string>;
     /** 出现在多个 projectKey 的会话 id（归一化键） */
     duplicateSessionIds?: ReadonlySet<string>;