华为云码道接入 DevEco CLI 鸿蒙应用开发AICoding

一、前言

让 AI 写一张登录页，需求可以很直观：页面上有应用名、手机号、密码和登录按钮。但一张看起来像登录页的图，还没有回答几个开发问题：输入值由谁保存？密码切换成明文后是否还在？空输入如何提示？用到的 ArkUI API 是否适用于项目的 SDK？

这篇文章以虚构应用"云栖生活"为例，把华为云码道 CodeArts Agent 的项目技能与 DevEco CLI 接起来。

目标是让 Agent 沿着"读取官方文档---生成规格---修改 ArkTS---构建工程"的顺序工作。

码道负责理解任务、规划与修改代码，DevEco CLI 提供鸿蒙开发工具入口。华为开发者联盟另外提供的 DevEco Code 是独立 Agent，本文使用的客户端仍是华为云码道。

1.1 华为云码道与 DevEco CLI 的关系

很多人会把"AI 写代码"和"命令行工具"混为一谈。实际上它们是两层：

层级	角色	典型工作	本例对应
AI 智能体层	华为云码道（CodeArts）代码智能体	理解需求、生成规格、规划任务、修改代码、协调工具	读取 `requirements/统一登录页需求.md`，生成 `feature-spec.md` 与 `test_case.md`，修改 `Index.ets`，调用构建工具
工具链层	DevEco CLI / DevEco Studio / hdc / hvigor	编译、构建、签名、安装、设备管理、本地文档查询	`devecocli build`、`devecocli docs search`、hvigor 构建、HAP 打包

简单说：码道是"大脑"，DevEco CLI 是"手脚"。码道不会替代 CLI，而是通过项目 Skill 和内置工具去调用 CLI。这意味着：

没有 DevEco CLI/Studio，码道只能写静态代码，无法编译、打包、安装到设备。
有了 DevEco CLI/Studio，码道才能把这些工具编排进一个可验证的闭环。
"客户端显示 Skill 已加载"不等于"CLI 命令能执行"，更不等于"构建成功"，三者需要分别记录证据。

1.2 本文要示范的重点

本文重点不是介绍登录页怎么画，而是展示一种可验证的 AI 协作方式：

把需求写成规格（Spec），再让 AI 按规格编码；
把文档查询、代码修改、构建结果都留下可追溯的证据；
把 AI 工具调用与 DevEco CLI 调用区分开，避免把"AI 说成功了"当成"工程确实构建成功了"。

二、两种模式：Vibe Coding 与 Spec Coding

在让 AI 写鸿蒙页面时，实际存在两种工作模式。

2.1 Vibe Coding：凭感觉直接写

做法：给 Agent 一句自然语言，比如"把 Index.ets 改成登录页"，让它直接改代码。

优点：快，一轮对话可能就出界面。

缺点：

AI 可能凭记忆写 API，不查当前 SDK 文档；
没有明确验收标准，只能人工看截图判断对错；
改坏了难以追溯是需求理解错、API 用错，还是构建环境错；
多轮迭代后，代码和对话都容易失控。

证据要求：至少保留最终代码、构建退出码、HAP 路径。如果涉及设备验证，还需截图。

2.2 Spec Coding：先写规格再编码

做法：先把需求拆成规格文档（Feature Spec）和测试用例（Test Case），Agent 再依据规格生成代码，最后按用例验证。

优点：

需求、实现、验证三者解耦，便于逐条核对；
Agent 在编码前必须先查文档，减少凭记忆乱写；
测试用例成为共同验收标准，避免"看起来差不多就行"；
后续修复或回归时，规格和用例可直接复用。

缺点：前期需要多一步规格生成；对简单一次性任务可能显得重。

证据要求：需求文件、规格文档、测试用例、文档查询记录、代码差异、构建报告、测试报告（如有设备测试）。

2.3 本文采用的模式

本文采用 Spec Coding。原因很直接：这个登录页需求来自四平台对比实验，需要各平台在相同验收标准下实现；如果只让 AI 直接写，最终代码差异会大到无法对比。

对应到本工程，文件结构如下：

text 复制代码

requirements/
└── 统一登录页需求.md          # 原始需求（人工编写，四平台共用）

.codeartsdoer/hmos/runs/20261007-172500/
├── feature-request.md          # 码道归一化后的请求
├── feature-spec.md             # 8 个场景的规格
├── test_case.md                # 8 个测试用例、24 条"四诚实证据"断言
├── context-notes.md            # 文档查询记录与项目上下文
├── logic/
│   ├── commit-info.md          # 代码提交/变更说明
│   ├── convergence-report.md   # 构建收敛报告
│   └── entry-default-unsigned.hap  # 构建产物
└── feature-dev-manifest.md     # 完整流水线清单

三、Spec Coding 实战：从需求到 HAP

3.1 环境准备：让当前执行环境找到 DevEco CLI

本系列使用 Windows、DevEco CLI 1.3.0-stable、DevEco Studio 26.0.0.821 和 API 26 工程。版本是这次材料的环境记录，不代表之后安装 @stable 仍会取得同一个版本。官方快速入门给出的稳定版安装命令如下；本机已经安装，可以直接查版本。

powershell 复制代码

# 未安装时执行；已经安装的读者先核对版本
npm install -g @deveco/deveco-cli@stable
devecocli --version

# 本文机器的 Studio 安装位置，读者需替换为自己的路径
$env:DEVECO_CLI_STUDIO_PATH = 'D:\HarmonyOS\IDE\devecostudio-windows-26.0.0.821\DevEco Studio'

DEVECO_CLI_STUDIO_PATH 指向 Studio 安装根目录，不是项目目录，也不是 bin 子目录。PowerShell 中的 $env: 赋值只影响当前会话及其子进程；已经启动的 IDE 或另一个终端不一定取得它。后续应在 Agent 实际执行命令的环境中核对路径，避免人工终端能构建、Agent 却找不到工具链。

新建演示工程时，可用一个独立的英文路径：

powershell 复制代码

devecocli create --app-name LoginShowcase --bundle-name com.example.loginshowcase --api-level 26 --project-path 'D:\HarmonyLab\HuaweiLogin'
Set-Location -LiteralPath 'D:\HarmonyLab\HuaweiLogin'

D:\HarmonyLab\HuaweiLogin 是读者示例路径。系列准备阶段曾遇到 create 拒绝含中文的工程路径，因此这里采用 ASCII 路径。已有工程可以直接打开，不必重复创建。项目根目录应能看到 build-profile.json5，页面入口是 entry/src/main/ets/pages/Index.ets。

3.2 把随包 Skill 放入码道的项目目录

码道官方规定的本地项目技能目录是 .codeartsdoer/skills/。本篇把随 DevEco CLI 安装包发布的 SKILL.md 放进其 deveco-cli 子目录，让技能只服务于这个演示工程。

首次安装可在工程根目录执行：

powershell 复制代码

$projectPath = (Get-Location).Path
$npmGlobalRoot = (npm root -g).Trim()
$skillSource = Join-Path $npmGlobalRoot '@deveco\deveco-cli\SKILL.md'
$skillDirectory = Join-Path $projectPath '.codeartsdoer\skills\deveco-cli'
New-Item -ItemType Directory -Path $skillDirectory -Force | Out-Null
Copy-Item -LiteralPath $skillSource -Destination (Join-Path $skillDirectory 'SKILL.md')

最终目录应是：

text 复制代码

.codeartsdoer/
└── skills/
    └── deveco-cli/
        └── SKILL.md

当前 CLI 随包支持的 Agent 别名中没有 codearts，因此这里使用文件导入路线，不给读者杜撰一条 --agent codearts 命令。文件内容也应保留官方随包版本，方便与 CLI 版本对应。

打开这个工程，在码道设置的"技能与规则"中查看项目级技能，确认 deveco-cli 可见且已开启；然后在对话中明确要求使用该技能。

确认接入时，至少保留两个证据：客户端显示的技能名称和状态，以及 Agent 随后执行的 DevEco CLI 命令。仅列出磁盘上的文件，或者 Agent 回答一句"已加载"，都不足以独立核对后续调用。

本机验证中，码道项目级设置实际显示 deveco-cli，状态为启用，来源为当前工程的 .codeartsdoer/skills/deveco-cli。devecocli 可执行文件位于 D:\DevTools\npm-global\devecocli.ps1，--version 可正常返回 1.3.0-stable。但当前执行环境下 devecocli docs search 子命令会异常退出，因此本轮文档查询改用码道内置 skillSearch 完成；构建则通过码道 hmosBuild 工具（底层调用 DevEco CLI / hvigor）实际执行。这个结果说明"客户端加载 Skill""命令存在""子命令可正常执行"和"Agent 通过工具调用 CLI"需要分别记录。

3.3 写页面之前，先查询官方文档

DevEco CLI 的 docs search 和 docs read 是本地鸿蒙文档入口。Skill 告诉 Agent 怎样使用这些入口，查到的文档再为实现提供依据。理想情况下先分别搜索输入框和密码相关内容：

powershell 复制代码

devecocli docs search TextInput --limit 5
devecocli docs search 密码 --limit 5
# 把下面的占位符替换成上一步实际返回的 documentId
devecocli docs read '<实际返回的documentId>'

在本机当前执行环境中，devecocli docs search 子命令异常退出，因此 Agent 改用码道内置 skillSearch 完成等效查询。实际查询词与返回文档如下：

查询关键词	文档标题 / ID	用途
`ArkUI TextInput password type show hide icon`	`textinput #TextInputOptions对象说明`	确认占位文本、输入类型、密码可见性图标
`ArkUI Column Row Button Text layout padding margin borderRadius`	`button #Button`	确认按钮组件用法
`ArkTS @State @Component state management`	`@state：组件内状态 #@State`	确认组件内状态管理
`ArkUI prompt toast showToast message`	`class (promptaction) #showToast`	确认本地提示 API

其中 textinput #TextInputOptions对象说明 与 class (promptaction) #showToast 进一步通过 harmony-doc-view 读取了完整内容，确认 TextInput 支持 placeholder、type(InputType)、showPasswordIcon 等属性，以及 PromptAction.showToast 的调用方式。

在码道中可以先发送这段提示词：

text 复制代码

请使用当前工程的 deveco-cli Skill。先核对技能名称和来源路径。
若 devecocli docs search 可正常执行，请用它查找 ArkUI TextInput、密码输入及状态绑定的官方文档；
若该子命令异常退出，改用 skillSearch 完成等效查询。
请展示命令/查询词和返回的文档标题或 ID，并选择相关条目读取。
说明本工程如何保存手机号、密码及密码显隐状态，本轮先不要改代码。
若技能或文档查询不可用，保留真实错误，不要编造查询结果。

这一步应回答的是 API 与状态使用方式，不只是给出一段与项目版本无关的示例。保存文档 ID 之后，后续修复也可以回到同一条资料，而不必反复凭记忆猜 API。

3.4 生成规格与测试用例

在 Spec Coding 模式下，Agent 不直接改代码，而是先基于需求生成规格文档。本工程的需求是 requirements/统一登录页需求.md，Agent 据此生成：

feature-spec.md：8 个场景（初始渲染、手机号输入、密码输入、显隐切换、空手机号、空密码、演示成功、视觉适配）
test_case.md：8 个测试用例、24 条"四诚实证据"断言
context-notes.md：文档查询记录、项目架构说明、风险约束

这一步把"登录页"从一个模糊需求变成可逐项核对的契约。例如：

场景四明确规定：点击显隐控制后，密码内容保持不变；
TC-004 的断言 tp-015 要求：两次切换前后，密码输入框的实际内容保持为 mySecret123 不变。

这些断言在后续设备测试中可以直接使用；即使跳过设备测试，它们也明确了代码应该满足的行为。

3.5 编码实现"云栖生活"登录页

本系列四个平台使用相同的任务规格。页面背景为 #F6F8FC，主按钮为 #2563EB，左右边距约 24vp，顶部显示"云栖生活"和"欢迎回来，登录后继续探索"。手机号与密码默认空，密码默认隐藏，底部标明"演示界面，不连接真实账号服务"。

本轮实际修改了 entry/src/main/ets/pages/Index.ets，关键状态与逻辑如下：

typescript 复制代码

// 放在 @Entry / @Component 的 Index 组件内部
@State phone: string = '';
@State password: string = '';
@State isPasswordVisible: boolean = false;

private showToast(message: string): void {
  this.getUIContext().getPromptAction().showToast({ message: message });
}

private handleLogin(): void {
  if (this.phone.length === 0) {
    this.showToast('请输入手机号');
    return;
  }
  if (this.password.length === 0) {
    this.showToast('请输入密码');
    return;
  }
  this.showToast('演示模式，未连接账号服务');
}

手机号直接判空；密码只检查长度，保留用户实际输入。登录按钮调用 handleLogin()，通过 PromptAction.showToast 给出本地提示。密码显隐控制只修改 isPasswordVisible，不重建或重置密码值；密码输入框的 type 绑定为 this.isPasswordVisible ? InputType.Normal : InputType.Password，并开启 showPasswordIcon(true) 让系统提供默认显隐图标。

最终页面还包含：顶部蓝色圆形"云"字标识、应用名"云栖生活"、副标题"欢迎回来，登录后继续探索"、手机号输入区、密码输入区、胶囊样式"登录"按钮，以及底部"演示界面，不连接真实账号服务"文案。背景色 #F6F8FC，主文字 #1F2937，辅助文字 #6B7280，按钮背景 #2563EB，内容区左右边距 24vp，输入框圆角 12vp。

如果首轮页面已有布局，可用这个小迭代继续检查 AI 的修改质量：

text 复制代码

请只完善当前登录页的密码显示/隐藏行为。保留已有布局、phone与password状态。
查阅本机TextInput文档后实现显隐切换；输入一段演示密码后，连续切换两次，
密码内容应保持不变。不要在日志、最终报告或持久化文件中输出密码内容。
请说明改了哪些状态与事件，并列出检查这个行为的方法。

登录页的价值在这里开始显现：一张静态截图可以看布局，连续切换与点击行为才能看状态是否正确。

3.6 构建与收敛

在工程根目录执行代码规范检查与构建，且分别记录退出码。本轮实际通过码道 hmosBuild 工具调用 DevEco CLI / hvigor 完成构建，等价命令如下：

powershell 复制代码

# 本机实际由 hmosBuild 工具调用 devecocli / hvigor 执行
# 因原工程路径含中文字符，先在临时英文路径 D:\tmp\hmos-login 构建
devecocli build --project D:\tmp\hmos-login --mode release --product default --modules entry
$buildExitCode = $LASTEXITCODE
Write-Output "build exit code: $buildExitCode"

实际构建结果：

字段	值
构建状态	`BUILD SUCCESSFUL`
退出码	`0`
HAP 路径	`entry\build\default\outputs\default\entry-default-unsigned.hap`（临时构建路径）
产物大小	134,992 字节
签名状态	未签名（项目未配置 signingConfigs）
构建警告	`Function may throw exceptions`（来自 `showToast` 调用）；`Will skip sign 'hos_hap'`（未配置签名）

构建期间遇到一个问题：原工程路径 D:\AIApplication\workspace\wppdocs\鸿蒙材料\DevEco CLI与鸿蒙自动化\四平台鸿蒙登录页_20261005\runs\huawei_codearts_agent 包含中文字符和中文括号，hvigor 报错 00306003 Specification Limit Violation。处理办法是把工程完整复制到纯英文临时目录 D:\tmp\hmos-login，在那里构建成功后再将 HAP 拷回原始工程的输出目录 .codeartsdoer/hmos/runs/20261007-172500/logic/。原始工程路径下的代码文件与临时路径保持一致。

check lint 输出规范问题及实践建议，它不等同于完整语法、类型与打包验证。构建应看本次真实退出码、完整错误和新产物路径，不能只看终端中出现过"success"，也不能拿旧 HAP 当作这次修改的结果。

需要独立的语法诊断时，可以选配 DevEco CLI 内置 MCP。码道官方支持本地 stdio 服务，可在其 MCP 设置中添加。码道 MCP 说明

字段	本文的配置思路
服务名称	`deveco-mcp`
传输	`stdio`
启动程序	本机 Node 可执行文件的绝对路径；可用 `(Get-Command node).Source` 查询
参数	npm 全局包下 `@deveco/deveco-cli/dist/cli.js` 的绝对路径，以及 `serve`、`mcp`
环境	`PROJECT_PATH` 指向当前工程；`DEVECO_PATH` 指向本机 Studio 安装根

本机安装包的 MCP check 工具接受如下输入：

json 复制代码

{"files": ["entry/src/main/ets/pages/Index.ets"]}

这里只采用 check。其他语言工具以当前 Studio 和客户端实际暴露的列表为准；项目准备完成、服务连接成功、工具真正调用，是不同的记录项。Skill 不会自动开启 MCP，init --skill 与 init --mcp 也不能写在同一条命令里。CLI 的全部命令不会因此自动变成 MCP 工具。

码道在这个题材中可使用的能力，是官方支持的项目技能、本地 MCP 接入口以及内置的 HarmonyOS 开发工具（如 hmosBuild、skillSearch）。

把 DevEco CLI 的使用方法放到项目技能中，再把一张登录页拆成文档依据、页面状态和检查条件，能让后续协作有明确起点。

更重要的是，要区分两种 AI 协作模式：

Vibe Coding 适合快速验证想法，但证据容易缺失；
Spec Coding 适合需要可追溯、可对比、可回归的工程任务。