flower-trellis 0.6.3 → 0.6.5

package/src/plugin/application-service.js

@@ -21,26 +21,9 @@ import {
   normalizeContentSelection,
   selectContentSkillEntries,
 } from "./content-selection.js";
+import { classifyLockReachability } from "./lock-reachability.js";
 
-/**
- * 计算 lock roots 可达的全部 Plugin。
- *
- * @param {import("./contracts.js").PluginLock} lock Plugin lock
- * @returns {Set<string>} 可达 Plugin ID
- */
-function reachableLockIds(lock) {
-  const byId = new Map(lock.plugins.map((plugin) => [plugin.id, plugin]));
-  const reachable = new Set();
-  const visit = (id) => {
-    if (reachable.has(id)) return;
-    reachable.add(id);
-    const plugin = byId.get(id);
-    if (!plugin) return;
-    Object.keys(plugin.dependencies).sort(compareUtf8).forEach(visit);
-  };
-  [...lock.roots].sort(compareUtf8).forEach(visit);
-  return reachable;
-}
+const SKILL_GARDEN_MIGRATION_OWNER_ID = "flower/skill-garden";
 
 /**
  * 汇总既有 Plugin state 的实际投影平台，供无显式选择的生命周期继续复用。
@@ -122,6 +105,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 +227,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 +259,7 @@ export class PluginApplicationService {
       approvals: options.approvals || [],
       approvedDigests: options.approvedDigests,
       nonInteractive: options.nonInteractive,
+      preserveIds: options.preserveIds || [],
       onPreflight: options.onPreflight,
     });
   }
@@ -199,7 +271,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 +352,7 @@ export class PluginApplicationService {
       approvals: options.approvals || [],
       approvedDigests: options.approvedDigests,
       nonInteractive: options.nonInteractive,
+      preserveIds: options.preserveIds || [],
       onPreflight: options.onPreflight,
     });
   }
@@ -397,10 +470,10 @@ export class PluginApplicationService {
       }
     }
     if (lock) {
-      const reachable = reachableLockIds(lock);
+      const { reachableIds } = classifyLockReachability(pluginsFile.plugins, lock);
       for (const id of [...lockById.keys()].sort(compareUtf8)) {
         if (options.id && id !== options.id) continue;
-        if (!reachable.has(id)) {
+        if (!reachableIds.has(id)) {
           diagnostics.push({
             code: "verify.lock-orphan",
             path: id,
@@ -557,10 +630,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 +671,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 +719,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);
@@ -665,6 +769,7 @@ export class PluginApplicationService {
           if (desiredDirectoryPaths.has(entry.path)) continue;
           const target = path.join(this.projectRoot, ...entry.path.split("/"));
           const currentHash = hashDirectoryIfExists(target);
+          if (currentHash === null) continue;
           if (currentHash !== entry.hash) {
             throw new PluginRuntimeError(`受管 Plugin 目录已被用户修改，拒绝删除:${entry.path}`, {
               code: PLUGIN_RUNTIME_ERROR_CODES.CONTENT_CONFLICT,
@@ -680,6 +785,7 @@ export class PluginApplicationService {
         if (desiredPaths.has(entry.path)) continue;
         const target = path.join(this.projectRoot, ...entry.path.split("/"));
         const currentHash = hashFileIfExists(target);
+        if (currentHash === null) continue;
         if (currentHash !== entry.hash) {
           throw new PluginRuntimeError(`受管 Plugin 文件已被用户修改，拒绝删除:${entry.path}`, {
             code: PLUGIN_RUNTIME_ERROR_CODES.CONTENT_CONFLICT,
@@ -697,6 +803,12 @@ export class PluginApplicationService {
         });
       }
     }
+    if (preservedIds.size > 0) {
+      assertNoPreservedTargetConflicts(preservedEntries, {
+        mutations: removalMutations,
+        directoryRemovals,
+      });
+    }
 
     const patchPlanner = getPluginPatchPlanner();
     let patchResult = standardContentPlan(resolution.graph);
@@ -774,6 +886,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/contracts.js

@@ -118,6 +118,7 @@
  * @property {"gitlab"} type GitLab 来源
  * @property {string} reference GitLab project path
  * @property {string} [indexCommit] Marketplace 索引 commit
+ * @property {string} [indexPath] Marketplace 索引安全相对路径
  */
 
 /**

package/src/plugin/lock-reachability.js

@@ -0,0 +1,37 @@
+import { compareUtf8 } from "./stable-order.js";
+
+/**
+ * 从当前直接声明出发，分类既有 lock 中的可达、孤立和缺失节点。
+ *
+ * lock roots 可能来自半清理的旧项目，不能作为活跃 Plugin 的事实入口。调用方应使用当前
+ * `plugins.json` 声明开始遍历，才能在不访问外部来源的前提下识别可冻结节点和孤立状态。
+ *
+ * @param {import("./contracts.js").ProjectPluginDeclaration[]} declarations 当前直接声明
+ * @param {import("./contracts.js").PluginLock|null} lock 既有 Plugin lock
+ * @returns {{reachableIds:Set<string>,orphanIds:Set<string>,missingIds:Set<string>}} lock 节点分类
+ */
+export function classifyLockReachability(declarations, lock) {
+  const plugins = lock?.plugins || [];
+  const byId = new Map(plugins.map((plugin) => [plugin.id, plugin]));
+  const visited = new Set();
+  const reachableIds = new Set();
+  const missingIds = new Set();
+
+  const visit = (id) => {
+    if (visited.has(id)) return;
+    visited.add(id);
+    const plugin = byId.get(id);
+    if (!plugin) {
+      missingIds.add(id);
+      return;
+    }
+    reachableIds.add(id);
+    Object.keys(plugin.dependencies).sort(compareUtf8).forEach(visit);
+  };
+
+  declarations.map(({ id }) => id).sort(compareUtf8).forEach(visit);
+  const orphanIds = new Set(
+    plugins.map(({ id }) => id).filter((id) => !reachableIds.has(id)).sort(compareUtf8),
+  );
+  return { reachableIds, orphanIds, missingIds };
+}

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 } : {}),
     };
   });

package/src/plugin/schemas/project-files.js

@@ -38,6 +38,7 @@ const sourceDescriptorSchema = {
         type: { const: "gitlab" },
         reference: { type: "string", format: "gitlab-project" },
         indexCommit: { type: "string", format: "git-commit" },
+        indexPath: SAFE_PATH_SCHEMA,
       },
     },
     {

package/src/plugin/sources/gitlab-provider.js

@@ -20,6 +20,9 @@ import {
 } from "./remote-archive.js";
 
 const PROFILE_RANK = Object.freeze({ standard: 0, integration: 1, system: 2 });
+const RD_GUIDE_SOURCE_ID = "rd-guide";
+const RD_GUIDE_PROJECT = "digital-rd-governance/rd-guide";
+const LEGACY_RD_GUIDE_MARKETPLACE_PATH = ".flower-marketplace/marketplace.json";
 
 /**
  * GitLab Marketplace Provider；网络阶段由 prepare() 显式触发。
@@ -178,6 +181,7 @@ export class GitLabSourceProvider {
       inspected.version,
       manifest,
       inspected.indexCommit,
+      inspected.indexPath,
     );
     if (lockedPlugin) this.#assertLockedInspectionMatches(lockedPlugin, candidate);
     return candidate;
@@ -191,6 +195,7 @@ export class GitLabSourceProvider {
    */
   async prepareLocked(plugin) {
     if (this.packageRoots.has(this.#key(plugin))) return;
+    const indexPath = this.#lockedMarketplacePath(plugin);
     const cached = this.#findCachedPackage(plugin);
     if (cached) {
       this.#registerLockedCandidate(plugin, cached.root, cached.manifest, "standard");
@@ -198,7 +203,7 @@ export class GitLabSourceProvider {
     }
     const raw = await this.client.readRawFile(
       this.source.project,
-      this.source.marketplacePath,
+      indexPath,
       plugin.source.indexCommit,
     );
     let marketplace;
@@ -627,7 +632,7 @@ export class GitLabSourceProvider {
    *
    * @param {string} pluginId Plugin 本地 ID
    * @param {string} requestedVersion 请求版本
-   * @returns {Promise<{entry:object,version:object,indexCommit:string}>} Marketplace 版本上下文
+   * @returns {Promise<{entry:object,version:object,indexCommit:string,indexPath:string}>} Marketplace 版本上下文
    */
   async #marketplaceVersionForInspection(pluginId, requestedVersion) {
     const marketplace = await this.prepareIndex();
@@ -639,7 +644,7 @@ export class GitLabSourceProvider {
         path: `${this.id}/${pluginId}`,
       });
     }
-    return { entry, version, indexCommit: this.indexCommit };
+    return { entry, version, indexCommit: this.indexCommit, indexPath: this.source.marketplacePath };
   }
 
   /**
@@ -647,12 +652,13 @@ export class GitLabSourceProvider {
    *
    * @param {string} pluginId Plugin 本地 ID
    * @param {import("../contracts.js").ResolvedPlugin} plugin 已锁定 Plugin
-   * @returns {Promise<{entry:object,version:object,indexCommit:string}>} Marketplace 版本上下文
+   * @returns {Promise<{entry:object,version:object,indexCommit:string,indexPath:string}>} Marketplace 版本上下文
    */
   async #lockedMarketplaceVersionForInspection(pluginId, plugin) {
+    const indexPath = this.#lockedMarketplacePath(plugin);
     const raw = await this.client.readRawFile(
       this.source.project,
-      this.source.marketplacePath,
+      indexPath,
       plugin.source.indexCommit,
     );
     let marketplace;
@@ -683,7 +689,7 @@ export class GitLabSourceProvider {
         path: plugin.id,
       });
     }
-    return { entry, version, indexCommit: plugin.source.indexCommit };
+    return { entry, version, indexCommit: plugin.source.indexCommit, indexPath };
   }
 
   /**
@@ -700,7 +706,8 @@ export class GitLabSourceProvider {
       lockedPlugin.commit.toLowerCase() !== candidate.commit ||
       lockedPlugin.integrity !== candidate.integrity ||
       lockedPlugin.source.reference !== candidate.source.reference ||
-      lockedPlugin.source.indexCommit !== candidate.source.indexCommit
+      lockedPlugin.source.indexCommit !== candidate.source.indexCommit ||
+      this.#lockedMarketplacePath(lockedPlugin) !== candidate.source.indexPath
     ) {
       throw new PluginRuntimeError(`GitLab lock 与 Marketplace 不一致:${lockedPlugin.id}`, {
         code: PLUGIN_RUNTIME_ERROR_CODES.TARGET_DRIFT,
@@ -717,9 +724,17 @@ export class GitLabSourceProvider {
    * @param {object} version Marketplace 版本条目
    * @param {object} manifest 已校验 Plugin manifest
    * @param {string} [indexCommit] Marketplace index commit
+   * @param {string} [indexPath] Marketplace index path
    * @returns {import("../contracts.js").PluginCandidate} Provider 候选
    */
-  #candidateFromMarketplaceVersion(canonicalId, entry, version, manifest, indexCommit = this.indexCommit) {
+  #candidateFromMarketplaceVersion(
+    canonicalId,
+    entry,
+    version,
+    manifest,
+    indexCommit = this.indexCommit,
+    indexPath = this.source.marketplacePath,
+  ) {
     const id = composeCanonicalPluginId(this.id, manifest.id);
     if (id !== canonicalId || manifest.version !== version.version) {
       throw new PluginRuntimeError(`远程 Plugin 身份与索引不一致:${canonicalId}@${version.version}`, {
@@ -741,6 +756,7 @@ export class GitLabSourceProvider {
         type: "gitlab",
         reference: this.#sourceReference(entry.source),
         indexCommit,
+        indexPath: assertSafePosixRelativePath(indexPath, "Marketplace index path"),
       },
       commit: version.commit.toLowerCase(),
       integrity: version.integrity,
@@ -825,7 +841,10 @@ export class GitLabSourceProvider {
     const candidate = {
       id: plugin.id,
       version: plugin.version,
-      source: plugin.source,
+      source: {
+        ...plugin.source,
+        indexPath: this.#lockedMarketplacePath(plugin),
+      },
       commit: plugin.commit,
       integrity: plugin.integrity,
       manifest,
@@ -834,6 +853,28 @@ export class GitLabSourceProvider {
     this.#registerCandidate(candidate, root);
   }
 
+  /**
+   * 解析旧 lock 固定使用的 Marketplace 路径。
+   *
+   * 旧 RD Guide 独立 Plugin 只存在于历史 `.flower-marketplace` 索引；该映射同时限定来源
+   * ID、项目和 Plugin ID 族，避免对其它 GitLab Marketplace 做多路径探测或误判。
+   *
+   * @param {import("../contracts.js").ResolvedPlugin} plugin 已锁定 Plugin
+   * @returns {string} 安全的固定 Marketplace 索引路径
+   */
+  #lockedMarketplacePath(plugin) {
+    const indexPath = plugin.source.indexPath || (
+      this.id === RD_GUIDE_SOURCE_ID &&
+      this.source.project === RD_GUIDE_PROJECT &&
+      plugin.source.id === RD_GUIDE_SOURCE_ID &&
+      plugin.source.reference === RD_GUIDE_PROJECT &&
+      plugin.id.startsWith(`${RD_GUIDE_SOURCE_ID}/xhgj-`)
+        ? LEGACY_RD_GUIDE_MARKETPLACE_PATH
+        : this.source.marketplacePath
+    );
+    return assertSafePosixRelativePath(indexPath, "Marketplace index path");
+  }
+
   /**
    * 登记已准备固定包候选。
    *