AIデバッグブリッジ

AIはコード全体を読んで仮説を立てることには強いですが、ランタイムを直接観測できません。 そのためデバッグが「AIの推測 → 人が実行 → 人がエラーをコピペ → AIが再推測」という遅いリレーになります。

AIデバッグブリッジは、このリレーから人を取り除きます。標準的な構造化デバッグ行（@BLYCK@ {json}）をコードに仕込むと、Blyckがすべてのターゲットの出力ストリームを吸い上げ、AIに統一された形式で供給します。デバッグが**「AIが実験を設計 → 実行 → 構造化された結果を直接観測 → 修正」**へと変わります。Web・デスクトップ・モバイル・コンソールで共通です。

なぜ必要か

従来のログデバッグの問題	内容
遅い	AIの推測 → 人が実行 → 人がエラーをコピペ → AIが再推測（人がリレーの中間に挟まる）
欠落	コンソールの一部だけがコピペされ、間欠バグはその瞬間を捕まえられない
非構造的	生のスタックトレース/混在ログをAIが推測でパース
プラットフォームがバラバラ	Webコンソール / logcat / os_log / stdout … アプローチがすべて異なる

核心となる洞察はただ一つの問いです — 「そのアプリの出力は、Blyckが所有するテキストストリーム（PTY・ターミナル・SSH・logcat・ログファイル）に流れ込むか?」 ほとんどが「はい」であり、唯一の例外であるブラウザコンソールでさえ、Blyckはすでに通路を持っています。

ワイヤー形式 — 構造化デバッグ行

プラットフォームに関係なく、1行に目印 + 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`		`ファイル:行`（任意）

ヘルパーAPI — コードに仕込む2つの関数

概念は2つだけです。

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 を提供します。

キャプチャ — 2つのパイプ、1つのバッファ

パイプA — Blyck所有ストリーム共通パーサー

ターミナルPTY · SSHシェル · adb logcat など、Blyckが起動または接続したすべてのテキストストリームから @BLYCK@ {json} 行を抽出・パースし、構造化リングバッファ（上限1000、FIFO）に保存します。非プローブの一般出力は Run & Observe のエラーマーカーパースへ流れます（役割分離）。

パイプB — ブラウザコンソール

webview 内に閉じ込められたブラウザ console は Live Preview のコンソール収集が受け取り、同じバッファに正規化します。ブラウザ側でも console.log("@BLYCK@ …") の1行で済みます。

→ 2つのパイプが同じバッファに合流するため、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シェル出力	パイプA
Webサーバー側（SSR・devサーバー）	プロセス stdout	パイプA
Webブラウザ側 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@` プローブ1行を挿入（`js/ts`·`python`·`dart`·`bash`、ローカル）
`debug_release_check(path)`	読み取り（自動）	ディレクトリを再帰スキャン → 残った `@BLYCK@` の位置を報告（`removable` を表示）
`debug_strip(path)`	確認	`@BLYCK@` 出力文のみを一括除去（ローカル、3重の安全網）

2つの動作モード

収集は完全リアルタイム（ストリームが入ってくると即座にバッファ）です。AIの反応の仕方が2通りあります。

モードA — 能動デバッグループ（作業中）

1ターン内で: プローブを仕込む → アプリ実行 → ライブ debug_read → 判断 → 修正 → 再実行 → 再観測。 人がエラーリレーから抜け、AIが編集・実行・観測・修正のループを単独で回します。試行錯誤を潰す核心。

モードB — 自動調査（アプリが動いていて落ちたとき）

level:error または assert の @BLYCK@ が到着すると、AIが尋ねなくてもアクティブなチャットに自動的に割り込んで原因を調査します。「ランタイム不変条件が破れたらAIを呼ぶブレークポイント」のような感覚です。

ライブデバッグパネル

Ctrl+Shift+D でトグルします。構造化された @BLYCK@ ストリームをリアルタイムで表示し、label · loc · level · source フィルター、一時停止・クリア、🔔 自動調査トグル（モードB）を提供します。

AIが読む同じバッファを人も見るので、「AIが今何を観測しながら修正しているか」が会話ウィンドウと並んで透明に表れます。

シナリオ — カート合計のバグ

ユーザー: 「カート合計のバグを直して」
AI: 疑わしい箇所に blyckDbg('after-add', {qty, total}) · blyckAssert(total > 0, 'total-positive', …) を挿入
AI: アプリ実行（ターミナルまたはプレビュー）→ ライブ debug_read で流れを観測
assert 破れ → その瞬間の値・位置をまるごとAIが見る → 即座に修正 → 再実行
ユーザーはデバッグパネル + 会話ウィンドウでリアルタイムに見学
完了 → デプロイ時にプローブが自動無効化

デプロイゲート — プローブが一粒も残らないように

原則: プローブは開発専用、デプロイ時に自動でno-op/除去。手動の片付けなし。

リリースフラグ（NODE_ENV=production · python -O · ビルドタグ除去 · NDEBUG …）→ shim がネイティブデバッグ機構にコンパイルされ自動無効化されます。目印が残ってもリリースでは動きません — 最も重要な安全網。
debug_release_check(path) — 再帰スキャンで残った @BLYCK@ の位置を報告し、各行が出力文（除去対象）かどうかを表示します。
debug_strip(path) — 片付けを実行します。3重の安全網:
- 出力文のみ除去 — @BLYCK@ が print/log/console 呼び出しに含まれる行のみ。コメント・文字列定数・ドキュメント・ヘルパー呼び出しは保存
- shim定義ファイルを保存 — ヘルパー内部の出力行を消すとファイルが壊れるため、ファイルごとスキップ
- truncateガード — 読み取りキャップを超えて切られた大きなファイルは、再書き込みすると欠落するためスキップ

制限事項

debug_probe（自動挿入）は現在 ローカルファイル + js/ts·python·dart·bash のみサポートします。コンパイル言語（go·rust·java·c# など）とリモート（SFTP）ファイルは debug_shim でヘルパーを直接付けてください。
shim 11種のうち 8種（js·python·bash·go·rust·java·csharp·dart） は実際のコンパイル・実行で検証済みで、c·kotlin·swift はビルドツールチェーンの不在により出力検査のみを経ています。
AIはストリームを常時凝視しません（モードA・B限定）。モードB（自動調査）はデフォルトOFFであり、有効にするときはトークンコストを考慮してください。
目印が壊れないよう、@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。（Webターゲットはブラウザコンソール = パイプB）