dota2-assistant/AGENTS.md

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

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

项目是什么

Windows 上的 Dota 2 助手：透明 egui Overlay + 本地 axum GSI HTTP 服务（默认 :3000），从官方 Game State Integration 接收状态，结合 OpenDota API 与 SQLite 缓存 做 BP 与出装推荐。详见 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 字段；不要假设能拿到对方未展示的信息。

开发命令

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，不属于纯单元测试必选项。