expo-harmony-toolkit 1.8.3 → 1.9.1

package/docs/roadmap.md

@@ -6,6 +6,7 @@
 
 - 所有 Expo project types 与 package categories，最终都进入同一条 `mainline capability catalog`
 - `v2.0.0` 本身就要接近最完美、最最终的交付形态，而不是“还差最后一段 extension”
+- `v2.0.0` 的可靠打包承诺收敛为 catalog-covered Expo projects：只要依赖已经进入主线 capability catalog，就必须稳定闭环
 - 公开承诺仍然按 evidence gate 逐步放开，而不是因为目标扩大就提前放宽 `latest`
 - `latest` 继续只承接完整验收的 `verified`
 - `next` 继续承接 fast track，用来加速收敛，但不伪装成 `verified`
@@ -65,6 +66,8 @@
 
 ## 当前主线
 
+`v1.8.x` 已完成 repo 内可收口项，当前主线切到 `v1.9.x`。`v1.9.0` 先落 bare workflow baseline、app foundation modules 与 `react-native-gesture-handler` formal slice；`v1.9.1` 作为 build-hap patch release，补上 HAR normalize opt-out，让已确认 ohpm 可直接消费纯 HAR 的项目可以绕过 `expo-harmony-local-deps`。剩余需要真机或 release HAP 的证据继续保留在 v1.8.x capability board，不阻塞 v1.9.x 的 bare / foundation / third-party onboarding 工作。
+
 ### v1.8.0 Intake Hardening + Parallel Promotion
 
 目标日期：`2026-05-15`
@@ -98,7 +101,9 @@
 
 目标日期：`2026-06-15`
 
-目标：把 v1.8.0 建好的 intake + promotion 架子收口到可持续执行的证据节奏。
+状态：repo-only closeout complete；device / release evidence carryover。
+
+目标：把 v1.8.0 建好的 intake + promotion 架子收口到可持续执行的证据节奏，并把外部验收项从 repo 内可完成项中拆开。
 
 - 每个 preview capability 必须单独维护：
   - bundle evidence
@@ -108,12 +113,18 @@
 - combined sample 只负责回归烟测，不再替代单 capability 证据
 - `toolkit-config.json`、`doctor-report.json`、roadmap、support matrix、acceptance board 保持同源同步
 - `latest` 仍不承接任何证据未闭环的 capability
+- 不需要真机或 release HAP 的收尾项已经完成，可以进入 `v1.9.x`
+- 仍然顺延的外部证据：
+  - 单 capability 真机 device acceptance record
+  - 单 capability release HAP runtime acceptance
 
 ### v1.9.0 Bare Workflow Baseline + App Foundation Modules
 
 目标日期：`2026-08-31`
 
-目标：先把 bare workflow 拉进主线，并补齐最容易卡死真实项目的官方基础模块。
+状态：implementation baseline complete；device / release evidence carryover。
+
+目标：把 bare workflow 拉进主线，补齐最容易卡死真实项目的官方基础模块，并先建立第三方 blocker 的正式接入切片。
 
 - bare workflow 正式进入主线里程碑
 - 优先补齐：
@@ -123,6 +134,15 @@
   - `expo-clipboard`
   - `expo-haptics`
 - 高频第三方 native dependencies 开始进入同一 capability catalog
+- `react-native-gesture-handler` 进入 formal acceptance slice：
+  - 保留 experimental / non-verified 边界
+  - 补齐 sample / fixture / doctor / debug build evidence
+  - device / release evidence 仍按 promotion gate 单独关闭
+- project-shape regression farm 建立最小版本：
+  - managed core
+  - managed native heavy
+  - bare
+  - third-party native heavy
 - 对每个新能力继续坚持：
   - fixture
   - sample route
@@ -131,18 +151,40 @@
   - bundle
   - debug build
   - acceptance 记录
+- 本阶段不改变 `verified` 边界；foundation modules 以 `preview` + `runtimeMode=shim` 记录，`react-native-gesture-handler` 以 `experimental` + formal adapter slice 记录
+
+### v1.9.1 Build HAP HAR Normalize Opt-out
+
+目标日期：`2026-06-02`
 
-### v1.9.1 Third-party Native Wave A
+目标：把 issue #1 中的本地 HAR 解压 opt-out 做成正式 patch release，同时不改变默认 verified build path。
+
+- `build-hap` 新增显式 opt-out：
+  - `EXPO_HARMONY_SKIP_HAR_NORMALIZE=1`
+  - `expo-harmony build-hap --no-har-normalize`
+- 默认继续执行现有 `normalizeLocalHarDependencies` 路径：
+  - 解压 `file:*.har` 到 `expo-harmony-local-deps`
+  - 临时改写 root / entry `oh-package.json5`
+  - 注册 normalized local HAR modules
+  - 执行依赖 normalized local package 的 RNOH codegen / path 兜底
+- opt-out 开启后：
+  - 保留 `file:../node_modules/.../*.har`
+  - 让 `ohpm install --all` 直接消费纯 HAR
+  - 在 build report / CLI 文档里明确提示跳过的自动兜底
+- 本阶段只改变 build-hap escape hatch，不扩大 `verified` 能力边界
+- `v1.9.0` 已经存在于 npm `next`，本阶段发布为 `v1.9.1` 并进入 `latest`
+
+### v1.9.2 Third-party Native Wave A
 
 目标日期：`2026-09-30`
 
 目标：优先清掉最容易挡住“任何 Expo 项目”的高频第三方 native blocker。
 
 - 第一批高频第三方 native blocker 进入正式 onboarding：
-  - `react-native-gesture-handler`
   - `react-native-safe-area-context`
   - `react-native-screens`
   - `@react-native-async-storage/async-storage`
+- `react-native-gesture-handler` 如果在 `v1.9.0` 已完成 formal acceptance slice，则本阶段只继续补 device / release evidence 与 promotion 决策
 - 建立第三方 native capability onboarding checklist：
   - catalog entry
   - shim / adapter strategy
@@ -151,14 +193,14 @@
   - debug + release evidence
 - 任何进入 Wave A 的 blocker，都不允许继续停留在“矩阵外模糊探索”
 
-### v1.9.2 Third-party Native Wave B + Regression Farm
+### v1.9.3 Third-party Native Wave B + Regression Farm
 
 目标日期：`2026-10-31`
 
-目标：扩大第三方 native 覆盖，并建立“任何 Expo 项目”目标需要的持续回归面。
+目标：扩大第三方 native 覆盖，并把 `v1.9.0` 建好的最小 regression farm 扩容成持续回归面。
 
 - 第二批高频第三方 native 依赖进入主线
-- 引入 project-shape regression farm：
+- 扩容 project-shape regression farm：
   - managed core
   - managed native heavy
   - bare
@@ -193,13 +235,16 @@
 - 对仍无法在 `v2.0.0` 前关闭的项，必须提前明确降级策略与替代路径
 - `v2.0.0` 不接受“先宣布完成，再慢慢补长尾”
 
-### v2.0.0 Any Expo Project Reliable Packaging
+### v2.0.0 Catalog-covered Expo Project Reliable Packaging
+
+原 `Any Expo Project Reliable Packaging` 叙事保留为 intake 目标，但可靠打包承诺明确收敛到 catalog-covered 项目。
 
 目标日期：`2026-12-31`
 
-定义：任何 Expo 项目，只要依赖已经存在于主线 capability catalog 内，就能可靠打包成鸿蒙 App；`v2.0.0` 本身就是基本接近最完美、最最终的形态。
+定义：任何 Expo 项目，只要依赖已经存在于主线 capability catalog 内，就能可靠打包成鸿蒙 App；未进入 catalog 的依赖必须至少被 `doctor` 明确分类、指出 blocker，并给出下一步。`v2.0.0` 本身就是基本接近最完美、最最终的形态。
 
-- 不再只覆盖“主流项目”，而是把“任何 Expo 项目都能可靠打包成鸿蒙 App”作为正式版本定义
+- 不再只覆盖“主流项目”，而是把 catalog-covered Expo projects 的可靠打包作为正式版本定义
+- “任何 Expo 项目都能可靠打包成鸿蒙 App”不得被简化成无边界长尾承诺；真实承诺边界是 mainline capability catalog
 - `Managed/CNG` 与 bare workflow 都必须进入稳定交付路径
 - 高频官方 Expo 模块与高频第三方 native blockers 必须已经进入同一公开 capability catalog
 - `doctor -> sync-template -> bundle -> build-hap --mode debug|release` 必须对主线 catalog 内项目形成稳定闭环
@@ -208,7 +253,8 @@
 ## 长期方向
 
 - 所有输入最终都进入同一个 `mainline capability catalog`
-- `v2.0.0` 就是“任何 Expo 项目可靠打包成鸿蒙 App”的正式目标版本
+- `v2.0.0` 就是 catalog-covered Expo projects 可靠打包成鸿蒙 App 的正式目标版本
+- 对 catalog 外项目，正式目标是完整 intake：能分类、能说明 blocker、能给下一步，而不是伪装成已经可靠打包
 - `latest` 只由完整验收能力驱动
 - `next` 用来加速收敛主线 backlog，而不是制造伪 verified 叙事
 - roadmap 的关键问题不再是“要不要把某类项目算进主线”，而是“它何时进入主线、当前缺哪格 evidence、下一步怎么 unblock”

package/docs/support-matrix.md

@@ -1,6 +1,6 @@
-# v1.8 支持矩阵
+# v1.9 支持矩阵
 
-`v1.8` 继续采用 tiered support model，但从现在开始把“层级”与“晋升距离”拆开表达：
+`v1.9` 继续采用 tiered support model，并把“层级”与“晋升距离”拆开表达：
 
 - `supportTier` 表示公开承诺层级
 - `runtimeMode` 表示当前运行时接入形态：`shim`、`adapter`、`verified`
@@ -9,11 +9,12 @@
 - `coverageProfile` 表示当前项目属于哪条主线输入形态
 - `nextActions` 表示 toolkit 为当前项目生成的有序下一步
 
-同时，`v1.8.x` 的 roadmap 已经改成单一 `mainline capability catalog` 方向：
+同时，roadmap 已经改成单一 `mainline capability catalog` 方向：
 
 - bare workflow 与第三方 native package 不再被描述成“收官后才考虑的另一条 extension 终局”
 - `v2.0.0` 本身被定义成“任何 Expo 项目都能可靠打包成鸿蒙 App”的目标版本
 - 但当前公开承诺依旧没有放宽；它们只是进入同一主线 backlog，而不是已经进入 `verified`
+- `v1.9.0` 新增的是 bare intake baseline、app foundation preview shim baseline 与 `react-native-gesture-handler` formal experimental slice，不是 verified 扩容
 
 `doctor --strict` 继续只代表 `verified`。
 
@@ -106,15 +107,22 @@
 | `expo-image-picker` | `preview` | `adapter` | `bundle=yes[automated], debugBuild=yes[automated], device=yes[manual-doc], release=no[none]` | react-native-image-picker, react-native-permissions | ohos.permission.CAMERA、ohos.permission.MICROPHONE、ohos.permission.READ_IMAGEVIDEO | `/image-picker` |
 | `expo-location` | `preview` | `adapter` | `bundle=yes[automated], debugBuild=yes[automated], device=yes[manual-doc], release=no[none]` | @react-native-community/geolocation, react-native-permissions | ohos.permission.LOCATION、ohos.permission.APPROXIMATELY_LOCATION、ohos.permission.LOCATION_IN_BACKGROUND、ohos.permission.ACCELEROMETER | `/location` |
 | `expo-camera` | `preview` | `adapter` | `bundle=yes[automated], debugBuild=yes[automated], device=yes[manual-doc], release=no[none]` | react-native-camera-kit, react-native-permissions | ohos.permission.CAMERA、ohos.permission.MICROPHONE | `/camera` |
+| `expo-secure-store` | `preview` | `shim` | `bundle=yes[automated], debugBuild=yes[automated], device=no[none], release=no[none]` | toolkit-managed bridge | 无新增必需权限 | `/secure-store` |
+| `expo-asset` | `preview` | `shim` | `bundle=yes[automated], debugBuild=yes[automated], device=no[none], release=no[none]` | toolkit-managed bridge | 无新增必需权限 | `/asset` |
+| `expo-device` | `preview` | `shim` | `bundle=yes[automated], debugBuild=yes[automated], device=no[none], release=no[none]` | toolkit-managed bridge | 无新增必需权限 | `/device` |
+| `expo-clipboard` | `preview` | `shim` | `bundle=yes[automated], debugBuild=yes[automated], device=no[none], release=no[none]` | @react-native-oh-tpl/clipboard | 无新增必需权限 | `/clipboard` |
+| `expo-haptics` | `preview` | `shim` | `bundle=yes[automated], debugBuild=yes[automated], device=no[none], release=no[none]` | toolkit-managed bridge | 无新增必需权限 | `/haptics` |
 <!-- GENERATED:support-matrix-preview-capabilities:end -->
 
 说明：
 
 - 当前四项 preview capability 都已经完成 preview baseline 的 bundle / debug build / route walkthrough
 - 四项 preview capability 都已经进入 `adapter` 路径；`device=yes[manual-doc]` 只表示已有人工设备验收记录，仍不代表 verified 或 release-ready
-- 当前 preview baseline 的默认 evidenceSource 固定为：`bundle/debugBuild=automated`、`device=manual-doc`、`release=none`
+- 当前原生 adapter preview baseline 的默认 evidenceSource 固定为：`bundle/debugBuild=automated`、`device=manual-doc`、`release=none`
+- `v1.9.0` 新增的 app foundation modules 当前是 `runtimeMode=shim`，`bundle/debugBuild=automated`，`device/release=none`
 - `v1.8.2` 的 ccnubox release HAP 模拟器安装/启动记录只证明 app-shell release 构建链路，不改变上述 per-capability `release=no[none]`
 - `v1.8.x` 开始，combined sample smoke 只负责总回归；每项 capability 还必须单独维护 device / release acceptance 记录，见 [acceptance/v1.8.x-capability-board.md](../acceptance/v1.8.x-capability-board.md)
+- `v1.8.x` repo 内可完成的 closeout 已完成；剩余 carryover 只包括单 capability 真机 device record 与 release HAP runtime acceptance
 - `expo-file-system`
   - `🟡` 当前主路径是 UTF-8/base64 sandbox I/O、append/partial read、`getInfoAsync({ md5: true })` 与 `downloadAsync`
 - `expo-image-picker`
@@ -129,7 +137,7 @@
 | Expo 能力 / 依赖 | 当前层级 | runtimeMode | evidence | 说明 |
 | --- | --- | --- | --- | --- |
 | `expo-notifications` | `experimental` | `shim` | `bundle=no, debugBuild=no, device=no, release=no` | 服务链路与交付故事未打通 |
-| `react-native-gesture-handler` | `experimental` | matrix 外本地探索 | matrix 外 | 继续保留本地探索 shim，但不在公开 verified 矩阵内 |
+| `react-native-gesture-handler` | `experimental` | `adapter` | `bundle=yes[automated], debugBuild=yes[automated], device=no[none], release=no[none]` | v1.9.0 formal acceptance slice；必须与 `@react-native-oh-tpl/react-native-gesture-handler` 成对接入，仍不在公开 verified 矩阵内 |
 
 ## UI Stack 配对规则
 
@@ -229,7 +237,7 @@ toolkit 受管的核心产物仍包括：
 
 ## Release Tracks
 
-从 `v1.8` 开始，发布节奏按双轨设计：
+从 `v1.8` 开始，发布节奏按双轨设计；`v1.9.0` 继续沿用同一规则：
 
 <!-- GENERATED:support-matrix-release-tracks:start -->
 - `latest`
@@ -255,9 +263,12 @@ toolkit 受管的核心产物仍包括：
 
 `v1.8.2` 记录的 simulator release-HAP evidence 只覆盖 ccnubox app-shell 的 signed HAP 构建、安装和启动；单 capability 的 release acceptance 仍必须按各自记录单独关闭。
 
+`v1.8.x` repo-only closeout 不改变 capability evidence source：`device=yes[manual-doc]` 仍只代表既有人工基线，`release=no[none]` 仍表示没有单 capability release HAP runtime evidence。
+
 ## 当前仍未进入正式公开承诺
 
-- bare Expo
+- bare Expo；当前只进入 intake / debug baseline
+- `expo-secure-store`、`expo-asset`、`expo-device`、`expo-clipboard`、`expo-haptics` 当前仍只是 preview shim baseline
 - 多 Expo / RNOH 并行 verified 矩阵
 - 任意第三方 native package 的即时正式承诺
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-harmony-toolkit",
-  "version": "1.8.3",
+  "version": "1.9.1",
   "description": "面向 Managed/CNG Expo 项目的 HarmonyOS 迁移、准入检查与 UI-stack 构建工具链",
   "main": "app.plugin.js",
   "types": "build/index.d.ts",