flower-trellis 0.6.3 → 0.6.5

package/src/commands/plugin.js

@@ -1,3 +1,4 @@
+import { observeTelemetryOperation, beginTelemetryOperation, noteTelemetryError } from "../lib/telemetry-operation.js";
 import fs from "node:fs";
 import path from "node:path";
 import { PLUGIN_ERROR_CODES, PluginError } from "../plugin/errors.js";
@@ -636,7 +637,10 @@ async function executeWithCapabilityApproval(execute, preview, options, output)
         default: false,
       });
     }
-    if (!approved) throw error;
+    if (!approved) {
+      error.telemetryCancelled = true;
+      throw error;
+    }
     return execute(previewResult.approvalRequests.map(({ pluginId }) => pluginId));
   }
 }
@@ -747,7 +751,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 = {}) {
@@ -778,6 +782,12 @@ export async function plugin(ctx, options = {}) {
       const remoteRuntime = await loadRemotePluginRuntime();
       return await remoteRuntime.runPluginManagementCommand(parsed, ctx, options, output);
     }
+    if (parsed.command === "add" && !parsed.dryRun) {
+      if (!ctx.telemetryOperation && !process.env.FLOWER_TELEMETRY_PARENT_OPERATION) {
+        return await observeTelemetryOperation(ctx, "plugin_add", nested => plugin(nested, options), options.telemetry || {});
+      }
+      beginTelemetryOperation(ctx);
+    }
     const trellisAlreadyMaterialized = ["materialized", "restoring"].includes(ctx.trellisControlMode) ||
       ["materialized", "restoring"].includes(options.trellisControlMode);
     if (
@@ -834,6 +844,8 @@ export async function plugin(ctx, options = {}) {
       options,
       registry,
       lock,
+      pluginsFile,
+      preserveIds: options.preserveIds || [],
     });
 
     if (parsed.command !== "add" && canonicalId && !canonicalId.includes("/")) {
@@ -889,7 +901,14 @@ export async function plugin(ctx, options = {}) {
       }));
     }
 
-    await remoteRuntime?.prepareRemotePluginCandidates({ parsed, canonicalId, registry, lock });
+    await remoteRuntime?.prepareRemotePluginCandidates({
+      parsed,
+      canonicalId,
+      registry,
+      lock,
+      pluginsFile,
+      preserveIds: options.preserveIds || [],
+    });
 
     const service = new PluginApplicationService(ctx.target, { registry, store });
     let result;
@@ -906,6 +925,7 @@ export async function plugin(ctx, options = {}) {
         platforms: parsed.platforms,
         ...(parsed.contentSelection ? { contentSelection: parsed.contentSelection } : {}),
         dryRun: parsed.dryRun,
+        preserveIds: options.preserveIds || [],
         onPreflight: options.onPreflight,
       };
       result = parsed.dryRun ? service.add(addOptions) : await executeWithCapabilityApproval(
@@ -925,6 +945,7 @@ export async function plugin(ctx, options = {}) {
         platforms: parsed.platforms,
         ...(parsed.contentSelection ? { contentSelection: parsed.contentSelection } : {}),
         dryRun: parsed.dryRun,
+        preserveIds: options.preserveIds || [],
         onPreflight: options.onPreflight,
       };
       result = parsed.dryRun ? service.update(updateOptions) : await executeWithCapabilityApproval(
@@ -955,6 +976,7 @@ export async function plugin(ctx, options = {}) {
     printResult(result, parsed.json, output, { compact, verbose });
     return result.ok === false ? 3 : 0;
   } catch (error) {
+    noteTelemetryError(ctx, error);
     const json = parsed?.json || ctx.passthrough?.includes("--json");
     const code = error instanceof PluginError ? error.code : "PLUGIN_UNEXPECTED_ERROR";
     const publicPath = error.path && !path.isAbsolute(error.path) ? error.path : "";

package/src/commands/self-check.js

@@ -1,5 +1,21 @@
 import { buildSelfCheck } from "../lib/self-check.js";
 import { reportTelemetry } from "../lib/telemetry.js";
+import { hasHelpFlag } from "../lib/cli-args.js";
+
+/** 打印 self-check 命令帮助。 */
+function printSelfCheckHelp() {
+  console.log(`flower-trellis self-check — 输出稳定的启动更新检查 JSON
+
+用法:
+  flower-trellis self-check [--manual] [--force-remote] [--target <dir>]
+
+选项:
+  --manual         绕过提示节流，但不强制绕过远端缓存
+  --force-remote   强制检查远端版本
+  --target <dir>   要检查的项目目录
+
+该命令供 SessionStart hook 和自动化读取，成功时始终输出 JSON。`);
+}
 
 /**
  * flower-trellis self-check:输出结构化启动更新检查结果。
@@ -11,6 +27,10 @@ import { reportTelemetry } from "../lib/telemetry.js";
  * @returns {Promise<void>}
  */
 export async function selfCheck(ctx) {
+  if (hasHelpFlag(ctx.passthrough)) {
+    printSelfCheckHelp();
+    return;
+  }
   const forceRemote = ctx.passthrough.includes("--force-remote");
   const manual = ctx.passthrough.includes("--manual") ||
     ctx.passthrough.includes("--ignore-prompt-suppression");

package/src/commands/self-update.js

@@ -1,3 +1,4 @@
+import { observeTelemetryOperation, beginTelemetryOperation, completeTelemetryOperation } from "../lib/telemetry-operation.js";
 import { spawnSync } from "node:child_process";
 import {
   buildSelfCheck,
@@ -6,6 +7,24 @@ import {
   safetyState,
 } from "../lib/self-check.js";
 import { installFlowerVersion } from "../lib/update-check.js";
+import { hasHelpFlag } from "../lib/cli-args.js";
+
+/** 打印 self-update 命令帮助。 */
+function printSelfUpdateHelp() {
+  console.log(`flower-trellis self-update — 更新全局 Flower 并重叠加当前项目
+
+用法:
+  flower-trellis self-update --target <dir> --dry-run
+  flower-trellis self-update --target <dir> --yes [--project-only] [-- <update flags>]
+
+选项:
+  --dry-run       只展示全局升级、项目更新与安全检查
+  -y, --yes       确认真实写入
+  --project-only  跳过全局包升级，仅修复项目版本差异
+  --              把后续冲突策略转发给项目 update
+
+建议先运行 --dry-run；真实更新完成后按输出进入 trellis-push。`);
+}
 
 /** 判断参数里是否包含指定 flag。 */
 function hasFlag(args, name) {
@@ -13,15 +32,16 @@ function hasFlag(args, name) {
 }
 
 /** 执行命令并在失败时给出统一错误。 */
-function runCommand(command, args, cwd, failureMessage) {
+function runCommand(command, args, cwd, failureMessage, env = process.env) {
   const res = spawnSync(command, args, {
     cwd,
+    env,
     stdio: "inherit",
     shell: process.platform === "win32",
   });
   if (res.status !== 0) {
     const reason = res.error ? res.error.message : `退出码 ${res.status ?? 1}`;
-    throw new Error(`${failureMessage}(${reason})`);
+    throw Object.assign(new Error(`${failureMessage}(${reason})`), { code: res.status === 130 ? "FLOWER_OPERATION_CANCELLED" : "FLOWER_UPSTREAM_FAILED" });
   }
 }
 
@@ -109,6 +129,18 @@ function printFlowerUpdateResult(fields) {
  * @returns {Promise<void>}
  */
 export async function selfUpdate(ctx) {
+  return observeTelemetryOperation(ctx, "self_update", executeSelfUpdate);
+}
+
+/** 执行已建立外部操作上下文的命令。
+ * @param {object} ctx 命令上下文
+ * @returns {Promise<void>} 完成
+ */
+async function executeSelfUpdate(ctx) {
+  if (hasHelpFlag(ctx.passthrough)) {
+    printSelfUpdateHelp();
+    return;
+  }
   const dryRun = hasFlag(ctx.passthrough, "--dry-run");
   const yes = hasFlag(ctx.passthrough, "--yes") || hasFlag(ctx.passthrough, "-y");
   const projectOnly = hasFlag(ctx.passthrough, "--project-only");
@@ -171,11 +203,12 @@ export async function selfUpdate(ctx) {
     return;
   }
 
+  beginTelemetryOperation(ctx);
   if (shouldInstallFlower) {
     const res = installFlowerVersion(check.recommendation.version, { cwd: ctx.target });
     if (res.status !== 0) {
       const reason = res.error ? res.error.message : `退出码 ${res.status ?? 1}`;
-      throw new Error(`全局 flower-trellis 升级失败(${reason})`);
+      throw Object.assign(new Error(`全局 flower-trellis 升级失败(${reason})`), { code: res.status === 130 ? "FLOWER_OPERATION_CANCELLED" : "FLOWER_UPSTREAM_FAILED" });
     }
   } else {
     console.log("  · 跳过全局 flower-trellis 升级");
@@ -186,8 +219,10 @@ export async function selfUpdate(ctx) {
     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);
   console.log(`\n🌸 flower-trellis self-update 完成 → ${ctx.target}`);
   printFlowerUpdateResult({

package/src/commands/telemetry.js

@@ -1,4 +1,19 @@
 import { readTelemetryState, setTelemetryEnabled } from "../lib/telemetry.js";
+import { queueTelemetryEvent, telemetryQueueStatus } from "../lib/telemetry-queue.js";
+import { hasHelpFlag } from "../lib/cli-args.js";
+
+/** 打印 telemetry 命令帮助。 */
+function printTelemetryHelp() {
+  console.log(`flower-trellis telemetry — 管理匿名安装遥测
+
+用法:
+  flower-trellis telemetry status
+  flower-trellis telemetry enable
+  flower-trellis telemetry disable
+
+status 只读取用户级状态；enable/disable 会更新用户级遥测开关。
+环境变量 FLOWER_NO_TELEMETRY=1 可临时停用上报。`);
+}
 
 /**
  * 格式化可空时间。
@@ -32,16 +47,30 @@ function printStatus(env) {
   console.log(`  开发者名称:${state?.developerName || "首次有效上报时识别"}`);
   console.log(`  最近尝试:${formatTime(state?.lastAttemptAt || null)}`);
   console.log(`  最近成功:${formatTime(state?.lastSuccessAt || null)}`);
+  const queue = telemetryQueueStatus({ env });
+  console.log(`  待发送:${queue.pending ?? "未知"}；本地丢弃:${queue.dropped ?? "未知"}`);
+  console.log(`  v2 最近成功:${formatTime(queue.lastSuccessAt)}；最近诊断:${queue.diagnostic || "无"}`);
+  console.log(`  最早重试:${formatTime(queue.nextRetryAt)}`);
 }
 
 /**
  * flower-trellis telemetry:查询或修改用户级匿名遥测开关。
  *
  * @param {object} ctx 见 cli-args.js 的 parseCliArgs()
+ * @param {object} options 活动采集依赖，供隔离验证使用
  * @returns {Promise<void>} 命令执行完成后返回
  */
-export async function telemetry(ctx) {
+export async function telemetry(ctx, options = {}) {
+  if (hasHelpFlag(ctx.passthrough)) {
+    printTelemetryHelp();
+    return;
+  }
   const action = ctx.passthrough[0] || "status";
+  if (action === "record-activity") {
+    const platform = ctx.passthrough[1];
+    if (["claude", "codex"].includes(platform)) queueTelemetryEvent(ctx.target, { event: "activity_daily", ai_platform: platform }, options);
+    return;
+  }
   if (action === "status") {
     printStatus(process.env);
     return;

package/src/commands/uninstall.js

@@ -3,6 +3,22 @@ import {
   applySkillGardenUninstall,
   planSkillGardenUninstall,
 } from "../builtin-plugins/skill-garden/uninstall.js";
+import { hasHelpFlag } from "../lib/cli-args.js";
+
+/** 打印 uninstall 命令帮助。 */
+function printUninstallHelp() {
+  console.log(`flower-trellis uninstall — 卸载 Trellis 并清理受管强化资产
+
+用法:
+  flower-trellis uninstall [--target <dir>] [--dry-run] [-y|--yes]
+
+选项:
+  --dry-run       只预览 Trellis 与 Plugin 清理计划
+  -y, --yes       传给 Trellis 的非交互确认
+  --target <dir>  目标项目目录
+
+若仍有其它 Plugin 依赖 flower/skill-garden，命令会拒绝清理并列出依赖方。`);
+}
 
 /**
  * flower-trellis uninstall：由 Trellis 删除自身内容，再按 Plugin state 清理平台资产。
@@ -11,6 +27,10 @@ import {
  * @returns {Promise<void>} 卸载完成后返回
  */
 export async function uninstall(ctx) {
+  if (hasHelpFlag(ctx.passthrough)) {
+    printUninstallHelp();
+    return;
+  }
   const { target } = ctx;
   const dryRun = ctx.passthrough.includes("--dry-run");
   const cleanupPlan = planSkillGardenUninstall(target);

package/src/commands/update-check.js

@@ -12,10 +12,25 @@ import {
   buildSelfCheck,
   DEFAULT_UPDATE_PROMPT_SNOOZE_HOURS,
 } from "../lib/self-check.js";
+import { hasHelpFlag } from "../lib/cli-args.js";
 
 const POLICIES = new Set(["off", "notify", "ask", "auto"]);
 const ACTIONABLE_STATUSES = new Set(["update_available", "project_out_of_sync"]);
 
+/** 打印 update-check 命令帮助。 */
+function printUpdateCheckHelp() {
+  console.log(`flower-trellis update-check — 管理启动更新检查策略
+
+用法:
+  flower-trellis update-check get [--target <dir>]
+  flower-trellis update-check set [--policy <off|notify|ask|auto>] [--interval-hours <n>]
+  flower-trellis update-check <disable|enable|reset>
+  flower-trellis update-check snooze [--hours <n>|--days <n>]
+  flower-trellis update-check skip
+
+set 至少需要一个策略选项；snooze 与 skip 仅在当前存在可操作更新提示时有效。`);
+}
+
 /** 读取 flag 后面的取值。 */
 function optionValue(args, name) {
   const index = args.indexOf(name);
@@ -79,6 +94,10 @@ function assertTrellisProject(target) {
  */
 export async function updateCheck(ctx) {
   const args = ctx.passthrough;
+  if (hasHelpFlag(args)) {
+    printUpdateCheckHelp();
+    return;
+  }
   const action = args.find((arg) => !arg.startsWith("-")) || "get";
   assertTrellisProject(ctx.target);
 

package/src/commands/update.js

@@ -1,5 +1,6 @@
+import { observeTelemetryOperation, beginTelemetryOperation, completeTelemetryOperation } from "../lib/telemetry-operation.js";
 import { runTrellis, runTrellisPty } from "../lib/trellis-runner.js";
-import { trellisUpdatePassthroughArgs } from "../lib/cli-args.js";
+import { hasHelpFlag, trellisUpdatePassthroughArgs } from "../lib/cli-args.js";
 import { plugin } from "./plugin.js";
 import { printBanner, getDeveloper } from "../lib/banner.js";
 import { checkForUpdate } from "../lib/update-check.js";
@@ -29,6 +30,7 @@ import {
   restoreUpdateSnapshot,
 } from "../lib/update-transaction.js";
 import { runWithTrellisIntegrationEnabled } from "../lib/trellis-control.js";
+import { classifyLockReachability } from "../plugin/lock-reachability.js";
 
 const SILENT_OUTPUT = Object.freeze({
   columns: 80,
@@ -40,6 +42,23 @@ const SILENT_OUTPUT = Object.freeze({
   off() {},
 });
 
+/** 打印 update 命令帮助。 */
+function printUpdateHelp() {
+  console.log(`flower-trellis update — 升级 Trellis 并重放已声明 Plugin
+
+用法:
+  flower-trellis update [trellis flags] [flower flags]
+
+常用选项:
+  --target <dir>           目标 Trellis 项目
+  --dry-run                仅预览升级与 Plugin 变化
+  --enhance-only           跳过 Trellis update，仅重放 Plugin
+  --backup-retention <n>   成功后保留最近 n 份升级备份，0 表示不清理
+  --no-update-check        本次跳过 flower-trellis 版本检查
+
+跨版本预览会在项目外沙箱执行；真实更新失败时会尝试恢复受管状态。`);
+}
+
 /**
  * 判断普通跨版本 dry-run 是否需要进入项目外升级沙箱。
  *
@@ -89,6 +108,17 @@ 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 pluginsFile = store.readPlugins();
+  const lock = store.readLock();
+  const { reachableIds } = classifyLockReachability(pluginsFile.plugins, lock);
+  const preserveIds = (lock?.plugins || [])
+    .filter(({ id, source }) => (
+      reachableIds.has(id) &&
+      id !== SKILL_GARDEN_PLUGIN_ID &&
+      ["gitlab", "github"].includes(source.type)
+    ))
+    .map(({ id }) => id);
   const onPreflight = compensationSnapshot || ctx.trellisControlExtendSnapshot
     ? ({ plan }) => {
       const targets = [
@@ -100,7 +130,7 @@ export async function replayPlugins(ctx, target, dryRun, compensationSnapshot =
     }
     : undefined;
   if (ctx.enhance) {
-    const declared = new ProjectStore(target).readPlugins().plugins
+    const declared = pluginsFile.plugins
       .some(({ id }) => id === SKILL_GARDEN_PLUGIN_ID);
     const code = await plugin({
       ...ctx,
@@ -113,6 +143,7 @@ export async function replayPlugins(ctx, target, dryRun, compensationSnapshot =
       ],
     }, {
       skillGarden: { variant: ctx.variant, skills: ctx.skills },
+      preserveIds,
       compact: true,
       onPreflight,
       output,
@@ -122,15 +153,17 @@ export async function replayPlugins(ctx, target, dryRun, compensationSnapshot =
   }
 
   output.log("· --no-enhance:跳过 Skill-Garden，仅重放其它已声明 Plugin");
-  const preserveSkillGarden = new ProjectStore(target).readLock()?.plugins
-    .some(({ id }) => id === SKILL_GARDEN_PLUGIN_ID) === true;
+  const preserveSkillGarden = reachableIds.has(SKILL_GARDEN_PLUGIN_ID);
   const code = await plugin({
     ...ctx,
     target,
     passthrough: ["replay", ...(dryRun ? ["--dry-run"] : [])],
   }, {
     skillGarden: { preserve: preserveSkillGarden },
-    preserveIds: preserveSkillGarden ? [SKILL_GARDEN_PLUGIN_ID] : [],
+    preserveIds: [
+      ...preserveIds,
+      ...(preserveSkillGarden ? [SKILL_GARDEN_PLUGIN_ID] : []),
+    ],
     compact: true,
     onPreflight,
     output,
@@ -207,13 +240,30 @@ function printBackupRetentionResult(result, output = console) {
  * @returns {Promise<void>} 升级、强化叠加与备份保留处理完成后返回
  */
 export async function update(ctx) {
+  return observeTelemetryOperation(ctx, "update", executeUpdate);
+}
+
+/** 执行已建立外部操作上下文的命令。
+ * @param {object} ctx 命令上下文
+ * @returns {Promise<void>} 完成
+ */
+async function executeUpdate(ctx) {
+  if (hasHelpFlag(ctx.passthrough)) {
+    printUpdateHelp();
+    return;
+  }
   const dryRun = ctx.passthrough.includes("--dry-run");
+  if (!dryRun) beginTelemetryOperation(ctx);
   if (!dryRun && ctx.trellisControlMode !== "materialized" && ctx.trellisControlMode !== "restoring") {
-    return runWithTrellisIntegrationEnabled(ctx.target, ({ extendSnapshot }) => update({
+    const result = await runWithTrellisIntegrationEnabled(ctx.target, ({ extendSnapshot }) => update({
       ...ctx,
       trellisControlMode: "materialized",
+      telemetryDeferCompletion: true,
       trellisControlExtendSnapshot: extendSnapshot,
     }));
+    completeTelemetryOperation(ctx, "update");
+    await showCommandCompletion("update", ctx.target, { passthrough: ctx.passthrough, outcome: "success", output: ctx.trellisControlQuiet ? SILENT_OUTPUT : console });
+    return result;
   }
   const { target } = ctx;
   const quiet = ctx.trellisControlQuiet === true;
@@ -258,7 +308,7 @@ export async function update(ctx) {
         { stripBanner: true, ...(quiet ? { stdout: SILENT_OUTPUT } : {}) },
       );
       if (code !== 0) {
-        throw new Error(`trellis update 失败(退出码 ${code}),已中止,未重新叠加`);
+        throw Object.assign(new Error(`trellis update 失败(退出码 ${code}),已中止,未重新叠加`), { code: code === 130 ? "FLOWER_OPERATION_CANCELLED" : "FLOWER_UPSTREAM_FAILED" });
       }
       await replayPlugins(ctx, target, dryRun, compensationSnapshot);
       updateSucceeded = true;
@@ -307,10 +357,11 @@ export async function update(ctx) {
     output.log("  · --backup-retention 0:保留全部升级备份");
   }
 
+  if (!ctx.telemetryDeferCompletion) completeTelemetryOperation(ctx, "update");
   const telemetryPromise = dryRun
     ? null
     : reportTelemetry(target, "update_completed", { force: true });
-  await showCommandCompletion("update", target, {
+  if (!ctx.telemetryDeferCompletion) await showCommandCompletion("update", target, {
     passthrough: ctx.passthrough,
     outcome: dryRun ? "preview" : "success",
     output,

package/src/commands/worktree.js

@@ -8,6 +8,7 @@ import {
 } from "../lib/trellis-python-command.js";
 
 const SUPPORTED_COMMANDS = new Set(["status", "prepare", "migrate", "create", "remove"]);
+const HELP_OPTIONS = new Set(["-h", "--help"]);
 const VALUE_OPTIONS = new Set([
   "--branch",
   "--base",
@@ -19,6 +20,114 @@ const VALUE_OPTIONS = new Set([
 ]);
 const BOOLEAN_OPTIONS = new Set(["--json", "--dry-run", "--yes", "--inherit-route-prefs"]);
 
+/**
+ * 识别 worktree 根级或子命令级帮助请求。
+ *
+ * @param {string[]} args `worktree` 之后的参数
+ * @returns {string|null|undefined} 子命令名、根级帮助标记，或非帮助请求
+ */
+function requestedHelpCommand(args) {
+  const first = args[0];
+  if (first === "help" || HELP_OPTIONS.has(first)) {
+    const command = args[1];
+    if (command && !SUPPORTED_COMMANDS.has(command)) {
+      throw new Error(`worktree help 不支持子命令: ${command}`);
+    }
+    return command || null;
+  }
+  if (SUPPORTED_COMMANDS.has(first) && args.slice(1).some((token) => HELP_OPTIONS.has(token))) {
+    return first;
+  }
+  return undefined;
+}
+
+/**
+ * 打印 worktree 根级或指定子命令的场景化帮助。
+ *
+ * @param {string|null} command 可选子命令
+ * @returns {void}
+ */
+function printWorktreeHelp(command) {
+  if (command === "status") {
+    console.log(`flower-trellis worktree status — 只读诊断目标 worktree
+
+用法:
+  flower-trellis worktree status [--target <dir>] [--json]
+
+先运行 status，再根据返回的 ready-local、needs-prepare、needs-init 或
+needs-migration 状态选择下一步。`);
+    return;
+  }
+  if (command === "prepare") {
+    console.log(`flower-trellis worktree prepare — 准备分支本地运行状态
+
+用法:
+  flower-trellis worktree prepare [--target <dir>] [--developer <name>]
+                                   [--inherit-route-prefs] [--json]
+
+prepare 不创建 Git worktree，只补齐目标分支本地的 developer、runtime 和 registry 状态。
+仅在确实需要继承当前控制 worktree 的个人路由偏好时使用 --inherit-route-prefs。`);
+    return;
+  }
+  if (command === "migrate") {
+    console.log(`flower-trellis worktree migrate — 迁移旧版 worktree 投影
+
+用法:
+  flower-trellis worktree migrate [--target <dir>] --dry-run [--json]
+  flower-trellis worktree migrate [--target <dir>] [--json]
+
+必须先用 --dry-run 检查迁移计划，再执行真实迁移。`);
+    return;
+  }
+  if (command === "create") {
+    console.log(`flower-trellis worktree create — 创建新分支、worktree 和 planning task
+
+只读预检:
+  flower-trellis worktree create --target <dir> --branch <new-branch> [--base <ref>]
+    --task-title <title> --task-slug <slug> [--task-description <text>]
+    [--developer <name>] [--json]
+
+确认执行:
+  flower-trellis worktree create ... --yes --plan-fingerprint <sha256>
+
+重要:
+  --branch 必须是尚不存在的新分支；create 不挂载已有分支。
+  已有分支请改用:
+    git worktree add <target> <existing-branch>
+    flower-trellis worktree status --target <target>
+  若 status 返回 needs-prepare，再运行:
+    flower-trellis worktree prepare --target <target> [--developer <name>]`);
+    return;
+  }
+  if (command === "remove") {
+    console.log(`flower-trellis worktree remove — 安全移除已登记的 linked worktree
+
+用法:
+  flower-trellis worktree remove [--target <dir>] [--json]
+
+目标必须无未提交修改、活动任务、会话或锁；remove 保留对应 Git 分支。`);
+    return;
+  }
+  console.log(`flower-trellis worktree — 管理分支本地化 Git worktree
+
+用法:
+  flower-trellis worktree <子命令> [选项]
+  flower-trellis worktree <子命令> --help
+
+子命令:
+  status    只读诊断目标 worktree 状态
+  prepare   准备分支本地 developer、runtime 和 registry 状态
+  migrate   迁移旧版 worktree 投影
+  create    创建新分支、worktree 和 planning task
+  remove    安全移除 worktree，保留 Git 分支
+
+推荐先运行:
+  flower-trellis worktree status --target <target>
+
+创建新分支请查看:
+  flower-trellis worktree create --help`);
+}
+
 /**
  * 解析 Flower worktree 子命令参数。
  *
@@ -154,6 +263,11 @@ export function printWorktreeResult(payload) {
  * @returns {Promise<number>} 进程退出码
  */
 export async function worktree(ctx) {
+  const helpCommand = requestedHelpCommand(ctx.passthrough);
+  if (helpCommand !== undefined) {
+    printWorktreeHelp(helpCommand);
+    return 0;
+  }
   const parsed = parseWorktreeArgs(ctx.passthrough);
   if (parsed.command === "create" && !ctx.targetExplicit) {
     throw new Error("worktree create 必须显式传入 --target");

package/src/lib/cli-args.js

@@ -1,6 +1,16 @@
 import path from "node:path";
 import { DEFAULT_UPDATE_BACKUP_RETENTION } from "../constants.js";
 
+/**
+ * 判断命令参数是否请求帮助。
+ *
+ * @param {string[]} args 命令自身收到的参数
+ * @returns {boolean} 是否包含 -h 或 --help
+ */
+export function hasHelpFlag(args) {
+  return args.some((arg) => arg === "-h" || arg === "--help");
+}
+
 /**
  * 解析 flower-trellis argv，分离自有参数与 Trellis 透传参数。
  *

package/src/lib/developer.js

@@ -4,7 +4,7 @@ import { execFileSync } from "node:child_process";
  * 读取目标目录可见的 Git 开发者名称。
  *
  * @param {string} target 目标项目根目录
- * @param {{env?:NodeJS.ProcessEnv}} [options] 读取选项
+ * @param {{env?:NodeJS.ProcessEnv,timeoutMs?:number}} [options] 读取选项
  * @returns {string|null} Git 开发者名称，无法识别时返回 null
  */
 export function readGitDeveloper(target, options = {}) {
@@ -13,6 +13,7 @@ export function readGitDeveloper(target, options = {}) {
       execFileSync("git", ["-C", target, "config", "user.name"], {
         encoding: "utf8",
         env: options.env || process.env,
+        ...(options.timeoutMs ? { timeout: options.timeoutMs } : {}),
       }).trim() || null
     );
   } catch {
@@ -25,7 +26,7 @@ export function readGitDeveloper(target, options = {}) {
  *
  * @param {string[]} passthrough Trellis 透传参数
  * @param {string} target 目标项目根目录
- * @param {{env?:NodeJS.ProcessEnv}} [options] 读取选项
+ * @param {{env?:NodeJS.ProcessEnv,timeoutMs?:number}} [options] 读取选项
  * @returns {string|null} 开发者名称，无法识别时返回 null
  */
 export function getDeveloper(passthrough, target, options = {}) {