dsh-go-adb-link
Manifest validAuto-finds the phone ADB TCP port and keeps adb connected, with a tool-layer risk guard and wireless-debugging pairing.
dsh-go-adb-link
DSH Go 原生插件:自动找到手机上的 ADB TCP 端口并保持连接。
本仓库:https://github.com/chen114514st/dsh-go-adb-link(二改版,版本 1.3.4) 二改于 https://github.com/usi112/dsh-go-adb-link 上游原版:https://github.com/edgy7493/dsh-go-adb-link
兼容性
- 适配 DSH Go 1.1.0(当前最新版;引擎
r15-dsh0.2.2-rc.1-node24.22.1,Android arm64),实测连接、面板、adb/adb_pair工具均正常。 - 1.0.16 也兼容:该版本新增了「本机 ADB shell 工具」和「Shizuku/本机 ADB 自更新」,两者都会碰到 adbd;实测升级后本插件的
127.0.0.1:3455通道会自动恢复,lastError为空,无需重连或重装。 - 1.0.15 可用;更早的版本没有验证。
- DSH Go 更新频率较高。升级到新版引擎后如果遇到连接异常、面板不显示、工具报错等问题,请到 Issues 提 issue,附上 App 版本号、引擎版本和面板里的
lastError,方便定位。
安装
二改版以 npm scoped 包发布:@zzchen/dsh-go-adb-link(官方市场条目用的是这个包名)。
上游原版仍占用非 scoped 的 dsh-go-adb-link(npm latest 1.2.4),不要和本版混装。用下面三种方式之一安装:
-
从插件市场或 npm 安装(推荐)
dsh plugin --profile web add @zzchen/dsh-go-adb-link -
GitHub 直装(紧跟本仓库源码)
dsh plugin --profile web add github:chen114514st/dsh-go-adb-link -
离线 tarball:从 Releases 下载
@zzchen/dsh-go-adb-link-1.3.4.tgz(npm pack 产物名为zzchen-dsh-go-adb-link-1.3.4.tgz)放到手机,然后dsh plugin --profile web add /sdcard/Download/zzchen-dsh-go-adb-link-1.3.4.tgz
想装上游原版(1.2.4,不含本仓库的行为边界与配对等改动)才用非 scoped 名:
dsh plugin --profile web add dsh-go-adb-link。
装完到 App 的「引擎」页重启一次引擎,输入框上方的状态条就会出现。
装完状态条立即出现在输入框上方;lib/ 代码改动需要到 App 的「引擎」页重启引擎。
首次授权(只需一次)
第一次连接时手机会弹出「允许 USB 调试吗」。请点允许,并勾选「始终允许使用这台计算机进行调试」。 勾了之后重连不再弹窗,插件才能全自动;没勾的话每次重连都要再点一次。
端口不是 3455 也能用吗
- 同一个手机换了端口:可以。点「连接」分两段扫描:先快速扫常见端口段(1024–10000),
几秒内找不到再全端口扫描(1–65535),发 ADB 握手找 adbd,不看端口号;扫描只认
CNXN/AUTH应答,并过滤 TCP 自连造成的误报。 - 另一个手机打开了 adb:插件跑在哪台手机的环境里就找哪台,不会去连别的设备的局域网端口。
- 经典 ADB over TCP(
adb tcpip、Stellar 的 TCP 功能)可以直接扫描找到。 - Android 11+ 原生「无线调试」是 TLS 配对端口,握手探测不到,改用下面的配对流程。
自动重连先试记住的端口和 3455、5555;都不通且之前授权过,会在后台走这两段扫描。
- AI 工具支持传
serial(等价于adb -s),多设备时不会连错机器。 - adb server 长时间掉线时,面板打开期间会每 5 分钟尝试
adb start-server一次,再自动重连。
固定端口与无线调试配对(1.3.0)
固定端口:面板上的「固定端口」会执行 adb tcpip 3455,让 adbd 固定监听 3455。
它要求当前已有传输(已连上的 TCP 或插着 USB),手机整个掉线时没有地方下发这条命令,
所以全端口扫描的兜底仍然保留。执行后 adbd 会重启一次、连接短暂断开,插件会等端口重新
监听再自动连上;tcpip 设置只对本次开机有效,手机重启或 adbd 重启后要再点一次。
个别厂商 ROM 会限制 adb tcpip,失败时面板会提示。
无线调试配对:Android 11+ 在「开发者选项 → 无线调试 → 使用配对码配对设备」里显示
IP、配对端口和 6 位配对码。让 AI 用 adb_pair 工具完成配对:配对成功后插件用
adb mdns services 找 _adb-tls-connect._tcp 服务并自动 adb connect,地址会记进
state.json 的 addr,以后自动重连直接用这个地址;找不到连接端口时,让 AI 用
connectPort 参数重试(端口就在「无线调试」主页面)。
配对码是敏感信息:只交给 adb 一次,不写 state.json、不进面板「最近命令」、不回显,
工具调用卡上也用 •••••• 代替。配对、连接、断开都属于建立调试通道,工具层直接放行,不再要求点「允许一次」。
TLS 配对记住的 addr 和固定端口的经典 TCP 是两条路径:点「固定端口」会清掉 addr、
切回经典模式;想再用无线调试就重新配对一次。
数据与安全
- 运行记忆写在
$DSH_HOME/dsh-go/adb-link/state.json(端口、是否授权、是否自动重连), 不在插件包内,卸载/升级不会带走或误发。 - 插件会执行本机的
adb程序;缺 adb 时会调用apt-get install -y adb。 - 不读取剪贴板、输入框、对话内容;只连
127.0.0.1上识别出的 adbd。 - 本机 adb server(
127.0.0.1:5037)与 bash 共享,所以插件连上后普通adb命令也能用。 - 截图(
adb exec-out screencap -p)按二进制保存成 PNG:优先/sdcard/Download/DSH-Go/,写不进去就放$DSH_HOME/dsh-go/adb-link/out/,不会把乱码塞进对话。
AI 行为边界
插件不再只是笼统要求「主动使用 adb」,而是把边界写进给 AI 的系统提示和工具说明里:
- 先说再做:AI 每次通过 adb 操作手机前,要先用一句话说明要做什么、为什么,不静默执行。
- 只读可直接查:
devices、getprop、pm list、dumpsys、logcat -d、截图、uiautomator dump、进程/电量/网络/温度查询这类不改变手机状态的命令,可以直接跑。 - 写文件也算写入:
logcat不带-c但带-f/--file/-r/-n会写存储,按写入操作处理,需要你同意。 - 系统级 / 写入先征得同意:安装卸载 APK、
appops改权限、settings put/delete、input模拟点击输入、am启动广播、强制停止、重启、删除或清空数据,必须先得到你的同意才执行。 - 红线不变:登录、支付、验证码、删除重要数据等敏感操作永远不通过 adb 执行,仍按原有规则先确认。
插件面板里也会显示这条说明。之所以收紧,是因为手机上常有账号和支付信息,而开启自动批准后命令可能不经确认就执行;这样 AI 的行为更容易被看见和拦住。
限制不是只写在提示词里
- 工具层会先给命令分级:只读放行;系统级 / 写入停下;
rm、pm clear、format、dd of=/dev/block/*、sideload这类删数据命令直接红线拦截,没有放行途径。 - 被拦下时,面板会显示 AI 想执行的命令,并出现「允许一次」「拒绝」两个按钮。点「允许一次」只放行这一条、这个参数,120 秒后失效;授权只在内存里,不写盘,也不改
state.json。 - 放行只对完全相同的参数有效;AI 换参数会被重新拦下,提示词也明确要求它不许换参数绕过。
故障排查
| 现象 | 原因 | 处理 |
|---|---|---|
| 状态条一直「ADB 未连接」 | adbd 没有开 TCP 调试 | 确认「无线调试」或 Stellar/TCP 已打开;插 USB 后点「连接」 |
连接报 Connection refused | 记住的端口已失效(重启、adbd 重启) | 点「扫描端口」,先快速段再全端口 |
| 卡在「等待授权」 | 手机弹窗没点允许,或没勾「始终允许」 | 在手机上点允许并勾选;不行就撤销调试授权后重连 |
| 扫描很久没结果 | 全端口段 1–65535 最坏约 46 秒(面板上限 58 秒) | 等它跑完;常见端口通常在快速段几秒内命中 |
| 「固定端口」报没有可用传输 | 当前没有 TCP 连接也没有 USB,adb tcpip 没有下发对象 | 先连上(或插 USB)再点「固定端口」 |
| 重启手机后 3455 失效 | adb tcpip 只对本次开机有效 | 重启后点「固定端口」,或让插件重新扫描 |
| 配对成功但连不上 | 无线调试的连接端口和配对端口是随机的 | 重新配对,或用「无线调试」主页的 IP:端口作为 connectPort 传给 adb_pair |
| 面板「上次错误」非空 | 上一次连接失败的类别 | unauthorized:去手机允许调试;no-device:端口通了但设备没就绪,重启 adbd 再连;connect-failed:端口失效,点扫描;tls-connect-failed:TLS 地址失效,重新配对 |
卸载
dsh plugin --profile web remove @zzchen/dsh-go-adb-link
也可以直接在 App 的插件详情里卸载。
更新日志
- 1.3.4:包名改为 npm scoped 的
@zzchen/dsh-go-adb-link并发布到 npm(非 scoped 名归上游);插件 id 与market-entry.json同步更新;补官方市场条目;功能与 1.3.3 相同。 - 1.3.3:扫描改为两段(先快速段 1024–10000,找不到再全端口),状态条区分「快速扫描 / 扫描端口」;面板新增「下一步」引导,按当前状态与
lastError给出可操作提示;README 新增「故障排查」表与lastError对照。 - 1.3.2:连接、断开、无线调试配对改判为只读档,不再要求面板「允许一次」(之前连上和 AI 重试要走两遍,体验很差);
adb tcpip、安装、改设置等系统级操作仍然需要放行;-s/-H/-P全局参数不再影响分级;补adb connect/adb tcpip分级单测。 - 1.3.1:
adb_pair纳入工具层 guard(配对按 confirm 处理,未放行时记进面板待允许,配对码只显示成••••••);risk.js把adb pair判为 confirm;修正配对工具说明里的语病;固定端口期间状态条显示「正在固定端口…」;host:port 拼接收敛到formatHostPort(),IPv6 地址统一加方括号;adbConnect遇到空目标直接报no-target;parseMdns去掉没有人用的 legacy 分支;README 补充 TLS 与固定端口互斥。 - 1.3.0:面板新增「固定端口」(
adb tcpip 3455,仅本次开机有效,需已有传输);新增 Android 11+ 无线调试配对工具adb_pair(配对码不落盘、mDNS 自动发现连接端口、地址记住后自动重连);logcat -f/--file/-r/-n写文件归入需同意;README 补固定端口与配对说明。 - 1.2.5:把 AI 行为边界从「提示词自觉」变成工具层强制:命令分只读 / 需同意 / 红线三级,面板新增「允许一次」「拒绝」,授权 120 秒过期且只对相同参数有效;截图按 PNG 落盘;工具支持
serial;snapshot请求去重、adb server 掉线低频自愈;测试改用临时DSH_HOME,无 ADB 通道自动跳过,新增单测与npm test。 - 1.2.4:新增面向 AI 的
adb工具(结构化参数、自动重连、原生结果卡);提示词改为「先说再做、系统级或写入操作先征得同意」(见「AI 行为边界」)。 - 1.2.3:连接成功后注入「主动使用 adb」的系统提示(系统级操作用 adb,不先问用户); 保留原有的自动查找端口、自动重连与面板。
- 0.1.0:首个版本,状态条 + 面板 + 自动连接。
License
MIT
Comments
Loading…
Similar plugins
by ZSeven-W
DeepSeek Harness plugin for Android — build, run, and interact with a live emulator or USB device stream inside a conversation, driven entirely through adb.
★ 361
↓ 882/wk
MIT
TypeScript
Nov 10, 2026
dsh plugin --profile web add @zseven-w/dsh-androidTaints the agent when tool results carry untrusted content, gates the privileged calls that follow, and refuses credentials passed to network-capable tools in every mode.
★ 0
dsh plugin --profile web add dsh-taintguardA PIN-protected, chat-only mobile web client for DeepSeek Harness, served on an isolated port over LAN or a self-provided tunnel.
★ 0
dsh plugin --profile web add dsh-mobile-accessA Phone tab in dsh-better-sidebar: SMS and calls over Twilio and SIP lines bridged through Asterisk, call audio through your server, Live, Voicemail and Do not disturb modes with live voicemail transc
★ 0
dsh plugin --profile web add @lucagiftzek/dsh-phoneAndroid companion bridge: QR-code LAN pairing with revocable device tokens and TLS fingerprints, a phone-connection and device-management panel, and an HTTPS access proxy serving sessions, live events
★ 5
↓ 60/wk
NOASSERTION
Go
dsh plugin --profile web add dsh-linksby JMINN0
安卓手机上的 adb 插件:在手机内部给自己开一个 adb shell,无需 root、无需电脑,关 WiFi 也能用。AI 助手用它可以装 App、看日志、截图、执行 shell 命令。 / Android adb plugin that gives an AI agent a real adb shell from inside the phone — no root, no PC.
★ 0
MIT
JavaScript
Nov 6, 2026
dsh plugin --profile web add dsh-go-plugin-adb