tokenmetre 0.2.0__tar.gz

tokenmetre-0.2.0/PKG-INFO

@@ -0,0 +1,189 @@
+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 编号贯穿，唯一权威源）

tokenmetre-0.2.0/README.md

@@ -0,0 +1,156 @@
+# 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 编号贯穿，唯一权威源）

tokenmetre-0.2.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tokenmetre"
+version = "0.2.0"
+description = "Local-first token usage collector for AI coding agents (Claude Code): passive transcript scan, per-project stats, optional cloud sync"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "bsawang" }]
+keywords = ["token", "usage", "claude-code", "ai", "metrics", "cost"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Environment :: Web Environment",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development",
+]
+dependencies = [
+    "fastapi>=0.110",
+    "uvicorn>=0.29",
+    "pydantic>=2.6",
+    "pyjwt>=2.8",
+    "psycopg[binary,pool]>=3.1",
+    "alembic>=1.13",
+    "python-dotenv>=1.0",
+]
+
+[project.optional-dependencies]
+trae = ["pycryptodome>=3.20"]
+all = ["tokenmetre[trae]"]
+
+[project.urls]
+Homepage = "https://github.com/bsawang/tokenMetreCom"
+Repository = "https://github.com/bsawang/tokenMetreCom"
+
+[project.scripts]
+tokenmetre = "tokenmetre.cli.main:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["tokenmetre*"]
+
+[tool.setuptools.package-data]
+tokenmetre = [
+    "data/*.yaml",
+    "web/fonts/*",
+    "web/frontend/dist/**",
+    "adapters/**/*.md",
+    "adapters/**/*.py",
+]

tokenmetre-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tokenmetre-0.2.0/src/tokenmetre/__init__.py

@@ -0,0 +1 @@
+

tokenmetre-0.2.0/src/tokenmetre/adapters/__init__.py

@@ -0,0 +1 @@
+

tokenmetre-0.2.0/src/tokenmetre/adapters/claude-code/__init__.py

@@ -0,0 +1 @@
+