vosonandCursor
a089660ca9
Remove build_library and runtime artifacts, ignore regenerable outputs, and add README/AGENTS/DESIGN/CHANGELOG for the simplified project. Co-authored-by: Cursor <cursoragent@cursor.com>
89 lines
3.8 KiB
Markdown
89 lines
3.8 KiB
Markdown
# 协作说明（面向 AI 与贡献者）
|
||
|
||
本文件描述 **上分帝（Climperor）** 的职责边界、代码布局与修改注意点。
|
||
|
||
## 项目是什么
|
||
|
||
Windows 上的 Dota 2 **天梯选将识别**工具：用 GSI 感知选将阶段，截屏后对顶栏 10 格做 OpenCV 模板匹配，输出双方阵容与选将时间线。
|
||
|
||
- 中文名：上分帝
|
||
- 英文名 / 仓库目录：Climperor / `climperor`
|
||
- 模板来源：**仅** Steam CDN 官方头像（`templates/cdn/`）
|
||
- **已放弃** real 实拍模板库补充；不要再引入 `templates/real/` 或入库流水线
|
||
|
||
## 目录与模块
|
||
|
||
| 路径 | 职责 |
|
||
|------|------|
|
||
| `common.py` | 配置 IO、槽位几何、裁切、NCC 匹配、天梯遮罩、CDN 模板加载 |
|
||
| `recognize.py` | 单帧识别；`recognize_image()` 供会话复用 |
|
||
| `draft_session.py` | 整局选将跟踪、改判、皮肤规避策略 |
|
||
| `gsi_watch.py` / `gsi_setup.py` | GSI 监听与 cfg 安装 |
|
||
| `fetch_cdn_templates.py` | 拉取 CDN 头像 + 生成 `heroes.json` |
|
||
| `autocalibrate.py` / `calibrate.py` | ROI 自动 / 手动标定 |
|
||
| `capture.py` | 屏幕捕获 |
|
||
| `evaluate.py` | 按 `samples/labels.json` 批量评测 |
|
||
| `roles.py` / `grid.py` / `modes.py` | 位置字、禁用网格、模式字 |
|
||
| `config.json` | 相对坐标、阈值、GSI 参数 |
|
||
| `templates/cdn/` | 全英雄 CDN 模板（需提交或由脚本生成） |
|
||
| `templates/roles/` / `templates/modes/` | 位置 / 模式辅助模板 |
|
||
|
||
运行时产物（**勿提交**，见 `.gitignore`）：
|
||
|
||
- `samples/raw/` — 截图
|
||
- `preview/` — 标定 / sheet 预览
|
||
- `results/` — 每局 JSON
|
||
- `failures/` — `--truth` 调试用错识裁切
|
||
|
||
## 数据流
|
||
|
||
```
|
||
Dota 2 GSI → gsi_watch.py (:3223)
|
||
→ DraftSession 轮询截屏
|
||
→ recognize_image (CDN 模板 + 可选天梯遮罩)
|
||
→ roles / grid / modes（辅助）
|
||
→ results/draft_*.json + 终端时间线
|
||
```
|
||
|
||
## 技术约束（修改前必读）
|
||
|
||
- **合规**：仅 GSI + 屏幕截图；**禁止**读进程内存、注入、绕过 VAC。
|
||
- **GSI 范围**：普通玩家视角拿不到双方 pick；GSI 只作阶段触发与 `team_slot` 等自身信息。
|
||
- **模板策略**：只维护 CDN 层。皮肤问题用会话策略（选人可改判、决策 `allow_revise=False`、best 帧偏 HERO_SELECTION），不要为皮肤加模板库。
|
||
- **坐标**：一律相对坐标（相对屏幕高 / 相对中心），勿写死像素分辨率。
|
||
- **宁可不认，不可乱认**：`min_score` + `min_margin` 双门控；不确定就 `null`。
|
||
- **平台**：面向 Windows；截屏依赖无边框/窗口模式。
|
||
|
||
## 开发命令
|
||
|
||
```powershell
|
||
pip install -r requirements.txt
|
||
python fetch_cdn_templates.py
|
||
python gsi_setup.py --check
|
||
python gsi_watch.py --once
|
||
python recognize.py samples/raw/<帧>.png --sheet
|
||
python evaluate.py
|
||
```
|
||
|
||
## 修改原则
|
||
|
||
- 只改任务所需逻辑，避免无关重构与大范围格式化。
|
||
- 代码标识符、日志、错误信息、注释用**英文**；用户可见摘要可用中文。
|
||
- 改匹配阈值或裁切时，用 `evaluate.py` / 标注帧验证，并更新 `CHANGELOG.md` 与必要时的 `DESIGN.md`。
|
||
- 改 GSI cfg 时同步核对 `gsi_setup.py` 与 Dota `gamestate_integration` 目录。
|
||
- 改 `heroes.json` 结构时同步 `grid.py`（依赖 `attr` / `name_loc`）。
|
||
- 不要重新引入 real 模板双层库、`cdn_penalty`、`build_library.py`。
|
||
|
||
## 文档分工
|
||
|
||
| 文件 | 内容 |
|
||
|------|------|
|
||
| `README.md` | 安装与操作手册 |
|
||
| `DESIGN.md` | 背景、选型、关键实测与决策记录 |
|
||
| `AGENTS.md` | 本文件：给协作者 / AI 的约束 |
|
||
| `CHANGELOG.md` | 面向用户的版本变更 |
|
||
|
||
## 与 dota2-hex
|
||
|
||
本仓库独立演进。并入或旁路对接时，仍须遵守 [dota2-hex/AGENTS.md](../dota2-hex/AGENTS.md) 的合规边界。
|