开源 · Apache 2.0 · 给 AI 用的硬件调试工具包Open source · Apache 2.0 · a hardware debugging toolkit for AI

板子在外地死机了。
三个 AI 已经进去看了。
Your board just crashed
in another city.
Three AIs are already inside.

DeviceHands 让云端的大模型、你身边的本地模型、设备里的小模型一起调试真实硬件:亲自进到设备里去查,互相商量,再把结论画给你看。 DeviceHands lets a large cloud model, a local model near you and a small model on the device debug real hardware together: they go inside the device, talk it over, and draw you the answer.

01现场The scene

外地的设备,
半夜死机了
A device far away
dies at night

可能是手机、电视、音箱、电脑,也可能是一台服务器——里面都有一块板子。没有人在旁边。住在设备里的小模型第一个发现。A phone, a TV, a speaker, a computer or a rack server: there is a board inside each of them. Nobody is around. The small model that lives on the device notices first.

  • 设备端模型 · 规划中On-device model · planned

02本地模型The local model

离得最近的
先接手
The closest one
takes it first

实验室电脑上的本地模型,经 USB 和串口直接连着设备。它把启动日志、崩溃记录、上次死机留下的现场都取回来。The local model on the lab PC is wired to the device over USB and serial. It pulls back the boot log, the crash records and what the last crash left behind.

  • 本地模型用设备工具 · 现在能用Local model with device tools · shipped
  • 串口 · adb · 烧录 · 现在能用UART · adb · flashing · shipped

03主脑The main brain

最强的那个,
在你身边
The strongest one
stays with you

主脑可能在你家里的电脑上,也可能在云端。实验室的台架主动连回来,隔着城市,它照样读得到日志、下得了命令。The main brain may run on your own machine or in the cloud. The lab bench dials home, so from another city it can still read the logs and run commands.

  • 两地调试 · 现在能用Two-site debugging · shipped
  • Claude Code · Cursor · Codex

04讨论The discussion

三个地方,
一场讨论
Three places,
one discussion

三个模型能力不同、位置不同,看到的也不同。它们交换证据,互相追问,谁也不靠猜。Three models with different strengths in different places see different things. They trade evidence and question each other. Nobody guesses.

  • 多模型同桌讨论 · 规划中Models in one thread · planned

05工具包The toolkit

进到设备里,
打开工具包
Go inside,
open the toolkit

光看日志不够,就亲自进去。设备里面什么分析工具都没有,所以它们带了自己的:DeviceHands 工具包。日志、崩溃记录、时间轴、搜索,都在里面。When logs are not enough, they go in. There are no analysis tools on the device, so they bring their own: the DeviceHands toolkit. Logs, crash records, the timeline and search are all in it.

  • 在设备上执行命令 · 现在能用Run commands on the device · shipped
  • 内存 · 跟踪 · 规划中Memory · tracing · planned

06勘查The search

找到 PC 指针
停下的地方
Find where the
program counter stopped

程序跑到哪一条指令停的,调用栈一层层是谁叫的谁,那个指针指到了哪里。工具把零散的日志对到一条时间轴上,直接画出来。Which instruction it stopped on, who called whom up the stack, where that pointer went. The tools line the scattered logs up on one timeline and draw it.

  • 时间轴 · 崩溃记录 · 现在能用Timeline · crash records · shipped
  • PC 指针定位 · 规划中PC analysis · planned

07主脑出手The main brain steps in

卡住了,
主脑亲自来
Stuck.
The main brain comes in.

本地模型看到了现象,找不到原因。主脑自己进来看一眼,把三方的发现连成一条线:3 秒前,另一段代码把这个指针清零了。The local model sees the symptom but not the cause. The main brain comes in to look for itself and joins the three sets of findings into one line: 3 seconds earlier, other code cleared this pointer.

  • 主脑直接操作设备 · 现在能用Main brain drives the device · shipped

最后交到你手上的,
是一份看得懂的报告
What reaches you in the end
is a report you can read

结论Finding
存储驱动用了一个已经被清零的指针。The storage driver used a pointer that had been cleared.
证据Evidence
PC 位置 · 5 层调用栈 · 对齐后的时间轴PC location · 5 stack frames · the merged timeline
下一步Next
补丁已备好,要我烧进去再跑 20 次确认吗?A patch is ready. Flash it and run 20 boots to confirm?

故事里的 bug 和数据是编的,用来演示流程。The bug and the data in this story are invented to show the flow.

传统调试工具把日志交给你。DeviceHands 把结论交给你,附上证据,再画成一张你看得懂的图。 Traditional debug tools hand you the logs. DeviceHands hands you the conclusion, with the evidence, drawn as a picture you can read.

TP02 · 脑MINDS

一个 bug,
几个模型一起看
One bug.
Several models on it.

云端大模型负责推理,本地小模型守着整条日志流。它们交换证据、互相质疑,最后交给你一份看得懂的报告。这是它和传统调试工具最不一样的地方。A cloud model does the reasoning while a small local model reads the whole log stream. They trade evidence, challenge each other, and hand you a report you can read. This is where it parts ways with traditional debug tools.

启动偶尔卡 40 秒Boot sometimes stalls 40 s概念示意 · 对话是手写的Concept · hand-written
  1. 你You

    升级之后,板子偶尔开机要卡 40 秒。帮我看看。After the update the board sometimes stalls 40 s at boot. Take a look.

  2. 主脑Main brain

    我先复现。已经重启 5 次并录下串口,第 3 次卡住了。Reproducing first. Rebooted 5 times with the serial port recording; run 3 stalled.

    reboot ×5 · uart capture · 5 logs saved
  3. 值守Watcher

    5 份日志我都读完了。卡住那次,存储初始化重试了 3 遍;另外 4 次一遍就过。Read all 5 logs. In the stalled run storage init retried 3 times; the other 4 passed first try.

    [ 2.104] mmc0: init retry 1/3
    [ 15.310] mmc0: init retry 2/3
    [ 41.782] mmc0: ready
  4. 板上On board

    卡住那次我这边还在。重试期间别的进程都在等这块存储。I was still up during the stall. Everything else was waiting on that storage device.

  5. 主脑Main brain

    对上了:时间都耗在 2.1 s 到 41.8 s 之间的重试上。我去看驱动里这次升级改过的超时设置。That lines up: the time went into retries between 2.1 s and 41.8 s. Checking the timeout this update changed in the driver.

  6. 给你的报告Report for you
    结论Finding
    存储初始化偶发重试,每次多等约 13 秒。Storage init occasionally retries, about 13 s each time.
    证据Evidence
    5 次启动里 1 次复现 · 3 行串口日志 · 时间轴截图1 of 5 boots · 3 UART lines · timeline snapshot
    下一步Next
    改回超时值,再跑 20 次启动确认。要我现在做吗?Restore the timeout and run 20 boots to confirm. Shall I?
现在能用Shipped

你的编程助手(Claude Code、Cursor、Codex)经 MCP 直接调板子;自带的网页助手和命令行对话可以跑在本地模型(Ollama、任何 OpenAI 兼容服务)或云端 API 上,用的是同一套板子工具。Your coding agent (Claude Code, Cursor, Codex) drives boards over MCP. The built-in web assistant and CLI chat run on a local model (Ollama, any OpenAI-compatible server) or a cloud API, with the same board tools.

规划中Planned

几个模型和你坐在同一个对话里查一个 bug;本地小模型自己盯日志流;设备端模型。上面那段对话是这个功能的概念示意,不是模型真实输出。Several models and you in one thread on one bug; a local model that watches the stream by itself; an on-device model. The conversation above is a concept of that feature, not real model output.

TP03 · 眼EYES

结论不是一段文字,
是一张会动的图
The answer is not a paragraph.
It is a picture that moves.

模型分析完,直接画给你看:哪一秒出的事、内存从哪开始涨、时间花在了哪个函数上。一眼看懂,再决定要不要往下追。When the models are done they draw it for you: which second it went wrong, where memory started to climb, which function the time went into. Read it at a glance, then decide whether to dig.

时间轴Timeline现在能用Shipped
UARTlogcatkernelevents −3.0 s reboot
内存曲线Memory规划中 · 示意Planned · concept
leak starts · +1.8 MB/min
时间花在哪Where time goes规划中 · 示意Planned · concept

时间轴今天就在网页界面里。内存、性能、调度这几类分析图属于规划中的 Linux 分析工具箱,上面两张是示意,数据是编的。The timeline is in the web UI today. Memory, performance and scheduler views belong to the planned Linux analysis toolbox; the two charts above are concepts with invented data.

TP04 · 手臂REACH

板子在外地,
大脑在云端
The board is far away.
The brain is in the cloud.

模型分在三个地方:云端的大模型做核心大脑,本地电脑上的模型守着日志,板子上的模型就在现场。板子可以在另一个城市的实验室里,台架上的小程序主动连回来,实验室不用对外开任何端口。The models sit in three places: a large model in the cloud is the core brain, a model on your local machine watches the logs, and a model on the board is right at the scene. The board can be in a lab in another city; a small agent on the bench dials home, so the lab opens no inbound ports.

  • 串口、USB、烧录,隔着网络照样用Serial, USB and flashing all work across the network
  • 台架上的程序可以远程更新,不用人去现场The bench agent updates remotely; nobody walks to the lab
  • 云端和本地的模型今天就能用;板上模型在规划中Cloud and local models work today; the on-board model is planned
  • 一台台架接多块板、多个串口:正在做Several boards and serial ports per bench: in progress

TP05 · 接入PLUG IN

接进你已经在用的 AIPlugs into the AI you already use

谁来用这双手Who uses the hands

  • Claude Code
  • Cursor
  • Codex
  • 任何 MCP 客户端Any MCP client

模型放在哪Where the models run

  • 云端 APICloud APIs
  • Ollama
  • OpenAI 兼容服务OpenAI-compatible servers

手怎么碰到板子How the hands reach a board

  • adb
  • UART
  • ssh
  • fastboot
  • EDL 9008
  • 厂商工具Vendor tools
36个 MCP 工具MCP tools
3,037条自动测试automated tests
3种接入:MCP · 命令行 · 网页ways in: MCP · CLI · web
Apache 2.0开源,可商用open source, commercial use OK

TP06 · 路线ROADMAP

这双手会越来越巧The hands keep learning

现在能用Shipped

  • 串口、adb、ssh、fastboot、9008、厂商下载工具UART, adb, ssh, fastboot, EDL 9008, vendor download tools
  • 整包烧录,写之前核对板子身份Full-package flashing with a board identity check first
  • 多路日志对时的时间轴和搜索Merged-clock timeline and log search
  • 两地调试:板子在实验室,模型在别处Two-site debugging: board in the lab, models elsewhere
  • 网页界面和自带助手,可跑本地模型Web UI with a built-in assistant that can run on a local model

正在做In progress

  • 一台台架接多块板、多个串口Several boards and serial ports on one bench

规划中Planned

  • 模型圆桌:几个模型同桌讨论,给人汇报Round table: several models discuss and report to you
  • Linux 分析工具箱:内存泄漏、性能、调度、eBPF,结果画成图Linux analysis toolbox: leaks, performance, scheduler, eBPF, drawn as charts
  • 不跑 Linux 的设备Devices that do not run Linux
  • 更多调试技能,按产品类型扩展More debugging skills, extended per product type

TP07 · 开始START

三步,把手接上Three steps to attach the hands

bash
# 1 · 装好(不需要 root)install (no root needed)
git clone https://github.com/TbusOS/android-llm-bridge
cd android-llm-bridge && ./scripts/install.sh

# 2 · 看看它够得到什么see what it can reach
uv run alb status
uv run alb devices

# 3 · 把手交给你的 AIhand it to your AI
claude mcp add alb -- uv run --project "$PWD" alb-mcp

代码目前在 android-llm-bridge 仓库,正在改名为 DeviceHands;命令行工具叫 alb。然后对你的 AI 说一句:「帮我看看这块板子为什么起不来。」The code lives in the android-llm-bridge repository for now and is being renamed to DeviceHands; the command-line tool is called alb. Then tell your AI: "find out why this board will not boot."