clawt 3.5.3 → 3.6.1

package/docs/notification.md

@@ -1,94 +0,0 @@
-### 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/project-config.md

@@ -1,132 +0,0 @@
-### 项目级配置
-
-#### 概述
-
-项目级配置是每个 Git 项目独立的 clawt 配置，用于记录该项目特有的设置（如主工作分支名、validate 自动运行命令等）。与全局配置（`~/.clawt/config.json`，见 [config-file.md](./config-file.md)）不同，项目级配置按项目隔离存储。
-
-#### 存放路径
-
-```
-~/.clawt/projects/<projectName>/config.json
-```
-
-其中 `<projectName>` 为项目根目录的目录名（通过 `git rev-parse --show-toplevel` 获取后取 `basename`）。
-
-#### 配置项列表
-
-```json
-{
-  "clawtMainWorkBranch": "main",
-  "validateRunCommand": "npm test"
-}
-```
-
-| 配置项 | 类型 | 必填 | 默认值 | 说明 |
-| --- | --- | --- | --- | --- |
-| `clawtMainWorkBranch` | `string` | 是 | `""` | 项目的主工作分支名，用于 create 时检测当前分支是否为主分支，以及 sync、merge 等命令获取主分支名 |
-| `validateRunCommand` | `string` | 否 | `undefined` | validate 成功后自动执行的命令（作为 `-r` 选项的默认值）。不传 `-r` 时，validate 命令会自动从此项读取 |
-
-#### 配置项定义数据源
-
-项目级配置项的完整定义集中在 `src/constants/project-config.ts` 中的 `PROJECT_CONFIG_DEFINITIONS` 常量，作为**单一数据源**（Single Source of Truth）。新增项目配置项只需在此处维护，`PROJECT_DEFAULT_CONFIG` 和 `PROJECT_CONFIG_DESCRIPTIONS` 会自动从中派生：
-
-```typescript
-// src/constants/project-config.ts
-
-export const PROJECT_CONFIG_DEFINITIONS: ProjectConfigDefinitions = {
-  clawtMainWorkBranch: {
-    defaultValue: '',
-    description: '主 worktree 的工作分支名',
-  },
-  validateRunCommand: {
-    defaultValue: undefined as unknown as string | undefined,
-    description: 'validate 成功后自动执行的命令（-r 的默认值）',
-  },
-};
-
-/** 项目默认配置（从 PROJECT_CONFIG_DEFINITIONS 自动派生） */
-export const PROJECT_DEFAULT_CONFIG: Required<ProjectConfig> = deriveDefaultConfig(PROJECT_CONFIG_DEFINITIONS);
-
-/** 项目配置项描述映射（从 PROJECT_CONFIG_DEFINITIONS 自动派生） */
-export const PROJECT_CONFIG_DESCRIPTIONS: Record<keyof Required<ProjectConfig>, string> = deriveConfigDescriptions(PROJECT_CONFIG_DEFINITIONS);
-```
-
-#### 相关类型定义
-
-类型定义位于 `src/types/projectConfig.ts`：
-
-| 类型 | 说明 |
-| --- | --- |
-| `ProjectConfig` | 项目级配置接口，包含 `clawtMainWorkBranch`（必填）和 `validateRunCommand`（可选） |
-| `ProjectConfigItemDefinition<T>` | 单个配置项定义，含 `defaultValue`（默认值）、`description`（描述）、可选 `allowedValues`（枚举值列表，仅对 string 类型有效） |
-| `ProjectConfigDefinitions` | 所有配置项的完整定义映射，键为 `ProjectConfig` 的所有属性名，值为对应的 `ProjectConfigItemDefinition` |
-
-```typescript
-// src/types/projectConfig.ts
-
-export interface ProjectConfig {
-  clawtMainWorkBranch: string;
-  validateRunCommand?: string;
-}
-
-export interface ProjectConfigItemDefinition<T> {
-  defaultValue: T;
-  description: string;
-  allowedValues?: T extends string ? readonly string[] : never;
-}
-
-export type ProjectConfigDefinitions = {
-  [K in keyof Required<ProjectConfig>]: ProjectConfigItemDefinition<ProjectConfig[K]>;
-};
-```
-
-#### 工具函数
-
-工具函数位于 `src/utils/project-config.ts`：
-
-| 函数 | 签名 | 说明 |
-| --- | --- | --- |
-| `getProjectConfigPath` | `(projectName: string) => string` | 获取项目配置文件的完整路径 |
-| `loadProjectConfig` | `() => ProjectConfig \| null` | 加载当前项目的配置，配置文件不存在或解析失败时返回 `null` |
-| `saveProjectConfig` | `(config: ProjectConfig) => void` | 保存项目配置到文件，自动创建项目子目录 |
-| `requireProjectConfig` | `() => ProjectConfig` | 获取当前项目配置，不存在或缺少 `clawtMainWorkBranch` 时抛出 `ClawtError` |
-| `getMainWorkBranch` | `() => string` | 从项目配置中获取主工作分支名（内部调用 `requireProjectConfig`） |
-| `getValidateRunCommand` | `() => string \| undefined` | 从项目配置中获取 validate 自动执行命令，未配置时返回 `undefined` |
-
-#### 设置方式
-
-通过 `clawt init` 命令设置（详见 [init.md](./init.md)）：
-
-```bash
-# 以当前分支作为主工作分支初始化
-clawt init
-
-# 指定主工作分支名
-clawt init -b <branchName>
-
-# 交互式查看和修改所有项目配置项
-clawt init show
-```
-
-`init show` 子命令调用通用的 `interactiveConfigEditor`（`src/utils/config-strategy.ts`），基于 `PROJECT_CONFIG_DEFINITIONS` 构建配置项列表，提供交互式面板供用户查看和修改所有项目配置项。
-
-#### 前置校验
-
-除 `clawt init` 以外的所有核心命令（create、run、validate、sync、remove、merge、reset），执行时都会校验项目级配置是否存在。如果未执行过 `clawt init`，命令会直接报错并提示用户先初始化：
-
-```
-✗ 该项目尚未初始化，请先执行 clawt init -b<branchName>设置主工作分支
-```
-
-> **实现细节**：`ensureOnMainWorkBranch()` 内部已通过 `getMainWorkBranch()` -> `requireProjectConfig()` 完成了项目配置校验，因此调用了 `ensureOnMainWorkBranch` 的命令（create、run、validate、sync、remove、merge）无需再显式调用 `requireProjectConfig()`，避免重复校验。仅 reset 命令因不调用 `ensureOnMainWorkBranch`，需要自行调用 `requireProjectConfig()`。
-
-#### 路径常量
-
-在 `src/constants/paths.ts` 中定义：
-
-```typescript
-/** 项目级配置目录 ~/.clawt/projects/ */
-export const PROJECTS_CONFIG_DIR = join(CLAWT_HOME, 'projects');
-```
-
----

package/docs/projects.md

@@ -1,135 +0,0 @@
-### 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

@@ -1,90 +0,0 @@
-### 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)
-   - HEAD 存在性校验
-   - 项目配置文件校验（确保项目已通过 `clawt init` 初始化）
-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. **当前分支安全检查**：逐个检查待移除的分支，如果该分支或其对应的验证分支（`clawt-validate-<branchName>`）是主 worktree 当前所在分支，则抛出错误并阻止移除。
-5. 列出即将移除的 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)
-```
-
-6. **判断是否删除本地分支**：
-   - 如果配置文件 `~/.clawt/config.json` 中 `autoDeleteBranch` 为 `true`，则跳过询问，直接删除分支
-   - 否则询问用户是否删除，用户拒绝时提示可稍后手动删除
-7. 对每个 worktree 依次执行（单个失败不影响其他）：
-
-```bash
-# 移除 worktree
-git worktree remove -f <worktree路径>
-
-# 如果用户选择了删除分支（或 autoDeleteBranch 为 true）
-git branch -D <branchName>
-
-# 无条件删除验证分支（不受用户确认控制，存在则删除）
-git branch -D clawt-validate-<branchName>
-# 无条件清理该分支对应的 validate 快照
-```
-
-8. 如果使用 `--all` 模式，额外清理整个项目的 validate 快照目录。
-
-9. 移除完成后执行清理：
-   - `git worktree prune` 清理已失效的 worktree 引用
-   - 如果 `~/.clawt/worktrees/<project>/` 下已无 worktree，则删除该项目目录
-
-10. 批量移除时，单个 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

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

package/docs/resume.md

@@ -1,100 +0,0 @@
-### 5.11 在已有 Worktree 中恢复会话
-
-**命令：**
-
-```bash
-# 指定分支名（支持模糊匹配）
-clawt resume -b <branchName>
-
-# 不指定分支名（列出所有分支供多选）
-clawt resume
-```
-
-**参数：**
-
-| 参数 | 必填 | 说明                                                  |
-| ---- | ---- | ----------------------------------------------------- |
-| `-b` | 否   | 要恢复的分支名（支持模糊匹配，不传则列出所有分支供多选） |
-
-**使用场景：**
-
-当用户之前通过 `clawt run` 或 `clawt create` 创建了 worktree 但会话已结束，希望在该 worktree 中重新打开 Claude Code 交互式界面继续工作。支持一次选中多个分支，自动在独立终端 Tab 中批量恢复。
-
-**运行流程：**
-
-1. **前置校验**（`PRE_CHECK_RESUME`）：主 worktree 校验 (2.1) + HEAD 存在性校验 + Claude Code CLI 可用性校验
-2. **解析目标 worktree**：根据是否传入 `-b` 参数以及 worktree 数量，采用不同的解析策略：
-   - **未传 `-b` 参数**：
-     - 获取当前项目所有 worktree
-     - 无可用 worktree → 报错退出
-     - 仅 1 个 worktree → 通过 `resolveTargetWorktrees` 直接使用，无需选择
-     - 多个 worktree → 通过 `promptGroupedMultiSelectBranches` 展示**按日期分组的交互式多选列表**（详见下文「按日期分组多选」）
-   - **传了 `-b` 参数**：通过 `resolveTargetWorktrees` 解析，匹配策略如下：
-     1. **精确匹配优先**：在 worktree 列表中查找分支名完全相同的 worktree，找到则直接使用
-     2. **模糊匹配**（子串匹配，大小写不敏感）：
-        - 唯一匹配 → 直接使用
-        - 多个匹配 → 通过交互式多选列表让用户从匹配结果中选择
-     3. **无匹配** → 报错退出，并列出所有可用分支名
-3. **根据选中数量自动分发**：
-   - **用户未选择任何分支** → 直接退出
-   - **选中 1 个** → 根据全局配置项 `resumeInPlace` 决定打开方式：
-     - `resumeInPlace: true` → 在当前终端就地恢复，通过 `launchInteractiveClaude()` 启动（使用 `spawnSync` + `inherit stdio`）
-     - `resumeInPlace: false`（默认） → 通过 `launchInteractiveClaudeInNewTerminal()` 在新终端 Tab 中恢复，终端类型由 `terminalApp` 配置控制
-   - **选中多个** → 进入批量恢复流程（见下文），始终在新终端 Tab 中打开，不受 `resumeInPlace` 影响
-
-**批量恢复流程：**
-
-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 源码的编码逻辑一致）。
-
----