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

环境与版本

项目版本 / 规格
云手机8 vCPU / 12 GB / 1260×2720,ALN-AL00
系统版本HarmonyOS 5.0.1.130(SP2C00E1R4P1log)
设备 API17
Command Line Tools6.0.1.251
hvigor / ohpm6.21.1 / 6.0.1
编译 SDKHarmonyOS 6.0.1 (API 21)
JDK17.0.21
hdspace CLI2.3.3
宿主系统Windows 11 x64

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

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

我遇到的四次:

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

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

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

二、Skill 怎么组织

我没有写成一篇文档,而是拆成四块:

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

2.1 输入:先固化环境事实

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

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 的核心是一张有顺序的清单,不能乱:

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 foundedhdc list targets设备已掉线,需要重新 tconn
Connect failed进程 + 端口① hdspace 进程已退出 ② hdc 缓存了死连接
00303024 Configuration Error两个 modelVersion缺字段或两边不相等
No signingConfig found无警告,未签名可直接装
failed to start abilityhilog + 截图应用已启动,返回值不可信

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

2.4 验证断言:不靠返回值,靠证据

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

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 步,看端口。

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

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

第 3 步,重启隧道。

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

第 4 步,hdc kill 再 tconn。

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 次之后,我改了三处:

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

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

六、效果

用 Skill 之前 vs 之后:

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

七、代码与数据

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

  • 仓库:https://gitcode.com/cpyaxjq/harmonyos-cloudphone-task-continuation
  • 工程:apps/harmonyshadow/(可直接 hvigorw assembleHap)
  • 脚本:scripts/hdc_wrap.py(可靠的 hdc 复位封装)

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

八、一点判断

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

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

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

Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐