climperor/AGENTS.md

协作说明（面向 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；截屏依赖无边框/窗口模式。

开发命令

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 的合规边界。