dsh-config-manager 0.1.57 → 0.1.59

package/README.md

@@ -317,6 +317,10 @@ dsh-config-manager restore [--id <id>] [--dry-run]
 dsh-config-manager reinstall [--version <v>] [--yes] [--list]
                              [--wipe-config] [--dry-run]       # one-click reinstall of DSH itself
 dsh-config-manager recover-stale-lock [--data-dir <dir>]       # clear a leftover lock (see below)
+dsh-config-manager verify [--id <file|path>] [--json]         # read-only check of backup ZIPs
+                          [--data-dir <dir>]
+dsh-config-manager backup [--sections <a,b,c>] [--out <path>] # offline file-level backup
+                          [--dry-run] [--data-dir <dir>]
 ```
 
 **`reinstall` — rescue when DSH is broken.** It reinstalls the `@deepseek-ai/dsh` launcher across platforms (uses the right command per OS: PowerShell on Windows, bash on Unix). By default it reinstalls the launcher + clears global caches; interactively it asks which **dangerous** clean-up items to include (settings / plugins / session data & credentials) — those are **not** selected by default, and any destructive choice requires a second confirmation by typing `YES` before anything runs. Before wiping any `~/.dsh` data it makes an emergency backup at `.reinstall-backup` (the `snapshots/` folder is deliberately never touched).
@@ -348,6 +352,40 @@ dsh-config-manager restore --id <snapshot-id>                 # execute (current
 
 Every overwrite/delete is first copied to `<snapshotDir>/pre-restore/` so you can manually change your mind. Exit code is `1` if any action failed; the report honestly lists restored / removedPlugins / manualHints / failed / skipped.
 
+**`verify` — is that old backup still usable?** The GUI lives inside DSH, so it cannot answer this when DSH will not start; `verify` can. It re-reads a backup ZIP from disk **without writing a single byte**, then reports one verdict per file:
+
+| Verdict | Meaning |
+|---|---|
+| `OK` | Structurally valid and every entry matches its SHA-256 in `integrity/checksums.json` |
+| `MISSING` | The file is not there (wrong path / already deleted) |
+| `CORRUPT` | Damaged or tampered — the message names the exact offending entry |
+| `UNSUPPORTED` | A valid backup this plugin version cannot read (schema too new, or an encrypted container that must be decrypted first) |
+| `VERIFY_ERROR` | The check itself failed (disk I/O); never downgraded to a guess |
+
+With no argument it checks **every** `*.zip` in the exports directory; pass a file name or a path to check just one. Exit code is `1` unless **all** checked backups are `OK` — which makes it safe to assert from CI or a scheduled task. `--json` prints the same result machine-readably.
+
+```bash
+dsh-config-manager verify                # check every backup in the exports directory
+dsh-config-manager verify --json         # machine-readable (exit code still 0/1)
+dsh-config-manager verify my-backup.zip  # check a single file by name
+dsh-config-manager verify C:/backups/dsh-config.zip   # ...or by path
+```
+
+**`backup` — backup even when DSH is down.** This is the offline counterpart of the GUI export: it packs the parts of `$DSH_HOME` that can be read **without the DSH runtime** (skills, agent presets, agent instructions, and the plugin’s own config) into a ZIP with the same structure as a GUI export (`manifest.json` + `integrity/checksums.json` + section directories), then immediately self-checks what it wrote with the same engine as `verify` — a backup command that never verified its own output would be worse than none.
+
+**Credential files never enter a backup.** `.credentials.*`, `.env`, `*.pem` and friends are excluded by an explicit blacklist, only whitelisted directories are walked (never the whole home directory), and symlinks are skipped rather than followed.
+
+Structured sections (settings / UI / providers / plugins / MCP / prompts / workspaces) are **not** silently faked: they need the DSH service layer to read and redact, so they are left out and marked `false` in the manifest — the plan printout lists them under “not offline-collectable” so you know exactly what this backup does and does not contain. Use the GUI export when DSH is healthy for a full backup.
+
+```bash
+dsh-config-manager backup --dry-run                       # list what would be packed (zero writes)
+dsh-config-manager backup                                 # write into the exports directory, then self-check
+dsh-config-manager backup --out D:/rescue/config.zip      # explicit destination (never overwrites)
+dsh-config-manager backup --sections skills,self          # narrow the scope
+```
+
+`--sections` accepts `skills,agentPresets,agentInstructions,self,pluginFiles`. `pluginFiles` is **opt-in** (as in the GUI): it copies third-party plugin files verbatim, and `dsh-ssh.json` holds plaintext host passwords — select it only when you have looked at what is in there.
+
 **A typical rescue flow** when DSH won't start: ① `dsh-config-manager reinstall` to bring the launcher back (plus any clean-up), ② `dsh web` to start DSH again, ③ re-add the plugin from the registry, and ④ pull a snapshot from the remote repo (or run `dsh-config-manager restore`) to bring your config back. The CLI works at every step regardless of DSH's health.
 
 **`recover-stale-lock` — when every operation suddenly fails.** Before touching your config, the plugin claims a small environment lock (it records who is operating plus a heartbeat) so that two operations can never write your config at the same time. If a `dsh web` process is **force-killed** (Task Manager, `kill -9`), the lock file survives with a dead owner: the next operation is refused, and it stays refused **no matter how often you retry or restart DSH** — because the plugin deliberately never removes a lock on its own (a wrong guess could evict a live operation).

package/README.zh-CN.md

@@ -80,6 +80,8 @@ DSH 是你的 AI 助手工作台，里面存着你的各种设置：模型配置
 | ⏰ | **定时全量备份** | 按固定周期（6h / 12h / 24h / 7d）自动全量备份，一劳永逸，密钥永不包含 |
 | 🛒 | **配置市场** | 浏览并一键安装社区分享的配置——供应链警示 + 逐分区批准 |
 | 🗂️ | **配置档案 Profiles** | 保存多套配置（工作 / 个人），随时切换 |
+| 🧩 | **本地插件随备份迁移** | `link:` / `file:` 安装的本地开发插件会被打包进备份，换机不再丢失 |
+| 🗄️ | **保留策略可配（GFS 分层）** | 「最近 N 份 + 每月留 1 份 + 每年留 1 份」，默认值等价旧行为 |
 | 🤖 | **Agent 工具** | Agent 会话内直接备份 / 快照 / 恢复 / 同步 |
 
 ---
@@ -293,6 +295,10 @@ dsh-config-manager restore [--id <id>] [--dry-run]
                            [--profile <name>] [--settings <path>]
 dsh-config-manager reinstall [--version <v>] [--yes] [--list]
                              [--wipe-config] [--dry-run]       # 一键重装 DSH 程序本体
+dsh-config-manager verify [--id <文件|路径>] [--json]          # 只读自检备份 ZIP
+                          [--data-dir <dir>]
+dsh-config-manager backup [--sections <a,b,c>] [--out <path>] # 离线文件级备份
+                          [--dry-run] [--data-dir <dir>]
 ```
 
 **`reinstall` —— DSH 损坏时的救急重装。** 跨平台一键重装 `@deepseek-ai/dsh` 启动器（按操作系统自动选用正确命令：Windows 走 PowerShell、Unix 走 bash）。默认重装启动器 + 清全局残留缓存；交互式多选会询问是否勾选**危险**清理项（设置 / 插件 / 会话与凭据）——这些**默认不勾选**，且只要涉及删数据的动作，执行前都必须**二次确认输入 `YES`**。清空 `~/.dsh` 数据前会先做一份 `.reinstall-backup` 紧急备份（`snapshots/` 目录按设计绝不触碰）。
@@ -324,6 +330,41 @@ dsh-config-manager restore --id <snapshot-id>                 # 执行恢复（
 
 每次覆盖/删除前都会先把当前文件复制到 `<snapshotDir>/pre-restore/`，可人工反悔。任一动作失败则退出码为 1；报告如实列出 已还原 / 已卸载插件 / 需人工处理 / 失败 / 跳过。
 
+**`verify` —— 三个月前那个备份现在还能不能用？** GUI 长在 DSH 里，DSH 起不来时它答不了这个问题，`verify` 能。它把备份 ZIP 从磁盘重读一遍，**一个字节都不写**，然后逐文件给出裁决：
+
+| 裁决 | 含义 |
+|---|---|
+| `OK` | 结构合法，且每个条目都与 `integrity/checksums.json` 里的 SHA-256 一致 |
+| `MISSING` | 文件不在（路径写错 / 已被删除） |
+| `CORRUPT` | 损坏或被篡改——报错会**点名具体是哪个条目** |
+| `UNSUPPORTED` | 备份本身有效，但本版本插件读不了（schema 过新，或整体加密容器需先解密） |
+| `VERIFY_ERROR` | 自检自身失败（磁盘 IO）；绝不降级成猜测结论 |
+
+不给参数就校验导出目录下**全部** `*.zip`；给文件名或路径就只校验那一个。**只要有一个不是 `OK` 退出码就是 `1`**，因此可直接在 CI / 定时任务里断言。`--json` 输出同样的机器可读结果。
+
+```bash
+dsh-config-manager verify                # 校验导出目录下的全部备份
+dsh-config-manager verify --json         # 机器可读（退出码语义不变）
+dsh-config-manager verify my-backup.zip  # 按文件名只校验一个
+dsh-config-manager verify C:/backups/dsh-config.zip   # 或按路径
+```
+
+**`backup` —— DSH 挂了也能备份。** 它是 GUI 导出的离线版：把 `$DSH_HOME` 里**无需 DSH 运行时即可直读**的部分（skills、agent presets、agent instructions、插件自身配置）打成与 GUI 导出同结构的 ZIP（`manifest.json` + `integrity/checksums.json` + 分区目录），落盘后立即用与 `verify` 同一引擎对自己做一次自检——一个从不校验自己产物的备份命令，比没有更糟。
+
+**凭据文件永不进入备份。** `.credentials.*`、`.env`、`*.pem` 等由显式黑名单排除；只遍历白名单目录（绝不对整个主目录递归）；symlink 一律跳过而非跟随。
+
+结构化分区（设置 / UI / providers / 插件 / MCP / prompts / workspaces）**不会**被偷偷伪造：它们需要 DSH 服务层读值并脱敏，因此一律不写入、在 manifest 里标记为 `false`——计划输出会把它们列在「离线不可收集」下，让你清楚这份备份到底有什么、没有什么。DSH 健康时想要完整备份，请用 GUI 导出。
+
+```bash
+dsh-config-manager backup --dry-run                       # 列出将打包哪些文件（零写入）
+dsh-config-manager backup                                 # 写入导出目录，随后自动自检
+dsh-config-manager backup --out D:/rescue/config.zip      # 指定输出（绝不覆盖既有文件）
+dsh-config-manager backup --sections skills,self          # 收窄范围
+```
+
+`--sections` 可选值为 `skills,agentPresets,agentInstructions,self,pluginFiles`。其中 `pluginFiles` 与 GUI 侧一致属**默认关闭**：它原样复制第三方插件自有文件，而 `dsh-ssh.json` 里是明文主机密码——确认过内容之后再选它。
+
+
 **典型救急流程**（DSH 起不来时）：① `dsh-config-manager reinstall` 先把启动器重装回来（必要时顺带清理），② `dsh web` 重新启动 DSH，③ 从仓库装回插件，④ 从远程仓库拉取快照（或执行 `dsh-config-manager restore`）把配置恢复回来。整个流程中 CLI 全程可用，与 DSH 是否健康无关。
 
 ### 🤖 Agent 可调用的模型工具
@@ -393,6 +434,7 @@ dsh-config-manager restore --id <snapshot-id>                 # 执行恢复（
 4. **历史会话默认不迁移**（v1 仅支持文件级复制）
 5. **加密备份**：密码丢失则无法解密（设计使然——请牢记密码）
 6. **快照恢复是离线的、诚实的**：离线引擎无法恢复的条目（快照无整文件备份时的 settings namespace / patch 行、存在 DSH storages 里的 workspace 记录）会如实列为跳过并指向在线回滚；凭据**值**绝不自动改写（只提示人工补录）；无插件基线的旧快照只提示人工核对新增插件
+7. **本地源插件（`link:` / `file:`）随备份打包**：导出时执行 `npm pack` 把本地开发中的插件打成 tarball 一并备份，导入时解包到 `$DSH_HOME/dsh-config-manager/local-plugins/` 后按 `file:` 安装。因此：① 备份体积会随本地插件的体积增大（单插件超过 100 MB 会被跳过并告警，建议先发布到 registry / git 再备份）；② 插件**源码**会进入备份（与「密钥永不进备份」不冲突——密钥仍被排除，这里进的是代码）；③ 打包需要本机有可用的 `npm`，无 npm 时该插件退化为原行为（保留原 spec，换机后仍需手工安装）
 
 > 维护者与开发者：构建、测试、自动发布与完整技术说明见 [DEVELOPERS.md](DEVELOPERS.md)。
 

package/lib/adapters/index.d.ts

@@ -9,6 +9,7 @@
  */
 import type { ConfigAdapter } from '../core/types.ts';
 import { type NamespaceProvider } from './settings.ts';
+import { type LocalPluginPackHook } from './plugins.ts';
 import { type CredentialRefsProvider } from './credentials.ts';
 export interface AdapterRegistryOptions {
     /** settings namespace 清单（宿主从 settings.yaml 顶层 key 解析注入；缺省 [] → settings/ui/credentials 为空） */
@@ -23,6 +24,11 @@ export interface AdapterRegistryOptions {
     includeSessions?: boolean;
     /** 插件自身包名：导出 plugins 分区时不列自己（避免自引用；缺省 dsh-config-manager） */
     selfPluginName?: string;
+    /**
+     * T1：本地源（link:/file:）插件打包钩子。注入后，导出 plugins 分区时会为这类插件
+     * 执行 `npm pack` 并把 tarball 随备份带走；不注入 = 保持改造前行为（本地插件换机丢失）。
+     */
+    localPluginPack?: LocalPluginPackHook;
     /**
      * self 分区：插件自身配置目录（相对 ~/.dsh 根，如 'dsh-config-manager'）。
      * 缺省 'dsh-config-manager'；传入 '' 表示不挂载（宿主自定义 dataDir 在 homeDir 外时）。
@@ -37,6 +43,7 @@ export { SettingsAdapter } from './settings.ts';
 export { UiAdapter, isUiNamespace, KNOWN_UI_NAMESPACE_PREFIXES, UI_MIGRATION_NOTES } from './ui.ts';
 export { ProvidersAdapter, DEFAULT_PROVIDER_NAMESPACES, type ProviderExportEntry, type ProviderExportSection } from './providers.ts';
 export { PluginsAdapter, USER_PATCH_FILE } from './plugins.ts';
+export type { LocalPluginPackHook } from './plugins.ts';
 export { McpAdapter, extractMcpServers, buildMcpPatchLine, type McpExportEntry, type McpExportSection } from './mcp.ts';
 export { PromptsAdapter, extractPrompts, mergePromptIntoLine, buildPromptLine, type PromptExportEntry, type PromptsExportSection } from './prompts.ts';
 export { SkillsAdapter } from './skills.ts';

package/lib/adapters/index.js

@@ -19,7 +19,7 @@ export function createAdapters(options = {}) {
         new SettingsAdapter(namespaces),
         new UiAdapter(namespaces),
         new ProvidersAdapter(),
-        new PluginsAdapter(options.selfPluginName),
+        new PluginsAdapter(options.selfPluginName, options.localPluginPack),
         new McpAdapter(),
         new PromptsAdapter(),
         new SkillsAdapter(),

package/lib/adapters/plugins.d.ts

@@ -1,7 +1,17 @@
+import type { PackLocalPluginsResult } from '../core/local-plugin-pack.ts';
 import type { MsgFunc } from '../core/messages.ts';
-import type { PluginsSection } from '../schema/types.ts';
+import type { PluginEntry, PluginsSection } from '../schema/types.ts';
 import type { ApplyResult, ConfigAdapter, ExportOptions, ExportSection, HostContext, ImportContext, PlanItem, ValidationResult } from '../core/types.ts';
 export declare const USER_PATCH_FILE = "cordis.patch.yml";
+/**
+ * 本地源插件打包钩子（由宿主注入，见 src/index.ts createAdapters）。
+ * 返回打包结果（含字节与重写后的 spec）；不注入 = 不做本地源打包（保持旧行为）。
+ */
+export type LocalPluginPackHook = (plugins: PluginEntry[], ctx: HostContext) => Promise<PackLocalPluginsResult>;
+/** 本地插件 tarball 解包到 homeDir 内的固定缓存目录（相对 $DSH_HOME）。 */
+export declare const LOCAL_TARBALL_CACHE_REL = "dsh-config-manager/local-plugins";
+/** 归档内相对路径 → 缓存目录下的安全文件名（拒绝任何路径穿越）。 */
+export declare function localTarballCacheName(relativePath: string): string;
 /** pnpm-workspace.yaml 相对 $DSH_HOME 的路径（plugins 分区内按「插件安装配置」管理）。 */
 export declare const PNPM_WORKSPACE_REL: (profile: string | undefined) => string;
 export declare class PluginsAdapter implements ConfigAdapter<PluginsSection> {
@@ -11,7 +21,9 @@ export declare class PluginsAdapter implements ConfigAdapter<PluginsSection> {
     readonly portability: 'portable';
     /** 插件自身包名：导出 plugins 分区时不列自己（避免备份里出现「当前正在生成备份的插件」的自引用条目） */
     private readonly selfName;
-    constructor(selfName?: string);
+    /** T1：本地源（link:/file:）插件打包钩子；未注入 = 不打包（保持改造前行为） */
+    private readonly localPack;
+    constructor(selfName?: string, localPack?: LocalPluginPackHook);
     export(ctx: HostContext, _options: ExportOptions): Promise<ExportSection<PluginsSection>>;
     analyzeImport(data: PluginsSection, ctx: ImportContext): Promise<PlanItem[]>;
     applyItem(item: PlanItem, ctx: ImportContext): Promise<ApplyResult>;

package/lib/adapters/plugins.js

@@ -4,11 +4,66 @@
  *
  * 安全不变量：绝不打包插件二进制；导入走 DSH 官方机制（dsh plugin CLI → needsRestart 提示）。
  * patch 行导入（用户自定义行：启用/禁用/插入）写回 cordis.patch.yml，同样 needsRestart。
+ *
+ * T1（本地源插件迁移）：`link:` / `file:` 来源的插件指向本机路径，换机后必然不可达
+ * （曾导致插件被静默丢失）。导出时经注入的 `localPack` 执行 `npm pack`，把 tarball 作为
+ * 文件条目随分区进入 ZIP（落在 `plugin-files/local-plugins/` 前缀下，复用既有文件类分区通道，
+ * **不新增分区 id**）；导入时把 spec 重写为 `file:<解包后的绝对路径>` 再交给官方安装通道。
  */
 import { isDeepStrictEqual } from 'node:util';
 import { installSpecFor, resolveProfileNameFromArgv } from '../core/plugin-cli.js';
+import { isLocalPluginSpec, isPackedLocalSpec, LOCAL_PLUGIN_DIR } from '../core/local-plugin-pack.js';
 import { msgOf, zhMsg } from '../core/messages.js';
 export const USER_PATCH_FILE = 'cordis.patch.yml';
+/** tarball 字节 → base64（零依赖，避免 Buffer 在浏览器侧类型问题） */
+function bytesToBase64(data) {
+    if (typeof Buffer !== 'undefined')
+        return Buffer.from(data).toString('base64');
+    let binary = '';
+    for (const b of data)
+        binary += String.fromCharCode(b);
+    return btoa(binary);
+}
+/** base64 → 字节（导入端解包用） */
+function base64ToBytes(b64) {
+    if (typeof Buffer !== 'undefined')
+        return new Uint8Array(Buffer.from(b64, 'base64'));
+    const binary = atob(b64);
+    const out = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1)
+        out[i] = binary.charCodeAt(i);
+    return out;
+}
+/** 本地插件 tarball 解包到 homeDir 内的固定缓存目录（相对 $DSH_HOME）。 */
+export const LOCAL_TARBALL_CACHE_REL = 'dsh-config-manager/local-plugins';
+/** 按包名取出备份内的 tarball 条目（不存在返回 undefined）。 */
+function tarballOf(data, pkgName) {
+    return data.localTarballs?.find((t) => t.packageName === pkgName);
+}
+/** 归档内相对路径 → 缓存目录下的安全文件名（拒绝任何路径穿越）。 */
+export function localTarballCacheName(relativePath) {
+    const base = relativePath.split('/').pop() ?? '';
+    if (base === '' || base.includes('\\') || base === '.' || base === '..') {
+        throw new Error(`非法 tarball 相对路径: ${relativePath}`);
+    }
+    return base;
+}
+/**
+ * 把备份内的 tarball 写入 `$DSH_HOME/dsh-config-manager/local-plugins/<name>`，
+ * 返回**绝对路径**（供 `file:` spec 使用）。
+ *
+ * 为什么写进 $DSH_HOME 内：`ctx.target.fs` 是「限定在 home 根内」的门面
+ * （`DshFileSystemFacade.abs()` 对根外路径抛 fsPathEscape），写 homeDir 外会被拒。
+ * 该目录同时落在既有保留区内（`dsh-config-manager/`），随 self 分区语义一致。
+ */
+async function writeLocalTarball(ctx, tarball) {
+    const name = localTarballCacheName(tarball.relativePath);
+    const rel = `${LOCAL_TARBALL_CACHE_REL}/${name}`;
+    await ctx.target.fs.writeFile(rel, base64ToBytes(tarball.base64));
+    // `file:` spec 一律用正斜杠（pnpm 跨平台接受正斜杠；反斜杠在部分版本需转义）
+    const abs = `${ctx.target.homeDir.replace(/[\\/]+$/, '')}/${rel}`;
+    return abs.replace(/\\/g, '/');
+}
 /** pnpm-workspace.yaml 相对 $DSH_HOME 的路径（plugins 分区内按「插件安装配置」管理）。 */
 export const PNPM_WORKSPACE_REL = (profile) => `profiles/${profile !== undefined && profile !== '' ? profile : 'web'}/pnpm-workspace.yaml`;
 /** patch 行 raw 是否由其他 adapter 管理（mcp-client 行 / systemPrompt / planMode 行）。
@@ -50,8 +105,11 @@ export class PluginsAdapter {
     portability = 'portable';
     /** 插件自身包名：导出 plugins 分区时不列自己（避免备份里出现「当前正在生成备份的插件」的自引用条目） */
     selfName;
-    constructor(selfName = 'dsh-config-manager') {
+    /** T1：本地源（link:/file:）插件打包钩子；未注入 = 不打包（保持改造前行为） */
+    localPack;
+    constructor(selfName = 'dsh-config-manager', localPack) {
         this.selfName = selfName;
+        this.localPack = localPack;
     }
     async export(ctx, _options) {
         const plugins = [];
@@ -97,10 +155,45 @@ export class PluginsAdapter {
         catch (err) {
             warnings.push(msgOf(ctx)('adapter.pnpmReadFailed', { reason: err instanceof Error ? err.message : String(err) }));
         }
+        // T1：本地源（link:/file:）插件打包。这些 spec 指向本机路径，换机后必然不可达
+        // （曾导致插件被静默丢失）。钩子由宿主注入；未注入 / 无本地源 / 单个失败一律不中断导出。
+        let localTarballs;
+        let effectivePlugins = plugins;
+        if (this.localPack !== undefined) {
+            try {
+                const packed = await this.localPack(plugins, ctx);
+                warnings.push(...packed.warnings);
+                if (packed.packed.length > 0) {
+                    localTarballs = packed.packed.map((p) => ({
+                        packageName: p.packageName,
+                        version: p.version,
+                        relativePath: p.relativePath,
+                        base64: bytesToBase64(p.data),
+                    }));
+                    // 清单里的 spec 同步改写为可移植形式：即便导入端不拆 tarball，
+                    // 也不会再把本机绝对路径写进目标 profile package.json。
+                    const rewritten = packed.rewritten;
+                    effectivePlugins = plugins.map((p) => rewritten[p.name] !== undefined ? { ...p, spec: rewritten[p.name] } : p);
+                }
+            }
+            catch (err) {
+                warnings.push(msgOf(ctx)('adapter.localPackFailed', { reason: err instanceof Error ? err.message : String(err) }));
+            }
+        }
         return {
             sectionId: 'plugins',
-            data: { version: 1, plugins, patch, pnpmWorkspace },
-            counts: { plugins: plugins.length, patchLines: patch.length },
+            data: {
+                version: 1,
+                plugins: effectivePlugins,
+                patch,
+                pnpmWorkspace,
+                ...(localTarballs !== undefined ? { localTarballs } : {}),
+            },
+            counts: {
+                plugins: effectivePlugins.length,
+                patchLines: patch.length,
+                ...(localTarballs !== undefined ? { localTarballs: localTarballs.length } : {}),
+            },
             warnings,
         };
     }
@@ -136,11 +229,14 @@ export class PluginsAdapter {
         for (const p of data.plugins) {
             const id = `plugin:${p.name}`;
             const tp = targetInstalled.find((t) => t.name === p.name);
+            // T1：该插件在备份内自带 tarball（本地源 link:/file:）→ 目标机无需原始路径即可安装。
+            const hasTarball = tarballOf(data, p.name) !== undefined;
+            const tarballHint = hasTarball ? msg('adapter.pluginLocalTarballHint') : undefined;
             if (!tp) {
                 items.push({
                     id, kind: 'Install', adapter: 'plugins',
                     description: msg('adapter.pluginInstall', { name: p.name, version: p.version }),
-                    detail: p.isBundle ? msg('adapter.pluginBundleMember') : undefined,
+                    detail: p.isBundle ? msg('adapter.pluginBundleMember') : tarballHint,
                     severity: 'info',
                 });
             }
@@ -218,7 +314,20 @@ export class PluginsAdapter {
             try {
                 // 非 registry 来源（github:/file: 等）按来源 spec 安装，registry 包按裸包名装 npm 最新版
                 const data = ctx.sections.get('plugins');
-                const spec = data?.plugins.find((p) => p.name === name)?.spec;
+                let spec = data?.plugins.find((p) => p.name === name)?.spec;
+                // T1：备份内自带 tarball → 解包到 homeDir 内的本地插件缓存目录，把 spec 重写为绝对路径。
+                // 这是「换机后本地插件不再丢失」的关键：原始绝对路径在目标机不存在，解包出的 tgz 一定存在。
+                const tarball = data !== undefined ? tarballOf(data, name) : undefined;
+                if (tarball !== undefined) {
+                    try {
+                        const abs = await writeLocalTarball(ctx, tarball);
+                        spec = `file:${abs}`;
+                    }
+                    catch (err) {
+                        // 解包失败不阻断安装尝试：退回原 spec（可能失败，但会如实报错而非静默丢失）
+                        ctx.onLog?.(`本地插件 ${name} 的 tarball 解包失败，回退原始 spec：${err instanceof Error ? err.message : String(err)}`);
+                    }
+                }
                 // 执行日志：记录实际将发起的子进程命令行（与宿主 DshPluginsFacade 的
                 // dsh plugin --profile <p> add <spec> 一致）；仅非敏感文本，渲染前 UI 再 redact 兜底
                 ctx.onLog?.(`$ dsh plugin --profile ${ctx.target.profile ?? resolveProfileNameFromArgv()} add ${installSpecFor(name, spec)}`);
@@ -277,6 +386,30 @@ export class PluginsAdapter {
         if (data.pnpmWorkspace !== undefined && data.pnpmWorkspace !== null && typeof data.pnpmWorkspace !== 'string') {
             issues.push({ path: 'pnpmWorkspace', message: msg('adapter.validate.string', { subject: 'pnpmWorkspace' }), severity: 'error' });
         }
+        // T1：本地插件 tarball 载荷（缺省合法；存在时逐条校验形状与路径安全）
+        if (data.localTarballs !== undefined) {
+            if (!Array.isArray(data.localTarballs)) {
+                issues.push({ path: 'localTarballs', message: msg('adapter.validate.array', { subject: 'localTarballs' }), severity: 'error' });
+            }
+            else {
+                data.localTarballs.forEach((t, i) => {
+                    if (t === null || typeof t !== 'object') {
+                        issues.push({ path: `localTarballs[${i}]`, message: msg('adapter.validate.object', { subject: 'localTarballs[]' }), severity: 'error' });
+                        return;
+                    }
+                    for (const field of ['packageName', 'version', 'relativePath', 'base64']) {
+                        if (typeof t[field] !== 'string' || t[field] === '') {
+                            issues.push({ path: `localTarballs[${i}].${field}`, message: msg('adapter.validate.string', { subject: field }), severity: 'error' });
+                        }
+                    }
+                    // 相对路径必须落在 LOCAL_PLUGIN_DIR 之下且不含穿越段（防写 homeDir 外）
+                    const rel = typeof t.relativePath === 'string' ? t.relativePath.replace(/\\/g, '/') : '';
+                    if (rel !== '' && (!rel.startsWith(`${LOCAL_PLUGIN_DIR}/`) || rel.includes('..'))) {
+                        issues.push({ path: `localTarballs[${i}].relativePath`, message: msg('adapter.validate.localTarballPath', { path: rel }), severity: 'error' });
+                    }
+                });
+            }
+        }
         return { valid: issues.filter((i) => i.severity === 'error').length === 0, issues };
     }
 }

package/lib/cli/index.d.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { type SnapshotMeta } from '../core/restore.ts';
 import { type ReinstallItemId } from '../core/reinstall.ts';
-export type CliCommand = 'snapshots' | 'restore' | 'reinstall' | 'recover-stale-lock' | 'help';
+export type CliCommand = 'snapshots' | 'restore' | 'reinstall' | 'recover-stale-lock' | 'verify' | 'backup' | 'help';
 export interface CliOptions {
     command: CliCommand;
     /** --data-dir：快照数据目录覆盖 */
@@ -22,6 +22,14 @@ export interface CliOptions {
     list: boolean;
     /** --wipe-config：reinstall 等价勾选全部数据类（settings/plugins/data） */
     wipeConfig: boolean;
+    /** --json：verify 输出机器可读结果（便于 CI / 定时任务断言） */
+    json: boolean;
+    /** --sections <a,b,c>：backup 要打包的离线分区白名单（缺省取默认分区） */
+    sections?: string;
+    /** --out <path>：backup 输出 ZIP 路径（缺省写入导出目录，自动去重不覆盖） */
+    out?: string;
+    /** verify 的位置参数（文件名或路径；与 --id 同义，最多一个） */
+    positionals: string[];
 }
 export type ParseResult = {
     ok: true;
@@ -65,3 +73,5 @@ 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 覆盖优先，缺省 $DSH_HOME/dsh-config-manager/exports */
+export declare function resolveExportsDir(flag: string | undefined, env?: Record<string, string | undefined>): string;