kitt-stt 的 Agent 驗證與效能分析平台

最值得導入的是一個完整的驗證流程：agent 能找到功能、啟動自己的服務、以正式協定驅動、保存原始證據，再讀取小型結構化結果。kitt-stt 已有大部分工具；目前的問題是這些工具分散，功能測試、效能量測與 trace 的界線沒有在同一入口說清楚。

本次已在獨立 worktree 導入專案內的 verify-kitt-stt skill、Docker 證據出口、既有硬體 profiler 的整合，以及 Perfetto SQL 查詢。圖表沿用既有工具，沒有新增 observability server 或修改 STT 推論邏輯。這是一個可執行的平台起點，尚不是自動判定效能回歸或自主調參的系統。

研究基準為本機 main 的 67160fab；分支為 research/agent-verification-20260912，目錄為 隔離研究工作樹。外部來源查閱日期為 2026-09-12。下文區分程式已提供的能力、實跑結果與尚未實作的建議。

1. pstack 哪些流程值得採用

這裡的 pstack 指 Cursor 公開的工程 workflow 集合。它的價值是把工作拆成有證據門檻的流程；不同 playbook 的交付物不同，不能用同一個「測試綠燈」代替所有結論。¹

上述流程分別來自建立／維護 skill 與各 playbook。²³⁴⁵⁶⁷ 採用的是驗證原則；pstack 的特定編輯器安裝方式、模型配置、開 PR／合併流程不會自動成為這個 repo 的操作授權。

對 agent 最重要的介面是「給定問題，應執行哪一條命令；結果在哪裡；哪些數字能支持結論」。讓它看懂更多圖像有幫助，但若缺少輸入雜湊、量測邊界、樣本數與退出狀態，一張漂亮圖表仍然容易導致錯誤歸因。

2. 目前 repo 已經有哪些能力

flowchart TD
    A[Feature map：選擇功能與證據] --> B[Docker harness：獨立 image / container / localhost port]
    B --> C[Doctor：health / build / model / target]
    C --> D[Live tests：真實 WAV + WS frames]
    D --> E{功能是否通過}
    E -->|是，且要求效能量測| F[既有 hardware_profile：bulk + realtime]
    E -->|否，或不做效能量測| G[保留退出碼與證據]
    F --> G
    G --> H[確認 driver 結束後的新 trace 快照]
    H --> I[停止並匯出 logs / config / trace]
    I --> J[清除本次 container ID]
    J --> K[JSON / CSV 給 agent；HTML / Perfetto 給人]

因此，新增另一套 benchmark driver 或另一套 chart renderer 的收益不高。先把既有資料保存、標記邊界，再提供可查詢形式，能以較小改動讓下一個 agent 直接使用。

3. 指標必須先定義量測邊界

hardware_profile.py 的 HTML 另把 server_rtf × duration_s 顯示為累計運算時間。它是由比值回推的量，不是新的端到端量測，而且報表 duration_s 與服務端包含 preroll 的有效音訊分母可能不同。需要精確分解時，讀 final metrics 或 trace 的原始時間。

EOT 尤其需要獨立處理。src/eot.py:apply 的 WAIT 可以先送 final text，再繼續等待；COMMIT 有 final 時把 EOT metadata 附在 transcription，沒有 final 時才送明確的 semantic stop。只看「收到 final」或某個 stop callback，無法證明使用者的 turn 已正確結案。

4. 需要補哪些指標與圖表

以下是後續增量的優先順序。只有表中的第一列已在本次導入；其餘是有來源落點的建議。

建議的比較最小單位是「固定一個 workload cell」。例如同一 6 秒音訊、realtime、單座位、相同暖機、同一模型與 provider，先做多次獨立 baseline，再交錯跑 A／B。不同長度或 bulk／realtime 不可混成一個 p95。三輪可作為初步穩定性檢查，但不是統計充分性的保證；尾端指標需要更多樣本與跨輪穩定性。

圖表應由原始資料產生並保留 CSV。對 agent，先給每個 cell 的 JSON 摘要與查詢入口；對人，提供可縮放的 latency／RTF／interim 曲線，再在需要比較時補分布圖。沒有足夠樣本時，圖與文字都標成 smoke measurement。

5. 工具選擇

Perfetto 官方文件已直接提供 AI workflow 與 Trace Processor 的 SQL 介面；現有 Chrome JSON trace 可由 CLI 載入，無需先自製另一套 trace database。⁸⁹ 本次 SQL 額外保留 track 與 final／interim phase，輸出樣本數、平均、p50、p95、最大值以及 counter 和匯入診斷。

py-spy 能輸出火焰圖、speedscope 或 raw 資料，也支援部分平台的 native stack。¹⁰ Memray 的 run 適合從 process 開始取 allocation profile；native mode 回答的問題比 RSS 數字更深入，但也會增加觀測成本。¹¹ Nsight Systems 提供 CUDA 與系統時序，應在 GPU 假說明確時使用。¹² 三者都未在本次安裝或執行，不能把它們寫成已得到的診斷證據。

6. 本次實際導入

6.1 一個可重跑的入口

在專案內新增 .agents/skills/verify-kitt-stt/，有 Launch、Doctor、Drive、Evidence、Cleanup、Helpers，並列出 streaming ASR、wake、manual control、forced stop、connection logs 五個功能。skill 裡的命令可直接在這個 worktree 執行，不依賴原先 workspace 共用文件的固定 checkout。

tests/docker-test.sh 增加兩個 opt-in 參數：

EVIDENCE_DIR=/path/to/local-evidence PROFILE_LENGTHS=3,6 \
  IMAGE=kitt-stt:my-verification HOST_PORT=9317 \
  LIVE_TEST_TARGET=tests/functional/live/test_btn_control.py \
  ./tests/docker-test.sh --build -k test_btn_activate

指定全新目錄後才收集證據。PROFILE_LENGTHS 啟用既有硬體 profiler；不指定則維持功能驗證。快取音檔必須存在，避免原本的音檔 generator 在不知情時呼叫外部 TTS。skill 提供以 repository WAV 產生 3／6 秒測試片段的本機步驟。

6.2 證據與失敗語意

Manifest 記錄 Git revision、工作樹狀態、來源檔雜湊、命令、host 與參數；另保存 ASR 模型／輸入 WAV 雜湊、有效設定、實際 image ID 與 port binding。原有 profiler 即使有 timeout row 仍可能 exit 0，因此 wrapper 會讀回 JSON，拒絕錯誤列或缺失／非有限的數值。

容器由 docker create 回傳的 ID 管理。每次 provider attempt 有自己的 artifact 目錄；收集與停止之後才 remove 該 ID。測試失敗保留原 nonzero code；若功能本來成功但證據匯出失敗，整次驗證仍為 nonzero。這些契約已有獨立的可執行檢查，Docker 替身只用來測 harness 的成功／失敗／copy error 路徑；STT 功能驗收則使用真實服務。

6.3 實跑才發現的 shutdown 邊界

src/server.py:322 設定 tracing signal handler，但 src/html_server.py:89 的 serve() 會透過 event loop 重新註冊 SIGINT／SIGTERM。第一次 capture 實際只看到 shutting down ...，沒有 Final trace flushed。Tracing threads 為非 daemon；不能把 docker stop 當成已完成最後 flush 的證據。

本次保留服務端程式，讓收集器在 driver 結束後確認兩次新的週期 trace 寫入，再停止容器。第二次寫入排除第一個 snapshot 在 driver 結束前已開始序列化的可能。capture.json 分別記錄 snapshot_after_driver_exit 與 final_flush_logged；後者可以是 false，前者必須有證據。這增加約兩個 flush interval 的等待，預設最多約 20 秒，另加 Docker 停止等待。

這個做法保留的是已完成 driver 工作的證據，並沒有修好服務端 shutdown。下一個獨立 runtime 修正應讓 trace cleanup 綁在 app.serve() 的生命週期 finally，以避免 signal handlers 互相覆蓋；需要另行驗證正常停止、啟動錯誤與重複 cleanup。它也不會把「driver 提早斷線、尚未 commit 的 turn」變成完整 EOT 測試。

7. 驗證結果與解讀

第一輪已通過單一 control 功能與四個 profile rows，但缺少 final flush 確認，整輪被正確標為失敗，證據仍留在 /path/to/local-evidence。修改收集方式後的完整 skill 重跑使用 /path/to/local-evidence；該輪 exit code 為 0，capture 沒有匯出錯誤，共保留 3,778 events，snapshot_after_driver_exit=true。精確 container ID 的移除與證據留存已核對並寫入 cleanup-check.json。

最後將 health 的純文字回應命名為 health.txt 後，又以同一映像重跑單一 control 功能；證據在 /path/to/local-evidence。該輪 1 passed、5 deselected，exit code 0，317 events 保留，容器已移除。前述完整 profile run 仍保留當時名為 health.json 的原始純文字回應，未改寫歷史證據。本次建立的兩個 image tags 亦已清除；重跑 skill 會重新建置。

測試主機為 RTX 4090，driver 580.173.02。ASR startup path 為 cuda (config default)，有效設定仍使用 CUDA；TurnSense 在其 runtime 中檢查實際 active provider。ASR 的 label／設定不等於逐節點 provider assignment 證據，因此這裡不宣稱每個 ASR operator 都在 GPU。主機同時有其他既存服務，本次沒有獨占 GPU；數字只驗證量測流程。

重播音訊由 say-lock-all.wav 本機重複／裁切，長度為 3 秒與 6 秒；每種 feed 先暖機三次，表中每格只有一次正式樣本。

原始 JSON、CSV 與 互動圖表 同時保存。重點是即時模式有 interim 與可量測的停頓；即使 final latency 只有約 49 ms，6 秒樣本中間仍出現約 2.55 秒的更新間隔，因此「final 很快」不足以描述整體體驗。此現象尚未完成重複實驗與根因歸因。

這不是優化前後比較：兩輪服務端程式相同，不能把其差異歸功於效能改善。暖機、OS 排程、音訊 pacing、共享 GPU 與 callback 行為都可能影響數字。查詢整條 trace 時也會包含功能 case、暖機、bulk 和 realtime，必須保留這個混合 workload 標記。

Perfetto v58.2 能載入本次 trace 並執行 repo SQL，但也報告 trace_sorter_negative_timestamp_dropped（1）和 slice_spill_overlapping_complete_event（3）。第一輪原始資料確認負時間戳來自 server_startup：它的開始時間早於 tracer 自己的 time origin。重疊事件使用相同 logical thread track，不能把畫面上的 nesting 當成真實 CPU call stack。這些警告沒有被刪掉或自動「修正」；分析 startup 與 parent/self-time 時必須先修正輸出語意。

SQL 摘要 與 parser log 保留這些診斷。查詢各 track 後加總的 domain event 數量已與原始 JSON 核對：interim decode 48、final decode 11；這包含暖機與功能測試，並非 4 個正式 profile rows 的樣本數。核對結果在 sql-validation.json。

8. 下一階段如何讓 AI 自主評估

先以目前的入口建立少數代表性 workload：短指令、長句、wake-only、COMPLETE、INCOMPLETE、退出詞以及多座位完全重疊。每個 workload 指定它要觀察的 final／commit／cancel 契約，以及可接受的錯誤率；品質 gate 與效能數字要一起保存。

接著增加 correlation 與多次試驗。每個 observation 至少包含 run ID、connection ID、turn／segment ID、輸入雜湊、feed、長度、座位數、暖機標記、成功／錯誤狀態，以及其時間邊界。再把「前後環境是否相容」做成可檢查的比較前提。當前 manifest 提供追溯材料，但尚未自動阻擋所有不可比的比較。

最後才採用 hillclimb：固定 workload 與品質 gate，提出由 trace 支持的一個假說，每次只改一個因素，保存 before／after／spread／測試結果，決定保留或撤回。若 metric 的波動大於變更效果，就回到量測流程排除干擾，而不是讓 agent 繼續猜測微調。這是本研究建議的最小演進路線。

評估 agent 平台本身

STT latency 是產品指標；驗證平台還需要評估 agent 是否能可靠取得結論。可用固定任務與乾淨 worktree，對比導入前後的操作紀錄，先量下面四項，不把本次導入直接宣稱為 token 或工時節省。

這些指標比新增 agent framework 更能回答「平台是否真的讓 AI 更有效」。目前已驗證的是操作與證據流程；尚未進行盲測的 agent A／B evaluation。

來源

Repository 來源以本工作樹為準：tests/docker-test.sh、tests/verification_evidence.py、tests/verification_trace.sql、tests/functional/live/conftest.py、tests/batch_decode/hardware_profile.py、tests/batch_decode/concurrency_profile.py、src/server.py、src/html_server.py、src/asr/batch_asr_manager.py、src/kitt_stt_service.py、src/eot.py、src/turnsense/runtime.py、utils/perfetto_trace.py、utils/sys_diag.py。