@logictan/dsh-config-manager 0.1.60 → 0.1.61

package/lib/core/backup.js

@@ -9,6 +9,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import { parseJsonSafe } from '../utils/json.js';
+import { parsePatchLayerKey } from './patch-layers.js';
 import { sha256Hex } from '../utils/hashing.js';
 import { normalizePath } from '../utils/paths.js';
 import { atomicWriteFile } from '../utils/atomic-write.js';
@@ -180,10 +181,11 @@ async function engineSnapshotEntry(ctx, target) {
                     copiedTo: `blobs/${crypto.randomUUID()}`,
                 };
             }
-            // patchLine：从组合 patch 文件读取原行（file 为必填的 file 字段约定为 'cordis.patch.yml'）
-            const file = 'cordis.patch.yml';
+            // patchLine：ref 是层限定复合键（<file>#<lineId>），据此到**对应层**读原行。
+            // 旧快照的裸 lineId 由 parsePatchLayerKey 兼容为 home 层。
+            const { file, lineId } = parsePatchLayerKey(target.ref);
             const lines = await ctx.patchFile.readPatchLines(file);
-            const line = lines.find((l) => l.lineId === target.ref);
+            const line = lines.find((l) => l.lineId === lineId);
             return { kind: 'patchLine', adapter: target.adapter, ref: target.ref, before: line?.raw ?? null, existed: line !== undefined };
         }
         case 'skills':

package/lib/core/patch-layers.d.ts

@@ -0,0 +1,32 @@
+/**
+ * cordis patch 层的寻址契约（唯一真源）。
+ *
+ * 宿主组装 patch 栈的顺序是 `bundle → profile → home → --patch`（后者覆盖前者），两层分工不同：
+ *  - home 层 `$DSH_HOME/cordis.patch.yml`：全机偏好，对每个 profile 生效；
+ *  - profile 层 `$DSH_HOME/profiles/<profile>/cordis.patch.yml`：该 profile 专属（端口、trustedHosts、
+ *    挂载行…），换机恢复时必须跟着走。
+ *
+ * 两层的**持久化标识**是这里的两个逻辑 token，而不是相对路径：同步快照会跨机器、
+ * 跨 profile 导入，相对路径会把源机的 profile 名带过去。home 层 token 与历史快照里的
+ * `PatchLine.file` 取值逐字相同（存量快照零改动即可解析回 home 层）。
+ *
+ * 层限定复合键 `<file>#<lineId>`：两层可以存在同名 `lineId`，而计划项 id / `target.ref` /
+ * 快照条目必须唯一指向「哪一层的哪一行」，否则应用与回滚会写错层。两个 token 与 lineId 都不含
+ * `#`（后者由 `readPatchLines` 保证非空字符串，此处不额外校验），分隔符无歧义。
+ */
+/** home 层 token（`$DSH_HOME/cordis.patch.yml`）；取值与历史快照的 file 字段一致。 */
+export declare const HOME_PATCH_FILE = "cordis.patch.yml";
+/** profile 层 token（`$DSH_HOME/profiles/<profile>/cordis.patch.yml`）。 */
+export declare const PROFILE_PATCH_FILE = "profile:cordis.patch.yml";
+/** 层限定复合键：`<file>#<lineId>`。 */
+export declare function patchLayerKey(file: string, lineId: string): string;
+/**
+ * 解析层限定复合键。
+ *
+ * 兼容分支：旧快照的 `target.ref` / `SnapshotEntry.ref` 是裸 `lineId`（当时只有 home 层），
+ * 不含 `#` 即视作 home 层。lineId 本身不含 `#`，因此该分支无歧义。
+ */
+export declare function parsePatchLayerKey(ref: string): {
+    file: string;
+    lineId: string;
+};

package/lib/core/patch-layers.js

@@ -0,0 +1,39 @@
+/**
+ * cordis patch 层的寻址契约（唯一真源）。
+ *
+ * 宿主组装 patch 栈的顺序是 `bundle → profile → home → --patch`（后者覆盖前者），两层分工不同：
+ *  - home 层 `$DSH_HOME/cordis.patch.yml`：全机偏好，对每个 profile 生效；
+ *  - profile 层 `$DSH_HOME/profiles/<profile>/cordis.patch.yml`：该 profile 专属（端口、trustedHosts、
+ *    挂载行…），换机恢复时必须跟着走。
+ *
+ * 两层的**持久化标识**是这里的两个逻辑 token，而不是相对路径：同步快照会跨机器、
+ * 跨 profile 导入，相对路径会把源机的 profile 名带过去。home 层 token 与历史快照里的
+ * `PatchLine.file` 取值逐字相同（存量快照零改动即可解析回 home 层）。
+ *
+ * 层限定复合键 `<file>#<lineId>`：两层可以存在同名 `lineId`，而计划项 id / `target.ref` /
+ * 快照条目必须唯一指向「哪一层的哪一行」，否则应用与回滚会写错层。两个 token 与 lineId 都不含
+ * `#`（后者由 `readPatchLines` 保证非空字符串，此处不额外校验），分隔符无歧义。
+ */
+/** home 层 token（`$DSH_HOME/cordis.patch.yml`）；取值与历史快照的 file 字段一致。 */
+export const HOME_PATCH_FILE = 'cordis.patch.yml';
+/** profile 层 token（`$DSH_HOME/profiles/<profile>/cordis.patch.yml`）。 */
+export const PROFILE_PATCH_FILE = 'profile:cordis.patch.yml';
+/** 层限定复合键的分隔符（两个层 token 与 lineId 都不含它）。 */
+const PATCH_LAYER_SEPARATOR = '#';
+/** 层限定复合键：`<file>#<lineId>`。 */
+export function patchLayerKey(file, lineId) {
+    return `${file}${PATCH_LAYER_SEPARATOR}${lineId}`;
+}
+/**
+ * 解析层限定复合键。
+ *
+ * 兼容分支：旧快照的 `target.ref` / `SnapshotEntry.ref` 是裸 `lineId`（当时只有 home 层），
+ * 不含 `#` 即视作 home 层。lineId 本身不含 `#`，因此该分支无歧义。
+ */
+export function parsePatchLayerKey(ref) {
+    const at = ref.indexOf(PATCH_LAYER_SEPARATOR);
+    if (at < 0)
+        return { file: HOME_PATCH_FILE, lineId: ref };
+    return { file: ref.slice(0, at), lineId: ref.slice(at + 1) };
+}
+//# sourceMappingURL=patch-layers.js.map

package/lib/core/rollback.js

@@ -8,6 +8,7 @@
  *  - settings 回滚仍走 expectedRevision 乐观锁，避免覆盖导入后用户的新修改。
  */
 import { resolveFileTarget } from './backup.js';
+import { parsePatchLayerKey } from './patch-layers.js';
 import { msgOf } from './messages.js';
 /** 逆序补偿单条快照条目；返回 null=成功，否则为失败原因 */
 async function compensateOne(entry, ctx, store) {
@@ -57,10 +58,9 @@ async function compensateOne(entry, ctx, store) {
         }
         case 'patchLine': {
             try {
-                // 引擎只管理 profile 的 cordis.patch.yml（backup.ts 的 patchLine 快照只记 lineId 作 ref，
-                // 不含文件编码）——回滚固定写回该文件；切勿把 lineId 当文件名（否则 patchPath 抛「仅支持管理」）。
-                const file = 'cordis.patch.yml';
-                const lineId = entry.ref;
+                // 快照条目的 ref 是层限定复合键（<file>#<lineId>）——必须写回**同一层**，
+                // 否则 profile 层的原值会被写进 home 层。旧快照的裸 lineId 兼容为 home 层。
+                const { file, lineId } = parsePatchLayerKey(entry.ref);
                 await ctx.patchFile.applyPatchChanges(file, [
                     { lineId, raw: entry.before, action: entry.before === null ? 'remove' : 'update' },
                 ]);

package/lib/index.d.ts

@@ -132,6 +132,27 @@ export declare class DshPluginsFacade implements PluginsFacade {
         needsRestart: boolean;
     }>;
 }
+/** Patch-file facade：用户 patch 层（$DSH_HOME/cordis.patch.yml）+ profile patch 层
+ * （$DSH_HOME/profiles/<name>/cordis.patch.yml），两者都在 home 根内。
+ *
+ * 导出仅为让测试能用**真实门面**（而非 mock）钉住层寻址——mock 会让两个层 token 的取值
+ * 撞车无处暴露（DshPluginsFacade 同款做法）。 */
+export declare class DshPatchFileFacade implements PatchFileFacade {
+    private readonly homeDir;
+    private readonly profile;
+    private readonly msg;
+    constructor(homeDir: string, profile: string, msg?: MsgFunc);
+    private patchPath;
+    readPatchLines(file: string): Promise<{
+        lineId: string;
+        raw: unknown;
+    }[]>;
+    applyPatchChanges(file: string, changes: {
+        lineId: string;
+        raw: unknown;
+        action: 'insert' | 'update' | 'remove';
+    }[]): Promise<void>;
+}
 /** 同步路由可预期的请求级错误（status 缺省 400；引擎/传输失败走 500） */
 export declare class SyncRouteError extends Error {
     readonly status: number;
@@ -217,18 +238,6 @@ export declare function executeRestorePlan(plan: RestorePlan, exec: RestoreExecu
  * 是真实故障，仍按 500 暴露，绝不伪装成「未登录」。
  */
 export declare function isGitHubAuthMissing(error: unknown): boolean;
-/** /status 的插件诊断位（issue #28）。仅回非敏感元信息：目录、profile 名、计数。 */
-export interface PluginDiagnostics {
-    homeDir: string;
-    profile: string;
-    /** profile 目录的 package.json 是否可读（不可读 → 清单必然为空） */
-    profileManifestReadable: boolean;
-    /** 插件清单来源 = package.json 的 dependencies 里非 in-box 的包 */
-    installedPluginCount: number;
-    installedPluginNames: string[];
-    /** dsh.profile.bundles 声明（非空即「替换默认插件栈」） */
-    bundles: string[];
-}
 /**
  * Mount the config-manager engine: host context, adapters, and the
  * /api/dsh-config-manager routes (when a webServer is present).

package/lib/index.js

@@ -65,9 +65,10 @@ import { registerModelTools } from './core/model-tools.js';
 import { computeConsultReport } from './core/migration-consult.js';
 import { readExportZipSource, buildLocalSnapshotSource, buildProfileSource } from './core/consult-source.js';
 import { makeMsg, msgOf, zhMsg } from './core/messages.js';
-import { cleanupAbortedInstall, hasDshBundlePatch, installErrorFor, installSpecFor, listInstalledPlugins, resolveProfileDir, resolveProfileNameFromArgv, readProfileManifest, runDshPlugin, validateProfileName, } from './core/plugin-cli.js';
+import { cleanupAbortedInstall, hasDshBundlePatch, installErrorFor, installSpecFor, listInstalledPlugins, resolveProfileDir, resolveProfileNameFromArgv, runDshPlugin, validateProfileName, } from './core/plugin-cli.js';
 import { ImportNotConfirmedError, ImportUserSkippedError } from './core/types.js';
-import { createAdapters, USER_PATCH_FILE } from './adapters/index.js';
+import { createAdapters } from './adapters/index.js';
+import { HOME_PATCH_FILE, PROFILE_PATCH_FILE } from './core/patch-layers.js';
 import { createLocalPluginPackHook } from './core/local-plugin-host.js';
 import { createEncryptionProvider, decryptCredentials, decryptArchive, SecurityError, encryptArchive, isArchiveBlob, verifyEncryptedBlob } from './security/index.js';
 import { createHardenedZipParser } from './security/zip-security.js';
@@ -105,7 +106,7 @@ export const name = 'config-manager';
 /** Services required before the engine can mount (present in every profile). */
 export const inject = ['settings', 'credentials'];
 /** Plugin version, kept in sync with package.json ("version"). */
-const PLUGIN_VERSION = '0.1.60';
+const PLUGIN_VERSION = '0.1.61';
 /** Plugin own package name — excluded from its own exported plugins list. */
 const PLUGIN_NAME = 'dsh-config-manager';
 /**
@@ -126,6 +127,8 @@ export const DEFAULT_GITHUB_CLIENT_ID = 'Ov23liq4i7n8UsylGRfb';
 /* ---------------------------------------------------------------- constants */
 /** Route family — must match the browser half's CONFIG_MANAGER_API exactly. */
 const API = {
+    // 设置页页脚版本行（pluginVersion / dshVersion）。只读，loopback fence。
+    status: '/api/dsh-config-manager/status',
     // P2-⑫：导出前只读预览（不落盘 ZIP；返回各分区 counts + 估算大小）
     // P1-⑧：快照管理（手动删除 + 置顶豁免自动清理）
     // m-backup-schedule：定时全量备份（读/存 backup-schedule.json + 立即执行一次）
@@ -520,11 +523,12 @@ class DshWorkspaceFacade {
         await registry.delete(id);
     }
 }
-/** Profile 目录内的 patch 文件（非 bundle 插件激活行写入处，marketplace 同款路径）。 */
-const PROFILE_PATCH_FILE = 'cordis.patch.yml';
 /** Patch-file facade：用户 patch 层（$DSH_HOME/cordis.patch.yml）+ profile patch 层
- * （$DSH_HOME/profiles/<name>/cordis.patch.yml），两者都在 home 根内。 */
-class DshPatchFileFacade {
+ * （$DSH_HOME/profiles/<name>/cordis.patch.yml），两者都在 home 根内。
+ *
+ * 导出仅为让测试能用**真实门面**（而非 mock）钉住层寻址——mock 会让两个层 token 的取值
+ * 撞车无处暴露（DshPluginsFacade 同款做法）。 */
+export class DshPatchFileFacade {
     homeDir;
     profile;
     msg;
@@ -534,11 +538,11 @@ class DshPatchFileFacade {
         this.msg = msg;
     }
     patchPath(file) {
-        if (file === USER_PATCH_FILE)
-            return join(this.homeDir, USER_PATCH_FILE);
+        if (file === HOME_PATCH_FILE)
+            return join(this.homeDir, HOME_PATCH_FILE);
         if (file === PROFILE_PATCH_FILE)
-            return join(this.homeDir, 'profiles', this.profile, PROFILE_PATCH_FILE);
-        throw new Error(this.msg('host.patchUnsupported', { user: USER_PATCH_FILE, profile: PROFILE_PATCH_FILE, file }));
+            return join(this.homeDir, 'profiles', this.profile, HOME_PATCH_FILE);
+        throw new Error(this.msg('host.patchUnsupported', { user: HOME_PATCH_FILE, profile: PROFILE_PATCH_FILE, file }));
     }
     async readPatchLines(file) {
         const p = this.patchPath(file);
@@ -1199,31 +1203,6 @@ function parseMeForm(raw) {
 export function isGitHubAuthMissing(error) {
     return error instanceof GitHubAuthError && (error.code === 'unauthorized' || error.code === 'no_token');
 }
-/**
- * 读取插件诊断信息（issue #28）：把「插件到底读了哪个目录 / 哪个 profile / 看到什么」变成
- * 用户可自查的数据——此前只存在于宿主内部，导致「装了插件却识别不到」无从定位。
- * best-effort：失败不抛出（诊断位缺失不应拖垮 /status）。
- */
-async function readPluginDiagnostics(host) {
-    try {
-        const profileDir = resolveProfileDir(host.homeDir, host.profile ?? 'web');
-        const manifest = readProfileManifest(profileDir);
-        const installed = await host.plugins.listInstalled();
-        const bundles = manifest?.dsh?.profile?.bundles;
-        return {
-            homeDir: host.homeDir,
-            profile: host.profile ?? 'web',
-            profileManifestReadable: manifest !== null,
-            installedPluginCount: installed.length,
-            installedPluginNames: installed.map((p) => p.name),
-            bundles: Array.isArray(bundles) ? bundles : [],
-        };
-    }
-    catch (err) {
-        host.log.warn(`plugin diagnostics unavailable: ${err instanceof Error ? err.message : String(err)}`);
-        return {};
-    }
-}
 /** Build the /api/dsh-config-manager route family. */
 function makeRoutes(deps) {
     const { host, adapters, exportsDir, tmpDir, snapshotsDir, runs, syncDir, dataDir, credentials, githubClientId, githubClientSecret, history } = deps;
@@ -1605,6 +1584,19 @@ function makeRoutes(deps) {
     });
     const routesList = [
         // ------------------------------------------------------------- status
+        // 设置页页脚版本行：插件版本 + DSH 版本。只读、无 secret，loopback fence。
+        {
+            kind: 'exact',
+            path: API.status,
+            handler: async (req, res) => {
+                if (!guard(req, res, 'GET'))
+                    return;
+                writeJson(res, 200, {
+                    pluginVersion: PLUGIN_VERSION,
+                    dshVersion: host.dshVersion,
+                });
+            },
+        },
         // ------------------------------------------------------------- export
         // ---------------------------------------------------- export-preview
         // P2-⑫：导出前只读预览（不落盘 ZIP）：对选中分区逐个 adapter.export 收集 counts

package/lib/utils/env-lock.d.ts

@@ -222,6 +222,22 @@ export interface EnvLockManagerOptions {
     /** heartbeat 续期写失败回调（留痕；不中断 mutation） */
     onHeartbeatWriteFailure?: (err: unknown) => void;
 }
+/**
+ * 从 /proc/<pid>/stat 文本提取进程创建身份（starttime，字段 22）。
+ *
+ * 字段布局（man 5 proc_pid_stat）：1 pid, 2 comm, 3 state, …, 22 starttime, 23 vsize, 24 rss。
+ * comm 可能含空格与括号，故必须按**最后一个** ')' 切片；切片后 index 0 对应字段 3，
+ * 于是字段 N 的索引是 N-3 —— **starttime 的索引是 19**。
+ *
+ * 历史缺陷：此处曾取 index 21（= 字段 24 rss）。rss 随进程内存占用变化，
+ * 使同一进程的两次读取得到不同身份，被误判为「PID 复用」→ STALE_LOCK_DETECTED，
+ * 进而可能让 recoverStaleLock() 捕获一个**仍存活**的持有者的锁。
+ * 该路径仅在 Linux 生效（macOS/Windows 无 /proc），故只在 Linux CI 上暴露。
+ *
+ * @param statText /proc/<pid>/stat 全文
+ * @returns starttime 字符串；畸形/字段不足 → null（不抛错，也不编造身份）
+ */
+export declare function parseLinuxProcStartTime(statText: string): string | null;
 /**
  * EnvironmentLockManager：跨进程环境锁管理器。
  *

package/lib/utils/env-lock.js

@@ -153,16 +153,37 @@ function defaultIo() {
         } },
     };
 }
+/**
+ * 从 /proc/<pid>/stat 文本提取进程创建身份（starttime，字段 22）。
+ *
+ * 字段布局（man 5 proc_pid_stat）：1 pid, 2 comm, 3 state, …, 22 starttime, 23 vsize, 24 rss。
+ * comm 可能含空格与括号，故必须按**最后一个** ')' 切片；切片后 index 0 对应字段 3，
+ * 于是字段 N 的索引是 N-3 —— **starttime 的索引是 19**。
+ *
+ * 历史缺陷：此处曾取 index 21（= 字段 24 rss）。rss 随进程内存占用变化，
+ * 使同一进程的两次读取得到不同身份，被误判为「PID 复用」→ STALE_LOCK_DETECTED，
+ * 进而可能让 recoverStaleLock() 捕获一个**仍存活**的持有者的锁。
+ * 该路径仅在 Linux 生效（macOS/Windows 无 /proc），故只在 Linux CI 上暴露。
+ *
+ * @param statText /proc/<pid>/stat 全文
+ * @returns starttime 字符串；畸形/字段不足 → null（不抛错，也不编造身份）
+ */
+export function parseLinuxProcStartTime(statText) {
+    const close = statText.lastIndexOf(')');
+    if (close < 0)
+        return null;
+    const fields = statText.slice(close + 1).trim().split(/\s+/);
+    const starttime = fields[19];
+    return typeof starttime === 'string' && starttime !== '' ? starttime : null;
+}
 /** 默认进程探测（跨平台 best-effort；OS identity 能力由平台决定） */
 function defaultProbe() {
     const selfOsIdentity = (() => {
         try {
             if (process.platform === 'linux') {
-                // /proc/<pid>/stat 第 22 字段 = starttime（tick 数）
                 const l = fssync.readFileSync(`/proc/${process.pid}/stat`, 'utf8').toString();
-                const afterComm = l.slice(l.lastIndexOf(')') + 1).trim().split(/\s+/);
-                // 格式: state ppid ... starttime：comm 后第一字段是 state，starttime 是第 22 个（index 21 起）
-                return `linux:${afterComm[21] ?? 'unknown'}`;
+                const starttime = parseLinuxProcStartTime(l);
+                return starttime === null ? null : `linux:${starttime}`;
             }
             if (process.platform === 'darwin')
                 return `darwin:${process.pid}:${Date.now()}`; // 不可靠 → 保守返回占位
@@ -213,8 +234,8 @@ function defaultProbe() {
             if (process.platform === 'linux') {
                 try {
                     const l = fssync.readFileSync(`/proc/${pid}/stat`, 'utf8').toString();
-                    const afterComm = l.slice(l.lastIndexOf(')') + 1).trim().split(/\s+/);
-                    osIdentity = `linux:${afterComm[21] ?? 'unknown'}`;
+                    const starttime = parseLinuxProcStartTime(l);
+                    osIdentity = starttime === null ? null : `linux:${starttime}`;
                 }
                 catch {
                     osIdentity = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logictan/dsh-config-manager",
-  "version": "0.1.60",
+  "version": "0.1.61",
   "license": "MIT",
   "description": "Sync your DeepSeek Harness (DSH) configuration between machines over a private git or WebDAV channel: settings, plugins, MCP servers, skills, agent presets, workspaces and provider credentials. DSH 配置远程同步插件（私有通道，明文自用）。",
   "keywords": [
@@ -160,7 +160,7 @@
     "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-client-ui-settings": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.6-alpha.2",
     "@deepseek-ai/dsh-credentials": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-host-plugin-inventory": "^0.1.0-rc.6",

package/src/adapters/index.ts

@@ -79,7 +79,7 @@ export type { CredentialRefsProvider } from './credentials.ts';
 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 { PluginsAdapter } 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';

package/src/adapters/mcp.ts

@@ -14,7 +14,7 @@ import type {
   ApplyResult, ConfigAdapter, ExportOptions, ExportSection, HostContext,
   ImportContext, PlanItem, ValidationResult,
 } from '../core/types.ts';
-import { USER_PATCH_FILE } from './plugins.ts';
+import { HOME_PATCH_FILE } from '../core/patch-layers.ts';
 
 /** 导出记录：McpServerEntry 之外附加来源 patch 行 id（导入写回定位用） */
 export interface McpExportEntry extends McpServerEntry {
@@ -95,7 +95,7 @@ export class McpAdapter implements ConfigAdapter<McpExportSection> {
     const warnings: string[] = [];
     let lines: { lineId: string; raw: unknown }[] = [];
     try {
-      lines = await ctx.patchFile.readPatchLines(USER_PATCH_FILE);
+      lines = await ctx.patchFile.readPatchLines(HOME_PATCH_FILE);
     } catch (err) {
       warnings.push(msgOf(ctx)('adapter.patchReadFailedMCP', { reason: err instanceof Error ? err.message : String(err) }));
     }
@@ -111,7 +111,7 @@ export class McpAdapter implements ConfigAdapter<McpExportSection> {
   async analyzeImport(data: McpExportSection, ctx: ImportContext): Promise<PlanItem[]> {
     const msg = ctx.msg;
     const items: PlanItem[] = [];
-    const targetLines = await ctx.target.patchFile.readPatchLines(USER_PATCH_FILE);
+    const targetLines = await ctx.target.patchFile.readPatchLines(HOME_PATCH_FILE);
     const targetServers = extractMcpServers(targetLines);
     for (const server of data.servers) {
       const id = `mcp:${server.serverName}`;
@@ -157,7 +157,7 @@ export class McpAdapter implements ConfigAdapter<McpExportSection> {
     const ref = item.target?.ref;
     if (!ref) return { ok: false, message: msg('adapter.missingTargetRef') };
     const raw = buildMcpPatchLine(ref, server);
-    await ctx.target.patchFile.applyPatchChanges(USER_PATCH_FILE, [
+    await ctx.target.patchFile.applyPatchChanges(HOME_PATCH_FILE, [
       { lineId: ref, raw, action: item.kind === 'Create' ? 'insert' : 'update' },
     ]);
     return { ok: true, needsRestart: true, message: msg('adapter.mcpWritten', { serverName }) };

package/src/adapters/patch-layers.test.ts

@@ -0,0 +1,201 @@
+/**
+ * cordis patch 的**层寻址**契约测试（S1–S5）：
+ *  - 导出同时覆盖 home 层与 profile 层，`file` 字段如实标注来源层；
+ *  - diff 阶段按行自带的层读目标端（profile 层已有同值 → Skip，不是 Create）；
+ *  - 计划项 id / target.ref 是层限定复合键，跨层同名 lineId 各自落各自层；
+ *  - 快照与回滚按层落位（回滚 profile 层的行不得污染 home 层）。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { PluginsAdapter } from './plugins.ts';
+import { makeContext, makeImportContext, MemSnapshotStore } from './test-helpers.ts';
+import { createSnapshot } from '../core/backup.ts';
+import { rollback } from '../core/rollback.ts';
+import { HOME_PATCH_FILE, PROFILE_PATCH_FILE, patchLayerKey } from '../core/patch-layers.ts';
+import { SECTION_IDS } from '../schema/config.ts';
+import type { ImportPlan, PlanItem } from '../core/types.ts';
+
+/** 只含一项的导入计划（estimatedActions 需覆盖全部分区，故按 SECTION_IDS 补零）。 */
+function importPlan(item: PlanItem): ImportPlan {
+  return {
+    items: [item],
+    globalStrategy: 'merge',
+    pathMappings: [],
+    missingSecrets: [],
+    needsRestart: false,
+    estimatedActions: Object.fromEntries(SECTION_IDS.map((id) => [id, 0])) as ImportPlan['estimatedActions'],
+  };
+}
+
+test('plugins.export: 两层 patch 行都进 section，file 字段区分来源层', async () => {
+  const ctx = makeContext('linux', '/home/alice', 'web');
+  const layered = ctx.useLayeredPatch();
+  layered.set(HOME_PATCH_FILE, 'home-a', { id: 'home-a', disabled: true });
+  layered.set(HOME_PATCH_FILE, 'home-b', { id: 'home-b', disabled: true });
+  layered.set(PROFILE_PATCH_FILE, 'profile-a', { id: 'profile-a', name: 'pkg-a' });
+  layered.set(PROFILE_PATCH_FILE, 'profile-b', { id: 'profile-b', name: 'pkg-b' });
+
+  const out = await new PluginsAdapter().export(ctx, { includeSecrets: false });
+  assert.equal(out.data.patch.length, 4, `两层并集必须齐全: ${JSON.stringify(out.data.patch)}`);
+  assert.deepEqual(
+    [...new Set(out.data.patch.map((p) => p.file))].sort(),
+    [HOME_PATCH_FILE, PROFILE_PATCH_FILE].sort(),
+    'file 必须区分来源层',
+  );
+  assert.deepEqual(
+    out.data.patch.filter((p) => p.file === PROFILE_PATCH_FILE).map((p) => p.lineId),
+    ['profile-a', 'profile-b'],
+  );
+});
+
+test('plugins.export: profile 层文件缺失时降级为仅 home 层（不产生 error 级告警）', async () => {
+  const ctx = makeContext('linux', '/home/alice', 'web');
+  const layered = ctx.useLayeredPatch();
+  layered.set(HOME_PATCH_FILE, 'home-a', { id: 'home-a', disabled: true });
+
+  const out = await new PluginsAdapter().export(ctx, { includeSecrets: false });
+  assert.equal(out.data.patch.length, 1);
+  assert.deepEqual([...new Set(out.data.patch.map((p) => p.file))], [HOME_PATCH_FILE]);
+  assert.equal(out.warnings.length, 0, `缺 profile 层不是故障: ${out.warnings.join(' | ')}`);
+});
+
+test('plugins.analyzeImport: 目标端 profile 层已有同行 → Skip（不是 Create）', async () => {
+  const src = makeContext('linux', '/home/alice', 'web');
+  const srcLayered = src.useLayeredPatch();
+  const raw = { id: 'webserver', config: { port: 3080 } };
+  srcLayered.set(PROFILE_PATCH_FILE, 'webserver', raw);
+
+  const adapter = new PluginsAdapter();
+  const exported = await adapter.export(src, { includeSecrets: false });
+  const sections = new Map([['plugins', exported.data]]);
+
+  // 目标机 profile 层已有同值行 → Skip（旧实现只读 home 层，会误判成 Create）
+  const dst = makeContext('linux', '/home/bob', 'web');
+  dst.useLayeredPatch().set(PROFILE_PATCH_FILE, 'webserver', raw);
+  const items = await adapter.analyzeImport(exported.data, makeImportContext(dst, sections));
+  const item = items.find((i) => i.id === `patch:${patchLayerKey(PROFILE_PATCH_FILE, 'webserver')}`);
+  assert.equal(item?.kind, 'Skip', JSON.stringify(items));
+
+  // 目标机 profile 层同 id 但不同值 → Conflict（旧实现只读 home 层，会误判成 Create）
+  const dst2 = makeContext('linux', '/home/bob2', 'web');
+  dst2.useLayeredPatch().set(PROFILE_PATCH_FILE, 'webserver', { id: 'webserver', config: { port: 9999 } });
+  const items2 = await adapter.analyzeImport(exported.data, makeImportContext(dst2, sections));
+  const item2 = items2.find((i) => i.id === `patch:${patchLayerKey(PROFILE_PATCH_FILE, 'webserver')}`);
+  assert.equal(item2?.kind, 'Conflict', JSON.stringify(items2));
+});
+
+test('plugins: 跨层同名 lineId → 两个独立计划项，各自落各自层', async () => {
+  const src = makeContext('linux', '/home/alice', 'web');
+  const srcLayered = src.useLayeredPatch();
+  srcLayered.set(HOME_PATCH_FILE, 'dup', { id: 'dup', config: { from: 'home' } });
+  srcLayered.set(PROFILE_PATCH_FILE, 'dup', { id: 'dup', config: { from: 'profile' } });
+
+  const adapter = new PluginsAdapter();
+  const exported = await adapter.export(src, { includeSecrets: false });
+  const sections = new Map([['plugins', exported.data]]);
+  assert.equal(exported.data.patch.length, 2);
+
+  const dst = makeContext('linux', '/home/bob', 'web');
+  dst.useLayeredPatch();
+  const items = await adapter.analyzeImport(exported.data, makeImportContext(dst, sections));
+  const patchItems = items.filter((i) => i.id.startsWith('patch:'));
+  assert.equal(patchItems.length, 2, `同名 lineId 必须是两个独立项: ${JSON.stringify(items)}`);
+
+  for (const item of patchItems) {
+    const r = await adapter.applyItem(item, makeImportContext(dst, sections));
+    assert.equal(r.ok, true, JSON.stringify(r));
+  }
+  const layered = dst.patchFile as unknown as { has: (f: string, id: string) => boolean };
+  assert.equal(layered.has(HOME_PATCH_FILE, 'dup'), true, 'home 层的行必须落在 home 层');
+  assert.equal(layered.has(PROFILE_PATCH_FILE, 'dup'), true, 'profile 层的行必须落在 profile 层');
+  assert.deepEqual(
+    (dst.patchFile as unknown as { rawOf: (f: string, id: string) => unknown }).rawOf(HOME_PATCH_FILE, 'dup'),
+    { id: 'dup', config: { from: 'home' } },
+  );
+  assert.deepEqual(
+    (dst.patchFile as unknown as { rawOf: (f: string, id: string) => unknown }).rawOf(PROFILE_PATCH_FILE, 'dup'),
+    { id: 'dup', config: { from: 'profile' } },
+  );
+});
+
+test('rollback: profile 层 patchLine 回滚写回 profile 层（home 层文件不受影响）', async () => {
+  const ctx = makeContext('linux', '/home/bob', 'web');
+  const layered = ctx.useLayeredPatch();
+  const original = { id: 'webserver', config: { port: 3080 } };
+  layered.set(PROFILE_PATCH_FILE, 'webserver', original);
+  layered.set(HOME_PATCH_FILE, 'webserver', { id: 'webserver', config: { port: 1111 } });
+
+  const item: PlanItem = {
+    id: `patch:${patchLayerKey(PROFILE_PATCH_FILE, 'webserver')}`,
+    kind: 'Update',
+    adapter: 'plugins',
+    description: 'write profile patch row',
+    severity: 'info',
+    target: { adapter: 'plugins', ref: patchLayerKey(PROFILE_PATCH_FILE, 'webserver') },
+  };
+  const plan = importPlan(item);
+  const store = new MemSnapshotStore();
+  const snapshot = await createSnapshot({ ctx, plan, sourceZip: '/tmp/x.zip', store, adapters: [] });
+  const entry = snapshot.entries.find((e) => e.kind === 'patchLine');
+  assert.ok(entry !== undefined, `快照必须登记 patchLine 条目: ${JSON.stringify(snapshot.entries)}`);
+  assert.deepEqual(entry.before, original, '快照必须记 profile 层原值（旧实现固定读 home 层，会记成 home 层的值）');
+
+  // 模拟导入改写 profile 层
+  await ctx.patchFile.applyPatchChanges(PROFILE_PATCH_FILE, [
+    { lineId: 'webserver', raw: { id: 'webserver', config: { port: 9999 } }, action: 'update' },
+  ]);
+  const report = await rollback({ ctx, snapshot, store, adapters: [] });
+  assert.equal(report.full, true, JSON.stringify(report));
+  assert.deepEqual(layered.rawOf(PROFILE_PATCH_FILE, 'webserver'), original, '回滚必须写回 profile 层原值');
+  assert.deepEqual(
+    layered.rawOf(HOME_PATCH_FILE, 'webserver'),
+    { id: 'webserver', config: { port: 1111 } },
+    'home 层的行不得被 profile 层回滚污染',
+  );
+});
+
+test('rollback: 旧快照的裸 lineId ref 兼容为 home 层', async () => {
+  const ctx = makeContext('linux', '/home/bob', 'web');
+  const layered = ctx.useLayeredPatch();
+  layered.set(HOME_PATCH_FILE, 'legacy', { id: 'legacy', disabled: false });
+
+  const item: PlanItem = {
+    id: 'patch:legacy',
+    kind: 'Update',
+    adapter: 'plugins',
+    description: 'legacy ref',
+    severity: 'info',
+    target: { adapter: 'plugins', ref: 'legacy' },
+  };
+  const plan = importPlan(item);
+  const store = new MemSnapshotStore();
+  const snapshot = await createSnapshot({ ctx, plan, sourceZip: '/tmp/x.zip', store, adapters: [] });
+  assert.deepEqual(snapshot.entries.find((e) => e.kind === 'patchLine')?.before, { id: 'legacy', disabled: false });
+
+  await ctx.patchFile.applyPatchChanges(HOME_PATCH_FILE, [
+    { lineId: 'legacy', raw: { id: 'legacy', disabled: true }, action: 'update' },
+  ]);
+  const report = await rollback({ ctx, snapshot, store, adapters: [] });
+  assert.equal(report.full, true, JSON.stringify(report));
+  assert.deepEqual(layered.rawOf(HOME_PATCH_FILE, 'legacy'), { id: 'legacy', disabled: false });
+});
+
+test('plugins.export: 存量快照的 file=home token 仍解析到 home 层', async () => {
+  const src = makeContext('linux', '/home/alice', 'web');
+  const layered = src.useLayeredPatch();
+  layered.set(HOME_PATCH_FILE, 'legacy-home', { id: 'legacy-home', disabled: true });
+
+  const adapter = new PluginsAdapter();
+  const exported = await adapter.export(src, { includeSecrets: false });
+  assert.equal(exported.data.patch[0]?.file, HOME_PATCH_FILE, 'home 层 token 与历史快照取值一致');
+
+  const sections = new Map([['plugins', exported.data]]);
+  const dst = makeContext('linux', '/home/bob', 'web');
+  dst.useLayeredPatch();
+  const items = await adapter.analyzeImport(exported.data, makeImportContext(dst, sections));
+  const item = items.find((i) => i.id.startsWith('patch:'));
+  assert.equal(item?.target?.ref, patchLayerKey(HOME_PATCH_FILE, 'legacy-home'));
+  await adapter.applyItem(item!, makeImportContext(dst, sections));
+  assert.equal((dst.patchFile as unknown as { has: (f: string, id: string) => boolean }).has(HOME_PATCH_FILE, 'legacy-home'), true);
+});