feat(llm): 用量落库 + 只读汇总端点 + 面板用量小卡（契约 v0.64）

- model 层新增可选 UsageSink（nil ⇒ 逐字不变，既有用例零改动）
- 组合根注入 UsageWriter：有界队列 1024 + 单写者 + 批量事务（128/批、2s 兜底），
  队列满丢弃 + 限流 WARN，绝不阻塞模型调用；sink 挂 RuntimeLLM（热重载不断）
- 迁移 0017：表 llm_usage（13 列，session_id 可空）+ idx_created_at + idx_session_id
- 新端点 GET /api/v1/admin/llm/usage（owner|admin 读；缺省近 24h、上限 90 天、
  超限 400 不静默裁剪；hitRate = cacheHit/(cacheHit+cacheMiss)，分母 0 ⇒ 0；
  绝不含凭据与正文；未接线/查库失败 ⇒ 500 usage_unavailable）
- LLM_USAGE_RETENTION（默认 720h，≤0 = 关闭清理）：启动清一次 + 每小时
- 面板 LLM 页「用量（近 24h）」小卡 + Docs 两份同步 v0.64
- 已知缺口（如实登记）：session_id 恒 NULL，需 loop 侧在请求上打标，留列后接

.env.example

@@ -51,6 +51,17 @@ CHAT_DOCUMENT_MAX_BYTES=20971520
 DOCUMENT_GC_INTERVAL=1h
 DOCUMENT_RETENTION=168h
 
+# ---- LLM 用量样本保留期（llm_usage 表；切片 U1，主人裁决「2.4 落」） ----
+# 每次成功模型调用都会把一条**非敏感**用量样本（token 计数 / 缓存两档 / 模型名 /
+# 用途 / 耗时）异步落进 llm_usage 表，供 GET /api/v1/admin/llm/usage 与面板的
+# 用量小卡聚合。**凭据与消息正文绝不入库、绝不进日志**。
+# 写入是有界队列 + 单写者 + 批量事务：队列满就丢弃并限流 WARN，**绝不阻塞模型调用**。
+# LLM_USAGE_RETENTION：保留期（Go duration），默认 720h（30 天）。
+# 启动时清理一次 + 此后每小时清理一次（清扫间隔无 env 键：保留期才是旋钮）。
+# ⚠️ 写 0 或负数 = **关闭清理**（样本全留，日志会写明「llm usage retention disabled」）。
+#    `LLM_USAGE_RETENTION=0` 不是「立即清空」——那种解释会让一次笔误把成本视图清空。
+LLM_USAGE_RETENTION=720h
+
 # ---- 认证 / 管理员 ----
 # JWT_SECRET 必填，长度 >= 32；缺失或过短会在启动时 panic。
 JWT_SECRET=change-me-to-a-random-string-at-least-32-characters