deveco_hmigbot 0.21.5

package/skills/migrate-core/references/topics/system-capabilities/telephony-dial.md

@@ -0,0 +1,49 @@
+# 电话拨号（Telephony Kit）
+
+> 拉起系统拨号界面（显示待拨号码）用 Telephony Kit 的 `call.makeCall`——**不是** `Want + startAbility`。这与浏览器/URL 跳转（`browser-intent.md`，走 `viewData`）是**不同机制**，勿混用。
+
+---
+
+## 基本导入
+
+```typescript
+import { call } from '@kit.TelephonyKit'
+import { BusinessError } from '@kit.BasicServicesKit'
+```
+
+---
+
+## 拉起系统拨号界面
+
+> ✅ **验证状态**：已 probe 编译通过（`call.makeCall('10086')`，BUILD SUCCESSFUL）
+
+```typescript
+// makeCall(phoneNumber: string): Promise<void>
+// 号码作为 string 实参直接传入；跳转到系统拨号界面并显示待拨号码。
+// 只支持在 UIAbility 中调用；可能失败（如设备无电话能力），须接 .catch。
+function dialNumber(phoneNumber: string): void {
+  call.makeCall(phoneNumber)
+    .then(() => {
+      hilog.info(DOMAIN, TAG, `Dialer opened for ${phoneNumber}`)
+    })
+    .catch((err: BusinessError) => {
+      hilog.error(DOMAIN, TAG, `makeCall failed: code=${err.code}, message=${err.message}`)
+    })
+}
+```
+
+---
+
+## 关键约定
+
+- **用 `call.makeCall(phoneNumber)`**，号码是纯字符串（如 `'1234567890'`），**不带 `tel:` 前缀**。
+- **不要**把拨号走 `Want{action:'ohos.want.action.viewData', uri:'tel:<号码>'}` + `startAbility`——那条隐式路径非正解。
+- **不要**用已废弃的 `call.dial(...)`（自 API 9 起废弃，替代能力仅对系统应用开放）；应用侧拉起拨号界面用 `makeCall`。
+- `call` 从 `@kit.TelephonyKit` 导入，不要从 `@kit.AbilityKit` / Want 相关模块导入。
+- syscap `SystemCapability.Applications.Contacts`（since API 7）；`makeCall` 只是拉起拨号界面（不直接拨出），本身无需额外权限。
+
+---
+
+## module.json5 配置
+
+拉起系统拨号界面（`makeCall`）**无需**在 module.json5 声明 action/entity——直接调用即可（区别于隐式 Want 拉起需声明 skills 的场景）。

package/skills/migrate-core/references/topics/system-capabilities/video-playback.md

@@ -0,0 +1,42 @@
+# 视频播放（AVPlayer + XComponent）
+
+> 视频特化层：AVPlayer 状态机/fd:// 协议/倍速等音视频通用基础见 avplayer-guide.md；本篇只写视频独有工程问题。断言来源为生产迁移复盘，未逐条复验，首用按 SDK 查证。
+
+## 1. Surface 时序（最高频坑）
+
+- `XComponent(type: SURFACE)` 的 `onLoad` 拿 surfaceId 与 AVPlayer 初始化需**双向等待**：surfaceId 已设 + player 已 Initialized 都满足才 attach；surfaceId 在 Initialized 之后、`prepare` 之前设置。
+- `prepared` 前收到的 `seek` 请求先暂存、prepared 后重放。
+- 时长用 `durationUpdate` 事件获取，不用 getDuration。
+- 启播参数由调用方**透传 videoUrl**（进页面再反查详情接口 = 部分子项返空 + ~700ms 延迟）；业务详情走 `fromJson` 反序列化（plain object 字段 setter 静默失败）；`router.pushUrl` 路径下 `@Param` 不注入，用 AppStorageV2/显式透传兜底。
+
+## 2. 后台与横屏
+
+- **有声视频后台续播可申请 AUDIO_PLAYBACK 长时任务**（官方该类型覆盖"音频、视频在后台播放"）；**无声/静音视频页不要申请**——系统一致性校验检测不到播放会拒批或挂起；后台只需展示画面的走画中画 PiP（另见 background-tasks.md 同条）。
+- 进/退横屏必须**成对** set/restore orientation（aboutToAppear/aboutToDisappear 配对）；沉浸全屏 + `setSpecificSystemBarEnabled('navigationIndicator', false)` 防进度条最右段被系统手势横条遮挡。
+- 返回挽留 Dialog 拦截 `onBackPress`。
+
+## 3. Letterbox（保留原始宽高比）
+
+- 禁 XComponent `width/height('100%')` 直接拉伸；按视频宽高比算实际 `xcWidthVp/xcHeightVp` 与偏移 `videoOffsetXVp/Y`。
+- 顶/底控制栏 position **钉到视频帧**（用 videoOffset 偏移），不钉屏幕边、不用外层 `alignContent: Center`（Center 会让顶栏漂移、黑边上挂按钮）；外层 Stack 用 `TopStart`。
+
+## 4. 控件层
+
+- 控件 3.5s 自动隐藏，定时器覆盖 PLAYING / PAUSED / PREPARED 三态。
+- XComponent 之上放**透明点击层**接收点击唤出控件（XComponent 自身不接）。
+- 按钮图标直拷 Android 原工程 webp，禁用 Unicode 字形/手搓黑圆（两端字形不一致）。
+- dp→vp 1:1 直拷；`layout_centerVertical` = `top:'50%'` + `translate(y:-halfH)`。
+
+## 5. 视频专属错误速记
+
+| 错误 | 正确做法 |
+|---|---|
+| linearGradient 用 0xAARRGGBB number（吞 alpha） | 用 `'rgba()'` 字符串或带 alpha 颜色 |
+| 无声视频页加 AUDIO_PLAYBACK | 后台画面走 PiP；有声续播才申请 |
+| 横屏方向只 set 不 restore | 成对管理 |
+| XComponent 100% 拉伸 | letterbox 计算实际宽高 |
+| 顶/底栏钉屏幕边/Center 对齐 | 钉视频帧偏移 |
+| XComponent 上无透明点击层 | 加透明层接点击 |
+
+---
+蒸馏自 corpus/candidates/arkts-video-playback，2026-09 吸收

package/skills/migrate-core/references/topics/system-capabilities/webview-patterns.md

@@ -0,0 +1,38 @@
+# WebView 工程模式（Web 组件 + WebviewController）
+
+> 嵌 WebView 场景（不限浏览器）的已验证模式。`Web()`/`WebviewController` API 与状态体系 V1/V2 无关。断言未逐条复验，首用按 SDK 查证。
+
+## 1. JS 执行四原则
+
+1. **IIFE 包裹**：注入 JS 一律 `(function(){ ... })()`，防全局污染。
+2. **catch 兜底**：`runJavaScript()` 返回 Promise，必须 `.catch()`——页面异常否则带崩应用。
+3. **大文件分块**：rawfile 加载的 JS/CSS（如 Readability.js）用分块 `uint8ArrayToString()`（每 8192 字节一块），`String.fromCharCode(...spread)` 会栈溢出。
+4. **返回值反序列化**：`runJavaScript` 返回的是表达式结果的 **JSON 字符串化**形式——字符串被外层引号包裹、内部引号/换行被转义，需手动 strip + unescape；JS 返回 Promise 时会自动等待 resolve 再返回。
+
+## 2. CSS 注入（幂等）
+
+`runJavaScript` 创建带唯一 ID 的 `<style>`：查 `getElementById(styleId)`，无则 createElement 挂 head，有则只更新 `textContent`——多次注入不叠加；注入前对 CSS 做 `\` `` ` `` `$` 转义。移除 = 按 ID remove。
+
+## 3. 样式持久化
+
+页面导航后注入的 `<style>` 全丢。方案：`onPageEnd` 回调里统一 `reapplyStyles()`（检查所有样式开关状态、重注已开启项），比逐 toggle 分别持久化干净。
+
+## 4. WebView 内 fetch 调外部 API
+
+"读取 DOM → 调外部服务 → 回写 DOM"类功能（原地翻译/摘要/标注）优先在 WebView JS 环境内 `fetch()` 完成，一次 runJavaScript 走完全流程——不走 ArkTS native HTTP（省多轮 ArkTS↔JS 通信与序列化映射）。
+
+## 5. 双 WebView 通信（分屏）
+
+两个 WebView 无法直接通信。已验证通道：**借 `document.title`**——发送方 JS 设 `document.title = '__MSG_TYPE__' + payload`；接收方在 `onTitleReceive` 检测前缀拦截处理、不更新真实标题。
+
+## 6. ArkTS 环境差异速查
+
+| 问题 | 处置 |
+|---|---|
+| 无全局 TextEncoder/TextDecoder | `import { util } from '@kit.ArkTS'` → `new util.TextEncoder()` |
+| 无全局 URL 类 | 手动解析字符串（`indexOf('://')` 等），不能 `new URL(str)` |
+| 无 `{ ...obj }` 展开 | 逐字段构造新对象 |
+| rawfile 返回 Uint8Array | 分块转字符串（见 §1.3） |
+
+---
+蒸馏自 corpus/candidates/arkts-webview，2026-09 吸收

package/skills/migrate-core/references/topics/ui-alignment/README.md

@@ -0,0 +1,344 @@
+<!-- 原技能 arkts-ui-alignment，已吸收为 migrate-core 语料专题，不再单独注册 -->
+> 将 Android UI 设计迁移到 ArkTS/HarmonyOS 的等价实现。当用户需要匹配 Android Material Design 视觉效果、把 Android 布局/控件映射到 ArkTS 等价物（含 SymbolGlyph 图标体系、颜色/间距/字号对齐）时触发。即使只说"还原这个安卓界面""图标怎么对应"也应触发。不适用于 ArkTS 原创组件设计。
+
+# ArkTS UI Alignment — Android UI 迁移对齐
+
+## API 版本
+
+本 skill 基于 **API 12+**（HarmonyOS 5.0.0+）。UI 相关导入：
+
+- ArkUI 组件：内置，无需额外导入
+- SymbolGlyph：内置，资源引用 `$r('sys.symbol.xxx')`
+- 弹窗/轻提示：`this.getUIContext().getPromptAction()`，无需额外导入
+
+不确定的平台行为查官方文档确认（devecocli docs），不凭记忆写。
+
+---
+
+## 生成约定：本项目锁 ArkUI V2
+
+本 skill 的产物是**可运行的迁移页面**，一律用 **ArkUI V2** 声明式外壳（本 skill 讲的是视觉/控件对齐，不改这条）：
+
+- 页面 struct = `@Entry @ComponentV2`（**不是** `@Component`）；状态用 `@Local`/`@Param`/`@Once`/`@Event`/`@Monitor`/`@Provider`/`@Consumer`（**绝不**用 V1 的 `@State`/`@Prop`/`@Link`/`@Watch`/`@Provide`/`@Consume`）。
+- 本文档下方示例若出现 V1 装饰器，一律按 V2 改写；**映射/颜色/symbol/间距等对齐事实不变，只换装饰器外壳**。
+- **迁移还原场景**：源 XML/dimens 有实际值时以源值为准（1:1 还原）；本文的颜色系统映射与 4vp 间距体系仅在源值缺失时兜底。
+
+```typescript
+@Entry
+@ComponentV2
+struct Index {
+  @Local selected: string = ''
+  build() { /* 迁移后的 UI */ }
+}
+```
+
+---
+
+## Android → ArkTS 组件映射表
+
+| Android 元素 | ArkTS 组件 | 备注 |
+|-------------|-----------|------|
+| `BottomNavigationView` | 自定义 `Row` + `@Builder tabBarItem` | 不用 `Tabs` 在 Navigation 内部 |
+| `BottomSheetDialogFragment` | `NavDestination` (全屏) 或 `Sheet` | 视需求选择 |
+| `DrawerLayout` | `SideBarContainer` | 侧边栏 |
+| `RecyclerView` | `List` + `LazyForEach` | 虚拟列表 |
+| `ViewPager2` | `Swiper` | 翻页 |
+| `CoordinatorLayout` | `Stack` + 自定义手势 | 需手动实现 |
+| `CardView` | `Column` + `borderRadius` + `shadow` | 卡片 |
+| `FloatingActionButton` | `Button` + `Stack` 右下对齐（`Alignment.BottomEnd`） | FAB；勿写死 position 坐标 |
+| `ProgressBar` (Linear) | `Progress({ type: ProgressType.Linear })` | 进度条 |
+| `ProgressBar` (Circular) | `Progress({ type: ProgressType.Ring })` | 进度环 |
+| `Toolbar` / `ActionBar` | `NavDestination` 标题栏 | 自动 |
+| `AlertDialog` | `getUIContext().getPromptAction().showDialog()` / `openCustomDialog` | 弹窗（全局 `AlertDialog.show` 已废弃；禁 @CustomDialog+CustomDialogController，V2 宿主运行时 controller 不绑定） |
+| `PopupMenu` | `Menu` + `MenuItem` | 菜单 |
+| `Snackbar` | `getUIContext().getPromptAction().showToast()` | 轻提示（全局 `promptAction.*` 已废弃） |
+| `ImageView` + Glide | `Image(url)` 或 `@ohos/imageknife` | 图片加载 |
+| `EditText` | `TextInput` / `TextArea`(多行) | 输入框 |
+| `CheckBox` | `Checkbox` | 多选 |
+| `RadioButton` + `RadioGroup` | `Radio`(同 group) | 单选 |
+| `Switch` / `SwitchCompat` | `Toggle({ type: ToggleType.Switch })` | 开关 |
+| `SeekBar` | `Slider` | 滑块 |
+| `Spinner` | `Select` | 下拉选择 |
+| `SwipeRefreshLayout` | `Refresh` | 下拉刷新 |
+
+> 详细映射 + 代码示例见 `references/layout-mapping.md`
+
+---
+
+## SymbolGlyph 图标体系
+
+### 已验证可用名称（编译验证通过，按类别速查）
+
+以下名称经 DevEco Studio 真机编译验证**存在**，可直接 `$r('sys.symbol.<名>')` 使用：
+
+- **导航/箭头**：`house` `chevron_left` `chevron_right` `chevron_up` `chevron_down` `arrow_left` `arrow_right` `arrow_up` `arrow_down` `arrow_2_circlepath`
+- **列表/布局**：`list_bullet` `line_3_horizontal` `square_grid_2x2`
+- **媒体控制**：`play_fill` `pause_fill` `playpause_fill` `backward_fill` `forward_end_fill` `backward_end_fill` `speaker_wave_2_fill` `mic` `mic_fill` `repeat` `repeat_1` `shuffle`
+- **账户/隐私**：`person` `person_fill` `person_2` `lock` `eye` `eye_slash`（密码框显示/隐藏 = `eye` / `eye_slash`）
+- **状态/标记**：`checkmark` `checkmark_circle` `checkmark_circle_fill` `xmark` `xmark_circle` `xmark_circle_fill` `plus` `plus_circle` `minus_circle` `info_circle` `exclamationmark_circle` `questionmark_circle`
+- **常用操作**：`magnifyingglass` `trash` `gearshape` `envelope` `bell` `bell_fill` `heart` `heart_fill` `star` `star_fill` `bookmark` `bookmark_fill` `link` `paperplane` `paperplane_fill` `hand_thumbsup`
+- **内容/时间**：`doc` `folder` `folder_fill` `calendar` `calendar_badge_plus` `clock` `camera` `camera_fill` `map` `flag` `bolt`
+- **电商**：`cart` `cart_fill` `bag` `bag_fill` `gift` `gift_fill` `creditcard`
+- **其它**：`wifi` `sun_max` `moon` `cloud`
+
+### 已验证【不存在】+ 替代方案（编译报 `Unknown resource name`）
+
+| 猜测名称（不存在） | 替代 |
+|---|---|
+| `forward_fill` | **`forward_end_fill`**（前进/下一首；`forward_fill` 本身不存在） |
+| `ellipsis` / `dot_3_horizontal` | `line_3_horizontal` |
+| `square_and_arrow_up`（分享） | `paperplane` / `paperplane_fill` |
+| `tray_arrow_down` | `envelope` |
+| `chart_bar` | `square_grid_2x2` |
+| `eye_fill` / `eye_slash_fill` | `eye` / `eye_slash`（无 `_fill` 后缀） |
+| `location` / `location_fill` | `map`（无 `location` 裸名） |
+| `photo` | `doc` / `square_grid_2x2` |
+| `music_note` | `speaker_wave_2_fill` |
+| `tag` / `doc_fill` / `person_circle` / `slider_horizontal_3` | 改用上方已验证名 |
+
+### 使用规范
+
+```typescript
+// 标准用法
+SymbolGlyph($r('sys.symbol.house'))
+  .fontSize(22)
+  .fontColor([Color.Black])
+
+// 条件颜色（选中/未选中）
+SymbolGlyph($r('sys.symbol.play_fill'))
+  .fontSize(20)
+  .fontColor(this.isActive ? [Color.Black] : ['#99182431'])
+```
+
+**铁律**：
+- 统一使用 `SymbolGlyph`；**绝不**把 Unicode emoji 或符号字（`♂` `♀` `✓` `★` 等）塞进 `Text` 当图标——那破坏视觉对齐、不是图标
+- `fontColor` 参数是**数组**：`[Color.Black]` 不是 `Color.Black`
+- **只用上方已验证清单里的名字**。图标不在清单时**按序回退**：① 清单里**语义最近的合法 symbol**（人物/性别→`person`/`person_fill`/`person_2`、搜索→`magnifyingglass`、分享→`paperplane`）→ ② 确需精确图形且工程自带矢量图才用 `Image` → ③ **绝不** emoji/Unicode 符号字，**绝不**凭猜发未验证 `sys.symbol.*`（编译必报 `Unknown resource name` 致整页失败；"先标 `[待验证]` 再发"挡不住）。
+- ⚠️ 系统库**无**专用性别符号（`male`/`female`/`person_badge`/`figure_stand` probe 实证不存在）→ 性别男/女一律用通用 `person`/`person_2`（区分靠右侧文字标签），**别**回退 `Text('♂'/'♀')`。
+
+### `ohos_` 前缀命名空间（HarmonyOS 原生图标）
+
+除上面的裸名（源自 SF Symbols 命名体系）外，系统还预置一小撮 **`ohos_` 前缀**的鸿蒙原生图标。编译验证存在的有：`ohos_wifi` `ohos_lock` `ohos_trash` `ohos_star` `ohos_photo` `ohos_mic`。某些图标两种形并存（如 `wifi` 与 `ohos_wifi` 都可用）。**绝大多数常见动作没有 ohos_ 形**（`ohos_add`/`ohos_delete`/`ohos_settings`/`ohos_share`/`ohos_search`… 全部**不存在**，仍用裸名）。规则同上：**只用编译验证过的 `ohos_` 名**，不要凭猜造 `ohos_xxx`。遇到鸿蒙系统设置类页面的原生图标（WiFi/锁/相册等）可优先考虑对应 `ohos_` 名。
+
+---
+
+## 颜色系统映射
+
+| Material 语义 | HarmonyOS 色值 | 用途 |
+|-------------|---------------|------|
+| primaryColor | `#007DFF` | 品牌蓝、主操作按钮 |
+| surface | `#FAFAFA` | 卡片/面板背景 |
+| background | `#FFFFFF` | 页面背景 |
+| onSurface | `#182431` | 深色主文字 |
+| onSurfaceVariant | `#99182431` | 次要文字（60% 不透明度） |
+| divider | `#E0E0E0` | 分割线 |
+| error | `#E84026` | 错误提示 |
+| disabled | `#66182431` | 禁用态文字 |
+| overlay | `#1A000000` | 蒙层/阴影（10% 黑） |
+| pillBg | `#1F000000` | 药丸指示器背景（12% 黑） |
+
+### 系统颜色资源
+
+```typescript
+// 推荐使用系统语义色（随深色模式自动切换）
+$r('sys.color.ohos_id_color_text_primary')     // 主文字
+$r('sys.color.ohos_id_color_text_secondary')   // 次要文字
+$r('sys.color.ohos_id_color_background')       // 背景色
+```
+
+---
+
+## 间距系统
+
+采用 **4vp 基数**，保持视觉一致性：
+
+| 级别 | 值 | 用途 |
+|------|---|------|
+| xs | 4vp | 紧凑间距 |
+| sm | 8vp | 列表项内间距 |
+| md | 12vp | 组件间距 |
+| lg | 16vp | 区域间距、标准 padding |
+| xl | 20vp | 大区域间距 |
+| xxl | 24vp | 页面边距 |
+
+```typescript
+// 示例
+Row() { ... }
+  .padding({ left: 16, right: 16, top: 8, bottom: 8 })
+  .margin({ top: 12 })
+```
+
+---
+
+## Tab 栏方案
+
+> **先分清两种 Tab，别一刀切**：下面"别把 `Tabs` 放进 `Navigation`"的告诫**只针对底部主导航 + Navigation 路由**这一种场景。**顶部分段切换（Android `TabLayout` + `ViewPager2`，不在 Navigation 内）应直接用原生 `Tabs`**，不要手搓 `Row` 页签 + `Swiper` 同步（那是回避、还原度差）：
+>
+> ```typescript
+> Tabs({ barPosition: BarPosition.Start, index: this.idx }) {
+>   TabContent() { FirstPage() }.tabBar('推荐')
+>   TabContent() { SecondPage() }.tabBar('关注')
+> }
+> .onChange((i: number) => { this.idx = i })   // 点击/滑动双向同步由 Tabs 自带，无需自管手势
+> ```
+>
+> 顶部三段式/中部分类 Tab = `Tabs({barPosition: BarPosition.Start}) + TabContent().tabBar(...)`；横向滚动多 Tab 加 `.barMode(BarMode.Scrollable)`。
+
+### Tabs 与 Navigation 的层次：照源码，不预设
+
+`Tabs` 放在 `Navigation` 内部时，`NavDestination` 子页面会覆盖整个区域（包括 Tab 栏）——这正是安卓多数应用
+（Activity 压栈 / NavHost 覆盖 BottomNavigationView）的既有行为，**默认就这么做**，Tab 页仍是 route_map 注册的
+NavDestination（见 flow/navigation-migration.md，Index 壳冻结、页面只经 AppRouter 到达）。
+只有源码里子页面**保留底栏可见**（BottomNavigationView 在 Activity 根布局、NavHost 只占内容区，子页在同一 NavHost 内）
+时，才把自定义 Tab 栏放到 Navigation 外部，且外部 Tab 页也必须是注册页（Tab 切换 = 替换到对应路由），不能写成
+`if (index === …)` 的未注册分支。
+
+### 源码保留底栏时的写法：自定义 Tab 栏放在 Navigation 外部
+
+```typescript
+Column() {
+  // 内容区（Navigation 占满剩余空间）
+  Navigation(this.navPathStack) {
+    // Tab 内容根据 currentTabIndex 切换
+    if (this.currentTabIndex === 0) { HomeComponent() }
+    else if (this.currentTabIndex === 1) { QueueComponent() }
+    // ...
+  }
+  .navDestination(this.routerMap)
+  .mode(NavigationMode.Stack)
+  .layoutWeight(1)
+
+  // MiniPlayer（Navigation 外部，不被覆盖）
+  if (this.isPlayerVisible && !this.isFullPlayerVisible) {
+    MiniPlayerArea()
+  }
+
+  // 自定义 Tab 栏（Navigation 外部，不被覆盖）
+  if (!this.isFullPlayerVisible) {
+    CustomTabBar()
+  }
+}
+```
+
+---
+
+## 药丸指示器 Tab 样式
+
+Material 3 风格的底部 Tab 栏（药丸形背景指示选中态）：
+
+```typescript
+@Builder
+tabBarItem(index: number, title: Resource, icon: Resource) {
+  Column() {
+    // 药丸形背景
+    Column() {
+      SymbolGlyph(icon)
+        .fontSize(22)
+        .fontColor(this.currentTabIndex === index ?
+          [Color.Black] : ['#99182431'])
+    }
+    .width(48)
+    .height(28)
+    .borderRadius(14)
+    .backgroundColor(this.currentTabIndex === index ?
+      '#1F000000' : '#00000000')
+    .justifyContent(FlexAlign.Center)
+
+    Text(title)
+      .fontSize(10)
+      .fontColor(this.currentTabIndex === index ?
+        '#182431' : '#99182431')
+      .margin({ top: 2 })
+  }
+  .layoutWeight(1)
+  .justifyContent(FlexAlign.Center)
+  .height('100%')
+  .onClick(() => { this.currentTabIndex = index; })
+}
+```
+
+> 完整代码见 `references/visual-patterns.md`
+
+---
+
+## 封面图 + Fallback 模式
+
+网络图片 + 文字首字母占位符：
+
+```typescript
+if (this.coverUrl.length > 0) {
+  Image(this.coverUrl)
+    .width(40).height(40)
+    .borderRadius(6)
+    .objectFit(ImageFit.Cover)
+} else {
+  Column() {
+    Text(this.title.length > 0 ?
+      this.title.charAt(0).toUpperCase() : '?')
+      .fontSize(18)
+      .fontWeight(FontWeight.Bold)
+      .fontColor(Color.White)
+  }
+  .width(40).height(40)
+  .borderRadius(6)
+  .backgroundColor('#BDBDBD')
+  .justifyContent(FlexAlign.Center)
+}
+```
+
+---
+
+## 常见错误
+
+### 1. Emoji vs SymbolGlyph 混用
+```typescript
+// ❌ emoji 大小不可控
+Text('📋').fontSize(22)  // 实际渲染大小不确定
+
+// ✓ SymbolGlyph 大小精确可控
+SymbolGlyph($r('sys.symbol.list_bullet'))
+  .fontSize(22)
+  .fontColor([Color.Black])
+```
+
+### 2. 使用不存在的 symbol 名称
+```typescript
+// ❌ 编译报 Unknown resource name
+SymbolGlyph($r('sys.symbol.tray_arrow_down'))
+
+// ✓ 使用已验证的名称或查阅清单
+SymbolGlyph($r('sys.symbol.envelope'))
+```
+
+### 3. Tabs 与 Navigation 的层次
+```typescript
+// 默认（源码子页覆盖底栏）：Tabs 在 Navigation 内，子页 NavDestination 覆盖整区 —— 与安卓一致，不是缺陷
+Navigation() {
+  Tabs() { ... }
+}
+
+// 仅当源码子页保留底栏可见：Tab 栏放在 Navigation 外部，Tab 页仍走注册路由
+Column() {
+  Navigation() { ... }.layoutWeight(1)
+  CustomTabBar()  // 始终可见
+}
+```
+
+---
+
+## 生成检查清单
+
+- [ ] Android 组件已查对照表找到 ArkTS 等价物
+- [ ] 图标统一使用 SymbolGlyph（不使用 emoji）
+- [ ] Symbol 名称来自已验证清单
+- [ ] 颜色/间距按源码 1:1（本文色值表与 4vp 基数只在源码没给值时兜底）
+- [ ] Tabs 层次照源码：子页覆盖底栏用默认形态；源码保留底栏才把 Tab 栏放 Navigation 外
+- [ ] 封面图有 fallback 占位
+
+---
+
+## References
+
+- `references/layout-mapping.md` — Android→ArkTS 组件映射详细版 + 代码示例 + 单位转换
+- `references/visual-patterns.md` — 药丸 Tab 栏 + 封面 fallback + MiniPlayer + SymbolGlyph + 阴影卡片
+- `references/dark-mode.md` — 深色模式适配（双资源目录/媒体深浅版本）

package/skills/migrate-core/references/topics/ui-alignment/references/dark-mode.md

@@ -0,0 +1,47 @@
+# 深浅色适配（dark-mode）
+
+> ⚠ 本文样例中 `getContext(this)` 为已废弃写法：组件内一律改 `this.getUIContext().getHostContext()`；Ability 内用 `this.context`。
+
+
+> 支持深浅色的工程必读；conventions §E 的"状态栏/自绘不自动切换"两条的细则出处。
+
+## 1. 心智模型
+
+- ColorMode 三值（`ConfigurationConstant.ColorMode`）：`NOT_SET(-1)`=跟随系统（默认）、`DARK(0)`、`LIGHT(1)`。应用固定一种用 `getApplicationContext().setColorMode(...)`；一旦应用主动设过，系统切换不再覆盖本应用。读当前值：`getContext(this).config.colorMode`（多窗口下每个 UI 实例各自感知，别依赖全局单例）。
+- 第一原则**不写具体颜色值**，引用语义 token：文字 `$r('sys.color.font_primary|font_secondary|…')`、图标 `icon_primary|icon_on_primary`、背景 `comp_background_primary|comp_divider`、交互态 `interactive_hover|interactive_click`。业务自定义色放 `base/element/color.json` + `dark/element/color.json` 同名覆写，引用 `$r('app.color.xxx')`。
+- `$r()` 的刷新机制：框架保留 resource 引用、切主题时重新解析。属性透传链路必须保留 `Resource` 类型——中途解成 `Color` 数值再传 = 首次正确、切换后不刷新。
+
+## 2. 资源限定词目录
+
+```
+resources/base/element/color.json   # 浅色基线
+resources/dark/element/color.json   # 深色覆写（同 name 覆盖）
+resources/dark/media/icon.svg       # 深色图标覆写
+resources/2in1-dark/element/…       # 2in1 深色（不是 2in1/）
+```
+
+反模式：`icon_dark.svg`/`icon_night.png` 文件名后缀区分主题——绕过限定词匹配，深色下不命中。
+HSP/HAR 每个模块须独立提供自己的 `src/main/resources/dark/`，主包 dark/ 覆盖不到模块内部资源（"HSP 深色失效、主包正常"先查这条）。
+
+## 3. 框架不自动处理的三处
+
+1. **状态栏/导航栏前景色**：不随页面 ColorMode 自动变。主题变化回调里显式调 `window.setWindowSystemBarProperties({ statusBarContentColor, navigationBarContentColor })`。
+2. **Canvas/Web/XComponent 自绘内容**：订阅 `mediaquery.matchMediaSync('(dark-mode: true)')` 的 change 事件（或组件 `onColorModeChange` 回调）触发重绘。
+3. **Menu/Popup 等浮层**：`MenuOptions.colorMode` 未显式设置时可能与宿主不一致。
+
+## 4. 症状 → 优先怀疑
+
+| 现象 | 优先怀疑 |
+|---|---|
+| 按压/悬浮态两种模式一个样 | 硬编码 `'rgba(0,0,0,0.1)'` 类字面值 |
+| 深色下整页仍浅色底 | 根布局 `.backgroundColor(Color.White)`/`'#FFFFFF'` |
+| 图标深色下看不见 | Image 没设 `.fillColor($r('sys.color.icon_primary'))`；SVG 用 stroke 非 fill |
+| 切主题不变、重进才对 | 透传丢 Resource 引用 / 自绘未订阅切换 |
+| 想固定深色被系统切走 | 没走 `ApplicationContext.setColorMode` |
+| 状态栏文字看不清 | 没调 `setWindowSystemBarProperties` |
+
+排查顺序：读 colorMode → 切主题验证（完全不刷新=丢引用/未订阅；刷新但色不对=缺 dark 副本/硬编码）→ Inspector 抓实际颜色值 → 查 dark/ 目录（含每个 HSP）。
+grep 定位：`Color\.`、`'#[0-9A-Fa-f]{3,8}'`、`rgba?\(`、`*_dark.*` 文件名、`setWindowSystemBarProperties`。
+
+---
+蒸馏自 corpus/candidates/arkts-dark-mode，2026-09 吸收