tokenmetre 0.2.0__py3-none-any.whl

tokenmetre/__init__.py

@@ -0,0 +1 @@
+

tokenmetre/adapters/__init__.py

@@ -0,0 +1 @@
+

tokenmetre/adapters/claude-code/__init__.py

@@ -0,0 +1 @@
+

tokenmetre/adapters/claude-code/adapter.py

@@ -0,0 +1,498 @@
+"""
+tokenMetre CC adapter: transcript 解析 + scan 入库。
+
+v2 架构(无 hook, codeburn 风格 per-message):
+  - 直接读 ~/.claude/projects/<sanitized_cwd>/*.jsonl transcript
+  - 每条 assistant message → 一条 Record(UNIQUE session_id + ts 天然去重)
+  - scan 游标用 SQLite processed_sessions 表
+  - 零 hook 依赖、零 mark 文件、零实时注入
+
+用法:
+  python adapters/claude-code/adapter.py scan --project <cwd>
+  python adapters/claude-code/adapter.py scan --all
+  python adapters/claude-code/adapter.py scan --status
+  python adapters/claude-code/adapter.py scan --dry-run
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+# pip 安装后直接用包命名空间(loader 动态加载本文件, tokenmetre 已在 site-packages)
+from tokenmetre.core.core import (
+    Record, derive_host, derive_user, derive_category, derive_provider,
+)
+from tokenmetre.core import db, registry, bind
+
+
+# ============================================================
+# CC transcript 路径处理
+# ============================================================
+
+def _sanitize_cwd_for_cc(cwd: str) -> str:
+    r"""把 Windows 绝对路径转 CC projects 目录名格式。
+    例: E:\work\ai\tokenMetre → E--work-ai-tokenMetre"""
+    s = str(cwd).rstrip("/\\")
+    # 盘符: E: → E--
+    s = re.sub(r'^([A-Za-z]):\\', r'\1--', s)
+    # 把 \ 换成 -
+    s = s.replace("\\", "-")
+    s = s.replace("/", "-")
+    # 去掉末尾的 -
+    s = s.rstrip("-")
+    return s
+
+
+def _find_cc_project_dir(cwd: str) -> Path | None:
+    """找 CC projects 下对应 cwd 的目录。精确匹配失败时大小写不敏感兜底。"""
+    cc_dir = Path.home() / ".claude" / "projects"
+    if not cc_dir.is_dir():
+        return None
+    exact = _sanitize_cwd_for_cc(cwd)
+    exact_path = cc_dir / exact
+    if exact_path.is_dir():
+        return exact_path
+    # 大小写不敏感兜底(CC 可能对同项目用不同盘符大小写)
+    exact_lower = exact.lower()
+    for child in cc_dir.iterdir():
+        if child.is_dir() and child.name.lower() == exact_lower:
+            return child
+    return None
+
+
+# ============================================================
+# transcript 解析(per-turn, 纯函数)
+# ============================================================
+
+def parse_transcript(transcript_path: str) -> list[dict]:
+    """解析 CC transcript JSONL, 返回 LLM 调用组列表(同 token = 同一次 LLM 调用 = 一条 Record)。
+
+    每条结果:
+      {
+        "ts": "2026-09-10T15:30:00+08:00",
+        "model": "deepseek-flash[1M]",
+        "token_in": 1500, "token_cache": 800, "token_out": 300,
+        "tool_names": ["Read", "Read", "Bash"],
+        "file_exts": [".md"],
+        "has_text": True,
+      }
+
+    处理逻辑:
+      1. 遍历 entry, 只关心 type="assistant" (跳过 user/attachment/queue-operation 等所有非 assistant)
+      2. 提取 tool_names / file_exts / has_text / usage tokens
+      3. 过滤纯 thinking 碎片(has_thinking=True 且 无 text 无 tools)和 token=0 空消息
+      4. 按 token_total 连续分组: token 相同 → 同一次 LLM 调用 → 合并成一条
+      5. 同 token 组内合并: token 取第一条(相同), tools/exts 取并集
+    """
+    p = Path(transcript_path).expanduser()
+    if not p.exists():
+        return []
+
+    # Step 1+2: 收集所有 assistant entry, 提取字段
+    raw: list[dict] = []
+    for line in p.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            entry = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+
+        # 只关心 assistant
+        if entry.get("type") != "assistant":
+            continue
+
+        msg = entry.get("message") or {}
+        content = msg.get("content") or []
+        if not isinstance(content, list):
+            continue
+
+        tool_names: list[str] = []
+        file_exts: list[str] = []
+        bash_cmds: list[str] = []
+        has_thinking = False
+        has_text = False
+
+        for c in content:
+            if not isinstance(c, dict):
+                continue
+            ctype = c.get("type", "")
+            if ctype == "tool_use":
+                tname = c.get("name", "")
+                tool_names.append(tname)
+                inp = c.get("input") or {}
+                if tname in ("Write", "Edit", "MultiEdit", "Patch", "Replace") and isinstance(inp, dict):
+                    fp = inp.get("file_path") or inp.get("path") or ""
+                    if fp:
+                        ext = os.path.splitext(fp)[1].lower()
+                        if ext:
+                            file_exts.append(ext)
+                elif tname in ("Bash", "RunCommand", "Terminal", "Execute") and isinstance(inp, dict):
+                    cmd = inp.get("command", "")
+                    if cmd:
+                        bash_cmds.append(cmd)
+            elif ctype == "thinking":
+                has_thinking = True
+            elif ctype == "text":
+                has_text = True
+
+        usage = msg.get("usage") or {}
+        token_in = int(usage.get("input_tokens") or usage.get("prompt_tokens") or 0)
+        token_cache = int(usage.get("cache_read_input_tokens") or usage.get("cache_read_tokens") or 0)
+        token_out = int(usage.get("output_tokens") or usage.get("completion_tokens") or 0)
+        token_total = token_in + token_cache + token_out
+
+        raw.append({
+            "ts": msg.get("timestamp") or entry.get("timestamp") or "",
+            "model": msg.get("model", "unknown"),
+            "token_in": token_in,
+            "token_cache": token_cache,
+            "token_out": token_out,
+            "token_total": token_total,
+            "tool_names": tool_names,
+            "file_exts": file_exts,
+            "bash_cmds": bash_cmds,
+            "has_thinking": has_thinking,
+            "has_text": has_text,
+            # 归属真相: 每条 entry 自带的工作目录(实测 100% 有值)。
+            # 一个 session 内可能漂移多个项目, 所以必须逐条记, 不能取会话目录。
+            "cwd": entry.get("cwd") or "",
+        })
+
+    # Step 3: 过滤纯 thinking 碎片 + token_total=0 空消息
+    valid = [m for m in raw
+             if not (m["has_thinking"] and not m["has_text"] and not m["tool_names"])
+             and m["token_total"] > 0]
+
+    if not valid:
+        return []
+
+    # Step 4+5: 按 token_total 连续分组(同 token = 同一次 LLM 调用)
+    result: list[dict] = []
+    cur_group: list[dict] = [valid[0]]
+
+    for m in valid[1:]:
+        if m["token_total"] == cur_group[0]["token_total"]:
+            cur_group.append(m)
+        else:
+            merged = _merge_group(cur_group)
+            if merged:
+                result.append(merged)
+            cur_group = [m]
+
+    merged = _merge_group(cur_group)
+    if merged:
+        result.append(merged)
+
+    return result
+
+
+def _merge_group(group: list[dict]) -> dict | None:
+    """把同 token 的一组 assistant messages 合并成一条 Record 输入。"""
+    if not group:
+        return None
+
+    first = group[0]
+    all_tools: list[str] = []
+    all_exts: list[str] = []
+    all_bash_cmds: list[str] = []
+    any_text = False
+
+    for m in group:
+        all_tools.extend(m["tool_names"])
+        all_exts.extend(m["file_exts"])
+        all_bash_cmds.extend(m.get("bash_cmds", []))
+        if m["has_text"]:
+            any_text = True
+
+    if not all_tools and not any_text:
+        return None
+
+    return {
+        "ts": first["ts"],
+        "model": first["model"],
+        "token_in": first["token_in"],      # 同组 token 全相同, 取第一条
+        "token_cache": first["token_cache"],
+        "token_out": first["token_out"],
+        "tool_names": all_tools,
+        "file_exts": list(dict.fromkeys(all_exts)),
+        "bash_cmds": all_bash_cmds,
+        "has_text": any_text,
+        # 同一次 LLM 调用的所有 entry 共享 cwd; 取组内首个非空值兜底
+        "cwd": next((m.get("cwd") for m in group if m.get("cwd")), ""),
+    }
+
+
+# ============================================================
+# 进度条(零依赖 ASCII, 单行覆盖刷新)
+# ============================================================
+
+def _progress(current: int, total: int, width: int = 30, label: str = "") -> None:
+    """单行 ASCII 进度条: 每步覆盖写同一行, 完成后换行。"""
+    if total <= 0:
+        return
+    pct = current / total
+    filled = int(width * pct)
+    bar = "█" * filled + "░" * (width - filled)
+    tail = f" {current}/{total}"
+    if label:
+        tail = f" {label}{tail}"
+    sys.stdout.write(f"\r  [{bar}]{tail}")
+    sys.stdout.flush()
+    if current >= total:
+        sys.stdout.write("\n")
+        sys.stdout.flush()
+
+
+# ============================================================
+# scan 核心: transcript → Record → SQLite
+# ============================================================
+
+def _transcript_to_record(
+    msg: dict,
+    session_id: str,
+    source: str = "claude-code",
+) -> Record | None:
+    """把 parse_transcript 的输出 → Record。
+
+    只做确定性映射, 不调 LLM, **不读 registry** —— 采集层是纯函数,
+    同输入永远同输出。归属由消息自带的 cwd 承载, 读时/上报时才解析。
+    """
+    ts = msg.get("ts") or ""
+    if not ts:
+        return None
+
+    return Record(
+        ts=ts,
+        session_id=session_id,
+        source=source,
+        user=derive_user(),
+        host=derive_host(),
+        provider=derive_provider(msg["model"]),  # 由模型名确定性反推(transcript 无厂商字段)
+        model=msg["model"],
+        token_in=msg["token_in"],
+        token_cache=msg["token_cache"],
+        token_out=msg["token_out"],
+        cwd=msg.get("cwd") or "",
+        category=derive_category(
+            tool_names=msg.get("tool_names", []),
+            file_exts=msg.get("file_exts"),
+            has_text=msg.get("has_text", False),
+            bash_cmds=msg.get("bash_cmds"),
+        ),
+    )
+
+
+def _all_transcript_dirs() -> list[Path]:
+    """~/.claude/projects/ 下所有会话目录。"""
+    cc_dir = Path.home() / ".claude" / "projects"
+    if not cc_dir.is_dir():
+        return []
+    return sorted(p for p in cc_dir.iterdir() if p.is_dir())
+
+
+def scan_transcripts(
+    dirs: list[Path] | None = None,
+    force_rescan: bool = False,
+    dry_run: bool = False,
+) -> dict:
+    """扫描 transcript → Record → SQLite。
+
+    **扫描源与归属解耦**: 一条会话住在哪个目录不再决定它属于哪个项目 ——
+    每条 record 自带 cwd, 归属在「读时统计」和「上报云端」时才解析。
+    所以这里不做任何 registry 过滤, 命中什么扫什么; 未登记项目的 record
+    留在库里, 等 `register add` / `register claim` 认领后自动出现。
+
+    返回 {"transcripts_found","sessions_scanned","sessions_skipped",
+          "messages_parsed","records_inserted","records_updated"}
+    """
+    dirs = _all_transcript_dirs() if dirs is None else dirs
+    transcripts: list[Path] = []
+    for d in dirs:
+        transcripts.extend(sorted(d.glob("*.jsonl")))
+
+    total_transcripts = len(transcripts)
+
+    # 先按游标筛出真正要处理的 session, 进度条只跑这一批 ——
+    # 否则增量扫描时也会为每个游标命中的 session 刷一帧, 白刷屏。
+    todo: list[Path] = []
+    skipped_sessions = 0
+    for t in transcripts:
+        if not force_rescan and db.is_session_processed(t.stem, t.stat().st_mtime):
+            skipped_sessions += 1
+        else:
+            todo.append(t)
+
+    sessions_scanned = 0
+    total_msgs = 0
+    total_inserted = 0
+    total_updated = 0
+
+    for done, transcript in enumerate(todo, 1):
+        session_id = transcript.stem
+        mtime = transcript.stat().st_mtime
+        if len(todo) > 1:
+            _progress(done, len(todo))
+
+        records_batch: list[Record] = []
+        for m in parse_transcript(str(transcript)):
+            total_msgs += 1
+            rec = _transcript_to_record(m, session_id)
+            if rec is not None:
+                records_batch.append(rec)
+
+        sessions_scanned += 1
+        if dry_run:
+            total_inserted += len(records_batch)  # dry-run 假装全是新增
+            continue
+
+        # v3.2: 按每条 record 的归属项目的 cloud 配置, 分组写 DB
+        # 有 cloud → sync_status=pending, cloud_key=api_base
+        # 无 cloud → sync_status=synced, cloud_key=None
+        groups: dict[tuple[str, str | None], list] = {}
+        for rec in records_batch:
+            hit = registry.resolve_attribution(rec.cwd)
+            cloud_key: str | None = None
+            sync_status: str = "synced"
+            if hit:
+                pid, _slug = hit
+                cloud = registry.get_project_cloud(pid)
+                if cloud and cloud.get("api_base"):
+                    sync_status = "pending"
+                    cloud_key = cloud["api_base"]
+            groups.setdefault((sync_status, cloud_key), []).append(rec)
+
+        for (sync_status, cloud_key), group_records in groups.items():
+            n_ins, n_upd = db.insert_records_batch(
+                group_records, sync_status=sync_status, cloud_key=cloud_key,
+            )
+            total_inserted += n_ins
+            total_updated += n_upd
+
+        db.mark_session_processed(session_id, str(transcript), mtime)
+
+    return {
+        "transcripts_found": total_transcripts,
+        "sessions_scanned": sessions_scanned,
+        "sessions_skipped": skipped_sessions,
+        "messages_parsed": total_msgs,
+        "records_inserted": total_inserted,
+        "records_updated": total_updated,
+    }
+
+
+def scan_project(cwd: str, force_rescan: bool = False, dry_run: bool = False) -> dict:
+    """只扫某个 cwd 对应的 transcript 目录。
+
+    调试入口 —— 注意它**不再决定归属**, 只是缩小扫描范围。
+    """
+    proj_dir = _find_cc_project_dir(cwd)
+    if proj_dir is None:
+        return {
+            "transcripts_found": 0, "sessions_scanned": 0, "sessions_skipped": 0,
+            "messages_parsed": 0, "records_inserted": 0, "records_updated": 0,
+            "error": "CC projects 目录未找到(该项目可能还没有 transcript)",
+        }
+    return scan_transcripts([proj_dir], force_rescan=force_rescan, dry_run=dry_run)
+
+
+def scan_all_active(force_rescan: bool = False, dry_run: bool = False) -> dict:
+    """兼容旧入口 —— 现在等同于全量扫所有 transcript(不再按 active 过滤)。"""
+    return scan_transcripts(force_rescan=force_rescan, dry_run=dry_run)
+
+
+def scan_status() -> dict:
+    """transcript 处理状态 + 按归属聚合的 record 数。
+
+    归属是读时解析的(按 record.cwd), 所以这里用 db.distinct_cwds() 拿到
+    所有出现过的 cwd, 逐个解析归组 —— 未登记的会被 `resolve_attribution` 挡掉。
+    """
+    active_dirs = registry.load_registry().get("active", [])
+    processed = db.get_processed_session_ids()
+
+    transcripts: list[Path] = []
+    for d in _all_transcript_dirs():
+        transcripts.extend(d.glob("*.jsonl"))
+    unprocessed = sum(
+        1 for t in transcripts
+        if not db.is_session_processed(t.stem, t.stat().st_mtime)
+    )
+
+    grouped: dict[str, dict] = {}
+    for cwd, n in db.distinct_cwds():
+        hit = registry.resolve_attribution(cwd)
+        if hit is None:
+            continue
+        pid, slug = hit
+        g = grouped.setdefault(pid, {"slug": slug, "cwds": 0, "records": 0})
+        g["cwds"] += 1
+        g["records"] += n
+
+    return {
+        "active_projects": len(active_dirs),
+        "total_transcripts": len(transcripts),
+        "processed_sessions": len(processed),
+        "unprocessed_sessions": unprocessed,
+        "total_records": db.count_records(),
+        "distinct_cwds": len(db.distinct_cwds()),
+        "pending_sync": bind.pending_pushable(),
+        "projects": [
+            {"project_id": pid, **v} for pid, v in sorted(grouped.items())
+        ],
+    }
+
+
+# ============================================================
+# CLI 入口(直接跑 adapter.py 时用; 实际扫描入口主要通过 cli/main.py scan)
+# ============================================================
+
+def main():
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")
+    ap = argparse.ArgumentParser(prog="tokenmetre-adapter-scan")
+    sub = ap.add_subparsers(dest="command", required=True)
+
+    p_scan = sub.add_parser("scan")
+    p_scan.add_argument("--project", help="只扫该 cwd 的 transcript 目录(默认全扫)")
+    p_scan.add_argument("--all", action="store_true", help="(默认行为, 保留兼容)")
+    p_scan.add_argument("--force", action="store_true", help="忽略游标, 全量重扫")
+    p_scan.add_argument("--dry-run", action="store_true", help="只看会产出什么, 不实际写")
+
+    sub.add_parser("status")
+
+    args = ap.parse_args()
+
+    if args.command == "scan":
+        if args.project:
+            result = scan_project(args.project, force_rescan=args.force, dry_run=args.dry_run)
+        else:
+            result = scan_transcripts(force_rescan=args.force, dry_run=args.dry_run)
+        if "error" in result:
+            print(f"[FAIL] {result['error']}")
+            sys.exit(1)
+        tag = "(dry-run) " if args.dry_run else ""
+        print(f"{tag}sessions: {result.get('sessions_scanned', 0)}  "
+              f"msgs: {result.get('messages_parsed', 0)}  "
+              f"inserted: {result['records_inserted']}  "
+              f"updated: {result.get('records_updated', 0)}")
+
+    elif args.command == "status":
+        s = scan_status()
+        print(f"active projects: {s['active_projects']}")
+        print(f"transcripts: {s['total_transcripts']}")
+        print(f"processed sessions: {s['processed_sessions']}")
+        print(f"unprocessed sessions: {s['unprocessed_sessions']}")
+        print(f"total records: {s['total_records']}  (distinct cwd: {s['distinct_cwds']})")
+        print(f"pending sync: {s['pending_sync']}")
+        for p in s["projects"]:
+            print(f"  {p['slug']}: {p['cwds']} cwds, {p['records']} records")
+
+
+if __name__ == "__main__":
+    main()

tokenmetre/adapters/claude-code/commands/tokenmetre-report.md

@@ -0,0 +1,69 @@
+---
+name: tokenmetre-report
+description: 汇总 tokenMetre 采集的 token 数据,按 source/model 聚合 unified_token,输出表格报告。当用户问"token 用了多少""开发成本多少""unified_token"时使用。
+---
+
+# tokenmetre-report
+
+产出 tokenMetre 数据汇总报告。**先 scan 再 report**——scan 是唯一的入库入口。
+
+## 执行步骤
+
+1. 先 scan 最新 transcript,确保 SQLite 有新数据:
+
+   ```bash
+   python "$HOME/.tokenmetre/bin/tokenmetre" scan
+   ```
+
+   `tokenmetre` **不在 PATH 上,必须走绝对路径**(直接执行 `~/.tokenmetre/bin/tokenmetre` 会因 shebang 是 `python3` 而静默失败)。
+
+   想跨项目汇总就先 `scan --all`。
+
+2. 生成报告(已内置聚合 + unified_token):
+
+   ```bash
+   python "$HOME/.tokenmetre/bin/tokenmetre" report
+   ```
+
+   常用选项:
+
+   ```bash
+   python "$T" report --all                  # 跨所有项目
+   python "$T" report --project <slug>       # 只看某项目
+   python "$T" report --from <ISO8601> --to <ISO8601>
+   ```
+
+   ⚠️ **没有** `--category` 参数。要按 category 拆分,直接查库:
+
+   ```bash
+   python - <<'PY'
+   import sqlite3, pathlib
+   c = sqlite3.connect(str(pathlib.Path.home()/'.tokenmetre'/'tokenmetre.db'))
+   for r in c.execute('select category, count(*), sum(token_in), sum(token_cache), sum(token_out) '
+                      'from records group by category order by 2 desc'):
+       print(r)
+   PY
+   ```
+
+   数据源:LocalEmit 模式读本地 SQLite;HttpEmit 模式拉云端。云端模式有 pending sync 时会标注提示。
+
+3. unified_token 用 `~/.tokenmetre/data/weights.yaml` 的权重算:
+
+   ```
+   unified = (token_in*price_in + token_cache*price_cache + token_out*price_out)
+           / (price_in + price_cache + price_out)
+   ```
+
+   某模型算不出 unified_token(显示为 0 / None)说明 `weights.yaml` 未收录它,
+   用 `/tokenmetre-pricing` skill 补价格。
+
+4. 按 source + model 聚合,category 作为辅助维度展示。
+
+5. 用 markdown 表格输出,字段顺序:`source | model | 记录数 | token_in | token_cache | token_out | unified_token`
+
+## 如果没有 records
+
+提示 "no records yet. run `tokenmetre scan` to import transcript data."。
+
+排查顺序:① 项目是否 `register add` 登记过 → ② 该目录下 CC 是否真的产生过 transcript
+(`~/.claude/projects/<sanitized-path>/*.jsonl`)→ ③ 跑 `scan --status` 看游标状态。

tokenmetre/adapters/claude-code/commands/tokenmetre-scan.md

@@ -0,0 +1,92 @@
+---
+name: tokenmetre-scan
+description: 扫描 Claude Code transcript 把 token 数据入库并生成统计报告。当用户说"scan token"、"提交工作量"、"我今天写了多少 token"时使用。
+---
+
+# tokenmetre-scan
+
+扫描 Claude Code transcript → SQLite 入库 → 生成统计报告。
+
+v3 架构:零 hook、零 plugin,完全只读 CC 自己写的 transcript;per-LLM-call 粒度。
+**扫描与归属解耦**:扫描只负责把 transcript 里的内容连同每条消息的 `cwd` 落库,
+归属在读时按 cwd 解析(见下)。
+
+## 执行步骤
+
+1. 扫描 transcript 入库:
+
+   ```bash
+   python "$HOME/.tokenmetre/bin/tokenmetre" scan
+   ```
+
+   `tokenmetre` **不在 PATH 上,必须走绝对路径**(直接执行 `~/.tokenmetre/bin/tokenmetre` 会因 shebang 是 `python3` 而静默失败)。
+
+   默认**全量扫 `~/.claude/projects/**`**,不再按 active 过滤 —— 因为会话住在哪个
+   目录不再决定它属于哪个项目。已处理过的 session 按 mtime 游标自动跳过。
+
+   常用选项:
+
+   ```bash
+   python "$T" scan --project <cwd>   # 只扫该目录的 transcript(调试用)
+   python "$T" scan --force           # 忽略游标全量重扫(改了 category 规则后用)
+   python "$T" scan --dry-run         # 只看会产出什么,不实际写
+   python "$T" scan --status          # 处理状态 + 按归属聚合
+   ```
+
+   ⚠️ `--force` 现在真正生效 —— 写入改成 upsert 了,重扫会覆盖旧行。
+   (v3.0 用的是 `INSERT OR IGNORE`,重扫写不进去,这个 bug 已修)
+
+2. 生成报告:
+
+   ```bash
+   python "$HOME/.tokenmetre/bin/tokenmetre" report
+   ```
+
+   常用选项:
+
+   ```bash
+   python "$T" report --all                  # 跨所有项目
+   python "$T" report --project <slug>
+   python "$T" report --from <ISO8601> --to <ISO8601>
+   ```
+
+   ⚠️ `report` **没有** `--category` 参数。
+
+3. 用 markdown 表格输出,字段顺序:`source | model | 记录数 | token_in | token_cache | token_out | unified_token`
+
+## 如果没有 records
+
+分两种情况,别混:
+
+- **库里根本没记录** → 报告 "no records yet. run `tokenmetre scan` ..."。先 `scan` 入库。
+- **库里有记录、但报表是空的/偏少** → 大概率是**未归属**:这些记录的 cwd 不在任何
+  active 链上,也没有被 claim。`report` 会打一行
+  「N 条记录的工作目录未登记/未认领, 不计入」提示。用 `register add <cwd>`
+  (新项目) 或 `register claim <cwd> --id <tm_xxx>`(搬家/子目录) 认领后**立即出现** ——
+  不需要重扫, 归属是读时解析的。
+
+排查:`scan --status` 看 `total records` 与 `distinct cwd`;`register list` 看 active / ignored / claims。
+
+## 分类(category)说明
+
+scan 按工具名确定性映射 category(**不调 LLM**),共 5 类:
+
+| category | 中文 | 包含工具 / 判定 |
+|---|---|---|
+| `documentation` | 文档 | Write 目标文件后缀 `.md` / `.markdown` |
+| `coding` | 编码 | Write / Edit / MultiEdit / Patch / Replace(非 .md) |
+| `execution` | 实施 | Skill / Agent / Task / TodoWrite + Bash「写/装/跑」 |
+| `exploration` | 调研 | Read / Glob / Grep / LS / Search / WebFetch / WebSearch + Bash「读/查/搜」 |
+| `discussion` | 讨论 | AskUserQuestion,或无工具但有 text |
+
+**优先级**:`documentation > coding > execution > exploration > discussion`
+
+一次 LLM 调用触发多个工具时,按优先级取最高的 category。
+
+## 粒度说明
+
+**一条 record = 一次 LLM 调用**(不是一条 assistant message)。
+CC 会把一次调用拆成 thinking / text / tool_use 等多条 jsonl entry,它们共享同一组 usage 数字;
+scan 按相同 usage 归组,所以记录数会明显少于 assistant entry 数——这是**正确的**,不是丢数据。
+
+例:`29fe6af6` 会话里 14 条 assistant entry → 6 条 record(`#6+#7` 一组、`#9+#10+#11` 一组……)。