clawt 2.10.1 → 2.11.1

package/dist/postinstall.js

@@ -9,6 +9,7 @@ var CONFIG_PATH = join(CLAWT_HOME, "config.json");
 var LOGS_DIR = join(CLAWT_HOME, "logs");
 var WORKTREES_DIR = join(CLAWT_HOME, "worktrees");
 var VALIDATE_SNAPSHOTS_DIR = join(CLAWT_HOME, "validate-snapshots");
+var CLAUDE_PROJECTS_DIR = join(homedir(), ".claude", "projects");
 
 // src/constants/messages/common.ts
 var COMMON_MESSAGES = {
@@ -63,7 +64,33 @@ var RUN_MESSAGES = {
   /** 中断后清理完成 */
   INTERRUPT_CLEANED: (count) => `\u2713 \u5DF2\u6E05\u7406 ${count} \u4E2A worktree \u548C\u5BF9\u5E94\u5206\u652F`,
   /** 中断后保留 worktree */
-  INTERRUPT_KEPT: "\u5DF2\u4FDD\u7559 worktree\uFF0C\u53EF\u7A0D\u540E\u4F7F\u7528 clawt remove \u624B\u52A8\u6E05\u7406"
+  INTERRUPT_KEPT: "\u5DF2\u4FDD\u7559 worktree\uFF0C\u53EF\u7A0D\u540E\u4F7F\u7528 clawt remove \u624B\u52A8\u6E05\u7406",
+  /** 非 TTY 环境降级输出：任务启动 */
+  PROGRESS_TASK_STARTED: (index, total, branch, path) => `[${index}/${total}] ${branch} \u542F\u52A8  ${path}`,
+  /** 非 TTY 环境降级输出：任务完成 */
+  PROGRESS_TASK_DONE: (index, total, branch, duration, cost, path) => `[${index}/${total}] ${branch} \u2713 \u5B8C\u6210 ${duration} ${cost}  ${path}`,
+  /** 非 TTY 环境降级输出：任务失败 */
+  PROGRESS_TASK_FAILED: (index, total, branch, duration, path) => `[${index}/${total}] ${branch} \u2717 \u5931\u8D25 ${duration}  ${path}`,
+  /** 并发限制提示 */
+  CONCURRENCY_INFO: (concurrency, total) => `\u5E76\u53D1\u9650\u5236: ${concurrency}\uFF0C\u5171 ${total} \u4E2A\u4EFB\u52A1`,
+  /** 并发数无效提示 */
+  CONCURRENCY_INVALID: "\u5E76\u53D1\u6570\u5FC5\u987B\u4E3A\u6B63\u6574\u6570",
+  /** 任务文件不存在 */
+  TASK_FILE_NOT_FOUND: (path) => `\u4EFB\u52A1\u6587\u4EF6\u4E0D\u5B58\u5728: ${path}`,
+  /** 任务文件中没有解析到有效任务 */
+  TASK_FILE_EMPTY: "\u4EFB\u52A1\u6587\u4EF6\u4E2D\u6CA1\u6709\u89E3\u6790\u5230\u6709\u6548\u4EFB\u52A1",
+  /** 任务文件中某个任务块缺少分支名 */
+  TASK_FILE_MISSING_BRANCH: (blockIndex) => `\u4EFB\u52A1\u6587\u4EF6\u7B2C ${blockIndex} \u4E2A\u4EFB\u52A1\u5757\u7F3A\u5C11\u5206\u652F\u540D\uFF08# branch: ...\uFF09`,
+  /** 任务文件中某个任务块缺少任务描述 */
+  TASK_FILE_MISSING_TASK: (branch) => `\u4EFB\u52A1\u6587\u4EF6\u4E2D\u5206\u652F ${branch} \u7F3A\u5C11\u4EFB\u52A1\u63CF\u8FF0`,
+  /** 任务文件中某个任务块缺少任务描述（无分支名时按索引定位） */
+  TASK_FILE_MISSING_TASK_BY_INDEX: (blockIndex) => `\u4EFB\u52A1\u6587\u4EF6\u7B2C ${blockIndex} \u4E2A\u4EFB\u52A1\u5757\u7F3A\u5C11\u4EFB\u52A1\u63CF\u8FF0`,
+  /** --file 和 --tasks 不能同时使用 */
+  FILE_AND_TASKS_CONFLICT: "--file \u548C --tasks \u4E0D\u80FD\u540C\u65F6\u4F7F\u7528",
+  /** 任务文件加载成功 */
+  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"
 };
 
 // src/constants/messages/create.ts
@@ -269,6 +296,10 @@ var CONFIG_DEFINITIONS = {
   confirmDestructiveOps: {
     defaultValue: true,
     description: "\u6267\u884C\u7834\u574F\u6027\u64CD\u4F5C\uFF08reset\u3001validate --clean\uFF09\u524D\u662F\u5426\u63D0\u793A\u786E\u8BA4"
+  },
+  maxConcurrency: {
+    defaultValue: 0,
+    description: "run \u547D\u4EE4\u9ED8\u8BA4\u6700\u5927\u5E76\u53D1\u6570\uFF0C0 \u8868\u793A\u4E0D\u9650\u5236"
   }
 };
 function deriveDefaultConfig(definitions) {

package/docs/spec.md

@@ -168,7 +168,7 @@ git show-ref --verify refs/heads/<branchName> 2>/dev/null
 | 命令                  | 说明                                           | 对应场景 |
 | --------------------- | ---------------------------------------------- | -------- |
 | `clawt create`        | 批量创建 worktree 及对应分支                     | 5.1      |
-| `clawt run`           | 批量创建 worktree + 启动 Claude Code 执行任务    | 5.2      |
+| `clawt run`           | 批量创建 worktree + 启动 Claude Code 执行任务（支持任务文件）    | 5.2      |
 | `clawt validate`      | 在主 worktree 验证某个 worktree 分支的变更        | 5.4      |
 | `clawt merge`         | 合并某个已验证的 worktree 分支到主 worktree       | 5.6      |
 | `clawt remove`        | 移除 worktree（支持模糊匹配/多选/全部）             | 5.5      |
@@ -259,7 +259,10 @@ clawt create -b <branchName> [-n <count>]
 # 方式一：通过 --tasks 参数直接指定任务（多任务并行）
 clawt run -b <branchName> --tasks <task1> --tasks <task2> --tasks <task3>
 
-# 方式二：不传 --tasks，在 worktree 中打开 Claude Code 交互式界面
+# 方式二：通过 -f 从任务文件读取任务列表
+clawt run -f <path>
+
+# 方式三：不传 --tasks 也不传 -f，在 worktree 中打开 Claude Code 交互式界面
 clawt run -b <branchName>
 ```
 
@@ -267,21 +270,67 @@ clawt run -b <branchName>
 
 | 参数      | 必填 | 说明                                                        |
 | --------- | ---- | ----------------------------------------------------------- |
-| `-b`      | 是   | 分支名                                                      |
+| `-b`      | 否   | 分支名（使用 `-f` 时可选，否则必填）                          |
 | `--tasks` | 否   | 任务描述（可多次指定，每个 --tasks 对应一个任务，任务数量即 worktree 数量）。不传则在 worktree 中打开 Claude Code 交互式界面 |
+| `-f`      | 否   | 从任务文件读取任务列表（与 `--tasks` 互斥）                    |
+| `-c`      | 否   | 最大并发数，`0` 表示不限制                                    |
+
+**互斥约束：**
+
+- `--file` 和 `--tasks` **不能同时使用**
+- 非 `-f` 模式必须指定 `-b`
 
 **交互式 Claude Code 界面模式：**
 
-当不传 `--tasks` 时，会创建单个 worktree，然后通过 `spawnSync` + `inherit stdio` 在该 worktree 中直接启动 Claude Code CLI 交互式界面，让用户与 Claude Code 直接交互。
+当不传 `--tasks` 也不传 `-f` 时，会创建单个 worktree，然后通过 `spawnSync` + `inherit stdio` 在该 worktree 中直接启动 Claude Code CLI 交互式界面，让用户与 Claude Code 直接交互。
 
 启动命令通过配置项 `claudeCodeCommand`（默认值 `claude`）指定，支持自定义命令及参数。
 
-**运行流程：**
+#### 任务文件格式
+
+任务文件使用 Markdown 文件中嵌入 HTML 注释标签的自定义格式，标签外的任何文本都不会被解析。
+
+```markdown
+这里可以写任何说明文字，会被忽略
+
+<!-- CLAWT-TASKS:START -->
+# branch: feat-login
+实现用户登录功能
+<!-- CLAWT-TASKS:END -->
+
+<!-- CLAWT-TASKS:START -->
+# branch: fix-bug
+修复内存泄漏问题
+这是多行任务描述
+可以写很多行
+<!-- CLAWT-TASKS:END -->
+```
+
+**格式规则：**
+
+1. **任务块界定**：每个任务用 `<!-- CLAWT-TASKS:START -->` 和 `<!-- CLAWT-TASKS:END -->` 包裹
+2. **分支名声明**：块内必须有一行 `# branch: <分支名>`（冒号前后的空格可灵活）
+3. **任务描述**：块内除分支名行以外的所有行，合并为任务描述（支持多行）
+4. **块外内容忽略**：标签外的任何文本都不会被解析
+5. **必填校验**：每个块必须包含任务描述；分支名默认必填，但使用 `-b` 参数时分支名为可选（会被忽略，用 `-b` 值自动编号）
+
+**解析实现：** `src/utils/task-file.ts` 中的 `parseTaskFile()` 和 `loadTaskFile()` 函数，类型定义为 `TaskFileEntry`（`src/types/taskFile.ts`）。
+
+#### 任务文件模式运行流程
+
+使用 `-f` 时的执行路径（`handleRun` → `handleRunFromFile`）：
+
+1. 调用 `loadTaskFile(options.file)` 读取解析文件
+2. **有 `-b` 参数**：忽略文件中的分支名，用 `-b` 值自动编号创建 worktree（`createWorktrees(branch, count)`）
+3. **无 `-b` 参数**：使用文件中每个任务的独立分支名，先 `sanitizeBranchName` 清理后调用 `createWorktreesByBranches(branches)`
+4. 调用 `executeBatchTasks(worktrees, tasks, concurrency)` 执行
+
+#### --tasks 模式运行流程
 
 1. 若传了 `--tasks`，解析得到任务数组 `tasks[]`；若未传，先检测分支是否已存在（已存在则提示使用 `clawt resume -b <branchName>` 恢复会话），然后创建单个 worktree 并启动 Claude Code 交互式界面（流程结束，不进入后续并行执行阶段）
 2. `n = tasks.length`
 3. 按照 **5.1** 的流程创建 `n` 个 worktree
-4. 对每个 worktree 并行启动 Claude Code CLI：
+4. 通过公共函数 `executeBatchTasks`（`src/utils/task-executor.ts`）启动批量任务执行，该函数负责进度面板渲染、SIGINT 中断处理、并发控制和汇总输出。对每个 worktree 并行启动 Claude Code CLI：
    ```bash
    cd ~/.clawt/worktrees/<project>/<branchName>-<i>
    claude -p "<tasks[i]>" --output-format json --permission-mode bypassPermissions
@@ -329,7 +378,7 @@ Claude Code CLI 以 `--output-format json` 运行时，退出后会在 stdout
 1. 为每个 Claude Code 子进程维护状态（运行中 / 已完成 / 已失败）
 2. 监听每个子进程的 `close` 事件（基于 Node.js `ChildProcess` 的事件驱动机制）
 3. 当某个子进程触发 `close` 事件时，解析其 stdout 输出的 JSON
-4. 在主 worktree 的 clawt 终端实时输出通知：
+4. 在主 worktree 的 clawt 终端实时输出通知（进度面板每个任务行末尾显示 worktree 路径，终端可点击跳转）：
 
 ```
 ✓ [完成] worktree: ~/.clawt/worktrees/main-project/feature-scheme-1
@@ -1039,6 +1088,8 @@ clawt resume
 
 启动命令通过配置项 `claudeCodeCommand`（默认值 `claude`）指定，与 `clawt run` 不传 `--tasks` 时的交互式界面行为一致。
 
+**会话自动续接：** 启动前会自动检测该 worktree 是否存在 Claude Code 历史会话（通过检查 `~/.claude/projects/<encoded-path>/` 下是否有 `.jsonl` 文件判断），如果存在则自动追加 `--continue` 参数继续上次对话，否则打开新对话。启动信息中会显示当前模式（"继续上次对话"或"新对话"）。路径编码规则：将绝对路径中所有非字母数字字符替换为 `-`（与 Claude Code 源码的编码逻辑一致）。
+
 ---
 
 ### 5.12 将主分支代码同步到目标 Worktree
@@ -1316,7 +1367,7 @@ clawt status [--json]
 - 测试辅助文件：
   - `tests/helpers/setup.ts`：全局 setup，禁用 chalk 颜色输出避免 ANSI 转义码干扰断言
   - `tests/helpers/fixtures.ts`：测试数据工厂，提供 `createWorktreeInfo()`、`createWorktreeStatus()`、`createWorktreeList()` 等工厂函数
-- 覆盖范围：`src/` 下的 `utils/`、`errors/`、`constants/` 全部关键模块，共 12 个测试文件、163 个测试用例
+- 覆盖范围：`src/` 下的 `commands/`、`utils/`、`errors/`、`constants/` 全部关键模块
 - 覆盖率统计排除项：`src/index.ts`（入口文件）、`src/types/**`（类型定义）、`src/logger/**`（日志模块）
 - npm 脚本：
   - `npm test`：执行全部测试（`vitest run`）

package/package.json

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

package/src/commands/resume.ts

@@ -48,6 +48,6 @@ async function handleResume(options: ResumeOptions): Promise<void> {
   const worktrees = getProjectWorktrees();
   const worktree = await resolveTargetWorktree(worktrees, RESUME_RESOLVE_MESSAGES, options.branch);
 
-  // 启动 Claude Code 交互式界面
-  launchInteractiveClaude(worktree);
+  // 启动 Claude Code 交互式界面（resume 自动续接历史会话）
+  launchInteractiveClaude(worktree, { autoContinue: true });
 }

package/src/commands/run.ts

@@ -1,27 +1,20 @@
 import type { Command } from 'commander';
-import type { ChildProcess } from 'node:child_process';
 import { logger } from '../logger/index.js';
 import { ClawtError } from '../errors/index.js';
 import { MESSAGES } from '../constants/index.js';
-import type { RunOptions, ClaudeCodeResult, TaskResult, TaskSummary, WorktreeInfo } from '../types/index.js';
+import type { RunOptions, WorktreeInfo } from '../types/index.js';
 import {
   validateMainWorktree,
   validateClaudeCodeInstalled,
   createWorktrees,
+  createWorktreesByBranches,
   sanitizeBranchName,
   checkBranchExists,
-  spawnProcess,
-  killAllChildProcesses,
-  cleanupWorktrees,
   getConfigValue,
   printSuccess,
-  printError,
-  printWarning,
-  printInfo,
-  printSeparator,
-  printDoubleSeparator,
-  confirmAction,
   launchInteractiveClaude,
+  loadTaskFile,
+  executeBatchTasks,
 } from '../utils/index.js';
 
 /**
@@ -32,165 +25,93 @@ export function registerRunCommand(program: Command): void {
   program
     .command('run')
     .description('批量创建 worktree 并启动 Claude Code 执行任务')
-    .requiredOption('-b, --branch <branchName>', '分支名')
+    .option('-b, --branch <branchName>', '分支名')
     .option('--tasks <task...>', '任务列表（可多次指定），不传则在 worktree 中打开 Claude Code 交互式界面')
+    .option('-c, --concurrency <n>', '最大并发数，0 表示不限制')
+    .option('-f, --file <path>', '从任务文件读取任务列表（与 --tasks 互斥）')
     .action(async (options: RunOptions) => {
       await handleRun(options);
     });
 }
 
-/** executeClaudeTask 的返回结构，包含子进程引用和结果 Promise */
-interface ClaudeTaskHandle {
-  /** 子进程实例，用于在中断时终止 */
-  child: ChildProcess;
-  /** 任务结果 Promise */
-  promise: Promise<TaskResult>;
-}
-
 /**
- * 在指定 worktree 中执行 Claude Code 任务，由于是--output-format json形式，所以这里固定claude code cli的启动命令
- * @param {WorktreeInfo} worktree - worktree 信息
- * @param {string} task - 任务描述
- * @returns {ClaudeTaskHandle} 包含子进程引用和结果 Promise
+ * 解析并发数参数
+ * 优先级：命令行参数 > 全局配置 > 默认值 0
+ * @param {string | undefined} optionValue - 命令行传入的并发数字符串
+ * @param {number} configValue - 全局配置中的默认并发数
+ * @returns {number} 解析后的并发数，0 表示不限制
  */
-function executeClaudeTask(worktree: WorktreeInfo, task: string): ClaudeTaskHandle {
-  const child = spawnProcess(
-    'claude',
-    ['-p', task, '--output-format', 'json', '--permission-mode', 'bypassPermissions'],
-    {
-      cwd: worktree.path,
-      // stdin 必须设置为 'ignore'，不能用 'pipe'
-      // 原因：claude -p 是非交互模式，不需要 stdin 输入。如果 stdin 为 'pipe'，
-      // 父进程会创建一个可写流连接到子进程但从不写入也不关闭，
-      // claude 检测到 stdin 是管道后会尝试读取输入，导致进程永远卡住
-      stdio: ['ignore', 'pipe', 'pipe'],
-    },
-  );
-
-  const promise = new Promise<TaskResult>((resolve) => {
-    let stdout = '';
-    let stderr = '';
-
-    child.stdout?.on('data', (data: Buffer) => {
-      stdout += data.toString();
-    });
-
-    child.stderr?.on('data', (data: Buffer) => {
-      stderr += data.toString();
-    });
-
-    child.on('close', (code) => {
-      let result: ClaudeCodeResult | null = null;
-      let success = code === 0;
-
-      try {
-        if (stdout.trim()) {
-          result = JSON.parse(stdout.trim()) as ClaudeCodeResult;
-          success = !result.is_error;
-        }
-      } catch {
-        logger.warn(`解析 Claude Code 输出失败: ${stdout.substring(0, 200)}`);
-      }
-
-      resolve({
-        task,
-        branch: worktree.branch,
-        worktreePath: worktree.path,
-        success,
-        result,
-        error: success ? undefined : stderr || '任务执行失败',
-      });
-    });
-
-    child.on('error', (err) => {
-      resolve({
-        task,
-        branch: worktree.branch,
-        worktreePath: worktree.path,
-        success: false,
-        result: null,
-        error: err.message,
-      });
-    });
-  });
-
-  return { child, promise };
-}
-
-/**
- * 输出单个任务完成通知
- * @param {TaskResult} taskResult - 任务结果
- */
-function printTaskNotification(taskResult: TaskResult): void {
-  const { success, worktreePath, branch, result } = taskResult;
-  const status = success ? '完成' : '失败';
-  const icon = success ? '✓' : '✗';
-  const durationStr = result ? `${(result.duration_ms / 1000).toFixed(1)}s` : 'N/A';
-  const costStr = result ? `$${result.total_cost_usd.toFixed(2)}` : 'N/A';
-  const resultStr = success ? 'success' : 'failed';
-
-  if (success) {
-    printSuccess(`${icon} [${status}] worktree: ${worktreePath}`);
-  } else {
-    printError(`${icon} [${status}] worktree: ${worktreePath}`);
+function parseConcurrency(optionValue: string | undefined, configValue: number): number {
+  if (optionValue === undefined) {
+    return configValue;
   }
-  printInfo(`  分支: ${branch}`);
-  printInfo(`  耗时: ${durationStr}`);
-  printInfo(`  花费: ${costStr}`);
-  printInfo(`  结果: ${resultStr}`);
-  printSeparator();
-}
 
-/**
- * 输出所有任务的汇总信息
- * @param {TaskSummary} summary - 汇总信息
- */
-function printTaskSummary(summary: TaskSummary): void {
-  printDoubleSeparator();
-  printInfo(`全部任务已完成 (${summary.total}/${summary.total})`);
-  printInfo(`  成功: ${summary.succeeded}`);
-  printInfo(`  失败: ${summary.failed}`);
-  printInfo(`  总耗时: ${(summary.totalDurationMs / 1000).toFixed(1)}s`);
-  printInfo(`  总花费: $${summary.totalCostUsd.toFixed(2)}`);
-  printDoubleSeparator();
+  const parsed = parseInt(optionValue, 10);
+  if (Number.isNaN(parsed) || parsed < 0) {
+    throw new ClawtError(MESSAGES.CONCURRENCY_INVALID);
+  }
+  return parsed;
 }
 
 /**
- * 处理用户中断（Ctrl+C）后的清理流程
- * 根据全局配置决定自动清理或交互式确认
- * @param {WorktreeInfo[]} worktrees - 本次创建的 worktree 列表
+ * 处理从任务文件执行的逻辑
+ * @param {RunOptions} options - 命令选项（包含 file 字段）
  */
-async function handleInterruptCleanup(worktrees: WorktreeInfo[]): Promise<void> {
-  const autoDelete = getConfigValue('autoDeleteBranch');
+async function handleRunFromFile(options: RunOptions): Promise<void> {
+  // 有 -b 参数时，文件中的分支名为可选
+  const branchRequired = !options.branch;
+  // 加载并解析任务文件
+  const entries = loadTaskFile(options.file!, { branchRequired });
+  printSuccess(MESSAGES.TASK_FILE_LOADED(entries.length, options.file!));
 
-  if (autoDelete) {
-    // 全局配置了自动删除，直接清理
-    cleanupWorktrees(worktrees);
-    printSuccess(MESSAGES.INTERRUPT_AUTO_CLEANED(worktrees.length));
-    return;
-  }
+  const tasks = entries.map((e) => e.task);
 
-  // 交互式确认是否清理
-  const shouldClean = await confirmAction(MESSAGES.INTERRUPT_CONFIRM_CLEANUP);
+  let worktrees: WorktreeInfo[];
 
-  if (shouldClean) {
-    cleanupWorktrees(worktrees);
-    printSuccess(MESSAGES.INTERRUPT_CLEANED(worktrees.length));
+  if (options.branch) {
+    // 有 -b 参数：忽略文件中的分支名，用 -b 自动编号
+    worktrees = createWorktrees(options.branch, entries.length);
   } else {
-    printInfo(MESSAGES.INTERRUPT_KEPT);
+    // 无 -b 参数：使用文件中每个任务的独立分支名
+    const branches = entries.map((e) => sanitizeBranchName(e.branch!));
+    worktrees = createWorktreesByBranches(branches);
   }
+
+  // 解析并发数
+  const concurrency = parseConcurrency(options.concurrency, getConfigValue('maxConcurrency'));
+
+  logger.info(`run 命令（文件模式）执行，任务数: ${entries.length}，并发数: ${concurrency || '不限制'}`);
+
+  await executeBatchTasks(worktrees, tasks, concurrency);
 }
 
 /**
  * 执行 run 命令的核心逻辑
- * 不传 --tasks 时创建单个 worktree 并打开 Claude Code 交互式界面
- * 传 --tasks 时批量创建 worktree 并并行执行任务
+ * 支持三种模式：
+ * 1. -f 任务文件模式
+ * 2. --tasks 命令行任务模式
+ * 3. 无任务参数时打开交互式界面
  * @param {RunOptions} options - 命令选项
  */
 async function handleRun(options: RunOptions): Promise<void> {
   validateMainWorktree();
   validateClaudeCodeInstalled();
 
+  // 互斥校验：--file 和 --tasks 不能同时使用
+  if (options.file && options.tasks) {
+    throw new ClawtError(MESSAGES.FILE_AND_TASKS_CONFLICT);
+  }
+
+  // --file 模式
+  if (options.file) {
+    return handleRunFromFile(options);
+  }
+
+  // 非 --file 模式必须指定 -b
+  if (!options.branch) {
+    throw new ClawtError(MESSAGES.BRANCH_OR_FILE_REQUIRED);
+  }
+
   // 未传 --tasks 时，创建单个 worktree 并打开 Claude Code 交互式界面
   if (!options.tasks || options.tasks.length === 0) {
     // 分支已存在时，提示用户使用 resume 恢复会话
@@ -214,73 +135,14 @@ async function handleRun(options: RunOptions): Promise<void> {
   }
 
   const count = tasks.length;
-  logger.info(`run 命令执行，分支: ${options.branch}，任务数: ${count}`);
 
-  // 创建 worktree
-  const worktrees = createWorktrees(options.branch, count);
-  printSuccess(MESSAGES.WORKTREE_CREATED(worktrees.length));
-  for (const wt of worktrees) {
-    printInfo(`  分支: ${wt.branch}  路径: ${wt.path}`);
-  }
-  printInfo('');
+  // 解析并发数：命令行参数 > 全局配置 > 默认值 0
+  const concurrency = parseConcurrency(options.concurrency, getConfigValue('maxConcurrency'));
 
-  // 并行执行 Claude Code 任务，每个完成时实时通知
-  const startTime = Date.now();
-  const handles = worktrees.map((wt, index) => {
-    const task = tasks[index];
-    logger.info(`启动任务 ${index + 1}: ${task} (worktree: ${wt.path})`);
-    return executeClaudeTask(wt, task);
-  });
+  logger.info(`run 命令执行，分支: ${options.branch}，任务数: ${count}，并发数: ${concurrency || '不限制'}`);
 
-  // 收集所有子进程引用，用于中断时终止
-  const childProcesses = handles.map((h) => h.child);
-
-  // 监听 SIGINT（Ctrl+C），终止所有子进程并触发清理流程
-  let interrupted = false;
-  const sigintHandler = async () => {
-    if (interrupted) return;
-    interrupted = true;
-
-    printInfo('');
-    printWarning(MESSAGES.INTERRUPTED);
-    killAllChildProcesses(childProcesses);
-
-    // 等待所有子进程退出后再执行清理
-    await Promise.allSettled(handles.map((h) => h.promise));
-
-    await handleInterruptCleanup(worktrees);
-    process.exit(1);
-  };
-  process.on('SIGINT', sigintHandler);
-
-  const taskPromises = handles.map((handle) =>
-    handle.promise.then((result) => {
-      // 被中断时不再输出通知
-      if (!interrupted) {
-        printTaskNotification(result);
-      }
-      return result;
-    }),
-  );
-
-  const results = await Promise.all(taskPromises);
-
-  // 正常完成，移除 SIGINT 监听器
-  process.removeListener('SIGINT', sigintHandler);
-
-  // 被中断时不输出汇总（已在 sigintHandler 中处理退出）
-  if (interrupted) return;
-
-  const totalDurationMs = Date.now() - startTime;
-
-  // 汇总
-  const summary: TaskSummary = {
-    total: results.length,
-    succeeded: results.filter((r) => r.success).length,
-    failed: results.filter((r) => !r.success).length,
-    totalDurationMs,
-    totalCostUsd: results.reduce((sum, r) => sum + (r.result?.total_cost_usd ?? 0), 0),
-  };
+  // 创建 worktree
+  const worktrees = createWorktrees(options.branch, count);
 
-  printTaskSummary(summary);
+  await executeBatchTasks(worktrees, tasks, concurrency);
 }

package/src/constants/config.ts

@@ -25,6 +25,10 @@ export const CONFIG_DEFINITIONS: ConfigDefinitions = {
     defaultValue: true,
     description: '执行破坏性操作（reset、validate --clean）前是否提示确认',
   },
+  maxConcurrency: {
+    defaultValue: 0,
+    description: 'run 命令默认最大并发数，0 表示不限制',
+  },
 };
 
 /**

package/src/constants/index.ts

@@ -1,4 +1,4 @@
-export { CLAWT_HOME, CONFIG_PATH, LOGS_DIR, WORKTREES_DIR, VALIDATE_SNAPSHOTS_DIR } from './paths.js';
+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 { EXIT_CODES } from './exitCodes.js';
@@ -6,3 +6,13 @@ export { ENABLE_BRACKETED_PASTE, DISABLE_BRACKETED_PASTE, PASTE_THRESHOLD_MS } f
 export { DEFAULT_CONFIG, CONFIG_DESCRIPTIONS, APPEND_SYSTEM_PROMPT } from './config.js';
 export { AUTO_SAVE_COMMIT_MESSAGE } from './git.js';
 export { DEBUG_LOG_PREFIX, DEBUG_TIMESTAMP_FORMAT } from './logger.js';
+export {
+  SPINNER_FRAMES,
+  SPINNER_INTERVAL_MS,
+  CURSOR_UP,
+  CLEAR_LINE,
+  CURSOR_HIDE,
+  CURSOR_SHOW,
+  TASK_STATUS_ICONS,
+  TASK_STATUS_LABELS,
+} from './progress.js';

package/src/constants/messages/run.ts

@@ -13,4 +13,34 @@ export const RUN_MESSAGES = {
   INTERRUPT_CLEANED: (count: number) => `✓ 已清理 ${count} 个 worktree 和对应分支`,
   /** 中断后保留 worktree */
   INTERRUPT_KEPT: '已保留 worktree，可稍后使用 clawt remove 手动清理',
+  /** 非 TTY 环境降级输出：任务启动 */
+  PROGRESS_TASK_STARTED: (index: number, total: number, branch: string, path: string) =>
+    `[${index}/${total}] ${branch} 启动  ${path}`,
+  /** 非 TTY 环境降级输出：任务完成 */
+  PROGRESS_TASK_DONE: (index: number, total: number, branch: string, duration: string, cost: string, path: string) =>
+    `[${index}/${total}] ${branch} ✓ 完成 ${duration} ${cost}  ${path}`,
+  /** 非 TTY 环境降级输出：任务失败 */
+  PROGRESS_TASK_FAILED: (index: number, total: number, branch: string, duration: string, path: string) =>
+    `[${index}/${total}] ${branch} ✗ 失败 ${duration}  ${path}`,
+  /** 并发限制提示 */
+  CONCURRENCY_INFO: (concurrency: number, total: number) =>
+    `并发限制: ${concurrency}，共 ${total} 个任务`,
+  /** 并发数无效提示 */
+  CONCURRENCY_INVALID: '并发数必须为正整数',
+  /** 任务文件不存在 */
+  TASK_FILE_NOT_FOUND: (path: string) => `任务文件不存在: ${path}`,
+  /** 任务文件中没有解析到有效任务 */
+  TASK_FILE_EMPTY: '任务文件中没有解析到有效任务',
+  /** 任务文件中某个任务块缺少分支名 */
+  TASK_FILE_MISSING_BRANCH: (blockIndex: number) => `任务文件第 ${blockIndex} 个任务块缺少分支名（# branch: ...）`,
+  /** 任务文件中某个任务块缺少任务描述 */
+  TASK_FILE_MISSING_TASK: (branch: string) => `任务文件中分支 ${branch} 缺少任务描述`,
+  /** 任务文件中某个任务块缺少任务描述（无分支名时按索引定位） */
+  TASK_FILE_MISSING_TASK_BY_INDEX: (blockIndex: number) => `任务文件第 ${blockIndex} 个任务块缺少任务描述`,
+  /** --file 和 --tasks 不能同时使用 */
+  FILE_AND_TASKS_CONFLICT: '--file 和 --tasks 不能同时使用',
+  /** 任务文件加载成功 */
+  TASK_FILE_LOADED: (count: number, path: string) => `✓ 从 ${path} 加载了 ${count} 个任务`,
+  /** 未指定 -b 或 -f */
+  BRANCH_OR_FILE_REQUIRED: '请指定 -b 分支名或 -f 任务文件',
 } as const;

package/src/constants/paths.ts

@@ -15,3 +15,6 @@ export const WORKTREES_DIR = join(CLAWT_HOME, 'worktrees');
 
 /** validate 快照目录 ~/.clawt/validate-snapshots/ */
 export const VALIDATE_SNAPSHOTS_DIR = join(CLAWT_HOME, 'validate-snapshots');
+
+/** Claude Code 项目会话目录 ~/.claude/projects/ */
+export const CLAUDE_PROJECTS_DIR = join(homedir(), '.claude', 'projects');

package/src/constants/progress.ts

@@ -0,0 +1,39 @@
+/** Braille spinner 帧序列 */
+export const SPINNER_FRAMES: readonly string[] = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+
+/** spinner 刷新间隔（毫秒） */
+export const SPINNER_INTERVAL_MS = 100;
+
+/** ANSI 转义：光标上移 n 行 */
+export const CURSOR_UP = (n: number): string => `\x1B[${n}A`;
+
+/** ANSI 转义：清除从光标到行尾 */
+export const CLEAR_LINE = '\x1B[0K';
+
+/** ANSI 转义：隐藏光标 */
+export const CURSOR_HIDE = '\x1B[?25l';
+
+/** ANSI 转义：显示光标 */
+export const CURSOR_SHOW = '\x1B[?25h';
+
+/** 任务状态图标 */
+export const TASK_STATUS_ICONS = {
+  /** 排队中 */
+  PENDING: '◦',
+  /** 完成 */
+  DONE: '✓',
+  /** 失败 */
+  FAILED: '✗',
+} as const;
+
+/** 任务状态标签 */
+export const TASK_STATUS_LABELS = {
+  /** 排队中 */
+  PENDING: '排队中',
+  /** 运行中 */
+  RUNNING: '运行中',
+  /** 完成 */
+  DONE: '完成',
+  /** 失败 */
+  FAILED: '失败',
+} as const;

package/src/types/command.ts

@@ -12,6 +12,10 @@ export interface RunOptions {
   branch: string;
   /** 任务列表（支持多次 --tasks 传入），不传则在 worktree 中打开 Claude Code 交互式界面 */
   tasks?: string[];
+  /** 最大并发数（Commander 传入为字符串），0 表示不限制 */
+  concurrency?: string;
+  /** 任务文件路径（与 --tasks 互斥） */
+  file?: string;
 }
 
 /** validate 命令选项 */

package/src/types/config.ts

@@ -8,6 +8,8 @@ export interface ClawtConfig {
   autoPullPush: boolean;
   /** 执行破坏性操作（reset、validate --clean）前是否提示确认 */
   confirmDestructiveOps: boolean;
+  /** run 命令默认最大并发数，0 表示不限制 */
+  maxConcurrency: number;
 }
 
 /** 单个配置项的完整定义（默认值 + 描述） */