dsh-config-manager 0.1.71 → 0.1.73

package/lib/adapters/plugins.js

@@ -16,6 +16,7 @@ import { sha256Hex } from '../utils/hashing.js';
 import { installSpecFor, resolveProcessProfileName } from '../core/plugin-cli.js';
 import { classifyPluginSpec, LOCAL_PLUGIN_DIR, resolveLocalPluginPath } from '../core/local-plugin-pack.js';
 import { msgOf, zhMsg } from '../core/messages.js';
+import { engineMsg } from './messages.js';
 import { stringifyJsonSafe } from '../utils/json.js';
 import { isPathSafe, normalizePath } from '../utils/paths.js';
 import { isENOENT } from '../utils/guards.js';
@@ -58,7 +59,7 @@ function tarballOf(data, pkgName) {
 export function localTarballCacheName(relativePath) {
     const base = relativePath.split('/').pop() ?? '';
     if (base === '' || base.includes('\\') || base === '.' || base === '..') {
-        throw new Error(`非法 tarball 相对路径: ${relativePath}`);
+        throw new Error(engineMsg('adapter.tarballRelPathInvalid', { path: relativePath }));
     }
     return base;
 }
@@ -677,7 +678,7 @@ export class PluginsAdapter {
                         names: clean.dropped.map((d) => d.name).join(', '),
                     }));
                 }
-                return { ok: true, needsRestart: true, message: notes.join('；') };
+                return { ok: true, needsRestart: true, message: notes.join(msg('adapter.listSeparator')) };
             }
             catch (err) {
                 const reason = err instanceof Error ? err.message : String(err);
@@ -710,7 +711,7 @@ export class PluginsAdapter {
                     }
                     catch (err) {
                         // 解包失败不阻断安装尝试：退回原 spec（可能失败，但会如实报错而非静默丢失）
-                        ctx.onLog?.(`本地插件 ${name} 的 tarball 解包失败，回退原始 spec：${err instanceof Error ? err.message : String(err)}`);
+                        ctx.onLog?.(msg('adapter.localTarballUnpackFailed', { name, err: err instanceof Error ? err.message : String(err) }));
                     }
                 }
                 // 执行日志：记录实际将发起的子进程命令行（与宿主 DshPluginsFacade 的

package/lib/adapters/prompts.d.ts

@@ -1,4 +1,5 @@
 import type { MsgFunc } from '../core/messages.ts';
+import './messages.ts';
 import type { PromptEntry } from '../schema/types.ts';
 import type { ApplyResult, ConfigAdapter, ExportOptions, ExportSection, HostContext, ImportContext, PlanItem, ValidationResult } from '../core/types.ts';
 /** 导出记录：PromptEntry 之外记录来源行名与所在层（导入重建 / 写回定位用） */

package/lib/adapters/prompts.js

@@ -13,6 +13,8 @@
  * 于是写进 profile 层的 systemPrompt / planMode 在备份里全部丢失。现在两层都读、写回原层。
  */
 import { msgOf, zhMsg } from '../core/messages.js';
+// t6：注册 adapters 域追加目录（本模块只消费注入的 msg，故只引它的注册副作用）。
+import './messages.js';
 import { locatePatchLineLayer, readEffectivePatchLines, resolveWriteLayer } from '../core/patch-layers.js';
 import { sectionMeta } from '../schema/section-registry.js';
 import { validateJsonSection } from './json-section.js';
@@ -146,7 +148,11 @@ export class PromptsAdapter {
                     items.push({
                         id, kind: 'Conflict', adapter: 'prompts',
                         description: msg('adapter.promptDiff', { name: p.name }),
-                        detail: `行 ${p.sourceLineId} current=${JSON.stringify(sameName.text).slice(0, 80)} imported=${JSON.stringify(p.text).slice(0, 80)}`,
+                        detail: msg('adapter.promptDiffDetail', {
+                            line: String(p.sourceLineId),
+                            current: JSON.stringify(sameName.text).slice(0, 80),
+                            imported: JSON.stringify(p.text).slice(0, 80),
+                        }),
                         severity: 'warning',
                         // 层身份随计划项走：快照按这一层记原行、回滚才能写回原文件（issue #71）
                         target: { adapter: 'prompts', ref: p.sourceLineId ?? '', file: targetLine.file },

package/lib/adapters/self.d.ts

@@ -8,7 +8,13 @@
  *   - market/market-config.json 配置市场配置
  *
  * 排除项：sync/sync-history.json（执行记录，属数据非配置）、market/cache/（缓存）、
- * snapshots/（快照）、tmp/ exports/（临时/导出产物）——只备份「配置」，不备份数据。
+ * snapshots/（快照）、tmp/ exports/（临时/导出产物）、rollback-points/（回滚点库——磁盘体检
+ * 会统计它，但它是**数据**不是配置）、checkpoints/（遗留旧检查点库，已不再读取，也不删）
+ * ——只备份「配置」，不备份数据。
+ *
+ * 与磁盘体检（`src/core/disk-usage.ts`）的关系：那边新增统计 `rollback-points` / 遗留
+ * `checkpoints` **不改变本分区的载荷**——本清单是白名单（`SELF_CONFIG_FILES`），
+ * 被统计的目录一律不在其中，既不重复也不遗漏（守卫见 `self.test.ts`）。
  *
  * 实现：继承 FileCollectionAdapter 复用 analyzeImport/applyItem/validate（幂等 hash 比对、
  * 快照/回滚路径一致）；**清单来自覆写的 listRelPaths()（白名单），export() 与 preview() 都经
@@ -41,7 +47,7 @@ import { FileCollectionAdapter } from './file-collection.ts';
 export declare const SELF_CONFIG_FILES: readonly string[];
 export declare class SelfAdapter extends FileCollectionAdapter {
     readonly id: 'self';
-    readonly displayName = "Plugin Self Config";
+    readonly displayName: string;
     readonly defaultIncluded = true;
     readonly portability: 'portable';
     /** 插件自身配置目录（相对 homeDir；宿主按 dataDir 解析注入，缺省 dsh-config-manager） */

package/lib/adapters/self.js

@@ -1,3 +1,4 @@
+import { sectionMeta } from '../schema/section-registry.js';
 import { FileCollectionAdapter } from './file-collection.js';
 /** self 分区白名单文件（相对 baseDir，即 $DSH_HOME/dsh-config-manager/）。 */
 export const SELF_CONFIG_FILES = [
@@ -65,7 +66,7 @@ function canonicalizeWithoutRunState(raw) {
 }
 export class SelfAdapter extends FileCollectionAdapter {
     id = 'self';
-    displayName = 'Plugin Self Config';
+    displayName = sectionMeta('self').displayName;
     defaultIncluded = true;
     portability = 'portable';
     /** 插件自身配置目录（相对 homeDir；宿主按 dataDir 解析注入，缺省 dsh-config-manager） */
@@ -96,7 +97,7 @@ export class SelfAdapter extends FileCollectionAdapter {
      * 同时是单元 id（self:<rel>）与 includeItems 的比对键 —— 不能随平台漂移成反斜杠。
      */
     async listRelPaths(ctx) {
-        const empty = { paths: [], skippedLinks: [], followedLinks: 0, unreadableDirs: [] };
+        const empty = { paths: [], skippedLinks: [], skippedDepDirs: [], followedLinks: 0, unreadableDirs: [] };
         const found = [];
         for (const rel of SELF_CONFIG_FILES) {
             const full = `${this.baseDir}/${rel}`;

package/lib/adapters/sessions.d.ts

@@ -8,6 +8,7 @@
  * core/session-select.ts（单位 = 会话目录、文件名判据不写死、按日志最新 mtime 倒序）。
  */
 import { FileCollectionAdapter } from './file-collection.ts';
+import './messages.ts';
 import type { ApplyResult, ExportOptions, ExportSection, HostContext, ImportContext, PlanItem } from '../core/types.ts';
 import type { FilesSection } from '../schema/types.ts';
 export declare class SessionsAdapter extends FileCollectionAdapter {

package/lib/adapters/sessions.js

@@ -10,6 +10,8 @@
 import { FileCollectionAdapter } from './file-collection.js';
 import { listFilesDetailed } from './link-report.js';
 import { msgOf } from '../core/messages.js';
+// t6：注册 adapters 域追加目录（本模块只消费注入的 msg，故只引它的注册副作用）。
+import './messages.js';
 import { groupSessionUnits, isSessionLogFileName, normalizeSessionLimit, pickLatestSessionUnits, sessionIdKey } from '../core/session-select.js';
 import { projectKeyOf } from '../core/session-meta.js';
 import { applyPathMapping } from '../core/path-mapping.js';
@@ -357,7 +359,7 @@ export class SessionsAdapter extends FileCollectionAdapter {
                 continue;
             const dirRel = await this.findSessionDir(ctx, next.sessionId, next.key, allKeys);
             if (dirRel === null) {
-                uncoupled.push(next.sessionId + '（' + msg('export.sessionRelationNotFound') + '）');
+                uncoupled.push(msg('adapter.sessionUncoupledNote', { id: next.sessionId, reason: msg('export.sessionRelationNotFound') }));
                 continue;
             }
             const listing = await listFilesDetailed(ctx.fs, dirRel);
@@ -374,7 +376,7 @@ export class SessionsAdapter extends FileCollectionAdapter {
                 loaded.push({ relativePath: this.relPathOf(rel), data, contentHash: sha256Hex(data) });
             }
             if (tooLarge || loaded.length === 0) {
-                uncoupled.push(next.sessionId + '（' + msg('export.sessionParentTooLarge') + '）');
+                uncoupled.push(msg('adapter.sessionUncoupledNote', { id: next.sessionId, reason: msg('export.sessionParentTooLarge') }));
                 continue;
             }
             usedBytes += unitBytes;

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

@@ -167,6 +167,15 @@ export declare class MockHostContext implements HostContext {
     sessions?: HostContext['sessions'];
     /** 可选（issue #71）：技能服务端口；测试按需注入（缺省 = 退回纯目录扫描）。 */
     skills?: HostContext['skills'];
+    /**
+     * 可选（第三方插件数据）：系统 home 与它的文件门面。缺省 undefined = **旧宿主形态**
+     * （pluginData / pluginAssets 不收集也不写入，如实报码）；需要它们的测试自行注入，
+     * 或用 withOsHome() 把系统 home 指向本夹具自己的根。
+     */
+    osHomeDir?: string;
+    homeFs?: HostContext['homeFs'];
+    /** 测试助手：把「系统 home」指向本上下文的根（两分区在本夹具里即可直接用） */
+    withOsHome(): this;
     constructor(platform: string, homeDir: string, profile?: string);
 }
 export declare function makeContext(platform: string, homeDir: string, profile?: string): MockHostContext;

package/lib/adapters/test-helpers.js

@@ -261,6 +261,19 @@ export class MockHostContext {
     sessions;
     /** 可选（issue #71）：技能服务端口；测试按需注入（缺省 = 退回纯目录扫描）。 */
     skills;
+    /**
+     * 可选（第三方插件数据）：系统 home 与它的文件门面。缺省 undefined = **旧宿主形态**
+     * （pluginData / pluginAssets 不收集也不写入，如实报码）；需要它们的测试自行注入，
+     * 或用 withOsHome() 把系统 home 指向本夹具自己的根。
+     */
+    osHomeDir;
+    homeFs;
+    /** 测试助手：把「系统 home」指向本上下文的根（两分区在本夹具里即可直接用） */
+    withOsHome() {
+        this.osHomeDir = this.homeDir;
+        this.homeFs = this.fs;
+        return this;
+    }
     constructor(platform, homeDir, profile) {
         this.platform = platform;
         this.homeDir = homeDir;
@@ -283,6 +296,7 @@ export function makeManifest(platform = 'win32') {
             settings: false, ui: false, providers: false, plugins: false, mcp: false, prompts: false,
             skills: false, agentPresets: false, agentInstructions: false, workspaces: false, pluginFiles: false,
             credentialsStatus: false, secrets: false, sessions: false, self: false,
+            pluginData: false, pluginAssets: false,
         },
         security: { containsSecrets: false, encrypted: false, encryption: null },
     };

package/lib/adapters/ui.d.ts

@@ -11,8 +11,8 @@ import { type NamespaceProvider } from './settings.ts';
 export declare const KNOWN_UI_NAMESPACE_PREFIXES: readonly string[];
 /** namespace 名是否属于 UI 类（大小写不敏感前缀匹配） */
 export declare function isUiNamespace(name: string): boolean;
-/** localStorage 等 Host 无通道的 UI 状态说明（纯说明，不含值；研究报告 §2.2/§4.4） */
-export declare const UI_MIGRATION_NOTES: UiSection['uiMigrationNotes'];
+/** UI 迁移说明行（取文案在调用期现取；缺省 = 当前引擎语言的 engineMsg）。 */
+export declare function uiMigrationNotes(msg?: MsgFunc): UiSection['uiMigrationNotes'];
 export declare class UiAdapter implements ConfigAdapter<UiSection> {
     readonly id: 'ui';
     readonly displayName: string;

package/lib/adapters/ui.js

@@ -1,4 +1,5 @@
 import { zhMsg } from '../core/messages.js';
+import { engineMsg } from './messages.js';
 import { collectNamespaceRecords, planNamespaceItems, applyNamespaceItem, resolveNamespaces } from './settings.js';
 import { sectionMeta } from '../schema/section-registry.js';
 import { validateJsonSection } from './json-section.js';
@@ -20,30 +21,28 @@ export function isUiNamespace(name) {
     const lower = name.toLowerCase();
     return KNOWN_UI_NAMESPACE_PREFIXES.some((p) => lower.startsWith(p.toLowerCase()));
 }
-/** localStorage 等 Host 无通道的 UI 状态说明（纯说明，不含值；研究报告 §2.2/§4.4） */
-export const UI_MIGRATION_NOTES = [
-    {
-        plugin: 'dsh-task-board',
-        storage: 'localStorage',
-        key: 'dsh.taskBoard.v1',
-        migratable: false,
-        reason: '任务看板数据存于浏览器 localStorage，Host 侧无访问通道，需在目标机器重新配置',
-    },
-    {
-        plugin: 'dsh-aionui-panel',
-        storage: 'localStorage',
-        key: 'aionui-panel.*',
-        migratable: false,
-        reason: '面板宽度/折叠状态存于浏览器 localStorage，Host 侧无访问通道，需在目标机器重新配置',
-    },
-    {
-        plugin: 'dsh-client-ui-*',
-        storage: 'localStorage',
-        key: '*',
-        migratable: false,
-        reason: '浏览器端 UI 状态无法经 Host API 迁移',
-    },
+/**
+ * localStorage 等 Host 无通道的 UI 状态说明（纯说明，不含值；研究报告 §2.2/§4.4）。
+ *
+ * t6（英文界面零中文）：说明行的 `reason` 是用户可见文案 ⇒ 表里只放**目录键**，取文案在导出期现取
+ * （`uiMigrationNotes(msg)`）—— 这样导出的说明行跟随界面语言，而不是冻结在装配期语言。
+ * （表本身是数据；中文只存在于 adapters 域的追加目录 `src/adapters/messages.ts`。）
+ */
+const UI_MIGRATION_NOTE_ROWS = [
+    { plugin: 'dsh-task-board', storage: 'localStorage', key: 'dsh.taskBoard.v1', migratable: false, reasonKey: 'adapter.uiLocalStorageTaskBoard' },
+    { plugin: 'dsh-aionui-panel', storage: 'localStorage', key: 'aionui-panel.*', migratable: false, reasonKey: 'adapter.uiLocalStoragePanel' },
+    { plugin: 'dsh-client-ui-*', storage: 'localStorage', key: '*', migratable: false, reasonKey: 'adapter.uiLocalStorageGeneric' },
 ];
+/** UI 迁移说明行（取文案在调用期现取；缺省 = 当前引擎语言的 engineMsg）。 */
+export function uiMigrationNotes(msg = engineMsg) {
+    return UI_MIGRATION_NOTE_ROWS.map((row) => ({
+        plugin: row.plugin,
+        storage: row.storage,
+        key: row.key,
+        migratable: row.migratable,
+        reason: msg(row.reasonKey),
+    }));
+}
 export class UiAdapter {
     id = 'ui';
     // 元数据唯一来源 = 注册表（t31）：不再与 ui/export-flow.ts 的导出目录各写一份
@@ -59,10 +58,11 @@ export class UiAdapter {
         const all = await resolveNamespaces(this.namespaces, ctx);
         const uiNames = all.filter((n) => isUiNamespace(n));
         const namespaces = await collectNamespaceRecords(ctx, uiNames, warnings);
+        const notes = uiMigrationNotes(ctx.msg);
         return {
             sectionId: 'ui',
-            data: { version: 1, namespaces, uiMigrationNotes: UI_MIGRATION_NOTES },
-            counts: { namespaces: Object.keys(namespaces).length, notes: UI_MIGRATION_NOTES.length },
+            data: { version: 1, namespaces, uiMigrationNotes: notes },
+            counts: { namespaces: Object.keys(namespaces).length, notes: notes.length },
             warnings,
         };
     }

package/lib/adapters/workspaces.d.ts

@@ -1,4 +1,5 @@
 import type { MsgFunc } from '../core/messages.ts';
+import './messages.ts';
 import type { WorkspacesSection } from '../schema/types.ts';
 import type { ApplyResult, ConfigAdapter, ExportOptions, ExportSection, ExportUnit, HostContext, ImportContext, PlanItem, ValidationResult } from '../core/types.ts';
 /**

package/lib/adapters/workspaces.js

@@ -7,6 +7,8 @@
 import { isDeepStrictEqual } from 'node:util';
 import { normalizePath } from '../utils/paths.js';
 import { zhMsg } from '../core/messages.js';
+// t6：注册 adapters 域追加目录（本模块只消费注入的 msg，故只引它的注册副作用）。
+import './messages.js';
 import { validateJsonSection } from './json-section.js';
 // issue #45 勾选联动第二判据：工作区 path 的 cwd 目录键（DSH 就是按它把会话显示在工作区下的）
 import { projectKeyOf } from '../core/session-meta.js';
@@ -211,14 +213,16 @@ export class WorkspacesAdapter {
             // 目标端无法写入（如路径 realpath 失败/目录不存在）→ 非致命警告（§34.17），
             // 不触发整体回滚——否则一个失效路径会拖垮已成功导入的其余配置。
             const reason = err instanceof Error ? err.message : String(err);
-            const detail = notes.length > 0 ? '（' + notes.join('；') + '）' : '';
+            const detail = notes.length > 0
+                ? ctx.msg('adapter.workspaceNotesParen', { notes: notes.join(ctx.msg('adapter.listSeparator')) })
+                : '';
             return {
                 ok: false,
                 warning: true,
                 message: ctx.msg('adapter.workspaceWriteFailed', { ref, msg: reason }) + detail,
             };
         }
-        return { ok: true, ...(notes.length > 0 ? { message: notes.join('；') } : {}) };
+        return { ok: true, ...(notes.length > 0 ? { message: notes.join(ctx.msg('adapter.listSeparator')) } : {}) };
     }
     /**
      * 全部分区收尾之后（finalizeImport）：把本次导入的工作区记录里声明的会话登记进工作区（issue #45 缺口②）。
@@ -416,7 +420,7 @@ async function registerImportedSessions(ctx, rec, units) {
     const outsideNote = outsideFailed > 0
         ? ctx.msg('adapter.workspaceSessionsOutsideBundle', { count: String(outsideFailed) })
         : '';
-    const compose = (head) => (outsideNote === '' || head === '' ? head + outsideNote : head + '；' + outsideNote);
+    const compose = (head) => (outsideNote === '' || head === '' ? head + outsideNote : head + ctx.msg('adapter.listSeparator') + outsideNote);
     if (bundledFailed > 0) {
         return {
             message: compose(ctx.msg('adapter.workspaceSessionsPending', {

package/lib/cli/actions.d.ts

@@ -121,6 +121,12 @@ export interface RescuePaths {
     locksDir: string;
     controlRoots: readonly string[];
     profile: string;
+    /**
+     * 离线导出的 manifest.exporter.version（CLI 传真实版本；缺省 = 中性占位）。
+     * 为什么不在这里再算一次版本：actions.ts 不得 import ./index.ts（会成环），
+     * 而版本号只有 CLI 侧从 package.json 读得到 —— 由 runWeb 经本结构注入。
+     */
+    exporterVersion?: string;
 }
 export interface RescueStatus {
     generatedAt: string;
@@ -173,7 +179,9 @@ export type WriteGateOutcome = {
 /**
  * 写动作的前置门（与 CLI `sessions repair --fix` 同一判据）。
  *
- * `needsDshStopped`：只有**改写会话字节**的动作才需要「DSH 已停」这一条（清理缓存不需要）。
+ * `needsDshStopped`：**改写/搬动会话字节**的动作（会话布局归位 repairSessions、字节级就地修复
+ * repairSessionLogInline）与**快照恢复**（runSnapshotRestore 会覆盖/删除 `$DSH_HOME` 下正在使用的文件）
+ * 都要「DSH 已停」这一条；磁盘清理不需要（只碰可重建缓存）。
  */
 export declare function checkWriteGates(controlRoots: readonly string[], options?: {
     needsDshStopped: boolean;

package/lib/cli/actions.js

@@ -282,7 +282,9 @@ function errorText(error) {
 /**
  * 写动作的前置门（与 CLI `sessions repair --fix` 同一判据）。
  *
- * `needsDshStopped`：只有**改写会话字节**的动作才需要「DSH 已停」这一条（清理缓存不需要）。
+ * `needsDshStopped`：**改写/搬动会话字节**的动作（会话布局归位 repairSessions、字节级就地修复
+ * repairSessionLogInline）与**快照恢复**（runSnapshotRestore 会覆盖/删除 `$DSH_HOME` 下正在使用的文件）
+ * 都要「DSH 已停」这一条；磁盘清理不需要（只碰可重建缓存）。
  */
 export async function checkWriteGates(controlRoots, options = { needsDshStopped: true }) {
     for (const report of readSafeMode(controlRoots)) {
@@ -989,7 +991,8 @@ export async function exportOfflineBackup(paths, sections) {
         }
         const checksums = buildChecksums(collection.entries);
         const manifest = buildManifest({
-            exporterVersion: 'rescue-console',
+            // 真实版本（runWeb 经 RescuePaths 注入）；拿不到时给中性占位，绝不谎报某个具体版本。
+            exporterVersion: paths.exporterVersion ?? '0.0.0-unknown',
             // 离线探测不到真实 DSH 版本：如实标注，不谎报
             dshVersion: 'cli-offline',
             platform: process.platform,

package/lib/cli/help.js

@@ -101,7 +101,7 @@ export const COMMAND_HELP = [
         title: '离线救急台（本机网页）',
         usage: 'web',
         summary: '离线救急台：只读诊断 + 逐项确认的修复',
-        usageLines: ['web [--port <n>] [--no-open] [--home <dir>] [--data-root <dir>] [--idle-timeout <min>]'],
+        usageLines: ['web [--port <n>] [--no-open] [--home <dir>] [--data-dir <dir>] [--data-root <dir>] [--profile <name>] [--idle-timeout <min>]'],
         description: [
             '启动一个只绑 127.0.0.1 的本机网页，把诊断与修复动作摆成能点的界面：',
             '实例心跳 / SAFE MODE / 残留锁 / 快照 / 备份自检 / 磁盘占用 / 会话体检 / 档案实例。',
@@ -117,7 +117,9 @@ export const COMMAND_HELP = [
                     { flag: '--no-open', desc: '启动后不打开浏览器（SSH / 无桌面场景）' },
                     { flag: '--idle-timeout <min>', desc: '空闲多少分钟自动退出（0 = 不自动退出；缺省 30）' },
                     { flag: '--home <dir>', desc: '要查看的 DSH home（缺省 $DSH_HOME，即 ~/.dsh）' },
-                    { flag: '--data-root <dir>', desc: '插件数据根 dataDir（自定义时必须显式传）' },
+                    { flag: '--data-dir <dir>', desc: '快照 / 导出目录（历史语义）：尾段是 snapshots / exports 时按它的父目录当数据根，再派生 快照/导出/锁 三个目录；否则整条按数据根处理（缺省 $DSH_HOME/dsh-config-manager）' },
+                    { flag: '--data-root <dir>', desc: '插件数据根 dataDir（自定义时必须显式传；给了就以它为准）' },
+                    { flag: '--profile <name>', desc: '救急台操作的 DSH profile（缺省 web；影响「恢复」页的目标档案）' },
                     { flag: '-h, --help', desc: '显示本页' },
                 ],
             },
@@ -141,6 +143,7 @@ export const COMMAND_HELP = [
             '快照是每次导入前自动留下的整机配置副本；本命令只读，按新→旧列出：',
             'ID / 创建时间 / 来源 ZIP / 状态 / 条目数 / 宿主文件数 / 插件数。',
             '没有任何快照时打印「无快照」并照常返回 0。',
+            '目录存在却读不出来（权限 / 路径被文件占住）时，把事实打到 stderr 并以非 0 退出 —— 读不到 ≠ 没有快照。',
         ],
         sections: [
             {
@@ -150,7 +153,13 @@ export const COMMAND_HELP = [
                     { flag: '-h, --help', desc: '显示本页' },
                 ],
             },
-            { title: '退出码', entries: [{ flag: '0', desc: '列出成功（没有快照也是 0）' }] },
+            {
+                title: '退出码',
+                entries: [
+                    { flag: '0', desc: '列出成功（目录不存在、没有快照也是 0）' },
+                    { flag: '1', desc: '快照目录存在但读不出来（≠ 没有快照；原因打到 stderr）' },
+                ],
+            },
         ],
         examples: ['dcm snapshots', 'dcm snapshots --data-dir D:/rescue/snapshots'],
     },
@@ -159,7 +168,7 @@ export const COMMAND_HELP = [
         title: '只读自检备份 ZIP',
         usage: 'verify [<file|path>]',
         summary: '只读自检备份 ZIP（无参 = 导出目录全部）',
-        usageLines: ['verify [<file|path>] [--json] [--data-dir <dir>]'],
+        usageLines: ['verify [<file|path> | --id <file|path>] [--json] [--data-dir <dir>]'],
         description: [
             '重新读取备份 ZIP，核对结构与 integrity/checksums.json 的逐条 SHA-256；全程零写入。',
             '无参数时校验导出目录下全部 *.zip；也可以给一个文件名或完整路径。',
@@ -180,6 +189,7 @@ export const COMMAND_HELP = [
                 title: '选项',
                 entries: [
                     { flag: '--json', desc: '机器可读输出（退出码仍为 0/1；出错的 JSON 也走 stdout）' },
+                    { flag: '--id <file|path>', desc: '待校验目标（文件名或路径）；与位置参数同义，同时给出时以 --id 为准' },
                     { flag: '--data-dir <dir>', desc: '导出目录（缺省 $DSH_HOME/dsh-config-manager/exports）' },
                     { flag: '-h, --help', desc: '显示本页' },
                 ],
@@ -276,8 +286,9 @@ export const COMMAND_HELP = [
         description: [
             '把配置恢复到该快照的状态：每个被覆盖或被删除的文件先拷到 <快照目录>/pre-restore/，以便反悔。',
             '不带 --id 时挑最近一个非 rolled-back 的快照；--dry-run 只打印计划，零写入。',
-            '真正执行前有两道门，任一不过就拒绝（没有 --force）：',
-            '  ① SAFE MODE 存在未恢复的 transaction；② 环境锁被别的任务持有。',
+            '真正执行前有三道门，任一不过就拒绝（没有 --force）：',
+            '  ① SAFE MODE 存在未恢复的 transaction；② 环境锁被别的任务持有；',
+            '  ③ 本机有 DSH 实例在跑（恢复会覆盖/删除它正在使用的文件）——关掉 DSH，或改用 dcm web 救急台。',
         ],
         sections: [
             {
@@ -296,7 +307,7 @@ export const COMMAND_HELP = [
                 title: '退出码',
                 entries: [
                     { flag: '0', desc: '全部动作成功（--dry-run 恒 0）' },
-                    { flag: '1', desc: '有失败步骤 / 没有可用快照 / id 非法 / SAFE MODE 或环境锁拒绝' },
+                    { flag: '1', desc: '有失败步骤 / 没有可用快照 / 快照目录读不出来 / id 非法 / SAFE MODE、环境锁或「DSH 在跑」拒绝' },
                 ],
             },
         ],
@@ -320,6 +331,8 @@ export const COMMAND_HELP = [
             '--map old=new 用于跨机恢复：命中前缀会先改写首帧 cwd，其余帧逐字节保留。',
             '--keep <dir> 处理重复 id：点名保留哪一份，其余移进 sessions/.cm-repair-quarantine-<时间戳>/（只搬不删）。',
             '写盘前会检查 DSH 是否在跑；在跑则拒绝，避免边读边改。',
+            '--json 的 ok 与退出码同源：0（无阻断级问题）时为 true，否则 false —— 两者不会互相矛盾。',
+            '会话根不存在或存在却读不出来时，repair 都如实报错并非 0 退出（读不到 ≠ 没有会话）。',
         ],
         sections: [
             {
@@ -344,9 +357,9 @@ export const COMMAND_HELP = [
             {
                 title: '退出码',
                 entries: [
-                    { flag: '0', desc: '无阻断问题；repair 的 dry-run 恒 0' },
-                    { flag: '1', desc: '有阻断问题；repair 的 --fix 有失败/冲突/回滚；参数错误' },
-                    { flag: '2', desc: 'list / doctor 找不到会话根目录' },
+                    { flag: '0', desc: '无阻断问题；repair 的 dry-run 恒 0（--json 的 ok 同时为 true）' },
+                    { flag: '1', desc: '有阻断问题（--json 的 ok 为 false）；repair 的 --fix 有失败/冲突/回滚；repair 的会话根不存在或读不出来；参数错误' },
+                    { flag: '2', desc: 'list / doctor 找不到会话根目录（repair 的同一情形是 1）' },
                 ],
             },
         ],

package/lib/cli/index.d.ts

@@ -137,5 +137,28 @@ export interface CliDeps {
  * reinstall → 交互多选 + 二次确认 + 跨平台执行。失败项存在时 exit 1，否则 0。
  */
 export declare function runCli(argv: readonly string[], io?: CliIo, env?: Record<string, string | undefined>, deps?: CliDeps): Promise<number>;
+/** 救急台的目录事实（由 --data-dir / --data-root 统一派生；四处只认这一份）。 */
+export interface WebPaths {
+    /** 插件数据根（快照/导出/锁都挂在它下面） */
+    root: string;
+    /** 与 root 同值（RescuePaths.dataDir 的语义） */
+    dataDir: string;
+    snapshotsDir: string;
+    exportsDir: string;
+    locksDir: string;
+    controlRoots: string[];
+}
+/**
+ * 派生救急台要用的四个目录 —— **root 只算一次**，再同时派生 snapshots / exports / locks / dataDir。
+ *
+ * 为什么必须统一：`--data-dir` 的历史语义是「快照目录 / 导出目录」，尾段命中 `snapshots`/`exports`
+ * 时要**上溯一层**才是数据根。此前只对「那一条」取原值、另一条仍 `path.join(dataDir, ...)`，
+ * 于是 `--data-dir <root>/snapshots` 会派生出 `<root>/snapshots/exports`（半上溯）——
+ * 命令行与网页看到的目录事实立刻分叉。`--data-root` 恒为准。
+ */
+export declare function resolveWebPaths(opts?: {
+    dataRoot?: string;
+    dataDir?: string;
+}, env?: Record<string, string | undefined>): WebPaths;
 /** 导出目录：--data-dir 覆盖优先，缺省 $DSH_HOME/dsh-config-manager/exports */
 export declare function resolveExportsDir(flag: string | undefined, env?: Record<string, string | undefined>): string;