clawt 2.14.1 → 2.15.0

package/README.md

@@ -52,6 +52,29 @@ clawt run -f tasks.md
 
 # 从任务文件读取任务，但用 -b 自动编号分支（文件中分支名可省略）
 clawt run -f tasks.md -b feat
+
+# 试运行：仅预览将要创建的 worktree 和任务，不实际执行
+clawt run -b <branch> --tasks "任务1" --tasks "任务2" --dry-run
+```
+
+**`--dry-run` 预览示例：**
+
+```
+════════════════════════════════════════
+  Dry Run 预览
+════════════════════════════════════════
+任务数: 2 │ 并发数: 不限制 │ Worktree: ~/.clawt/worktrees/project
+────────────────────────────────────────
+✓ [1/2] feat-1
+  路径: ~/.clawt/worktrees/project/feat-1
+  任务: 任务1
+
+✓ [2/2] feat-2
+  路径: ~/.clawt/worktrees/project/feat-2
+  任务: 任务2
+
+════════════════════════════════════════
+✓ 预览完成，无冲突。移除 --dry-run 即可正式执行。
 ```
 
 **任务文件格式：**

package/dist/index.js

@@ -98,7 +98,23 @@ var RUN_MESSAGES = {
   /** 任务文件加载成功 */
   TASK_FILE_LOADED: (count, path) => `\u2713 \u4ECE ${path} \u52A0\u8F7D\u4E86 ${count} \u4E2A\u4EFB\u52A1`,
   /** 未指定 -b 或 -f */
-  BRANCH_OR_FILE_REQUIRED: "\u8BF7\u6307\u5B9A -b \u5206\u652F\u540D\u6216 -f \u4EFB\u52A1\u6587\u4EF6"
+  BRANCH_OR_FILE_REQUIRED: "\u8BF7\u6307\u5B9A -b \u5206\u652F\u540D\u6216 -f \u4EFB\u52A1\u6587\u4EF6",
+  /** dry-run 预览标题 */
+  DRY_RUN_TITLE: "Dry Run \u9884\u89C8",
+  /** dry-run 任务数量 */
+  DRY_RUN_TASK_COUNT: (count) => `\u4EFB\u52A1\u6570: ${count}`,
+  /** dry-run 并发数 */
+  DRY_RUN_CONCURRENCY: (concurrency) => `\u5E76\u53D1\u6570: ${concurrency === 0 ? "\u4E0D\u9650\u5236" : concurrency}`,
+  /** dry-run worktree 目录 */
+  DRY_RUN_WORKTREE_DIR: (dir) => `Worktree: ${dir}`,
+  /** dry-run 分支已存在警告 */
+  DRY_RUN_BRANCH_EXISTS_WARNING: (name) => `\u5206\u652F ${name} \u5DF2\u5B58\u5728`,
+  /** dry-run 交互式模式提示（无任务描述） */
+  DRY_RUN_INTERACTIVE_MODE: "\u6A21\u5F0F: \u4EA4\u4E92\u5F0F\uFF08\u65E0\u9884\u8BBE\u4EFB\u52A1\uFF09",
+  /** dry-run 预览完成且无冲突 */
+  DRY_RUN_READY: "\u9884\u89C8\u5B8C\u6210\uFF0C\u65E0\u51B2\u7A81\u3002\u79FB\u9664 --dry-run \u5373\u53EF\u6B63\u5F0F\u6267\u884C\u3002",
+  /** dry-run 存在分支冲突 */
+  DRY_RUN_HAS_CONFLICT: "\u5B58\u5728\u5206\u652F\u51B2\u7A81\uFF0C\u5B9E\u9645\u6267\u884C\u65F6\u5C06\u4F1A\u62A5\u9519\u3002\u8BF7\u5148\u5904\u7406\u51B2\u7A81\u7684\u5206\u652F\u3002"
 };
 
 // src/constants/messages/create.ts
@@ -969,6 +985,16 @@ function ensureClawtDirs() {
   ensureDir(LOGS_DIR);
   ensureDir(WORKTREES_DIR);
 }
+function parseConcurrency(optionValue, configValue) {
+  if (optionValue === void 0) {
+    return configValue;
+  }
+  const parsed = parseInt(optionValue, 10);
+  if (Number.isNaN(parsed) || parsed < 0) {
+    throw new ClawtError(MESSAGES.CONCURRENCY_INVALID);
+  }
+  return parsed;
+}
 
 // src/utils/prompt.ts
 import Enquirer from "enquirer";
@@ -1492,6 +1518,14 @@ import { resolve } from "path";
 import { existsSync as existsSync8, readFileSync as readFileSync3 } from "fs";
 var TASK_BLOCK_REGEX = /<!-- CLAWT-TASKS:START -->([\s\S]*?)<!-- CLAWT-TASKS:END -->/g;
 var BRANCH_LINE_REGEX = /^#\s*branch:\s*(.+)$/;
+var EMPTY_TASKS_MESSAGE = "\u4EFB\u52A1\u5217\u8868\u4E0D\u80FD\u4E3A\u7A7A";
+function parseTasksFromOptions(rawTasks) {
+  const tasks = rawTasks.map((t) => t.trim()).filter(Boolean);
+  if (tasks.length === 0) {
+    throw new ClawtError(EMPTY_TASKS_MESSAGE);
+  }
+  return tasks;
+}
 function parseTaskFile(content, options) {
   const branchRequired = options?.branchRequired ?? true;
   const entries = [];
@@ -1742,6 +1776,59 @@ async function executeBatchTasks(worktrees, tasks, concurrency) {
   printTaskSummary(summary);
 }
 
+// src/utils/dry-run.ts
+import chalk4 from "chalk";
+import { join as join5 } from "path";
+var DRY_RUN_TASK_DESC_MAX_LENGTH = 70;
+function truncateTaskDesc(task) {
+  const oneLine = task.replace(/\n/g, " ").trim();
+  if (oneLine.length <= DRY_RUN_TASK_DESC_MAX_LENGTH) {
+    return oneLine;
+  }
+  return oneLine.slice(0, DRY_RUN_TASK_DESC_MAX_LENGTH) + "...";
+}
+function printDryRunPreview(branchNames, tasks, concurrency) {
+  const projectDir = getProjectWorktreeDir();
+  const isInteractive = tasks.length === 0;
+  printDoubleSeparator();
+  printInfo(`  ${chalk4.bold(MESSAGES.DRY_RUN_TITLE)}`);
+  printDoubleSeparator();
+  const summaryParts = [
+    MESSAGES.DRY_RUN_TASK_COUNT(branchNames.length),
+    MESSAGES.DRY_RUN_CONCURRENCY(concurrency),
+    MESSAGES.DRY_RUN_WORKTREE_DIR(projectDir)
+  ];
+  if (isInteractive) {
+    summaryParts.push(MESSAGES.DRY_RUN_INTERACTIVE_MODE);
+  }
+  printInfo(summaryParts.join(chalk4.gray(" \u2502 ")));
+  printSeparator();
+  let hasConflict = false;
+  for (let i = 0; i < branchNames.length; i++) {
+    const branch = branchNames[i];
+    const worktreePath = join5(projectDir, branch);
+    const exists = checkBranchExists(branch);
+    if (exists) hasConflict = true;
+    const indexLabel = `[${i + 1}/${branchNames.length}]`;
+    if (exists) {
+      printInfo(`${chalk4.yellow("\u26A0")} ${indexLabel} ${chalk4.yellow(branch)} ${chalk4.gray("\u2014")} ${chalk4.yellow(MESSAGES.DRY_RUN_BRANCH_EXISTS_WARNING(branch))}`);
+    } else {
+      printInfo(`${chalk4.green("\u2713")} ${indexLabel} ${chalk4.cyan(branch)}`);
+    }
+    printInfo(`  ${chalk4.gray("\u8DEF\u5F84:")} ${worktreePath}`);
+    if (!isInteractive) {
+      printInfo(`  ${chalk4.gray("\u4EFB\u52A1:")} ${truncateTaskDesc(tasks[i])}`);
+    }
+    printInfo("");
+  }
+  printDoubleSeparator();
+  if (hasConflict) {
+    printInfo(chalk4.yellow(`\u26A0 ${MESSAGES.DRY_RUN_HAS_CONFLICT}`));
+  } else {
+    printInfo(chalk4.green(`\u2713 ${MESSAGES.DRY_RUN_READY}`));
+  }
+}
+
 // src/utils/alias.ts
 function applyAliases(program2, aliases) {
   for (const [alias, commandName] of Object.entries(aliases)) {
@@ -1756,7 +1843,7 @@ function applyAliases(program2, aliases) {
 }
 
 // src/utils/config-strategy.ts
-import chalk4 from "chalk";
+import chalk5 from "chalk";
 import Enquirer3 from "enquirer";
 function isValidConfigKey(key) {
   return key in DEFAULT_CONFIG;
@@ -1800,9 +1887,9 @@ async function promptConfigValue(key, currentValue) {
 }
 function formatConfigValue(value) {
   if (typeof value === "boolean") {
-    return value ? chalk4.green("true") : chalk4.yellow("false");
+    return value ? chalk5.green("true") : chalk5.yellow("false");
   }
-  return chalk4.cyan(String(value));
+  return chalk5.cyan(String(value));
 }
 async function promptBooleanValue(key, currentValue) {
   const choices = [
@@ -1846,7 +1933,7 @@ async function promptStringValue(key, currentValue) {
 }
 
 // src/commands/list.ts
-import chalk5 from "chalk";
+import chalk6 from "chalk";
 function registerListCommand(program2) {
   program2.command("list").description("\u5217\u51FA\u5F53\u524D\u9879\u76EE\u6240\u6709 worktree").option("--json", "\u4EE5 JSON \u683C\u5F0F\u8F93\u51FA").action((options) => {
     handleList(options);
@@ -1883,12 +1970,12 @@ function printListAsText(projectName, worktrees) {
     for (const wt of worktrees) {
       const status = getWorktreeStatus(wt);
       const isIdle = status ? isWorktreeIdle(status) : false;
-      const pathDisplay = isIdle ? chalk5.hex("#FF8C00")(wt.path) : wt.path;
+      const pathDisplay = isIdle ? chalk6.hex("#FF8C00")(wt.path) : wt.path;
       printInfo(`  ${pathDisplay}   [${wt.branch}]`);
       if (status) {
         printInfo(`    ${formatWorktreeStatus(status)}`);
       } else {
-        printInfo(`    ${chalk5.yellow(MESSAGES.WORKTREE_STATUS_UNAVAILABLE)}`);
+        printInfo(`    ${chalk6.yellow(MESSAGES.WORKTREE_STATUS_UNAVAILABLE)}`);
       }
       printInfo("");
     }
@@ -1991,19 +2078,16 @@ async function handleRemove(options) {
 
 // src/commands/run.ts
 function registerRunCommand(program2) {
-  program2.command("run").description("\u6279\u91CF\u521B\u5EFA worktree \u5E76\u542F\u52A8 Claude Code \u6267\u884C\u4EFB\u52A1").option("-b, --branch <branchName>", "\u5206\u652F\u540D").option("--tasks <task...>", "\u4EFB\u52A1\u5217\u8868\uFF08\u53EF\u591A\u6B21\u6307\u5B9A\uFF09\uFF0C\u4E0D\u4F20\u5219\u5728 worktree \u4E2D\u6253\u5F00 Claude Code \u4EA4\u4E92\u5F0F\u754C\u9762").option("-c, --concurrency <n>", "\u6700\u5927\u5E76\u53D1\u6570\uFF0C0 \u8868\u793A\u4E0D\u9650\u5236").option("-f, --file <path>", "\u4ECE\u4EFB\u52A1\u6587\u4EF6\u8BFB\u53D6\u4EFB\u52A1\u5217\u8868\uFF08\u4E0E --tasks \u4E92\u65A5\uFF09").action(async (options) => {
+  program2.command("run").description("\u6279\u91CF\u521B\u5EFA worktree \u5E76\u542F\u52A8 Claude Code \u6267\u884C\u4EFB\u52A1").option("-b, --branch <branchName>", "\u5206\u652F\u540D").option("--tasks <task...>", "\u4EFB\u52A1\u5217\u8868\uFF08\u53EF\u591A\u6B21\u6307\u5B9A\uFF09\uFF0C\u4E0D\u4F20\u5219\u5728 worktree \u4E2D\u6253\u5F00 Claude Code \u4EA4\u4E92\u5F0F\u754C\u9762").option("-c, --concurrency <n>", "\u6700\u5927\u5E76\u53D1\u6570\uFF0C0 \u8868\u793A\u4E0D\u9650\u5236").option("-f, --file <path>", "\u4ECE\u4EFB\u52A1\u6587\u4EF6\u8BFB\u53D6\u4EFB\u52A1\u5217\u8868\uFF08\u4E0E --tasks \u4E92\u65A5\uFF09").option("-d, --dry-run", "\u9884\u89C8\u6A21\u5F0F\uFF0C\u4EC5\u5C55\u793A\u4EFB\u52A1\u8BA1\u5212\u4E0D\u5B9E\u9645\u6267\u884C").action(async (options) => {
     await handleRun(options);
   });
 }
-function parseConcurrency(optionValue, configValue) {
-  if (optionValue === void 0) {
-    return configValue;
-  }
-  const parsed = parseInt(optionValue, 10);
-  if (Number.isNaN(parsed) || parsed < 0) {
-    throw new ClawtError(MESSAGES.CONCURRENCY_INVALID);
+function resolveBranchNamesFromFile(options, entryCount, entries) {
+  if (options.branch) {
+    const sanitized = sanitizeBranchName(options.branch);
+    return generateBranchNames(sanitized, entryCount);
   }
-  return parsed;
+  return entries.map((e) => sanitizeBranchName(e.branch));
 }
 async function handleRunFromFile(options) {
   const branchRequired = !options.branch;
@@ -2021,12 +2105,39 @@ async function handleRunFromFile(options) {
   logger.info(`run \u547D\u4EE4\uFF08\u6587\u4EF6\u6A21\u5F0F\uFF09\u6267\u884C\uFF0C\u4EFB\u52A1\u6570: ${entries.length}\uFF0C\u5E76\u53D1\u6570: ${concurrency || "\u4E0D\u9650\u5236"}`);
   await executeBatchTasks(worktrees, tasks, concurrency);
 }
+function handleDryRunFromFile(options) {
+  const branchRequired = !options.branch;
+  const entries = loadTaskFile(options.file, { branchRequired });
+  printSuccess(MESSAGES.TASK_FILE_LOADED(entries.length, options.file));
+  const tasks = entries.map((e) => e.task);
+  const branchNames = resolveBranchNamesFromFile(options, entries.length, entries);
+  const concurrency = parseConcurrency(options.concurrency, getConfigValue("maxConcurrency"));
+  printDryRunPreview(branchNames, tasks, concurrency);
+}
 async function handleRun(options) {
   validateMainWorktree();
-  validateClaudeCodeInstalled();
   if (options.file && options.tasks) {
     throw new ClawtError(MESSAGES.FILE_AND_TASKS_CONFLICT);
   }
+  if (options.dryRun) {
+    if (options.file) {
+      return handleDryRunFromFile(options);
+    }
+    if (!options.branch) {
+      throw new ClawtError(MESSAGES.BRANCH_OR_FILE_REQUIRED);
+    }
+    const sanitized = sanitizeBranchName(options.branch);
+    if (!options.tasks || options.tasks.length === 0) {
+      printDryRunPreview([sanitized], [], 0);
+      return;
+    }
+    const tasks2 = parseTasksFromOptions(options.tasks);
+    const branchNames = generateBranchNames(sanitized, tasks2.length);
+    const concurrency2 = parseConcurrency(options.concurrency, getConfigValue("maxConcurrency"));
+    printDryRunPreview(branchNames, tasks2, concurrency2);
+    return;
+  }
+  validateClaudeCodeInstalled();
   if (options.file) {
     return handleRunFromFile(options);
   }
@@ -2044,10 +2155,7 @@ async function handleRun(options) {
     launchInteractiveClaude(worktree);
     return;
   }
-  const tasks = options.tasks.map((t) => t.trim()).filter(Boolean);
-  if (tasks.length === 0) {
-    throw new ClawtError("\u4EFB\u52A1\u5217\u8868\u4E0D\u80FD\u4E3A\u7A7A");
-  }
+  const tasks = parseTasksFromOptions(options.tasks);
   const count = tasks.length;
   const concurrency = parseConcurrency(options.concurrency, getConfigValue("maxConcurrency"));
   logger.info(`run \u547D\u4EE4\u6267\u884C\uFF0C\u5206\u652F: ${options.branch}\uFF0C\u4EFB\u52A1\u6570: ${count}\uFF0C\u5E76\u53D1\u6570: ${concurrency || "\u4E0D\u9650\u5236"}`);
@@ -2413,7 +2521,7 @@ async function handleMerge(options) {
 }
 
 // src/commands/config.ts
-import chalk6 from "chalk";
+import chalk7 from "chalk";
 import Enquirer5 from "enquirer";
 function registerConfigCommand(program2) {
   const configCmd = program2.command("config").description("\u4EA4\u4E92\u5F0F\u67E5\u770B\u548C\u4FEE\u6539\u5168\u5C40\u914D\u7F6E").action(async () => {
@@ -2474,7 +2582,7 @@ async function handleInteractiveConfigSet() {
     const isObject = typeof DEFAULT_CONFIG[k] === "object";
     return {
       name: k,
-      message: `${k}: ${isObject ? chalk6.dim(JSON.stringify(config2[k])) : formatConfigValue(config2[k])}  ${chalk6.dim(`\u2014 ${CONFIG_DESCRIPTIONS[k]}`)}`,
+      message: `${k}: ${isObject ? chalk7.dim(JSON.stringify(config2[k])) : formatConfigValue(config2[k])}  ${chalk7.dim(`\u2014 ${CONFIG_DESCRIPTIONS[k]}`)}`,
       ...isObject && { disabled: CONFIG_ALIAS_DISABLED_HINT }
     };
   });
@@ -2583,7 +2691,7 @@ async function handleReset() {
 }
 
 // src/commands/status.ts
-import chalk7 from "chalk";
+import chalk8 from "chalk";
 function registerStatusCommand(program2) {
   program2.command("status").description("\u663E\u793A\u9879\u76EE\u5168\u5C40\u72B6\u6001\u603B\u89C8").option("--json", "\u4EE5 JSON \u683C\u5F0F\u8F93\u51FA").action((options) => {
     handleStatus(options);
@@ -2679,7 +2787,7 @@ function printStatusAsJson(result) {
 }
 function printStatusAsText(result) {
   printDoubleSeparator();
-  printInfo(`  ${chalk7.bold.cyan(MESSAGES.STATUS_TITLE(result.main.projectName))}`);
+  printInfo(`  ${chalk8.bold.cyan(MESSAGES.STATUS_TITLE(result.main.projectName))}`);
   printDoubleSeparator();
   printInfo("");
   printMainSection(result.main);
@@ -2692,17 +2800,17 @@ function printStatusAsText(result) {
   printDoubleSeparator();
 }
 function printMainSection(main) {
-  printInfo(`  ${chalk7.bold("\u25C6")} ${chalk7.bold(MESSAGES.STATUS_MAIN_SECTION)}`);
-  printInfo(`    \u5206\u652F: ${chalk7.bold(main.branch)}`);
+  printInfo(`  ${chalk8.bold("\u25C6")} ${chalk8.bold(MESSAGES.STATUS_MAIN_SECTION)}`);
+  printInfo(`    \u5206\u652F: ${chalk8.bold(main.branch)}`);
   if (main.isClean) {
-    printInfo(`    \u72B6\u6001: ${chalk7.green("\u2713 \u5E72\u51C0")}`);
+    printInfo(`    \u72B6\u6001: ${chalk8.green("\u2713 \u5E72\u51C0")}`);
   } else {
-    printInfo(`    \u72B6\u6001: ${chalk7.yellow("\u2717 \u6709\u672A\u63D0\u4EA4\u4FEE\u6539")}`);
+    printInfo(`    \u72B6\u6001: ${chalk8.yellow("\u2717 \u6709\u672A\u63D0\u4EA4\u4FEE\u6539")}`);
   }
   printInfo("");
 }
 function printWorktreesSection(worktrees, total) {
-  printInfo(`  ${chalk7.bold("\u25C6")} ${chalk7.bold(MESSAGES.STATUS_WORKTREES_SECTION)} (${total} \u4E2A)`);
+  printInfo(`  ${chalk8.bold("\u25C6")} ${chalk8.bold(MESSAGES.STATUS_WORKTREES_SECTION)} (${total} \u4E2A)`);
   printInfo("");
   if (worktrees.length === 0) {
     printInfo(`    ${MESSAGES.STATUS_NO_WORKTREES}`);
@@ -2714,39 +2822,39 @@ function printWorktreesSection(worktrees, total) {
 }
 function printWorktreeItem(wt) {
   const statusLabel = formatChangeStatusLabel(wt.changeStatus);
-  printInfo(`  ${chalk7.bold("\u25CF")} ${chalk7.bold(wt.branch)}   [${statusLabel}]`);
+  printInfo(`  ${chalk8.bold("\u25CF")} ${chalk8.bold(wt.branch)}   [${statusLabel}]`);
   const parts = [];
   if (wt.insertions > 0 || wt.deletions > 0) {
-    parts.push(`${chalk7.green(`+${wt.insertions}`)} ${chalk7.red(`-${wt.deletions}`)}`);
+    parts.push(`${chalk8.green(`+${wt.insertions}`)} ${chalk8.red(`-${wt.deletions}`)}`);
   }
   if (wt.commitsAhead > 0) {
-    parts.push(chalk7.yellow(`${wt.commitsAhead} \u4E2A\u672C\u5730\u63D0\u4EA4`));
+    parts.push(chalk8.yellow(`${wt.commitsAhead} \u4E2A\u672C\u5730\u63D0\u4EA4`));
   }
   if (wt.commitsBehind > 0) {
-    parts.push(chalk7.yellow(`\u843D\u540E\u4E3B\u5206\u652F ${wt.commitsBehind} \u4E2A\u63D0\u4EA4`));
+    parts.push(chalk8.yellow(`\u843D\u540E\u4E3B\u5206\u652F ${wt.commitsBehind} \u4E2A\u63D0\u4EA4`));
   } else {
-    parts.push(chalk7.green("\u4E0E\u4E3B\u5206\u652F\u540C\u6B65"));
+    parts.push(chalk8.green("\u4E0E\u4E3B\u5206\u652F\u540C\u6B65"));
   }
   printInfo(`    ${parts.join("   ")}`);
   if (wt.hasSnapshot) {
-    printInfo(`    ${chalk7.blue("\u6709 validate \u5FEB\u7167")}`);
+    printInfo(`    ${chalk8.blue("\u6709 validate \u5FEB\u7167")}`);
   }
   printInfo("");
 }
 function formatChangeStatusLabel(status) {
   switch (status) {
     case "committed":
-      return chalk7.green(MESSAGES.STATUS_CHANGE_COMMITTED);
+      return chalk8.green(MESSAGES.STATUS_CHANGE_COMMITTED);
     case "uncommitted":
-      return chalk7.yellow(MESSAGES.STATUS_CHANGE_UNCOMMITTED);
+      return chalk8.yellow(MESSAGES.STATUS_CHANGE_UNCOMMITTED);
     case "conflict":
-      return chalk7.red(MESSAGES.STATUS_CHANGE_CONFLICT);
+      return chalk8.red(MESSAGES.STATUS_CHANGE_CONFLICT);
     case "clean":
-      return chalk7.gray(MESSAGES.STATUS_CHANGE_CLEAN);
+      return chalk8.gray(MESSAGES.STATUS_CHANGE_CLEAN);
   }
 }
 function printSnapshotsSection(snapshots) {
-  printInfo(`  ${chalk7.bold("\u25C6")} ${chalk7.bold(MESSAGES.STATUS_SNAPSHOTS_SECTION)} (${snapshots.length} \u4E2A)`);
+  printInfo(`  ${chalk8.bold("\u25C6")} ${chalk8.bold(MESSAGES.STATUS_SNAPSHOTS_SECTION)} (${snapshots.length} \u4E2A)`);
   printInfo("");
   if (snapshots.length === 0) {
     printInfo(`    ${MESSAGES.STATUS_NO_SNAPSHOTS}`);
@@ -2754,15 +2862,15 @@ function printSnapshotsSection(snapshots) {
     return;
   }
   for (const snap of snapshots) {
-    const orphanLabel = snap.worktreeExists ? "" : `  ${chalk7.yellow(MESSAGES.STATUS_SNAPSHOT_ORPHANED)}`;
-    const icon = snap.worktreeExists ? chalk7.blue("\u25CF") : chalk7.yellow("\u26A0");
+    const orphanLabel = snap.worktreeExists ? "" : `  ${chalk8.yellow(MESSAGES.STATUS_SNAPSHOT_ORPHANED)}`;
+    const icon = snap.worktreeExists ? chalk8.blue("\u25CF") : chalk8.yellow("\u26A0");
     printInfo(`  ${icon} ${snap.branch}${orphanLabel}`);
   }
   printInfo("");
 }
 
 // src/commands/alias.ts
-import chalk8 from "chalk";
+import chalk9 from "chalk";
 function getRegisteredCommandNames(program2) {
   return program2.commands.map((cmd) => cmd.name());
 }
@@ -2783,7 +2891,7 @@ ${MESSAGES.ALIAS_LIST_TITLE}
 `);
   printSeparator();
   for (const [alias, command] of entries) {
-    printInfo(`  ${chalk8.bold(alias)} \u2192 ${chalk8.cyan(command)}`);
+    printInfo(`  ${chalk9.bold(alias)} \u2192 ${chalk9.cyan(command)}`);
   }
   printInfo("");
   printSeparator();

package/dist/postinstall.js

@@ -90,7 +90,23 @@ var RUN_MESSAGES = {
   /** 任务文件加载成功 */
   TASK_FILE_LOADED: (count, path) => `\u2713 \u4ECE ${path} \u52A0\u8F7D\u4E86 ${count} \u4E2A\u4EFB\u52A1`,
   /** 未指定 -b 或 -f */
-  BRANCH_OR_FILE_REQUIRED: "\u8BF7\u6307\u5B9A -b \u5206\u652F\u540D\u6216 -f \u4EFB\u52A1\u6587\u4EF6"
+  BRANCH_OR_FILE_REQUIRED: "\u8BF7\u6307\u5B9A -b \u5206\u652F\u540D\u6216 -f \u4EFB\u52A1\u6587\u4EF6",
+  /** dry-run 预览标题 */
+  DRY_RUN_TITLE: "Dry Run \u9884\u89C8",
+  /** dry-run 任务数量 */
+  DRY_RUN_TASK_COUNT: (count) => `\u4EFB\u52A1\u6570: ${count}`,
+  /** dry-run 并发数 */
+  DRY_RUN_CONCURRENCY: (concurrency) => `\u5E76\u53D1\u6570: ${concurrency === 0 ? "\u4E0D\u9650\u5236" : concurrency}`,
+  /** dry-run worktree 目录 */
+  DRY_RUN_WORKTREE_DIR: (dir) => `Worktree: ${dir}`,
+  /** dry-run 分支已存在警告 */
+  DRY_RUN_BRANCH_EXISTS_WARNING: (name) => `\u5206\u652F ${name} \u5DF2\u5B58\u5728`,
+  /** dry-run 交互式模式提示（无任务描述） */
+  DRY_RUN_INTERACTIVE_MODE: "\u6A21\u5F0F: \u4EA4\u4E92\u5F0F\uFF08\u65E0\u9884\u8BBE\u4EFB\u52A1\uFF09",
+  /** dry-run 预览完成且无冲突 */
+  DRY_RUN_READY: "\u9884\u89C8\u5B8C\u6210\uFF0C\u65E0\u51B2\u7A81\u3002\u79FB\u9664 --dry-run \u5373\u53EF\u6B63\u5F0F\u6267\u884C\u3002",
+  /** dry-run 存在分支冲突 */
+  DRY_RUN_HAS_CONFLICT: "\u5B58\u5728\u5206\u652F\u51B2\u7A81\uFF0C\u5B9E\u9645\u6267\u884C\u65F6\u5C06\u4F1A\u62A5\u9519\u3002\u8BF7\u5148\u5904\u7406\u51B2\u7A81\u7684\u5206\u652F\u3002"
 };
 
 // src/constants/messages/create.ts

package/docs/spec.md

@@ -278,6 +278,7 @@ clawt run -b <branchName>
 | `--tasks` | 否   | 任务描述（可多次指定，每个 --tasks 对应一个任务，任务数量即 worktree 数量）。不传则在 worktree 中打开 Claude Code 交互式界面 |
 | `-f`      | 否   | 从任务文件读取任务列表（与 `--tasks` 互斥）                    |
 | `-c`      | 否   | 最大并发数，`0` 表示不限制                                    |
+| `--dry-run` | 否 | 试运行模式，仅输出预览信息不实际执行                            |
 
 **互斥约束：**
 
@@ -351,6 +352,51 @@ clawt run -b <branchName>
 
 **注意：** 当 `n = 1` 时（只有一个任务），worktree 目录命名规则同 **5.1**（不加 `-1` 后缀）。
 
+#### `--dry-run` 预览模式
+
+传入 `--dry-run` 时不实际创建 worktree 和执行任务，仅输出预览信息供用户确认。预览由 `printDryRunPreview()`（`src/utils/dry-run.ts`）负责渲染。
+
+**输出格式：**
+
+```
+════════════════════════════════════════
+  Dry Run 预览
+════════════════════════════════════════
+任务数: 3 │ 并发数: 不限制 │ Worktree: ~/.clawt/worktrees/project
+────────────────────────────────────────
+✓ [1/3] feat-login
+  路径: ~/.clawt/worktrees/project/feat-login
+  任务: 实现登录功能
+
+⚠ [2/3] feat-signup — 分支 feat-signup 已存在
+  路径: ~/.clawt/worktrees/project/feat-signup
+  任务: 实现注册功能
+
+✓ [3/3] fix-bug
+  路径: ~/.clawt/worktrees/project/fix-bug
+  任务: 修复内存泄漏
+
+════════════════════════════════════════
+✓ 预览完成，无冲突。移除 --dry-run 即可正式执行。
+```
+
+**格式规则：**
+
+1. **标题区**：双线分隔符包裹标题 `Dry Run 预览`
+2. **摘要行**：任务数、并发数、Worktree 目录路径合并为一行，用灰色 `│` 分隔；交互式模式（无 `--tasks`）会额外追加模式信息
+3. **分支列表**：
+   - 正常分支：行首绿色 `✓` + 序号 + 青色分支名
+   - 冲突分支：行首黄色 `⚠` + 序号 + 黄色分支名 + 灰色 `—` + 黄色警告文本（如 `分支 xxx 已存在`），警告合并在序号行
+4. **路径/任务行**：2 空格缩进，灰色标签前缀（`路径:` / `任务:`）
+5. **任务描述截断**：超过 70 字符时末尾加 `...`，多行合并为单行
+6. **结尾**：双线分隔符后根据冲突情况输出结论——无冲突时绿色 `✓` 提示，有冲突时黄色 `⚠` 警告
+
+**实现要点：**
+
+- 常量定义在 `src/constants/messages/run.ts`（`DRY_RUN_*` 系列）
+- `DRY_RUN_WORKTREE_DIR` 前缀为 `Worktree:`（简短形式）
+- `truncateTaskDesc()` 负责截断任务描述（最大长度 70 字符）
+
 ---
 
 ### 5.3 任务完成通知机制

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawt",
-  "version": "2.14.1",
+  "version": "2.15.0",
   "description": "本地并行执行多个Claude Code Agent任务，融合 Git Worktree 与 Claude Code CLI 的命令行工具",
   "type": "module",
   "main": "dist/index.js",

package/src/commands/run.ts

@@ -9,12 +9,16 @@ import {
   createWorktrees,
   createWorktreesByBranches,
   sanitizeBranchName,
+  generateBranchNames,
   checkBranchExists,
   getConfigValue,
+  parseConcurrency,
   printSuccess,
   launchInteractiveClaude,
   loadTaskFile,
+  parseTasksFromOptions,
   executeBatchTasks,
+  printDryRunPreview,
 } from '../utils/index.js';
 
 /**
@@ -29,28 +33,32 @@ export function registerRunCommand(program: Command): void {
     .option('--tasks <task...>', '任务列表（可多次指定），不传则在 worktree 中打开 Claude Code 交互式界面')
     .option('-c, --concurrency <n>', '最大并发数，0 表示不限制')
     .option('-f, --file <path>', '从任务文件读取任务列表（与 --tasks 互斥）')
+    .option('-d, --dry-run', '预览模式，仅展示任务计划不实际执行')
     .action(async (options: RunOptions) => {
       await handleRun(options);
     });
 }
 
 /**
- * 解析并发数参数
- * 优先级：命令行参数 > 全局配置 > 默认值 0
- * @param {string | undefined} optionValue - 命令行传入的并发数字符串
- * @param {number} configValue - 全局配置中的默认并发数
- * @returns {number} 解析后的并发数，0 表示不限制
+ * 从任务文件解析出分支名列表
+ * 有 -b 参数时使用自动编号，否则使用文件中每个任务块的独立分支名
+ * @param {RunOptions} options - 命令选项
+ * @param {number} entryCount - 任务条目数量
+ * @param {Array<{branch?: string}>} entries - 解析出的任务条目（含可选分支名）
+ * @returns {string[]} 分支名列表
  */
-function parseConcurrency(optionValue: string | undefined, configValue: number): number {
-  if (optionValue === undefined) {
-    return configValue;
-  }
-
-  const parsed = parseInt(optionValue, 10);
-  if (Number.isNaN(parsed) || parsed < 0) {
-    throw new ClawtError(MESSAGES.CONCURRENCY_INVALID);
+function resolveBranchNamesFromFile(
+  options: RunOptions,
+  entryCount: number,
+  entries: Array<{ branch?: string }>,
+): string[] {
+  if (options.branch) {
+    // 有 -b 参数：忽略文件中的分支名，用 -b 自动编号
+    const sanitized = sanitizeBranchName(options.branch);
+    return generateBranchNames(sanitized, entryCount);
   }
-  return parsed;
+  // 无 -b 参数：使用文件中每个任务的独立分支名
+  return entries.map((e) => sanitizeBranchName(e.branch!));
 }
 
 /**
@@ -85,6 +93,22 @@ async function handleRunFromFile(options: RunOptions): Promise<void> {
   await executeBatchTasks(worktrees, tasks, concurrency);
 }
 
+/**
+ * 处理 dry-run 模式下从任务文件读取的逻辑
+ * @param {RunOptions} options - 命令选项（包含 file 字段）
+ */
+function handleDryRunFromFile(options: RunOptions): void {
+  const branchRequired = !options.branch;
+  const entries = loadTaskFile(options.file!, { branchRequired });
+  printSuccess(MESSAGES.TASK_FILE_LOADED(entries.length, options.file!));
+
+  const tasks = entries.map((e) => e.task);
+  const branchNames = resolveBranchNamesFromFile(options, entries.length, entries);
+  const concurrency = parseConcurrency(options.concurrency, getConfigValue('maxConcurrency'));
+
+  printDryRunPreview(branchNames, tasks, concurrency);
+}
+
 /**
  * 执行 run 命令的核心逻辑
  * 支持三种模式：
@@ -95,13 +119,41 @@ async function handleRunFromFile(options: RunOptions): Promise<void> {
  */
 async function handleRun(options: RunOptions): Promise<void> {
   validateMainWorktree();
-  validateClaudeCodeInstalled();
 
   // 互斥校验：--file 和 --tasks 不能同时使用
   if (options.file && options.tasks) {
     throw new ClawtError(MESSAGES.FILE_AND_TASKS_CONFLICT);
   }
 
+  // dry-run 模式：仅解析和展示任务计划，不实际创建 worktree 或启动 Claude Code
+  if (options.dryRun) {
+    // dry-run 不需要校验 Claude Code 是否安装
+    if (options.file) {
+      return handleDryRunFromFile(options);
+    }
+
+    if (!options.branch) {
+      throw new ClawtError(MESSAGES.BRANCH_OR_FILE_REQUIRED);
+    }
+
+    const sanitized = sanitizeBranchName(options.branch);
+
+    if (!options.tasks || options.tasks.length === 0) {
+      // 交互式模式 dry-run：展示单个 worktree 信息
+      printDryRunPreview([sanitized], [], 0);
+      return;
+    }
+
+    const tasks = parseTasksFromOptions(options.tasks);
+    const branchNames = generateBranchNames(sanitized, tasks.length);
+    const concurrency = parseConcurrency(options.concurrency, getConfigValue('maxConcurrency'));
+    printDryRunPreview(branchNames, tasks, concurrency);
+    return;
+  }
+
+  // 正常执行模式需要校验 Claude Code
+  validateClaudeCodeInstalled();
+
   // --file 模式
   if (options.file) {
     return handleRunFromFile(options);
@@ -128,12 +180,7 @@ async function handleRun(options: RunOptions): Promise<void> {
     return;
   }
 
-  const tasks = options.tasks.map((t) => t.trim()).filter(Boolean);
-
-  if (tasks.length === 0) {
-    throw new ClawtError('任务列表不能为空');
-  }
-
+  const tasks = parseTasksFromOptions(options.tasks);
   const count = tasks.length;
 
   // 解析并发数：命令行参数 > 全局配置 > 默认值 0

package/src/constants/messages/run.ts

@@ -43,4 +43,20 @@ export const RUN_MESSAGES = {
   TASK_FILE_LOADED: (count: number, path: string) => `✓ 从 ${path} 加载了 ${count} 个任务`,
   /** 未指定 -b 或 -f */
   BRANCH_OR_FILE_REQUIRED: '请指定 -b 分支名或 -f 任务文件',
+  /** dry-run 预览标题 */
+  DRY_RUN_TITLE: 'Dry Run 预览',
+  /** dry-run 任务数量 */
+  DRY_RUN_TASK_COUNT: (count: number) => `任务数: ${count}`,
+  /** dry-run 并发数 */
+  DRY_RUN_CONCURRENCY: (concurrency: number) => `并发数: ${concurrency === 0 ? '不限制' : concurrency}`,
+  /** dry-run worktree 目录 */
+  DRY_RUN_WORKTREE_DIR: (dir: string) => `Worktree: ${dir}`,
+  /** dry-run 分支已存在警告 */
+  DRY_RUN_BRANCH_EXISTS_WARNING: (name: string) => `分支 ${name} 已存在`,
+  /** dry-run 交互式模式提示（无任务描述） */
+  DRY_RUN_INTERACTIVE_MODE: '模式: 交互式（无预设任务）',
+  /** dry-run 预览完成且无冲突 */
+  DRY_RUN_READY: '预览完成，无冲突。移除 --dry-run 即可正式执行。',
+  /** dry-run 存在分支冲突 */
+  DRY_RUN_HAS_CONFLICT: '存在分支冲突，实际执行时将会报错。请先处理冲突的分支。',
 } as const;