dsh-config-manager 0.1.71 → 0.1.72

package/lib/core/command-rollback.d.ts

@@ -0,0 +1,178 @@
+/**
+ * 宿主斜杠命令 /rollback（别名 /rw）—— 不打开设置面板也能回退（对齐 dsh-rewind 的 /rewind、/undo）。
+ *
+ * 语义（用户 2026-10-12 确认方案 A）：
+ *   /rollback            → 当前**会话**的可回退点列表（回合号 / 时间 / 类型 / 状态 / 可回退性）
+ *   /rollback <id>       → 回退到该点，走**与 HTTP 路由同源**的那道写入门：
+ *                          runWithMutationLock（= SAFE MODE 门 + 跨进程/跨 kind 环境锁）
+ *                          → 引擎 preview（零写入）→ 引擎 rewind（userConfirmed=true）
+ *   引擎回的 confirmation-required / protected-point / record-incomplete 一律翻成可读错误结果，
+ *   **绝不绕过**（命令入口没有「确认按钮」，用户敲下 id 就是那次确认；其余门照旧全量生效）。
+ *
+ * 纪律（与 src/core/model-tools.ts 的 registerModelTools 同口径）：
+ *  · 命令服务**惰取**：一律 ctx.get('commands') 调用期读取，绝不属性访问 ctx.commands、
+ *    绝不放进 inject —— 未组合该服务的部署必须照常启动（命令是可选能力，不是硬依赖）；
+ *  · 注册失败只 warn：命令挂不上不得影响其它装配（宿主启动 = blocker）；
+ *  · 用户可见文案一律走宿主字典 engineMsg（key: command.rollback.*），**取文案那一刻**解析语言；
+ *  · 本模块不 import @deepseek-ai/dsh-commands 的运行时值（只做结构化窄化），core 保持与 DSH 解耦。
+ */
+import type { MutationLockPort } from '../utils/env-lock.ts';
+import type { RollbackPointSummary, RollbackRewindResult } from './rollback-point.ts';
+/**
+ * 命令结果（与 @deepseek-ai/dsh-commands 的 `CommandResult` **逐字同形**）。
+ *
+ * 为什么在这里自己声明而不是 import 那门包的类型：`src/core/**` 的架构边界（tests/architecture-boundaries.test.ts
+ * 的 core allow 表）只允许 node 内置 / core 内部 / schema / utils / security / migrations / js-yaml ——
+ * `@deepseek-ai/*` 仅允许出现在 `src/index.ts` 与 `src/client/`。core 必须保持与 DSH 解耦，
+ * 所以这里做**结构化窄化**；两边一旦漂移，`command-rollback.test.ts` 的编译期断言会红。
+ */
+export type CommandResult = {
+    readonly kind: 'success';
+    readonly text?: string;
+    readonly sourceEventSeq?: number;
+} | {
+    readonly kind: 'error';
+    readonly text: string;
+};
+/** 命令名（无前导斜杠）与别名。 */
+export declare const ROLLBACK_COMMAND_NAME = "rollback";
+export declare const ROLLBACK_COMMAND_ALIAS = "rw";
+/**
+ * 命令定义 id：/rw 别名是**第二条定义** —— 同一个 definitionId（客户端按 definitionId 做身份化行为，
+ * 别名与主名必须被视作同一条命令）。
+ */
+export declare const ROLLBACK_COMMAND_DEFINITION_ID = "dsh-config-manager/rollback";
+/** 命令服务惰取回调（调用期读 ctx.get('commands')；未组合返回 undefined）。 */
+export type CommandServiceReader = () => CommandServiceLike | undefined | null;
+/** 一条已注册命令的最小形状（避免把 DSH 类型变成本插件的硬依赖）。 */
+export interface CommandDefinitionLike {
+    readonly name: string;
+    readonly description: string;
+    readonly definitionId?: string;
+    readonly input?: {
+        readonly hint: string;
+        readonly attachments?: boolean;
+    };
+    readonly handler: (invocation: CommandInvocationLike) => CommandResult | Promise<CommandResult>;
+}
+/** 一次命令调用的最小形状（只读用到的字段）。 */
+export interface CommandInvocationLike {
+    readonly agent: unknown;
+    /** 命令名之后的原文（含分隔空白）。 */
+    readonly rawInput: string;
+    /** 派发 UI 持有的取消信号（透传给回退执行）。 */
+    readonly signal?: AbortSignal;
+}
+/** 命令服务的最小形状（ctx.get('commands') 的结构化窄化）。 */
+export interface CommandServiceLike {
+    register(definition: CommandDefinitionLike): unknown;
+}
+/** 宿主提供的回退能力（由 src/index.ts 装配；测试用假的实现即可）。 */
+export interface RollbackCommandHost {
+    /** 当前 agent 所属会话（拿不准则 ok:false —— 绝不猜）。 */
+    agentSession(agent: unknown): AgentSessionFacts;
+    /** 列出该会话的回退点（含存储栈状态；只读）。 */
+    list(sessionId: string): Promise<RollbackCommandListResult>;
+    /**
+     * 执行回退：runWithMutationLock → SAFE MODE → 引擎 preview → 引擎 rewind。
+     *
+     * 被 SAFE MODE / 环境锁挡住时**抛 EnvironmentLockUnavailableError**（与 HTTP 路由同口径），
+     * 由本模块翻成可读错误结果。
+     */
+    rewind(input: RollbackRewindExecution): Promise<RollbackRewindResult>;
+}
+/**
+ * 回退执行入参。
+ *
+ * 只带 id + 取消信号：引擎 `rewind({ id, userConfirmed: true })` 的**写入面**已经由该点的记录
+ * 决定（不是调用方临时指定路径），多传会话/分块只会制造「两处口径」；会话事实只供只读列表过滤用。
+ */
+export interface RollbackRewindExecution {
+    readonly id: string;
+    readonly signal?: AbortSignal;
+}
+/** 列表结果（引擎 RollbackListResult 的可测子集）。 */
+export interface RollbackCommandListResult {
+    ok: boolean;
+    storage: {
+        available: boolean;
+        root: string;
+        detail?: string;
+    };
+    points: readonly RollbackPointSummary[];
+    error?: string;
+}
+/** 当前 agent 的会话事实（宽进严出：形状不符即 ok:false）。 */
+export type AgentSessionFacts = {
+    ok: true;
+    sessionId: string;
+    chunks: readonly string[];
+} | {
+    ok: false;
+    detail: string;
+};
+/** 绝对路径判定（win32 盘符 + POSIX 前缀 + UNC；纯函数，不引 node:path）。 */
+export declare function isAbsolutePath(value: string): boolean;
+/**
+ * 从 agent 窄化会话事实。
+ *
+ * **不猜**：agent.session.id 读不出来就退回 agent.id（DSH 的 Agent.id 就是会话 id）；
+ * 两者都读不出 → ok:false（命令如实报「拿不到当前会话」，而不是列全网的点）。
+ * 工作区分块只认**绝对路径**的 cwd（与 rollbackSessionBindingOf 同一口径）。
+ */
+export declare function agentSessionFactsOf(agent: unknown): AgentSessionFacts;
+/** 解析结果：空输入 = 只读列表；单个 token = 目标点 id；其余 = invalid。 */
+export type RollbackCommandInput = {
+    kind: 'list';
+} | {
+    kind: 'rewind';
+    id: string;
+} | {
+    kind: 'invalid';
+    detail: string;
+};
+/**
+ * 解析 rawInput（命令名之后的原文，含分隔空白）。
+ * 语法只有两种：空 = 列表；单个非空 token = 目标 id。多 token 一律 invalid。
+ */
+export declare function parseRollbackCommand(rawInput: string): RollbackCommandInput;
+/** 渲染只读列表（本会话没有点时给「本会话没有」，绝不冒充「全库为空」）。 */
+export declare function renderRollbackList(result: RollbackCommandListResult, sessionId: string): CommandResult;
+/** 把引擎结果翻成命令结果（失败一律带机器码 + 技术细节；processed 的段事实不隐藏）。 */
+export declare function renderRewindResult(result: RollbackRewindResult, id: string): CommandResult;
+/** 命令依赖（index.ts 装配；测试直接构造）。 */
+export interface RollbackCommandDeps {
+    readonly host: RollbackCommandHost;
+    /** mutation lock 端口（index.ts 传 host.mutationLock；测试可传 undefined 或假端口）。 */
+    readonly mutationLock?: MutationLockPort;
+    /** SAFE MODE 同步谓词（与 HTTP 路由同一份 host.safeModeIsBlocked）。 */
+    readonly isBlocked?: () => boolean;
+}
+/**
+ * 构造命令处理器（**纯编排**：不注册、不读 ctx）。
+ *
+ * 带参数时：parser → agentSession（只用于「这次是不是列表」的会话判定）→ host.rewind。
+ * host.rewind 内部才是那道门：runWithMutationLock → SAFE MODE → 引擎 preview → 引擎 rewind
+ * EnvironmentLockUnavailableError（SAFE MODE / 环境锁被挡）在此翻成可读错误结果。
+ * 任何未预期异常也翻成错误结果 —— 命令处理器抛异常会让整条命令生命周期报泛化失败，
+ * UI 只看到一句「失败」；这里如实把原因说清楚。
+ */
+export declare function makeRollbackCommandHandler(deps: RollbackCommandDeps): (invocation: CommandInvocationLike) => Promise<CommandResult>;
+/** 注册所需的依赖面（命令服务惰取回调 + 宿主日志 + 命令依赖）。 */
+export interface RollbackCommandRegistrationOptions {
+    /** 惰取命令服务：实现必须是「调用期」的 ctx.get('commands')（绝不属性访问、绝不进 inject）。 */
+    readonly readCommands: CommandServiceReader;
+    readonly deps: RollbackCommandDeps;
+    /** 只 warn：注册失败/服务缺失不得影响其它装配。 */
+    readonly log?: {
+        warn(message: string, meta?: unknown): void;
+    };
+}
+/**
+ * 注册 /rollback 与 /rw（两条定义 = 同一 definitionId）。
+ *
+ * 服务缺失 → warn 后**安静返回**（未组合 commands 的部署照常启动、不抛错）；
+ * 服务存在但 register 抛错 → warn（其余装配不受影响）。
+ * @returns 反注册函数（重复调用安全）。
+ */
+export declare function registerRollbackCommand(options: RollbackCommandRegistrationOptions): () => void;

package/lib/core/command-rollback.js

@@ -0,0 +1,289 @@
+/**
+ * 宿主斜杠命令 /rollback（别名 /rw）—— 不打开设置面板也能回退（对齐 dsh-rewind 的 /rewind、/undo）。
+ *
+ * 语义（用户 2026-10-12 确认方案 A）：
+ *   /rollback            → 当前**会话**的可回退点列表（回合号 / 时间 / 类型 / 状态 / 可回退性）
+ *   /rollback <id>       → 回退到该点，走**与 HTTP 路由同源**的那道写入门：
+ *                          runWithMutationLock（= SAFE MODE 门 + 跨进程/跨 kind 环境锁）
+ *                          → 引擎 preview（零写入）→ 引擎 rewind（userConfirmed=true）
+ *   引擎回的 confirmation-required / protected-point / record-incomplete 一律翻成可读错误结果，
+ *   **绝不绕过**（命令入口没有「确认按钮」，用户敲下 id 就是那次确认；其余门照旧全量生效）。
+ *
+ * 纪律（与 src/core/model-tools.ts 的 registerModelTools 同口径）：
+ *  · 命令服务**惰取**：一律 ctx.get('commands') 调用期读取，绝不属性访问 ctx.commands、
+ *    绝不放进 inject —— 未组合该服务的部署必须照常启动（命令是可选能力，不是硬依赖）；
+ *  · 注册失败只 warn：命令挂不上不得影响其它装配（宿主启动 = blocker）；
+ *  · 用户可见文案一律走宿主字典 engineMsg（key: command.rollback.*），**取文案那一刻**解析语言；
+ *  · 本模块不 import @deepseek-ai/dsh-commands 的运行时值（只做结构化窄化），core 保持与 DSH 解耦。
+ */
+import { engineMsg } from './engine-locale.js';
+import { EnvironmentLockUnavailableError } from '../utils/env-lock.js';
+/** 命令名（无前导斜杠）与别名。 */
+export const ROLLBACK_COMMAND_NAME = 'rollback';
+export const ROLLBACK_COMMAND_ALIAS = 'rw';
+/**
+ * 命令定义 id：/rw 别名是**第二条定义** —— 同一个 definitionId（客户端按 definitionId 做身份化行为，
+ * 别名与主名必须被视作同一条命令）。
+ */
+export const ROLLBACK_COMMAND_DEFINITION_ID = 'dsh-config-manager/rollback';
+/** 绝对路径判定（win32 盘符 + POSIX 前缀 + UNC；纯函数，不引 node:path）。 */
+export function isAbsolutePath(value) {
+    if (value.startsWith('/') || value.startsWith('\\'))
+        return true;
+    return /^[A-Za-z]:[\\/]/.test(value);
+}
+/**
+ * 从 agent 窄化会话事实。
+ *
+ * **不猜**：agent.session.id 读不出来就退回 agent.id（DSH 的 Agent.id 就是会话 id）；
+ * 两者都读不出 → ok:false（命令如实报「拿不到当前会话」，而不是列全网的点）。
+ * 工作区分块只认**绝对路径**的 cwd（与 rollbackSessionBindingOf 同一口径）。
+ */
+export function agentSessionFactsOf(agent) {
+    if (agent === null || typeof agent !== 'object')
+        return { ok: false, detail: 'agent-not-object' };
+    const rec = agent;
+    let sessionId;
+    let cwd;
+    const session = rec.session;
+    if (session !== null && typeof session === 'object') {
+        const s = session;
+        if (typeof s.id === 'string' && s.id !== '')
+            sessionId = s.id;
+        const header = s.header;
+        if (header !== null && typeof header === 'object') {
+            const value = header.cwd;
+            if (typeof value === 'string' && value !== '')
+                cwd = value;
+        }
+    }
+    if (sessionId === undefined && typeof rec.id === 'string' && rec.id !== '')
+        sessionId = rec.id;
+    if (sessionId === undefined)
+        return { ok: false, detail: 'session-id-missing' };
+    const chunks = cwd !== undefined && isAbsolutePath(cwd) ? [cwd] : [];
+    return { ok: true, sessionId, chunks };
+}
+/**
+ * 解析 rawInput（命令名之后的原文，含分隔空白）。
+ * 语法只有两种：空 = 列表；单个非空 token = 目标 id。多 token 一律 invalid。
+ */
+export function parseRollbackCommand(rawInput) {
+    const trimmed = (rawInput ?? '').trim();
+    if (trimmed === '')
+        return { kind: 'list' };
+    const parts = trimmed.split(/\s+/);
+    if (parts.length !== 1)
+        return { kind: 'invalid', detail: 'too-many-arguments' };
+    return { kind: 'rewind', id: parts[0] ?? '' };
+}
+/* ------------------------------------------------------------------ 渲染 */
+function isoOf(createdAt) {
+    if (!Number.isFinite(createdAt))
+        return '?';
+    try {
+        return new Date(createdAt).toISOString();
+    }
+    catch {
+        return '?';
+    }
+}
+/** 点状态：受保护 / 捕获不完整 / 正常（三者互斥，按引擎字段的优先级分派）。 */
+function stateLabel(point) {
+    if (point.protected)
+        return engineMsg('command.rollback.stateProtected');
+    if (point.incomplete)
+        return engineMsg('command.rollback.stateIncomplete');
+    return engineMsg('command.rollback.stateNormal');
+}
+/** 该点两态各自的「可回退 / 不可回退」摘要（诚实：按段逐项说，再给总判）。 */
+function restorableLabel(point) {
+    const segments = point.segments ?? [];
+    const parts = [];
+    for (const segment of segments) {
+        const label = segment.restorable ? engineMsg('command.rollback.restorableYes') : engineMsg('command.rollback.restorableNo');
+        parts.push(engineMsg('command.rollback.segmentLabel', {
+            state: engineMsg(segment.state === 'workspace' ? 'command.rollback.segmentWorkspace' : 'command.rollback.segmentSession'),
+            label,
+        }));
+    }
+    if (parts.length === 0)
+        return engineMsg('command.rollback.restorableNo');
+    const any = segments.some((segment) => segment.restorable);
+    return engineMsg('command.rollback.restorableSummary', {
+        parts: parts.join(engineMsg('command.rollback.listSeparator')),
+        verdict: any ? engineMsg('command.rollback.restorableYes') : engineMsg('command.rollback.restorableNo'),
+    });
+}
+function turnLabel(point) {
+    return point.turn === null ? engineMsg('command.rollback.turnUnknown') : String(point.turn);
+}
+function kindLabel(point) {
+    return engineMsg(point.kind === 'guard' ? 'command.rollback.kindGuard' : 'command.rollback.kindAuto');
+}
+/** 渲染只读列表（本会话没有点时给「本会话没有」，绝不冒充「全库为空」）。 */
+export function renderRollbackList(result, sessionId) {
+    if (!result.storage.available) {
+        return {
+            kind: 'error',
+            text: engineMsg('command.rollback.storageUnavailable', { detail: result.storage.detail ?? result.storage.root }),
+        };
+    }
+    if (result.error !== undefined && result.error !== '') {
+        return { kind: 'error', text: engineMsg('command.rollback.listFailed', { detail: result.error }) };
+    }
+    const points = (result.points ?? []).filter((point) => point.sessionId === sessionId);
+    if (points.length === 0)
+        return { kind: 'error', text: engineMsg('command.rollback.empty') };
+    const lines = points.map((point, index) => engineMsg('command.rollback.listRow', {
+        index: String(index + 1),
+        id: point.id,
+        turn: turnLabel(point),
+        createdAt: isoOf(point.createdAt),
+        kind: kindLabel(point),
+        state: stateLabel(point),
+        restorable: restorableLabel(point),
+    }));
+    return { kind: 'success', text: [engineMsg('command.rollback.listTitle'), ...lines].join('\n') };
+}
+/** 段结果的一行技术事实（定位失败用；**不是**文案分派的语义依据）。 */
+function segmentFacts(segments) {
+    if (segments === undefined || segments.length === 0)
+        return '';
+    return segments
+        .map((segment) => segment.state + '/' + segment.status + (segment.reasonCode !== undefined ? '(' + segment.reasonCode + ')' : ''))
+        .join(',');
+}
+/** 把引擎结果翻成命令结果（失败一律带机器码 + 技术细节；processed 的段事实不隐藏）。 */
+export function renderRewindResult(result, id) {
+    const detail = result.detail ?? '';
+    if (result.ok && result.outcome === 'restored') {
+        return { kind: 'success', text: engineMsg('command.rollback.rewindRestored', { id, detail }) };
+    }
+    if (result.outcome === 'partial') {
+        // 「部分恢复」既不是成功也不是泛化失败：逐段事实必须上屏（含被跳过的段）。
+        return {
+            kind: 'error',
+            text: engineMsg('command.rollback.rewindPartial', {
+                id,
+                segments: engineMsg('command.rollback.segmentFacts', { facts: segmentFacts(result.segments) }),
+                detail,
+            }),
+        };
+    }
+    return {
+        kind: 'error',
+        text: engineMsg('command.rollback.rewindFailed', { id, code: String(result.code), detail }),
+    };
+}
+/**
+ * 构造命令处理器（**纯编排**：不注册、不读 ctx）。
+ *
+ * 带参数时：parser → agentSession（只用于「这次是不是列表」的会话判定）→ host.rewind。
+ * host.rewind 内部才是那道门：runWithMutationLock → SAFE MODE → 引擎 preview → 引擎 rewind
+ * EnvironmentLockUnavailableError（SAFE MODE / 环境锁被挡）在此翻成可读错误结果。
+ * 任何未预期异常也翻成错误结果 —— 命令处理器抛异常会让整条命令生命周期报泛化失败，
+ * UI 只看到一句「失败」；这里如实把原因说清楚。
+ */
+export function makeRollbackCommandHandler(deps) {
+    return async (invocation) => {
+        const parsed = parseRollbackCommand(invocation.rawInput);
+        if (parsed.kind === 'invalid') {
+            return { kind: 'error', text: engineMsg('command.rollback.usageInvalid', { detail: parsed.detail }) };
+        }
+        const facts = deps.host.agentSession(invocation.agent);
+        if (!facts.ok) {
+            return { kind: 'error', text: engineMsg('command.rollback.sessionUnavailable', { detail: facts.detail }) };
+        }
+        if (parsed.kind === 'list') {
+            try {
+                return renderRollbackList(await deps.host.list(facts.sessionId), facts.sessionId);
+            }
+            catch (error) {
+                return { kind: 'error', text: engineMsg('command.rollback.listFailed', { detail: errorText(error) }) };
+            }
+        }
+        try {
+            const execution = {
+                id: parsed.id,
+                ...(invocation.signal !== undefined ? { signal: invocation.signal } : {}),
+            };
+            return renderRewindResult(await deps.host.rewind(execution), parsed.id);
+        }
+        catch (error) {
+            if (error instanceof EnvironmentLockUnavailableError) {
+                return {
+                    kind: 'error',
+                    text: engineMsg('command.rollback.mutationLocked', { reason: error.reason, id: parsed.id }),
+                };
+            }
+            return {
+                kind: 'error',
+                text: engineMsg('command.rollback.rewindFailed', { id: parsed.id, code: 'exception', detail: errorText(error) }),
+            };
+        }
+    };
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * 注册 /rollback 与 /rw（两条定义 = 同一 definitionId）。
+ *
+ * 服务缺失 → warn 后**安静返回**（未组合 commands 的部署照常启动、不抛错）；
+ * 服务存在但 register 抛错 → warn（其余装配不受影响）。
+ * @returns 反注册函数（重复调用安全）。
+ */
+export function registerRollbackCommand(options) {
+    const disposers = [];
+    let service;
+    try {
+        service = options.readCommands() ?? undefined;
+    }
+    catch (error) {
+        options.log?.warn(engineMsg('command.rollback.serviceUnavailable', { detail: errorText(error) }));
+        return () => { };
+    }
+    if (service === undefined || typeof service.register !== 'function') {
+        options.log?.warn(engineMsg('command.rollback.serviceUnavailable', { detail: 'commands-service-missing' }));
+        return () => { };
+    }
+    const handler = makeRollbackCommandHandler(options.deps);
+    const definitions = [
+        {
+            name: ROLLBACK_COMMAND_NAME,
+            definitionId: ROLLBACK_COMMAND_DEFINITION_ID,
+            description: engineMsg('command.rollback.commandDesc'),
+            input: { hint: engineMsg('command.rollback.commandInputHint') },
+            handler,
+        },
+        {
+            name: ROLLBACK_COMMAND_ALIAS,
+            definitionId: ROLLBACK_COMMAND_DEFINITION_ID,
+            description: engineMsg('command.rollback.commandDescAlias'),
+            input: { hint: engineMsg('command.rollback.commandInputHint') },
+            handler,
+        },
+    ];
+    for (const definition of definitions) {
+        try {
+            const disposer = service.register(definition);
+            if (typeof disposer === 'function')
+                disposers.push(disposer);
+        }
+        catch (error) {
+            options.log?.warn(engineMsg('command.rollback.registerFailed', { name: definition.name, detail: errorText(error) }));
+        }
+    }
+    return () => {
+        for (const dispose of disposers.splice(0)) {
+            try {
+                dispose();
+            }
+            catch (error) {
+                options.log?.warn(engineMsg('command.rollback.registerFailed', { name: 'dispose', detail: errorText(error) }));
+            }
+        }
+    };
+}
+//# sourceMappingURL=command-rollback.js.map

package/lib/core/consult-source.js

@@ -17,6 +17,7 @@ import { MANIFEST_FILE, CHECKSUMS_FILE, parseManifest, validateManifest } from '
 import { verifyChecksumsJson } from '../security/integrity.js';
 import { SECTION_JSON_PATHS, SECTION_FILE_PREFIXES, isFileSection } from '../schema/config.js';
 import { scanAndRedact, scanText } from '../security/secret-scanner.js';
+import { engineMsg } from './messages-core.js';
 /** 从导出 ZIP 读取并归一化源数据（只读） */
 export async function readExportZipSource(ref, zipPath, opts = {}) {
     const highEntropy = opts.highEntropy ?? true;
@@ -62,12 +63,12 @@ export async function readExportZipSource(ref, zipPath, opts = {}) {
                 manifestIssues = validateManifest(parsed);
             }
             catch {
-                manifestIssues = [{ path: '$', message: 'manifest 无法解析', severity: 'error' }];
+                manifestIssues = [{ path: '$', message: engineMsg('core.consult.manifestUnparsable'), severity: 'error' }];
             }
         }
     }
     else {
-        manifestIssues = [{ path: '$', message: 'manifest 缺失', severity: 'error' }];
+        manifestIssues = [{ path: '$', message: engineMsg('core.consult.manifestMissing'), severity: 'error' }];
     }
     // 3. checksums（捕获不匹配，不抛错）
     const checksumIssues = [];
@@ -86,9 +87,9 @@ export async function readExportZipSource(ref, zipPath, opts = {}) {
             const result = verifyChecksumsJson(entries, archive.readEntryText(CHECKSUMS_FILE));
             checksums = result.ok ? {} : null;
             for (const m of result.mismatches)
-                checksumIssues.push(`"${m}" (hash 不符)`);
+                checksumIssues.push(engineMsg('core.consult.hashMismatch', { name: m }));
             for (const m of result.missing)
-                checksumIssues.push(`"${m}" (缺失)`);
+                checksumIssues.push(engineMsg('core.consult.entryMissing', { name: m }));
         }
         catch (err) {
             checksumIssues.push(err instanceof Error ? err.message : String(err));
@@ -184,8 +185,8 @@ export function buildLocalSnapshotSource(ref, input) {
         sections: sectionFlags,
         security: { containsSecrets: false, encrypted: false, encryption: null },
     };
-    const manifestIssues = input.verify.ok ? [] : [{ path: '$', message: input.verify.reason ?? '快照完整性校验失败', severity: 'error' }];
-    const checksumIssues = input.verify.ok ? [] : [input.verify.reason ?? '快照完整性校验失败'];
+    const manifestIssues = input.verify.ok ? [] : [{ path: '$', message: input.verify.reason ?? engineMsg('core.consult.snapshotIntegrityFailed'), severity: 'error' }];
+    const checksumIssues = input.verify.ok ? [] : [input.verify.reason ?? engineMsg('core.consult.snapshotIntegrityFailed')];
     const migratability = {
         ok: input.restorePlan.errors.length === 0,
         itemCount: input.restorePlan.itemCount,

package/lib/core/disk-usage.d.ts

@@ -1,7 +1,20 @@
-/** 体检子区（顺序即界面展示顺序：先备份产物，再缓存/暂存） */
-export declare const DISK_USAGE_AREAS: readonly ['exports', 'snapshots', 'sync', 'marketCache', 'marketWork', 'tmp', 'logs', 'bootState', 'migrationHistory', 'transactions', 'locks', 'vault'];
-/** 体检子区 id */
-export type DiskUsageArea = typeof DISK_USAGE_AREAS[number];
+/**
+ * 只报告、**不提供清理**的子区（当前一条：回滚点库 = `dataDir/rollback-points`）。
+ * 它只是「口径清单」：报告/展示一律用完备的 `DISK_USAGE_AREAS`，清理候选另有白名单
+ * （`IMMEDIATE_CLEAN_CATEGORIES` / 清理入口 categories），两者不得混用。
+ */
+export declare const DISK_USAGE_EXTRA_AREAS: readonly ['rollback-points'];
+/** 体检子区（顺序即报告/展示顺序：先备份产物，再缓存/暂存，末位为只读保护的附加区） */
+export declare const DISK_USAGE_AREAS: readonly ["exports", "snapshots", "sync", "marketCache", "marketWork", "tmp", "logs", "bootState", "migrationHistory", "transactions", "locks", "vault", "rollback-points"];
+/** 全部体检子区 id（= `DISK_USAGE_AREAS` 的元素类型） */
+export type DiskUsageScanArea = typeof DISK_USAGE_AREAS[number];
+/**
+ * 体检子区 id（**与 `DiskUsageScanArea` 同一集合**，13 键完备）。
+ *
+ * 2026-10-13 收口：文案登记（t6）落地后不再分叉 —— 按本类型写 `Record<DiskUsageArea, …>`
+ * 时漏掉任一子区（含 rollback-points）都会在编译期报错，而不是静默缺项。
+ */
+export type DiskUsageArea = DiskUsageScanArea;
 /** 子区回收策略语义（决定界面文案，不由界面自行判断） */
 export type DiskUsagePolicy = 
 /** 可随时重建/可重新下载：现在就能整块清掉（tmp、market/cache、market/work） */
@@ -27,20 +40,69 @@ export interface DiskUsageAreaReport {
     /** 已超过保留期的条目数（仅 retained） */
     expiredCount?: number;
 }
+/**
+ * 已知的**遗留数据**目录（插件已不再读取、也绝不自动清理）。
+ *
+ * 为什么单列而不并进 `DISK_USAGE_AREAS`：它们不是「本插件的现役数据区」——不再被任何代码
+ * 读取、也不参与清理；报告只用**相对 dataDir 的路径**把它们指认清楚，
+ * 且结构必须能容纳未来更多条（数组，不是单条 object）。
+ */
+export interface LegacyDataDir {
+    /** 稳定 id（界面/接口引用） */
+    id: string;
+    /** 相对 dataDir 的 POSIX 风格相对路径（如 `checkpoints`） */
+    relPath: string;
+}
+/**
+ * 遗留数据目录清单（当前一条：旧检查点库）。
+ *
+ * `checkpoints/` 是回滚点库改名（`rollback-points/`）之前的旧目录：新代码**不再读取**它，
+ * 本插件也**不去删**它（删除是不可逆动作，需用户单独授权）。
+ */
+export declare const LEGACY_DATA_DIRS: readonly LegacyDataDir[];
+/** 单条遗留数据的体检结果（只报告；`policy` 恒为 protected） */
+export interface DiskUsageLegacyEntry {
+    /** 稳定 id（与 `LEGACY_DATA_DIRS` 逐条对应） */
+    id: string;
+    /** 相对 dataDir 的路径（如 `checkpoints`） */
+    relPath: string;
+    /** 绝对路径（界面「在哪儿」展示） */
+    path: string;
+    /** 字节数（不存在/不可读 → 0，必须与 unreadable 一起看） */
+    sizeBytes: number;
+    /** 文件数（不存在/不可读 → 0） */
+    fileCount: number;
+    /** 读不到/不存在/被非目录占住 → true（界面必须显示「未统计」，绝不伪报 0 字节） */
+    unreadable: boolean;
+    /** 恒为 `protected`：只报告，绝不提供自动清理 */
+    policy: 'protected';
+}
+/** 子区明细记录：`DISK_USAGE_AREAS` 的**每个**子区（含回滚点库等附加子区）逐键必填 ——
+ *  报告运行时恒为完整结构，索引访问不可能拿到 undefined（`noUncheckedIndexedAccess` 下也成立，
+ *  故只读消费者如离线救急台可直接 `report.areas[area]`，不需要缺失回退）。 */
+export type DiskUsageAreasReport = Record<DiskUsageScanArea, DiskUsageAreaReport>;
 /** 体检报告（路径字段供界面「在哪儿」展示；均为本机绝对路径，无敏感内容） */
 export interface DiskUsageReport {
     /** dataDir（`$DSH_HOME/dsh-config-manager`） */
     dataDir: string;
-    /** 全部子区合计字节数 */
+    /** 全部**子区**合计字节数（含回滚点库等附加子区；**不含**遗留数据 —— 见 legacy） */
     totalBytes: number;
-    /** 全部子区合计文件数 */
+    /** 全部子区合计文件数（口径同 totalBytes） */
     totalFiles: number;
     /** 可立即清理（regenerable）子区合计字节数 */
     reclaimableBytes: number;
     /** 到达自动回收期的字节数（retained 子区） */
     expiredBytes: number;
-    /** 各子区明细 */
-    areas: Record<DiskUsageArea, DiskUsageAreaReport>;
+    /** 各子区明细（恒含 `DISK_USAGE_AREAS` 的全部子区，逐键必填） */
+    areas: DiskUsageAreasReport;
+    /**
+     * 遗留数据明细（插件**已不再读取**、也**不代删**；只报告）。
+     * 结构可容纳多条（见 `LEGACY_DATA_DIRS`）；**不计入 totalBytes**（子区合计与遗留数据
+     * 分开列，界面才不会把「能解释来源的占用」和「遗留占用」混成一个数）。
+     * 类型上可选只是为了让既有报告字面量（测试/旧调用方）继续成立 —— 宿主
+     * `GET /disk-usage` 恒回传本字段（无遗留目录时为空数组）。
+     */
+    legacy?: readonly DiskUsageLegacyEntry[];
     /** 定时备份产物的保留口径（「保留最近 N 个」；界面用它解释为什么有的备份不会自动回收） */
     backupRetention: {
         keepLast: number;
@@ -72,8 +134,10 @@ export declare const IMMEDIATE_CLEAN_CATEGORIES: readonly ['tmp', 'marketCache',
 export type ImmediateCleanCategory = typeof IMMEDIATE_CLEAN_CATEGORIES[number];
 /** 缓存清理结果里与子区对应的键（老字段快照/临时/市场沿用原语义） */
 export type CleanupResultCategory = ImmediateCleanCategory | 'exports';
-/** 子区 → 物理目录（单一映射点；展示与统计都不再重复挑目录） */
-export declare function diskUsageDirOf(dirs: DiskUsageDirs, area: DiskUsageArea): string;
+/** 子区 → 物理目录（单一映射点；展示与统计都不再重复挑目录）。
+ *  回滚点库不在 `DiskUsageDirs` 里显式传：它的位置 = `dataDir` + `ROLLBACK_POINTS_DIR`
+ *  （与引擎常量逐字一致，有源码级守卫），宿主路由与离线 CLI 两条构造路径因此不可能漂移。 */
+export declare function diskUsageDirOf(dirs: DiskUsageDirs, area: DiskUsageScanArea): string;
 /** 子区语义与保留期（界面据此选文案；retained 子区必带 retentionMs） */
 export interface DiskUsagePolicyInput {
     /** 导出产物保留期（cache-cleaner 的 exportsRetentionMs） */