clawt 3.4.6 → 3.5.1

package/dist/postinstall.js

@@ -164,7 +164,22 @@ ${branches.map((b) => `    - ${b}`).join("\n")}`,
   /** merge 交互选择提示 */
   MERGE_SELECT_BRANCH: "\u8BF7\u9009\u62E9\u8981\u5408\u5E76\u7684\u5206\u652F",
   /** merge 模糊匹配到多个结果提示 */
-  MERGE_MULTIPLE_MATCHES: (name) => `"${name}" \u5339\u914D\u5230\u591A\u4E2A\u5206\u652F\uFF0C\u8BF7\u9009\u62E9\uFF1A`
+  MERGE_MULTIPLE_MATCHES: (name) => `"${name}" \u5339\u914D\u5230\u591A\u4E2A\u5206\u652F\uFF0C\u8BF7\u9009\u62E9\uFF1A`,
+  /** 询问是否使用 AI 辅助解决冲突 */
+  MERGE_CONFLICT_ASK_AI: "\u68C0\u6D4B\u5230\u5408\u5E76\u51B2\u7A81\uFF0C\u662F\u5426\u4F7F\u7528 Claude Code \u81EA\u52A8\u89E3\u51B3\uFF1F",
+  /** AI 冲突解决开始 */
+  MERGE_CONFLICT_AI_START: (fileCount) => `\u6B63\u5728\u4F7F\u7528 Claude Code \u5206\u6790\u5E76\u89E3\u51B3 ${fileCount} \u4E2A\u51B2\u7A81\u6587\u4EF6...`,
+  /** AI 冲突解决成功 */
+  MERGE_CONFLICT_AI_SUCCESS: "\u2713 Claude Code \u5DF2\u6210\u529F\u89E3\u51B3\u6240\u6709\u51B2\u7A81",
+  /** AI 冲突解决后仍有未解决的冲突 */
+  MERGE_CONFLICT_AI_PARTIAL: (remaining) => `Claude Code \u5DF2\u5904\u7406\u51B2\u7A81\u6587\u4EF6\uFF0C\u4F46\u4ECD\u6709 ${remaining} \u4E2A\u6587\u4EF6\u5B58\u5728\u51B2\u7A81
+  \u8BF7\u624B\u52A8\u5904\u7406\u5269\u4F59\u51B2\u7A81\u540E\u6267\u884C git add . && git merge --continue`,
+  /** AI 冲突解决失败 */
+  MERGE_CONFLICT_AI_FAILED: (errorMsg) => `Claude Code \u89E3\u51B3\u51B2\u7A81\u5931\u8D25: ${errorMsg}
+  \u8BF7\u624B\u52A8\u5904\u7406\uFF1A
+  \u89E3\u51B3\u51B2\u7A81\u540E\u6267\u884C git add . && git merge --continue`,
+  /** --auto 模式下的冲突手动解决（配置为 manual） */
+  MERGE_CONFLICT_MANUAL: "\u5408\u5E76\u5B58\u5728\u51B2\u7A81\uFF0C\u8BF7\u624B\u52A8\u5904\u7406\uFF1A\n  \u89E3\u51B3\u51B2\u7A81\u540E\u6267\u884C git add . && git merge --continue"
 };
 
 // src/constants/messages/validate.ts
@@ -490,6 +505,16 @@ var HOME_MESSAGES = {
   HOME_SWITCH_SUCCESS: (from, to) => `\u2713 \u5DF2\u4ECE ${from} \u5207\u6362\u5230\u4E3B\u5DE5\u4F5C\u5206\u652F ${to}`
 };
 
+// src/constants/messages/tasks.ts
+var TASKS_CMD_MESSAGES = {
+  /** 任务模板文件已存在 */
+  TASK_INIT_FILE_EXISTS: (path) => `\u6587\u4EF6\u5DF2\u5B58\u5728: ${path}\uFF0C\u5982\u9700\u8986\u76D6\u8BF7\u5148\u5220\u9664`,
+  /** 任务模板生成成功 */
+  TASK_INIT_SUCCESS: (path) => `\u2713 \u4EFB\u52A1\u6A21\u677F\u5DF2\u751F\u6210: ${path}`,
+  /** 任务模板使用提示 */
+  TASK_INIT_HINT: (path) => `\u4F7F\u7528 clawt run -f ${path} \u6267\u884C\u4EFB\u52A1`
+};
+
 // src/constants/messages/interactive-panel.ts
 import chalk from "chalk";
 
@@ -548,7 +573,8 @@ var MESSAGES = {
   ...COMPLETION_MESSAGES,
   ...INIT_MESSAGES,
   ...COVER_VALIDATE_MESSAGES,
-  ...HOME_MESSAGES
+  ...HOME_MESSAGES,
+  ...TASKS_CMD_MESSAGES
 };
 
 // src/constants/terminal.ts
@@ -592,6 +618,15 @@ var CONFIG_DEFINITIONS = {
   autoUpdate: {
     defaultValue: true,
     description: "\u662F\u5426\u542F\u7528\u81EA\u52A8\u66F4\u65B0\u68C0\u67E5\uFF08\u6BCF 24 \u5C0F\u65F6\u68C0\u67E5\u4E00\u6B21 npm registry\uFF09"
+  },
+  conflictResolveMode: {
+    defaultValue: "ask",
+    description: "merge \u51B2\u7A81\u65F6\u7684\u89E3\u51B3\u6A21\u5F0F\uFF1Aask\uFF08\u8BE2\u95EE\u662F\u5426\u4F7F\u7528 AI\uFF09\u3001auto\uFF08\u81EA\u52A8 AI \u89E3\u51B3\uFF09\u3001manual\uFF08\u624B\u52A8\u89E3\u51B3\uFF09",
+    allowedValues: ["ask", "auto", "manual"]
+  },
+  conflictResolveTimeoutMs: {
+    defaultValue: 3e5,
+    description: "Claude Code \u51B2\u7A81\u89E3\u51B3\u8D85\u65F6\u65F6\u95F4\uFF08\u6BEB\u79D2\uFF09\uFF0C\u9ED8\u8BA4 300000\uFF085 \u5206\u949F\uFF09"
   }
 };
 function deriveDefaultConfig(definitions) {

package/docs/alias.md

@@ -31,7 +31,7 @@ clawt alias remove <alias>
 
 **约束规则：**
 
-1. **别名不能覆盖内置命令名**：别名不能与任何已注册的内置命令同名（动态检测，当前包括 `list`、`create`、`remove`、`run`、`resume`、`validate`、`merge`、`config`、`sync`、`reset`、`status`、`alias`、`projects`、`completion`、`init`）。如果用户尝试设置与内置命令同名的别名，输出错误提示并返回
+1. **别名不能覆盖内置命令名**：别名不能与任何已注册的内置命令同名（动态检测，当前包括 `list`、`create`、`remove`、`run`、`resume`、`validate`、`cover`、`merge`、`config`、`sync`、`reset`、`status`、`alias`、`projects`、`completion`、`init`、`home`）。如果用户尝试设置与内置命令同名的别名，输出错误提示并返回
 2. **目标必须是内置命令**：别名的目标（`<command>`）必须是已注册的内置命令名。如果指定了不存在的目标命令，输出错误提示并返回
 3. **参数透传**：通过别名调用时，所有选项和参数会完全透传给目标命令，行为与直接调用目标命令完全一致
 
@@ -105,4 +105,10 @@ clawt alias list
 clawt alias remove l
 ```
 
+**实现要点：**
+
+- 消息常量定义在 `src/constants/messages/alias.ts`（`ALIAS_MESSAGES`），包括列表为空提示、设置/移除成功、别名不存在、与内置命令冲突、目标命令不存在等消息
+- 别名应用逻辑位于 `src/utils/alias.ts` 的 `applyAliases` 函数：在主入口 `src/index.ts` 中，所有命令注册完成后调用，遍历配置中的 `aliases` 映射，通过 Commander.js 的 `.alias()` 方法为对应命令注册别名。如果目标命令不存在则跳过并输出 warn 级别日志
+- 内置命令冲突检测通过 `getRegisteredCommandNames(program)` 动态获取所有已注册命令名，而非硬编码命令列表
+
 ---

package/docs/completion.md

@@ -37,7 +37,7 @@ clawt completion install
 | `-f` / `--file` 参数之后     | 动态列出匹配的文件和子目录（不限制文件类型，支持子目录递归浏览）    |
 | `config set` / `config get` 之后 | 动态列出所有配置项键名（从 `CONFIG_DEFINITIONS` 获取）         |
 | 输入以 `-` 开头              | 列出当前命令层级的可用选项（short/long）                       |
-| 其他情况                     | 列出当前命令层级的可用子命令及别名                              |
+| 其他情况                     | 列出当前命令层级的可用子命令及别名；若输入为空，同时列出可用选项    |
 
 **文件路径补全细节：**
 - 支持子目录递归浏览（如 `tasks/` 后继续 Tab 可深入子目录）

package/docs/config.md

@@ -25,7 +25,7 @@ clawt config reset
 1. 读取全局配置文件 `~/.clawt/config.json`
 2. 列出所有配置项供用户选择（`Enquirer.Select`），每项显示：
    - 配置项名称
-   - 当前值（布尔值绿色/黄色，字符串青色）
+   - 当前值（布尔值绿色/黄色，字符串和数字青色）
    - 配置项描述（暗淡色 dim）
    - 对象类型配置项（如 `aliases`）标灰不可选，提示用户通过专用命令管理
 3. 用户选择某个配置项后，根据值类型自动选择提示策略：
@@ -86,7 +86,8 @@ clawt config reset
 - 配置项类型定义：`ConfigItemDefinition` 新增可选字段 `allowedValues`（`readonly string[]`），仅对 string 类型有效，用于枚举值校验和交互式 Select 提示
 - 值解析与提示策略：`src/utils/config-strategy.ts` 中的 `parseConfigValue()`（CLI 字符串解析）和 `promptConfigValue()`（交互式提示），基于类型和 `allowedValues` 自动分发
 - 交互式配置编辑：`handleInteractiveConfigSet` 调用通用的 `interactiveConfigEditor`（`src/utils/config-strategy.ts`），传入 `CONFIG_DEFINITIONS` 和 `disabledKeys`（对象类型配置项禁用映射），不再在 config 命令中直接构建选择列表和调用 `promptConfigValue`
-- `saveConfig(config)`：`src/utils/config.ts` 中新增的通用配置写入函数，将完整配置对象持久化到文件
-- `formatConfigValue(value)`：支持 boolean（绿色/黄色）和 string/number（青色）的格式化显示。`undefined` / `null` 值显示为暗淡色的 `(未设置)`。对象类型配置项（如 `aliases`）在交互式列表中通过 `JSON.stringify` 以暗淡色显示
+- `saveConfig(config)`：`src/utils/config.ts` 中的通用配置写入函数，将完整配置对象持久化到文件
+- `formatConfigValue(value)`：支持 boolean（绿色/黄色）和 string/number（青色）的格式化显示。`undefined` / `null` 值显示为暗淡色的 `(未设置)`
+- 对象类型配置项（如 `aliases`）的显示逻辑在 `interactiveConfigEditor` 的列表构建中处理：通过 `JSON.stringify` 以暗淡色显示值，并标记为不可选（disabled），提示用户通过 `clawt alias` 命令管理
 
 ---

package/docs/cover-validate.md

@@ -20,9 +20,10 @@ clawt cover
 
 ##### 步骤 1：前置校验
 
-1. **主 worktree 校验**（2.1）
-2. **项目级配置校验**（`requireProjectConfig`）
-3. **验证分支校验**：当前分支必须以 `clawt-validate-` 开头，否则报错退出
+1. **主 worktree 校验**（`requireMainWorktree`）
+2. **HEAD 校验**（`requireHead`）
+3. **项目级配置校验**（`requireProjectConfig`）
+4. **验证分支校验**：当前分支必须以 `clawt-validate-` 开头，否则报错退出
 
 ##### 步骤 2：查找目标 worktree
 

package/docs/create.md

@@ -10,20 +10,25 @@ clawt create -b <branchName> [-n <count>]
 
 | 参数 | 必填 | 说明                                                  |
 | ---- | ---- | ----------------------------------------------------- |
-| `-b` | 是   | 分支名                                                |
-| `-n` | 否   | 需要创建的 worktree 数量，默认 `1`                      |
+| `-b, --branch` | 是   | 分支名                                                |
+| `-n, --number` | 否   | 需要创建的 worktree 数量，默认 `1`                      |
 
 **运行流程：**
 
-1. **主 worktree 校验** (2.1)
-2. **确保在主工作分支上**（`ensureOnMainWorkBranch`）：在创建 worktree 之前，确保当前处于配置的主工作分支（`clawtMainWorkBranch`）上。
+通过 `runPreChecks(PRE_CHECK_CREATE)` 执行统一前置校验，包含以下检查项：
+
+1. **主 worktree 校验**（`requireMainWorktree`）(2.1)
+2. **HEAD 存在性校验**（`requireHead`）：确保仓库有至少一次 commit
+3. **确保在主工作分支上**（`ensureOnClawtMainWorkBranch`）：在创建 worktree 之前，确保当前处于配置的主工作分支（`clawtMainWorkBranch`）上。
    - 如果当前分支**是** `clawtMainWorkBranch`，正常继续
    - 如果当前在**验证分支**（`clawt-validate-` 前缀）上：
      - 验证分支上的修改视为可丢弃的临时状态
      - 如果工作区有未提交更改，自动执行 `git reset --hard HEAD && git clean -fd` 清理；若已干净则跳过清理
      - 然后自动切换到主工作分支，继续创建流程
    - 如果当前在**其他普通分支**上：
-     - 如果工作区有未提交的更改，提供交互式选择（避免将修改意外带到主工作分支上）：
+     - 首先显示警告：`当前分支 <currentBranch> 与配置的主工作分支 <mainBranch> 不一致，如需更新请执行 clawt init`
+     - 然后通过 `confirmAction('是否继续执行？')` 让用户确认是否继续；用户拒绝则抛出"已取消操作"退出
+     - 用户确认后，如果工作区有未提交的更改，提供交互式选择（避免将修改意外带到主工作分支上）：
        ```
        ⚠ 当前分支有未提交的更改，请选择处理方式：
 
@@ -33,16 +38,17 @@ clawt create -b <branchName> [-n <count>]
        ```
        - 选择 reset → 执行 `git reset --hard HEAD && git clean -fd`
        - 选择 stash → 执行 `git add . && git stash push -m "clawt:auto-stash"`
-       - 选择 exit → 抛出错误退出
-       - 处理完成后再次校验工作区是否干净，不干净则报错退出
+       - 选择 exit → 抛出错误"用户选择退出，请手动处理工作区更改后重试"
+       - 处理完成后再次校验工作区是否干净，不干净则报错"工作区仍然不干净，请手动处理"
      - 执行 `git checkout <clawtMainWorkBranch>`，然后继续创建流程
-3. **创建数量校验**：校验 `-n` 参数必须为正整数，否则报错 `无效的创建数量: "<value>"，请输入正整数`
-4. **分支名合法性校验与转换** (2.3)
-5. **分支名存在性校验** (2.4)
+4. **主分支工作区干净校验**（`requireCleanWorkingDir`）：确保主工作分支的工作区和暂存区干净，存在未提交更改时报错"主 worktree 有未提交的更改，请先处理"
+5. **创建数量校验**：校验 `-n` 参数必须为正整数，否则报错 `无效的创建数量: "<value>"，请输入正整数`
+6. **分支名合法性校验与转换** (2.3)
+7. **分支名存在性校验** (2.4)
    - 若 `n = 1`：校验 `branchName`
    - 若 `n > 1`：校验 `branchName-1` 到 `branchName-n`
    - 所有分支名在创建任何 worktree **之前**完成全部校验
-6. **批量创建 worktree + 验证分支**
+8. **批量创建 worktree + 验证分支**
    - 若 `n = 1`：
      ```bash
      git worktree add -b <branchName> ~/.clawt/worktrees/<project>/<branchName>
@@ -58,7 +64,7 @@ clawt create -b <branchName> [-n <count>]
      git worktree add -b <branchName>-n ~/.clawt/worktrees/<project>/<branchName>-n
      git branch clawt-validate-<branchName>-n
      ```
-7. **输出创建日志**
+9. **输出创建日志**
 
 **输出格式：**
 
@@ -82,4 +88,14 @@ clawt create -b <branchName> [-n <count>]
 ────────────────────────────────────────
 ```
 
+**实现要点：**
+
+- 前置校验配置定义在 `src/constants/pre-checks.ts` 的 `PRE_CHECK_CREATE` 常量中
+- 分支名清理逻辑在 `src/utils/branch.ts` 的 `sanitizeBranchName` 中
+- 分支名生成逻辑在 `src/utils/branch.ts` 的 `generateBranchNames` 中
+- worktree 批量创建逻辑在 `src/utils/worktree.ts` 的 `createWorktrees` 中
+- 确保在主工作分支的逻辑在 `src/utils/validate-branch.ts` 的 `ensureOnMainWorkBranch` 中
+- 脏工作区交互处理逻辑在 `src/utils/validate-branch.ts` 的 `handleDirtyWorkingDir` 中
+- 相关消息常量定义在 `src/constants/messages/create.ts` 和 `src/constants/messages/common.ts` 中
+
 ---

package/docs/home.md

@@ -16,21 +16,24 @@ clawt home
 
 **运行流程：**
 
-1. **主 worktree 校验** (2.1)
-2. **项目级配置校验**：调用 `requireProjectConfig()` 检查项目是否已初始化
-3. **获取分支信息**：
+1. **前置校验**：调用 `runPreChecks` 执行统一前置校验：
+   - `requireMainWorktree`：校验当前目录是否在主 worktree 根目录 (2.1)
+   - `requireHead`：校验 HEAD 是否存在（仓库至少有一次 commit）
+   - `requireProjectConfig`：校验项目配置文件是否存在且合法
+   - `requireMainBranchExists`：校验配置中的主工作分支在 git 仓库中是否存在
+2. **获取分支信息**：
    - 通过 `getMainWorkBranch()` 获取主工作分支名
    - 通过 `getCurrentBranch()` 获取当前所在分支名
-4. **判断是否需要切换**：
+3. **判断是否需要切换**：
    - 当前分支 === 主工作分支 → 输出提示信息，无需切换
    - 当前分支 !== 主工作分支 → 调用 `ensureOnMainWorkBranch()` 执行切换
-5. **输出结果**
+4. **输出结果**
 
 **输出格式：**
 
 ```
 # 已在主工作分支上
-ℹ 已在主工作分支 main 上，无需切换
+已在主工作分支 main 上，无需切换
 
 # 切换成功
 ✓ 已从 clawt-validate-feat-login 切换到主工作分支 main
@@ -48,7 +51,8 @@ clawt home
 **实现要点：**
 
 - 命令注册函数 `registerHomeCommand` 位于 `src/commands/home.ts`
-- 依赖 `validateMainWorktree`、`requireProjectConfig`、`ensureOnMainWorkBranch`、`getCurrentBranch`、`getMainWorkBranch` 等工具函数
-- `requireProjectConfig()` 为显式调用，因为 home 命令不经过 `ensureOnMainWorkBranch()` 的隐式校验路径（仅在需要切换时才调用 `ensureOnMainWorkBranch()`）
+- 前置校验通过 `runPreChecks` 统一调用，传入 `requireMainWorktree`、`requireHead`、`requireProjectConfig`、`requireMainBranchExists` 四项校验
+- 主逻辑依赖 `ensureOnMainWorkBranch`、`getCurrentBranch`、`getMainWorkBranch`、`guardMainWorkBranchExists` 等工具函数
+- `ensureOnMainWorkBranch()` 仅在需要切换时才调用（当前分支不等于主工作分支时）
 
 ---

package/docs/init.md

@@ -27,20 +27,24 @@ clawt init show
 **运行流程（设置模式）：**
 
 1. **主 worktree 校验** (2.1)
-2. **确定主工作分支名**：
+2. **加载现有配置**：尝试读取 `~/.clawt/projects/<projectName>/config.json`（可能为 `null`）
+3. **确定主工作分支名**：
    - 传了 `-b` → 使用指定的分支名
-   - 未传 `-b` → 使用当前分支名（`git rev-parse --abbrev-ref HEAD`）
-3. **写入项目级配置**：将 `clawtMainWorkBranch` 写入 `~/.clawt/projects/<projectName>/config.json`
-   - 配置文件不存在 → 创建
-   - 配置文件已存在 → 覆盖整个配置文件内容
-4. **输出成功提示**
+   - 未传 `-b` → 先验证 HEAD 存在，再使用当前分支名（`git rev-parse --abbrev-ref HEAD`）
+4. **合并并写入项目级配置**：将 `clawtMainWorkBranch` 合并到现有配置并写入 `~/.clawt/projects/<projectName>/config.json`
+   - 配置文件不存在 → 创建新配置
+   - 配置文件已存在 → 合并现有配置，仅更新 `clawtMainWorkBranch` 字段（保留其他配置项不变）
+5. **输出成功提示**：
+   - 已有配置 → `✓ 已将主工作分支从 <旧分支> 更新为 <新分支>`
+   - 无已有配置 → `✓ 项目初始化成功，主工作分支设置为: <分支名>`
 
 **运行流程（show 模式）：**
 
 1. **主 worktree 校验** (2.1)
-2. **读取项目级配置**：读取 `~/.clawt/projects/<projectName>/config.json`
+2. **项目配置校验**（`requireProjectConfig`）：读取 `~/.clawt/projects/<projectName>/config.json`
    - 配置不存在 → 抛出错误 `项目尚未初始化，请先执行 clawt init 设置主工作分支`
-   - 配置存在 → 进入交互式面板
+   - 配置缺少 `clawtMainWorkBranch` 字段 → 抛出错误 `项目配置缺少主工作分支信息，请重新执行 clawt init 设置主工作分支`
+   - 配置存在且合法 → 进入交互式面板
 3. **交互式配置编辑**：调用 `interactiveConfigEditor`（`src/utils/config-strategy.ts`），基于 `PROJECT_CONFIG_DEFINITIONS` 构建配置项列表（详见 [project-config.md](./project-config.md)）
    - 列出所有项目配置项，显示名称、当前值和描述
    - 用户选择配置项后，根据值类型自动选择输入方式（与全局配置的交互式编辑逻辑一致）
@@ -61,9 +65,12 @@ clawt init show
 
 # show 未初始化（抛出错误）
 项目尚未初始化，请先执行 clawt init 设置主工作分支
+
+# show 配置缺少主工作分支字段（抛出错误）
+项目配置缺少主工作分支信息，请重新执行 clawt init 设置主工作分支
 ```
 
-**重复执行：** 支持重复执行，后一次覆盖前一次的配置。
+**重复执行：** 支持重复执行，后一次会合并到现有配置中更新 `clawtMainWorkBranch`，不影响其他配置项。
 
 **实现要点：**
 

package/docs/list.md

@@ -16,11 +16,10 @@ clawt list [--json]
 
 1. **主 worktree 校验** (2.1)
 2. **获取项目名** (2.2)
-3. 扫描 `~/.clawt/worktrees/<project>/` 目录
-4. 对每个子目录，验证是否为有效的 git worktree（`git worktree list` 交叉验证）
-5. 根据 `--json` 选项决定输出格式：
-   - 指定 `--json` → 以 JSON 格式输出
-   - 未指定 → 以文本格式输出
+3. 获取项目的所有 worktree 列表（扫描 `~/.clawt/worktrees/<project>/` 目录，与 `git worktree list` 交叉验证）
+4. 根据 `--json` 选项决定输出格式：
+   - 指定 `--json` → 以 JSON 格式输出（仅包含 path 和 branch）
+   - 未指定 → 以文本格式输出（包含变更状态信息）
 
 **文本输出格式（默认）：**
 
@@ -30,9 +29,16 @@ clawt list [--json]
 当前项目: main-project
 
   ~/.clawt/worktrees/main-project/feature-scheme-1   [feature-scheme-1]
+    3 个提交   +120 -30   (未提交修改)
+
   ~/.clawt/worktrees/main-project/feature-scheme-2   [feature-scheme-2]
-  ~/.clawt/worktrees/main-project/feature-scheme-3   [feature-scheme-3]
-  ~/.clawt/worktrees/main-project/bugfix-login        [bugfix-login]
+    1 个提交   +45 -10
+
+  ~/.clawt/worktrees/main-project/feature-scheme-3   [feature-scheme-3]    ← 橙色路径（空闲）
+    0 个提交   无变更
+
+  ~/.clawt/worktrees/main-project/bugfix-login   [bugfix-login]
+    2 个提交   +80 -25
 
 共 4 个 worktree
 ```

package/docs/merge.md

@@ -33,26 +33,26 @@ clawt merge [-m <commitMessage>]
         - 唯一匹配 → 直接使用
         - 多个匹配 → 通过交互式列表让用户从匹配结果中选择
      3. **无匹配** → 报错退出，并列出所有可用分支名
-3. **主 worktree 状态检测**
+4. **主 worktree 状态检测**
    - 执行 `git status --porcelain`
    - 如果有更改：
      - 如果存在该分支的 validate 快照（`~/.clawt/validate-snapshots/<project>/<branchName>.tree`），额外输出警告 `主 worktree 可能存在 validate 残留状态，可先执行 clawt validate -b <branchName> --clean 清理`
      - 提示 `主 worktree 有未提交的更改，请先处理`，退出
    - 无更改 → 继续
-4. **Squash 检测与执行（auto-save 临时提交压缩）**
+5. **Squash 检测与执行（auto-save 临时提交压缩）**
    - 通过 `git log HEAD..<branchName> --format=%s` 检查目标分支是否存在以 `AUTO_SAVE_COMMIT_MESSAGE`（`chore: auto-save before sync`）为前缀的 commit
-   - **不存在** → 跳过，进入步骤 5
+   - **不存在** → 跳过，进入步骤 6
    - **存在** → 提示用户是否将所有提交压缩为一个：
      ```
      检测到 sync 产生的临时提交，是否将所有提交压缩为一个？
        压缩后变更将保留在目标worktree的暂存区，需要重新提交（可使用 Claude Code Cli或其他工具生成提交信息）
      ```
-   - **用户选择不压缩** → 跳过，进入步骤 5
+   - **用户选择不压缩** → 跳过，进入步骤 6
    - **用户选择压缩** →
      1. 获取主分支名（从项目级配置 `clawtMainWorkBranch` 获取）
      2. 计算分叉点：`git merge-base <mainBranch> <branchName>`
      3. 在目标 worktree 中执行 `git reset --soft <merge-base>`，将所有 commit 撤销到暂存区
-     4. 如果用户提供了 `-m` → 直接在目标 worktree 执行 `git commit -m '<commitMessage>'`，输出成功提示，继续步骤 5
+     4. 如果用户提供了 `-m` → 直接在目标 worktree 执行 `git commit -m '<commitMessage>'`，输出成功提示，继续步骤 6
      5. 如果用户未提供 `-m` → 提示用户前往目标 worktree 自行提交后重新执行 `clawt merge`：
         ```
         ✓ 已将所有提交压缩到暂存区
@@ -61,7 +61,7 @@ clawt merge [-m <commitMessage>]
           提交完成后执行：clawt merge -b <branch>
         ```
         **退出流程**
-5. **根据目标 worktree 状态决定是否需要提交**
+6. **根据目标 worktree 状态决定是否需要提交**
    - 检测目标 worktree 工作区是否干净（`git status --porcelain`）
    - **工作区有未提交修改**：
      - 如果用户未提供 `-m`，提示 `<worktreePath> 有未提交的修改，请通过 -m 参数提供提交信息`（其中 `<worktreePath>` 为目标 worktree 的完整路径），退出
@@ -75,23 +75,23 @@ clawt merge [-m <commitMessage>]
      - 检查目标分支相对于主分支是否有本地提交（`git log HEAD..<branchName> --oneline`）
      - 有本地提交 → 跳过提交步骤，直接进入合并
      - 无本地提交 → 提示 `目标 worktree 没有任何可合并的变更（工作区干净且无本地提交）`，退出
-6. **回到主 worktree 进行合并**
+7. **回到主 worktree 进行合并**
    ```bash
    cd <主 worktree 路径>
    git merge <branchName>
    ```
-7. **冲突检测**（双层机制）
+8. **冲突检测**（双层机制）
    - **try-catch 层**：`git merge` 抛出异常时，先检查是否有冲突，有冲突则报错退出，否则重新抛出原始异常
    - **二次确认层**：即使 merge 未抛异常，也再次检查是否有合并冲突
    - **有冲突** → 提示 `合并存在冲突，请手动处理：\n  解决冲突后执行 git add . && git merge --continue`，退出
    - **无冲突** → 继续
-8. **推送（受 `autoPullPush` 配置控制）**
+9. **推送（受 `autoPullPush` 配置控制）**
    - `autoPullPush` 为 `false` → 输出提示 `已跳过自动 pull/push，请手动执行 git pull && git push`
    - `autoPullPush` 为 `true` → 执行 `git pull` + `git push`：
      - `git pull` 失败且有冲突 → 输出警告 `自动 pull 时发生冲突，merge 已完成但远程同步失败`，退出（不再 push）
      - `git pull` 失败且无冲突 → 抛出错误
      - `git push` 失败 → 输出警告 `自动 push 失败，merge 和 pull 已完成\n  请手动执行 git push`，退出
-9. **输出成功提示**
+10. **输出成功提示**
 
 ```
 # 提供了 -m 且已推送时
@@ -111,7 +111,7 @@ clawt merge [-m <commitMessage>]
 ✓ 分支 feature-scheme-1 已成功合并到当前分支
 ```
 
-10. **merge 成功后确认并清理 worktree 和分支（可选）**
+11. **merge 成功后确认并清理 worktree 和分支（可选）**
    - 如果配置文件中 `autoDeleteBranch` 为 `true`，自动执行清理
    - 否则交互式询问用户是否清理
    - 用户确认后，依次执行：
@@ -129,7 +129,7 @@ clawt merge [-m <commitMessage>]
    - 输出清理成功提示：`✓ 已清理 worktree 和分支: <branchName>`
    - 验证分支的删除时机与目标分支保持一致（见 [2.5 验证分支生命周期](#25-验证分支)）：用户确认清理 → 同步删除验证分支；用户拒绝清理 → 验证分支也保留
 
-11. **清理 validate 快照**
+12. **清理 validate 快照**
     - merge 成功后，如果存在该分支的 validate 快照（`~/.clawt/validate-snapshots/<project>/<branchName>.tree` 和 `<branchName>.head`），自动删除这些快照文件（merge 成功后快照已无意义）
 
 > **注意：** 清理确认和清理操作均在 merge 成功后执行。只有 merge 成功才会询问用户是否清理 worktree 和分支，避免 merge 冲突时用户被提前询问造成困惑。

package/docs/remove.md

@@ -24,7 +24,10 @@ clawt remove
 
 **运行流程：**
 
-1. **主 worktree 校验** (2.1)
+1. **前置校验**：
+   - 主 worktree 校验 (2.1)
+   - HEAD 存在性校验
+   - 项目配置文件校验（确保项目已通过 `clawt init` 初始化）
 2. **获取项目名** (2.2)
 3. **确定待移除的 worktree 列表**：
    - **指定 `--all`** → 选中当前项目所有 worktree（若当前项目无 worktree，则提示并退出）
@@ -39,7 +42,8 @@ clawt remove
           - 唯一匹配 → 直接使用
           - 多个匹配 → 通过交互式多选列表让用户从匹配结果中选择
        3. **无匹配** → 报错退出，并列出所有可用分支名
-4. 列出即将移除的 worktree 及对应分支：
+4. **当前分支安全检查**：逐个检查待移除的分支，如果该分支或其对应的验证分支（`clawt-validate-<branchName>`）是主 worktree 当前所在分支，则抛出错误并阻止移除。
+5. 列出即将移除的 worktree 及对应分支：
 
 ```
 即将移除以下 worktree 及本地分支：
@@ -51,29 +55,36 @@ clawt remove
 是否同时删除对应的本地分支和验证分支？(y/N)
 ```
 
-5. 用户确认后（只需确认一次），对每个 worktree 依次执行（单个失败不影响其他）：
+6. **判断是否删除本地分支**：
+   - 如果配置文件 `~/.clawt/config.json` 中 `autoDeleteBranch` 为 `true`，则跳过询问，直接删除分支
+   - 否则询问用户是否删除，用户拒绝时提示可稍后手动删除
+7. 对每个 worktree 依次执行（单个失败不影响其他）：
 
 ```bash
-# 确保当前处于主工作分支上（若不在则自动切回）
-git checkout <clawtMainWorkBranch>
-
 # 移除 worktree
 git worktree remove -f <worktree路径>
 
-# 如果用户选择了删除分支
+# 如果用户选择了删除分支（或 autoDeleteBranch 为 true）
 git branch -D <branchName>
 
-# 无条件删除验证分支和清理快照（不受用户确认控制）
+# 无条件删除验证分支（不受用户确认控制，存在则删除）
 git branch -D clawt-validate-<branchName>
-# 清理该分支对应的 validate 快照
+# 无条件清理该分支对应的 validate 快照
 ```
 
-6. 如果配置文件 `~/.clawt/config.json` 中 `autoDeleteBranch` 为 `true`，则跳过询问，直接删除分支。
+8. 如果使用 `--all` 模式，额外清理整个项目的 validate 快照目录。
+
+9. 移除完成后执行清理：
+   - `git worktree prune` 清理已失效的 worktree 引用
+   - 如果 `~/.clawt/worktrees/<project>/` 下已无 worktree，则删除该项目目录
 
-7. 如果使用 `--all` 模式，额外清理整个项目的 validate 快照目录。
+10. 批量移除时，单个 worktree 移除失败不会中断整个流程，而是收集所有失败项，最后汇总报告并以错误状态退出（抛出 ClawtError）。
 
-8. 移除完成后，清理空目录（如果 `~/.clawt/worktrees/<project>/` 下已无 worktree，则删除该项目目录）。
+**实现要点：**
 
-9. 批量移除时，单个 worktree 移除失败不会中断整个流程，而是收集所有失败项，最后汇总报告并以错误状态退出（抛出 ClawtError）。
+- 消息常量定义在 `src/constants/messages/remove.ts`
+- 分支解析逻辑复用公共模块 `resolveTargetWorktrees`（`src/utils/worktree-matcher.ts`）
+- 验证分支删除通过 `deleteValidateBranch`（`src/utils/validate-branch.ts`），内部判断分支是否存在后才执行删除
+- 快照清理通过 `removeSnapshot` 和 `removeProjectSnapshots`（`src/utils/validate-snapshot.ts`）
 
 ---

package/docs/reset.md

@@ -16,12 +16,14 @@ clawt reset
 
 **运行流程：**
 
-1. **主 worktree 校验** (2.1)
-2. **项目级配置校验**（`requireProjectConfig()`，因 reset 不调用 `ensureOnMainWorkBranch`，需自行校验）
-3. **检测工作区状态**：通过 `git status --porcelain` 检测主 worktree 是否有未提交的更改
+1. **前置校验**（`runPreChecks`）：
+   - `requireMainWorktree`：主 worktree 校验 (2.1)
+   - `requireHead`：HEAD 存在校验
+   - `requireProjectConfig`：项目级配置校验
+2. **检测工作区状态**：通过 `git status --porcelain` 检测主 worktree 是否有未提交的更改
    - **工作区干净** → 输出提示 `主 worktree 工作区和暂存区已是干净状态，无需重置`，退出
    - **工作区不干净** → 继续
-3. **确认破坏性操作**：如果配置项 `confirmDestructiveOps` 为 `true`，提示确认（显示即将执行的危险指令和操作后果），用户取消则退出
+3. **确认破坏性操作**：如果配置项 `confirmDestructiveOps` 为 `true`，提示确认（显示即将执行的危险指令 `git reset --hard + git clean -fd` 和操作后果 `丢弃所有未提交的更改`），用户取消则输出 `已取消操作` 并退出
 4. **重置工作区和暂存区**：
    ```bash
    git reset --hard HEAD

package/docs/resume.md

@@ -22,9 +22,8 @@ clawt resume
 
 **运行流程：**
 
-1. **主 worktree 校验** (2.1)
-2. **Claude Code CLI 校验**：确认 `claude` CLI 可用
-3. **解析目标 worktree**：根据是否传入 `-b` 参数以及 worktree 数量，采用不同的解析策略：
+1. **前置校验**（`PRE_CHECK_RESUME`）：主 worktree 校验 (2.1) + HEAD 存在性校验 + Claude Code CLI 可用性校验
+2. **解析目标 worktree**：根据是否传入 `-b` 参数以及 worktree 数量，采用不同的解析策略：
    - **未传 `-b` 参数**：
      - 获取当前项目所有 worktree
      - 无可用 worktree → 报错退出
@@ -36,7 +35,7 @@ clawt resume
         - 唯一匹配 → 直接使用
         - 多个匹配 → 通过交互式多选列表让用户从匹配结果中选择
      3. **无匹配** → 报错退出，并列出所有可用分支名
-4. **根据选中数量自动分发**：
+3. **根据选中数量自动分发**：
    - **用户未选择任何分支** → 直接退出
    - **选中 1 个** → 根据全局配置项 `resumeInPlace` 决定打开方式：
      - `resumeInPlace: true` → 在当前终端就地恢复，通过 `launchInteractiveClaude()` 启动（使用 `spawnSync` + `inherit stdio`）