KevinClaw / VER14：API Latency Observability 上線後全域架構變更與除錯 (DEBUG) 歷程總覽報告

報告環境標註：NB 開發環境 (VER14_NB)
基線時間節點：2026-08-02 ~ 2026-08-03（Provider-Neutral API Latency Observability Phase 0–7B 結案）
統計區間：2026-08-03 至 2026-08-22
目的：系統性彙整自「端到端延遲可觀測性 (Latency Observability)」上線以來，平台的十大核心架構演進、重大除錯修復 (Debug Fixes) 與實際落地成果。

🧭 目錄 (Table of Contents)

1. 起點回顧：API Latency Observability 體系建立 (2026-08-02 ~ 2026-08-03)
2. 重大架構變更與功能演進摘要 (Top Architecture Evolutions)
   • 2.1 雙引擎資料庫 MySQL Production Hardening 與 Parity
   • 2.2 平台級速率限制子系統 (Platform Rate Limiting Subsystem – RL0 ~ RL1)
   • 2.3 專案控制平面 (Project Foundation P0 ~ P1) 與主機救援模式 (Host Rescue Mode)
   • 2.4 開源安裝引導 (Setup Wizard) 與 MCP 工具生態大幅擴充
   • 2.5 多供應商原生 Token 計量、生成速度 (Throughput) 與分析報表
   • 2.6 工作區線上編輯器 (Preview Editor) 與原子寫入防護
   • 2.7 AI Provider 能力治理、原生工具流統一與推論模型支援
   • 2.8 自動化排程器 (Scheduler) 現代化與即時編輯 Modal
   • 2.9 前端渲染一致性升級 (LaTeX / KaTeX / Mermaid / 表格修復)
   • 2.10 雙開發環境 (NB / PC) 融合與檔案上傳容量升級 (26MB)
3. 核心除錯與疑難排解全記錄 (Comprehensive Debug Highlights)
4. 架構演進效益與關鍵量化成果對照表
5. 總結與未來展望 (Summary & Next Steps)

1. 起點回顧：API Latency Observability 體系建立 (2026-08-02 ~ 2026-08-03)

🎯 變更目的與核心目標

在 VER14 系統支援多 Provider (OpenAI, Anthropic, Gemini, Ollama, OpenRouter) 與複雜 MCP 工具調用後，串流卡頓、首字延遲高及各環節耗時不明確等問題亟待量化分析。建立 無 Provider 偏見、無破壞性（Provider-Neutral & Non-Breaking）的端到端 API 延遲可觀測性框架。

🏗️ 架構設計

1. 樹狀階層 Span (Hierarchical Span Lineage Tree)：以 LatencyTrace 為根，動態分派 child_span()，涵蓋 Route、Prepare、Provider Request、MCP Tool 及 Subsystem。
2. ContextVar 輕量傳播：利用 Python contextvars.ContextVar 跨非同步協程與線程傳遞 Trace Context，單次記錄開銷小於 0.1ms。
3. 確定性一致性抽樣：透過 SHA-256(trace_id) Hash Bucket 實現請求全鏈路一致採樣或丟棄。
4. 管理後台可視化與獨立分析器：新增 /api/admin/latency-traces 控制台與 scripts/analyze_latency_traces.py 分析工具。

🚀 重大突破：首刷立即 Flushing (First Fragment Immediate Flush)

在 Phase 7B 5-Sample 生產採樣中，發現 OpenRouter 串流下模型已於 4.02 秒產出首個 Token，但 UI 直到 21.64 秒才顯示文字（等待緩衝滿 800 字元）。實施首個有效內文區塊無條件立即發射優化後，首字可見時間由 21.6 秒大幅降至毫秒級。

2. 重大架構變更與功能演進摘要 (Top Architecture Evolutions)

自 Latency Observability 結案後，VER14 平台在資料庫、安全性、執行隔離、模型生態及前端交互等維度進行了全面升級：

timeline
    title VER14 架構演進里程碑 (2026-08-03 至 2026-08-22)
    2026-08-03 : Latency Observability 全域結案 : 首刷立即 Flush 優化
    2026-08-07 : 雙引擎 MySQL Parity 硬化 : 確立 MySQL Production Backend : 備份恢復演練
    2026-08-08 : 平台級速率限制 (RL0~RL1) : Text Chat Canary 上線 : Rate Limit Admin UI
    2026-08-09 : 專案控制平面 P0 上線 : Workspace 作用域綁定 : Channel 身份映射
    2026-08-13 : 主機救援模式 (Host Rescue HR0~HR3) : 單一對話截圖 : 排程執行按鈕動態化
    2026-08-15 : 開源 Setup Wizard : MCP 工具生態 (Fugle/TWSE/Chart) : UTF-8 串流防破失
    2026-08-16 : 精確 Token 計量與 Throughput : ai_token_usage_logs 表 : 速度排行報表
    2026-08-17 : 工作區 Markdown 線上編輯器 : 原子寫入服務 : ETag Revision 防衝突
    2026-08-21 : AI Provider 能力動態閘道 : OpenAI/Anthropic 原生工具流統一 : 推論思考模型動態過濾
    2026-08-22 : 排程即時編輯 Modal : 歷史對齊 LaTeX/Mermaid : 雙環境融合 (NB/PC) : 上傳上限 26MB

2.1 雙引擎資料庫 MySQL Production Hardening 與 Parity

• 變更目的：解決 SQLite 在多使用者、多通道並發寫入時的資料庫鎖定瓶頸，將 MySQL 確立為正式生產環境核心後端，並保持雙引擎契約一致。
• 改善目標與架構實作：
  1. 全 Repository MySQL Parity：重構 IdentityRepository、WorkspaceRepository、SchedulerRepository、MediaJobRepository、OfficeJobRepository、ModelRoutingRepository、ExecutionPolicyRepository 與 ExecutionRunRepository，完全消除對 SQLite 的硬編碼依賴。
  2. MySQL Shim 相容性層：自動轉換 SQLite ON CONFLICT 語法為 MySQL ON DUPLICATE KEY UPDATE，以及適配 PRAGMA table_info。
  3. 嚴格安全與測試契約：建立獨立 MySQL 測試憑證與資料庫，禁止在 MySQL 發生錯誤時靜默降級 (Silent Fallback) 為 SQLite。
  4. MySQL 自動備份與災難演練：支援自動 MySQL Dump 備份機制與 .sql.partial 寫入校驗。
• 成果：完成 MySQL 上線切換，達成 100% 雙引擎架構契約一致性，顯著提升高並發寫入穩定性。

2.2 平台級速率限制子系統 (Platform Rate Limiting Subsystem – RL0 ~ RL1)

• 變更目的：防止單一使用者或外部 API 用戶過度調用消耗 API Key 配額，建立獨立於 Provider 配額的平台級流量控制與防護。
• 改善目標與架構實作：
  1. RL0 靜態核心與契約分離：明確區分「平台速率限制 (Platform Rate Limit)」與「上游供應商配額 (Provider Quota)」，採單使用者單一 Tier 契約與原子生命週期。
  2. RL1 Text Chat Canary 驗證：針對真實使用者 it_mes_user 進行 Canary 灰度放量驗證，確認 429 拒絕響應與 Trace 審計正常。
  3. Rate Limit Admin Control Center：後台提供視覺化 Tier 分配、即時審計日誌 (ai_rate_limit_audit_logs) 與 HTTP Ingress 攔截。
• 成果：平台具備毫秒級多維度速率限制能力，有效防止惡意請求與意外並發風暴。

2.3 專案控制平面 (Project Foundation P0 ~ P1) 與主機救援模式 (Host Rescue Mode)

• 變更目的：建立多租戶、多專案的隔離環境邊界，並為 Windows 伺服器運維提供嚴格審計的救援模式。
• 改善目標與架構實作：
  1. Project P0 Foundation：引入 Project 核心實體、ProjectRepository，支援 Personal Project 自動配置與歷史對話/工作區關聯回填 (Backfill)。
  2. 專案管理 UI 與 API：提供專案建立、成員權限配置與作用域切換。
  3. 通道身份映射 UI：支援 Telegram、WordPress 客服等通道與內部帳號動態綁定。
  4. 主機救援模式 (Host Rescue Mode HR0 ~ HR3)：為 Platform Admin 提供受控的 Windows 主機維運工具，具備即時審計日誌與嚴密路徑白名單。
• 成果：奠定多專案資源隔離與安全邊界基石，消除跨工作區污染風險。

2.4 開源安裝引導 (Setup Wizard) 與 MCP 工具生態大幅擴充

• 變更目的：簡化開源部署難度，降低初次安裝門檻，並擴展金融、圖表與文檔解析能力。
• 改善目標與架構實作：
  1. setup_wizard.py 開源配置引導：整合雙引擎 MySQL / SQLite 一鍵選擇與 initialize_runtime_database_schema() 自動建表。
  2. MCP 工具鏈矩陣擴充：
     • Fugle Market Data MCP & TWSE OpenAPI MCP：即時台股行情與公開財務報表解析。
     • Chart MCP (chat_mcp_server)：支援 Agent 動態生成專業統計圖表。
     • Obsidian MCP Server：實現知識庫筆記雙向讀寫與長期記憶整合。
     • AnyDoc MCP v2 Pipeline & PaddleOCR：強化 PDF/Word/Excel 及圖片文檔光學字元識別。
  3. MCP 序列化自動啟動 (Autostart Serialization)：解決多個 MCP Server 併發啟動競爭導致超時失敗的問題。
• 成果：擴充至 14 種 MCP 服務，大幅提升 Agent 在金融分析、數據繪圖與知識庫管理方面的實戰能力。

2.5 多供應商原生 Token 計量、生成速度 (Throughput) 與分析報表

• 變更目的：解決各大 LLM 串流返回 Token 不一致、舊版估算不準確且無法統計生成吞吐量的痛點。
• 改善目標與架構實作：
  1. 多供應商原生 Usage 提取：
     • OpenAI / OpenRouter：提取 stream_options.include_usage。
     • Google Gemini：提取 usageMetadata (promptTokenCount, candidatesTokenCount)。
     • Anthropic：提取 message_start / message_delta.usage。
     • Ollama Local/Cloud：提取 eval_count 與 prompt_eval_count。
  2. 純模型生成時間 ($T_{gen}$) 與吞吐量 ($text{tok/s}$) 計算：精確扣除路由、搜尋與工具執行耗時，計算純模型串流生成速度。
  3. 資料庫持久化與管理報表：
     • 建立 ai_token_usage_logs 表，於 save_message() 自動寫入。
     • 開放 /api/analytics/token-usage API 與後台日/週/月統計圖表與 Model 速度排行榜。
     • 修復排程器 (Scheduler) 與 Agent 模式下的 Token 追蹤與持久化。
• 成果：實現 100% 精準的 Token 統計與模型速度量化監控，徹底告別字數估算時代。

2.6 工作區線上編輯器 (Preview Editor) 與原子寫入防護

• 變更目的：讓使用者能在 Universal Client 與 Web 預覽面板直接編輯 .md 與 .txt 檔案，同時確保資料一致性與防寫入衝突。
• 改善目標與架構實作：
  1. 原子寫入服務 (PreviewEditorService)：實現安全暫存檔寫入與原子重命名替換，防止寫入中斷導致檔案毀損。
  2. Revision (ETag) 樂觀鎖防衝突機制：編輯前鎖定版本號，若多端併發修改或檔案已被外部變更則拒絕覆寫並提示衝突。
  3. 非 Unicode Payload 攔截與路徑沙盒校驗：阻擋惡意編碼與跨越 Workspace 沙盒的非法路徑。
  4. 編輯器 UX 優化：支援 Ctrl+S 快捷儲存、即時 Diff 行數統計與「預覽 👁️ / 編輯 ✏️」雙模式切換。
• 成果：建立高可靠的工作區文字線上編輯工作流，保障文檔寫入安全。

2.7 AI Provider 能力治理、原生工具流統一與推論模型支援

• 變更目的：統一多 Provider 的 Agent 工具調用架構，適配 DeepSeek R1 / Kimi 等最新思考推論模型，並消除 Provider 之間的協議差異。
• 改善目標與架構實作：
  1. Provider Capability Gate (能力閘道)：跨進入點集中動態校驗 Provider 與 Model 的能力（Text, Vision, Tools, Reasoning, Audio, Video），防止無效請求打入上游。
  2. 原生 Agent 工具調用統一 (Native Agent Tools)：
     • 統一 OpenAI-Compatible 原生 Agent Tools。
     • 實作 Anthropic 原生 Agent Tools。
     • 支援安全並行工具調用 (Safe Parallel Tool Execution)。
  3. 推論思考模型動態過濾 (Reasoning Filter & Provider-Aware Gate)：
     • 動態查詢 ModelCapabilityService 能力表，自動適配思考模型與 Delta 雙欄位解析（如 reasoning_content 與 thought 標籤）。
     • 修復 Kimi / DeepSeek 串流思考過程換行排版與格式異常問題。
  4. Provider Live Canary Gate：建立安全的 Provider 生產級 Canary 驗證與自動除帳機制。
• 成果：全面支援最新主流思考模型，大幅降低 Agent 多輪工具調用的失敗率。

2.8 自動化排程器 (Scheduler) 現代化與即時編輯 Modal

• 變更目的：提升背景排程任務的穩定性、可視性與管理靈活性。
• 改善目標與架構實作：
  1. 排程執行按鈕動態化：點擊「執行一次」時，UI 按鈕即時動態切換為「背景執行中」狀態，避免重複觸發。
  2. 卡住任務自我修復 (Stuck Run Cancellation & Auto Recovery)：背景自動監測超時或異常中斷的執行緒並釋放鎖定狀態。
  3. Schedule Edit Modal (2026-08-22)：
     • 新增前端彈出式排程編輯視窗。
     • 支援即時 Cron 表達式語法解析與繁體中文語意回饋（如 每週一至週五 08:30）。
     • 提供後端 /api/scheduler/update 端點，支援即時更新排程 Prompt、模型、Cron 與狀態。
  4. TTFT 延遲採樣修復：修復非串流 Agent 模式下的首輪首字延遲 (TTFT) 採樣打點。
• 成果：排程系統達到企業級可用性，操作回饋清晰流暢。

2.9 前端渲染一致性升級 (LaTeX / KaTeX / Mermaid / 表格修復)

• 變更目的：解決歷史對話載入與即時串流渲染效果不一致、數學公式及圖表解析失敗的顯示瑕疵。
• 改善目標與架構實作：
  1. 歷史對話渲染對齊：統一 Markdown 渲染管道，使重新整理後的歷史訊息與即時串流擁有一致的排版。
  2. KaTeX 數學公式與 LaTeX 符號深度支援：正確渲染行內 $ ... $ 與塊級 $$ ... $$ 數學公式。
  3. Mermaid 圖表自動容錯與修復：新增 Mermaid 語法自動清理器 (Sanitizer)，遇到異常語法時平滑降級顯示代碼，避免前端白屏崩潰。
  4. 縮排 Markdown 表格空行自動補齊：解決多層縮排或列表中的表格被錯誤當成純文字的問題。
  5. Diff 紅綠高亮與快捷比較按鈕：對話中的 Code Diff 自動渲染紅綠高亮，並提供一鍵比對檔案徽章。
• 成果：前端對話與工作區文檔的渲染表現達到極高質感與穩定度。

2.10 雙開發環境 (NB / PC) 融合與檔案上傳容量升級 (26MB)

• 變更目的：整合筆電 (NB) 與桌機 (PC) 雙環境的客製化調整，並滿足用戶傳輸較大檔案的需求。
• 改善目標與架構實作：
  1. 雙環境代碼與配置融合 (Merge)：
     • 合併 PC 環境的 Ollama 32k num_ctx VRAM 配置、MCP venv 路徑修正及資料庫探索 Prompt 優化。
     • 建立標準的雙環境 Git 同步與除錯文檔歸檔規範（NB 存於 docs/debug/ 根目錄，PC 存於 docs/debug/PC_VER14/）。
  2. 上傳容量解耦升級 (2026-08-22)：將沙盒與聊天對話最大上傳檔案容量限制自 16MB 正式提升至 26MB，並建立全域解耦配置。
• 成果：雙端環境保持高度同步，支援更大體積的檔案傳輸與分析。

3. 核心除錯與疑難排解全記錄 (Comprehensive Debug Highlights)

在上述架構推進過程中，團隊針對多個關鍵 Bug 進行了深度診斷與修復，詳細記錄於 docs/debug/：

4. 架構演進效益與關鍵量化成果對照表

5. 總結與未來展望 (Summary & Next Steps)

自 API Latency Observability 架構上線以來，kevinclaw / VER14 專案經歷了從「可觀測性建立」、「核心資料庫硬化 (MySQL)」到「平台級治理 (Rate Limit, Project P0, Provider Capabilities, Token Analytics)」的全面躍升。

系統不僅徹底解決了串流延遲、多字節亂碼、併發鎖定與 Token 估算不精確等歷史問題，更構建了高可靠、可擴展且具備自我修復能力的現代化 AI 智能體平台架構。

🔮 未完成與未來發展藍圖 (Future Plans & Roadmap)

1. Multi-Agent Workflow Modernization Revision v2：
   • 推進 Planner、Coordinator、Workflow Repository 與 Reviewer 狀態機落地。
2. Realtime Voice Gateway (Stage 3/4)：
   • 評估語音模型選型，落實 Realtime session lease 與 Voice Tool Bridge 橋接。
3. 長對話智慧 Context 壓縮 (Context Compression)：
   • 超越固定輪次滑動視窗，實作自動化語意摘要壓縮機制。
4. Web & Desktop 混合工作區執行 (Solution 1 & 2)：
   • Client-Side Local Workspace 混合執行模式。
5. 自動化 macOS GitHub Actions 打包工作流：
   • 完成跨平台建置與發布自動化。

本報告由 Antigravity 依據專案真實 Git 歷程、docs/debug/、docs/audits/ 與 Obsidian 記憶庫編制而成。