clawt 2.20.0 → 3.0.0

package/dist/postinstall.js

@@ -11,6 +11,7 @@ var WORKTREES_DIR = join(CLAWT_HOME, "worktrees");
 var VALIDATE_SNAPSHOTS_DIR = join(CLAWT_HOME, "validate-snapshots");
 var CLAUDE_PROJECTS_DIR = join(homedir(), ".claude", "projects");
 var UPDATE_CHECK_PATH = join(CLAWT_HOME, "update-check.json");
+var PROJECTS_CONFIG_DIR = join(CLAWT_HOME, "projects");
 
 // src/constants/messages/common.ts
 var COMMON_MESSAGES = {
@@ -113,7 +114,9 @@ var RUN_MESSAGES = {
 // src/constants/messages/create.ts
 var CREATE_MESSAGES = {
   /** 创建数量参数无效 */
-  INVALID_COUNT: (value) => `\u65E0\u6548\u7684\u521B\u5EFA\u6570\u91CF: "${value}"\uFF0C\u8BF7\u8F93\u5165\u6B63\u6574\u6570`
+  INVALID_COUNT: (value) => `\u65E0\u6548\u7684\u521B\u5EFA\u6570\u91CF: "${value}"\uFF0C\u8BF7\u8F93\u5165\u6B63\u6574\u6570`,
+  /** 当前不在主工作分支上的警告 */
+  CREATE_WARN_NOT_ON_MAIN_BRANCH: (mainBranch, currentBranch) => `\u5F53\u524D\u4E0D\u5728\u4E3B\u5DE5\u4F5C\u5206\u652F ${mainBranch} \u4E0A\uFF08\u5F53\u524D: ${currentBranch}\uFF09`
 };
 
 // src/constants/messages/merge.ts
@@ -210,7 +213,12 @@ ${branches.map((b) => `    - ${b}`).join("\n")}`,
   /** 自动 sync 开始提示 */
   VALIDATE_AUTO_SYNC_START: (branch) => `\u6B63\u5728\u81EA\u52A8\u540C\u6B65\u4E3B\u5206\u652F\u5230 ${branch} ...`,
   /** 用户拒绝自动 sync */
-  VALIDATE_AUTO_SYNC_DECLINED: (branch) => `\u8BF7\u624B\u52A8\u6267\u884C clawt sync -b ${branch} \u540C\u6B65\u4E3B\u5206\u652F\u540E\u91CD\u8BD5`
+  VALIDATE_AUTO_SYNC_DECLINED: (branch) => `\u8BF7\u624B\u52A8\u6267\u884C clawt sync -b ${branch} \u540C\u6B65\u4E3B\u5206\u652F\u540E\u91CD\u8BD5`,
+  /** 验证分支不存在 */
+  VALIDATE_BRANCH_NOT_FOUND: (validateBranch, branch) => `\u9A8C\u8BC1\u5206\u652F ${validateBranch} \u4E0D\u5B58\u5728\uFF0C\u8BF7\u5148\u6267\u884C clawt create \u6216 clawt run \u521B\u5EFA\u5206\u652F ${branch}`,
+  /** validate 成功（含验证分支信息） */
+  VALIDATE_SUCCESS_WITH_BRANCH: (branch, validateBranch) => `\u2713 \u5DF2\u5207\u6362\u5230\u9A8C\u8BC1\u5206\u652F ${validateBranch} \u5E76\u5E94\u7528\u5206\u652F ${branch} \u7684\u53D8\u66F4
+  \u53EF\u4EE5\u5F00\u59CB\u9A8C\u8BC1\u4E86`
 };
 
 // src/constants/messages/sync.ts
@@ -235,7 +243,9 @@ ${branches.map((b) => `    - ${b}`).join("\n")}`,
   /** sync 交互选择提示 */
   SYNC_SELECT_BRANCH: "\u8BF7\u9009\u62E9\u8981\u540C\u6B65\u7684\u5206\u652F",
   /** sync 模糊匹配到多个结果提示 */
-  SYNC_MULTIPLE_MATCHES: (name) => `"${name}" \u5339\u914D\u5230\u591A\u4E2A\u5206\u652F\uFF0C\u8BF7\u9009\u62E9\uFF1A`
+  SYNC_MULTIPLE_MATCHES: (name) => `"${name}" \u5339\u914D\u5230\u591A\u4E2A\u5206\u652F\uFF0C\u8BF7\u9009\u62E9\uFF1A`,
+  /** sync 后验证分支已重建提示 */
+  SYNC_VALIDATE_BRANCH_REBUILT: (validateBranch) => `\u9A8C\u8BC1\u5206\u652F ${validateBranch} \u5DF2\u91CD\u5EFA`
 };
 
 // src/constants/messages/resume.ts
@@ -276,7 +286,9 @@ ${branches.map((b) => `    - ${b}`).join("\n")}`,
   REMOVE_PARTIAL_FAILURE: (failures) => `\u4EE5\u4E0B worktree \u79FB\u9664\u5931\u8D25\uFF1A
 ${failures.map((f) => `  \u2717 ${f.path}: ${f.error}`).join("\n")}`,
   /** 用户选择保留本地分支 */
-  REMOVE_BRANCHES_KEPT: "\u5DF2\u4FDD\u7559\u672C\u5730\u5206\u652F\uFF0C\u53EF\u7A0D\u540E\u4F7F\u7528 git branch -D <\u5206\u652F\u540D> \u624B\u52A8\u5220\u9664"
+  REMOVE_BRANCHES_KEPT: "\u5DF2\u4FDD\u7559\u672C\u5730\u5206\u652F\uFF0C\u53EF\u7A0D\u540E\u4F7F\u7528 git branch -D <\u5206\u652F\u540D> \u624B\u52A8\u5220\u9664",
+  /** 确认删除本地分支和验证分支 */
+  REMOVE_CONFIRM_DELETE_BRANCHES: "\u662F\u5426\u540C\u65F6\u5220\u9664\u5BF9\u5E94\u7684\u672C\u5730\u5206\u652F\u548C\u9A8C\u8BC1\u5206\u652F\uFF1F"
 };
 
 // src/constants/messages/reset.ts
@@ -393,7 +405,7 @@ var PROJECTS_MESSAGES = {
 // src/constants/messages/completion.ts
 var COMPLETION_MESSAGES = {
   /** completion 命令的主描述 */
-  COMPLETION_COMMAND_DESC: "\u751F\u6210\u548C\u5B89\u88C5 shell \u81EA\u52A8\u8865\u5168\u811A\u672C",
+  COMPLETION_COMMAND_DESC: "\u4E3A\u7EC8\u7AEF\u63D0\u4F9B shell \u81EA\u52A8\u8865\u5168\u529F\u80FD\uFF08bash/zsh\uFF09",
   /** bash 子命令描述 */
   COMPLETION_BASH_DESC: "\u8F93\u51FA bash \u81EA\u52A8\u8865\u5168\u811A\u672C",
   /** zsh 子命令描述 */
@@ -412,6 +424,22 @@ var COMPLETION_MESSAGES = {
   COMPLETION_INSTALL_WRITE_ERROR: (filePath) => `\u65E0\u6CD5\u5199\u5165\u6587\u4EF6 ${filePath}\uFF0C\u8BF7\u68C0\u67E5\u6587\u4EF6\u6743\u9650\u6216\u624B\u52A8\u914D\u7F6E\u3002`
 };
 
+// src/constants/messages/init.ts
+var INIT_MESSAGES = {
+  /** init 成功 */
+  INIT_SUCCESS: (branch) => `\u2713 \u9879\u76EE\u521D\u59CB\u5316\u6210\u529F\uFF0C\u4E3B\u5DE5\u4F5C\u5206\u652F\u8BBE\u7F6E\u4E3A: ${branch}`,
+  /** init 更新 */
+  INIT_UPDATED: (oldBranch, newBranch) => `\u2713 \u5DF2\u5C06\u4E3B\u5DE5\u4F5C\u5206\u652F\u4ECE ${oldBranch} \u66F4\u65B0\u4E3A ${newBranch}`,
+  /** init show 查看当前项目完整配置（JSON 格式） */
+  INIT_SHOW: (configJson) => `${configJson}`,
+  /** init 未初始化 */
+  INIT_NOT_INITIALIZED: "\u9879\u76EE\u5C1A\u672A\u521D\u59CB\u5316\uFF0C\u8BF7\u5148\u6267\u884C clawt init \u8BBE\u7F6E\u4E3B\u5DE5\u4F5C\u5206\u652F",
+  /** 项目未初始化（requireProjectConfig 使用） */
+  PROJECT_NOT_INITIALIZED: "\u9879\u76EE\u5C1A\u672A\u521D\u59CB\u5316\uFF0C\u8BF7\u5148\u6267\u884C clawt init \u8BBE\u7F6E\u4E3B\u5DE5\u4F5C\u5206\u652F",
+  /** 项目配置缺少 clawtMainWorkBranch 字段 */
+  PROJECT_CONFIG_MISSING_BRANCH: "\u9879\u76EE\u914D\u7F6E\u7F3A\u5C11\u4E3B\u5DE5\u4F5C\u5206\u652F\u4FE1\u606F\uFF0C\u8BF7\u91CD\u65B0\u6267\u884C clawt init \u8BBE\u7F6E\u4E3B\u5DE5\u4F5C\u5206\u652F"
+};
+
 // src/constants/messages/index.ts
 var MESSAGES = {
   ...COMMON_MESSAGES,
@@ -427,7 +455,8 @@ var MESSAGES = {
   ...STATUS_MESSAGES,
   ...ALIAS_MESSAGES,
   ...PROJECTS_MESSAGES,
-  ...COMPLETION_MESSAGES
+  ...COMPLETION_MESSAGES,
+  ...INIT_MESSAGES
 };
 
 // src/constants/terminal.ts

package/docs/alias.md

@@ -0,0 +1,108 @@
+### 5.15 命令别名管理
+
+**命令：**
+
+```bash
+# 列出所有命令别名
+clawt alias
+clawt alias list
+
+# 设置命令别名
+clawt alias set <alias> <command>
+
+# 移除命令别名
+clawt alias remove <alias>
+```
+
+**子命令：**
+
+| 子命令 | 说明 |
+| ------ | ---- |
+| `clawt alias` / `clawt alias list` | 列出所有已配置的命令别名 |
+| `clawt alias set <alias> <command>` | 设置命令别名，将 `<alias>` 映射到 `<command>` |
+| `clawt alias remove <alias>` | 移除指定的命令别名 |
+
+**参数：**
+
+| 参数 | 必填 | 说明 |
+| ---- | ---- | ---- |
+| `<alias>` | 是（set / remove） | 别名名称 |
+| `<command>` | 是（set） | 目标内置命令名 |
+
+**约束规则：**
+
+1. **别名不能覆盖内置命令名**：别名不能与任何已注册的内置命令同名（动态检测，当前包括 `list`、`create`、`remove`、`run`、`resume`、`validate`、`merge`、`config`、`sync`、`reset`、`status`、`alias`、`projects`、`completion`、`init`）。如果用户尝试设置与内置命令同名的别名，输出错误提示并返回
+2. **目标必须是内置命令**：别名的目标（`<command>`）必须是已注册的内置命令名。如果指定了不存在的目标命令，输出错误提示并返回
+3. **参数透传**：通过别名调用时，所有选项和参数会完全透传给目标命令，行为与直接调用目标命令完全一致
+
+**持久化：**
+
+别名配置存储在 `~/.clawt/config.json` 的 `aliases` 字段中（类型 `Record<string, string>`，默认 `{}`）。
+
+**运行流程：**
+
+#### `alias list`（默认）
+
+1. 读取配置文件中的 `aliases` 字段
+2. 如果没有配置任何别名，输出提示 `(无别名)`
+3. 如果有别名，逐行输出所有别名映射
+
+**输出格式：**
+
+```
+当前别名列表：
+────────────────────────────────────────
+
+  l → list
+  r → run
+  v → validate
+
+────────────────────────────────────────
+```
+
+#### `alias set <alias> <command>`
+
+1. **校验别名不与内置命令冲突**：检查 `<alias>` 是否为内置命令名，是则输出错误提示并返回
+2. **校验目标命令存在**：检查 `<command>` 是否为已注册的内置命令名，不是则输出错误提示并返回
+3. 将别名写入配置文件的 `aliases` 字段（如果别名已存在，覆盖旧值）
+4. 输出成功提示
+
+**输出格式：**
+
+```
+✓ 已设置别名: l → list
+```
+
+#### `alias remove <alias>`
+
+1. 读取配置文件中的 `aliases` 字段
+2. 检查指定的别名是否存在，不存在则输出错误提示并返回
+3. 从 `aliases` 中删除该别名并写入配置文件
+4. 输出成功提示
+
+**输出格式：**
+
+```
+✓ 已移除别名: l
+```
+
+**别名使用示例：**
+
+```bash
+# 设置别名
+clawt alias set l list
+clawt alias set r run
+clawt alias set v validate
+
+# 使用别名（等同于对应的完整命令）
+clawt l          # 等同于 clawt list
+clawt r task.md  # 等同于 clawt run task.md
+
+# 查看所有别名
+clawt alias list
+
+# 移除别名
+clawt alias remove l
+```
+
+---

package/docs/completion.md

@@ -0,0 +1,55 @@
+### 5.16 `clawt completion` 命令
+
+为终端环境（bash/zsh）生成并安装 `clawt` 的命令、选项及参数的自动补全脚本。
+
+#### 语法
+```bash
+clawt completion bash
+clawt completion zsh
+clawt completion install
+```
+
+#### 子命令说明
+
+| 子命令    | 说明                                                                                |
+| --------- | ----------------------------------------------------------------------------------- |
+| `bash`    | 输出适用于 bash 的补全脚本（用户可重定向到 `~/.bashrc`）                                |
+| `zsh`     | 输出适用于 zsh 的补全脚本（用户可重定向到 `~/.zshrc`）                                  |
+| `install` | 自动检测当前 shell 类型，将补全脚本追加到对应的配置文件中                                  |
+
+#### `install` 子命令流程
+
+1. 通过 `process.env.SHELL` 检测当前 shell 类型
+2. 根据 shell 类型确定目标配置文件：
+   - zsh → `~/.zshrc`（追加 `source <(clawt completion zsh)`）
+   - bash → `~/.bashrc`（追加 `eval "$(clawt completion bash)"`）
+3. 检查目标文件中是否已包含 `clawt completion`，已存在则跳过并提示
+4. 追加成功后提示用户重启终端或 source 配置文件
+5. 未知 shell 类型时输出警告，提示手动配置
+
+#### 动态补全特性
+
+补全脚本通过内部子命令 `_complete` 实现动态补全，不对外公开。补全引擎基于 Commander.js 的命令树结构遍历，支持以下场景：
+
+| 场景                         | 补全行为                                                   |
+| ---------------------------- | ---------------------------------------------------------- |
+| `-b` / `--branch` 参数之后   | 动态列出当前项目所有 worktree 分支名（通过 `getProjectWorktrees`） |
+| `-f` / `--file` 参数之后     | 动态列出匹配的文件和子目录（不限制文件类型，支持子目录递归浏览）    |
+| `config set` / `config get` 之后 | 动态列出所有配置项键名（从 `CONFIG_DEFINITIONS` 获取）         |
+| 输入以 `-` 开头              | 列出当前命令层级的可用选项（short/long）                       |
+| 其他情况                     | 列出当前命令层级的可用子命令及别名                              |
+
+**文件路径补全细节：**
+- 支持子目录递归浏览（如 `tasks/` 后继续 Tab 可深入子目录）
+- 目录候选项以 `/` 结尾，补全时不自动追加空格
+- 不限制文件类型，列出所有非隐藏文件
+- 跳过隐藏文件和目录（以 `.` 开头）
+
+#### 实现说明
+
+- 补全命令注册函数：`registerCompletionCommand()`（在 `src/commands/completion.ts`）
+- 消息常量：`COMPLETION_MESSAGES`（在 `src/constants/messages/completion.ts`）
+- 核心函数：`generateCompletions()` 解析当前输入上下文并输出候选项，`completeFilePath()` 处理文件路径补全，`tryCompleteSpecialArg()` 处理特殊参数（分支名、文件路径、配置键）的动态补全，`completeFromCommandTree()` 基于命令树遍历生成子命令和选项候选项
+- shell 脚本生成：`getBashScript()`、`getZshScript()` 分别生成对应 shell 的补全脚本
+
+---

package/docs/config-file.md

@@ -0,0 +1,43 @@
+### 5.7 默认配置文件
+
+**路径：** `~/.clawt/config.json`
+
+**生成时机：** 全局安装后自动生成（通过 `postinstall` 脚本）。
+
+**升级策略：** 配置文件已存在时，执行增量合并而非简单跳过：
+
+- **新版本新增的配置项** → 使用默认值补充到用户配置中
+- **用户已有的配置项** → 保留用户的值，不覆盖
+- **新版本已移除的配置项** → 从用户配置中删除
+
+仅在合并后配置发生变化时才写入文件。配置文件损坏或无法解析时，视为不存在，重新生成默认配置。
+
+**默认内容：**
+
+```json
+{
+  "autoDeleteBranch": false,
+  "claudeCodeCommand": "claude",
+  "autoPullPush": false,
+  "confirmDestructiveOps": true,
+  "maxConcurrency": 0,
+  "terminalApp": "auto",
+  "aliases": {},
+  "autoUpdate": true
+}
+```
+
+**配置项说明：**
+
+| 配置项             | 类型      | 默认值    | 说明                                               |
+| ------------------ | --------- | --------- | -------------------------------------------------- |
+| `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） |
+| `aliases` | `Record<string, string>` | `{}` | 命令别名映射，键为别名，值为目标内置命令名 |
+| `autoUpdate` | `boolean` | `true` | 是否启用自动更新检查（每 24 小时通过 npm registry 检查一次新版本） |
+
+---

package/docs/config.md

@@ -0,0 +1,91 @@
+### 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` 自动分发
+- `saveConfig(config)`：`src/utils/config.ts` 中新增的通用配置写入函数，将完整配置对象持久化到文件
+- `formatConfigValue(value)`：支持 boolean（绿色/黄色）和 string/number（青色）的格式化显示。对象类型配置项（如 `aliases`）在交互式列表中通过 `JSON.stringify` 以暗淡色显示
+
+---

package/docs/create.md

@@ -0,0 +1,85 @@
+### 5.1 批量创建 Worktree（Worktree 对应分支）
+
+**命令：**
+
+```bash
+clawt create -b <branchName> [-n <count>]
+```
+
+**参数：**
+
+| 参数 | 必填 | 说明                                                  |
+| ---- | ---- | ----------------------------------------------------- |
+| `-b` | 是   | 分支名                                                |
+| `-n` | 否   | 需要创建的 worktree 数量，默认 `1`                      |
+
+**运行流程：**
+
+1. **主 worktree 校验** (2.1)
+2. **确保在主工作分支上**（`ensureOnMainWorkBranch`）：在创建 worktree 之前，确保当前处于配置的主工作分支（`clawtMainWorkBranch`）上。
+   - 如果当前分支**是** `clawtMainWorkBranch`，正常继续
+   - 如果当前在**验证分支**（`clawt-validate-` 前缀）上：
+     - 验证分支上的修改视为可丢弃的临时状态
+     - 如果工作区有未提交更改，自动执行 `git reset --hard HEAD && git clean -fd` 清理；若已干净则跳过清理
+     - 然后自动切换到主工作分支，继续创建流程
+   - 如果当前在**其他普通分支**上：
+     - 如果工作区有未提交的更改，提供交互式选择（避免将修改意外带到主工作分支上）：
+       ```
+       ⚠ 当前分支有未提交的更改，请选择处理方式：
+
+       ❯ 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>`，然后继续创建流程
+3. **创建数量校验**：校验 `-n` 参数必须为正整数，否则报错 `无效的创建数量: "<value>"，请输入正整数`
+4. **分支名合法性校验与转换** (2.3)
+5. **分支名存在性校验** (2.4)
+   - 若 `n = 1`：校验 `branchName`
+   - 若 `n > 1`：校验 `branchName-1` 到 `branchName-n`
+   - 所有分支名在创建任何 worktree **之前**完成全部校验
+6. **批量创建 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
+     ```
+7. **输出创建日志**
+
+**输出格式：**
+
+```
+✓ 已创建 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
+────────────────────────────────────────
+```
+
+---

package/docs/init.md

@@ -0,0 +1,65 @@
+### 5.19 初始化项目级配置
+
+**命令：**
+
+```bash
+# 设置主工作分支（使用当前分支）
+clawt init
+
+# 设置主工作分支（指定分支名）
+clawt init -b <branchName>
+
+# 查看当前项目的 init 配置
+clawt init show
+```
+
+**参数：**
+
+| 参数/子命令 | 必填 | 说明 |
+| --- | --- | --- |
+| `-b` | 否 | 指定主工作分支名。不传则使用当前分支 |
+| `show` | 否 | 查看当前项目的 init 配置 |
+
+**功能说明：**
+
+初始化项目级配置，将指定分支记录为该项目的主工作分支（`clawtMainWorkBranch`）。该配置用于 `create` / `run` 时检测当前分支是否为主工作分支，并在偏离时提醒用户。详见 [2.6 项目级配置](#26-项目级配置)。
+
+**运行流程（设置模式）：**
+
+1. **主 worktree 校验** (2.1)
+2. **确定主工作分支名**：
+   - 传了 `-b` → 使用指定的分支名
+   - 未传 `-b` → 使用当前分支名（`git rev-parse --abbrev-ref HEAD`）
+3. **写入项目级配置**：将 `clawtMainWorkBranch` 写入 `~/.clawt/projects/<projectName>/config.json`
+   - 配置文件不存在 → 创建
+   - 配置文件已存在 → 覆盖整个配置文件内容
+4. **输出成功提示**
+
+**运行流程（show 模式）：**
+
+1. **主 worktree 校验** (2.1)
+2. **读取项目级配置**：读取 `~/.clawt/projects/<projectName>/config.json`
+   - 配置不存在 → 抛出错误 `项目尚未初始化，请先执行 clawt init 设置主工作分支`
+   - 配置存在 → 以 JSON 格式输出配置内容
+
+**输出格式：**
+
+```
+# 首次初始化
+✓ 项目初始化成功，主工作分支设置为: main
+
+# 更新已有配置
+✓ 已将主工作分支从 develop 更新为 main
+
+# show 查看配置（JSON 格式输出）
+{
+  "clawtMainWorkBranch": "main"
+}
+
+# show 未初始化（抛出错误）
+项目尚未初始化，请先执行 clawt init 设置主工作分支
+```
+
+**重复执行：** 支持重复执行，后一次覆盖前一次的配置。
+
+---

package/docs/list.md

@@ -0,0 +1,67 @@
+### 5.8 获取当前项目所有 Worktree
+
+**命令：**
+
+```bash
+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. 根据 `--json` 选项决定输出格式：
+   - 指定 `--json` → 以 JSON 格式输出
+   - 未指定 → 以文本格式输出
+
+**文本输出格式（默认）：**
+
+每个 worktree 会显示路径、分支名和变更状态。每个 worktree 条目下方额外显示一行状态信息（提交数、变更行数、未提交修改），各条目之间以空行分隔。如果某个 worktree 处于空闲状态（0 个提交、无变更、无未提交修改），其路径会以橙色高亮显示，方便用户快速识别可能需要清理或还未开始工作的 worktree。
+
+```
+当前项目: main-project
+
+  ~/.clawt/worktrees/main-project/feature-scheme-1   [feature-scheme-1]
+  ~/.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]
+
+共 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` 时启用。
+
+---