面向 KovaaK's FPS Aim Trainer 的认真训练者：打完一局，它已经看完了你的鼠标轨迹、对局遥测、击杀记录和录像，能告诉你哪里出了问题、偏了多少度、下次练什么。
不打分、不玄学——所有证据来自你自己的机器，分析与数据都留在本地。
Coach 的瞄准知识不再只有官方一套。我们把整条知识体系做成了可替换的开放格式：懂瞄准的你——教练、UP 主、硬核玩家——可以把自己的知识做成一个「知识包」，导入 Aiming Cookie 后整库替换官方知识。Coach 讲什么、推荐什么训练，全按你的体系来；官方知识库永远是内置默认档，一键切回，坏包自动回退，分析不受影响。
- 想做自己的知识库：从 知识库 SDK 规范 开始（English），模板包 改一改就能导入
- 数据说明文档：AC 采集哪些数据、从哪来、反映什么，逐类写清——做「数据→现象」映射规则的前提（中文 / English）
- 官方诊断规则以同样格式随产品发布（
knowledge/mapping/），是最好的参照样本；校验器 CLI 随仓库提供
市面上的瞄准工具只有两种：数据面板（给你 KPS/命中率，但不说为什么）和感觉派教学（说得出为什么，但看不到你的数据）。
Aiming Cookie 的立场是：教练必须先看证据，再开口。 它把一局训练拆成四路证据，用确定性管线测量、用视觉管线"看"靶子，最后让大模型教练拿着这些事实讲课——每一句判断都能追溯到具体数据，讲不到的就是不知道。
你打一局 KovaaK
│ （全自动，无需任何操作）
▼
┌─────────────────────────────────────────┐
│ 多源证据采集 │
│ 对局遥测 · Stats 击杀表 · │
│ Performance 计数 · Raw Input 轨迹 · 录像 │
└─────────────────────────────────────────┘
▼
┌─────────────────────────────────────────┐
│ 确定性分析 + 通用视觉 CV │
│ 运动学指标 · 靶子检测 · 击中判定 · │
│ 偏移向量 · 转火节奏 · 跟靶误差 │
└─────────────────────────────────────────┘
▼
┌─────────────────────────────────────────┐
│ AI Coach 讲解 │
│ 读真实数据 → 指出问题 → @ 视频片段 │
│ → 给训练建议 → 记录进步 │
└─────────────────────────────────────────┘
分数面板只会告诉你"打得怎么样"，遥测能回答"场面和手到底发生了什么"：
- 全自动采集：KovaaK 击杀表、成绩计数、对局遥测、窗口录像随局自动入库，打完即得；源文件指纹校验，改过一个字节都会被发现
- 靶子的完整真值：每个靶子何时出现、在哪、怎么移动、多大、何时被消灭——全部来自游戏自身数据，不是从画面里估算；尺寸直接取自场景定义
- Windows Raw Input（opt-in 授权）：1ms 采样率的操作系统级真实鼠标信号——不是游戏内插值的近似值
- 真值直接算指标：每发子弹的命中/脱靶、击杀瞬间的角度误差、跟靶误差曲线、转火耗时——由"靶子真值 + 原生输入"直接导出，命中口径以遥测为权威，角度测量精确到亚度级
- 同一条毫秒时间轴：所有证据互相对齐，Coach 指到的每一秒都对得上画面
遥测不可用的对局（旧存档、特殊场景），视觉管线能从录像里独立重建证据：
- 全场景覆盖：静态点击（甩枪/点靶）、动态点击（移动靶）、切换（转火）、追踪四大类，任何地图无需预先配置
- 零训练、零模型文件：基于封闭三形状先验（KovaaK 靶只有球/竖胶囊/人形）+ 颜色假设集自动发现靶色，纯传统 CV，确定性可复现
- 行为细节：准星修正动作的形态、转火轨迹等画面层证据，可与遥测交叉印证
- 诚实降级：每局带质量门（靶色置信度、击杀配对率、覆盖率），看不懂的局（如烟花粒子场景）绝不编造视觉结论
接上你自己的 LLM Provider（OpenAI 兼容协议），或使用 Aiming Cookie 官方托管服务（内测期）后：
- 讲解基于事实：Coach 通过受控工具读取分析证据（指标、事件、分布），而不是靠模型瞎猜；术语遵循社群校订的对照表（甩枪/停稳/转火，不说 flick/settle）
- @ 视频回看：讲解里说"这 3 秒注意看你的修正"，点 @ 标记直接跳到录像对应时刻
- 训练闭环：从诊断生成训练计划 → 跟踪完成情况 → 复测对比进步
- 场景直达：一键搜索 KovaaK 官方场景库（17 万+ 场景），推荐场景经你确认后直接拉起 KovaaK 开练
- 本地知识库：内置瞄准理论、KovaaK 数据解读、外设（鼠标/鼠标垫）选择等结构化知识，Coach 讲课前必须先查库、查不到就明说
- 长期视角：跨局趋势、历史对照是 Coach 的本职，不需要你翻旧记录
- 单用户桌面应用：局、分析、对话、知识全部留在本机，以 JSON 文件存储（
%APPDATA%），人可读、可备份 - 自动的联网只有两类：版本更新检查、KovaaK 版本适配表获取——都不涉及你的训练数据
- 其余联网由你决定：模型流量只发往你自己配置的 Provider（或内测期的官方托管服务）；诊断包只在你手动点「上传」时才会发送
三个日常表面，没有仪表盘堆砌：
- Coach：对话 + 当前训练计划 + 「本次讨论」挂载的局（点开即看该局录像）
- History：每局的时间线、分析状态、录像回放
- 分析工作台：诊断结论 / 视频播放器 / 数据视图三栏，从任一指标下钻
v1.3.2 已发布（安装包与自动更新经官网分发；安装包未签名，SmartScreen 需选择「仍要运行」）。
- ✅ 四源采集链路、通用视觉分析、Coach 全能力、自动更新——均经真机验证
- 🚧 已知限制：含视频的分析需等待 1-2 分钟（有进度显示）；击中判定存在 ±10px 视觉灰区；安装包未签名
- 📋 详细状态与阻塞见
docs/PROGRESS.md
普通用户：从官网 aimingcookie.com 下载安装包 → 安装 → 设置页配置 LLM Provider → 授权 Raw Input 与窗口采集 → 打开 KovaaK 开打。
从源码运行与开发：见 docs/DEVELOPMENT.md（三进程启动、测试命令、Tauri 打包）。
| 层 | 技术 | 要点 |
|---|---|---|
| 桌面壳 | Tauri (Rust) | 窗口采集、Raw Input、本地令牌、子进程编排 |
| 后端 | Python FastAPI | 分析任务队列、KovaaK 摄取、确定性分析管线 |
| Coach 运行时 | Bun/Node sidecar | LLM 对话编排、受控工具、JSONL 会话持久化 |
| 视觉 | OpenCV 传统 CV | 三形状分类 + 颜色假设集，无神经网络 |
| 前端 | Next.js | Coach / History / 分析工作台 |
| 数据 | 本地 JSON 文件 | 无数据库，人可读可备份 |
数据合同采用"冻结合同"治理：关键 schema 显式版本化（*.v1），升级必须走版本演进而非静默改写。
| 路径 | 职责 |
|---|---|
kovaak_tracker/ |
确定性分析与视觉领域逻辑（运动学、CV、证据合同） |
telemetry_capture/ |
对局遥测采集与 KovaaK 版本适配 |
webapp/backend/ |
FastAPI、任务队列、KovaaK 摄取、Coach 编排 |
webapp/coach-runtime/ |
Node Coach sidecar（对话、工具、知识库） |
webapp/frontend/ |
Next.js 前端与 Tauri 桌面壳 |
third_party/pi/ |
项目接管的 Pi runtime 源码基线 |
design/ |
官网落地页与历史设计稿 |
scripts/ |
构建、打包、e2e 辅助脚本 |
docs/ |
产品、架构、路线图、进度与历史资料 |
tests/, webapp/tests/ |
核心与 Web/Desktop 回归测试 |
- 产品目标与范围：
docs/PRD.md - 系统边界与数据合同：
docs/ARCHITECTURE.md - 安装、启动、测试：
docs/DEVELOPMENT.md - 交付顺序：
docs/ROADMAP.md· 当前快照：docs/PROGRESS.md - 文档体系总入口：
docs/README.md
本项目以 GPL-3.0-or-later 开源发布。第三方归属见 NOTICE：
- RefleK's（GPL-3.0）：KovaaK
.perf成绩解析器的字段映射改编自其实现，见kovaak_tracker/performance_parser.py - pi (Pi Agent Harness)（MIT）：vendored 于
third_party/pi/
本项目为独立个人项目，与 KovaaK's / FPS Aim Trainer、Steam、Valve 无任何从属关系。
本文描述的能力以当前代码、测试和真机运行结果为准。