expo-harmony-toolkit 1.7.1 → 1.7.3

package/docs/official-native-capabilities-sample.md

@@ -2,12 +2,11 @@
 
 路径：`examples/official-native-capabilities-sample`
 
-这个 sample 是 `v1.7.x` 的官方 preview native-capability walkthrough。它的目标不是把 preview 能力包装成 `verified`，而是把“当前真实支持的核心路径”和“当前明确不支持的边界”都讲清楚。
+这个 sample 是 `v1.7.3` 的官方 preview native-capability walkthrough。它的目标不是把 preview 能力包装成 `verified`，而是把四项能力当前真实可承诺的 `🟡` 子集集中演示出来，并把 preview 边界收敛到真机 / release 证据，而不是接口缺口。
 
 标记说明：
 
 - `🟡` 当前可用子集：这部分已经有可信实现，样例和模拟器路径可用；下一步主要缺真机 / release 证据
-- `🟠` 当前未纳入子集：包本身已进入 `preview`，但这个具体子 API 还没有到可信对外承诺；这不是“只差真机”
 
 ## 当前覆盖
 
@@ -29,20 +28,13 @@
 
 `🟡 当前可用子集`：
 
-- 创建 sandbox 目录
-- UTF-8 写入
-- 读回内容
-- `getInfoAsync`
-- `readDirectoryAsync`
-- `copyAsync`
-- `moveAsync`
-- 删除生成产物
-
-`🟠 当前未纳入子集`：
-
-- `base64`
+- sandbox 目录创建
+- UTF-8 写入 / 读回
+- base64 roundtrip
+- append / partial read
+- `getInfoAsync({ md5: true })`
 - `downloadAsync`
-- 更广的 Expo parity
+- 清理生成产物
 
 ### `/image-picker`
 
@@ -50,52 +42,42 @@
 
 - media permission
 - camera permission
-- 单图图库选择
-- 单次系统相机拍照
-- denied / canceled / successful asset 三类结果展示
-
-`🟠 当前未纳入子集`：
-
-- `getPendingResultAsync` 的完整 Expo parity
-- 多选、多媒体、更深一层的系统恢复语义
+- 单选图库选择
+- 多选图库选择
+- mixed image+video library selection
+- system photo capture
+- system video capture
+- pending result 恢复
+- image / video asset metadata 展示
 
 ### `/location`
 
 `🟡 当前可用子集`：
 
 - foreground permission
+- background permission
 - `getCurrentPositionAsync`
-- `getLastKnownPositionAsync`
+- `watchPositionAsync`
+- `getHeadingAsync`
+- `watchHeadingAsync`
 - `geocodeAsync`
 - `reverseGeocodeAsync`
 
-`🟠 当前未纳入子集`：
-
-- `watchPositionAsync`
-- background permission parity
-- `watchHeadingAsync`
-- `getHeadingAsync`
+说明：
 
-这些 `🟠` 项不是“已经实现，只差真机验证”，而是当前还没补齐到可信实现，所以暂时不纳入对外可承诺子集。
+- 背景权限按 Harmony 的独立后台权限契约暴露，不伪装成 Expo 的完全同构平台行为
+- heading 使用 Harmony 传感器方向语义，属于最接近 Expo 的等价语义，不复用 GPS `direction`
 
 ### `/camera`
 
 `🟡 当前可用子集`：
 
-- camera permission
-- 通过 Harmony system camera UI 完成 still-photo capture
-- 把返回 asset metadata 回传给 JS
-- denied / canceled / successful capture 三类结果展示
-
-`🟠 当前未纳入子集`：
-
-- embedded live preview
+- embedded `CameraView` preview
 - `pausePreview` / `resumePreview`
-- microphone permission parity
-- video recording
-- scanning APIs 之外的更深 Expo parity
-
-这些 `🟠` 项不是“已经实现，只差真机验证”，而是当前还没补齐到可信实现，所以暂时不纳入对外可承诺子集。
+- still photo capture
+- video recording start / stop / toggle
+- microphone permission snapshot
+- denied / canceled / successful result 展示
 
 ## 推荐命令
 
@@ -126,7 +108,7 @@ pnpm run harmony:doctor:strict
 如果要继续验证 release 构建，先准备本地签名覆盖文件：
 
 ```bash
-mkdir -p .expo-harmony
+cp .expo-harmony/signing.local.example.json .expo-harmony/signing.local.json
 $EDITOR .expo-harmony/signing.local.json
 pnpm run harmony:env
 pnpm run harmony:build:release
@@ -134,6 +116,7 @@ pnpm run harmony:build:release
 
 说明：
 
+- `.expo-harmony/signing.local.example.json` 是可直接复制的本地 signing 範本
 - `.expo-harmony/signing.local.json` 是本地 signing 入口
 - toolkit 会把本地 signing 合并进 `harmony/build-profile.json5`
 - 即使 release 构建可走通，在没有真机前，这四项能力也仍保持 `preview`
@@ -142,7 +125,5 @@ pnpm run harmony:build:release
 
 - 这个 sample 属于 `preview` 主线，不等于已经进入 `verified`
 - `doctor-report.json` 与 `toolkit-config.json` 中的 `runtimeMode` / `evidence.*` 会如实反映这些能力距离 verified 还缺哪些证据
-- `🟡` 项可以理解为“只差真机 / release 证据的下一步”
-- `🟠` 项不能理解成“只差真机”，因为当前实现边界本身还没有补齐
 - 当前重点是“模拟器下真正可用、核心流清楚、文档一致”
 - 等未来补齐真机 gate 后，才讨论 capability promotion

package/docs/official-ui-stack-sample.md

@@ -47,7 +47,7 @@ pnpm run harmony:build:debug
 如果要继续验证 release 构建，先准备本地签名覆盖文件：
 
 ```bash
-mkdir -p .expo-harmony
+cp .expo-harmony/signing.local.example.json .expo-harmony/signing.local.json
 $EDITOR .expo-harmony/signing.local.json
 pnpm run harmony:env
 pnpm run harmony:build:release
@@ -55,6 +55,7 @@ pnpm run harmony:build:release
 
 说明：
 
+- `.expo-harmony/signing.local.example.json` 是可直接复制的本地 signing 範本
 - `.expo-harmony/signing.local.json` 是本地 signing 入口
 - signing 缺失时，release 构建应明确失败，而不是假成功
 

package/docs/signing-and-release.md

@@ -27,6 +27,7 @@ expo-harmony env
 
 - `debug` 构建仍可继续做本地验证
 - `release` 构建不应视为 ready
+- 可以直接从 `.expo-harmony/signing.local.example.json` 复制出 `.expo-harmony/signing.local.json` 再填入真实材料
 
 ## 推荐流程
 
@@ -40,6 +41,8 @@ expo-harmony build-hap --mode debug
 ### Release 验证
 
 ```bash
+cp .expo-harmony/signing.local.example.json .expo-harmony/signing.local.json
+$EDITOR .expo-harmony/signing.local.json
 expo-harmony env
 expo-harmony build-hap --mode release
 ```

package/docs/support-matrix.md

@@ -5,6 +5,7 @@
 - `supportTier` 表示公开承诺层级
 - `runtimeMode` 表示当前运行时接入形态：`shim`、`adapter`、`verified`
 - `evidence` 表示距离 verified 还缺哪些证据格
+- `evidenceSource` 表示每个证据格来自自动化、人工记录，还是当前无证据
 
 `doctor --strict` 继续只代表 `verified`。
 
@@ -12,6 +13,7 @@
 
 唯一 `verified` 矩阵仍是 `expo55-rnoh082-ui-stack`。
 
+<!-- GENERATED:support-matrix-verified-matrix:start -->
 | 项目 | 要求 |
 | --- | --- |
 | Expo SDK | `55` |
@@ -21,9 +23,10 @@
 | `@react-native-oh/react-native-harmony-cli` | `0.82.18` |
 | `@react-native-community/cli` | `20.x` |
 | `metro` | `0.83.x` |
-| App Shell 依赖 | `expo-router` `6.x`、`expo-linking` `55.x`、`expo-constants` `55.x` |
+| App Shell 依赖 | `expo-router` `55.x`、`expo-linking` `55.x`、`expo-constants` `55.x`、`@expo/metro-runtime` `55.x`、`react-dom` `19.1.1` |
 | UI stack 依赖 | `react-native-reanimated` `3.6.0`、`react-native-svg` `15.0.0` |
 | 原生标识 | 至少设置 `android.package` 或 `ios.bundleIdentifier` |
+<!-- GENERATED:support-matrix-verified-matrix:end -->
 
 ## Support Tiers
 
@@ -36,26 +39,31 @@
 
 ## Verified Allowlist
 
+<!-- GENERATED:support-matrix-verified-allowlist:start -->
 - `expo`
+- `@expo/metro-runtime`
 - `expo-constants`
 - `expo-linking`
 - `expo-router`
 - `react`
+- `react-dom`
 - `react-native`
 - `expo-status-bar`
 - `@babel/runtime`
 - `@react-native-community/cli`
 - `metro`
-- `expo-harmony-toolkit`
 - `@react-native-oh/react-native-harmony`
 - `@react-native-oh/react-native-harmony-cli`
+- `expo-harmony-toolkit`
 - `react-native-reanimated`
-- `react-native-svg`
 - `@react-native-oh-tpl/react-native-reanimated`
+- `react-native-svg`
 - `@react-native-oh-tpl/react-native-svg`
+<!-- GENERATED:support-matrix-verified-allowlist:end -->
 
 ## Capability Telemetry
 
+<!-- GENERATED:support-matrix-capability-telemetry:start -->
 所有 capability 从现在开始都同时公开：
 
 - `supportTier`
@@ -64,42 +72,47 @@
 - `evidence.debugBuild`
 - `evidence.device`
 - `evidence.release`
+- `evidenceSource.bundle`
+- `evidenceSource.debugBuild`
+- `evidenceSource.device`
+- `evidenceSource.release`
 
 判读规则：
 
 - `runtimeMode=shim`：说明当前还在桥接或占位阶段，即使 bundle / debug build 已完成，也不应宣称 verified
 - `runtimeMode=adapter`：说明已经进入真实适配路径，但仍缺少某些验收证据
 - `runtimeMode=verified`：说明能力已进入正式承诺，且证据闭环完成
+<!-- GENERATED:support-matrix-capability-telemetry:end -->
 
 为了避免把“只差真机”与“当前子 API 还没实现到位”混在一起，`v1.7.x` 文档额外使用以下标记：
 
 - `🟡 可用待晋升`：当前子集已经有可信实现，样例和模拟器路径可用；下一步主要缺真机 / release 证据
-- `🟠 未纳入当前子集`：包本身已进入 `preview`，但这个具体子 API 还没有到可信对外承诺；这不是“只差真机”
 - `⛔ 完全不支持`：能力仍在 catalog 外，或根本不在当前公开承诺范围
 
 ## Preview 能力
 
+<!-- GENERATED:support-matrix-preview-capabilities:start -->
 | Expo 能力 | 当前层级 | runtimeMode | evidence | Harmony 依赖方向 | 受管权限 | 官方 sample route |
 | --- | --- | --- | --- | --- | --- | --- |
-| `expo-file-system` | `preview` | `adapter` | `bundle=yes, debugBuild=yes, device=yes, release=no` | toolkit-managed sandbox file adapter | 无新增必需权限 | `/file-system` |
-| `expo-image-picker` | `preview` | `adapter` | `bundle=yes, debugBuild=yes, device=yes, release=no` | toolkit-managed Harmony media picker adapter | `ohos.permission.CAMERA`、`ohos.permission.READ_IMAGEVIDEO` | `/image-picker` |
-| `expo-location` | `preview` | `adapter` | `bundle=yes, debugBuild=yes, device=yes, release=no` | toolkit-managed `@ohos.geoLocationManager` TurboModule | `ohos.permission.LOCATION`、`ohos.permission.APPROXIMATELY_LOCATION` | `/location` |
-| `expo-camera` | `preview` | `adapter` | `bundle=yes, debugBuild=yes, device=yes, release=no` | toolkit-managed `@ohos.multimedia.cameraPicker` TurboModule | `ohos.permission.CAMERA` | `/camera` |
+| `expo-file-system` | `preview` | `adapter` | `bundle=yes[automated], debugBuild=yes[automated], device=yes[manual-doc], release=no[none]` | react-native-fs | 无新增必需权限 | `/file-system` |
+| `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` |
+<!-- GENERATED:support-matrix-preview-capabilities:end -->
 
 说明：
 
 - 当前四项 preview capability 都已经完成 preview baseline 的 bundle / debug build / route walkthrough
-- 四项 preview capability 都已经进入 `adapter` 路径；`device=yes` 只表示已有样例侧与运行时路径证据，仍不代表 verified 或 release-ready
+- 四项 preview capability 都已经进入 `adapter` 路径；`device=yes[manual-doc]` 只表示已有人工设备验收记录，仍不代表 verified 或 release-ready
+- 当前 preview baseline 的默认 evidenceSource 固定为：`bundle/debugBuild=automated`、`device=manual-doc`、`release=none`
 - `expo-file-system`
-  - `🟡` 当前主路径是 UTF-8 sandbox I/O，包括目录创建、读写、复制、移动与删除
+  - `🟡` 当前主路径是 UTF-8/base64 sandbox I/O、append/partial read、`getInfoAsync({ md5: true })` 与 `downloadAsync`
 - `expo-image-picker`
-  - `🟡` 当前主路径是单图图库选择、单次系统相机拍照，以及 denied / canceled / successful asset 结果展示
+  - `🟡` 当前主路径是单选、多选、mixed library selection、system photo/video capture、pending result 恢复，以及 image/video metadata 展示
 - `expo-location`
-  - `🟡` 当前主路径是前台权限、current / last-known / geocode / reverse-geocode
-  - `🟠` `watchPositionAsync`、背景权限与 heading API 当前未纳入 v1.7.x 可承诺子集；这不是“只差真机”，而是实现还没补齐到可信状态
+  - `🟡` 当前主路径是 foreground/background permission、current / watch、heading snapshot/watch、geocode / reverse-geocode
 - `expo-camera`
-  - `🟡` 当前主路径是相机权限与通过系统相机 UI 的 still capture
-  - `🟠` embedded preview、preview pause/resume、microphone、video 当前未纳入 v1.7.x 可承诺子集；这不是“只差真机”，而是实现还没补齐到可信状态
+  - `🟡` 当前主路径是 embedded preview、preview pause/resume、still capture、video recording 与 microphone permission
 
 ## Experimental 能力
 
@@ -110,6 +123,7 @@
 
 ## UI Stack 配对规则
 
+<!-- GENERATED:support-matrix-ui-stack:start -->
 canonical 包与 Harmony adapter 包固定为双向强制：
 
 - `react-native-reanimated` ↔ `@react-native-oh-tpl/react-native-reanimated`
@@ -126,6 +140,7 @@ canonical 包与 Harmony adapter 包固定为双向强制：
 
 - `@react-native-oh-tpl/react-native-reanimated`: `github:react-native-oh-library/react-native-harmony-reanimated#9fdbe676209937383907be0592291223c6ca7ad7&path:react-native-harmony-reanimated`
 - `@react-native-oh-tpl/react-native-svg`: `github:react-native-oh-library/react-native-harmony-svg#97c31d2f72559931d62fa84a9c86e86d343753d3&path:react-native-harmony-svg`
+<!-- GENERATED:support-matrix-ui-stack:end -->
 
 ## `doctor`
 
@@ -150,10 +165,15 @@ expo-harmony doctor --project-root /path/to/app --target-tier preview
 - `capabilities[].evidence.debugBuild`
 - `capabilities[].evidence.device`
 - `capabilities[].evidence.release`
+- `capabilities[].evidenceSource.bundle`
+- `capabilities[].evidenceSource.debugBuild`
+- `capabilities[].evidenceSource.device`
+- `capabilities[].evidenceSource.release`
 
 判读方式：
 
 - 任一 `evidence.* = false`，表示晋升到 verified 前仍缺证据
+- `evidenceSource.device = manual-doc`，表示该证据来自人工验收记录，不应被表述成自动化设备验证
 - `runtimeMode !== verified`，表示即使已有部分证据，也仍不属于正式承诺
 
 当前公开阻断 issue code 继续包括：
@@ -187,13 +207,14 @@ toolkit 受管的核心产物仍包括：
 
 - `entry/src/main/module.json5` 的 `requestPermissions` 由 toolkit 根据已启用能力自动补齐
 - preview / experimental 能力的 Metro import path 通过 `.expo-harmony/shims/<package>` 接管
-- `toolkit-config.json` 会记录 capability 的 `runtimeMode` 与 `evidence`
+- `toolkit-config.json` 会记录 capability 的 `runtimeMode`、`evidence` 与 `evidenceSource`
 - verified UI stack 依赖继续走现有 autolinking + `.har` 管理逻辑
 
 ## Release Tracks
 
 从 `v1.8` 开始，发布节奏按双轨设计：
 
+<!-- GENERATED:support-matrix-release-tracks:start -->
 - `latest`
   - 只承接完整验收的 `verified` 能力
   - 只允许 verified sample / gate 作为发布依据
@@ -201,6 +222,7 @@ toolkit 受管的核心产物仍包括：
   - 承接 preview fast track
   - 必须至少通过 preview sample、bundle、debug build gate
   - 不得被描述为 verified 或 release-ready
+<!-- GENERATED:support-matrix-release-tracks:end -->
 
 ## Capability Promotion Gate
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-harmony-toolkit",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "description": "面向 Managed/CNG Expo 项目的 HarmonyOS 迁移、准入检查与 UI-stack 构建工具链",
   "main": "app.plugin.js",
   "types": "build/index.d.ts",
@@ -23,12 +23,21 @@
     "README.md",
     "README.en.md",
     "LICENSE",
-    "docs"
+    "docs/cli-build.md",
+    "docs/npm-release.md",
+    "docs/official-app-shell-sample.md",
+    "docs/official-minimal-sample.md",
+    "docs/official-native-capabilities-sample.md",
+    "docs/official-ui-stack-sample.md",
+    "docs/roadmap.md",
+    "docs/signing-and-release.md",
+    "docs/support-matrix.md"
   ],
   "scripts": {
-    "build": "tsc --project tsconfig.json",
+    "build": "rm -rf build && tsc --project tsconfig.json",
     "clean": "rm -rf build coverage",
-    "pack:check": "npm pack --dry-run",
+    "docs:sync": "node ./scripts/update-generated-docs.js",
+    "pack:check": "node ./scripts/pack.js --dry-run --json",
     "release:check": "node ./scripts/release-check.js",
     "test": "jest --runInBand",
     "prepare": "pnpm build"
@@ -77,7 +86,6 @@
     "@types/jest": "^30.0.0",
     "@types/node": "^24.5.2",
     "@types/semver": "^7.7.1",
-    "expo": "^55.0.8",
     "jest": "^30.2.0",
     "ts-jest": "^29.4.4",
     "typescript": "^5.9.2"