aoe2coach

# aoe2coach [](https://github.com/kw300/aoe2coach/actions/workflows/ci.yml) **《帝国时代 II》进步非常困难。** 输掉比赛后，往往只会留下一种模糊的感觉，觉得某些地方出了问题，而重看比赛录像又需要花费20分钟。 **aoe2coach 让玩家可以与比赛录像交流。** 进入游戏，询问哪里出了问题，然后从实际的比赛录像中提供指导：开局策略、升级时机、闲置的城镇中心时间、军队选择、升级和决定比赛的战斗。 比赛录像始终保留在对话中。可以跟进讨论深入了解单位、战斗、经济、市场使用、文明奖励或最近几场比赛的重复习惯，而无需重新开始。网页工作流程围绕练习重点构建：从录像中检测可能习惯，固定需要训练的习惯，将目标带入完整的指导报告，并导出整个会话以保存。 **目前最好的结果来自于在2026年2月Last Chieftains更新之前记录的比赛录像。** 完整的解析器暴露了村民队列、EAPM、地图数据、命令和更丰富的对象时间线，以适用于这些游戏。更新后的比赛仍然通过轻量级解析器运行，而丰富的解析器赶上更新的比赛格式。 ## 演示：Hera vs Sora Kuma 此示例分析了Khmer vs Malay Arabia游戏中[**Hera**](https://liquipedia.net/ageofempires/Hera)和[**Sora Kuma**](https://liquipedia.net/ageofempires/Sora_Kuma）两名世界上最强的AoE2玩家之间的比赛。观看比赛，然后尝试在相同的比赛录像中使用aoe2coach网页工作流程：预览事实，选择要指导的玩家，审查轻量级习惯建议，固定需要练习的习惯，并在准备好时运行完整分析。 <p> <a href="https://www.youtube.com/watch?v=T3ZhmVcX3Vw"><img alt="在YouTube上播放Hera vs Sora Kuma比赛VOD" src="docs/assets/youtube-card.jpg" width="640"></a> </p> <video src="https://github.com/user-attachments/assets/709add66-b88c-48c4-aae0-0881067ca380" controls width="720"></video> --- ## 入门指南 ### 1. 安装 ```bash git clone https://github.com/kw300/aoe2coach cd aoe2coach python3 -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -U pip pip install -e ".[full,web]" # 旧录像的丰富解析器 ``` 对于当前补丁的录像，请安装 `.[fast,web]`。 ### 2. 配置 ```bash cp env.example .env # 添加API密钥/提供商配置（gitignored） ``` 从[Anthropic Console](https://console.anthropic.com/settings/keys)获取Claude模型的密钥或从[OpenAI API密钥](https://platform.openai.com/api-keys)获取GPT模型的密钥。 您需要提供密钥并直接向提供商付费；aoe2coach不托管或转售API访问权限。 Anthropic: ```bash AOE2COACH_PROVIDER=anthropic ANTHROPIC_API_KEY=sk-ant-... ``` OpenAI: ```bash AOE2COACH_PROVIDER=openai OPENAI_API_KEY=sk-... ``` API调用会产生费用；在运行完整分析之前，请查看[Anthropic定价](https://www.anthropic.com/pricing)或[OpenAI定价](https://platform.openai.com/docs/pricing/)。 aoe2coach使用轻量级模型进行初步习惯检测，使用旗舰模型进行比赛录像报告和详细指导。 CLI和浏览器UI读取本地`.env`；网页应用永远不会请求或存储API密钥。 可选的模型覆盖、推理努力和OpenAI兼容的端点示例位于[`env.example`](env.example)。 您更喜欢通过MCP兼容的助手引入模型，而不是配置aoe2coach API密钥吗？此路径正在进行中；请参见[其他运行方式](#其他运行方式)和[docs/mcp.md](docs/mcp.md)。 ### 3. 运行 ```bash aoe2coach web # 打开浏览器 ``` 然后拖入比赛录像，或从左侧面板选择一个。网页应用在进行完整分析调用之前预览确定性事实：地图、玩家、文明、结果、比赛日期、缩略图、基本信息和可读的时间线。 选择要指导的玩家，审查轻量级练习重点建议，固定需要跟踪的习惯，添加自定义习惯（如果需要），然后使用旗舰模型运行完整分析。 固定的和检测到的习惯将被传递到报告中，以便指导员可以将比赛证据与玩家的当前训练目标联系起来。 使用 **导出会话** 将当前的预览、习惯、时间线和聊天作为Markdown文件保存在 `reports/session-exports/` 下，并从浏览器下载副本。 您更喜欢终端吗？CLI执行相同的操作，脚本化： ```bash aoe2coach find # 定位比赛录像文件 aoe2coach analyze latest # 保存报告 aoe2coach trends --last 10 # 重复习惯 aoe2coach metrics latest # 统计JSON aoe2coach minimap latest # 地图PNG ``` 请提供API密钥。费用取决于模型和提供商：aoe2coach可以使用较便宜的模型进行练习重点检测，使用旗舰模型进行最终指导报告。 保存的报告位于 `reports/`（[阅读示例aoe2coach聊天记录](reports/session-exports/aoc-mgz-de-66.6-2026-06-02-10-13-30.md)）。 ## 提供的内容 **1. 具有观点的指导报告：** ``` Jian Hei 比 Feudal 快一分钟到达，但随后停滞了。 Feudal 后立即有一个 232 秒的空闲城镇中心，损失了约 8 名村民，并且再也没有恢复：71 名村民对 112 名村民，没有帝国，并且 Janissary 群无法与 Bombards 抗衡。 首要任务：永远不要让城镇中心空闲。 你已经有速度了；添加村民。 ``` **2. 练习重点工作流程** - 在运行完整报告之前，选择被指导的玩家，让轻量级模型建议特定于比赛录像的习惯。固定有用的习惯，添加自定义目标，完整分析将明确考虑这些练习目标，而不是产生通用的比赛后审查。 **3. 跨游戏的习惯跟踪** - `aoe2coach trends --last 10` 查找重复模式： *"封建时代的升级在过去 10 场比赛中的 7 场比赛中缺失，并且在大多数游戏中，有 1,500+ 木材在城堡时代浮动。 解决这两个问题将改善封建时代的时机问题。* **4. 交互式指导** - `aoe2coach web` 打开浏览器聊天：选择比赛录像，选择要指导的玩家，运行完整报告，然后在实时对话中提出后续问题（“为什么 25 分钟的战斗如此昂贵？”，“什么一直出错？”）。正在开发中的MCP路径还可以将比赛指标带到兼容的助手 - 请参见[其他运行方式](#其他运行方式)。 **5. 会话导出** - 网页UI可以将当前的比赛录像预览、练习重点习惯、基本信息、时间线和聊天记录导出为Markdown，然后本地保存并下载浏览器副本。 ## 工作原理 核心思想： **用代码做具体、枯燥的事情；让模型进行判断。** ``` 比赛文件 → 解析 → 计算统计数据 → 模型指导 → 报告 (.aoe2record) (mgz) (村民计时、 (几KB JSON， 空闲TC、建筑顺序、 紧凑的指标) 谁赢得了每场战斗) ``` 计时、村民数量和谁输掉了哪场战斗都是用Python确定性计算的。模型根据几KB的结构化统计数据和“什么是好的”参考进行指导，这使得报告快速、便宜，并基于比赛录像。 ### 使用的比赛数据 - **升级时间** （封建/城堡/帝国）和它们之间的间隔 - **村民生产 → 空闲城镇中心检测** — 最主要的宏观漏洞 - **建筑顺序** — 每个建筑物，均有名称和时间戳 - **军队组成和独特单位使用** ，以及**已研究的命名技术/升级** - **关键技术状态** — 已研究与可用但未使用 vs. 未可用升级线路，基于本地文明技术树 - **资源浮动** — 银行中未花费的资源 - **战斗时间线** — 战斗发生时间、双方损失、谁赢得了交易 - **EAPM** 、**胜负**、**文明**、**地图**和每个玩家的**实际排名ELO** （按个人资料ID） - **玩家颜色** 根据解析器提供的颜色标签进行归一化，以便UI高亮、缩略图标记和模型上下文在比赛版本之间保持一致。 ⚡ = 需要丰富的解析器（旧比赛录像；见下文）。当前补丁游戏仍然提供时代、建筑顺序、文明和结果。 ## 哪些比赛录像有效 比赛录像格式每个补丁都会发生变化，丰富的解析器（[`mgz`](https://github.com/happyleavesaoc/aoc-mgz)）目前涵盖了2026年2月Last Chieftains更新之前使用的格式： - **2026年2月之前的比赛录像 → 完整处理** （村民生产、空闲TC、EAPM、战斗时间线、缩略图）。安装 `.[full]`。 - **2026年2月及更新的比赛录像 → 轻量级解析** 通过[`mgz-fast`](https://github.com/AoEInsights/aoc-mgz) — 建筑顺序、时代计时、结果、较少的深入统计数据。安装 `.[fast]`。 *(为什么延迟： [aoc-mgz #138](https://github.com/happyleavesaoc/aoc-mgz/issues/138)。)* **想尝试兼容的比赛录像吗？** [`aoc-mgz` 比赛录像库](https://github.com/happyleavesaoc/aoc-mgz/tree/master/tests/recs) 有旧的2026年2月之前的AoE2/AoC比赛文件（`.mgz` / `.aoe2record`），包括演示中使用的GL.Hera游戏。 ## 底层 aoe2coach尝试为模型提供足够小的比赛证据，以便进行推理，同时足够具体以停止模糊的建议： - **经济节奏：** 村民队列间隙转换为估计的空闲城镇中心时间，以便“增加更多村民”与生产滑移的确切分钟联系起来。 - **时代和建筑节奏：** 封建/城堡/帝国计时，第一批生产建筑和主要技术作为时间戳事件，而不是模糊的开局标签。 - **战斗压力：** 在丰富的比赛录像中，对象数量下降被分组为战斗，记录每位玩家的损失和交易结果。它不是战术比赛录像查看器，但它告诉指导员哪些战斗可能决定了比赛。 - **升级基础：** 常见技术根据本地文明技术树检查，然后模型查看它们，因此不可用的升级被标记为不可用，而错过的升级与已研究的升级分开。 - **练习重点：** 检测到的和固定的习惯被包含在最终模型请求中作为训练优先级，因此报告可以将当前比赛录像与玩家积极尝试改进的内容联系起来。 - **玩家颜色：** 解析器提供的颜色标签在到达Web UI或模型之前被标准化，原始颜色ID仅作为备用方案。这样可以避免在比赛/解析器版本之间出现颜色调色板错误。 ## 其他运行方式 **MCP（进行中，无aoe2coach API密钥）— 将比赛指标带到助手。** aoe2coach附带一个可用的MCP服务器（`tools`：`list_replays`、`replay_metrics`、`replay_trends`；`prompts`：`coach`、`coach_trends`）。服务器通过标准MCP公开确定性的比赛数据，但设置打包和比赛选择UX仍在完善中。Claude Code/Desktop是当前记录的客户端。完整设置： **[docs/mcp.md](docs/mcp.md)**。 ## 路线图 - **玩家配置文件和目标感知指导** - 从最近的比赛、固定的习惯、ELO上下文、文明/地图模式和重复的弱点中构建可重复使用的玩家配置文件，然后针对每个单场比赛报告的目标是那些可能使玩家进步的习惯。 - **多游戏趋势习惯指导** - 通过地图、文明、匹配、游戏阶段和损失模式对习惯进行分组，使`trends --last 10`更精确，然后将趋势总结转化为指导分析和练习目标，在网页工作流程中。 - **最新补丁丰富解析** - 通过提取`mgz-fast`中的更多数据并自动将旧/新比赛录像路由到正确的解析器来缩小当前AoE2补丁差距。 - **MCP助手工作流程** - 改进MCP路径，以便玩家可以使用兼容的助手进行指导，并提供打包的配置片段和更清晰的比赛UX。 - **模型选择和成本配置文件** - 添加文档化的旗舰、预算、OpenAI兼容和本地模型的预设，以及更清晰的缓存/成本报告。 - **指导评估测试** - 维护一个小型匿名比赛录像库，并带有预期的指标快照和黄金指导检查，以便对解析器更改和提示编辑进行回归测试。 - **指导行为和游戏知识调整** - 完善指导风格、补丁感知AoE2知识、文明/单位细微差别和更好的后续答案的系统提示。 - **更智能的战斗分析** - 将对象损失与命令位置、单位成本、选定对象ID相结合，估计战斗发生的位置及其价值。 - **建筑顺序和ELO基准** - 将开局、时机和文明/地图性能与匹配感知的模板和公共评级括号数据进行比较。 ## 限制 - 丰富的解析器目前涵盖2026年2月Last Chieftains更新之前的比赛录像；更新的梯子游戏使用更轻的解析器。 - 战斗分析故意粗糙。目前，丰富的解析器提供建筑/研究/单位输入、地图数据、起始对象、命令位置和对象/资源时间序列。aoe2coach使用这些时间线中的下降来标记昂贵的战斗和出血的一方。确切的组成、定位、归因杀戮和路径级战斗重建属于未来的模拟级分析路径。 ## 致谢 在 [**mgz**](https://github.com/happyleavesaoc/aoc-mgz)和 [**AoEInsights `mgz-fast`分支**](https://github.com/AoEInsights/aoc-mgz) （比赛解析）、 [**SiegeEngineers aoe2techtree**](https://github.com/SiegeEngineers/aoe2techtree) 数据集（游戏数据名称）和用于指导的自带模型提供商。 ## 许可证 MIT - 请参阅 [LICENSE](LICENSE)。