@deveco-test/deveco-code 1.0.2 → 1.0.4

package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/18-error-code.md

@@ -0,0 +1,24 @@
+# 18. 错误码速查
+
+| 错误码 | 说明 | 相关章节 |
+|--------|------|---------|
+| **100003** | Router 页面栈超过 32 页 | [08-navigation](08-navigation.md) |
+| **100005** | Navigation 跳转未注册 builder 函数的页面 | [08-navigation](08-navigation.md) |
+| **100006** | Navigation 跳转未包含 NavDestination 的页面 | [08-navigation](08-navigation.md) |
+| **100021** | 声明式 FrameNode 不允许修改（设属性、增删子节点、绑定控制器） | [11-extension](11-extension.md) |
+| **10505001** | 成员属性名与 CustomComponent 链式方法/通用属性重名；属性不存在；NavDestination 错用 titleMode 等 | [03-component](03-component.md)、[07-attribute-params](07-attribute-params.md) |
+| **10605038** | 无类型对象字面量（arkts-no-untyped-obj-literals） | [00-arkts-syntax](00-arkts-syntax.md) |
+| **10605040** | 内联对象字面量作类型（arkts-no-obj-literals-as-types） | [00-arkts-syntax](00-arkts-syntax.md) |
+| **106203** | 对未挂载节点执行操作 | [11-extension](11-extension.md) |
+| **10905202** | Button('label') 与 children 同时传入 | [04-build](04-build.md) |
+| **130000** | addMonitor/clearMonitor 目标必须是 @ObservedV2 class 或 @ComponentV2 实例 | [05-state](05-state.md) |
+| **130002** | addMonitor/clearMonitor 回调必须为命名函数 | [05-state](05-state.md) |
+| **140109** | @Builder 内修改入参（API 23+） | [05-state](05-state.md) |
+| **arkts-no-decl-merging** | 跨文件顶层 interface/class 重名 | [03-component](03-component.md) |
+| **arkts-no-destruct-decls** | 禁止解构声明 | [00-arkts-syntax](00-arkts-syntax.md) |
+| **arkts-no-any-unknown** | 禁止 any/unknown | [00-arkts-syntax](00-arkts-syntax.md) |
+| **arkts-no-ctor-prop-decls** | 禁止构造参数属性 | [00-arkts-syntax](00-arkts-syntax.md) |
+| **arkts-no-func-expressions** | 禁止函数表达式（用箭头函数） | [00-arkts-syntax](00-arkts-syntax.md) |
+| **arkts-no-nested-funcs** | @Extend/@Styles 内嵌套函数定义 | [10-style](10-style.md)、[00-arkts-syntax](00-arkts-syntax.md) |
+| **arkts-no-untyped-obj-literals** | 无类型对象字面量 | [00-arkts-syntax](00-arkts-syntax.md) |
+| **arkts-no-spread** | 禁止对象展开 | [00-arkts-syntax](00-arkts-syntax.md) |

package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-apis/_index.md

@@ -0,0 +1,75 @@
+# ArkUI API 参数速查索引
+
+> 各分类独立文件，按需读取。每个组件以"卡片"形式呈现，包含构造签名、参数表、属性方法表和事件表。
+
+## 检索方式（避免整读大文件）
+
+**查具体组件 API**（Row / List / Text / Navigation 等）：
+- **大文件**（01-layout 24KB / 02-basic 28KB）：在「组件索引」查组件所在文件，再 `Grep "^### 组件名" <文件> -A 45 -n` 取卡片（卡片 30–50 行）。**勿整读**，整读只为一张卡片浪费 10×+ token。
+- **小文件**（<5KB，如 03/04/05/07/11/12）：直接 Read 整个分类文件即可，比走索引更省。
+- **已知组件所在文件**：直接 `Grep "^### 组件名" <文件> -A 45 -n` 取卡片，可跳过本索引。
+
+**查主题 / 枚举 / 资源名**（动画 / 手势 / 装饰器 / 枚举 / sys.symbol）：
+- 08/09/10/14/16 文件较小（<5KB），直接 Read 或 Grep 主题词
+- 17-resources（50KB sys.symbol / sys.color 名称表）：`Grep "图标名或颜色名" 17-resources.md` 定位，勿整读
+
+## 分类文件
+
+| 文件 | 分类 | 大小 |
+|------|------|------|
+| [01-layout.md](01-layout.md) | 1. 布局容器 | 24KB |
+| [02-basic-components.md](02-basic-components.md) | 2. 基础组件 | 28KB |
+| [03-data-display.md](03-data-display.md) | 3. 数据展示组件 | 3KB |
+| [04-selectors.md](04-selectors.md) | 4. 选择器组件 | 2KB |
+| [05-media.md](05-media.md) | 5. 媒体与绘图组件 | 3KB |
+| [06-advanced.md](06-advanced.md) | 6. 高级/组合组件 | 2KB |
+| [07-security.md](07-security.md) | 7. 安全组件 | <1KB |
+| [08-state-decorators.md](08-state-decorators.md) | 8. 状态管理装饰器 | 5KB |
+| [09-animation.md](09-animation.md) | 9. 动画 API | 5KB |
+| [10-gesture.md](10-gesture.md) | 10. 手势与事件 | 3KB |
+| [11-dialog-menu.md](11-dialog-menu.md) | 11. 弹窗/菜单/模态 | 5KB |
+| [12-navigation.md](12-navigation.md) | 12. 导航与路由 | 3KB |
+| [13-rendering.md](13-rendering.md) | 13. 渲染控制 | <1KB |
+| [14-extension.md](14-extension.md) | 14. 自定义扩展 | 1KB |
+| [15-theme-style.md](15-theme-style.md) | 15. 主题与样式 | <1KB |
+| [16-enums.md](16-enums.md) | 16. 枚举类型速查 | 4KB |
+| [17-resources.md](17-resources.md) | 17. 系统资源名称（sys.symbol / sys.color） | 50KB |
+
+## 组件索引（按组件名定位卡片所在文件）
+
+> 用 `Grep "^### 组件名" <文件> -A 45 -n` 取卡片。
+
+**01-layout.md** — 布局容器
+Row / Column / Flex / Stack / List / ListItem / ListItemGroup / Grid / GridRow / GridCol / WaterFlow / Scroll / Tabs / TabContent / Swiper / RelativeContainer（含核心用法） / SideBarContainer / Panel / Refresh / Badge / Counter / AlphabetIndexer
+
+**02-basic-components.md** — 基础组件
+Text / Span / ImageSpan / SymbolSpan·SymbolGlyph / TextInput / TextArea / Button / Image / Slider / Toggle / Radio / Checkbox / CheckboxGroup / Progress / Rating / LoadingProgress / Search / Select
+
+**03-data-display.md** — 数据展示
+Gauge / DataPanel / QRCode / CalendarPicker·TextClock·TextTimer
+
+**04-selectors.md** — 选择器
+DatePicker / TimePicker / TextPicker / PatternLock
+
+**05-media.md** — 媒体与绘图
+Video / Canvas·Shape
+
+**07-security.md** — 安全
+SaveButton / PasteButton
+
+**11-dialog-menu.md** — 弹窗/菜单/模态
+弹窗 API / CustomDialogController / 菜单 / Popup / 模态
+
+**12-navigation.md** — 导航与路由
+Navigation / NavPathStack / NavDestination / Router
+
+## 主题类文件（按主题词检索，无单组件卡片）
+
+| 文件 | 主题 |
+|------|------|
+| 08-state-decorators.md | V1/V2 装饰器、全局状态 API |
+| 09-animation.md | 属性动画 / 动画曲线 / 转场动画 / TransitionEffect / PageTransition / 帧动画 |
+| 10-gesture.md | 基础手势 / 组合手势 / 手势绑定 / 通用事件 / 拖拽事件 |
+| 14-extension.md | Modifier 系列 / 自定义节点 |
+| 16-enums.md | 布局 / 组件 / 手势 / 动画 / 效果 枚举 |
+| 17-resources.md | sys.symbol 各类图标 / sys.color 128 色（Grep 名称定位） |

package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/00-arkts-syntax.md

@@ -0,0 +1,229 @@
+# 0. ArkTS 语法约束（arkts-* 规则）
+
+> ArkTS 是 TypeScript 的静态子集，不少 TS 习惯写法在 ArkTS 会编译报错。本节按官方 `arkts-*` 规则标签组织，标签与编译器/linter 报错一一对应。**写任何 .ets 前先扫本文件，尤其 top traps（实测高频）。**
+>
+> 定位：与 01-import 至 20-particle 的 **ArkUI 组件/状态/导航约束** 正交，本节专注 **ArkTS 语言级语法规则**。
+
+## ⚠Top traps（实测高频，生成前必扫）
+
+| # | 陷阱 | ❌ 错误 | ✅ 正确 |
+|---|------|---------|--------|
+| 1 | 解构 | `const { a, b } = obj` | `const a = obj.a; const b = obj.b;` |
+| 2 | 无类型对象字面量 | `const cfg = { timeout: 30 }` | `const cfg: Config = { timeout: 30 }`（先声明 `interface Config`） |
+| 3 | 原型/结构类型 | `X.prototype.fn = ...` 或传结构匹配对象 | 在 class 内声明方法；用 `extends`/`implements` 做类型兼容 |
+| 4 | 遗漏 export/import | 一个文件定义 `class CartItem`，另一文件直接用未导出 | 声明处加 `export`；使用处加 `import { CartItem } from '...'` |
+| 5 | kit 命名空间错 | `import { audio } from '@kit.MediaKit'` | `audio` → `@kit.AudioKit`；`media` → `@kit.MediaKit` |
+| 6 | enum 反射方法 | `HeavenlyStem.values()` / `Color.keys()` / `MyEnum.entries()` | ArkTS 枚举无 `.values()/.keys()/.entries()`，声明显式数组迭代 |
+
+### 三个最高频错误的完整正例
+
+**① 遗漏 export/import → `Cannot find name 'X'`**（单类最常犯）
+
+```ets
+// ❌ model 文件忘了 export；页面文件忘了 import
+class CartItem { id: string = '' }          // CartItem.ets — no export
+struct CartPage { item: CartItem = new CartItem() }  // Cannot find name 'CartItem'
+
+// ✅ 声明处 export，使用处文件顶部 import
+export class CartItem { id: string = '' }   // CartItem.ets
+import { CartItem } from '../model/CartItem' // CartPage.ets — FIRST line
+// 路由表 / @Builder 命名页面 struct 时必须逐个 import——NavPathStack 不会使其全局可见：
+import { HomePage } from './HomePage'
+import { DetailPage } from './DetailPage'
+```
+
+**② 无类型上下文的对象字面量 → `arkts-no-untyped-obj-literals`**（类型不会渗入嵌套字面量或调用实参）
+
+```ets
+// ❌ 无类型上下文，在调用实参/数组元素等任何位置都失败
+const cfg = { timeout: 30 }
+foo({ id: 1, name: 'a' })
+const rows = [{ x: 1 }, { x: 2 }]
+
+// ✅ 先声明 interface，在字面量处标注
+interface Config { timeout: number }
+const cfg: Config = { timeout: 30 }
+foo({ id: 1, name: 'a' } as ItemArg)         // 标注实参
+const rows: Point[] = [{ x: 1 }, { x: 2 }]   // 标注数组而非变量
+// Record 字面量需带引号 key：
+const m: Record<string, number> = { 'a': 1 }
+```
+
+**③ `enum.values()` 或臆造枚举成员 → `Property 'X' does not exist on type 'typeof Enum'`**
+
+```ets
+// ❌ ArkTS 枚举无反射；臆造的框架枚举成员也不存在
+for (const s of HeavenlyStem.values()) {}  // .values() 不存在
+animation({ curve: Curve.Spring })         // Curve 无 'Spring'
+
+// ✅ 声明显式成员数组迭代；只从 quick-apis/16-enums.md 取真实成员
+const ALL_STEMS: HeavenlyStem[] = [HeavenlyStem.JIA, HeavenlyStem.YI]
+for (const s of ALL_STEMS) {}
+animation({ curve: Curve.Smooth })         // 真实成员
+```
+
+---
+
+## TypeScript → ArkTS 改写表（tag 与报错一一对应）
+
+| TS 写法 | ArkTS 改写 | 规则标签 |
+|---------|-----------|---------|
+| `var x = 1` | `let x = 1` / `const x = 1` | `arkts-no-var` |
+| `let x: any` / `unknown` | 明确类型；未定时用 `Object` 或联合类型 | `arkts-no-any-unknown` |
+| `const { a, b } = obj` | `const a = obj.a; const b = obj.b` | `arkts-no-destruct-decls` |
+| `function f({ a }: P)` | `function f(p: P)` 后用 `p.a` | `arkts-no-destruct-params` |
+| `[x, y] = [y, x]` | 用临时变量逐一赋值 | `arkts-no-destruct-assignment` |
+| `const fn = function() {}` | `const fn = () => {}` | `arkts-no-func-expressions` |
+| `const id = <T>(v: T): T => v` | `function id<T>(v: T): T { return v }` | `arkts-no-generic-lambdas` |
+| 函数体内 `function inner() {}` | `const inner = (): void => {}` 或提升为类方法 | `arkts-no-nested-funcs` |
+| `<string>value` | `value as string` | `arkts-as-casts` |
+| `obj as const` | 显式声明常量类型 | `arkts-no-as-const` |
+| `type T = { x: number }` | `interface T { x: number }` | `arkts-no-obj-literals-as-types` |
+| `f(p: { x: number })` | 定义具名 interface 作参数类型 | `arkts-no-obj-literals-as-types` |
+| `interface I { [key: string]: T }` | `Record<string, T>` | `arkts-no-indexed-signatures` |
+| `type C = A & B` | `interface C extends A, B {}` | `arkts-no-intersection-types` |
+| `type N = T['prop']` | 直接使用目标类型 | `arkts-no-aliases-by-index` |
+| `obj['key']`（非 Record） | `obj.key`；动态 key 用 Record | `arkts-no-props-by-index` |
+| `const o = { a: 1 }`（无类型） | `const o: MyIface = { a: 1 }` 或 Record | `arkts-no-untyped-obj-literals` |
+| `Pick`/`Omit`/`ReturnType` 等 | 手写具名 interface | `arkts-no-utility-types` |
+| `delete obj.x` | 字段加 `\| undefined`，`obj.x = undefined` | `arkts-no-delete` |
+| `'key' in obj` | `obj.key !== undefined` 或 `instanceof` | `arkts-no-in` |
+| `for (const k in obj)` | `for...of` / `Map` / 已知 key 列表 | `arkts-no-for-in` |
+| `v is Cat`（类型守卫） | `instanceof` 检查 + `as` 收窄 | `arkts-no-is` |
+| `{ ...obj1, ...obj2 }` | 构造新对象，显式赋值字段 | `arkts-no-spread` |
+| `throw 'msg'` | `throw new Error('msg')` | `arkts-limited-throw` |
+| `catch (e: Error)` | `catch (e)` 后 `const err = e as Error` | `arkts-no-types-in-catch` |
+| `constructor(public x: number) {}` | 在 class 体内声明字段，构造中赋值 | `arkts-no-ctor-prop-decls` |
+| `#privateField` | `private privateField` | `arkts-no-private-identifiers` |
+| `class D implements Base`（Base 是类） | `extends Base`，或抽 interface | `arkts-implements-only-iface` |
+| `function* gen() { yield }` | 返回数组/迭代器类，或改普通函数 | `arkts-no-generators` |
+| `fn.bind(this)` | 捕获 this 的箭头函数 | `arkts-no-func-bind` |
+| `/pattern/g` | `new RegExp("pattern", "g")` | `arkts-no-regexp-literals` |
+| `Object.assign(t, s)` | 显式赋值字段或用构造器 | `arkts-limited-stdlib` |
+| `obj.hasOwnProperty('k')` | `obj.k !== undefined` | `arkts-limited-stdlib` |
+| `globalThis.x` | 显式导出单例 / AppStorage | `arkts-no-globalthis` |
+| `// @ts-ignore` | 修复底层类型错误；抑制被禁 | `arkts-strict-typing-required` |
+| `import type { T }` | `import { T }` | `arkts-no-special-imports` |
+| `import './polyfill'` | 删除；显式 import 所需符号 | `arkts-no-side-effects-imports` |
+| `import x = require('m')` | `import x from 'm'` | `arkts-no-require` |
+| `export = X` | `export default X` | `arkts-no-export-assignment` |
+| `router.getParams() as MyIface` | interface 不能实例化，用 `as` 转换；构造用 class | TS2693 |
+
+---
+
+## 核心硬约束（未标 WARNING 均为 ERROR 级）
+
+### Types
+| 规则 | 说明 |
+|------|------|
+| 禁止 `any`/`unknown` | 含 `as unknown as T` 双重断言；用具体类型、`Object`、联合类型 |
+| 类型名作用域内唯一 | 不复用 imported 类型名作本地 struct/class 名（`arkts-unique-names`） |
+| 无结构类型 | 需 `extends`/`implements`（`arkts-no-structural-typing`） |
+| 对象字面量需类型上下文 | 含调用实参、回调返回；外层类型不渗入嵌套 |
+| Record 字面量需带引号 key | `{ 'k': v }` 非 `{ k: v }` |
+| 类类型对象字面量列全部字段 | class 默认值不使字段可选；用 `static of()` 工厂 |
+| 无内联对象类型 | 用具名 interface（`arkts-no-obj-literals-as-types`） |
+| 无交叉类型 `A & B` | 用接口继承（`arkts-no-intersection-types`） |
+| 无索引签名 | 用 `Record<K,V>`（`arkts-no-indexed-signatures`） |
+| 工具类型仅 Partial/Required/Readonly/Record | 其余手写（`arkts-no-utility-types`） |
+| 显式标注泛型调用和返回类型 | `arkts-no-inferred-generic-params` / `arkts-no-implicit-return-types` |
+| **enum 无反射方法** | `.values()/.keys()/.entries()` 不存在；用显式成员数组 |
+| **禁止声明合并** | 类/接口分开定义，同类型名不能在多个文件顶层声明（`arkts-no-decl-merging`） |
+| **对象字面量必须补齐全部必填字段** | 字段类型对齐；可选字段才允许缺省，声明时标 `?` |
+
+### Null safety（检查错误最大来源）
+| 规则 | 说明 |
+|------|------|
+| 可能 undefined 的值必须收窄 | `?.`、`?? fallback`、`if (x !== undefined)` |
+| `T \| undefined` 不能赋给 `T` | **含函数实参**：`foo(x)` 中 x 为 `T \| undefined` 不能传给 `param: T`，传参前 `?? defaultValue` 或 if 收窄 |
+| 空状态组件用 `T \| undefined` 或真实初始值 | 不用非空断言 `!` |
+| 优先 `undefined` 而非 `null` | 外部 null 用 `?? undefined` 转换 |
+
+### @Link 绑定约束
+| 规则 | 说明 |
+|------|------|
+| **@Link 源必须是 @State** | 传给子组件 `@Link` 的父属性必须是 `@State`/`@Prop` 等装饰变量，不能是 `private`/普通属性 |
+| **@Link 传值用 `this.`** | `Child({ aLink: this.aState })`（推荐）；`$aState` 是 API9 前旧写法，不推荐 |
+| **@Prop 传值** | 见 [05-state](05-state.md) @Prop 节：本地有初始化则可选（同 @State），无则必选；支持父组件常规变量但只做数值初始化、不触发刷新 |
+
+```ets
+// ❌ WRONG — 普通属性传 @Link
+struct Parent {
+  private count: number = 0
+  build() {
+    Child({ count: this.count })  // Error: regular property cannot be assigned to @Link
+  }
+}
+
+// ✅ RIGHT — @State 才能传 @Link
+struct Parent {
+  @State count: number = 0
+  build() {
+    Child({ count: this.count })
+  }
+}
+```
+
+### Functions and classes
+| 规则 | 说明 |
+|------|------|
+| 不用 `function(){}` 作值 | 用箭头函数（`arkts-no-func-expressions`） |
+| 无嵌套函数声明 | `arkts-no-nested-funcs` |
+| async 方法必须显式标注 `Promise<T>` | 省略报 error；无返回值写 `Promise<void>` |
+| 独立/static 方法无 `this` | static 成员用类名访问（`arkts-no-standalone-this`） |
+| 无构造参数属性 | `arkts-no-ctor-prop-decls` |
+| 同作用域不允许同名函数声明 | 无函数重载，每函数名只有一个实现 |
+| 无 `#` 私有字段 | 用 `private`（`arkts-no-private-identifiers`） |
+| `implements` 仅接口 | 接口不能 extends 类 |
+| 无 generator/`yield`、类表达式、`Function.bind` | |
+
+### Exports and imports（"Cannot find name" / "not exported" 高频来源）
+| 规则 | 说明 |
+|------|------|
+| 跨文件使用的类型必须 `export` | 忘记 export 报 `Module '...' declares 'X' locally, but it is not exported` |
+| 自定义类型必须显式 `import` | `Cannot find name 'X'` 几乎总是缺 import |
+| "No overload matches this call" = 实参类型/数量错 | 常见：传错枚举（如 `EdgeEffect.Spring` 处传 `ScrollAlign.Start`）、给类型化枚举传 string、回调签名错 |
+
+> kit 归属和速查表见 [01-import](01-import.md)。
+
+### Statements and expressions
+| 规则 | 说明 |
+|------|------|
+| 无任何解构 | 声明/赋值/参数（`arkts-no-destruct-*`） |
+| import 必须在文件顶部 | 其他语句之前（`arkts-no-misplaced-imports`） |
+| 无 `delete`、`in`、`for...in`、`with` | |
+| 非 Record 无索引访问 `obj['k']` | 用点访问（`arkts-no-props-by-index`） |
+| `throw` 只抛 Error+子类 | `catch (e)` 无类型注解；系统 API 错误用 `BusinessError` |
+| 无 `is` 类型守卫 | 用 `instanceof` + `as` |
+| 对象展开受限 | 数组展开 OK（`arkts-no-spread`） |
+| 无正则字面量 | 用 `new RegExp()`（`arkts-no-regexp-literals`） |
+| 无 `@ts-ignore` | `arkts-strict-typing-required` |
+| **JSON.parse 收窄模式** | 先 `as` 转换到原始类型，再逐字段校验赋值到严格类型，不直接使用 `as` 后的对象 |
+
+```ts
+// JSON.parse 收窄 — 不要直接信任 parsed 结果
+interface TaskRaw { id?: number; title?: string }
+const raw = JSON.parse(text) as TaskRaw
+const task: Task = { id: raw.id ?? 0, title: raw.title ?? '' }
+```
+
+### Standard library
+- 禁用：`eval`、`Object.assign/create/freeze/defineProperty`、`Reflect`/`Proxy`、`Symbol()`（除 `.iterator`）、`globalThis`
+- 无 `import type`、副作用导入、`require`、`export =`
+
+### 模板字符串注意
+> **注意**：`restrictions.md` 声称模板字符串不支持，但 `arkts-rules.md` "Explicitly allowed constructs" 明确 **模板字符串合法**（`Text(\`${this.msg}\`)` 是惯用写法）。以 `arkts-rules.md` 为准——模板字符串、`value as T`、`Record<K,V>`、箭头函数均合法，不要防御性改写。
+
+---
+
+## 显式允许的构造（不要过度限制）
+
+模板字面量、`as T` 断言、`Record<K,V>` + 索引访问、`Partial<T>`/`Required<T>`/`Readonly<T>`、箭头函数、`async/await`、泛型类/接口/函数、数组展开 `[...a]`、表达式上下文 `typeof x`、`new RegExp()`、联合类型/类型别名、`for...of`/`Map`/`Set`——**全部合法，正常使用**。**例外：`@Component`（V1）struct 内的 getter accessor 会被编译转换丢弃，禁用，改用普通成员方法**（`@ComponentV2` 不受此限）。
+
+## 参考
+
+- 错误码速查见 [18-error-code](../quick-apis/18-error-code.md)
+- 空安全回调场景高发错误见 [09-attribute-params](07-attribute-params.md) 空安全节
+- kit 归属和速查表见 [01-import](01-import.md)
+- 对象字面量类型约束见 [10-type-annotation](00-arkts-syntax.md)
+- 命名冲突（struct 名 ≠ imported 类型名、跨文件重名）见 [03-component](03-component.md)

package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/01-import.md

@@ -0,0 +1,116 @@
+# 1. 模块导入（import）约束
+
+## 规则
+
+| 规则 | 说明 |
+|------|------|
+| **禁止使用 `@ohos.*` 路径导入** | 旧版导入路径，**必须用 `@kit.*` 替代**。`import router from '@ohos.router'` → `import { router } from '@kit.ArkUI'` |
+| **禁止凭记忆编造 import** | 模块路径和导出符号必须来自检索结果/速查表，不得猜测 |
+| **禁止遗漏必要的 import** | 代码中使用的外部类型/函数/枚举必须有对应 import 声明 |
+| **禁止 import 未使用的模块** | 导入了但未使用的模块必须删除 |
+| **禁止从错误 kit 导入** | 每个 API 只属于一个 kit，不能从错误的 kit 导入（参考下方速查表） |
+
+## Kit 导入速查表
+
+### @kit.ArkUI（UI 开发核心 kit）
+
+```ts
+import {
+  UIContext, window, BuilderNode, FrameNode, NodeController,
+  ComponentContent, NodeContent, NodeRenderState,
+  LengthMetrics, ColorMetrics, matrix4, curves,
+  router, PromptAction, ImageModifier, KeyboardAvoidMode,
+  Font, uiObserver, UIUtils,
+  Theme, ThemeControl, CustomColors, CustomTheme,
+  CircleShape, RectShape, EllipseShape, PathShape, Binding
+} from '@kit.ArkUI'
+```
+
+| 使用场景 | 导入符号 |
+|---------|---------|
+| UI 上下文操作 | `UIContext` |
+| 窗口管理 | `window` |
+| 自定义节点 | `BuilderNode`, `FrameNode`, `NodeController` |
+| 自定义内容 | `ComponentContent`, `NodeContent` |
+| 节点渲染状态 | `NodeRenderState` |
+| 尺寸/颜色度量 | `LengthMetrics`, `ColorMetrics` |
+| 矩阵变换 / 动画曲线 | `matrix4`, `curves` |
+| 页面路由 / 弹窗提示 | `router`, `PromptAction` |
+| 图片属性修改器 / 键盘避让 | `ImageModifier`, `KeyboardAvoidMode` |
+| 自定义字体 / UI 观察者 | `Font`, `uiObserver` |
+| V1/V2 兼容工具 | `UIUtils` |
+| 主题相关 | `Theme`, `ThemeControl`, `CustomColors`, `CustomTheme` |
+| Shape 裁切 | `CircleShape`, `RectShape`, `EllipseShape`, `PathShape` |
+| 数据绑定 | `Binding` |
+
+### @kit.AbilityKit（应用模型 kit）
+
+```ts
+import { UIAbility, AbilityConstant, Want, common, Configuration, ConfigurationConstant, bundleManager } from '@kit.AbilityKit'
+```
+
+| 使用场景 | 导入符号 |
+|---------|---------|
+| Ability 生命周期 | `UIAbility`, `AbilityConstant` |
+| Ability 间通信 | `Want` |
+| 获取上下文类型 | `common`（如 `common.UIAbilityContext`） |
+| 配置变更 / 包管理 | `Configuration`, `ConfigurationConstant`, `bundleManager` |
+
+### @kit.BasicServicesKit（基础服务 kit）
+
+```ts
+import { BusinessError, request, commonEventManager } from '@kit.BasicServicesKit'
+```
+
+| 使用场景 | 导入符号 |
+|---------|---------|
+| 错误类型捕获 | `BusinessError` |
+| 网络下载 / 公共事件 | `request`, `commonEventManager` |
+
+### 其他 kit
+
+| Kit | 导入符号 | 使用场景 |
+|-----|---------|---------|
+| `@kit.ArkData` | `unifiedDataChannel`, `uniformTypeDescriptor` | 拖拽数据传递（UTD） |
+| `@kit.ImageKit` | `image` | 图片处理（编解码、缩放等） |
+| `@kit.InputKit` | `pointer`, `IntentionCode` | 光标样式、输入设备 |
+| `@kit.ArkGraphics2D` | `uiEffect` | 模糊效果等图形能力 |
+| `@kit.CoreFileKit` | `fileIo` | 文件读写 |
+| `@kit.ArkTS` | `buffer` | 二进制缓冲区 |
+| `@kit.PerformanceAnalysisKit` | `hilog` | 日志输出 |
+
+## 全局内置（不需要 import）
+
+基础组件（`Column/Row/Text/Button/Image/List/Grid/Scroll/Stack/Flex/Tabs/Navigation/NavDestination/TextInput` 等）、控制器类型（`SwiperController/TextInputController/Scroller/NavPathStack` 等直接 `new`）、渲染控制（`ForEach/LazyForEach/if-else`）、`AttributeModifier`/`AttributeUpdater` 等扩展接口、枚举（`Color/FontWeight/Curve/FlexAlign/Alignment/Axis/ImageFit/InputType/ButtonType/TextAlign/TextOverflow/Visibility/PlayMode` 等）全局可用。
+
+**特别注意以下全局类型不要 import（`@kit.ArkUI` 不导出它们）：**
+- `NavPathStack`、`AppStorage`、`canIUse`、`getContext` — 全局可用，不要 import
+- `ObservedV2`、`Trace` — 装饰器全局可用，不要 import
+- `Resource`、`ResourceColor`、`ResourceStr` — 全局类型，不要 import
+- `AlertDialog`、`ActionSheet`、`DatePickerDialog`、`TimePickerDialog`、`TextPickerDialog` — 弹窗全局可用（但建议通过 UIContext 调用）
+- `LocalStorage`、`PersistentStorage`、`AppStorage` — 状态类型全局可用
+
+**以下需要 import：**
+- `AppStorageV2`、`PersistenceV2` — **需要**从 `@kit.ArkUI` 导入
+- 小写 `curves` 命名空间 — **需要**从 `@kit.ArkUI` 导入（`Curve.*` 枚举是全局的）
+
+> **注意**：`AttributeModifier` 不要在 `@kit.ArkUI` 里 import，它在全局 component 作用域（实测 TC_EXT_COMPONENT_001）。
+
+## 常见错误对比
+
+| ❌ 错误写法 | ✅ 正确写法 |
+|-----------|-----------|
+| `import router from '@ohos.router'` | `import { router } from '@kit.ArkUI'` |
+| `import window from '@ohos.window'` | `import { window } from '@kit.ArkUI'` |
+| `import promptAction from '@ohos.promptAction'` | `import { PromptAction } from '@kit.ArkUI'`（或通过 UIContext 获取） |
+| `import { BusinessError } from '@ohos.base'` | `import { BusinessError } from '@kit.BasicServicesKit'` |
+| `import { UIAbility } from '@kit.ArkUI'` | `import { UIAbility } from '@kit.AbilityKit'` |
+| `import { hilog } from '@kit.ArkUI'` | `import { hilog } from '@kit.PerformanceAnalysisKit'` |
+| `import { image } from '@kit.ArkUI'` | `import { image } from '@kit.ImageKit'` |
+| `import { fileIo } from '@kit.ArkUI'` | `import { fileIo } from '@kit.CoreFileKit'` |
+| `import { mediaQuery } from '@kit.ArkUI'`（小写 q） | `import { MediaQuery } from '@kit.ArkUI'`（大写 Q） |
+
+## 参考
+
+- **关键**：ArkTS 全局内置能力已在上文列出；凡是不在列表中的，必须先查速查表或检索确认再写，不凭记忆编造
+- 组件/struct 基本约束见 [03-component](03-component.md)：创建组件不需要 `new`；`struct` 无继承；static 无意义；组件名不得与系统组件重名

package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/02-uicontext.md

@@ -0,0 +1,56 @@
+# 2. UIContext — 全局接口必须通过 `getUIContext()`
+
+## 规则
+
+Stage 模型下一个 ArkTS 引擎可运行多个 ArkUI 实例，全局接口通过分析调用链中的上下文信息确定当前 UI 上下文，异步接口和非 UI 接口可能导致 UI 上下文跟踪失败。**禁止直接使用全局接口，必须通过 `UIContext` 获取替代接口。**
+
+获取方式：组件内 `this.getUIContext()`；窗口侧 `windowClass.getUIContext()`。
+
+## 全局接口 → UIContext 替换表（高频）
+
+| ❌ 禁止的全局接口 | ✅ UIContext 替代 | 说明 |
+|---|---|---|
+| `AlertDialog.show` | `uiContext.showAlertDialog()` | |
+| `ActionSheet.show` | `uiContext.showActionSheet()` | |
+| `router.*` | `uiContext.getRouter().*` | |
+| `promptAction.*` | `uiContext.getPromptAction().*` | |
+| `vp2px/px2vp/fp2px/px2fp` | `uiContext.vp2px()` 等（直接方法） | |
+| `animateTo` | `uiContext.animateTo()` | |
+| `@ohos.mediaquery` | `uiContext.getMediaQuery()` | |
+| `@ohos.font` | `uiContext.getFont()` | |
+| `@ohos.measure` | `uiContext.getMeasureUtil()` | 文本计算 |
+| `@ohos.animator` | `uiContext.createAnimator()` | |
+| `@ohos.arkui.observer` | `uiContext.getUIObserver()` | 无感监听 |
+| `@ohos.arkui.dragController` | `uiContext.getDragController()` | |
+| `@ohos.arkui.componentSnapshot` | `uiContext.getComponentSnapshot()` | 组件截图 |
+| `@ohos.arkui.componentUtils` | `uiContext.getComponentUtils()` | |
+| `@ohos.arkui.inspector` | `uiContext.getUIInspector()` | 组件布局回调 |
+| `focusControl` | `uiContext.getFocusController()` | |
+| `cursorControl` | `uiContext.getCursorControl()` | |
+| `getContext` | `uiContext.getHostContext()` | 获取当前 Ability 的 Context |
+| `LocalStorage.getShared` | `uiContext.getSharedLocalStorage()` | |
+| `CalendarPickerDialog.show` | `uiContext.runScopedTask(() => CalendarPickerDialog.show(...))` | 无直接替代，需 runScopedTask 包裹 |
+| `DatePickerDialog` | `uiContext.showDatePickerDialog()` | |
+| `TimePickerDialog` | `uiContext.showTimePickerDialog()` | |
+| `TextPickerDialog` | `uiContext.showTextPickerDialog()` | |
+| `ContextMenu` | `uiContext.getContextMenuController()` | |
+| `lpx2px` / `px2lpx` | `uiContext.lpx2px()` 等（直接方法） | |
+| `keyframeAnimateTo` | `uiContext.keyframeAnimateTo(param, keyframes)` | **存在**，但**不支持** springMotion/responsiveSpringMotion/interpolatingSpring |
+| `animateToImmediately` | **无替换，禁止使用** | |
+
+## 常见错误对比
+
+| ❌ 错误写法 | ✅ 正确写法 |
+|------------|-----------|
+| `AlertDialog.show({ message: 'x' })` | `this.getUIContext().showAlertDialog({ message: 'x' })` |
+| `router.pushUrl({ url: 'pages/Second' })` | `this.getUIContext().getRouter().pushUrl({ url: 'pages/Second' })` |
+| `promptAction.showToast({ message: 'hi' })` | `this.getUIContext().getPromptAction().showToast({ message: 'hi' })` |
+| `let px = vp2px(20)` | `let px = this.getUIContext().vp2px(20)` |
+| `animateTo({ duration: 300 }, () => {})` | `this.getUIContext().animateTo({ duration: 300 }, () => {})` |
+
+**根因**：AI 训练数据中直接调用全局接口的示例很多，且语法上不报错但在多实例场景会出问题。
+
+## 参考
+
+- 动画顺序与限制见 [05-state-v1](05-state.md) @Builder 部分和 [13-style](10-style.md) 动画约束
+- 废弃接口替换见 [19-deprecated](14-deprecated.md)

package/resources/deveco/skills/hmos-arkui-develop-skill/references/quick-rules/03-component.md

@@ -0,0 +1,105 @@
+# 3. 自定义组件与命名约束
+
+## 规则
+
+### 组件基本约束
+
+| 规则 | 说明 | 错误码 |
+|------|------|--------|
+| `struct` 无继承 | 自定义组件基于 struct，**不能有继承关系** | — |
+| 禁止名称冲突 | 自定义组件名、类名、函数名**不得与系统组件名重复**（`Button`/`Text`/`Image` 等） | — |
+| 单一 `@Entry` | 单个 UI 页面仅允许一个 `@Entry` 装饰的组件 | — |
+| `@Component` 与 `@ComponentV2` 互斥 | 不能同时装饰同一个 struct | — |
+| 创建组件不需要 `new` | `Column()`、`Text('x')`；只有控制器类用 `new`（`new NavPathStack()`） | — |
+| 成员函数/变量不建议 `static` | 仅能从组件内部访问，静态声明无意义 | — |
+| V1 不支持静态代码块 | `@Component` 或 `@CustomDialog` 中 `static {}` 不执行（API 22 起告警） | — |
+| `@Component`（V1）禁 getter accessor | 编译转换会丢弃 getter，可能造成运行时崩溃；改用普通成员方法（`@ComponentV2` 不受此限） | — |
+| 生命周期钩子不能 `private` | `aboutToAppear`、`aboutToDisappear` 等生命周期方法**不能标记为 `private`** | — |
+| 成员属性名禁止与链式方法重名 | 见下方"保留名"清单 | **10505001** |
+| 跨文件 interface/class 必须重名校验 | 同一 hap 全局作用域，通用名跨文件碰撞 → `arkts-no-decl-merging` | **arkts-no-decl-merging** |
+
+### 成员变量名禁止与 CustomComponent 链式方法/通用属性重名
+
+`@State/@Prop/@Local` 等成员名**禁止**使用以下（会与基类链式方法签名冲突，触发 `10505001`）：
+
+`id`、`width`、`height`、`margin`、`padding`、`offset`、`position`、`border`、`borderRadius`、`backgroundColor`、`brightness`、`direction`、`value`、`scale`、`rotate`、`opacity`、`visibility`、`zIndex`、`size`、`layoutWeight`、`aspectRatio`、`flexBasis`、`flexGrow`、`flexShrink`、`alignSelf`、`justifyContent`、`alignItems`、`alignContent`、`borderWidth`、`borderColor`、`borderStyle`、`borderImage`、`foregroundColor`、`colorFilter`、`clip`、`gradient`、`blur`、`shadow`、`transform`、`markAnchor`、`translate`、`clickEffect`、`hoverEffect`、`draggable`、`enabled`、`tabIndex`（所有通用属性名 + CustomComponent 基类属性均为禁区）
+
+命名约定：用业务前缀（`current/slide/item/bg/screen/my` 等）消歧义，如 `currentValue` 而非 `value`。
+
+### 跨文件 interface/class 重名 → `arkts-no-decl-merging`（CRITICAL）
+
+ArkTS 把同一 hap 内**所有页面**编译进**共享全局作用域**。多个页面文件在顶层声明同名 `interface`/`class`，会被判定为"声明合并"而报错。**碰撞发生在文件之间，本文件内看不到。** 命名之前需要避免重名存在。
+
+## 框架保留字全表
+
+自定义组件中定义的方法/变量若与下表重名，会导致运行时异常。凡列出的，一律改用不同名字。
+
+| 保留字 | 保留字 | 保留字 | 保留字 |
+|---|---|---|---|
+| isRenderInProgress | isInitialRenderDone | runReuse_ | paramsGenerator_ |
+| watchedProps | recycleManager_ | hasBeenRecycled_ | preventRecursiveRecycle_ |
+| delayRecycleNodeRerender | delayRecycleNodeRerenderDeep | defaultConsume_ | reconnectConsume_ |
+| providedVars_ | dirtyElementIdsNeedsUpdateSynchronously_ | localStoragebackStore_ | ownObservedPropertiesStore__ |
+| obtainOwnObservedProperties | getlocalStorage_ | setlocalStorage_ | getisViewV2 |
+| aboutToBeDeleted | aboutToBeDeletedInternal | purgeDeleteElmtId | purgeVariableDependenciesOnElmtIdOwnFunc |
+| debugInfoStateVars | initAllowComponentFreeze | setActiveInternal | onActiveInternal |
+| onInactiveInternal | purgeVariableDependenciesOnElmtId | initialRender | rerender |
+| updateRecycleElmtId | updateStateVars | initialRenderView | UpdateElement |
+| delayCompleteRerender | flushDelayCompleteRerender | forceRerenderNode | collectElementsNeedToUpdateSynchronously |
+| viewPropertyHasChanged | uiNodeNeedUpdateV2 | performDelayedUpdate | declareWatch |
+| addProvidedVar | findProvidePU__ | initializeConsume | reconnectToConsume |
+| disconnectedConsume | markElemenDirtyById | updateDirtyElements | observeComponentCreation |
+| observeComponentCreation2 | getOrCreateRecycleManager | getRecycleManager | hasRecycleManager |
+| initRecycleManager | rebuildUpdateFunc | observeRecycleComponentCreation | aboutToReuseInternal |
+| stopRecursiveRecycle | aboutToRecycleInternal | recycleSelf | isRecycled |
+| UpdateLazyForEachElements | createStorageLink | createStorageProp | createLocalStorageLink |
+| createLocalStorageProp | debugInfoView | debugInfoViewInternal | debugInfoDirtyDescendantElementIds |
+| __mkRepeatAPI | reuseOrCreateNewComponent | dirtDescendantElementIds_ | monitorIdsDelayedUpdate |
+| monitorIdsDelayedUpdateForAddMonitor_ | computedIdsDelayedUpdate | recyclePoolV2_ | resetStateVarsOnReuse |
+| aboutToReuseInternals | resetMonitorsOnReuse | resetComputed | resetConsumer |
+| initParam | updateParam | resetParam | getViewV2ChildById |
+| addDelayedMonitorIdsForAddMonitor | addDelayedComputedIds | inactiveComponents_ | compareNumber |
+| currentlyRenderedElmtIdStack_ | dirtRetakenElementIds_ | parent_ | renderingPaused |
+| isDeleting_ | isCompFreezeAllowed_ | prebuildFuncQueues | propertyChangedFuncQueues |
+| extraInfo_ | __isBlockRecycleOrReuse__ | elmtIdsDelayedUpdate_ | prebuildPhase_ |
+| isPrebuilding_ | prebuildingElmtId_ | doRecycle | doReuse |
+| nativeViewPartialUpdate | create | createRecycle | markNeedUpdate |
+| syncInstanceId | restoreInstanceId | getInstanceId | markStatic |
+| finishUpdateFunc | setCardId | getCardId | elmtIdExists |
+| isLazyItemRender | isFirstRender | findChildByIdForPreview | resetRecycleCustomNode |
+| queryNavDestinationInfo | queryNavigationInfo | queryRouterPageInfo | getUIContext |
+| sendStateInfo | getUniqueId | setIsV2 | getDialogController |
+| allowReusableV2Descendant | id__ | updateId | scheduleDelayedUpdate |
+| setParent | getParent | removeChild | addChild |
+| isDeleting | setDeleting | setDeleteStatusRecursively | setActiveCount |
+| getChildViewV2ForElmtId | debugInfoRegisteredElmtIds | debugInfoElmtIds | dumpStateVars |
+| isViewActive | dumpReport | forceCompleteRerender | __ClearAllRecycle__PUV2ViewBase__Internal |
+| hasNodeUpdateFunc | pauseRendering | restoreRendering | forEachUpdateFunction |
+| getNodeById | getCurrentlyRenderedElmtId | debugInfoViewHierarchy | debugInfoUpdateFuncByElmtId |
+| debugInfoInactiveComponents | findViewInHierarchy | onDumpInfo | printDFXHeader |
+| processOnDumpCommands | traverseChildDoRecycleOrReuse | processPropertyChangedFuncQueue | setPrebuildPhase |
+| isNeedBuildPrebuildCmd | prebuildComponent | isEnablePrebuildInMultiFrame | ifElseBranchUpdateFunctionDirtyRetaken |
+| onDumpInspector | activeCount_ | isView_ | childrenWeakrefMap_ |
+| builderNodeWeakrefMap_ | updateFuncByElmtId | id_ | shareLocalStorage_ |
+| __parentViewBuildNode__ | __enableBuilderNodeConsume__ | __elmtId2Repeat___ | arkThemeScopeManager |
+| setArkThemeScopeManager | onWillApplyThemeInternally | getShareLocalStorage | setShareLocalStorage |
+| propagateToChildren | propagateToChildrenToConnected | propagateToChildrenToDisconnected | addChildBuilderNode |
+| setParentBuilderNode__ | removeChildBuilderNode | clearChildBuilderNode | getChildById |
+| purgeDeletedElmtIds | updateStateVarsOfChildByElmtId | createOrGetNode | ifElseBranchUpdateFunction |
+
+> 高频禁区：`rerender/aboutToAppear/aboutToDisappear/aboutToReuse/aboutToRecycle/initialRender/updateStateVars/getUIContext/observeComponentCreation/create/setParent/getParent/addChild/removeChild/markNeedUpdate/forceRerenderNode/findProvidePU__/isViewV2/localStorage_/id__/elmtIdsDelayedUpdate/recycleManager_` 等。`getUIContext` 本身也是保留名，不要 shadow。
+
+## 常见错误对比
+
+| ❌ 错误写法 | ✅ 正确写法 | 说明 |
+|------------|-----------|------|
+| `struct Button {}` | `struct MyButton {}` | 与系统组件名冲突 |
+| `@State value: string = ''` | `@State currentValue: string = ''` | 与 `.value()` 冲突 → 10505001 |
+| `@State direction: number = 0` | `@State moveDirection: number = 0` | 与 `.direction` 冲突 |
+| `@State position: number = 0` | `@State slotPosition: number = 0` | 与 `.position` 冲突 |
+| 变量命名 `rerender` | `rerenderValue` | 与框架保留字冲突 |
+
+## 参考
+
+- 容器直接子组件约束见 [16-layout](12-layout.md)
+- 成员变量命名与链式方法冲突（错误码 10505001）