clawt 3.7.0 → 3.8.0

package/docs/config-file.md

@@ -0,0 +1,49 @@
+### 5.7 默认配置文件
+
+**路径：** `~/.clawt/config.json`
+
+**生成时机：** 全局安装后自动生成（通过 `postinstall` 脚本）。
+
+**升级策略：** 配置文件已存在时，执行增量合并而非简单跳过：
+
+- **新版本新增的配置项** → 使用默认值补充到用户配置中
+- **用户已有的配置项** → 保留用户的值，不覆盖
+- **新版本已移除的配置项** → 从用户配置中删除
+
+仅在合并后配置发生变化时才写入文件。配置文件损坏或无法解析时，视为不存在，重新生成默认配置。
+
+**默认内容：**
+
+```json
+{
+  "autoDeleteBranch": false,
+  "claudeCodeCommand": "claude",
+  "autoPullPush": false,
+  "confirmDestructiveOps": true,
+  "maxConcurrency": 0,
+  "terminalApp": "auto",
+  "resumeInPlace": false,
+  "aliases": {},
+  "autoUpdate": true,
+  "conflictResolveMode": "ask",
+  "conflictResolveTimeoutMs": 300000
+}
+```
+
+**配置项说明：**
+
+| 配置项             | 类型      | 默认值    | 说明                                               |
+| ------------------ | --------- | --------- | -------------------------------------------------- |
+| `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）前是否提示确认 |
+| `maxConcurrency` | `number` | `0` | run 命令默认最大并发数，`0` 表示不限制 |
+| `terminalApp` | `string` | `"auto"` | 批量 resume 使用的终端应用：`auto`（自动检测）、`iterm2`、`terminal`（macOS） |
+| `resumeInPlace` | `boolean` | `false` | resume 单选时是否在当前终端就地打开，`false` 则通过 `terminalApp` 在新 Tab 中打开 |
+| `aliases` | `Record<string, string>` | `{}` | 命令别名映射，键为别名，值为目标内置命令名 |
+| `autoUpdate` | `boolean` | `true` | 是否启用自动更新检查（每 24 小时通过 npm registry 检查一次新版本） |
+| `conflictResolveMode` | `string` | `"ask"` | merge 冲突时的解决模式：`ask`（询问是否使用 AI）、`auto`（自动 AI 解决）、`manual`（手动解决） |
+| `conflictResolveTimeoutMs` | `number` | `300000` | Claude Code 冲突解决超时时间（毫秒），默认 300000（5 分钟） |
+
+---

package/docs/config.md

@@ -0,0 +1,93 @@
+### 5.10 交互式查看和修改全局配置
+
+**命令：**
+
+```bash
+# 交互式修改配置（等同于 config set 无参数）
+clawt config
+
+# 修改配置项（无参数进入交互式，有参数直接设置）
+clawt config set [key] [value]
+
+# 获取单个配置项的值
+clawt config get <key>
+
+# 将配置恢复为默认值
+clawt config reset
+```
+
+#### 交互式修改配置（`config` / `config set`）
+
+直接执行 `clawt config` 或 `clawt config set`（不带参数）进入交互式配置修改模式。
+
+**运行流程：**
+
+1. 读取全局配置文件 `~/.clawt/config.json`
+2. 列出所有配置项供用户选择（`Enquirer.Select`），每项显示：
+   - 配置项名称
+   - 当前值（布尔值绿色/黄色，字符串和数字青色）
+   - 配置项描述（暗淡色 dim）
+   - 对象类型配置项（如 `aliases`）标灰不可选，提示用户通过专用命令管理
+3. 用户选择某个配置项后，根据值类型自动选择提示策略：
+   - **boolean 类型** → `Select`（true / false）
+   - **number 类型** → `Input`（带数字校验）
+   - **string 类型 + 有 `allowedValues`** → `Select`（枚举列表）
+   - **string 类型 + 无 `allowedValues`** → `Input`（自由输入）
+4. 将修改后的配置持久化到配置文件
+5. 输出成功提示：`✓ <key> 已设置为 <value>`
+
+#### 直接设置配置项（`config set <key> <value>`）
+
+当带参数执行 `clawt config set <key> <value>` 时，直接修改指定配置项。
+
+**参数：**
+
+| 参数 | 必填 | 说明 |
+| ---- | ---- | ---- |
+| `key` | 否 | 配置项名称（不传则进入交互式模式） |
+| `value` | 否 | 配置值（传了 `key` 时必填） |
+
+**运行流程：**
+
+1. 校验 `key` 是否为有效的配置项名称（基于 `DEFAULT_CONFIG` 的键列表），无效则输出错误及可用配置项列表
+2. 校验 `value` 是否缺失，缺失则提示：`缺少配置值，用法: clawt config set <key> <value>`
+3. 根据目标配置项的类型解析并校验值：
+   - **boolean** → 仅接受 `true` 或 `false`
+   - **number** → `Number()` 解析，`NaN` 报错
+   - **string + 有 `allowedValues`** → 校验值是否在枚举列表中
+   - **string + 无 `allowedValues`** → 无额外校验
+4. 加载配置、修改目标项、持久化
+5. 输出成功提示：`✓ <key> 已设置为 <value>`
+
+#### 获取单个配置项（`config get <key>`）
+
+**参数：**
+
+| 参数 | 必填 | 说明 |
+| ---- | ---- | ---- |
+| `key` | 是 | 配置项名称 |
+
+**运行流程：**
+
+1. 校验 `key` 是否为有效的配置项名称，无效则输出错误及可用配置项列表
+2. 读取配置文件，获取目标配置项的值
+3. 输出：`<key> = <value>`
+
+#### 恢复默认配置（`config reset`）
+
+**运行流程：**
+
+1. 始终提示确认（显示即将执行的操作和后果：当前配置将被覆盖为默认值），不受 `confirmDestructiveOps` 配置控制。用户取消则退出
+2. 将默认配置写入 `~/.clawt/config.json`（覆盖现有配置文件）
+3. 输出成功提示：`✓ 配置已恢复为默认值`
+
+**实现要点：**
+
+- 配置项类型定义：`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`）的显示逻辑在 `interactiveConfigEditor` 的列表构建中处理：通过 `JSON.stringify` 以暗淡色显示值，并标记为不可选（disabled），提示用户通过 `clawt alias` 命令管理
+
+---

package/docs/cover-validate.md

@@ -0,0 +1,94 @@
+### 5.21 将验证分支修改覆盖回目标 Worktree
+
+**命令：**
+
+```bash
+clawt cover
+```
+
+> 无需指定分支名，自动从当前验证分支名（`clawt-validate-<branchName>`）中推导目标分支。
+
+**参数：**
+
+无额外参数。必须在验证分支上执行。
+
+**使用场景：**
+
+在 `validate` 验证过程中，用户可能会在主 worktree（验证分支上）对代码进行修改（如修复测试失败、调整逻辑等）。`cover` 命令用于将这些修改覆盖回目标 worktree，使目标 worktree 的代码与验证分支上的最新状态同步。
+
+**运行流程：**
+
+##### 步骤 1：前置校验
+
+1. **主 worktree 校验**（`requireMainWorktree`）
+2. **HEAD 校验**（`requireHead`）
+3. **项目级配置校验**（`requireProjectConfig`）
+4. **验证分支校验**：当前分支必须以 `clawt-validate-` 开头，否则报错退出
+
+##### 步骤 2：查找目标 worktree
+
+从验证分支名中提取目标分支名（去掉 `clawt-validate-` 前缀），然后在项目的 worktree 列表中精确匹配目标分支对应的 worktree。如果目标 worktree 不存在（可能已被移除），报错退出。
+
+##### 步骤 3：校验快照存在并读取
+
+校验目标分支的 validate 快照是否存在。如果快照不存在，提示用户先执行 `clawt validate -b <branch>` 创建快照。读取快照中的 tree hash（`snapshotTreeHash`），作为增量计算的基准。
+
+##### 步骤 3.5：工作区干净检查
+
+检测主 worktree（验证分支上）的工作区和暂存区是否干净（`isWorkingDirClean`）：
+
+- **不干净**（有修改）→ 正常继续，这是 cover 的典型使用场景
+- **干净**（无修改）→ 输出提示信息 `当前验证分支的工作区和暂存区没有任何修改，可能为误操作`，并通过 `confirmAction` 询问用户 `是否继续执行覆盖？`：
+  - 用户确认 → 继续执行
+  - 用户取消 → 直接返回，不执行后续步骤
+
+> 工作区干净时通常意味着用户没有在验证分支上做任何修改就执行了 cover，这大概率是误操作。增加确认提示可以避免不必要的覆盖操作。
+
+##### 步骤 4：计算增量 patch
+
+通过 `computeIncrementalPatch()` 计算验证分支上相对于快照的增量变更：
+
+1. 保存当前暂存区的 tree hash（`savedIndexTreeHash`），用于后续恢复
+2. `git add .` + `git write-tree` 获取当前工作区的完整 tree hash（`currentTreeHash`）
+3. 通过 `git read-tree` 恢复原始暂存区状态（无论成功失败都执行，在 `finally` 块中）
+4. 比较 `snapshotTreeHash` 与 `currentTreeHash`：
+   - **相同** → 无增量变更，输出提示后返回
+   - **不同** → 通过 `git diff-tree` 生成 patch
+
+##### 步骤 5：应用 patch 到目标 worktree
+
+将增量 patch 通过 `git apply --binary` 应用到目标 worktree 的工作区。如果 patch apply 失败，报错退出并提示用户检查目标 worktree 工作区状态。
+
+##### 步骤 6：更新快照
+
+将 `currentTreeHash` 写入快照的 `.tree` 文件，使后续再次 cover 时的基准正确。**只更新 `treeHash`，不更新 `headCommitHash` 和 `stagedTreeHash`**（保留 validate 时写入的原值）。
+
+##### 步骤 7：输出成功提示
+
+```
+✓ 已将验证分支上的修改覆盖到 worktree => <branchName>
+```
+
+**错误消息：**
+
+| 消息常量 | 触发条件 | 提示内容 |
+| -------- | -------- | -------- |
+| `COVER_VALIDATE_NOT_ON_VALIDATE_BRANCH` | 当前分支不是验证分支 | 提示先通过 `clawt validate` 切换到验证分支 |
+| `COVER_VALIDATE_TARGET_NOT_FOUND` | 目标 worktree 不存在 | 提示确认该 worktree 尚未被移除 |
+| `COVER_VALIDATE_NO_SNAPSHOT` | 无快照 | 提示先执行 `clawt validate -b <branch>` 创建快照 |
+| `COVER_VALIDATE_NO_CHANGES` | 无增量变更 | 提示无需覆盖 |
+| `COVER_VALIDATE_WORKING_DIR_CLEAN` | 工作区干净 | 提示可能为误操作，需确认是否继续 |
+| `COVER_VALIDATE_APPLY_FAILED` | patch 应用失败 | 提示检查目标 worktree 工作区状态后重试 |
+
+**实现要点：**
+
+- 命令注册名为 `cover`（非 `cover-validate`），用户通过 `clawt cover` 调用
+- 核心函数：`handleCoverValidate()`（`src/commands/cover-validate.ts`）
+- 辅助函数：
+  - `extractTargetBranchName()`：从验证分支名提取目标分支名
+  - `findTargetWorktreePath()`：查找目标 worktree 路径
+  - `computeIncrementalPatch()`：计算增量 patch
+- 消息常量：`COVER_VALIDATE_MESSAGES`（`src/constants/messages/cover-validate.ts`）
+- `writeSnapshot` 调用时只传 `treeHash`，利用其可选参数特性保留磁盘上的 `headCommitHash` 和 `stagedTreeHash` 原值
+
+---

package/docs/create.md

@@ -0,0 +1,105 @@
+### 5.1 批量创建 Worktree（Worktree 对应分支）
+
+**命令：**
+
+```bash
+clawt create -b <branchName> [-n <count>] [--no-post-create]
+```
+
+**参数：**
+
+| 参数 | 必填 | 说明                                                  |
+| ---- | ---- | ----------------------------------------------------- |
+| `-b, --branch` | 是   | 分支名                                                |
+| `-n, --number` | 否   | 需要创建的 worktree 数量，默认 `1`                      |
+| `--post-create` | 否   | 执行 postCreate hook（默认开启，`--no-post-create` 跳过）。详见 [post-create-hook.md](./post-create-hook.md) |
+
+**运行流程：**
+
+通过 `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('是否继续执行？')` 让用户确认是否继续；用户拒绝则抛出"已取消操作"退出
+     - 用户确认后，如果工作区有未提交的更改，提供交互式选择（避免将修改意外带到主工作分支上）：
+       ```
+       ⚠ 当前分支有未提交的更改，请选择处理方式：
+
+       ❯ reset        - 丢弃所有更改 (git reset --hard HEAD && git clean -fd)
+         stash        - 暂存更改 (git add . && git stash)
+         exit         - 退出，手动处理
+       ```
+       - 选择 reset → 执行 `git reset --hard HEAD && git clean -fd`
+       - 选择 stash → 执行 `git add . && git stash push -m "clawt:auto-stash"`
+       - 选择 exit → 抛出错误"用户选择退出，请手动处理工作区更改后重试"
+       - 处理完成后再次校验工作区是否干净，不干净则报错"工作区仍然不干净，请手动处理"
+     - 执行 `git checkout <clawtMainWorkBranch>`，然后继续创建流程
+4. **主分支工作区干净校验**（`requireCleanWorkingDir`）：确保主工作分支的工作区和暂存区干净，存在未提交更改时报错"主 worktree 有未提交的更改，请先处理"
+5. **创建数量校验**：校验 `-n` 参数必须为正整数，否则报错 `无效的创建数量: "<value>"，请输入正整数`
+6. **分支名合法性校验与转换** (2.3)
+7. **分支名存在性校验** (2.4)
+   - 若 `n = 1`：校验 `branchName`
+   - 若 `n > 1`：校验 `branchName-1` 到 `branchName-n`
+   - 所有分支名在创建任何 worktree **之前**完成全部校验
+8. **批量创建 worktree + 验证分支**
+   - 若 `n = 1`：
+     ```bash
+     git worktree add -b <branchName> ~/.clawt/worktrees/<project>/<branchName>
+     git branch clawt-validate-<branchName>
+     ```
+   - 若 `n > 1`：
+     ```bash
+     git worktree add -b <branchName>-1 ~/.clawt/worktrees/<project>/<branchName>-1
+     git branch clawt-validate-<branchName>-1
+     git worktree add -b <branchName>-2 ~/.clawt/worktrees/<project>/<branchName>-2
+     git branch clawt-validate-<branchName>-2
+     ...
+     git worktree add -b <branchName>-n ~/.clawt/worktrees/<project>/<branchName>-n
+     git branch clawt-validate-<branchName>-n
+     ```
+9. **执行 postCreate hook**：调用 `runPostCreateHooks(worktrees, !options.postCreate)` 以 fire-and-forget 模式后台异步并行执行 postCreate hook（用户自定义的初始化操作）。`--no-post-create` 时跳过。详见 [post-create-hook.md](./post-create-hook.md)
+10. **输出创建日志**
+
+**输出格式：**
+
+```
+✓ 已创建 3 个 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
+────────────────────────────────────────
+```
+
+**实现要点：**
+
+- 前置校验配置定义在 `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` 中
+- postCreate hook 执行逻辑在 `src/hooks/post-create.ts` 中，通过 `src/utils/index.js` 统一导出 `runPostCreateHooks`
+- hook 相关消息常量定义在 `src/constants/messages/post-create.ts` 中
+
+---

package/docs/home.md

@@ -0,0 +1,70 @@
+### 5.20 切换回主工作分支
+
+**命令：**
+
+```bash
+clawt home
+```
+
+**参数：**
+
+无参数。
+
+**功能说明：**
+
+切换回项目的主工作分支。当用户在主 worktree 中处于验证分支或其他分支时，可通过 `clawt home` 一键切换回 `clawtMainWorkBranch` 所记录的主工作分支。
+
+**运行流程：**
+
+1. **场景判断**：根据当前所在位置区分三种场景：
+   - **场景 1：不在 git 仓库中** → 输出错误提示 `请在主 worktree 的根目录下执行 clawt`，退出
+   - **场景 2：在子 worktree 中** → 输出提示信息，引导用户先 `cd` 到主 worktree 路径
+   - **场景 3：在主 worktree 中** → 执行前置校验后切换到主工作分支
+2. **前置校验**（仅场景 3）：调用 `runPreChecks` 执行统一前置校验：
+   - `requireHead`：校验 HEAD 是否存在（仓库至少有一次 commit）
+   - `requireProjectConfig`：校验项目配置文件是否存在且合法
+   - `requireMainBranchExists`：校验配置中的主工作分支在 git 仓库中是否存在
+3. **获取分支信息**（仅场景 3）：
+   - 通过 `getMainWorkBranch()` 获取主工作分支名
+   - 通过 `getCurrentBranch()` 获取当前所在分支名
+4. **判断是否需要切换**：
+   - 当前分支 === 主工作分支 → 输出提示信息，无需切换
+   - 当前分支 !== 主工作分支 → 调用 `ensureOnMainWorkBranch()` 执行切换
+5. **输出结果**
+
+**输出格式：**
+
+```
+# 不在 git 仓库中
+✗ 请在主 worktree 的根目录下执行 clawt
+
+# 在子 worktree 中
+💡 当前在子 worktree 中，请先切换到主 worktree：
+  cd <主 worktree 路径>
+
+# 已在主工作分支上
+已在主工作分支 main 上，无需切换
+
+# 切换成功
+✓ 已从 clawt-validate-feat-login 切换到主工作分支 main
+```
+
+**消息常量：**
+
+定义在 `src/constants/messages/home.ts`：
+
+| 常量 | 说明 |
+| --- | --- |
+| `HOME_ALREADY_ON_MAIN(branch)` | 已在主工作分支上，无需切换 |
+| `HOME_SWITCH_SUCCESS(from, to)` | 切换成功提示，显示原分支和目标分支 |
+| `HOME_NOT_IN_MAIN_WORKTREE(mainPath)` | 在子 worktree 中，提示 cd 到主 worktree 路径 |
+
+**实现要点：**
+
+- 命令注册函数 `registerHomeCommand` 位于 `src/commands/home.ts`
+- 不在 git 仓库中或在子 worktree 中的场景不需要 `runPreChecks`，直接在命令处理函数中判断并输出
+- 前置校验通过 `runPreChecks` 统一调用，传入 `requireHead`、`requireProjectConfig`、`requireMainBranchExists` 三项校验（仅场景 3）
+- 主逻辑依赖 `ensureOnMainWorkBranch`、`getCurrentBranch`、`getMainWorkBranch`、`isMainWorktree`、`isInsideGitRepo`、`getMainWorktreePath` 等工具函数
+- `ensureOnMainWorkBranch()` 仅在需要切换时才调用（当前分支不等于主工作分支时）
+
+---

package/docs/init.md

@@ -0,0 +1,89 @@
+### 5.19 初始化项目级配置
+
+**命令：**
+
+```bash
+# 设置主工作分支（使用当前分支）
+clawt init
+
+# 设置主工作分支（指定分支名）
+clawt init -b <branchName>
+
+# 交互式查看和修改项目配置
+clawt init show
+
+# 以 JSON 格式输出项目配置
+clawt init show --json
+```
+
+**参数：**
+
+| 参数/子命令 | 必填 | 说明 |
+| --- | --- | --- |
+| `-b` | 否 | 指定主工作分支名。不传则使用当前分支 |
+| `show` | 否 | 交互式查看和修改项目配置 |
+| `show --json` | 否 | 以 JSON 格式输出项目配置（跳过交互式流程） |
+
+**功能说明：**
+
+初始化项目级配置，将指定分支记录为该项目的主工作分支（`clawtMainWorkBranch`）。该配置用于 `create` / `run` 时检测当前分支是否为主工作分支，并在偏离时提醒用户。`init show` 子命令提供交互式面板，可查看和修改所有项目配置项（如 `validateRunCommand`、`postCreate`）。项目级配置的完整说明见 [project-config.md](./project-config.md)。
+
+**运行流程（设置模式）：**
+
+1. **主 worktree 校验** (2.1)
+2. **加载现有配置**：尝试读取 `~/.clawt/projects/<projectName>/config.json`（可能为 `null`）
+3. **确定主工作分支名**：
+   - 传了 `-b` → 使用指定的分支名
+   - 未传 `-b` → 先验证 HEAD 存在，再使用当前分支名（`git rev-parse --abbrev-ref HEAD`）
+4. **合并并写入项目级配置**：将 `clawtMainWorkBranch` 合并到现有配置并写入 `~/.clawt/projects/<projectName>/config.json`
+   - 配置文件不存在 → 创建新配置
+   - 配置文件已存在 → 合并现有配置，仅更新 `clawtMainWorkBranch` 字段（保留其他配置项不变）
+5. **输出成功提示**：
+   - 已有配置 → `✓ 已将主工作分支从 <旧分支> 更新为 <新分支>`
+   - 无已有配置 → `✓ 项目初始化成功，主工作分支设置为: <分支名>`
+
+**运行流程（show 模式）：**
+
+1. **主 worktree 校验** (2.1)
+2. **项目配置校验**（`requireProjectConfig`）：读取 `~/.clawt/projects/<projectName>/config.json`
+   - 配置不存在 → 抛出错误 `项目尚未初始化，请先执行 clawt init 设置主工作分支`
+   - 配置缺少 `clawtMainWorkBranch` 字段 → 抛出错误 `项目配置缺少主工作分支信息，请重新执行 clawt init 设置主工作分支`
+   - 配置存在且合法 → 继续
+2.5. **`--json` 模式判断**：如果指定了 `--json` 选项，直接以 JSON 格式输出当前项目配置，跳过交互式流程并返回
+3. **交互式配置编辑**：调用 `interactiveConfigEditor`（`src/utils/config-strategy.ts`），基于 `PROJECT_CONFIG_DEFINITIONS` 构建配置项列表（详见 [project-config.md](./project-config.md)）
+   - 列出所有项目配置项，显示名称、当前值和描述
+   - 用户选择配置项后，根据值类型自动选择输入方式（与全局配置的交互式编辑逻辑一致）
+4. **持久化修改**：将修改后的值合并到当前配置并写入配置文件
+5. **输出成功提示**：`✓ 项目配置 <key> 已设置为 <value>`
+
+**输出格式：**
+
+```
+# 首次初始化
+✓ 项目初始化成功，主工作分支设置为: main
+
+# 更新已有配置
+✓ 已将主工作分支从 develop 更新为 main
+
+# show 交互式修改成功
+✓ 项目配置 validateRunCommand 已设置为 npm test
+
+# show --json 输出
+{"clawtMainWorkBranch":"main","validateRunCommand":"npm test","postCreate":"npm install"}
+
+# show 未初始化（抛出错误）
+项目尚未初始化，请先执行 clawt init 设置主工作分支
+
+# show 配置缺少主工作分支字段（抛出错误）
+项目配置缺少主工作分支信息，请重新执行 clawt init 设置主工作分支
+```
+
+**重复执行：** 支持重复执行，后一次会合并到现有配置中更新 `clawtMainWorkBranch`，不影响其他配置项。
+
+**实现要点：**
+
+- `init show` 子命令从 JSON 展示改为交互式面板，调用 `interactiveConfigEditor`（`src/utils/config-strategy.ts`）实现通用交互式配置编辑
+- 配置项定义来自 `PROJECT_CONFIG_DEFINITIONS`（`src/constants/project-config.ts`），详见 [项目级配置文档](./project-config.md)
+- 消息常量：`MESSAGES.INIT_SELECT_PROMPT`（选择配置项提示语）、`MESSAGES.INIT_SET_SUCCESS`（修改成功提示），定义在 `src/constants/messages/init.ts`
+
+---

package/docs/list.md

@@ -0,0 +1,73 @@
+### 5.8 获取当前项目所有 Worktree
+
+**命令：**
+
+```bash
+clawt list [--json]
+```
+
+**参数：**
+
+| 参数     | 必填 | 说明                                     |
+| -------- | ---- | ---------------------------------------- |
+| `--json` | 否   | 以 JSON 格式输出（仅包含 path 和 branch） |
+
+**运行流程：**
+
+1. **主 worktree 校验** (2.1)
+2. **获取项目名** (2.2)
+3. 获取项目的所有 worktree 列表（扫描 `~/.clawt/worktrees/<project>/` 目录，与 `git worktree list` 交叉验证）
+4. 根据 `--json` 选项决定输出格式：
+   - 指定 `--json` → 以 JSON 格式输出（仅包含 path 和 branch）
+   - 未指定 → 以文本格式输出（包含变更状态信息）
+
+**文本输出格式（默认）：**
+
+每个 worktree 会显示路径、分支名和变更状态。每个 worktree 条目下方额外显示一行状态信息（提交数、变更行数、未提交修改），各条目之间以空行分隔。如果某个 worktree 处于空闲状态（0 个提交、无变更、无未提交修改），其路径会以橙色高亮显示，方便用户快速识别可能需要清理或还未开始工作的 worktree。
+
+```
+当前项目: 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]
+    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
+```
+
+如果没有 worktree：
+
+```
+当前项目: main-project
+
+  (无 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"
+    }
+  ]
+}
+```
+
+---

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` 时启用。
+
+---