🌱 Token 小精灵 / Token Sprite

你写下的每个 Token，都在让它长大。
Every token you write helps it grow.

把真实的 AI 编程用量变成一只住在桌面角落、一路破壳进化的小精灵。
Turn your real AI-coding usage into a tiny desktop companion that hatches, evolves, and grows with you.

CODE → HATCH → EVOLVE → COLLECT

写代码获得真实 Token → 达成成就抽精灵蛋 → 五段进化 → 收进图鉴。
Write code, earn real tokens, hatch mystery eggs, evolve through five stages, and complete your collection.

macOS · Windows · Linux · 本地读取 / Local-only · 不上传 / Nothing uploaded

🥚 孵化与进化 / Hatch & Evolve

选一颗蛋，它会吸收你真实使用掉的 Token，从破壳一路成长到最终化形。
Choose an egg and feed it with the tokens you actually use, from first crack to final form.

六种属性、六条完整进化线：草木、海洋、岩浆、雷电、机械与冰晶。破壳前，你永远不知道会遇见谁。
Six elements, six complete evolution lines: flora, ocean, magma, thunder, mech, and ice. You will not know who is inside until the egg hatches.

抽到重复的同类蛋？在孵化器里一键合并——喂养进度全累加，还按稀有度额外送 token，加速孵一只喜欢的。
Got duplicate eggs of the same species? Merge them in the incubator—progress stacks and you earn bonus tokens by rarity, fast-tracking a favorite.

✨ 为什么特别 / Why It’s Different

• 真实劳动养出来 / Powered by real work：读取本地 AI 编程工具的真实 Token 用量，写多少就长多少。 / It grows from your actual local AI-coding usage.
• 会陪你 / A companion, not a counter：连续工作会劝你休息，深夜会提醒早点睡，久别重逢会向你招手。 / It nudges you to rest, sleep, and come back without turning work into pressure.
• 桌面常驻 / Always on your desktop：悬浮置顶、自由拖动，也能缩成侧边探头。 / Always on top, draggable, and able to peek quietly from the screen edge.
• 孵化收集 / Hatch and collect：成就 → 抽蛋 → 进化 → 图鉴，让每次写代码都有期待。 / Achievements unlock eggs; eggs evolve into creatures for your collection.
• 全本地私密 / Private by design：只读本机日志，用量绝不上传；仅正式版会向 GitHub 查询有无新版本。 / Usage stays on your machine and is never uploaded; only released builds check GitHub for new versions.

🏆 成就与抽蛋 / Achievements & Hatching

达成成就获得抽蛋券；每张券大概率开出对应稀有度，并有 15% 概率提升一档。新手期门槛低、发券快，前几天就能集齐前 4 只、挑一只重点养。
Complete achievements to earn egg tickets. Each ticket usually matches its rarity, with a 15% chance to upgrade by one tier. Early achievements are quick, so you can collect the first few species in days and pick a favorite.

抽到的是一颗蛋。放进孵化器继续写代码，完成五段进化才会正式收进图鉴。
Every draw gives you an egg. Keep coding to complete all five stages and add its final form to your collection.

数值可在 src/config/achievements.js 与 src/config/rarities.js 调整。
Balance values live in src/config/achievements.js and src/config/rarities.js.

🖥️ 界面一览 / A Look Inside

全本地、免登录，一个悬浮小窗搞定：改名、抽卡、孵化、图鉴、成就。
Fully local, no login — one floating window: rename, draw, hatch, collect, and earn achievements.

🚀 快速开始 / Quick Start

需要 Node.js 20+，支持 macOS、Windows 与 Linux。
Requires Node.js 20+ and runs on macOS, Windows, and Linux.

macOS 普通用户安装 / Install on macOS

普通用户请从 GitHub Releases 下载最新的 .dmg，打开后把 Token 小精灵拖进“应用程序”。若未签名，首次打开右键点图标选“打开”通过一次系统提示即可。源码方式主要面向开发者。
Download the latest .dmg from GitHub Releases and drag Token Sprite into Applications. If it is unsigned, right-click the app and choose “Open” once to pass Gatekeeper. The source workflow below is mainly for developers.

有新版时，正式版会弹窗提醒；菜单栏的小精灵图标 → 检查更新 也会打开下载页，下载新版 .dmg 覆盖安装即可，成长数据保留。
When a new version is available, released builds show a reminder. The menu-bar icon → Check for Updates opens the download page; grab the new .dmg and reinstall over the old one—your growth data is kept.

如果小精灵不在桌面上，点击菜单栏的小精灵图标 → 召回小精灵。显示器拔插、分辨率变化或睡眠恢复后，如果窗口完全跑出屏幕，应用也会自动把它带回来。
If your sprite disappears, choose Recall Sprite from its menu-bar icon. It also returns automatically after display changes or wake when its window is fully off-screen.

从源码运行 / Run from source

git clone https://github.com/shiyubao78/token-sprite.git
cd token-sprite
npm install
npm start

启动后，小精灵会出现在桌面右下角。
Once started, your sprite appears in the bottom-right corner of the desktop.

🤖 一句话让 Agent 帮你装 / Let Your Agent Install It

把下面这句话直接发给 Codex、Claude Code 或其他能操作终端的 Agent：
Send this directly to Codex, Claude Code, or any terminal-capable agent:

帮我安装并运行 github.com/shiyubao78/token-sprite
Install and run github.com/shiyubao78/token-sprite for me.

仓库内置 AGENTS.md 与 CLAUDE.md，Agent 可以自动完成克隆、安装与启动。
The repository includes AGENTS.md and CLAUDE.md, so an agent can clone, install, and launch it for you.

🔄 一句话让 Agent 帮你更新 / Let Your Agent Update It

想升级到最新版，同样发一句话给 Agent 即可，成长数据会保留：
To upgrade to the latest version, just send your agent one line—your growth data is kept:

帮我把 token-sprite 更新到最新版
Update token-sprite to the latest version for me.

源码方式安装的，Agent 会 git pull 最新代码并重装启动；下载安装版的，Agent 会取最新 Release 覆盖旧版。
For source installs the agent runs git pull and reinstalls; for downloaded builds it fetches the latest release and replaces the old app.

🧩 工作原理 / How It Works

应用会自动检测本机支持的 AI 工具，读取本地日志中的 Token 用量。没安装的工具会自动跳过，数据不会离开你的电脑。
The app detects supported AI tools and reads token usage from local logs. Missing tools are skipped automatically, and your data never leaves your computer.

安装时会记录基准，此后从 0 开始养；你新使用多少 Token，它就成长多少。
A baseline is recorded on installation. Only new usage counts toward your sprite’s growth.

只能统计在本地保存可解析用量日志的工具。服务端用量无法从本机读取。
Only tools that store parseable usage logs locally can be counted. Cloud-only usage is not accessible.

添加其他工具 / Add Another Tool

如果 Gemini CLI、OpenCode、Aider 等工具会把用量写进本地日志，可以在 scripts/usage.mjs 的 READERS 中增加读取器：

async function readYourTool() {
  const root = join(homedir(), '.yourtool');
  if (!(await exists(root))) return null;
  let total = 0, recentTokens = 0, todayTokens = 0, lastActivityAt = 0;
  // 遍历本地日志并累加用量 / Parse local logs and accumulate usage.
  return { total, recentTokens, todayTokens, lastActivityAt };
}

export const READERS = [
  /* existing readers */
  { source: 'yourtool', label: 'Your Tool', read: readYourTool },
];

也可以直接让你的 Agent 完成：
You can also ask your agent to do it:

查看我本地 <工具> 的用量日志格式，为 token-sprite 添加读取器。
Inspect my local <tool> usage logs and add a reader to token-sprite.

📦 打包桌面应用 / Package the Desktop App

在目标系统上运行对应命令，产物会写入 release/：
Run the matching command on the target operating system. Builds are written to release/.

npm run pack         # macOS universal app
npm run pack:mac:release # macOS universal DMG + ZIP + update metadata
npm run pack:win     # Windows portable app + installer
npm run pack:linux   # Linux AppImage

• macOS 本地构建：没有 Developer ID 凭证时仍是未签名版本，首次运行可能需要右键选择“打开”。正式 Release 必须经过签名和 Apple 公证。
• Windows：SmartScreen 拦截时选择“更多信息 → 仍要运行”。
• Linux：先为 AppImage 添加执行权限；透明和置顶效果取决于桌面环境。
• Packaging must run on its target OS. GitHub Actions can also build all three platforms.

🔧 自定义 / Customize

• 品种、稀有度、名称、图片路径 / Species, rarity, names, and artwork: src/config/species.js
• 成就、门槛、抽卡概率 / Achievements, thresholds, and odds: src/config/achievements.js, src/config/rarities.js
• 自定义形象 / Custom artwork: assets/sprite/<species>/1-seed.png … 5-adult.png

每个阶段使用 512×512 透明 PNG。
Each stage uses a 512×512 transparent PNG.

📄 License

非商业授权 / Noncommercial. 本项目禁止商业使用。

• 源代码 / Source code: PolyForm Noncommercial 1.0.0
• 美术素材 / Art assets（assets/**）: CC BY-NC 4.0

可自由用于个人、学习、非营利用途；使用素材需署名。内置形象为 AI 生成，仅作示例，可自行替换。
Free for personal, educational, and nonprofit use; assets require attribution. Built-in artwork is AI-generated as an example and can be replaced.