Auditaur 除錯工作流程
將 Auditaur 作為 Tauri 應用程式除錯的第一道診斷表面。當以代理程式(agent)身分運作時,偏好機器可讀的 JSON 格式。核心心智模型為:Auditaur 觀察應用程式,但不取代應用程式正常的開發命令。
意圖對應表
將常見的使用者短語轉譯為對應的 Auditaur 工作流程:
| 使用者短語 | 代理程式解讀 |
|---|---|
| "觀察應用程式" | 附加到已運行的應用程式並監看就緒狀態。 |
| "以 Auditaur 啟動" / "Auditaur 啟動應用程式" | 當 .auditaur/config.json 存在時執行 auditaur start;否則在 Auditaur 觀察下以 debug run -- <正常命令> 啟動正常的應用程式命令。 |
| "使用 Auditaur 除錯應用程式" | 先檢查就緒狀態,然後檢查日誌/時間線/追蹤/IPC。 |
| "驅動應用程式" / "在應用程式中點擊" | 需要 Tauri 原生驅動橋接,然後使用 auditaur drive。 |
| "執行測試腳本" / "對應用程式進行冒煙測試" | 對已設定的預設腳本執行 auditaur drill,或對命名腳本執行 auditaur drill <名稱>。 |
| "手動核准" / "人類關卡" / "OAuth 同意" | 使用腳本關卡,以便在人類操作完成時保持應用程式工作階段固定。 |
保留應用程式正常的啟動命令。有可用的簡單儲存庫設定流程時,優先使用:
auditaur start
auditaur drill
auditaur inspect
auditaur stop
這些命令預設會讀取 .auditaur/config.json 並共用 .auditaur/session.json,因此代理程式無需自訂包裝器來處理就緒輪詢、工作階段 ID、資料庫路徑或行程清理。
當代理程式需要機器可讀的啟動輸出時,請使用 auditaur start --json。它會輸出一個最終的 JSON 物件,包含確切的應用程式工作階段、行程、選擇器、工作階段檔案路徑以及任何產生的命名連接埠。auditaur stop 會停止記錄的行程樹,並在清理後移除工作階段檔案,使後續命令不會針對已終止的工作階段。
就緒性優先
在讀取日誌或驅動 UI 之前,先確認哪些已就緒:
auditaur debug --app <app-name> --json status
對於正在運行的應用程式,持續監看直到核心遙測就緒:
auditaur debug --app <app-name> --active --json watch --until-ready --timeout-seconds 120
如果任務需要前端遙測,請加上 --require-frontend。如果任務需要 WebView 選擇器操作,請使用 Auditaur 應用程式內驅動橋接:在每個 Auditaur 工作階段的確切一個除錯/測試 WebView 中啟用 initAuditaur({ driveBridge: true }),並在就緒監看命令中加入 --require-drive-bridge。
npm run tauri dev
auditaur debug --app <app-name> --active --require-frontend --json watch --until-ready --timeout-seconds 120
在 Windows PowerShell 上:
npm run tauri dev
auditaur debug --app <app-name> --active --require-frontend --json watch --until-ready --timeout-seconds 120
Auditaur drive 使用 Tauri 原生應用程式內驅動橋接。應用程式必須在每個 Auditaur 工作階段的確切一個除錯/測試 WebView 中明確啟用 initAuditaur({ driveBridge: true }),然後 auditaur drive 會通過該橋接發送有限請求。
啟動應用程式
預設優先使用附加模式:讓開發者、IDE、Tauri 開發伺服器或現有終端機擁有應用程式啟動權,然後使用 auditaur debug watch 觀察就緒狀態。這能保留使用者的正常環境、除錯器、熱重載以及終端機輸出。
僅在代理程式或冒煙腳本需要擁有可重複執行時使用包裝模式。包裝模式仍應透過其正常命令啟動應用程式;Auditaur 觀察該程序,而不是取代應用程式啟動系統。
| 情境 | 偏好模式 |
|---|---|
| 人類在地端除錯 | 附加到已運行的應用程式 |
| IDE/除錯器/Tauri 開發工作流程已運行 | 附加 |
| 代理程式需要端到端驗證執行 | 包裝器 |
| 內部使用或類似 CI 的地端冒煙測試 | 包裝器 |
如果代理程式應啟動應用程式,請包裝現有命令:
auditaur start
auditaur start 使用 .auditaur/config.json,回報就緒狀態,寫入 .auditaur/session.json,並在應用程式就緒後刻意讓它保持運行。如果設定檔宣告了命名連接埠,start 會保留隨機的地端連接埠,在命令中展開 {{port:name}} 佔位符,設定已設定的連接埠環境變數,並在工作階段檔案和 JSON 輸出中記錄所選的連接埠。如果尚無設定檔,請使用較低層級的形式:
auditaur debug --app <app-name> --require-frontend --json run --timeout-seconds 180 --write-session .auditaur/session.json -- npm run tauri dev
debug run 回報就緒狀態,並在應用程式就緒後刻意讓它保持運行。當提供了 --app 時,它會忽略生成前已存在的符合探索記錄,等待新的 Auditaur 工作階段,並將就緒狀態固定到該確切的工作階段/資料庫/行程 ID。使用 --write-session <路徑> 來進行代理程式擁有的啟動,以便後續命令可以讀取 sessionId、instanceId、pid、databasePath 以及生成的選擇器引數陣列,而不是使用 --active 或 --latest 猜測。驗證完成後,使用 auditaur stop 清理已產生的應用程式行程。
解讀就緒狀態
檢查 stages 陣列:
app_discovery:Auditaur 探索檔案存在。heartbeat:應用程式心跳是最新的。telemetry_database:SQLite 資料庫存在且結構驗證通過。session:可以查詢到工作階段資料列。window:Tauri 視窗遙測存在。backend_telemetry:後端/外掛日誌、跨度或視窗資料列存在。frontend_telemetry:前端日誌/錯誤/IPC/事件存在;僅在--require-frontend時需要。drive_bridge:Tauri 原生應用程式內驅動橋接狀態存在且具有最新的心跳;僅在--require-drive-bridge時需要。cdp_endpoint:舊版瀏覽器除錯端點就緒;僅在明確請求時檢查。
如果就緒狀態為 false,請遵循階段訊息和 hints,而不是從終端機輸出猜測。
驅動 WebView
在變更應用程式之前,先檢查 Tauri 原生驅動橋接:
auditaur drive --app <app-name> --active --json inspect
如果需要目標選擇,請使用橋接目標:
auditaur drive --app <app-name> --active --json click --target auditaur-bridge --selector '<css>'
盡可能先使用唯讀操作:
auditaur drive --app <app-name> --active --json exists --selector '<css>'
auditaur drive --app <app-name> --active --json text --selector '<css>'
auditaur drive --app <app-name> --active --json snapshot --selector body --output failure.json
auditaur drive --app <app-name> --active --json screenshot --selector body --output failure.png --snapshot-output failure.json
在分享快照成品之前請先檢閱;它們可能包含 DOM 文字、URL 或其他敏感內容。
對於文字輸入,當直接設定 DOM 值並觸發 input/change 事件就已足夠時,請使用 fill。當框架控制的輸入框或文字區域需要聚焦文字插入時,請使用 type:
auditaur drive --app <app-name> --active --json type --selector 'textarea' --value 'hello' --visible-only
在驗證模態框、焦點覆蓋層或全螢幕外殼(可能留下重複的隱藏 DOM)時,偏好對選擇器操作(wait、exists、text、click、fill、type、hover、select、check 和 uncheck)使用 --visible-only(或 --visible)。
如果 drive inspect 回報 bridge.status 為 inactive,請在前端啟用 driveBridge。一旦啟用,即可透過 Tauri 原生橋接使用 wait、exists、text、click、fill、type、press、hover、select、check、uncheck、evaluate、snapshot 和 screenshot。橋接截圖會先嘗試原生 WebView 擷取(screenshotBackend=tauri_native_webview_snapshot)以獲得無遮擋的 WebView 畫素;選擇器截圖會裁剪該 WebView 影像並回報 screenshotScope=selector 加上 selectorRect。如果 WebView 擷取失敗,Auditaur 會回退到原生視窗擷取(screenshotBackend=tauri_native_window_xcap),然後再回退到 DOM 文字摘要 PNG(screenshotBackend=bridge_dom_summary_canvas)並附帶錯誤中繼資料。evaluate 會在 WebView 中執行任意 JavaScript,因此請將橋接限制在開發/測試工作階段。如果橋接處於非啟用狀態,請使用 Auditaur 遙測(timeline、ipc、traces、explain)作為事實來源,並僅在需要模擬手動 UI 輸入時搭配無障礙工具自動化。
舊版相容性:--cdp-port 可能出現在較舊的命令中,但 auditaur drive 會忽略它。對驅動命令使用正面措辭:說明它們使用 Tauri 原生驅動橋接。
檢查遙測資料
就緒後,使用結構化的讀取命令:
auditaur apps --json
auditaur sessions --json
auditaur logs --json
auditaur errors --json
auditaur ipc --json
auditaur events --json
auditaur traces --json
auditaur timeline --json
auditaur explain --json
當有過期或多個工作階段時,偏好使用 --session <id>、--db <路徑>、--active、--latest、--pid 或 --instance-id。
腳本中的人類關卡
對於需要真實人類操作同時保留相同固定應用程式工作流程的工作流程,請使用腳本人類關卡:OAuth/裝置碼核准、OS 權限提示、安裝程式權限提升、外部瀏覽器交接、相機/麥克風權限、硬體安全金鑰,或任何代理程式應暫停而非模擬信任敏感性輸入的流程。
在腳本中加入關卡,並使用 --script <路徑> 執行腳本:
{
"gates": [
{
"name": "核准 GitHub 登入",
"instructions": "請在應用程式或瀏覽器中完成 GitHub 裝置碼核准,然後返回此處。",
"selector": "#status-card",
"expectText": "已登入",
"manualContinue": true,
"timeoutMs": 300000,
"choices": [
{ "id": "done", "label": "完成", "outcome": "continue" },
{ "id": "blocked", "label": "受阻", "outcome": "fail" }
]
}
]
}
人類關卡在 Auditaur 已生成並固定新的應用程式工作階段並達到就緒狀態後執行,但在選擇器/文字/錯誤/IPC/explain 證據收集之前。在關卡期間不要重新啟動應用程式或切換到不同的工作階段;重點是將關卡前後的證據保持附加到同一個工作階段/資料庫/行程 ID。關卡可以是僅選擇器監控的等待、手動繼續、帶有 continue/retry/skip/fail/abort 結果的選擇、輸入以及剪貼簿提示。敏感輸入和剪貼簿值預設會在腳本報告中編輯,但地端暫存的關卡回應 JSON 可能會短暫包含原始輸入值,直到腳本消費並移除它。
當關卡需要手動回應時,Auditaur 也會在固定的工作階段資料庫旁發布一個工作階段本機請求。代理程式可以透過 MCP 列出並回應這些請求:
auditaur mcp
使用 list_pending_human_gates 來尋找待處理的關卡,並使用 respond_human_gate 並提供 requestId、可選的 choiceId、可選的 inputs 和一個明確的 responder 值。使用與腳本相同的 Auditaur 資料目錄執行 MCP 伺服器,以便它可以看到工作階段本機的請求檔案。如果已使用 auditaur init extension 安裝了 Copilot canvas 擴充功能,請為待處理的關卡開啟 auditaur-human-gate 畫布,讓使用者獲得動作卡並可以點擊回應。終端機 ENTER/選擇輸入仍然是沒有 MCP 或 canvas 用戶端時的備用方案。
常見失敗模式
- 無探索檔案:應用程式仍在編譯、尚未啟動,或未註冊 Auditaur 外掛。
- 資料庫無法讀取/結構無效:應用程式部分初始化或資料目錄錯誤。
- 無前端遙測:前端 API 未初始化、尚未觸發任何前端操作,或在 UI 中匯出失敗。
- 驅動橋接未啟用:在確切一個除錯/測試 WebView 中啟用
initAuditaur({ driveBridge: true }),否則使用遙測加上無障礙工具備用方案。 - 待處理的人類關卡:不要以合成應用程式狀態繞過它。將關卡指示呈現給使用者,透過 canvas/MCP/終端機路徑回應,然後在同一個固定工作階段上繼續收集證據。
- 目標不明確:使用
--target auditaur-bridge;如果多個工作階段符合,請使用--session-id、--instance-id、--pid、--latest或--active區分。 - JSON 輸出污染:從最新的 Auditaur CLI 使用
debug run --json;子行程的啟動輸出不應出現在 JSON 行中。
驗證循環
對於高信賴度的變更:
- 執行相關的測試/建置。
- 使用
auditaur debug啟動或附加。 - 執行已設定的
auditaur drill;如果它發布了人類關卡,請透過 canvas/MCP/終端機回應路徑呈現,而不是取代手動操作。 - 當需要 UI 覆蓋率時,透過 Tauri 原生橋接驅動一條代表性的 UI 路徑。
- 當前端遙測重要時,重新檢查
debug status --require-frontend。 - 檢查
timeline和explain。 - 清理已產生的應用程式行程和暫存遙測目錄。