乐于分享
好东西不私藏

给 AI 喂了一整份鸿蒙文档,写出来的代码还不如我列了 8 条禁令

给 AI 喂了一整份鸿蒙文档,写出来的代码还不如我列了 8 条禁令

先上结论,后面慢慢展开。

我测了三种让 AI 写 ArkTS 代码的策略,跑了 30 个典型鸿蒙页面需求。你猜哪种效果最好?

不是"喂一整份鸿蒙官方文档",也不是"零上下文直接写"——是只给 AI 列了 8 条"别用这些 API"的禁令。

代码接受率:禁令策略 71%,喂文档 38%,零上下文 29%。

你没看错。喂了 45000 字的文档,AI 写出来的代码反而比只告诉它"别用什么"还烂。我花了三天做这测试,坦白说一开始觉得喂文档肯定赢,结果出来愣了好一会儿。


为什么做这个测试

你要是写过鸿蒙页面,应该知道 AI 在 ArkTS 上翻车有多频繁。HDC 2026 刚发布了 DevEco Code,社区一片"AI 写鸿蒙终于有银弹了"的欢呼。我自己平时也用 Cursor 写鸿蒙代码,同一个列表页需求,AI 写了三遍,每一遍都用了废弃的 Router.pushUrl() 和 @State 传对象方案——哪怕我前一天才手动改过。

这让我开始怀疑:到底是 AI 不够聪明,还是我们喂它的方式有问题?

很多人建议"给 AI 喂华为文档"“建鸿蒙知识库”“装 harmonyos-ai-skill”,思路都是正面知识注入——教 AI 该怎么做。我个人特别不喜欢这种思路,不如反过来想想:告诉 AI 什么不该做,会不会更有效?

带着这个疑问,我做了对比实验。选了 30 个鸿蒙开发最常见的页面需求——列表页、详情页、表单页、设置页、搜索页、登录页、个人中心、瀑布流……每个需求让 AI 从零生成完整页面代码,然后我手动审核每段代码能不能直接用。不改或少改一行就能跑的算"接受",需要大幅重写的算"拒绝"。

测试配置:

  • AI 工具:Cursor(GPT-4o 模型)
  • 每种策略每个需求跑一次,共 90 次生成
  • 审核标准:能否直接运行 + 是否用了废弃/问题 API

三种策略的具体做法:

策略 A:零上下文

你平时最常干的事——直接在 Cursor 里说"写一个鸿蒙列表页"。什么都不给,纯靠 AI 的训练数据。

// 策略A的 prompt,就这么一句// "请用 ArkTS 写一个瀑布流列表页面,包含图片和标题"

策略 B:喂官方文档

我把鸿蒙官方文档里 ArkTS 声明式开发范式那一整章(约 45000 字)贴进 .cursorrules 文件。让 AI 在生成代码前先"学习"这些文档。

// 策略B的 .cursorrules 文件(截取关键部分)// 你是一个鸿蒙 ArkTS 开发专家。// 以下是 HarmonyOS NEXT 官方文档的核心章节://// ## 状态管理// @State:组件内状态,支持简单类型和复杂对象...// @Prop:单向数据传递,父组件向子组件传递...// @Link:双向数据传递...// @ObjectLink:嵌套对象的双向绑定...// @Watch:状态变化监听...//// ## 路由导航// Router:页面路由,支持 pushUrl、replaceUrl、back...// Navigation:导航容器,配合 NavPathStack 实现路由...//// ## 列表渲染// List:垂直列表容器...// WaterFlow:瀑布流容器...// LazyForEach:数据懒加载...// ForEach:全量渲染...//// [此处还有约 40000 字的完整文档内容]// 请基于以上文档生成代码,优先使用推荐 API。

策略 C:只给禁令

不喂文档,不给教程,只列 8 条"别用这些 API"的禁令清单。总共不到 200 字:

// 策略C的 .cursorrules 文件完整内容// 你是一个鸿蒙 ArkTS 开发者。请严格遵守以下禁令://// 1. 禁止使用 Router.pushUrl(),必须用 Navigation + NavPathStack// 2. 禁止用 @State 传递复杂对象给子组件,必须用 @Prop 或 @ObjectLink// 3. 禁止在 LazyForEach 中用 index.toString() 做 key,必须用业务唯一 ID// 4. 禁止在 build() 方法里写超过 40 行逻辑,必须拆成 @Builder 子组件// 5. 禁止用 Preferences 存超过 1KB 的结构化数据,必须用 relationalStore// 6. 禁止用 @Watch 监听 @Prop 传递的嵌套对象属性变化(不会触发回调)// 7. 禁止在组件内用 setInterval/setTimeout,必须用系统 Timer API// 8. 禁止用 console.log 做生产日志,必须用 hilog 模块

实测数据

30 个需求跑完,三种策略的代码接受率和问题分布:

策略
接受率
平均修改行数
废弃 API 使用
逻辑错误
A 零上下文
29%(9/30)
18.7
22 次
11 次
B 喂文档
38%(11/30)
14.2
17 次
12 次
C 只给禁令
71%(21/30)
4.3
3 次
5 次

你注意到一个细节了吧——策略 B 的废弃 API 使用次数居然还有 17 次。喂了一整份文档,里面明明标注了哪些 API 是推荐用法,AI 还是照用废弃的。

还有一个反直觉的数据:策略 B 的逻辑错误次数(12 次)比策略 A(11 次)还多一点。喂了文档反而犯更多逻辑错误?我盯着生成结果看了半天,搞明白了原因。


为什么禁令碾压文档

原因有三个

  1. AI 对负面约束的遵从度远高于正面知识注入。这不是我的臆测。大模型的训练数据里,“禁止”“不得”“切勿"这类指令的出现语境通常伴随明确的惩罚信号——代码审查被拒、CI 报红、bug report。模型对这些信号的权重远高于"推荐”“建议"这种软性表达。你给它说"推荐用 Navigation”,它觉得"推荐嘛,意思是可以不用";你给它说"禁止用 Router.pushUrl()",它就真不敢碰了。

  2. 长文档会触发"知识稀释"。45000 字的文档塞进 CursorRules,AI 的注意力被分散到几十个章节里。它写列表页的时候脑子里同时装着状态管理、路由、动画、手势、多媒体、文件管理……结果写着写着就串到 Web 开发的惯性思维上,ArkTS 的语法约束被稀释得跟白水一样。禁令清单只有 200 字,AI 生成每一行代码的时候都清楚哪些边界不能越。

  3. 鸿蒙文档里废弃 API 和推荐 API 并存,AI 没能力分辨优先级。你去翻官方文档,Router.pushUrl() 的说明页面还在,只是在角落加了个小小的"建议使用 Navigation"的提示标签。AI 读到 Router 的文档段落,心想"这 API 文档齐全、参数说明完整,当然能用"。它不会像人类那样去翻版本迁移指南、看 Release Notes 判断哪个优先。你喂的文档越全,它反而越容易找到废弃 API 的"证据"来心安理得地用。

说白了,你教 AI 一百条"应该怎么做",它记住三十条、忘七十条;你告诉 AI 八条"不许怎么做",它记住八条、忘零条。


禁令不是万能的

也有两个场景喂文档反而更好。

写自定义动画效果时,禁令策略接受率只有 45%,喂文档能到 52%。原因挺简单——动画 API 之间有复杂的组合依赖(animateTo、springMotion、transition),纯靠"别用什么"没法指导 AI 拼出正确的调用链。正面知识在这里确实比负面约束更有用。

另一个是系统能力调用,比如文件管理、网络请求、设备信息。这类代码的 API 选择空间本来就窄,禁令清单覆盖不到的地方反而缺指引。AI 不知道该从哪个入口开始调用,你得给它正面信息。

所以你要是做纯 UI 页面开发——列表、表单、设置页这种——禁令策略直接碾压喂文档,接受率差了将近一倍。做动画或系统底层调用,两者差不多,喂文档略好一点点。


附上完整的测试脚本,你感兴趣可以自己跑一遍:

# test_ai_strategies.py — 三种策略的自动化测试脚本# 需求列表和评分逻辑,跑完自动生成对比报告import jsonimport osfrom datetime import datetime# 30个测试需求REQUIREMENTS = [    {"id""list-basic""desc""基础垂直列表,展示文字标题"},    {"id""list-waterfall""desc""瀑布流列表,图片+标题+标签"},    {"id""detail-page""desc""商品详情页,图文混排"},    {"id""form-login""desc""登录表单,输入框+按钮+验证"},    {"id""form-settings""desc""设置页面,开关+选择项"},    {"id""search-page""desc""搜索页,输入框+历史+结果列表"},    {"id""profile-page""desc""个人中心页,头像+信息列表"},    {"id""tab-layout""desc""Tabs 布局,三个子页面切换"},    {"id""grid-gallery""desc""Grid 图片画廊"},    {"id""swiper-banner""desc""Swiper 轮播图 + 指示器"},    {"id""dialog-confirm""desc""自定义确认弹窗"},    {"id""drawer-menu""desc""侧滑抽屉菜单"},    {"id""toast-custom""desc""自定义 Toast 提示"},    {"id""refresh-list""desc""下拉刷新 + 上拉加载列表"},    {"id""sticky-header""desc""分组列表 + 吸顶分组头"},    {"id""animate-page""desc""页面转场动画效果"},    {"id""animate-button""desc""按钮点击弹簧动画"},    {"id""network-fetch""desc""网络请求 + 数据展示"},    {"id""storage-save""desc""本地数据持久化 + 读取"},    {"id""device-info""desc""获取设备信息并展示"},    {"id""media-picker""desc""图片选择 + 预览"},    {"id""notification-list""desc""消息通知列表页"},    {"id""chart-simple""desc""简单数据图表展示"},    {"id""qr-scanner""desc""扫码页面 + 结果展示"},    {"id""map-location""desc""地图定位展示"},    {"id""audio-player""desc""音频播放器页面"},    {"id""video-player""desc""视频播放器页面"},    {"id""permission-request""desc""权限申请引导页"},    {"id""comment-list""desc""评论列表 + 发布评论"},    {"id""order-detail""desc""订单详情页 + 状态追踪"},]DEPRECATED_APIS = [    "Router.pushUrl""Router.replaceUrl""Router.back",    "@State 传对象给子组件""index.toString() as key",    "Preferences > 1KB""@Watch on @Prop nested",    "setInterval/setTimeout in component""console.log",]def evaluate_code(code: str, requirement: dict) -> dict:    """评估生成的代码:是否可运行、是否用了废弃API、逻辑错误数"""    accepted = True    deprecated_count = 0    logic_errors = 0    modifications_needed = 0    for api in DEPRECATED_APIS:        if api.split("(")[0in code:            deprecated_count += 1            accepted = False    # 简化评估:超过3处废弃API或2处逻辑错误则拒绝    if deprecated_count >= 3 or logic_errors >= 2:        accepted = False        modifications_needed = deprecated_count * 5 + logic_errors * 8    elif deprecated_count >= 1:        modifications_needed = deprecated_count * 3    return {        "req_id": requirement["id"],        "accepted": accepted,        "deprecated_apis": deprecated_count,        "logic_errors": logic_errors,        "modifications": modifications_needed,    }def run_test(strategy: str) -> list:    """模拟三种策略的测试结果"""    # 实际测试中,这里调用 Cursor API 生成代码并评估    # 以下是实测数据的结构化记录    results_file = f"results_{strategy}.json"    if os.path.exists(results_file):        with open(results_file) as f:            return json.load(f)    return []def generate_report(results_a, results_b, results_c):    """生成对比报告"""    report = {        "date": datetime.now().isoformat(),        "strategy_a": {            "acceptance_rate"sum(1 for r in results_a if r["accepted"]) / len(results_a),            "avg_modifications"sum(r["modifications"for r in results_a) / len(results_a),            "deprecated_total"sum(r["deprecated_apis"for r in results_a),            "logic_errors_total"sum(r["logic_errors"for r in results_a),        },        "strategy_b": {            "acceptance_rate"sum(1 for r in results_b if r["accepted"]) / len(results_b),            "avg_modifications"sum(r["modifications"for r in results_b) / len(results_b),            "deprecated_total"sum(r["deprecated_apis"for r in results_b),            "logic_errors_total"sum(r["logic_errors"for r in results_b),        },        "strategy_c": {            "acceptance_rate"sum(1 for r in results_c if r["accepted"]) / len(results_c),            "avg_modifications"sum(r["modifications"for r in results_c) / len(results_c),            "deprecated_total"sum(r["deprecated_apis"for r in results_c),            "logic_errors_total"sum(r["logic_errors"for r in results_c),        },    }    return reportif __name__ == "__main__":    print("运行三种策略测试...")    print(f"测试需求数: {len(REQUIREMENTS)}")    print(f"废弃API清单: {len(DEPRECATED_APIS)} 条")    # 实际使用时替换为真实的AI生成+评估流程    print("请参考 README 配置 Cursor API 后运行完整测试")

顺带一提,我做的 App 叫雷达鸭,鸿蒙版的 UI 页面大部分是 AI 写的,就是用禁令策略跑的,华为应用市场能搜到。

等鸿蒙 Next 正式版出来,希望 DevEco Code 能把"禁令思维"内置进去——不是光教 AI 该用什么,而是先告诉它别碰哪些坑。


关于作者:老三,10+ 年软件开发老兵,软件设计师 & 人工智能应用工程师,专注鸿蒙 ArkTS 北向开发和 Web 前端,闲了就在 CSDN 写点鸿蒙和 AI 的碎碎念。

本文遵循 MIT 协议,转载请注明出处。