flower-trellis 0.6.1 → 0.6.3

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") {
@@ -470,7 +607,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) {

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]
@@ -875,6 +904,7 @@ export async function plugin(ctx, options = {}) {
             : "*"
         ),
         platforms: parsed.platforms,
+        ...(parsed.contentSelection ? { contentSelection: parsed.contentSelection } : {}),
         dryRun: parsed.dryRun,
         onPreflight: options.onPreflight,
       };
@@ -893,6 +923,7 @@ 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,
         onPreflight: options.onPreflight,
       };

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 = [];

package/src/lib/telemetry.js

@@ -8,8 +8,8 @@ import { readGitDeveloper } from "./developer.js";
 import { readManifest, readUpdateCheck } from "./manifest.js";
 import { flowerVersion, trellisVersion } from "./versions.js";
 
-/** Flower 遥测接收地址。 */
-export const FLOWER_TELEMETRY_ENDPOINT = "https://ai-api.hub.flower-cli.com/";
+/** Flower 遥测接收地址。主机名与 `/api/flower-trellis` 路由前缀都由服务端契约固定,缺一不可。 */
+export const FLOWER_TELEMETRY_ENDPOINT = "https://ai-api.hub.flower-cli.com/api/flower-trellis/telemetry";
 
 const TELEMETRY_SCHEMA_VERSION = 1;
 /** 遥测请求保留 10 秒公网预算，避免慢速 TLS 建连或服务端响应被过早中止。 */

package/src/lib/trellis-runner.js

@@ -60,6 +60,45 @@ function classifyHeaderLine(line, bannerSet) {
   return "content";
 }
 
+/**
+ * 上游 `trellis update` 的 npm 落后提示行。用宽松匹配容忍上游微调文案,
+ * 捕获组取出它自报的 CLI 版本,复用到 Flower 的替代说明里。
+ */
+const UPSTREAM_UPGRADE_NOTICE = /Your CLI \(([^)]+)\) is behind npm\b/;
+
+/**
+ * 上游紧跟其后的引导动作行。只匹配独立成行的 `Run: trellis upgrade`,
+ * 避免误伤降级分支里 `1. Update your CLI: trellis upgrade` 这类真实错误指引。
+ */
+const UPSTREAM_UPGRADE_ACTION = /^Run:\s*trellis upgrade$/;
+
+/**
+ * 正文开始后继续按行过滤的行数上限。
+ *
+ * 上游版本提示固定打印在 `trellis update` 输出最前面,给一个有限窗口即可覆盖;
+ * 设上限是为了不让不完整行长期滞留在缓冲区里,影响后续交互输出的实时性。
+ */
+const UPSTREAM_NOTICE_LINE_BUDGET = 40;
+
+/**
+ * 改写上游 trellis 的 npm 升级提示。
+ *
+ * Flower 在 package.json 里固定 `@mindfoldhq/trellis` 版本,并由 postinstall 同步全局 CLI,
+ * 所以上游「CLI 落后于 npm,请运行 trellis upgrade」是错误引导:照做会让全局 CLI 脱离
+ * Flower 的版本控制,下次安装又被同步回去。这里替换成 Flower 自己的说明而不是静默丢弃,
+ * 让用户仍然知道版本检查发生过、以及为什么不需要照做。
+ *
+ * @param {string} line 未去色的原始输出行
+ * @returns {string|null|undefined} 替换文案;null 表示丢弃该行;undefined 表示不匹配
+ */
+export function rewriteUpstreamUpgradeNotice(line) {
+  const t = stripAnsi(line).trim();
+  const notice = UPSTREAM_UPGRADE_NOTICE.exec(t);
+  if (notice) return `  · Trellis 版本由 Flower 固定(${notice[1]}),已忽略上游 npm 升级提示`;
+  if (UPSTREAM_UPGRADE_ACTION.test(t)) return null;
+  return undefined;
+}
+
 /**
  * 用当前 node 执行 trellis bin(普通 spawn),透传子命令与参数。
  *
@@ -83,6 +122,11 @@ export function runTrellis(args, cwd, opts = {}) {
       const banner = trellisBannerLines();
       const rl = createInterface({ input: child.stdout });
       rl.on("line", (line) => {
+        const notice = rewriteUpstreamUpgradeNotice(line);
+        if (notice !== undefined) {
+          if (notice !== null) process.stdout.write(notice + "\n");
+          return;
+        }
         const kind = classifyHeaderLine(line, banner);
         // 普通(非 pty)场景一直按行过滤即可:trellis 此时是 -y 非交互,无 inquirer
         if (kind === "skip") return;
@@ -99,10 +143,15 @@ export function runTrellis(args, cwd, opts = {}) {
 
 /**
  * 在伪终端(node-pty)里运行 trellis,**保留其全部交互**(模板 / monorepo / 冲突菜单),
- * 同时过滤掉它开头重复打印的启动 banner / 副标题 / Developer / Mode。
+ * 同时过滤掉它开头重复打印的启动 banner / 副标题 / Developer / Mode,
+ * 以及它自带的、与 Flower 版本固定策略冲突的 npm 升级提示。
+ *
+ * 过滤分三个阶段:
+ *  - "header":逐行识别 banner 类行并丢弃(proxy 保留),遇到正文行转入 "notice";
+ *  - "notice":只改写上游 npm 升级提示,其余原样输出,超出行数预算后转入 "raw";
+ *  - "raw":完全透传。
  *
- * 过滤只作用于「头部阶段」:逐行识别 banner 类行并丢弃(proxy 保留),
- * 一旦遇到正文行或 inquirer 渲染(隐藏光标序列 ESC[?25l)立即停止过滤、转为完全透传,
+ * 任一阶段遇到 inquirer 渲染(隐藏光标序列 ESC[?25l)都立即转入 "raw",
  * 以免破坏交互菜单的光标控制。
  *
  * @param {string[]} args
@@ -133,17 +182,18 @@ export function runTrellisPty(args, cwd, opts = {}) {
     }
 
     const bannerSet = trellisBannerLines();
-    let filtering = !!opts.stripBanner;
+    let phase = opts.stripBanner ? "header" : "raw";
+    let noticeBudget = UPSTREAM_NOTICE_LINE_BUDGET;
     let buf = "";
 
     const dataSubscription = child.onData((data) => {
-      if (!filtering) {
+      if (phase === "raw") {
         stdout.write(data);
         return;
       }
       // inquirer 开始渲染(隐藏光标)→ 立即停止过滤,整体透传,保住交互菜单
       if (data.includes("\x1b[?25l")) {
-        filtering = false;
+        phase = "raw";
         stdout.write(buf + data);
         buf = "";
         return;
@@ -152,16 +202,32 @@ export function runTrellisPty(args, cwd, opts = {}) {
       const parts = buf.split(/\r?\n/);
       buf = parts.pop(); // 末尾不完整行留待下次
       for (const line of parts) {
-        const kind = classifyHeaderLine(line, bannerSet);
-        if (kind === "skip") continue;
-        if (kind === "keep") {
+        if (phase === "raw") {
+          stdout.write(line + "\r\n");
+          continue;
+        }
+        if (phase === "notice" && noticeBudget-- <= 0) {
+          phase = "raw";
           stdout.write(line + "\r\n");
           continue;
         }
-        filtering = false; // 正文开始
+        const notice = rewriteUpstreamUpgradeNotice(line);
+        if (notice !== undefined) {
+          if (notice !== null) stdout.write(notice + "\r\n");
+          continue;
+        }
+        if (phase === "header") {
+          const kind = classifyHeaderLine(line, bannerSet);
+          if (kind === "skip") continue;
+          if (kind === "keep") {
+            stdout.write(line + "\r\n");
+            continue;
+          }
+          phase = "notice"; // 正文开始:banner 过滤结束,但仍在有限窗口内改写上游版本提示
+        }
         stdout.write(line + "\r\n");
       }
-      if (!filtering && buf) {
+      if (phase === "raw" && buf) {
         stdout.write(buf);
         buf = "";
       }
@@ -185,6 +251,11 @@ export function runTrellisPty(args, cwd, opts = {}) {
     stdout.on("resize", onResize);
 
     child.onExit(({ exitCode, signal }) => {
+      // 过滤阶段可能扣着一行不完整输出(末尾无换行),退出前补发,避免最后一行被吞掉。
+      if (buf) {
+        stdout.write(buf);
+        buf = "";
+      }
       // 先停止接收子进程输出，再恢复宿主终端；否则迟到的 9001h 会重新污染父终端。
       dataSubscription.dispose();
       stdin.off("data", onStdin);