给AI Agent补节鸿蒙课：DevEco CLI从安装到实战
Codex能写鸿蒙代码吗？能。Claude Code呢？也能。
但你要是让它们写一个沉浸光感的ImmersiveMaterial配置，大概率会编出几个不存在的API参数。不是它们不够聪明，而是HarmonyOS 7.0的新特性还没进训练数据，ArkTS的@Builder、@Reusable装饰器在GitHub上也找不到几个开源示例。
DevEco CLI解决的正是这个"知识断层"问题。
它不是一个AI Agent，而是HarmonyOS开发能力的"外挂知识库+工具链"。通过Skill机制集成到Cod$ex、Claude Code等已有Agent中，让它们从"凭记忆猜API"变成"查文档写代码"。
DevEco CLI（npm包名 @deveco/deveco-cli）是OpenHarmony SIG维护的官方命令行工具，2026年4月发布，MIT开源协议。
它做了三件事：
封装工具链——把DevEco Studio里的ohpm（包管理）、hvigor（构建）、hdc（设备通信）、emulator（模拟器）、hilog（日志）统一为一个CLI入口。所有输出均为JSON（stdout），进度信息走stderr，天然适合AI Agent解析。
内置文档库——HarmonyOS官方文档本地化，通过docs命令全文检索。API参考、开发指南、最佳实践、FAQ都能搜。
对接AI Agent——内置支持trae-cn、opencode、cursor、codebuddy、qoder、claude-code、codex七种Agent。通过Skill机制和MCP服务接入，不改变Agent本身，只给它增加鸿蒙能力。
一句话定位：DevEco CLI不是替代你的AI Agent，而是给它补鸿蒙课。
🔗 DevEco CLI — AI Agent与鸿蒙工具链之间的适配层
前置条件
- DevEco Studio ≥ 6.1.0（CLI会自动检测安装路径）
- Node.js ≥ 18，推荐22及以上版本（Node.js 18低版本可能报语法错误）
- macOS或Windows（暂不支持Linux）
安装步骤
# 安装稳定版（推荐@stable而非@latest）
npm install -g @deveco/deveco-cli@stable
# 验证
devecocli --version
# 后续升级
devecocli update
看到版本号输出就说明安装成功。如果安装成功但执行报语法错误，先检查Node.js版本——升级到22通常能解决。
这是DevEco CLI最关键的设计。它不是一个独立工具，而是一个"技能包"，需要安装到AI Agent的Skills目录中才能发挥最大价值。
安装Skill到Agent
# 装给 Claude Code（用户级）
devecocli init --agent claude-code
# 装给 Codex
devecocli init --agent codex
# 同时装给多个 Agent
devecocli init --agent opencode,cursor,claude-code
# 装到某个项目的特定目录下
devecocli init --path ./MyApp
# 覆盖已有配置（更新Skill时用）
devecocli init --agent claude-code --force
init命令会自动检测目标Agent的Skills目录，把deveco-cli技能文件写入对应位置。以Claude Code为例，安装完成后，在对话中输入 /skills 确认列表中出现deveco-cli即可。
配置MCP服务（可选，推荐）
除了Skill，DevEco CLI还提供MCP（Model Context Protocol）服务，主要用于ArkTS语法检查：
# 在项目目录下配置 MCP
devecocli init --mcp --agent claude-code --project ./
MCP配置会写入项目的 .mcp.json 文件，可以提交到Git。团队成员拉取代码即获得相同的鸿蒙AI开发环境——新人不需要手动配置。
安装好Skill后，在Claude Code里可以直接用自然语言驱动，也可以手动在终端调用。核心命令如下：
工程管理——create（脚手架创建）、build（编译打包）、run（构建+安装+启动）
设备调试——device（设备列表）、emulator（模拟器全生命周期）、log（应用日志诊断）
知识能力——docs（文档检索）、skills（技能市场）、init（Skill安装）、serve（MCP服务托管）
每条命令都支持 --help 查看参数。比如想看build怎么用：
创建一个新鸿蒙工程也很简单：
devecocli create --app-name MyApp --bundle-name com.example.myapp --api-level 26
启动模拟器、运行应用、查看日志的典型流程：
devecocli emulator list
devecocli emulator start "Pura 90"
devecocli run
devecocli log --level E --from 5m
这是最能体现DevEco CLI价值的功能。HarmonyOS 7.0（API 26）带来大量新特性，沉浸光感（Immersive Light）就是其中之一。但很多开发者根本不知道它叫什么、怎么用。
传统方式：打开浏览器→搜鸿蒙开发者文档→在几千页里翻→API 26新增内容可能还没更新到线上。
DevEco CLI方式：
# 搜索"沉浸光感"
devecocli docs search 沉浸光感
返回JSON结构结果，包含文档ID、标题和摘要。限制返回数量：
devecocli docs search 沉浸光感 --limit 5
找到文档ID后，读取完整内容：
devecocli docs read <文档ID>
不知道有哪些文档分类？查看目录：
通过docs命令，你会发现沉浸光感有两种使用方式：
方式一：全局开启。在module.json5中配置metadata，Dialog、Toast、Select、Slider等系统组件自动获得光感效果。
方式二：组件级设置。用systemMaterial属性为单个组件配置：
Button('提交')
.systemMaterial(
new uiMaterial.ImmersiveMaterial({
style: uiMaterial.ImmersiveStyle.THICK,
interactive: true,
lightEffect: { color: undefined },
colorInvert: true,
applyShadow: true
})
)
5种材质样式（ULTRA_THIN到ULTRA_THICK）、交互形变、自动反色、材质阴影——这些参数，Claude Code自己根本不可能知道。但有了docs命令，AI Agent可以先查文档再写代码，准确率直线上升。
🔄 Agent工作流：查文档→写代码→构建运行→验证迭代
注意：docs命令返回的是结构化JSON，设计上就是给AI Agent解析的，不是给人直接看的。集成Skill后，AI Agent会自动调用docs搜索，开发者只需要用自然语言提需求。
DevEco CLI还接入了鸿蒙官方的格物市场（Skill Marketplace），上面提供可复用的专家经验包：
# 列出所有可用技能
devecocli skills list --long
# 搜索关键词
devecocli skills find deveco
格物市场地址：https://matrix.openharmony.cn/#/skillSquare
Skill本质上是告诉AI Agent"在特定场景下该怎么操作"的经验包。社区和官方共同维护，覆盖多设备适配、崩溃定位、元服务开发等场景。这个生态还在快速扩展。
装好Skill后，你在Claude Code里直接用自然语言即可：
创建工程：帮我创建一个HarmonyOS项目，包名com.example.shop
文档查询：查一下ArkUI中@State和@Prop装饰器的区别
构建运行：用release模式构建当前项目，然后在我的Pura 90模拟器上运行
日志排查：查看这个应用最近10分钟的Error级别日志，帮我分析崩溃原因
Claude Code收到指令后，通过Skill知识调用对应的devecocli命令，拿到JSON结果后分析并给出建议。整个过程你不需要记住任何CLI参数。
四个设计决策体现了Agent-first思维：
输出全JSON。所有命令的stdout都是结构化JSON。AI Agent不需要解析人类可读文本，直接拿到机器可读的数据。
Skill标准化。不是私有协议，而是一套标准的技能描述格式。任何支持Skill机制的Agent都能接入。
MCP标准化。通过Model Context Protocol提供服务接口，Claude Code、Codex、Cursor都能无缝对接。
团队可复制。项目级.mcp.json可提交到Git，团队成员拉取代码即获得相同的鸿蒙AI开发环境。
很多人会问：DevEco Code已经是AI-Native的鸿蒙IDE了，DevEco CLI有什么存在价值？
答案很简单：DevEco Code是自带AI大脑的全套IDE，DevEco CLI是给任意AI Agent配的鸿蒙能力插件。
⚖️ 两种方案对比：DevEco Code vs DevEco CLI
如果你用DevEco Code，DevEco CLI可以集成进去增强它的能力。如果你习惯用Codex或Claude Code，DevEco CLI是你唯一不需要换工具就能获得鸿蒙开发能力的方案。
选择权在你手里。不是让你适应鸿蒙工具，而是让鸿蒙工具适应你的AI Agent。
DevEco CLI不试图成为新的AI Agent，也不试图替代DevEco Code。它做的事情很克制：把HarmonyOS开发能力封装成标准化接口，让任何AI Agent都能调用。
这个思路很务实。程序员不会为了开发鸿蒙就换掉自己熟悉的Claude Code或Codex，但他们会愿意给自己的工具装一个鸿蒙技能包。
npm install一行命令，devecocli init一条配置，你的AI Agent就获得了鸿蒙工程创建、编译构建、设备调试、文档检索的完整能力。从"猜API"到"查API"，从手动操作到自然语言驱动。
不是让AI Agent学会鸿蒙，而是给AI Agent配一个鸿蒙专家。
👆 关注「代码和弦」，获取更多AI Agent × 鸿蒙开发实战内容
