Poker Tracker (PT) v1.0

Personal poker session tracker with interactive dashboard. Zero dependencies · Local-first · AI-agent ready · Multi-currency · MIT-licensed.

个人扑克战绩追踪系统，带交互式可视化仪表盘。 零依赖 · 本地优先 · 原生支持 AI 助手 · 多币种 · MIT 开源协议。

---

What is this? / 这是什么？

You finish a poker session. You're tired. You just want to say "MTT, buy-in 5000, 3rd place, won 20k" and move on. Not open Excel.

打完牌很累，不想填 Excel。直接说"MTT，买入 5000，第三，奖金两万"——PT 自动识别录入。想看战绩？一句"战绩怎么样"，跨币种、跨类型、跨时间统计秒出。

PT gives you / PT 给你：

• Natural-language input in Chinese or English / 中英文自然语言录入
• Multi-currency (CNY/USD/HKD/KRW/EUR/GBP/JPY/SGD) / 多币种支持
• Per-type stats: ITM rate, ROI, FT rate for MTT; win rate, $/hr for Cash / 类型专项统计
• Interactive dashboard: cumulative P&L curve, by-location, rank histogram / 交互式仪表盘
• AI-agent integration — chat assistants pick up sessions from voice notes / AI 助手集成
• Local-only data, zero cloud, zero CDN / 数据 100% 本地

---

Quick Start / 快速开始

# 1. Clone & install / 克隆 + 安装
git clone https://github.com/DannyAce66/Poker_Tracker.git
cd Poker_Tracker
pip install -e .

# 2. Try the bundled sample (18 fictional sessions) / 试用 18 条虚构样例
pt --data-dir data list
pt --data-dir data stats
pt --data-dir data visualize        # → visualization/dashboard.html

# 3. Start your own / 开始记录你自己的
pt record --type MTT --buyin 5000 --prize 20000 --players 120 --rank 3
pt parse "今天 MTT 买入5000 第3名 奖金2万 120人" --commit
pt stats --type MTT --currency USD
pt visualize

Personalize the owner / 自定义称呼

# Linux/macOS
export PT_OWNER_NAME="Alex"
export PT_DEFAULT_CURRENCY="USD"

# Windows PowerShell
$env:PT_OWNER_NAME = "Alex"
$env:PT_DEFAULT_CURRENCY = "USD"

---

Core commands / 核心命令

Command 命令	What it does 功能
pt record --type ... --buyin ... --prize ...	Record a session / 录入一场
pt parse "natural language..."	Parse text; --commit to write / 解析自然语言
pt stats [--type ...] [--currency ...]	Statistics / 统计
pt list [--limit N]	List sessions, newest first / 列出最近场次
pt show ID	Show one session / 查看单场详情
pt remove ID	Delete a session / 删除（小心）
pt visualize	Generate dashboard HTML / 生成可视化
pt undo	Roll back last write / 回滚最近一次写入
pt audit --tail N	View audit log / 查看审计日志
pt healthcheck	Data integrity check / 数据完整性检查

Add --json to any command for agent-friendly structured output. 任何命令加 --json 输出 JSON（AI 助手友好）。

---

Interactive dashboard / 交互式仪表盘

pt visualize
# → visualization/dashboard.html

Single self-contained HTML, no CDN, no server. 单 HTML，无 CDN、无需启动服务器。

Components / 组件:

• KPI cards per currency (sessions, profit, ROI, win rate) / KPI 卡片（按币种）
• Cumulative P&L curve — multi-currency lines on shared time axis / 盈亏曲线（多币种叠加）
• By-location table sorted by profit / 地点分析表
• MTT rank distribution histogram / MTT 排名分布
• Recent 50 sessions table / 最近 50 场
• Filters: type, currency, date range / 过滤器：类型、币种、日期

---

Python library / Python 库

from pt import Store, Session, Stats, parse_voice

store = Store()  # auto-loads SOT / 自动加载真相源

# Record / 录入
s = Session(type="MTT", date="2026-05-29", location="Vegas",
            buyin=1500, buyin_currency="USD",
            prize=4500, prize_currency="USD",
            players=180, rank=12,
            tags=["main event"])
store.add(s)

# Natural language / 自然语言
parsed = parse_voice("今天 Cash 在 Macau 买入 HK$30000 水上 20000 4小时")
if not parsed["missing"]:
    store.add(Session(**parsed["session"]))

# Stats / 统计
stats = Stats(store)
print(stats.summary(type="MTT", currency="USD"))
print(stats.cumulative_pnl(currency="USD"))
print(stats.by_location())

# Update / 修改
store.update(s.id, prize=5500)  # auto-recomputes profit

# Rollback / 回滚
store.undo()

---

Safety features / 安全机制

Feature 特性	What you get / 你得到的
Atomic writes / 原子写入	tmp + rename — no half-written files / 不会留半成品文件
Auto-backup / 自动备份	Each write snapshots SOT (12 retained) / 每次写入自动快照
Audit log / 审计日志	Every write recorded in JSONL / 每次写入记录在 audit.log
One-step undo / 一键撤销	store.undo() / 恢复到上次写入前
Healthcheck / 健康检查	pt healthcheck (7 invariants) / 数据完整性自检
Test suite / 测试套件	34 tests / 单元测试

---

AI agent integration / AI 助手集成

PT ships with a complete agent guide at skills/SKILL.md and a constitution at RULES.md. Drop them into your agent's context (Claude Code, Hermes, Cursor, etc.) and it will know:

PT 自带完整的 agent 指南和系统宪法。把它们放进你的 agent 的 context，它就会知道：

• When to scan messages for poker session mentions / 何时扫描扑克场次提及
• When to ask for confirmation (always before writes) / 何时确认（任何写操作前）
• Where each piece of info goes / 每条信息应该录到哪个字段
• How to handle errors and roll back / 如何处理错误、如何回滚

# For Claude Code / Claude Code 配置
cp RULES.md ~/.claude/skills/poker-tracker/RULES.md
cp skills/SKILL.md ~/.claude/skills/poker-tracker/SKILL.md

---

Data model / 数据模型

{
  "id": "8-char-uuid",
  "date": "2026-03-22",
  "type": "MTT",
  "location": "Macau",
  "buyin": 8000,
  "buyin_currency": "CNY",
  "prize": 35000,
  "prize_currency": "CNY",
  "players": 180,
  "rank": 3,
  "duration": 0,
  "profit": 27000,
  "profit_currency": "CNY",
  "notes": "Final table run",
  "tags": ["final table"],
  "meta": {
    "created_at": "2026-03-22T23:30:00",
    "updated_at": "2026-03-22T23:30:00"
  }
}

See SPEC.md for the full schema and RULES.md for usage conventions. 完整 schema 见 SPEC.md，使用规范见 RULES.md。

---

Project structure / 项目结构

Poker_Tracker/
├── RULES.md                    ← system constitution / 系统宪法
├── README.md                   ← this file / 本文件
├── LICENSE                     ← MIT
├── SPEC.md                     ← formal data spec / 数据规格
├── setup.py / requirements.txt
├── data/
│   ├── sample.jsonl            ← 18 fictional sessions / 18 条虚构样例
│   └── .gitkeep
├── pt/                         ← core library / 核心库
│   ├── models.py / store.py / parser.py / stats.py / audit.py / cli.py
├── tools/
│   ├── visualize.py            ← dashboard generator / 仪表盘生成
│   └── healthcheck.py          ← integrity check / 数据完整性
├── tests/
│   └── test_all.py             ← 34 tests / 测试
├── visualization/
│   ├── _template.html
│   └── dashboard.html          ← generated / 生成产物（不入仓库）
├── skills/
│   └── SKILL.md                ← AI agent integration / agent 接口
├── docs/
│   └── GUIDE.md                ← bilingual tutorial / 中英双语教程
└── scripts/
    └── install.sh              ← one-click setup / 一键安装

---

License / 许可

MIT — see LICENSE.

---

What's new in v1.0 / v1.0 新特性

Major rewrite from v0.1.x / 相对 v0.1.x 的大重构：

• New schema / 新 schema: added id, tags, meta.created_at/updated_at
• JSONL replaces CSV / JSONL 取代 CSV: human-readable, git-friendly, safer
• SQLite backend dropped / SQLite 后端废弃: single source of truth
• Interactive dashboard / 交互式仪表盘: cumulative P&L + by-location + rank histogram (was: text only)
• Atomic writes + auto-backup + audit log + undo / 原子写入 + 自动备份 + 审计 + 撤销: was: none
• PT_OWNER_NAME configurable / owner 可配置: via env var
• Healthcheck / 健康检查: 7 invariants enforced
• Voice parser bug fixes / 语音解析 bug 修复:
  • $2000 now correctly detected as USD (was: always CNY)
  • Year no longer hard-coded to 2026
• 34 tests / 34 个测试: unit + sample-data + invariant
• RULES.md constitution / RULES.md 宪法: agents have explicit hard rules
• skills/SKILL.md / skills/SKILL.md: standardized AI-agent integration

See docs/GUIDE.md for the full bilingual tutorial. 完整中英双语教程见 docs/GUIDE.md。