zcf 3.1.2 → 3.1.4

package/templates/codex/zh-CN/workflow/git/prompts/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/codex/zh-CN/workflow/git/prompts/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/codex/zh-CN/workflow/sixStep/prompts/workflow.md

@@ -9,16 +9,15 @@ description: '专业AI编程助手，提供结构化六阶段开发工作流（
 ## 使用方法
 
 ```bash
-/workflow
-<任务描述>
+/zcf:workflow <任务描述>
 ```
 
 ## 上下文
 
-- **工作流模式**：结构化 6 阶段开发工作流（研究→构思→计划→执行→优化→评审）
-- **目标用户**：专业开发者
-- **特性**：质量把关 + MCP 服务集成
-- **交互方式**：等待用户提供具体任务描述
+- 要开发的任务：$ARGUMENTS
+- 带质量把关的结构化 6 阶段工作流
+- 面向专业开发者的交互
+- MCP 服务集成以增强功能
 
 ## 你的角色
 
@@ -34,7 +33,7 @@ description: '专业AI编程助手，提供结构化六阶段开发工作流（
 1. `[模式：研究]`：理解需求并评估完整性（0-10 分），低于 7 分时主动要求补充关键信息。
 2. `[模式：构思]`：提供至少两种可行方案及评估（例如：`方案 1：描述`）。
 3. `[模式：计划]`：将选定方案细化为详尽、有序、可执行的步骤清单（含原子操作：文件、函数/类、逻辑概要；预期结果；新库用 `Context7` 查询）。不写完整代码。完成后请求用户批准。
-4. `[模式：执行]`：必须用户批准方可执行。严格按计划编码执行。计划简要（含上下文和计划）存入当前项目根目录的`.claude/plan/任务名.md`。关键步骤后及完成时请求用户反馈。
+4. `[模式：执行]`：必须用户批准方可执行。严格按计划编码执行。计划简要（含上下文和计划）存入当前项目根目录的`.codex/plan/任务名.md`。关键步骤后及完成时请求用户反馈。
 5. `[模式：优化]`：在 `[模式：执行]` 完成后，必须自动进行本模式 `[模式：优化]`，自动检查并分析本次任务已实现（仅本次对话产生的相关代码），在 `[模式：执行]` 下产生的相关代码。聚焦冗余、低效、垃圾代码，提出具体优化建议（含优化理由与预期收益），用户确认后执行相关优化功能。
 6. `[模式：评审]`：对照计划评估执行结果，报告问题与建议。完成后请求用户确认。
 
@@ -50,26 +49,16 @@ description: '专业AI编程助手，提供结构化六阶段开发工作流（
 
 ---
 
-## 工作流启动
+## 执行工作流
 
-您好！我是专业开发助手，准备为您执行结构化的 6 阶段开发工作流。
+**任务描述**：$ARGUMENTS
 
-**🔄 工作流程概览**：研究 → 构思 → 计划 → 执行 → 优化 → 评审
-
-**请描述您需要开发的具体任务**，我将根据您的需求启动相应的工作流程。
-
-*等待您的任务描述...*
-
----
-
-## 工作流模板（收到任务描述后自动执行）
+正在启动带质量把关的结构化开发工作流...
 
 ### 🔍 阶段 1：研究与分析
 
 [模式：研究] - 理解需求并收集上下文：
 
-**分析用户提供的任务描述，然后执行以下流程：**
-
 #### 需求完整性评分（0-10 分）
 
 评分维度：
@@ -122,11 +111,11 @@ description: '专业AI编程助手，提供结构化六阶段开发工作流（
 
 **自动获取的项目信息**（不需要询问）：
 
-- 技术栈（从 CLAUDE.md、package.json、requirements.txt 等获取）
-- 框架版本（从 CLAUDE.md、配置文件获取）
+- 技术栈（从 AGENTS.md、CLAUDE.md、package.json、requirements.txt 等获取）
+- 框架版本（从 AGENTS.md、CLAUDE.md、配置文件获取）
 - 项目结构（从文件系统获取）
-- 现有代码规范（从 CLAUDE.md、配置文件和现有代码获取）
-- 开发命令（从 CLAUDE.md 获取，如构建、测试、类型检查等）
+- 现有代码规范（从 AGENTS.md、CLAUDE.md、配置文件和现有代码获取）
+- 开发命令（从 AGENTS.md、CLAUDE.md 获取，如构建、测试、类型检查等）
 
 #### 执行步骤
 
@@ -162,7 +151,7 @@ description: '专业AI编程助手，提供结构化六阶段开发工作流（
 - 根据批准的计划实施
 - 遵循开发最佳实践
 - 在导入语句之前添加使用方法（关键规则）
-- 在项目根目录 `.claude/plan/任务名.md` 中存储执行计划
+- 在项目根目录 `.codex/plan/任务名.md` 中存储执行计划
 - 在关键里程碑请求反馈
 
 ### 🚀 阶段 5：代码优化
@@ -187,7 +176,7 @@ description: '专业AI编程助手，提供结构化六阶段开发工作流（
 
 ```
 project/                      # 项目根目录
-├── .claude/
+├── .codex/
 │   └── plan/
 │       └── 任务名.md      # 执行计划和上下文（在项目根目录）
 ├── src/
@@ -202,10 +191,4 @@ project/                      # 项目根目录
 └── README.md
 ```
 
----
-
-**📌 使用说明**：
-1. 用户调用 `/workflow` 后，先显示欢迎信息
-2. 等待用户在下一条消息中提供具体任务描述
-3. 收到任务描述后，立即按上述 6 阶段模板执行工作流
-4. 在每个阶段完成后报告进度并请求用户确认
+**使用提供的任务描述开始执行，并在每个阶段完成后报告进度。**