JOJO
bd2de76368
- Fix 6.4: use git branch -D (squash merge needs force delete) - Expand 6.6: add review-comments, mergeable check, branch protection API - Add 6.7: real-world troubleshooting table from PR #1 experience
255 lines
11 KiB
Markdown
255 lines
11 KiB
Markdown
# Repository Guidelines (Code-Verified)
|
||
|
||
> Last verified against current codebase: 2026-04-10
|
||
> Scope: `/Users/jojo/Desktop/agents/正在修复中/agents`
|
||
|
||
这份文档基于当前仓库实际代码重写。若与未来代码冲突，以代码为准并及时更新本文档。
|
||
|
||
## 1) 当前项目结构（按代码现状）
|
||
|
||
- **后端入口**
|
||
- `main.py`: 统一启动入口（当前默认走 Web 模式 + thinking_mode=True）
|
||
- `server/app.py`: 推荐的 Web 服务入口（封装并转发到 `server/app_legacy.py`）
|
||
- `web_server.py`: 兼容入口，已标记 deprecated，但仍可启动
|
||
- **后端核心目录**
|
||
- `server/`: Flask 业务主线（chat/task 以 REST 任务轮询为主，Socket.IO 主要用于兼容与实时辅助通道）
|
||
- `core/`: 终端与工具编排（`main_terminal.py`、`web_terminal.py`、`main_terminal_parts/*`）
|
||
- `modules/`: 可复用能力模块（terminal/file/memory/sub_agent/upload_security/user 等）
|
||
- `config/`: 配置拆分（`api.py`, `limits.py`, `terminal.py`, `paths.py` ...），由 `config/__init__.py` 聚合并加载 `.env`
|
||
- `utils/`: API client、日志、上下文与对话工具等公共函数
|
||
- **前端目录**
|
||
- `static/src/`: Vue 3 + TS 前端
|
||
- 监控动画相关核心文件：
|
||
- `static/src/components/chat/monitor/MonitorDirector.ts`
|
||
- `static/src/stores/monitor.ts`
|
||
- `static/src/components/chat/monitor/*`
|
||
- **其他子项目/资源**
|
||
- `android-webview-app/`: Android WebView 客户端工程
|
||
- `easyagent/`: 独立前端子目录（与根目录前端并存）
|
||
|
||
## 2) 当前可用启动/构建命令（已按代码核对）
|
||
|
||
### Python / 服务端
|
||
- 安装依赖：`pip install -r requirements.txt`
|
||
- 推荐启动 Web：`python -m server.app`
|
||
- 可选参数：`python -m server.app --path ./project --port 8091 --debug --thinking-mode`
|
||
- 兼容启动方式：`python web_server.py`
|
||
- 统一入口：`python main.py`（当前实现会默认进入 Web 启动流程）
|
||
|
||
### Frontend（根目录）
|
||
- 安装依赖：`npm install`
|
||
- 构建：`npm run build`
|
||
- 开发监听（当前脚本是 build watch）：`npm run dev`
|
||
- Lint：`npm run lint`
|
||
|
||
## 3) 测试现状（不要再写过时命令）
|
||
|
||
- 当前仓库内可见自动化冒烟：`test/test_server_refactor_smoke.py`（`unittest`）
|
||
- 运行方式：`python -m unittest test.test_server_refactor_smoke`
|
||
- `test_system_message.py` 依赖外部 `MOONSHOT_API_KEY` 与网络，不属于离线稳定 CI 用例。
|
||
- 当前仓库未发现 `pytest.ini`/`pyproject.toml`/`tox.ini`；不要默认要求 `pytest` 作为唯一入口。
|
||
|
||
## 4) 代码修改约定（实用版）
|
||
|
||
- **最小改动原则**：只改与需求直接相关文件，避免顺手重构。
|
||
- **后端改动优先级**：先改 `modules/`、`server/` 内对应模块，最后才动入口。
|
||
- **前端改动优先级**：按 `static/src` 现有分层改（`app/`、`stores/`、`components/`、`composables/`）。
|
||
- 涉及 monitor 动画/事件联动时，至少同步检查：
|
||
- `MonitorDirector.ts`（动画与场景执行）
|
||
- `stores/monitor.ts`（事件队列与状态机）
|
||
|
||
## 5) 风格与质量
|
||
|
||
- Python：4 空格、`snake_case` 函数、`PascalCase` 类，新增公共函数尽量补 type hints。
|
||
- Vue/TS：保持现有代码风格，不做无关风格清洗。
|
||
- 日志：优先复用现有 logger/日志路径，不引入大量临时 `print`。
|
||
- 提交前至少做与改动相关的最小验证（命令输出或手工步骤要可复现）。
|
||
|
||
## 6) Git 工作流（开发 + Review）
|
||
|
||
### 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/<分支名> # 强制删除（Squash Merge 不产生 merge commit，Git 会提示 not fully merged）
|
||
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 --comments <编号>` |
|
||
| 查看 PR Review 评论 | `tea pulls review-comments <编号>` |
|
||
| 创建 PR | `tea pulls create --base main --head <分支> --title "..."` |
|
||
| 查看 PR diff | `tea pulls checkout <编号>` 后 `git diff main...<分支>` |
|
||
| 查看 PR mergeable 状态 | `tea api "/repos/<owner>/<repo>/pulls/<编号>"` |
|
||
| Approve | `tea pulls approve <编号>` |
|
||
| Request Changes | `tea pulls reject <编号>` |
|
||
| 添加评论 | `tea comment <编号>` |
|
||
| Squash 合并 | `tea pulls merge <编号> --style squash` |
|
||
| 关闭 PR | `tea pulls close <编号>` |
|
||
| 查看分支保护 | `tea branches list` |
|
||
| 保护分支 | `tea branches protect main` |
|
||
| 取消保护 | `tea branches unprotect main` |
|
||
| 修改保护规则 | `tea api -X PATCH "/repos/<owner>/<repo>/branch_protections/main" --data '{"required_approvals":0}'` |
|
||
| 删除远程分支 | `git push origin --delete <分支名>` |
|
||
| 强制删除本地分支 | `git branch -D <分支名>` |
|
||
|
||
### 6.7 故障排查（实战验证）
|
||
|
||
| 症状 | 原因 | 解决 |
|
||
|------|------|------|
|
||
| `tea pulls merge` 报 `mergeable: False` | Gitea 缓存了旧的保护规则评估结果 | 先用 `tea api "/repos/<owner>/<repo>/pulls/<编号>"` 确认 `mergeable` 字段；若规则已修改但 PR 仍不可合并，可 `tea branches unprotect main` → `git push origin main` → `tea branches protect main` 绕过 |
|
||
| `git branch -d` 提示 `not fully merged` | Squash Merge 不会在本地产生 merge commit，Git 检测不到合并关系 | 用 `git branch -D` 强制删除 |
|
||
| PR 需要 approval 才能合并但你是唯一开发者 | Gitea 默认 `required_approvals=1` 且作者不能自 approve | `tea api -X PATCH "/repos/<owner>/<repo>/branch_protections/main" --data '{"required_approvals":0}'` |
|
||
| `git push origin main` 被拒绝 | 分支保护 `enable_push: false` 生效 | 正常——不应直接 push main。合并必须通过 `tea pulls merge` 或临时 unprotect（仅紧急情况） |
|
||
| `tea whoami` 报 `no available login` | `tea` 和 `git` 认证独立，git SSH 通了不代表 tea API 认证也通了 | 参照 6.5 节用 Token 完成 `tea login add` |
|
||
|
||
## 7) 安全与仓库卫生
|
||
|
||
- 严禁提交真实密钥（`.env`、token、cookie、用户隐私）。
|
||
- `logs/`, `data/`, `users/`, `project/` 为运行态目录（见 `.gitignore`），分享前需脱敏。
|
||
- 不要把本地构建产物（如 `static/dist/`、`node_modules/`）纳入提交。
|
||
|
||
## 8) Android App 发布联动要求（重要）
|
||
|
||
当修改前端并需要发布 Android WebView App 时，必须同步执行以下步骤（依据 `doc/android_app_release_and_update.md`）：
|
||
|
||
1. 同时更新版本信息
|
||
- `android-webview-app/app/build.gradle.kts`：递增 `versionCode`，更新 `versionName`
|
||
2. 同时更新更新说明
|
||
- `android-webview-app/APP_CHANGELOG.md`：在顶部新增当前版本说明
|
||
3. 完成修改后提醒用户运行上传脚本
|
||
- 在发布流程中运行：`bash /Users/jojo/Desktop/agents/正在修复中/agents/upload_android_apk.sh`
|
||
|
||
> 禁止只改前端代码而不更新版本号/更新说明，否则会导致客户端更新提示与分发信息不一致。
|
||
|
||
## 9) 给 Agent 的硬性要求
|
||
|
||
- 先读当前代码再执行，不依赖历史文档记忆。
|
||
- 输出结果必须带：
|
||
1. 修改文件列表
|
||
2. 核心变更点
|
||
3. 验证结果（已执行命令/未执行原因）
|
||
- 如果发现本文档过时，直接更新 `AGENTS.md` 并在结果中说明依据。
|