HarmonyOS DevEco Code 入门与最佳实践：迈入 Agent 时代，大展“鸿图”

1. 引言：AI 赋能鸿蒙，终端里的超级智能体

在 HarmonyOS 开发中，开发者常常深陷于频繁切换查阅 API 文档、繁琐的 ArkTS 模板代码编写以及冗长的排错链路中。想想HarmonyOS Next刚推出时，全新的编程语言，全新的开发框架，对于所有的开发者来说都有极大的开发成本。虽然一起推出了CodeGenie代码助手，但是只限于知识问答和代码提示，作用有效。随着HarmonyOS的推广以及AI的发展，市面上出现了比如Claude Code、Cursor、Antigravity、CodeX等AI编程工具，对HarmonyOS也提供了一定程度的支持，但是对于编译构建工具等支持不友好，自动写完代码还需要手动编译检查代码编译问题等。

随着 HDC 2026 和 HarmonyOS 7 的发布，鸿蒙正式宣告迈入 Agent 时代，DevEco Code（原 codegenie_cli）也应运而生。它作为 OpenHarmony-SIG 孵化的专属 AI 开发助手，不仅仅是一个代码生成工具，更是一个能直接打通编译、设备调试、ArkTS 报错修复和文档检索的终端超级智能体 (CLI-first Agent)。它将从根本上重塑我们的开发心智模型，让开发者从“代码工人”化身为“数字研发团队的主管”。

2. DevEco Code 核心架构与原理解析

2.1 基于 OpenCode 的底座架构与原理图

DevEco Code 底层基于强大的 OpenCode 架构，它的核心设计理念是“高内聚，强扩展”。它不仅自带了对大模型的调度能力，还能通过标准协议无缝接入各类外部工具。

以下是 DevEco Code 的核心架构示意图：

2.2 核心价值与横向全面对比

下面为了更直观地理解 DevEco Code 的价值，我们将其与日常使用的 IDE 插件（如 CodeGenie）以及业界顶级的通用终端 Agent（如 Claude Code / Cursor）进行多维度对比：

特性维度	DevEco Studio 内置 CodeGenie	通用终端 Agent (如 Claude Code)	DevEco Code (专属鸿蒙智能体)
交互形态	IDE 侧边栏 / 局部代码行内补全	独立终端 CLI / 命令行接管	独立终端 CLI / 命令行强接管
系统级执行权限	被动补全，无底层终端控制权	主动，可跨文件读写及执行终端命令	主动，可跨文件读写及执行终端命令
鸿蒙原生基因	强 (官方内置组件库支持)	弱 (经常产生基于 React/Flutter 的幻觉)	极强 (基于 OpenCode，深度理解 ArkUI/ArkTS)
上下文感知范围	严重依赖 IDE 当前打开的激活文件	优秀的全局工程源码扫描	全局源码扫描 + .deveco.md 项目级深度约束
架构扩展性	封闭生态，依赖官方版本迭代功能	支持 MCP 协议与通用 CLI 插件	完整支持 MCP、Skills、Subagent、Hooks 四大生态

从表中可以看出，DevEco Code 既具备了通用智能体的自主执行能力，又完美弥补了通用模型在 HarmonyOS 垂直领域的“水土不服”。并且DevEco Code 满足作为 Agent 的三大特征：感知（Perception）（读取 Workspace）、决策（Decision）（决定是查文档还是改代码）、行动（Action）（直接调用 hvigor 编译或推送到真机）

3. 环境搭建与快速入门

3.1 安装与依赖配置

DevEco Studio升级到7.0版本后打开CodeGenie后会有deveco code安装引导提示：

要安装体验这款终端智能体，你需要具备 Node.js 18+ 环境。打开你的终端，通过 npm 可以全局一键安装核心包：

npm install -g @openharmony-sig/deveco-code

执行命令安装完成后需要登录华为账号，点击“Sign in with HUAWEI account”后会打开浏览器进行HUAWEI账号认证，目前DevEco Code免费提供 GLM-5.1 模型，单账号默认每分钟 50 次请求：

登录完成后需要配置DevEco Studio 的路径，默认选择系统安装路径即可（以Mac为例，默认安装的Application路径即可）

接着同意使用协议：

接下来就大功告成了，可以终端交互使用DevEco Code了：

3.2 首次化配置与模型接入 (Providers)

在你的鸿蒙项目根目录下执行 deveco-code，系统会引导你完成初始化。你可以配置账号授权、API Key，并灵活切换不同的 LLM Provider（例如接入基于昇腾算力的云端模型，或者本地部署的轻量级推理服务）。在 DevEco Code 中输入 /models 可进入模型配置界面：

也可以通过 /connect 进入 Provider 选择界面，配置支持的第三方模型：

也可以通过 deveco.jsonc 配置模型：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "deveco": {
      "name": "DevEco Code",
      "models": {
        "glm-5": {
          "tool_call": true,
          "limit": {
            "context": 200000,
            "output": 8192
          }
        }
      },
      "options": {
        "baseURL": "https://api.openbitfun.com/v1",
        "apiKey": "{env:DEVECO_API_KEY}"
      }
    }
  }
}

配置完成后，DevEco Code 提供了三种核心交互模式，可以按 Tab 键切换：

• Build：默认模式，适合工程生成、代码生成、配置修正、测试执行、推包运行和发布执行

• Plan：适合需求拆解、技术方案、发布规划、测试规划和文档生成
• Goal：适合 SDD 五阶段从需求到实现与构建验证的端到端特性交付

4. 核心功能深度实战演练

DevEco Code 集成了常用 HarmonyOS 开发工具能力：

工具	说明
build_project	执行编译构建并导出构建产物
start_app	在模拟器或真机上运行应用
hdc_log	收集/清理设备日志/查看连接模拟器
verify_ui	执行 UI 操作验证功能是否正确
arkts_check	ArkTS 静态语法检查
arkts_knowledge_search	HarmonyOS 知识搜索
switch_cwd	切换构建项目路径
下面体验通过自然语言来进行代码生成等能力。

4.1 场景一：自然语言驱动的 ArkTS 复杂业务生成

在自动模式下，你无需自己新建文件和搭建骨架。
直接输入指令：> 帮我用 ArkTS 写一个商品列表瀑布流组件，需支持下拉刷新，并且状态管理必须使用 @ObservedV2 和 @Trace，最后在 Index.ets 中引入它。

任务执行完成：

DevEco Code 会自主分析当前工程目录，寻找合适的 components 文件夹，创建 ProductList.ets，编写逻辑，甚至自动扫描并复用你项目里已有的基础 Loading 动画组件，一气呵成。

4.2 场景二：智能终端编译与真机调试（后台任务管理）

传统的 AI 工具生成代码后，你还要切回控制台手动编译。而在 DevEco Code 中，你可以说：> 帮我清理缓存并编译推送到真机。
它会自动在终端执行 hvigorw clean assembleHap 和相应的 hdc 安装命令。

4.3 场景三：异常捕获与自动化 Bug 修复（时光机回滚）

当项目编译失败或出现 Hilog 崩溃栈时，直接将报错信息粘贴进对话框，DevEco Code 会自动检索最新的 HarmonyOS 官方文档，定位错误堆栈并直接在源码中应用修复。

5. 进阶玩法：扩展你的专属 AI 开发流水线

依托鸿蒙智能体框架的开放生态，DevEco Code 允许开发者打造专属于团队的自动化产线。

5.1 玩转 Skills 与 Subagent：上下文隔离的艺术

在扩展团队自动化任务时，我们经常会遇到“大模型忘记上下文”或“Token 爆仓”的问题。DevEco Code 提供了两种不同的架构模式来完美解决：

• Agent Skill（技能）：通常以 Markdown 形式存放在 .agents/skills 目录下。Skill 运行时会完全继承当前主对话的上下文。
  • 适用场景：“基于刚才我们修改的代码，帮我生成符合规范的 Git Commit Message”。因为继承了记忆，它精准知道你刚才做了什么。
• Subagent（子智能体）：使用 /agent 命令唤起。它在后台开辟了一条绝对隔离的独立上下文窗口。
  • 适用场景：当你让 Agent 执行“鸿蒙全工程代码架构规范审查”时。Subagent 会在独立的沙箱里阅读几万行代码，最后只将几百字的最终审查报告传回给你的主对话。这样你的主对话永远干净利落，不会被源码碎片撑爆。

5.2 接入自定义 MCP：Figma 设计稿一键还原实战

MCP 是大模型连接外部工具（如数据库、第三方软件）的标准桥梁。

客户端/前端开发中离不开UI的开放，高效率的高保真的还原UI设计稿一直是客户端开发的难题，在AI开发工具中，之前都是把设计稿直接截图给AI解析后生成，但是效果差强人意，取决于AI对图像的理解效果，而且如果使用的模型是非多模态，不支持图片理解，则这条路也走不通了。有了MCP可以全包真的读取设计稿内容进行还原，效率和效果都很好，很多设计平台，比如mastergo、figma都提供了MCP服务。

通过在 DevEco Code 中安装 Figma MCP Server，你可以在终端直接下发设计稿链接：
> 请调用 Figma MCP，根据这个 URL 分析设计稿，并使用 ArkTS 重构我当前的首页 UI。
DevEco Code 会自主获取页面的截图、色值、间距和字体样式，生成贴合现代审美的鸿蒙原生 UI。这完美弥补了纯文本大模型缺乏视觉感知能力的致命痛点。

DevEco Code中安装MCP Server可以在可在 ~/.config/deveco/deveco.jsonc 中配置 MCP：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "playwright": {
      "type": "local",
      "command": ["npx", "@playwright/mcp@latest"],
      "enabled": true
    }
  }
}

这里面替换成figma或者master平台的配置后退出并重新执行 deveco 启动后就会开始生效。

5.3 自动化 Hooks 的运用

借用 Git Hooks 的思想，Claude Code可以使用 /hooks 设定 AI 工具执行前后的自动化逻辑。例如，配置一条 Hook：在 DevEco Code 每次修改完任意 .ets 文件后，自动静默执行 hvigorw format。这确保了无论 AI 生成的代码多么天马行空，落盘的代码永远符合团队严格的排版规范。但是遗憾的是DevEco Code基于OpenCode，没有提供hook能力，不过可以通过插件系统实现类似能力。

通过 .opencode/plugin/ 目录下的 TypeScript/JavaScript 插件，利用 tool.execute.before (对应 PreToolUse) 和 tool.execute.after (对应 PostToolUse) 拦截事件，功能覆盖且更灵活 。也可以使用社区独立插件opencode-claude-hooks，通过npm install opencode-claude-hooks安装后，在 opencode.json 加载插件，自动读取：

• /.claude/settings.json
• ~/.claude/settings.json

支持：SessionStart / UserPromptSubmit / PreToolUse / PostToolUse / Stop 等主流事件；command / http / prompt 三类钩子，大约 80% 语法兼容。

6. 避坑指南与工程最佳实践

💡 高级技术提示：

1. 上下文记忆压缩 (/compact)：随着深度的探讨，无效的中间思考和尝试日志会堆积在 AI 的记忆中。在完成一个里程碑功能后，务必执行 /compact 命令，它可以将数万 Tokens 的繁杂对话浓缩提炼为核心需求。这不仅大幅降低 API 成本，还能显著减少 AI 后续回答的理解延迟。
   
2. 自定义全局工程约束 (.deveco.md)：为了让 AI 懂你们的团队，可以在项目根目录创建一个 .deveco.md 文件。写入如：“所有业务组件必须按 Feature 模块拆分”、“网络请求必须使用团队内部封装的 XxHttp 库”。DevEco Code 每次启动都会优先读取它，如同给智能体戴上了“项目紧箍咒”，彻底消灭代码风格不统一的问题。
3. 网络与 API 兼容：如果你使用海外 LLM Provider，注意配置本地终端的网络代理环境。同时，生成代码时建议在 prompt 中显式强调当前工程使用的是 HarmonyOS NEXT 还是 HarmonyOS 5.0，以避免废弃 API 的误用。

7. 总结

DevEco Code 作为深度融合了操作系统能力的 CLI 优先智能体，绝非一个简单的“对话框”，而是真正参与工程构建、具备执行力和理解力的数字研发合伙人。

在 HarmonyOS 7 开启的 Agent 时代，重复的构建、排错与繁琐配置将被智能体彻底接管，核心的业务架构与产品创新将重回开发者手中。拥抱 DevEco Code，让我们在鸿蒙的星辰大海中，大展“鸿图”！