flower-trellis 0.6.3 → 0.6.4

package/enhancements/MANIFEST.json

@@ -1,5 +1,5 @@
 {
-  "syncedAt": "2026-08-26T01:20:11.756Z",
+  "syncedAt": "2026-08-28T18:19:48.301Z",
   "syncedFrom": "vendor/skill-garden",
   "sourceCommit": "124b592037eef542d7faf7ecb3be93b4bfd3aed0",
   "common": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flower-trellis",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "一键安装/升级 Trellis 并自动融合 skill-garden 强化包(默认 Claude + agents)",
   "type": "module",
   "bin": {
@@ -70,9 +70,9 @@
     "commit-and-tag-version": "^12.7.3"
   },
   "flowerReleaseNotes": {
-    "version": "0.6.3",
+    "version": "0.6.4",
     "source": "CHANGELOG.md",
-    "body": "### ✨ 新功能 Features\n\n* **plugin:** 对齐 RD Guide 的 Marketplace 包模型 ([e399d6e](https://github.com/SilentFlower/flower-trellis/commit/e399d6e70042256258431a4629f5efa15ba2f417))\n* **plugin:** 支持在非 Trellis 项目中管理通用 Skill ([0a9cd62](https://github.com/SilentFlower/flower-trellis/commit/0a9cd62ff3cd37971f5d65ea8500e4f51ed3a280))\n* **plugin:** 复用 GitLab 全局凭据 ([a3c6b16](https://github.com/SilentFlower/flower-trellis/commit/a3c6b1616b123ff0f7328ce5b2eace5eb631ae5b))\n* **plugin:** 支持 Marketplace Skill 子集选择 ([6406ccb](https://github.com/SilentFlower/flower-trellis/commit/6406ccbdbe982a885069a6a4af133fc132565a1c))\n\n\n### 🐛 修复 Bug Fixes\n\n* **plugin:** 加速 GitLab RD Guide Skill 清单读取 ([8bd1eac](https://github.com/SilentFlower/flower-trellis/commit/8bd1eac86ac32680d52c6fa715ece1b4c4ba99ef))",
+    "body": "### 🐛 修复 Bug Fixes\n\n* **plugin:** 支持离线冻结未更新的外部 Plugin ([6210cfa](https://github.com/SilentFlower/flower-trellis/commit/6210cfae8d459a3e7b105043e4ecbc23d1b5bed9))",
     "truncated": false
   },
   "optionalDependencies": {

package/src/commands/plugin-remote.js

@@ -537,12 +537,15 @@ export async function runPluginManagementCommand(parsed, ctx, options, output) {
 /**
  * 为生命周期命令登记所需的远程 Source Provider。
  *
- * @param {{parsed:object,projectRoot:string,options:object,registry:object,lock:object|null}} context 远程准备上下文
+ * @param {{parsed:object,projectRoot:string,options:object,registry:object,lock:object|null,preserveIds?:string[]}} context 远程准备上下文
  * @returns {Promise<void>} 登记完成
  */
-export async function registerRemotePluginSources({ parsed, projectRoot, options, registry, lock }) {
+export async function registerRemotePluginSources({ parsed, projectRoot, options, registry, lock, preserveIds = [] }) {
+  const preserved = new Set(preserveIds);
   const remoteIds = new Set(["add", "update", "remove", "verify", "replay"].includes(parsed.command)
-    ? (lock?.plugins || []).filter(({ source }) => ["gitlab", "github"].includes(source.type)).map(({ source }) => source.id)
+    ? (lock?.plugins || [])
+      .filter(({ id, source }) => !preserved.has(id) && ["gitlab", "github"].includes(source.type))
+      .map(({ source }) => source.id)
     : []);
   let sourceStore = null;
   let configuredSources = null;
@@ -584,6 +587,15 @@ export async function registerRemotePluginSources({ parsed, projectRoot, options
       remoteIds.add(simpleSourceOption);
     }
   }
+  if (parsed.command === "update" && parsed.pluginId?.includes("/")) {
+    for (const sourceId of collectUnregisteredDependencySources(
+      registry,
+      [parsed.pluginId],
+      preserveIds,
+    )) {
+      remoteIds.add(sourceId);
+    }
+  }
   remoteIds.delete("local");
   if (remoteIds.size === 0) return;
 
@@ -628,25 +640,57 @@ export async function registerRemotePluginSources({ parsed, projectRoot, options
 /**
  * 准备远程 Plugin 候选及固定 lock 缓存。
  *
- * @param {{parsed:object,canonicalId:string|null,registry:object,lock:object|null}} context 候选准备上下文
+ * @param {{parsed:object,canonicalId:string|null,registry:object,lock:object|null,preserveIds?:string[]}} context 候选准备上下文
  * @returns {Promise<void>} 准备完成
  */
-export async function prepareRemotePluginCandidates({ parsed, canonicalId, registry, lock }) {
+export async function prepareRemotePluginCandidates({ parsed, canonicalId, registry, lock, preserveIds = [] }) {
   if (parsed.command === "add" && registry.has(parseCanonicalPluginId(canonicalId).sourceId)) {
-    await prepareRemoteLock(registry, lock);
-    await prepareRemoteClosure(registry, [canonicalId]);
+    await prepareRemoteLock(registry, lock, preserveIds);
+    await prepareRemoteClosure(registry, [canonicalId], preserveIds);
   } else if (parsed.command === "update") {
     // 更新单一 Plugin 时，解析器仍会 lock-first 重放完整图；先恢复全部远程固定包，
     // 再只为本轮显式更新目标加载新候选，避免顺带升级其它外部 Plugin。
-    await prepareRemoteLock(registry, lock);
+    await prepareRemoteLock(registry, lock, preserveIds);
     const updateIds = canonicalId
       ? [canonicalId]
       : (lock?.plugins || []).filter(({ source }) => ["gitlab", "github"].includes(source.type)).map(({ id }) => id);
-    await prepareRemoteClosure(registry, updateIds);
+    await prepareRemoteClosure(registry, updateIds, preserveIds);
     assertExternalVersionsNotReused(registry, lock, updateIds);
   } else if (["remove", "verify", "replay"].includes(parsed.command)) {
-    await prepareRemoteLock(registry, lock);
+    await prepareRemoteLock(registry, lock, preserveIds);
+  }
+}
+
+/**
+ * 从当前可读取的活跃候选中收集尚未登记的依赖来源。
+ *
+ * 注册阶段不能准备远程候选，但 builtin/local 候选已经可读。先沿这些候选展开依赖，才能在
+ * 旧 lock 的同来源节点全部被冻结时，仍为本轮新增的非冻结依赖登记 Provider。
+ *
+ * @param {object} registry Provider 注册表
+ * @param {string[]} initialIds 活跃入口 canonical ID
+ * @param {string[]} [preserveIds] 不读取来源的冻结 Plugin ID
+ * @returns {string[]} 尚未登记的依赖来源 ID
+ */
+function collectUnregisteredDependencySources(registry, initialIds, preserveIds = []) {
+  const preserved = new Set(preserveIds);
+  const pending = [...new Set(initialIds)];
+  const visited = new Set();
+  const sourceIds = new Set();
+  while (pending.length > 0) {
+    const id = pending.shift();
+    if (visited.has(id) || preserved.has(id)) continue;
+    visited.add(id);
+    const { sourceId } = parseCanonicalPluginId(id);
+    if (!registry.has(sourceId)) {
+      sourceIds.add(sourceId);
+      continue;
+    }
+    for (const candidate of registry.listCandidates(id)) {
+      pending.push(...Object.keys(candidate.manifest.dependencies || {}));
+    }
   }
+  return [...sourceIds].sort(compareUtf8);
 }
 
 /**
@@ -654,20 +698,21 @@ export async function prepareRemotePluginCandidates({ parsed, canonicalId, regis
  *
  * @param {object} registry Provider 注册表
  * @param {string[]} initialIds 初始 canonical ID
+ * @param {string[]} [preserveIds] 不读取来源的冻结 Plugin ID
  * @returns {Promise<void>} 准备完成
  */
-async function prepareRemoteClosure(registry, initialIds) {
+async function prepareRemoteClosure(registry, initialIds, preserveIds = []) {
+  const preserved = new Set(preserveIds);
   const pending = [...new Set(initialIds)];
   const visited = new Set();
   while (pending.length > 0) {
     const id = pending.shift();
-    if (visited.has(id)) continue;
+    if (visited.has(id) || preserved.has(id)) continue;
     visited.add(id);
     const { sourceId } = parseCanonicalPluginId(id);
     if (!registry.has(sourceId)) continue;
     const provider = registry.get(sourceId);
-    if (typeof provider.prepare !== "function") continue;
-    await provider.prepare(id);
+    if (typeof provider.prepare === "function") await provider.prepare(id);
     for (const candidate of provider.listCandidates(id)) {
       pending.push(...Object.keys(candidate.manifest.dependencies || {}));
     }
@@ -679,11 +724,17 @@ async function prepareRemoteClosure(registry, initialIds) {
  *
  * @param {object} registry Provider 注册表
  * @param {import("../plugin/contracts.js").PluginLock|null} lock 当前 lock
+ * @param {string[]} [preserveIds] 不读取来源的冻结 Plugin ID
  * @returns {Promise<void>} 恢复完成
  */
-async function prepareRemoteLock(registry, lock) {
+async function prepareRemoteLock(registry, lock, preserveIds = []) {
+  const preserved = new Set(preserveIds);
   for (const plugin of lock?.plugins || []) {
-    if (!["gitlab", "github"].includes(plugin.source.type) || !registry.has(plugin.source.id)) continue;
+    if (
+      preserved.has(plugin.id) ||
+      !["gitlab", "github"].includes(plugin.source.type) ||
+      !registry.has(plugin.source.id)
+    ) continue;
     const provider = registry.get(plugin.source.id);
     if (typeof provider.prepareLocked === "function") await provider.prepareLocked(plugin);
     else if (typeof provider.prepare === "function") await provider.prepare(plugin.id);

package/src/commands/plugin.js

@@ -747,7 +747,7 @@ function pluginExitCode(error) {
  * 执行 Plugin 生命周期命令。
  *
  * @param {object} ctx cli-args.js 的执行上下文
- * @param {{cwd?:string,providers?:object[],output?:{log:(message:string)=>void,error:(message:string)=>void},interactive?:boolean,prompts?:object,confirmApproval?:(requests:object[])=>Promise<boolean>|boolean,compact?:boolean,onPreflight?:(result:object)=>void,trellisControlMode?:"materialized"|"restoring"}} [options] 测试、Provider、输出与交互确认注入
+ * @param {{cwd?:string,providers?:object[],output?:{log:(message:string)=>void,error:(message:string)=>void},interactive?:boolean,prompts?:object,confirmApproval?:(requests:object[])=>Promise<boolean>|boolean,compact?:boolean,preserveIds?:string[],onPreflight?:(result:object)=>void,trellisControlMode?:"materialized"|"restoring"}} [options] 测试、Provider、输出与交互确认注入
  * @returns {Promise<number>} 进程退出码
  */
 export async function plugin(ctx, options = {}) {
@@ -834,6 +834,7 @@ export async function plugin(ctx, options = {}) {
       options,
       registry,
       lock,
+      preserveIds: options.preserveIds || [],
     });
 
     if (parsed.command !== "add" && canonicalId && !canonicalId.includes("/")) {
@@ -889,7 +890,13 @@ export async function plugin(ctx, options = {}) {
       }));
     }
 
-    await remoteRuntime?.prepareRemotePluginCandidates({ parsed, canonicalId, registry, lock });
+    await remoteRuntime?.prepareRemotePluginCandidates({
+      parsed,
+      canonicalId,
+      registry,
+      lock,
+      preserveIds: options.preserveIds || [],
+    });
 
     const service = new PluginApplicationService(ctx.target, { registry, store });
     let result;
@@ -906,6 +913,7 @@ export async function plugin(ctx, options = {}) {
         platforms: parsed.platforms,
         ...(parsed.contentSelection ? { contentSelection: parsed.contentSelection } : {}),
         dryRun: parsed.dryRun,
+        preserveIds: options.preserveIds || [],
         onPreflight: options.onPreflight,
       };
       result = parsed.dryRun ? service.add(addOptions) : await executeWithCapabilityApproval(
@@ -925,6 +933,7 @@ export async function plugin(ctx, options = {}) {
         platforms: parsed.platforms,
         ...(parsed.contentSelection ? { contentSelection: parsed.contentSelection } : {}),
         dryRun: parsed.dryRun,
+        preserveIds: options.preserveIds || [],
         onPreflight: options.onPreflight,
       };
       result = parsed.dryRun ? service.update(updateOptions) : await executeWithCapabilityApproval(

package/src/commands/update.js

@@ -89,6 +89,13 @@ function pluginPlatformArgs(platforms) {
  */
 export async function replayPlugins(ctx, target, dryRun, compensationSnapshot = null) {
   const output = ctx.trellisControlQuiet ? SILENT_OUTPUT : console;
+  const store = new ProjectStore(target);
+  const lock = store.readLock();
+  const preserveIds = (lock?.plugins || [])
+    .filter(({ id, source }) => (
+      id !== SKILL_GARDEN_PLUGIN_ID && ["gitlab", "github"].includes(source.type)
+    ))
+    .map(({ id }) => id);
   const onPreflight = compensationSnapshot || ctx.trellisControlExtendSnapshot
     ? ({ plan }) => {
       const targets = [
@@ -100,7 +107,7 @@ export async function replayPlugins(ctx, target, dryRun, compensationSnapshot =
     }
     : undefined;
   if (ctx.enhance) {
-    const declared = new ProjectStore(target).readPlugins().plugins
+    const declared = store.readPlugins().plugins
       .some(({ id }) => id === SKILL_GARDEN_PLUGIN_ID);
     const code = await plugin({
       ...ctx,
@@ -113,6 +120,7 @@ export async function replayPlugins(ctx, target, dryRun, compensationSnapshot =
       ],
     }, {
       skillGarden: { variant: ctx.variant, skills: ctx.skills },
+      preserveIds,
       compact: true,
       onPreflight,
       output,
@@ -122,7 +130,7 @@ export async function replayPlugins(ctx, target, dryRun, compensationSnapshot =
   }
 
   output.log("· --no-enhance:跳过 Skill-Garden，仅重放其它已声明 Plugin");
-  const preserveSkillGarden = new ProjectStore(target).readLock()?.plugins
+  const preserveSkillGarden = lock?.plugins
     .some(({ id }) => id === SKILL_GARDEN_PLUGIN_ID) === true;
   const code = await plugin({
     ...ctx,

package/src/plugin/application-service.js

@@ -22,6 +22,8 @@ import {
   selectContentSkillEntries,
 } from "./content-selection.js";
 
+const SKILL_GARDEN_MIGRATION_OWNER_ID = "flower/skill-garden";
+
 /**
  * 计算 lock roots 可达的全部 Plugin。
  *
@@ -122,6 +124,94 @@ function standardContentPlan(graph) {
   };
 }
 
+/**
+ * 校验冻结 Plugin 的 lock/state 对应关系与当前目标摘要。
+ *
+ * @param {string} projectRoot 项目根
+ * @param {import("./contracts.js").ResolvedPlugin} locked 冻结 lock entry
+ * @param {import("./contracts.js").PluginStateEntry} applied 冻结 state entry
+ * @returns {void}
+ */
+function assertPreservedState(projectRoot, locked, applied) {
+  if (
+    applied.version !== locked.version ||
+    !contentSelectionsEqual(applied.contentSelection, locked.contentSelection)
+  ) {
+    throw new PluginRuntimeError(`冻结 Plugin 的 lock/state 不一致:${locked.id}`, {
+      code: PLUGIN_RUNTIME_ERROR_CODES.TARGET_DRIFT,
+      path: locked.id,
+    });
+  }
+  for (const entry of applied.paths) {
+    const target = path.join(projectRoot, ...entry.path.split("/"));
+    const actual = entry.kind === "directory"
+      ? hashDirectoryIfExists(target)
+      : hashFileIfExists(target);
+    if (actual !== entry.hash) {
+      throw new PluginRuntimeError(`冻结 Plugin 目标摘要漂移:${entry.path}`, {
+        code: PLUGIN_RUNTIME_ERROR_CODES.TARGET_DRIFT,
+        path: entry.path,
+        details: { expected: entry.hash, actual },
+      });
+    }
+  }
+  for (const patchEntry of applied.patches) {
+    const target = path.join(projectRoot, ...patchEntry.target.split("/"));
+    const actual = hashFileIfExists(target);
+    if (actual !== patchEntry.resultHash) {
+      throw new PluginRuntimeError(`冻结 Plugin Patch 目标摘要漂移:${patchEntry.target}`, {
+        code: PLUGIN_RUNTIME_ERROR_CODES.TARGET_DRIFT,
+        path: patchEntry.target,
+        details: { expected: patchEntry.resultHash, actual },
+      });
+    }
+  }
+}
+
+/**
+ * 判断两个项目内路径是否相同或存在父子关系。
+ *
+ * @param {string} left 左路径
+ * @param {string} right 右路径
+ * @returns {boolean} 是否相交
+ */
+function pathsOverlap(left, right) {
+  return left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
+}
+
+/**
+ * 阻止活跃 Plugin 的计划改写冻结 Plugin 的受管目标。
+ *
+ * @param {import("./contracts.js").PluginStateEntry[]} preservedEntries 冻结 state entries
+ * @param {{mutations?:Array<{owner:string,target:string}>,directoryClaims?:Array<{owner:string,path:string}>,directoryRemovals?:Array<{owner:string,path:string}>,patchMutations?:Array<{owner:string,target:string}>}} plan 活跃计划片段
+ * @returns {void}
+ */
+function assertNoPreservedTargetConflicts(preservedEntries, plan) {
+  const protectedTargets = preservedEntries.flatMap((plugin) => [
+    ...plugin.paths.map(({ path: target }) => ({ owner: plugin.id, target })),
+    ...plugin.patches.map(({ target }) => ({ owner: plugin.id, target })),
+  ]);
+  const activeTargets = [
+    ...(plan.mutations || []).map(({ owner, target }) => ({ owner, target })),
+    ...(plan.directoryClaims || []).map(({ owner, path: target }) => ({ owner, target })),
+    ...(plan.directoryRemovals || []).map(({ owner, path: target }) => ({ owner, target })),
+    ...(plan.patchMutations || []).map(({ owner, target }) => ({ owner, target })),
+  ];
+  for (const active of activeTargets) {
+    const protectedTarget = protectedTargets.find((entry) => pathsOverlap(active.target, entry.target));
+    if (!protectedTarget) continue;
+    throw new PluginRuntimeError(`活跃 Plugin 计划与冻结目标冲突:${active.target}`, {
+      code: PLUGIN_RUNTIME_ERROR_CODES.CONTENT_CONFLICT,
+      path: active.target,
+      details: {
+        activeOwner: active.owner,
+        preservedOwner: protectedTarget.owner,
+        preservedTarget: protectedTarget.target,
+      },
+    });
+  }
+}
+
 /**
  * Flower Plugin 生命周期应用服务。
  */
@@ -156,7 +246,7 @@ export class PluginApplicationService {
   /**
    * 添加或更新一个直接 Plugin 声明并应用完整图。
    *
-   * @param {{id:string,version?:string,platforms?:string[],contentSelection?:import("./contracts.js").PluginContentSelection,dryRun?:boolean,approvals?:string[],approvedDigests?:Map<string,string>|Record<string,string>,nonInteractive?:boolean,onPreflight?:(result:object)=>void}} options 添加选项
+   * @param {{id:string,version?:string,platforms?:string[],contentSelection?:import("./contracts.js").PluginContentSelection,dryRun?:boolean,approvals?:string[],approvedDigests?:Map<string,string>|Record<string,string>,nonInteractive?:boolean,preserveIds?:string[],onPreflight?:(result:object)=>void}} options 添加选项
    * @returns {object} 生命周期结果
    */
   add(options) {
@@ -188,6 +278,7 @@ export class PluginApplicationService {
       approvals: options.approvals || [],
       approvedDigests: options.approvedDigests,
       nonInteractive: options.nonInteractive,
+      preserveIds: options.preserveIds || [],
       onPreflight: options.onPreflight,
     });
   }
@@ -199,7 +290,7 @@ export class PluginApplicationService {
    * 其锁定包也已不可重放，逐个更新会在其它节点上撞 `已锁定 Plugin 包不可重放`。
    * 传入 `widen` 时按 `update: "all"` 解析，让全部节点都允许升级，一次性解开这种死锁。
    *
-   * @param {{id?:string|null,version?:string,widen?:Map<string,string>|Record<string,string>,contentSelection?:import("./contracts.js").PluginContentSelection|null,platforms?:string[],dryRun?:boolean,approvals?:string[],approvedDigests?:Map<string,string>|Record<string,string>,nonInteractive?:boolean,onPreflight?:(result:object)=>void}} [options] 更新选项
+   * @param {{id?:string|null,version?:string,widen?:Map<string,string>|Record<string,string>,contentSelection?:import("./contracts.js").PluginContentSelection|null,platforms?:string[],dryRun?:boolean,approvals?:string[],approvedDigests?:Map<string,string>|Record<string,string>,nonInteractive?:boolean,preserveIds?:string[],onPreflight?:(result:object)=>void}} [options] 更新选项
    * @returns {object} 生命周期结果
    */
   update(options = {}) {
@@ -280,6 +371,7 @@ export class PluginApplicationService {
       approvals: options.approvals || [],
       approvedDigests: options.approvedDigests,
       nonInteractive: options.nonInteractive,
+      preserveIds: options.preserveIds || [],
       onPreflight: options.onPreflight,
     });
   }
@@ -557,10 +649,39 @@ export class PluginApplicationService {
     const pluginsFile = validatePluginsFile(input.plugins);
     const previousLock = this.store.readLock();
     const previousState = this.store.readState();
+    const preservedIds = new Set(input.preserveIds || []);
+    const previousLockById = new Map((previousLock?.plugins || []).map((plugin) => [plugin.id, plugin]));
+    const previousStateById = new Map((previousState?.plugins || []).map((plugin) => [plugin.id, plugin]));
     const resolution = resolvePluginGraph(pluginsFile.plugins, this.registry, {
       lockedPlugins: previousLock?.plugins || [],
       update: input.update,
+      preserveIds: [...preservedIds],
     });
+    const resolvedIds = new Set(resolution.graph.plugins.map(({ id }) => id));
+    const preservedEntries = [];
+    for (const id of [...preservedIds].sort(compareUtf8)) {
+      const previousLocked = previousLockById.get(id);
+      const previousEntry = previousStateById.get(id);
+      if (!previousLocked || !resolvedIds.has(id)) {
+        throw new PluginRuntimeError(`冻结 Plugin 缺少既有 lock:${id}`, {
+          code: PLUGIN_RUNTIME_ERROR_CODES.TARGET_DRIFT,
+          path: id,
+        });
+      }
+      if (!previousEntry) {
+        throw new PluginRuntimeError(`冻结 Plugin 缺少既有 state:${id}`, {
+          code: PLUGIN_RUNTIME_ERROR_CODES.TARGET_DRIFT,
+          path: id,
+        });
+      }
+      assertPreservedState(this.projectRoot, previousLocked, previousEntry);
+      preservedEntries.push(previousEntry);
+    }
+    const activeGraph = {
+      roots: resolution.graph.roots.filter((id) => !preservedIds.has(id)),
+      plugins: resolution.graph.plugins.filter(({ id }) => !preservedIds.has(id)),
+    };
+    const activeSelected = resolution.selected.filter(({ id }) => !preservedIds.has(id));
     let projection = {
       mutations: [],
       payloads: new Map(),
@@ -569,47 +690,45 @@ export class PluginApplicationService {
       directoryRemovals: [],
     };
     let platformSelection = { platforms: [], targets: [] };
-    if (resolution.graph.plugins.length > 0) {
+    if (activeGraph.plugins.length > 0) {
       const platforms = input.platforms.length > 0
         ? input.platforms
         : statePlatforms(previousState);
       platformSelection = this.platformDetector(this.projectRoot, platforms);
       projection = projectPluginContent({
         projectRoot: this.projectRoot,
-        graph: resolution.graph,
-        selected: resolution.selected,
+        graph: activeGraph,
+        selected: activeSelected,
         registry: this.registry,
         platformSelection,
         previousState,
       });
     }
-    const preservedIds = new Set(input.preserveIds || []);
     if (preservedIds.size > 0) {
-      for (const id of preservedIds) {
-        const previousEntry = previousState?.plugins.find((plugin) => plugin.id === id);
-        const nextIndex = projection.state.plugins.findIndex((plugin) => plugin.id === id);
-        if (!previousEntry || nextIndex < 0) {
-          throw new PluginRuntimeError(`冻结 Plugin 缺少既有 state:${id}`, {
-            code: PLUGIN_RUNTIME_ERROR_CODES.TARGET_DRIFT,
-            path: id,
-          });
-        }
-        projection.state.plugins[nextIndex] = structuredClone(previousEntry);
-        const previousLocked = previousLock?.plugins.find((plugin) => plugin.id === id);
-        const graphIndex = resolution.graph.plugins.findIndex((plugin) => plugin.id === id);
-        if (!previousLocked || graphIndex < 0) {
-          throw new PluginRuntimeError(`冻结 Plugin 缺少既有 lock:${id}`, {
-            code: PLUGIN_RUNTIME_ERROR_CODES.TARGET_DRIFT,
-            path: id,
-          });
-        }
-        resolution.graph.plugins[graphIndex] = structuredClone(previousLocked);
-      }
-      projection.mutations = projection.mutations.filter(({ owner }) => !preservedIds.has(owner));
-      projection.directoryClaims = projection.directoryClaims.filter(({ owner }) => !preservedIds.has(owner));
-      projection.directoryRemovals = projection.directoryRemovals
-        .filter(({ owner }) => !preservedIds.has(owner));
-      if (previousState?.migration) projection.state.migration = structuredClone(previousState.migration);
+      const projectedStateById = new Map(projection.state.plugins.map((plugin) => [plugin.id, plugin]));
+      projection.state.plugins = resolution.graph.plugins.map(({ id }) => {
+        if (preservedIds.has(id)) return structuredClone(previousStateById.get(id));
+        const projected = projectedStateById.get(id);
+        if (!projected) throw new Error(`Resolved Plugin 缺少投影 state:${id}`);
+        return projected;
+      });
+      resolution.graph.plugins = resolution.graph.plugins.map((plugin) => (
+        preservedIds.has(plugin.id)
+          ? structuredClone(previousLockById.get(plugin.id))
+          : plugin
+      ));
+      assertNoPreservedTargetConflicts(preservedEntries, {
+        mutations: projection.mutations,
+        directoryClaims: projection.directoryClaims,
+        directoryRemovals: projection.directoryRemovals,
+      });
+    }
+    if (
+      preservedIds.has(SKILL_GARDEN_MIGRATION_OWNER_ID) &&
+      !projection.state.migration &&
+      previousState?.migration
+    ) {
+      projection.state.migration = structuredClone(previousState.migration);
     }
 
     const previousDirectories = new Map();
@@ -619,7 +738,11 @@ export class PluginApplicationService {
       }
     }
     const directoryClaims = [];
-    const desiredDirectoryPaths = new Set();
+    const desiredDirectoryPaths = new Set(
+      projection.state.plugins.flatMap((plugin) => plugin.paths
+        .filter(({ kind }) => kind === "directory")
+        .map(({ path: target }) => target)),
+    );
     const directoryOwners = new Map();
     for (const claim of projection.directoryClaims) {
       desiredDirectoryPaths.add(claim.path);
@@ -697,6 +820,12 @@ export class PluginApplicationService {
         });
       }
     }
+    if (preservedIds.size > 0) {
+      assertNoPreservedTargetConflicts(preservedEntries, {
+        mutations: removalMutations,
+        directoryRemovals,
+      });
+    }
 
     const patchPlanner = getPluginPatchPlanner();
     let patchResult = standardContentPlan(resolution.graph);
@@ -774,6 +903,11 @@ export class PluginApplicationService {
         });
       }
     }
+    if (preservedIds.size > 0) {
+      assertNoPreservedTargetConflicts(preservedEntries, {
+        patchMutations: patchResult.patchMutations,
+      });
+    }
     const grants = new Map(patchResult.grants.map(({ pluginId, grant }) => [pluginId, grant]));
     for (const plugin of resolution.graph.plugins) {
       const grant = grants.get(plugin.id) || (

package/src/plugin/resolver/dependency-resolver.js

@@ -3,6 +3,7 @@ import {
   PLUGIN_RUNTIME_ERROR_CODES,
   PluginRuntimeError,
 } from "../runtime-errors.js";
+import { parseCanonicalPluginId } from "../schemas/shared.js";
 import { compareUtf8 } from "../stable-order.js";
 import { normalizeContentSelection } from "../content-selection.js";
 
@@ -41,6 +42,40 @@ function defaultCapabilityGrant(request) {
   };
 }
 
+/**
+ * 从旧 lock 合成只参与依赖求解的冻结候选。
+ *
+ * 冻结候选不代表本地仍有可读取的 Plugin 包，因此 content 只放合法占位值；调用方必须在
+ * 内容投影前剥离该候选，并原样复用旧 lock/state。
+ *
+ * @param {import("../contracts.js").ResolvedPlugin} locked 已锁定 Plugin
+ * @returns {import("../contracts.js").PluginCandidate} 冻结候选
+ */
+function createPreservedCandidate(locked) {
+  const { pluginId } = parseCanonicalPluginId(locked.id);
+  return {
+    id: locked.id,
+    version: locked.version,
+    source: structuredClone(locked.source),
+    commit: locked.commit,
+    integrity: locked.integrity,
+    manifest: {
+      schemaVersion: 1,
+      id: pluginId,
+      name: locked.id,
+      version: locked.version,
+      compatibility: structuredClone(locked.compatibility),
+      dependencies: structuredClone(locked.dependencies),
+      capabilities: {
+        profile: locked.capabilities.profile,
+        required: [...locked.capabilities.granted],
+        optional: [...locked.capabilities.denied],
+      },
+      content: { skills: [] },
+    },
+  };
+}
+
 /**
  * 深复制约束映射。
  *
@@ -162,7 +197,7 @@ function stableTopologicalOrder(roots, selected) {
  *
  * @param {import("../contracts.js").ProjectPluginDeclaration[]} declarations 直接声明
  * @param {{listCandidates:(id:string)=>import("../contracts.js").PluginCandidate[]}} registry Source Registry
- * @param {{lockedPlugins?:import("../contracts.js").ResolvedPlugin[],update?:string[]|"all",grantCapabilities?:(request:import("../contracts.js").CapabilityRequest,candidate:import("../contracts.js").PluginCandidate)=>import("../contracts.js").CapabilityGrant}} [options] 解析选项
+ * @param {{lockedPlugins?:import("../contracts.js").ResolvedPlugin[],update?:string[]|"all",preserveIds?:string[],grantCapabilities?:(request:import("../contracts.js").CapabilityRequest,candidate:import("../contracts.js").PluginCandidate)=>import("../contracts.js").CapabilityGrant}} [options] 解析选项
  * @returns {{graph:import("../contracts.js").ResolvedGraph,selected:import("../contracts.js").PluginCandidate[],orphans:string[],constraints:Record<string,Array<{range:string,from:string}>>}} 解析结果
  */
 export function resolvePluginGraph(declarations, registry, options = {}) {
@@ -172,10 +207,20 @@ export function resolvePluginGraph(declarations, registry, options = {}) {
   const updateIds = options.update === "all"
     ? new Set(lockedPlugins.map(({ id }) => id))
     : new Set(options.update || []);
+  const preservedIds = new Set(options.preserveIds || []);
   const grantCapabilities = options.grantCapabilities || defaultCapabilityGrant;
   const initialConstraints = new Map();
   const rootDeclarations = new Map(declarations.map((declaration) => [declaration.id, declaration]));
 
+  for (const id of [...preservedIds].sort(compareUtf8)) {
+    if (!lockedById.has(id)) {
+      throw new PluginRuntimeError(`冻结 Plugin 缺少既有 lock:${id}`, {
+        code: PLUGIN_RUNTIME_ERROR_CODES.TARGET_DRIFT,
+        path: id,
+      });
+    }
+  }
+
   for (const declaration of [...declarations].sort((left, right) => compareUtf8(left.id, right.id))) {
     const entries = initialConstraints.get(declaration.id) || [];
     entries.push({ range: declaration.version, from: "project" });
@@ -201,11 +246,15 @@ export function resolvePluginGraph(declarations, registry, options = {}) {
     if (!nextId) return { selected, constraints };
 
     let candidates;
-    try {
-      candidates = registry.listCandidates(nextId);
-    } catch (error) {
-      if (error?.code !== PLUGIN_RUNTIME_ERROR_CODES.SOURCE_NOT_FOUND) throw error;
-      candidates = [];
+    if (preservedIds.has(nextId)) {
+      candidates = [createPreservedCandidate(lockedById.get(nextId))];
+    } else {
+      try {
+        candidates = registry.listCandidates(nextId);
+      } catch (error) {
+        if (error?.code !== PLUGIN_RUNTIME_ERROR_CODES.SOURCE_NOT_FOUND) throw error;
+        candidates = [];
+      }
     }
     if (candidates.length === 0) {
       throw new PluginRuntimeError(`找不到 Plugin 依赖:${nextId}`, {
@@ -298,7 +347,9 @@ export function resolvePluginGraph(declarations, registry, options = {}) {
       integrity: candidate.integrity,
       dependencies,
       compatibility: candidate.manifest.compatibility,
-      capabilities: grantCapabilities(candidate.manifest.capabilities, candidate),
+      capabilities: preservedIds.has(id)
+        ? structuredClone(lockedById.get(id).capabilities)
+        : grantCapabilities(candidate.manifest.capabilities, candidate),
       ...(contentSelection ? { contentSelection } : {}),
     };
   });