AI 디버그 브리지

AI는 코드 전체를 읽고 가설을 세우는 데는 강하지만 런타임을 직접 관찰하지 못합니다. 그래서 디버깅이 “AI 추측 → 사람이 실행 → 사람이 에러 복붙 → AI 재추측”의 느린 릴레이가 됩니다.

AI 디버그 브리지는 이 릴레이에서 사람을 빼냅니다. 표준 구조적 디버그 라인(@BLYCK@ {json})을 코드에 심으면, Blyck이 모든 타깃의 출력 스트림을 빨아들여 AI에게 통일된 형식으로 먹입니다. 디버깅이 “AI가 실험을 설계 → 실행 → 구조적 결과를 직접 관찰 → 수정” 으로 바뀝니다. 웹·데스크탑·모바일·콘솔 공통입니다.

왜 필요한가

기존 로그 디버깅의 문제	내용
느림	AI 추측 → 사람이 실행 → 사람이 에러 복붙 → AI 재추측 (사람이 릴레이 중간에 낌)
손실	콘솔 일부만 복붙됨, 간헐 버그는 그 순간을 못 잡음
비구조적	생 스택트레이스/혼합 로그를 AI가 추측 파싱
플랫폼 제각각	웹 콘솔 / logcat / os_log / stdout … 접근법이 다 다름

핵심 통찰은 단 하나의 질문입니다 — “그 앱의 출력이 Blyck이 소유한 텍스트 스트림(PTY·터미널·SSH·logcat·로그파일)으로 흘러 들어오나?” 대부분 “예”이고, 유일한 예외인 브라우저 콘솔조차 Blyck은 이미 통로를 갖고 있습니다.

와이어 형식 — 구조적 디버그 라인

플랫폼과 무관하게, 한 줄에 표식 + 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는 와이어에 넣지 않습니다. 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 빌드태그, Rust cfg(debug_assertions), Swift #if DEBUG, Kotlin BuildConfig.DEBUG 등). 릴리스 빌드에서 자동으로 제거/무력화되어 런타임 비용이 0입니다. → 배포 게이트 참고.

캡처 — 두 파이프, 한 버퍼

파이프 A — Blyck 소유 스트림 공통 파서

터미널 PTY · SSH 셸 · 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 셸 출력	파이프 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@ 출력문만 일괄 제거(로컬, 안전 3중망)

debug_probe의 가치

debug_probe는 “AI가 손으로 이스케이프를 틀려 debug_read에 안 잡히는” 사고를 막는 형식 보장이 핵심입니다. 빠른 단발 캡처에 헬퍼 없이도 한 줄을 정확히 삽입합니다.

두 가지 동작 모드

수집은 완전 실시간(스트림이 들어오는 즉시 버퍼)입니다. AI의 반응 방식이 두 가지입니다.

모드 A — 능동 디버깅 루프 (작업 중)

한 턴 안에서: 프로브 심기 → 앱 실행 → 라이브 debug_read → 판단 → 수정 → 재실행 → 재관찰. 사람이 에러 릴레이에서 빠지고, AI가 편집·실행·관찰·수정 루프를 혼자 돌립니다. 시행착오를 죽이는 핵심.

모드 B — 자동 조사 (앱이 돌다가 터질 때)

level:error 또는 assert @BLYCK@ 가 도착하면, AI가 묻지 않아도 활성 채팅에 자동으로 끼어들어 원인을 조사합니다. “런타임 불변식이 깨지면 AI를 부르는 중단점” 같은 느낌입니다.

모드 B는 기본 OFF — 자동 AI 턴은 비용입니다

자동 조사는 토큰 비용이 들기 때문에 안전장치 4겹으로 묶여 있고 기본 비활성입니다.

1. 기본 OFF (opt-in) — AI 설정 패널 체크박스 또는 라이브 디버그 패널의 🔔 버튼으로만 활성화(설정은 영속)
2. 글로벌 레이트리밋 — 60초당 최대 3건
3. 중복 억제 — 같은 label+loc 는 120초 쿨다운
4. 유휴일 때만 — AI가 응답 중이면 스킵(이벤트는 버퍼에 남음)

AI는 스트림을 항상 응시하지 않습니다

AI는 매 순간 로그를 들여다보지 않습니다. 작업 루프 안에서 읽거나(모드 A), 이벤트가 깨울 때(모드 B) 봅니다. 노는 출력에 토큰을 안 쓰는 게 오히려 효율적입니다.

라이브 디버그 패널

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 · 빌드태그 제거 · NDEBUG …) → shim이 네이티브 디버그 장치로 컴파일돼 자동 무력화됩니다. 표식이 남아도 릴리스에선 안 돕니다 — 가장 중요한 안전망.
2. debug_release_check(path) — 재귀 스캔으로 남은 @BLYCK@ 위치를 보고하고, 각 줄에 출력문(제거 대상)인지 표시합니다.
3. debug_strip(path) — 정리를 실행합니다. 안전 3중망:
   • 출력문만 제거 — @BLYCK@ 가 print/log/console 호출에 든 줄만. 주석·문자열 상수·문서·헬퍼 호출은 보존
   • shim 정의 파일 보존 — 헬퍼 내부 출력 줄을 지우면 파일이 깨지므로 파일째 스킵
   • truncate 가드 — 읽기 캡을 넘겨 잘린 큰 파일은 다시 쓰면 손실되므로 스킵

no-op이 기본인 이유

debug_strip(제거)이 아니라 가드된 no-op(무력화) 이 기본입니다. 플래그만 켜면 운영 디버깅용으로 프로브를 되살릴 수 있기 때문입니다.

제한사항

• 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. (웹 타깃은 브라우저 콘솔 = 파이프 B)