refactor(observability): Phase2.2 成本归因 trace_id列+token日志写入+LLM/MCP/媒体子span [v2026.07.19.3]

VERSION

@@ -3,11 +3,20 @@
 # 版本号格式: vYYYY.MM.DD.N   (年.月.日.当日递增序号，从 1 开始)
 # 环境标签:   prod = 正式版 | test = 测试版
 
-VERSION=v2026.07.19.2
+VERSION=v2026.07.19.3
 ENV=prod
 DATE=2026-07-19
 BASE_IMAGE=qihu-aiflow:with-deps
-BACKUP_IMAGE=qihu-aiflow:backup-20260719-002
+BACKUP_IMAGE=qihu-aiflow:backup-20260719-003
+
+## 本版本变更 (v2026.07.19.3 / prod)
+- Phase2.2 成本归因：token_usage_logs 新增 trace_id 列（迁移 020_add_trace_id_token_usage_logs.sql，幂等 ALTER），打通「链路 -> 成本」归集
+- _write_media_token_log（媒体图片/视频）注入 get_trace_id()，每条媒体 TokenUsageLog 现可回溯到请求链路
+- LogService.log_token_usage 增加 trace_id 参数（为后续文本 LLM token 记账接通成本归因预留）
+- chat_service / chat_media 在 LLM 补全、MCP 工具拉取/调用、技能执行、AGNES 媒体生成处加 span 子链路（async with span），一次请求可下钻耗时分布
+- 注意：_generate_media_task 为后台 fire-and-forget，其 span 会因处于 asyncio.create_task 表达式内而非法，已移除；真实媒体耗时由 chat_media 内 media.agnes_call span 覆盖
+- 纯增量埋点，不改接口返回结构与业务行为；pytest 9 passed + vitest 4 passed 门禁绿
+- 部署前已按 SOP 备份 rollback 点 qihu-aiflow:backup-20260719-003
 
 ## 本版本变更 (v2026.07.19.1 / prod)
 - Phase1 chat.py 巨石拆分收官：10070 行单体拆分为 chat_{utils,media,agents,skill,mcp,context,knowledge,service}.py 共 8 个子模块，controller 层 chat.py 降至 1352 行（<3000 目标达成）

backend/python/app/middleware/log_service.py

@@ -57,7 +57,7 @@ class LogService:
                         app_id: str = None, app_name: str = None,
                         conversation_id: str = None, prompt_tokens: int = 0,
                         completion_tokens: int = 0, total_tokens: int = 0,
-                        cost: float = 0):
+                        cost: float = 0, trace_id: str = None):
         """记录Token消耗日志"""
         db = SessionLocal()
         try:
@@ -73,6 +73,7 @@ class LogService:
                 completion_tokens=completion_tokens,
                 total_tokens=total_tokens,
                 cost=cost,
+                trace_id=trace_id,
             )
             db.add(log)
             db.commit()

backend/python/app/models.py

@@ -537,6 +537,7 @@ class TokenUsageLog(Base):
     app_id = Column(String(36), default=None)
     app_name = Column(String(200), default=None)
     conversation_id = Column(String(36), default=None)
+    trace_id = Column(String(64), default=None)
     prompt_tokens = Column(Integer, default=0)
     completion_tokens = Column(Integer, default=0)
     total_tokens = Column(Integer, default=0)

migrations/020_add_trace_id_token_usage_logs.sql

@@ -0,0 +1,7 @@
+-- Phase 2.2: add trace_id to token_usage_logs for cost attribution (idempotent)
+SET @db = DATABASE();
+SET @col_exists = (SELECT COUNT(*) FROM information_schema.columns WHERE table_schema = @db AND table_name = 'token_usage_logs' AND column_name = 'trace_id');
+SET @sql = IF(@col_exists = 0, 'ALTER TABLE token_usage_logs ADD COLUMN trace_id VARCHAR(64) NULL DEFAULT NULL', 'SELECT 1');
+PREPARE stmt FROM @sql;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;