tokenMetre

AI 时代的开发工作量计量器。把 LLM 消耗的 token 作为衡量开发工作量的参考指标。

参考值,非权威计价标准。零 hook、纯 transcript 采集、按项目统计、可选云端协作。

它做什么

1. 注册项目: tokenmetre register add <cwd> 登记目录
2. 扫描 transcript: tokenmetre scan 纯文件读取 ~/.claude/projects/**/*.jsonl
3. 确定性分类: 同 token 合并成 LLM 调用组 → 工具→5 类映射
4. 落盘 SQLite: 14 字段 Record,UNIQUE(session_id, ts) 天然去重
5. Web 面板: tokenmetre web 启动瘦统计面板
6. 可选云端协作: 注册后可连 tokenmetre.umap.earth 多成员汇聚

线上入口

https://tokenmetre.umap.earth — 营销站 / · 用户工作台 /app · 运维后台 /admin。

---

本地端安装

pip install tokenmetre
tokenmetre install claude-code --verify

• pip install 把 CLI 装进系统（PyPI: tokenmetre）
• tokenmetre install claude-code 做数据侧部署：幂等写 ~/.claude/settings.json 的 cleanupPeriodDays
• 运行时数据落在 ~/.tokenmetre/（SQLite + 配置缓存）

快速上手：Web 管理面板

# 登记项目（同时自动 scan 一次）
tokenmetre register add E:\work\ai\your-project

# 启动本地管理面板
tokenmetre web          # 默认 http://127.0.0.1:8080

浏览器打开面板，看到的就是你的全部 AI 工具消耗数据：

面板提供项目统计、Token 用量、权重配置、Agent 管理和云端协作入口——日常使用的主界面。

CLI 辅助命令

面板之外，偶尔需要快速查数或脚本集成时可以用 CLI：

tokenmetre report --all                   # 全局摘要
tokenmetre report --project myprj         # 单项目明细
tokenmetre scan --force                   # 强制重扫 transcript

CLI 命令速查

命令	作用
install claude-code [--verify]	安装/验证 CC adapter
register add <cwd>	登记激活目录（自动 scan）
register remove <cwd>	取消登记
register list	查看已登记项目
register claim <cwd> --id <tm_xxx>	显式认领（目录搬家后归位）
scan [--force] [--project <cwd>]	扫描 transcript → SQLite
report [--all] [--project <slug>]	CLI 统计摘要
web [--port]	启动本地 Web 面板
cloud add [cwd] --base <url> --token <token>	启用某项目云端协作
cloud show / cloud remove	查看/关闭 cloud 配置
sync [--project <slug>]	push 本地 pending records 到云端
config sync [--base <url>]	拉取云端全局配置

分类规则

5 类确定性映射（采集端不调 LLM），优先级: documentation > coding > execution > exploration > discussion

category	含义
文档 documentation	写 markdown 文件
编码 coding	写/改代码文件
实施 execution	跑命令: 安装/构建/执行/文件操作
调研 exploration	读文件/搜索/查 git/上网
讨论 discussion	纯对话交互

详细判定规则见 docs/spec.md §I.3。

数据位置

路径	用途
~/.tokenmetre/tokenmetre.db	SQLite 主库 — records + processed_sessions
~/.tokenmetre/projects.json	项目注册表（active/ignored/claims）
~/.tokenmetre/config.json	云端全局配置缓存（config sync 拉取）
~/.tokenmetre/weights.yaml	provider 计价比重（无云端缓存时回退用）

数据安全

Claude Code 默认 30 天清理 transcript。install 自动确保 cleanupPeriodDays ≥ 1（默认 365）。想长期保留就设大数字，无哨兵值。

---

云端部署（运维侧）

本地启动

# 1. 配置 .env（参考 .env.example）:
#    DATABASE_URL / TMCOM_API_TOKEN / TMCOM_JWT_SECRET / TMCOM_ADMIN_PASSWORD
# 2. 安装依赖
pip install -e .
# 3. 从项目根启动（不能 cd api/）
python -m api.server --port 9000

首次启动自动: Alembic 迁移建表 + 种子 admin。

Vercel + Supabase（生产）

# schema 变更后本地直连线上库执行迁移
python -c "from api import db; db.init()"

# 部署（CLI 直推，GitHub 自动部署已断开）
vercel deploy --prod --yes

环境变量（Vercel Dashboard）: DATABASE_URL（Supabase pooler :6543） / TMCOM_API_TOKEN / TMCOM_JWT_SECRET / TMCOM_ADMIN_PASSWORD / TMCOM_OPEN_REGISTER（默认关） / 可选邮件 OAuth 配置。

前端构建

cd api/web/site;  npm install; npm run build   # 营销站
cd ../user;       npm install; npm run build   # 用户工作台
cd ../admin;      npm install; npm run build   # 运维后台

数据库

PostgreSQL（Supabase 免费档）。连接串用 pooler :6543 transaction mode；密码含特殊字符需 percent-encode。

---

机器端接入

用户登录 /app/projects → 引导卡复制自己的 token:

tokenmetre cloud add --base https://tokenmetre.umap.earth --token tm_xxxx
tokenmetre sync

---

配套文档

• docs/spec.md — 规约全文（Record/分类/公式 + 云端服务规约 + F 编号）
• docs/api-contract.md — 接口契约（本地端 + 机器端 API + 云端内部）
• docs/architecture.md — 整体架构 + pip 打包边界
• docs/README.md — 开发文档（目录结构 + 踩坑备忘）
• docs/ROADMAP.md — 进度表（Phase 分组 + F 编号贯穿，唯一权威源）