Update CodeBuddy commands and rules for better workflow. (#3213)

Author: domchen

.codebuddy/commands/cr.md

@@ -61,10 +61,17 @@ done
 
 ### 本地模式
 
+获取当前分支相对 main 的完整变更：
+
 ```bash
+# 拉取最新的 main 分支
+git fetch origin main
+
+# 当前分支相对 origin/main 的完整变更（已提交 + 暂存区 + 工作区的最终结果）
+git diff origin/main
+
+# 查看文件状态（用于识别未跟踪文件）
 git status
-git diff
-git diff --cached
 ```
 
 对于未跟踪的新增文件（`git status` 中以 `??` 开头的文件），使用 Read 工具读取文件内容进行审查。
@@ -73,9 +80,8 @@ git diff --cached
 
 先获取 PR 信息（一次调用获取所有需要的字段）：
 ```bash
-PR_INFO=$(gh pr view {pr_number} --json headRefName,baseRefName,author)
+PR_INFO=$(gh pr view {pr_number} --json headRefName,author)
 PR_BRANCH=$(echo "$PR_INFO" | jq -r '.headRefName')
-BASE_BRANCH=$(echo "$PR_INFO" | jq -r '.baseRefName')
 PR_AUTHOR=$(echo "$PR_INFO" | jq -r '.author.login')
 ```
 
@@ -94,9 +100,14 @@ git worktree add /tmp/pr-review-{pr_number} pr-{pr_number}
 cd /tmp/pr-review-{pr_number}
 ```
 
-获取变更内容和评论：
+获取变更内容和评论（两种情况通用）：
 ```bash
-git diff origin/${BASE_BRANCH}...HEAD
+# 拉取最新的 main 分支
+git fetch origin main
+
+# 当前分支相对 origin/main 的完整变更
+git diff origin/main
+
 gh pr view {pr_number} --comments
 ```
 

.codebuddy/commands/pr.md

@@ -10,13 +10,16 @@ description: 提交 PR - 自动识别新建或追加提交
 
 ## 前置检查
 
-### 检查是否已有开启的 PR
-
 ```bash
-CURRENT_BRANCH=$(git branch --show-current)
-gh pr list --head "$CURRENT_BRANCH" --state open --json number,url
+git fetch origin main && \
+CURRENT_BRANCH=$(git branch --show-current) && \
+echo "CURRENT_BRANCH:$CURRENT_BRANCH" && \
+gh pr list --head "$CURRENT_BRANCH" --state open --json number,url && \
+gh api user --jq '.login'
 ```
 
+记录：当前分支、是否有开启的 PR、GitHub username（供新建模式使用）。
+
 根据结果选择模式：
 
 | 当前分支 | 已有开启的 PR | 模式 |
@@ -30,82 +33,123 @@ gh pr list --head "$CURRENT_BRANCH" --state open --json number,url
 ## 第一步：确定提交范围
 
 运行 `git status --porcelain`：
-- 若无输出：提示无变更，终止流程
-- 若暂存区有内容，且工作区也有内容（含未跟踪文件）：询问用户选择局部提交或全部提交
-- 否则：全部提交（执行 `git add .`）
+- 若有输出：
+  - 若暂存区有内容，且工作区也有内容（含未跟踪文件）：询问用户选择局部提交或全部提交
+  - 否则：全部提交
+- 若无输出：记录为**无本地变更**，跳过第二、三步
 
 **判断方法**：第一列非空格为暂存区有内容；第二列非空格或以 `??` 开头为工作区有内容。
 
-若为**局部提交**，记录**暂存区文件列表**供后续步骤使用。
+若为**局部提交**，使用 `git diff --cached --name-only` 记录**暂存区文件列表**供后续步骤使用。
 
 ---
 
 ## 第二步：格式化代码
 
+若 `./codeformat.sh` 存在，执行：
+
 ```bash
 ./codeformat.sh
 ```
 
 忽略输出的报错信息，只要运行就会完成格式化。
 
-格式化后根据第一步确定的提交范围处理：
+格式化后根据第一步结果处理暂存区：
 
-| 提交范围 | 处理方式 |
-|----------|----------|
-| 全部提交 | 执行 `git add .` 将所有变更（包括格式化修改）加入暂存区 |
-| 局部提交 | 检查第一步记录的暂存区文件是否被格式化修改，如有则重新加入暂存区（`git add {文件}`），忽略其他文件的格式化修改 |
+| 第一步结果 | 处理方式 |
+|------------|----------|
+| 全部提交 | 执行 `git add .` 将所有变更加入暂存区 |
+| 局部提交 | 仅将第一步记录的文件重新加入暂存区（`git add {文件}`） |
 
 ---
 
-## 第三步：生成提交信息
-
-查看将要提交的内容：
+## 第三步：生成 Commit 信息
 
 ```bash
 git diff --cached
 ```
 
-根据变更内容生成**Commit 信息**（英语，120 字符内，以句号结尾，侧重描述用户可感知的变化）。
+根据暂存区变更生成 **Commit 信息**：英语，120 字符内，以句号结尾，侧重描述用户可感知的变化。
 
 ---
 
 ## 第四步：提交并推送
 
-**直接执行，无需确认。**
-
 ### 追加模式
 
+检查未推送的 commit：
+
 ```bash
-git commit -m "{Commit 信息}"
+git log origin/{当前分支}..HEAD --oneline
+```
+
+| 暂存区 | 未推送 commit | 操作 |
+|--------|---------------|------|
+| 有内容 | - | 提交并推送 |
+| 无内容 | 有 | 仅推送 |
+| 无内容 | 无 | 提示"无新变更需要提交"，流程结束 |
+
+```bash
+# 若暂存区有内容，提交并推送
+git commit -m "{Commit 信息}" && git push
+
+# 若暂存区无内容但有未推送 commit，仅推送
 git push
 ```
 
 输出：
 
 ```
-**Commit**：{Commit 信息}
+**Commit**：{Commit 信息}（若有新提交）
 
 **PR 链接**（已追加提交）：{PR 链接}
 ```
 
 ### 新建模式
 
-生成以下信息：
+#### 1. 分析完整变更
 
-- **分支名称**：`feature/{username}_模块名` 或 `bugfix/{username}_模块名`（`{username}` 为 GitHub 用户 ID 全小写，模块名用下划线连接，最多两个单词）
+分析 PR 包含的所有变更：
+
+```bash
+git log origin/main..HEAD --oneline   # 已有 commit
+git diff --cached                      # 本次暂存区变更（若第三步已获取则复用）
+```
+
+若已有 commit 为空且暂存区无内容，提示无变更，终止流程。
+
+#### 2. 生成 PR 信息
+
+根据上述完整变更（已有 commit + 暂存区变更）生成：
+
+- **分支名称**：`feature/{username}_模块名` 或 `bugfix/{username}_模块名`（`{username}` 为前置检查获取的 GitHub 用户 ID 全小写，模块名用下划线连接，最多两个单词）
+- **PR 标题**：英语，120 字符内，以句号结尾，侧重描述用户可感知的变化
 - **PR 描述**：中文，简要说明变更内容和目的
 
+#### 3. 处理分支并提交推送
+
+切换到新分支：
+
+| 当前分支 | 操作 |
+|----------|------|
+| main | `git checkout -b {分支名称}` |
+| 非 main | `git branch -m {分支名称}` |
+
+提交并推送：
+
 ```bash
-git checkout -b {分支名称}
+# 若暂存区有内容，先提交
 git commit -m "{Commit 信息}"
+
+# 推送并创建 PR
 git push -u origin {分支名称}
-gh pr create --title "{Commit 信息}" --body "{PR 描述}"
+gh pr create --title "{PR 标题}" --body "{PR 描述}"
 ```
 
 输出：
 
 ```
-**PR 标题**：{Commit 信息}
+**PR 标题**：{PR 标题}
 
 **PR 描述**：{PR 描述}
 

.codebuddy/commands/switch-main.md

@@ -0,0 +1,137 @@
+---
+description: 管理 Git Worktree - 创建、切换或清理 worktree，自动同步测试缓存
+---
+
+# Git Worktree 管理
+
+管理 git worktree，支持创建、切换和清理操作，切换时自动同步测试缓存目录。
+
+---
+
+## 公共步骤：获取主仓库信息
+
+```bash
+MAIN_REPO=$(git worktree list --porcelain | head -1 | sed 's/worktree //')
+REPO_NAME=$(basename "$MAIN_REPO")
+```
+
+---
+
+## 参数解析
+
+| $ARGUMENTS | 操作 |
+|------------|------|
+| 空 | 列出现有 worktree，询问用户进入或删除 |
+| `{name}` | 进入该 worktree（不存在则创建） |
+
+Worktree 路径命名规范：`{项目名称}-{name}`，与主仓库同级目录。
+
+---
+
+## 无参数模式
+
+```bash
+git worktree list
+```
+
+若只有主仓库，提示用户使用 `/worktree {name}` 创建新的 worktree，**终止流程**。
+
+若有其他 worktree，展示列表并询问用户要执行的操作：
+- 进入某个 worktree（执行「同步缓存并切换」，`WT_PATH` 为用户选择的路径）
+- 删除某个 worktree（执行「删除 worktree」流程）
+
+---
+
+## 进入 worktree
+
+### 1. 计算路径并检查是否存在
+
+```bash
+WT_PATH="$MAIN_REPO/../$REPO_NAME-{name}"
+test -d "$WT_PATH" && echo "exists" || echo "not found"
+```
+
+### 2. 若不存在则创建
+
+```bash
+git fetch origin main
+git worktree add -b {name} "$WT_PATH" origin/main
+```
+
+### 3. 同步缓存并切换
+
+从主仓库拷贝测试缓存（若存在）：
+
+```bash
+if [ -d "$MAIN_REPO/test/baseline/.cache" ]; then
+    mkdir -p "$WT_PATH/test/baseline"
+    cp -r "$MAIN_REPO/test/baseline/.cache" "$WT_PATH/test/baseline/"
+    echo "已同步 test/baseline/.cache"
+fi
+
+if [ -d "$MAIN_REPO/test/out" ]; then
+    mkdir -p "$WT_PATH/test"
+    cp -r "$MAIN_REPO/test/out" "$WT_PATH/test/"
+    echo "已同步 test/out"
+fi
+```
+
+切换到 worktree：
+
+```bash
+cd "$WT_PATH"
+```
+
+输出（新建时）：
+
+```
+**Worktree 已创建**：{WT_PATH}
+**分支**：{name}
+**已同步缓存**：{同步的目录列表}
+```
+
+输出（已存在时）：
+
+```
+**已切换到 worktree**：{WT_PATH}
+**已同步缓存**：{同步的目录列表}
+```
+
+---
+
+## 删除 worktree
+
+### 1. 检查未提交变更
+
+```bash
+git -C "{worktree 路径}" status --porcelain
+```
+
+若有未提交变更，提示用户并询问是否继续删除。用户取消则**终止流程**。
+
+### 2. 切换工作目录（如需要）
+
+若当前工作目录在待删除的 worktree 内，先切换到主仓库：
+
+```bash
+cd "$MAIN_REPO"
+```
+
+### 3. 移除 worktree
+
+```bash
+git worktree remove "{worktree 路径}" --force
+```
+
+输出：
+
+```
+**已删除 worktree**：{worktree 路径}
+```
+
+---
+
+## 重要限制
+
+- **NEVER** 删除主仓库
+- 创建 worktree 时始终基于 `origin/main`

.codebuddy/commands/worktree.md

@@ -6,8 +6,8 @@ alwaysApply: true
 ## 编码规范
 
 - 对话用中文，代码和注释用英语
-- 新需求的编码任务禁止直接编码，先输出关键接口和伪代码，穷尽所有疑问向用户提问，方案确认后才可编码
-- 不生成说明文件，除非明确要求
+- 所有说明文件、方案设计文件统一放在 `.codebuddy/designs/` 目录（已加入 .gitignore，不参与提交）
+- 新需求禁止直接编码，先输出详细方案设计文件，穷尽疑问向用户提问，用户明确确认后再按方案编码
 - 复用项目已有功能，保持变更简洁，避免重复代码
 - 重构时审查关联代码合理性，顺带清理冗余，不考虑向后兼容
 - 版权声明里的年份对新增的文件要使用当前年份（如 `Copyright (C) 2026 Tencent`），已有文件保持原年份不变