AI 除錯橋接

AI 擅長閱讀整份程式碼並建立假設,但無法直接觀察執行階段。 因此除錯變成「AI 猜測 → 人執行 → 人複製貼上錯誤 → AI 再猜測」的緩慢接力。

AI 除錯橋接把人從這個接力中抽離。只要在程式碼中埋入標準的結構化除錯行(@BLYCK@ {json}),Blyck 就會吸收所有目標的輸出串流,並以統一格式餵給 AI。除錯因此變成**「AI 設計實驗 → 執行 → 直接觀察結構化結果 → 修正」**。網頁·桌面·行動·主控台皆通用。

為什麼需要

傳統記錄除錯的問題	內容
慢	AI 猜測 → 人執行 → 人複製貼上錯誤 → AI 再猜測(人卡在接力中間)
遺漏	只複製貼上部分主控台內容,間歇性錯誤抓不到那一瞬間
非結構化	AI 靠猜測解析原始堆疊追蹤/混雜的記錄
平台各異	網頁主控台 / logcat / os_log / stdout … 存取方式各不相同

核心洞察只是一個問題 — 「那個應用程式的輸出,是否會流入 Blyck 所擁有的文字串流(PTY·終端機·SSH·logcat·記錄檔)?」 多數情況答案是「是」,而唯一的例外瀏覽器主控台,Blyck 也早已握有通道。

Wire 格式 — 結構化除錯行

與平台無關,一行就是標記 + JSON。

@BLYCK@ {"label":"after-add","vals":{"qty":3,"total":null},"level":"debug","loc":"cart.js:42"}

欄位	必填	說明
label	✅	探針名稱
vals		要觀察的值(物件)。若非物件則以 {value:…} 包裝
level		debug · info · warn · error · assert(預設 debug)
loc		檔案:行號(選填)

Blyck 在擷取時蓋章

ts(時間戳記)· source(terminal/preview)· sessionId 不放在 wire 上。 Blyck 在抓取記錄的當下附加(避開時鐘·環境差異)。以標記 @BLYCK@ 與一般記錄區分,讓解析器精準挑出;即使 JSON 損毀,也會以 level:warn + 原文(raw)保存以防遺失。

輔助 API — 埋入程式碼的兩個函式

概念只有兩個。

• blyckDbg(label, vals) — 吐出值(探針)。
• blyckAssert(cond, label, vals) — 驗證假設,若不成立則發出 level:"assert" 事件。

debug_shim(lang) 工具會回傳 11 種語言的 thin shim(各約 5 行) — js/ts · python · bash · go · rust · java · csharp · dart(flutter) · kotlin · swift · c。全部都提供 dbg + assert。

發行版自動失效

每個 shim 都對應到該語言的原生除錯專用機制(JS if (BLYCK_DEBUG) DCE、Python if __debug__:、Go build tag、Rust cfg(debug_assertions)、Swift #if DEBUG、Kotlin BuildConfig.DEBUG 等)。在發行版建置中會自動移除/失效,因此執行階段成本為 0。→ 參考 部署閘門。

擷取 — 兩個管道,一個緩衝區

管道 A — Blyck 所擁有串流的共用解析器

從終端機 PTY · SSH shell · adb logcat 等所有由 Blyck 啟動或連接的文字串流中,擷取並解析 @BLYCK@ {json} 行,儲存到結構化環形緩衝區(上限 1000,FIFO)。非探針的一般輸出則流向 Run & Observe 的錯誤標記解析(職責分離)。

管道 B — 瀏覽器主控台

被困在 webview 內的瀏覽器 console,由 Live Preview 的主控台收集接手並正規化為同一個緩衝區。在瀏覽器端也只需 console.log("@BLYCK@ …") 一行即可。

→ 兩個管道匯流到同一個緩衝區,因此無論目標是什麼,AI 看到的格式都相同。

各平台記錄串流

所謂「平台轉接器」其實只是把該平台記錄流入 Blyck 終端機而已。只要把串流掛在終端機上,@BLYCK@ 就會自動收集。

目標	將記錄流入 Blyck 串流	處理
主控台 / CLI / 後端	終端機 stdout/stderr	管道 A
Android	adb logcat	管道 A
iOS	idevicesyslog / os_log	管道 A
Flutter	flutter run 或 flutter logs(行動·桌面整合)	管道 A
遠端(SSH)	SSH shell 輸出	管道 A
網頁伺服器端(SSR·dev 伺服器)	行程 stdout	管道 A
網頁瀏覽器端 console	webview console	管道 B

AI 工具(MCP)— 5 種

工具	權限	職責
debug_read(filter?)	讀取(自動)	直接讀取結構化除錯事件(人複製貼上 0 次)。filter:label·level·loc·source·sessionId·paneId·sinceTs·sinceSeq(增量輪詢)·limit
debug_shim(lang)	讀取(自動)	回傳各語言的 blyckDbg/blyckAssert 輔助函式原始碼(含發行版自動 no-op 防護)
debug_probe(path, line, label, expr)	確認	在 檔案:行號 插入一行格式有保證的 @BLYCK@ 探針(js/ts·python·dart·bash,本機)
debug_release_check(path)	讀取(自動)	遞迴掃描目錄 → 回報殘留的 @BLYCK@ 位置(標示 removable)
debug_strip(path)	確認	僅批次移除 @BLYCK@ 輸出語句(本機,三重安全網)

debug_probe 的價值

debug_probe 的核心是格式保證,可避免「AI 手動跳脫弄錯導致 debug_read 抓不到」的意外。在快速的單次擷取時,即使沒有輔助函式也能精準插入一行。

兩種運作模式

收集是完全即時的(串流進來就立即進緩衝區)。AI 的反應方式有兩種。

模式 A — 主動除錯迴圈(作業中)

在一個回合內:埋探針 → 執行應用程式 → 即時 debug_read → 判斷 → 修正 → 重新執行 → 重新觀察。 人從錯誤接力中抽離,AI 獨自運轉編輯·執行·觀察·修正迴圈。這是消滅試誤的關鍵。

模式 B — 自動調查(應用程式跑著跑著爆掉時)

當 level:error 或 assert 的 @BLYCK@ 到達時,AI 即使沒被詢問也會自動介入使用中的聊天並調查原因。感覺就像「執行階段不變式被打破時就呼叫 AI 的中斷點」。

模式 B 預設為 OFF — 自動 AI 回合是有成本的

自動調查會耗費 token 成本,因此被綁上四層安全機制且預設停用。

1. 預設 OFF(opt-in) — 僅能透過 AI 設定面板的核取方塊或即時除錯面板的 🔔 按鈕啟用(設定會持久保存)
2. 全域速率限制 — 每 60 秒最多 3 件
3. 重複抑制 — 相同 label+loc 有 120 秒冷卻
4. 僅在閒置時 — AI 正在回應時則略過(事件仍留在緩衝區)

AI 不會一直盯著串流

AI 不會時時刻刻盯著記錄。它在作業迴圈中讀取(模式 A),或被事件喚醒時(模式 B) 才查看。不在無事輸出上耗 token,反而更有效率。

即時除錯面板

以 Ctrl+Shift+D 切換。即時顯示結構化的 @BLYCK@ 串流,並提供 label · loc · level · source 篩選、暫停·清除、🔔 自動調查切換(模式 B)。

由於人也看得到 AI 所讀的同一個緩衝區,「AI 現在正在觀察什麼並修正」就會與對話視窗並列,透明地呈現。

情境 — 購物車合計錯誤

1. 使用者:「幫我修購物車合計錯誤」
2. AI:在可疑處插入 blyckDbg('after-add', {qty, total}) · blyckAssert(total > 0, 'total-positive', …)
3. AI:執行應用程式(終端機或預覽)→ 用即時 debug_read 觀察流程
4. assert 失敗 → AI 一次看到那一瞬間的值·位置 → 立即修正 → 重新執行
5. 使用者在除錯面板 + 對話視窗中即時觀看
6. 完成 → 部署時探針自動失效

部署閘門 — 讓探針一絲不留

原則:探針僅供開發使用,部署時自動 no-op/移除,無需手動清理。

1. 發行版旗標(NODE_ENV=production · python -O · 移除 build tag · NDEBUG …)→ shim 會編譯成原生除錯機制而自動失效。即使標記殘留,在發行版也不會運作 — 這是最重要的安全網。
2. debug_release_check(path) — 透過遞迴掃描回報殘留的 @BLYCK@ 位置,並在每行標示是否為輸出語句(待移除對象)。
3. debug_strip(path) — 執行清理。三重安全網:
   • 僅移除輸出語句 — 只移除 @BLYCK@ 位於 print/log/console 呼叫中的行。註解·字串常數·文件·輔助函式呼叫皆保留
   • 保留 shim 定義檔 — 刪除輔助函式內部的輸出行會使檔案損毀,因此整個檔案略過
   • truncate 防護 — 超過讀取上限而被截斷的大型檔案,重寫會造成遺失,因此略過

為什麼預設是 no-op

預設是有防護的 no-op(失效),而非 debug_strip(移除)。因為只要開啟旗標,就能為了正式環境除錯而讓探針復活。

限制事項

• debug_probe(自動插入)目前僅支援 本機檔案 + js/ts·python·dart·bash。編譯式語言(go·rust·java·c# 等)與遠端(SFTP)檔案,請用 debug_shim 直接貼上輔助函式。
• 11 種 shim 中,8 種(js·python·bash·go·rust·java·csharp·dart) 已透過實際編譯·執行驗證,而 c·kotlin·swift 因缺乏建置工具鏈,僅經過輸出檢查。
• AI 不會持續盯著串流(僅限模式 A·B)。模式 B(自動調查)預設為 OFF,啟用時請考量 token 成本。
• 為避免標記損毀,@BLYCK@ 之後請僅輸出純 JSON(例:在 PowerShell 中若混入引號殘留物,會以 malformed 警告保存)。

FAQ

Q. 我需要複製主控台輸出再給 AI 嗎? → 不需要。那正是這個功能的核心。埋入探針並執行應用程式後,AI 會用 debug_read 直接讀取值。

Q. 我執行了,但 debug_read 抓不到。 → 輸出必須流入 Blyck 所啟動的終端機/預覽串流。隔離執行等不顯示在畫面上的路徑,其輸出不會被管道 A 抓到。請在終端機面板中執行,行動端則請把 adb logcat·flutter logs 串流掛在終端機上。

Q. 部署時一定要刪掉探針嗎? → 只要開啟發行版旗標,shim 就會自動失效而不執行。若想連標記也清理乾淨,請用 debug_release_check 檢查後再用 debug_strip。

Q. 應用程式發生錯誤時,AI 會自動介入嗎? → 開啟 模式 B(自動調查) 就會。預設為 OFF,可透過 AI 設定面板或即時除錯面板(Ctrl+Shift+D)的 🔔 按鈕啟用。

Q. 行動/Flutter 也可以嗎? → 可以。只要在 Blyck 終端機掛上記錄串流,裝置應用程式的 @BLYCK@ 就會自動收集 — Android adb logcat、iOS idevicesyslog、Flutter flutter run/flutter logs。(網頁目標的瀏覽器主控台 = 管道 B)