我喜欢的 ZCod这些 Agent，怎么把鸿蒙应用写好

，.┏ (^ω^)=☞@.犭а①＋☆ā

11人浏览 · 2026-11-06 16:32:14

，.┏ (^ω^)=☞@.犭а①＋☆ā · 2026-11-06 16:32:14 发布

规则从哪来、怎么装进去、对方更新了怎么一直跟上

2026-11-06 · 鸿蒙开发 / AI 编码助手

用通用 AI 助手写 ArkTS，翻车方式几乎一模一样：它写出来的代码看着很像 TypeScript，然后 DevEco Studio 一片红。

不是模型不够聪明，是没人告诉它 ArkTS 的边界在哪。它会顺手写出解构赋值、无类型对象字面量、any、动态属性访问；它还会凭印象编 API——.bgColor()、Switch(...)、vp2px()。这些名字听起来都对，但前两个根本不存在，第三个已经废弃。

我后来把这几条拿去和规则原文对了一遍，发现它们不是公众号文章编的段子，而是白纸黑字写在 DevEco Code 的 Skill 里：

模型爱写	规则文件里的判定	出处
`.bgColor()`	应为 `.backgroundColor()`	`SKILL.md` § Fabricated modifiers
`Switch(...)`	应为 `Toggle({ type: ToggleType.Switch, isOn })`	`SKILL.md` § Hallucinated names
`vp2px()` / `px2vp()`	已废弃，改用 `display.getDefaultDisplaySync().densityPixels`	`SKILL.md` § Hallucinated names
`import { audio } from '@kit.MediaKit'`	kit 名错，`audio` 属 `@kit.AudioKit`	`SKILL.md` Top-5 traps

所以问题从来不是「换一个更强的模型」，而是规则有没有进到上下文里。

1. 结论先行：换 Agent，不用换钥匙

华为的 DevEco Code 之所以写鸿蒙代码一次编译通过率高，核心不是内置模型，而是它把 83 条 ArkTS linter 规则、高频陷阱表、防幻觉清单做成了一个规则库，强制在写每个 .ets 文件前过一遍。

但这里有个容易被忽略的事实：那套规则是 MIT 开源的 markdown，不绑定任何模型，也不绑定任何 Agent。它躺在一个公开 Git 仓库里，谁都能下载。也就是说，我喜欢的 ZCode、DeepSeek、Harm（以及 Claude Code、Cursor、Copilot……）照样能用同一套规则，只要解决三件事：

规则从哪拿（源头，而不是二手解读）
怎么装进这个 Agent（常驻 + 按需，别一股脑塞满上下文）
对方升级后怎么持续跟上（版本化 + 自动 diff）

2. 规则从哪来

2.1 先排除三个「看起来像、其实不是」的地方

地方	为什么不是
那篇公众号文章	二手解读，只列了 6 条示例，且会随版本过期
npm 主包 `@deveco/deveco-code` 的 tarball	实测只有 6 个文件（bin、postinstall、README、CHANGELOG…），不含规则；但它的 `CHANGELOG.md` 值得盯，会写「补充 ArkTS 导航路由规则」这类变更
平台包 `@deveco/deveco-code-windows-x64`	解压后 193 MB 单 exe，规则被编进二进制，读不出来

文章末尾其实给了线索：「本文基于对 DevEco Code（@deveco/deveco-code 0.1.12）本地安装包的规则库、工具链及官方文档的实际分析整理」。顺着这个版本号往下追就对了。

2.2 真正的源头

GitCode 开源仓库（MIT，免登录）
https://gitcode.com/openharmony-sig/deveco-code

文章对应版本 tag
refs/tags/v0.1.12  ->  4f6825973d45cdb304803dbadc291ee016b65626
发布日 2026-09-05，文章写于 2026-09-09

规则库路径
packages/opencode/resources/skills/arkts-grammar-standards/
├── SKILL.md                     # 入口：Top-5 陷阱、核心硬约束、组件 cookbook、防幻觉清单
└── references/
    ├── arkts-rules.md           # 83 条规则索引（Ref / Rule Tag / Severity / Migratable / Description）
    ├── arkui-structure-rules.md
    ├── kit-api-quick-ref.md
    ├── recipes-core.md / recipes-forms.md
    ├── ts-to-arkts-rewrites.md
    └── ui-quality-checklist.md

arkts-rules.md 第 37 行原话：83 rules. Severity: ERROR must be fixed; WARNING should be fixed. 后面就是那张 83 行的索引表，规则标签形如 arkts-no-any-unknown、arkts-no-untyped-obj-literals，和编译器报错一一对应——这一点很关键，意味着 报错信息可以直接反查规则。

最省事的拿法，一条命令：

curl -L -o arkts-rules.md \
  "https://raw.gitcode.com/openharmony-sig/deveco-code/raw/v0.1.12/packages/opencode/resources/skills/arkts-grammar-standards/references/arkts-rules.md"

raw.gitcode.com/openharmony-sig/deveco-code/raw/<ref>/<path> 免 token，把 v0.1.12 换成 v0.2.5 或 develop 就是对应版本。想自动发现路径，用 git clone --depth 1 --filter=blob:none --sparse 加 git ls-tree -r --name-only；GitCode 的 tree API 也能用，但默认每页只返回 20 条，必须 per_page=100&page=N 翻页。

另外三个官方补充源，适合用来交叉核对 API 而不是当规则库：华为开发者联盟博客《从 TypeScript 到 ArkTS：如何让 AI 写出能编译通过的鸿蒙代码》、ArkTS 编程规范、以及规则文件里反复引用的 TypeScript to ArkTS Migration Guide。

2.3 一手规则里最值钱的三样东西

83 条索引表：带严重级别和「能否机械改写」，可以直接生成检查清单。
防幻觉清单：SKILL.md 里专门列了不存在的修饰符和 API 名，并明确「AI 被明确告知这些名字不存在，而不是靠训练记忆撞运气」。kit-api-quick-ref.md 开头更直接：Any namespace member not shown here is unverified — look it up in the SDK .d.ts, never guess。
按需查表路由：SKILL.md 末尾有一张 Reference files (read on demand) 表——报错里出现 arkts-xxx 就读 arkts-rules.md，要调系统 kit 就读 kit-api-quick-ref.md，迁移 TS 就读 ts-to-arkts-rewrites.md。这本身就是一套分层加载设计，照搬即可。

顺带一个反直觉的点：规则文件里专门有一节 Legal constructs (do NOT over-restrict)，写明模板字符串、value as T、Record<K,V>、Partial<T> 都是合法的。网上很多「ArkTS 禁令清单」把这些也一起禁了，反而把模型捆死。照抄二手清单，比没有规则更糟。

3. 怎么把规则装进任意 Agent

3.1 三层结构

层	放什么	放在哪	token 策略
L1 常驻	10~20 条高频硬约束 + 防幻觉清单 + 「不许凭记忆编 API」	System Prompt / `AGENTS.md` / `CLAUDE.md` / `.cursorrules`	越短越好，控制在几百 token
L2 按需	83 条索引、cookbook、kit 速查、改写手册	`.agents/skills/arkts-grammar-standards/` 整个目录	用到才读，靠 `_index.md` 或 `SKILL.md` 的路由表定位
L3 验证	编译、静态检查、真机运行	Agent 的工具链 / 脚本 / CI	不占上下文，但决定规则是否真的生效

只做 L1 会漏，全塞进 L1 会「lost in the middle」——有第三方对比测试观察到，常驻指令超过约 1200 token 后，靠后的规则被明显忽略。所以分层不是洁癖，是刚需。

3.2 各 Agent 的落点

规则内容只有一份，变的只是入口文件名：

Agent	常驻规则入口	按需 Skill 入口
ZCode（智谱 GLM 系编辑器）	工作区 `AGENTS.md`	`.agents/skills/<name>/SKILL.md`
DeepSeek（网页 / API）	System Prompt / 自定义指令；把规则文件作为附件或检索知识库	无原生 Skill 目录，用「按索引读文件」的提示词模拟
Harm（鸿蒙向 Agent，如 DevEco Code / CodeGenie 类）	IDE 内 Rules	`.deveco/skills/`，同时兼容 `.agents/skills/`
Claude Code	`CLAUDE.md`、`.claude/rules/*.md`	`.claude/skills/`
Cursor	`AGENTS.md`、`.cursor/rules/*.mdc`	`.cursor/skills/`
GitHub Copilot	`.github/copilot-instructions.md`	`.agents/skills/`

（各工具的入口名以它当前文档为准：DevEco Code 的 .deveco/skills/ 见社区文档，源码侧可确认的是发现规则为标准 **/SKILL.md。）

一个实用做法：把规则放在 .agents/ 作为唯一真源，其余入口用软链指过去。要注意 Windows 上 Git 默认把软链写成文本文件，团队里有人用 Windows 得先开 core.symlinks=true；另外 Cursor 的规则文件必须是 .mdc，Claude Code 只认 .md，同一份内容需要不同扩展名的链接。

好消息是 DevEco Code 的 Skill 发现逻辑就是标准 **/SKILL.md（源码里 glob("{*.md,**/SKILL.md}")），frontmatter 也只有 name / description。把整个 arkts-grammar-standards/ 目录拷进 .agents/skills/，ZCode、Codex、Claude Code、DevEco Code 都能直接认。

3.3 可直接复制的最小常驻规则

你正在编写 HarmonyOS / ArkTS 代码（.ets），ArkTS 是 TypeScript 的严格子集。
写任何 .ets 文件前，先读 .agents/skills/arkts-grammar-standards/SKILL.md 的
「Top-5 traps」与「Reference files」表，按任务特征读取对应 references 文件。

硬约束：
- 禁止 any / unknown；所有变量、参数、返回值显式标注类型
- 对象字面量在任何位置都必须有类型上下文（interface / class / Record）
- 禁止解构赋值，逐字段赋值；禁止动态属性访问 obj[key]
- 禁止结构化类型匹配，类型兼容必须显式 extends / implements
- 跨文件类型必须 export / import 齐全；@kit.* 命名空间必须查表核对
- async 函数必须显式标注 Promise<T>；可空值用 ?. / ?? / if 窄化
- 禁止凭记忆编造组件名、修饰符、枚举成员、@kit.* API；
  未在本项目规则文件中出现的名字一律视为不存在，去 SDK .d.ts 查证
- 已知不存在或已废弃：.bgColor()、Switch(...)、vp2px()/px2vp()、
  Preferences.getString()、ScrollEdgeEffect

注意：模板字符串、value as T、Record<K,V>、Partial<T>、箭头函数、
for...of、Map/Set 都是合法的，不要防御性禁用。

流程：每写完一个 .ets 文件立刻做静态检查，任务结束前必须完整编译通过；
编译失败不得交付。构建重试上限 10 次，超限停下汇报根因。

3.4 光有规则不够，要有闭环

DevEco Code 的做法值得照抄：写前加载规则 → arkts_check（新版为 devecocli check arkts）秒级静态检查 → build_project / devecocli build 完整编译 → start_app 部署 → 可选 verify_ui 截图验收。给构建和 UI 验证设重试配额，避免 Agent 无限循环烧时间。

对通用 Agent 而言，哪怕没有这些专用工具，也至少把「编译通过才允许回复完成」写进常驻规则，并让它调用项目里的 hvigor / hdc 脚本。没有验证的规则只是建议，有验证的规则才是约束。

4. 对方更新了怎么办

4.1 规则是会动的，而且已经动过

ref	commit	形态	规则文件数
`v0.1.12`（文章版本）	`4f68259`	`arkts-grammar-standards/`，`arkts-rules.md` 单表声明 83 条	53
`v0.2.5`（当前 npm latest）	`b56e1b8`	改名为 `hmos-arkui-develop-skill/`	73
`develop`（2026-11-05）	`e953444`	规则拆进 `references/quick-rules/00~14` + `_index.md`，另加 `quick-apis/01~18`	87

注意：83 条规则并没有被删掉——新版 quick-rules/_index.md 里 00-arkts-syntax 的描述仍是「83 条 arkts-* 规则索引、TS→ArkTS 改写表、空安全、export/import、类型注解」。只是从一张大表变成了编码前 / 编码中 / 检视时分阶段查的索引结构。

所以千万别把 arkts-grammar-standards 这个路径写死在脚本里，一升级就 404。

4.2 三层更新信号

信号	来源	说明
版本号	npm `dist-tags`（`latest` / `stable` / `daily`）	最快，`daily` 几乎每天变
源码指针	`git ls-remote` 取 tag / develop 的 commit sha	精确对应某一版规则
内容指纹	每个 `.md` 的 sha256	最可靠，能发现同版本号下改内容

4.3 一键复抓

我在工作区放了一个无依赖的 Node 脚本 sync-rules.mjs，逻辑是：读 npm dist-tags → git ls-remote 比对 commit → 用 git ls-tree 动态枚举 resources/skills/**/*.md（自动适应改名和拆分）→ 走 raw 下载 → 逐文件 hash 比对 → 有变更就把旧版归档到 history/<ref>/<sha7>/ 并生成中文差异报告。

node sync-rules.mjs                 # 同步 develop + latest 对应 tag + 文章快照
node sync-rules.mjs --check        # 只探测，有更新退出码 2，适合挂计划任务 / CI
node sync-rules.mjs --ref v0.1.12  # 抓文章对应的历史版本
node sync-rules.mjs --all          # 连 stable / daily 一起抓

工程上再补一步：把 snapshots/ 提交进自己的仓库，规则变更走 PR 评审；--check 挂到定时任务，有更新再跑全量同步。这样规则就和依赖一样可审计、可回滚。

5. 几个真踩过的坑

别拿整页 HTML 判重：微信公众号文章发布后可修改、也可能删除，要留快照；但整页 HTML 每次返回都带动态 token，直接 hash 会天天误报「有更新」。已改成只用 #js_content 提取后的正文做指纹。
别把 193 MB 二进制当源：规则只在 GitCode 源码里，npm 主包只是壳。
tree API 默认 20 条：不翻页会以为仓库里没有规则目录。
规则不是越多越好：83 条全塞进 System Prompt，效果不如 15 条常驻 + 一张按需查表路由。
别禁掉合法构造：Legal constructs 那一节是防「过度约束」的，二手清单常常缺这一块。
版本要对得上：文章讲的是 0.1.12，当前 npm 已是 latest=0.2.5 / stable=0.3.0-stable。引用规则时带上 ref，否则半年后无法复现。

6. 来源清单

用途	地址
规则源码（一手）	`https://gitcode.com/openharmony-sig/deveco-code`
83 条规则直链	`https://raw.gitcode.com/openharmony-sig/deveco-code/raw/v0.1.12/packages/opencode/resources/skills/arkts-grammar-standards/references/arkts-rules.md`
版本 / 发布时间 / CHANGELOG	`https://registry.npmjs.org/@deveco%2Fdeveco-code`
目录树 API	`https://gitcode.com/api/v5/repos/openharmony-sig/deveco-code/git/trees/develop?recursive=1&per_page=100&page=1`
官方编码规范	`https://device.harmonyos.com/cn/docs/apiref/harmonyos-guides/arkts-coding-style-guide`
线索文章	`https://mp.weixin.qq.com/s/9DxX711I0vMs2VK67NVeOg`
本地抓取方案	同目录 `../来源与抓取说明.md`、`../sync-rules.mjs`、`../reports/latest.md`

注：文中 ZCode 指智谱 GLM 系编辑器，Harm 泛指鸿蒙向 Agent（DevEco Code / CodeGenie 一类）。名字不重要——只要你的 Agent 能读 System Prompt / Rules / Skill，把上表里的入口换成它认的那个文件名即可，规则正文一份就够。

一句话收尾：模型决定代码写得多快，规则决定它能不能编译过。 而规则不该靠收藏一篇公众号文章，应该像依赖一样，有源头、有版本、有 diff、能回滚。

人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

昇腾平台推理调看这篇就够了-调优思路总览

部署成推理服务」中间的调优，本质是在正确性/精度守住的前提下，沿"模型压缩 → 图与算子融合 → 调度与 KV 管理 → 并行与通信 → 显存 → 服务化调度"逐层找瓶颈、逐层调，并靠 AISBench 压测 + msProf 系列 Profiling 把瓶颈测出来，而不是盲目改参数。接入昇腾知识图谱。

人工智能6S服务平台

ReAct 、Plan-and-Solve、Reflection：三种 Agent 范式的原理与代码

一句话让Agent变成昇腾专家，昇腾任务轻松搞定。评测入口：请按这个开源仓接入昇腾图谱：刚开始接触 Agent，想把 ReAct、Plan-and-Solve、Reflection 这三套循环搞清楚：能读懂 Python 的函数和字典，知道 LLM 的输入输出是什么；不需要 GPU，也不需要 API key：示例在 Python 3.13 上运行；模型调用用占位函数替代，接真模型只需换掉这一个函数

人工智能6S服务平台

国产操作系统推荐 2026：个人桌面与办公信创两条线，六款主流系统如何排位

国产操作系统在 2026 年跨过了规模化门槛，进入了体验竞争阶段。统信软件公开披露，统信 UOS 生态适配总数突破1000 万，其中硬件适配82 万以上、软件适配920 万以上、适配厂商1.5 万家以上；deepin 社区全球用户规模达800 万以上，累计下载量突破8000 万次，海外用户占比超过37%；鸿蒙电脑自 2025 年 6 月首批开售，到 2026 年 10 月累计发货量突破100 万台