clawt 2.19.0 → 3.0.0

package/docs/log.md

@@ -0,0 +1,67 @@
+### 5.9 日志系统
+
+**日志目录：** `~/.clawt/logs/`
+
+**日志文件命名：** `clawt-YYYY-MM-DD.log`（按日期滚动）
+
+**日志级别：**
+
+| 级别    | 说明               | 使用场景                               |
+| ------- | ------------------ | -------------------------------------- |
+| `debug` | 调试信息           | Git 命令执行详情、变量值等               |
+| `info`  | 一般信息           | 操作开始/完成、创建/移除 worktree 等     |
+| `warn`  | 警告信息           | 分支名被转换、非致命异常等              |
+| `error` | 错误信息           | 命令执行失败、校验不通过等               |
+
+**实现方案：** 使用 `winston` + `winston-daily-rotate-file` 库。
+
+**日志格式：**
+
+```
+[2025-02-06 14:30:22] [INFO ] 创建 worktree: ~/.clawt/worktrees/main-project/feature-scheme-1
+[2025-02-06 14:30:22] [DEBUG] 执行命令: git worktree add -b feature-scheme-1 ~/.clawt/worktrees/main-project/feature-scheme-1
+[2025-02-06 14:30:23] [WARN ] 分支名已转换: feature/a.b → feature-a-b
+[2025-02-06 14:30:25] [ERROR] 分支 feature-scheme-1 已存在，无法创建
+```
+
+**保留策略：**
+
+- 日志文件保留 30 天
+- 单个日志文件最大 10MB
+
+#### `--debug` 控制台调试输出
+
+通过全局选项 `--debug` 可将调试日志实时输出到终端，方便排查问题。
+
+**实现机制：**
+
+- 在 Commander.js 的 `preAction` 钩子中检测 `--debug` 选项，按需调用 `enableConsoleTransport()` 函数
+- `enableConsoleTransport()` 动态向 winston 实例添加 `Console` transport（level 为 `debug`），该函数幂等，多次调用不会重复添加 transport
+- 相关常量定义在 `src/constants/logger.ts`：
+  - `DEBUG_TIMESTAMP_FORMAT`：时间戳格式（`HH:mm:ss.SSS`，精简，不含日期）
+
+**控制台日志格式：**
+
+```
+HH:mm:ss.SSS LEVEL 消息内容
+```
+
+**日志级别颜色映射：**
+
+| 级别    | 颜色   |
+| ------- | ------ |
+| `error` | 红色   |
+| `warn`  | 黄色   |
+| `info`  | 青色   |
+| `debug` | 灰色   |
+
+**使用示例：**
+
+```bash
+clawt run -b feature-login --debug
+clawt validate -b feature-scheme --debug
+```
+
+> **注意：** `--debug` 选项不影响文件日志（file transport），文件日志始终按原有策略写入。控制台输出仅在传入 `--debug` 时启用。
+
+---

package/docs/merge.md

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

package/docs/notification.md

@@ -0,0 +1,94 @@
+### 5.3 任务完成通知机制
+
+**触发条件：** 通过 `clawt run` 启动了多个 Claude Code 任务后自动进入通知模式。
+
+**机制说明：**
+
+Claude Code CLI 以 `--output-format stream-json --verbose` 运行时，stdout 会持续输出 JSON 行（每行一个事件），包括 `system`、`assistant`（含 `tool_use` 和 `text`）、`user`（含 `tool_result`）等类型。任务结束时输出 `type: "result"` 事件：
+
+```json
+{
+  "type": "result",
+  "subtype": "success",
+  "is_error": false,
+  "duration_ms": 182809,
+  "duration_api_ms": 0,
+  "num_turns": 1,
+  "result": "xxx",
+  "stop_reason": "stop_sequence",
+  "session_id": "e771e449-b695-48e7-8006-bbf3f0dd3e98",
+  "total_cost_usd": 0,
+  "usage": { ... }
+}
+```
+
+**流式事件解析（`src/utils/stream-parser.ts`）：**
+
+由于 stdout 的 `data` 事件可能在行中间切割，使用 `createLineBuffer()` 行缓冲器拼接完整行后，通过 `parseStreamLine()` 解析为 `StreamEvent` 对象，再由 `parseStreamEvent()` 提取活动信息（`ParsedActivity`）：
+
+- **`tool_use` 类型**：提取工具名和文件路径/命令参数，格式如 `Read index.ts`、`Bash ls -la`
+- **`text` 类型**：提取文本片段，格式如 `思考中: 让我分析一下`
+- **`result` 类型**：构造 `ClaudeCodeResult` 对象，提取耗时、费用、结果文本等
+
+活动描述文本最大长度为 `ACTIVITY_TEXT_MAX_LENGTH`（30 字符），超出后截断并追加省略号。结果预览文本最大长度为 `RESULT_PREVIEW_MAX_LENGTH`（40 字符）。
+
+**事件监听与通知流程：**
+
+1. 为每个 Claude Code 子进程维护状态（运行中 / 已完成 / 已失败）
+2. 监听每个子进程的 `close` 事件（基于 Node.js `ChildProcess` 的事件驱动机制）
+3. 在流式传输过程中实时解析每一行事件，当遇到 `type=result` 时保存到 `finalResult`；子进程触发 `close` 事件时，flush 行缓冲器并组装最终结果
+4. 在主 worktree 的 clawt 终端实时输出通知。TTY 环境下使用进度面板，进度面板每个任务行第二列显示 worktree 路径（终端可点击跳转），运行中显示实时活动描述，完成/失败后显示结果预览。任务行格式示例：
+
+```
+[1/3] /path/to/worktree  ⠹ 运行中 1m23s  Read index.ts
+[2/3] /path/to/worktree  ✓ 完成   2m05s  $0.08  任务已成功完成
+[3/3] /path/to/worktree  ◦ 排队中
+```
+
+5. 先完成的先通知，**不需要**失败重试机制
+6. 当所有任务完成后，输出汇总信息：
+
+```
+════════════════════════════════════════
+全部任务已完成 (3/3)
+  成功: 2
+  失败: 1
+  总耗时: 245.3s
+  总花费: $0.15
+════════════════════════════════════════
+```
+
+#### 进度面板渲染机制
+
+进度面板由 `ProgressRenderer`（`src/utils/progress.ts`）负责渲染，渲染函数拆分到 `src/utils/progress-render.ts`。
+
+**TTY 模式渲染策略（备选屏幕缓冲区）：**
+
+- **进入备选屏幕**：`start()` 时通过 `ALT_SCREEN_ENTER`（`\x1B[?1049h`）进入终端备选屏幕缓冲区，隔离进度面板与主屏幕内容
+- **禁用行换行**：通过 `LINE_WRAP_DISABLE`（`\x1B[?7l`）防止超长行自动折行，配合按终端宽度截断保证每行只占一行
+- **每帧渲染**：使用 `CLEAR_SCREEN` + `CURSOR_HOME` 清屏后完全重绘，无需计算 `CURSOR_UP` 回退量，不受终端 reflow 影响
+- **防闪烁**：每帧渲染使用 Synchronized Output（`SYNC_OUTPUT_START` / `SYNC_OUTPUT_END`），终端缓冲全部输出后一次性刷新
+- **行宽截断**：通过 `truncateToTerminalWidth()`（`src/utils/progress-render.ts`）将含 ANSI 转义码的字符串截断到终端可见列数，使用 `string-width` 库正确计算中文/emoji 宽度
+- **终端 resize 响应**：监听 `process.stdout` 的 `resize` 事件，窗口宽度变化时立即触发重绘
+- **退出时恢复**：`stop()` 时恢复行换行、显示光标、退出备选屏幕，然后在主屏幕上重新输出最终面板状态（备选屏幕内容不保留）
+- **异常退出兜底**：注册 `process.on('exit')` 处理器，确保即使异常退出也能恢复终端状态
+
+**任务行格式：**
+
+```
+[1/3] /path/to/worktree  ⠹ 运行中 1m23s  Read index.ts
+[2/3] /path/to/worktree  ✓ 完成   2m05s  $0.08  任务已成功完成
+[3/3] /path/to/worktree  ◦ 排队中
+```
+
+- 第二列为 worktree 路径（`path.padEnd(maxPathWidth)` 对齐）
+- 运行中状态：末尾显示实时活动描述文本（如工具名+文件名、思考中+文本片段）
+- 完成/失败状态：末尾显示结果预览文本（从 `ClaudeCodeResult.result` 提取，最大 40 字符）
+
+**非 TTY 降级模式：**
+
+- 启动时输出 `[1/3] branch 启动 path`
+- 完成时输出 `[1/3] branch ✓ 完成 duration cost detail`（`detail` 优先使用结果预览，无则回退到路径）
+- 失败时输出 `[1/3] branch ✗ 失败 duration detail`
+
+---

package/docs/projects.md

@@ -0,0 +1,135 @@
+### 5.18 跨项目 Worktree 概览
+
+**命令：**
+
+```bash
+clawt projects [name] [--json]
+```
+
+**参数：**
+
+| 参数     | 必填 | 说明                                           |
+| -------- | ---- | ---------------------------------------------- |
+| `[name]` | 否   | 指定项目名，查看该项目的 worktree 详情           |
+| `--json` | 否   | 以 JSON 格式输出完整数据                        |
+
+**使用场景：**
+
+当使用 clawt 管理多个不同项目时，快速了解所有项目的 worktree 数量、磁盘占用和最近活跃时间。也可以指定项目名查看该项目下每个 worktree 的分支、路径、最后修改时间和磁盘占用。
+
+**注意：** `projects` 命令不需要在主 worktree 中执行（与其他命令不同），它直接扫描 `~/.clawt/worktrees/` 目录。
+
+**运行流程：**
+
+#### 无参数模式（项目概览）
+
+1. 扫描 `~/.clawt/worktrees/` 目录，列出所有项目子目录（如果目录不存在或为空，输出 `(暂无项目，worktrees 目录为空)` 提示并结束）
+2. 对每个项目收集以下信息：
+   - **项目名**（目录名即项目名）
+   - **worktree 数量**（项目目录下的子目录数）
+   - **最近活跃时间**（取项目目录自身和所有 worktree 目录 mtime 的最大值，通过 `formatLocalISOString()` 格式化为本机时区的 ISO 8601 字符串）
+   - **磁盘占用**（通过 `calculateDirSize()` 递归计算整个项目目录的总大小）
+3. 按最近活跃时间降序排序
+4. 输出概览信息（文本或 JSON）
+
+#### 指定项目模式（worktree 详情）
+
+1. 检查 `~/.clawt/worktrees/<name>/` 是否存在，不存在则报错退出
+2. 扫描项目目录，对每个 worktree 子目录收集（如果项目目录下无 worktree 子目录，输出 `(该项目下无 worktree)` 提示并结束）：
+   - **分支名**（目录名即分支名）
+   - **worktree 路径**
+   - **最后修改时间**（目录 mtime，通过 `formatLocalISOString()` 格式化）
+   - **磁盘占用**（通过 `calculateDirSize()` 递归计算）
+3. 按最后修改时间降序排序
+4. 输出详情信息（文本或 JSON）
+
+**文本输出格式（概览模式）：**
+
+```
+════════════════════════════════════════
+  项目概览
+════════════════════════════════════════
+
+  ● my-project
+    3 个 worktree   最近活跃: 2 小时前   磁盘占用: 1.5 GB
+
+  ● another-project
+    1 个 worktree   最近活跃: 3 天前   磁盘占用: 256.0 MB
+
+────────────────────────────────────────
+
+  共 2 个项目   总占用: 1.8 GB
+
+════════════════════════════════════════
+```
+
+**文本输出格式（详情模式）：**
+
+```
+════════════════════════════════════════
+  项目详情: my-project
+════════════════════════════════════════
+
+  ◆ 路径: ~/.clawt/worktrees/my-project
+    总占用: 1.5 GB
+
+────────────────────────────────────────
+
+  ● feature-login
+    ~/.clawt/worktrees/my-project/feature-login
+    最后修改: 2 小时前   磁盘占用: 800.0 MB
+
+  ● feature-signup
+    ~/.clawt/worktrees/my-project/feature-signup
+    最后修改: 1 天前   磁盘占用: 700.0 MB
+
+════════════════════════════════════════
+```
+
+**JSON 输出格式（概览模式，`--json`）：**
+
+```json
+{
+  "projects": [
+    {
+      "name": "my-project",
+      "worktreeCount": 3,
+      "lastActiveTime": "2025-06-15T18:30:00.000+08:00",
+      "diskUsage": 1610612736
+    }
+  ],
+  "totalProjects": 1,
+  "totalDiskUsage": 1610612736
+}
+```
+
+**JSON 输出格式（详情模式，`--json`）：**
+
+```json
+{
+  "name": "my-project",
+  "projectDir": "/Users/<username>/.clawt/worktrees/my-project",
+  "worktrees": [
+    {
+      "branch": "feature-login",
+      "path": "/Users/<username>/.clawt/worktrees/my-project/feature-login",
+      "lastModifiedTime": "2025-06-15T18:30:00.000+08:00",
+      "diskUsage": 838860800
+    }
+  ],
+  "totalDiskUsage": 838860800
+}
+```
+
+**实现要点：**
+
+- 命令注册函数：`registerProjectsCommand()`（在 `src/commands/projects.ts`）
+- 类型定义在 `src/types/project.ts`：`ProjectOverview`、`ProjectWorktreeDetail`、`ProjectDetailResult`、`ProjectsOverviewResult`
+- 命令选项类型：`ProjectsOptions`（在 `src/types/command.ts`）
+- 消息常量在 `PROJECTS_MESSAGES`（在 `src/constants/messages/projects.ts`）
+- 时间格式化使用 `formatLocalISOString()`（在 `src/utils/formatter.ts`），输出本机时区的 ISO 8601 字符串（替代 `Date.toISOString()` 的 UTC 输出）
+- 磁盘大小展示使用 `formatDiskSize()`（在 `src/utils/formatter.ts`），将字节数格式化为带单位的可读字符串
+- 目录大小计算使用 `calculateDirSize()`（在 `src/utils/fs.ts`），递归遍历目录计算总字节数
+- 时间的相对展示使用 `formatRelativeTime()`（在 `src/utils/formatter.ts`），将 ISO 8601 日期转换为中文相对时间（如"2 小时前"）
+
+---

package/docs/remove.md

@@ -0,0 +1,79 @@
+### 5.5 移除 Worktree
+
+**命令：**
+
+```bash
+# 移除当前项目所有 worktree
+clawt remove --all
+
+# 指定分支名（支持模糊匹配）
+clawt remove -b <branchName>
+
+# 不指定参数（列出所有分支供多选）
+clawt remove
+```
+
+**参数：**
+
+| 参数      | 必填 | 说明                                                                   |
+| --------- | ---- | ---------------------------------------------------------------------- |
+| `--all`   | 否   | 移除当前项目 (`~/.clawt/worktrees/<project>/`) 下所有 worktree           |
+| `-b`      | 否   | 指定分支名（支持模糊匹配，不传则列出所有分支供多选）                       |
+
+> **提示：** 不传 `--all` 也不传 `-b` 时，会列出当前项目所有 worktree 供交互式多选。
+
+**运行流程：**
+
+1. **主 worktree 校验** (2.1)
+2. **获取项目名** (2.2)
+3. **确定待移除的 worktree 列表**：
+   - **指定 `--all`** → 选中当前项目所有 worktree（若当前项目无 worktree，则提示并退出）
+   - **未指定 `--all`** → 通过 `resolveTargetWorktrees` 解析目标 worktree（多选版本），匹配策略如下：
+     - **未传 `-b` 参数**：
+       - 无可用 worktree → 报错退出
+       - 仅 1 个 worktree → 直接使用，无需选择
+       - 多个 worktree → 通过交互式多选列表（Enquirer.MultiSelect）让用户选择（空格选择，回车确认）
+     - **传了 `-b` 参数**：
+       1. **精确匹配优先**：在 worktree 列表中查找分支名完全相同的 worktree，找到则直接使用
+       2. **模糊匹配**（子串匹配，大小写不敏感）：
+          - 唯一匹配 → 直接使用
+          - 多个匹配 → 通过交互式多选列表让用户从匹配结果中选择
+       3. **无匹配** → 报错退出，并列出所有可用分支名
+4. 列出即将移除的 worktree 及对应分支：
+
+```
+即将移除以下 worktree 及本地分支：
+
+  1. ~/.clawt/worktrees/main-project/feature-scheme-1  →  分支: feature-scheme-1  验证分支: clawt-validate-feature-scheme-1
+  2. ~/.clawt/worktrees/main-project/feature-scheme-2  →  分支: feature-scheme-2  验证分支: clawt-validate-feature-scheme-2
+  3. ~/.clawt/worktrees/main-project/feature-scheme-3  →  分支: feature-scheme-3  验证分支: clawt-validate-feature-scheme-3
+
+是否同时删除对应的本地分支和验证分支？(y/N)
+```
+
+5. 用户确认后（只需确认一次），对每个 worktree 依次执行（单个失败不影响其他）：
+
+```bash
+# 确保当前处于主工作分支上（若不在则自动切回）
+git checkout <clawtMainWorkBranch>
+
+# 移除 worktree
+git worktree remove -f <worktree路径>
+
+# 如果用户选择了删除分支
+git branch -D <branchName>
+
+# 无条件删除验证分支和清理快照（不受用户确认控制）
+git branch -D clawt-validate-<branchName>
+# 清理该分支对应的 validate 快照
+```
+
+6. 如果配置文件 `~/.clawt/config.json` 中 `autoDeleteBranch` 为 `true`，则跳过询问，直接删除分支。
+
+7. 如果使用 `--all` 模式，额外清理整个项目的 validate 快照目录。
+
+8. 移除完成后，清理空目录（如果 `~/.clawt/worktrees/<project>/` 下已无 worktree，则删除该项目目录）。
+
+9. 批量移除时，单个 worktree 移除失败不会中断整个流程，而是收集所有失败项，最后汇总报告并以错误状态退出（抛出 ClawtError）。
+
+---

package/docs/reset.md

@@ -0,0 +1,35 @@
+### 5.13 重置主 Worktree 工作区和暂存区
+
+**命令：**
+
+```bash
+clawt reset
+```
+
+**无参数。**
+
+**使用场景：**
+
+当用户通过 `clawt validate` 将分支变更迁移到主 worktree 后，希望快速清除工作区和暂存区的所有修改，恢复到干净状态。与 `clawt validate --clean` 的区别在于：`reset` 仅重置工作区和暂存区，**不删除** validate 快照文件，也**不切换分支**，适用于只想清空变更而保留快照以便后续增量 validate 的场景。
+
+> **设计原因**：reset 的职责是「重置工作区状态」，分支切换属于 validate --clean 和 remove 等命令的职责。将分支切换耦合到 reset 会违反单一职责原则。
+
+**运行流程：**
+
+1. **主 worktree 校验** (2.1)
+2. **项目级配置校验**（`requireProjectConfig()`，因 reset 不调用 `ensureOnMainWorkBranch`，需自行校验）
+3. **检测工作区状态**：通过 `git status --porcelain` 检测主 worktree 是否有未提交的更改
+   - **工作区干净** → 输出提示 `主 worktree 工作区和暂存区已是干净状态，无需重置`，退出
+   - **工作区不干净** → 继续
+3. **确认破坏性操作**：如果配置项 `confirmDestructiveOps` 为 `true`，提示确认（显示即将执行的危险指令和操作后果），用户取消则退出
+4. **重置工作区和暂存区**：
+   ```bash
+   git reset --hard HEAD
+   git clean -fd
+   ```
+5. **输出成功提示**：
+   ```
+   ✓ 主 worktree 工作区和暂存区已重置
+   ```
+
+---

package/docs/resume.md

@@ -0,0 +1,99 @@
+### 5.11 在已有 Worktree 中恢复会话
+
+**命令：**
+
+```bash
+# 指定分支名（支持模糊匹配）
+clawt resume -b <branchName>
+
+# 不指定分支名（列出所有分支供多选）
+clawt resume
+```
+
+**参数：**
+
+| 参数 | 必填 | 说明                                                  |
+| ---- | ---- | ----------------------------------------------------- |
+| `-b` | 否   | 要恢复的分支名（支持模糊匹配，不传则列出所有分支供多选） |
+
+**使用场景：**
+
+当用户之前通过 `clawt run` 或 `clawt create` 创建了 worktree 但会话已结束，希望在该 worktree 中重新打开 Claude Code 交互式界面继续工作。支持一次选中多个分支，自动在独立终端 Tab 中批量恢复。
+
+**运行流程：**
+
+1. **主 worktree 校验** (2.1)
+2. **Claude Code CLI 校验**：确认 `claude` CLI 可用
+3. **解析目标 worktree**：根据是否传入 `-b` 参数以及 worktree 数量，采用不同的解析策略：
+   - **未传 `-b` 参数**：
+     - 获取当前项目所有 worktree
+     - 无可用 worktree → 报错退出
+     - 仅 1 个 worktree → 通过 `resolveTargetWorktrees` 直接使用，无需选择
+     - 多个 worktree → 通过 `promptGroupedMultiSelectBranches` 展示**按日期分组的交互式多选列表**（详见下文「按日期分组多选」）
+   - **传了 `-b` 参数**：通过 `resolveTargetWorktrees` 解析，匹配策略如下：
+     1. **精确匹配优先**：在 worktree 列表中查找分支名完全相同的 worktree，找到则直接使用
+     2. **模糊匹配**（子串匹配，大小写不敏感）：
+        - 唯一匹配 → 直接使用
+        - 多个匹配 → 通过交互式多选列表让用户从匹配结果中选择
+     3. **无匹配** → 报错退出，并列出所有可用分支名
+4. **根据选中数量自动分发**：
+   - **用户未选择任何分支** → 直接退出
+   - **选中 1 个** → 在当前终端恢复（同原有行为），通过 `launchInteractiveClaude()` 启动（使用 `spawnSync` + `inherit stdio`）
+   - **选中多个** → 进入批量恢复流程（见下文）
+
+**批量恢复流程：**
+
+1. **计算会话状态**：一次性遍历所有选中的 worktree，通过 `hasClaudeSessionHistory()` 检测是否存在历史会话，构建 sessionMap 避免重复 I/O
+2. **输出预览**：列出即将恢复的分支及其会话状态（"继续上次对话"或"新对话"）
+3. **用户确认**：提示即将在 N 个独立终端 Tab 中恢复会话，等待用户确认
+4. **逐个在新终端 Tab 中启动**：通过 `launchInteractiveClaudeInNewTerminal()` 构建 shell 命令并通过 AppleScript 在新终端 Tab 中执行
+5. **输出完成提示**
+
+**终端 Tab 管理：**
+
+批量恢复通过 `openCommandInNewTerminalTab()`（`src/utils/terminal.ts`）在新终端 Tab 中启动 Claude Code。终端类型由配置项 `terminalApp` 控制：
+
+| 配置值     | 行为                                                         |
+| ---------- | ------------------------------------------------------------ |
+| `auto`     | 自动检测：优先检测 iTerm2 是否已安装（`/Applications/iTerm.app`），已安装则使用 iTerm2，否则降级到 Terminal.app |
+| `iterm2`   | 强制使用 iTerm2                                               |
+| `terminal` | 强制使用 Terminal.app                                         |
+
+**平台限制：** 批量恢复目前仅支持 macOS 平台（通过 AppleScript 打开终端 Tab）。非 macOS 平台会抛出错误。
+
+**权限要求：** Terminal.app 通过 System Events 模拟键盘操作（`Cmd+T`）新建 Tab，需要在「系统设置 → 隐私与安全性 → 辅助功能」中授权终端应用。iTerm2 使用原生 AppleScript 接口，无需辅助功能权限。
+
+启动命令通过配置项 `claudeCodeCommand`（默认值 `claude`）指定，与 `clawt run` 不传 `--tasks` 时的交互式界面行为一致。
+
+**按日期分组多选：**
+
+当未传 `-b` 且有多个 worktree 时，使用 `promptGroupedMultiSelectBranches` 展示按创建日期分组的交互式多选列表，实现流程如下：
+
+1. **日期分组**（`groupWorktreesByDate`）：通过 `statSync` 获取各 worktree 目录的文件系统创建时间（`birthtime`），按本地时区格式化为 `YYYY-MM-DD` 作为分组键。无法获取创建时间的分支归入「未知日期」组。分组按日期降序排列，未知日期组在最后。
+2. **构建选项列表**（`buildGroupedChoices`）：生成包含以下元素的 Enquirer MultiSelect choices 数组：
+   - 顶部：全局全选选项 `[select-all]`
+   - 每组：日期分隔线（显示日期和相对时间，如「2026-02-26（昨天）」）→ 组级全选选项 `[select-all: YYYY-MM-DD]` → 该组内各分支
+2.5. **构建组成员映射**（`buildGroupMembershipMap`）：生成"组全选 name → 该组分支 name 列表"的 Map，供三级联动的 `space()` 方法快速查找某个组全选项对应的所有分支
+3. **三级联动选择**：通过继承 Enquirer MultiSelect 并覆写 `space()` 方法实现，同步逻辑由 `syncGlobalSelectAll` 和 `syncGroupSelectAll` 两个内部函数负责：
+   - **全局全选**：toggle 所有 choices（含组全选）
+   - **组级全选**：toggle 该组内所有分支，并同步全局全选状态
+   - **普通分支**：toggle 该分支，同步所属组全选和全局全选状态
+4. **过滤结果**：返回时过滤掉全选项和组全选项，只返回实际选中的 worktree
+
+相对日期显示规则：`formatRelativeDate` 基于自然日差值计算——今天 / 昨天 / N 天前 / N 个月前 / N 年前。
+
+相关常量定义在 `src/constants/prompt.ts`：
+
+| 常量 | 说明 |
+| ---- | ---- |
+| `GROUP_SELECT_ALL_PREFIX` | 组级全选选项的 name 前缀（`__group_select_all_`） |
+| `GROUP_SELECT_ALL_LABEL(dateLabel)` | 生成组级全选选项的显示文本 |
+| `GROUP_SEPARATOR_LABEL(dateLabel, relativeTime)` | 生成日期分隔线的显示文本（含 chalk 高亮） |
+| `UNKNOWN_DATE_GROUP` | 无法获取创建日期时的默认分组名称（`未知日期`） |
+| `UNKNOWN_DATE_SEPARATOR_LABEL` | 未知日期分组的分隔线显示文本 |
+| `SELECT_ALL_NAME` | 全局全选选项的标识名称（`__select_all__`） |
+| `SELECT_ALL_LABEL` | 全局全选选项的显示文本（`[select-all]`） |
+
+**会话自动续接：** 启动前会自动检测该 worktree 是否存在 Claude Code 历史会话（通过检查 `~/.claude/projects/<encoded-path>/` 下是否有 `.jsonl` 文件判断），如果存在则自动追加 `--continue` 参数继续上次对话，否则打开新对话。启动信息中会显示当前模式（"继续上次对话"或"新对话"）。路径编码规则：将绝对路径中所有非字母数字字符替换为 `-`（与 Claude Code 源码的编码逻辑一致）。
+
+---