@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/usage_report.py

@@ -0,0 +1,531 @@
+#!/usr/bin/env python3
+"""usage_report —— **每票真实模型成本**（定价锚点，2026-09-22 落地）。
+
+## 为什么需要它
+定价不能靠猜。2026-09-22 实测发现：服务端扣费公式里有**最低 1 积分封顶**
+（`cost = max(1, ceil(cost元 × 10 × 1.2 × 100)/100)`），历史 1841 次消耗里 **95.2% 都被封顶**
+⇒ 只看"扣了多少积分"**根本推不出真实成本**（之前"¥0.11/请求"其实是我们的**售价**，不是成本）。
+所以锚点分两段：
+
+- **从现在起（精确）**：服务端把计价依据一并落库（`costYuan` + `usage{prompt,cacheHit,cacheMiss,output}`
+  + `rate` 单价快照 + `margin/peak`，2026-09-22 上线，见 whyshu-svr `src/routes/argent.js`）；
+  本脚本直接读 `costYuan` ⇒ 每票成本**精确**。
+- **历史（只有区间）**：非封顶行可由金额精确反推（`cost = |金额| / (cnyToPoints × margin)`）；
+  封顶行只能给**上界** `1/(cny×margin)` 元。报告里用 `¥lo ～ ¥hi` 表达，并标 `exact=False`。
+
+## 归因（诚实近似）
+把每一次请求按时间落进 case 的 `planned → done/failed` 窗口（前后各外扩 90s/300s）；
+窗口重叠的票（一店一批、一个 subagent 跑 3 张）**整批求和再按票数摊**，标 `batched=true`。
+所以输出里的"每票成本"是**该批次摊到的量**，是定价下限的稳健锚，不是逐次调用的精确归属。
+
+用法：
+  python3 scripts/usage_report.py --pull                     # 拉流水（增量去重）
+  python3 scripts/usage_report.py --report [--month 2026-09] [--json]
+退出码：0 正常；1 拉取失败；2 参数错误
+"""
+from __future__ import annotations
+import argparse, datetime as dt, json, os, pathlib, re, sys, time, urllib.error, urllib.request
+
+try:
+    from flow_registry import consumer_doc as _registry_doc      # P2a：base + 业务线合并（唯一真源）
+except Exception:  # noqa: BLE001 —— 半坏机器上退回单文件（升级链路要能跑）
+    def _registry_doc(path=None):
+        _p = pathlib.Path(path) if path else (HERE / "flow-requirements.json")
+        return json.loads(_p.read_text(encoding="utf-8"))
+
+
+HERE = pathlib.Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE / 'lib'))
+from argent_datadir import resolve_data_dir  # noqa: E402  数据目录唯一判据（勿在此复制链）
+DATA = pathlib.Path(resolve_data_dir()['dir'])
+USAGE = DATA / "usage"
+HISTORY = USAGE / "points-history.jsonl"        # 原始流水（按 _id 去重）
+LOCAL = USAGE / "local-requests.jsonl"           # 本机会话级用量（走官方直连也有）
+RATES = USAGE / "rate-table.json"               # 权威费率缓存（来自服务端 points-rules）
+DEFAULT_LEDGER = DATA / "flow-ledger.jsonl"
+POINTS_PER_YUAN = 10.0                          # 1 元 = 10 积分（售价侧）
+DEFAULT_MARGIN, DEFAULT_CNY_TO_POINTS = 1.2, 10.0
+# 内置兜底费率（与服务端 config.points.models 保持一致；正常应经 --pull-rates 取权威值）
+DEFAULT_RATES = {"margin": DEFAULT_MARGIN, "cnyToPoints": DEFAULT_CNY_TO_POINTS,
+                 "peakHours": [[9, 12], [14, 18]],
+                 "models": {"deepseek-v4-flash": {"cacheHit": 0.1, "input": 3.0, "output": 9.0},
+                            "deepseek-v4-pro": {"cacheHit": 0.3, "input": 9.0, "output": 27.0}}}
+
+LEAD_SEC, TAIL_SEC = 90, 300                    # 窗口外扩（派发前思考 + 跑完复核）
+
+
+def load_registry() -> dict:
+    try:
+        return _registry_doc()
+    except Exception:                                            # noqa: BLE001
+        return {}
+
+
+def api_creds() -> tuple:
+    base = (os.environ.get("WHYSHU_API_URL") or "https://whyshu.com").rstrip("/")
+    tok = os.environ.get("WHYSHU_API_KEY") or ""
+    if not tok:
+        for name in ("whyshu.env", "fulfillment.env"):
+            try:
+                for line in (DATA / name).read_text(encoding="utf-8").splitlines():
+                    t = line.strip()
+                    if t.startswith("WHYSHU_API_KEY="):
+                        tok = t.split("=", 1)[1].strip().strip('"').strip("'")
+            except Exception:                                    # noqa: BLE001
+                continue
+    return base, tok
+
+
+def pull(pages: int = 20, limit: int = 200) -> int:
+    """增量拉取积分流水（按 _id 去重）。返回新增条数；-1 = 失败。"""
+    base, tok = api_creds()
+    if not tok:
+        print("❌ 缺 WHYSHU_API_KEY（进程环境或 ~/.dsh/argent/*.env）", file=sys.stderr)
+        return -1
+    seen = set()
+    if HISTORY.exists():
+        for line in HISTORY.read_text(encoding="utf-8").splitlines():
+            try:
+                seen.add(json.loads(line)["_id"])
+            except Exception:                                    # noqa: BLE001
+                continue
+    USAGE.mkdir(parents=True, exist_ok=True)
+    HISTORY.parent.mkdir(parents=True, exist_ok=True)   # 首次运行目录还不存在时也要能写
+    new = 0
+    with HISTORY.open("a", encoding="utf-8") as fh:
+        for page in range(1, pages + 1):
+            url = f"{base}/api/argent/points-history?limit={limit}&page={page}"
+            req = urllib.request.Request(url, headers={"Authorization": f"Bearer {tok}"})
+            try:
+                with urllib.request.urlopen(req, timeout=30) as r:
+                    doc = json.loads(r.read().decode("utf-8") or "{}")
+            except urllib.error.HTTPError as e:
+                print(f"❌ 拉取失败 HTTP {e.code}（page {page}）", file=sys.stderr)
+                return -1
+            except Exception as e:                               # noqa: BLE001
+                print(f"❌ 拉取失败：{e}", file=sys.stderr)
+                return -1
+            items = doc.get("transactions") or doc.get("items") or []
+            if not items:
+                break
+            for t in items:
+                if t.get("_id") in seen:
+                    continue
+                seen.add(t["_id"])
+                fh.write(json.dumps(t, ensure_ascii=False) + "\n")
+                new += 1
+            if len(items) < limit:
+                break
+    print(f"  ✅ 流水：新增 {new} 条（累计 {len(seen)} 条）→ {HISTORY}")
+    return new
+
+
+def pull_rates() -> dict:
+    """拉权威费率表（公开端点，无需登录）并缓存。失败时保留旧缓存/兜底值。"""
+    base, _ = api_creds()
+    try:
+        with urllib.request.urlopen(f"{base}/api/argent/points-rules", timeout=20) as r:
+            doc = json.loads(r.read().decode("utf-8") or "{}")
+        table = {"margin": float(doc.get("margin") or DEFAULT_MARGIN),
+                 "cnyToPoints": float(doc.get("cnyToPoints") or DEFAULT_CNY_TO_POINTS),
+                 "peakHours": doc.get("peakHours") or DEFAULT_RATES["peakHours"],
+                 "models": {m["model"]: {"cacheHit": float(m["perMillion"]["cacheHit"]),
+                                         "input": float(m["perMillion"]["input"]),
+                                         "output": float(m["perMillion"]["output"])}
+                            for m in (doc.get("models") or []) if m.get("perMillion")}}
+        if not table["models"]:
+            raise ValueError("服务端未返回 models")
+        USAGE.mkdir(parents=True, exist_ok=True)
+        RATES.write_text(json.dumps(table, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+        print(f"  ✅ 费率表已更新（{len(table['models'])} 个模型，margin {table['margin']}）→ {RATES}")
+        return table
+    except Exception as e:                                       # noqa: BLE001
+        print(f"  ⚠️ 费率表拉取失败（沿用缓存/兜底）：{e}", file=sys.stderr)
+        return load_rates()
+
+
+def load_rates() -> dict:
+    try:
+        t = json.loads(RATES.read_text(encoding="utf-8"))
+        if t.get("models"):
+            return t
+    except Exception:                                            # noqa: BLE001
+        pass
+    return DEFAULT_RATES
+
+
+def is_peak(ts: float, rates: dict) -> bool:
+    """峰谷判定：按**北京时间**（服务端 TZ 即 Asia/Shanghai，与文档一致）。"""
+    h = dt.datetime.fromtimestamp(ts, dt.timezone(dt.timedelta(hours=8))).hour
+    return any(a <= h < b for a, b in (rates.get("peakHours") or []))
+
+
+def price_row(row: dict, rates: dict) -> float:
+    """本机用量 → 元（与服务端 computeCostYuan 同一公式：命中/未命中/输出 × 单价 × 峰谷）。
+
+    ⚠️ `row["ts"]` 是**毫秒**（会话日志 `time` 字段），折算成秒后才能判峰谷。
+    """
+    m = (rates.get("models") or {}).get(row.get("model") or "") or DEFAULT_RATES["models"]["deepseek-v4-flash"]
+    yuan = (int(row.get("cacheRead") or 0) * m["cacheHit"] + int(row.get("input") or 0) * m["input"]
+            + int(row.get("output") or 0) * m["output"]) / 1_000_000
+    ts_sec = float(row.get("ts") or 0) / 1000.0
+    return yuan * (1.0 if is_peak(ts_sec, rates) else 0.5)
+
+
+def load_local(rates: dict, path: pathlib.Path = None) -> list:
+    """本机会话用量（`local-usage.mjs` 产出）→ 统一行结构（成本精确，无需封顶估计）。"""
+    path = path or LOCAL
+    out = []
+    if not path.exists():
+        return out
+    for line in path.read_text(encoding="utf-8").splitlines():
+        try:
+            r = json.loads(line)
+        except Exception:                                        # noqa: BLE001
+            continue
+        cy = price_row(r, rates)
+        out.append({"id": None, "ts": float(r.get("ts") or 0) / 1000.0, "points": cy,
+                    "spend": True, "type": "local_usage", "source": "local",
+                    "kind": r.get("kind") or "chat", "session": r.get("session"),
+                    "model": r.get("model") or "", "peak": is_peak(float(r.get("ts") or 0) / 1000.0, rates),
+                    "costLo": cy, "costHi": cy, "exact": True, "charged": 0.0,
+                    "tokens": int(r.get("input") or 0) + int(r.get("cacheRead") or 0) + int(r.get("output") or 0),
+                    "prompt": int(r.get("input") or 0) + int(r.get("cacheRead") or 0),
+                    "cacheHit": r.get("cacheRead"), "cacheMiss": r.get("input"), "output": r.get("output")})
+    out.sort(key=lambda x: x["ts"])
+    return out
+
+
+def scan_local() -> int:
+    """调用 local-usage.mjs 增量扫描本机会话日志。返回新增请求数（-1 = 失败）。"""
+    import subprocess
+    try:
+        r = subprocess.run(["node", str(HERE / "local-usage.mjs"), "--json"],
+                           capture_output=True, text=True, timeout=600)
+        if r.returncode != 0:
+            print(f"  ⚠️ 本机扫描失败：{(r.stderr or r.stdout or '').strip()[:200]}", file=sys.stderr)
+            return -1
+        n = int(json.loads(r.stdout).get("newRequests") or 0)
+        print(f"  ✅ 本机会话：新增 {n} 次请求 → {LOCAL}")
+        return n
+    except Exception as e:                                       # noqa: BLE001
+        print(f"  ⚠️ 本机扫描失败：{e}", file=sys.stderr)
+        return -1
+
+
+def parse_desc(desc) -> dict:
+    """从 description 取 tokens/模型（服务端模板：`AI对话消耗 133 tokens（deepseek-v4-flash，高峰时段）`）。"""
+    d = str(desc or "")
+    m = re.search(r"(\d+)\s*tokens", d)
+    mm = re.search(r"（([^，,]+)[，,]", d)
+    return {"tokens": int(m.group(1)) if m else 0, "modelDesc": (mm.group(1) if mm else ""),
+            "peakDesc": "高峰" in d}
+
+
+def row_cost(t: dict) -> tuple:
+    """一次请求的真实成本 (lo, hi, exact, charged)——见文件头"两段锚点"。
+
+    精确：新数据带 costYuan；历史的非封顶行可由金额反推（误差 <0.01 元，来自 ceil 取整）。
+    上界：历史封顶行（金额恰为 1 积分）只知道 cost ≤ 1/(cny×margin) 元。
+    """
+    cny = float(t.get("cnyToPoints") or DEFAULT_CNY_TO_POINTS)
+    mg = float(t.get("margin") or DEFAULT_MARGIN)
+    raw = float(t.get("amount") or 0)
+    if raw >= 0:                        # 发放/充值/管理调整：不是消耗，既无成本也无"收费"
+        return 0.0, 0.0, True, 0.0
+    amt = abs(raw)
+    charged = amt / cny
+    if t.get("costYuan") is not None:
+        cy = float(t["costYuan"])
+        return cy, cy, True, charged
+    if amt > 1.0:                       # 未封顶 ⇒ 由金额反推（ceil 取整，误差 ≤ 0.01/(cny×margin) 元）
+        return amt / (cny * mg), amt / (cny * mg), True, charged
+    return 0.0, 1.0 / (cny * mg), False, charged      # 封顶 ⇒ 仅上界
+
+
+def load_history(path: pathlib.Path) -> list:
+    out = []
+    if not path.exists():
+        return out
+    for line in path.read_text(encoding="utf-8").splitlines():
+        try:
+            t = json.loads(line)
+        except Exception:                                        # noqa: BLE001
+            continue
+        try:
+            epoch = dt.datetime.fromisoformat(str(t.get("created_at") or t.get("createdAt") or "")
+                                              .replace("Z", "+00:00")).timestamp()
+        except Exception:                                        # noqa: BLE001
+            continue
+        info = parse_desc(t.get("description"))
+        amt = float(t.get("amount") or 0)
+        lo, hi, exact, charged = row_cost(t)
+        u = t.get("usage") or {}
+        out.append({"id": t.get("_id"), "ts": epoch, "points": -amt if amt < 0 else 0.0,
+                    "spend": amt < 0, "type": t.get("type"), "source": "proxy", "kind": "proxy",
+                    "model": t.get("model") or info["modelDesc"],
+                    "peak": t.get("peak") if t.get("peak") is not None else info["peakDesc"],
+                    "costLo": lo, "costHi": hi, "exact": exact, "charged": charged,
+                    "tokens": u.get("total") or info["tokens"],
+                    "prompt": u.get("prompt"), "cacheHit": u.get("cacheHit"),
+                    "cacheMiss": u.get("cacheMiss"), "output": u.get("output")})
+    out.sort(key=lambda x: x["ts"])
+    return out
+
+
+def load_cases(ledger: pathlib.Path, doc: dict = None) -> dict:
+    """台账 → caseId: {start, end, flow, terminal}（窗口归因输入）。
+
+    只收**已注册流程**的 case（`doc['flows']`）；缺 doc 时按前缀黑名单兜底。
+    否则 `claim__<x>` / `preflight__<x>` / `lease` 这类事件会变成幽灵票，把每票成本摊薄。
+    """
+    cases: dict = {}
+    known = set((doc or {}).get("flows") or {})
+    skip = {"claim", "preflight", "lease", "lease-remind", "heartbeat", "notify", "invoice-ready-leftover"}
+    if not ledger.exists():
+        return cases
+    for line in ledger.read_text(encoding="utf-8").splitlines():
+        try:
+            e = json.loads(line)
+        except Exception:                                        # noqa: BLE001
+            continue
+        cid = str(e.get("caseId") or "")
+        if not cid or "__" not in cid:
+            continue
+        flow = cid.split("__")[0]
+        if (known and flow not in known) or (not known and flow in skip):
+            continue
+        ts = float(e.get("ts") or 0)
+        c = cases.setdefault(cid, {"caseId": cid, "flow": flow, "start": ts, "end": ts, "terminal": ""})
+        c["start"] = min(c["start"], ts) if c["start"] else ts
+        c["end"] = max(c["end"], ts)
+        if str(e.get("event")) in ("done", "failed", "blocked"):
+            c["terminal"] = str(e.get("event"))
+    return cases
+
+
+def attribute(cases: dict, hist: list, doc: dict) -> dict:
+    """窗口归因 + 批次摊分（纯函数）。成本按 lo/hi 双轨累计。"""
+    flow_cap = {fid: str((f or {}).get("capability") or "") for fid, f in (doc.get("flows") or {}).items()}
+    # 票据成本只能由**流程角色会话**产生：本机对话/开发会话（kind=chat）不进窗口，
+    # 否则我自己的长对话会把每票成本算成天价（2026-09-22 实测 chat 侧 43 亿 cacheRead）。
+    events = [h for h in hist if h.get("spend") and (h.get("source") != "local" or h.get("kind") == "flow")]
+    wins = []
+    for c in cases.values():
+        cap = flow_cap.get(c["flow"], "")
+        if not cap:
+            continue
+        wins.append({**c, "capability": cap, "w0": c["start"] - LEAD_SEC, "w1": c["end"] + TAIL_SEC,
+                     "costLo": 0.0, "costHi": 0.0, "tokens": 0, "reqs": 0.0, "exact": True})
+    wins.sort(key=lambda x: x["w0"])
+    batches = []
+    for w in wins:
+        if batches and w["w0"] <= batches[-1]["w1"]:
+            batches[-1]["items"].append(w)
+            batches[-1]["w1"] = max(batches[-1]["w1"], w["w1"])
+        else:
+            batches.append({"w0": w["w0"], "w1": w["w1"], "items": [w]})
+    for b in batches:
+        inside = [h for h in events if b["w0"] <= h["ts"] <= b["w1"]]
+        b["costLo"] = sum(h["costLo"] for h in inside)
+        b["costHi"] = sum(h["costHi"] for h in inside)
+        b["tokens"] = sum(h["tokens"] for h in inside)
+        b["reqs"] = len(inside)
+        b["exact"] = all(h["exact"] for h in inside)
+        n = max(1, len(b["items"]))
+        for w in b["items"]:
+            w["costLo"] = b["costLo"] / n
+            w["costHi"] = b["costHi"] / n
+            w["tokens"] = b["tokens"] // n
+            w["reqs"] = b["reqs"] / n
+            w["exact"] = b["exact"]
+            w["batched"] = n > 1
+            w["batchSize"] = n
+    return {"byCase": {w["caseId"]: w for w in wins}, "batches": batches, "hist": hist}
+
+
+def summary(attr: dict, month: str, doc: dict) -> dict:
+    hist = [h for h in attr["hist"]
+            if h.get("spend") and time.strftime("%Y-%m", time.localtime(h["ts"])) == month]
+    total_lo = sum(h["costLo"] for h in hist)
+    total_hi = sum(h["costHi"] for h in hist)
+    charged = sum(h["charged"] for h in hist)          # 本机行 charged=0（未走代理计费）
+    local_hist = [h for h in hist if h.get("source") == "local"]
+    proxy_hist = [h for h in hist if h.get("source") != "local"]
+    local_flow = [h for h in local_hist if h.get("kind") == "flow"]
+    by_source = {
+        "local": {"requests": len(local_hist), "tokens": sum(h["tokens"] for h in local_hist),
+                  "costYuan": round(sum(h["costHi"] for h in local_hist), 4),
+                  "flowRequests": len(local_flow),
+                  "flowCostYuan": round(sum(h["costHi"] for h in local_flow), 4),
+                  "chatRequests": len(local_hist) - len(local_flow),
+                  "chatCostYuan": round(sum(h["costHi"] for h in local_hist) - sum(h["costHi"] for h in local_flow), 4)},
+        "proxy": {"requests": len(proxy_hist), "tokens": sum(h["tokens"] for h in proxy_hist),
+                  "costYuanLo": round(sum(h["costLo"] for h in proxy_hist), 4),
+                  "costYuanHi": round(sum(h["costHi"] for h in proxy_hist), 4),
+                  "chargedYuan": round(charged, 4)},
+    }
+    proxy_lo = sum(h["costLo"] for h in proxy_hist)
+    proxy_hi = sum(h["costHi"] for h in proxy_hist)
+    by_model: dict = {}
+    for h in hist:
+        k = h["model"] or "(未知)"
+        e = by_model.setdefault(k, {"reqs": 0, "tokens": 0, "costLo": 0.0, "costHi": 0.0,
+                                    "charged": 0.0, "exactReqs": 0, "cacheHit": 0, "cacheMiss": 0, "output": 0})
+        e["reqs"] += 1
+        e["tokens"] += h["tokens"]
+        e["costLo"] += h["costLo"]
+        e["costHi"] += h["costHi"]
+        e["charged"] += h["charged"]
+        e["exactReqs"] += 1 if h["exact"] else 0
+        for f in ("cacheHit", "cacheMiss", "output"):
+            if h.get(f) is not None:
+                e[f] += int(h[f])
+    cases = [w for w in attr["byCase"].values()
+             if time.strftime("%Y-%m", time.localtime(w["end"])) == month]
+    per_cap: dict = {}
+    for w in cases:
+        e = per_cap.setdefault(w["capability"], {"tickets": 0, "costLo": 0.0, "costHi": 0.0, "tokens": 0,
+                                                "reqs": 0.0, "batched": 0, "exact": True, "terminal": {}})
+        e["tickets"] += 1
+        e["costLo"] += w["costLo"]
+        e["costHi"] += w["costHi"]
+        e["tokens"] += w["tokens"]
+        e["reqs"] += w["reqs"]
+        e["batched"] += 1 if w.get("batched") else 0
+        e["exact"] = e["exact"] and w.get("exact", True)
+        k = w["terminal"] or "(在飞)"
+        e["terminal"][k] = e["terminal"].get(k, 0) + 1
+    attributed = sum(w["costHi"] for w in cases)
+    attributed_lo = sum(w["costLo"] for w in cases)
+    # 可归因池 = 本机流程角色会话 + 代理侧（这些才可能是"为客户干的活"）
+    pool_lo = by_source["local"]["flowCostYuan"] + by_source["proxy"]["costYuanLo"]
+    pool_hi = by_source["local"]["flowCostYuan"] + by_source["proxy"]["costYuanHi"]
+    for cap, e in per_cap.items():
+        n = max(1, e["tickets"])
+        e["yuanLoPerTicket"] = round(e["costLo"] / n, 4)
+        e["yuanHiPerTicket"] = round(e["costHi"] / n, 4)
+        e["avgTokensPerTicket"] = e["tokens"] // n
+        e["avgReqsPerTicket"] = round(e["reqs"] / n, 1)
+    return {
+        "month": month, "pointsPerYuan": POINTS_PER_YUAN,
+        "requests": len(hist), "tokens": sum(h["tokens"] for h in hist),
+        "costYuanLo": round(total_lo, 4), "costYuanHi": round(total_hi, 4),
+        "chargedYuan": round(charged, 4), "chargedPoints": round(charged * POINTS_PER_YUAN, 2),
+        "bySource": by_source,
+        # 票据成本 vs 角色开销：稳定运行后 overhead 应远小于 attributed；若反了，说明
+        # 要么票窗口没覆盖到真实工作会话，要么角色在票据之外空转（两种都要查）。
+        "attributedYuanLo": round(attributed_lo, 4), "attributedYuanHi": round(attributed, 4),
+        "flowPoolYuanLo": round(pool_lo, 4), "flowPoolYuanHi": round(pool_hi, 4),
+        "overheadYuanLo": round(max(0.0, pool_lo - attributed_lo), 4),
+        "overheadYuanHi": round(max(0.0, pool_hi - attributed), 4),
+        "marginLo": round(charged / proxy_hi, 3) if proxy_hi else None,     # 最保守：成本取上界
+        "marginHi": round(charged / proxy_lo, 3) if proxy_lo else None,     # 最乐观：成本取下界
+        "exactRequests": sum(1 for h in hist if h["exact"]),
+        "instrumentedRequests": sum(1 for h in hist if h["cacheHit"] is not None),
+        "byModel": by_model, "perCapability": per_cap, "ticketsCounted": len(cases),
+        "note": ("两条腿：**本机**（会话日志逐次用量 × 权威费率，精确）＋**代理**（服务端 costYuan，"
+                 "2026-09-22 起精确；更早的封顶行只有上界）。每票成本 = 该票窗口内的**流程角色会话**"
+                 "消耗按票摊分（对话/开发会话不计入），窗口重叠按批摊分。"),
+    }
+
+
+def render_report(s: dict) -> str:
+    loc = s.get("bySource", {}).get("local", {})
+    px = s.get("bySource", {}).get("proxy", {})
+    L = [f"  模型成本锚点（{s['month']}）",
+         f"  真实成本合计：¥{s['costYuanLo']:.2f} ～ ¥{s['costYuanHi']:.2f}"
+         f"｜请求 {s['requests']} 次｜tokens {s['tokens']:,}",
+         f"    本机（会话日志，精确）：¥{loc.get('costYuan', 0):.2f}"
+         f"｜{loc.get('requests', 0)} 次（流程角色 {loc.get('flowRequests', 0)} / 对话 {loc.get('chatRequests', 0)}）",
+         f"    代理（服务端 costYuan）：¥{px.get('costYuanLo', 0):.2f} ～ ¥{px.get('costYuanHi', 0):.2f}"
+         f"｜{px.get('requests', 0)} 次｜收费 ¥{px.get('chargedYuan', 0):.2f}"
+         f"（毛利 {(s['marginLo'] or 0):.2f}× ～ {(s['marginHi'] or 0):.2f}×）",
+         f"    票据窗口内 {s.get('attributedYuanLo', 0):.2f} ～ {s.get('attributedYuanHi', 0):.2f}"
+         f"｜窗口外角色开销（调度/巡检/开发）{s.get('overheadYuanLo', 0):.2f} ～ {s.get('overheadYuanHi', 0):.2f}",
+         "  " + "-" * 96]
+    for m, v in sorted(s["byModel"].items(), key=lambda x: -x[1]["costHi"]):
+        L.append(f"    {m:20} {v['reqs']:>5} 次｜{v['tokens']:>11,} tokens"
+                 f"｜成本 ¥{v['costLo']:.2f}～{v['costHi']:.2f}｜收费 ¥{v['charged']:.2f}"
+                 f"｜精确 {v['exactReqs']}/{v['reqs']}")
+        if v["cacheHit"] or v["cacheMiss"] or v["output"]:
+            L.append(f"    {'':20} 缓存命中 {v['cacheHit']:,}｜未命中 {v['cacheMiss']:,}｜输出 {v['output']:,}")
+    if loc:
+        L.append(f"    （本机流程角色会话成本 ¥{loc.get('flowCostYuan', 0):.2f}；"
+                 f"对话/开发会话 ¥{loc.get('chatCostYuan', 0):.2f} 不计入票据成本）")
+    L.append("  " + "-" * 96)
+    L.append("  按能力的**每票真实成本**（= 定价下限锚；含失败票，失败也烧 token）：")
+    for cap, v in sorted(s["perCapability"].items(), key=lambda x: -x[1]["tickets"]):
+        rng = (f"¥{v['yuanLoPerTicket']:.3f}" if v["exact"] else f"≤¥{v['yuanHiPerTicket']:.3f}")
+        L.append(f"    {cap:16} 票 {v['tickets']:>3}｜每票成本 {rng:>9}"
+                 f"｜{v['avgTokensPerTicket']:>9,} tokens｜{v['avgReqsPerTicket']:>5} 请求/票"
+                 f"｜同批 {v['batched']}｜终态 {v['terminal']}")
+    L.append("")
+    L.append("  ⚠️ " + s["note"])
+    return "\n".join(L)
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="每票/每日真实模型成本（定价锚点）")
+    ap.add_argument("--pull", action="store_true", help="从服务端拉积分流水（增量去重）")
+    ap.add_argument("--report", action="store_true")
+    ap.add_argument("--month", help="YYYY-MM（缺省=当月）")
+    ap.add_argument("--ledger", default=str(DEFAULT_LEDGER))
+    ap.add_argument("--pages", type=int, default=20, help="--pull 最多翻多少页（每页 200 条）")
+    ap.add_argument("--json", action="store_true")
+    ap.add_argument("--pull-rates", action="store_true", help="只刷新权威费率表")
+    ap.add_argument("--no-local", action="store_true", help="忽略本机会话用量（只看代理侧）")
+    ap.add_argument("--snapshot", action="store_true", help="把当日快照追加到 usage/daily.jsonl（供定时器积累趋势）")
+    a = ap.parse_args(argv)
+
+    if a.pull_rates:
+        pull_rates()
+        return 0
+    if a.pull:
+        pull_rates()
+        n = pull(a.pages)
+        scan_local()
+        if n < 0:
+            return 1
+        # ⚠️ 采集完必须继续走下面的"算 + 落快照"：早期版本在这里直接 return，
+        # 于是定时器每天只采集、**从不写快照**（daily.jsonl 永远停在手动那一次）。
+        if not a.snapshot:
+            return 0
+    month = a.month or time.strftime("%Y-%m")
+    doc = load_registry()
+    rates = load_rates()
+    hist = load_history(HISTORY)
+    if not a.no_local:
+        hist = hist + load_local(rates)
+        hist.sort(key=lambda x: x["ts"])
+    attr = attribute(load_cases(pathlib.Path(a.ledger).expanduser(), doc), hist, doc)
+    s = summary(attr, month, doc)
+    USAGE.mkdir(parents=True, exist_ok=True)
+    (USAGE / f"{month}-cost.json").write_text(json.dumps(s, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    if a.snapshot:
+        # 逐日追加（同一天只保留最后一条），供"跑一段时间"后看趋势/回归
+        line = {"date": time.strftime("%Y-%m-%d"), "month": month, "requests": s["requests"],
+                "costYuanLo": s["costYuanLo"], "costYuanHi": s["costYuanHi"],
+                "costYuan": s["bySource"]["local"]["costYuan"] + s["bySource"]["proxy"]["costYuanHi"],
+                "localFlowCostYuan": s["bySource"]["local"]["flowCostYuan"],
+                "chargedYuan": s["chargedYuan"], "attributedYuanHi": s["attributedYuanHi"],
+                "overheadYuanHi": s["overheadYuanHi"], "tickets": s["ticketsCounted"],
+                "perCapability": {k: {"tickets": v["tickets"], "yuanHiPerTicket": v["yuanHiPerTicket"]}
+                                  for k, v in s["perCapability"].items()}}
+        daily = USAGE / "daily.jsonl"
+        keep = []
+        if daily.exists():
+            keep = [l for l in daily.read_text(encoding="utf-8").splitlines()
+                    if l.strip() and json.loads(l).get("date") != line["date"]]
+        daily.write_text("\n".join(keep + [json.dumps(line, ensure_ascii=False)]) + "\n", encoding="utf-8")
+        print(f"  （快照追加：{daily}）")
+    if a.json:
+        print(json.dumps(s, ensure_ascii=False, indent=2))
+    else:
+        print(render_report(s))
+        print(f"  （快照：{USAGE / (month + '-cost.json')}）")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())