flower-trellis 0.6.2 → 0.6.4

package/src/commands/plugin-remote.js

@@ -7,13 +7,17 @@ import {
   PluginRuntimeError,
 } from "../plugin/runtime-errors.js";
 import { parseCanonicalPluginId } from "../plugin/schemas/shared.js";
+import { GITLAB_OAUTH_REQUEST_SCOPES } from "../plugin/auth/credential-store.js";
+import { GitLabCredentialResolver } from "../plugin/auth/gitlab-credential-resolver.js";
 import { createCredentialStore } from "../plugin/auth/keyring-credential-store.js";
 import { GitLabCredentialManager, GitLabOAuthClient } from "../plugin/auth/gitlab-oauth.js";
 import { GitLabRestClient } from "../plugin/gitlab/rest-client.js";
 import { GitHubRestClient } from "../plugin/github/rest-client.js";
 import { GitLabSourceProvider } from "../plugin/sources/gitlab-provider.js";
 import { GitHubSourceProvider } from "../plugin/sources/github-provider.js";
+import { SourceRegistry } from "../plugin/sources/source-registry.js";
 import { UserSourceStore } from "../plugin/sources/user-source-store.js";
+import { listContentSkillChoices } from "../plugin/content-selection.js";
 import { compareUtf8 } from "../plugin/stable-order.js";
 
 /**
@@ -53,8 +57,9 @@ function printManagementResult(result, json, output) {
     return;
   }
   if (result.subcommand === "status") {
+    const scopeSuffix = result.scopes?.length ? `，scope=${result.scopes.join(",")}` : "";
     output.log(result.authorized
-      ? `GitLab 已登录:${result.sourceId}，scope=${result.scopes.join(",")}`
+      ? `GitLab 已登录:${result.sourceId}${scopeSuffix}`
       : `GitLab 未登录:${result.sourceId}`);
   } else output.log(`GitLab auth ${result.subcommand} 完成:${result.sourceId}`);
   if (result.persistent === false) output.log("系统 Keyring 不可用，凭据仅在当前进程内有效");
@@ -134,16 +139,23 @@ export async function getPluginAuthStatus(sourceId, options = {}) {
     };
   }
   const credentialBundle = options.credentialBundle || await createCredentialStore(options.credentialStoreOptions);
-  const credential = await credentialBundle.store.get(source);
+  const resolver = options.credentialResolver || new GitLabCredentialResolver({
+    store: credentialBundle.store,
+    persistent: credentialBundle.persistent,
+    env: options.env,
+    runGlab: options.runGlab,
+    glabCommand: options.glabCommand,
+  });
+  const status = await resolver.status(source);
   return {
     ok: true,
     command: "auth",
     subcommand: "status",
     sourceId: source.id,
-    authorized: Boolean(credential),
-    scopes: credential?.scope || [],
-    expiresAt: credential?.expiresAt || null,
-    persistent: credentialBundle.persistent,
+    authorized: status.authorized,
+    scopes: status.scopes,
+    expiresAt: status.expiresAt,
+    persistent: status.persistent,
   };
 }
 
@@ -167,7 +179,16 @@ export async function searchPluginMarketplaces(parsed, ctx, options = {}) {
       sleep: options.sleep,
       now: options.now,
     });
-    manager = new GitLabCredentialManager({ store: credentialBundle.store, oauth, now: options.now });
+    manager = new GitLabCredentialManager({
+      store: credentialBundle.store,
+      oauth,
+      now: options.now,
+      persistent: credentialBundle.persistent,
+      credentialResolver: options.credentialResolver,
+      env: options.env,
+      runGlab: options.runGlab,
+      glabCommand: options.glabCommand,
+    });
   }
   const results = [];
   const diagnostics = [];
@@ -193,6 +214,122 @@ export async function searchPluginMarketplaces(parsed, ctx, options = {}) {
   };
 }
 
+/**
+ * 为 TUI 按需读取 Marketplace Plugin 的 manifest Skill 清单。
+ *
+ * @param {{pluginId:string,version?:string,source?:string|null,lockedPlugin?:import("../plugin/contracts.js").ResolvedPlugin|null}} request 读取请求
+ * @param {object} ctx CLI 上下文
+ * @param {object} [options] Provider、凭据和测试注入
+ * @returns {Promise<{ok:true,pluginId:string,version:string,name:string,skills:Array<{name:string,path:string,description?:string,version?:string}>}>} Skill 清单
+ */
+export async function inspectPluginContentSkills(request, ctx, options = {}) {
+  const canonicalId = request.pluginId || request.lockedPlugin?.id;
+  if (!canonicalId) {
+    throw new PluginRuntimeError("读取 Plugin Skill 清单需要 Plugin ID", {
+      code: PLUGIN_RUNTIME_ERROR_CODES.USAGE_ERROR,
+      path: "pluginId",
+    });
+  }
+  const registry = new SourceRegistry(options.providers || []);
+  const lock = request.lockedPlugin
+    ? { schemaVersion: 1, roots: [request.lockedPlugin.id], plugins: [request.lockedPlugin] }
+    : null;
+  const parsed = request.lockedPlugin
+    ? { command: "verify", pluginId: canonicalId, source: null }
+    : { command: "add", pluginId: canonicalId, source: request.source || null };
+
+  await registerRemotePluginSources({
+    parsed,
+    projectRoot: ctx.target,
+    options,
+    registry,
+    lock,
+  });
+  const manifestInspection = await inspectRemotePluginContentManifest({
+    canonicalId,
+    registry,
+    version: request.version,
+    lockedPlugin: request.lockedPlugin || null,
+  });
+  if (manifestInspection) {
+    return {
+      ok: true,
+      pluginId: canonicalId,
+      version: manifestInspection.version,
+      name: manifestInspection.manifest.name,
+      skills: listContentSkillChoices(manifestInspection.manifest.content.skills || [], canonicalId),
+    };
+  }
+  await prepareRemotePluginForSkillInspection({
+    parsed,
+    canonicalId,
+    registry,
+    lock,
+    version: request.version,
+  });
+
+  let plugin = request.lockedPlugin || null;
+  if (!plugin) {
+    const candidates = registry.listCandidates(canonicalId);
+    plugin = candidates.find((candidate) => candidate.version === request.version) || null;
+    if (!plugin) {
+      throw new PluginRuntimeError(`Marketplace Plugin 版本不存在:${canonicalId}@${request.version}`, {
+        code: PLUGIN_RUNTIME_ERROR_CODES.SOURCE_NOT_FOUND,
+        path: canonicalId,
+      });
+    }
+  }
+
+  const pluginPackage = registry.readPackage(plugin);
+  return {
+    ok: true,
+    pluginId: canonicalId,
+    version: plugin.version,
+    name: pluginPackage.manifest.name,
+    skills: listContentSkillChoices(pluginPackage.manifest.content.skills || [], canonicalId),
+  };
+}
+
+/**
+ * 优先用 Provider 的 manifest-only inspection 读取 Skill 清单元数据。
+ *
+ * 这里不需要运行时包内容，也不需要 canonical tree hash；完整安装/更新仍会在生命周期
+ * 中准备固定包并校验摘要。TUI 首屏只展示 manifest 声明，避免为 checkbox 下载 archive。
+ *
+ * @param {{canonicalId:string,registry:object,version?:string|null,lockedPlugin?:object|null}} context 读取上下文
+ * @returns {Promise<{version:string,manifest:import("../plugin/contracts.js").PluginManifest}|null>} manifest inspection 结果
+ */
+async function inspectRemotePluginContentManifest({ canonicalId, registry, version, lockedPlugin }) {
+  const { sourceId } = parseCanonicalPluginId(canonicalId);
+  if (!registry.has(sourceId)) return null;
+  const provider = registry.get(sourceId);
+  if (typeof provider.inspectContentManifest !== "function") return null;
+  return provider.inspectContentManifest(canonicalId, { version, lockedPlugin });
+}
+
+/**
+ * 为 TUI Skill inspection 准备远程包。
+ *
+ * inspection 只需要读取用户当前选择的一个包版本；Provider 支持单版本准备时不走完整依赖闭包，
+ * 避免为了展示 checkbox 下载同一 Plugin 的全部历史版本。
+ *
+ * @param {{parsed:object,canonicalId:string,registry:object,lock:object|null,version?:string|null}} context 准备上下文
+ * @returns {Promise<void>} 准备完成
+ */
+async function prepareRemotePluginForSkillInspection({ parsed, canonicalId, registry, lock, version }) {
+  if (lock) {
+    await prepareRemotePluginCandidates({ parsed, canonicalId, registry, lock });
+    return;
+  }
+  const { sourceId } = parseCanonicalPluginId(canonicalId);
+  const provider = registry.has(sourceId) ? registry.get(sourceId) : null;
+  if (version && typeof provider?.prepareVersion === "function") {
+    await provider.prepareVersion(canonicalId, version);
+    return;
+  }
+  await prepareRemotePluginCandidates({ parsed, canonicalId, registry, lock });
+}
+
 /**
  * 探测 GitHub 来源并返回可持久化 descriptor 与兼容性结果。
  *
@@ -309,10 +446,10 @@ export async function runPluginManagementCommand(parsed, ctx, options, output) {
         baseUrl: parsed.baseUrl || base.baseUrl,
         project: parsed.project || base.project,
         ref: parsed.ref || base.ref || "main",
-        marketplacePath: parsed.marketplacePath || base.marketplacePath || ".flower-marketplace/marketplace.json",
+        marketplacePath: parsed.marketplacePath || base.marketplacePath || ".flower-plugin/marketplace.json",
         oauth: {
           applicationId: parsed.applicationId || base.oauth?.applicationId,
-          scopes: ["read_api", "read_repository"],
+          scopes: GITLAB_OAUTH_REQUEST_SCOPES,
         },
       };
       if (sourceType === "github") {
@@ -400,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;
@@ -447,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;
 
@@ -470,7 +619,16 @@ export async function registerRemotePluginSources({ parsed, projectRoot, options
       sleep: options.sleep,
       now: options.now,
     });
-    manager = new GitLabCredentialManager({ store: credentialBundle.store, oauth, now: options.now });
+    manager = new GitLabCredentialManager({
+      store: credentialBundle.store,
+      oauth,
+      now: options.now,
+      persistent: credentialBundle.persistent,
+      credentialResolver: options.credentialResolver,
+      env: options.env,
+      runGlab: options.runGlab,
+      glabCommand: options.glabCommand,
+    });
   }
   // 依赖闭包可能跨 source，因此登记全部可用来源，而不是只登记入口来源。
   for (const source of sources) {
@@ -482,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);
 }
 
 /**
@@ -508,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 || {}));
     }
@@ -533,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

@@ -17,6 +17,7 @@ import {
   SKILL_GARDEN_PLUGIN_ID,
   SkillGardenBuiltinProvider,
 } from "../builtin-plugins/skill-garden/provider.js";
+import { contentSelectionFromSkillNames } from "../plugin/content-selection.js";
 
 const REMOTE_PLUGIN_ENTRY = new URL("./plugin-remote.js", import.meta.url);
 const PATCH_RUNTIME_ENTRY = new URL("../plugin/install/patch-planner.js", import.meta.url);
@@ -35,6 +36,7 @@ const PLUGIN_CONFLICT_CODES = new Set([
   PLUGIN_RUNTIME_ERROR_CODES.DEPENDENCY_MISSING,
   PLUGIN_RUNTIME_ERROR_CODES.DEPENDENCY_CONFLICT,
   PLUGIN_RUNTIME_ERROR_CODES.DEPENDENCY_CYCLE,
+  PLUGIN_RUNTIME_ERROR_CODES.CONTENT_SELECTION_INVALID,
   PLUGIN_RUNTIME_ERROR_CODES.CONTENT_CONFLICT,
   PLUGIN_RUNTIME_ERROR_CODES.TARGET_DRIFT,
   PLUGIN_RUNTIME_ERROR_CODES.VERIFY_FAILED,
@@ -227,7 +229,7 @@ function parseManagementArgs(argv) {
  * 解析 Plugin 多级命令参数。
  *
  * @param {string[]} argv `plugin` 后的参数
- * @returns {{command:string,pluginId:string|null,source:string|null,version:string|null,platforms:string[],dryRun:boolean,json:boolean,help:boolean}} 解析结果
+ * @returns {{command:string,pluginId:string|null,source:string|null,version:string|null,platforms:string[],contentSelection:object|null,dryRun:boolean,json:boolean,help:boolean}} 解析结果
  */
 export function parsePluginArgs(argv) {
   const authoring = parsePluginAuthoringArgs(argv);
@@ -238,6 +240,7 @@ export function parsePluginArgs(argv) {
   const command = rootHelp ? "list" : (argv[0] || "list");
   const positional = [];
   const platforms = [];
+  const contentSkills = [];
   const widen = [];
   let source = null;
   let version = null;
@@ -247,7 +250,13 @@ export function parsePluginArgs(argv) {
 
   for (let index = 1; index < argv.length; index += 1) {
     const token = argv[index];
-    if (token === "--source" || token === "--version" || token === "--platform" || token === "--widen") {
+    if (
+      token === "--source" ||
+      token === "--version" ||
+      token === "--platform" ||
+      token === "--widen" ||
+      token === "--content-skill"
+    ) {
       const value = argv[index + 1];
       if (!value || value.startsWith("--")) {
         throw new PluginRuntimeError(`${token} 缺少取值`, {
@@ -259,6 +268,7 @@ export function parsePluginArgs(argv) {
       if (token === "--source") source = value;
       else if (token === "--version") version = value;
       else if (token === "--widen") widen.push(value);
+      else if (token === "--content-skill") contentSkills.push(value);
       else platforms.push(value);
       continue;
     }
@@ -341,6 +351,24 @@ export function parsePluginArgs(argv) {
       path: command,
     });
   }
+  const contentSelection = contentSkills.length > 0
+    ? contentSelectionFromSkillNames(contentSkills, {
+      code: PLUGIN_RUNTIME_ERROR_CODES.USAGE_ERROR,
+      path: "--content-skill",
+    })
+    : null;
+  if (contentSelection && !["add", "update"].includes(command)) {
+    throw new PluginRuntimeError("--content-skill 仅支持 plugin add 与单个 plugin update", {
+      code: PLUGIN_RUNTIME_ERROR_CODES.USAGE_ERROR,
+      path: command,
+    });
+  }
+  if (contentSelection && command === "update" && (!positional[0] || widen.length > 0)) {
+    throw new PluginRuntimeError("--content-skill 仅支持单个 plugin update，且不能与 --widen 同时使用", {
+      code: PLUGIN_RUNTIME_ERROR_CODES.USAGE_ERROR,
+      path: "--content-skill",
+    });
+  }
   return {
     command,
     pluginId: positional[0] || null,
@@ -348,6 +376,7 @@ export function parsePluginArgs(argv) {
     version,
     widen: parseWidenPairs(widen),
     platforms: parsePlatforms(platforms),
+    contentSelection,
     dryRun,
     json,
     help,
@@ -365,8 +394,8 @@ function printPluginHelp(output) {
     : "";
   output.log(`用法:
   flower-trellis plugin list [--json]
-  flower-trellis plugin add <plugin> [--source <来源 ID|项目内路径>] [--version <range>] [--platform <id>] [--dry-run] [--json]
-  flower-trellis plugin update [plugin] [--version <range>] [--widen <plugin>=<range>]... [--platform <id>] [--dry-run] [--json]
+  flower-trellis plugin add <plugin> [--source <来源 ID|项目内路径>] [--version <range>] [--platform <id>] [--content-skill <name>]... [--dry-run] [--json]
+  flower-trellis plugin update [plugin] [--version <range>] [--widen <plugin>=<range>]... [--platform <id>] [--content-skill <name>]... [--dry-run] [--json]
   flower-trellis plugin remove <plugin> [--dry-run] [--json]
   flower-trellis plugin verify [plugin] [--json]
   flower-trellis plugin init --id <source/plugin> --name <name> [--version <semver>] [--profile <standard|integration>] [--patches] [--marketplace] [--non-interactive] [--json]
@@ -718,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 = {}) {
@@ -805,6 +834,7 @@ export async function plugin(ctx, options = {}) {
       options,
       registry,
       lock,
+      preserveIds: options.preserveIds || [],
     });
 
     if (parsed.command !== "add" && canonicalId && !canonicalId.includes("/")) {
@@ -860,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;
@@ -875,7 +911,9 @@ 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(
@@ -893,7 +931,9 @@ export async function plugin(ctx, options = {}) {
           : parsed.version ? { version: parsed.version } : {}),
         ...(Object.keys(parsed.widen || {}).length > 0 ? { widen: parsed.widen } : {}),
         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/lib/skill-catalog.js

@@ -444,6 +444,16 @@ function isCommonSkillInstalled(target, name) {
   );
 }
 
+/**
+ * 判断目标是否已经初始化为 Trellis 项目。
+ *
+ * @param {string} target 目标项目根目录
+ * @returns {boolean} 是否存在 `.trellis` 入口
+ */
+function hasTrellisProject(target) {
+  return fs.existsSync(path.join(target, ".trellis"));
+}
+
 /**
  * 读取当前可管理的通用技能元数据。
  *
@@ -502,6 +512,15 @@ function listWorkflowEnhancementSkills(target, variantDir) {
  * @returns {{variant: string, version: string, commonSkills: object[], enhancementSkills: object[]}} 菜单清单
  */
 export function listSkillCatalog(target, variantOverride) {
+  if (!hasTrellisProject(target)) {
+    return {
+      variant: variantOverride || "common",
+      version: "",
+      commonSkills: listCommonSkills(target),
+      enhancementSkills: [],
+    };
+  }
+
   const { variant, version, variantDir } = resolveEnhancementSnapshot(
     target,
     variantOverride,
@@ -625,7 +644,7 @@ export function syncInstalledCommonSkills(target) {
  * @returns {{removed: string[], skipped: string[]}} 已删除与未发现的路径
  */
 export function removeCommonSkills(target, variantOverride, names) {
-  resolveEnhancementSnapshot(target, variantOverride);
+  if (hasTrellisProject(target)) resolveEnhancementSnapshot(target, variantOverride);
   const available = new Set(listCommonSnapshotNames());
   const removed = [];
   const skipped = [];