Metadata-Version: 2.4
Name: tokenmetre
Version: 0.2.0
Summary: Local-first token usage collector for AI coding agents (Claude Code): passive transcript scan, per-project stats, optional cloud sync
Author: bsawang
Project-URL: Homepage, https://github.com/bsawang/tokenMetreCom
Project-URL: Repository, https://github.com/bsawang/tokenMetreCom
Keywords: token,usage,claude-code,ai,metrics,cost
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn>=0.29
Requires-Dist: pydantic>=2.6
Requires-Dist: pyjwt>=2.8
Requires-Dist: psycopg[binary,pool]>=3.1
Requires-Dist: alembic>=1.13
Requires-Dist: python-dotenv>=1.0
Provides-Extra: trae
Requires-Dist: pycryptodome>=3.20; extra == "trae"
Provides-Extra: all
Requires-Dist: tokenmetre[trae]; extra == "all"

# 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`。

---

## 本地端安装

```bash
pip install tokenmetre
tokenmetre install claude-code --verify
```

- `pip install` 把 CLI 装进系统
- `tokenmetre install claude-code` 做数据侧部署:幂等写 `~/.claude/settings.json` 的 cleanupPeriodDays + 软链 skill/command markdown
- 运行时数据落在 `~/.tokenmetre/`(SQLite / 配置缓存)

验证: `tokenmetre install claude-code --verify`

## 使用流程

```bash
# 1. 登记要计量的项目
tokenmetre register add E:\work\ai\some-project
tokenmetre register add E:\work\ai\another-project

# 2. 扫描（register add 已自动 scan；定期手动补扫）
tokenmetre scan

# 3. 看 Web 面板
tokenmetre web                    # http://127.0.0.1:8080

# 4. 或 CLI 报表
tokenmetre report --all
```

## 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）。想长期保留就设大数字，无哨兵值。

---

## 云端部署（运维侧）

### 本地启动

```powershell
# 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（生产）

```powershell
# 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 配置。

### 前端构建

```powershell
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:

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

---

## 配套文档

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