DevEco Code 还是 DevEco CLI？现有 Flutter 鸿蒙工程先分清工具职责

团队准备升级一个 Flutter 鸿蒙宿主，开发者把“帮我修好 API 26 构建错误”交给 AI 工具。屏幕上很快出现新代码，但第一次运行仍报插件路径找不到。问题不一定在 AI 能力，而在于任务没有拆开：谁负责提出修改，谁负责调用实际工具，谁确认改动没有破坏 Flutter/Dart 与鸿蒙宿主之间的契约？

华为把 DevEco Code 描述为面向 HarmonyOS 开发的 AI Agent，把 DevEco CLI 描述为提供工具集、官方知识库和 Skills 的原子化能力。本文用跨平台应援灯牌控制应用的基础工程示范如何把两者放进同一条可验证的工作链。参考工程当前是 Flutter + OpenHarmony API 20；本文没有在其中安装 DevEco Code/CLI，也没有完成 API 26 迁移。

1. 先把“AI 能帮忙”拆成三类工作

开发中的自然语言请求至少有三种：解释错误、修改源码、运行验证。第一类可以从日志和文件推理；第二类必须明确允许编辑哪些文件；第三类必须调用真实工具并保存输出。若把“给我一段建议”和“工程已经通过构建”混为一谈，用户最终得到的是没有证据的完成声明。

工作	预期产物	不能代替
DevEco Code 辅助分析/修改	变更建议、补丁、错误定位	编译日志与设备行为
DevEco CLI/本地工具调用	检查、构建、运行等实际输出	业务需求正确性
人工复核	跨端边界、兼容判断、验收结论	可重复的自动步骤

官方 HarmonyOS 7 新能力一览 概括了 DevEco Code 的生成、修复、构建和功能验证方向，以及 DevEco CLI 的工具化能力。具体命令与可用 Skill 会随安装版本变化，所以文章不凭宣传页推断某个子命令一定存在。

2. 在旧工程里先限定改动边界

参考工程有 Dart 页面、Flutter 平台通道、鸿蒙 ohos 宿主和 Gradle/KMP 相关部分。一次 API 26 评估若只关注 build-profile.json5，可能漏掉 Flutter OH 分支与插件对新 SDK 的支持。开始前先列出允许读取与允许修改的范围。

任务：找出鸿蒙宿主升级 API 26 的首个构建阻塞
允许读取：ohos/、pubspec.yaml、Flutter OH 版本信息
允许修改：本次确认的 ohos 构建配置或插件兼容代码
禁止修改：Android/iOS 业务行为、无关 UI、发布签名密钥
完成条件：给出原始错误、最小补丁、复跑命令和新日志

这是提交给开发助手的任务说明示例，不是某个工具的专用配置格式。重点是把成功条件放在命令输出上，而不是“AI 已回答”。若问题涉及签名或账号，先把凭据从日志和提示词中剔除。

3. 安装前核对工具来源与版本

官方页面给出了 @deveco/deveco-code@stable 与 @deveco/deveco-cli@stable 的 npm 安装入口。stable 是随时间变化的发布通道；团队复现故障时应记录实际解析到的版本，而不是只写“装了 stable”。以下命令是读者在自己机器上的操作示例，本文未在参考工程执行全局安装。

npm view @deveco/deveco-code@stable version
npm view @deveco/deveco-cli@stable version
npm install -g @deveco/deveco-code@stable
npm install -g @deveco/deveco-cli@stable
npm list -g --depth=0

输入来自官方包名，输出需要保存在环境记录中。安装报错时先查 Node/npm、网络源和包发布状态；不要为了让命令“看起来成功”切换到未知镜像或不明安装包。官方 DevEco Studio 工具页 是确认当前安装说明的入口。

4. 保留 Flutter 工程的真实源图

AI 助手若把工程误当作纯 ArkTS 项目，可能建议删除 Flutter 插件或重建 entry 模块。先给它最小源图：Dart UI 在 lib/，鸿蒙入口在 ohos/entry/，构建由 Hvigor 与 Flutter OH 插件协作。参考工程的 ohos/hvigorfile.ts 引入 flutterHvigorPlugin，EntryAbility.ets 继承 FlutterAbility；这些不是可以随意替换的样板。

$root = 'D:\lesson\lesson59'
rg -n 'flutterHvigorPlugin|flutter_tools|FlutterAbility|GeneratedPluginRegistrant' "$root\ohos"
rg -n 'MethodChannel|EventChannel' "$root\lib"
Get-Content -LiteralPath "$root\ohos\build-profile.json5" |
  Select-String 'compileSdkVersion|targetSdkVersion|compatibleSdkVersion'

这些命令用于建立修改前的事实清单。搜索结果是定位线索，不能自动证明插件兼容 API 26；需要继续查 Flutter OH 分支发布信息和真正的构建结果。实际写文章或问题单时，用产品场景解释用途，但保留源码中的真实文件名和符号。

5. 让 AI 给出“假设—证据—改动”三段式结果

例如 flutterHvigorPlugin 导入失败，有人会立即怀疑 SDK 版本；但更直接的可能是本地 file: 路径不存在、ohpm 依赖未安装或 Node/Hvigor 版本不匹配。向 DevEco Code 提问时，先给完整错误的前后文与环境版本，再要求它列出可证伪的假设。

请只分析第一次出现的错误，不继续猜测后续连锁报错。
输出：
1. 最可能的三个原因，每个附对应日志行或文件位置。
2. 每个原因的只读核查命令。
3. 建议的最小修改，不修改 Android/iOS 与发布签名。
4. 修改后的复跑命令及“什么输出才算通过”。
如果没有实际运行命令，请明确写“未运行”。

这段提示词的输入边界是脱敏日志和可读文件；它防止没有证据时直接动手。若工具能调用构建，仍要看它实际调用的目录、工具版本和退出码，而不只看最后一句解释。

6. 用 CLI 输出固定可重复步骤

DevEco CLI 定位是提供原子化开发能力，不等于参考工程已接入某个官方 Skill。对当前工程，最稳妥的验证起点仍是已有工具：先检查 flutter 与 Node 版本、依赖，再运行项目自己的 Hvigor/Flutter 构建命令。具体可用 CLI 子命令通过安装版本的 --help 查询，不在文章里虚构命令。

where.exe node
node --version
where.exe npm
npm --version
& 'D:\lesson\flutter_flutter\bin\flutter.bat' --version
Get-ChildItem -LiteralPath 'D:\lesson\lesson59\ohos' -Filter 'hvigorw*'

这一步只固定环境，尚未构建。参考工程的 Flutter OH 版本曾记录为 3.35.8-ohos-1.0.3-beta，但读者必须以自己机器上的命令输出为准。任何构建结果都要连同执行目录、完整命令、退出码和首个错误保存，否则无法与下一次尝试比较。

7. 评审 AI 补丁时优先看跨端契约

AI 可能提出“删除未使用的平台通道”来消除警告；然而 Flutter 端的 MethodChannel 名称、方法名、回调时序与鸿蒙插件注册关系，往往比一行构建配置更重要。审查时按“文件范围—行为变更—兼容性—验证”四栏看 diff。

git -C 'D:\lesson\lesson59' status --short
git -C 'D:\lesson\lesson59' diff -- ohos lib pubspec.yaml
git -C 'D:\lesson\lesson59' diff --check

diff --check 只能发现一部分空白问题，不代表 ArkTS/Dart 语义正确。看 diff 时先确认它没有触碰不在任务范围内的 Android/iOS 文件，也没有把本地绝对路径写进可移植配置；然后再按目标工程的构建和测试路径验证。

8. “编译通过”和“功能通过”要分别记

一段修改可能修好 ohpm install，但 Flutter 首页仍白屏；也可能本地 HAP 构建完成，API 26 设备上的插件调用仍失败。下面的验收记录把四层结果拆开，不能由上层替下层填“通过”。

层级	需要的证据	参考工程本次状态
静态改动	diff、修改原因	本文没有改工程
构建	命令、退出码、产物	未执行 API 26 构建
启动	设备版本、冷启动日志	未执行
功能	输入、预览、设备连接用例	基础工程未实现灯牌业务

华为 DevEco Studio 工具概述 列出了 IDE、Hvigor、ohpm 和命令行工具的职责。工具能力丰富并不意味着一个 AI 会话自动覆盖四层证据。

9. 常见误用如何排查

现象	首先核查	不要直接认定
AI 说“已修复”，工程仍报错	是否实际写入文件、是否复跑同一命令	工具在撒谎或项目不可修
CLI 找不到命令	当前版本 --help、PATH、Node/npm	文档中的所有能力都不存在
生成代码用到了纯 ArkTS 入口	是否识别 FlutterAbility 与插件注册	可以直接替换宿主结构
API 26 构建通过但旧设备失败	target/compatible 配置、插件兼容	新 SDK 本身有缺陷
日志上传包含密钥	工具隐私设置、日志脱敏	默认上传内容一定安全

DevEco Code 的 /collect 等日志相关命令在 官方命令说明 中有介绍；故障反馈前应检查将要提交的文件，不能把账号与签名材料一起交出去。

10. 一份可以直接复用的协作清单

开始前保存工具版本、工程提交和首个失败日志；提问时约束改动边界与完成标准；收到补丁后看 diff、跨端契约和命令输出；最后用设备把关键行为跑一遍。DevEco Code 负责提高定位与修改效率，DevEco CLI 与本地构建工具负责给出可重复的执行证据，开发者负责判断产品行为是否正确。

参考资料：HarmonyOS 7 新能力一览、DevEco Studio 工具页、工具概述、DevEco Code 命令说明。安装包版本、子命令和平台支持范围以当前官方页面和本机 --help 为准。