arkts-rules

name	arkts-rules
verified_against	harmonyos-6.1.1-api24
description	HarmonyOS / ArkTS 严格语法规则。 **激活条件**（满足任一即激活）： - 用户在写 / 改 .ets 或 .ts 文件，且文件路径含 entry/ / .arkui / harmonyos / ohos - 用户在迁移 TypeScript 代码到 ArkTS - 用户问 arkts-no-* 编译错误 - 用户提到 @kit.* / @ohos.* / Stage 模型 / ArkUI 装饰器 **不激活**：纯 TypeScript / 浏览器 / Node.js 项目（即使语法相似）；React / Vue / 小程序代码。

ArkTS 严格规则

触发场景：用户要写或改 .ets / .ts 鸿蒙文件、迁移 TypeScript 代码、或编译报 arkts-no-*。

核心心智模型

ArkTS = TypeScript 的 AOT-friendly 严格子集 + ArkUI 装饰器扩展。 所有"运行时不可静态分析"的特性都被禁用，因为 ArkCompiler 要做 AOT 编译。先声明，后使用是唯一心智模型。

必须遵守的硬约束

类型系统

❌ any / unknown / var
❌ 对象字面量没有先声明 class/interface
❌ obj['key'] 动态索引（除非 obj 是 Map/Record）
❌ 索引签名 [k:string]: T
❌ 结构性类型（class A 和 class B 字段相同也不互通）
❌ 交叉类型 A & B / 条件类型 / 类表达式 / Symbol

语法

❌ 解构赋值 const {a,b} = obj
❌ function 表达式（用箭头函数）
❌ 私有字段 # 前缀（用 private 关键字）
❌ /regex/ 字面量（用 new RegExp）
❌ delete 操作符（设 null）
❌ 一元 + 转字符串（用 Number() / parseInt）
❌ for...in（用 for-of 或普通 for）
❌ 类字段未初始化（声明时或 constructor 必须赋值）

模块

✅ import { http } from '@kit.NetworkKit';        ← Kit 化路径，HarmonyOS 5+ 推荐
⚠️ import http from '@ohos.net.http';             ← 旧式，仍可编译
❌ npm 包：axios / lodash / moment 等              ← 鸿蒙生态不存在，用 OHPM 包替代

改写常见 TS 反模式

TypeScript 写法	ArkTS 改写
const o = { a: 1, b: 2 }	先 class O { a: number = 0; b: number = 0; } 再 const o: O = { a: 1, b: 2 }
Record<string, any>	Map<string, T>，T 为具体类型
obj['key']	改用 obj.key（点访问类字段）或 map.get('key')
const {a, b} = obj	const a = obj.a; const b = obj.b;
function f() {}	const f = (): void => {}
+'1'	Number('1') 或 parseInt('1', 10)
/foo/g	new RegExp('foo', 'g')
for (const k in o)	for (const k of Object.keys(o))
delete o.x	o.x = null;（字段类型需含 null）

验证流程（写完代码必跑）

ohpm install                            # 改了 oh-package.json5 才需要
hvigorw codeLinter                      # ArkTS 规则强校验
hvigorw assembleHap -p buildMode=debug  # 真编译验证

任何 arkts-no-* 错误码：在 01-language-arkts/02-typescript-to-arkts-migration.md 搜该编号。

当不确定 API 形态

不要凭训练数据写。ArkTS / ArkUI / Kit API 在 API 12 → 14 → 18 → 20 → 21 → 22 多次变化。

1. 先在 upstream-docs/openharmony-docs/zh-cn/application-dev/reference/ 搜对应 Kit
2. 找不到再上 developer.huawei.com
3. 仍不确定就告诉用户「我无法验证此 API 当前形态，建议你在 IDE 里 Ctrl+点进类型定义确认」

高频踩坑 · AI 必读

下面 5 条是真鸿蒙 app 实战中最常被 AI 写错的——不是语法层、是写代码时的"惯性盲区"：

1. Record<K,V> 字面量初始化也违反 arkts-no-untyped-obj-literals —— AI 容易认为"Record 已经声明类型了"就直接 : Record<string, X> = { k: v }。改 Map<K,V>.set() 或先 class。规则 ARKTS-RECORD。
2. 任何 await 行不在 try 块内 → codeLinter 报 "Function may throw exceptions" —— ArkTS 严格模式。规则 ARKTS-AWAIT-TRY。
3. picker.PhotoViewPicker / decodeWithStream 等 HarmonyOS 6 已弃用 —— AI 训练数据里多是旧版。规则 ARKTS-DEPRECATED-PICKER / ARKTS-DEPRECATED-DECODE。
4. ArkTS 不支持 union（如 string | object[]） —— OpenAI Vision 等 API 的 content 字段必须拆双字段 + 自定义序列化。规则 ARKTS-NO-UNION-CONTENT。详见 multimodal-llm。
5. @kit.AbilityKit 命名空间易混 —— Configuration 在 @kit.AbilityKit 顶层 export，不在 ConfigurationConstant.* 命名空间下。AI 常误写 ConfigurationConstant.Configuration → 编译器报 Namespace 'ConfigurationConstant' has no exported member 'Configuration'。不确定就 Ctrl+点进类型定义。详见 runtime-pitfalls § 九。

工程层装配陷阱（grep 扫不出来的）见 runtime-pitfalls。

抑制 scanner 误报（inline-suppress）

scanner 偶有误报或你已审过的特殊情形——不需要改规则，用注释抑制即可：

标记	写在	效果
// scan-ignore: <RULE-ID>	同行（行尾）或上一行	抑制该规则的本次命中
// scan-ignore: <RULE-ID-A>, <RULE-ID-B>	同上	一次抑制多条规则
// scan-ignore-line	仅同行（行尾）	抑制本行所有规则

⚠️ scan-ignore-line 字面是"忽略此行"，仅匹配同行——把它写在违规上一行不会抑制下一行。需要跨行抑制就用具名 scan-ignore: <RULE-ID>（命名注释一般写在被抑制行上方更清晰）。

例：

// scan-ignore: STATE-009              ← 上一行抑制（推荐用于 KV/DB API 调用）
this.prefs.delete('cached-token');

this.cache.set('k', 'v');  // scan-ignore: STATE-009     ← 行尾抑制也行

const next = JSON.parse(raw);  // scan-ignore-line       ← 抑制本行所有规则

被抑制的命中既不输出也不计数——属于真正的"逃生口"，不会让你的 exit code 假装通过。

引用稳定 ID（强制）

所有 ArkTS / 状态 / Kit 反模式都有稳定 ID——回答用户时必须引用。完整映射表：references/spec-quick-ref.md。

常用 ID：

• ARKTS-001..016 编译期语法（any / 解构 / for-in / delete 等）
• STATE-001..009 运行时状态（V1V2 混用 / 就地 mutation）
• KIT-001 PERF-001 SEC-001..007 COMPAT-001 各领域
• CSPRNG-001 Math.random() 在加密 / nonce / IV / signature 上下文（三档严重度：/security/ 或 /crypto/ 路径下 = High；文件含 cryptoFramework / nonce / aesGcm / huks / signKey / hmac 等关键字 = High；否则 Medium 提醒）。改用 cryptoFramework.createRandom().generateRandomSync(N) 或 HUKS

被钩子命中违规时，回复结构应是：引用 ID → 引用 references 中的"正确写法" → 不要另造一个看似对的版本。

ArkTS-Sta（use static 静态模式）· 只需知情

HDC 2026 前后官方在推进 ArkTS-Sta（静态类型模式）：文件首行 use static 导语、真静态类型系统、对象天然共享（不再需要 @Sendable）、Native 互操作走 ANI（替代 NAPI）。当前状态：演进中，生产不用。

• 本 skill 的全部规则针对动态 ArkTS（当前生产主线，.ets 默认形态）
• 看到首行 "use static" 的文件：那是另一套类型/并发/状态管理语义，不要把本仓 V1/V2 状态规则与 NAPI 惯例套上去；提示用户该特性未到生产推荐阶段
• 不要主动建议用户迁移到 ArkTS-Sta

进一步参考

• 完整 ID 映射 + 规范条款：references/spec-quick-ref.md
• 完整对照：01-language-arkts/01-arkts-vs-typescript.md
• 全部规则编号：01-language-arkts/02-typescript-to-arkts-migration.md
• 上游：upstream-docs/.../quick-start/arkts-migration-background.md
• 实战 case study：docs/case-studies/llm-chat-app.md —— 真实 LLM 对话 app 的 ArkTS 踩坑全记录（M3 Configuration 命名空间 / M5 union content / M6 await-try / M9 资源句柄 / M11 弃用 API 等）