From 2799608051ceef9f552ae93b179877e4a61826c9 Mon Sep 17 00:00:00 2001
From: JOJO <1498581755@qq.com>
Date: Mon, 27 Apr 2026 23:31:14 +0800
Subject: [PATCH] docs(agents): add comprehensive git workflow and review spec

---
 AGENTS.md | 148 +++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 141 insertions(+), 7 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 5253f20..66b92a6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -65,14 +65,148 @@
 - 日志：优先复用现有 logger/日志路径，不引入大量临时 `print`。
 - 提交前至少做与改动相关的最小验证（命令输出或手工步骤要可复现）。
 
-## 6) 提交与 PR
+## 6) Git 工作流（开发 + Review）
 
-- 使用 Conventional Commits：`feat:` `fix:` `refactor:` `chore:` ...
-- PR 描述至少包含：
-  - 改了哪些文件
-  - 为什么改
-  - 如何验证
-  - 风险/回滚点
+### 6.1 核心原则
+
+- **永远不直接在 `main` 上提交**。所有改动必须走功能分支。
+- 每个功能分支合入 main 时使用 **Squash Merge**，保持 main 历史干净（一个功能 = 一个 commit）。
+- 使用 **Conventional Commits**：`feat:` `fix:` `refactor:` `chore:` `docs:` `test:` `perf:`。
+- 本仓库托管于 **Gitea**（`git.cyjai.com`），CLI 工具为 **`tea`**。
+
+### 6.2 场景一：当对话目的是「修改源代码」
+
+AI 执行前应确保 `tea` CLI 已安装并认证（详见 6.5 节），运行 `tea whoami` 检查。
+
+AI 必须按以下流程引导用户（每一步都要向用户说明当前在做什么）：
+
+```
+0. 检查工作区状态
+   git status
+   如有未提交的改动（切换分支可能丢失）：
+   - 若无关：提醒用户先 commit 或 discard
+   - 若有关：git stash push -m "WIP: <简短描述>" 暂存
+
+1. 从 main 切出功能分支
+   git checkout main && git pull origin main
+   git checkout -b feature/<简短描述> main
+
+2. 完成修改后，提交
+   git add <修改的文件>
+   git commit -m "feat(scope): 简短描述"
+
+   如有多个逻辑独立的改动，拆成多个 commit
+   如只有一个功能，一个 commit 即可
+
+3. 推送到远程
+   git push origin feature/<分支名>
+
+4. 创建 Pull Request（用 tea CLI，不碰网页）
+   tea pulls create \
+     --base main \
+     --head feature/<分支名> \
+     --title "feat(scope): 简短描述" \
+     --description "## 改动说明
+   - 改了哪些文件
+   - 为什么改
+   - 如何验证
+   - 风险/回滚点"
+
+5. 告知用户 PR 编号，提示用户：
+   "可以开一个新对话让我 review 这个 PR"
+```
+
+**重要约束**：
+- AI 必须先在本地验证修改能正常运行，再建议用户提交。
+- 修改完成后 AI 应主动告知：修改了哪些文件、核心变更点、验证结果。
+- 禁止 AI 在未经用户确认的情况下执行 `git push` 或 `tea pulls merge`。
+
+### 6.3 场景二：当对话目的是「Review 代码」
+
+用户会在对话中说「帮我 review PR #N」或「review 最新提交」。AI 按以下流程操作：
+
+```
+1. 确保本地代码最新
+   git fetch origin
+   git checkout main && git pull origin main
+
+2. 获取待 review 的改动
+   方式 A（PR review）：
+     tea pulls checkout <PR编号>
+   方式 B（本地 review，如用户刚提交未创建 PR）：
+     git diff main...feature/<分支名>
+
+3. 逐文件审查，关注以下维度：
+   ✅ 逻辑正确性：边界条件、错误处理、空值检查
+   ✅ 安全性：SQL 注入、XSS、密钥泄露、权限校验
+   ✅ 性能：不必要的循环、N+1 查询、大对象拷贝
+   ✅ 代码风格：命名规范、函数长度、注释质量
+   ✅ 测试覆盖：是否有对应测试、测试是否通过
+   ✅ 架构一致性：是否符合第 4-5 节的代码约定
+
+4. 输出 Review Report，格式如下：
+   ### 📋 Review Report — PR #N
+   | 文件 | 严重程度 | 问题 | 建议 |
+   |------|---------|------|------|
+   | xxx.py | 🔴 严重 | ... | ... |
+   | yyy.ts | 🟡 建议 | ... | ... |
+   | zzz.py | 🟢 良好 | — | — |
+
+   **总结**：[通过 / 需修改 / 建议重构]
+   如需修改，逐条给出可操作的具体建议。
+
+5. 输出 Review Report 后，**等待用户确认**再操作 PR。
+   用户确认后执行：
+   - 通过：`tea pulls approve <PR编号>`
+   - 需修改：`tea pulls reject <PR编号>` 并在评论中逐条说明
+   - 添加评论：`tea comment <PR编号>`
+   注意：approve/reject 与 merge 一样，都须经用户确认（与 6.2 约束一致）。
+
+6. Review 通过后，指导用户合并：
+   tea pulls merge <PR编号> --style squash
+
+7. Review 完成后清理 `tea pulls checkout` 创建的临时分支：
+   git checkout main
+   git branch -D pr-<PR编号>   # 强制删除（本地临时分支无需保留）
+```
+
+### 6.4 合并后的清理
+
+合并完成后 AI 应提醒用户执行：
+
+```bash
+git checkout main && git pull origin main
+git branch -d feature/<分支名>          # 删除本地分支
+git push origin --delete feature/<分支名>  # 删除远程分支（可选）
+```
+
+### 6.5 `tea` CLI 安装与认证（首次使用）
+
+```bash
+# 安装
+brew install tea
+
+# 认证（在 git.cyjai.com → 设置 → 应用 → 生成令牌）
+tea login add \
+  --name gitea \
+  --url https://git.cyjai.com \
+  --token <你的令牌>
+```
+
+### 6.6 常见命令速查
+
+| 操作 | 命令 |
+|------|------|
+| 列出 PR | `tea pulls list` |
+| 创建 PR | `tea pulls create --base main --head <分支> --title "..."` |
+| 查看 PR diff | `tea pulls checkout <编号>` 后 `git diff main...<分支>` |
+| Approve | `tea pulls approve <编号>` |
+| Request Changes | `tea pulls reject <编号>` |
+| 添加评论 | `tea comment <编号>` |
+| Squash 合并 | `tea pulls merge <编号> --style squash` |
+| 关闭 PR | `tea pulls close <编号>` |
+| 分支保护 | `tea branches protect main` |
+| 列出分支 | `tea branches list` |
 
 ## 7) 安全与仓库卫生