DevEco Code 深度研读:华为鸿蒙系统 AI Agent 开发闭环

DevEco Code 的定位：面向华为鸿蒙系统的 AI Agent CLI

DevEco Code 是一款面向华为鸿蒙系统应用开发的 AI Agent 命令行工具。它的目标不是只回答技术问题，也不是只生成一段代码，而是把开发者日常要做的读代码、改代码、检查 ArkTS、构建项目、运行应用、查看日志和验证 UI 放进同一个终端工作流。

这个定位很关键。很多 AI 编程工具的能力边界停在「写出代码」，DevEco Code 进一步强调「把代码跑起来」。对鸿蒙应用开发来说，这意味着 Agent 需要理解 DevEco Studio、Hvigor、HDC、ArkTS 规则、项目结构和设备运行环境，而不是只懂通用 TypeScript。

源码层面看，DevEco Code 基于 OpenCode 扩展开发，保留了 OpenCode 的 TUI、Provider、MCP、Skill、Plugin 和多 Agent 架构，再针对 HarmonyOS 场景增加专用工具链。这种路线让它既有通用 AI 编程底座，又能聚焦鸿蒙开发者的真实流程。

工程结构：主战场在 packages/opencode

仓库仍然保留 OpenCode 上游的大型 monorepo 形态，包括 Web App、桌面端、SDK、Slack 集成、控制台等目录。但 DevEco Code 当前最核心的发布形态是 CLI，主包在 `packages/opencode`，命令入口是 `deveco`。

`packages/opencode/package.json` 里可以看到 CLI binary 配置：

{          name: 'deveco',          bin: {          deveco: './bin/deveco'          }          }

根目录声明 Bun 作为包管理和构建工具，`packages/opencode` 的脚本也围绕 Bun 展开，例如 `typecheck`、`test`、`build`。发布时，源码内部包名和版本会通过发布脚本转换为 npm 包 `@deveco/deveco-code`，最终用户安装后执行的是 `deveco` 命令。

这说明读这个仓库时要有一个判断：不是所有目录都和当前 DevEco CLI 发布直接相关。理解它的运行链路，优先看 `packages/opencode/src`、`packages/opencode/resources` 和 `packages/opencode/script`。

插件层：三类 DevEco 专用扩展

DevEco Code 的专用能力首先从内部插件加载开始。源码里默认加载了三个内部插件：认证插件、数据分析插件、Harmony N-API 动态工具插件。

const internalPlugins = [          DevEcoAuthPlugin,          AnalyticsPlugin,          HarmonyNapiDynamicToolsPlugin,          ]

`DevEcoAuthPlugin` 负责华为账号登录、OAuth token 注入和刷新；`AnalyticsPlugin` 负责在登录且允许采集时记录会话与工具使用数据；`HarmonyNapiDynamicToolsPlugin` 则负责把本地 HarmonyOS 相关能力注册成 Agent 可调用工具。

这个插件层是 OpenCode 通用体系和 DevEco 定制体系之间的连接点。OpenCode 提供插件钩子，DevEco Code 借这些钩子接入账号、模型、后端服务和原生工具。

工具层：把鸿蒙开发动作变成 Agent 能调用的工具

DevEco Code 最值得关注的是工具层。它把鸿蒙应用开发中经常出现的动作拆成工具，然后让 Agent 按场景组合调用。

常见工具可以分成三组：

·项目与上下文工具：`switch_cwd` 用来切换当前会话绑定的 HarmonyOS 项目根目录。

·代码与构建工具：`arkts_check`、`check_ets_files`、`build_project` 用来做 ArkTS 检查和项目构建。

·设备与验证工具：`start_app`、`verify_ui`、`save_ui_screenshot`、`get_ui_verification_log` 用来启动应用、验证界面、保存截图和读取日志。

其中 `build_project`、`start_app`、`verify_ui` 等工具来自动态工具定义，再通过 `@deveco-codegenie/mcp-bridge` 走原生桥接。可以把它理解为：TypeScript 侧负责 Agent 体系和参数校验，原生 bridge 侧负责靠近 DevEco Studio、模拟器和设备的具体动作。

async function callHarmonyNapiTool(input: ToolInput) {          await ensureInitialized(input.worktree)          const resultJson = await bridge.callTool(input.toolName, JSON.stringify(input.args))          return JSON.parse(resultJson)          }

这套设计的意义在于，Agent 不需要直接拼命令行，也不需要猜本机工具路径；它通过稳定工具接口调用能力，用户也更容易理解每一步到底做了什么。

ArkTS 检查：让 AI 写代码更贴近鸿蒙规范

ArkTS 的语法和类型约束比普通 TypeScript 更严格。AI 如果只按通用 TypeScript 习惯生成代码，就容易写出不符合 ArkTS 规则的实现。DevEco Code 为此提供了 `arkts_check`，让 Agent 在完整构建前先对指定 `.ets` 文件做快速检查。

这个工具会把内置检查脚本写到临时目录，然后使用 DevEco Studio 自带 Node 运行。它返回结构化诊断，包括文件、行号、列号、严重级别、错误信息和规则名。

一个理想的修改流程是：

编辑 .ets 文件          -> arkts_check 快速检查          -> 修复 ArkTS 规则问题          -> build_project 完整构建          -> start_app 运行验证

这种顺序很适合 Agent，因为它把反馈提前了。越早发现 ArkTS 约束问题，越容易做小步修正，也越接近真实鸿蒙开发流程。

Agent 和 Skill：从普通助手升级为工程流程

DevEco Code 不只改了工具，还重写了 Agent 行为。默认 `build` agent 的提示词明确要求：构建用 `build_project`，运行用 `start_app`，编辑 `.ets` 后用 `arkts_check` 做快速反馈，UI 验证则需要用户明确提出。

它还内置了多个 HarmonyOS 相关 Skill：

·`deveco-create-project`：创建 ArkTS 项目。

·`arkui-knowledge`：提供 ArkUI 界面开发指导。

·`arkts-grammar-standards`：提示 ArkTS 语法规范。

·`arkts-error-fixes`：辅助修复编译与类型错误。

·`arkts-runtime-fix`：辅助定位运行时崩溃和日志问题。

更进一步的是 `goal` agent。它要求按 SDD 五阶段推进：需求分析、架构设计、任务拆解、实现、验证。实现交给 `spec-implementation` 子代理，验证交给 `spec-verify` 子代理。对复杂功能来说，这套流程可以让 Agent 先形成需求和任务，再进入编码和验证。

登录、模型与知识库：在线能力构成体验上限

DevEco Code 的内置模型通道依赖华为账号登录。登录流程会打开浏览器，通过本地回调服务器接收结果，默认端口为 `10101`。源码中还可以看到区域限制逻辑：当前只接受中国站账号。

本地保存的 OAuth 信息会做加密处理，敏感字段使用 AES-256-GCM 存储。这一层设计让用户登录态可以跨会话复用，同时避免明文保存 token。

模型方面，源码中有默认配置，也会向 DevEco 后端拉取动态模型列表。静态默认值里，文本模型是 `glm-5`，UI 验证模型是 `Qwen2.5-VL-72B`；README 中还提到 GLM-5.1 和 Qwen3-VL。这里说明模型入口具备动态更新空间，实际可用模型以服务端和登录态为准。

知识库工具 `arkts_knowledge_search` 也依赖登录。它要求 Agent 在回答 ArkTS、ArkUI、HarmonyOS SDK、构建错误等问题前优先查询官方知识库。这是很实用的约束，因为鸿蒙 API 和框架能力会持续更新，单靠模型记忆并不可靠。

发布与运行环境：先把工具链准备好

DevEco Code 通过 npm 发布，用户侧最短路径是：

npm install -g @deveco/deveco-code          deveco

如果只做对话和代码编辑，Node.js 是基本前置条件；如果要构建、运行、设备调试，还要安装 DevEco Studio，并配置 `DEVECO_HOME` 指向安装目录。源码发布脚本当前聚焦 Windows x64、macOS arm64、macOS x64 三类平台，README 也明确当前平台支持集中在 Windows 和 macOS。

源码里有一个值得记录的口径差异：README 推荐 DevEco Studio 6.1 及以上，而 `env.ts` 里的最低版本常量是 `6.0.0`。实践中建议按 README 准备 6.1 及以上环境，能获得更一致的工具链体验。

落地关注点：数据、权限和工具命名

面向个人开发者，DevEco Code 的集成度很有吸引力；面向团队试点，则建议提前关注三件事。

第一是数据采集。Analytics 插件会在登录并启用采集时记录 query、answer、token、工具调用、修改文件名、增删行数、系统信息等，并上传到华为端点。项目名会做哈希，但对话正文仍属于需要纳入团队规范管理的数据。

第二是权限边界。DevEco Code 能读写文件、调用构建、启动应用和访问外部工具。团队环境里建议先明确工作区范围、敏感文件读取策略、外部目录访问策略和插件来源。

第三是工具命名。源码里同时存在 `arkts_check` 和 `check_ets_files` 两条检查路径，README 工具表更偏向展示 `check_ets_files`。对普通用户来说，最好把推荐流程固定下来：编辑后优先快速检查，再完整构建，最后按需要启动和验证。

推荐试用路径：从小闭环到完整闭环

我建议把 DevEco Code 的试用分成三层推进。

第一层是代码协作闭环：让它读项目、解释架构、修改小功能、执行 ArkTS 快速检查。这能验证它是否理解项目结构和 ArkTS 基本约束。

第二层是构建运行闭环：配置 `DEVECO_HOME`，让它执行 `build_project`，构建通过后再执行 `start_app`。这能验证本地 DevEco Studio、SDK、模拟器或真机环境是否被正确接入。

第三层是验收闭环：在明确需要 UI 验证时，再启用 `verify_ui`。这个能力适合验证页面是否打开、按钮是否响应、核心流程是否走通；如果要判断复杂动效或极细视觉差异，仍建议结合人工确认。

总的来说，DevEco Code 的方向非常清晰：把华为鸿蒙系统应用开发中的编码、检查、构建、运行、诊断和验证串成一个 Agent 可执行的工程闭环。它值得作为鸿蒙开发团队的智能化工作台来研究和试点。