用途
Token Card 用于生成一张 SVG 卡片，汇总本机 AI 编程代理的使用情况，包括总 token 数、等效 API 成本、当前连续使用天数，以及各代理之间的用量分布。生成的卡片会作为文件写入工作区，供 README 或文档页面引用。
卡片是提交到仓库的产物，而不是托管图片，因此它从仓库本身渲染，不依赖第三方端点持续在线。
何时启用
- 有人希望在 README 或文档页面中展示使用数据。
- 有人要求提供跨工具的代理活动可分享摘要。
如果问题是“我这周花了多少”，应改用 /cost-report。两者读取不同来源并产生不同结果：
| /cost-report | Token Card | |
|---|---|---|
| 来源 | ~/.claude/metrics/costs.jsonl，由 ECC 的 stop:cost-tracker 钩子写入 | 各代理自身的会话日志 |
| 代理 | Claude Code | Claude Code、Codex、Gemini CLI、OpenCode |
| 输出 | 终端摘要，可选 CSV | 提交到仓库的 SVG 文件 |
底层工具
本技能运行的工具是 @tokenchit/cli，MIT 许可：https://github.com/iyashjayesh/tokenchit
它被有意固定到精确版本。@latest 会解析为注册表当前提供的任意版本，而该工具会读取本地会话日志——因此未来某个被篡改的版本可能在任何人审查之前就被执行并访问这些日志。应固定版本，并有意识地提升固定版本：
TOKENCHIT_VERSION=0.10.0
首次运行前检查固定产物：
npm view @tokenchit/cli@0.10.0 dist.integrity dist.tarball
工作流程
1. 首次下载前先询问
npx 会从 npm 注册表获取包并执行它。这是对代码的远程下载，且该代码将读取本地日志，因此在某台机器上首次运行前必须获得用户的明确确认。如果用户拒绝，就此停止，并说明原本会运行什么。
2. 配置（除非是 dry run）
如果 .tokenchit.json 不存在，运行：
npx -y @tokenchit/cli@0.10.0 init
它会检测本机上哪些代理有日志并记录下来。该文件应被提交，且绝不包含凭据。
当用户传入 --dry-run 时完全跳过此步，并报告将创建 .tokenchit.json。会写入配置文件的预览不是预览。
3. 渲染卡片
裸命令会写入配置的输出——除非 .tokenchit.json 指定了其他路径，否则为 tokenchit.svg：
npx -y @tokenchit/cli@0.10.0 sync
只追加用户实际要求的标志，每个标志严格按下方拼写。不要把占位符复制进命令——sync 会忽略无法识别的位置参数而不是拒绝它，因此带方括号的 [--dry-run] 会作为垃圾参数传给 CLI，卡片仍会被写入，这与要求相反。
| 标志 | 效果 |
|---|---|
| --out <path> | 写入配置输出以外的位置 |
| --theme auto | light | dark | 卡片主题；auto 会适配读者的系统 |
| --dry-run | 打印将写入的内容，不触碰任何文件 |
sync 读取本地文件且不发送任何内容：没有提示、没有代码、没有文件内容离开本机，也不向任何服务器传输。围绕它的 npx 调用是一次注册表下载——这是本工作流中的网络访问，第 1 步就是对此达成一致的地方。
4. 报告并提供建议
打印它产生的数据——token、等效成本、连续天数、各代理分布——以及写入的路径。如果仓库的 README 尚未引用该卡片，可提议添加：
sync 打印的是相对于仓库根目录的路径。Markdown 图片相对于其所在文件解析，因此要为正在编辑的 README 重写路径：位于 docs/usage.svg 的卡片从根 README 看是 ./docs/usage.svg，但从 docs/zh-CN/README.md 看是 ../usage.svg。把打印的路径粘贴到嵌套 README 会指向 docs/zh-CN/docs/usage.svg 并渲染失败。
未经要求不要编辑 README。
第 4 步后停止。发布到公共排行榜是单独的 publish 命令，需要明确选择加入，不属于本工作流——仅在用户点名要求时运行。unpublish 会再次移除该行和账户。
输出
SVG 的路径、其中包含的数据，以及用于引用它的 markdown 片段。在 dry run 时：将写入的内容，磁盘上没有任何更改。
说明
- 需要 Node.js 22 或更高版本（包声明 engines: { node: ">=22" }）。不进行全局安装；npx 每次运行都会获取固定版本。
- 仅读取 token 计数和时间戳。