dsh-config-manager 0.1.59 → 0.1.61

package/README.md

@@ -52,7 +52,7 @@ Move your complete DeepSeek Harness setup without manually reinstalling plugins,
 
 ### Sync DSH configuration across machines
 
-Keep portable configuration synchronized between machines through a private Git repository or WebDAV — secrets never sync.
+Keep portable configuration synchronized between machines through a private Git repository or WebDAV — secrets do not sync by default (the payload is run through the SecretScanner); check "Export secrets" with an encryption password and `~/.dsh/.credentials.yaml` travels as scrypt + AES-256-GCM ciphertext inside the encrypted snapshot, so another machine can restore the credentials while the remote (Git host / WebDAV provider) only ever sees ciphertext.
 
 ### Schedule automatic full backups
 
@@ -76,7 +76,7 @@ Browse the built-in official market for ready-made configurations (model provide
 | 🔒 | **Secret safety** | API Keys are not exported by default — non-encrypted imports ask you to re-enter; encrypted backups restore them with the password |
 | ↩️ | **Automatic rollback** | Failed import restores everything automatically |
 | 📸 | **Snapshot restore** | Undo an import: whole-file restore + uninstall added plugins (CLI & GUI) |
-| 🔄 | **Remote Sync** | Push/pull portable config via **Git private repo or WebDAV** (secrets never sync) |
+| 🔄 | **Remote Sync** | Push/pull portable config via **Git private repo or WebDAV** (secrets do not sync by default; encrypted snapshots can optionally carry encrypted credentials) |
 | ⏰ | **Scheduled backups** | Full backup on a fixed cadence (6h / 12h / 24h / 7d) — set-and-forget, secrets never included |
 | 🛒 | **Config Marketplace** | Browse & one-click install community configs — supply-chain warnings + per-section approval |
 | 🗂️ | **Profiles** | Save multiple setups (Work / Personal) and switch anytime — preview + auto-backup + rollback |
@@ -248,6 +248,7 @@ Push / pull your portable config between machines through **either of two channe
 - **WebDAV auth** uses HTTP Basic: the `username` is stored in the config and may be echoed back into the UI, while the `password` is read live from the DSH credentials slot `DSH_CONFIG_MANAGER_SYNC_WEBDAV_PASSWORD` — it never appears in any sync file or log.
 - **Plugins auto-install**: when pulling diffs, plugins that are new in the backup are **installed automatically** on confirm — no manual per-item ticking in the diff list. Only **version-conflict** plugins still ask you to pick "Keep Current / Use Imported".
 - **Push preview before uploading** — the Push button first shows a read-only preview of what will be sent (sections + per-section counts + changed-vs-baseline markers, first-baseline notice) and only writes the remote after you confirm.
+- **Secrets do not sync by default**: every section goes through the `SecretScanner` (sensitive field values stripped) and the credential section is structurally excluded. With "Export secrets" checked and an encryption password set, `~/.dsh/.credentials.yaml` travels as scrypt + AES-256-GCM ciphertext in a **separate credentials payload** of the encrypted snapshot (never inside any section); the receiving side decrypts it into per-ref "credential migration" items that are written back to the local credential store (`credentials.set`) only after you confirm. The password is memory-only and never persisted or logged; **auto sync never carries credentials** (it has no password and skips encrypted snapshots).
 
 ### 🛒 Configuration Marketplace
 
@@ -395,14 +396,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

@@ -13,7 +13,7 @@ DSH Config Manager 是一个 DeepSeek Harness 配置备份与迁移插件：一
 - Profiles（配置档案）
 - Workspace / AGENTS.md
 
-把当前 DeepSeek Harness 环境导出为可移植备份，在另一台电脑上一键恢复；也支持通过 Git / WebDAV 跨机同步（密钥永不参与同步）；还能通过内置**配置市场**浏览、一键安装社区分享的现成配置。
+把当前 DeepSeek Harness 环境导出为可移植备份，在另一台电脑上一键恢复；也支持通过 Git / WebDAV 跨机同步（密钥默认不同步，勾选「导出密钥」并加密后可随加密快照迁移）；还能通过内置**配置市场**浏览、一键安装社区分享的现成配置。
 
 [English](README.md) · [简体中文](README.zh-CN.md)
 
@@ -52,7 +52,7 @@ DSH 是你的 AI 助手工作台，里面存着你的各种设置：模型配置
 
 ### 在多台电脑间同步 DSH 配置
 
-通过私有 Git 仓库或 WebDAV 在多台电脑间保持可移植配置同步——密钥永不参与同步。
+通过私有 Git 仓库或 WebDAV 在多台电脑间保持可移植配置同步——密钥默认不参与同步（同步载荷会被 SecretScanner 剥离）；勾选「导出密钥」并设置加密密码后，`~/.dsh/.credentials.yaml` 会以 scrypt + AES-256-GCM 密文随加密快照上行，换机后可随同步写回本机凭据，远端（Git 仓库 / WebDAV 服务商）全程只见密文。
 
 ### 定时自动全量备份
 
@@ -76,7 +76,7 @@ DSH 是你的 AI 助手工作台，里面存着你的各种设置：模型配置
 | 🔒 | **密钥安全** | API Key 默认不导出；非加密导入后提醒重新填写，加密备份用密码解锁恢复 |
 | ↩️ | **自动回滚** | 导入失败自动恢复原样，不会弄坏现有配置 |
 | 📸 | **快照恢复** | 撤销一次导入：整文件还原 + 卸载新增插件（CLI 与 GUI 均支持） |
-| 🔄 | **远程同步** | 通过 **Git 私有仓库或 WebDAV** 推送 / 拉取可移植配置（密钥永不参与同步） |
+| 🔄 | **远程同步** | 通过 **Git 私有仓库或 WebDAV** 推送 / 拉取可移植配置（密钥默认不参与同步；加密快照可选携带密文凭据） |
 | ⏰ | **定时全量备份** | 按固定周期（6h / 12h / 24h / 7d）自动全量备份，一劳永逸，密钥永不包含 |
 | 🛒 | **配置市场** | 浏览并一键安装社区分享的配置——供应链警示 + 逐分区批准 |
 | 🗂️ | **配置档案 Profiles** | 保存多套配置（工作 / 个人），随时切换 |
@@ -243,6 +243,7 @@ dsh plugin --profile web add dsh-config-manager@latest
 - **切换通道重新开始**：Git 与 WebDAV 的快照 / 共同祖先**互不共享**。切换通道后，同步从新远端的空基线重新开始——请先推送一个新快照。
 - **WebDAV 认证**采用 HTTP Basic：`username` 存配置、可在界面回显；`password` 则实时从 DSH credentials 槽位 `DSH_CONFIG_MANAGER_SYNC_WEBDAV_PASSWORD` 读取——绝不出现于任何同步文件或日志。
 - **插件自动安装**：拉取差异时，备份里新增的插件会在确认导入时**自动安装**，无需在差异列表里逐项手动勾选；只有**版本冲突**的插件仍需要你决定「保留当前 / 采用备份」。
+- **密钥默认不同步**：同步载荷逐分区过 `SecretScanner`（敏感字段值剥离），凭据分区结构性排除。勾选「导出密钥」并设置加密密码后，`~/.dsh/.credentials.yaml` 以 scrypt + AES-256-GCM 密文作为**独立凭据载荷**随加密快照上行（不放进任何分区）；拉取侧解密后生成逐条「凭据迁移」项，你确认采纳才写回本机凭据（`credentials.set`）。加密密码仅存内存，绝不落盘 / 落日志；**自动同步恒不含凭据**（无密码可用，遇到加密快照会跳过）。
 
 ### 🛒 配置市场（Marketplace）
 

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/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

@@ -12,8 +12,12 @@ export type LocalPluginPackHook = (plugins: PluginEntry[], ctx: HostContext) =>
 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";
@@ -25,6 +29,12 @@ export declare class PluginsAdapter implements ConfigAdapter<PluginsSection> {
     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>;

package/lib/adapters/plugins.js

@@ -11,9 +11,13 @@
  * **不新增分区 id**）；导入时把 spec 重写为 `file:<解包后的绝对路径>` 再交给官方安装通道。
  */
 import { isDeepStrictEqual } from 'node:util';
+import { sha256Hex } from '../utils/hashing.js';
 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';
+import { isPathSafe, normalizePath } from '../utils/paths.js';
+import { PLUGIN_PATCH_REF_PREFIX } from '../core/backup.js';
+import { parsePnpmPatchedDependencies, sanitizePnpmWorkspacePatches } from './pnpm-workspace.js';
 export const USER_PATCH_FILE = 'cordis.patch.yml';
 /** tarball 字节 → base64（零依赖，避免 Buffer 在浏览器侧类型问题） */
 function bytesToBase64(data) {
@@ -64,8 +68,12 @@ async function writeLocalTarball(ctx, tarball) {
     const abs = `${ctx.target.homeDir.replace(/[\\/]+$/, '')}/${rel}`;
     return abs.replace(/\\/g, '/');
 }
+/** profile 目录相对 $DSH_HOME 的路径（patches/ 与 pnpm-workspace.yaml 都挂在这里）。 */
+export const PNPM_PROFILE_DIR = (profile) => `profiles/${profile !== undefined && profile !== '' ? profile : 'web'}`;
 /** pnpm-workspace.yaml 相对 $DSH_HOME 的路径（plugins 分区内按「插件安装配置」管理）。 */
-export const PNPM_WORKSPACE_REL = (profile) => `profiles/${profile !== undefined && profile !== '' ? profile : 'web'}/pnpm-workspace.yaml`;
+export const PNPM_WORKSPACE_REL = (profile) => `${PNPM_PROFILE_DIR(profile)}/pnpm-workspace.yaml`;
+/** 单个 patch 文件随备份迁移的体积上限（issue #35；patch 是纯文本，超过说明放错了东西）。 */
+export const MAX_PATCH_FILE_BYTES = 2 * 1024 * 1024;
 /** patch 行 raw 是否由其他 adapter 管理（mcp-client 行 / systemPrompt / planMode 行）。
  * 这些行的导入归 mcp.ts / prompts.ts，plugins 分区只负责普通用户行（启用/禁用/插入插件等）。 */
 function isManagedElsewhere(raw) {
@@ -155,6 +163,46 @@ export class PluginsAdapter {
         catch (err) {
             warnings.push(msgOf(ctx)('adapter.pnpmReadFailed', { reason: err instanceof Error ? err.message : String(err) }));
         }
+        // issue #35：`patchedDependencies` 引用的 patches/** 必须与声明同进同出。
+        // 只搬 pnpm-workspace.yaml 文本会让目标机拿到「声明在、文件不在」的组合，
+        // 此后 pnpm 拒绝**一切** add（含插件安装）——实测 13/13 插件安装全灭。
+        let patchFiles;
+        if (pnpmWorkspace !== null && pnpmWorkspace !== '') {
+            const parsed = parsePnpmPatchedDependencies(pnpmWorkspace);
+            if (parsed.unsupported !== null) {
+                warnings.push(msgOf(ctx)('adapter.pwPatchesUnsupported', { line: parsed.unsupported }));
+            }
+            const collected = [];
+            for (const decl of parsed.declared) {
+                const rel = normalizePath(decl.path);
+                if (rel === '' || !isPathSafe(rel)) {
+                    warnings.push(msgOf(ctx)('adapter.patchFileUnsafe', { name: decl.name, path: decl.path }));
+                    continue;
+                }
+                const homeRel = `${PNPM_PROFILE_DIR(ctx.profile)}/${rel}`;
+                try {
+                    if (!(await ctx.fs.exists(homeRel))) {
+                        warnings.push(msgOf(ctx)('adapter.patchFileMissing', { name: decl.name, path: rel }));
+                        continue;
+                    }
+                    const data = await ctx.fs.readFile(homeRel);
+                    if (data.byteLength > MAX_PATCH_FILE_BYTES) {
+                        warnings.push(msgOf(ctx)('adapter.patchFileTooLarge', {
+                            name: decl.name, path: rel, limit: `${Math.floor(MAX_PATCH_FILE_BYTES / 1024)} KiB`,
+                        }));
+                        continue;
+                    }
+                    collected.push({ relativePath: rel, base64: bytesToBase64(data) });
+                }
+                catch (err) {
+                    warnings.push(msgOf(ctx)('adapter.patchFileReadFailed', {
+                        name: decl.name, path: rel, reason: err instanceof Error ? err.message : String(err),
+                    }));
+                }
+            }
+            if (collected.length > 0)
+                patchFiles = collected;
+        }
         // T1：本地源（link:/file:）插件打包。这些 spec 指向本机路径，换机后必然不可达
         // （曾导致插件被静默丢失）。钩子由宿主注入；未注入 / 无本地源 / 单个失败一律不中断导出。
         let localTarballs;
@@ -188,21 +236,88 @@ export class PluginsAdapter {
                 patch,
                 pnpmWorkspace,
                 ...(localTarballs !== undefined ? { localTarballs } : {}),
+                ...(patchFiles !== undefined ? { patchFiles } : {}),
             },
             counts: {
                 plugins: effectivePlugins.length,
                 patchLines: patch.length,
                 ...(localTarballs !== undefined ? { localTarballs: localTarballs.length } : {}),
+                ...(patchFiles !== undefined ? { patchFiles: patchFiles.length } : {}),
             },
             warnings,
         };
     }
+    /**
+     * 导入后目标机**可能**存在的 patch 文件集合（相对 profile 目录）——issue #35。
+     * = 备份携带的 patchFiles ∪ 目标机本来就有的文件。只用于判定「声明能否被满足」，
+     * 不做任何写入（写入在 applyItem 内、且先于 pnpm-workspace.yaml）。
+     */
+    async patchAvailability(data, ctx) {
+        const set = new Set();
+        for (const pf of data.patchFiles ?? []) {
+            const rel = normalizePath(pf.relativePath);
+            if (rel !== '' && isPathSafe(rel))
+                set.add(rel);
+        }
+        const profileDir = PNPM_PROFILE_DIR(ctx.target.profile);
+        for (const decl of parsePnpmPatchedDependencies(data.pnpmWorkspace ?? '').declared) {
+            const rel = normalizePath(decl.path);
+            if (rel === '' || !isPathSafe(rel) || set.has(rel))
+                continue;
+            try {
+                if (await ctx.target.fs.exists(`${profileDir}/${rel}`))
+                    set.add(rel);
+            }
+            catch { /* 读不到 = 视为不存在 */ }
+        }
+        return set;
+    }
     async analyzeImport(data, ctx) {
         const msg = ctx.msg;
         const items = [];
         // pnpm-workspace.yaml：先于插件安装写入（allowBuilds / minimumReleaseAgeExclude 需在
         // pnpm add 时生效）。与目标不同 → Create/Update；无文件/内容一致 → Skip。
         if (data.pnpmWorkspace !== undefined && data.pnpmWorkspace !== null && data.pnpmWorkspace !== '') {
+            // issue #35：patch 文件项必须**先于** pnpm-workspace.yaml。
+            // 原因有二：① 配置里的 patchedDependencies 只有文件已就位才可用，先写配置会留下
+            // 「声明在、文件未到」的窗口（中途中断 → 目标机 pnpm 从此拒绝一切 add）；
+            // ② 它们是独立计划项（可被用户 keepCurrent 否决），配置项的写入不得越权替它们落盘。
+            // 作为计划项还有第三个作用：进入导入前快照（回滚可还原被覆盖的原文件）。
+            for (const pf of data.patchFiles ?? []) {
+                const rel = normalizePath(pf.relativePath);
+                if (rel === '' || !isPathSafe(rel))
+                    continue;
+                const id = `plugins:patch:${rel}`;
+                const abs = `${PNPM_PROFILE_DIR(ctx.target.profile)}/${rel}`;
+                let current = null;
+                try {
+                    current = await ctx.target.fs.exists(abs) ? await ctx.target.fs.readFile(abs) : null;
+                }
+                catch {
+                    current = null;
+                }
+                const target = { adapter: 'plugins', ref: `${PLUGIN_PATCH_REF_PREFIX}${rel}` };
+                if (current === null) {
+                    items.push({
+                        id, kind: 'Create', adapter: 'plugins',
+                        description: msg('adapter.patchFileCreate', { path: rel }), severity: 'info', target,
+                    });
+                }
+                else if (sha256Hex(current) === sha256Hex(base64ToBytes(pf.base64))) {
+                    items.push({ id, kind: 'Skip', adapter: 'plugins', description: msg('adapter.fileSame', { path: rel }), severity: 'info' });
+                }
+                else {
+                    items.push({
+                        id, kind: 'Conflict', adapter: 'plugins',
+                        description: msg('adapter.fileDiff', { path: rel }), severity: 'warning', target,
+                    });
+                }
+            }
+            // issue #35：目标机满足不了的 patchedDependencies 声明必须剔除——否则写进去之后，
+            // 目标机 pnpm 会因为「patch 文件读不到」拒绝**一切** add（含本次要装的插件）。
+            const available = await this.patchAvailability(data, ctx);
+            const clean = sanitizePnpmWorkspacePatches(data.pnpmWorkspace, (rel) => available.has(rel));
+            const droppedNames = clean.dropped.map((d) => d.name).join(', ');
             let current = null;
             try {
                 const rel = PNPM_WORKSPACE_REL(ctx.target.profile);
@@ -213,16 +328,38 @@ export class PluginsAdapter {
             catch {
                 current = null;
             }
-            if (current !== data.pnpmWorkspace) {
+            if (current !== clean.text) {
                 items.push({
                     id: 'plugins:pnpm-workspace',
                     kind: current === null ? 'Create' : 'Update',
                     adapter: 'plugins',
                     description: current === null ? msg('adapter.pwCreate') : msg('adapter.pwUpdate'),
+                    ...(clean.dropped.length > 0
+                        ? { detail: msg('adapter.pwPatchesDroppedDetail', { count: String(clean.dropped.length), names: droppedNames }) }
+                        : {}),
                     severity: 'info',
                     target: { adapter: 'plugins', ref: 'pnpm-workspace.yaml' },
                 });
             }
+            // 剔除是**可见**的信息项（不静默改变用户配置语义）
+            if (clean.dropped.length > 0) {
+                items.push({
+                    id: 'plugins:pnpm-workspace-dropped',
+                    kind: 'Warning',
+                    adapter: 'plugins',
+                    description: msg('adapter.pwPatchesDropped', { count: String(clean.dropped.length), names: droppedNames }),
+                    severity: 'warning',
+                });
+            }
+            if (clean.unsupported !== null) {
+                items.push({
+                    id: 'plugins:pnpm-workspace-flow',
+                    kind: 'Warning',
+                    adapter: 'plugins',
+                    description: msg('adapter.pwPatchesUnsupported', { line: clean.unsupported }),
+                    severity: 'warning',
+                });
+            }
         }
         // 插件：包名唯一键；同版本 Skip / 未装 Install / 版本不同 Conflict
         const targetInstalled = await ctx.target.plugins.listInstalled();
@@ -284,15 +421,65 @@ export class PluginsAdapter {
         const msg = ctx.msg;
         // pnpm-workspace.yaml：插件安装的 pnpm 配置（allowBuilds / minimumReleaseAgeExclude），
         // 必须先于任何插件安装写入，pnpm add 时才能生效。失败为非致命 warning。
+        // issue #35：patch 文件项（写入 profile 的 patches/ 目录；同时进入导入前快照，可回滚）
+        if (item.id.startsWith('plugins:patch:')) {
+            const ref = item.target?.ref;
+            if (ref === undefined || !ref.startsWith(PLUGIN_PATCH_REF_PREFIX)) {
+                return { ok: false, message: msg('adapter.missingTargetRef') };
+            }
+            const rel = normalizePath(ref.slice(PLUGIN_PATCH_REF_PREFIX.length));
+            if (rel === '' || !isPathSafe(rel)) {
+                return { ok: false, message: msg('adapter.patchFileUnsafe', { name: item.id, path: rel }) };
+            }
+            const data = ctx.sections.get('plugins');
+            const pf = data?.patchFiles?.find((p) => normalizePath(p.relativePath) === rel);
+            if (pf === undefined)
+                return { ok: false, message: msg('adapter.dataMissingFile', { ref: rel }) };
+            try {
+                await ctx.target.fs.writeFile(`${PNPM_PROFILE_DIR(ctx.target.profile)}/${rel}`, base64ToBytes(pf.base64));
+                return { ok: true };
+            }
+            catch (err) {
+                return {
+                    ok: false,
+                    warning: true,
+                    message: msg('adapter.patchFileWriteFailed', { path: rel, reason: err instanceof Error ? err.message : String(err) }),
+                };
+            }
+        }
         if (item.id === 'plugins:pnpm-workspace') {
             const data = ctx.sections.get('plugins');
             const text = data?.pnpmWorkspace;
             if (text === undefined || text === null || text === '') {
                 return { ok: false, message: msg('adapter.pwMissing') };
             }
+            // issue #35：判定「声明能否被满足」只看**此刻磁盘上的真实状态**——patch 文件项
+            // （`plugins:patch:*`）在计划里排在本项之前，已按用户决策落盘或保留原样。
+            // 这里**绝不**替它们写文件：那样会绕过用户在冲突项上的 keepCurrent 选择，
+            // 正是 issue #35 要消除的「静默覆盖」。
+            const profileDir = PNPM_PROFILE_DIR(ctx.target.profile);
+            const available = new Set();
+            for (const decl of parsePnpmPatchedDependencies(text).declared) {
+                const rel = normalizePath(decl.path);
+                if (rel === '' || !isPathSafe(rel) || available.has(rel))
+                    continue;
+                try {
+                    if (await ctx.target.fs.exists(`${profileDir}/${rel}`))
+                        available.add(rel);
+                }
+                catch { /* 读不到 = 视为不存在 */ }
+            }
+            const clean = sanitizePnpmWorkspacePatches(text, (rel) => available.has(rel));
             try {
-                await ctx.target.fs.writeFile(PNPM_WORKSPACE_REL(ctx.target.profile), new TextEncoder().encode(text));
-                return { ok: true, needsRestart: true, message: msg('adapter.pwWritten') };
+                await ctx.target.fs.writeFile(PNPM_WORKSPACE_REL(ctx.target.profile), new TextEncoder().encode(clean.text));
+                const notes = [msg('adapter.pwWritten')];
+                if (clean.dropped.length > 0) {
+                    notes.push(msg('adapter.pwWrittenPatchesDropped', {
+                        count: String(clean.dropped.length),
+                        names: clean.dropped.map((d) => d.name).join(', '),
+                    }));
+                }
+                return { ok: true, needsRestart: true, message: notes.join('；') };
             }
             catch (err) {
                 const reason = err instanceof Error ? err.message : String(err);

package/lib/adapters/pnpm-workspace.d.ts

@@ -0,0 +1,26 @@
+export interface PatchedDependency {
+    /** 依赖名（patchedDependencies 的键） */
+    name: string;
+    /** 声明的 patch 路径（相对 profile 目录，已去引号；原始写法保留） */
+    path: string;
+}
+export interface ParsePatchedResult {
+    declared: PatchedDependency[];
+    /** 无法安全改写的形态（如单行 flow 映射）→ 调用方据此告警，绝不猜着改 */
+    unsupported: string | null;
+}
+/** 解析 patchedDependencies 的声明（纯函数；不校验文件是否存在）。 */
+export declare function parsePnpmPatchedDependencies(text: string): ParsePatchedResult;
+export interface SanitizeResult {
+    /** 清理后的文本（无需修改时与入参逐字节相同） */
+    text: string;
+    declared: PatchedDependency[];
+    /** 被移除的条目（目标机没有对应 patch 文件） */
+    dropped: PatchedDependency[];
+    unsupported: string | null;
+}
+/**
+ * 删除 patchedDependencies 中「目标机不存在对应 patch 文件」的条目。
+ * @param available 判断某相对路径（相对 profile 目录）在**导入后**是否存在
+ */
+export declare function sanitizePnpmWorkspacePatches(text: string, available: (relPath: string) => boolean): SanitizeResult;