aramgg_client

语言：简体中文（默认） | English

英雄联盟 ARAM 辅助工具，基于 Electron + Vue 3 + electron-vite。当前能力集中在：

• 通过 LCU 只读接口和 OnJsonApiEvent WebSocket 读取选人、游戏流程状态。
• 在 ARAM 选人阶段通过英雄详情窗口顶部展示当前英雄与席位英雄的只读推荐。
• 在实际对局 InProgress 阶段自动截图并按卡片位置识别海克斯强化。
• 通过英雄详情、海克斯顶部浮窗和游戏右侧推荐列表展示英雄、海克斯、装备等胜率和推荐信息。

本项目只做辅助判断和展示，不自动选英雄、不自动换 bench、不自动锁定或接受交换。

动态图表由开源项目 Star History 提供。

如果这个项目对你有帮助，欢迎通过微信或支付宝支持后续开发与维护。

• src/main/：Electron 主进程，窗口、IPC、LCU、截图、OCR、数据加载。
• src/preload/：sandbox preload，通过 window.electronAPI 暴露最小业务 API。
• src/renderer/：Vue 渲染进程，页面、组件、服务和样式。
• src/shared/：main、preload 与 renderer 共用的 IPC 类型契约。
• tests/unit/：纯工具、状态转换等可独立运行的 Vitest 单元测试。
• tests/electron/：Electron/Node 侧测试脚本。
• docs/：当前功能指南、排障、架构进度和归档文档。
• legacy/：仅保留归档材料，不再包含旧 React 源码；新功能不要放到这里。

dist/、dist-electron/、build/ 是构建产物，不应提交。

npm install
npm run dev
npm run prepare:client-data
npm run test:unit
npm run test:augment-ocr
npm run lint
npm run type-check
npm run build
npm run pack

针对性脚本：

node tests/electron/test-aram-bench-recommendation.js
node tests/electron/test-winrate-query.js
node tests/electron/test-screenshot-analysis.js
node tests/electron/test-augment-ocr-fixtures.js

GitHub Actions 会在 Windows Runner 上执行 lint、type-check、unit tests 和 npm run pack。

• 推送到 master：生成 Actions artifact，方便检查安装包。
• 推送 v* tag：自动创建 GitHub Release，并上传安装包、.blockmap 和 latest.yml。
• 手动触发 Build Windows Release：只生成 Actions artifact，不创建 GitHub Release。

Release workflow 使用 Node 22.18.0 和 npm 10，并通过 npm ci --ignore-scripts 安装依赖。改动依赖或 package-lock.json 后，发布前先用 npm 10 校验一次锁文件：

npx -p npm@10 npm ci --ignore-scripts

正式发布使用 npm version，它会同时更新 package.json / package-lock.json、创建版本提交，并创建 v* tag。根据变更范围选择一个命令：

npm run release:patch
npm run release:minor
npm run release:major

然后推送版本提交和 tag：

npm run release:push

安装包发布后，更新远端客户端配置 /api/client/v1/config，让旧版本客户端能看到新版本和更新日志：

• client.latestVersion：新版本号。
• client.downloadUrl：新安装包或最新下载页。
• client.autoUpdateEnabled：自动下载/安装总开关，未完整测试前保持 false 或不下发。
• client.updateFeedUrl：自动更新 feed 目录；只有 client.autoUpdateEnabled: true 时才会被客户端使用。
• client.changelog / client.releaseNotes：新版本更新条目。

自动更新 feed 目录需要包含 latest.yml、aramgg_client Setup <version>.exe 和对应 .exe.blockmap。当前优先更新 latestVersion、downloadUrl 和更新日志，让旧客户端走手动下载；等自动更新链路验证完整后再开启 autoUpdateEnabled。

远端配置不能自行扩展更新信任根。启用自动更新前，必须在 src/main/app-update-service.ts 中写入确认后的 HTTPS feed origin 和 Windows 证书发布者 CN，并发布经过 Authenticode 签名的安装包。开发环境只有同时启用 ARAMGG_ALLOW_DEV_UPDATE_CHECK，才会读取 ARAMGG_UPDATE_ALLOWED_ORIGINS 和 ARAMGG_UPDATE_PUBLISHER_NAMES 进行本地链路测试。

示例：当前 0.1.0 执行 npm run release:patch 会生成 0.1.1 的版本提交和 v0.1.1 tag；推送后 GitHub Actions 会校验 tag 必须等于 package.json 版本，校验通过才发布 Release。

不要手动创建轻量 tag 代替发布脚本。需要清理错误发布时，先确认要删除的本地和远端 tag，再按同一版本号重建 annotated tag。

• 新增源码、服务、工具、IPC 契约和测试优先使用 TypeScript；只有延续既有 JavaScript 模块或工具边界确实不方便时才新增 .js。
• Vue 组件继续使用单文件组件，业务逻辑尽量放到 services 或 utilities。
• 新增或修改 Electron API 时，先更新 src/shared/ipc-contract.ts，再同步 main handler、preload bridge 和 renderer 调用方。
• TypeScript 迁移和排障细节见 TypeScript 集成总结。

客户端数据接口、API Key 申请和接入说明见 ARAMGG 数据 API 开发者页面。

本仓库不提交真实 API Key。需要本地配置时，复制 .env.local.example 为 .env.local，再填入自己的 ARAMGG_DATA_API_KEY。

客户端数据的 manifest 路径和资源 URL 会经过统一安全校验。ARAMGG_DATA_ALLOWED_ORIGINS 只用于显式补充可信数据源，多个 origin 用逗号分隔；生产源必须使用 HTTPS，只有本地开发的 localhost 可使用 HTTP。

客户端展示数据采用按语言隔离的本地优先策略：默认中文继续使用 current.json / versions/<dataVersion>/，英文和繁中使用 current.<locale>.json / versions/<locale>/<dataVersion>/。打包内置和运行时完整数据会先用于英雄详情、海克斯弹窗和推荐列表渲染；远端配置只用于后台检查和准备同语言新版本，必需文件完整后才切换。

• 完整架构
• 大乱斗 LCU 只读推荐进度
• 游戏阶段检测指南
• LCU 排障指南
• 自动海克斯检测使用指南
• 客户端数据 API 分发策略
• 客户端多语言数据支持专项审查
• 全项目代码审查与整改状态
• Electron 客户端版本更新方案
• Electron / electron-vite 架构整改进度
• TypeScript 开发约定
• 项目改进建议与实施进度
• 需求规格

较早的实现总结、计划和完成报告已归档到 docs/archive/2026-01-legacy，仅保留历史上下文；当前实现以本节列出的文档和源码为准。

• 主界面状态栏右上角的语言菜单支持 zh-CN、en-US 和 zh-TW；下方状态区保持客户端版本、数据版本、LCU 连接一行三列。选择成功后，主窗口、英雄详情、席位推荐、海克斯浮窗、右侧推荐列表和赛后海报会统一切换文案与数据。
• 语言切换是先准备、后提交的事务：只有本地或数据 API 存在完整且精确匹配的目标语言数据集时，才会广播 locale-changed 并切换 Vue i18n；准备期间仅语言菜单显示局部进度，提交后的远端版本信息在后台刷新，失败时界面和数据都保留原语言。
• Renderer 文案集中在 src/renderer/i18n/messages.ts；新增用户可见文案必须同时补齐三种语言，并通过语言资源键一致性单测。
• 主窗口默认按主显示器工作区靠右展示，英雄详情窗口、海克斯顶部浮窗和右侧推荐列表仍由主进程统一布局。
• 主界面「窗口偏好」可控制进游戏是否关闭英雄详情页、是否展示海克斯顶部浮窗、是否展示海克斯右侧推荐列表。
• LCU 凭据默认从运行中的 League Client 进程自动发现；主界面「游戏目录」是自动发现失败时的高级兜底，只用于读取 LCU lockfile / 日志。
• Windows 安装包使用 NSIS 引导式安装，可在安装时选择安装目录；安装器会把用户选择的父目录归一化到 ...\aramgg_client 应用子目录。
• 运行时可变数据统一通过 src/main/modules/app-paths.ts 管理：安装版优先写入安装目录旁的 aramgg_client-data/，不可写时回退到 Electron userData。
• 子目录约定：config/ 存储 electron-store 配置，logs/ 存储应用日志，data/ 存储版本化客户端数据缓存，ocr-partial-screenshots/ 存储 OCR 调试截图。

Renderer 不拥有 Node 能力，只能通过 preload 暴露的 electronAPI 调用主进程。Electron 窗口保持 nodeIntegration: false、contextIsolation: true、sandbox: true、webSecurity: true。

LCU 推荐链路只能读取状态和统计数据。禁止把 pickOrBan、benchSwap、action、acceptTrade、declineTrade 等改变选人结果的接口接入推荐模块。

• LINUX DO