dsh-config-manager 0.1.78 → 0.1.80

package/src/adapters/mcp.ts

@@ -18,10 +18,16 @@ import type { McpServerEntry } from '../schema/types.ts';
 import { sectionMeta } from '../schema/section-registry.ts';
 import { validateJsonSection } from './json-section.ts';
 import type {
-  ApplyResult, ConfigAdapter, ExportOptions, ExportSection, HostContext,
+  ApplyResult, ConfigAdapter, ExportOptions, ExportSection, ExportUnit, HostContext,
   ImportContext, PlanItem, ValidationResult,
 } from '../core/types.ts';
 import { locatePatchLineLayer, readEffectivePatchLines, resolveWriteLayer } from '../core/patch-layers.ts';
+import {
+  MCP_CONNECTOR_STORE_REL, buildConnectorRecord, comparableConnector, exportConnectorBlock,
+  findConnectorRecord, mergeConnectorIntoStoreText, pickConnectorKey, readConnectorStore,
+  refillFieldsOf,
+} from '../core/mcp-connector-store.ts';
+import type { ConnectorExportEntry, McpConnectorExport } from '../core/mcp-connector-store.ts';
 
 /** 导出记录：McpServerEntry 之外附加来源 patch 行 id 与所在层（导入写回定位用） */
 export interface McpExportEntry extends McpServerEntry {
@@ -33,7 +39,17 @@ export interface McpExportEntry extends McpServerEntry {
   sourceFile?: string;
 }
 
-export interface McpExportSection { version: 1; servers: McpExportEntry[]; }
+export interface McpExportSection {
+  version: 1;
+  servers: McpExportEntry[];
+  /**
+   * MCP 连接器（\`dsh-mcp-connector\` 插件）的连接，第二个数据源。
+   *
+   * 为什么并列而不是新增分区：两条路径在 DSH 里都是「MCP 服务器」，用户心智里是一件事；
+   * 而备份格式是追加字段 ⇒ 旧备份没有它 = 空，读旧包的代码不受影响。
+   */
+  connectors?: McpConnectorExport;
+}
 
 /**
  * 从 patch 行数组中提取 MCP server 条目（以 config.serverName 存在为判定）。
@@ -97,11 +113,60 @@ export function buildMcpPatchLine(lineId: string, server: McpServerEntry): Recor
   return { id: lineId, name: 'dsh-mcp-client', config };
 }
 
+/** 连接器计划项的 id 前缀（导入时按前缀分派到 applyConnectorItem） */
+const MCP_CONNECTOR_ITEM_PREFIX = 'mcp-connector:';
+
+/** 计划项 detail：stdio 给命令 + 参数，http 给 URL（不打印任何 header/env 值，防凭据入日志） */
+function describeConnector(entry: ConnectorExportEntry): string {
+  const head = entry.transport === 'stdio'
+    ? [entry.command ?? '', ...(entry.args ?? [])].filter((s) => s !== '').join(' ')
+    : (entry.url ?? '');
+  return `${entry.transport} ${head}`.trim().slice(0, 200);
+}
+
 function newLineId(serverName: string): string {
   const slug = serverName.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
   return `mcp-${slug || 'server'}`;
 }
 
+/**
+ * 单元 id：两条数据源各自独立前缀。
+ *
+ * 为什么必须分开：patch 行的 `serverName` 与连接器的 `serverName` 完全可能同名（同一台服务器的两条
+ * 历史配置路径），共用 id 会让「勾了其中一个」变成「两个一起勾」，与选择器「逐项可勾」的前提冲突。
+ * 命名空间仍以 `mcp:` 开头 —— 与 ExportUnit 的「<section>:<单元>」约定一致。
+ */
+export function mcpServerUnitId(serverName: string): string {
+  return 'mcp:patch:' + serverName
+}
+
+export function mcpConnectorUnitId(key: string): string {
+  return 'mcp:connector:' + key
+}
+
+/** 单元体积 = 该条目在包里的 UTF-8 字节数（与 /export-preview 对 JSON 分区的口径一致） */
+function unitBytes(value: unknown): number {
+  return new TextEncoder().encode(JSON.stringify(value) ?? '').byteLength
+}
+
+/** 只读的 stdio 描述（命令 + 参数），不打印任何 env / header 值 */
+function stdioDetail(entry: { command?: string; args?: string[] }): string {
+  return [entry.command ?? '', ...(entry.args ?? [])].filter((s) => s !== '').join(' ').slice(0, 200)
+}
+
+/**
+ * 连接器整块的条目级过滤。
+ *
+ * allow === undefined = 全量（旧调用方零改动）；过滤后一条不剩 → 返回 undefined，
+ * 让 `connectors` 字段整个消失（而不是留一个空块冒充「连接器已备份」）。
+ */
+function filterConnectorBlock(block: McpConnectorExport, allow: readonly string[] | undefined): McpConnectorExport | undefined {
+  if (allow === undefined) return block
+  const connections = block.connections.filter((c) => allow.includes(mcpConnectorUnitId(c.key)))
+  const oauthConnections = block.oauthConnections.filter((c) => allow.includes(mcpConnectorUnitId(c.key)))
+  if (connections.length === 0 && oauthConnections.length === 0) return undefined
+  return { ...block, connections, oauthConnections }
+}
 export class McpAdapter implements ConfigAdapter<McpExportSection> {
   readonly id = 'mcp' as const;
   // 元数据唯一来源 = 注册表（t31）：不再与 ui/export-flow.ts 的导出目录各写一份
@@ -109,7 +174,7 @@ export class McpAdapter implements ConfigAdapter<McpExportSection> {
   readonly defaultIncluded = sectionMeta('mcp').defaultIncluded;
   readonly portability = sectionMeta('mcp').portability;
 
-  async export(ctx: HostContext, _options: ExportOptions): Promise<ExportSection<McpExportSection>> {
+  async export(ctx: HostContext, options: ExportOptions): Promise<ExportSection<McpExportSection>> {
     const warnings: string[] = [];
     // issue #71：两层都读（home 层优先），否则 profile 层里的 server 全部丢失
     const read = await readEffectivePatchLines(ctx.patchFile, ctx.profile);
@@ -117,14 +182,90 @@ export class McpAdapter implements ConfigAdapter<McpExportSection> {
       warnings.push(msgOf(ctx)('adapter.patchReadFailedMCP', { reason: `${f.file}: ${f.reason}` }));
     }
     const servers = extractMcpServers(read.lines);
+    // 条目级白名单：undefined = 整分区全量（旧调用方零改动）；空数组 = 一条都不带。
+    // 选择器把「部分勾选」翻译成 includeItems['mcp']，这里必须如实过滤，否则勾了等于没勾。
+    const allow = options.includeItems?.[this.id];
+    const pickedServers = allow === undefined
+      ? servers
+      : servers.filter((s) => allow.includes(mcpServerUnitId(s.serverName)));
+    // 第二个数据源：连接器插件的 `storages/mcp_connector.json`（用户实际配置 MCP 的地方）。
+    // 读不到 = 本机没装/没用连接器（正常，静默）；读到了解析不了 = 异常，如实报 warning，
+    // **绝不**当作空表导出 —— 否则用户以为备份里有，恢复时才发现丢了。
+    let connectors: McpConnectorExport | undefined;
+    try {
+      const store = await readConnectorStore(ctx.fs);
+      if (store.exists && !store.parsed) {
+        warnings.push(msgOf(ctx)('adapter.mcpConnectorReadFailed', { reason: store.error ?? 'unknown' }));
+      } else if (store.exists && store.parsed) {
+        // 文件不存在 = 本机没有任何连接器：不写这个字段（旧备份也没有它，形状保持一致）
+        connectors = filterConnectorBlock(exportConnectorBlock(store.connections), allow);
+      }
+    } catch (err) {
+      warnings.push(msgOf(ctx)('adapter.mcpConnectorReadFailed', { reason: err instanceof Error ? err.message : String(err) }));
+    }
+    const data: McpExportSection = { version: 1, servers: pickedServers };
+    if (connectors !== undefined) data.connectors = connectors;
     return {
       sectionId: 'mcp',
-      data: { version: 1, servers },
-      counts: { servers: servers.length },
+      data,
+      counts: {
+        servers: pickedServers.length,
+        ...(connectors !== undefined ? { connectors: connectors.connections.length } : {}),
+      },
       warnings,
     };
   }
 
+  /**
+   * 条目级单元清单（选择器靠它决定「能不能展开」）。
+   *
+   * 契约（core/types.ts:1211）：纯函数、零 I/O，且必须与 export(includeItems) 自洽 ——
+   * 单元 id 就是 export 白名单里认的 id，两边共用 mcpServerUnitId / mcpConnectorUnitId。
+   *
+   * 单元 label 与 detail 只放「能帮用户认出是哪条」的信息：连接器的 detail 复用
+   * describeConnector（stdio 给命令 + 参数、http 给 URL），**绝不**带出 env / header 值。
+   */
+  listUnits(section: ExportSection<McpExportSection>): ExportUnit[] {
+    const units: ExportUnit[] = [];
+    const seen = new Set<string>();
+    for (const server of section.data.servers ?? []) {
+      const id = mcpServerUnitId(server.serverName);
+      if (seen.has(id)) continue;
+      seen.add(id);
+      units.push({
+        id,
+        label: server.serverName,
+        detail: server.type === 'stdio' ? stdioDetail(server) : (server.url ?? ''),
+        sizeBytes: unitBytes(server),
+      });
+    }
+    const connectors = section.data.connectors;
+    for (const connection of connectors?.connections ?? []) {
+      const id = mcpConnectorUnitId(connection.key);
+      if (seen.has(id)) continue;
+      seen.add(id);
+      units.push({
+        id,
+        label: connection.name,
+        detail: describeConnector(connection),
+        sizeBytes: unitBytes(connection),
+      });
+    }
+    for (const oauth of connectors?.oauthConnections ?? []) {
+      const id = mcpConnectorUnitId(oauth.key);
+      if (seen.has(id)) continue;
+      seen.add(id);
+      units.push({
+        id,
+        label: oauth.name,
+        // OAuth 连接只带引用（Token 永不进备份），detail 说明它靠重新授权才能用
+        detail: 'oauth ' + oauth.serverName,
+        sizeBytes: unitBytes(oauth),
+      });
+    }
+    return units;
+  }
+
   async analyzeImport(data: McpExportSection, ctx: ImportContext): Promise<PlanItem[]> {
     const msg = ctx.msg;
     const items: PlanItem[] = [];
@@ -166,10 +307,92 @@ export class McpAdapter implements ConfigAdapter<McpExportSection> {
         }
       }
     }
+    items.push(...await this.analyzeConnectors(data, ctx));
+    return items;
+  }
+
+  /**
+   * 连接器来源的计划项。
+   *
+   * 三条纪律：
+   *  ① 目标存储「存在但解析不了」→ 只报 warning、**零写入**（整文件改写会把 grants 等表一起抹掉）；
+   *  ② 条目里还有占位符 → 不写，产出「需重填凭据」的 warning（写进去 = 给用户一个起不来的 Server）；
+   *  ③ 同名 server 同时来自 patch 行与连接器 → 两条都保留，另加一条 warning（不隐式合并，
+   *     两者在 DSH 里是两份独立配置，合并会悄悄改变用户的生效结果）。
+   */
+  private async analyzeConnectors(data: McpExportSection, ctx: ImportContext): Promise<PlanItem[]> {
+    const msg = ctx.msg;
+    const block = data.connectors;
+    if (block === undefined) return [];
+    const items: PlanItem[] = [];
+    const target = await readConnectorStore(ctx.target.fs);
+    if (target.exists && !target.parsed) {
+      items.push({
+        id: 'mcp-connector:store',
+        kind: 'Warning',
+        adapter: 'mcp',
+        description: msg('adapter.mcpConnectorTargetUnreadable', { reason: target.error ?? 'unknown' }),
+        severity: 'warning',
+      });
+    }
+    const writable = target.parsed;
+    for (const entry of block.connections ?? []) {
+      const id = `mcp-connector:${entry.key}`;
+      // 双来源同名：告诉用户「这条连接和 patch 行里的同名 server 是两份」，不替用户做决定。
+      // 放在「需重填」判断**之前**——两条事实都要讲，不能因为一条要重填就吞掉另一条。
+      if (data.servers.some((s) => s.serverName === entry.serverName)) {
+        items.push({
+          id: `mcp-connector-name:${entry.key}`,
+          kind: 'Warning', adapter: 'mcp',
+          description: msg('adapter.mcpConnectorDuplicateName', { serverName: entry.serverName }),
+          severity: 'warning',
+        });
+      }
+      const refill = refillFieldsOf(entry);
+      if (refill.length > 0) {
+        items.push({
+          id, kind: 'Warning', adapter: 'mcp',
+          description: msg('adapter.mcpConnectorNeedsRefill', { name: entry.name }),
+          detail: refill.join(', '),
+          severity: 'warning',
+        });
+        continue;
+      }
+      if (!writable) continue;
+      const existing = findConnectorRecord(target.connections, entry);
+      const detail = describeConnector(entry);
+      if (existing === undefined) {
+        items.push({
+          id, kind: 'Create', adapter: 'mcp',
+          description: msg('adapter.mcpConnectorCreate', { name: entry.name }),
+          detail,
+          severity: 'info',
+          target: { adapter: 'mcp', ref: MCP_CONNECTOR_STORE_REL },
+        });
+      } else if (isDeepStrictEqual(comparableConnector(existing), comparableConnector(entry))) {
+        items.push({ id, kind: 'Skip', adapter: 'mcp', description: msg('adapter.mcpConnectorSame', { name: entry.name }), severity: 'info' });
+      } else {
+        items.push({
+          id, kind: 'Conflict', adapter: 'mcp',
+          description: msg('adapter.mcpConnectorDiff', { name: entry.name }),
+          detail: `current=${JSON.stringify(comparableConnector(existing))} imported=${JSON.stringify(comparableConnector(entry))}`.slice(0, 200),
+          severity: 'warning',
+          target: { adapter: 'mcp', ref: MCP_CONNECTOR_STORE_REL },
+        });
+      }
+    }
+    for (const oauth of block.oauthConnections ?? []) {
+      items.push({
+        id: `mcp-connector:${oauth.key}`, kind: 'Warning', adapter: 'mcp',
+        description: msg('adapter.mcpConnectorOauth', { name: oauth.name }),
+        severity: 'warning',
+      });
+    }
     return items;
   }
 
   async applyItem(item: PlanItem, ctx: ImportContext): Promise<ApplyResult> {
+    if (item.id.startsWith(MCP_CONNECTOR_ITEM_PREFIX)) return this.applyConnectorItem(item, ctx);
     const msg = ctx.msg;
     const serverName = item.id.replace(/^mcp:/, '');
     const data = ctx.sections.get('mcp') as McpExportSection | undefined;
@@ -189,6 +412,39 @@ export class McpAdapter implements ConfigAdapter<McpExportSection> {
     return { ok: true, needsRestart: true, message: msg('adapter.mcpWritten', { serverName }) };
   }
 
+  /**
+   * 写入一条连接：读全文件 → 只替换 `tables.connections[<key>]` → 整文件原子写。
+   *
+   * 为什么整文件写而不是走宿主 storage 服务：本机没装 `@deepseek-ai/dsh-storage-domain`，
+   * 我们拿不到 `mcp_connector` 域的表句柄；而直接改文件又会被运行中的宿主内存态覆盖 ⇒
+   * 计划项与本结果都显式要求重启（needsRestart），写之前先把原文件整体快照（引擎侧按
+   * `storages/` 前缀走文件类快照）。
+   */
+  private async applyConnectorItem(item: PlanItem, ctx: ImportContext): Promise<ApplyResult> {
+    const msg = ctx.msg;
+    const key = item.id.slice(MCP_CONNECTOR_ITEM_PREFIX.length);
+    const data = ctx.sections.get('mcp') as McpExportSection | undefined;
+    const entry = data?.connectors?.connections.find((c) => c.key === key);
+    if (entry === undefined) return { ok: false, message: msg('adapter.mcpConnectorMissing', { name: key }) };
+    const refill = refillFieldsOf(entry);
+    if (refill.length > 0) {
+      return { ok: false, message: msg('adapter.mcpConnectorNeedsRefill', { name: entry.name }) };
+    }
+    const store = await readConnectorStore(ctx.target.fs);
+    if (store.exists && !store.parsed) {
+      return { ok: false, message: msg('adapter.mcpConnectorTargetUnreadable', { reason: store.error ?? 'unknown' }) };
+    }
+    const existing = findConnectorRecord(store.connections, entry);
+    const record = buildConnectorRecord(entry, {
+      existing,
+      key: pickConnectorKey(store.connections, entry),
+      now: Date.now(),
+    });
+    const text = mergeConnectorIntoStoreText(store, record);
+    await ctx.target.fs.writeFile(MCP_CONNECTOR_STORE_REL, new TextEncoder().encode(text));
+    return { ok: true, needsRestart: true, message: msg('adapter.mcpConnectorWritten', { name: entry.name }) };
+  }
+
   async validate(data: McpExportSection, msg: MsgFunc = zhMsg): Promise<ValidationResult> {
     return validateJsonSection<McpExportSection>('mcp', data, msg, (section, issues) => {
       if (!Array.isArray(section.servers)) {
@@ -200,6 +456,21 @@ export class McpAdapter implements ConfigAdapter<McpExportSection> {
           }
         }
       }
+      // connectors 是**可选追加字段**：旧备份没有它 = 合法；有它但形态不对才算错
+      const connectors = section.connectors;
+      if (connectors !== undefined) {
+        if (connectors === null || typeof connectors !== 'object' || !Array.isArray((connectors as { connections?: unknown }).connections)) {
+          issues.push({ path: 'connectors.connections', message: msg('adapter.validate.array', { subject: 'connectors.connections' }), severity: 'error' });
+        } else {
+          for (const c of (connectors as { connections: unknown[] }).connections) {
+            if (c === null || typeof c !== 'object'
+              || typeof (c as { key?: unknown }).key !== 'string' || (c as { key: string }).key === ''
+              || typeof (c as { serverName?: unknown }).serverName !== 'string' || (c as { serverName: string }).serverName === '') {
+              issues.push({ path: 'connectors.connections[]', message: msg('adapter.mcpConnectorInvalid'), severity: 'error' });
+            }
+          }
+        }
+      }
     });
   }
 }

package/src/adapters/messages.ts

@@ -35,6 +35,10 @@ export const zh = {
   'adapter.pluginDataEnvOverridden': '{path} 的位置被环境变量 {env} 覆盖，本次已跳过（不猜它指向哪里）',
   'adapter.pluginDataPathNotAllowed': '路径不在第三方插件数据的允许范围内，已拒绝写入: {path}',
   'adapter.pluginDataNoOsHome': '第三方插件的数据在系统主目录下，但当前宿主没有提供该目录的文件通道（旧版本宿主）：本次不读取也不导入 / third-party plugin data lives under the system home directory, but this host offers no file channel for it (older host): nothing is read or imported this time',
+  // ---------- pnpm 配置可移植净化（机器相关路径键） ----------
+  'adapter.pwMachinePathStripped': '已剥离 {count} 条与本机路径绑定的 pnpm 设置（换机后会指向不存在的目录）：{keys}',
+  'adapter.pwMachinePathKept': '保留本机原有的 {count} 条 pnpm 路径设置（不搬运来源机的路径）：{keys}',
+  'adapter.pwLocalReadFailed': '读取本机 pnpm-workspace.yaml 失败：{reason}（未写入 —— 避免把本机自己的 pnpm 路径设置清掉）',
 } as const;
 
 export const en: Record<keyof typeof zh, string> = {
@@ -53,6 +57,9 @@ export const en: Record<keyof typeof zh, string> = {
   'adapter.pluginDataEnvOverridden': "the location of {path} is overridden by the {env} environment variable; skipped this time (the new location is never guessed)",
   'adapter.pluginDataPathNotAllowed': 'the path is outside the range allowed for third-party plugin data and was refused: {path}',
   'adapter.pluginDataNoOsHome': 'third-party plugin data lives under the system home directory, but this host offers no file channel for it (older host): nothing is read or imported this time',
+  'adapter.pwMachinePathStripped': 'Stripped {count} pnpm setting(s) bound to machine-specific paths (they would point to non-existent directories on another machine): {keys}',
+  'adapter.pwMachinePathKept': "Kept this machine's own {count} pnpm path setting(s) (the source machine's paths are never carried over): {keys}",
+  'adapter.pwLocalReadFailed': "Failed to read the local pnpm-workspace.yaml: {reason} (nothing was written, so this machine's own pnpm path settings are not dropped)",
 };
 
 registerMessageCatalog({ id: 'adapters-domain', zh, en });

package/src/adapters/plugin-files.ts

@@ -110,7 +110,8 @@ export class PluginFilesAdapter implements ConfigAdapter<FilesSection> {
 
   /** 单元清单（零 I/O）：逐文件单元，id 与导入侧 `pluginFiles:<relPath>` 一致。 */
   listUnits(section: ExportSection<FilesSection>): ExportUnit[] {
-    return unitsFromFiles(this.id, section.data.files, (rel) => rel);
+    // files 可能缺省（空分区 / 手写 section）：按空表处理，不抛错 —— 选择器对任何分区都会调 listUnits
+    return unitsFromFiles(this.id, section.data.files ?? [], (rel) => rel);
   }
 
   async analyzeImport(data: FilesSection, ctx: ImportContext): Promise<PlanItem[]> {

package/src/adapters/plugins.test.ts

@@ -292,7 +292,7 @@ test('plugins: applyItem Install → needsRestart（官方机制，不打包二
   assert.ok(dst.plugins.installed.has('need-install'), '经 installPlugin 门面写入');
 });
 
-test('plugins: 非 registry spec（github:）随导入传给 install，registry 包不传 spec', async () => {
+test('plugins: 安装目标按 pluginInstallTarget 推导 —— github: 原样、registry 精确版本（issue #101）', async () => {
   const src = makeContext('win32', 'C:\\Users\\alice');
   src.plugins.installed.set('dsh-memory-evolve', { name: 'dsh-memory-evolve', version: '1.0.0', enabled: true, spec: 'github:csyangwen/dsh-memory-evolve' });
   src.plugins.installed.set('dshmarket', { name: 'dshmarket', version: '1.0.3', enabled: true, spec: '^1.0.3' });
@@ -306,7 +306,7 @@ test('plugins: 非 registry spec（github:）随导入传给 install，registry
   assert.equal(dst.plugins.lastSpec, 'github:csyangwen/dsh-memory-evolve', 'github: spec 必须原样传给安装通道');
 
   await adapter.applyItem(items.find((i) => i.id === 'plugin:dshmarket')!, makeImportContext(dst, sections));
-  assert.equal(dst.plugins.lastSpec, '^1.0.3', 'registry 版本区间也透传（由门面决定按裸名装最新）');
+  assert.equal(dst.plugins.lastSpec, 'dshmarket@1.0.3', '备份里有具体版本 → 精确安装（裸包名会被目标机既有 spec 挡住，issue #101）');
 });
 
 test('plugins: 安装失败 → 非致命 warning（§34.17，不触发整体回滚）', async () => {
@@ -355,6 +355,42 @@ test('plugins: 版本冲突 useImported → Update 走安装通道，失败同
   assert.equal(rFail.ok, false);
   assert.equal(rFail.warning, true, '更新失败同样为非致命 warning');
 });
+test('plugins: 安装后回读版本与备份不一致 → warning + 可复制的精确安装命令（issue #101）', async () => {
+  const src = makeContext('win32', 'C:\\Users\\alice');
+  src.plugins.installed.set('pkg-b', { name: 'pkg-b', version: '2.0.0', enabled: true });
+  const adapter = new PluginsAdapter();
+  const exported = await adapter.export(src, { includeSecrets: false });
+  const sections = new Map([['plugins', exported.data]]);
+
+  const dst = makeContext('linux', '/home/bob', 'web');
+  dst.plugins.installed.set('pkg-b', { name: 'pkg-b', version: '1.5.0', enabled: true });
+  const items = await adapter.analyzeImport(exported.data, makeImportContext(dst, sections));
+  const conflict = items.find((i) => i.id === 'plugin:pkg-b');
+  assert.equal(conflict?.kind, 'Conflict');
+  const updateItem: PlanItem = { ...conflict!, kind: 'Update', conflict: { itemId: conflict!.id, resolution: 'useImported' } };
+
+  // 子进程退出 0，但 pnpm 尊重了目标机既有 spec、什么都没换（真机空转形态）
+  dst.plugins.install = async (): Promise<{ needsRestart: boolean; installedVersion?: string | null }> => ({
+    needsRestart: true,
+    installedVersion: '1.5.0',
+  });
+  const stale = await adapter.applyItem(updateItem, makeImportContext(dst, sections));
+  assert.equal(stale.ok, false, '版本没落地就不能报 done');
+  assert.equal(stale.warning, true, '非致命：其余配置已导入');
+  assert.match(stale.message ?? '', /1\.5\.0/, '必须写出实际装成的版本');
+  assert.match(stale.message ?? '', /2\.0\.0/, '必须写出备份记录的版本');
+  assert.match(stale.message ?? '', /dsh plugin --profile web add pkg-b@2\.0\.0/, '给可复制的手动精确安装命令');
+
+  // 同一个计划项在版本真的落地时应判成功并写明版本
+  dst.plugins.install = async (): Promise<{ needsRestart: boolean; installedVersion?: string | null }> => ({
+    needsRestart: true,
+    installedVersion: '2.0.0',
+  });
+  const done = await adapter.applyItem(updateItem, makeImportContext(dst, sections));
+  assert.equal(done.ok, true);
+  assert.match(done.message ?? '', /2\.0\.0/, '成功文案必须带实际版本，便于用户核对');
+});
+
 /* ---------------- preview：只读预览不得触发任何本地源打包（总览慢的根因） ---------------- */
 
 test('plugins: preview 不调用打包钩子，但条目/白名单/告警与 export 同口径', async () => {
@@ -729,3 +765,141 @@ test('issue #95：目标清单缺失 / JSON 坏 / 形态不符 → 只告警，
   assert.equal(itemsC[0]?.kind, 'Warning');
   assert.match(itemsC[0]?.description ?? '', /形态/);
 });
+
+/* ---------------- ④ 可移植性净化：机器相关 pnpm 路径不随快照搬家 ---------------- */
+
+const MACHINE_WS = [
+  'storeDir: D:/pnpm-store',
+  'cacheDir: D:/pnpm-cache',
+  'nodeLinker: hoisted',
+  'allowBuilds:',
+  '  ssh2: true',
+  '',
+].join('\n');
+/** 剥离机器路径键之后应当逐字剩下的内容 */
+const PORTABLE_WS = ['nodeLinker: hoisted', 'allowBuilds:', '  ssh2: true', ''].join('\n');
+
+test('④ 可移植性：导出剥离机器相关 pnpm 路径键（其余逐字不变），且剥离可见', async () => {
+  const src = makeContext('win32', 'C:\\Users\\alice', 'web');
+  await src.fs.writeFile('profiles/web/pnpm-workspace.yaml', new TextEncoder().encode(MACHINE_WS));
+  const adapter = new PluginsAdapter();
+  const out = await adapter.export(src, { includeSecrets: false });
+  assert.equal(out.data.pnpmWorkspace, PORTABLE_WS, '机器路径键整行剥离，其余内容逐字不变');
+  assert.ok(
+    out.warnings.some((w) => w.includes('storeDir') && w.includes('cacheDir')),
+    `剥离必须走既有告警通道（不静默改写）: ${out.warnings.join(' | ')}`,
+  );
+
+  // 目标机全新（没有本机设置可保留）→ Create，且回填的文本里没有导出机路径
+  const dst = makeContext('linux', '/home/bob', 'web');
+  const sections = new Map([['plugins', out.data]]);
+  const items = await adapter.analyzeImport(out.data, makeImportContext(dst, sections));
+  const wsItem = items.find((i) => i.id === 'plugins:pnpm-workspace');
+  assert.equal(wsItem?.kind, 'Create');
+  const applied = await adapter.applyItem(wsItem!, makeImportContext(dst, sections));
+  assert.equal(applied.ok, true);
+  const written = new TextDecoder().decode(dst.fs.files.get('/home/bob/profiles/web/pnpm-workspace.yaml')!);
+  assert.equal(written, PORTABLE_WS);
+  assert.equal(written.includes('D:/pnpm-store'), false, '回填不得写入导出机路径');
+});
+
+test('④ 可移植性：老载荷仍带导出机路径 → 写回侧再剥一次；本机自己的设置保留、导出机路径不落地', async () => {
+  // 老版本备份（收集侧还没有净化）里带着来源机的路径键
+  const data: PluginsSection = {
+    version: 1,
+    plugins: [],
+    patch: [],
+    pnpmWorkspace: 'storeDir: /home/alice/pnpm-store\ncacheDir: /home/alice/.cache/pnpm\nnodeLinker: hoisted\n',
+  };
+  const adapter = new PluginsAdapter();
+  const dst = makeContext('linux', '/home/bob', 'web');
+  await dst.fs.writeFile(
+    'profiles/web/pnpm-workspace.yaml',
+    new TextEncoder().encode('storeDir: /home/bob/pnpm-store\nnodeLinker: isolated\n'),
+  );
+  const sections = new Map([['plugins', data]]);
+  const items = await adapter.analyzeImport(data, makeImportContext(dst, sections));
+  const wsItem = items.find((i) => i.id === 'plugins:pnpm-workspace');
+  assert.equal(wsItem?.kind, 'Update');
+  assert.ok(wsItem?.detail?.includes('已剥离'), `剥离必须走既有可见通道（detail）: ${wsItem?.detail}`);
+  assert.ok(wsItem?.detail?.includes('storeDir'), '保留本机设置也要说清');
+  const applied = await adapter.applyItem(wsItem!, makeImportContext(dst, sections));
+  assert.equal(applied.ok, true);
+  const written = new TextDecoder().decode(dst.fs.files.get('/home/bob/profiles/web/pnpm-workspace.yaml')!);
+  assert.equal(written, 'nodeLinker: hoisted\nstoreDir: /home/bob/pnpm-store\n');
+  assert.equal(written.includes('/home/alice'), false, '导出机的机器路径绝不落地');
+  assert.equal(written.includes('cacheDir'), false, '导出机独有的键不得带到本机');
+  assert.ok(applied.message?.includes('storeDir'), `写入结果也要说出来: ${applied.message}`);
+});
+
+test('④ 可移植性：只差机器路径行（本机设置接回后与现文本同义）→ 不生成计划项、零写入', async () => {
+  const dst = makeContext('linux', '/home/bob', 'web');
+  await dst.fs.writeFile(
+    'profiles/web/pnpm-workspace.yaml',
+    new TextEncoder().encode('nodeLinker: hoisted\nstoreDir: /home/bob/pnpm-store\n'),
+  );
+  const data: PluginsSection = {
+    version: 1,
+    plugins: [],
+    patch: [],
+    pnpmWorkspace: 'storeDir: /home/alice/pnpm-store\nnodeLinker: hoisted\n',
+  };
+  const adapter = new PluginsAdapter();
+  const items = await adapter.analyzeImport(data, makeImportContext(dst, new Map([['plugins', data]])));
+  assert.equal(
+    items.some((i) => i.id === 'plugins:pnpm-workspace'),
+    false,
+    '语义一致 ⇒ 不打扰用户、也不产生无意义的改写',
+  );
+});
+
+test('④ 可移植性：载荷剥完只剩空内容（来源机配置全是机器路径）→ 不产出空文件项', async () => {
+  const dst = makeContext('linux', '/home/bob', 'web');
+  const data: PluginsSection = { version: 1, plugins: [], patch: [], pnpmWorkspace: 'storeDir: /home/alice/pnpm-store\n' };
+  const adapter = new PluginsAdapter();
+  const items = await adapter.analyzeImport(data, makeImportContext(dst, new Map([['plugins', data]])));
+  assert.equal(items.some((i) => i.id === 'plugins:pnpm-workspace'), false, '没有可移植内容 ⇒ 不写空文件');
+  assert.equal(await dst.fs.exists('profiles/web/pnpm-workspace.yaml'), false, '零写入');
+});
+
+test('④ 可移植性：CRLF 的 pnpm-workspace.yaml 剥离后仍是 CRLF（无 EOL 漂移）', async () => {
+  const src = makeContext('win32', 'C:\\Users\\alice', 'web');
+  await src.fs.writeFile(
+    'profiles/web/pnpm-workspace.yaml',
+    new TextEncoder().encode('storeDir: D:/pnpm-store\r\nnodeLinker: hoisted\r\n'),
+  );
+  const out = await new PluginsAdapter().export(src, { includeSecrets: false });
+  assert.equal(out.data.pnpmWorkspace, 'nodeLinker: hoisted\r\n');
+});
+
+test('④ 可移植性：本机 pnpm-workspace.yaml 存在但读不出来 → 显式失败且零写入（不静默丢本机设置）', async () => {
+  const dst = makeContext('linux', '/home/bob', 'web');
+  const local = 'storeDir: /home/bob/pnpm-store\n';
+  await dst.fs.writeFile('profiles/web/pnpm-workspace.yaml', new TextEncoder().encode(local));
+  const data: PluginsSection = { version: 1, plugins: [], patch: [], pnpmWorkspace: 'nodeLinker: hoisted\n' };
+  const adapter = new PluginsAdapter();
+  const ctx = makeImportContext(dst, new Map([['plugins', data]]));
+  ctx.target.fs.exists = async () => true;
+  ctx.target.fs.readFile = async () => {
+    const e = new Error('EACCES: permission denied') as Error & { code?: string };
+    e.code = 'EACCES';
+    throw e;
+  };
+  const item: PlanItem = {
+    id: 'plugins:pnpm-workspace',
+    kind: 'Update',
+    adapter: 'plugins',
+    description: 'x',
+    severity: 'info',
+    target: { adapter: 'plugins', ref: 'pnpm-workspace.yaml' },
+  };
+  const applied = await adapter.applyItem(item, ctx);
+  assert.equal(applied.ok, false);
+  assert.equal(applied.warning, true);
+  assert.ok(applied.message?.includes('EACCES'), `失败原因要如实回报: ${applied.message}`);
+  assert.equal(
+    new TextDecoder().decode(dst.fs.files.get('/home/bob/profiles/web/pnpm-workspace.yaml')!),
+    local,
+    '读不到就不写：本机文件逐字不动',
+  );
+});