Imported from 115581748/LOL_MMR (
AGENTS.md). Install upstream withnpx skills add 115581748/LOL_MMR. Copyright stays with the author.
峡谷天平维护规则
使命
持续改进本仓库，同时保持数据、模型、桌面程序和发布产物稳定。不要为了产生改动而改动；只有在可靠性、正确性、数据质量、可解释性、可用性、性能或开发体验存在可验证收益时才修改代码。
优先顺序
- 修复构建失败、测试失败、运行时错误和回归。
- 修复重复、过期、缺失或不一致的 Riot 数据。
- 提高采集、缓存、断点续传、限流和 API 错误处理的可靠性。
- 保证模型口径稳定，明确区分事实、估计、启发式推断和 AI 解释。
- 改善会妨碍玩家理解逐局对比与复盘的界面问题。
- 为重要行为补充测试并减少重复代码。
- 仅在有测量证据时优化性能。
- 最后才是文档或没有明确证据的新功能。
自主维护流程
每次自主运行只选择一个小而高价值的改进：
- 检查工作区、近期改动、测试、TODO/FIXME、数据产物、构建配置和可用日志。
- 必要时检查 GitHub issue、PR 与 CI，但不要仅凭猜测修改代码。
- 按玩家影响、正确性、证据强度、成本和回归风险排列候选项。
- 只实现排名最高且能够完整验证的一项；不可分割的修改除外。
- 运行相关单元测试、静态检查与构建检查。
- 说明问题、证据、改动、验证结果、风险和后续项。
如果没有明确值得修改的问题，不要改代码，只输出检查报告。
项目不变量
- Riot Timeline 是赛后数据，不得表述为对局中的实时 API。
- 人物坐标约每 60 秒采样；击杀、购买、视野与目标事件可有毫秒时间戳。界面必须显示这种精度差异。
- 死亡时间与地点来自
CHAMPION_KILL；普通 Timeline 不提供精确复活事件，任何复活倒计时都必须标为估计且不得进入模型特征。 - Riot API 不提供真实兵线与野怪营地状态；不得把估算值冒充观测事实。
- 原因分析只能输出“候选原因/可能相关”，必须链接证据、来源和置信度；时间先后不等于因果。
- Riot 不直接提供团战事件；当前团战定义为连续击杀间隔不超过 15 秒且至少包含 3 次英雄击杀的规则聚类，必须标为派生事件并保留原始击杀证据。
- 基准必须匹配英雄和位置；修改时间分段、样本范围或指标定义时必须显式迁移并记录。
- 25 分钟前指标保持原口径；25 分钟后英雄伤害与承伤按 25+ 实际时长折算为每分钟。
- 数据写入必须可重复执行并按稳定键去重，不能通过删样本掩盖错误。
安全与 Git
- 不得提交、打印或持久化 Riot API Key、访问令牌、私有玩家数据或其他密钥。
- 不得修改生产密钥、删除生产数据、弱化验证、跳过失败测试或修改指标使结果看起来更好。
- 自主运行不得直接推送或合并
main，不得强推共享分支。 - 使用独立分支：
agent/daily-improvement-YYYY-MM-DD-short-description。 - 保持提交小且单一；不做每日大规模架构重写，不无依据引入大型依赖。
- 尊重已有未提交改动，不覆盖或清理用户工作。
验证
至少运行与改动相关的测试。常用命令：
python -m unittest tests.test_desktop_app tests.test_model
python -m compileall -q riot_model desktop tests修改桌面打包路径或资源后，还应使用 desktop/LOLHighRankComparator.spec 完成 PyInstaller 构建检查。若某项无法运行，必须说明原因，不得宣称全部验证通过。
完成标准
问题有证据、改动范围清晰、相关检查通过、没有已知回归，并且能用几句话解释其玩家价值。自主任务结束前记录可长期复用的经验，但不得记录密钥或临时数据。