agent-Specialization/AGENTS.md

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 应提醒用户执行：

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 安装与认证（首次使用）

# 安装
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 并在结果中说明依据。