# 协作说明（面向 AI 与贡献者）

本文件描述 `dota2-assistant` 的职责边界、代码布局与修改时的注意点，便于在仓库内高效、安全地迭代。

## 项目是什么

Windows 上的 Dota 2 助手：**透明 egui Overlay** + **本地 axum GSI HTTP 服务**（默认 `:3000`），从官方 Game State Integration 接收状态，结合 **OpenDota API** 与 **SQLite 缓存** 做 BP 与出装推荐。详见 [README.md](README.md)。

## 目录与模块

| 路径 | 职责 |
|------|------|
| `src/main.rs` | 入口：日志、`AppState`、后台 tokio 线程（GSI + 推荐）、主线程 `egui_overlay::start` |
| `src/gsi/` | GSI HTTP 路由与解析 |
| `src/state/` | 共享应用状态 |
| `src/api/` | OpenDota 客户端与模型 |
| `src/cache/` | SQLite 缓存 |
| `src/recommend/` | 推荐引擎与出装构建 |
| `src/overlay/` | Overlay UI（含 `views/` 下各界面） |
| `src/constants.rs` | 常量 |
| `config/` | GSI 配置模板 |
| `install_gsi.ps1` | Windows 下安装 GSI  cfg 的脚本 |

## 技术约束（修改前必读）

- **egui 版本**：`Cargo.toml` 中 `egui` 须与 `egui_overlay` 所依赖的 egui 主版本一致（当前注释已说明约束）。
- **线程模型**：Overlay 在主线程阻塞运行；异步 IO（GSI、HTTP 客户端）在独立 tokio runtime 线程。跨线程共享使用 `Arc<Mutex<AppState>>` 等现有模式，避免在 egui 线程上长跑 `block_on`。
- **合规与安全**：仅 GSI + 透明窗口；不要引入读进程内存、注入或违反 VAC 期望的行为。若文档或代码暗示「可作弊」类能力，应保持与 README 一致的限制说明。
- **GSI 数据范围**：仅能使用玩家可见的官方 GSI 字段；不要假设能拿到对方未展示的信息。

## 开发命令

```powershell
cargo build
cargo build --release
cargo clippy
cargo test   # 若有测试
```

本地产物在 `target/`，勿提交；若根目录存在 `.gitignore` 已忽略则保持现状。

## 修改原则

- 只改任务所需文件与逻辑，避免无关重构、大范围格式化或「顺手」改 README/新增文档（除非任务明确要求）。
- 命名、错误处理（`anyhow`、`tracing`）、模块划分与现有代码保持一致。
- 涉及 GSI 的改动时，核对 Dota 侧配置与 `README.md`/`install_gsi.ps1` 是否仍正确；端口等默认值与 `AppState`/设置路径对齐。

## 外部依赖

- 英雄/对局等数据以 **OpenDota** 为准；网络不可用时依赖本地缓存行为应可接受（可降级、日志清晰）。
- 运行与调试真实 GSI 需要本机安装 Dota 2 并配置 `gamestate_integration`，不属于纯单元测试必选项。