dsh-config-manager 0.1.69 → 0.1.71

package/lib/adapters/test-helpers.d.ts

@@ -10,6 +10,8 @@ export declare class MemFs implements FileSystemFacade {
     ensureDir?: FileSystemFacade['ensureDir'];
     /** 可选（issue #45）：绝对路径 realpath。测试按需注入；缺省维持「宿主不支持」的旧行为。 */
     realpathDir?: FileSystemFacade['realpathDir'];
+    /** 可选（只读预览）：目录体积上界。测试按需注入；缺省维持「宿主不支持」的旧行为（`link:` 体积按 0）。 */
+    dirSizeBytes?: FileSystemFacade['dirSizeBytes'];
     private readonly homeDir;
     constructor(homeDir: string);
     private key;
@@ -63,6 +65,11 @@ declare class AutoRegisterMap extends Map<string, {
 export declare class MemSettings implements SettingsFacade {
     /** 已注册命名空间（对齐真实 dsh-settings：插件激活时注册；未注册的 describe/replace 抛错） */
     registered: Set<string>;
+    /**
+     * 可选（宿主能力探测）：**默认不提供** ⇒ 既有测试继续覆盖「逐名 describe」回退路径；
+     * 需要验证快路径的测试自行挂上（真实宿主 DshSettingsFacade 始终提供）。
+     */
+    describeAll?: SettingsFacade['describeAll'];
     /** 有值的命名空间自动视为已注册 */
     ns: AutoRegisterMap;
     describe(namespace: string, _opts?: {
@@ -100,16 +107,36 @@ export declare class MemWorkspace implements WorkspaceFacade {
     writeRecord(r: WorkspaceRecord): Promise<void>;
     removeRecord(id: string): Promise<void>;
 }
+/**
+ * 内存 patch 门面，**按层分桶**（issue #71）。
+ *
+ * `lines` 仍是**用户（home）层**的桶 —— 绝大多数既有测试只关心「一行进、一行出」，
+ * 直接操作 `lines` 即可，语义与改造前完全一致。其它层（profile 层）走 `byFile`：
+ * 缺省空桶，因此「读两层」的调用方在旧测试里读到的 profile 层就是空的，不会污染断言。
+ *
+ * 分层用 `byFile(rel)` 显式取桶，避免测试里手写路径字符串。
+ */
 export declare class MemPatch implements PatchFileFacade {
+    /** 用户（home）层桶：`cordis.patch.yml`。 */
     lines: Map<string, {
         lineId: string;
         raw: unknown;
     }>;
-    readPatchLines(_file: string): Promise<{
+    /** 其它层桶：层路径 → 行表（profile 层等）。 */
+    byFile: Map<string, Map<string, {
+        lineId: string;
+        raw: unknown;
+    }>>;
+    /** 取（必要时建）某一层的桶；用户层恒为 `lines`（与旧测试兼容）。 */
+    bucket(file: string): Map<string, {
+        lineId: string;
+        raw: unknown;
+    }>;
+    readPatchLines(file: string): Promise<{
         lineId: string;
         raw: unknown;
     }[]>;
-    applyPatchChanges(_file: string, changes: {
+    applyPatchChanges(file: string, changes: {
         lineId: string;
         raw: unknown;
         action: 'insert' | 'update' | 'remove';
@@ -138,6 +165,8 @@ export declare class MockHostContext implements HostContext {
     fs: MemFs;
     /** 可选（issue #45）：会话存储端口；测试按需注入（缺省 = 宿主未提供该能力）。 */
     sessions?: HostContext['sessions'];
+    /** 可选（issue #71）：技能服务端口；测试按需注入（缺省 = 退回纯目录扫描）。 */
+    skills?: HostContext['skills'];
     constructor(platform: string, homeDir: string, profile?: string);
 }
 export declare function makeContext(platform: string, homeDir: string, profile?: string): MockHostContext;

package/lib/adapters/test-helpers.js

@@ -6,6 +6,7 @@ import { normalizePath } from '../utils/paths.js';
 import { createLogger } from '../utils/logger.js';
 import { sha256Hex } from '../utils/hashing.js';
 import { zhMsg } from '../core/messages.js';
+import { USER_PATCH_FILE } from '../core/patch-layers.js';
 export class MemFs {
     files = new Map();
     /** 可选（issue #37）：详细的链接遍历。测试按需注入；缺省走 listRecursive 回退路径。 */
@@ -14,6 +15,8 @@ export class MemFs {
     ensureDir;
     /** 可选（issue #45）：绝对路径 realpath。测试按需注入；缺省维持「宿主不支持」的旧行为。 */
     realpathDir;
+    /** 可选（只读预览）：目录体积上界。测试按需注入；缺省维持「宿主不支持」的旧行为（`link:` 体积按 0）。 */
+    dirSizeBytes;
     homeDir;
     constructor(homeDir) {
         this.homeDir = homeDir;
@@ -95,6 +98,11 @@ class AutoRegisterMap extends Map {
 export class MemSettings {
     /** 已注册命名空间（对齐真实 dsh-settings：插件激活时注册；未注册的 describe/replace 抛错） */
     registered = new Set();
+    /**
+     * 可选（宿主能力探测）：**默认不提供** ⇒ 既有测试继续覆盖「逐名 describe」回退路径；
+     * 需要验证快路径的测试自行挂上（真实宿主 DshSettingsFacade 始终提供）。
+     */
+    describeAll;
     /** 有值的命名空间自动视为已注册 */
     ns = new AutoRegisterMap(this.registered);
     async describe(namespace, _opts) {
@@ -167,17 +175,44 @@ export class MemWorkspace {
     async writeRecord(r) { this.records.set(r.id, r); }
     async removeRecord(id) { this.records.delete(id); }
 }
+/**
+ * 内存 patch 门面，**按层分桶**（issue #71）。
+ *
+ * `lines` 仍是**用户（home）层**的桶 —— 绝大多数既有测试只关心「一行进、一行出」，
+ * 直接操作 `lines` 即可，语义与改造前完全一致。其它层（profile 层）走 `byFile`：
+ * 缺省空桶，因此「读两层」的调用方在旧测试里读到的 profile 层就是空的，不会污染断言。
+ *
+ * 分层用 `byFile(rel)` 显式取桶，避免测试里手写路径字符串。
+ */
 export class MemPatch {
+    /** 用户（home）层桶：`cordis.patch.yml`。 */
     lines = new Map();
-    async readPatchLines(_file) {
-        return [...this.lines.values()];
+    /** 其它层桶：层路径 → 行表（profile 层等）。 */
+    byFile = new Map();
+    /** 取（必要时建）某一层的桶；用户层恒为 `lines`（与旧测试兼容）。 */
+    bucket(file) {
+        if (file === USER_PATCH_FILE)
+            return this.lines;
+        let bucket = this.byFile.get(file);
+        if (bucket === undefined) {
+            bucket = new Map();
+            this.byFile.set(file, bucket);
+        }
+        return bucket;
+    }
+    async readPatchLines(file) {
+        if (file === USER_PATCH_FILE)
+            return [...this.lines.values()];
+        const bucket = this.byFile.get(file);
+        return bucket === undefined ? [] : [...bucket.values()];
     }
-    async applyPatchChanges(_file, changes) {
+    async applyPatchChanges(file, changes) {
+        const bucket = this.bucket(file);
         for (const c of changes) {
             if (c.action === 'remove')
-                this.lines.delete(c.lineId);
+                bucket.delete(c.lineId);
             else
-                this.lines.set(c.lineId, { lineId: c.lineId, raw: c.raw });
+                bucket.set(c.lineId, { lineId: c.lineId, raw: c.raw });
         }
     }
 }
@@ -224,6 +259,8 @@ export class MockHostContext {
     fs;
     /** 可选（issue #45）：会话存储端口；测试按需注入（缺省 = 宿主未提供该能力）。 */
     sessions;
+    /** 可选（issue #71）：技能服务端口；测试按需注入（缺省 = 退回纯目录扫描）。 */
+    skills;
     constructor(platform, homeDir, profile) {
         this.platform = platform;
         this.homeDir = homeDir;

package/lib/adapters/workspaces.js

@@ -29,6 +29,50 @@ export function isCreatableWorkspacePath(path, platform = process.platform) {
 function reasonOf(error) {
     return error instanceof Error ? error.message : String(error);
 }
+/**
+ * 按记录 id 归并工作区记录（audit-foreign foreign-F2；与上游内核 FIX-foreign 同一口径）。
+ *
+ * 为什么必须归并：记录 id 由 `projectKeyOf(path)` 派生（多对一 —— 分隔符 run 会被折叠），
+ * 同一目录的两种写法（Windows 反斜杠/正斜杠、posix `/a/b` 与 `/a//b`）会产出**同一个 id 的两条记录**。
+ * 不归并的话：计划里出现同 id 的两条 Create（一次决策命中两条）、applyItem 按 id 只能取到第一条
+ * → 第二条记录的 path/title/sessionIds 静默消失（analysis.valid 仍为 true，零告警）。
+ *
+ * 归并规则：`sessionIds` 取**并集**（按 `sessionIdKey` 裸键去重，保持先到顺序；两种命名形态
+ * 指向同一条会话时只留一条），`path`/`title` 取**先到者**（与内核侧一致）。
+ * 返回顺序 = 首次出现顺序；`duplicateCount` 供调用方在计划里显式标注（绝不静默）。
+ */
+function mergeWorkspaceRecordsById(records) {
+    const order = [];
+    const byId = new Map();
+    for (const rec of records) {
+        // 纵深防御（t73 的 F2）：非对象记录直接跳过。第三方包可能带 null；validate 已拒（workspaces[]），
+        // 生产不可达 —— 但归并是**新增**调用点，不让它成为又一条内部 TypeError 的来源。
+        const raw = rec;
+        if (raw === null || typeof raw !== 'object')
+            continue;
+        // 只接受字符串元素（t73 的 F1）：`sessionIdKey` 的入参契约是字符串，数字/null 元素会让它抛
+        // TypeError（base 上这些元素根本不经过 sessionIdKey —— 归并去重是新增调用点）。非法元素丢弃。
+        const ids = Array.isArray(rec.sessionIds)
+            ? rec.sessionIds.filter((sid) => typeof sid === 'string')
+            : [];
+        const hit = byId.get(rec.id);
+        if (hit === undefined) {
+            byId.set(rec.id, { rec: { ...rec, sessionIds: [...ids] }, duplicateCount: 1 });
+            order.push(rec.id);
+            continue;
+        }
+        hit.duplicateCount += 1;
+        const seen = new Set(hit.rec.sessionIds.map((s) => sessionIdKey(s)));
+        for (const sid of ids) {
+            const key = sessionIdKey(sid);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            hit.rec.sessionIds.push(sid);
+        }
+    }
+    return order.map((id) => byId.get(id));
+}
 export class WorkspacesAdapter {
     id = 'workspaces';
     displayName = 'Workspaces';
@@ -62,7 +106,11 @@ export class WorkspacesAdapter {
     async analyzeImport(data, ctx) {
         const msg = ctx.msg;
         const items = [];
-        for (const rec of data.workspaces) {
+        // audit-foreign foreign-F2（适配器侧加固）：同一 id 的多条记录（同一目录的多种写法 → 同一个
+        // 派生 id）必须先**归并**再规划。否则会产出同 id 的两条 Create（用户一次决策命中两条，
+        // 逐条决策语义错乱），且 applyItem 按 id 只能取到第一条 → 第二条记录的 path/title/sessionIds
+        // 静默消失。归并口径与上游内核一致：sessionIds 取并集（按裸键去重），path/title 取先到者。
+        for (const { rec, duplicateCount } of mergeWorkspaceRecordsById(data.workspaces)) {
             const id = `workspace:${rec.id}`;
             /** issue #45：本工作区拥有的会话 id 随计划项带上（导入选择器据此联动勾选会话） */
             const ownedSessions = {
@@ -70,24 +118,35 @@ export class WorkspacesAdapter {
                 // 第二判据：sessionIds 覆盖不到的会话按「cwd 目录键相同」认领（与导出侧同一口径）
                 projectKey: projectKeyOf(rec.path),
             };
+            // 归并发生时的可见标注（raw key=value，与既有 detail 的 current=/imported= 同风格；
+            // 绝不静默：计划里看得见「这条是被归并过的」）
+            const mergeDetail = duplicateCount > 1
+                ? `duplicateIdRecords=${duplicateCount} mergedSessionIds=${rec.sessionIds.length}`
+                : '';
             const existing = (await ctx.target.workspace.listRecords()).find((r) => r.id === rec.id);
             if (!existing) {
                 items.push({
                     id, kind: 'Create', adapter: 'workspaces',
                     ...ownedSessions,
+                    ...(mergeDetail !== '' ? { detail: mergeDetail } : {}),
                     description: msg('adapter.workspaceCreate', { title: rec.title ?? rec.id, path: rec.path }), severity: 'info',
                     target: { adapter: 'workspaces', ref: rec.id },
                 });
             }
             else if (isDeepStrictEqual(existing, rec)) {
-                items.push({ id, kind: 'Skip', adapter: 'workspaces', ...ownedSessions, description: msg('adapter.workspaceSame', { id: rec.id }), severity: 'info' });
+                items.push({
+                    id, kind: 'Skip', adapter: 'workspaces', ...ownedSessions,
+                    ...(mergeDetail !== '' ? { detail: mergeDetail } : {}),
+                    description: msg('adapter.workspaceSame', { id: rec.id }), severity: 'info',
+                });
             }
             else {
                 items.push({
                     id, kind: 'Conflict', adapter: 'workspaces',
                     ...ownedSessions,
                     description: msg('adapter.workspaceDiff', { id: rec.id }),
-                    detail: `current=${JSON.stringify(existing)} imported=${JSON.stringify(rec)}`.slice(0, 200),
+                    detail: (`current=${JSON.stringify(existing)} imported=${JSON.stringify(rec)}`
+                        + (mergeDetail !== '' ? ' ' + mergeDetail : '')).slice(0, 200),
                     severity: 'warning', target: { adapter: 'workspaces', ref: rec.id },
                 });
             }
@@ -111,8 +170,19 @@ export class WorkspacesAdapter {
         if (!ref)
             return { ok: false, message: ctx.msg('adapter.missingTargetRef') };
         const data = ctx.sections.get('workspaces');
-        const rec = data?.workspaces.find((r) => r.id === ref);
-        if (!rec)
+        // audit-foreign foreign-F2（适配器侧加固）：同一 id 可能有多条记录（同一目录的多种写法派生同一 id）。
+        // 此前 find() 恒取第一条 → 第二条记录的 path/title/sessionIds 静默丢失（analysis.valid 仍为 true、
+        // 零告警）。这里取**全部**同 id 记录并按同一口径归并后写入 —— 绝不静默丢弃。同 id 的两条计划项
+        // 即便都执行，也只是重复写同一条归并结果（幂等）。
+        // t73 的 F2（纵深防御，两入口行为一致）：非数组 / 含 null 记录的畸形载荷一律不当成记录集 ——
+        // `r.id` 直接取会在 null 上抛（validate 已拒 ⇒ 生产不可达，但这里也不让它成为新的内部 TypeError 来源）。
+        const allRecords = data === undefined || !Array.isArray(data.workspaces) ? [] : data.workspaces;
+        const sameIdRecords = allRecords.filter((r) => {
+            const raw = r;
+            return raw !== null && typeof raw === 'object' && r.id === ref;
+        });
+        const rec = sameIdRecords.length === 0 ? undefined : mergeWorkspaceRecordsById(sameIdRecords)[0]?.rec;
+        if (rec === undefined)
             return { ok: false, message: ctx.msg('adapter.workspaceMissing', { ref }) };
         const notes = [];
         // issue #45 已知缺口①：备份里的工作区路径在本机不存在时，DSH registry.create() 的
@@ -195,6 +265,28 @@ export class WorkspacesAdapter {
                 for (const w of section.workspaces) {
                     if (w === null || typeof w !== 'object' || typeof w.id !== 'string' || typeof w.path !== 'string') {
                         issues.push({ path: 'workspaces[]', message: msg('adapter.validate.workspaceIdentity'), severity: 'error' });
+                        continue;
+                    }
+                    // ui-F3：sessionIds 是会话可见性的必需字段（docs/spec/bundle-format-v1.md §6），
+                    // 而 analyzeImport / finalizeImport 直接读 rec.sessionIds.length —— 缺它有两条后果：
+                    // ① validate 放过后 analyzeImport 抛内部 TypeError → 整包被拦下且文案不可行动；
+                    // ② 即便绕过，工作区记录也失去会话归属。这里按「必需数组」显式报出字段名。
+                    if (!Array.isArray(w.sessionIds)) {
+                        issues.push({ path: `workspaces.${String(w.id)}.sessionIds`, message: msg('adapter.validate.array', { subject: 'sessionIds' }), severity: 'error' });
+                    }
+                    else {
+                        // t73 的 F1：**元素级**校验 —— 归并去重会对每个元素调 sessionIdKey（字符串契约），
+                        // 非字符串元素会让 analyzeImport / applyItem 抛内部 TypeError（validate 放行 ⇒ 整包被拦、文案不可行动）。
+                        // 这里显式报出下标，让这种包在 validate 阶段就被拦下。
+                        w.sessionIds.forEach((sid, i) => {
+                            if (typeof sid !== 'string') {
+                                issues.push({
+                                    path: `workspaces.${String(w.id)}.sessionIds[${i}]`,
+                                    message: msg('adapter.validate.string', { subject: `sessionIds[${i}]` }),
+                                    severity: 'error',
+                                });
+                            }
+                        });
                     }
                 }
             }

package/lib/cli/actions.d.ts

@@ -4,6 +4,7 @@ import { readSafeModeMarkerSync } from '../core/phase3-host.ts';
 import { type SnapshotMeta } from '../core/restore.ts';
 import { type BackupFileMeta } from '../sync/backup-files.ts';
 import { type SessionHealthScanResult } from '../utils/session-health-scan.ts';
+import type { SessionVerifyResult } from '../utils/session-verify.ts';
 /** 进程是否存活（不发送信号，只探测）。EPERM = 存在但无权限发信号 → 仍算存活。 */
 export declare function isProcessAlive(pid: number): boolean;
 /** 一个在跑的 DSH 实例（来自 `<root>/running/<profile>.json` 心跳）。 */
@@ -229,25 +230,71 @@ export interface SessionLogRepairRow {
     /** 备份文件名（与日志同目录，回滚只认台账，不认用户给的路径） */
     backupName?: string;
     repairId?: string;
+    /**
+     * 写后真 codec 复验结论（**逐字段透传** service 的 SessionVerifyResult，不改造/不丢字段）。
+     * JSON 消费者必须据它区分三态：verified+equivalentToReadPath（现役读盘可读）/
+     * verified+!equivalentToReadPath（只有迁移链能还原）/ !verified（未验证，原因见 reason）。
+     * 预览路径不跑复验门 ⇒ 这一项缺省。
+     */
+    verify?: SessionVerifyResult;
+    /** 确定性失败（reason='verify-failed'）时：本次备份的自动回滚是否成功（false = 目标仍是修复后字节） */
+    rolledBack?: boolean;
     message: string;
 }
 export interface InlineRepairOutcome {
     ok: boolean;
     dryRun: boolean;
     rows: SessionLogRepairRow[];
-    /** 页面用的等价命令 */
+    /**
+     * 离线出口命令（可复制去终端）。
+     *
+     * **不是本入口的等价实现** —— 见 `repairSessionLogInline` 的能力边界：`sessions repair` 只做
+     * 布局归位与重复 id 隔离，不改写会话字节；字节级离线通道只有救急台 `dcm web`。
+     */
     commands: string[];
     error?: string;
 }
+/**
+ * 真 codec 复验结论 → 一句人话（**三态**；服务层 utils/session-verify.ts 的定义为准）。
+ *
+ *  · verified && equivalentToReadPath   → 「现役读盘可读」= header.version === catalog.currentVersion === 已装版本，
+ *                                          DSH 的现役读盘路径此刻就能直接读它；
+ *  · verified && !equivalentToReadPath  → 只有**迁移链**能还原（pre-v4 日志：官方 resolveCurrentLog 对本代之前的
+ *                                          代际返回 undefined，即「没有现役日志」）；
+ *  · !verified                          → 「**未验证**」= 本机跑不了真 codec 门（如 available catalog 缺席 / 代际对不上 /
+ *                                          缺子会话事实）——**这是最常见的一态，必须说出来**，绝不能让它看起来像成功；
+ *  · verify 缺失（改造前的旧结果 / 预览路径）→ 空串：调用方保持原文案，绝不臆造「已验证」。
+ */
+export declare function sessionVerifyNoteOf(verify: SessionVerifyResult | undefined): string;
+/** 会话修复行的文案入参（只吃机器可读事实 —— 便于单测与两边共用）。 */
+export interface SessionRepairRowFacts {
+    ok: boolean;
+    reason?: string;
+    droppedRows?: number;
+    backupName?: string;
+    rolledBack?: boolean;
+    verify?: SessionVerifyResult;
+}
+/**
+ * 会话修复行 → message（CLI 与离线救急台**同一份**文案）。
+ *
+ * 成功路径按 verify 分三态；**!verified 时不出现无限定的成功表述**（先声明未验证，再如实说写入已生效）；
+ * verify 缺失时**逐字保持改造前的文案**（向后兼容，不臆造）；verify-failed 时说明已自动回滚 + 官方错误 detail。
+ */
+export declare function sessionRepairRowMessage(facts: SessionRepairRowFacts): string;
 /**
  * **就地修复「重放重复行」**（离线救急台 /sessions 页的写入口）。
  *
  * 能力边界（**不得放宽**）：
  *  - 只做 `session-repair-service` 已有的那一类 —— 字节相同 + seq 相同的重放重复行（零损失）；
  *    其余类别（合成 closer / seq 空洞 / 不可解析行 / 容器非法 / header 不可读 / 子代理缺父）
- *    **只报告 + 给离线命令**，绝不在这里扩张（设计稿 §10.3/§10.4 的 G-23 界限）。
+ *    **只报告**，绝不在这里扩张（设计稿 §10.3/§10.4 的 G-23 界限）。
+ *  - **离线出口只有一个**：救急台 `dsh-config-manager web`（别名 `dcm web`）—— 它调用的就是本函数。
+ *    CLI 的 `sessions repair`（加 `--fix`/`--apply` 才落盘）**不是**字节级修复的等价命令：
+ *    它只做**布局归位**（按首帧 cwd 把目录搬回 `projectKeyOf(cwd)`）与**重复 id 隔离**，不碰会话字节。
+ *    此前把 `sessions repair --apply` 写成「等价命令」是不实表述（已订正，见下面的 `commands`）。
  *  - 三道写入门由服务层自持：单元必须解析到会话根内 / 无 `session.lock` / 文件不在 30s 静止期内；
- *    「DSH 已停」这一条由 `checkWriteGates` 在这里补上（= 与 CLI `sessions repair --apply` 同一道门，
+ *    「DSH 已停」这一条由 `checkWriteGates` 在这里补上（与 CLI 写动作共用同一道写入门，
  *    比应用内 T8 通道更严：T8 跑在 DSH 内部，靠静止期而非停机）。
  *  - 与 CLI 同源：预览-应用指纹一致（TOCTOU）/ 时间戳备份 / 原子换入 / 写后复验，全在服务层。
  *

package/lib/cli/actions.js

@@ -19,6 +19,7 @@ import { EXPORTS_RETENTION_DEFAULT_MS, MARKET_RETENTION_DEFAULT_MS, TMP_RETENTIO
 import { scanDiskUsage } from '../core/disk-usage.js';
 import { readSafeModeMarkerSync, safeModeMarkerPath } from '../core/phase3-host.js';
 import { listSnapshots } from '../core/restore.js';
+import { readInstalledVersion, resolveProfileDir } from '../core/plugin-cli.js';
 import { DshProfileError, DshProfileManager } from '../profiles/dsh-profile-manager.js';
 import { DshProfileLauncher, LAUNCHES_FILENAME, parseLaunches } from '../profiles/dsh-profile-launcher.js';
 import { DshProfileRuntimeRegistry, parseRuntimeRecord, RUNTIME_STALE_MS } from '../profiles/dsh-profile-runtime.js';
@@ -345,15 +346,74 @@ export async function checkWriteGates(controlRoots, options = { needsDshStopped:
     }
     return { ok: true };
 }
+/* ----------------------------------------------- 会话修复行的文案（纯函数，可单测） */
+/**
+ * 真 codec 复验结论 → 一句人话（**三态**；服务层 utils/session-verify.ts 的定义为准）。
+ *
+ *  · verified && equivalentToReadPath   → 「现役读盘可读」= header.version === catalog.currentVersion === 已装版本，
+ *                                          DSH 的现役读盘路径此刻就能直接读它；
+ *  · verified && !equivalentToReadPath  → 只有**迁移链**能还原（pre-v4 日志：官方 resolveCurrentLog 对本代之前的
+ *                                          代际返回 undefined，即「没有现役日志」）；
+ *  · !verified                          → 「**未验证**」= 本机跑不了真 codec 门（如 available catalog 缺席 / 代际对不上 /
+ *                                          缺子会话事实）——**这是最常见的一态，必须说出来**，绝不能让它看起来像成功；
+ *  · verify 缺失（改造前的旧结果 / 预览路径）→ 空串：调用方保持原文案，绝不臆造「已验证」。
+ */
+export function sessionVerifyNoteOf(verify) {
+    if (verify === undefined)
+        return '';
+    if (verify.verified) {
+        return verify.equivalentToReadPath
+            ? '真 codec 复验通过（现役读盘可读）。'
+            : '真 codec 复验通过（迁移链可还原，非现役读盘）。';
+    }
+    return '未验证：本机无法运行真 codec 复验（' + verify.reason + '）。';
+}
+/**
+ * 会话修复行 → message（CLI 与离线救急台**同一份**文案）。
+ *
+ * 成功路径按 verify 分三态；**!verified 时不出现无限定的成功表述**（先声明未验证，再如实说写入已生效）；
+ * verify 缺失时**逐字保持改造前的文案**（向后兼容，不臆造）；verify-failed 时说明已自动回滚 + 官方错误 detail。
+ */
+export function sessionRepairRowMessage(facts) {
+    const dropped = String(facts.droppedRows ?? 0);
+    const backup = String(facts.backupName ?? '（未落盘）');
+    if (!facts.ok) {
+        if (facts.reason === 'verify-failed') {
+            const rolled = facts.rolledBack === true
+                ? '已自动回滚到修复前字节'
+                : facts.rolledBack === false
+                    ? '已自动回滚未成功（目标仍是修复后字节，需人工处理）'
+                    : '已自动回滚（服务层未回传结果，请以目标字节为准）';
+            const detail = facts.verify !== undefined && !facts.verify.verified && facts.verify.detail !== undefined && facts.verify.detail !== ''
+                ? '；官方错误：' + facts.verify.detail
+                : '';
+            return '未修复（verify-failed）：真 codec 复验未通过，' + rolled + detail + '。';
+        }
+        return '未修复（' + (facts.reason ?? 'unknown') + '）：原文件未改动。';
+    }
+    if (facts.verify === undefined) {
+        // 向后兼容：没有复验结论就不添油加醋（改造前逐字如此）
+        return '已丢弃 ' + dropped + ' 行重放重复事件；备份 ' + backup;
+    }
+    if (facts.verify.verified) {
+        return '已丢弃 ' + dropped + ' 行重放重复事件；备份 ' + backup + '。' + sessionVerifyNoteOf(facts.verify);
+    }
+    return sessionVerifyNoteOf(facts.verify)
+        + '写入已生效（已丢弃 ' + dropped + ' 行重放重复事件；备份 ' + backup + '）——本机 DSH 能否现役读它**没有被证明**，可用 repairId 回滚。';
+}
 /**
  * **就地修复「重放重复行」**（离线救急台 /sessions 页的写入口）。
  *
  * 能力边界（**不得放宽**）：
  *  - 只做 `session-repair-service` 已有的那一类 —— 字节相同 + seq 相同的重放重复行（零损失）；
  *    其余类别（合成 closer / seq 空洞 / 不可解析行 / 容器非法 / header 不可读 / 子代理缺父）
- *    **只报告 + 给离线命令**，绝不在这里扩张（设计稿 §10.3/§10.4 的 G-23 界限）。
+ *    **只报告**，绝不在这里扩张（设计稿 §10.3/§10.4 的 G-23 界限）。
+ *  - **离线出口只有一个**：救急台 `dsh-config-manager web`（别名 `dcm web`）—— 它调用的就是本函数。
+ *    CLI 的 `sessions repair`（加 `--fix`/`--apply` 才落盘）**不是**字节级修复的等价命令：
+ *    它只做**布局归位**（按首帧 cwd 把目录搬回 `projectKeyOf(cwd)`）与**重复 id 隔离**，不碰会话字节。
+ *    此前把 `sessions repair --apply` 写成「等价命令」是不实表述（已订正，见下面的 `commands`）。
  *  - 三道写入门由服务层自持：单元必须解析到会话根内 / 无 `session.lock` / 文件不在 30s 静止期内；
- *    「DSH 已停」这一条由 `checkWriteGates` 在这里补上（= 与 CLI `sessions repair --apply` 同一道门，
+ *    「DSH 已停」这一条由 `checkWriteGates` 在这里补上（与 CLI 写动作共用同一道写入门，
  *    比应用内 T8 通道更严：T8 跑在 DSH 内部，靠静止期而非停机）。
  *  - 与 CLI 同源：预览-应用指纹一致（TOCTOU）/ 时间戳备份 / 原子换入 / 写后复验，全在服务层。
  *
@@ -363,12 +423,16 @@ export async function checkWriteGates(controlRoots, options = { needsDshStopped:
 export async function repairSessionLogInline(options, controlRoots) {
     const base = {
         ok: true, dryRun: !options.apply, rows: [],
-        commands: ['dsh-config-manager sessions repair --apply  # 等价命令（离线时）'],
+        // 不得再把 `sessions repair --apply` 说成等价命令：它只做布局归位与重复 id 隔离，不改写会话字节。
+        commands: [
+            'dsh-config-manager web  # 离线救急台：字节级就地修复的唯一离线通道（别名 dcm web）',
+            'dsh-config-manager sessions repair  # 只做布局归位与重复 id 隔离，不改写会话字节（--fix/--apply 才落盘）',
+        ],
     };
     if (options.unitIds.length === 0)
         return { ...base, ok: false, error: '没有选中任何会话单元。' };
     if (options.apply) {
-        // 与 sessions repair --apply 同一道门：改写会话字节必须先停 DSH（+ SAFE MODE + 环境锁）
+        // 与 CLI 写动作共用同一道写入门：改写会话字节必须先停 DSH（+ SAFE MODE + 环境锁）
         const gate = await checkWriteGates(controlRoots, { needsDshStopped: true });
         if (!gate.ok)
             return { ...base, ok: false, error: gate.reason };
@@ -388,7 +452,8 @@ export async function repairSessionLogInline(options, controlRoots) {
                 ...(preview.expect !== undefined ? { expect: preview.expect } : {}),
                 message: preview.ok
                     ? '可零损失修复：将丢弃 ' + String(preview.droppedRows ?? 0) + ' 行重放重复事件。'
-                    : '不可修复（' + (preview.reason ?? 'unknown') + '）：这一类只报告，请用离线命令或保留原样。',
+                    : '不可修复（' + (preview.reason ?? 'unknown') + '）：这一类只报告，本入口绝不改写它的字节；'
+                        + '字节级离线出口是救急台 dsh-config-manager web（sessions repair 只做布局归位与重复 id 隔离）。',
             });
             continue;
         }
@@ -397,18 +462,22 @@ export async function repairSessionLogInline(options, controlRoots) {
             homeDir: options.home, dataDir: options.dataDir, unitId,
             ...(expect !== undefined ? { expect } : {}),
         });
-        rows.push({
-            unitId,
+        // 文案与结构化字段同源：verify 逐字段透传（JSON 消费者据它区分三态），message 由纯函数分派
+        const facts = {
             ok: applied.ok,
             ...(applied.reason !== undefined ? { reason: applied.reason } : {}),
             ...(applied.droppedRows !== undefined ? { droppedRows: applied.droppedRows } : {}),
+            ...(applied.backupName !== undefined ? { backupName: applied.backupName } : {}),
+            ...(applied.rolledBack !== undefined ? { rolledBack: applied.rolledBack } : {}),
+            ...(applied.verify !== undefined ? { verify: applied.verify } : {}),
+        };
+        rows.push({
+            unitId,
+            ...facts,
             ...(applied.bytesBefore !== undefined ? { bytesBefore: applied.bytesBefore } : {}),
             ...(applied.bytesAfter !== undefined ? { bytesAfter: applied.bytesAfter } : {}),
-            ...(applied.backupName !== undefined ? { backupName: applied.backupName } : {}),
             ...(applied.repairId !== undefined ? { repairId: applied.repairId } : {}),
-            message: applied.ok
-                ? '已丢弃 ' + String(applied.droppedRows ?? 0) + ' 行重放重复事件；备份 ' + String(applied.backupName ?? '（未落盘）')
-                : '未修复（' + (applied.reason ?? 'unknown') + '）：原文件未改动。',
+            message: sessionRepairRowMessage(facts),
         });
     }
     return { ...base, ok: rows.every((r) => r.ok || !options.apply), rows };
@@ -782,6 +851,27 @@ export async function unlockEncryptedBackup(exportsDir, fileName, password) {
 function isDangerousRestoreKind(kind) {
     return kind === 'hostFileRestore' || kind === 'hostFileRemove' || kind === 'fileRestore' || kind === 'fileRemove' || kind === 'pluginRemove';
 }
+/** 本机 DSH 包名（T8-F3；与 core/restore.ts 的 `DSH_PACKAGE_NAME` 同值 —— 两处读的是同一个文件）。 */
+const DSH_PACKAGE_NAME = '@deepseek-ai/dsh';
+/**
+ * 目标档案当前的 DSH 版本（T8-F3；离线 CLI 的 best-effort 来源）。
+ *
+ * 为什么是这个来源：CLI 恰恰在 **DSH 已经起不来** 的场景下运行，没有「运行时权威版本」可问
+ * （那是宿主侧的东西：`HostContext.dshVersion` / `profileContext.installAnchor`）。这里与
+ * `core/restore.ts` 的兜底、档案页的 `DshProfileMeta.dshVersion` **读的是同一个文件**
+ * （`profiles/<p>/node_modules/@deepseek-ai/dsh/package.json`），所以显式传出不改变数值，
+ * 但把「版本判定来源」固定在一处（将来 CLI 若拿到更好的来源只改这里），且不再让 core 猜一次。
+ * 读不到 → undefined：core 按「版本未知」处理（不猜、不产出「版本不同」告警）。
+ */
+function currentProfileDshVersion(paths) {
+    try {
+        return readInstalledVersion(resolveProfileDir(paths.homeDir, paths.profile), DSH_PACKAGE_NAME) ?? undefined;
+    }
+    catch {
+        // 档案名非法 / 目录不可读 → 与「没装」同样处理：不猜版本（绝不因此让恢复计划失败）
+        return undefined;
+    }
+}
 /**
  * 取某个快照的**恢复计划**（只读；与 CLI \`restore --dry-run\` 同一实现）。
  *
@@ -796,6 +886,7 @@ export async function planSnapshotRestore(paths, snapshotId) {
             homeDir: paths.homeDir,
             profile: paths.profile,
             snapshotsRoot: paths.snapshotsDir,
+            currentDshVersion: currentProfileDshVersion(paths),
         });
         return {
             ok: true,
@@ -837,6 +928,7 @@ export async function runSnapshotRestore(paths, snapshotId) {
             homeDir: paths.homeDir,
             profile: paths.profile,
             snapshotsRoot: paths.snapshotsDir,
+            currentDshVersion: currentProfileDshVersion(paths),
         });
         return {
             ok: report.failed.length === 0,

package/lib/cli/help.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 离线 CLI 帮助文案的单一事实源（2026-10 整理）。
+ *
+ * 帮助分两层，都由本文件渲染，**绝不在 index.ts 里再散写一遍文案**：
+ *  - 速查页（`dcm help`）：按风险分组的命令表 + 通用选项，目标是「30 行内扫一眼就知道用哪个」；
+ *  - 详情页（`dcm <命令> --help` / `dcm help <命令>`）：说明 / 选项 / 退出码 / 示例。
+ *
+ * 两条渲染约定（改文案前先读）：
+ *  1. 速查页的「用法」列**只用 ASCII**（占位符写 `<file|path>` 而不是 `<文件|路径>`）：
+ *     CJK 是双宽字符，混进 padEnd 对齐的一列会让整页参差。
+ *  2. 退出码必须与实现一致 —— 判定逻辑在各 run* 函数里，这里只是结论；改了行为要同步改这里。
+ */
+export declare const IMPORT_SOURCE_IDS: readonly string[];
+/** 详情页里的一个「左列 + 右列」条目（选项 / 退出码 / 子命令都用它） */
+export interface HelpEntry {
+    /** 左列，只用 ASCII */
+    readonly flag: string;
+    /** 右列说明（中文） */
+    readonly desc: string;
+}
+export interface HelpSection {
+    readonly title: string;
+    readonly entries: readonly HelpEntry[];
+}
+export interface CommandHelp {
+    /** 命令名（`dcm <name> --help` 与 `dcm help <name>` 的键） */
+    readonly name: string;
+    /** 详情页首行：`<name> — <title>` */
+    readonly title: string;
+    /** 速查页里那一行的用法片段（ASCII only、尽量短） */
+    readonly usage: string;
+    /** 速查页里那一行的摘要（中文、一行） */
+    readonly summary: string;
+    /** 详情页「用法」段（不含 `dcm` 前缀，每项一行） */
+    readonly usageLines: readonly string[];
+    /** 详情页「说明」段（每项一行） */
+    readonly description: readonly string[];
+    /** 详情页的键值段，按声明顺序渲染 */
+    readonly sections: readonly HelpSection[];
+    /** 详情页「示例」 */
+    readonly examples: readonly string[];
+}
+export interface HelpRow {
+    /** 用法片段（ASCII only） */
+    readonly usage: string;
+    /** 一行摘要 */
+    readonly summary: string;
+    /** 该行指向的详情页（CommandHelp.name；`sessions` 有三行指向同一页） */
+    readonly help: string;
+}
+export interface HelpGroup {
+    readonly title: string;
+    readonly rows: readonly HelpRow[];
+}
+/** 通用选项（所有命令共有）——命令专属选项只出现在各自的详情页里 */
+export declare const GENERAL_OPTIONS: readonly HelpEntry[];
+/** 分组顺序 = 推荐阅读顺序：先诊断、再备份、再修复、最后才是危险的重装 */
+export declare const HELP_GROUPS: readonly HelpGroup[];
+export declare const COMMAND_HELP: readonly CommandHelp[];
+/** 速查页「用法」列的宽度（全表统一，保证摘要起始列一致） */
+export declare function usageColumnWidth(): number;
+/** 速查页（`dcm help`）：分组命令表 + 通用选项 + 上手顺序 */
+export declare function renderOverview(version: string): string[];
+/** 单命令详情页；不认识的名字返回 null（调用方决定怎么报错） */
+export declare function renderCommandHelp(name: string, version: string): string[] | null;