dsh-config-manager 0.1.72 → 0.1.73

package/lib/adapters/plugin-data.js

@@ -0,0 +1,309 @@
+/**
+ * pluginData / pluginAssets 分区 adapter（第三方插件数据迁移）。
+ *
+ * 数据来源 = \`src/core/plugin-data-registry.ts\` 的来源注册表：内置已取证来源 + 已安装插件在
+ * 自己 package.json 里声明的 \`dsh.dataDirs\`。每个「区域（area）」在备份里是**一个可勾选单元**，
+ * 单元 id = 区域的 home 相对 POSIX 路径（如 \`.dsh-wallpaper-engine/uploads\`）——
+ * 用户能在导出选择器里逐区域看到「几个文件 / 多大」，也能只带走配置、不带几百 MB 的上传壁纸。
+ *
+ * 为什么两个分区而不是一个：
+ *  - \`pluginData\` = 配置与轻量状态；\`pluginAssets\` = 大体积用户数据（上传的壁纸、本地数据库）；
+ *  - 「默认不勾选大资产」在既有 UI 选择模型里**只有分区级开关**这一条可靠通道（单元级只有
+ *    「默认全选 + 稀疏排除」，没有「默认排除」的概念）—— 拆成两个分区后，「可见但默认不勾选」
+ *    就是既有的 \`defaultIncluded=false\` 语义，不需要动共享选择模型，也不会与导入/市场两处选择语义打架。
+ *
+ * 实现：继承 FileCollectionAdapter（baseDir = ''，即 home 根；与 agentInstructions 同一形态），
+ * 复用它的单元分组 / 单分区字节闸门 / 预览-导出一致性 / 幂等哈希比对；只覆写三处：
+ *  ① \`listRelPaths()\` —— 清单来自来源注册表（并如实记录被环境变量覆盖而跳过的区域）；
+ *  ② \`unitIdOf()\` —— 单元 = 区域（最长前缀归属）；
+ *  ③ \`analyzeImport() / applyItem()\` —— **写入路径白名单**（见下）。
+ *
+ * 安全不变量（本分区是全仓唯一「按 home 相对路径任意写」的分区，必须自己守住）：
+ *  - **导入白名单**：只有「本机内置来源的区域」与「本机已安装插件声明的区域」之下的路径才允许写。
+ *    恶意/损坏的包想把 \`.credentials.yaml\` 或 \`AGENTS.md\` 塞进来，在这里被判 Error（计划里可见，
+ *    执行期不写）；applyItem 再查一遍（纵深防御），内层还有基类的 control-plane namespace 拒绝。
+ *  - **缓存永不收录**：role === 'cache' 的区域不属于任何分区，导出时根本不进清单。
+ *  - **环境变量覆盖即跳过**：区域声明的 env 存在且解析结果与默认位置不同 → 报码跳过，绝不猜新位置。
+ *  - **不产生用户可见散文**：告警与计划项文案一律走消息目录（i18n 铁律）。
+ */
+import { normalizePath } from '../utils/paths.js';
+import { engineMsg } from './messages.js';
+import { listFilesDetailed } from './link-report.js';
+import { sectionMeta } from '../schema/section-registry.js';
+import { BUILTIN_PLUGIN_DATA_SOURCES, areaOfPath, areasForSection, isExcludedRel, normalizeHomeRel, parseDeclaredDataDirs, } from '../core/plugin-data-registry.js';
+import { osHomeDirOf } from '../core/backup.js';
+import { FileCollectionAdapter } from './file-collection.js';
+/** 声明来源缓存的 TTL（毫秒）：一次导出/导入/执行里会多次解析，逐次读 15+ 个 package.json 是净开销 */
+const DECLARED_TTL_MS = 5_000;
+/** 单次解析里最多读取多少个已安装插件的 manifest（防御性上限：profile 依赖数量异常时不无限读） */
+const MAX_DECLARED_PACKAGES = 300;
+export class PluginDataAdapter extends FileCollectionAdapter {
+    id;
+    displayName;
+    defaultIncluded = false;
+    portability = 'deviceSpecific';
+    /** home 根（相对路径 = home 相对路径，与 agentInstructions 同形） */
+    baseDir = '';
+    builtin;
+    declaredTtlMs;
+    env;
+    /**
+     * 自述声明缓存。**必须带 ctx 键**（homeDir + profile）：这台机器装了某插件，不代表另一台装了 ——
+     * 缓存若按实例共享，导入到「没装该插件」的目标机时会拿源机的声明去放行写入，
+     * 白名单就变成了「谁先导入谁说了算」。
+     */
+    declaredMemo;
+    /** 本轮清单（listRelPaths 写入；unitIdOf 是同步纯函数，只能从这里拿区域表） */
+    active;
+    /** 本轮告警（环境变量覆盖跳过等；export/preview 收尾合并进返回的 warnings） */
+    pendingWarnings = [];
+    constructor(section, options = {}) {
+        super();
+        this.id = section;
+        this.displayName = sectionMeta(section).displayName;
+        this.builtin = options.sources ?? BUILTIN_PLUGIN_DATA_SOURCES;
+        this.declaredTtlMs = options.declaredTtlMs ?? DECLARED_TTL_MS;
+        this.env = options.env ?? process.env;
+    }
+    /** 本分区可收集区域（内置 + 自述声明） */
+    async allowedEntries(ctx) {
+        const sources = await this.allSources(ctx);
+        return areasForSection(sources, this.id);
+    }
+    async allSources(ctx) {
+        const declared = await this.declaredSources(ctx);
+        return [...this.builtin, ...declared];
+    }
+    /**
+     * 已安装插件的自述声明（dsh.dataDirs）。
+     *
+     * 为什么读 profile 的 node_modules 而不是全局目录：DSH 的插件装在 \`profiles/<profile>/node_modules\`
+     * 下（pnpm 隔离布局），且同一个包在不同 profile 可以是不同版本 —— 声明必须取**本 profile 实际装的**那份。
+     *
+     * 读不到（未安装 / 无声明 / 形状非法）一律跳过：本机制是**附加**信息，绝不因为一个包读不出来
+     * 就影响内置来源或整次导出。
+     */
+    async declaredSources(ctx) {
+        const now = Date.now();
+        const profile = ctx.profile !== undefined && ctx.profile !== '' ? ctx.profile : 'web';
+        const memoKey = ctx.homeDir + '|' + profile;
+        if (this.declaredMemo !== undefined
+            && this.declaredMemo.key === memoKey
+            && now - this.declaredMemo.at < this.declaredTtlMs) {
+            return this.declaredMemo.sources;
+        }
+        const base = 'profiles/' + profile;
+        const out = [];
+        let deps = [];
+        try {
+            const raw = await ctx.fs.readFile(base + '/package.json');
+            const parsed = JSON.parse(new TextDecoder().decode(raw));
+            const dep = parsed?.dependencies;
+            if (dep !== null && typeof dep === 'object')
+                deps = Object.keys(dep).slice(0, MAX_DECLARED_PACKAGES);
+        }
+        catch {
+            deps = [];
+        }
+        for (const name of deps) {
+            try {
+                const raw = await ctx.fs.readFile(base + '/node_modules/' + name + '/package.json');
+                const manifest = JSON.parse(new TextDecoder().decode(raw));
+                const source = parseDeclaredDataDirs(name, manifest);
+                if (source !== null)
+                    out.push(source);
+            }
+            catch {
+                // 未安装 / 无 manifest → 无声明，跳过
+            }
+        }
+        this.declaredMemo = { key: memoKey, at: now, sources: out };
+        return out;
+    }
+    /**
+     * 区域是否被环境变量覆盖（覆盖 → 返回变量名；未覆盖 / 未声明 → null）。
+     *
+     * 判定口径：变量**存在且解析结果与默认位置不同**才算覆盖 —— 仅仅 \`DSH_WE_DATA_DIR=~/.dsh-wallpaper-engine\`
+     * 这种「设成同一个值」的写法不该让区域凭空消失（那会让用户以为「没有数据」）。
+     * 解析只做 \`~\` 展开与分隔符归一（不做 realpath：不读盘、不猜）。
+     */
+    envOverrideOf(ctx, area) {
+        for (const name of area.envOverrides ?? []) {
+            const raw = this.env[name];
+            if (raw === undefined || raw.trim() === '')
+                continue;
+            const normalized = raw.trim().replace(/\\/g, '/').replace(/\/+$/, '');
+            // 默认位置以**系统 home** 为根（本分区的根；见 core/backup.ts 的 OS_HOME_FILE_SECTIONS）
+            const home = osHomeDirOf(ctx).replace(/\\/g, '/').replace(/\/+$/, '');
+            const expanded = normalized.startsWith('~/') ? home + normalized.slice(1) : normalized;
+            const defaultAbs = home + '/' + area.relPath;
+            if (expanded !== defaultAbs)
+                return name;
+        }
+        return null;
+    }
+    /**
+     * 区域是否是**普通文件**（而不是目录 / 不存在）。
+     *
+     * 判据顺序为什么是这样：`statSize` 对「非普通文件」与「不存在」都返回 null，无法单独区分
+     * 目录与缺失；所以先判「是文件」，其余一律按目录走遍历 —— 目录不存在时遍历返回空，
+     * 结果同样是「没有内容」，不会把缺失误报成文件，也不会把目录误读成空内容而静默丢数据。
+     * 门面未实现 statSize（旧宿主）时退回读一次内容：读得出来就是文件。
+     */
+    async isRegularFile(fsFacade, rel) {
+        if (fsFacade.statSize !== undefined) {
+            try {
+                return (await fsFacade.statSize(rel)) !== null;
+            }
+            catch {
+                return false;
+            }
+        }
+        try {
+            await fsFacade.readFile(rel);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    static emptyListing() {
+        return { paths: [], skippedLinks: [], skippedDepDirs: [], followedLinks: 0, unreadableDirs: [] };
+    }
+    /**
+     * 清单枚举 = 来源注册表的区域（覆写基类的目录递归；baseDir='' 时基类实现会递归**整个 home**）。
+     *
+     * **必须覆写**：home 根上递归会遍历 profiles/ sessions/ attachments/ 等全部内容（本机实测
+     * 4000+ 文件 / 数百 MB），既慢又会把无关目录当成该分区的「可勾选单元」。
+     */
+    async listRelPaths(ctx) {
+        // 本分区的根是**系统 home**（~/.dsh-wallpaper-engine、~/.mnemon …），不是 $DSH_HOME ——
+        // 内容 I/O 一律走 homeFs；宿主没提供就什么都不收集，并如实报码（绝不退回 $DSH_HOME 去读错位置）。
+        const homeFs = ctx.homeFs;
+        if (homeFs === undefined) {
+            this.active = [];
+            this.pendingWarnings = [engineMsg('adapter.pluginDataNoOsHome')];
+            return PluginDataAdapter.emptyListing();
+        }
+        const entries = await this.allowedEntries(ctx);
+        this.active = entries;
+        const warnings = [];
+        const paths = [];
+        const listing = PluginDataAdapter.emptyListing();
+        for (const entry of entries) {
+            const rel = entry.area.relPath;
+            const env = this.envOverrideOf(ctx, entry.area);
+            if (env !== null) {
+                warnings.push(engineMsg('adapter.pluginDataEnvOverridden', { path: rel, env }));
+                continue;
+            }
+            if (await this.isRegularFile(homeFs, rel)) {
+                paths.push(rel);
+                continue;
+            }
+            let sub;
+            try {
+                sub = await listFilesDetailed(homeFs, rel);
+            }
+            catch {
+                // 目录不存在 / 读不到 → 视为无内容（存在的空目录与缺失在这里同义：都没有文件可带）
+                continue;
+            }
+            listing.skippedLinks.push(...sub.skippedLinks);
+            listing.skippedDepDirs.push(...sub.skippedDepDirs);
+            listing.unreadableDirs.push(...sub.unreadableDirs);
+            listing.followedLinks += sub.followedLinks;
+            for (const p of sub.paths) {
+                if (isExcludedRel(entry.area, p))
+                    continue;
+                paths.push(p);
+            }
+        }
+        listing.paths = paths;
+        this.pendingWarnings = warnings;
+        return listing;
+    }
+    /**
+     * 单元 = 区域（最长前缀归属）。
+     *
+     * 用「本轮清单写入的区域表」而不是重新解析：listRelPaths 与本函数在同一次 collect 里成对调用，
+     * 重算会让两次解析结果不一致时出现「单元 id 不在清单里」（选择器勾不上）。测试/异常路径下
+     * \`active\` 可能是 undefined（例如直接调 listUnits），此时退回**内置来源**的最长前缀 —— 与清单口径同源。
+     */
+    unitIdOf(relativePath) {
+        const entries = this.active ?? areasForSection(this.builtin, this.id);
+        const hit = areaOfPath(entries, normalizePath(relativePath));
+        return hit === null ? normalizePath(relativePath) : hit.area.relPath;
+    }
+    /**
+     * 读一个成员文件：**换根到系统 home 门面**（基类的其余逻辑 —— 体积、哈希、字节闸门 —— 一字不动）。
+     *
+     * 能走到这里说明 listRelPaths 产出过条目（缺门面时它不产出任何路径），因此缺门面即**抛错**，
+     * 不再造一个「空文件」出来（那会把缺通道伪装成空内容）。
+     */
+    async readMember(ctx, rel, mode, statTimes) {
+        const homeFs = ctx.homeFs;
+        if (homeFs === undefined)
+            throw new Error(engineMsg('adapter.pluginDataNoOsHome'));
+        return super.readMember({ ...ctx, fs: homeFs }, rel, mode, statTimes);
+    }
+    async export(ctx, options) {
+        this.pendingWarnings = [];
+        const out = await super.export(ctx, options);
+        return { ...out, warnings: [...out.warnings, ...this.pendingWarnings] };
+    }
+    async preview(ctx, options) {
+        this.pendingWarnings = [];
+        const out = await super.preview(ctx, options);
+        return {
+            ...out,
+            section: { ...out.section, warnings: [...out.section.warnings, ...this.pendingWarnings] },
+        };
+    }
+    /**
+     * 导入分析 + **写入路径白名单**（本分区唯一的越界防线）。
+     *
+     * 判据：路径必须是本机可解析的某个区域（内置来源，或已安装插件的自述声明）之下，且未被该区域
+     * 的 excludeRel 排除。不满足 → Error（计划里可见、执行期不写），绝不「尽力而为」地写出去。
+     */
+    async analyzeImport(data, ctx) {
+        // 宿主没有系统 home 门面（旧宿主）→ 白名单为空 + 目标读也换不了根：**全部拒绝**并说明原因。
+        // 绝不退回 $DSH_HOME 的 ctx.fs 去比对/写入（那会落到错误位置）。
+        const homeFs = ctx.target.homeFs;
+        const entries = homeFs === undefined ? [] : await this.allowedEntries(ctx.target);
+        const items = await super.analyzeImport(data, homeFs === undefined ? ctx : { ...ctx, target: { ...ctx.target, fs: homeFs } });
+        return items.map((item) => {
+            const ref = item.target?.ref;
+            if (ref === undefined)
+                return item;
+            const rel = normalizeHomeRel(ref);
+            if (rel !== null && areaOfPath(entries, rel) !== null)
+                return item;
+            return {
+                id: item.id,
+                ...(item.unitId !== undefined ? { unitId: item.unitId } : {}),
+                kind: 'Error',
+                adapter: this.id,
+                description: engineMsg(homeFs === undefined ? 'adapter.pluginDataNoOsHome' : 'adapter.pluginDataPathNotAllowed', { path: ref }),
+                severity: 'error',
+            };
+        });
+    }
+    /** 应用前再查一遍白名单（纵深防御：plan 可能来自消费者手工构造/缓存反序列化） */
+    async applyItem(item, ctx) {
+        const homeFs = ctx.target.homeFs;
+        if (homeFs === undefined) {
+            return { ok: false, message: engineMsg('adapter.pluginDataNoOsHome') };
+        }
+        const ref = item.target?.ref;
+        if (ref !== undefined) {
+            const rel = normalizeHomeRel(ref);
+            const entries = await this.allowedEntries(ctx.target);
+            if (rel === null || areaOfPath(entries, rel) === null) {
+                return { ok: false, message: engineMsg('adapter.pluginDataPathNotAllowed', { path: ref }) };
+            }
+        }
+        return super.applyItem(item, { ...ctx, target: { ...ctx.target, fs: homeFs } });
+    }
+}
+//# sourceMappingURL=plugin-data.js.map

package/lib/adapters/self.d.ts

@@ -47,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） */

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/client.d.ts

@@ -20,7 +20,7 @@ type Platform = 'win32' | 'darwin' | 'linux' | 'freebsd' | 'openbsd' | 'aix' | '
  * 明确不实现的分区（keybindings/workflows/commands）不在此列；
  * rules 已由 agentInstructions（~/.dsh/AGENTS.md，dsh-agent-instructions 全局指令）承接。
  */
-type SectionId = 'settings' | 'ui' | 'providers' | 'plugins' | 'mcp' | 'prompts' | 'skills' | 'agentPresets' | 'agentInstructions' | 'workspaces' | 'pluginFiles' | 'credentialsStatus' | 'secrets' | 'sessions' | 'self';
+type SectionId = 'settings' | 'ui' | 'providers' | 'plugins' | 'mcp' | 'prompts' | 'skills' | 'agentPresets' | 'agentInstructions' | 'workspaces' | 'pluginFiles' | 'credentialsStatus' | 'secrets' | 'sessions' | 'self' | 'pluginData' | 'pluginAssets';
 /** 加密备份的算法参数（非秘密：salt/iv/authTag 仅用于解密与完整性校验） */
 interface EncryptionInfo {
   algorithm: 'aes-256-gcm';
@@ -1593,7 +1593,7 @@ declare const uiZh: {
   readonly 'sync.kind.skip': '跳过';
   readonly 'sync.kind.conflict': '冲突';
   readonly 'sync.kind.install': '安装';
-  readonly 'sync.kind.missingSecret': '缺密钥';
+  readonly 'sync.kind.missingSecret': '凭据迁移';
   readonly 'sync.kind.missingDependency': '缺依赖';
   readonly 'sync.kind.pathMapping': '路径映射';
   readonly 'sync.kind.warning': '警告';
@@ -1948,8 +1948,10 @@ declare const uiZh: {
   readonly 'export.category.settings': 'DSH 全局设置（namespace 分区，redacted）';
   readonly 'export.category.providers': 'LLM Provider / Model / 默认模型 / BaseURL';
   readonly 'export.category.plugins': '已安装插件清单与启用状态（不含二进制）';
-  readonly 'export.category.pluginFiles': '插件自有配置文件（白名单 + plugin-config/ 目录，整文件复制）';
+  readonly 'export.category.pluginFiles': '其他插件放在 ~/.dsh 根下的零散配置文件（白名单 + plugin-config/ 目录，整文件复制）';
   readonly 'export.category.self': '本插件自身配置（同步/自动同步/分区选择/UI 偏好/市场；sync-*.json 等，不含凭据值）';
+  readonly 'export.category.pluginData': '其他插件在系统主目录下的数据（如 ~/.dsh-wallpaper-engine、~/.mnemon 的配置与状态；可再生成缓存绝不收录）';
+  readonly 'export.category.pluginAssets': '其他插件的大体积文件（上传的壁纸、本地数据库等；默认不勾选）';
   readonly 'export.category.mcp': 'MCP 服务器组合配置（需重启生效）';
   readonly 'export.category.prompts': 'System Prompt / Plan Mode 提示';
   readonly 'export.category.skills': '用户技能文件（~/.dsh/skills）';
@@ -4062,12 +4064,50 @@ interface RollbackPointSummary {
   spreadMs?: number;
   segments?: RollbackSegmentSummary[];
 }
+/**
+ * 台账占用（issue #89 P2：可观测）。
+ * `bytes` = records/ + payloads/ 的实际字节数；`budgetBytes` = 触发淘汰的字节预算；
+ * `evicted` = 本进程内被预算淘汰的自动点累计数。缺省（老宿主没这个字段）= 界面不渲染这一行。
+ */
+interface RollbackLedgerStatus {
+  records: number;
+  bytes: number;
+  budgetBytes: number;
+  evicted: number;
+  /**
+   * 已超预算且**无处可淘汰**（典型：单条点本身就大于预算）。
+   * 老宿主没有这个字段 ⇒ `undefined` 与 `false` 同义，绝不因为读不到就报警。
+   */
+  overBudget?: boolean;
+}
 interface RollbackStorageStatus {
   available: boolean;
   root?: string;
   detail?: string;
   guidance?: RollbackGuidance[];
   requirements?: readonly string[];
+  /** 磁盘偏好：回合自动留点开关（缺省 / false = 关闭） */
+  rollbackEnabled?: boolean;
+  /** 本进程此刻是否真的在留点（关闭后订阅已解绑）。与 rollbackEnabled 正常一致 */
+  rollbackActive?: boolean;
+  /** 台账占用（老宿主没有这个字段） */
+  ledger?: RollbackLedgerStatus;
+}
+/** 开关读 / 写的结果（POST 成功才会改进程 gate）。 */
+interface RollbackPrefsResult {
+  ok: boolean;
+  rollbackEnabled: boolean;
+  rollbackActive?: boolean;
+}
+/** 台账清理结果（只删自动点；guard 与 protected 保留）。 */
+interface RollbackPurgeResult {
+  ok: boolean;
+  code?: string;
+  detail?: string;
+  removedRecords?: number;
+  removedPayloads?: number;
+  removedObjects?: number;
+  bytes?: number;
 }
 interface RollbackListResult {
   ok?: boolean;
@@ -4316,6 +4356,19 @@ interface RollbackPointPort {
   rollbackPointFileDiff?(id: string, path: string): Promise<RollbackFileDiffResult>;
   restoreRollbackPoint(id: string, opts: RollbackRewindOptions): Promise<RollbackRewindResult>;
   removeRollbackPoint(id: string, userConfirmed: boolean): Promise<RollbackRemoveResult>;
+  /**
+   * 回合自动留点开关（issue #88：它跟配置备份/同步是两件事，必须能关）。
+   * 可选实现：端口缺失时界面**不渲染**开关（绝不给一个点了没反应的入口）。
+   */
+  rollbackPrefs?(): Promise<RollbackPrefsResult>;
+  setRollbackEnabled?(enabled: boolean): Promise<RollbackPrefsResult>;
+  /**
+   * 清理台账（issue #89 P1/P2：把已经涨上去的占用收回来）。
+   * **只删自动点**；`includeGuards` 为 true 时连 guard 也删，protected 永不删。
+   */
+  purgeRollbackPoints?(opts: {
+    includeGuards: boolean;
+  }): Promise<RollbackPurgeResult>;
 }
 //#endregion
 //#region src/client/recovery/recovery-api.d.ts
@@ -4390,6 +4443,25 @@ declare class RecoveryApi implements RecoveryPort, RollbackPointPort {
    * body 必须 `userConfirmed: true`（未确认 → 409 `confirmation-required`）；本方法不自动置 true。
    */
   removeRollbackPoint(id: string, userConfirmed: boolean): Promise<RollbackRemoveResult>;
+  /**
+   * GET /recovery/rollback-points/prefs（issue #88）：读开关。
+   * `rollbackEnabled` = 磁盘偏好（用户意图，随 self 分区进备份）；
+   * `rollbackActive` = 本进程此刻是否真的在留点（关闭后订阅已解绑）。两者正常一致。
+   */
+  rollbackPrefs(): Promise<RollbackPrefsResult>;
+  /**
+   * POST /recovery/rollback-points/prefs（issue #88）：写开关。
+   * 宿主写盘成功后才切进程 gate —— 写失败却把功能打开，等于「界面说开着、实际不留点」。
+   */
+  setRollbackEnabled(enabled: boolean): Promise<RollbackPrefsResult>;
+  /**
+   * POST /recovery/rollback-points/cleanup（issue #89）：清理台账占用。
+   * **只删自动点**；`includeGuards` 为 true 时连救援点也删（protected 永不删）。
+   * 返回逐类删除计数与释放字节，界面照实说「删了多少 / 还剩多少」。
+   */
+  purgeRollbackPoints(opts: {
+    includeGuards: boolean;
+  }): Promise<RollbackPurgeResult>;
   /** POST /recovery/sessions/rollback（T8）：按台账 repairId 回滚（客户端不传路径）。 */
   rollbackSessionRepair(repairId: string): Promise<SessionRepairRollbackResult>;
   /**
@@ -4618,11 +4690,13 @@ declare const zh$4: {
   readonly 'section.agentPresets': 'Agent 预设';
   readonly 'section.agentInstructions': '全局指令';
   readonly 'section.workspaces': '工作区';
-  readonly 'section.pluginFiles': '插件文件';
+  readonly 'section.pluginFiles': '其他插件零散文件';
   readonly 'section.credentialsStatus': '凭据状态';
   readonly 'section.secrets': '密钥';
   readonly 'section.sessions': '历史会话';
-  readonly 'section.self': '插件自身配置';
+  readonly 'section.self': '本插件自身配置';
+  readonly 'section.pluginData': '其他插件数据';
+  readonly 'section.pluginAssets': '其他插件大文件';
   readonly 'view.about': '关于';
   readonly 'about.snippet.environment': '### 环境 / Environment';
   readonly 'about.releaseNotes.rateLimited': 'GitHub API 速率限制（Rate limit exceeded），请稍后再试或直接在 GitHub 上查看。';
@@ -6349,6 +6423,20 @@ declare const zh$1: {
   readonly 'rollback.badge.incomplete': '两态不全';
   readonly 'rollback.badge.protected': '受保护（只进不出）';
   readonly 'rollback.apiMissing': '当前宿主没有回滚点能力（插件版本过旧）：界面不假装可用';
+  readonly 'rollback.switch.label': '启用回合自动留点';
+  readonly 'rollback.switch.hint': '关闭后不再订阅会话事件、不再写台账，聊天里的「↺ 回退」入口一并收起；已有回滚点仍可查看、回退与清理。';
+  readonly 'rollback.switch.unknown': '正在读取开关状态（还没读到之前不显示成「已关闭」）。';
+  readonly 'rollback.switch.diverged': '磁盘上的偏好是「开启」，但本进程没有启用留点（通常是被另一个 DSH 实例改过）。重新打开一次开关即可让本进程生效。';
+  readonly 'rollback.ledger.summary': '台账 {records} 个点 · {size}';
+  readonly 'rollback.ledger.budget': '字节预算 {budget}，已按预算淘汰 {evicted} 个最旧自动点';
+  readonly 'rollback.ledger.overBudget': '台账已到 {size}，超过 {budget} 的字节预算，但已经没有可自动淘汰的点了（通常是单个回滚点本身大于预算）—— 再增长请手动清理。';
+  readonly 'rollback.cleanup': '清理台账';
+  readonly 'rollback.cleanup.confirmTitle': '清理回滚点台账';
+  readonly 'rollback.cleanup.confirmMessage': '删除全部自动回滚点（救援点与受保护点按下面的勾选处置），并回收它们的内容副本。工作区文件与会话日志不会被改动。';
+  readonly 'rollback.cleanup.includeGuards': '同时删除救援点（回退前的自动救援点，删了不可撤销）';
+  readonly 'rollback.cleanup.done': '已删除 {records} 个回滚点，释放 {size}';
+  readonly 'rollback.cleanup.none': '没有可删除的回滚点（自动点为空）';
+  readonly 'rollback.switch.saveFailed': '开关保存失败，仍按原状态运行：';
   readonly 'rollback.retention.hint': '自动点：每会话最多 {perSession} 个、全局最多 {total} 个，超出只淘汰最旧的自动点。回退前的救援点不占这两个额度、也不被它们淘汰，但用户删不掉，所以另有自己的两道上限：每会话最多 {guardsPerSession} 个、全局最多 {guards} 个（无论按哪道算，超出都淘汰最旧的救援点）。';
   readonly 'rollback.autopoint.hint': '回滚点由每个回合结束时自动留：工作区快照 + 会话游标（没有「手动拍点」入口）。';
   readonly 'rollback.state.workspace': '工作区';
@@ -6390,6 +6478,7 @@ declare const zh$1: {
   readonly 'rollback.code.session-out-of-root': '会话日志不在本机会话根内，已拒绝';
   readonly 'rollback.code.session-too-large': '会话日志超过上限：只记下了游标（回退不依赖副本）';
   readonly 'rollback.code.session-active': '这条对话正在运行（会话日志刚被写过）：此时带文件段的回退会被拒绝、工作区一个字节都不动；只回溯消息不受影响（回退只 fork 子会话，不改写原日志）';
+  readonly 'rollback.code.subagent-session': '这是子代理会话（origin=subagent），插件不为它自动留回滚点：它的工作区与父对话相同，留点只会挤占你自己对话的台账空间。';
   readonly 'rollback.preview.sessionActive': '这条对话正在运行：本轮结束前只回溯消息（不改动工作区），避免与正在写盘的工具抢文件。等本轮结束后重新打开本弹窗，即可连文件一起回退。';
   readonly 'rollback.sessionActive.denied': '这条对话正在运行：本次一个文件都没有改动。请等本轮结束，或改成「只回溯消息」再试。';
   readonly 'rollback.code.session-fork-unavailable': '当前宿主没有提供会话 fork 能力，因此不能回退会话';
@@ -6415,7 +6504,7 @@ declare const zh$1: {
   readonly 'rollback.warn.trackDegraded': '有一态留得不完整（回退可能不完整）';
   readonly 'rollback.warn.protected': '该回滚点受保护（只进不出）：不可回退、不可删除';
   readonly 'rollback.warn.guardFailed': '回退前的救援点没留成（已记告警后继续）';
-  readonly 'rollback.warn.createdRefused': '本次不删除任何「留点后新建」的路径：捕获时的证明名单不完整（有整目录被忽略 / 路径索引缺失 / 目录读不出），无法证明哪些是新建的';
+  readonly 'rollback.warn.createdRefused': '本次不删除任何「留点后新建」的路径：捕获时的证明名单不完整（有整目录被忽略 / 路径索引缺失 / 目录读不出 / 留点被时间预算中断），无法证明哪些是新建的';
   readonly 'rollback.warn.unknown': '未识别的告警（技术细节见下方）';
   readonly 'rollback.preview': '预览回退';
   readonly 'rollback.preview.title': '回退预览';