AI 自动化调试指南
HFLinkCLI 内嵌的 Lua 脚本模式(见 Lua 脚本模式)天然适合与 AI 编程助手结合:它把调试器的全部能力—— 连接探针、Flash 下载、内存/寄存器访问、RTT、高速采样、表达式求值——收敛为一套文本进、文本出的 机器接口。AI 擅长读文档、写脚本、解读输出,调试器擅长确定性地执行硬件操作,两者恰好互补。 本页说明这一设计思路,并给出几个可直接改造的案例。
设计思路:AI 出主意,调试器动手
传统调试流程中,人是唯一的"执行器":看寄存器、点烧录、抄日志,再把现象转述给工具或同事。 Lua 脚本模式把"执行"交给程序,AI 则接管"判断":
角色 |
职责 |
|---|---|
AI |
阅读 API 文档与现象描述 → 生成 Lua 脚本 → 解读执行输出 → 迭代修正 |
HFLinkCLI |
确定性地执行脚本:连探针、烧镜像、读内存、采数据,结构化报告成败 |
这套接口有几个刻意为之的特点,正好是 AI 协作需要的:
文本进、文本出。脚本是纯文本,执行结果是控制台输出与退出码,都能原样贴进对话。
确定性与可复现。同一脚本对同一目标行为一致;脚本可以先审查、再执行,可进版本库、可进 CI, 也能反复复跑。
结构化错误。接口失败统一返回
nil, message, code(错误三元组),进程以退出码0/1/2区分成败,AI 能读懂失败原因并自我修正。默认最小权限。safe 模式裁剪了
io/os等标准库;Flash 操作可用hf.flash.dry_run()离线生成计划先行确认,再真正接触硬件。全链路覆盖。从枚举探针到烧录、读变量、采波形,一个脚本即可编排完整流程, 无需在多个工具间搬运数据。
除 Lua 模式外,gdb / rtt 子命令兼容标准工具链(GDB/MI、telnet),AI 生成的通用工具同样可以驱动;
但"把完整流程编排进一个脚本"的能力是 Lua 模式独有的,也是下文案例的基础。
推荐工作流
人:描述意图、审查脚本、授权执行
│
▼
AI 生成 Lua 脚本 ──→ 人工审查 ──→ HFLinkCLI 执行 ──→ 捕获 stdout/stderr 与退出码
▲ │
└────────────────── 贴回输出,AI 解读并迭代 ◄─────────┘
让 AI 高效生成可运行脚本,关键是喂足上下文:
附上 Lua 脚本模式 全文作为 API 字典(接口签名、错误约定、生命周期规则都在其中)。
说明环境事实:探针型号、目标芯片与 Pack 选择器、镜像路径、关注的变量名或地址。
要求输出完整脚本:逐调用检查错误三元组、按创建逆序释放资源、关键步骤
print进度。
下面是一个可直接使用的提示词模板:
你是一名嵌入式调试助手,我将提供 HFLinkCLI Lua 模式的 API 文档(hf 全局表)。
请编写一个完整可运行的 Lua 脚本:
目标:连接探针,烧录 app.elf 到 STM32H723ZGTx@STM32H7xx_DFP,然后 halt 并读取
全局变量 g_errorCount(uint32_t);大于 0 时打印其值并以退出码 1 结束,
否则复位运行并以退出码 0 结束。
要求:
- 每个调用按错误三元组约定检查,失败时用 error() 给出中文原因
- 按创建逆序释放资源
- 关键步骤用 print 输出
只输出完整脚本文件内容。
案例一:自动烧录
让 AI 生成一条"插上就烧"的产线/桌面脚本:烧录 app.elf 并复位运行,全程无人工干预。
-- ai_flash.lua —— 用法:HFLinkCLI ai_flash.lua
local function check(value, message, code)
if value == nil then
error(string.format("%s (%d)", message, code))
end
return value
end
local device = check(hf.open(check(hf.devices())[1]))
check(device:start_dap())
check(device:set_interface("swd"):set_speed(10000000))
device:pack("STM32H723ZGTx@STM32H7xx_DFP") -- 保存 Pack 选择器,connect() 时打开会话
check(device:connect())
-- 完整下载(擦除 + 编程 + 校验,自动跳过内容已一致的扇区),完成后复位运行
local result, message, primary, cleanup = hf.flash.program(device, "app.elf", {
reset_after = true,
})
if not result then
error(string.format("烧录失败:%s (primary=%d, cleanup=%d)", message, primary, cleanup))
end
print("烧录成功,已复位运行")
device:disconnect()
device:close()
两个可选的增强,都很适合让 AI 补全:
先预演再执行:把
hf.flash.program(...)换成hf.flash.dry_run(device, "app.elf")离线生成擦写计划(涉及哪些 bank、扇区、操作),贴给 AI 或人工确认无误后再真正烧录。批量与差异:AI 可以把脚本扩展成遍历多台探针、逐台烧录并汇总结果的版本。
案例二:采集数据,交给 AI 分析
调试器是目标板旁唯一的"数据入口"。用高速内存采样(HSS)把某个变量录下来,输出 CSV,
再让 AI 分析趋势、毛刺与周期抖动。变量地址不必手查 map 文件——用表达式引擎的 sym()
直接从 ELF 按符号名解析:
-- ai_hss.lua —— 用法:HFLinkCLI ai_hss.lua > samples.csv
local function check(value, message, code)
if value == nil then
error(string.format("%s (%d)", message, code))
end
return value
end
local device = check(hf.open(check(hf.devices())[1]))
check(device:start_dap())
check(device:set_interface("swd"):set_speed(10000000))
device:pack("STM32H723ZGTx@STM32H7xx_DFP")
check(device:connect())
local target = check(device:pack_target("P0"))
-- 从 ELF 解析变量地址,AI 只需知道变量名
local sess = check(hf.expr.open("app.elf"))
local addr = check(sess:sym("g_counter"))
sess:close()
local session = check(hf.hss.create(target))
check(session:add_block(addr, 4))
check(session:start(1000)) -- 采样周期 1000 µs ≈ 1 kHz
local frames = {}
while #frames < 2000 do -- 采 2000 帧(约 2 秒)
local batch = check(session:read(64)) -- SampleView 数组(零拷贝视图)
for _, view in ipairs(batch) do
frames[#frames + 1] = view
end
end
check(session:stop())
print("ts_ns,counter")
for _, view in ipairs(frames) do
print(string.format("%d,%d", view:ts(), view:u32(1)))
end
device:disconnect()
device:close()
随后把 samples.csv 交给 AI:让它统计均值与方差、标出异常跳变、判断是否存在周期性抖动。
固件走 RTT 输出日志时也是同一模式——hf.rtt.create(target) 启动会话、循环 rtt:read()
把日志落成文本(见 rtt — RTT 守护与终端),AI 归纳错误模式、聚类失败用例的效率远高于人眼翻屏。
案例三:烧录后自动验证(冒烟测试)
烧录成功不等于固件正常。让脚本烧完后停机检查全局状态、断言版本号,把"烧录 + 验证"合成 一个可进 CI 的步骤;断言直接写在源码符号层面,AI 从源码就能生成:
-- ai_smoke.lua —— 用法:HFLinkCLI ai_smoke.lua
local function check(value, message, code)
if value == nil then
error(string.format("%s (%d)", message, code))
end
return value
end
local device = check(hf.open(check(hf.devices())[1]))
check(device:start_dap())
check(device:set_interface("swd"):set_speed(10000000))
device:pack("STM32H723ZGTx@STM32H7xx_DFP")
check(device:connect())
local result, message, primary, cleanup = hf.flash.program(device, "app.elf")
if not result then
error(string.format("烧录失败:%s (primary=%d, cleanup=%d)", message, primary, cleanup))
end
local target = check(device:pack_target("P0"))
check(target:halt()) -- 停机读内存,避免读到撕裂数据
-- 表达式引擎:按 GDB 语法直接读 C 全局变量,类型信息来自 ELF
local sess = check(hf.expr.open("app.elf"))
sess:set_reader(function(addr, size)
return target:read_memory(addr, size) -- 返回 Buffer(string 亦可);失败返回 nil 即视为读取失败
end)
local version = check(sess:eval("g_fw.buildVersion"))
print(string.format("固件版本:0x%08X", version))
if version ~= 0x00030007 then
error("固件版本不符合预期")
end
local errors = check(sess:eval("g_sysStats.errorCount"))
print("错误计数:", errors)
if errors > 0 then
error("启动后出现错误计数")
end
sess:close()
check(target:resume())
device:disconnect()
device:close()
退出码即测试结论(0 通过、1 失败),CI 或产线 MES 只看退出码就能联动;排查失败时
把 stderr 里的错误三元组贴回给 AI 继续定位。
案例四:故障现场速查
目标跑飞、疑似 hardfault 时,先让脚本把现场"拍照",再把照片交给 AI 结合源码与 map 文件解读:
-- ai_crash.lua —— 用法:HFLinkCLI ai_crash.lua > crash_report.txt
local function check(value, message, code)
if value == nil then
error(string.format("%s (%d)", message, code))
end
return value
end
local device = check(hf.open(check(hf.devices())[1]))
check(device:start_dap())
check(device:set_interface("swd"):set_speed(10000000))
device:pack("STM32H723ZGTx@STM32H7xx_DFP")
check(device:connect())
local target = check(device:pack_target("P0"))
check(target:halt())
local names = { [13] = "SP", [14] = "LR", [15] = "PC" }
for number = 13, 15 do
print(string.format("%s = 0x%08X", names[number], check(target:read_reg(number))))
end
local sp = check(target:read_reg(13))
local stack = check(target:read_memory(sp, 128)) -- Buffer,解码一步到位
print("栈顶 128 字节:")
for i = 0, #stack - 4, 4 do
print(string.format("0x%08X: 0x%08X", sp + i, stack:le_u32(i)))
end
device:disconnect()
device:close()
把 crash_report.txt 连同问题现象贴给 AI:"PC 落在 0x0800xxxx,帮我判断是空指针、
栈溢出还是中断里调用了不可重入函数"。AI 通常会追问更多现场——异常状态寄存器 CFSR
(0xE000ED28)、完整的入栈寄存器组、调用栈回溯——这些都能用 pack_context():read32()、
target:read_memory() 继续采集。一问一答之间,人和 AI 就完成了一次完整的远程诊断。
实践建议与安全边界
先审查,再执行。AI 生成的脚本可能误解意图或 API;执行前人工通读一遍,尤其是涉及 烧录、整片擦除的脚本。拿不准时先让脚本走
dry_run/probe等只读路径。默认 safe 模式。案例中全部脚本都可在 safe 模式运行;只有确需读写本地文件 (如导出二进制采集文件)时才加
--privileged,此时更应严格审查脚本内容。 safe 模式不是完整沙箱,不要对不受信任来源的脚本运行(见 Lua 脚本模式)。一次一个目标。多台探针同时在线时,脚本默认取
hf.devices()[1];批量场景应让 AI 按序列号显式选择,避免烧错目标。反馈闭环要完整。执行后把 stdout、stderr 与退出码原样回贴给 AI,不要只转述结论; 错误三元组里的
message与code往往直接指出修正方向。把可复用的脚本沉淀下来。验证过的脚本进版本库,成为团队的调试资产——下次遇到同类 问题,AI 在旧脚本基础上小改即可,比从零生成更可靠。