본문으로 건너뛰기
M

dsh-harmonyos-agent

mobius-2046/dsh-harmonyos-agent

HarmonyOS(ArkTS) 앱 개발 에이전트입니다. build, install, launch, hilog, screenshot, crash log, UI dump/tap/assert를 포함한 15개 작업의 harmony 도구와 Web UI 로그 패널을 제공합니다.

설치

dsh plugin --profile web add github:mobius-2046/dsh-harmonyos-agent

README

dsh-harmony

version license platform actions

把「改 ArkTS → 等编译 → 装真机 → 翻 hilog → 再改」这条循环,变成一句话交代:agent 自己跑完,并把证据(编译结论、安装结果、启动画面、日志)摆回你面前。

hilog 日志面板:设备切换、级别筛选、实时跟随、快照对比

这东西给谁用

写给正在做鸿蒙应用、并且已经在用 DevEco Studio 把工程跑起来的人:

  • 工程在本地,hvigorw、hdc、签名配置都能用;真机或模拟器插着。
  • 每天的动作是重复的:改几行 ArkTS、等两分钟编译、装到手机、点开、看 hilog 里那条报错。
  • 你想用自然语言把这串动作交代出去,而不是亲手点十六下;出错时希望它先读第一条错误再改,而不是盲改。

不是给这些场景的:只想点预览器看效果、不做真机调试的人;没有 hdc 设备的人;期待它替代 DevEco 的断点调试、内存分析、UI 预览器的人——那些我没做,也不假装能做。

你现在这样干,装上之后

现在装上之后省掉什么
改完代码,切到 DevEco,点构建,等进度条一句「改完跑一下真机」,agent compile 先做类型检查、再 run 构建装机切窗口、盯进度条
装完手动点开应用,看有没有崩run 一次做完:装包、补 HSP、拉起、抓 6 秒日志三次点击 + 一次等待
日志窗口里按进程名筛,滚很久找那条 FATALlogs 给包名就只留这个进程的行;crash 直接读最新崩溃日志并解出栈顶帧手筛、翻文件
报错看不懂:9568305、EBUSY、签名不过错误码表给处置建议,失败后一行「接下来做什么」搜论坛、反复试
改完不确定界面对不对screenshot 截图、ui op=assert 断言文字/个数/指纹肉眼比对
想确认某接口从哪个版本开始有docs op=api 查本地 SDK 的 @since翻官网、等加载

一分钟上手

前置:Windows、dsh >=0.2.1-rc.5、DevEco Studio 6.x(提供 hvigorw 和 hdc)、设备已连上 hdc list targets。

# 1. 安装(插件页选目录,或命令行)
dsh plugin --profile desktop add file:<本目录>

# 2. 重启一次 Harness(浏览器半边与日志面板要重新加载)

# 3. 新建会话,预设选择器里选 HarmonyOS

预设选择器里的 HarmonyOS 卡片

然后第一句话可以是:

/plan 给这个工程加一个设置页,带深色模式开关

它只读调研、给方案和验证命令;你批准(或 /build)后进 build,改完代码自己构建、装机、拉日志。

它提供什么

部件内容
预设 harmony与官方 standard 同源的编码工具面,人格换成鸿蒙专家;运行时注册,不占用官方预设位
命令/build(plan 停在半路时直接开工)、/mode(看当前 plan / goal 状态)、/goal(要求写清完成判据与验证方式);/plan 是宿主内置
技能harmony-project、harmony-arkts、harmony-build-deploy、harmony-ohpm
工具一个 harmony,十五个动作,见下表
日志面板侧边栏 hilog 图标 → 全屏日志页:设备切换、级别/进程/关键字过滤、实时跟随、快照与对比
设备徽标侧边栏左下角的小手机图标:绿色胶囊=在线台数;点开看每台的机型、序列号、API、电量、温度、内存与存储

三个模式不是三个 agent,而是同一个会话的三种状态:

模式进入方式行为
plan/plan只读调研,产出方案,exit_plan_mode 提交审批;工具层面拒绝构建/装机
goal/goal <目标>;完成判据:<可观察结果>;验证方式:<命令>持久目标 + 自动续跑;缺判据或验证方式会被拒绝,避免「一轮轮继续」
build关闭 plan 后的默认状态直接改文件并构建验证

十七个动作

action做的事
buildhvigorw assembleHap(hsp: true 时再跑 assembleHsp),返回产物、是否已签名、结构化错误
compile只做 ArkTS 类型检查,约是完整构建的一半时间
depsohpm install --all:改了 oh-package.json5 之后同步依赖
runbuild → 装包 →(HSP)补依赖 → aa start → 抓日志,五段结论;matrix 可按设备分工;plan 模式下拒绝
devices列出设备与机型、API、电量、温度、内存、存储
deploy装指定 .hap,可选拉起;支持多设备
logs限时抓 hilog;给 bundleName 就按 pid 只留这个应用;filter 用子串或 /regex/flags;默认返回摘要(级别计数、重复折叠、错误列表),view: "raw" 看原文
screenshot抓设备截图到本地,返回路径与分辨率
appop=start/stop/clear/uninstall 启停、清数据、卸载;op=query 查装没装、什么版本(只读)
doctor一次查完 hdc / 设备 / SDK / hvigorw / 签名 / shared 产物 / ohpm;fix: true 时顺手修三类验得出的问题
sign核对签名材料与证书有效期;op=verify 验已有签名;op=rebuild 让 hvigor 重签一次
uidump 读控件树;find 只查不点;wait 等文字出现/消失;assert 断言界面(文字、个数、指纹),device=all 逐台跑出一张表;tap/input/key/swipe 操作
fileop=pull 拉回、op=send 推上去;op=ls 列目录、op=cat 读文本开头、op=du 算目录大小(这三个只读,plan 模式下也能用)
crash读最新 jscrash / cppcrash / appfreeze,解出进程、原因、栈顶帧
docs离线文档:config 配目录、search 查关键词、read 读原文、api 查接口的 @since
db看应用自己的 SQLite:op=list 列出沙箱里的 .db,op=query 跑一条只读语句(拒一切写操作)
trace抓一段 hitrace:返回事件类型与进程排行,原始 .ftrace 留给 perfetto

多台设备有两种写法:device="all" 或 device="a,b" 设备列表;每台要做不同的事就用 matrix:

matrix: "009180680c438f8f=install;03516892320539=run"

run 只编译一次;结果是一张「设备 × 动作 × 结果」的表,没启动的行写 — 而不是 0。写法错(动作拼错、同一台写两次、id 不在线)在编译之前返回。

想先看它跑一次?用这个示例工程

仓库里带了一个最小工程 samples/hello-app(一个按钮、一个计数器,没有第三方依赖),构建 10 秒左右:

# 1. 让工具找到工程(第一次需要 local.properties,内容一行 sdk.dir=…)
harmony build projectDir=<仓库>/samples/hello-app
# 2. 装到真机并看日志(先按上一节配好签名)
harmony sign op=sign projectDir=<仓库>/samples/hello-app
harmony run projectDir=<仓库>/samples/hello-app device=all

看到 hello-app: tap 1 那行日志,就说明整条链路是通的。

签名:工程的事,sign 只负责核对与验签

自动构建默认出 unsigned HAP,真机装不上。签名材料配在工程自己的 build-profile.json5(DevEco 的 Signing Configs 写进去的就是它),hvigorw assembleHap 会直接签出 *-signed.hap——所以本插件不接触密码,也不需要你在这里填:

  • sign(默认 op=report):材料在不在、证书什么时候过期、products 引用的配置是否存在。plan 模式可用。
  • sign op=verify:拿 hap-sign-tool verify-app 验已签的那份,确认证书链与 profile 都对得上。
  • sign op=rebuild:让 hvigor 重新构建并签名一次(等价 build,只是目的不同)。

build-profile.json5 里的 storePassword/keyPassword 是 DevEco 的本地加密串,只有 DevEco 和 hvigor 解得上——仓库里放它没问题,本插件也从不尝试解密。

打开代码面板

左侧栏第二个图标是只读的工程浏览页:左边文件树,右边源码,顶上能按名字找 struct / class / interface / function。填一次工程目录会记住(存在浏览器本地),下次打开直接点「加载」。

它只读源码和 .json5 / .md,不写、不改、不监听文件变化;node_modules、build、.hvigor 这类目录会跳过。目的是「确认这段逻辑到底怎么写的」时不用切 IDE——要改代码还是回编辑器。

翻手机上的文件

不用把文件拉回本机也能看:

harmony file op=ls remote=/data/local/tmp        # 目录在前,带大小与时间
harmony file op=cat remote=/data/local/tmp/app.log   # 只读开头 64 KB,用 seconds 改预算
harmony file op=du remote=/data/log              # 这个目录占多少

这几个 op 只认设备上的绝对路径(/data/...),不认 Windows 盘符。路径不存在时会把 ls/head 自己的报错原样带出来,不会骗你说「是空的」。

抓一段 trace

卡顿、丢帧这类问题,先看那一秒到底在跑什么:

harmony trace seconds=2 categories="ace app sched"

返回的是摘要(事件类型排行、进程排行、时间跨度、缓冲区有没有写满),原始文件落在 %TEMP%/dsh-harmony-trace/ 下,可以直接拖进 perfetto 看火焰图——本插件不做火焰图,只保证「先看一眼」不用开 IDE。

设备上如果 DevEco 的 Profiler 正开着,hitrace 会报 OpenRecording failed, errorCode(1103);这个错误会原样转述,并提示关掉 Profiler 或重启设备(这台机器上重启是唯一能恢复的办法)。

看应用里的数据库

调试时最常问「这条记录到底存成什么了」:

harmony db op=list bundleName=com.example.app
harmony db op=query bundleName=com.example.app remote=/data/app/el2/100/database/com.example.app/entry/rdb/USER.db \
  sql="select * from USER limit 5"

数据库先从设备拉到 %TEMP% 再打开(带 -wal/-shm,读到的是最新状态),打开方式是只读,语句只放行 SELECT / WITH / PRAGMA / EXPLAIN——写操作会被直接拒绝,不是靠自觉。应用沙箱里的库通常要 root 设备(hdc shell id 看 uid)。

看日志与查文档

点侧边栏 hilog:选设备 → 灌入最近 120 行 → 实时追加。按级别、进程、关键字过滤都在浏览器里完成,不重连。

对话里问"有没有报错",不需要把 200 行灌进来:logs 默认给一份摘要——记录条数与时间范围、错误/警告计数、按次数排的错误前几条、出现最多的重复行(×48 这种)。大概十来行,先回答"坏没坏、坏在哪",要看原文再加 view: "raw"。

复现问题前点 快照 存基准,修完再存一份,点 对比:按行出现次数报「新增 / 消失 / 相同」。快照可以改名、导出 .log、单条删除,名字与内容存在浏览器本地。

查接口先配一次文档目录(离线,不联网):

harmony  action=docs  op=config  dir=D:\docs-openharmony-6.1-release\zh-cn\application-dev
harmony  action=docs  op=config  sdk=D:\SDK\Openharmony-6.0\20\ets\api

之后 docs op=search / op=read / op=api。搜索有硬预算(4000 文件 / 64 MB / 10 秒),停下时说清扫了多少、为什么停——「没扫完」不会说成「没有」。

边界

  • 只支持 Windows(启用 tool-pwsh、关闭 tool-bash)。
  • 工程目录必须可写:hvigor 要写 <project>/.hvigor 与 build/。
  • 签名归工程:build-profile.json5 里没配 signingConfigs 就只会出 unsigned,真机装不上。本插件不存密码——配好之后 hvigorw 自己签,sign 只核对与验签。
  • run 的「日志为空」是正常结果,不等于「没有崩溃」。
  • 同一工程同时只允许本工具发一个构建(第二个会被锁挡回);DevEco Studio 自己的构建只能靠 EBUSY 发现。

发版记录

版本主要变化
0.38.0只读代码面板:文件树 + 源码 + 按名字找符号
0.37.0trace:抓一段 hitrace 并给摘要,原始文件交 perfetto(不做火焰图)
0.36.0db:列应用数据库、跑只读 SQL(拒写操作),真机验证
0.35.0file 加 ls / cat / du:不拉文件也能看目录、读文本开头、算占用(只读,plan 下也可用)
0.34.0logs 默认返回摘要(级别计数、重复折叠、错误列表),回答"有没有新错误"
0.33.0sign 收敛为 report / verify / rebuild:删掉设置页填密码与凭证库,密码回到工程配置
0.32.2适配 DSH 0.2.2:Fetch 路由改在 ctx.effect 里注册,面板与设备浮层恢复
0.32.1缺 local.properties 时 build / doctor 直接说该建哪个文件
0.32.0sign op=sign/verify 真签名 + 设置页填密码(只存本机)
0.31.2修:deploy / run 收到 D:/... 形式的路径会装不上(hdc 需要反斜杠)
0.31.1修:两台设备的 matrix 被误判成「设备没连接」
0.31.0ui op=assert 支持 device=all,结果为「N/M 台符合预期」+ 每台一行
0.30.0run 支持 matrix:一条调用里按设备分工,结果是一张表
0.29.0app op=query 查安装状态与版本
0.28.0快照可改名、导出 .log、单条删除
0.27.0ui op=assert 断言界面:文字、个数、指纹
0.26.0doctor fix: true 修残留构建锁、缺 pnpm wrapper、缺 HSP 产物
0.25.0run 失败按首错归类,给「接下来做什么」
0.24.0同一工程同时只跑一个构建
0.23.0ui op=wait 等文字出现或消失
0.22.0sign 核对签名配置与证书有效期
0.21.1设备徽标标出「上次使用」并可切换
0.21.0doctor 每项探测限时,超时与「没来得及跑」分开报
0.20.0离线文档:docs 的 config / search / read / api
0.19.0错误码处置建议、记住上次设备、ui op=find
0.7.0–0.18.0多设备、plan 守卫、HSP 分层安装、快照对比、截图、app、doctor、ui、logs 过滤、file、compile、crash、/goal、deps、日志按 pid

完整动机与细节见 CHANGELOG.md,安装包见 Releases。

更多

  • docs/design-notes.md:给维护者——踩过的坑、改代码何时要重启、工具 schema 陷阱、为什么预设是运行时注册的。
  • docs/roadmap.md:接下来做什么、以及不做什么。
  • LICENSE:MIT。

관련 플러그인