dsh-config-manager 0.1.58 → 0.1.60

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).
@@ -357,14 +395,15 @@ Symptoms and the fix:
 | Symptom | Meaning | Fix |
 |---|---|---|
 | 「另一个任务正在运行，请稍后重试。」 / "Another task is running, please retry." | A live operation holds the lock | Just wait — it clears itself |
-| 「检测到上次异常退出残留的配置锁…重试或重启 DSH 均无效」 / relayed in the log as `自动同步已跳过` | The owner process is **proven dead** (leftover lock) | Run the command below, or use GUI **Recovery → 事故恢复** |
+| 「检测到上次异常退出残留的配置锁…重试或重启 DSH 均无效」 / relayed in the log as `自动同步已跳过` | The owner process is **proven dead** (leftover lock) | Run the command below, or use GUI **Recovery → 事故恢复 → 回收残留锁** |
+| Same message, but the owner PID was **reused** by an unrelated process (common on Windows) | The heartbeat has been stale for a very long time, so the lock is still classified as a leftover one | Same fix — a heartbeat that has not been refreshed for far longer than the stale window is now reclaimable |
 
 ```bash
 # safe: it inspects first and refuses unless the owner is proven dead (a live lock is never touched)
 dsh-config-manager recover-stale-lock
 ```
 
-**Plugins installed but the backup doesn't see them?** Check **Settings → DSH Config Manager → About**: it now shows which directory / profile the plugin list was read from, and how many plugins were detected. The list comes from `$DSH_HOME/profiles/<profile>/package.json` → `dependencies`, where `<profile>` is resolved as `config.profile` → `--profile` → `web`. If the shown path is not the profile you installed into (Desktop builds may use a different profile or a different `DSH_HOME`), that is the cause — align `--profile` / `DSH_HOME` with it.
+**Plugins installed but the backup doesn't see them?** Check **Settings → DSH Config Manager → About**: it now shows which directory / profile the plugin list was read from, and how many plugins were detected. The list comes from `$DSH_HOME/profiles/<profile>/package.json` → `dependencies` (plus anything declared in `dsh.profile.bundles` that is not a dependency), where `<profile>` is resolved as `config.profile` → `--profile` → `web`. If the shown path is not the profile you installed into (Desktop builds may use a different profile or a different `DSH_HOME`), that is the cause — align `--profile` / `DSH_HOME` with it.
 
 ### 🌐 Behind a proxy? (GitHub login / sync)
 

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/file-collection.js

@@ -11,17 +11,21 @@ import path from 'node:path';
 import { sha256Hex } from '../utils/hashing.js';
 import { isReservedInternalRel, normalizePath } from '../utils/paths.js';
 import { msgOf, zhMsg } from '../core/messages.js';
+import { linkWarnings, listFilesDetailed } from './link-report.js';
 export class FileCollectionAdapter {
     async export(ctx, _options) {
         const files = [];
         const warnings = [];
-        let rels = [];
+        // issue #37：用「跟随 junction/符号链接」的遍历，并把跟随/跳过的链接写进告警——
+        // 此前链接目录及其全部内容被静默排除，备份仍报成功。
+        let listing = { paths: [], skippedLinks: [], followedLinks: 0, unreadableDirs: [] };
         try {
-            rels = await ctx.fs.listRecursive(this.baseDir);
+            listing = await listFilesDetailed(ctx.fs, this.baseDir);
         }
         catch {
             // 目录不存在视为空
         }
+        const rels = listing.paths;
         for (const rel of rels) {
             const data = await ctx.fs.readFile(rel);
             const relPath = this.baseDir === '' ? rel : rel.replace(new RegExp(`^${escapeRegExp(this.baseDir)}[\\/]`), '');
@@ -29,6 +33,7 @@ export class FileCollectionAdapter {
         }
         if (rels.length === 0)
             warnings.push(msgOf(ctx)('adapter.dirEmpty', { type: this.displayName }));
+        warnings.push(...linkWarnings(msgOf(ctx), this.displayName, listing));
         return {
             sectionId: this.id,
             data: { version: 1, files },

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

@@ -0,0 +1,16 @@
+/**
+ * 文件类分区的「链接目录」报告（issue #37）。
+ *
+ * 背景：备份静默跳过 junction/符号链接，用户拿到的仍是「成功」，却少了整块内容。
+ * 修复分两步：① `utils/recursive-walk.ts` 跟随链接收集内容；② 本模块把「跟随了什么、
+ * 跳过了什么、为什么跳过」变成备份报告里可见的告警 —— 缺了 ②，用户依然无从察觉缺失。
+ *
+ * 纯函数（除 listFilesDetailed 的 IO 委托外），两个 adapter 共用，避免文案再次漂移。
+ */
+import type { FileSystemFacade } from '../core/types.ts';
+import type { MsgFunc } from '../core/messages.ts';
+import type { RecursiveListing } from '../utils/recursive-walk.ts';
+/** 取遍历结果：宿主未实现 listRecursiveDetailed（旧版/测试 mock）时回退，行为与旧版一致。 */
+export declare function listFilesDetailed(fs: FileSystemFacade, dir: string): Promise<RecursiveListing>;
+/** 把遍历结果转成告警行（无链接时返回空数组 —— 不制造噪音）。 */
+export declare function linkWarnings(msg: MsgFunc, type: string, listing: RecursiveListing): string[];

package/lib/adapters/link-report.js

@@ -0,0 +1,47 @@
+/** 跳过原因 → 消息 key（与 SkippedLink.reason 一一对应，穷尽映射） */
+const REASON_KEY = {
+    loop: 'adapter.linkReason.loop',
+    'outside-home': 'adapter.linkReason.outsideHome',
+    broken: 'adapter.linkReason.broken',
+    unreadable: 'adapter.linkReason.unreadable',
+    'too-deep': 'adapter.linkReason.tooDeep',
+};
+/** 单条原因下最多列出的路径数（其余折叠为计数，避免把报告撑爆） */
+const MAX_PATHS_PER_REASON = 5;
+/** 取遍历结果：宿主未实现 listRecursiveDetailed（旧版/测试 mock）时回退，行为与旧版一致。 */
+export async function listFilesDetailed(fs, dir) {
+    if (fs.listRecursiveDetailed !== undefined)
+        return fs.listRecursiveDetailed(dir);
+    return { paths: await fs.listRecursive(dir), skippedLinks: [], followedLinks: 0, unreadableDirs: [] };
+}
+/** 把遍历结果转成告警行（无链接时返回空数组 —— 不制造噪音）。 */
+export function linkWarnings(msg, type, listing) {
+    const out = [];
+    if (listing.followedLinks > 0) {
+        out.push(msg('adapter.linksFollowed', { type, count: String(listing.followedLinks) }));
+    }
+    if (listing.skippedLinks.length > 0) {
+        const byReason = new Map();
+        for (const s of listing.skippedLinks) {
+            const arr = byReason.get(s.reason) ?? [];
+            arr.push(s.path);
+            byReason.set(s.reason, arr);
+        }
+        const detail = [...byReason.entries()].map(([reason, paths]) => {
+            const shown = paths.slice(0, MAX_PATHS_PER_REASON).join(', ');
+            const more = paths.length > MAX_PATHS_PER_REASON ? ` (+ ${paths.length - MAX_PATHS_PER_REASON})` : '';
+            return `${msg(REASON_KEY[reason])} ${paths.length} 个: ${shown}${more}`;
+        }).join('；');
+        out.push(msg('adapter.linksSkipped', { type, count: String(listing.skippedLinks.length), detail }));
+    }
+    if (listing.unreadableDirs.length > 0) {
+        const shown = listing.unreadableDirs.slice(0, MAX_PATHS_PER_REASON).join(', ');
+        const more = listing.unreadableDirs.length > MAX_PATHS_PER_REASON
+            ? ` (+ ${listing.unreadableDirs.length - MAX_PATHS_PER_REASON})` : '';
+        out.push(msg('adapter.dirsUnreadable', {
+            type, count: String(listing.unreadableDirs.length), detail: `${shown}${more}`,
+        }));
+    }
+    return out;
+}
+//# sourceMappingURL=link-report.js.map

package/lib/adapters/plugin-files.js

@@ -7,7 +7,8 @@
  * 导入时按同一相对路径写回原位置。默认关闭（defaultIncluded=false，用户显式勾选才导出）。
  */
 import { sha256Hex } from '../utils/hashing.js';
-import { zhMsg } from '../core/messages.js';
+import { msgOf, zhMsg } from '../core/messages.js';
+import { linkWarnings, listFilesDetailed } from './link-report.js';
 import { isPathSafe, isReservedInternalRel } from '../utils/paths.js';
 export const DEFAULT_PLUGIN_FILE_WHITELIST = ['dsh-ssh.json', 'pet.json'];
 export class PluginFilesAdapter {
@@ -40,14 +41,16 @@ export class PluginFilesAdapter {
             }
         }
         // 2) 约定配置目录递归收集（相对 ~/.dsh 根的完整路径；与白名单文件去重）
+        // issue #37：与 skills 等同一条遍历（跟随 junction/符号链接 + 跳过留痕）
+        let listing = { paths: [], skippedLinks: [], followedLinks: 0, unreadableDirs: [] };
         if (this.collectDir !== undefined) {
-            let rels = [];
             try {
-                rels = await ctx.fs.listRecursive(this.collectDir);
+                listing = await listFilesDetailed(ctx.fs, this.collectDir);
             }
             catch {
                 // 目录不存在视为空
             }
+            const rels = listing.paths;
             for (const rel of rels) {
                 if (seen.has(rel))
                     continue;
@@ -64,7 +67,7 @@ export class PluginFilesAdapter {
             sectionId: 'pluginFiles',
             data: { version: 1, files },
             counts: { files: files.length },
-            warnings: [],
+            warnings: linkWarnings(msgOf(ctx), this.displayName, listing),
         };
     }
     async analyzeImport(data, ctx) {

package/lib/adapters/plugins.d.ts

@@ -1,9 +1,23 @@
+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;
+/** profile 目录相对 $DSH_HOME 的路径（patches/ 与 pnpm-workspace.yaml 都挂在这里）。 */
+export declare const PNPM_PROFILE_DIR: (profile: string | undefined) => string;
 /** pnpm-workspace.yaml 相对 $DSH_HOME 的路径（plugins 分区内按「插件安装配置」管理）。 */
 export declare const PNPM_WORKSPACE_REL: (profile: string | undefined) => string;
+/** 单个 patch 文件随备份迁移的体积上限（issue #35；patch 是纯文本，超过说明放错了东西）。 */
+export declare const MAX_PATCH_FILE_BYTES: number;
 export declare class PluginsAdapter implements ConfigAdapter<PluginsSection> {
     readonly id: 'plugins';
     readonly displayName = "Plugins";
@@ -11,8 +25,16 @@ 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>>;
+    /**
+     * 导入后目标机**可能**存在的 patch 文件集合（相对 profile 目录）——issue #35。
+     * = 备份携带的 patchFiles ∪ 目标机本来就有的文件。只用于判定「声明能否被满足」，
+     * 不做任何写入（写入在 applyItem 内、且先于 pnpm-workspace.yaml）。
+     */
+    private patchAvailability;
     analyzeImport(data: PluginsSection, ctx: ImportContext): Promise<PlanItem[]>;
     applyItem(item: PlanItem, ctx: ImportContext): Promise<ApplyResult>;
     validate(data: PluginsSection, msg?: MsgFunc): Promise<ValidationResult>;