flower-trellis 0.6.8 → 0.6.9

package/src/assets/flower_session_start.py

@@ -8,10 +8,9 @@ import argparse
 import json
 import os
 import re
+import subprocess
 import sys
-from contextlib import redirect_stdout
 from importlib.util import module_from_spec, spec_from_file_location
-from io import StringIO
 from pathlib import Path
 
 
@@ -86,6 +85,40 @@ def _load_hook(root: Path, hook: str):
     return module
 
 
+def _run_native_hook(root: Path, hook: str, hook_input: dict) -> dict | None:
+    """在独立解释器中执行原生 hook，保留真实标准流边界。
+
+    @param root: 当前部署项目根目录。
+    @param hook: 已验证的原生平台 hook 相对路径。
+    @param hook_input: 宿主传入并已规范化 cwd 的事件 JSON。
+    @return: 原生标准 SessionStart 输出；原生 hook 跳过时返回 None。
+    """
+    environment = os.environ.copy()
+    environment["PYTHONIOENCODING"] = "utf-8"
+    result = subprocess.run(
+        [sys.executable, "-X", "utf8", str(root / hook)],
+        cwd=root,
+        env=environment,
+        input=json.dumps(hook_input, ensure_ascii=False).encode("utf-8"),
+        capture_output=True,
+        check=False,
+    )
+    stderr = result.stderr.decode("utf-8", errors="replace")
+    if stderr:
+        # 原生诊断属于真实 Hook 证据，不能因包装器捕获输出而被吞掉。
+        sys.stderr.write(stderr)
+        sys.stderr.flush()
+    if result.returncode != 0:
+        raise ValueError(f"原生 hook 退出码 {result.returncode}")
+    stdout = result.stdout.decode("utf-8-sig")
+    if not stdout.strip():
+        return None
+    output = json.loads(stdout)
+    if not isinstance(output, dict):
+        raise ValueError("原生 hook 输出必须为 JSON 对象")
+    return output
+
+
 def render_part(root: Path, hook: str, part: str, hook_input: dict) -> dict | None:
     """生成指定分段，只有 state 执行原生主入口的副作用。
 
@@ -97,21 +130,10 @@ def render_part(root: Path, hook: str, part: str, hook_input: dict) -> dict | No
     """
     if hook not in HOOKS or part not in PARTS:
         raise ValueError("不支持的 SessionStart hook 或分段")
-    module = _load_hook(root, hook)
-    if module.should_skip_injection():
-        return None
     if part == "state":
-        output = StringIO()
-        original_stdin = sys.stdin
-        try:
-            sys.stdin = StringIO(json.dumps(hook_input, ensure_ascii=False))
-            with redirect_stdout(output):
-                module.main()
-        finally:
-            sys.stdin = original_stdin
-        if not output.getvalue().strip():
+        result = _run_native_hook(root, hook, hook_input)
+        if result is None:
             return None
-        result = json.loads(output.getvalue())
         context = result["hookSpecificOutput"]["additionalContext"]
         if len(WORKFLOW_BLOCK.findall(context)) != 1:
             raise ValueError("原生启动输出必须包含且仅包含一个 trellis-workflow 块")
@@ -133,6 +155,9 @@ def render_part(root: Path, hook: str, part: str, hook_input: dict) -> dict | No
                 result["systemMessage"] = "\n".join(filter(None, [result.get("systemMessage"), message]))
                 print(message, file=sys.stderr)
     else:
+        module = _load_hook(root, hook)
+        if module.should_skip_injection():
+            return None
         builder = module._build_workflow_toc if hook == HOOKS[0] else module._build_workflow_overview
         context = split_workflow(builder(root / ".trellis/workflow.md"))[part]
         result = {"hookSpecificOutput": {"hookEventName": "SessionStart"}}

package/src/assets/flower_telemetry_hook.py

@@ -5,6 +5,7 @@
 from __future__ import annotations
 
 import json
+import ntpath
 import os
 import shutil
 import subprocess
@@ -57,7 +58,7 @@ def _can_skip(platform: str) -> bool:
             return hint.get("delivered") is True
         retry = meta.get("nextRetryAt")
         return bool(retry and datetime.fromisoformat(retry.replace("Z", "+00:00")).timestamp() > time.time())
-    except (OSError, ValueError, TypeError, AttributeError):
+    except (OSError, ValueError, TypeError, AttributeError, RuntimeError):
         return False
 
 
@@ -86,10 +87,24 @@ def main() -> None:
         command = shutil.which("flower-trellis")
         if not command:
             return
+        argv = [command, "telemetry", "record-activity", platform, "--target", target]
+        run_options = {}
+        if os.name == "nt" and os.path.splitext(command)[1].lower() in {".cmd", ".bat"}:
+            processor = os.environ.get("COMSPEC")
+            if not processor and os.environ.get("SystemRoot"):
+                processor = os.path.join(os.environ["SystemRoot"], "System32", "cmd.exe")
+            if not processor or not ntpath.isabs(processor):
+                return
+            # CMD 的环境占位符只展开一轮；引号和关闭延迟展开共同保留特殊路径字符。
+            environment = os.environ.copy()
+            environment["FLOWER_ACTIVITY_HOOK_CLI"] = command
+            environment["FLOWER_ACTIVITY_HOOK_TARGET"] = target
+            argv = f'"{processor}" /d /v:off /s /c ""%FLOWER_ACTIVITY_HOOK_CLI%" telemetry record-activity {platform} --target "%FLOWER_ACTIVITY_HOOK_TARGET%""'
+            run_options = {"executable": processor, "env": environment}
         # 只转交固定事件类型、平台和本地定位参数；Node 独占身份创建及队列写入。
-        subprocess.run([command, "telemetry", "record-activity", platform, "--target", target],
+        subprocess.run(argv,
                        cwd=target, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
-                       stderr=subprocess.DEVNULL, timeout=3, check=False)
+                       stderr=subprocess.DEVNULL, timeout=3, check=False, **run_options)
     except (OSError, ValueError, TypeError, subprocess.SubprocessError):
         return
 

package/src/cli.js

@@ -7,7 +7,7 @@ import { readManifest } from "./lib/manifest.js";
 import { ProjectStore } from "./plugin/state/project-store.js";
 import { runTrellis } from "./lib/trellis-runner.js";
 import { parseCliArgs } from "./lib/cli-args.js";
-import { installWindowsTerminalInputRecovery } from "./lib/terminal-state.js";
+import { installWindowsTerminalInputRecovery, scheduleWindowsTerminalExit } from "./lib/terminal-state.js";
 
 /**
  * flower-trellis CLI 主入口。
@@ -204,6 +204,12 @@ async function main() {
       const code = await runTrellis([cmd, ...ctx.passthrough], ctx.target);
       process.exit(code);
     }
+    // 非交互完成不会经过退出菜单；必须等编排、计时和遥测收尾后再释放 Windows CLI。
+    if (process.platform === "win32" && (cmd === "init" || cmd === "update")) {
+      // Windows 管道写入是异步的，显式退出前等两个输出流排空，避免截断完成行和计时。
+      await Promise.all([process.stdout, process.stderr].map((stream) => new Promise((resolve) => stream.write("", resolve))));
+      scheduleWindowsTerminalExit({ exitCode: process.exitCode ?? 0 });
+    }
   } catch (err) {
     console.error(`❌ ${err.message}`);
     if (process.env.DEBUG || process.env.FLOWER_DEBUG) console.error(err.stack);

package/src/commands/self-check.js

@@ -1,3 +1,4 @@
+import { timeOperation } from "../lib/operation-timing.js";
 import { buildSelfCheck } from "../lib/self-check.js";
 import { reportTelemetry } from "../lib/telemetry.js";
 import { hasHelpFlag } from "../lib/cli-args.js";
@@ -39,11 +40,11 @@ export async function selfCheck(ctx) {
   if (ctx.updateCheck === false) {
     process.env.FLOWER_NO_UPDATE_CHECK = "1";
   }
-  const result = await buildSelfCheck(ctx.target, {
+  const result = await timeOperation("self-check", "预检", () => buildSelfCheck(ctx.target, {
     forceRemote,
     ignorePromptSuppression: manual,
     recordPrompt: !manual,
     onRemoteCheck: () => reportTelemetry(ctx.target, "version_check"),
-  });
+  }));
   console.log(JSON.stringify(result, null, 2));
 }

package/src/commands/self-update.js

@@ -1,3 +1,4 @@
+import { timeOperation } from "../lib/operation-timing.js";
 import { observeTelemetryOperation, beginTelemetryOperation, completeTelemetryOperation } from "../lib/telemetry-operation.js";
 import { spawnSync } from "node:child_process";
 import {
@@ -129,7 +130,8 @@ function printFlowerUpdateResult(fields) {
  * @returns {Promise<void>}
  */
 export async function selfUpdate(ctx) {
-  return observeTelemetryOperation(ctx, "self_update", executeSelfUpdate);
+  if (hasHelpFlag(ctx.passthrough)) return executeSelfUpdate(ctx);
+  return timeOperation("self-update", "流程总计（包含子阶段及交互等待）", () => observeTelemetryOperation(ctx, "self_update", executeSelfUpdate));
 }
 
 /** 执行已建立外部操作上下文的命令。
@@ -152,11 +154,11 @@ async function executeSelfUpdate(ctx) {
     "--no-update-check",
     ...projectUpdateForwardArgs(forwarded),
   ];
-  const check = await buildSelfCheck(ctx.target, {
+  const check = await timeOperation("self-update", "预检", () => buildSelfCheck(ctx.target, {
     writeCache: !dryRun,
     forceRemote: !projectOnly,
     ignorePromptSuppression: true,
-  });
+  }));
   const shouldInstallFlower = !projectOnly && check.status === "update_available" && check.recommendation;
   const effectiveSafety = check.safety || safetyState(
     ctx.target,
@@ -207,7 +209,8 @@ async function executeSelfUpdate(ctx) {
 
   beginTelemetryOperation(ctx);
   if (shouldInstallFlower) {
-    const res = installFlowerVersion(check.recommendation.version, { cwd: ctx.target });
+    console.log("  · 正在安装 Flower 新版本（含依赖与全局同步）");
+    const res = timeOperation("self-update", "全局安装（含依赖与postinstall）", () => installFlowerVersion(check.recommendation.version, { cwd: ctx.target }));
     if (res.status !== 0) {
       const reason = res.error ? res.error.message : `退出码 ${res.status ?? 1}`;
       throw Object.assign(new Error(`全局 flower-trellis 升级失败(${reason})`), { code: res.status === 130 ? "FLOWER_OPERATION_CANCELLED" : "FLOWER_UPSTREAM_FAILED" });
@@ -216,13 +219,14 @@ async function executeSelfUpdate(ctx) {
     console.log("  · 跳过全局 flower-trellis 升级");
   }
 
-  runCommand(
+  console.log("  · 正在更新目标项目");
+  timeOperation("self-update", "项目更新（含子阶段及交互等待）", () => runCommand(
     "flower-trellis",
     projectArgs,
     ctx.target,
     "目标项目重叠加失败,请手动运行:" + projectUpdateCommand(ctx.target, forwarded),
     { ...process.env, FLOWER_TELEMETRY_PARENT_OPERATION: ctx.telemetryOperation?.id || "self_update" },
-  );
+  ));
 
   completeTelemetryOperation(ctx, "self_update");
   const dirty = gitDirtySummary(ctx.target);

package/src/commands/update.js

@@ -1,3 +1,4 @@
+import { beginOperationTiming, timeOperation } from "../lib/operation-timing.js";
 import { observeTelemetryOperation, beginTelemetryOperation, completeTelemetryOperation } from "../lib/telemetry-operation.js";
 import { runTrellis, runTrellisPty } from "../lib/trellis-runner.js";
 import { hasHelpFlag, trellisUpdatePassthroughArgs } from "../lib/cli-args.js";
@@ -172,20 +173,20 @@ export async function replayPlugins(ctx, target, dryRun, compensationSnapshot =
 }
 
 async function previewCrossVersionUpdate(ctx, currentVersion, targetVersion) {
-  const sandbox = createUpdateSandbox(ctx.target);
+  const sandbox = timeOperation("update", "创建沙箱", () => createUpdateSandbox(ctx.target));
   console.log(
     `· 跨版本 dry-run:在项目外沙箱预演 Trellis + Plugin (${currentVersion} → ${targetVersion})`,
   );
   try {
-    const code = await runTrellis(
+    const code = await timeOperation("update", "沙箱上游更新", () => runTrellis(
       ["update", ...sandboxTrellisUpdateArgs(ctx.passthrough)],
       sandbox.root,
-      { stripBanner: true },
-    );
+      { stripBanner: true, managedUpdate: true },
+    ));
     if (code !== 0) throw new Error(`沙箱 trellis update 失败(退出码 ${code})`);
-    await replayPlugins(ctx, sandbox.root, true);
+    await timeOperation("update", "沙箱插件预演", () => replayPlugins(ctx, sandbox.root, true));
   } finally {
-    disposeUpdateSandbox(sandbox);
+    timeOperation("update", "清理沙箱", () => disposeUpdateSandbox(sandbox));
   }
 }
 
@@ -240,7 +241,18 @@ function printBackupRetentionResult(result, output = console) {
  * @returns {Promise<void>} 升级、强化叠加与备份保留处理完成后返回
  */
 export async function update(ctx) {
-  return observeTelemetryOperation(ctx, "update", executeUpdate);
+  if (ctx.finishUpdateTiming || hasHelpFlag(ctx.passthrough)) {
+    return observeTelemetryOperation(ctx, "update", executeUpdate);
+  }
+  const finish = beginOperationTiming("update", "总计（包含子阶段）");
+  try {
+    return await observeTelemetryOperation({ ...ctx, finishUpdateTiming: finish }, "update", executeUpdate);
+  } catch (error) {
+    finish(false);
+    throw error;
+  } finally {
+    finish();
+  }
 }
 
 /** 执行已建立外部操作上下文的命令。
@@ -262,6 +274,7 @@ async function executeUpdate(ctx) {
       trellisControlExtendSnapshot: extendSnapshot,
     }));
     completeTelemetryOperation(ctx, "update");
+    ctx.finishUpdateTiming?.();
     await showCommandCompletion("update", ctx.target, { passthrough: ctx.passthrough, outcome: "success", output: ctx.trellisControlQuiet ? SILENT_OUTPUT : console });
     return result;
   }
@@ -292,34 +305,34 @@ async function executeUpdate(ctx) {
   await checkForUpdate(ctx, "update");
 
   output.log("\n同步全局 Trellis:");
-  syncGlobalTrellis({ logger: output, stdio: quiet ? "ignore" : "inherit" });
+  timeOperation("update", "同步全局Trellis", () => syncGlobalTrellis({ logger: output, stdio: quiet ? "ignore" : "inherit" }));
 
   try {
     compensationSnapshot = !dryRun && !ctx.enhanceOnly
-      ? createUpdateSnapshot(target)
+      ? timeOperation("update", "创建恢复快照", () => createUpdateSnapshot(target))
       : null;
     if (useUpdateSandbox) {
       await previewCrossVersionUpdate(ctx, currentTrellisVersion, targetTrellisVersion);
       updateSucceeded = true;
     } else if (!ctx.enhanceOnly) {
-      const code = await runTrellisPty(
+      const code = await timeOperation("update", "上游更新（含交互等待）", () => runTrellisPty(
         ["update", ...trellisUpdatePassthroughArgs(ctx.passthrough)],
         target,
-        { stripBanner: true, ...(quiet ? { stdout: SILENT_OUTPUT } : {}) },
-      );
+        { stripBanner: true, managedUpdate: true, ...(quiet ? { stdout: SILENT_OUTPUT } : {}) },
+      ));
       if (code !== 0) {
         throw Object.assign(new Error(`trellis update 失败(退出码 ${code}),已中止,未重新叠加`), { code: code === 130 ? "FLOWER_OPERATION_CANCELLED" : "FLOWER_UPSTREAM_FAILED" });
       }
-      await replayPlugins(ctx, target, dryRun, compensationSnapshot);
+      await timeOperation("update", "插件重放", () => replayPlugins(ctx, target, dryRun, compensationSnapshot));
       updateSucceeded = true;
     } else {
       output.log("· --enhance-only:跳过 trellis update,仅重新叠加强化包");
-      await replayPlugins(ctx, target, dryRun);
+      await timeOperation("update", "插件重放", () => replayPlugins(ctx, target, dryRun));
       updateSucceeded = true;
     }
   } catch (error) {
     if (compensationSnapshot) {
-      const recovery = restoreUpdateSnapshot(compensationSnapshot);
+      const recovery = timeOperation("update", "失败恢复", () => restoreUpdateSnapshot(compensationSnapshot));
       if (!recovery.ok) {
         output.error(`  ✗ Update 补偿恢复不完整;快照保留:${recovery.manifestPath}`);
         for (const failure of recovery.failedPaths) {
@@ -336,22 +349,22 @@ async function executeUpdate(ctx) {
     throw error;
   } finally {
     if (updateSucceeded && !dryRun && !ctx.enhanceOnly) {
-      const restored = restoreConfigPreserveSnapshot(target, configSnapshot);
+      const restored = timeOperation("update", "恢复本地配置", () => restoreConfigPreserveSnapshot(target, configSnapshot));
       if (restored.restored) {
         output.log(`  ✓ config.yaml 已保留本地配置: ${restored.keys.join(", ")}`);
       }
     }
     if (compensationSnapshot && (updateSucceeded || compensationRecovered)) {
-      disposeUpdateSnapshot(compensationSnapshot);
+      timeOperation("update", "清理快照", () => disposeUpdateSnapshot(compensationSnapshot));
     }
   }
 
   if (shouldManageBackups) {
-    const backupResult = pruneUpdateBackups(target, {
+    const backupResult = timeOperation("update", "清理旧备份", () => pruneUpdateBackups(target, {
       retention: backupRetention,
       beforeSnapshot: backupSnapshot,
       dryRun,
-    });
+    }));
     printBackupRetentionResult(backupResult, output);
   } else if (!ctx.enhanceOnly && backupRetention === 0) {
     output.log("  · --backup-retention 0:保留全部升级备份");
@@ -361,6 +374,7 @@ async function executeUpdate(ctx) {
   const telemetryPromise = dryRun
     ? null
     : reportTelemetry(target, "update_completed", { force: true });
+  if (!ctx.telemetryDeferCompletion) ctx.finishUpdateTiming?.();
   if (!ctx.telemetryDeferCompletion) await showCommandCompletion("update", target, {
     passthrough: ctx.passthrough,
     outcome: dryRun ? "preview" : "success",

package/src/lib/global-trellis-sync.js

@@ -1,3 +1,4 @@
+import { timeOperation } from "./operation-timing.js";
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
@@ -74,12 +75,13 @@ export function npmGlobalPrefix() {
  * 计算 npm 全局 prefix 下的 trellis 可执行文件路径。
  *
  * @param {string|null} prefix npm 全局 prefix
+ * @param {string} [platform] 当前平台
  * @returns {string|null} 可执行文件路径,不可推导或文件不存在时返回 null
  */
-export function trellisBinInPrefix(prefix) {
+export function trellisBinInPrefix(prefix, platform = process.platform) {
   if (!prefix) return null;
   const candidates =
-    process.platform === "win32"
+    platform === "win32"
       ? ["trellis.cmd", "trellis.ps1", "trellis"].map((name) => path.join(prefix, name))
       : [path.join(prefix, "bin", "trellis")];
   return candidates.find((candidate) => fs.existsSync(candidate)) || null;
@@ -103,6 +105,48 @@ export function globalTrellisVersion(cwd = os.tmpdir(), command = "trellis") {
   return extractLastVersion(`${res.stdout || ""}\n${res.stderr || ""}`);
 }
 
+/**
+ * 从可验证的 npm 安装及启动器读取全局版本，无法证明归属时返回 null。
+ * @param {string|null} prefix npm 全局 prefix
+ * @param {string|null} command prefix 内实际启动器
+ * @param {string} [platform] 当前平台
+ * @returns {string|null} 实际安装版本或兼容探测信号
+ */
+export function installedGlobalTrellisVersion(prefix, command, platform = process.platform) {
+  if (!prefix || !command) return null;
+  try {
+    const root = path.join(prefix, ...(platform === "win32" ? [] : ["lib"]), "node_modules", TRELLIS_PACKAGE);
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+    const bin = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.trellis;
+    if (pkg.name !== TRELLIS_PACKAGE || !VERSION_RE.test(pkg.version) || typeof bin !== "string") return null;
+    const target = path.resolve(root, bin);
+    const relative = path.relative(root, target);
+    if (!relative || relative.startsWith("..") || path.isAbsolute(relative) || !fs.statSync(target).isFile()) return null;
+    const realTarget = fs.realpathSync(target);
+    const realRelative = path.relative(fs.realpathSync(root), realTarget);
+    if (!realRelative || realRelative.startsWith("..") || path.isAbsolute(realRelative)) return null;
+    if (platform !== "win32") {
+      if (fs.realpathSync(command) !== realTarget) return null;
+    } else {
+      if (path.resolve(command) !== path.resolve(prefix, "trellis.cmd")) return null;
+      // 只接受 npm cmd-shim 的标准 Node 启动器全文；自定义包装可能另行调用其它版本。
+      const binRelative = path.relative(prefix, target).split(path.sep).join("\\");
+      const expected = [
+        "@ECHO off", "GOTO start", ":find_dp0", "SET dp0=%~dp0", "EXIT /b", ":start",
+        "SETLOCAL", "CALL :find_dp0", "", 'IF EXIST "%dp0%\\node.exe" (',
+        '  SET "_prog=%dp0%\\node.exe"', ') ELSE (', '  SET "_prog=node"',
+        '  SET PATHEXT=%PATHEXT:;.JS;=;%', ')', '',
+        `endLocal & goto #_undefined_# 2>NUL || title %COMSPEC% & "%_prog%"  "%dp0%\\${binRelative}" %*`,
+        "",
+      ].join("\n");
+      if (fs.readFileSync(command, "utf8").replaceAll("\r\n", "\n") !== expected) return null;
+    }
+    return pkg.version;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * 同步本机全局 Trellis 到 flower-trellis 捆绑版本。
  *
@@ -110,6 +154,10 @@ export function globalTrellisVersion(cwd = os.tmpdir(), command = "trellis") {
  * @param {{log:(message:string)=>void}} [opts.logger] 输出对象,默认使用 console
  * @param {string} [opts.cwd] 执行目录,默认当前目录
  * @param {"inherit"|"ignore"} [opts.stdio] npm 安装子进程输出模式
+ * @param {string} [opts.prefix] 指定 npm prefix，用于隔离测试
+ * @param {string} [opts.platform] 平台测试替身
+ * @param {Function} [opts.spawn] npm 安装测试替身
+ * @param {Function} [opts.probeVersion] 兼容版本探测测试替身
  * @returns {{targetVersion:string,currentVersion:string|null,installed:boolean,skipped:boolean,command:string}} 同步结果
  */
 export function syncGlobalTrellis(opts = {}) {
@@ -129,9 +177,13 @@ export function syncGlobalTrellis(opts = {}) {
     };
   }
 
-  const prefix = npmGlobalPrefix();
-  const prefixBin = trellisBinInPrefix(prefix);
-  const currentVersion = prefixBin ? globalTrellisVersion(os.tmpdir(), prefixBin) : null;
+  const platform = opts.platform || process.platform;
+  const prefix = timeOperation("全局Trellis", "定位安装", () => opts.prefix ?? npmGlobalPrefix());
+  const prefixBin = trellisBinInPrefix(prefix, platform);
+  const currentVersion = timeOperation("全局Trellis", "读取版本", () => (
+    installedGlobalTrellisVersion(prefix, prefixBin, platform) ||
+    (prefixBin ? (opts.probeVersion || globalTrellisVersion)(os.tmpdir(), prefixBin) : null)
+  ));
   if (currentVersion === targetVersion) {
     logger.log(`  ✓ 全局 Trellis 已是 ${targetVersion}`);
     return {
@@ -149,11 +201,11 @@ export function syncGlobalTrellis(opts = {}) {
     logger.log(`  · 安装全局 Trellis:${targetVersion}`);
   }
 
-  const res = spawnSync("npm", ["install", "-g", `${TRELLIS_PACKAGE}@${targetVersion}`], {
+  const res = timeOperation("全局Trellis", "安装", () => (opts.spawn || spawnSync)("npm", ["install", "-g", `${TRELLIS_PACKAGE}@${targetVersion}`], {
     cwd,
     stdio: opts.stdio || "inherit",
-    shell: process.platform === "win32",
-  });
+    shell: platform === "win32",
+  }));
 
   if (res.status !== 0) {
     const reason = res.error ? res.error.message : `退出码 ${res.status ?? 1}`;

package/src/lib/operation-timing.js

@@ -0,0 +1,50 @@
+import { performance } from "node:perf_hooks";
+
+/**
+ * 开始一个本地诊断阶段；父阶段包含子阶段，不能相加作为总耗时。
+ * @param {string} scope 固定操作名，不得传入用户路径或参数
+ * @param {string} stage 固定阶段名
+ * @param {{env?:object,output?:{write:Function},now?:Function}} [options] 运行环境与测试替身
+ * @returns {(success?:boolean)=>void} 幂等结束函数
+ */
+export function beginOperationTiming(scope, stage, options = {}) {
+  if ((options.env || process.env).FLOWER_TIMING !== "1") return () => {};
+  const output = options.output || process.stderr;
+  const now = options.now || (() => performance.now());
+  const started = now();
+  let finished = false;
+  const write = (message) => {
+    try { output.write(message); } catch { /* 诊断流失效不能影响升级结果。 */ }
+  };
+  write(`  · [耗时 ${scope}/${stage}] 开始\n`);
+  return (success = true) => {
+    if (finished) return;
+    finished = true;
+    write(`  · [耗时 ${scope}/${stage}] ${success ? "完成" : "失败"} ${Math.max(0, Math.round(now() - started))} ms\n`);
+  };
+}
+
+/**
+ * 计时同步或异步操作，保留返回值、退出码和原始异常。
+ * @template T
+ * @param {string} scope 固定操作名
+ * @param {string} stage 固定阶段名
+ * @param {()=>T} operation 原操作
+ * @param {object} [options] 计时依赖
+ * @returns {T} 原操作的返回值
+ */
+export function timeOperation(scope, stage, operation, options = {}) {
+  const finish = beginOperationTiming(scope, stage, options);
+  const complete = (value) => {
+    const code = typeof value === "number" ? value : value?.status;
+    finish(value !== null && value?.ok !== false && !value?.error && !value?.signal && (typeof code !== "number" || code === 0));
+    return value;
+  };
+  const fail = (error) => { finish(false); throw error; };
+  try {
+    const result = operation();
+    return result && typeof result.then === "function" ? result.then(complete, fail) : complete(result);
+  } catch (error) {
+    return fail(error);
+  }
+}

package/src/lib/self-check.js

@@ -4,10 +4,11 @@ import path from "node:path";
 import { readManifest, readUpdateCheck, writeUpdateCheck } from "./manifest.js";
 import {
   buildReleaseNotesSummary,
-  fetchPackageUpdateMetadata,
+  createUpdateMetadataReader,
   getUpdateRecommendation,
   isPrerelease,
 } from "./update-check.js";
+import { isRemoteCacheFresh, cachedReleaseNotes } from "./update-check-cache.js";
 import { isRunningViaNpx } from "./runtime-env.js";
 import { flowerVersion, trellisVersion } from "./versions.js";
 import { ProjectStore } from "../plugin/state/project-store.js";
@@ -37,48 +38,6 @@ function readProjectTrellisVersion(target) {
   }
 }
 
-/** 判断远程探测缓存是否仍在 interval 内。 */
-function isRemoteCacheFresh(updateCheck, now = new Date()) {
-  if (updateCheck.lastStatus === "offline" || updateCheck.lastErrorCode) return false;
-  if (!updateCheck.lastRemote) return false;
-  if (!updateCheck.lastCheckedAt) return false;
-  const checkedAt = new Date(updateCheck.lastCheckedAt).getTime();
-  if (!Number.isFinite(checkedAt)) return false;
-  return now.getTime() - checkedAt < updateCheck.intervalHours * 60 * 60 * 1000;
-}
-
-/**
- * 判断缓存的 release notes 是否匹配本次检查范围。
- *
- * @param {object} updateCheck 归一化 updateCheck 配置
- * @param {{from:string|null,to:string|null,channel:string,reason:string}|null} range 本次期望范围
- * @returns {object|null} 可复用的缓存摘要
- */
-function cachedReleaseNotes(updateCheck, range) {
-  const cached = updateCheck.lastReleaseNotes;
-  if (!cached || !range || cached.unavailable) return null;
-  const cachedRange = cached.range || {};
-  if (
-    cachedRange.from !== range.from ||
-    cachedRange.to !== range.to ||
-    cachedRange.channel !== range.channel
-  ) {
-    return null;
-  }
-  if (!Array.isArray(cached.versions) || !cached.versions.length) return null;
-  // 同一版本范围的内容相同;reason 只是触发路径,不能让项目追平场景丢失摘要。
-  return {
-    ...cached,
-    range: {
-      ...cachedRange,
-      from: range.from,
-      to: range.to,
-      channel: range.channel,
-      reason: range.reason,
-    },
-  };
-}
-
 /**
  * 构造新版升级 release notes 范围。
  *
@@ -544,7 +503,7 @@ export function safetyState(target, status, command) {
  * 构建启动自更新检查结果。
  *
  * @param {string} target 目标项目根
- * @param {{writeCache?: boolean, forceRemote?: boolean, fetchMetadata?: () => Promise<object|null>,onRemoteCheck?:()=>Promise<unknown>,recordPrompt?:boolean,ignorePromptSuppression?:boolean}} options 检查选项
+ * @param {{writeCache?:boolean,forceRemote?:boolean,fetchMetadata?:Function,fetchTags?:Function,fetchImpl?:Function,timeoutMs?:number,onRemoteCheck?:()=>Promise<unknown>,recordPrompt?:boolean,ignorePromptSuppression?:boolean}} [options] 检查选项
  * @returns {Promise<object>} 结构化检查结果
  */
 export async function buildSelfCheck(target, options = {}) {
@@ -552,9 +511,8 @@ export async function buildSelfCheck(target, options = {}) {
   const forceRemote = options.forceRemote === true;
   const recordPrompt = options.recordPrompt === true;
   const ignorePromptSuppression = options.ignorePromptSuppression === true;
-  const fetchMetadata = typeof options.fetchMetadata === "function"
-    ? options.fetchMetadata
-    : fetchPackageUpdateMetadata;
+  const reader = createUpdateMetadataReader(options);
+  const fetchMetadata = reader.readMetadata;
   const onRemoteCheck = typeof options.onRemoteCheck === "function"
     ? options.onRemoteCheck
     : null;
@@ -698,11 +656,11 @@ export async function buildSelfCheck(target, options = {}) {
     };
   }
 
-  const [metadata] = await Promise.all([
-    safeFetchPackageUpdateMetadata(fetchMetadata),
+  const [remoteTags] = await Promise.all([
+    reader.readTags(),
     onRemoteCheck ? Promise.resolve().then(onRemoteCheck).catch(() => null) : null,
   ]);
-  if (!metadata) {
+  if (!remoteTags) {
     const resultBase = persistRemoteCache({
       lastStatus: "offline",
       lastErrorCode: "fetch_failed",
@@ -726,17 +684,19 @@ export async function buildSelfCheck(target, options = {}) {
     };
   }
 
-  tags = metadata.tags;
+  tags = remoteTags;
   const recommendation = getUpdateRecommendation(currentFlower, tags);
   const remoteStatus = recommendation ? "update_available" : "up_to_date";
   const releaseNotesRange = recommendation
     ? updateReleaseNotesRange(currentFlower, recommendation)
-    : projectReleaseNotesRange(projectFlower, currentFlower);
-  const releaseNotes = releaseNotesFromMetadata(metadata, releaseNotesRange);
+    : projectOutOfSync ? projectReleaseNotesRange(projectFlower, currentFlower) : null;
+  const releaseNotes = cachedReleaseNotes(updateCheck, releaseNotesRange) || (releaseNotesRange
+    ? releaseNotesFromMetadata(await fetchMetadata(), releaseNotesRange)
+    : null);
   const resultBase = persistRemoteCache({
     lastCheckedAt: now.toISOString(),
     lastRemote: tags,
-    lastReleaseNotes: releaseNotes && !releaseNotes.unavailable ? releaseNotes : null,
+    ...(releaseNotes && !releaseNotes.unavailable ? { lastReleaseNotes: releaseNotes } : {}),
     lastStatus: remoteStatus,
     lastErrorCode: null,
   });