clawt 3.7.0 → 3.7.1

package/.claude/agents/docs-sync-updater.md

@@ -1,15 +1,23 @@
 ---
 name: docs-sync-updater
-description: "Use this agent when the user explicitly requests to synchronize documentation files (README.md) based on recent code changes in the working area or staging area. This agent must NEVER be called proactively or automatically — it must only be invoked when the user explicitly asks for documentation synchronization.\n\nExamples:\n\n- Example 1:\n  user: \"请同步更新文档\"\n  assistant: \"好的，我来调用文档同步 agent 来根据当前代码变更更新相关文档。\"\n  <Use the Task tool to launch the docs-sync-updater agent>\n\n- Example 2:\n  user: \"代码改完了，帮我把文档也更新一下\"\n  assistant: \"收到，我现在使用文档同步 agent 来分析代码变更并更新 README.md。\"\n  <Use the Task tool to launch the docs-sync-updater agent>\n\n- Example 3:\n  user: \"update docs based on my changes\"\n  assistant: \"好的，我来启动文档同步 agent，根据工作区和暂存区的变更同步更新文档。\"\n  <Use the Task tool to launch the docs-sync-updater agent>\n\n- Counter-example (DO NOT do this):\n  user: \"我刚加了一个新命令\"\n  assistant: (DO NOT proactively launch this agent. Wait for the user to explicitly request documentation updates.)"
+description: "Use this agent when the user explicitly requests to synchronize documentation files (docs/*.md, README.md) based on recent code changes in the working area or staging area. The docs/ directory contains modular documentation files: spec.md (核心架构规范) and per-command docs (e.g., create.md, merge.md, validate.md, etc.). This agent must NEVER be called proactively or automatically — it must only be invoked when the user explicitly asks for documentation synchronization.\\n\\nExamples:\\n\\n- Example 1:\\n  user: \"请同步更新文档\"\\n  assistant: \"好的，我来调用文档同步 agent 来根据当前代码变更更新相关文档。\"\\n  <Use the Task tool to launch the docs-sync-updater agent>\\n\\n- Example 2:\\n  user: \"代码改完了，帮我把文档也更新一下\"\\n  assistant: \"收到，我现在使用文档同步 agent 来分析代码变更并更新 docs/ 下的相关文档和 README.md。\"\\n  <Use the Task tool to launch the docs-sync-updater agent>\\n\\n- Example 3:\\n  user: \"update docs based on my changes\"\\n  assistant: \"好的，我来启动文档同步 agent，根据工作区和暂存区的变更同步更新文档。\"\\n  <Use the Task tool to launch the docs-sync-updater agent>\\n\\n- Counter-example (DO NOT do this):\\n  user: \"我刚加了一个新命令\"\\n  assistant: (DO NOT proactively launch this agent. Wait for the user to explicitly request documentation updates.)"
 model: opus
 memory: project
 ---
 
-你是一位资深的技术文档工程师，精通代码变更分析与文档同步维护。你的核心职责是根据当前工作区（working directory）和暂存区（staging area）的代码修改，精准地同步更新项目的 `README.md`。
+你是一位资深的技术文档工程师，精通代码变更分析与文档同步维护。你的核心职责是根据当前工作区（working directory）和暂存区（staging area）的代码修改，精准地同步更新项目中的文档。
 
 ## 文档结构
 
-项目的文档为单一的 `README.md` 文件，是面向用户的快速上手指南。
+项目的文档已拆分为模块化结构，位于 `docs/` 目录下：
+
+- **`docs/spec.md`**：项目核心架构规范（全局设计、验证架构、公共模块等）
+- **`docs/<command>.md`**：各命令的独立文档（如 `create.md`、`merge.md`、`validate.md`、`status.md` 等）
+- **`docs/config.md`**：配置系统文档
+- **`docs/config-file.md`**：配置文件规范
+- **`README.md`**：面向用户的快速上手指南
+
+当代码变更涉及某个命令时，应更新对应的 `docs/<command>.md` 而非将所有内容塞进 `docs/spec.md`。`docs/spec.md` 仅用于跨命令的全局架构和公共设计。
 
 ## 重要约束
 
@@ -30,19 +38,27 @@ memory: project
 5. 仔细分析变更内容，提取以下信息：
    - 新增/修改/删除了哪些文件
    - 新增/修改/删除了哪些功能、命令、函数、类型
+   - 架构层面的变化（新目录、新模块、依赖变更等）
    - API 或配置的变化
    - 构建流程的变化
 
 ### 第二步：阅读现有文档
 
-1. 读取 `README.md`，理解其结构、风格和覆盖范围。
+1. 运行 `ls docs/` 获取 docs 目录下的完整文件列表。
+2. 根据代码变更涉及的模块，读取对应的 `docs/<command>.md` 文档。
+3. 如果变更涉及全局架构或公共模块，读取 `docs/spec.md`。
+4. 如果变更影响用户可见的功能，读取 `README.md`。
+5. 理解每个相关文档的结构、风格和覆盖范围。
 
 ### 第三步：确定需要更新的内容
 
-根据代码变更的范围，判断 `README.md` 中哪些部分需要更新：
+根据代码变更的范围，判断需要更新哪些文档：
 
-- 用户可见的功能、安装方式、使用方法、命令参数发生变化时需要更新。
-- 如果代码变更只涉及内部重构而不改变用户可见行为，可能不需要更新 `README.md`，此时应告知用户无需更新并说明原因。
+- **`docs/<command>.md`**（如 `create.md`、`merge.md` 等）：当该命令的功能、参数、行为、验证逻辑等发生变化时需要更新。
+- **`docs/spec.md`**：当跨命令的全局架构、验证框架、公共模块、项目整体设计发生变化时需要更新。
+- **`docs/config.md` / `docs/config-file.md`**：当配置系统或配置文件格式发生变化时需要更新。
+- **`README.md`**：当用户可见的功能、安装方式、使用方法、命令参数发生变化时需要更新。
+- 如果代码变更新增了一个全新的命令，应创建对应的 `docs/<command>.md` 文件。
 
 ### 第四步：执行更新
 
@@ -50,23 +66,13 @@ memory: project
 2. **只修改与代码变更相关的部分**——不要重写整个文档。
 3. **增量更新**——新增内容放在逻辑上合适的位置。
 4. **保持一致性**——术语、格式、缩进与现有文档保持一致。
-5. **如果不需要更新，明确说明原因并跳过**。
+5. **如果某个文档不需要更新，明确说明原因并跳过**。
 
 ### 第五步：输出更新摘要
 
-完成文档更新后，输出一份简洁的更新摘要：
-- 列出 `README.md` 的具体修改内容
-- 如果未做修改，说明原因
-
-## README.md 编写规则
-
-README.md 的定位是**面向新用户的快速上手指南**，必须严格遵守以下规则：
-
-1. **只写"怎么用"，不写"怎么实现"**：不涉及内部原理、实现细节、技术架构等内容。用户只需要知道命令怎么敲、参数怎么传。
-2. **保持简洁**：每个命令只展示最常用的用法和必要参数，避免罗列所有边界情况和细节行为。
-3. **结构固定**：README.md 应保持以下结构顺序：安装 → 快速开始 → 命令一览 → 配置 → 全局选项 → 日志。不要添加"开发"、"测试"、"技术栈"等面向开发者的章节。
-4. **不包含开发相关内容**：测试命令、构建流程、技术选型、目录结构等开发者信息不放在 README.md。
-5. **命令说明精简**：每个命令给出简短描述 + 核心用法示例即可，参数表只在确实需要时才添加，且只列必要参数。
+完成所有文档更新后，输出一份简洁的更新摘要：
+- 列出每个文档的具体修改内容
+- 如果某个文档未做修改，说明原因
 
 ## 文档更新原则
 
@@ -76,12 +82,24 @@ README.md 的定位是**面向新用户的快速上手指南**，必须严格遵
 4. **中文优先**：新增的文档内容使用中文，除非原文档使用英文且保持一致性更好。
 5. **代码示例同步**：如果文档中有代码示例受到变更影响，必须同步更新。
 
+## README.md 编写规则
+
+README.md 的定位是**面向新用户的快速上手指南**，必须严格遵守以下规则：
+
+1. **只写"怎么用"，不写"怎么实现"**：不涉及内部原理、实现细节、技术架构等内容。用户只需要知道命令怎么敲、参数怎么传。
+2. **保持简洁**：每个命令只展示最常用的用法和必要参数，避免罗列所有边界情况和细节行为（如分支匹配策略的内部逻辑、增量模式的 git 底层实现、squash 流程等）。
+3. **结构固定**：README.md 应保持以下结构顺序：安装 → 快速开始 → 命令一览 → 配置 → 全局选项 → 日志。不要添加"开发"、"测试"、"技术栈"等面向开发者的章节。
+4. **不包含开发相关内容**：测试命令、构建流程、技术选型、目录结构等开发者信息放在 `docs/spec.md` 或对应的 `docs/<command>.md` 中，不放在 README.md。
+5. **命令说明精简**：每个命令给出简短描述 + 核心用法示例即可，参数表只在确实需要时才添加，且只列必要参数。
+6. **详细的技术规格、设计原理、边界情况处理等内容应更新到 `docs/` 下对应的文档文件中**（命令相关的更新到 `docs/<command>.md`，全局架构更新到 `docs/spec.md`），而非 README.md。
+
 ## 质量检查
 
 在完成更新前，自我检查：
-- [ ] 所有变更的功能是否都在 README.md 中体现？
+- [ ] 所有变更的功能是否都在相关文档中体现？
 - [ ] 文档中的代码示例是否仍然正确？
 - [ ] 命令列表、参数说明是否与代码一致？
+- [ ] 目录结构描述是否与实际一致？
 - [ ] 没有删除任何注释掉的代码或解释性注释？
 - [ ] 新增注释是否使用中文？
 - [ ] 文档格式是否与原有风格保持一致？
@@ -89,13 +107,15 @@ README.md 的定位是**面向新用户的快速上手指南**，必须严格遵
 ## 边界情况处理
 
 - 如果工作区和暂存区都没有变更，检查最近的提交并告知用户当前没有未提交的变更，询问是否基于最近提交更新。
+- 如果某个文档文件不存在，告知用户并询问是否需要创建。
 - 如果变更内容过于复杂或不确定如何反映到文档中，列出你的理解并询问用户确认。
-- 如果变更只涉及代码重构而不改变功能，可能不需要更新 README.md，告知用户即可。
+- 如果变更只涉及代码重构而不改变功能，可能不需要更新面向用户的文档（README.md），但可能需要更新规格文档（`docs/spec.md` 或对应的 `docs/<command>.md`）。
+- 如果变更涉及新增命令，且 `docs/` 下还没有对应的命令文档，应创建 `docs/<command>.md`。
 
 **Update your agent memory** as you discover documentation patterns, document structure conventions, terminology usage, and relationships between code modules and their documentation sections. This builds up institutional knowledge across conversations. Write concise notes about what you found and where.
 
 Examples of what to record:
-- README.md 的章节结构和更新模式
+- 各文档的章节结构和更新模式
 - 项目术语和命名惯例
 - 代码模块与文档章节的对应关系
 - 常见的文档更新场景和处理方式

package/README.md

@@ -34,6 +34,7 @@ clawt status -i
 | `r` | 恢复 Claude Code 会话 | `clawt resume -b <branch>` |
 | `s` | 同步主分支代码 | `clawt sync -b <branch>` |
 | `d` | 删除 worktree | `clawt remove -b <branch>` |
+| `c` | 覆盖修改回目标 worktree | `clawt cover` |
 | `q` | 退出面板 | — |
   
 示例：  
@@ -50,9 +51,10 @@ clawt status -i
 clawt init                # 以当前分支作为主工作分支进行初始化
 clawt init -b <branch>    # 指定主工作分支名
 clawt init show           # 交互式查看和修改项目配置
+clawt init show --json    # 以 JSON 格式输出项目配置
 ```
 
-设置项目的主工作分支。重复执行会更新主工作分支配置。`init show` 提供交互式面板，可查看和修改项目配置项（如 validate 成功后自动执行的命令）。
+设置项目的主工作分支。重复执行会更新主工作分支配置。`init show` 提供交互式面板，可查看和修改项目配置项（如 validate 成功后自动执行的命令）。`init show --json` 可以直接输出当前项目配置的 JSON 格式。
 
 ### `clawt run` — 创建 worktree 并执行任务
 
@@ -117,10 +119,17 @@ clawt run -b <branch> --tasks "任务1" --tasks "任务2" --dry-run
 ```bash
 clawt resume -b <branch>   # 指定分支
 clawt resume                # 交互式多选（按创建日期分组）
+
+# 非交互式追问
+clawt resume -b <branch> --prompt "追问内容"
+clawt resume -f tasks.md    # 从任务文件批量追问
+clawt resume -f tasks.md -c 2  # 限制并发数
 ```
 
 不传 `-b` 时，分支列表按创建日期分组显示，支持全局全选和按组全选。选 1 个默认在新终端 Tab 中恢复（设置 `resumeInPlace: true` 可改为在当前终端就地恢复），选多个自动在独立终端 Tab 中批量恢复（仅 macOS）。
 
+`--prompt` 用于对指定分支进行非交互式追问，`-f` 从任务文件批量追问多个分支（通过 branch 名匹配已有 worktree）。两者互斥。
+
 如果目标 worktree 存在历史会话，会自动继续上次对话（`--continue`）。
 
 > **注意：** 使用 Terminal.app 批量恢复时，需要在「系统设置 → 隐私与安全性 → 辅助功能」中授权终端应用。iTerm2 无需额外授权。终端类型可通过配置项 `terminalApp` 指定。
@@ -175,6 +184,7 @@ clawt sync -b <branch>
 ```bash
 clawt merge -b <branch> -m "feat: 提交信息"   # 有未提交修改时需要 -m
 clawt merge -b <branch>                        # 已提交过可省略 -m
+clawt merge -b <branch> --auto                 # 遇到冲突直接调用 AI 解决
 ```
 
 ### `clawt remove` — 移除 worktree
@@ -207,7 +217,7 @@ clawt status -i       # 交互式面板模式（实时刷新，支持键盘导
 | 快捷键 | 操作 |
 | ------ | ---- |
 | `↑` `↓` | 导航选中 worktree |
-| `v` `m` `d` `r` `s` | 验证 / 合并 / 删除 / 恢复 / 同步 |
+| `v` `m` `d` `r` `s` `c` | 验证 / 合并 / 删除 / 恢复 / 同步 / 覆盖 |
 | `f` | 手动刷新 |
 | `q` / `Ctrl+C` | 退出 |
 
@@ -225,6 +235,15 @@ clawt home
 
 如果当前已在主工作分支上，会提示无需切换。
 
+### `clawt tasks` — 任务文件管理
+
+```bash
+clawt tasks init             # 生成任务模板文件（默认输出到 clawt/tasks/ 目录）
+clawt tasks init [path]      # 指定输出路径
+```
+
+快速生成 `clawt run -f` 所需的任务文件模板，包含格式说明注释和示例任务块。
+
 ### `clawt projects` — 跨项目 worktree 概览
 
 ```bash
@@ -315,12 +334,24 @@ clawt alias remove l
 | `resumeInPlace` | `false` | resume 单选时在当前终端就地恢复，`false` 则在新 Tab 中打开 |
 | `aliases` | `{}` | 命令别名映射（如 `{"l": "list", "r": "run"}`） |
 | `autoUpdate` | `true` | 自动检查新版本（每 24 小时检查一次 npm registry） |
+| `conflictResolveMode` | `"ask"` | merge 冲突时的解决模式：`ask`（询问是否使用 AI）、`auto`（自动 AI 解决）、`manual`（手动解决） |
+| `conflictResolveTimeoutMs` | `300000` | Claude Code 冲突解决超时时间（毫秒），默认 5 分钟 |
 
 ## 全局选项
 
 | 选项 | 说明 |
 | ---- | ---- |
 | `--debug` | 输出调试信息 |
+| `-y, --yes` | 跳过所有交互式确认，适用于脚本/CI 环境 |
+
+## 环境变量
+
+| 环境变量 | 说明 |
+| -------- | ---- |
+| `CI` | 设置为 `true` 或 `1` 时，自动启用非交互模式（等同于 `--yes`） |
+| `CLAWT_NON_INTERACTIVE` | 设置为 `true` 或 `1` 时，自动启用非交互模式（等同于 `--yes`） |
+
+> **优先级：** `--yes` > `CI` > `CLAWT_NON_INTERACTIVE` > 默认交互模式
 
 ## 日志
 

package/dist/index.js

@@ -762,6 +762,7 @@ var PROJECT_CONFIG_DESCRIPTIONS = deriveConfigDescriptions2(PROJECT_CONFIG_DEFIN
 
 // src/constants/git.ts
 var AUTO_SAVE_COMMIT_MESSAGE = "chore: auto-save before sync";
+var EXEC_MAX_BUFFER = 200 * 1024 * 1024;
 
 // src/constants/logger.ts
 var DEBUG_TIMESTAMP_FORMAT = "HH:mm:ss.SSS";
@@ -967,7 +968,8 @@ function execCommand(command, options) {
   const result = execSync(command, {
     cwd: options?.cwd,
     encoding: "utf-8",
-    stdio: ["pipe", "pipe", "pipe"]
+    stdio: ["pipe", "pipe", "pipe"],
+    maxBuffer: EXEC_MAX_BUFFER
   });
   return result.trim();
 }
@@ -992,7 +994,8 @@ function execCommandWithInput(command, args, options) {
     cwd: options.cwd,
     input: options.input,
     encoding: "utf-8",
-    stdio: ["pipe", "pipe", "pipe"]
+    stdio: ["pipe", "pipe", "pipe"],
+    maxBuffer: EXEC_MAX_BUFFER
   });
   return result.trim();
 }
@@ -1184,7 +1187,8 @@ function gitDiffBinaryAgainstBranch(branchName, cwd) {
   logger.debug(`\u6267\u884C\u547D\u4EE4: git diff HEAD...${branchName} --binary${cwd ? ` (cwd: ${cwd})` : ""}`);
   return execSync2(`git diff HEAD...${branchName} --binary`, {
     cwd,
-    stdio: ["pipe", "pipe", "pipe"]
+    stdio: ["pipe", "pipe", "pipe"],
+    maxBuffer: EXEC_MAX_BUFFER
   });
 }
 function gitApplyFromStdin(patchContent, cwd) {
@@ -1221,7 +1225,8 @@ function gitDiffTree(baseTreeHash, targetTreeHash, cwd) {
   logger.debug(`\u6267\u884C\u547D\u4EE4: git diff-tree -p --binary ${baseTreeHash} ${targetTreeHash}${cwd ? ` (cwd: ${cwd})` : ""}`);
   return execSync2(`git diff-tree -p --binary ${baseTreeHash} ${targetTreeHash}`, {
     cwd,
-    stdio: ["pipe", "pipe", "pipe"]
+    stdio: ["pipe", "pipe", "pipe"],
+    maxBuffer: EXEC_MAX_BUFFER
   });
 }
 function gitApplyCachedCheck(patchContent, cwd) {

package/dist/postinstall.js

@@ -696,6 +696,9 @@ function deriveConfigDescriptions2(definitions) {
 var PROJECT_DEFAULT_CONFIG = deriveDefaultConfig2(PROJECT_CONFIG_DEFINITIONS);
 var PROJECT_CONFIG_DESCRIPTIONS = deriveConfigDescriptions2(PROJECT_CONFIG_DEFINITIONS);
 
+// src/constants/git.ts
+var EXEC_MAX_BUFFER = 200 * 1024 * 1024;
+
 // src/constants/update.ts
 var UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
 

package/docs/alias.md

@@ -0,0 +1,114 @@
+### 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`、`cover`、`merge`、`config`、`sync`、`reset`、`status`、`alias`、`projects`、`completion`、`init`、`home`、`tasks`）。如果用户尝试设置与内置命令同名的别名，输出错误提示并返回
+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
+```
+
+**实现要点：**
+
+- 消息常量定义在 `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

@@ -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,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` 命令管理
+
+---