Agent Player Achievements (AGPA) 🏆

仪表盘预览

没有 AGPA ❌

• 看不见你的编码习惯，跨会话无法追溯
• 无法追踪进步——变快了？用了更多工具？无从得知
• 没有动力去探索 Agent 的全部功能
• 每天重复——没有惊喜，没有里程碑

有了 AGPA ✅

• 自动追踪——每次工具调用、文件编辑、Git 提交都被自动记录
• Steam 风格仪表盘——经验条、等级、连胜、热力图、成就展柜
• 217 个成就，覆盖 11 个类别——从「Hello World」到「完美主义者」
• 即时反馈——终端弹窗、macOS 通知、8-bit 音效

快速开始

前提条件： Node.js ≥ 18

# 方案 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

就这样。继续使用你的 Agent——成就会随着你的工作自动解锁。

[!TIP] 想立刻看看仪表盘长什么样？运行 agpa demo 即可生成演示数据。

agpa dashboard         # 打开成就仪表盘
agpa stats             # 查看进度
agpa assets download   # （可选）预下载全部 219 张 pixel-art 徽章

工作原理

你的编码会话
  │
  ├─ 你写代码，Agent 响应——每个动作都被追踪
  │   └─ 双通道：MCP 工具 + Hook 事件
  │
  ├─ 会话结束 → 引擎评估 217 个成就
  │   └─ 解锁了？→ macOS 通知 🎉
  │
  └─ agpa dashboard → 查看、排序、筛选、分享

两个数据通道 → 一个引擎 → 一个仪表盘：

| 通道 | 方式 | 捕获内容 | |---------|--------|----------| | Hook CLI | 工具钩子（通过 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 |

两个通道都写入同一个 ~/.agent-achievements/ 事件日志。引擎用 12 种条件类型评估 217 个成就。

[!NOTE] 零开销。 Hook CLI 是亚毫秒级的子进程。MCP 服务器在 STDIO 上运行，无网络调用。所有数据留在你的机器上。

功能特性

• 🎮 成就仪表盘 — 经验条、等级、连胜、活动热力图、稀有度分布、展柜
• 🏆 217 个成就，覆盖 11 个类别 — 从「Hello World」到「完美主义者」
• 🔥 GitHub 风格活动热力图 — 4 个月的编码活动一览无余
• 📸 分享卡片 — 暗色/亮色主题，双语，可下载 PNG
• 🔊 8-bit 音效与通知 — 按稀有度分级的复古音效 + 解锁时桌面推送通知
• 📂 多配置文件 — 最多 4 个配置，随时切换（工作、个人、实验）

支持的工具

| 工具 | 自动追踪 | 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 配置是备选方案。

agpa init 会自动检测 Claude Code 并注册两个通道。手动配置：

MCP 配置 (~/.claude/.mcp.json 或项目根目录的 .mcp.json)：

{
  "mcpServers": {
    "agpa": {
      "command": "npx",
      "args": ["-y", "@eiainano/agpa", "agpa-mcp"]
    }
  }
}

Hook 注册 — agpa init 会将 Hook 条目添加到你的 Claude Code 设置中。用 agpa verify 验证。

这些编辑器支持 MCP，但没有暴露 Hook API 用于自动追踪。你可以通过 MCP 获得工具调用追踪。

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "agpa": {
      "command": "npx",
      "args": ["-y", "@eiainano/agpa", "agpa-mcp"]
    }
  }
}

VS Code (.vscode/mcp.json):

{
  "mcpServers": {
    "agpa": {
      "command": "npx",
      "args": ["-y", "@eiainano/agpa", "agpa-mcp"]
    }
  }
}

这些工具支持 TS 插件进行 Hook 级别的自动追踪。agpa init 会注册插件 + MCP 配置。

手动 MCP 配置 (opencode.json 或 Kilo Code 设置)：

{
  "mcpServers": {
    "agpa": {
      "command": "npx",
      "args": ["-y", "@eiainano/agpa", "agpa-mcp"]
    }
  }
}

TS 插件（由 agpa init 注册）会自动处理 PostToolUse、SessionStart、SessionEnd 和其他 Hook 事件。

Hermes 没有暴露 Hook API。基于 MCP 的追踪覆盖工具调用和会话事件。

MCP 配置 (~/.hermes/mcp.json):

{
  "mcpServers": {
    "agpa": {
      "command": "npx",
      "args": ["-y", "@eiainano/agpa", "agpa-mcp"]
    }
  }
}

OpenClaw 支持插件系统进行 Hook 级别的追踪。agpa init 会注册插件和 MCP 配置。

手动 MCP 配置：

{
  "mcpServers": {
    "agpa": {
      "command": "npx",
      "args": ["-y", "@eiainano/agpa", "agpa-mcp"]
    }
  }
}

CLI 命令

| 命令 | 描述 | |---------|-------------| | agpa init | 自动检测并注册到你的 Agent 工具 | | 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-bit 稀有度分级音效 (on, off) | | agpa activity | 查看连胜 + 4 个月活动热力图 | | agpa export | 导出成就数据为 JSON | | agpa import | 从备份导入 | | agpa mcp | 启动 MCP 服务器（stdio 模式） | | agpa web | agpa dashboard 的别名 | | agpa pack | 列出或查看已安装的社区成就包 | | agpa banner | 切换终端 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/ 即可安装：

agpa pack list              # 列出已安装的包
agpa pack info <id>         # 查看包详情

参见创建成就包指南，了解包格式规范、事件类型目录和 12 种条件类型。

仪表盘

agpa dashboard           # 默认 :3867
agpa dashboard 8080      # 自定义端口
agpa dashboard --profile work   # 使用特定配置启动

• 统计：XP、等级、总成就数、连胜、任务数、工具使用次数
• 热力图：GitHub 风格的 4 个月活动网格
• 展柜：固定的最爱成就（最多 6 个）
• 成就网格：搜索、按稀有度/类别排序、筛选已解锁/未解锁
• 音效开关：8-bit 稀有度分级效果
• 分享按钮：生成精美的双语卡片 → PNG 下载

架构

                    ┌─────────────────────────┐
                    │   引擎 (src/engine/)     │
                    │   track() / poll()      │
                    └─────────────────────────┘
                      ↗                    ↖
            MCP Server               Hook CLI
          (src/main.ts)           (src/cli/hook.ts)
                │                        │
          STDIO 长连接            短生命周期子进程
                │                  (stdin pipe)
                │                        │
          Agent 主动调用          Hook 自动触发
          有意识的行为              Agent 无感知
                │                        │
          ┌─────┴─────┐          ┌──────┴──────┐
          │ 手动追踪   │          │ 自动追踪    │
          │ image.read │          │ tool.complete│
          │ lang_used  │          │ file.edit   │
          │ plan.mode  │          │ session.*   │
          │ ...        │          │ agent.spawn │
          └───────────┘          └─────────────┘
                    ╲            ╱
                event.log  ← 两个通道都在此写入
                          │
                     engine.poll()
                          │
                     state.json
                          │
                     仪表盘

项目结构

src/
├── main.ts                  # MCP Server 入口 (STDIO)
├── tool-registry.ts         # 中心工具注册
├── cli/
│   ├── index.ts             # 统一 CLI 入口（27 个命令）
│   ├── hook.ts              # Hook CLI (track + poll + auto 模式)
│   ├── init.ts              # 交互式安装向导
│   ├── dashboard.ts         # 仪表盘启动器
│   ├── doctor.ts            # 系统诊断
│   └── ...                  # 22 个 CLI 命令
├── engine/
│   ├── engine.ts            # 核心引擎 (track / poll / stats)
│   ├── 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     # 自定义 API 端点
├── tools/                   # MCP 工具定义 (8 个工具)
├── utils/                   # 通知、验证、配置、像素画、电池等
├── verify/
│   └── auditor.ts           # 成就验证逻辑
├── config.ts                # 全局配置
└── helpers.ts               # 共享工具函数

pixel-art-output/            # Logo 图片 (README 用)
achievement-definitions.yaml   # 217 个成就定义（权威数据源）
scripts/                     # 开发工具（Logo 生成、像素画生成、音效）

🔒 安全与隐私

• 本地优先 — 所有事件数据保存在 ~/.agent-achievements/。无遥测、无云同步、运行时无网络调用。
• 可审计 — 引擎是操作 JSONL 文件的纯 TypeScript 函数。无混淆、无二进制文件。
• 依赖精简 — 5 个运行时依赖 (@modelcontextprotocol/sdk, yaml, zod, figlet) — 全部经过广泛审计。
• STDIO 隔离 — MCP 服务器仅通过标准 I/O 通信。不暴露 HTTP 端点。
• Hook 沙箱 — Hook CLI 以亚毫秒级子进程运行 — 无法持久化状态或访问网络。
• 供应链安全 — 无原生模块、无 postinstall 脚本、安装时不下载任何二进制文件。

如需报告安全漏洞，请参阅 SECURITY.md。

👥 参与贡献

欢迎贡献！无论是成就包、Dashboard 改进、新工具接入，还是引擎修复——每个技能水平都有参与路径。

• CONTRIBUTING.md — 环境配置、编码规范、PR 流程与 4 条参与路径
• 创建成就包 — 编写成就定义的完整指南
• .github/ISSUE_TEMPLATE/ — Issue 与 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 | 启用匿名使用遥测 | false | true, false | | AGPA_TELEMETRY_SERVER | 自定义遥测端点 URL | '' (无) | URL 字符串 | | AGPA_TOOL_SOURCE | 覆盖工具来源标识 | 自动检测 | claude-code, hermes, openclaw 等 | | AGPA_MODEL | 当前 AI 模型名称（用于成就判定） | auto | 任意模型字符串 |

[!TIP] 环境变量会覆盖 config.json 的设置。在 Shell 配置或 Agent 配置中设置它们以持久化覆盖。

常见问题

Q: 这会让我的 Agent 变慢吗？ A: 不会。Hook CLI 是亚毫秒级的子进程。MCP 服务器在 STDIO 上运行，零网络开销。

Q: 我可以配合多个 Agent 使用吗？ A: 可以。安装向导会自动检测 Claude Code、Kilo Code、OpenCode、Hermes 和 OpenClaw。每个 Agent 可以有独立的配置。

Q: 我的成就没有解锁？ A: 运行 agpa doctor——它会诊断追踪状态、Hook 注册情况和事件覆盖。

Q: 这和 WakaTime 或其他编码活动追踪器有什么区别？ A: WakaTime 告诉你做了什么——时长、语言、项目。AGPA 让它变得有趣——经验值、等级、成就、连胜，以及 Steam 风格的多巴胺刺激。它是在你现有工作流之上的游戏化层，而不是另一个需要查看的仪表盘。就像健身追踪器的原始步数和 Pokémon Go 徽章的区别——同样的数据，不同的体验。

Q: 我可以自定义成就名称吗？ A: 可以。仪表盘中的 /customize 页面允许你重命名任何成就。

故障排除

[!IMPORTANT] 遇到任何问题第一步： 运行 agpa doctor——它能一次性诊断追踪状态、Hook 注册、事件覆盖和配置问题。

| 症状 | 可能原因 | 解决方法 | |---------|-------------|-----| | 成就无法解锁 | Hook/MCP 未注册 | 运行 agpa doctor 检查 Hook 注册 + 事件覆盖 | | 仪表盘无法启动 | 端口 3867 被占用 | agpa dashboard 8080（或任何空闲端口） | | agpa init 失败 | Agent 工具未检测到 | 检查支持的工具列表；使用手动 MCP JSON 配置作为备选 | | 没有 macOS 通知 | terminal-notifier 缺失 | 运行 brew install terminal-notifier，或 agpa init 会自动安装 | | 音效不播放 | 浏览器音频上下文被阻止 | 在仪表盘页面任意位置点击以启用音频 | | 配置切换不工作 | 配置不存在 | agpa profile list 查看可用配置，然后 agpa profile switch <name> | | Agent 日志中有 Hook CLI 错误 | stdin pipe 为空（首次运行正常） | 正常——Hook 是短生命周期子进程；错误记录在 ~/.agent-achievements/error.log |

持续性问题请检查 ~/.agent-achievements/error.log 或提交 Issue。

Star 历史

许可

MIT — 详见 LICENSE