AI 调试桥

AI 在通读整段代码并提出假设方面很强,但无法直接观察运行时。 于是调试变成了”AI 猜测 → 人执行 → 人复制粘贴报错 → AI 再猜测”这样缓慢的接力。

AI 调试桥把人从这场接力中抽离出来。只要在代码中植入标准的结构化调试行(@BLYCK@ {json}),Blyck 就会吸入所有目标的输出流,以统一格式喂给 AI。调试随之变为 “AI 设计实验 → 执行 → 直接观察结构化结果 → 修复”。Web·桌面·移动·控制台通用。

为什么需要

传统日志调试的问题	内容
慢	AI 猜测 → 人执行 → 人复制粘贴报错 → AI 再猜测(人卡在接力中间)
丢失	只复制粘贴了部分控制台,间歇性 bug 抓不到出现的那一刻
非结构化	AI 靠猜测解析原始堆栈跟踪/混合日志
平台各异	Web 控制台 / 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 种语言的轻量 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 所有的流的通用解析器

从 Blyck 启动或连接的所有文本流(终端 PTY · SSH shell · adb logcat 等)中提取并解析 @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
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@ 探针(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 此刻在观察什么、在修什么”会与对话窗并排,透明可见。

场景 —— 购物车合计 bug

1. 用户:“修一下购物车合计的 bug”
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) —— 执行清理。三重安全网:
   • 仅移除输出语句 —— 只处理 @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。(Web 目标的浏览器控制台 = 管道 B)