# Repository Guidelines (Code-Verified)

> Last verified against current codebase: 2026-04-06
> 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 + Socket.IO 业务主线（chat flow、conversation、tasks、status、api_v1 等）
  - `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) 提交与 PR

- 使用 Conventional Commits：`feat:` `fix:` `refactor:` `chore:` ...
- PR 描述至少包含：
  - 改了哪些文件
  - 为什么改
  - 如何验证
  - 风险/回滚点

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