【HarmonyOS AI】鸿蒙开发者需要搞懂的 AI Coding 概念

【HarmonyOS AI】鸿蒙开发者需要搞懂的 AI Coding 概念

一、前言

最近群里聊 AI、DevEco CLI、DevEco Code，Skill、MCP、知识库这几个词出镜率很高，但真问起来，不少人其实只停留在看着眼熟，知道个大概的层面。

我一直推崇的就是费曼学习法，所以我坚持更新。所学所知，如果能完整表达，别人听后可以理解，这说明自己掌握牢固。这篇不堆术语，作为五年的鸿蒙开发者，今年也深入学习了AI，获得了相关AI的证书和能力认证，所以今天为了鸿蒙开发同学们从AI专有名词底层概念一层层往上讲，把每个东西内部长什么样、怎么工作、代码怎么写，都尽量说明白给大家听。

二、大模型与 AI Coding（AI编程）

AI Coding 的能力底座是 大模型（LLM），烧token，烧钱，再加上工程能力约束才能真正做好提效，否则只是demo。 现在的大模型基本上都基于 Transformer 架构，训练时喂进去海量代码和文本，学习 token 之间的关联规律。 推理时，你输入一段文字，模型会通过自注意力机制计算每个 token 与其他 token 的关联权重，最终输出一个概率分布，表示下一个 token 可能是哪个。 然后它用采样策略，比如贪心解码、temperature、top-k、top-p，选出一个 token，再把结果拼回输入，继续生成下一段。

（很多人说现在的LLM目前只是初级阶段，底层机制上，只是下字预测。但是基于上层Chain-of-Thought（思维链），Test-time compute（推理时计算）Agent 循环。借助外部反馈、在循环中迭代，表现出类似思考的效果。AI目前已经到达中级阶段。）

所以表面上看它是一句句地输出，实际上内部是「多层注意力计算 + 概率分布 + 采样」的循环。现在一些推理模型，比如 OpenAI o1、DeepSeek-R1、Claude 3.7 Thinking，还会在这个过程中进行自我验证、链式思考和多步推导，不只是单次 next-token 预测。

这个机制决定了它的两个硬伤。 1、AI幻觉 ：它会一本正经地编出不存在的 API、参数或路径，而且看起来特别像真的。 2、上下文窗口：它能同时看进去的文本长度有限，你把整个大工程塞给它，它后面就记不清前面的约束，写出来的代码前后矛盾。

所以很多人理解的「AI 写代码」其实还停留在代码补全，2024-2025年这个阶段（鸿蒙的CodeGenie就是代码辅助产品）：你敲半行，它补后半行。那确实是 AI，但和现在说的 AI Coding 不是一回事。 我们用 DevEco Code ，让它做个带验证码的登录页，它做的不是糊两段代码就交差，而是翻文档、写实现、自己构建、推到真机跑、跑崩了拉日志、看明白再改。整条链路走完，能跑的成品才递到你手上。

差别就在这里：补全只动嘴补两行，AI Coding 是把活干完，因为智能体有手有脚，这也是openclaw里程碑之后，带来的技术革新。

要让大模型靠谱地干完活，不能只靠模型本身，需要 Prompt、上下文工程、Agent、工具调用、知识库、RAG 这一套配合。

三、Prompt（提示词） 与上下文工程

你输入给 AI 的那段话，叫 提示词：Prompt。

Prompt 不是越长越好，关键是把任务背景、约束、验收标准说明白。

比如"写个登录页"和"写一个 ArkTS 登录页，账号密码登录，带验证码倒计时，适配手机和平板，用 ArkUI 状态管理 V2"，得到的完全是两个结果。

但 Prompt 只是入口。更系统一点的玩法是 上下文工程 。大模型的窗口有限，你不可能把整个项目都塞进去，所以需要挑最有用的信息喂给它：项目结构、代码规范、依赖关系、历史修改、相关文件片段。上下文工程的核心就是帮 AI 在有限窗口里建立对当前工程的正确理解。 DevEco Code 的 build模式，就是做一些简单的工作马上开干。 DevEco Code 的 Plan模式呢，就是简化提示词的负担，都过一步步和你沟通，确定最终的提示词内容。 DevEco Code 的 Goal 模式里，它会先生成 plan.md和 spec.md，其实就是在做这件事：把需求、约束、验收标准整理成一份结构化的上下文，后续所有代码生成和验证都围绕这份上下文展开，而不是让 AI 每次从零猜。

四、Agent：能自己干活的 AI

Agent 不是某个具体产品，而是一种工作方式。你可以把它理解成一个被你雇来、能独立跑流程的执行者：你下指令，它拆任务、调工具、看结果，搞不定才回头问你。（也看智能体的，有的超笨，还是需要调。）

Agent 能干活，核心靠两点。

1、工具调用（Function Calling） 。通用大模型只会输出文字，但 AI Coding 需要它真的能操作工程：读文件、跑命令、查日志、调用 API。工具调用就是大模型根据你的请求，判断该调哪个函数，并生成正确的参数。比如你说"构建这个项目"，它会识别出该调用 devecocli build，然后自己执行并读取返回结果。

一个典型的工具调用请求长这样：

{
  "name": "devecocli_build",
  "arguments": {
    "project_path": "D:\\DevTools\\deveco-projects\\MyApp",
    "build_mode": "debug"
  }
}

AI 不是直接帮你敲命令，而是向工具描述"我要做什么"，由工具去执行，再把结果返回给 AI。这样既安全又可复用。

工具调用这个概念不只是鸿蒙在用。OpenAI 在 2023 年 6 月给 GPT-4 加了 Function Calling，让模型可以输出结构化函数调用。后来各家模型都跟进，只是名字不同：有的叫 tool use，有的叫 function calling。它们做的事都一样：让 AI 从"只会聊天"变成"能操作外部系统"。

但工具一多就出问题。假设你有构建工具、日志工具、文档工具、测试工具，每个 AI 助手都要单独接一遍，就是 N×M 的网状集成。每新增一个工具，所有 AI 助手都要改一遍；每新增一个 AI 助手，所有工具都要改一遍。这件事迫切需要标准化，于是 MCP 出现了。

2、结果闭环。Agent 不是写完代码就算完，而是要构建、运行、验证，发现不对再改，直到满足验收标准。没闭环的 AI 是在猜，有闭环的 AI 才靠谱。华为对 DevEco Code 的官方定位是"开箱即用的鸿蒙 AI Coding 工具"，意思就是它出厂就理解鸿蒙这套工程体系，能自己跑这个闭环。

五、MCP：统一工具插座

MCP（Model Context Protocol，模型上下文协议） 是 Anthropic 在 2024 年 11 月开源的协议。

它的定位很简单：给 AI 工具定义一个统一的插座标准。工具按 MCP 标准暴露接口，任何支持 MCP 的 AI 都能插上来用，不用重复对接。可以理解成笔记本电脑的万能插头效果。

MCP 基于 JSON-RPC 2.0 通信，核心角色有三个：

• Host：运行 AI 的应用，比如 Cursor、Claude、DevEco Code。
• Client：Host 里的一个连接器，负责跟一个 MCP Server 建立会话。
• Server：提供具体能力的服务，比如 DevEco CLI 内置的 MCP 服务。

连接时先走初始化协商，双方交换支持的 capabilities：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "sampling": {} },
    "clientInfo": { "name": "DevEcoCode", "version": "0.1.3" }
  }
}

Server 回应自己支持的能力，比如 tools、resources、prompts：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": {}, "resources": {} },
    "serverInfo": { "name": "deveco-mcp", "version": "1.2.0" }
  }
}

协商完成后进入操作阶段。MCP 定义了三种核心能力：

• Tools：供 AI 调用的功能，比如构建项目、读取日志、查文档。
• Resources：可向 AI 提供的上下文数据，比如文件内容、项目配置。
• Prompts：预定义的提示模板，比如"分析这段崩溃日志"。

AI 想调用工具时，先通过 tools/list 查看有哪些工具可用：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

Server 返回工具清单，每个工具配一份 JSON Schema，说明名字、功能、需要什么参数：

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "devecocli_build",
        "description": "构建 HarmonyOS 项目",
        "inputSchema": {
          "type": "object",
          "properties": {
            "build_mode": { "type": "string", "enum": ["debug", "release"] }
          },
          "required": ["build_mode"]
        }
      }
    ]
  }
}

AI 决定调用时，发 tools/call：

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "devecocli_build",
    "arguments": { "build_mode": "debug" }
  }
}

Server 执行完返回结果：

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      { "type": "text", "text": "BUILD SUCCESSFUL in 272 ms" }
    ],
    "isError": false
  }
}

落到鸿蒙开发这边，DevEco CLI 内置了 MCP 服务。你常用的 AI 助手，比如 Cursor、Claude、WorkBuddy，接上之后就能直接命令它"构建这个项目""把包推到那台 Mate 60""把报错日志拉出来"。配置就一行：

devecocli init --mcp --agent opencode --project .

跑完会在项目里生成 .opencode/opencode.json，里面描述 MCP Server 怎么启动：

{
  "mcp": {
    "deveco-mcp": {
      "type": "local",
      "command": ["devecocli", "serve", "mcp"],
      "environment": {
        "PROJECT_PATH": "D:\\DevTools\\deveco-projects\\MyApp"
      },
      "enabled": true
    }
  }
}

之后你的 AI 助手启动时，会自动拉起 devecocli serve mcp 这个进程，通过 stdio 或 HTTP 与 CLI 通信。AI 从只会聊天，变成真正能操作你的工程。

六、Skill：把经验打包成指令

那 Agent 凭什么偏偏懂鸿蒙，不像通用大模型那样瞎编？答案在 Skill 和知识库。

Skill 可以理解为把老师傅的经验固化下来的一包精确指令。那些高频、又特别容易出错的操作，提前写明白步骤打包好，你一声令下它直接执行，不用大模型当场现编流程。

一个 Skill 包其实就是一个目录，里面有固定结构。以 hmos-arkui-develop-skill 为例：

hmos-arkui-develop-skill/
├── SKILL.md              # 入口文件：说明这个 Skill 是干什么的、什么时候触发、怎么工作
├── README.md             # 给人看的友好说明
└── references/           # 知识库资料
    ├── quick-apis/       # API 速查表
    │   ├── 01-layout.md
    │   ├── 02-basic-components.md
    │   ├── 08-state-decorators.md
    │   └── 16-enums.md
    ├── quick-rules/      # 编码规则与常见错误
    └── common-mistakes/  # 典型踩坑案例

SKILL.md 是核心。它通常在头部用 YAML frontmatter 描述元信息：

---
name: hmos-arkui-develop-skill
description: |
  ArkUI 代码开发助手，面向 HarmonyOS UI 开发，提供基于知识库的 UI 开发能力。
  触发场景：
  (1) 用户要求生成 ArkUI 页面或组件
  (2) 用户在现有 .ets 工程上要求增删改功能
  (3) 用户提供报错/截图要求修复 ArkUI 代码
---

正文部分写工作流、核心原则、输出格式。比如它会规定：写代码前先查 references/quick-apis/ 确认参数，不凭记忆去干活。只做必要的修改，不覆盖已有业务逻辑；生成完后要做语法检查。

分析类 Skill 的结构类似，但 references 里放的是故障模式库。比如 hmos-jscrash-analysis：

hmos-jscrash-analysis/
├── SKILL.md
├── README.md
└── references/
    ├── fault-mode-library.md   # 按 Reason / Error name / Error message 匹配的三级根因库
    └── jscrash-patterns.md     # 典型崩溃模式与修复建议

它的 SKILL.md 会规定工作流：先提取日志里的 Reason、Error name、Error message、Stacktrace，再匹配 fault-mode-library，定位第一个应用栈帧，然后输出根因和修复建议。AI 拿到这个 Skill，就不是在瞎猜崩溃原因，而是按既定流程分析。

鸿蒙 Skill 市场目前大概有 33 个，按用途分几类。 写代码相关的：hmos-arkts-syntax-checker 专查 ArkTS 语法错，hmos-arkui-develop-skill 管组件怎么写，hmos-arkts-knowledge-retriever 负责查 API 资料； debug 那一类更全：hmos-jscrash-analysis 看 JS 闪退，hmos-cppcrash-analysis 看原生层崩溃，hmos-appfreeze-analysis 看冻屏卡死，hmos-memleak-analysis 查内存泄漏 hmos-jsleak-analysis 此外还有管多设备适配的 hmos-multidevice-scenario-entry 查废弃接口的 hmos-arkts-deprecated-interface-checker 帮状态管理从 V1 迁到 V2 的 hmos-arkui-statemgt-migration。

安装时一条条加，也可以整包拉：

devecocli skills add --skill hmos-arkts-syntax-checker --path D:\deveco-skills
devecocli skills add --skill hmos-jscrash-analysis --path D:\deveco-skills
devecocli skills add --skill hmos-memleak-analysis --path D:\deveco-skills

华为文档里提到，Skill 能把任务速度提 3 倍以上、Token 消耗降 70% 往下，原因是 AI 不必在对话里反复背那些又长又易错的配置。而且这些能力跟着 IDE 版本走，永远对应当下的最佳实践，不会让你用出过时的写法。

七、知识库与 RAG

知识库 更接近一份随时可查的规范手册。通用大模型有个硬伤：什么都知道一点，一到鸿蒙这种有自己一套规矩的领域就露怯，多设备适配、元服务那些弯弯绕它真不一定接得住，让你写容易写出过时、堆技术债的代码。

知识库是官方跟着版本实时更新的，AI 动手前先去翻：这个组件叫什么、参数怎么传、这版支持不支持。在 CLI 里查文档就是一条命令的事：

devecocli docs search "TextInput"
devecocli docs read harmonyos-guides/application-models/arkts-page-start-overview

但知识库不是简单把文档存起来让 AI 去读。它的底层通常用 RAG（检索增强生成） 实现。RAG 的思路分四步：

1. 切分文档：把长文档切成小段，比如每个组件一段、每个 API 一段。
2. Embedding 向量化：用 Embedding 模型把每段文本转成一组数字向量。语义相近的文本，向量距离也近。
3. 存入向量库：把所有向量存进向量数据库，比如 FAISS、Milvus、Chroma。
4. 检索生成：AI 收到问题时，先把问题也转成向量，去库里找最相似的文档片段，再把找到的内容塞进 Prompt 一起生成。

Embedding 举个例子："TextInput 的 placeholder" 和 "输入框提示文字" 这两个句子，人类知道意思相近，Embedding 模型也会把它们映射到向量空间里相近的位置。这样即使文档里没出现"placeholder"这个词，只要语义相近，也能被检索出来。

RAG 解决的问题很直接：大模型不是记忆大师，它会忘、会编。RAG 让 AI 不用背整本手册，而是临时查最相关的那几页，再回答。这样生成出来的代码更准确，也更不容易过时。

AI 抓准了官方资料再写，和凭记忆编，出来的东西完全不是一个档次。

八、 DevEco Code 与 DevEco CLI

讲了这么多概念，该落到两件工具上了。DevEco Code 和 DevEco CLI 是华为给鸿蒙 AI Coding 搭的两个支点，分工明确。

DevEco Code 管的是 AI 体验本身。它是个命令行式的 AI Coding 工具，核心解决"怎么理解需求、怎么规划任务、怎么生成和修复代码"。它支持 Build / Plan / Goal 三种模式，内置 ArkTS 知识库和 Skills，支持推理模型的 thinking 参数，可以把思考过程打出来。0.1.3 这版重点提升了 ArkTS 代码生成质量、Goal 模式的工程化能力，以及中英文切换、低配 CPU 兼容等日常体验。

安装方式：

npm install -g @deveco/deveco-code

启动后是一个 TUI 界面，按 Tab 切模式，输入自然语言需求即可。

DevEco CLI 管的是工程能力入口。它把 HarmonyOS 开发里原本散落在 IDE 里的能力，统一包成命令行：创建工程、构建打包、管理设备和模拟器、安装 Skills、检索文档、读取日志、启动 MCP 服务。它更适合被脚本、CI/CD 和 Agent 调用。

安装方式：

npm install -g @deveco/deveco-cli@latest