docs: register llm_calls telemetry schema in wiki

research-wiki/schemas/llm-calls.md

@@ -0,0 +1,36 @@
+---
+type: schema
+node_id: schema:llm-calls
+title: "表结构: llm_calls(遥测 18 字段)"
+date: 2026-07-20
+---
+
+# 表结构: llm_calls(遥测 18 字段)
+
+
+## 列定义(冻结,M1 设计 §4.4 / ARCH §7.8)
+
+| 列 | 类型 | 说明 |
+|---|---|---|
+| call_id | TEXT PRIMARY KEY | 每次尝试独立 UUID;INSERT OR IGNORE 幂等 |
+| parent_call_id / session_id | TEXT | 调用链路(agent step → LLM call) |
+| model / provider / source_name | TEXT NOT NULL | 溯源;model 由旧 Protocol 的 model_name 更名(VT 迁移 §8) |
+| messages / response / thinking | TEXT NOT NULL | messages 落库前多模态 part 摘要(与缓存 key 共用 digest_messages) |
+| prompt_tokens / completion_tokens | INTEGER NOT NULL | usage 帧;缺失按 est 兜底 |
+| usage_source | TEXT NOT NULL | measured / estimated |
+| latency_ms | INTEGER NOT NULL | 尝试耗时;缓存命中 0 |
+| ttft_ms / max_inter_token_ms | REAL | 流式活性测量 |
+| cache_hit | INTEGER NOT NULL DEFAULT 0 | 命中标记 |
+| error | TEXT | 异常信息;取消记 "cancelled" |
+| cost | REAL | M1 恒 NULL,M2 pricing 换算 |
+| created_at | TEXT NOT NULL DEFAULT (datetime('now')) | 落库时刻 |
+
+## 埋点位置(单一 helper 铁律)
+
+- `middleware/telemetry.py::TelemetryEmitter` 是全库**唯一** `record_llm_call` 调用点;
+- `TelemetryMW`(最外层)记缓存命中与最终失败;`RetryMW._emit` 经同一 Emitter 逐次记尝试;
+- 写失败降级 warning 不冒泡;取消路径 finally 尽力记录。
+
+## 评估基线
+
+首版无历史基线,标"待首次运行后建立";验收断言: 单测覆盖成功/失败/缓存命中/取消四路径各产生恰一行;并发 50 协程写全落库。