前言

我把一个真实的鸿蒙工程(ArkTS + 一个 entry 模块,含分布式数据同步与麦克风权限声明)在 CodeArts Agent 里打开,本来只想做一件很简单的事:点一下运行,看看界面。

结果发现编辑器右上角根本没有运行按钮,Run and Debug 面板一片空白。

这件事最后查清楚了,结论比“缺个配置”复杂,也比“这个 IDE 不能用”乐观:CodeArts Agent 是一个定位非常明确的 AI 编码前端,它的能力边界画得很清楚——写代码很强,跑应用要靠 DevEco。这篇文章把这中间的全部过程、证据、配置和踩坑都记下来,你可以直接照着复现。

全文基于一次真实排查,所有命令输出、日志原文、耗时数字都来自我本机(macOS arm64)。版本信息见第二节,换版本后细节可能变化。

一、结论先行:它到底是什么

先说定性。CodeArts Agent 的 product.json 里有几个关键字段:quality: stable、版本 26.11.100、Electron 39.3.0、扩展市场指向 marketplace.ide.huaweicloud.com,并挂了一个 Open VSX 作为补充源。它的用户数据目录结构——User/workspaceStorage、extensions.json、argv.json、languagepacks.json——是标准的 VS Code 那一套。

所以它和 Trae 属于同一类产品:VS Code 的深度定制发行版 + AI 编码 Agent。自带扩展里除了 git、python、java、cpp、dart 这些通用语言包,就是华为自己的 huaweicloud.authentication、huaweicloud.codearts-agent-support、huaweicloud.codearts-pay、huaweicloud.resource-explorer,再加上一个完整的 AI 聊天栈(chat_sessions、chatLanguageModels.json,日志里还能看到 chatParticipantPrivate 这类 API 提案)。

它把鸿蒙工程当成“另一种语言的项目”来处理,不负责构建与部署。这一点不是猜测,下面第三节给证据。

内容方向里说的“码道”,是华为云 CodeArts 的代码智能体品牌;我这次实测用的是它在本机的桌面 IDE 形态——CodeArts Agent。下文的结论对“用码道写鸿蒙”同样成立:它擅长把代码写对,但不负责把应用跑起来。

请添加图片描述

一句话概括这个分工:CodeArts Agent 是“笔”,DevEco 是“手和腿”。

二、实测环境

项目值
主机macOS arm64
CodeArts Agent26.11.100(Electron 39.3.0)
DevEco Studio A/Applications/DevEco-Studio.app,版本 26.0.0,SDK API 26
DevEco Studio B/Applications/DevEco-Studio-6.1.1.app,版本 6.1.1,SDK API 24
官方扩展HuaweiDeveloperServicePlatform.harmonyosdevassistantforvscode 0.2.4(darwin-arm64,76.5 MB)
构建用 NodeDevEco 自带 node v24.14.1
被测工程一个真实项目 + 一个从模板新建的最小工程

顺带说一个容易被忽略的点:机器上装了两套 DevEco,SDK 版本不同(API 26 和 API 24)。选哪一套不是随便挑的,要看你工程上次是用谁编译的——第五节会给出判断依据。


三、第一现场:为什么“没有运行按钮”

3.1 先别怀疑配置

遇到“按钮不见了”,大多数人的第一反应是找设置项。但对 VS Code 系 IDE 来说,按钮是扩展“贡献”出来的,不是设置开关。所以排查顺序应该是:这个按钮,由谁创建?它还在不在?

请添加图片描述

3.2 三个证据

证据一:运行视图指向一个不存在的文件。 CodeArts Agent 把窗口状态存在 workspaceStorage/<hash>/state.vscdb(SQLite)。查一下就能看到:

debug.selectedroot | file:///…/yellow-river-memory/.arts/launch.json

而工程里 .arts/ 目录压根不存在。也就是说,调试视图被配置成去读一份 ArkTS 调试器的启动配置,但那个调试器没装,配置文件也不存在,于是面板空白。

证据二:自带扩展清单里没有鸿蒙。 遍历 app 包内 Contents/Resources/app/extensions,一共 107 个扩展,没有任何 ohos、arkts、harmony 相关的包。

证据三(决定性):读插件的 package.json。 这是最硬的证据。一个扩展能往 UI 上放什么,全写在 contributes 里:

  • 有 languages、grammars → 有语法高亮
  • 有 debuggers → 有调试器,Run 菜单才会有东西
  • 有 menus.editor/title/run → 编辑器右上角才会出现运行按钮

CodeArts Agent 自带的扩展里,这三类一个都没有。没有贡献点,VS Code 内核就不会渲染这个按钮——这跟配置无关,是能力缺失。

3.3 为什么“装个插件就有了”在这里不成立

对普通语言(JS、Python)来说,装个插件确实就能跑。但鸿蒙的运行链路是三段:编译(hvigorw)→ 签名(证书 + profile)→ 安装启动(hdc)。一个插件要把这三段都做完,才算“能跑”。

所以正确的期待不是“把按钮找回来”,而是“把能力接回来”——接回多少算多少。第五节的做法就是按这个思路来的。

3.4 顺手把 VS Code 的按钮机制讲清楚

既然查到这里,值得把机制说明白,以后遇到同类问题可以五分钟定位。

VS Code 编辑器右上角的运行按钮,走的是 editor/title/run 这个菜单贡献点。它的显示条件是“当前编辑器可运行”——也就是必须有某个扩展为这个文件类型提供了 runnable,或者提供了匹配的调试器(debuggers 贡献点声明了 type)。这两样都没有时,菜单项根本不会被创建。

launch.json 的角色是“配置”,不是“能力”。它写的 "type": "xxx" 必须有一个已注册的调试器去认领;没人认领,这份配置就是死文件。这解释了第一现场里那个矛盾现象:debug.selectedroot 指向 .arts/launch.json,可它既不存在、就算存在也没用——因为认领它的调试器没装。

这个机制对使用者有两个直接推论。第一,判断“某类项目能不能在某个 VS Code 系 IDE 里跑”,最有效的方法是看扩展市场里有没有对应调试器,而不是看菜单和设置。第二,遇到“按钮灰着/消失”,先查贡献点,再查 when 条件,最后才怀疑配置——顺序反了会浪费很多时间。


四、第二现场:macOS 的 App Translocation

排查过程中还撞到一个更隐蔽的坑,值得单独说,因为它会让“插件装好了却没效果”。

4.1 现象

日志里反复出现两类信息:

[error] No bundle location found for extension huaweicloud.authentication
[error] 这可能意味着该应用程序已被 macOS 隔离。请将 CodeArts Agent 移动到“应用程序”文件夹,然后重试。

同时,所有扩展的路径都指向一个奇怪的位置:

/private/var/folders/…/T/AppTranslocation/53A658FA-…/d/CodeArts Agent-2.app/…

4.2 原理

这个 app 是从 ~/Downloads 直接双击启动的,文件上带着 com.apple.quarantine 隔离属性。macOS 对这类“带隔离属性、且不在 /Applications 下”的应用有一套保护机制:把它挂载到随机命名的只读临时目录再运行,这就是 App Translocation。

后果很直接:app 里所有“相对路径解析”都可能失效(本地化语言包找不到、二进制 sidecar 定位不到),扩展宿主就会刷 No bundle location found。

请添加图片描述

4.3 修法与一个 TCC 陷阱

标准修法是两步:搬到 /Applications,清掉隔离属性。

ditto "/Users/…/Downloads/CodeArts Agent-2.app" "/Applications/CodeArts Agent.app"
xattr -dr com.apple.quarantine "/Applications/CodeArts Agent.app"

但这里有个坑:~/Downloads 受 macOS TCC 保护。即使给了足够权限,直接对下载目录里的 app 改扩展属性也会失败:

xattr: [Errno 1] Operation not permitted: '…/Downloads/CodeArts Agent-2.app'

连 touch 一个文件都不行。所以顺序必须是“先复制出去,再到新位置解隔离”,不能原地改。

4.4 验证

重启后确认主进程路径变成了真实路径:

/Applications/CodeArts Agent.app/Contents/MacOS/Electron

并且新实例的日志里,扩展激活是正常的。这一步做完,后面装扩展才不会白装。


五、把 ArkTS 能力接回来

5.1 官方确实有 VS Code 插件

华为在 Open VSX 上架了 HarmonyOS Dev Assistant for VS Code,发布者是 HuaweiDeveloperServicePlatform。我下载了 darwin-arm64 的 VSIX(76.5 MB),解开读 package.json,能力清单是这样的:

contributes内容
languagesarkts(.ets)、json5
grammarssource.arkts 语法定义
semanticTokenTypesstruct、component、label 等 ArkTS 专有语义
jsonValidation7 份 schema:module.json5、oh-package.json5、build-profile.json5、main_pages.json、app.json5、hvigor-config.json5、resources/**/element/*.json
viewsContainers一个 AI 助手面板(acp-client)
commandsharmonybot.* 一族(连接 Agent、发消息、登录、切换模型…)
configurationarkts.deveco.path、harmonybot.agentSettings 等

注意这里依然没有 debuggers,也没有 editor/title/run。所以结论在一开始就定型了:这个插件不会给你一个运行按钮,它给的是“语言能力 + Agent 能力”。

5.2 安装

"/Applications/CodeArts Agent.app/Contents/Resources/app/bin/code" \
  --install-extension ./hda.vsix --force

装完确认:

huaweideveloperserviceplatform.harmonyosdevassistantforvscode

在 IDE 的「扩展 → 已安装」里也能直接看到它:

请添加图片描述

5.3 配置 DevEco 路径(这一步最容易配错)

插件里有个硬编码兜底 /Applications/DevEco-Studio.app,并据此推导工具链路径(<DevEco>/Contents/tools/hvigor/bin)。所以 arkts.deveco.path 应该填到 Contents 为止,不是 .app:

{
  "arkts.deveco.path": "/Applications/DevEco-Studio.app/Contents",
  "harmonybot.agentSettings": {
    "devEcoStudio": { "installPath": "/Applications/DevEco-Studio.app/Contents" }
  }
}

为什么选 DevEco-Studio.app 而不是 DevEco-Studio-6.1.1.app?因为工程里 .hvigor/cache/project-config.json 记着上次构建实际用的 SDK:

"sdkPath": "/Applications/DevEco-Studio.app/Contents/sdk"

跟着工程的历史构建记录走,比按“版本号更大”猜要可靠。 落到设置文件里就是这几行:

请添加图片描述

5.4 验证:语言服务真的起来了

光看“已安装”没有意义,要看 LSP 有没有干活。插件的日志目录下会出现 server/idea-lsp-server.log,里面持续打印:

[INFO] - Sending request 'aceProject/onAsyncDidOpen'
[INFO] - callValidate: EntryAbility.ets
[TRACE] - synchronizeHostData: isProgramUptoDate cost: 0.1103ms

也就是说,打开 .ets 文件时,DevEco 那套 ArkTS 语言服务(ace-server)已经在做诊断和补全了。这一步成功,CodeArts Agent 才算“能写鸿蒙代码”。

不过要提醒一句:会话中途我注意到状态栏出现了 「LSP服务已停止」,它并不总是稳定运行。扩展里注册了 arkts.restartServer 命令(ArkTS: Restart Language Server),遇到补全或诊断失效时先用它重启,比直接重开 IDE 快得多。


六、从零做一个最小鸿蒙工程

为了有一个干净、可复现的样本,我没有拿那个真实工程改造,而是从官方模板起了一个最小工程。

6.1 模板来源

DevEco 自带一个最小工程模板:Contents/plugins/codegenie-plugin/previewProjectTemplate,37 个文件,结构完整(AppScope + entry + hvigor + 资源 + 测试目录)。直接复制出来改,比手写一遍靠谱。

6.2 版本必须对齐

模板默认 compatibleSdkVersion: 5.0.0(12),而本机只有 API 24 和 API 26 的 SDK。不改就会编译失败。对齐成本机实际 SDK 后:

"products": [{
  "name": "default",
  "compileSdkVersion": "26.0.0",
  "compatibleSdkVersion": "6.1.1(24)",
  "targetSdkVersion": "26.0.0",
  "runtimeOS": "HarmonyOS"
}]

6.3 页面代码

把模板里的 Hello World 换成一个有交互的计数器,便于观察状态更新:

@Entry
@Component
struct Index {
  @State count: number = 0;
  @State items: string[] = ['HarmonyOS', 'ArkTS', 'CodeArts Agent'];

  build() {
    Column({ space: 14 }) {
      Text('Hello HarmonyOS')
        .fontSize(30).fontWeight(FontWeight.Bold).fontColor('#1A73E8')
      Text(`点击次数:${this.count}`).fontSize(20)
      Button('点我 +1').width(160).height(44)
        .onClick(() => { this.count += 1; })
      ForEach(this.items, (item: string) => {
        Text(item).fontSize(16).fontColor('#666666')
      }, (item: string) => item)
    }
    .width('100%').height('100%').justifyContent(FlexAlign.Center)
  }
}

6.4 构建

关键是把 DevEco 自带的 Node 和 SDK 环境变量带上:

NODE_HOME=/Applications/DevEco-Studio.app/Contents/tools/node \
DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk \
/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw \
  --mode module -p product=default -p module=entry@default \
  -p buildMode=debug assembleHap --no-daemon

真实输出(节选):

Finished :entry:default@CompileArkTS... after 2 s 326 ms
Finished :entry:default@PackageHap...   after 418 ms
WARN: No signingConfig found for product default
BUILD SUCCESSFUL in 4 s 581 ms
34 tasks in total: 34 executed, 0 up-to-date

“34 executed, 0 up-to-date” 说明这是真正的冷构建,不是缓存命中。

同一套命令再跑一次(增量),集成终端里的真实输出是这样:

请添加图片描述

两处细节值得注意。第一,增量并没有快多少:33 个任务里 20 个仍然执行、13 个命中缓存,耗时 4.56 秒——说明时间主要花在那 20 个真正的编译任务上,而不是任务调度或打包。第二,截图里有一条 ArkTS 警告:

WARN: ArkTS:WARN File: .../ets/entryability/EntryAbility.ets:9:42
Function may throw exceptions. Special handling is required.

这是 ArkTS 在提示“可能抛异常的调用需要显式处理”。它不中断构建,但会把问题留到运行时,属于典型的“编译过了不等于没问题”。

6.5 产物长什么样

124 KB 的 HAP,unzip -l 出来就是一张清单:

条目体积作用
module.json1.6 KB模块清单:入口 ability、设备类型、页面路由
ets/modules.abc12.9 KBArkTS 编译产物(字节码)
resources.index1.1 KB资源索引:string / color / media 的映射表
resources/base/media/~103 KBbackground / foreground / startIcon 三张图
resources/base/profile/main_pages.json27 B页面清单(路由表)

两点观察:图标资源占了大头(约 103 KB,占整个包的八成以上),要压体积先压图;真正的业务代码只有 12.9 KB,说明这个规模的工程,编译耗时根本不在代码量上。以后排查“页面白屏”“资源找不到”,也就是在这三层里找。


七、运行链路的真实边界

编译通了,但离“跑起来”还差三道关。这一段是全文最“扫兴”也最实用的部分。

7.1 签名

产物文件名是 entry-default-unsigned.hap,因为 build-profile.json5 里:

"signingConfigs": []

是空的。而且我查了 ~/.ohos/config,里面确实有 4 套历史签名材料(.p12 / .cer / .p7b),但它们的 profile 绑定的 bundleName 分别是:

com.example.mo_fang
com.example.flutter_oh_demo
com.huawei.ohos_electron
com.shuming.harmonynotes

没有一个是当前工程的 bundleName。签名不是“有证书就行”,profile 和 bundleName 是绑定的,跨工程复用会直接被设备拒绝。

7.2 设备

hdc list targets
[Empty]

没有任何设备或模拟器。系统镜像其实是齐的(~/Library/Huawei/Sdk/system-image/HarmonyOS-6.1.1/{phone,pc}_all_arm),但没有已创建的实例。

7.3 预览器

本来有一条“零签名”的捷径:ArkUI 预览器可以在电脑上直接渲染页面。但命令行拉起失败了:

Error: Please restart previewer.
[31mCOMPILE RESULT:FAIL {ERROR:1}

PreviewBuild 任务在等一个已经连上的预览器进程——而那个进程是由 DevEco 的 IDE 通过本地套接字驱动的。换句话说,预览器是 IDE 的附属品,不是可以单独调用的命令行工具。

7.4 签名三件套到底是什么

既然签名是最硬的一道关,把它的构成说清楚,以后遇到报错能自己判断。

~/.ohos/config 里每个工程会生成三个文件:

  • .p12:密钥库,里面装着私钥。签名时用它给 HAP 签名。
  • .cer:开发者证书(公钥部分),由华为的 CA 签发,用来证明“这个私钥属于某个开发者账号”。
  • .p7b:profile(描述文件)。这是最容易被忽略、也最容易出错的一个——它里面写着允许安装的 bundleName、允许安装的设备列表(UDID)、以及配套的证书链。

签名校验时会三层一起验:HAP 的签名能否用 profile 里的证书验证、bundleName 是否在允许列表里、当前设备的 UDID 是否在允许列表里。任何一层不匹配就装不上。

这就是为什么“复用老工程的证书”行不通:.p7b 里写死了别的包名。我这次在日志里也看到过对应错误码(204144723: 软件包的签名与其它版本软件包的签名不一致),它说的就是这类不匹配。

DevEco 的“自动签名”做的事,其实是替你完成一个云端流程:用华为账号向 AGC 申请证书与 profile,然后把四个字段写回 build-profile.json5 的 signingConfigs:

"signingConfigs": [{
  "name": "default",
  "type": "HarmonyOS",
  "material": {
    "certpath": "…cer",
    "storePassword": "…",
    "keyAlias": "…",
    "keyPassword": "…",
    "profile": "…p7b",
    "signAlg": "SHA256withECDSA",
    "storeFile": "…p12"
  }
}]

看到 storePassword 和 keyPassword 了吗?这也是为什么签名这件事必须由有账号的人来做一次——它不是一个纯技术步骤,背后绑着身份。

7.5 实测:用 DevEco 预览器真跑了一遍

命令行预览器起不来,不代表看不到界面。DevEco 的预览器是 GUI 驱动的:我打开 entry/src/main/ets/pages/Index.ets,从「视图 → 工具窗口 → 预览器」调出面板,十几秒后页面就渲染出来了——手机外框里是标题、点击次数:0、按钮和三行列表。

为了确认它不是一张静态图,我在预览器里点了一下「点我 +1」,计数变成 1:

请添加图片描述

这一步的意义在于:它既不需要签名,也不需要模拟器,是验证“界面写得对不对”最快的回路。签名和设备的成本,可以推迟到你要验证真机行为(权限、分布式、传感器)时再付。

7.6 所以最终的结论是

想在屏幕上看到效果,最省事的路径不是继续折腾 CodeArts Agent,而是:

  1. DevEco 打开同一个工程;
  2. 登录华为账号 → Project Structure > Signing Configs 勾选自动签名(它会把证书写进 build-profile.json5);
  3. Device Manager 建一个模拟器(镜像已下载,不用等);
  4. 点运行,或者直接用右侧 Previewer 面板看界面(预览器不需要签名和设备,是最快的“看一眼”方式)。

八、协作流程:笔与手腿怎么配合

既然两边各自擅长不同的事,工作流就应该按这个分工来切。

8.1 共用一个工程目录

不要“CodeArts 里一份、DevEco 里一份”。两边打开同一个路径,所有配置自动共享。

8.2 签名一次,两边受益

DevEco 勾选自动签名后,会往 build-profile.json5 的 signingConfigs 里写证书路径与 profile。这个文件是两边共享的——所以 CodeArts Agent 侧编译出来的产物,自动就是带签名的。不用配两遍。

8.3 别让两边同时编译

hvigor 有 daemon 和 ~/.hvigor 缓存。两个 IDE 同时 assembleHap,容易踩缓存锁、看到莫名其妙的中间态报错。编译固定在一侧跑。

8.4 一天的顺序大概是这样

时段工具做什么
上午CodeArts Agent读工程、改 ArkTS、让 Agent 生成页面骨架
中途CodeArts Agent跑一次 assembleHap 确认没编译错误(4~5 秒,很轻)
中途DevEco需要看界面时开预览器;需要真机行为时起模拟器
收尾DevEco性能分析、hilog 排查、出包

九、“专属模型”到底贡献了什么

内容方向上有一类对比很常见:通用大模型 vs 鸿蒙专属模型。我没做跑分,但这次实测让我对“能力差在哪”有了一个更结构化的认识——把“鸿蒙能力”拆成四层看会清楚很多:

层级具体内容谁提供
语言层.ets 语法高亮、语义标注、补全扩展 + DevEco 的 ace-server
规范层7 份 json5 schema 校验(改错字段立刻报红)扩展的 jsonValidation
工具链层调 hvigorw 编译、hdc 部署、远程签名扩展的 Agent + DevEco 安装目录
知识层一堆 skills:deveco-cli 工作流、模拟器调试闭环、三方库评估、ASCF 接入…扩展内置的 skill 包

通用模型能补的是“语言层和规范层的一部分”——它能写出像样的 ArkTS,也能凭记忆告诉你 module.json5 该有哪些字段。但它补不了工具链层和知识层:它不知道你机器上 hvigorw 在哪、不知道你的 SDK 是 API 24 还是 26、不知道签名 profile 绑的是哪个 bundleName。

这次排查里,真正省时间的不是“模型会不会写 ArkTS”,而是这几件具体的事:能读懂 product.json 判断这是 VS Code 发行版、能想到去 contributes 里找 debuggers、知道 xattr 会撞 TCC、知道 .hvigor/cache/project-config.json 里记着真实 SDK 路径。这些都属于“知识层 + 工具链层”。

如果你想自己做一次对比实测,建议这样设计:同一个需求(比如“把这个页面改成带列表和计数器的布局”),让两个模型各改一遍,然后看三个指标——产出是否一次编译通过、是否需要查 schema 才知道字段名、改完后能否说清运行要依赖哪些外部条件。第三个指标最能拉开差距。

9.1 一个可复现的对比实测模板

为了让对比有说服力,需求要选“有明确验收标准”的,别选“优化一下代码”这种没法判定的。我建议用三个难度递进的任务,每个任务重复两遍(换个说法再问一次,观察稳定性):

任务验收标准观察点
A. 页面重构:把单列布局改成“标题 + 计数器 + 列表”assembleHap 一次通过是否用对 ForEach 的 keyGenerator;@State 用法是否正确
B. 配置修改:给模块加一个 extensionAbilities(如备份能力)编译通过且 schema 不报红是否知道字段嵌套层级;是否会自动去查 schema
C. 排障:给一段真实的编译报错,定位到具体文件行指出的行号与实际一致是否需要多轮追问才能收敛

记录表只需要四列:任务、一次通过(是/否)、查证次数(凭记忆/查 schema/查文档)、能否说清运行依赖(签名?设备?权限?)。二十次以内的样本就够了,结论会非常清楚——差距不在“写不写得出来”,而在“写出来对不对、知不知道自己为什么对”。


十、可复用清单

10.1 装官方扩展

# 下载(darwin-arm64 示例)
curl -L -o hda.vsix "https://open-vsx.org/api/HuaweiDeveloperServicePlatform/harmonyosdevassistantforvscode/darwin-arm64/0.2.4/file/HuaweiDeveloperServicePlatform.harmonyosdevassistantforvscode-0.2.4@darwin-arm64.vsix"

# 安装
"/Applications/CodeArts Agent.app/Contents/Resources/app/bin/code" \
  --install-extension ./hda.vsix --force

# 确认
"/Applications/CodeArts Agent.app/Contents/Resources/app/bin/code" --list-extensions

10.2 工程内的任务配置

在工程根目录建 .vscode/tasks.json,把编译/安装/启动做成官方任务(Ctrl+Shift+B 触发默认构建):

{
  "version": "2.0.0",
  "options": {
    "cwd": "${workspaceFolder}",
    "env": {
      "NODE_HOME": "/Applications/DevEco-Studio.app/Contents/tools/node",
      "DEVECO_SDK_HOME": "/Applications/DevEco-Studio.app/Contents/sdk"
    }
  },
  "tasks": [
    {
      "label": "鸿蒙: 构建 debug HAP",
      "type": "shell",
      "command": "/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw",
      "args": ["--mode", "module", "-p", "product=default",
               "-p", "module=entry@default", "-p", "buildMode=debug",
               "assembleHap", "--no-daemon"],
      "group": { "kind": "build", "isDefault": true },
      "problemMatcher": []
    },
    {
      "label": "鸿蒙: 安装到模拟器",
      "type": "shell",
      "command": "/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains/hdc",
      "args": ["install", "-r",
               "${workspaceFolder}/entry/build/default/outputs/default/entry-default-signed.hap"],
      "dependsOn": "鸿蒙: 构建 debug HAP",
      "problemMatcher": []
    },
    {
      "label": "鸿蒙: 启动 EntryAbility",
      "type": "shell",
      "command": "/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains/hdc",
      "args": ["shell", "aa", "start", "-b", "com.example.demoapp", "-a", "EntryAbility"],
      "dependsOn": "鸿蒙: 安装到模拟器",
      "problemMatcher": []
    }
  ]
}

注意第三个任务里的 -b 要换成你自己的 bundleName,安装任务用的是 -signed.hap——没签名的话这一步一定失败,别以为是路径写错了。

如果不想依赖 IDE 的任务系统,把同样的命令写成脚本更通用(图 6 的截图里跑的正是它):

#!/bin/bash
DEVECO="/Applications/DevEco-Studio.app/Contents"
export NODE_HOME="$DEVECO/tools/node"
export DEVECO_SDK_HOME="$DEVECO/sdk"
"$DEVECO/tools/hvigor/bin/hvigorw" --mode module \
  -p product=default -p module=entry@default -p buildMode=debug \
  assembleHap --no-daemon

10.3 三条常用检查命令

# 有没有设备
/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains/hdc list targets

# 上次构建用的是哪个 SDK
grep -o '"sdkPath":"[^"]*"' <工程>/.hvigor/cache/project-config.json

# 有哪些签名 profile、各自绑定哪个包名
for f in ~/.ohos/config/*.p7b; do
  echo "$f"
  strings "$f" | grep -o -E "com\.[a-zA-Z0-9._]+" | sort -u
done

10.4 官方命令行:devecocli

DevEco 还提供了一套官方命令行工具,npm 包名 @deveco/deveco-code(实测查询,当前 latest 为 0.2.5),装完命令叫 devecocli:

npm install -g @deveco/deveco-code
devecocli -h

它的子命令覆盖了从编译到运行的整条链路:

build      构建 HarmonyOS 工程
run        在已连接的设备上构建并运行
emulator   管理模拟器实例
login      登录华为开发者账号
logout     退出登录
update     升级 deveco-cli

这条路的价值是把“运行”从 IDE 里解耦出来了:在 CodeArts Agent 的终端里敲 devecocli run,理论上就能完成构建、安装、拉起。但要注意,它同样绕不过签名与设备——login 和 emulator 两个子命令摆在 run 前面,就是这个意思。签名和设备这两道关没有消失,只是换了个入口。


十一、踩坑清单与三条建议

把这次踩的坑列全,方便你对照:

  1. 别在 ~/Downloads 直接跑 IDE——隔离 + Translocation + TCC 三重坑,症状是“插件装了没反应”。
  2. 下载目录里改不了 xattr,必须先复制到 /Applications。
  3. 两套 DevEco 并存时别按版本号猜,看工程的历史 sdkPath。
  4. arkts.deveco.path 要填到 Contents,不是 .app。
  5. 签名 profile 绑 bundleName,老工程的证书不能直接复用。
  6. 预览器不能命令行拉起,PreviewBuild 会报 Please restart previewer.。
  7. 两边同时编译会抢缓存,编译固定一侧。

给官方的三条建议(如果团队能看到):

  • 建议一:官方扩展补一个 editor/title/run 贡献点。哪怕只是触发一次 assembleHap 并把结果输出到终端,用户心智上也会立刻不同——“能跑”和“不能跑”的差别,比“能写得更好”重要得多。
  • 建议二:把 PreviewBuild 对 IDE 套接字的依赖解耦,暴露一个 preview --once --screenshot out.png 的 CLI。这会直接解决“不装 DevEco 也想看一眼界面”的刚需。
  • 建议三:文档里显式写明 macOS 的落盘位置要求与 arkts.deveco.path 的取值形状。这两个点,第一次用的人 100% 会踩。

十二、适用与不适用

判断依据其实只有一句:这一步要不要“设备”或“签名”?要,就走 DevEco(或用官方的 devecocli);不要,就在 CodeArts Agent。

具体到场景:

适合 CodeArts Agent 的: 读一个陌生工程并画出调用关系;跨十几个文件批量改 API(比如把某个权限常量统一换名);生成页面骨架、写注释和 README;把编译报错丢给它定位;写元服务(ASCF)的样板逻辑;给开源工程补工程规范文件。

必须回 DevEco 的: 第一次配置签名;创建模拟器;真机部署;性能分析与 hilog;UI 预览器;出正式包。

两边都用: 先改代码再编译验证,编译报错回改,提交前自查。

顺带说一句,这套流程对另外几个方向同样适用:

  • 元服务落地:元服务本质还是 ArkTS 工程 + ASCF 配置,写代码环节完全可以在 CodeArts Agent 里做,编译与预览仍走 DevEco。
  • 跨端适配:module.json5 里的 deviceTypes(phone / tablet / 2in1 / wearable)改动,属于“纯配置文件改动”,在 CodeArts Agent 里有 schema 校验帮忙兜底,比凭记忆改安全。
  • 开源托管(AtomGit):.gitignore 里要排除 oh_modules、build、.hvigor,README 要写清 SDK 版本与签名前置条件——这类文档工作正是 AI 编码工具擅长的部分。这次踩的两个坑(隔离、签名 profile 绑定)如果一开始就写在 README 里,后来者能省两小时。

十三、延伸:三个方向的落地细节

内容方向里提到的另外三个场景(元服务、跨端、开源托管),其实都能套用上面这套流程,只是各自多一两个注意点。

13.1 元服务:工程结构只多一层配置

元服务不是新语言,仍然是 ArkTS + ArkUI,差别在构建形态与分发方式。工程里会多出 ASCF 相关的配置与模板结构。对我们这套工作流来说结论不变:页面与逻辑在 CodeArts Agent 里写,构建与预览在 DevEco 里跑。

真正要注意的是约束更紧:元服务对包体积、冷启动、免安装校验比普通应用敏感。所以改完别只看“编译通过”,要顺手看一眼产物大小——这次那个最小工程是 124 KB,其中约 103 KB 是三张图标资源,说明资源才是体积大头,元服务场景下该压缩的是图片而不是代码。

13.2 跨端适配:改的是配置,受益的是 schema

module.json5 里的 deviceTypes 决定这个模块能装到哪些设备(phone、tablet、2in1、wearable)。改这一项是纯配置工作,风险集中在“字段名和取值记错”——而这恰好是官方扩展那 6 份 schema 能兜住的地方:写错立刻在编辑器里报红,不用等到编译。

另一个实用点:预览器支持切设备与分辨率。模板目录里就带了一份 phoneSettingConfig_Phone.json,里面写得很直白:

"Resolution": { "args": { "Resolution": "360*780" } },
"DeviceType":  { "args": { "DeviceType": "phone" } }

所以“改 deviceTypes → 预览器换设备看效果”是一条很短的验证回路。跨端最容易翻车的不是逻辑,是布局在不同分辨率下的溢出——这一条回路能提前发现问题。

13.3 AtomGit 开源托管:把踩过的坑写进 README

把工程开源,最容易犯的错是“把不该提交的提交了”。

.gitignore 至少要排掉 oh_modules/、build/、.hvigor/、.idea/;但 oh-package-lock.json5 应当保留——它锁定依赖版本,是可复现构建的关键。签名材料绝对不能入库:.p12 是私钥,.p7b 里带着设备与包名信息,泄露等于把开发者身份交出去。

README 建议写清四件事,缺一件都会让后来者卡住:

  1. SDK 版本:本机是 API 26(兼容 6.1.1(24)),写清楚才知道要装哪套;
  2. 构建命令:带 NODE_HOME 与 DEVECO_SDK_HOME,否则 hvigorw 会报找不到 node 或 SDK;
  3. 签名前置条件:必须用自己的华为账号做一次自动签名,别人的证书不能复用;
  4. 诚实声明:例如“本项目已验证编译,运行需要设备与签名”——把边界写出来,比假装能跑更省事。

这次踩的两个坑——macOS 隔离导致插件失效、签名 profile 绑定 bundleName——如果一开始就写在“环境要求”里,后来者能少走两小时。


十四、把 Agent 用顺手的五个做法

工具好不好用,很大程度上取决于你怎么用它。这五条是这次实践里最有效的:

第一,动手前先让它读三个文件。 build-profile.json5 决定编译目标与产品配置,module.json5 决定模块形态,.hvigor/cache/project-config.json 里记着上次构建真实的 sdkPath。让它先读这三份,能省掉一半“改完编译不过”的往返——我这次判断该用哪套 DevEco,就是靠第三份文件。

第二,编译输出原样贴给它,不要自己总结。 hvigor 的报错里带任务名、文件路径和行号,总结会把关键信息丢掉。No signingConfig found for product default 这种警告,只有在原样输出里才能看出它出现在 SignHap 任务之前。

第三,一次只改一个模块,改完立刻编译。 ArkTS 的类型检查比较严,跨模块改动容易连环报错;小步编译只要 4~5 秒,比一次改一大片再回头排查快得多。

第四,schema 报红时把整段 json5 一起给它。 它需要看到上下文层级才能判断该改哪一层;只贴报错那一行,它经常改到相邻的层级上去。

第五,让它把“运行前置条件”总结成清单。 AI 很擅长回答“要跑起来还差什么”,这类清单放进 README,比留在对话记录里有用得多。

还有一个反向用法值得单独说:用它来读别人的工程。开源鸿蒙项目里,build-profile.json5 + module.json5 + oh-package.json5 三个文件基本能还原出工程形态——几个模块、面向什么设备、依赖哪些库、用什么 SDK 编译。让它先输出一份“工程地图”再动手改,比直接开改安全得多,也更符合“笔”这个定位。

最后

这次实测最有价值的收获,不是“CodeArts Agent 能不能跑鸿蒙”这个问题本身,而是它逼我把一个模糊的问题拆成了三个可验证的问题:按钮由谁创建?能力由谁提供?边界在哪里?

答案分别是:扩展创建、DevEco 提供、在签名和设备上。

如果你也在用 AI 编码 IDE 折腾鸿蒙,建议先花十分钟把这三件事确认清楚,再决定把时间投在哪。至于那个运行按钮——它不会出现,但你会得到一个比按钮更值钱的东西:一套自己说得清的能力边界。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐