clawt 2.14.0 → 2.15.0

package/docs/spec.md

@@ -21,7 +21,7 @@
   - [5.7 默认配置文件](#57-默认配置文件)
   - [5.8 获取当前项目所有 Worktree](#58-获取当前项目所有-worktree)
   - [5.9 日志系统](#59-日志系统)
-  - [5.10 查看和管理全局配置](#510-查看和管理全局配置)
+  - [5.10 交互式查看和修改全局配置](#510-交互式查看和修改全局配置)
   - [5.11 在已有 Worktree 中恢复会话](#511-在已有-worktree-中恢复会话)
   - [5.12 将主分支代码同步到目标 Worktree](#512-将主分支代码同步到目标-worktree)
   - [5.13 重置主 Worktree 工作区和暂存区](#513-重置主-worktree-工作区和暂存区)
@@ -174,7 +174,9 @@ git show-ref --verify refs/heads/<branchName> 2>/dev/null
 | `clawt merge`         | 合并某个已验证的 worktree 分支到主 worktree       | 5.6      |
 | `clawt remove`        | 移除 worktree（支持模糊匹配/多选/全部）             | 5.5      |
 | `clawt list`          | 列出当前项目所有 worktree（支持 `--json` 格式输出） | 5.8      |
-| `clawt config`        | 查看全局配置                                     | 5.10     |
+| `clawt config`        | 交互式查看和修改全局配置（等同于 `config set`）      | 5.10     |
+| `clawt config set`    | 修改配置项（无参数进入交互式，有参数直接设置）          | 5.10     |
+| `clawt config get`    | 获取单个配置项的值                                 | 5.10     |
 | `clawt config reset`  | 将配置恢复为默认值                                | 5.10     |
 | `clawt resume`        | 在已有 worktree 中恢复 Claude Code 会话（支持多选批量恢复） | 5.11     |
 | `clawt sync`          | 将主分支最新代码同步到目标 worktree                  | 5.12     |
@@ -276,6 +278,7 @@ clawt run -b <branchName>
 | `--tasks` | 否   | 任务描述（可多次指定，每个 --tasks 对应一个任务，任务数量即 worktree 数量）。不传则在 worktree 中打开 Claude Code 交互式界面 |
 | `-f`      | 否   | 从任务文件读取任务列表（与 `--tasks` 互斥）                    |
 | `-c`      | 否   | 最大并发数，`0` 表示不限制                                    |
+| `--dry-run` | 否 | 试运行模式，仅输出预览信息不实际执行                            |
 
 **互斥约束：**
 
@@ -349,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 任务完成通知机制
@@ -1000,51 +1048,82 @@ clawt validate -b feature-scheme --debug
 
 ---
 
-### 5.10 查看和管理全局配置
+### 5.10 交互式查看和修改全局配置
 
 **命令：**
 
 ```bash
-# 查看全局配置
+# 交互式修改配置（等同于 config set 无参数）
 clawt config
 
+# 修改配置项（无参数进入交互式，有参数直接设置）
+clawt config set [key] [value]
+
+# 获取单个配置项的值
+clawt config get <key>
+
 # 将配置恢复为默认值
 clawt config reset
 ```
 
-#### 查看配置
+#### 交互式修改配置（`config` / `config set`）
+
+直接执行 `clawt config` 或 `clawt config set`（不带参数）进入交互式配置修改模式。
 
 **运行流程：**
 
 1. 读取全局配置文件 `~/.clawt/config.json`
-2. 遍历所有配置项（以 `CONFIG_DEFINITIONS` 为单一数据源），逐项展示：
-   - 配置项名称（粗体）
+2. 列出所有配置项供用户选择（`Enquirer.Select`），每项显示：
+   - 配置项名称
    - 当前值（布尔值绿色/黄色，字符串青色）
    - 配置项描述（灰色）
-3. 输出配置文件路径，提示用户可直接编辑
+   - 对象类型配置项（如 `aliases`）标灰不可选，提示用户通过专用命令管理
+3. 用户选择某个配置项后，根据值类型自动选择提示策略：
+   - **boolean 类型** → `Select`（true / false）
+   - **number 类型** → `Input`（带数字校验）
+   - **string 类型 + 有 `allowedValues`** → `Select`（枚举列表）
+   - **string 类型 + 无 `allowedValues`** → `Input`（自由输入）
+4. 将修改后的配置持久化到配置文件
+5. 输出成功提示：`✓ <key> 已设置为 <value>`
 
-**输出格式：**
+#### 直接设置配置项（`config set <key> <value>`）
 
-```
-配置文件路径: ~/.clawt/config.json
-────────────────────────────────────────
-  autoDeleteBranch: false
-  移除 worktree 时是否自动删除对应本地分支
+当带参数执行 `clawt config set <key> <value>` 时，直接修改指定配置项。
 
-  claudeCodeCommand: claude
-  Claude Code CLI 启动指令
+**参数：**
 
-  autoPullPush: false
-  merge 成功后是否自动执行 git pull 和 git push
+| 参数 | 必填 | 说明 |
+| ---- | ---- | ---- |
+| `key` | 否 | 配置项名称（不传则进入交互式模式） |
+| `value` | 否 | 配置值（传了 `key` 时必填） |
 
-  confirmDestructiveOps: true
-  执行破坏性操作（reset、validate --clean）前是否提示确认
+**运行流程：**
 
-────────────────────────────────────────
+1. 校验 `key` 是否为有效的配置项名称（基于 `DEFAULT_CONFIG` 的键列表），无效则输出错误及可用配置项列表
+2. 校验 `value` 是否缺失，缺失则提示用法：`clawt config set <key> <value>`
+3. 根据目标配置项的类型解析并校验值：
+   - **boolean** → 仅接受 `true` 或 `false`
+   - **number** → `Number()` 解析，`NaN` 报错
+   - **string + 有 `allowedValues`** → 校验值是否在枚举列表中
+   - **string + 无 `allowedValues`** → 无额外校验
+4. 加载配置、修改目标项、持久化
+5. 输出成功提示：`✓ <key> 已设置为 <value>`
 
-```
+#### 获取单个配置项（`config get <key>`）
 
-#### 恢复默认配置
+**参数：**
+
+| 参数 | 必填 | 说明 |
+| ---- | ---- | ---- |
+| `key` | 是 | 配置项名称 |
+
+**运行流程：**
+
+1. 校验 `key` 是否为有效的配置项名称，无效则输出错误及可用配置项列表
+2. 读取配置文件，获取目标配置项的值
+3. 输出：`<key> = <value>`
+
+#### 恢复默认配置（`config reset`）
 
 **运行流程：**
 
@@ -1052,6 +1131,13 @@ clawt config reset
 2. 将默认配置写入 `~/.clawt/config.json`（覆盖现有配置文件）
 3. 输出成功提示：`✓ 配置已恢复为默认值`
 
+**实现要点：**
+
+- 配置项类型定义：`ConfigItemDefinition` 新增可选字段 `allowedValues`（`readonly string[]`），仅对 string 类型有效，用于枚举值校验和交互式 Select 提示
+- 值解析与提示策略：`src/utils/config-strategy.ts` 中的 `parseConfigValue()`（CLI 字符串解析）和 `promptConfigValue()`（交互式提示），基于类型和 `allowedValues` 自动分发
+- `saveConfig(config)`：`src/utils/config.ts` 中新增的通用配置写入函数，将完整配置对象持久化到文件
+- `formatConfigValue(value)`：支持 boolean、string、number、对象类型（如 `aliases`，按键值对逐行展示）的格式化显示
+
 ---
 
 ### 5.11 在已有 Worktree 中恢复会话

package/package.json

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

package/src/commands/config.ts

@@ -1,7 +1,7 @@
 import type { Command } from 'commander';
 import chalk from 'chalk';
 import Enquirer from 'enquirer';
-import { DEFAULT_CONFIG, CONFIG_DESCRIPTIONS, MESSAGES } from '../constants/index.js';
+import { DEFAULT_CONFIG, CONFIG_DESCRIPTIONS, MESSAGES, CONFIG_ALIAS_DISABLED_HINT } from '../constants/index.js';
 import { logger } from '../logger/index.js';
 import {
   loadConfig,
@@ -123,10 +123,15 @@ async function handleInteractiveConfigSet(): Promise<void> {
   logger.info('config set 命令执行，进入交互式配置');
 
   // 构建选择列表，显示配置项名称、当前值和描述
-  const choices = keys.map((k) => ({
-    name: k,
-    message: `${k}: ${formatConfigValue(config[k])}  ${chalk.dim(`— ${CONFIG_DESCRIPTIONS[k]}`)}`,
-  }));
+  // 对象类型配置项（如 aliases）标灰不可选，提示用户通过专用命令管理
+  const choices = keys.map((k) => {
+    const isObject = typeof DEFAULT_CONFIG[k] === 'object';
+    return {
+      name: k,
+      message: `${k}: ${isObject ? chalk.dim(JSON.stringify(config[k])) : formatConfigValue(config[k])}  ${chalk.dim(`— ${CONFIG_DESCRIPTIONS[k]}`)}`,
+      ...(isObject && { disabled: CONFIG_ALIAS_DISABLED_HINT }),
+    };
+  });
 
   // @ts-expect-error enquirer 类型声明未导出 Select 类，但运行时存在
   const selectedKey: keyof ClawtConfig = await new Enquirer.Select({

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/config.ts

@@ -37,7 +37,7 @@ export const CONFIG_DEFINITIONS: ConfigDefinitions = {
   },
   aliases: {
     defaultValue: {} as Record<string, string>,
-    description: '命令别名映射（通过 clawt alias 命令管理）',
+    description: '命令别名映射',
   },
 };
 

package/src/constants/index.ts

@@ -1,6 +1,7 @@
 export { CLAWT_HOME, CONFIG_PATH, LOGS_DIR, WORKTREES_DIR, VALIDATE_SNAPSHOTS_DIR, CLAUDE_PROJECTS_DIR } from './paths.js';
 export { INVALID_BRANCH_CHARS } from './branch.js';
 export { MESSAGES } from './messages/index.js';
+export { CONFIG_ALIAS_DISABLED_HINT } from './messages/index.js';
 export { EXIT_CODES } from './exitCodes.js';
 export { ENABLE_BRACKETED_PASTE, DISABLE_BRACKETED_PASTE, PASTE_THRESHOLD_MS, VALID_TERMINAL_APPS, ITERM2_APP_PATH } from './terminal.js';
 export { DEFAULT_CONFIG, CONFIG_DESCRIPTIONS, CONFIG_DEFINITIONS, APPEND_SYSTEM_PROMPT } from './config.js';

package/src/constants/messages/config.ts

@@ -1,3 +1,6 @@
+/** 对象类型配置项禁用提示（如 aliases 需通过专用命令管理） */
+export const CONFIG_ALIAS_DISABLED_HINT = '(通过 clawt alias 命令管理)';
+
 /** config 命令专属提示消息 */
 export const CONFIG_CMD_MESSAGES = {
   /** 配置已恢复为默认值 */

package/src/constants/messages/index.ts

@@ -7,7 +7,9 @@ import { SYNC_MESSAGES } from './sync.js';
 import { RESUME_MESSAGES } from './resume.js';
 import { REMOVE_MESSAGES } from './remove.js';
 import { RESET_MESSAGES } from './reset.js';
-import { CONFIG_CMD_MESSAGES } from './config.js';
+import { CONFIG_CMD_MESSAGES, CONFIG_ALIAS_DISABLED_HINT } from './config.js';
+
+export { CONFIG_ALIAS_DISABLED_HINT };
 import { STATUS_MESSAGES } from './status.js';
 import { ALIAS_MESSAGES } from './alias.js';
 

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;

package/src/types/command.ts

@@ -16,6 +16,8 @@ export interface RunOptions {
   concurrency?: string;
   /** 任务文件路径（与 --tasks 互斥） */
   file?: string;
+  /** 预览模式，仅展示任务计划不实际执行 */
+  dryRun?: boolean;
 }
 
 /** validate 命令选项 */

package/src/utils/config.ts

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { CONFIG_PATH, CLAWT_HOME, LOGS_DIR, WORKTREES_DIR, DEFAULT_CONFIG, MESSAGES } from '../constants/index.js';
+import { ClawtError } from '../errors/index.js';
 import { ensureDir } from './fs.js';
 import { logger } from '../logger/index.js';
 import type { ClawtConfig } from '../types/index.js';
@@ -65,3 +66,22 @@ export function ensureClawtDirs(): void {
   ensureDir(LOGS_DIR);
   ensureDir(WORKTREES_DIR);
 }
+
+/**
+ * 解析并发数参数
+ * 优先级：命令行参数 > 全局配置 > 默认值 0
+ * @param {string | undefined} optionValue - 命令行传入的并发数字符串
+ * @param {number} configValue - 全局配置中的默认并发数
+ * @returns {number} 解析后的并发数，0 表示不限制
+ */
+export 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);
+  }
+  return parsed;
+}

package/src/utils/dry-run.ts

@@ -0,0 +1,89 @@
+import chalk from 'chalk';
+import { join } from 'node:path';
+import { MESSAGES } from '../constants/index.js';
+import { checkBranchExists } from './git.js';
+import { getProjectWorktreeDir } from './worktree.js';
+import { printInfo, printDoubleSeparator, printSeparator } from './formatter.js';
+
+/** dry-run 模式下任务描述的最大显示长度 */
+const DRY_RUN_TASK_DESC_MAX_LENGTH = 70;
+
+/**
+ * 截取任务描述，超出最大长度时末尾加省略号
+ * 多行内容会被合并为单行显示
+ * @param {string} task - 原始任务描述
+ * @returns {string} 截取后的任务描述
+ */
+export function truncateTaskDesc(task: string): string {
+  // 将换行替换为空格，保证单行显示
+  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) + '...';
+}
+
+/**
+ * 输出 dry-run 预览信息，展示将要创建的 worktree 列表和任务摘要
+ * @param {string[]} branchNames - 分支名列表
+ * @param {string[]} tasks - 任务描述列表（与 branchNames 等长，交互式模式可为空数组）
+ * @param {number} concurrency - 并发数
+ */
+export function printDryRunPreview(branchNames: string[], tasks: string[], concurrency: number): void {
+  const projectDir = getProjectWorktreeDir();
+  const isInteractive = tasks.length === 0;
+
+  // 标题区
+  printDoubleSeparator();
+  printInfo(`  ${chalk.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(chalk.gray(' │ ')));
+
+  printSeparator();
+
+  // 逐个展示 worktree 信息
+  let hasConflict = false;
+  for (let i = 0; i < branchNames.length; i++) {
+    const branch = branchNames[i];
+    const worktreePath = join(projectDir, branch);
+    const exists = checkBranchExists(branch);
+
+    if (exists) hasConflict = true;
+
+    // 序号行：正常用绿色 ✓，冲突用黄色 ⚠ + 警告文本
+    const indexLabel = `[${i + 1}/${branchNames.length}]`;
+    if (exists) {
+      printInfo(`${chalk.yellow('⚠')} ${indexLabel} ${chalk.yellow(branch)} ${chalk.gray('—')} ${chalk.yellow(MESSAGES.DRY_RUN_BRANCH_EXISTS_WARNING(branch))}`);
+    } else {
+      printInfo(`${chalk.green('✓')} ${indexLabel} ${chalk.cyan(branch)}`);
+    }
+
+    // 路径行（2空格缩进）
+    printInfo(`  ${chalk.gray('路径:')} ${worktreePath}`);
+
+    // 任务描述行（2空格缩进，非交互式模式）
+    if (!isInteractive) {
+      printInfo(`  ${chalk.gray('任务:')} ${truncateTaskDesc(tasks[i])}`);
+    }
+
+    printInfo('');
+  }
+
+  // 结尾
+  printDoubleSeparator();
+  if (hasConflict) {
+    printInfo(chalk.yellow(`⚠ ${MESSAGES.DRY_RUN_HAS_CONFLICT}`));
+  } else {
+    printInfo(chalk.green(`✓ ${MESSAGES.DRY_RUN_READY}`));
+  }
+}

package/src/utils/index.ts

@@ -48,7 +48,7 @@ export {
 export { sanitizeBranchName, generateBranchNames, validateBranchesNotExist } from './branch.js';
 export { validateMainWorktree, validateGitInstalled, validateClaudeCodeInstalled } from './validation.js';
 export { createWorktrees, getProjectWorktrees, getProjectWorktreeDir, cleanupWorktrees, getWorktreeStatus, createWorktreesByBranches } from './worktree.js';
-export { loadConfig, writeDefaultConfig, writeConfig, saveConfig, getConfigValue, ensureClawtDirs } from './config.js';
+export { loadConfig, writeDefaultConfig, writeConfig, saveConfig, getConfigValue, ensureClawtDirs, parseConcurrency } from './config.js';
 export { printSuccess, printError, printWarning, printInfo, printSeparator, printDoubleSeparator, confirmAction, confirmDestructiveAction, formatWorktreeStatus, isWorktreeIdle, formatDuration } from './formatter.js';
 export { ensureDir, removeEmptyDir } from './fs.js';
 export { multilineInput } from './prompt.js';
@@ -57,9 +57,10 @@ export { getSnapshotPath, hasSnapshot, readSnapshotTreeHash, readSnapshot, write
 export { findExactMatch, findFuzzyMatches, promptSelectBranch, promptMultiSelectBranches, resolveTargetWorktree, resolveTargetWorktrees } from './worktree-matcher.js';
 export type { WorktreeResolveMessages, WorktreeMultiResolveMessages } from './worktree-matcher.js';
 export { ProgressRenderer } from './progress.js';
-export { parseTaskFile, loadTaskFile } from './task-file.js';
+export { parseTaskFile, loadTaskFile, parseTasksFromOptions } from './task-file.js';
 export { executeBatchTasks } from './task-executor.js';
 export { detectTerminalApp, openCommandInNewTerminalTab } from './terminal.js';
+export { truncateTaskDesc, printDryRunPreview } from './dry-run.js';
 export { applyAliases } from './alias.js';
 export { isValidConfigKey, getValidConfigKeys, parseConfigValue, promptConfigValue, formatConfigValue } from './config-strategy.js';
 

package/src/utils/task-file.ts

@@ -10,6 +10,24 @@ const TASK_BLOCK_REGEX = /<!-- CLAWT-TASKS:START -->([\s\S]*?)<!-- CLAWT-TASKS:E
 /** 匹配分支名行的正则：# branch: <name> */
 const BRANCH_LINE_REGEX = /^#\s*branch:\s*(.+)$/;
 
+/** 任务列表为空时的错误提示 */
+const EMPTY_TASKS_MESSAGE = '任务列表不能为空';
+
+/**
+ * 从命令行 --tasks 选项中解析出有效的任务列表
+ * 去除首尾空白并过滤空字符串，结果为空时抛出错误
+ * @param {string[]} rawTasks - 原始任务字符串数组
+ * @returns {string[]} 过滤后的有效任务列表
+ * @throws {ClawtError} 任务列表为空时抛出
+ */
+export function parseTasksFromOptions(rawTasks: string[]): string[] {
+  const tasks = rawTasks.map((t) => t.trim()).filter(Boolean);
+  if (tasks.length === 0) {
+    throw new ClawtError(EMPTY_TASKS_MESSAGE);
+  }
+  return tasks;
+}
+
 /**
  * 解析任务文件内容，提取所有任务块
  * 每个块内 `# branch: <name>` 为分支名，其余行为任务描述