clawt 2.4.0 → 2.5.1

package/.claude/agent-memory/docs-sync-updater/MEMORY.md

@@ -8,14 +8,14 @@
 - run 命令对应 `5.2 批量创建 Worktree + 执行 Claude Code 任务`，流程按步骤编号描述
 - merge 命令对应 `5.6 合并验证过的分支`，流程按步骤编号描述
 - config 命令对应 `5.10 查看全局配置`，只读展示配置
-- resume 命令对应 `5.11 在已有 Worktree 中恢复会话`，查找已有 worktree 并启动交互式界面
+- resume 命令对应 `5.11 在已有 Worktree 中恢复会话`，支持模糊匹配和交互式分支选择（-b 可选）
 - 配置项说明在 `5.7 默认配置文件` 章节的表格中
 - 更新模式：新增步骤时追加编号，配置项影响范围变化时更新说明列
 
 ### CLAUDE.md
 - 面向 Claude Code 的项目架构指引，精简扼要
 - run 命令流程在 `核心流程（run 命令）` 章节，编号列表描述
-- resume 命令流程在独立的 `### resume 命令流程` 章节，编号列表描述
+- resume 命令流程在独立的 `### resume 命令流程` 章节，编号列表 + 缩进列表描述匹配策略
 - merge 和 run 中断清理在 `validate + merge 工作流` 章节，一行式描述用箭头连接流程
 - utils 目录描述用括号内逗号分隔列举功能模块
 - 更新模式：编号列表追加步骤，箭头链追加阶段，括号内追加关键词
@@ -28,14 +28,21 @@
 
 ## 关键约定
 - `autoDeleteBranch` 配置项影响三处：remove 命令、merge 命令、run 中断清理
-- merge 的清理确认在 merge 操作之前询问（避免交互中断），但清理在 merge 成功后执行
+- `confirmDestructiveOps` 配置项影响两处：reset 命令、validate --clean
+- merge 的清理确认和清理操作均在 merge 成功后执行（避免 merge 冲突时提前询问用户造成困惑）
 - merge 成功后自动清理对应的 validate 快照（hasSnapshot + removeSnapshot）
+- merge 成功消息根据 `autoPullPush` 配置动态显示推送状态
 - run 的中断清理在所有子进程退出后执行
+- run 交互式模式在创建 worktree 前检测分支是否已存在，已存在则提示使用 resume
+- remove 命令删除 worktree 时自动清理对应快照，`--all` 模式额外清理项目快照目录
+- remove 批量操作时收集错误继续处理，最后汇总报告
 - 文档中文风格，技术术语保留英文（worktree, merge, branch, SIGINT 等）
 - cleanupWorktrees 是 merge 和 run 共用的公共清理函数（在 src/utils/worktree.ts）
 - `launchInteractiveClaude` 是 run（交互式模式）和 resume 共用的公共函数（在 src/utils/claude.ts）
 - killAllChildProcesses 是 run 专用的子进程终止函数（在 src/utils/shell.ts）
-- validate 快照管理函数在 `src/utils/validate-snapshot.ts`，被 validate 和 merge 两个命令使用
+- validate 快照管理函数在 `src/utils/validate-snapshot.ts`，被 validate、merge 和 remove 三个命令使用
+- `confirmDestructiveAction` 在 `src/utils/formatter.ts`，被 reset 和 validate --clean 使用
+- sanitizeBranchName 清理后为空串时抛出 BRANCH_NAME_EMPTY 错误
 
 ## 配置项同步检查点
 
@@ -68,6 +75,8 @@ Notes:
 - resume 和 run（交互式模式）共用 `launchInteractiveClaude()`，该函数从 run.ts 提取到 src/utils/claude.ts
 - `claudeCodeCommand` 配置项同时影响 run 交互式模式和 resume 命令
 - reset 命令与 validate --clean 的区别：reset 不删除快照文件，validate --clean 会删除快照
+- resume 的 `-b` 参数为可选，核心函数 `resolveTargetWorktree()` 封装匹配策略：精确→模糊（子串，大小写不敏感）→交互选择
+- resume 的交互式选择使用 Enquirer.Select（`promptSelectBranch()`），消息常量在 `MESSAGES.RESUME_*`
 
 ## validate 快照机制
 

package/CLAUDE.md

@@ -34,8 +34,9 @@ run 命令有两种模式：
 
 1. `validateMainWorktree()` 确认在主 worktree 根目录
 2. `validateClaudeCodeInstalled()` 确认 claude CLI 可用
-3. `createWorktrees()` 创建单个 worktree
-4. `launchInteractiveClaude()` 通过 `spawnSync` + `inherit stdio` 在 worktree 中直接启动 Claude Code 交互式界面（启动命令由配置项 `claudeCodeCommand` 指定，默认 `claude`）
+3. 检测分支是否已存在（`checkBranchExists()`），已存在则提示使用 `clawt resume -b <branch>` 恢复会话
+4. `createWorktrees()` 创建单个 worktree
+5. `launchInteractiveClaude()` 通过 `spawnSync` + `inherit stdio` 在 worktree 中直接启动 Claude Code 交互式界面（启动命令由配置项 `claudeCodeCommand` 指定，默认 `claude`）
 
 **模式二：传 `--tasks`（并行任务模式）**
 
@@ -50,7 +51,9 @@ run 命令有两种模式：
 
 1. `validateMainWorktree()` 确认在主 worktree 根目录
 2. `validateClaudeCodeInstalled()` 确认 claude CLI 可用
-3. `findWorktreeByBranch()` 在当前项目的 worktree 列表中按分支名查找已有 worktree
+3. `resolveTargetWorktree()` 解析目标 worktree（`-b` 可选）：
+   - 未传 `-b`：仅 1 个 worktree 直接使用，多个通过 `promptSelectBranch()`（Enquirer.Select）交互选择
+   - 传了 `-b`：`findExactMatch()` 精确匹配 → `findFuzzyMatches()` 子串模糊匹配（大小写不敏感，唯一直接使用，多个交互选择） → 无匹配报错并列出可用分支
 4. `launchInteractiveClaude()` 在目标 worktree 中启动 Claude Code 交互式界面
 
 ### validate + merge 工作流
@@ -58,12 +61,12 @@ run 命令有两种模式：
 - `validate`：将目标分支的全量变更（已提交 + 未提交）通过 `git diff HEAD...branch --binary` 的 patch 方式迁移到主 worktree，便于在主 worktree 中测试。支持两种模式：
   - **首次 validate**（无历史快照）：patch 迁移全量变更 → 通过 `git write-tree` 保存快照为 git tree 对象 → 结果：暂存区=空，工作目录=全量变更
   - **增量 validate**（存在历史快照）：读取旧 tree hash → 确保主 worktree 干净 → patch 迁移最新变更 → 保存新 tree 对象快照 → `git read-tree` 将旧 tree 载入暂存区 → 结果：暂存区=上次快照，工作目录=最新变更（可通过 `git diff` 查看增量差异）
-  - `--clean` 选项：重置主 worktree + 删除对应快照文件
+  - `--clean` 选项：根据 `confirmDestructiveOps` 配置提示确认 → 重置主 worktree + 删除对应快照文件
   - 快照存储路径：`~/.clawt/validate-snapshots/<projectName>/<branchName>.tree`（存储 git tree 对象 hash）
   - tree 对象不依赖主分支 HEAD，无需一致性校验
   - 变更检测：同时检测目标 worktree 的未提交修改和已提交 commit，两者均无则提示无需验证
   - 未提交修改处理：有未提交修改时先做临时 commit，diff 完成后通过 `git reset --soft` 撤销恢复原状
-- `merge`：检测目标 worktree 状态（有修改则需 `-m` 提交，已提交则跳过，无变更则报错）→ **squash 检测**（检查目标分支是否存在 `AUTO_SAVE_COMMIT_MESSAGE` 前缀的 auto-save commit，如有则提示用户是否压缩所有提交：用户确认后通过 `gitMergeBase` 计算分叉点、`gitResetSoftTo` 将所有 commit reset 到暂存区；有 `-m` 则直接提交继续流程，无 `-m` 则提示用户自行提交后退出）→ 合并到主 worktree → pull → push → 可选清理 worktree 和分支（受 `autoDeleteBranch` 配置或交互式确认控制）→ 清理对应的 validate 快照
+- `merge`：检测目标 worktree 状态（有修改则需 `-m` 提交，已提交则跳过，无变更则报错）→ **squash 检测**（检查目标分支是否存在 `AUTO_SAVE_COMMIT_MESSAGE` 前缀的 auto-save commit，如有则提示用户是否压缩所有提交：用户确认后通过 `gitMergeBase` 计算分叉点、`gitResetSoftTo` 将所有 commit reset 到暂存区；有 `-m` 则直接提交继续流程，无 `-m` 则提示用户自行提交后退出）→ 合并到主 worktree → 根据 `autoPullPush` 配置决定是否 pull + push（成功消息动态显示推送状态）→ merge 成功后确认并清理 worktree 和分支（受 `autoDeleteBranch` 配置或交互式确认控制）→ 清理对应的 validate 快照
 - `run` 中断清理：Ctrl+C 终止所有子进程后，根据 `autoDeleteBranch` 配置自动清理或交互式确认清理本次创建的 worktree 和分支
 
 ### sync 命令流程
@@ -80,14 +83,14 @@ run 命令有两种模式：
 
 1. `validateMainWorktree()` 确认在主 worktree 根目录
 2. 检测主 worktree 工作区和暂存区是否干净（`isWorkingDirClean()`）
-3. 不干净 → `gitResetHard()` + `gitCleanForce()` 重置工作区和暂存区（保留 validate 快照）
+3. 不干净 → 根据 `confirmDestructiveOps` 配置决定是否通过 `confirmDestructiveAction()` 提示确认 → `gitResetHard()` + `gitCleanForce()` 重置工作区和暂存区（保留 validate 快照）
 4. 已干净 → 提示无需重置
 
 ### 目录层级
 
 - `src/commands/` — 各命令的注册与处理逻辑
-- `src/utils/` — 工具函数（git 操作（含三点 diff、分支合并、冲突检测、merge-base 计算、commit message 检测、soft reset 到指定 commit、write-tree/read-tree 等）、shell 执行与子进程管理、分支名处理、worktree 管理与批量清理、配置、格式化输出、交互式输入、Claude Code 交互式启动、validate 快照管理（基于 git tree 对象））
-- `src/constants/` — 常量定义（路径、退出码、消息模板、分支规则、配置默认值、终端控制序列、validate 快照目录、sync 相关消息、git 常量（如 `AUTO_SAVE_COMMIT_MESSAGE`）、squash 相关消息、reset 相关消息）
+- `src/utils/` — 工具函数（git 操作（含三点 diff、分支合并、冲突检测、merge-base 计算、commit message 检测、soft reset 到指定 commit、write-tree/read-tree、分支存在性检测等）、shell 执行与子进程管理、分支名处理、worktree 管理与批量清理、配置、格式化输出与破坏性操作确认、交互式输入、Claude Code 交互式启动、validate 快照管理（基于 git tree 对象））
+- `src/constants/` — 常量定义（路径、退出码、消息模板、分支规则、配置默认值、终端控制序列、validate 快照目录、sync 相关消息、git 常量（如 `AUTO_SAVE_COMMIT_MESSAGE`）、squash 相关消息、reset 相关消息、remove 相关消息、破坏性操作确认消息）
 - `src/types/` — TypeScript 类型定义
 - `src/errors/` — 自定义 `ClawtError` 错误类（携带退出码）
 - `src/logger/` — winston 日志（按日期滚动，写入 `~/.clawt/logs/`）
@@ -96,7 +99,7 @@ run 命令有两种模式：
 
 - 所有命令执行前都会调用 `validateMainWorktree()` 确保在主 worktree 根目录（`git rev-parse --git-common-dir === ".git"`）
 - Worktree 统一存放在 `~/.clawt/worktrees/<projectName>/` 下
-- 全局配置文件 `~/.clawt/config.json`，postinstall 时自动创建/合并，包含 `autoDeleteBranch`（是否自动删除分支）、`claudeCodeCommand`（Claude Code CLI 启动指令，用于 `run` 和 `resume` 的交互式界面）、`autoPullPush`（merge 后是否自动 pull/push）三个配置项。配置项以 `CONFIG_DEFINITIONS` 为单一数据源，`DEFAULT_CONFIG` 和 `CONFIG_DESCRIPTIONS` 均从中派生
+- 全局配置文件 `~/.clawt/config.json`，postinstall 时自动创建/合并，包含 `autoDeleteBranch`（是否自动删除分支）、`claudeCodeCommand`（Claude Code CLI 启动指令，用于 `run` 和 `resume` 的交互式界面）、`autoPullPush`（merge 后是否自动 pull/push）、`confirmDestructiveOps`（破坏性操作前是否提示确认，影响 `reset` 和 `validate --clean`）四个配置项。配置项以 `CONFIG_DEFINITIONS` 为单一数据源，`DEFAULT_CONFIG` 和 `CONFIG_DESCRIPTIONS` 均从中派生
 - shell 命令执行有同步（`execCommand` → `execSync`）、异步（`spawnProcess` → `spawn`）和同步带 stdin（`execCommandWithInput` → `execFileSync`）三种方式
 - 项目为纯 ESM（`"type": "module"`），模块导入需带 `.js` 后缀
 - 分支名特殊字符会被 `sanitizeBranchName()` 自动清理

package/README.md

@@ -58,7 +58,7 @@ clawt run -b <branchName>
 
 每个 `--tasks` 对应一个独立的 worktree，Claude Code 会在各自隔离的环境中并行执行任务。任务完成后会实时通知结果，全部完成后输出汇总信息。
 
-不传 `--tasks` 时会创建单个 worktree，并在其中直接启动 Claude Code 交互式界面（通过 `spawnSync` + `inherit stdio`），让用户与 Claude Code 直接交互。启动命令由配置项 `claudeCodeCommand` 指定（默认 `claude`）。
+不传 `--tasks` 时会创建单个 worktree，并在其中直接启动 Claude Code 交互式界面（通过 `spawnSync` + `inherit stdio`），让用户与 Claude Code 直接交互。启动命令由配置项 `claudeCodeCommand` 指定（默认 `claude`）。如果指定的分支已存在，会提示使用 `clawt resume -b <branchName>` 恢复会话。
 
 任务执行过程中按 Ctrl+C 可中断所有任务。中断后会根据配置自动清理或询问是否清理本次创建的 worktree 和分支（`autoDeleteBranch: true` 时自动清理）。
 
@@ -76,18 +76,32 @@ clawt run -b feature-login
 ### `clawt resume` — 在已有 worktree 中恢复 Claude Code 会话
 
 ```bash
+# 指定分支名（支持模糊匹配）
 clawt resume -b <branchName>
+
+# 不指定分支名（列出所有分支供选择）
+clawt resume
 ```
 
 | 参数 | 必填 | 说明 |
 | ---- | ---- | ---- |
-| `-b` | 是 | 要恢复的分支名 |
+| `-b` | 否 | 要恢复的分支名（支持模糊匹配，不传则列出所有分支供选择） |
 
 在之前通过 `clawt run` 或 `clawt create` 创建的 worktree 中重新打开 Claude Code 交互式界面，继续之前的工作。启动命令由配置项 `claudeCodeCommand` 指定（默认 `claude`）。
 
+**分支匹配策略：**
+- 传 `-b` 时，优先精确匹配分支名；未精确匹配则进行模糊匹配（子串匹配，大小写不敏感）；模糊匹配到多个时通过交互列表选择；无匹配时报错并列出所有可用分支
+- 不传 `-b` 时，列出当前项目所有可用分支供交互式选择（仅 1 个时自动使用）
+
 ```bash
-# 在已有 worktree 中恢复会话
+# 精确匹配
 clawt resume -b feature-login
+
+# 模糊匹配（匹配包含 "login" 的分支）
+clawt resume -b login
+
+# 交互式选择所有分支
+clawt resume
 ```
 
 ### `clawt validate` — 在主 worktree 验证分支变更
@@ -146,7 +160,7 @@ clawt merge -b <branchName> [-m <commitMessage>]
 | `-b` | 是 | 要合并的分支名 |
 | `-m` | 否 | 提交信息（目标 worktree 工作区有修改时必填） |
 
-将目标 worktree 的变更合并到主 worktree 的当前分支，并推送到远程仓库。如果目标 worktree 工作区有未提交的修改，需要通过 `-m` 提供提交信息；如果目标 worktree 已经提交过（工作区干净但有本地提交），可以省略 `-m` 直接合并。merge 成功后会询问是否清理对应的 worktree 和分支（如果配置了 `autoDeleteBranch: true` 则自动清理）。
+将目标 worktree 的变更合并到主 worktree 的当前分支。如果配置了 `autoPullPush: true`，合并后会自动推送到远程仓库。如果目标 worktree 工作区有未提交的修改，需要通过 `-m` 提供提交信息；如果目标 worktree 已经提交过（工作区干净但有本地提交），可以省略 `-m` 直接合并。merge 成功后会询问是否清理对应的 worktree 和分支（如果配置了 `autoDeleteBranch: true` 则自动清理）。
 
 如果检测到目标分支存在 `clawt sync` 产生的临时提交（auto-save commit），会自动提示是否将所有提交压缩（squash）为一个。用户选择压缩后，所有 commit 会被 reset 到暂存区：如果提供了 `-m` 则直接提交并继续合并流程；如果未提供 `-m` 则提示用户前往目标 worktree 自行提交后重新执行 merge。
 
@@ -177,15 +191,27 @@ clawt remove -b feature-scheme
 clawt remove -b feature-scheme-2
 ```
 
-移除时会询问是否同时删除对应的本地分支。
+移除时会询问是否同时删除对应的本地分支。移除 worktree 时会自动清理对应的 validate 快照；`--all` 模式还会清理整个项目的快照目录。批量移除时单个失败不会中断整个流程，最后汇总报告失败项。
 
 ### `clawt list` — 列出当前项目所有 worktree
 
 ```bash
-clawt list
+clawt list [--json]
 ```
 
-列出当前项目在 `~/.clawt/worktrees/` 下的所有 worktree 及对应分支。
+| 参数 | 必填 | 说明 |
+| ---- | ---- | ---- |
+| `--json` | 否 | 以 JSON 格式输出（仅包含 path 和 branch） |
+
+列出当前项目在 `~/.clawt/worktrees/` 下的所有 worktree 及对应分支。指定 `--json` 时以 JSON 格式输出，便于脚本解析。
+
+```bash
+# 文本格式输出（默认）
+clawt list
+
+# JSON 格式输出
+clawt list --json
+```
 
 ### `clawt reset` — 重置主 worktree 工作区和暂存区
 
@@ -193,7 +219,7 @@ clawt list
 clawt reset
 ```
 
-重置主 worktree 的工作区和暂存区（`git reset --hard` + `git clean -f`），恢复到干净状态。与 `clawt validate --clean` 不同，`reset` 不会删除 validate 快照文件，适用于只想清空变更而保留快照以便后续增量 validate 的场景。如果工作区和暂存区已是干净状态，会提示无需重置。
+重置主 worktree 的工作区和暂存区（`git reset --hard` + `git clean -f`），恢复到干净状态。如果配置了 `confirmDestructiveOps: true`（默认），执行前会提示确认。与 `clawt validate --clean` 不同，`reset` 不会删除 validate 快照文件，适用于只想清空变更而保留快照以便后续增量 validate 的场景。如果工作区和暂存区已是干净状态，会提示无需重置。
 
 ```bash
 # 重置主 worktree 工作区和暂存区
@@ -216,7 +242,8 @@ clawt config
 {
   "autoDeleteBranch": false,
   "claudeCodeCommand": "claude",
-  "autoPullPush": false
+  "autoPullPush": false,
+  "confirmDestructiveOps": true
 }
 ```
 
@@ -225,6 +252,7 @@ clawt config
 | `autoDeleteBranch` | `boolean` | `false` | 移除 worktree 时自动删除对应本地分支；merge 成功后自动清理 worktree 和分支；run 中断后自动清理本次创建的 worktree 和分支 |
 | `claudeCodeCommand` | `string` | `"claude"` | Claude Code CLI 启动指令，用于 `clawt run` 不传 `--tasks` 时和 `clawt resume` 在 worktree 中打开交互式界面 |
 | `autoPullPush` | `boolean` | `false` | merge 成功后是否自动执行 git pull 和 git push |
+| `confirmDestructiveOps` | `boolean` | `true` | 执行破坏性操作（reset、validate --clean）前是否提示确认 |
 
 ## 分支名规则
 

package/dist/index.js

@@ -28,6 +28,8 @@ var MESSAGES = {
   CLAUDE_NOT_INSTALLED: "Claude Code CLI \u672A\u5B89\u88C5\uFF0C\u8BF7\u5148\u5B89\u88C5\uFF1Anpm install -g @anthropic-ai/claude-code",
   /** 分支已存在 */
   BRANCH_EXISTS: (name) => `\u5206\u652F ${name} \u5DF2\u5B58\u5728\uFF0C\u65E0\u6CD5\u521B\u5EFA`,
+  /** 分支已存在时提示使用 resume */
+  BRANCH_EXISTS_USE_RESUME: (name) => `\u5206\u652F ${name} \u5DF2\u5B58\u5728\uFF0C\u8BF7\u4F7F\u7528 clawt resume -b ${name} \u6062\u590D\u4F1A\u8BDD`,
   /** 分支名清理后为空 */
   BRANCH_NAME_EMPTY: (original) => `\u5206\u652F\u540D "${original}" \u4E2D\u4E0D\u5305\u542B\u5408\u6CD5\u5B57\u7B26\uFF0C\u65E0\u6CD5\u521B\u5EFA\u5206\u652F`,
   /** 分支名被转换 */
@@ -122,7 +124,17 @@ var MESSAGES = {
   RESET_ALREADY_CLEAN: "\u4E3B worktree \u5DE5\u4F5C\u533A\u548C\u6682\u5B58\u533A\u5DF2\u662F\u5E72\u51C0\u72B6\u6001\uFF0C\u65E0\u9700\u91CD\u7F6E",
   /** 批量移除部分失败 */
   REMOVE_PARTIAL_FAILURE: (failures) => `\u4EE5\u4E0B worktree \u79FB\u9664\u5931\u8D25\uFF1A
-${failures.map((f) => `  \u2717 ${f.path}: ${f.error}`).join("\n")}`
+${failures.map((f) => `  \u2717 ${f.path}: ${f.error}`).join("\n")}`,
+  /** resume 无可用 worktree */
+  RESUME_NO_WORKTREES: "\u5F53\u524D\u9879\u76EE\u6CA1\u6709\u53EF\u7528\u7684 worktree\uFF0C\u8BF7\u5148\u901A\u8FC7 clawt run \u6216 clawt create \u521B\u5EFA",
+  /** resume 模糊匹配无结果，列出可用分支 */
+  RESUME_NO_MATCH: (name, branches) => `\u672A\u627E\u5230\u4E0E "${name}" \u5339\u914D\u7684\u5206\u652F
+  \u53EF\u7528\u5206\u652F\uFF1A
+${branches.map((b) => `    - ${b}`).join("\n")}`,
+  /** resume 交互选择提示 */
+  RESUME_SELECT_BRANCH: "\u8BF7\u9009\u62E9\u8981\u6062\u590D\u7684\u5206\u652F",
+  /** resume 模糊匹配到多个结果提示 */
+  RESUME_MULTIPLE_MATCHES: (name) => `"${name}" \u5339\u914D\u5230\u591A\u4E2A\u5206\u652F\uFF0C\u8BF7\u9009\u62E9\uFF1A`
 };
 
 // src/constants/exitCodes.ts
@@ -696,15 +708,33 @@ function removeProjectSnapshots(projectName) {
 // src/commands/list.ts
 import chalk2 from "chalk";
 function registerListCommand(program2) {
-  program2.command("list").description("\u5217\u51FA\u5F53\u524D\u9879\u76EE\u6240\u6709 worktree").action(() => {
-    handleList();
+  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);
   });
 }
-function handleList() {
+function handleList(options) {
   validateMainWorktree();
   const projectName = getProjectName();
   const worktrees = getProjectWorktrees();
   logger.info(`list \u547D\u4EE4\u6267\u884C\uFF0C\u9879\u76EE: ${projectName}\uFF0C\u5171 ${worktrees.length} \u4E2A worktree`);
+  if (options.json) {
+    printListAsJson(projectName, worktrees);
+    return;
+  }
+  printListAsText(projectName, worktrees);
+}
+function printListAsJson(projectName, worktrees) {
+  const result = {
+    project: projectName,
+    total: worktrees.length,
+    worktrees: worktrees.map((wt) => ({
+      path: wt.path,
+      branch: wt.branch
+    }))
+  };
+  console.log(JSON.stringify(result, null, 2));
+}
+function printListAsText(projectName, worktrees) {
   printInfo(`\u5F53\u524D\u9879\u76EE: ${projectName}
 `);
   if (worktrees.length === 0) {
@@ -928,6 +958,10 @@ async function handleRun(options) {
   validateMainWorktree();
   validateClaudeCodeInstalled();
   if (!options.tasks || options.tasks.length === 0) {
+    const sanitized = sanitizeBranchName(options.branch);
+    if (checkBranchExists(sanitized)) {
+      throw new ClawtError(MESSAGES.BRANCH_EXISTS_USE_RESUME(sanitized));
+    }
     const worktrees2 = createWorktrees(options.branch, 1);
     const worktree = worktrees2[0];
     printSuccess(MESSAGES.WORKTREE_CREATED(1));
@@ -988,31 +1022,66 @@ async function handleRun(options) {
 }
 
 // src/commands/resume.ts
+import Enquirer2 from "enquirer";
 function registerResumeCommand(program2) {
-  program2.command("resume").description("\u5728\u5DF2\u6709 worktree \u4E2D\u6062\u590D Claude Code \u4EA4\u4E92\u5F0F\u4F1A\u8BDD").requiredOption("-b, --branch <branchName>", "\u8981\u6062\u590D\u7684\u5206\u652F\u540D").action((options) => {
-    handleResume(options);
+  program2.command("resume").description("\u5728\u5DF2\u6709 worktree \u4E2D\u6062\u590D Claude Code \u4EA4\u4E92\u5F0F\u4F1A\u8BDD").option("-b, --branch <branchName>", "\u8981\u6062\u590D\u7684\u5206\u652F\u540D\uFF08\u652F\u6301\u6A21\u7CCA\u5339\u914D\uFF0C\u4E0D\u4F20\u5219\u5217\u51FA\u6240\u6709\u5206\u652F\uFF09").action(async (options) => {
+    await handleResume(options);
   });
 }
-function findWorktreeByBranch(branchName) {
+function findExactMatch(worktrees, branchName) {
+  return worktrees.find((wt) => wt.branch === branchName);
+}
+function findFuzzyMatches(worktrees, keyword) {
+  const lowerKeyword = keyword.toLowerCase();
+  return worktrees.filter((wt) => wt.branch.toLowerCase().includes(lowerKeyword));
+}
+async function promptSelectBranch(worktrees, message) {
+  const selectedBranch = await new Enquirer2.Select({
+    message,
+    choices: worktrees.map((wt) => ({
+      name: wt.branch,
+      message: wt.branch
+    }))
+  }).run();
+  return worktrees.find((wt) => wt.branch === selectedBranch);
+}
+async function resolveTargetWorktree(branchName) {
   const worktrees = getProjectWorktrees();
-  const matched = worktrees.find((wt) => wt.branch === branchName);
-  if (!matched) {
-    throw new ClawtError(MESSAGES.WORKTREE_NOT_FOUND(branchName));
+  if (worktrees.length === 0) {
+    throw new ClawtError(MESSAGES.RESUME_NO_WORKTREES);
   }
-  return matched;
+  if (!branchName) {
+    if (worktrees.length === 1) {
+      return worktrees[0];
+    }
+    return promptSelectBranch(worktrees, MESSAGES.RESUME_SELECT_BRANCH);
+  }
+  const exactMatch = findExactMatch(worktrees, branchName);
+  if (exactMatch) {
+    return exactMatch;
+  }
+  const fuzzyMatches = findFuzzyMatches(worktrees, branchName);
+  if (fuzzyMatches.length === 1) {
+    return fuzzyMatches[0];
+  }
+  if (fuzzyMatches.length > 1) {
+    return promptSelectBranch(fuzzyMatches, MESSAGES.RESUME_MULTIPLE_MATCHES(branchName));
+  }
+  const allBranches = worktrees.map((wt) => wt.branch);
+  throw new ClawtError(MESSAGES.RESUME_NO_MATCH(branchName, allBranches));
 }
-function handleResume(options) {
+async function handleResume(options) {
   validateMainWorktree();
   validateClaudeCodeInstalled();
-  logger.info(`resume \u547D\u4EE4\u6267\u884C\uFF0C\u5206\u652F: ${options.branch}`);
-  const worktree = findWorktreeByBranch(options.branch);
+  logger.info(`resume \u547D\u4EE4\u6267\u884C\uFF0C\u5206\u652F: ${options.branch ?? "(\u672A\u6307\u5B9A)"}`);
+  const worktree = await resolveTargetWorktree(options.branch);
   launchInteractiveClaude(worktree);
 }
 
 // src/commands/validate.ts
 import { join as join4 } from "path";
 import { existsSync as existsSync6 } from "fs";
-import Enquirer2 from "enquirer";
+import Enquirer3 from "enquirer";
 function registerValidateCommand(program2) {
   program2.command("validate").description("\u5728\u4E3B worktree \u9A8C\u8BC1\u67D0\u4E2A worktree \u5206\u652F\u7684\u53D8\u66F4").requiredOption("-b, --branch <branchName>", "\u8981\u9A8C\u8BC1\u7684\u5206\u652F\u540D").option("--clean", "\u6E05\u7406 validate \u72B6\u6001\uFF08\u91CD\u7F6E\u4E3B worktree \u5E76\u5220\u9664\u5FEB\u7167\uFF09").action(async (options) => {
     await handleValidate(options);
@@ -1020,7 +1089,7 @@ function registerValidateCommand(program2) {
 }
 async function handleDirtyMainWorktree(mainWorktreePath) {
   printWarning("\u4E3B worktree \u5F53\u524D\u5206\u652F\u6709\u672A\u63D0\u4EA4\u7684\u66F4\u6539\uFF0C\u8BF7\u9009\u62E9\u5904\u7406\u65B9\u5F0F\uFF1A\n");
-  const choice = await new Enquirer2.Select({
+  const choice = await new Enquirer3.Select({
     message: "\u9009\u62E9\u5904\u7406\u65B9\u5F0F",
     choices: [
       {
@@ -1205,7 +1274,7 @@ async function shouldCleanupAfterMerge(branchName) {
     printInfo(`\u5DF2\u914D\u7F6E\u81EA\u52A8\u5220\u9664\uFF0Cmerge \u6210\u529F\u540E\u5C06\u81EA\u52A8\u6E05\u7406 worktree \u548C\u5206\u652F: ${branchName}`);
     return true;
   }
-  return confirmAction(`merge \u6210\u529F\u540E\u662F\u5426\u5220\u9664\u5BF9\u5E94\u7684 worktree \u548C\u5206\u652F (${branchName})\uFF1F`);
+  return confirmAction(`\u662F\u5426\u5220\u9664\u5BF9\u5E94\u7684 worktree \u548C\u5206\u652F (${branchName})\uFF1F`);
 }
 function cleanupWorktreeAndBranch(worktreePath, branchName) {
   cleanupWorktrees([{ path: worktreePath, branch: branchName }]);
@@ -1231,7 +1300,6 @@ async function handleMerge(options) {
   if (shouldExit) {
     return;
   }
-  const shouldCleanup = await shouldCleanupAfterMerge(options.branch);
   const targetClean = isWorkingDirClean(targetWorktreePath);
   if (!targetClean) {
     if (!options.message) {
@@ -1267,6 +1335,7 @@ async function handleMerge(options) {
   } else {
     printSuccess(MESSAGES.MERGE_SUCCESS_NO_MESSAGE(options.branch, autoPullPush));
   }
+  const shouldCleanup = await shouldCleanupAfterMerge(options.branch);
   if (shouldCleanup) {
     cleanupWorktreeAndBranch(targetWorktreePath, options.branch);
   }

package/docs/spec.md

@@ -106,6 +106,7 @@ const projectName = path.basename(projectRoot);
 1. 将所有非法字符替换为 `-`
 2. 将连续的 `-` 压缩为一个 `-`
 3. 去除首尾 `-`
+4. 如果转换后结果为空串（原始分支名不包含任何合法字符），报错退出
 
 **示例输出：**
 
@@ -164,7 +165,7 @@ git show-ref --verify refs/heads/<branchName> 2>/dev/null
 | `clawt validate`      | 在主 worktree 验证某个 worktree 分支的变更        | 5.4      |
 | `clawt merge`         | 合并某个已验证的 worktree 分支到主 worktree       | 5.6      |
 | `clawt remove`        | 移除 worktree（支持单个/批量/全部）               | 5.5      |
-| `clawt list`          | 列出当前项目所有 worktree                        | 5.8      |
+| `clawt list`          | 列出当前项目所有 worktree（支持 `--json` 格式输出） | 5.8      |
 | `clawt config`        | 查看全局配置                                     | 5.10     |
 | `clawt resume`        | 在已有 worktree 中恢复 Claude Code 交互式会话      | 5.11     |
 | `clawt sync`          | 将主分支最新代码同步到目标 worktree                  | 5.12     |
@@ -262,7 +263,7 @@ clawt run -b <branchName>
 
 **运行流程：**
 
-1. 若传了 `--tasks`，解析得到任务数组 `tasks[]`；若未传，创建单个 worktree 并启动 Claude Code 交互式界面（流程结束，不进入后续并行执行阶段）
+1. 若传了 `--tasks`，解析得到任务数组 `tasks[]`；若未传，先检测分支是否已存在（已存在则提示使用 `clawt resume -b <branchName>` 恢复会话），然后创建单个 worktree 并启动 Claude Code 交互式界面（流程结束，不进入后续并行执行阶段）
 2. `n = tasks.length`
 3. 按照 **5.1** 的流程创建 `n` 个 worktree
 4. 对每个 worktree 并行启动 Claude Code CLI：
@@ -371,9 +372,10 @@ validate 命令引入了**快照（snapshot）机制**来支持增量对比。
 当指定 `--clean` 选项时，执行清理逻辑后直接返回，不进入常规 validate 流程：
 
 1. **主 worktree 校验** (2.1)
-2. 如果主 worktree 有未提交更改，执行 `git reset --hard` + `git clean -fd` 清空
-3. 删除对应分支的快照文件
-4. 输出清理成功提示
+2. 如果配置项 `confirmDestructiveOps` 为 `true`，提示确认（显示即将执行的危险指令和操作后果），用户取消则退出
+3. 如果主 worktree 有未提交更改，执行 `git reset --hard` + `git clean -fd` 清空
+4. 删除对应分支的快照文件
+5. 输出清理成功提示
 
 #### 首次 validate（无历史快照）
 
@@ -550,11 +552,17 @@ git worktree remove -f <worktree路径>
 
 # 如果用户选择了删除分支
 git branch -D <branchName>
+
+# 清理该分支对应的 validate 快照
 ```
 
 6. 如果配置文件 `~/.clawt/config.json` 中 `autoDeleteBranch` 为 `true`，则跳过询问，直接删除分支。
 
-7. 移除完成后，清理空目录（如果 `~/.clawt/worktrees/<project>/` 下已无 worktree，则删除该项目目录）。
+7. 如果使用 `--all` 模式，额外清理整个项目的 validate 快照目录。
+
+8. 移除完成后，清理空目录（如果 `~/.clawt/worktrees/<project>/` 下已无 worktree，则删除该项目目录）。
+
+9. 批量移除时，单个 worktree 移除失败不会中断整个流程，而是收集所有失败项，最后汇总报告。
 
 ---
 
@@ -620,25 +628,33 @@ clawt merge -b <branchName> [-m <commitMessage>]
    - 检查 merge 退出码及 `git status` 是否存在冲突
    - **有冲突** → 提示 `合并存在冲突，请手动处理`，退出
    - **无冲突** → 继续
-7. **推送**
+7. **推送（受 `autoPullPush` 配置控制）**
    ```bash
+   # 仅当 autoPullPush 为 true 时执行
    git pull
    git push
    ```
 8. **输出成功提示**
 
 ```
-# 提供了 -m 时
+# 提供了 -m 且已推送时
 ✓ 分支 feature-scheme-1 已成功合并到当前分支
   提交信息: <commitMessage>
   已推送到远程仓库
 
-# 未提供 -m 时（目标 worktree 已提交过）
+# 提供了 -m 但未推送时
+✓ 分支 feature-scheme-1 已成功合并到当前分支
+  提交信息: <commitMessage>
+
+# 未提供 -m 且已推送时
 ✓ 分支 feature-scheme-1 已成功合并到当前分支
   已推送到远程仓库
+
+# 未提供 -m 且未推送时
+✓ 分支 feature-scheme-1 已成功合并到当前分支
 ```
 
-9. **merge 成功后清理 worktree 和分支（可选）**
+9. **merge 成功后确认并清理 worktree 和分支（可选）**
    - 如果配置文件中 `autoDeleteBranch` 为 `true`，自动执行清理
    - 否则交互式询问用户是否清理
    - 用户确认后，依次执行：
@@ -656,7 +672,7 @@ clawt merge -b <branchName> [-m <commitMessage>]
 10. **清理 validate 快照**
     - merge 成功后，如果存在该分支的 validate 快照（`~/.clawt/validate-snapshots/<project>/<branchName>.tree`），自动删除该快照文件（merge 成功后快照已无意义）
 
-> **注意：** 清理确认在 merge 操作之前询问（避免 merge 成功后因交互中断而遗留未清理的 worktree），但清理操作在 merge 成功后才执行。
+> **注意：** 清理确认和清理操作均在 merge 成功后执行。只有 merge 成功才会询问用户是否清理 worktree 和分支，避免 merge 冲突时用户被提前询问造成困惑。
 
 ---
 
@@ -680,7 +696,8 @@ clawt merge -b <branchName> [-m <commitMessage>]
 {
   "autoDeleteBranch": false,
   "claudeCodeCommand": "claude",
-  "autoPullPush": false
+  "autoPullPush": false,
+  "confirmDestructiveOps": true
 }
 ```
 
@@ -691,6 +708,7 @@ clawt merge -b <branchName> [-m <commitMessage>]
 | `autoDeleteBranch` | `boolean` | `false`   | 移除 worktree 时是否自动删除对应本地分支（无需每次确认）；merge 成功后是否自动清理 worktree 和分支；run 任务被中断（Ctrl+C）后是否自动清理本次创建的 worktree 和分支 |
 | `claudeCodeCommand` | `string` | `"claude"` | Claude Code CLI 启动指令，用于 `clawt run` 不传 `--tasks` 时和 `clawt resume` 在 worktree 中打开交互式界面 |
 | `autoPullPush` | `boolean` | `false` | merge 成功后是否自动执行 git pull 和 git push |
+| `confirmDestructiveOps` | `boolean` | `true` | 执行破坏性操作（reset、validate --clean）前是否提示确认 |
 
 ---
 
@@ -699,18 +717,26 @@ clawt merge -b <branchName> [-m <commitMessage>]
 **命令：**
 
 ```bash
-clawt list
+clawt list [--json]
 ```
 
+**参数：**
+
+| 参数     | 必填 | 说明                                     |
+| -------- | ---- | ---------------------------------------- |
+| `--json` | 否   | 以 JSON 格式输出（仅包含 path 和 branch） |
+
 **运行流程：**
 
 1. **主 worktree 校验** (2.1)
 2. **获取项目名** (2.2)
 3. 扫描 `~/.clawt/worktrees/<project>/` 目录
 4. 对每个子目录，验证是否为有效的 git worktree（`git worktree list` 交叉验证）
-5. 输出列表
+5. 根据 `--json` 选项决定输出格式：
+   - 指定 `--json` → 以 JSON 格式输出
+   - 未指定 → 以文本格式输出
 
-**输出格式：**
+**文本输出格式（默认）：**
 
 ```
 当前项目: main-project
@@ -731,6 +757,25 @@ clawt list
   (无 worktree)
 ```
 
+**JSON 输出格式（`--json`）：**
+
+```json
+{
+  "project": "main-project",
+  "total": 4,
+  "worktrees": [
+    {
+      "path": "~/.clawt/worktrees/main-project/feature-scheme-1",
+      "branch": "feature-scheme-1"
+    },
+    {
+      "path": "~/.clawt/worktrees/main-project/feature-scheme-2",
+      "branch": "feature-scheme-2"
+    }
+  ]
+}
+```
+
 ---
 
 ### 5.9 日志系统
@@ -797,6 +842,9 @@ clawt config
   autoPullPush: false
   merge 成功后是否自动执行 git pull 和 git push
 
+  confirmDestructiveOps: true
+  执行破坏性操作（reset、validate --clean）前是否提示确认
+
 ────────────────────────────────────────
 
 ```
@@ -808,14 +856,18 @@ clawt config
 **命令：**
 
 ```bash
+# 指定分支名（支持模糊匹配）
 clawt resume -b <branchName>
+
+# 不指定分支名（列出所有分支供选择）
+clawt resume
 ```
 
 **参数：**
 
 | 参数 | 必填 | 说明                                                  |
 | ---- | ---- | ----------------------------------------------------- |
-| `-b` | 是   | 要恢复的分支名（对应已有 worktree 的分支）               |
+| `-b` | 否   | 要恢复的分支名（支持模糊匹配，不传则列出所有分支供选择） |
 
 **使用场景：**
 
@@ -825,9 +877,18 @@ clawt resume -b <branchName>
 
 1. **主 worktree 校验** (2.1)
 2. **Claude Code CLI 校验**：确认 `claude` CLI 可用
-3. **查找目标 worktree**：在当前项目的 worktree 列表中按分支名查找匹配的 worktree
-   - 未找到 → 报错退出
-   - 找到 → 继续
+3. **解析目标 worktree**：根据 `-b` 参数解析目标 worktree，匹配策略如下：
+   - **未传 `-b` 参数**：
+     - 获取当前项目所有 worktree
+     - 无可用 worktree → 报错退出
+     - 仅 1 个 worktree → 直接使用，无需选择
+     - 多个 worktree → 通过交互式列表（Enquirer.Select）让用户选择
+   - **传了 `-b` 参数**：
+     1. **精确匹配优先**：在 worktree 列表中查找分支名完全相同的 worktree，找到则直接使用
+     2. **模糊匹配**（子串匹配，大小写不敏感）：
+        - 唯一匹配 → 直接使用
+        - 多个匹配 → 通过交互式列表让用户从匹配结果中选择
+     3. **无匹配** → 报错退出，并列出所有可用分支名
 4. **启动 Claude Code 交互式界面**：通过 `launchInteractiveClaude()` 在目标 worktree 中启动 Claude Code CLI 交互式界面（使用 `spawnSync` + `inherit stdio`）
 
 启动命令通过配置项 `claudeCodeCommand`（默认值 `claude`）指定，与 `clawt run` 不传 `--tasks` 时的交互式界面行为一致。
@@ -872,6 +933,7 @@ clawt sync -b <branchName>
      合并存在冲突，请进入目标 worktree 手动解决：
        cd ~/.clawt/worktrees/<project>/<branchName>
        解决冲突后执行 git add . && git merge --continue
+       clawt validate -b <branch> 验证变更
      ```
    - **无冲突** → 继续
 7. **清除 validate 快照**：合并成功后，如果该分支存在 validate 快照（`.tree` 文件），自动删除（代码基础已变化，旧快照无效）
@@ -902,12 +964,13 @@ clawt reset
 2. **检测工作区状态**：通过 `git status --porcelain` 检测主 worktree 是否有未提交的更改
    - **工作区干净** → 输出提示 `主 worktree 工作区和暂存区已是干净状态，无需重置`，退出
    - **工作区不干净** → 继续
-3. **重置工作区和暂存区**：
+3. **确认破坏性操作**：如果配置项 `confirmDestructiveOps` 为 `true`，提示确认（显示即将执行的危险指令和操作后果），用户取消则退出
+4. **重置工作区和暂存区**：
    ```bash
    git reset --hard
    git clean -f
    ```
-4. **输出成功提示**：
+5. **输出成功提示**：
    ```
    ✓ 主 worktree 工作区和暂存区已重置
    ```

package/package.json

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

package/src/commands/list.ts

@@ -2,6 +2,7 @@ import type { Command } from 'commander';
 import chalk from 'chalk';
 import { MESSAGES } from '../constants/index.js';
 import { logger } from '../logger/index.js';
+import type { ListOptions } from '../types/index.js';
 import {
   validateMainWorktree,
   getProjectName,
@@ -10,6 +11,7 @@ import {
   formatWorktreeStatus,
   printInfo,
 } from '../utils/index.js';
+// getWorktreeStatus 和 formatWorktreeStatus 仅在文本模式下使用
 
 /**
  * 注册 list 命令：列出当前项目所有 worktree
@@ -19,15 +21,17 @@ export function registerListCommand(program: Command): void {
   program
     .command('list')
     .description('列出当前项目所有 worktree')
-    .action(() => {
-      handleList();
+    .option('--json', '以 JSON 格式输出')
+    .action((options: ListOptions) => {
+      handleList(options);
     });
 }
 
 /**
  * 执行 list 命令的核心逻辑
+ * @param {ListOptions} options - 命令选项
  */
-function handleList(): void {
+function handleList(options: ListOptions): void {
   validateMainWorktree();
 
   const projectName = getProjectName();
@@ -35,6 +39,38 @@ function handleList(): void {
 
   logger.info(`list 命令执行，项目: ${projectName}，共 ${worktrees.length} 个 worktree`);
 
+  if (options.json) {
+    printListAsJson(projectName, worktrees);
+    return;
+  }
+
+  printListAsText(projectName, worktrees);
+}
+
+/**
+ * 以 JSON 格式输出 worktree 列表（仅包含 path 和 branch）
+ * @param {string} projectName - 项目名称
+ * @param {import('../types/index.js').WorktreeInfo[]} worktrees - worktree 列表
+ */
+function printListAsJson(projectName: string, worktrees: import('../types/index.js').WorktreeInfo[]): void {
+  const result = {
+    project: projectName,
+    total: worktrees.length,
+    worktrees: worktrees.map((wt) => ({
+      path: wt.path,
+      branch: wt.branch,
+    })),
+  };
+
+  console.log(JSON.stringify(result, null, 2));
+}
+
+/**
+ * 以文本格式输出 worktree 列表
+ * @param {string} projectName - 项目名称
+ * @param {import('../types/index.js').WorktreeInfo[]} worktrees - worktree 列表
+ */
+function printListAsText(projectName: string, worktrees: import('../types/index.js').WorktreeInfo[]): void {
   printInfo(`当前项目: ${projectName}\n`);
 
   if (worktrees.length === 0) {

package/src/commands/merge.ts

@@ -105,7 +105,7 @@ async function shouldCleanupAfterMerge(branchName: string): Promise<boolean> {
     printInfo(`已配置自动删除，merge 成功后将自动清理 worktree 和分支: ${branchName}`);
     return true;
   }
-  return confirmAction(`merge 成功后是否删除对应的 worktree 和分支 (${branchName})？`);
+  return confirmAction(`是否删除对应的 worktree 和分支 (${branchName})？`);
 }
 
 /**
@@ -153,9 +153,6 @@ async function handleMerge(options: MergeOptions): Promise<void> {
     return;
   }
 
-  // merge 前确认是否清理 worktree 和分支
-  const shouldCleanup = await shouldCleanupAfterMerge(options.branch);
-
   // 步骤 4：根据目标 worktree 状态决定是否需要提交
   const targetClean = isWorkingDirClean(targetWorktreePath);
 
@@ -206,7 +203,8 @@ async function handleMerge(options: MergeOptions): Promise<void> {
     printSuccess(MESSAGES.MERGE_SUCCESS_NO_MESSAGE(options.branch, autoPullPush));
   }
 
-  // 步骤 9：merge 成功后清理 worktree 和分支
+  // 步骤 9：merge 成功后确认并清理 worktree 和分支
+  const shouldCleanup = await shouldCleanupAfterMerge(options.branch);
   if (shouldCleanup) {
     cleanupWorktreeAndBranch(targetWorktreePath, options.branch);
   }

package/src/commands/resume.ts

@@ -1,4 +1,5 @@
 import type { Command } from 'commander';
+import Enquirer from 'enquirer';
 import { logger } from '../logger/index.js';
 import { ClawtError } from '../errors/index.js';
 import { MESSAGES } from '../constants/index.js';
@@ -18,42 +19,114 @@ export function registerResumeCommand(program: Command): void {
   program
     .command('resume')
     .description('在已有 worktree 中恢复 Claude Code 交互式会话')
-    .requiredOption('-b, --branch <branchName>', '要恢复的分支名')
-    .action((options: ResumeOptions) => {
-      handleResume(options);
+    .option('-b, --branch <branchName>', '要恢复的分支名（支持模糊匹配，不传则列出所有分支）')
+    .action(async (options: ResumeOptions) => {
+      await handleResume(options);
     });
 }
 
 /**
- * 在已有 worktree 列表中按分支名查找对应的 worktree
+ * 在 worktree 列表中精确匹配分支名
+ * @param {WorktreeInfo[]} worktrees - worktree 列表
  * @param {string} branchName - 目标分支名
- * @returns {WorktreeInfo} 匹配的 worktree 信息
- * @throws {ClawtError} 当找不到匹配的 worktree 时抛出
+ * @returns {WorktreeInfo | undefined} 匹配的 worktree，未找到返回 undefined
  */
-function findWorktreeByBranch(branchName: string): WorktreeInfo {
+function findExactMatch(worktrees: WorktreeInfo[], branchName: string): WorktreeInfo | undefined {
+  return worktrees.find((wt) => wt.branch === branchName);
+}
+
+/**
+ * 在 worktree 列表中进行模糊匹配（子串匹配，大小写不敏感）
+ * @param {WorktreeInfo[]} worktrees - worktree 列表
+ * @param {string} keyword - 匹配关键词
+ * @returns {WorktreeInfo[]} 匹配到的 worktree 列表
+ */
+function findFuzzyMatches(worktrees: WorktreeInfo[], keyword: string): WorktreeInfo[] {
+  const lowerKeyword = keyword.toLowerCase();
+  return worktrees.filter((wt) => wt.branch.toLowerCase().includes(lowerKeyword));
+}
+
+/**
+ * 通过交互式列表让用户从 worktree 列表中选择一个分支
+ * @param {WorktreeInfo[]} worktrees - 可供选择的 worktree 列表
+ * @param {string} message - 选择提示信息
+ * @returns {Promise<WorktreeInfo>} 用户选择的 worktree
+ */
+async function promptSelectBranch(worktrees: WorktreeInfo[], message: string): Promise<WorktreeInfo> {
+  // @ts-expect-error enquirer 类型声明未导出 Select 类，但运行时存在
+  const selectedBranch: string = await new Enquirer.Select({
+    message,
+    choices: worktrees.map((wt) => ({
+      name: wt.branch,
+      message: wt.branch,
+    })),
+  }).run();
+
+  return worktrees.find((wt) => wt.branch === selectedBranch)!;
+}
+
+/**
+ * 根据用户输入解析目标 worktree
+ * 匹配策略：精确匹配 → 模糊匹配（唯一直接使用，多个交互选择） → 无匹配报错
+ * 不传分支名时列出所有可用分支供选择
+ * @param {string} [branchName] - 用户输入的分支名（可选）
+ * @returns {Promise<WorktreeInfo>} 解析后的目标 worktree
+ * @throws {ClawtError} 无可用 worktree 或无匹配结果时抛出
+ */
+async function resolveTargetWorktree(branchName?: string): Promise<WorktreeInfo> {
   const worktrees = getProjectWorktrees();
-  const matched = worktrees.find((wt) => wt.branch === branchName);
 
-  if (!matched) {
-    throw new ClawtError(MESSAGES.WORKTREE_NOT_FOUND(branchName));
+  // 无可用 worktree，直接报错
+  if (worktrees.length === 0) {
+    throw new ClawtError(MESSAGES.RESUME_NO_WORKTREES);
+  }
+
+  // 未传 -b 参数：列出所有分支供选择
+  if (!branchName) {
+    // 只有一个 worktree 时直接使用，无需选择
+    if (worktrees.length === 1) {
+      return worktrees[0];
+    }
+    return promptSelectBranch(worktrees, MESSAGES.RESUME_SELECT_BRANCH);
+  }
+
+  // 1. 精确匹配优先
+  const exactMatch = findExactMatch(worktrees, branchName);
+  if (exactMatch) {
+    return exactMatch;
+  }
+
+  // 2. 模糊匹配
+  const fuzzyMatches = findFuzzyMatches(worktrees, branchName);
+
+  // 2a. 唯一匹配，直接使用
+  if (fuzzyMatches.length === 1) {
+    return fuzzyMatches[0];
+  }
+
+  // 2b. 多个匹配，交互选择
+  if (fuzzyMatches.length > 1) {
+    return promptSelectBranch(fuzzyMatches, MESSAGES.RESUME_MULTIPLE_MATCHES(branchName));
   }
 
-  return matched;
+  // 3. 无匹配，抛出错误并列出所有可用分支
+  const allBranches = worktrees.map((wt) => wt.branch);
+  throw new ClawtError(MESSAGES.RESUME_NO_MATCH(branchName, allBranches));
 }
 
 /**
  * 执行 resume 命令的核心逻辑
- * 查找已有 worktree 并恢复 Claude Code 会话
+ * 解析目标 worktree 并恢复 Claude Code 会话
  * @param {ResumeOptions} options - 命令选项
  */
-function handleResume(options: ResumeOptions): void {
+async function handleResume(options: ResumeOptions): Promise<void> {
   validateMainWorktree();
   validateClaudeCodeInstalled();
 
-  logger.info(`resume 命令执行，分支: ${options.branch}`);
+  logger.info(`resume 命令执行，分支: ${options.branch ?? '(未指定)'}`);
 
-  // 查找目标 worktree
-  const worktree = findWorktreeByBranch(options.branch);
+  // 解析目标 worktree（精确匹配 / 模糊匹配 / 交互选择）
+  const worktree = await resolveTargetWorktree(options.branch);
 
   // 启动 Claude Code 交互式界面
   launchInteractiveClaude(worktree);

package/src/commands/run.ts

@@ -8,6 +8,8 @@ import {
   validateMainWorktree,
   validateClaudeCodeInstalled,
   createWorktrees,
+  sanitizeBranchName,
+  checkBranchExists,
   spawnProcess,
   killAllChildProcesses,
   cleanupWorktrees,
@@ -191,6 +193,12 @@ async function handleRun(options: RunOptions): Promise<void> {
 
   // 未传 --tasks 时，创建单个 worktree 并打开 Claude Code 交互式界面
   if (!options.tasks || options.tasks.length === 0) {
+    // 分支已存在时，提示用户使用 resume 恢复会话
+    const sanitized = sanitizeBranchName(options.branch);
+    if (checkBranchExists(sanitized)) {
+      throw new ClawtError(MESSAGES.BRANCH_EXISTS_USE_RESUME(sanitized));
+    }
+
     const worktrees = createWorktrees(options.branch, 1);
     const worktree = worktrees[0];
     printSuccess(MESSAGES.WORKTREE_CREATED(1));

package/src/constants/messages.ts

@@ -8,6 +8,9 @@ export const MESSAGES = {
   CLAUDE_NOT_INSTALLED: 'Claude Code CLI 未安装，请先安装：npm install -g @anthropic-ai/claude-code',
   /** 分支已存在 */
   BRANCH_EXISTS: (name: string) => `分支 ${name} 已存在，无法创建`,
+  /** 分支已存在时提示使用 resume */
+  BRANCH_EXISTS_USE_RESUME: (name: string) =>
+    `分支 ${name} 已存在，请使用 clawt resume -b ${name} 恢复会话`,
   /** 分支名清理后为空 */
   BRANCH_NAME_EMPTY: (original: string) =>
     `分支名 "${original}" 中不包含合法字符，无法创建分支`,
@@ -107,4 +110,13 @@ export const MESSAGES = {
   /** 批量移除部分失败 */
   REMOVE_PARTIAL_FAILURE: (failures: Array<{ path: string; error: string }>) =>
     `以下 worktree 移除失败：\n${failures.map((f) => `  ✗ ${f.path}: ${f.error}`).join('\n')}`,
+  /** resume 无可用 worktree */
+  RESUME_NO_WORKTREES: '当前项目没有可用的 worktree，请先通过 clawt run 或 clawt create 创建',
+  /** resume 模糊匹配无结果，列出可用分支 */
+  RESUME_NO_MATCH: (name: string, branches: string[]) =>
+    `未找到与 "${name}" 匹配的分支\n  可用分支：\n${branches.map((b) => `    - ${b}`).join('\n')}`,
+  /** resume 交互选择提示 */
+  RESUME_SELECT_BRANCH: '请选择要恢复的分支',
+  /** resume 模糊匹配到多个结果提示 */
+  RESUME_MULTIPLE_MATCHES: (name: string) => `"${name}" 匹配到多个分支，请选择：`,
 } as const;

package/src/types/command.ts

@@ -40,8 +40,8 @@ export interface RemoveOptions {
 
 /** resume 命令选项 */
 export interface ResumeOptions {
-  /** 要恢复的分支名 */
-  branch: string;
+  /** 要恢复的分支名（可选，不传则列出所有分支供选择） */
+  branch?: string;
 }
 
 /** sync 命令选项 */
@@ -49,3 +49,9 @@ export interface SyncOptions {
   /** 要同步的分支名 */
   branch: string;
 }
+
+/** list 命令选项 */
+export interface ListOptions {
+  /** 以 JSON 格式输出 */
+  json?: boolean;
+}

package/src/types/index.ts

@@ -1,5 +1,5 @@
 export type { ClawtConfig, ConfigItemDefinition, ConfigDefinitions } from './config.js';
-export type { CreateOptions, RunOptions, ValidateOptions, MergeOptions, RemoveOptions, ResumeOptions, SyncOptions } from './command.js';
+export type { CreateOptions, RunOptions, ValidateOptions, MergeOptions, RemoveOptions, ResumeOptions, SyncOptions, ListOptions } from './command.js';
 export type { WorktreeInfo, WorktreeStatus } from './worktree.js';
 export type { ClaudeCodeResult } from './claudeCode.js';
 export type { TaskResult, TaskSummary } from './taskResult.js';