aico-cli 0.3.17 → 0.4.0

package/templates/commands/git/cleanBranches.md

@@ -0,0 +1,102 @@
+---
+description: 安全查找并清理已合并或过期的 Git 分支，支持 dry-run 模式与自定义基准/保护分支
+allowed-tools: Read(**), Exec(git fetch, git config, git branch, git remote, git push, git for-each-ref, git log), Write()
+argument-hint: [--base <branch>] [--stale <days>] [--remote] [--force] [--dry-run] [--yes]
+# examples:
+#   - /git-cleanBranches --dry-run
+#   - /git-cleanBranches --base release/v2.1 --stale 90
+#   - /git-cleanBranches --remote --yes
+---
+
+# Claude Command: Clean Branches
+
+该命令**安全地**识别并清理**已合并**或**长期未更新 (stale)** 的 Git 分支。
+默认以**只读预览 (`--dry-run`)** 模式运行，需明确指令才会执行删除操作。
+
+---
+
+## Usage
+
+```bash
+# [最安全] 预览将要清理的分支，不执行任何删除
+/git-cleanBranches --dry-run
+
+# 清理已合并到 main 且超过 90 天未动的本地分支 (需逐一确认)
+/git-cleanBranches --stale 90
+
+# 清理已合并到 release/v2.1 的本地与远程分支 (自动确认)
+/git-cleanBranches --base release/v2.1 --remote --yes
+
+# [危险] 强制删除一个未合并的本地分支
+/git-cleanBranches --force outdated-feature
+```
+
+### Options
+
+- `--base <branch>`：指定清理的基准分支（默认为仓库的 `main`/`master`）。
+- `--stale <days>`：清理超过指定天数未提交的分支（默认不启用）。
+- `--remote`：同时清理远程已合并/过期的分支。
+- `--dry-run`：**默认行为**。仅列出将要删除的分支，不执行任何操作。
+- `--yes`：跳过逐一确认的步骤，直接删除所有已识别的分支（适合 CI/CD）。
+- `--force`：使用 `-D` 强制删除本地分支（即使未合并）。
+
+---
+
+## What This Command Does
+
+1. **配置与安全预检**
+   - **更新信息**：自动执行 `git fetch --all --prune`，确保分支状态最新。
+   - **读取保护分支**：从 Git 配置读取不应被清理的分支列表（见下文“Configuration”）。
+   - **确定基准**：使用 `--base` 参数或自动识别的 `main`/`master` 作为比较基准。
+
+2. **分析识别（Find）**
+   - **已合并分支**：找出已完全合并到 `--base` 的本地（及远程，如加 `--remote`）分支。
+   - **过期分支**：如指定 `--stale <days>`，找出最后一次提交在 N 天前的分支。
+   - **排除保护分支**：从待清理列表中移除所有已配置的保护分支。
+
+3. **报告预览（Report）**
+   - 清晰列出“将要删除的已合并分支”与“将要删除的过期分支”。
+   - 若无 `--yes` 参数，**命令到此结束**，等待用户确认后再次执行（不带 `--dry-run`）。
+
+4. **执行清理（Execute）**
+   - **仅在不带 `--dry-run` 且用户确认后**（或带 `--yes`）执行。
+   - 逐一删除已识别的分支，除非用户在交互式确认中选择跳过。
+   - 本地用 `git branch -d <branch>`；远程用 `git push origin --delete <branch>`。
+   - 若指定 `--force`，本地删除会改用 `git branch -D <branch>`。
+
+---
+
+## Configuration (一次配置，永久生效)
+
+为防止误删重要分支（如 `develop`, `release/*`），请在仓库的 Git 配置中添加保护规则。命令会自动读取。
+
+```bash
+# 保护 develop 分支
+git config --add branch.cleanup.protected develop
+
+# 保护所有 release/ 开头的分支 (通配符)
+git config --add branch.cleanup.protected 'release/*'
+
+# 查看所有已配置的保护分支
+git config --get-all branch.cleanup.protected
+```
+
+---
+
+## Best Practices for Embedded Devs
+
+- **优先 `--dry-run`**：养成先预览再执行的习惯。
+- **活用 `--base`**：维护长期 `release` 分支时，用它来清理已合并到该 release 的 `feature` 或 `hotfix` 分支。
+- **谨慎 `--force`**：除非你百分百确定某个未合并分支是无用功，否则不要强制删除。
+- **团队协作**：在清理共享的远程分支前，先在团队频道通知一声。
+- **定期运行**：每月或每季度运行一次，保持仓库清爽。
+
+---
+
+## Why This Version Is Better
+
+- ✅ **更安全**：默认只读预览，且有可配置的保护分支列表。
+- ✅ **更灵活**：支持自定义基准分支，完美适配 `release` / `develop` 工作流。
+- ✅ **更兼容**：避免了在不同系统上行为不一的 `date -d` 等命令。
+- ✅ **更直观**：将复杂的 16 步清单，浓缩成一个带安全选项的、可直接执行的命令。
+- ✅ **风格一致**：与 `/commit` 命令共享相似的参数设计与文档结构。

package/templates/commands/git/commit.md

@@ -0,0 +1,93 @@
+---
+description: 创建格式规范的 Git 提交，使用约定式提交消息
+category: version-control-git
+allowed-tools: Bash, Read, Glob
+---
+
+# Claude 命令：提交
+
+此命令帮助您创建格式规范的提交，使用约定式提交消息格式。
+
+## 使用方法
+
+要创建提交，只需输入：
+
+```
+/commit
+```
+
+或使用选项：
+
+```
+/commit --no-verify
+```
+
+## 命令功能
+
+1. 除非指定 `--no-verify`，否则自动运行预提交检查：
+   - 检测包管理器（npm、pnpm、yarn、bun）并运行相应命令
+   - 运行 lint/format 检查（如果可用）
+   - 运行构建验证（如果存在构建脚本）
+   - 更新文档（如果存在生成脚本）
+2. 使用 `git status` 检查哪些文件已暂存
+3. 如果 0 个文件已暂存，自动使用 `git add` 添加所有修改和新文件
+4. 执行 `git diff` 来理解正在提交的更改
+5. 确保暂存的更改中没有敏感数据（如密码、API 密钥、个人信息、密钥等），如果有，则中止提交并通知用户
+6. 分析差异以确定是否存在多个不同的逻辑更改
+7. 如果检测到多个不同的更改，建议将提交拆分为多个较小的提交
+8. 对于每个提交（如果没有拆分则为单个提交），使用约定式提交格式创建提交消息（确保消息中没有敏感数据），并适当考虑可用的对话历史记录以获取额外上下文，不要立即执行提交，只是生成消息并显示给用户审阅
+9. 将生成的提交消息呈现给用户进行审阅和编辑
+10. 在用户确认后，使用最终确定的消息执行 `git commit` 命令
+
+## 提交最佳实践
+
+- **提交前验证**：确保代码已通过 lint 检查、构建正确且文档已更新
+  - 重要：如果验证失败，请勿继续提交，而是提供需要修复的反馈，以便用户决定如何处理
+  - 重要：不要实际修复问题，只需告知用户需要做什么，并让他们选择是修复还是继续提交
+- **原子提交**：每个提交应包含服务于单一目的的相关更改
+- **拆分大型更改**：如果更改涉及多个关注点，请将它们拆分为单独的提交
+- **约定式提交格式**：使用 `<type>: <description>` 格式，其中 type 可以是：
+  - `feat`: 新功能
+  - `fix`: 错误修复
+  - `docs`: 文档更改
+  - `style`: 代码样式更改（格式化等）
+  - `refactor`: 既不修复错误也不添加功能的代码更改
+  - `perf`: 性能改进
+  - `test`: 添加或修复测试
+  - `chore`: 构建过程、工具等的更改
+- **现在时，祈使语气**：以命令形式编写提交消息（例如，“添加功能”而不是“添加了功能”）
+- **利用上下文**：在相关时使用对话历史记录来通知提交消息，特别是当对话内容可能有助于理解更改意图时，尤其是在由其他 AI 工具审阅完整提交历史记录时，这些工具试图理解更改背后的上下文以理解基本原理、决策制定、意图、解决的问题等
+- **简洁的第一行**：将第一行保持在 72 个字符以内
+
+## Best Practices for Commits
+
+- **Atomic commits**：一次提交只做一件事，便于回溯与审阅。
+- **先分组再提交**：按目录/模块/功能点拆分。
+- **清晰主题**：首行 ≤ 72 字符，祈使语气（如 “add… / fix…”）。
+- **正文含上下文**：说明动机、方案、影响范围、风险与后续工作。
+- **遵循 Conventional Commits**：`<type>(<scope>): <subject>`。
+
+---
+
+## Type 与 Emoji 映射（使用 --emoji 时）
+
+- ✨ `feat`：新增功能
+- 🐛 `fix`：缺陷修复（含 🔥 删除代码/文件、🚑️ 紧急修复、👽️ 适配外部 API 变更、🔒️ 安全修复、🚨 解决告警、💚 修复 CI）
+- 📝 `docs`：文档与注释
+- 🎨 `style`：风格/格式（不改语义）
+- ♻️ `refactor`：重构（不新增功能、不修缺陷）
+- ⚡️ `perf`：性能优化
+- ✅ `test`：新增/修复测试、快照
+- 🔧 `chore`：构建/工具/杂务（合并分支、更新配置、发布标记、依赖 pin、.gitignore 等）
+- 👷 `ci`：CI/CD 配置与脚本
+- ⏪️ `revert`：回滚提交
+- 💥 `feat`：破坏性变更（`BREAKING CHANGE:` 段落中说明）
+
+> 若传入 `--type`/`--scope`，将**覆盖**自动推断。
+> 仅在指定 `--emoji` 标志时才会包含 emoji。
+
+---
+
+## 额外指导
+
+$ARGUMENTS

package/templates/commands/git/rollback.md

@@ -0,0 +1,90 @@
+---
+description: 交互式回滚 Git 分支到历史版本；列分支、列版本、二次确认后执行 reset / revert
+allowed-tools: Read(**), Exec(git fetch, git branch, git tag, git log, git reflog, git checkout, git reset, git revert, git switch), Write()
+argument-hint: [--branch <branch>] [--target <rev>] [--mode reset|revert] [--depth <n>] [--dry-run] [--yes]
+# examples:
+#   - /git-rollback                # 全交互模式，dry‑run
+#   - /git-rollback --branch dev   # 直接选 dev，其他交互
+#   - /git-rollback --branch dev --target v1.2.0 --mode reset --yes
+---
+
+# Claude Command: Git Rollback
+
+**目的**：安全、可视地将指定分支回滚到旧版本。
+默认处于 **只读预览 (`--dry-run`)**；真正执行需加 `--yes` 或在交互中确认。
+
+---
+
+## Usage
+
+```bash
+# 纯交互：列出分支 → 选分支 → 列最近 20 个版本 → 选目标 → 选择 reset 或 revert → 二次确认
+/git-rollback
+
+# 指定分支，其他交互
+/git-rollback --branch feature/calculator
+
+# 指定分支与目标 commit，并用 hard‑reset 一键执行（危险）
+/git-rollback --branch main --target 1a2b3c4d --mode reset --yes
+
+# 只想生成 revert 提交（非破坏式回滚），预览即可
+/git-rollback --branch release/v2.1 --target v2.0.5 --mode revert --dry-run
+```
+
+### Options
+
+| 选项                   | 说明                                                                               |
+| ---------------------- | ---------------------------------------------------------------------------------- |
+| `--branch <branch>`    | 要回滚的分支；缺省时交互选择。                                                     |
+| `--target <rev>`       | 目标版本（commit Hash、Tag、reflog 引用都行）；缺省时交互选择近 `--depth` 条记录。 |
+| `--mode reset\|revert` | `reset`：硬回滚历史；`revert`：生成反向提交保持历史完整。默认询问。                |
+| `--depth <n>`          | 在交互模式下列出最近 n 个版本（默认 20）。                                         |
+| `--dry-run`            | **默认开启**，只预览即将执行的命令。                                               |
+| `--yes`                | 跳过所有确认直接执行，适合 CI/CD 脚本。                                            |
+
+---
+
+## 交互流程
+
+1. **同步远端** → `git fetch --all --prune`
+2. **列分支** → `git branch -a`（本地＋远端，过滤受保护分支）
+3. **选分支** → 用户输入或传参
+4. **列版本** → `git log --oneline -n <depth>` + `git tag --merged` + `git reflog -n <depth>`
+5. **选目标** → 用户输入 commit hash / tag
+6. **选模式** → `reset` 或 `revert`
+7. **最终确认** （除非 `--yes`）
+8. **执行回滚**
+   - `reset`：`git switch <branch> && git reset --hard <target>`
+   - `revert`：`git switch <branch> && git revert --no-edit <target>..HEAD`
+9. **推送建议** → 提示是否 `git push --force-with-lease`（reset）或普通 `git push`（revert）
+
+---
+
+## 安全护栏
+
+- **备份**：执行前自动在 reflog 中记录当前 HEAD，可用 `git switch -c backup/<timestamp>` 恢复。
+- **保护分支**：如检测到 `main` / `master` / `production` 等受保护分支且开启 `reset` 模式，将要求额外确认。
+- **--dry-run 默认开启**：防止误操作。
+- **--force 禁止**：不提供 `--force`；如需强推，请手动输入 `git push --force-with-lease`。
+
+---
+
+## 适用场景示例
+
+| 场景                                            | 调用示例                                                         |
+| ----------------------------------------------- | ---------------------------------------------------------------- |
+| 热修补丁上线后发现 bug，需要回到 Tag `v1.2.0`   | `/git-rollback --branch release/v1 --target v1.2.0 --mode reset` |
+| 运维同事误推了 debug 日志提交，需要生成反向提交 | `/git-rollback --branch main --target 3f2e7c9 --mode revert`     |
+| 调研历史 bug，引导新人浏览分支历史              | `/git-rollback` （全交互，dry‑run）                              |
+
+---
+
+## 注意
+
+1. **reset vs revert**
+   - **reset** 会改变历史，需要强推并可能影响其他协作者，谨慎使用。
+   - **revert** 更安全，生成新提交保留历史，但会增加一次记录。
+2. **嵌入式仓库** 常有大体积二进制文件；回滚前请确保 LFS/子模块状态一致。
+3. 若仓库启用了 CI 强制校验，回滚后可能自动触发流水线；确认管控策略以免误部署旧版本。
+
+---

package/templates/commands/git/worktree.md

@@ -0,0 +1,276 @@
+---
+description: 管理 Git worktree，在项目平级的 ../.zcf/项目名/ 目录下创建，支持智能默认、IDE 集成和内容迁移
+allowed-tools: Read(**), Exec(git worktree add, git worktree list, git worktree remove, git worktree prune, git branch, git checkout, git rev-parse, git stash, git cp, detect-ide, open-ide, which, command, basename, dirname)
+argument-hint: <add|list|remove|prune|migrate> [path] [-b <branch>] [-o|--open] [--track] [--guess-remote] [--detach] [--checkout] [--lock] [--migrate-from <source-path>] [--migrate-stash]
+# examples:
+#   - /git-worktree add feature-ui                     # 从 main/master 创建新分支 'feature-ui'
+#   - /git-worktree add feature-ui -o                  # 创建 worktree 并直接用 IDE 打开
+#   - /git-worktree add hotfix -b fix/login -o         # 创建新分支 'fix/login'，路径为 'hotfix'
+#   - /git-worktree migrate feature-ui --from main     # 将主分支未提交内容迁移到 feature-ui
+#   - /git-worktree migrate feature-ui --stash         # 将当前 stash 迁移到 feature-ui
+---
+
+# Claude Command: Git Worktree
+
+管理 Git worktree，支持智能默认、IDE 集成和内容迁移，使用结构化的 `../.zcf/项目名/` 路径。
+
+直接执行命令并提供简洁结果。
+
+---
+
+## Usage
+
+```bash
+# 基本操作
+/git-worktree add <path>                           # 从 main/master 创建名为 <path> 的新分支
+/git-worktree add <path> -b <branch>               # 创建指定名称的新分支
+/git-worktree add <path> -o                        # 创建并直接用 IDE 打开
+/git-worktree list                                 # 显示所有 worktree 状态
+/git-worktree remove <path>                        # 删除指定的 worktree
+/git-worktree prune                                # 清理无效 worktree 记录
+
+# 内容迁移
+/git-worktree migrate <target> --from <source>     # 迁移未提交内容
+/git-worktree migrate <target> --stash             # 迁移 stash 内容
+```
+
+### Options
+
+| 选项               | 说明                                         |
+| ------------------ | -------------------------------------------- |
+| `add [<path>]`     | 在 `../.zcf/项目名/<path>` 添加新的 worktree |
+| `migrate <target>` | 迁移内容到指定 worktree                      |
+| `list`             | 列出所有 worktree 及其状态                   |
+| `remove <path>`    | 删除指定路径的 worktree                      |
+| `prune`            | 清理无效的 worktree 引用                     |
+| `-b <branch>`      | 创建新分支并检出到 worktree                  |
+| `-o, --open`       | 创建成功后直接用 IDE 打开（跳过询问）        |
+| `--from <source>`  | 指定迁移源路径（migrate 专用）               |
+| `--stash`          | 迁移当前 stash 内容（migrate 专用）          |
+| `--track`          | 设置新分支跟踪对应的远程分支                 |
+| `--guess-remote`   | 自动猜测远程分支进行跟踪                     |
+| `--detach`         | 创建分离 HEAD 的 worktree                    |
+| `--checkout`       | 创建后立即检出（默认行为）                   |
+| `--lock`           | 创建后锁定 worktree                          |
+
+---
+
+## What This Command Does
+
+1. **环境检查**
+   - 通过 `git rev-parse --is-inside-work-tree` 验证 Git 仓库
+   - 检测是否在主仓库或现有 worktree 中，进行智能路径计算
+
+2. **智能路径管理**
+   - 使用 worktree 检测自动从主仓库路径计算项目名
+   - 在结构化的 `../.zcf/项目名/<path>` 目录创建 worktree
+   - 正确处理主仓库和 worktree 执行上下文
+
+```bash
+# worktree 检测的核心路径计算逻辑
+get_main_repo_path() {
+  local git_common_dir=$(git rev-parse --git-common-dir 2>/dev/null)
+  local current_toplevel=$(git rev-parse --show-toplevel 2>/dev/null)
+
+  # 检测是否在 worktree 中
+  if [[ "$git_common_dir" != "$current_toplevel/.git" ]]; then
+    # 在 worktree 中，从 git-common-dir 推导主仓库路径
+    dirname "$git_common_dir"
+  else
+    # 在主仓库中
+    echo "$current_toplevel"
+  fi
+}
+
+MAIN_REPO_PATH=$(get_main_repo_path)
+PROJECT_NAME=$(basename "$MAIN_REPO_PATH")
+WORKTREE_BASE="$MAIN_REPO_PATH/../.zcf/$PROJECT_NAME"
+
+# 始终使用绝对路径防止嵌套问题
+ABSOLUTE_WORKTREE_PATH="$WORKTREE_BASE/<path>"
+```
+
+**关键修复**: 在现有 worktree 内创建新 worktree 时，始终使用绝对路径以防止出现类似 `../.zcf/project/.zcf/project/path` 的路径嵌套问题。
+
+3. **Worktree 操作**
+   - **add**: 使用智能分支/路径默认创建新 worktree
+   - **list**: 显示所有 worktree 的分支和状态
+   - **remove**: 安全删除 worktree 并清理引用
+   - **prune**: 清理孤立的 worktree 记录
+
+4. **智能默认**
+   - **分支创建**: 未指定 `-b` 时，使用路径名创建新分支
+   - **基础分支**: 新分支从 main/master 分支创建
+   - **路径解析**: 未指定路径时使用分支名作为路径
+   - **IDE 集成**: 自动检测并提示 IDE 打开
+
+5. **内容迁移**
+   - 在 worktree 之间迁移未提交改动
+   - 将 stash 内容应用到目标 worktree
+   - 安全检查防止冲突
+
+6. **安全特性**
+   - **路径冲突防护**: 创建前检查目录是否已存在
+   - **分支检出验证**: 确保分支未被其他地方使用
+   - **绝对路径强制**: 防止在 worktree 内创建嵌套的 `.zcf` 目录
+   - **删除时自动清理**: 同时清理目录和 git 引用
+   - **清晰的状态报告**: 显示 worktree 位置和分支状态
+
+7. **环境文件处理**
+   - **自动检测**: 扫描 `.gitignore` 文件中的环境变量文件模式
+   - **智能复制**: 复制 `.gitignore` 中列出的 `.env` 和 `.env.*` 文件
+   - **排除逻辑**: 跳过 `.env.example` 等模板文件
+   - **权限保护**: 保持原始文件权限和时间戳
+   - **用户反馈**: 提供已复制环境文件的清晰状态信息
+
+```bash
+# 环境文件复制实现
+copy_environment_files() {
+    local main_repo="$MAIN_REPO_PATH"
+    local target_worktree="$ABSOLUTE_WORKTREE_PATH"
+    local gitignore_file="$main_repo/.gitignore"
+    
+    # 检查 .gitignore 是否存在
+    if [[ ! -f "$gitignore_file" ]]; then
+        return 0
+    fi
+    
+    local copied_count=0
+    
+    # 检测 .env 文件
+    if [[ -f "$main_repo/.env" ]] && grep -q "^\.env$" "$gitignore_file"; then
+        cp "$main_repo/.env" "$target_worktree/.env"
+        echo "✅ 已复制 .env"
+        ((copied_count++))
+    fi
+    
+    # 检测 .env.* 模式文件（排除 .env.example）
+    for env_file in "$main_repo"/.env.*; do
+        if [[ -f "$env_file" ]] && [[ "$(basename "$env_file")" != ".env.example" ]]; then
+            local filename=$(basename "$env_file")
+            if grep -q "^\.env\.\*$" "$gitignore_file"; then
+                cp "$env_file" "$target_worktree/$filename"
+                echo "✅ 已复制 $filename"
+                ((copied_count++))
+            fi
+        fi
+    done
+    
+    if [[ $copied_count -gt 0 ]]; then
+        echo "📋 已从 .gitignore 复制 $copied_count 个环境文件"
+    fi
+}
+```
+
+---
+
+## Enhanced Features
+
+### IDE 集成
+
+- **自动检测**: VS Code → Cursor → WebStorm → Sublime Text → Vim
+- **智能提示**: 创建 worktree 后询问是否在 IDE 中打开
+- **直接打开**: 使用 `-o` 标志跳过提示直接打开
+- **自定义配置**: 通过 git config 配置
+
+### 内容迁移系统
+
+```bash
+# 迁移未提交改动
+/git-worktree migrate feature-ui --from main
+/git-worktree migrate hotfix --from ../other-worktree
+
+# 迁移 stash 内容
+/git-worktree migrate feature-ui --stash
+```
+
+**迁移流程**:
+
+1. 验证源有未提交内容
+2. 确保目标 worktree 干净
+3. 显示即将迁移的改动
+4. 使用 git 命令安全迁移
+5. 确认结果并建议后续步骤
+
+---
+
+## Examples
+
+```bash
+# 基本用法
+/git-worktree add feature-ui                       # 从 main/master 创建新分支 'feature-ui'
+/git-worktree add feature-ui -b my-feature         # 创建新分支 'my-feature'，路径为 'feature-ui'
+/git-worktree add feature-ui -o                    # 创建并直接用 IDE 打开
+
+# 内容迁移场景
+/git-worktree add feature-ui -b feature/new-ui     # 创建新功能 worktree
+/git-worktree migrate feature-ui --from main       # 迁移未提交改动
+/git-worktree migrate hotfix --stash               # 迁移 stash 内容
+
+# 管理操作
+/git-worktree list                                 # 查看所有 worktree
+/git-worktree remove feature-ui                    # 删除不需要的 worktree
+/git-worktree prune                                # 清理无效引用
+```
+
+**示例输出**:
+
+```
+✅ Worktree created at ../.zcf/项目名/feature-ui
+✅ 已复制 .env
+✅ 已复制 .env.local
+📋 已从 .gitignore 复制 2 个环境文件
+🖥️ 是否在 IDE 中打开 ../.zcf/项目名/feature-ui？[y/n]: y
+🚀 正在用 VS Code 打开 ../.zcf/项目名/feature-ui...
+```
+
+---
+
+## Directory Structure
+
+```
+parent-directory/
+├── your-project/            # 主项目
+│   ├── .git/
+│   └── src/
+└── .zcf/                    # worktree 管理
+    └── your-project/        # 项目 worktree
+        ├── feature-ui/      # 功能分支
+        ├── hotfix/          # 修复分支
+        └── debug/           # 调试 worktree
+```
+
+---
+
+## Configuration
+
+### IDE 配置
+
+- 支持 VS Code、Cursor、WebStorm、Sublime Text、Vim
+- 通过 git config 配置自定义 IDE
+- 基于优先级的自动检测选择
+
+### 自定义 IDE 设置
+
+```bash
+# 配置自定义 IDE
+git config worktree.ide.custom.sublime "subl %s"
+git config worktree.ide.preferred "sublime"
+
+# 控制自动检测
+git config worktree.ide.autodetect true  # 默认
+```
+
+---
+
+## Notes
+
+- **性能**: worktree 共享 `.git` 目录，节省磁盘空间
+- **安全**: 路径冲突防护和分支检出验证
+- **迁移**: 仅限未提交改动；已提交内容需使用 `git cherry-pick`
+- **IDE 要求**: 命令行工具必须在 PATH 中
+- **跨平台**: 支持 Windows、macOS、Linux
+- **环境文件**: 自动复制 `.gitignore` 中列出的环境文件到新 worktree
+- **文件排除**: 模板文件如 `.env.example` 仅保留在主仓库中
+
+---

package/templates/hooks/claude-code-hooks.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ \"$OS\" = \"Windows_NT\" ]; then powershell -File \"$env:USERPROFILE/.claude/hooks/scripts/PreToolUse/powershell/command-logger.ps1\"; else ~/.claude/hooks/scripts/PreToolUse/bash/command-logger.sh; fi"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ \"$OS\" = \"Windows_NT\" ]; then powershell -File \"$env:USERPROFILE/.claude/hooks/scripts/PreToolUse/powershell/file-protection.ps1\"; else ~/.claude/hooks/scripts/PreToolUse/bash/file-protection.sh; fi"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ \"$OS\" = \"Windows_NT\" ]; then powershell -File \"$env:USERPROFILE/.claude/hooks/scripts/PostToolUse/powershell/code-formatter.ps1\"; else ~/.claude/hooks/scripts/PostToolUse/bash/code-formatter.sh; fi"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ \"$OS\" = \"Windows_NT\" ]; then powershell -File \"$env:USERPROFILE/.claude/hooks/scripts/UserPromptSubmit/powershell/input-notifier.ps1\"; else ~/.claude/hooks/scripts/UserPromptSubmit/bash/input-notifier.sh; fi"
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ \"$OS\" = \"Windows_NT\" ]; then powershell -File \"$env:USERPROFILE/.claude/hooks/scripts/Notification/powershell/desktop-notifier.ps1\"; else ~/.claude/hooks/scripts/Notification/bash/desktop-notifier.sh; fi"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ \"$OS\" = \"Windows_NT\" ]; then powershell -File \"$env:USERPROFILE/.claude/hooks/scripts/Stop/powershell/session-summary.ps1\"; else ~/.claude/hooks/scripts/Stop/bash/session-summary.sh; fi"
+          }
+        ]
+      }
+    ]
+  }
+}