AgentPlayerAchievements

# Agent Player 成就系统 (AGPA) 🏆 <p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="pixel-art-output/agpa-logo-dark.png"> <source media="(prefers-color-scheme: light)" srcset="pixel-art-output/agpa-logo-light.png"> <img alt="AGPA Logo" src="pixel-art-output/agpa-logo-dark.png" width="192"> </picture> </p> <p align="center"> <strong>English</strong>&nbsp;|&nbsp;<a href="./README.zh-CN.md">中文</a>&nbsp;|&nbsp;<a href="./README.es.md">ES</a>&nbsp;|&nbsp;<a href="./README.ko.md">한국어</a>&nbsp;|&nbsp;<a href="./README.ja.md">日本語</a> </p> <p align="center"> AI 编程代理的游戏化成就系统。<br> <em>赚取经验值，解锁奖杯，提升等级 — 只需做你已经在做的事情。</em> </p> <p align="center"> <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a> <a href="#"><img src="https://img.shields.io/badge/achievements-217-blueviolet" alt="217 achievements"></a> <a href="#"><img src="https://img.shields.io/badge/tests-1207-green" alt="1207 tests"></a> <a href="#"><img src="https://img.shields.io/badge/node-%E2%89%A518-brightgreen" alt="Node >= 18"></a> <a href="#"><img src="https://img.shields.io/badge/CLI-27_commands-orange" alt="27 CLI commands"></a> <a href="https://github.com/eiainano/AgentPlayerAchievements"><img src="https://img.shields.io/github/stars/eiainano/AgentPlayerAchievements?style=flat&logo=github" alt="GitHub stars"></a> <a href="https://github.com/eiainano/AgentPlayerAchievements/commits/dev"><img src="https://img.shields.io/github/last-commit/eiainano/AgentPlayerAchievements/dev" alt="Last commit"></a> <a href="README.zh-CN.md"><img src="https://img.shields.io/badge/i18n-5_languages-blue" alt="i18n: 5 languages"></a> </p> <p align="center"> <b>Claude Code</b>&nbsp;·&nbsp;<b>Kilo Code</b>&nbsp;·&nbsp;<b>OpenCode</b>&nbsp;·&nbsp;<b>Hermes</b>&nbsp;·&nbsp;<b>OpenClaw</b> </p> <p align="center"> <a href="#quick-start">快速开始</a> · <a href="#how-it-works">工作原理</a> · <a href="#features">功能</a> · <a href="#supported-tools">支持的工具</a> · <a href="#cli-commands">CLI 命令</a> · <a href="#community-packs">社区包</a> · <a href="#dashboard">仪表盘</a> · <a href="#security--privacy">安全与隐私</a> · <a href="#contributing">贡献</a> · <a href="#faq">常见问题</a> </p> --- ### 没有 AGPA ❌ - **无法看到**您的编码习惯在各个会话中的表现 - **无法跟踪进度** — 变快了？使用更多工具了？无从得知 - **缺乏动力** 去探索代理的全部功能集 - **每天都一样** 的例行工作 — 没有惊喜，没有里程碑 ### 使用 AGPA ✅ - **自动跟踪** — 每次工具调用、文件编辑和 git 提交都自动记录 - **类似 Steam 的仪表盘** — 经验值条、等级、连胜、热图、成就展示 - **217 个成就**，涵盖 11 个类别 — 从“Hello World”到“完美主义者” - **即时反馈** — 终端弹窗、macOS 通知、解锁时的 8 位音效 --- ## 仪表盘预览 <p align="center"> <table> <tr> <td align="center" width="50%"> <img src="assets/screenshots/agpa-shot-1.png" alt="AGPA Home" width="100%"><br> _{<b>首页</b> — 经验值条、连胜、代理统计} </td> <td align="center" width="50%"> <img src="assets/screenshots/agpa-shot-2.png" alt="Achievement Grid" width="100%"><br> _{<b>成就网格</b> — 217 个成就 × 11 个类别} </td> </tr> <tr> <td align="center" width="50%"> <img src="assets/screenshots/agpa-shot-3.png" alt="Achievement Sets" width="100%"><br> _{<b>成就集</b> — 主题收藏，带有进度跟踪} </td> <td align="center" width="50%"> <img src="assets/screenshots/agpa-shot-4.png" alt="Achievement Detail" width="100%"><br> _{<b>详情卡</b> — 稀有度、解锁日期、重放动画} </td> </tr> </table> </p> --- ## 快速开始 **先决条件：** Node.js ≥ 18 ```bash # 选项 A：全局安装（推荐用户） npm install -g @eiainano/agpa agpa init # 选项 B：克隆并链接（推荐贡献者） git clone https://github.com/eiainano/AgentPlayerAchievements.git cd AgentPlayerAchievements && npm install && npm link agpa init ``` 就这样。继续使用您的代理 — 成就将自动解锁。 > [!TIP] > 想在没有等待实际解锁的情况下查看仪表盘吗？运行 `agpa demo` 立即生成示例数据。 ```bash agpa dashboard # 打开成就仪表盘 agpa stats # 查看进度 agpa assets download # （可选）预下载所有 219 个像素艺术徽章 ``` ## 工作原理 ``` 您的编码会话 │ ├─ 您编码，代理响应 — 每次操作都被跟踪 │ └─ 双通道：MCP 工具 + Hook 事件 │ ├─ 会话结束 → 引擎评估 217 个成就 │ └─ 解锁？ → macOS 通知 🎉 │ └─ agpa 仪表盘 → 查看、排序、筛选、分享 ``` **两个数据通道 → 一个引擎 → 一个仪表盘：** | 通道 | 方法 | 捕获 | |---------|--------|----------| | **Hook CLI** | 工具钩子（子进程 via stdin） | file.read/write/edit, tool.complete, git.commit, session.start/end, task.complete, agent.spawn | | **MCP Server** | STDIO 协议（7 种工具） | image.read, file.language_used, plan.mode_entered, user.message, automode.start, achievement config, explain | 两个通道都写入同一个 `~/.agent-achievements/` 事件日志。引擎评估 12 种条件类型以匹配 217 个成就。 > [!NOTE] > **零开销。** Hook CLI 是一个毫秒级的子进程。MCP 服务器在 STDIO 上运行，无需网络调用。所有数据都保留在您的机器上。 ## 功能 - 🎮 **成就仪表盘** — 经验值条、等级、连胜、活动热图、稀有度分解、展示 - 🏆 **217 个成就**，涵盖 11 个类别 — 从“Hello World”到“完美主义者” - 🔥 **GitHub 风格的活动热图** — 一目了然的 4 个月编码活动 - 📸 **分享卡片** — 黑色/白色主题，双语，可下载的 PNG - 🔊 **8 位音效和通知** — 稀有度分级的复古音效 + 解锁时的桌面推送通知 - 📂 **多配置文件** — 最多 4 个配置文件，随时切换（工作、个人、实验） ## 支持的工具 <p align="center"> <a href="#claude-code"><img src="https://img.shields.io/badge/Claude_Code-auto_+_MCP-blueviolet?logo=claude" alt="Claude Code"></a> <a href="#kilo-code--opencode"><img src="https://img.shields.io/badge/Kilo_Code-auto_+_MCP-00b4d8" alt="Kilo Code"></a> <a href="#kilo-code--opencode"><img src="https://img.shields.io/badge/OpenCode-auto_+_MCP-2ec4b6" alt="OpenCode"></a> <a href="#cursor--vs-code"><img src="https://img.shields.io/badge/Cursor-MCP_only-007acc?logo=cursor" alt="Cursor"></a> <a href="#cursor--vs-code"><img src="https://img.shields.io/badge/VS_Code-MCP_only-007acc?logo=visualstudiocode" alt="VS Code"></a> <a href="#hermes"><img src="https://img.shields.io/badge/Hermes-MCP_only-ff6b6b" alt="Hermes"></a> <a href="#openclaw"><img src="https://img.shields.io/badge/OpenClaw-auto_+_MCP-ffd166" alt="OpenClaw"></a> </p> | 工具 | 自动跟踪 | MCP 跟踪 | 最简单的设置 | |------|:----------:|:---------:|---------------| | Claude Code | ✅ | ✅ | `agpa init` 自动检测 | | Kilo Code | ✅ | ✅ | TS 插件 + MCP 配置 | | OpenCode | ✅ | ✅ | TS 插件 + MCP 配置 | | Hermes | — | ✅ | MCP JSON 配置 | | OpenClaw | ✅ | ✅ | 插件 + MCP 配置 | 除 Hermes（无 Hook API）外，所有五种工具都具有完整的双通道覆盖。对于任何 MCP 兼容的客户端（Cursor、VS Code、Windsurf 等），仅 MCP 跟踪开箱即用 — 您只会错过基于 Hook 的自动跟踪。 > [!TIP] > **MCP 新手？** 从 `agpa init` 开始 — 它会自动检测已安装的工具并配置所有内容。下面的手动 JSON 配置是备用方案。 <details> <summary><b>Claude Code</b> — 自动跟踪 + MCP（完整覆盖）</summary> `agpa init` 自动检测 Claude Code 并注册两个通道。手动设置： **MCP 配置** (`~/.claude/.mcp.json` 或项目根目录 `.mcp.json`)： ```json { "mcpServers": { "agpa": { "command": "npx", "args": ["tsx", "path/to/AgentPlayerAchievements/src/main.ts"] } } } ``` **Hook 注册** — `agpa init` 将 Hook 条目添加到您的 Claude Code 设置中。通过 `agpa verify` 验证。 </details> <details> <summary><b>Cursor / VS Code</b> — 仅 MCP</summary> 这些编辑器支持 MCP 但不公开 Hook API 以进行自动跟踪。您可以通过 MCP 获取工具调用跟踪。 **Cursor** (`.cursor/mcp.json`)： ```json { "mcpServers": { "agpa": { "command": "npx", "args": ["tsx", "path/to/AgentPlayerAchievements/src/main.ts"] } } } ``` **VS Code** (`.vscode/mcp.json`)： ```json { "mcpServers": { "agpa": { "command": "npx", "args": ["tsx", "path/to/AgentPlayerAchievements/src/main.ts"] } } } ``` </details> <details> <summary><b>Kilo Code / OpenCode</b> — 自动跟踪 + MCP（完整覆盖）</summary> 这些工具支持 TS 插件以进行 Hook 级自动跟踪。`agpa init` 注册插件 + MCP 配置。 **手动 MCP 配置** (`opencode.json` 或 Kilo Code 设置)： ```json { "mcpServers": { "agpa": { "command": "npx", "args": ["tsx", "path/to/AgentPlayerAchievements/src/main.ts"] } } } ``` TS 插件（由 `agpa init` 注册）自动处理 PostToolUse、SessionStart、SessionEnd 等 Hook 事件。 </details> <details> <summary><b>Hermes</b> — 仅 MCP</summary> Hermes 不公开 Hook API。基于 MCP 的跟踪涵盖工具调用和会话事件。 **MCP 配置** (`~/.hermes/mcp.json`)： ```json { "mcpServers": { "agpa": { "command": "npx", "args": ["tsx", "path/to/AgentPlayerAchievements/src/main.ts"] } } } ``` </details> <details> <summary><b>OpenClaw</b> — 自动跟踪 + MCP（完整覆盖）</summary> OpenClaw 支持插件系统以进行 Hook 级跟踪。`agpa init` 注册插件和 MCP 配置。 **手动 MCP 配置**： ```json { "mcpServers": { "agpa": { "command": "npx", "args": ["tsx", "path/to/AgentPlayerAchievements/src/main.ts"] } } } ``` </details> ## CLI 命令 | 命令 | 描述 | |---------|-------------| | `agpa init` | 自动检测并注册您的代理工具 | | `agpa uninstall` | 从所有已配置的工具中干净地删除 AGPA | | `agpa verify` | 检查安装正确性 | | `agpa doctor` | 诊断系统状态 | | `agpa dashboard` | 启动成就仪表盘（localhost:3867） | | `agpa stats` | 显示成就进度摘要 | | `agpa progress` | 列出所有成就及其解锁状态 | | `agpa profile` | 管理成就配置文件（创建、列出、切换、软件、删除） | | `agpa demo` | 为测试生成 MVP 演示数据 | | `agpa reset` | 重置所有跟踪数据 | | `agpa config` | 查看/修改配置（语言、声音、调试...） | | `agpa showcase` | 管理展示（列表、固定、取消固定、自动填充） | | `agpa search` | 按关键词/稀有度/类别搜索成就 | | `agpa suggest` | 建议下一个要狩猎的成就 | | `agpa sound` | 切换 8 位稀有度分级音效（开启、关闭） | | `agpa activity` | 查看连胜 + 4 个月的活动热图 | | `agpa export` | 将成就数据导出为 JSON | | `agpa import` | 从备份导入 | | `agpa mcp` | 启动 MCP 服务器（stdio 模式） | | `agpa web` | `agpa dashboard` 的别名 | | `agpa pack` | 列出或检查已安装的社区成就包 | | `agpa banner` | 切换终端横幅颜色主题（Neon/Arcade/Gold） | | `agpa history` | 浏览原始事件日志条目 | | `agpa explain` | 显示成就为何锁定/解锁（条件分解） | | `agpa watch` | 实时成就进度监视器 | | `agpa upgrade` | 检查更新并升级 AGPA | | `agpa completion` | 生成 shell 补全脚本（bash/zsh/fish） | > 完整的 CLI 参考资料：`agpa --help` ## 社区包 任何人都可以创建和分享成就包。将 YAML 文件放入 `~/.agent-achievements/packs/` 即可安装： ```bash agpa pack list # 列出已安装的包 agpa pack info <id> # 显示包详情 ``` 参见 [创建成就包](docs/creating-achievements.md)，了解包格式规范、事件类型目录和 12 种条件类型。 ## 仪表盘 <p align="center"> <em>统计行 → 连胜 + 热图 → 展示 → 成就网格，支持搜索/筛选</em> </p> ```bash agpa dashboard # 默认端口：3867 agpa dashboard 8080 # 自定义端口 agpa dashboard --profile work # 使用特定配置文件启动 ``` - **统计**: 经验值、等级、总成就、连胜、任务、工具使用 - **热图**: GitHub 风格的 4 个月活动网格 - **展示**: 已固定收藏的成就（最多 6 个） - **成就网格**: 支持搜索、按稀有度/类别排序、筛选已解锁/锁定 - **声音切换**: 8 位稀有度分级音效 - **分享按钮**: 生成精美的双语卡片 → PNG 下载 ## 架构 ``` ┌─────────────────────────┐ │ 引擎（src/engine/） │ │ track() / poll() │ └─────────────────────────┘ ↗ ↖ MCP 服务器 Hook CLI (src/main.ts) (src/cli/hook.ts) │ │ STDIO 长连接 短连接子进程 │ （stdin 管道） 代理有意识调用 Hook 触发 自主 自动跟踪 │ │ ┌─────┴─────┐ ┌──────┴──────┐ │ 手动 │ │ 自动跟踪 │ │ image.read │ │ tool.complete│ │ lang_used │ │ file.edit │ │ plan.mode │ │ session.* │ │ ... │ │ agent.spawn │ └───────────┘ └─────────────┘ ╲ ╱ event.log ← 两者写入此处 │ engine.poll() │ state.json │ 仪表盘 ``` ## 项目结构 ``` src/ ├── main.ts # MCP 服务器入口（STDIO） ├── tool-registry.ts # 集中式工具注册 ├── cli/ │ ├── index.ts # 统一 CLI 入口（27 个命令） │ ├── hook.ts # Hook CLI（跟踪 + 轮询 + 自动模式） │ ├── init.ts # 交互式安装向导 │ ├── dashboard.ts # 仪表盘启动器 │ ├── doctor.ts # 系统诊断 │ └── ... # 22 个其他 CLI 命令 ├── engine/ │ ├── engine.ts # 核心引擎（跟踪 / 轮询 / 统计） │ ├── evaluator.ts # 12 种条件类型评估器 │ ├── store.ts # JSONL 事件日志 + 状态持久化 │ ├── types.ts # TypeScript 接口 │ └── yaml-parser.ts # YAML 成就定义解析器 ├── dashboard/ │ ├── server.ts # HTTP 服务器 + API 路由 │ ├── api.ts # 卡片数据、统计数据聚合 │ ├── public/ # 零框架 HTML/CSS/JS 前端 │ └── customize-api.ts # 自定制端点 ├── tools/ # MCP 工具定义（7 种工具） ├── utils/ # 通知、验证、配置文件、像素艺术、电池等 ├── verify/ │ └── auditor.ts # 成就验证逻辑 ├── config.ts # 全局配置 └── helpers.ts # 共享实用程序 pixel-art-output/ # Logo 图片（README） achievement-definitions.yaml # 217 个成就定义（权威） scripts/ # 开发工具（Logo 生成、像素艺术生成、声音） ``` ## 🔒 安全与隐私 - **本地优先** — 所有事件数据都保留在 `~/.agent-achievements/` 中。无遥测，无云同步，运行时无需网络调用。 - **可审计** — 引擎是纯 TypeScript 函数，操作 JSONL 文件。无混淆，无二进制 blob。 - **最小依赖** — 5 个运行时依赖项 (`@modelcontextprotocol/sdk`, `yaml`, `zod`, `figlet`, `tsx`) — 全部经过广泛审计。 - **STDIO 隔离** — MCP 服务器仅通过标准输入/输出通信。无需暴露的 HTTP 端点。 - **Hook 沙盒** — Hook CLI 作为毫秒级子进程运行 — 它无法持久存储状态或访问网络。 - **供应链** — 无原生模块，无安装后脚本，无二进制下载。 要报告漏洞，请参阅 [SECURITY.md](SECURITY.md)。 ## 👥 贡献 我们欢迎贡献！无论是成就包、仪表盘改进、新工具集成还是引擎修复 — 都有适合每个技能水平的路径。 - **[CONTRIBUTING.md](CONTRIBUTING.md)** — 设置、编码约定、PR 流程和 4 种贡献路径 - **[创建成就包](docs/creating-achievements.md)** — 完整的成就定义编写指南 - **[`.github/ISSUE_TEMPLATE/`](.github/ISSUE_TEMPLATE/)** — 问题和 PR 模板 变量 | 变量名 | 描述 | 默认值 | 可选值 | |----------|-------------|---------|| `AGPA_PROFILE` |配置文件名称 | `default` | 任意字符串 | | `AGPA_LANG` | 界面语言 | `en` | `en`, `zh` | | `AGPA_ENABLED_CATEGORIES` | 筛选启用的成就类别 | 所有类别 | 以逗号分隔（例如 `onboarding,tool_mastery`） | | `AGPA_DEBUG` | 启用详细调试日志 | `false` | `true` | | `AGPA_SOUND` | 覆盖音效设置 | 配置文件设置 | `on`, `off`, `true`, `false` | | `AGPA_SIMPLE_ANIMATIONS` | 使用简化的终端动画 | `false` | `true` | | `AGPA_BANNER_THEME` | CLI 启动横幅样式 | `Arcade` | `Neon`, `Arcade`, `Gold` | | `AGPA_TELEMETRY` | 启用匿名使用情况统计 |` | `truefalse` | | `AGPA_TELEMETRY_SERVER` | 自定义统计端点 URL | `（无） | URL 字符串 | | `AGPA_TOOL_SOURCE` | 覆盖工具源标识符 | 自动检测 | `claude-code`, `hermes`, `openclaw` 等 | | `AGPA_MODEL` | 当前 AI 模型名称（用于成就） | `auto` | 任意模型字符串 | > [!TIP] > 环境变量会覆盖 `config.json` 设置。在 shell 配置文件或代理配置中设置它们以进行持久覆盖。 ## 常见问题 **问：这会减慢我的代理速度吗？** 答：不会。Hook CLI 是一个毫秒级的子进程。MCP 服务器在 STDIO 上运行，无网络开销。 **问：我可以将其与其他代理一起使用吗？** 答：可以。初始化向导会自动检测 Claude Code、Kilo Code、OpenCode、Hermes 和 OpenClaw。每个代理都可以有自己的配置文件。 **问：我的成就无法解锁？** 答：运行 `agpa doctor` — 它会诊断跟踪状态、钩子注册和事件覆盖。 **问：这与 WakaTime 或编码活动跟踪器有什么不同？** 答：WakaTime 告诉你 *做了什么* — 小时、语言、项目。AGPA 让它 *更有趣* — 经验值、等级、成就、连胜和 Steam 风格的成就感。它是在现有工作流上添加的游戏化，而不是另一个要查看的仪表盘。将其视为健身跟踪器的原始步数与 Pokémon Go 徽章之间的区别 — 相同的数据，不同的体验。 **问：我可以自定义成就名称吗？** 答：可以。仪表盘中的 `/customize` 页面允许您重命名任何成就。 ## 故障排除 > [!IMPORTANT] > **任何问题的第一步：** 运行 `agpa doctor` — 它一次性诊断跟踪状态、钩子注册、事件覆盖和配置问题。 | 症状 | 可能原因 | 解决方法 | |---------|-------------|-----| | 成就无法解锁 | Hook/MCP 未注册 | 运行 `agpa doctor` 检查钩子注册 + 事件覆盖 | | 仪表盘无法启动 | 端口 3867 已被占用 | `agpa dashboard 8080`（或其他空闲端口） | | `agpa init` 失败 | 代理工具未 检查支持的工具列表；使用手动 MCP JSON 配置作为备用 | | 没有 macOS 通知 | `terminal-notifier` 丢失 | 运行 `brew install terminal-notifier`，或 `agpa init` 自动安装它 | | 没有声音 | 音频上下文被浏览器阻止 | 在仪表盘页面上点击任意位置以启用音频 | | 配置文件切换不工作 | 配置文件不存在 | `agpa profile list` 查看可用配置文件，然后 `agpa profile switch <name>` | | Hook CLI 错误在代理日志中 | 标准输入管道为空（第一次运行预期） | 正常 — 钩子是短寿命的子进程；错误记录到 `~/.agent-achievements/error.log` | 对于持续存在的问题，请检查 `~/.agentievements/error.log` 或 [打开问题](https://github.com/eiainano/AgentPlayerAchievements/issues)。 ## 星级历史 <img alt="星级历史图表" src="https://api.com/svg?repos=eiainano%2Fagentplayerachievements&type=Date" width="100%"> ## 许可证 MIT — 请参阅 [LICENSE](LICENSE)