把鸿蒙云手机调试的 5 个坑写成 Skill：12 项检查清单与报错决策树

一次真实的 Skill 编写与使用记录。我在鸿蒙云手机上做 ArkTS 应用调试，同一个报错踩了三次、每次都要重新查一遍。于是把排查路径沉淀成一个 Skill，再用它把整条链路跑通。

环境与版本

项目	版本 / 规格
云手机	8 vCPU / 12 GB / 1260×2720，ALN-AL00
系统版本	HarmonyOS 5.0.1.130(SP2C00E1R4P1log)
设备 API	17
Command Line Tools	6.0.1.251
hvigor / ohpm	6.21.1 / 6.0.1
编译 SDK	HarmonyOS 6.0.1 (API 21)
JDK	17.0.21
hdspace CLI	2.3.3
宿主系统	Windows 11 x64

一、为什么这个问题值得写成 Skill

鸿蒙云手机调试有个特点：报错信息几乎都在骗人。

我遇到的四次：

yaml 复制代码

[Fail]Connect failed                              ← 隧道是活的，问题在 hdc 缓存
ERROR: 00303024 需要升级工程结构                    ← 实际是 modelVersion 缺失
hvigor WARN: No signingConfig found                ← 警告，未签名照样能装
error: failed to start ability.                    ← 应用其实已经起来了

前三次我都是从头查一遍，每次半小时起。第四次我意识到：这不是知识问题，是流程问题------步骤固定，但漏一步就得到错误结论。

这正是 Skill 适合解决的场景：把「先做什么、看什么、怎么判断」固化下来。

二、Skill 怎么组织

我没有写成一篇文档，而是拆成四块：

arduino 复制代码

hdspace-cloudphone-debug/
├── SKILL.md              主流程与决策树
├── references/
│   ├── errors.md         报错 → 真实原因对照表
│   └── hdc-cheatsheet.md hdc 常用命令
└── scripts/
    ├── reconnect.py      可靠的复位脚本
    └── run.sh            编译→安装→启动→截图 一条龙

2.1 输入：先固化环境事实

Skill 第一步不是执行命令，而是先把环境事实读出来，避免后续所有判断建立在错误假设上：

bash 复制代码

hdc -t 127.0.0.1:8712 shell "param get const.product.software.version; \
                             param get const.ohos.apiversion; \
                             param get const.product.model"

我的云手机返回 5.0.1.130 / 17 / ALN-AL00。这三个值决定了后续：

compatibleSdkVersion 能设多高
哪些 API 可用
竖屏还是折叠屏适配

如果不先读这三个值就改 build-profile.json5，很可能编出来装不上。

2.2 检查清单：12 项，按依赖顺序

Skill 的核心是一张有顺序的清单，不能乱：

markdown 复制代码

1. hdspace config 是否已配 AK/SK
2. hdspace cloudphone list 实例是否 Running
3. 隧道进程是否存活（不是看日志，是看进程）
4. 端口 8712 是否真的在 LISTEN
5. hdc kill → tconn 是否 Connect OK
6. hdc list targets 是否有设备
7. JAVA_HOME 是否指向 JDK 17
8. DEVECO_SDK_HOME 是否指向 sdk 目录
9. hvigor-config.json5 与 oh-package.json5 的 modelVersion 是否相等
10. AppScope 与 entry 下是否都有 app_icon.png
11. 是否声明 ohos.permission.INTERNET
12. 安装后截图验证，而不是看 aa start 返回值

第 3 步和第 4 步是关键：日志说成功不等于端口在监听。 我遇到过日志输出 connect to tunnel server success 但 netstat 里根本没有 8712 的情况------进程已经退出了。

2.3 决策树：一个报错怎么分流

references/errors.md 里最有用的一张表：

报错	先查	真实原因（我遇到过的）
`need connect-key`	命令是否带 `-t`	本地有多台设备，hdc 不知道指哪台
`Not match target founded`	`hdc list targets`	设备已掉线，需要重新 tconn
`Connect failed`	进程 + 端口	① hdspace 进程已退出 ② hdc 缓存了死连接
`00303024 Configuration Error`	两个 modelVersion	缺字段或两边不相等
`No signingConfig found`	无	警告，未签名可直接装
`failed to start ability`	hilog + 截图	应用已启动，返回值不可信

这张表是整篇 Skill 里被调用最多的部分。

2.4 验证断言：不靠返回值，靠证据

scripts/run.sh 最后一步固定是截图，不是看返回码：

bash 复制代码

hdc -t 127.0.0.1:8712 shell "snapshot_display -f /data/local/tmp/s1.jpeg"
hdc -t 127.0.0.1:8712 file recv /data/local/tmp/s1.jpeg ./s1.jpeg

截图存在、大小 > 10 KB、能打开------这三条都满足才算成功。

这是整个 Skill 里我最有把握的一条经验：鸿蒙命令行工具链的返回值不可靠，必须用产物验证。

三、实际使用：一次完整的排障

写完之后我立刻用了一次。场景：改完 ArkTS 后 hvigorw 卡住不动。

按 Skill 决策树走：

第 1 步，看进程。 hdspace 还在。

第 2 步，看端口。

bash 复制代码

netstat -ano | Select-String "8712"
# 无输出

端口没在监听------但日志还停在 connect to tunnel server success。

第 3 步，重启隧道。

bash 复制代码

hdspace cloudphone start-tunnel --name=HMCPhone_l36urR --port=8712

第 4 步，hdc kill 再 tconn。

bash 复制代码

hdc kill && hdc tconn 127.0.0.1:8712
# Connect OK

第 5 步，重跑编译。 18.3 秒通过。

整个过程不到 2 分钟。而第一次遇到这个问题时，我花了将近 20 分钟------一直在试 tconn，因为「日志说连上了」这个错误假设。

Skill 的价值就在这里：它把「我以为」换成了「我去查」。

四、哪些环节有效，哪些仍需人工判断

有效

报错对照表：命中率约 80%，四次报错里三次直接查表解决
12 项清单：拦住了两次配置错误（modelVersion 不一致、缺 app_icon）
截图断言：避免了「以为成功了其实白屏」的误判

仍需人工

UI 层面的问题：Skill 只能判断「有没有画面」，判断不了「布局对不对」。我第一次跑出来的界面按钮位置偏了，截图看不出来，是手动点的
编译错误的具体代码位置 ：00303024 这类配置错误能定位，但 ArkTS 语法错误还是要看完整日志
云手机被回收 ：剩余时长耗尽后所有命令都失败，但报错和「没连上」一模一样，Skill 里只能加一条「先看 cloudphone list 的剩余时长」提醒

一次误判

我有一次按 Skill 走完全部 12 项，全部通过，但应用就是没起来。

最后发现是 module.json5 里 mainElement 写成了 EntryAbility 而实际文件名是 entryability/EntryAbility.ets------路径对但大小写敏感。

这个不在清单里，也没法预判。Skill 降低了重复劳动，但它不能替代理解。

五、改进记录

用了 5 次之后，我改了三处：

把「看日志」改成「看进程 + 看端口」 ------ 日志骗过我两次
把 tconn 单独一步改成 hdc kill && tconn ------ 合并后不会再漏
加了「先读设备 API 版本」作为第 0 步 ------ 避免 SDK 版本设错

第 2 条改动收益最大。原来分两步写，我总是在着急的时候跳过 hdc kill，然后浪费十分钟。

六、效果

用 Skill 之前 vs 之后：

场景	之前	之后
隧道掉线恢复	约 20 分钟（反复试错）	约 2 分钟（照清单走）
modelVersion 报错	约 40 分钟（翻源码）	直接查表
判断应用是否启动	反复看日志	一张截图
完整链路跑通	2 小时+	约 15 分钟

七、代码与数据

完整 ArkTS 工程、调试脚本与实测日志：

仓库：gitcode.com/cpyaxjq/har...
工程：apps/harmonyshadow/（可直接 hvigorw assembleHap）
脚本：scripts/hdc_wrap.py（可靠的 hdc 复位封装）

同系列另一篇《不装 DevEco Studio：用官方 CLI 把 ArkTS 应用装进鸿蒙云手机》讲工具链细节。

八、一点判断

Skill 不该追求「替代人」，而应该追求「让同一类错误只花一次时间」。

我写的这个 Skill 里没有一句是「AI 帮我想到的」------每一条都来自一次真实的、浪费了半小时的失败。它现在能帮我在 2 分钟内恢复，只是因为我先在里面失败了 5 次。

如果你的工作里有「步骤固定、但漏一步就出错」的环节，那就是值得写成 Skill 的地方。