commit 561af4781762086459e32126237f119ae6a5aff9
Author: Joywayer <joywayer@163.com>
Date:   Thu Jun 25 06:25:30 2026 +0800

    first commit

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..d2ff201
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,12 @@
+/node_modules
+/oh_modules
+/local.properties
+/.idea
+**/build
+/.hvigor
+.cxx
+/.clangd
+/.clang-format
+/.clang-tidy
+**/.test
+/.appanalyzer
\ No newline at end of file
diff --git a/.mcp.json b/.mcp.json
new file mode 100644
index 0000000..6c42a04
--- /dev/null
+++ b/.mcp.json
@@ -0,0 +1,16 @@
+{
+  "mcpServers": {
+    "deveco-mcp": {
+      "type": "stdio",
+      "command": "devecocli",
+      "args": [
+        "serve",
+        "mcp"
+      ],
+      "env": {
+        "PROJECT_PATH": "G:\\Works\\YouleApp\\harmonyos\\gamelobby"
+      },
+      "enabled": true
+    }
+  }
+}
\ No newline at end of file
diff --git a/AppScope/app.json5 b/AppScope/app.json5
new file mode 100644
index 0000000..a247b28
--- /dev/null
+++ b/AppScope/app.json5
@@ -0,0 +1,11 @@
+{
+  "app": {
+    "bundleName": "com.example.gamelobby",
+    "vendor": "example",
+    "versionCode": 1000000,
+    "versionName": "1.0.0",
+    "buildVersion": "1",
+    "icon": "$media:layered_image",
+    "label": "$string:app_name"
+  }
+}
diff --git a/AppScope/resources/base/element/string.json b/AppScope/resources/base/element/string.json
new file mode 100644
index 0000000..26498de
--- /dev/null
+++ b/AppScope/resources/base/element/string.json
@@ -0,0 +1,8 @@
+{
+  "string": [
+    {
+      "name": "app_name",
+      "value": "GameLobby"
+    }
+  ]
+}
diff --git a/AppScope/resources/base/media/background.png b/AppScope/resources/base/media/background.png
new file mode 100644
index 0000000..923f2b3
Binary files /dev/null and b/AppScope/resources/base/media/background.png differ
diff --git a/AppScope/resources/base/media/foreground.png b/AppScope/resources/base/media/foreground.png
new file mode 100644
index 0000000..eb94275
Binary files /dev/null and b/AppScope/resources/base/media/foreground.png differ
diff --git a/AppScope/resources/base/media/layered_image.json b/AppScope/resources/base/media/layered_image.json
new file mode 100644
index 0000000..fb49920
--- /dev/null
+++ b/AppScope/resources/base/media/layered_image.json
@@ -0,0 +1,7 @@
+{
+  "layered-image":
+  {
+    "background" : "$media:background",
+    "foreground" : "$media:foreground"
+  }
+}
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..7d38e47
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,93 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 项目概述
+
+HarmonyOS NEXT（API 12+，目标 SDK `6.1.1(24)`，runtimeOS `HarmonyOS`）上的 **TSGame 游戏大厅原生外壳**。目标：用 ArkTS / ArkUI 声明式 / Stage 模型重写原 Android WebView 外壳，使现有 H5（大厅 + 全部子游戏 + 活动/收银台等网页）**一行不改**即可运行。
+
+当前处于 **M0 脚手架阶段**：`entry/` 仍是 DevEco 默认模板（`Index.ets` 为 Hello World），尚未落地设计文档中的多模块架构。实现工作以 `docs/设计文档/` 为唯一依据推进。
+
+**原 Android 项目位于 `../tsgame_android`**（相对本仓库根目录）——即本项目要复刻的 WebView 外壳源头。遇到契约/行为存疑时，以该 Android 工程的实际实现为准对照。
+
+## 工作约定
+
+- **🔴 H5 零改动是最高铁律**：H5 网页（大厅 + 全部子游戏）必须**完美适配新项目，不做任何修改**。所有适配工作只能发生在原生侧——H5 向原生注册的接口、原生向 H5 注册的接口、双向接口的调用时机/参数/数据结构，全部以《契约规范》为准、与原 Android 行为完全一致。**任何"改一下 H5 就好了"的方案都不被接受**；H5 行为存疑时改原生实现去迁就 H5，而非反过来。这是判断一切技术方案是否成立的首要判据。
+- **原生内部实现自由**：在不违背上述铁律的前提下，原生侧的内部实现（分层、模块拆分、数据结构、设计模式、用何种 HarmonyOS API/SDK、性能优化手段等）可以**根据实际情况自由设计**，不必拘泥于原 Android 的内部写法或设计文档的伪代码细节。铁律只约束"对 H5 暴露的边界行为"，边界以内怎么实现由开发者按 HarmonyOS 最佳实践决定。
+- **及时自动提交 git**：每完成一个可独立验收的小步骤（一个 Provider、一个状态机节点、一处可编译通过的改动）后，**主动执行 git 提交**，无需等待用户要求。提交信息用中文、说明"做了什么 + 对应契约/设计条目（如 §8、T-M1-04）"。⚠️ 仓库当前尚未 `git init`，首次提交前需先初始化。
+- HarmonyOS 相关操作（构建、运行、调试、设备、日志、查文档/SDK 签名）**必须**走 `deveco-cli` skill / `devecocli`，不要手搓 `hvigorw` 命令或直连 MCP HTTP 桥。
+- **禁止直接编辑 `project.godot` 类生成文件**；本项目对应的是 **不要手改 `oh-package-lock.json5`、`build/` 产物、`.hvigor/`**——它们由工具生成。
+
+## 常用命令
+
+构建/运行/测试统一通过 `devecocli`（见 `deveco-cli` skill）：
+
+- 构建 HAP（debug）：`devecocli build`（底层 hvigor `assembleHap`，产物 `entry/build/default/...`）
+- 运行到设备/模拟器：`devecocli run`；设备列表 `devecocli devices`
+- 真机/模拟器日志：`devecocli log`（hilog）
+- 查 SDK API 签名 / 鸿蒙文档：`devecocli docs <关键词>`（编码前核对 `@ohos.*` / `@kit.*` 实际签名）
+
+测试（Hypium，`@ohos/hypium` + `@ohos/hamock`）：
+
+- 本地单元测试：`entry/src/test/`（`LocalUnit.test.ets`、`List.test.ets`）——纯逻辑，不依赖设备
+- 设备插桩测试：`entry/src/ohosTest/`（`Ability.test.ets` 等）——需真机/模拟器
+- 通过 `devecocli test` 触发；目标：桥引擎 / `VersionResolver` / `MessageCodec` 单测覆盖率 **≥80%**
+
+代码检查（`code-linter.json5`，仅作用于 `**/*.ets`）：
+
+- 规则集 `@performance/recommended` + `@typescript-eslint/recommended`
+- **`@security/no-unsafe-*` 一组加密规则为 `error`**：禁用不安全的 AES/Hash/MAC/DH/DSA/ECDSA/RSA/3DES，写加密代码时务必遵守
+
+## 架构（big picture，需读多文件才能掌握）
+
+> 真正的架构在设计文档里，代码尚未落地。三份 SSOT 文档（修改实现前必读对应章节）：
+> - `docs/设计文档/TSGame_原生与H5接口契约总规范.md` —— **对外不可变契约**（H5 零改动的判据：handler 名、参数、数据结构、调用时机）
+> - `docs/设计文档/TSGame_HarmonyOS框架设计与开发指南.md` —— HarmonyOS 侧如何实现（分层、桥、容器、启动）
+> - `docs/设计文档/Plan/` —— 落地计划：`00_总体规划` / `01_任务分解WBS`（任务 ID `T-M{里程碑}-{序号}`）/ `02_测试与验收` / `03_风险登记册`
+
+### 分层（依赖单向向下，跨层只依赖接口）
+
+```
+① 应用/编排层  EntryAbility · StartupOrchestrator · 路由 · DI 组装根(AppModule)
+② 容器层       BridgeGameContainer(大厅/子游戏) │ GenericWebContainer(通用网页)
+③ 桥引擎层     BridgeController · MessageCodec · HandlerRegistry · SettingsProxy
+④ 能力层       每个原生能力 = 一个 CapabilityProvider 插件(share/login/location/...)
+⑤ 领域服务层   ConfigManager · ResourceManager · AppDataInjector · VersionResolver
+⑥ 平台服务层   HttpClient · Downloader · Unzipper · KvStore · LocalUploadServer · TaskScheduler
+横切层         Logger/Tracer · ErrorCenter · EventBus · DIContainer · Contracts(TS类型 SSOT)
+```
+
+目标多模块拆分（HAR/HSP）：`entry`(①②) / `feature_bridge`(③) / `feature_capabilities`(④) / `domain_resource`(⑤) / `platform`(⑥) / `contracts`(契约类型) / `common`(横切)。
+
+### 三条不可违背的关键约束
+
+1. **桥核心对能力零感知**：`feature_bridge` 不 import 任何具体能力，只持 `HandlerRegistry`；能力启动时把自己的 handler 注册进去。新增能力 = 新增一个 `CapabilityProvider`，零侵入桥核心。`contracts` HAR 用 `enum`/`interface` 固化所有 handler 名与 DTO，是全工程唯一来源（杜绝 `finsh`/`getcameraaAddress` 等拼写漂移）。
+2. **出站下发必须在 UI 线程**（§5.5）：`runJavaScript` 只能在 UI 线程调用，而能力回调常在非 UI 线程。`BridgeController.dispatch` 内置 UI 线程守卫；Provider 不关心线程，任意线程 `callHandler` 最终都在 UI 线程下发。
+3. **TaskPool 只搬 Sendable**（§9.1）：`@Concurrent` 任务跨线程传参/返回值必须是 Sendable，**不能传** callback / `WebviewController` / `UIAbilityContext`。下载/解压进度一律经 `emitter`/`AppStorage` 回 UI 线程，不要跨线程传函数。
+
+### 桥协议核心（"H5 零改动"命门，100% 复刻 lzyzsd/JsBridge）
+
+- H5→原生：`Web().onLoadIntercept` 拦截 `yy://`（含 iframe 导航）；`yy://return/` 前缀走回执，其余触发 `flushMessageQueue()`。
+- **队列回传不靠 `runJavaScript` 返回值**：`_fetchQueue()` 在 H5 内把 `iframe.src` 置为 `yy://return/_fetchQueue/<队列JSON>`，再次经 `onLoadIntercept` → `handleReturnData` 路由到预登记的 `_fetchQueue` 回调。务必忠实复刻此机制。
+- 原生→H5：`controller.runJavaScript("WebViewJavascriptBridge._handleMessageFromNative('"+json+"');")`；桥 JS 在 `onPageEnd` 注入（直接复用库原文件）。
+- **必须设 `DefaultHandler`（空实现）**：未注册的 handler 名落到默认空实现而不抛错，是"H5 调用永不报错"的最后防线。
+
+### 双容器模型
+
+- **BridgeGameContainer**（大厅/子游戏，对应 Android `webviewActivity`）：挂桥协议；`app_data.js` 必须在**加载页面之前**由 `AppDataInjector` 写入（H5 同步 `<script src>` 读取），切勿放到 `onPageEnd`；`setPostUrl`/`appservice` 在首次进度 100% 时下发。子游戏切换 = 同容器 `loadUrl`，不重建组件。
+- **GenericWebContainer**（通用网页，对应 `openwebActivity1`）：**不挂桥**，用 `javaScriptProxy` 注入 `settings` 对象（6 方法）+ `runJavaScript` 直调；回传走结果码 101 语义经 `emitter`/路由投回上层 Bridge 容器。
+
+### 本期范围与占位桩
+
+本期实现分享/登录/定位/音频/摇一摇/扫码/相机/震动/剪贴板/网络/设备等 Provider。**视频房（声网）与支付用占位桩**（`RoomStubProvider`/`PayStubProvider`，§6.5）：仍注册 handler，但 void 型空实现、有同步返回的回安全默认值、绝不触发出站推送——保证 H5 调用不报错、不卡死。**闲聊不涉及**（无 H5 桥接口）。组装根 `buildCapabilities()` 是唯一知道"全部能力"的地方，未来换回真实 Provider 即可。
+
+### 两个最高风险"阻塞性验证"（必须最先证伪）
+
+- **M1**：`yy://` 的 iframe 导航是否稳定触发 `onLoadIntercept`（不同 ArkWeb 版本有差异）。失败回退：`onInterceptRequest`+`WebSchemeHandler` → 或改注入 `javaScriptProxy` 同步通道（对 H5 仍透明）。
+- **M2**：`file://` 加载下 H5 的 XHR/fetch 取本地资源是否可用。失败启用官方跨域方案（自定义协议 / `onInterceptRequest`）。
+
+### 生产加固红线（附录 B）
+
+- `setWebDebuggingAccess(true)` **仅 debug 包**（`BuildProfile.DEBUG` 守卫），release 必关。
+- 密钥（微信 `AppSecret`、支付 `API_KEY`）**不入客户端**：登录走 code、支付签名走服务端。
+- 明文 HTTP 域名需在 `module.json5` 网络安全配置显式放行；`gamepaywelcome` 等外部唤起 scheme 在 `abilities.skills.uris` 声明。
diff --git a/build-profile.json5 b/build-profile.json5
new file mode 100644
index 0000000..0cb46cc
--- /dev/null
+++ b/build-profile.json5
@@ -0,0 +1,42 @@
+{
+  "app": {
+    "signingConfigs": [],
+    "products": [
+      {
+        "name": "default",
+        "signingConfig": "default",
+        "targetSdkVersion": "6.1.1(24)",
+        "compatibleSdkVersion": "6.1.1(24)",
+        "runtimeOS": "HarmonyOS",
+        "buildOption": {
+          "strictMode": {
+            "caseSensitiveCheck": true,
+            "useNormalizedOHMUrl": true
+          }
+        }
+      }
+    ],
+    "buildModeSet": [
+      {
+        "name": "debug",
+      },
+      {
+        "name": "release"
+      }
+    ]
+  },
+  "modules": [
+    {
+      "name": "entry",
+      "srcPath": "./entry",
+      "targets": [
+        {
+          "name": "default",
+          "applyToProducts": [
+            "default"
+          ]
+        }
+      ]
+    }
+  ]
+}
\ No newline at end of file
diff --git a/code-linter.json5 b/code-linter.json5
new file mode 100644
index 0000000..073990f
--- /dev/null
+++ b/code-linter.json5
@@ -0,0 +1,32 @@
+{
+  "files": [
+    "**/*.ets"
+  ],
+  "ignore": [
+    "**/src/ohosTest/**/*",
+    "**/src/test/**/*",
+    "**/src/mock/**/*",
+    "**/node_modules/**/*",
+    "**/oh_modules/**/*",
+    "**/build/**/*",
+    "**/.preview/**/*"
+  ],
+  "ruleSet": [
+    "plugin:@performance/recommended",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "rules": {
+    "@security/no-unsafe-aes": "error",
+    "@security/no-unsafe-hash": "error",
+    "@security/no-unsafe-mac": "warn",
+    "@security/no-unsafe-dh": "error",
+    "@security/no-unsafe-dsa": "error",
+    "@security/no-unsafe-ecdsa": "error",
+    "@security/no-unsafe-rsa-encrypt": "error",
+    "@security/no-unsafe-rsa-sign": "error",
+    "@security/no-unsafe-rsa-key": "error",
+    "@security/no-unsafe-dsa-key": "error",
+    "@security/no-unsafe-dh-key": "error",
+    "@security/no-unsafe-3des": "error"
+  }
+}
\ No newline at end of file
diff --git a/docs/设计文档/Plan/00_总体规划.md b/docs/设计文档/Plan/00_总体规划.md
new file mode 100644
index 0000000..e5d2abb
--- /dev/null
+++ b/docs/设计文档/Plan/00_总体规划.md
@@ -0,0 +1,98 @@
+# 00 · 总体规划
+
+## 1. 里程碑总览
+
+| 里程碑 | 主题 | 出口判据（Exit Gate） | 估时 | 可并行 |
+|---|---|---|---|---|
+| **M0** | 工程脚手架 + 契约类型 | 多模块工程可编译、可签名、CI 跑通；`contracts` 全量类型就位 | 3–4 人日 | — |
+| **M1** | 桥引擎（最高优先） | 最小回显 H5 跑通；**`yy://` 拦截阻塞性验证通过**；桥引擎单测 ≥80% | 6–8 人日 | — |
+| **M2** | 容器 + 启动 + 资源 | 真机加载现有大厅 H5、能进子游戏；**`file://` 跨域阻塞性验证通过** | 8–10 人日 | 平台层/配置/资源三轨并行 |
+| **M3** | 本期能力（含占位桩） | 本期能力真机逐条对照契约通过；视频房/支付桩不报错不卡死 | 14–18 人日 | **各 Provider 高度并行** |
+| **M4** | 通用网页容器 | 活动页/收银台/客服打开、`settings` 6 法 + 3 直调 + 101 回传一致 | 3–4 人日 | 可与 M3 尾段并行 |
+| **M5** | 性能与加固 | 切换流畅、冷启动达标、安全审查通过、全链路可观测 | 6–8 人日 | 部分可贯穿 M3/M4 |
+| **M6** | 暂缓能力集成（按需） | 真实视频房/支付打通，H5 仍零改动 | 视集成而定 | 独立 |
+
+> 总估时（M0–M5，不含 M6）：约 **40–52 人日**。按 3 人并行、关键路径串行估算，日历周期约 **5–7 周**。
+
+## 2. 关键路径与依赖 DAG
+
+```
+M0 脚手架/契约类型
+   │
+   ▼
+M1 桥引擎 ──(⚠ yy:// 拦截验证 = 整体可行性闸门)
+   │
+   ▼
+M2 容器+启动+资源 ──(⚠ file:// 跨域验证 = 第二闸门)
+   │
+   ├──────────────┬───────────────┐
+   ▼              ▼               ▼
+M3 能力(并行)   M4 通用网页容器   M5 性能/加固(贯穿)
+   │              │               │
+   └──────────────┴───────────────┘
+                  │
+                  ▼
+            本期验收（H5 零改动）
+                  │
+                  ▼
+            M6 暂缓能力按需集成
+```
+
+**关键路径**：`M0 → M1 → M2 → M3 → 验收`。M1/M2 的两个阻塞性验证是**最高风险节点**，必须前置（见 §5）。
+
+## 3. 并行轨道（提升效率的关键）
+
+| 轨道 | 启动条件 | 内容 |
+|---|---|---|
+| **轨道 A：桥/容器** | 立即 | M1 桥引擎 → M2 容器 → M4 通用容器 |
+| **轨道 B：平台/领域** | M0 完成后即可（不必等 M1） | 平台层（Http/Download/Unzip/KvStore/Permission/TaskPool）、ConfigManager、VersionResolver、ResourceManager、StartupOrchestrator |
+| **轨道 C：能力 Provider** | M1+M2 出口后 | 14+ 个 Provider **彼此独立**，可多人同时领，互不阻塞（依赖 contracts + bridge 接口已稳定） |
+| **轨道 D：质量/工程** | 贯穿全程 | CI、单测、契约一致性回归、可观测、安全加固 |
+
+> **效率要点**：轨道 B 大量纯逻辑（VersionResolver/MessageCodec/ConfigManager）**不依赖真机**，可在 M1 进行时并行开发并单测；能力 Provider 在 M3 高度并行是压缩工期的核心。
+
+## 4. 角色分工建议（按能力域，非按人头）
+
+| 角色 | 职责 | 主要任务 |
+|---|---|---|
+| **桥/容器负责人** | feature_bridge、容器、ArkWeb | M1 全部、M2 容器、M4、M5 性能 |
+| **平台/领域负责人** | platform、domain_resource | M2 平台/配置/资源/启动 |
+| **能力工程师 ×N** | feature_capabilities | M3 各 Provider（按 SDK 熟悉度分配：分享/支付/定位/媒体…） |
+| **QA/测试** | 契约一致性、真机回归 | 测试计划、回显 H5、44 handler 逐条核对 |
+| **技术负责人** | 架构守门、阻塞性验证决策 | 评审两个阻塞验证结果、风险闸门 |
+
+## 5. 阻塞性验证（必须前置，决定整体技术路线）
+
+| 验证 | 里程碑 | 通过判据 | 不通过时的回退 |
+|---|---|---|---|
+| **V1：`yy://` iframe 导航被 `onLoadIntercept` 捕获** | M1（`T-M1-07`） | 最小 H5 用 `iframe.src='yy://...'`，原生 `onLoadIntercept` 能取到该 URL 并拦截 | ① `onInterceptRequest`+`WebSchemeHandler` 注册 `yy` scheme；② 改注入的桥 JS 走 `javaScriptProxy.postMessage`（对 H5 仍透明） |
+| **V2：`file://` 页面 XHR/fetch 取本地资源可用** | M2（`T-M2-08`） | 现有大厅 H5 以 `file://` 加载，其对本地 js/css/资源的请求正常 | 用自定义协议/`onInterceptRequest` 接管本地资源响应（§7.3 框架文档） |
+
+> **铁律**：V1 不过则 M1 不算完成，V2 不过则 M2 不算完成。两者越早证伪越好，避免后期返工。
+
+## 6. 环境与工程约定
+
+- **工具链**：DevEco Studio + `devecocli`（build/run/emulator/log/docs）。API ≥ 12（建议 17/23）。
+- **工程形态**：1 个 entry HAP + 7 个 HAR（`feature_bridge`/`feature_capabilities`/`domain_resource`/`platform`/`contracts`/`common`）。详见框架文档 §4。
+- **构建产物**：`build-profile.json5` 配 `debug`/`release` 两 product；`devecocli build --product <p> --build-mode <m>`。
+- **签名**：M0 配好调试签名；release 签名走密钥库（不入库）。
+- **分支策略**：`main`（可发布）/ `develop`（集成）/ `feat/M{n}-{task}`（按任务）。每任务一 PR，过 CI + 代码评审合入 develop。
+- **CI**：每 PR 跑 `devecocli build`（debug）+ 单测；develop 夜间跑真机冒烟（回显 H5 + 大厅加载）。
+- **代码规范**：ArkTS 严格模式（禁 `any`）、`contracts` 为唯一 handler 名/DTO 来源、模块边界只依赖接口（框架 §3 约束）。
+
+## 7. Definition of Done（任务级通用 DoD）
+
+一个任务"完成"须同时满足：
+1. 代码合入 develop，过 CI（编译 + lint + 单测）。
+2. 若涉及契约：handler 名/参数/数据结构/回传时机**逐条对照《契约规范》**无偏差。
+3. 涉及线程的出站消息：经 UI 线程守卫（框架 §5.5）；涉及 TaskPool：仅传 Sendable + emitter 回传（§9.1）。
+4. **遵循框架附录 A（ArkTS/ArkUI 实现适配清单）**：struct 持有/生命周期解绑、严格语法、系统能力对照。
+5. 有对应测试（纯逻辑→单测；能力→真机用例记录）。
+6. 受影响文档 / [01 覆盖矩阵](./01_任务分解WBS.md) / [02 契约核对清单](./02_测试与验收计划.md) 更新。
+
+## 8. 进度跟踪机制
+
+- **任务看板**：以 `01_任务分解WBS.md` 的任务 ID 为卡片，状态 `☐/◐/☑/⚠`。
+- **每日站会**：同步关键路径任务与阻塞项；`⚠` 受阻项当日进风险登记册。
+- **里程碑评审**：到达每个 Exit Gate 召开评审，未达判据不进入下一里程碑（M1/M2 闸门尤其严格）。
+- **契约回归**：M3 起，每周跑一次"44 handler 真机逐条核对"，防回归。
diff --git a/docs/设计文档/Plan/01_任务分解WBS.md b/docs/设计文档/Plan/01_任务分解WBS.md
new file mode 100644
index 0000000..93570e8
--- /dev/null
+++ b/docs/设计文档/Plan/01_任务分解WBS.md
@@ -0,0 +1,198 @@
+# 01 · 任务分解（WBS）
+
+> 全量任务清单。每个任务含：**目标 / 产出物 / 依赖 / 验收 / 估时 / 角色**。
+> 角色缩写：桥=桥/容器、台=平台/领域、能=能力工程师、Q=QA。估时单位：人日(pd)。
+> 验收一律以《契约规范》对应条目为准；通用 DoD 见 [00_总体规划 §7](./00_总体规划.md)。
+
+---
+
+## M0 · 工程脚手架 + 契约类型
+
+| ID | 目标 | 产出物 | 依赖 | 验收 | 估时 | 角色 |
+|---|---|---|---|---|---|---|
+| **T-M0-01** | 创建多模块工程 | `devecocli create` 生成 entry + 6 HAR（`feature_bridge`/`feature_capabilities`/`domain_resource`/`platform`/`contracts`/`common`） | — | 工程可 `devecocli build`（debug）通过 | 1 | 桥 |
+| **T-M0-02** | 模块依赖与导出 | 各 `oh-package.json5` 依赖关系（单向向下）；`index.ets` 导出 | T-M0-01 | 跨模块 import 无环、可编译 | 0.5 | 桥 |
+| **T-M0-03** | 构建/签名/CI | `build-profile.json5`（debug/release product）；调试签名；CI 脚本（build+单测） | T-M0-01 | PR 触发 CI 通过 | 1 | 桥 |
+| **T-M0-04** | 契约类型（SSOT） | `contracts` HAR：`enum Handlers`（全部入站/出站 handler 名常量，含 `finsh`/`getcameraaAddress`/`backgameData-` 等原样拼写）；DTO interface（`sharetypeBean`/`MaplocationInfo`/`phoneInfoBean`/`savephotoURLBean`/`videoinfobean`/`Othervideoinfo`/`GamePay`/`sharelogin`/`sharesuccess`）；`Result<T>`/`Errors`；每 handler 的 `payloadType:'raw'|'json'` 标注 | T-M0-02 | 全量对照《契约规范》§8/§9/§12，零缺漏；编译通过 | 1.5 | 台 |
+| **T-M0-05** | 公共设施 | `common` HAR：`Logger`(分级)/`BridgeTracer`(traceId)/`EventBus`(emitter 封装)/`DIContainer`/**`ErrorCenter`(异常收敛+弹窗/静默/上报策略)**/`Result<T>` 配套 | T-M0-02 | 单测覆盖；可被各模块引用（框架 §10） | 1.5 | 台 |
+| **T-M0-06** | 引入桥 JS | 把 lzyzsd `WebViewJavascriptBridge.js` **原文件**放入 `feature_bridge/assets`，建读取/内联机制 | T-M0-01 | 文件就位、可被注入流程读取 | 0.5 | 桥 |
+| **T-M0-07** | App 入口与路由壳 | `EntryAbility`（Stage 模型生命周期，含 `onForeground/onBackground` 钩子接口）+ `Navigation`/路由骨架（Splash↔BridgeGameContainer↔GenericWebContainer 跳转与回传通道）+ `SplashPage` 壳（框架 §4） | T-M0-01 | 空壳可启动、可路由跳转；前后台钩子可触发 | 1 | 桥 |
+
+---
+
+## M1 · 桥引擎（最高优先 ⭐）
+
+| ID | 目标 | 产出物 | 依赖 | 验收 | 估时 | 角色 |
+|---|---|---|---|---|---|---|
+| **T-M1-01** | Web 控制器抽象 | `IWebController` 接口 + `WebviewControllerAdapter`（包 `webview.WebviewController`）+ `FakeWebController`（测试用） | T-M0-01 | 桥不直接依赖系统类；Fake 可记录脚本/模拟回执 | 1 | 桥 |
+| **T-M1-02** | 消息编解码 | `Message`（5 字段）+ `MessageCodec`：`toJson`/`toArray`/`escape`，**与 lzyzsd 完全一致的二次转义**（`\`、`"`） | T-M0-04 | 单测：与 Android 端样例字节级一致 | 1 | 桥 |
+| **T-M1-03** | Handler 注册表 | `HandlerRegistry`（put/get/default）+ `DefaultHandler`（空实现兜底） | T-M0-04 | 未注册名落默认 handler 不抛错（框架 §5.2/§6.5） | 0.5 | 桥 |
+| **T-M1-04** | 桥控制器 | `BridgeController`：`onLoadIntercept`/`callHandler`/`registerHandler`/`onPageEnd`/`flushMessageQueue`/`handleReturnData`/`dispatch`/`queue`；**`_fetchQueue` 走 `yy://return/` 回传**（非 runJavaScript 返回值）；**UI 线程守卫**（§5.5） | T-M1-01/02/03 | 单测（FakeWebController）：模拟 H5 callHandler→handler 分发、原生 callHandler→下发、回执路由、启动队列补发 | 2.5 | 桥 |
+| **T-M1-05** | 桥 JS 注入 | `onPageEnd` 中 `runJavaScript(BRIDGE_JS)` + 启动消息补发 | T-M1-04/T-M0-06 | 页面就绪后 `window.WebViewJavascriptBridge` 可用 | 0.5 | 桥 |
+| **T-M1-06** | 最小回显 H5 | 测试用 H5（`registerHandler('echo')`、`callHandler('getTime')`）+ 一个挂桥的最小测试页 | T-M1-04 | 真机：H5↔原生双向回显成功 | 1 | 桥/Q |
+| **T-M1-07 ⚠** | **阻塞性验证 V1** | 真机验证 `yy://` 的 iframe 导航被 `onLoadIntercept` 捕获；产出结论报告 | T-M1-06 | V1 通过；若不通过，按 [00 §5](./00_总体规划.md) 回退方案并更新设计 | 1 | 桥/技术负责人 |
+| **T-M1-08** | 桥引擎单测 | `BridgeController`/`MessageCodec`/`HandlerRegistry` 单测套件 | T-M1-04 | 覆盖率 ≥80%（框架 §13） | 1.5 | 桥/Q |
+
+> **M1 出口**：T-M1-06 跑通 + **T-M1-07（V1）通过** + T-M1-08 达标。
+
+---
+
+## M2 · 容器 + 启动 + 资源（轨道 A 容器 / 轨道 B 平台领域）
+
+### 平台层（轨道 B，可与 M1 并行起步）
+
+| ID | 目标 | 产出物 | 依赖 | 验收 | 估时 | 角色 |
+|---|---|---|---|---|---|---|
+| **T-M2-01** | 存储/文件 | `KvStore`(@ohos.data.preferences)、`FileSystem`(@ohos.file.fs) | T-M0-01 | 读写 `urlpath`/`upurlpath`；文件增删查 | 1 | 台 |
+| **T-M2-02** | 网络/下载 | `HttpClient`(@ohos.net.http 或 rcp)、`Downloader`（断点可选、进度回调） | T-M0-01 | GET 禁缓存；大文件下载带进度 | 1.5 | 台 |
+| **T-M2-03** | 解压/并发 | `Unzipper`(@ohos.zlib decompressFile)、`TaskScheduler`(TaskPool/Worker) **仅传 Sendable + emitter 进度**（§9.1） | T-M0-01 | zip 解压成功；解压在子线程、UI 不阻塞 | 1.5 | 台 |
+| **T-M2-04** | 权限/上传服务 | `PermissionGuard`（存储/电话/定位/相机/麦克风 用时申请）；`LocalUploadServer`（socket/NAPI 本机端口服务，截图上传用） | T-M0-01 | 权限流程合规；本机端口可访问 | 1.5 | 台 |
+
+### 配置/资源/启动（轨道 B）
+
+| ID | 目标 | 产出物 | 依赖 | 验收 | 估时 | 角色 |
+|---|---|---|---|---|---|---|
+| **T-M2-05** | 本地+远程配置 | `ConfigManager`：内置 `rawfile/app_config.json`（§4.2 全键）；远程配置请求（`http://gameconfig 去-换/ .txt?a=ts`，禁缓存）；`showmessage` 阻断、<30 错误文案 | T-M2-02 | 配置键齐全；远程 JSON 正确解析、阻断逻辑生效 | 2 | 台 |
+| **T-M2-06** | 分层覆盖 | `VersionResolver`：`agentlist`/`gamelist` 两棵树 + 二级 `url` 二次请求 + agent→channel→market→game **后层覆盖**（纯函数） | T-M2-05 | 单测：多层样例覆盖结果正确（《契约规范》§4.4） | 2 | 台 |
+| **T-M2-07** | 资源管理 | `ResourceManager`：路径规范、内置包拷贝+解压、`version.xml` 解析(@ohos.xml)、远程 zip 下载/删旧/解压、版本比较 | T-M2-03/06 | 首启拷贝、版本更新下载解压到正确目录（§5） | 2 | 台 |
+| **T-M2-08 ⚠** | **阻塞性验证 V2** | 真机验证 `file://` 大厅页 XHR/fetch 取本地资源；结论报告 | T-M2-07 + T-M2-10 | V2 通过；否则启用 §7.3 自定义协议方案并更新设计 | 1 | 台/桥 |
+| **T-M2-09** | app_data 注入 | `AppDataInjector`：加载前写 `<urlpath>/gamehall/app_data.js`（§6 全局变量同名同义） | T-M2-07 | H5 加载时能读到 `app_*` 变量；**时序在加载前**（§7.1 铁律） | 1 | 台 |
+| **T-M2-11** | 启动状态机 | `StartupOrchestrator`：INIT→…→ENTER_HALL；可重试/降级/阻断 | T-M2-05/07/09 | 真机按序走通；失败降级本地缓存 | 1.5 | 台 |
+
+### 容器（轨道 A）
+
+| ID | 目标 | 产出物 | 依赖 | 验收 | 估时 | 角色 |
+|---|---|---|---|---|---|---|
+| **T-M2-13** | **能力插件框架骨架** | `feature_capabilities`：`CapabilityProvider` 接口、`CapabilityContext`、注册表对接桥、组装根 `buildCapabilities()`/`AppModule`（DI 装配）、Provider 样板（框架 §6.1/§6.2） | T-M1-04、T-M0-05 | 一个示例 Provider 可注册并被桥分发；组装根可批量装配 | 1 | 桥 |
+| **T-M2-10** | 大厅/子游戏容器 | `BridgeGameContainer`：`Web` + 属性（JS/DOM/file/mixed/cache/geo/zoom）+ 生命周期接桥（`onControllerAttached` 注册能力、`onLoadIntercept` 接桥、`onPageEnd` 注桥）+ **首次进度 100% 推 `appservice`/`setPostUrl`** + `SwitchOverGameData` 同容器 `loadUrl` 切换 + `aboutToDisappear` 清理 | T-M1-08、T-M2-13、T-M0-07 | 入口 URL 规则正确（`weburl` 空→file://，非空→http://，带 `?Launchtype=0`） | 2 | 桥 |
+| **T-M2-12** | 集成联调 | 大厅 H5 真机加载 + 进子游戏 | T-M2-08/10/11 | 现有大厅 `index.html` 正常显示、可进子游戏 | 1 | 桥/Q |
+
+> **M2 出口**：T-M2-12 跑通 + **T-M2-08（V2）通过**。
+> **注**：`T-M2-13` 能力插件框架骨架是 **M3 全部 Provider 与 T-M2-10 容器注册能力的前置依赖**，须先于铺开能力完成。
+
+---
+
+## M3 · 本期能力（轨道 C，各 Provider 高度并行）
+
+> **前置依赖**：M3 全部 Provider 均依赖 `T-M2-13`（能力插件框架骨架）+ `T-M2-10`（容器可加载）+ `T-M0-04`（契约类型）。这三者就绪后，各 Provider 之间**互不依赖、可多人并行**。
+> 通用验收（每个 Provider）：入站 handler 名/参数解析、出站 handler 名/data 结构/时机**逐条对照《契约规范》§8/§9/§12**；异步回传经 UI 线程守卫；真机录用例。
+
+| ID | Provider | 入站 handler | 出站 handler | 关键实现/SDK | 估时 | 角色 |
+|---|---|---|---|---|---|---|
+| **T-M3-01** | `AppSystemProvider` | `orientation`、`browser`、`finsh`、`openApplyDownloadpath`、`notification`(空) | — | 屏幕方向、拉起浏览器、退出、按包名启动/下载兜底 | 1.5 | 能 |
+| **T-M3-02** | `DeviceProvider` | `getTime`、`getphonestate`、`getbattery`、`getwifiLevel`、`getcompareCode`、`getphoneInfo`、`getmarketname`、`getothername`、`getOther` | `getBattery`、`getwifiLevel`、`phonestate` | deviceInfo/telephony/batteryInfo/wifiManager；裸串 vs JSON 严格区分 | 2.5 | 能 |
+| **T-M3-03** | `NetworkProvider` | `getnetwork` | `getnetwork`(广播变化) | NetworkKit 监听 | 1 | 能 |
+| **T-M3-04** | `VibrateProvider` | `vibrator`、`repeatvibrator`、`canclevibrator` | — | @ohos.vibrator | 0.5 | 能 |
+| **T-M3-05** | `ClipboardProvider` | `gameCopytext`、`gamepastetext` | —（gamepastetext 同步返回串） | @ohos.pasteboard | 0.5 | 能 |
+| **T-M3-06** | `NavProvider` | `OpenurlTitleData`、`SwitchOverGameData`、`getGameinstall`(同步 0/1)、`backgameData` | `getWebdata` | 打开通用容器(M4)、同容器切换、目录判断 | 1.5 | 能/桥 |
+| **T-M3-07** | `PhotoProvider` | `getphoto` | `getphoto`(下载完成数组) | 批量下载图片到本地 + Downloader | 1.5 | 能 |
+| **T-M3-08** | `ShakeProvider` | `startshake`、`SwitchShake`、`stopshake` | `shakeEnd`(空串，触发后~1s) | @ohos.sensor 加速度 + 节流；声音可选 | 1.5 | 能 |
+| **T-M3-09** | `LocationProvider` | `startlocation`(1连续/否单次)、`getlocationinfo`(同步) | `getlocationinfo`(MaplocationInfo/错误码) | geoLocationManager；**隐私合规初始化**；错误码 0/-1/-2 | 2 | 能 |
+| **T-M3-10** | `AudioProvider` | `prepareaudio`(录音)、`mediaTypeAudio`、`srcIsloop`、`voicePlaying` | `getaudiourl`(`{audiourl,time}`)、`gameui_play_voice`、`gameui_stop_voice` | AVPlayer/SoundPool；录音上传(七牛等)；wav 路径拼接 | 3 | 能 |
+| **T-M3-11** | `ScanProvider` | `opensaoma` | `getsaomaData` | Scan Kit | 1 | 能 |
+| **T-M3-12** | `CameraProvider` | `opencamera` | `getcameraaAddress` | Camera Picker | 1 | 能 |
+| **T-M3-13** | `ShareProvider` | `friendsSharetypeUrlToptitleDescript` | `sharesuccess`(仅微信) | 微信分享 SDK；`type==2` 截图：`runJavaScript(canvas.toDataURL)` + LocalUploadServer | 2.5 | 能 |
+| **T-M3-14** | `LoginProvider` | `accreditlogin` | `sharelogin`(用户资料) | 微信登录；**建议 code 模式**（密钥下沉） | 2 | 能 |
+| **T-M3-15** | `RoomStubProvider`/`PayStubProvider` | `createRoom`/`exitRoom`/`getVideoinfo`/`DragViewvideoIsshow`；`paybrowser`/`getGameplay` | —（不触发） | **占位桩**：空实现 + 日志（§6.5） | 0.5 | 能 |
+| **T-M3-16** | 前后台联动 | — | `appservice`('1'/'2') | `UIAbility.onForeground/onBackground` → callHandler | 0.5 | 桥 |
+| **T-M3-17** | 契约一致性回归 | 全 44 入站 + 全出站真机逐条核对 | — | 对照《契约规范》§8/§9，出回归报告 | 2 | Q |
+
+> **M3 出口**：本期能力真机逐条通过；**视频房/支付桩被调用不报错不卡死**（T-M3-17 含此项）。
+
+---
+
+## M4 · 通用网页容器（轨道 A，可与 M3 尾段并行）
+
+| ID | 目标 | 产出物 | 依赖 | 验收 | 估时 | 角色 |
+|---|---|---|---|---|---|---|
+| **T-M4-01** | 通用容器 | `GenericWebContainer`：`Web` + cacheMode(有网 Default/无网 Only) + `javaScriptProxy` 注入 `settings` | T-M2-10 | 打开任意 url、属性正确 | 1.5 | 桥 |
+| **T-M4-02** | settings 注入 + 直调 | `SettingsProxy` 6 方法（`backgameData`/`loadurl`/`browser`/`finishweb`/`isexitdialogeshow`/`isbackfinishweb`）+ 3 个 `runJavaScript` 直调（`getWebdata`/`gamebackkeydown`/`backgameData`） | T-M4-01 | 逐一对照《契约规范》§11.3 | 1.5 | 桥 |
+| **T-M4-03** | 回传与返回键 | 101 结果经 router/emitter 回上层 → 上层 `callHandler('getWebdata')`；返回键逻辑（isbackfinishweb/isexitdialogeshow） | T-M4-02 | 活动页/收银台/客服打开、回传、返回正常 | 1 | 桥 |
+
+---
+
+## M5 · 性能与加固（轨道 D，部分贯穿 M3/M4）
+
+| ID | 目标 | 产出物 | 依赖 | 验收 | 估时 | 角色 |
+|---|---|---|---|---|---|---|
+| **T-M5-01** | Web 保活/预热 | `NodeController`+`BuilderNode` 离屏预创建/保活；启动期预热空 Web | T-M2-10 | 子游戏切换 <300ms、无白屏 | 2 | 桥 |
+| **T-M5-02** | 切换与桥重绑 | 子游戏切换走 `loadUrl` 复用；切换后桥/handler 重绑时序正确 | T-M5-01 | 切换后桥功能正常 | 1 | 桥 |
+| **T-M5-03** | 高频节流/批处理 | 定位/电量等高频 handler 节流；出站批处理 | T-M3-* | 跨引擎调用次数下降、无卡顿 | 1 | 桥 |
+| **T-M5-04** | 崩溃兜底/内存 | `onRenderExited` 重载；`aboutToDisappear` 彻底清理 | T-M2-10 | 渲染子进程崩溃可自恢复 | 1 | 桥 |
+| **T-M5-05** | 安全加固 | WebDebug 按 `isDebug` 守卫；密钥下沉服务端；明文 HTTP 域名白名单；file 跨域最小授权；自定义 scheme 注册(module.json5)；日志脱敏 | 各能力就绪 | 安全审查清单（附录 B）全过 | 2 | 桥/台 |
+| **T-M5-06** | 可观测 | `BridgeTracer` 全链路 traceId；接 APM/Crash | T-M0-05 | 能还原一条桥消息全链路 | 1 | 台 |
+| **T-M5-07** | 冷启动优化 | StartupOrchestrator 无依赖步骤并行化 | T-M2-11 | 冷启动到首帧达标（<2s 基线） | 1 | 台 |
+| **T-M5-08** | 包体/渠道裁剪（可选） | 能力 Provider 按渠道用 HSP 动态特性裁剪；包体瘦身（框架 §9 包体） | T-M3-* | 不同渠道包仅含所需能力，包体下降 | 1 | 桥/台 |
+
+---
+
+## M6 · 暂缓能力集成（按需，可延后）
+
+| ID | 目标 | 产出物 | 依赖 | 验收 | 估时 | 角色 |
+|---|---|---|---|---|---|---|
+| **T-M6-01** | 视频房真实 | `RoomProvider`（声网 RTC HarmonyOS SDK）替换桩 | M3 完成 | `createRoom/exitRoom/getVideoinfo/DragViewvideoIsshow` + 出站 `getVideoinfo` 真打通；H5 零改动 | 视 SDK | 能 |
+| **T-M6-02** | 支付真实 | `PayProvider`（浏览器收银台/或 App 内支付）替换桩；如启用 App 内支付则补 `PayuserPaytypePaystate` | M3 完成 | 支付闭环；H5 零改动 | 视 SDK | 能 |
+| **T-M6-03** | 补齐项（可选） | 抖音/快手登录(code)、主动截图 `getCanvasBase64`、QQ/抖音分享回传统一 | 按需 | 对照框架 §6.4 | 视需求 | 能 |
+
+---
+
+## 任务总数与估时汇总
+
+| 里程碑 | 任务数 | 估时(pd) |
+|---|---|---|
+| M0 | 7 | 7 |
+| M1 | 8 | 9 |
+| M2 | 13 | 19 |
+| M3 | 17 | 24.5 |
+| M4 | 3 | 4 |
+| M5 | 8 | 10 |
+| **合计(M0–M5)** | **56** | **≈73.5 pd（含测试/缓冲）** |
+| M6 | 3 | 视集成 |
+
+> 估时为"工作量"非"日历"。3 人并行、关键路径串行下，日历周期约 5–7 周（见 [00 §1](./00_总体规划.md)）。
+
+---
+
+## 附：框架设计 → 计划覆盖矩阵（完整性自检）
+
+> 逐条证明《框架设计与开发指南》每个章节都有计划任务承接，**无遗漏**。
+
+| 框架章节 | 计划任务 | 状态 |
+|---|---|---|
+| §1 设计原则 | 贯穿 DoD（[00 §7](./00_总体规划.md)）与代码规范（00 §6） | ✓ 原则类，非任务 |
+| §2 能力映射总表 | 各能力/桥任务的实现依据（引用表） | ✓ 参考 |
+| §3 分层架构 / §4 工程结构 | T-M0-01/02（建 entry+6 HAR）、**T-M0-07**（EntryAbility/路由/Splash） | ✓ |
+| §5.1–5.2 桥协议/控制器 | T-M1-02/03/04/05 | ✓ |
+| §5.3 同步/异步 | T-M1-04 + 各 Provider | ✓ |
+| §5.4 裸串vsJSON | T-M0-04（payloadType） | ✓ |
+| §5.5 线程模型 | T-M1-04（UI 守卫） | ✓ |
+| §5.6 IWebController | T-M1-01 | ✓ |
+| §6.1/6.2 插件框架/组装根/DI | **T-M2-13**（能力插件框架骨架） | ✓ 已补 |
+| §6.3 Provider 样板/截图分享 | T-M3-09(样板)、T-M3-13(分享截图) | ✓ |
+| §6.4 补齐项 | T-M6-03 | ✓ |
+| §6.5 占位桩 | T-M3-15 | ✓ |
+| §7.1 大厅/子游戏容器 | T-M2-10 | ✓ |
+| §7.2 通用网页容器 | T-M4-01/02/03 | ✓ |
+| §7.3 file:// 跨域 | T-M2-08（V2 阻塞验证） | ✓ |
+| §8.1 启动状态机 | T-M2-11 | ✓ |
+| §8.2 ConfigManager | T-M2-05 | ✓ |
+| §8.2 分层覆盖 | T-M2-06（VersionResolver） | ✓ |
+| §8.3 ResourceManager | T-M2-07 | ✓ |
+| §8.4 AppDataInjector | T-M2-09 | ✓ |
+| §9 性能（保活/并发/批处理/就绪渲染/内存/冷启动） | T-M5-01/02/03/04/07、T-M2-03 | ✓ |
+| §9 包体/HSP 裁剪 | **T-M5-08** | ✓ 已补 |
+| §9.1 TaskPool Sendable | T-M2-03 | ✓ |
+| §10 契约类型 SSOT | T-M0-04 | ✓ |
+| §10 日志/追踪 | T-M0-05（Tracer）、T-M5-06 | ✓ |
+| §10 ErrorCenter | **T-M0-05**（已含 ErrorCenter） | ✓ 已补 |
+| §10 事件总线/DI | T-M0-05 | ✓ |
+| §10 权限 | T-M2-04（PermissionGuard） | ✓ |
+| §10 安全 | T-M5-05 | ✓ |
+| §10 可测试 | T-M1-01/08 + 各单测 | ✓ |
+| §11 可追溯矩阵 | [02 测试与验收 §4](./02_测试与验收计划.md) 契约核对清单 + 本矩阵 | ✓ |
+| §12 路线图 M0–M6 | 本 WBS 全部里程碑 | ✓ |
+| §13 验收标准 | [02 测试与验收计划](./02_测试与验收计划.md) | ✓ |
+| 附录 A ArkTS/ArkUI 适配 | 贯穿 DoD（[00 §7](./00_总体规划.md) 已引用 §5.5/§9.1）+ T-M0-07/T-M2-10 落地 | ✓ |
+| 附录 B 生产加固合规 | T-M5-05（逐项）+ [02 §5 M5 Gate](./02_测试与验收计划.md) | ✓ |
+
+> **结论**：框架设计指南全部章节均有计划任务承接，覆盖完整。本次自检新增 `T-M0-07`、`T-M2-13`、`T-M5-08` 及 `T-M0-05` 的 ErrorCenter，补齐了能力插件框架骨架、入口/路由壳、ErrorCenter、包体裁剪四处缺口。
diff --git a/docs/设计文档/Plan/02_测试与验收计划.md b/docs/设计文档/Plan/02_测试与验收计划.md
new file mode 100644
index 0000000..5c1e352
--- /dev/null
+++ b/docs/设计文档/Plan/02_测试与验收计划.md
@@ -0,0 +1,88 @@
+# 02 · 测试与验收计划
+
+> 唯一判据：**现有 H5 零改动运行**，且行为与《契约规范》§8/§9/§11 完全一致。
+
+## 1. 测试层次
+
+| 层次 | 对象 | 手段 | 何时 |
+|---|---|---|---|
+| **单元测试** | 纯逻辑：`MessageCodec`、`HandlerRegistry`、`VersionResolver`、`ConfigManager` 解析、各 DTO 序列化 | ArkTS 单测 + `FakeWebController` | 随开发，CI 强制 |
+| **桥协议测试** | `BridgeController` 全路径 | FakeWebController 模拟 H5 收发 | M1 |
+| **集成测试** | 容器 + 启动 + 资源 + 配置 | 真机/模拟器 | M2 起 |
+| **契约一致性测试** | 全 44 入站 + 全出站 handler | 真机 + 测试 H5 探针 | M3 起每周回归 |
+| **端到端（E2E）** | 真实大厅 H5 + 子游戏 + 活动页 | 真机手测 + 录屏 | M3/M4 |
+| **性能测试** | 冷启动、子游戏切换、内存 | DevEco Profiler / hilog 打点 | M5 |
+| **安全测试** | 加固清单 | 人工审查 + 工具 | M5 |
+
+## 2. 关键测试资产
+
+### 2.1 最小回显 H5（M1 必备）
+一个独立测试页，仅用桥 API：
+- `registerHandler('echo', (d,cb)=>cb(d))`、`callHandler('getTime')`、`callHandler('echo','hi')`。
+- 验证：H5→原生→回执、原生→H5→回执、启动前积压消息补发、`yy://` 拦截（V1）。
+
+### 2.2 契约探针 H5（M3 回归）
+一个覆盖**全部 44 入站 handler**的探针页：逐个 `callHandler` 并记录回传，与《契约规范》期望值比对，输出"通过/差异"报告。出站 handler 用 `registerHandler` 全量挂载、记录原生推送。
+> 此页是"H5 零改动"的自动化守门员，纳入每周回归。
+
+## 3. 两个阻塞性验证（最高优先，决定技术路线）
+
+| 验证 | 用例 | 通过判据 | 不通过 → 动作 |
+|---|---|---|---|
+| **V1 `yy://` 拦截**（M1, T-M1-07） | 最小 H5 设 `iframe.src='yy://__queue__'`，原生 `onLoadIntercept` 取 URL | 能拿到 `yy://` URL 并拦截、`_fetchQueue` 回执经 `yy://return/` 到达 | 切 `onInterceptRequest`+`WebSchemeHandler`；或改桥 JS 走 `javaScriptProxy.postMessage`（[00 §5](./00_总体规划.md)） |
+| **V2 `file://` 跨域**（M2, T-M2-08） | 现有大厅 `index.html` 以 `file://` 加载，请求本地 js/css/图片/`app_data.js` | 资源全部正常加载、H5 正常运行 | 启用自定义协议/`onInterceptRequest` 接管本地资源（框架 §7.3） |
+
+> 这两项必须在对应里程碑**作为 Exit Gate 强制通过**。
+
+## 4. 契约一致性核对清单（H5 零改动判据）
+
+### 4.1 桥协议（§2）
+- [ ] `window.WebViewJavascriptBridge` 注入后 API 与事件 `WebViewJavascriptBridgeReady` 一致
+- [ ] `registerHandler`/`callHandler` 双向、回执、`callbackId`/`responseId` 路由正确
+- [ ] `_fetchQueue` 经 `yy://return/` 回传（非 runJavaScript 返回值）
+- [ ] 启动前积压消息在注桥后补发
+
+### 4.2 入站 44 handler（§8）—— 逐条核对名称/参数/同步返回
+- [ ] 账号社交：`accreditlogin`、`friendsSharetypeUrlToptitleDescript`、`getphoto`
+- [ ] 支付：`paybrowser`、`getGameplay`（**本期桩，验"不报错不卡死"**）
+- [ ] 设备信息：`getTime`、`getphonestate`、`getbattery`、`getwifiLevel`、`getnetwork`、`getcompareCode`、`getphoneInfo`、`getmarketname`、`getothername`、`getOther`
+- [ ] 交互：`orientation`、`vibrator`、`repeatvibrator`、`canclevibrator`、`gameCopytext`、`gamepastetext`、`notification`(空)
+- [ ] 摇一摇：`startshake`、`SwitchShake`、`stopshake`
+- [ ] 定位：`startlocation`、`getlocationinfo`
+- [ ] 音频：`prepareaudio`、`mediaTypeAudio`、`srcIsloop`、`voicePlaying`
+- [ ] 扫码/相机/浏览器/网页：`opensaoma`、`opencamera`、`browser`、`OpenurlTitleData`、`openApplyDownloadpath`
+- [ ] 子游戏/房间：`SwitchOverGameData`、`getGameinstall`、`createRoom`、`exitRoom`、`getVideoinfo`、`DragViewvideoIsshow`（**房间本期桩**）
+- [ ] 退出/返回：`finsh`、`backgameData`
+
+### 4.3 出站 handler（§9）—— 逐条核对名称/data 结构/时机
+- [ ] `appservice`(1/2)、`setPostUrl`、`getWebdata`、`getphoto`、`sharelogin`、`sharesuccess`、`shakeEnd`、`getBattery`、`getwifiLevel`、`getnetwork`、`getaudiourl`(+`filepath`)、`gameui_play_voice`、`gameui_stop_voice`、`getphoneinfo`、`getVideoinfo`(桩不推)、`PayuserPaytypePaystate`(桩不推)、`getlocationinfo`、`phonestate`、`getsaomaData`、`getcameraaAddress`
+- [ ] 名称陷阱：`backgameData-`（带连字符）≠ 入站 `backgameData`
+
+### 4.4 数据结构（§12）
+- [ ] `sharetypeBean`/`MaplocationInfo`/`phoneInfoBean`/`savephotoURLBean`/`videoinfobean`/`Othervideoinfo`/支付/`sharelogin`/`sharesuccess` 字段名同名同义
+
+### 4.5 启动/资源/容器（§3–§7、§11）
+- [ ] 配置键齐全、远程配置分层覆盖、`showmessage` 阻断
+- [ ] 资源路径、version.xml 版本比较、zip 下载解压
+- [ ] `app_data.js` 全局变量、**加载前注入**
+- [ ] 入口 URL（`weburl` 空/非空）、`?Launchtype=` 参数
+- [ ] 通用网页容器 `settings` 6 法 + 3 直调 + 101 回传
+
+## 5. 里程碑验收 Gate
+
+| 里程碑 | Gate |
+|---|---|
+| M0 | 工程编译/签名/CI 通过；`contracts` 全量类型对照契约零缺漏 |
+| **M1** | 回显 H5 双向通；**V1 通过**；桥单测 ≥80% |
+| **M2** | 真机加载大厅 H5、进子游戏；**V2 通过**；app_data.js 时序正确 |
+| M3 | §4.2/§4.3/§4.4 清单全过；**桩能力不报错不卡死** |
+| M4 | §11.3 通用容器一致；活动页/收银台/客服打开回传正常 |
+| M5 | 切换 <300ms、冷启动 <2s（基线）；安全清单（附录 B）全过；可观测可用 |
+| **本期总验收** | 现有大厅 + 全部子游戏 + 网页页面**零改动运行**；§4 全清单通过 |
+
+## 6. 缺陷分级与回归
+
+- **P0**：H5 无法运行/桥不通/崩溃 → 当日修复，阻塞合入。
+- **P1**：某 handler 行为不符契约 → 当迭代修复。
+- **P2**：性能/体验 → M5 收口。
+- 每次合入触发"契约探针 H5"回归，防止已通过的 handler 退化。
diff --git a/docs/设计文档/Plan/03_风险登记册.md b/docs/设计文档/Plan/03_风险登记册.md
new file mode 100644
index 0000000..d2d8b6b
--- /dev/null
+++ b/docs/设计文档/Plan/03_风险登记册.md
@@ -0,0 +1,47 @@
+# 03 · 风险登记册
+
+> 概率/影响：高/中/低。状态：开放/缓解中/关闭。受阻任务（`⚠`）须在此登记。
+
+## 1. 技术风险（最高优先）
+
+| ID | 风险 | 概率 | 影响 | 触发信号 | 缓解 / 应对 | 负责人 |
+|---|---|---|---|---|---|---|
+| **R-01** | **`yy://` 自定义 scheme 的 iframe 导航不被 `onLoadIntercept` 捕获**（桥不通） | 中 | 高（阻断全局） | T-M1-07 验证失败 | 前置到 M1 最先验证；回退：`onInterceptRequest`+`WebSchemeHandler` 注册 `yy` scheme；或改桥 JS 走 `javaScriptProxy.postMessage`（对 H5 透明）。三方案均零改 H5 | 桥/技术负责人 |
+| **R-02** | **`file://` 页面跨域受限**，H5 的 XHR/fetch 取本地资源失败 | 中 | 高（大厅/子游戏白屏） | T-M2-08 验证失败 | 前置到 M2；回退：自定义协议/`onInterceptRequest` 接管本地资源（框架 §7.3）。必要时把首页改用自定义 scheme 加载 | 台/桥 |
+| **R-03** | `MessageCodec` 转义与 lzyzsd 不一致，含特殊字符的 data 解析错位 | 中 | 中 | 含引号/反斜杠/中文的分享文案、JSON data 解析异常 | 单测以 Android 端样例做字节级对照；复用库 JS 原文件 | 桥 |
+| **R-04** | **线程问题**：能力回调在非 UI 线程调 `runJavaScript` 崩溃/丢消息 | 中 | 高 | 定位/支付/传感器回调偶发崩溃 | 强制 UI 线程守卫（框架 §5.5）；能力回传统一经桥（emitter/UIContext） | 桥 |
+| **R-05** | **TaskPool Sendable 约束**导致下载/解压回调传参编译/运行失败 | 中 | 中 | `@Concurrent` 报 Sendable 错 | 仅传 Sendable + emitter 回传（§9.1）；路径在 UI 线程取好传字符串 | 台 |
+| **R-06** | 远程配置二级 `url`/分层覆盖逻辑与 Android 不一致，选错下载地址/版本 | 中 | 中 | 资源版本判断错误、下错包 | `VersionResolver` 纯函数 + 多层样例单测，对照《契约规范》§4.4 | 台 |
+| **R-07** | Web 保活（NodeController/BuilderNode）生命周期/内存复杂，切换异常或泄漏 | 中 | 中 | 切换白屏/内存涨 | M5 才上；先用 `loadUrl` 切换保底；保活作为优化项可回退 | 桥 |
+| **R-08** | `app_data.js` 注入时序错误（加载后才写），H5 读不到配置 | 低 | 高 | 大厅读 `app_*` 为 undefined | 铁律：`INJECT_APP_DATA` 早于进入容器（框架 §7.1/§8.4）；测试覆盖 | 台 |
+
+## 2. 第三方 SDK / 平台风险
+
+| ID | 风险 | 概率 | 影响 | 缓解 / 应对 | 负责人 |
+|---|---|---|---|---|---|
+| **R-09** | 微信/分享/定位等厂商 **HarmonyOS SDK 缺失或能力不全** | 中 | 中 | 早期做 SDK 可用性盘点；缺失则系统能力替代（如系统分享/系统定位）或服务端代理；登录/支付走 code/服务端 | 能 |
+| **R-10** | 声网/支付 SDK 集成成本高 | 中 | 低（本期桩规避） | 本期占位桩，M6 按需集成；不阻塞主线 | 能 |
+| **R-11** | 高德等定位 SDK **隐私合规**未先行，定位失败/审核不过 | 中 | 中 | 使用前 `updatePrivacyShow/Agree`；权限用时申请 + 文案；优先系统定位 | 能 |
+| **R-12** | 本机 HTTP 上传服务（截图）实现复杂（无内置 server） | 中 | 低 | `@ohos.net.socket` 自建轻量服务或 NAPI；截图分享非核心可后置 | 台 |
+| **R-13** | ArkWeb 版本差异导致 API 行为变化 | 低 | 中 | 锁定目标 API 版本；编码前 `devecocli docs` 核对签名；CI 固定 SDK | 桥 |
+
+## 3. 工程 / 进度风险
+
+| ID | 风险 | 概率 | 影响 | 缓解 / 应对 | 负责人 |
+|---|---|---|---|---|---|
+| **R-14** | 团队 ArkTS/ArkUI 经验不足，前期效率低 | 中 | 中 | M0/M1 配对开发；沉淀附录 A 适配清单；统一脚手架样板 | 技术负责人 |
+| **R-15** | 契约理解偏差导致 handler 行为不符，后期返工 | 中 | 中 | `contracts` HAR 固化为 SSOT；契约探针 H5 每周回归；评审对照 | Q |
+| **R-16** | 能力并行开发接口/风格不统一 | 低 | 低 | `CapabilityProvider` 统一接口 + Provider 样板；代码评审 | 桥 |
+| **R-17** | 真机/设备不足影响联调与回归 | 低 | 中 | 早期备真机 + 模拟器；CI 夜间冒烟 | PM |
+
+## 4. 受阻任务记录（动态更新）
+
+| 日期 | 受阻任务 | 关联风险 | 描述 | 处置 | 状态 |
+|---|---|---|---|---|---|
+| — | — | — | （执行期间填写） | — | — |
+
+## 5. 风险闸门（与里程碑绑定）
+
+- **M1 闸门**：R-01 必须收敛（V1 通过或回退方案落地）方可进入 M2。
+- **M2 闸门**：R-02 必须收敛（V2 通过或回退方案落地）方可大规模铺 M3 能力。
+- **M5 闸门**：R-04/R-07 收敛 + 安全清单（框架附录 B）通过方可发布。
diff --git a/docs/设计文档/Plan/README.md b/docs/设计文档/Plan/README.md
new file mode 100644
index 0000000..89a8614
--- /dev/null
+++ b/docs/设计文档/Plan/README.md
@@ -0,0 +1,32 @@
+# TSGame HarmonyOS 开发计划（Plan）
+
+> 本目录是《[TSGame_HarmonyOS框架设计与开发指南](../TSGame_HarmonyOS框架设计与开发指南.md)》的**落地实施计划**，把"设计"拆解为"可执行、可验收、可追踪"的任务。
+>
+> 上游依据（单一事实来源 SSOT）：
+> - 《[TSGame_原生与H5接口契约总规范](../TSGame_原生与H5接口契约总规范.md)》—— 对外不可变契约（H5 零改动的判据）
+> - 《[TSGame_HarmonyOS框架设计与开发指南](../TSGame_HarmonyOS框架设计与开发指南.md)》—— HarmonyOS 侧如何实现
+
+## 文档导航
+
+| 文件 | 内容 | 读者 |
+|---|---|---|
+| [00_总体规划.md](./00_总体规划.md) | 里程碑、关键路径、依赖 DAG、并行轨道、角色分工、环境/分支、DoD、进度机制 | 全员 / PM |
+| [01_任务分解WBS.md](./01_任务分解WBS.md) | **核心**：按里程碑的全量任务（ID/目标/产出/依赖/验收/估时/角色） | 开发 |
+| [02_测试与验收计划.md](./02_测试与验收计划.md) | 测试策略、回显 H5、两个阻塞性验证、契约一致性回归、里程碑验收 Gate | 开发 / QA |
+| [03_风险登记册.md](./03_风险登记册.md) | 风险、概率/影响、缓解、触发条件、负责人 | PM / 技术负责人 |
+
+## 一页速览（TL;DR）
+
+- **目标**：在 HarmonyOS 上实现原生外壳，使现有 H5（大厅 + 全部子游戏 + 活动/收银台等网页）**一行不改**即可运行。
+- **本期范围**：桥引擎、双容器、启动/配置/资源、本期全部设备能力。**视频房、支付用占位桩**（不报错/不卡死），**闲聊不涉及**。真实视频房/支付列入 M6 按需集成。
+- **最高优先 & 最大风险**：M1 桥引擎，以及两个"阻塞性验证"——`yy://` 拦截（M1）、`file://` 跨域（M2）。这两点必须**最先证伪**，决定整体可行性。
+- **关键路径**：M0 → M1 → M2 →（M3 能力并行）→ M4 → M5。M6 可延后。
+- **判据**：以《契约规范》§8/§9/§11 的 handler 名、参数、数据结构、调用时机为唯一验收标准。
+
+## 任务 ID 规范
+
+`T-M{里程碑}-{序号}`，例：`T-M1-04` = 里程碑 M1 的第 4 个任务。跨文档引用任务用此 ID。
+
+## 状态约定
+
+`☐ 未开始` · `◐ 进行中` · `☑ 完成` · `⚠ 受阻`（受阻须在 [03_风险登记册](./03_风险登记册.md) 记录）。
diff --git a/docs/设计文档/TSGame_HarmonyOS框架设计与开发指南.md b/docs/设计文档/TSGame_HarmonyOS框架设计与开发指南.md
new file mode 100644
index 0000000..ce8bff1
--- /dev/null
+++ b/docs/设计文档/TSGame_HarmonyOS框架设计与开发指南.md
@@ -0,0 +1,762 @@
+# TSGame HarmonyOS 应用框架设计与开发指南
+
+> **配套文档**：本设计严格落地《[TSGame_原生与H5接口契约总规范](./TSGame_原生与H5接口契约总规范.md)》（下称《契约规范》）。**契约规范定义"对外必须一致的行为"，本文定义"HarmonyOS 侧如何优雅、高效地实现它"。** 二者配合即可让现有 H5 **零改动**运行。
+>
+> **设计目标**：现代化（ArkTS / ArkUI 声明式 / Stage 模型）、高性能（Web 保活、并发解压下载、零主线程阻塞）、架构优雅（分层 + 依赖倒置 + 能力插件化）、专业成熟（清晰边界、可测试、可观测、可演进）。
+>
+> **目标平台**：HarmonyOS NEXT（API 12+，建议 API 17/23），ArkWeb（方舟 Web）组件。
+
+---
+
+## 目录
+
+1. [设计原则](#1-设计原则)
+2. [Android → HarmonyOS 能力映射总表](#2-android--harmonyos-能力映射总表)
+3. [总体架构（分层 + 模块）](#3-总体架构分层--模块)
+4. [工程结构（模块化拆分）](#4-工程结构模块化拆分)
+5. [核心一：JsBridge 桥引擎设计](#5-核心一jsbridge-桥引擎设计)
+6. [核心二：能力插件框架（CapabilityProvider）](#6-核心二能力插件框架capabilityprovider)
+7. [容器设计：双容器模型](#7-容器设计双容器模型)
+8. [启动编排与配置/资源子系统](#8-启动编排与配置资源子系统)
+9. [性能架构](#9-性能架构)
+10. [横切关注点](#10-横切关注点)
+11. [契约可追溯性矩阵](#11-契约可追溯性矩阵)
+12. [实施路线图（里程碑）](#12-实施路线图里程碑)
+13. [验收标准](#13-验收标准)
+- [附录 A：ArkTS / ArkUI 实现适配清单](#附录-aarkts--arkui-实现适配清单)
+- [附录 B：生产加固与合规清单](#附录-b生产加固与合规清单)
+
+---
+
+## 1. 设计原则
+
+| 原则 | 说明 | 在本框架的体现 |
+|---|---|---|
+| **契约优先（Contract-First）** | H5 看到的协议是不可变契约，原生实现围绕契约展开 | 桥协议、handler 名、数据结构以《契约规范》为单一事实来源（SSOT），用 TS 类型固化 |
+| **依赖倒置（DIP）** | 上层依赖抽象，不依赖具体平台实现 | 桥引擎依赖 `ICapability`/`IPlatformService` 接口，能力模块按需注入 |
+| **能力插件化（Plugin）** | 每个原生能力是一个自注册插件 | `CapabilityProvider` 注册表，新增能力 = 新增一个 Provider，零侵入桥核心 |
+| **单一职责 + 分层** | 桥、能力、配置、资源、平台服务各司其职 | 见 §3 分层 |
+| **异步非阻塞** | IO/CPU 重活不上 UI 线程 | TaskPool/Worker 跑下载、解压、加解密；UI 线程只做编排与渲染 |
+| **可观测（Observability）** | 全链路可日志、可埋点、可诊断 | 统一 `Logger` + `BridgeTracer`，每条桥消息可追踪 |
+| **可演进** | 旧契约保留，新能力可叠加 | 契约层与实现层解耦；补齐项（QQ/抖音回调等）以新增 Provider 落地 |
+
+---
+
+## 2. Android → HarmonyOS 能力映射总表
+
+> 这是把《契约规范》的 Android 机制翻译到 HarmonyOS 的"罗塞塔石碑"，框架的所有实现都基于此映射。
+
+| 契约机制（Android） | HarmonyOS ArkWeb 等价物 | 说明 |
+|---|---|---|
+| `WebView`（X5/BridgeWebView） | `Web({ src, controller })` + `webview.WebviewController` | 声明式组件，Controller 控制行为 |
+| `shouldOverrideUrlLoading` 拦截 `yy://` | **`onLoadIntercept`**（返回 `true` 拦截） | 桥协议核心；`onLoadIntercept` 在 loadUrl 与 iframe 加载时均触发，正好匹配 H5 用 iframe.src 发起 `yy://` |
+| `loadUrl("javascript:...")` / `evaluateJavascript` | **`controller.runJavaScript(script)`**（带 Promise 回调） | 原生→H5 下发 |
+| `onPageFinished` 注入桥 JS | **`onPageEnd`** 中 `runJavaScript(桥JS)` | 注入 `WebViewJavascriptBridge.js` |
+| `addJavascriptInterface(obj, name)`（@JavascriptInterface） | **`javaScriptProxy` 属性** 或 `controller.registerJavaScriptProxy()` | 仅通用网页容器 `settings` 用 |
+| `onProgressChanged` | **`onProgressChange`** | 进度=100% 触发 `appservice`/`setPostUrl` |
+| `onResume/onPause/onStop`（前后台） | `UIAbility.onForeground/onBackground` + 页面 `onPageShow/onPageHide` | 推送 `appservice` |
+| WebSettings.setJavaScriptEnabled | `.javaScriptAccess(true)` | |
+| setDomStorageEnabled | `.domStorageAccess(true)` | |
+| setAllowFileAccess | `.fileAccess(true)`（默认开） | 访问本地文件系统 |
+| setAllowUniversalAccessFromFileURLs（file:// 跨域） | **无直接等价属性**；用官方跨域方案：`onInterceptRequest`/`WebSchemeHandler` 自定义协议接管本地资源，或以自定义 scheme 加载首页 | 见 §7.3；这是 file:// 加载下 H5 发 XHR/fetch 取本地资源的关键，**M2 必须验证** |
+| setMixedContentMode(ALWAYS_ALLOW) | `.mixedMode(MixedMode.All)` | |
+| setCacheMode(LOAD_NO_CACHE) | `.cacheMode(CacheMode.None)` | 主容器禁缓存 |
+| setGeolocationEnabled | `.geolocationAccess(true)` | |
+| setSupportZoom(false) | `.zoomAccess(false)` | |
+| setWebContentsDebuggingEnabled | `webview.WebviewController.setWebDebuggingAccess(true)` | 在 `aboutToAppear` 设置 |
+| `startActivityForResult`/`setResult`（容器间回传） | 路由参数 + 回调 / `emitter` 事件 / `AppStorage` | 通用网页容器回传 `data`（结果码 101 语义）见 §7.2 |
+| Intent extra | `router`/`Navigation` 参数对象 | |
+| SharedPreferences | `@ohos.data.preferences`（KV） | `urlpath`/`upurlpath` 等 |
+| 本机 HTTP server（截图上传） | **`@ohos.net.http` 是客户端、无内置服务端**；用 `@ohos.net.socket`(TCP) 自建轻量 HTTP 服务，或 NAPI 原生 server（如 cpp-httplib） | 监听本机端口，地址经 `setPostUrl` 告知 H5 |
+| OkHttp | `@ohos.net.http` / `rcp`（Remote Communication Kit） | 远程配置、下载 |
+| zip 解压 | `@ohos.zlib`（`decompressFile`） | TaskPool 内执行 |
+| 友盟/Bugly | HUAWEI Analytics Kit / APM / Crash Service | 可观测，非契约 |
+| 微信/QQ/抖音/高德 SDK | 各厂商 HarmonyOS SDK | 能力 Provider 内对接 |
+
+---
+
+## 3. 总体架构（分层 + 模块）
+
+采用**自上而下五层 + 横切层**，依赖方向单向向下，跨层只依赖接口。
+
+```
+┌────────────────────────────────────────────────────────────────────────┐
+│  ① 应用/编排层  App & Orchestration                                       │
+│     EntryAbility · StartupOrchestrator · 路由(Navigation) · 全局DI容器     │
+├────────────────────────────────────────────────────────────────────────┤
+│  ② 容器层  Containers (ArkUI Pages)                                       │
+│     BridgeGameContainer(大厅/子游戏)  │  GenericWebContainer(通用网页)     │
+├────────────────────────────────────────────────────────────────────────┤
+│  ③ 桥引擎层  Bridge Engine            ④ 能力层  Capabilities (插件)        │
+│     BridgeController · MessageCodec   │  Share/Login/Pay/Location/Audio/  │
+│     HandlerRegistry · QueueFlusher    │  Shake/Device/Clipboard/Net/...   │
+│     SettingsProxy(通用容器)           │  每个 = 一个 CapabilityProvider    │
+├────────────────────────────────────────────────────────────────────────┤
+│  ⑤ 领域服务层  Domain Services                                            │
+│     ConfigManager · ResourceManager · AppDataInjector · VersionResolver   │
+├────────────────────────────────────────────────────────────────────────┤
+│  ⑥ 平台服务层  Platform Services (对 SDK 的薄封装)                         │
+│     HttpClient · Downloader · Unzipper · KvStore · PermissionGuard ·      │
+│     LocalUploadServer · FileSystem · TaskScheduler(TaskPool/Worker)        │
+└────────────────────────────────────────────────────────────────────────┘
+  横切层  Cross-cutting： Logger/Tracer · ErrorCenter · EventBus · DIContainer · Contracts(TS类型)
+```
+
+**关键约束**：
+- 桥引擎层（③）**不认识任何具体能力**，只持有 `HandlerRegistry`；能力层（④）启动时把自己的 handler 注册进去 → **桥核心对能力数量零感知**。
+- 能力层（④）通过平台服务层（⑥）使用系统/厂商 SDK，**绝不**直接被容器层调用（保持单向）。
+- `Contracts` 横切层用 TypeScript `interface`/`enum`/常量固化《契约规范》的 handler 名与数据结构，**全工程唯一来源**。
+
+---
+
+## 4. 工程结构（模块化拆分）
+
+按 HarmonyOS **HAR/HSP 多模块**组织，强边界、可独立编译、可并行开发：
+
+```
+TSGameHarmony/
+├── entry/                         # 入口 HAP（应用/编排层 ①②）
+│   └── src/main/ets/
+│       ├── entryability/EntryAbility.ets
+│       ├── startup/StartupOrchestrator.ets
+│       ├── pages/
+│       │   ├── SplashPage.ets             # 启动引导（对应 weclomeactivity1）
+│       │   ├── BridgeGameContainer.ets    # 大厅/子游戏容器
+│       │   └── GenericWebContainer.ets    # 通用网页容器(对应 openwebActivity1)
+│       └── di/AppModule.ets               # 组装根：把各 Provider 注入桥
+│
+├── feature_bridge/   (HAR)        # 桥引擎层 ③ —— 与业务解耦的可复用桥
+│   └── ets/
+│       ├── BridgeController.ets
+│       ├── MessageCodec.ets · Message.ets
+│       ├── HandlerRegistry.ets
+│       ├── SettingsProxy.ets              # 通用容器 @javaScriptProxy 对象
+│       └── assets/WebViewJavascriptBridge.js   # 直接复用 lzyzsd 原文件
+│
+├── feature_capabilities/ (HAR)    # 能力层 ④ —— 每个能力一个文件夹
+│   └── ets/
+│       ├── CapabilityProvider.ets         # 插件接口 + 注册表
+│       ├── share/ login/ pay/ location/ audio/ shake/
+│       ├── device/ clipboard/ network/ vibrate/ scan/ camera/ photo/ room/
+│       └── index.ets                      # 汇总导出 provideAll()
+│
+├── domain_resource/  (HAR)        # 领域服务层 ⑤
+│   └── ets/ ConfigManager · ResourceManager · AppDataInjector · VersionResolver
+│
+├── platform/         (HAR)        # 平台服务层 ⑥
+│   └── ets/ HttpClient · Downloader · Unzipper · KvStore · PermissionGuard ·
+│            LocalUploadServer · FileSystem · TaskScheduler
+│
+├── contracts/        (HAR)        # 横切：契约类型（SSOT）
+│   └── ets/ Handlers.ets(枚举所有handler名) · dto/*.ets(数据结构) · Errors.ets
+│
+└── common/           (HAR)        # 横切：Logger/Tracer/EventBus/DI/Result<T>
+```
+
+> **为何这样切**：`feature_bridge` 与 `contracts` 不含任何业务，可被未来其他 H5 壳复用；`feature_capabilities` 可按渠道裁剪（如海外版去掉微信支付）；`domain_resource`/`platform` 可单测。
+
+---
+
+## 5. 核心一：JsBridge 桥引擎设计
+
+> 这是"H5 零改动"的命门。目标：**100% 复刻 lzyzsd/JsBridge 协议**（《契约规范》§2），但用 ArkTS 优雅实现。
+
+### 5.1 协议落地（与契约逐条对应）
+
+| 协议要素 | 实现 |
+|---|---|
+| 注入 `WebViewJavascriptBridge.js` | 在 `Web().onPageEnd` 回调里 `controller.runJavaScript(bridgeJs)`；JS 文件**直接复用库原文件**，保证 `window.WebViewJavascriptBridge` API 与事件 `WebViewJavascriptBridgeReady` 完全一致 |
+| H5→原生（`yy://`） | `Web().onLoadIntercept`（拦截范围含 **iframe 导航**，正好匹配 H5 用 `iframe.src='yy://…'` 发起调用）中：`URLDecode` 后，`yy://return/` 前缀→`handleReturnData`（回执/队列）；其余 `yy://` 前缀→`flushMessageQueue()`；返回 `true` 拦截，其余返回 `false` 放行 |
+| 取队列 `_fetchQueue()` | ⚠️ **队列不靠 `runJavaScript` 返回值取回**。`flushMessageQueue` 先以函数名 `_fetchQueue` 预登记回调，再 `runJavaScript("WebViewJavascriptBridge._fetchQueue();")`（不读返回值）；H5 内 `_fetchQueue` 把 `iframe.src` 置为 `yy://return/_fetchQueue/<队列JSON>`，**再次经 `onLoadIntercept` → `handleReturnData`** 路由到该回调。与 Android `BridgeWebView` 实现完全一致 |
+| 原生→H5 单条 | `controller.runJavaScript("WebViewJavascriptBridge._handleMessageFromNative('"+json+"');")` |
+| Message 结构 | `{handlerName, data, callbackId, responseId, responseData}`（§2.4），`MessageCodec` 负责与 lzyzsd 完全一致的转义（注意原库对 `\` 与 `"` 的二次转义） |
+| callbackId 生成 | `JAVA_CB_<自增>_<时间戳>`（格式可自定，H5 只原样回带） |
+| 启动消息队列 | 页面 `onPageEnd` 前 native 若 callHandler，先入 `startupMessage` 队列，注入桥 JS 后补发（§2.6） |
+
+> ⚠️ **M1 必须先验证的高风险点**：不同 ArkWeb 版本对**自定义 scheme（`yy://`）的 iframe 导航**是否稳定触发 `onLoadIntercept` 存在差异。M1 桥引擎自测时，**首先**用最小回显 H5 确认 `yy://` 能被 `onLoadIntercept` 捕获；若个别版本不触发，回退方案优先级：① `onInterceptRequest` + `WebSchemeHandler`（注册自定义 scheme，能力更强、可取 POST 体）；② 极端情况下改桥协议为 `javaScriptProxy` 注入一个 `_bridgeNative.postMessage(json)` 同步方法替代 `yy://` 通道（**此法需同步改写注入的 `WebViewJavascriptBridge.js` 的 `_doSend`/`_fetchQueue`，但对 H5 仍透明，`window.WebViewJavascriptBridge` 对外 API 不变**）。三种方案对 H5 均零改动。|
+
+### 5.2 BridgeController（桥控制器，每个 Bridge 容器持有一个）
+
+职责：管 WebviewController、URL 拦截分发、handler 注册、出入站消息编解码与回调表。**对外暴露 `registerHandler` / `callHandler`，与 Android 端 API 同名同义**。
+
+```typescript
+// feature_bridge —— 设计级伪代码（ArkTS 风格，省略 import）
+export type BridgeHandler = (data: string, callback: (resp: string) => void) => void;
+
+export class BridgeController {
+  private controller: webview.WebviewController;
+  private registry: HandlerRegistry;                       // 注入：能力层填充
+  private responseCallbacks = new Map<string, (d: string)=>void>();
+  private startupMessages: Message[] | null = [];          // 页面就绪前的积压
+  private uniqueId = 0;
+
+  // —— H5 → 原生：在 Web().onLoadIntercept 调用 ——
+  onLoadIntercept(url: string): boolean {
+    const u = decodeURIComponent(url);
+    if (u.startsWith('yy://return/')) { this.handleReturnData(u); return true; }
+    if (u.startsWith('yy://'))        { this.flushMessageQueue(); return true; }
+    return false;                                          // 正常导航
+  }
+
+  // —— 原生 → H5：能力层/容器调用 ——
+  callHandler(name: string, data: string, cb?: (resp: string)=>void): void {
+    const m = new Message(); m.handlerName = name; m.data = data;
+    if (cb) { const id = `JAVA_CB_${++this.uniqueId}_${SystemClock.now()}`;
+              this.responseCallbacks.set(id, cb); m.callbackId = id; }
+    this.queue(m);
+  }
+
+  registerHandler(name: string, h: BridgeHandler): void { this.registry.put(name, h); }
+
+  // —— 页面就绪：在 Web().onPageEnd 调用 ——
+  onPageEnd(): void {
+    this.controller.runJavaScript(BRIDGE_JS);              // 注入桥
+    if (this.startupMessages) { this.startupMessages.forEach(m => this.dispatch(m));
+                                this.startupMessages = null; }
+  }
+
+  // —— ⚠️ 关键：触发 H5 交出待发队列。注意队列【不是】靠 runJavaScript 返回值取回，
+  //         而是 _fetchQueue() 在 H5 内把 iframe.src 置为 'yy://return/_fetchQueue/<data>'，
+  //         再次被 onLoadIntercept 捕获 → handleReturnData 路由到这里注册的 '_fetchQueue' 回调。
+  private flushMessageQueue(): void {
+    // 以函数名 '_fetchQueue' 作为 key 预登记回调（与 callbackId 共用同一张 responseCallbacks 表）
+    this.responseCallbacks.set('_fetchQueue', (queueJson: string) => {
+      const list = MessageCodec.toArray(queueJson);        // H5 待发消息数组
+      for (const m of list) {
+        if (m.responseId) {                                // 是 H5 对"原生 callHandler"的回执
+          this.responseCallbacks.get(m.responseId)?.(m.responseData);
+          this.responseCallbacks.delete(m.responseId);
+        } else {                                           // 是 H5 主动 callHandler
+          const respFn = m.callbackId
+            ? (d: string) => this.queue(Message.response(m.callbackId!, d))
+            : (_: string) => {};
+          const handler = this.registry.get(m.handlerName) ?? this.registry.default();
+          handler(m.data, respFn);                         // ← 分发到能力层
+        }
+      }
+    });
+    // 仅触发，不读取返回值
+    this.controller.runJavaScript('WebViewJavascriptBridge._fetchQueue();');
+  }
+
+  // —— H5 → 原生 的回执通道：yy://return/<functionName>/<data> ——
+  // 既处理 _fetchQueue（队列回传），也处理普通 callbackId 回执
+  private handleReturnData(url: string): void {
+    const fn = parseFunctionFromReturnUrl(url);            // 如 '_fetchQueue' 或 'JAVA_CB_x_y'
+    const data = parseDataFromReturnUrl(url);
+    const cb = this.responseCallbacks.get(fn);
+    if (cb) { cb(data); this.responseCallbacks.delete(fn); }
+  }
+
+  private queue(m: Message): void {
+    if (this.startupMessages) this.startupMessages.push(m); else this.dispatch(m);
+  }
+  private dispatch(m: Message): void {
+    const json = MessageCodec.escape(m.toJson());
+    this.controller.runJavaScript(`WebViewJavascriptBridge._handleMessageFromNative('${json}');`);
+  }
+}
+```
+
+> 设计要点：
+> - `BridgeController` **完全不 import 任何能力**；能力通过 `registry` 注入。桥引擎成为独立 HAR，可复用、可单测。
+> - **务必忠实复刻"队列经 `yy://return/_fetchQueue/` 回传"的机制**，不要图省事改读 `runJavaScript` 的返回值——除非你同时改写注入的 `WebViewJavascriptBridge.js`（不推荐，破坏与成熟协议的一致性，易在边界场景出错）。`responseCallbacks` 一张表同时承载"函数名 key（`_fetchQueue`）"与"callbackId key（`JAVA_CB_*`）"两类回执，与 Android 端实现完全一致。
+> - 上文 `this.controller: webview.WebviewController` 仅为示意。**为可测试性，桥应依赖抽象 `IWebController`（见 §5.6），由容器注入真实 `WebviewController` 适配器**，单测时注入 mock。
+> - **必须设置 `DefaultHandler`（空实现）**：`flushMessageQueue` 分发时，`handler = registry.get(name) ?? registry.default()`。任何**未注册**的 handler 名都落到默认空实现而**不抛错**（对齐 Android `BridgeWebView.defaultHandler`）。这是"H5 调用永不报错"的最后防线，也是暂缓能力（§6.5）的安全网底座。
+
+### 5.5 线程模型（P0，必须遵守）⚠️
+
+> Android 原版 `BridgeWebView.dispatchMessage` 明确要求**只有在主线程才下发消息**（源码 `Thread.currentThread()==Looper.getMainLooper()` 才 `loadUrl`）。HarmonyOS 同理：**`runJavaScript` 只能在 UI（主）线程调用**。而能力回调（定位 `locationChange`、支付 SDK 回调、传感器、各类系统广播、TaskPool 完成）**经常发生在非 UI 线程**，若直接 `callHandler` → `runJavaScript` 会抛异常或行为异常。
+
+**强制规则**：
+1. **所有出站下发（`dispatch`/`runJavaScript`）必须在 UI 线程执行**。`BridgeController` 内部对 `dispatch` 做线程守卫：非 UI 线程则投递到 UI 线程任务队列。
+2. **入站分发（`flushMessageQueue` 触发的 handler 回调）默认就在 UI 线程**（`onLoadIntercept` 在 UI 线程回调），handler 内若开了子线程做重活，回主线程再 `callback`/`callHandler`。
+3. 能力 Provider 的异步事件回传统一经 `bridge.callHandler`，由桥内部保证线程切换，**Provider 不需自己关心线程**。
+
+```typescript
+// BridgeController 内：UI 线程守卫（示意）
+private uiContext: UIContext;                 // 由容器在 aboutToAppear/onPageShow 注入
+private dispatch(m: Message): void {
+  const run = () => {
+    const json = MessageCodec.escape(m.toJson());
+    this.controller.runJavaScript(`WebViewJavascriptBridge._handleMessageFromNative('${json}');`);
+  };
+  if (isOnUiThread()) run();
+  else this.uiContext.runScopedTask(run);     // 或 emitter/AppStorage 投递回 UI 线程
+}
+```
+
+> 实现方式可选：① UIContext 的 UI 线程任务；② `@ohos.events.emitter` 在 UI 线程订阅、能力线程 emit；③ `AppStorage`/`LocalStorage` 状态驱动。无论哪种，**对外保证：能力随便在哪个线程 `callHandler`，最终都在 UI 线程 `runJavaScript`**。
+
+### 5.6 IWebController 抽象（P2，支撑单测）
+
+桥不直接绑死系统类，依赖最小接口，便于 mock 与未来替换内核：
+
+```typescript
+export interface IWebController {            // 桥只用到这几个能力
+  runJavaScript(script: string): void;
+  runJavaScript(script: string, cb: (err: Error|null, ret: string)=>void): void;
+  loadUrl(url: string): void;
+}
+// 生产：WebviewControllerAdapter implements IWebController（包一层 webview.WebviewController）
+// 测试：FakeWebController implements IWebController（记录脚本、模拟 yy:// 回执）
+```
+> 这样 `feature_bridge` HAR 不 import `@kit.ArkWeb` 的具体类，`BridgeController`/`MessageCodec`/`VersionResolver` 均可纯逻辑单测，§13 的 ≥80% 覆盖率目标方可达成。
+
+### 5.3 同步返回 vs 异步推送
+
+《契约规范》区分两类返回，框架用同一套 `callback` 表达：
+- **同步返回**（如 `getTime`/`getnetwork`/`getlocationinfo` 主动取）：handler 内立即 `callback(value)`。
+- **异步推送**（如定位结果、支付回调）：能力层在事件到达时调用 `bridge.callHandler('出站名', data)`。
+
+### 5.4 数据载荷的"裸字符串 vs JSON"陷阱
+
+`MessageCodec` 不擅自 JSON 化 data。能力层按《契约规范》§8/§9 **逐 handler** 决定：`getTime` 回裸串、`getwifiLevel` 回 JSON 串。`contracts` 层为每个 handler 声明 `payloadType: 'raw' | 'json'` 与 DTO，编译期约束，杜绝写错。
+
+---
+
+## 6. 核心二：能力插件框架（CapabilityProvider）
+
+> 让"新增/裁剪一个原生能力"成为零侵入操作，是框架成熟度的体现。
+
+### 6.1 插件接口
+
+```typescript
+export interface CapabilityProvider {
+  readonly name: string;                                    // 如 'location'
+  // 把本能力的入站 handler 注册到桥；并持有 bridge 以便异步推送
+  register(bridge: BridgeController, ctx: CapabilityContext): void;
+  onForeground?(): void;  onBackground?(): void;            // 生命周期联动
+  onDestroy?(): void;
+}
+export interface CapabilityContext {
+  uiAbilityContext: common.UIAbilityContext;
+  config: ConfigManager; platform: PlatformServices; log: Logger;
+}
+```
+
+### 6.2 注册表 + 组装根（DI）
+
+```typescript
+// entry/di/AppModule.ets —— 组装根：唯一知道"全部能力"的地方
+export function buildCapabilities(): CapabilityProvider[] {
+  return [
+    new ShareProvider(), new LoginProvider(), new PayProvider(),
+    new LocationProvider(), new AudioProvider(), new ShakeProvider(),
+    new DeviceProvider(), new ClipboardProvider(), new NetworkProvider(),
+    new VibrateProvider(), new ScanProvider(), new CameraProvider(),
+    new PhotoProvider(), new NavProvider(),                          // OpenurlTitleData/SwitchOverGameData/backgameData
+    new AppSystemProvider(),                                          // orientation/browser/finsh/openApplyDownloadpath/notification
+    // —— 本期暂不集成：用占位桩注册，保证 H5 调用不报错（见 §6.5），未来换回真实 Provider ——
+    new RoomStubProvider(),   // 视频房（声网）暂缓  → 真实版 RoomProvider
+    new PayStubProvider(),    // 支付暂缓            → 真实版 PayProvider
+    // 闲聊：无 H5 桥接口，无需注册（默认 handler 兜底）
+  ];
+}
+// 容器初始化时：
+capabilities.forEach(p => p.register(bridge, ctx));
+```
+
+#### 44 个入站 handler → Provider 归属（确保零孤儿、可逐条核对《契约规范》§8）
+
+| Provider | 负责的入站 handler |
+|---|---|
+| `ShareProvider` | `friendsSharetypeUrlToptitleDescript` |
+| `LoginProvider` | `accreditlogin` |
+| `PayProvider` （本期=`PayStubProvider` 桩，§6.5） | `paybrowser`、`getGameplay`(旧版可选) |
+| `LocationProvider` | `startlocation`、`getlocationinfo` |
+| `AudioProvider` | `prepareaudio`、`mediaTypeAudio`、`srcIsloop`、`voicePlaying` |
+| `ShakeProvider` | `startshake`、`SwitchShake`、`stopshake` |
+| `DeviceProvider` | `getTime`、`getphonestate`、`getbattery`、`getwifiLevel`、`getcompareCode`、`getphoneInfo`、`getmarketname`、`getothername`、`getOther` |
+| `ClipboardProvider` | `gameCopytext`、`gamepastetext` |
+| `NetworkProvider` | `getnetwork` |
+| `VibrateProvider` | `vibrator`、`repeatvibrator`、`canclevibrator` |
+| `ScanProvider` | `opensaoma` |
+| `CameraProvider` | `opencamera` |
+| `PhotoProvider` | `getphoto` |
+| `RoomProvider` （本期=`RoomStubProvider` 桩，§6.5） | `createRoom`、`exitRoom`、`getVideoinfo`、`DragViewvideoIsshow` |
+| `NavProvider` | `OpenurlTitleData`、`SwitchOverGameData`、`getGameinstall`、`backgameData`(New) |
+| `AppSystemProvider` | `orientation`、`browser`、`finsh`、`openApplyDownloadpath`、`notification`(空实现) |
+
+> 合计 **44 个入站 handler 全部有且仅有一个归属**。出站 handler（§9）由对应 Provider 在事件到达时 `bridge.callHandler` 推送（如 `LocationProvider→getlocationinfo`、`PayProvider→PayuserPaytypePaystate`、`AudioProvider→getaudiourl/gameui_*`、`DeviceProvider→getBattery/getwifiLevel/phonestate`、`ScanProvider→getsaomaData`、`CameraProvider→getcameraaAddress`、`PhotoProvider→getphoto`、`ShareProvider→sharesuccess`、`LoginProvider→sharelogin`、`ShakeProvider→shakeEnd`、`NavProvider→getWebdata`、容器→`appservice/setPostUrl`）。
+
+### 6.3 一个 Provider 的样板（以定位为例）
+
+```typescript
+export class LocationProvider implements CapabilityProvider {
+  readonly name = 'location';
+  private bridge!: BridgeController; private ctx!: CapabilityContext;
+
+  register(bridge: BridgeController, ctx: CapabilityContext): void {
+    this.bridge = bridge; this.ctx = ctx;
+    bridge.registerHandler(H.startlocation, (data, _cb) => this.start(data === '1'));
+    bridge.registerHandler(H.getlocationinfo, (_d, cb) => cb(this.lastOrError()));
+  }
+  private start(continuous: boolean): void {
+    geoLocationManager.on('locationChange', loc => {
+      this.bridge.callHandler(H.getlocationinfo, JSON.stringify(toMapLocationInfo(loc)));
+      if (!continuous) geoLocationManager.off('locationChange');
+    });
+  }
+  private lastOrError(): string { /* 返回 MaplocationInfo JSON 或 {errorCode:-1,...} */ }
+}
+```
+
+> 同理：`ShareProvider`/`LoginProvider`/`PayProvider` 对接微信/QQ/抖音/支付 HarmonyOS SDK；`AudioProvider` 用 `AVPlayer`/`SoundPool`；`ScanProvider` 用 Scan Kit；`CameraProvider` 用 Camera Picker；`DeviceProvider` 用 deviceInfo/telephony/`@ohos.batteryInfo`/`@ohos.wifiManager`。**所有 handler 名、参数、回传结构严格照《契约规范》§8/§9/§12。**
+>
+> **`ShareProvider` 的"截图分享"内部流程**（契约 §10.1 的 `type=="2"`）：`friendsSharetypeUrlToptitleDescript` 收到 `type=="2"` 时，由 `ShareProvider` 内部 `runJavaScript("...canvas.toDataURL...")` 取当前页 Canvas 的 base64（失败可回退原生截图），再经平台层 `LocalUploadServer`（其地址此前已由 `setPostUrl` 告知 H5）上传/或直接交分享 SDK。此为**内部实现**，不新增对外 handler，对 H5 透明。
+
+### 6.4 补齐项以"新增 Provider/增强"落地（《契约规范》§14.2）
+
+| 待补齐 | 设计方案 |
+|---|---|
+| QQ/抖音分享结果回传 | `ShareProvider` 统一在分享 SDK 回调里 `callHandler('sharesuccess', {success,type})`，补齐三端一致 |
+| 抖音/快手登录 | 新增 `DouyinLoginProvider`，对接开放平台，**回传 code**（而非用户资料），由服务端换 token |
+| 主动截图 | 新增入站 handler `getCanvasBase64`（向后兼容、H5 可选用），`runJavaScript` 调 `canvas.toDataURL` 取回 base64 |
+| AppSecret/API_KEY 明文 | **下沉服务端**：登录走 code 模式，支付签名由服务端出，客户端不存密钥 |
+
+### 6.5 暂不实现的能力：占位桩（No-op Stub），保证 H5 调用不报错/不卡死
+
+> **范围**：本期**视频房**、**支付**、**闲聊**先不集成。但**接口必须"留空"**——即仍把对应 handler 注册进桥，只是实现为空操作。否则 H5 调用时行为不确定，且若 H5 传了 `responseCallback` 还可能**永久挂起**。
+
+**两道安全网（缺一不可）**：
+1. **桥默认 handler 兜底**：`BridgeController` 必须设置一个 `DefaultHandler`（空实现），任何**未注册**的 handler 名都路由到它，不抛错（对齐 Android `BridgeWebView.defaultHandler`）。这是最后防线。
+2. **显式占位 Provider**：对"明确暂缓"的能力，提供 `StubProvider` 显式注册占位 handler——行为确定、可日志、可灰度开启，优于依赖默认兜底。
+
+**占位桩的实现规则**：
+- **void 型 handler**（H5 不期望同步返回）：空实现（可选 `log`/轻提示"功能暂未开放"），**不要**调用任何 `callHandler` 出站。
+- **有同步返回的 handler**（H5 传了 `responseCallback`）：**必须回一个安全默认值**，否则 H5 卡死。如返回 `'0'`、空串 `''` 或合法空 JSON。
+- **绝不**触发该能力的出站 handler（如不 `callHandler('getVideoinfo')`、不 `callHandler('PayuserPaytypePaystate')`），H5 收不到推送即按"无事发生"处理。
+
+**本期占位清单**：
+
+| 能力 | 占位 Provider | 入站 handler（注册为桩） | 桩行为 | 关联出站（**不触发**） |
+|---|---|---|---|---|
+| 视频房（声网） | `RoomStubProvider` | `createRoom`、`exitRoom`、`getVideoinfo`、`DragViewvideoIsshow` | 全部 void，空实现 + 日志 | `getVideoinfo`(uid 推送) |
+| 支付 | `PayStubProvider` | `paybrowser`、`getGameplay`(旧) | void，空实现（可轻提示"支付暂未开放"） | `PayuserPaytypePaystate` |
+| 闲聊 | —— | **无 H5 接口**（《契约规范》§10.4：`sgapi` 是闲聊且全注释、无 `registerHandler`） | 无需桩；H5 若误调，走默认 handler 兜底 | —— |
+
+```typescript
+// 占位 Provider 样板：注册即留空，H5 调用安全无副作用
+export class RoomStubProvider implements CapabilityProvider {
+  readonly name = 'room(stub)';
+  register(bridge: BridgeController, ctx: CapabilityContext): void {
+    const noop: BridgeHandler = (_d, _cb) => { ctx.log.i('room not integrated yet'); };
+    bridge.registerHandler(H.createRoom, noop);
+    bridge.registerHandler(H.exitRoom, noop);
+    bridge.registerHandler(H.getVideoinfo, noop);
+    bridge.registerHandler(H.DragViewvideoIsshow, noop);
+  }
+}
+export class PayStubProvider implements CapabilityProvider {
+  readonly name = 'pay(stub)';
+  register(bridge: BridgeController, ctx: CapabilityContext): void {
+    bridge.registerHandler(H.paybrowser, (_d, _cb) => ctx.log.i('pay not integrated yet')); // 可 Toast 提示
+  }
+}
+```
+
+> **组装根切换**：`buildCapabilities()` 里把 `new RoomProvider()`/`new PayProvider()` 暂时替换为 `new RoomStubProvider()`/`new PayStubProvider()`。**契约 handler 名/数量不变**，未来集成时换回真实 Provider 即可，**对 H5 始终零改动、零报错**。
+> **闲聊**：本就没有 H5 桥接口，无需任何桩；默认 handler 兜底足以保证任何误调用不报错。
+
+---
+
+## 7. 容器设计：双容器模型
+
+《契约规范》明确有**两套**互不相同的 H5↔原生机制，框架对应**两类容器组件**。
+
+### 7.1 BridgeGameContainer（大厅 + 子游戏）
+
+对应 `webviewActivity`/`NewwebviewActivity`。基于桥协议。
+
+```typescript
+@Component
+export struct BridgeGameContainer {
+  private controller = new webview.WebviewController();
+  private bridge = new BridgeController(this.controller);
+
+  // ⚠️ 仅 debug 包开启远程调试；release 包必须关闭（安全加固，见附录 B）
+  aboutToAppear(): void { if (BuildProfile.DEBUG) webview.WebviewController.setWebDebuggingAccess(true); }
+
+  build() {
+    Web({ src: this.entryUrl(), controller: this.controller })
+      .javaScriptAccess(true).domStorageAccess(true).fileAccess(true)
+      .mixedMode(MixedMode.All).cacheMode(CacheMode.None)
+      .geolocationAccess(true).zoomAccess(false)
+      .onControllerAttached(() => { /* 注入对象(本容器不需要)、设 UA(默认即可) */
+                                    buildCapabilities().forEach(p => p.register(this.bridge, ctx)); })
+      .onLoadIntercept((e) => this.bridge.onLoadIntercept(e.data.getRequestUrl()))
+      .onPageEnd(() => { this.bridge.onPageEnd(); })        // 仅注入桥 + 补发启动队列
+      .onProgressChange((e) => { if (e.newProgress === 100 && !this.firstDone) {
+          this.firstDone = true;                            // 首次到 100% 才推
+          this.bridge.callHandler('appservice', '1');       // 前台
+          this.bridge.callHandler('setPostUrl', uploadUrl()); } })
+  }
+  // 子游戏切换 SwitchOverGameData → 仅 controller.loadUrl(新目录 index.html?Launchtype=1)
+}
+```
+
+> ⚠️ **时序铁律**：`app_data.js` 必须在本容器**加载页面之前**就由 `AppDataInjector` 写入大厅目录（见 §8.4，发生在 `StartupOrchestrator` 的 `INJECT_APP_DATA` 步、早于进入本容器）——因为 H5 首页用 `<script src="app_data.js">` 在**加载时同步读取**。**切勿**放到 `onPageEnd`/`onProgressChange` 里推，那时页面已加载完、H5 早已读过 `app_data.js`，为时已晚。`setPostUrl`/`appservice` 则按契约在首次进度 100% 时下发（与 Android `onProgressChanged==100` 一致）。
+
+- **入口 URL**：`weburl` 空 → `file://<解压根>/gamehall/index.html?Launchtype=0`；非空 → `http://<weburl 去-换/>?Launchtype=0`（《契约规范》§3/§5）。
+- **前后台**：`UIAbility.onForeground/onBackground` → `callHandler('appservice','1'|'2')`。
+- **子游戏切换**（路径 A，`SwitchOverGameData`）：同容器内 `controller.loadUrl()` 到目标目录，桥与 handler 不变。
+
+### 7.2 GenericWebContainer（通用网页容器）
+
+对应 `openwebActivity1`，**不挂桥**，用 `javaScriptProxy` 注入 `settings` 对象 + `runJavaScript` 直调。
+
+```typescript
+@Component
+export struct GenericWebContainer {
+  private controller = new webview.WebviewController();
+  // settings：H5→原生 6 方法（《契约规范》§11.3）
+  private settings = new SettingsProxy(this.controller, /*onReturnData*/ (data)=> this.finishWith101(data));
+
+  build() {
+    Web({ src: this.params.url, controller: this.controller })
+      .javaScriptAccess(true).domStorageAccess(true).fileAccess(true)
+      .geolocationAccess(true).zoomAccess(false)
+      .cacheMode(this.online ? CacheMode.Default : CacheMode.Only)    // 有网:按HTTP缓存策略(≈LOAD_DEFAULT)；无网:只用缓存(≈LOAD_CACHE_ELSE_NETWORK)。非关键项
+      .javaScriptProxy({
+        object: this.settings, name: 'settings',
+        methodList: ['backgameData','loadurl','browser','finishweb','isexitdialogeshow','isbackfinishweb'],
+        controller: this.controller,
+      })
+      .onProgressChange((e) => { if (e.newProgress === 100 && !this.loaded) {
+          this.loaded = true;
+          this.controller.runJavaScript(`getWebdata('${this.params.data}')`); } })   // 原生→H5 直调
+  }
+  // 返回键：若 H5 调过 isbackfinishweb() → runJavaScript('gamebackkeydown()')；退出确认 → runJavaScript('backgameData()')
+  private finishWith101(data: string) { /* 把 data 经路由/emitter 回传上层 Bridge 容器 → 上层 callHandler('getWebdata', data) */ }
+}
+```
+
+- `settings` 的 6 方法、`getWebdata`/`gamebackkeydown`/`backgameData` 三个直调函数严格照《契约规范》§11.3。
+- **回传上层**：用路由返回值或 `emitter` 事件把 `data` 投递回打开它的 Bridge 容器，由后者 `callHandler('getWebdata', data)`（复刻 Android 结果码 101 语义）。
+
+### 7.3 file:// 跨域
+
+H5 以 `file://` 加载并请求本地/远程资源。HarmonyOS 侧采用官方"Web 页面跨域解决方案"：用 `onInterceptRequest` 自定义本地资源响应，或为本地页配置自定义协议/响应头，避免 file 同源限制。**对 H5 透明**。
+
+---
+
+## 8. 启动编排与配置/资源子系统
+
+### 8.1 StartupOrchestrator（启动状态机）
+
+把《契约规范》§3 时序实现为**显式状态机**，每步可重试、可观测、可降级：
+
+```
+INIT → LOAD_LOCAL_CONFIG → REQUEST_PERMISSIONS → FETCH_REMOTE_CONFIG
+     → RESOLVE_VERSION → [PREPARE_RESOURCE: 内置拷贝/zip下载解压] → INJECT_APP_DATA
+     → ENTER_HALL (跳 BridgeGameContainer)
+   任一步失败 → FALLBACK(本地缓存) 或 BLOCK(showmessage 公告)
+```
+
+- `showmessage` 非空 → 阻断弹窗（§3.2）。
+- 远程配置长度 <30 视为错误文案直接提示。
+
+### 8.2 ConfigManager（配置）
+
+- **本地配置**：弃用"目录名编码"，改为随包内置 `resources/rawfile/app_config.json`（KV），提供《契约规范》§4.2 全部键：`agent/channel/gamedir/gamestart/appversion/market/gameid/weburl/gameconfig/other/tuiguang`。对 H5 无感知。
+- **远程配置**：`HttpClient.get("http://"+gameconfig.replace(/-/g,'/')+".txt?a="+ts)`，禁缓存。
+- **分层覆盖**：`VersionResolver` 实现 agent→channel→market→game 后层覆盖（§4.4），含 `agentlist`/`gamelist` 两棵树与二级 `url` 二次请求。用纯函数实现，便于单测。
+
+### 8.3 ResourceManager（资源）
+
+```
+路径（@ohos.file.fs + context.filesDir）：
+  解压根 urlpath = <filesDir>/tsgames/<bundle>/<时间戳>/<gamedir>
+  游戏目录       = <urlpath>/gamehall
+  入口           = file://<urlpath>/gamehall/index.html
+  KV 持久化       urlpath / upurlpath（@ohos.data.preferences）
+流程：
+  首启 → 拷贝内置包(rawfile) → @ohos.zlib.decompressFile 解压
+  非首启 → 比较 version.xml<version value> 与远程 game_version
+  需更新 → Downloader 下载 game_download(?a=ts) → 删旧 → decompressFile → 收尾
+```
+
+- 下载、解压在 **TaskPool/Worker** 执行（§9），UI 线程只收进度回调。
+- `version.xml` 解析用 `@ohos.xml`（XmlPullParser），取 `agent/game/channel/version`。
+
+### 8.4 AppDataInjector
+
+加载大厅前，在 `<urlpath>/gamehall/app_data.js` 写入《契约规范》§6 的全局变量（`app_version/app_agent/app_market/...`）。用 `fs` 写文件即可；**注意必须在 `Web` 加载该页面之前完成**（在 StartupOrchestrator 的 INJECT_APP_DATA 步，先于 ENTER_HALL）。
+
+---
+
+## 9. 性能架构
+
+> "高性能"落在四个可量化抓手上。
+
+| 抓手 | 设计 | 收益 |
+|---|---|---|
+| **Web 保活 / 预热** | 用 `NodeController` + `BuilderNode` 离屏预创建并保活 Web 组件；大厅↔子游戏切换走 `loadUrl` 而非重建组件；可在启动期预热一个空 Web 实例 | 子游戏进入<300ms，避免内核重启白屏 |
+| **并发卸载重活** | 下载/解压/解密/MD5 校验放 **TaskPool**（短任务）或 **Worker**（长驻）；UI 线程零阻塞 | 启动期不卡顿，进度流畅 |
+| **JSBridge 批处理** | 沿用 lzyzsd 队列语义：多条出站消息可在一次 `flushMessageQueue` 内聚合；高频 handler（定位/电量）做节流 | 减少 `runJavaScript` 跨引擎调用次数 |
+| **资源就绪即渲染** | 本地 `file://` 优先；首屏资源预解压；`onPageEnd` 后再注桥，避免阻塞首屏；图片/音频懒加载 | 首帧更快 |
+
+补充：
+- **内存**：容器 `aboutToDisappear` 解绑 Controller、`onRenderExited` 兜底重载（防渲染子进程崩溃白屏）。
+- **冷启动**：`StartupOrchestrator` 并行化"权限申请"与"内置包拷贝"等无依赖步骤。
+- **包体**：能力 Provider 按渠道裁剪（HSP 动态特性）。
+
+### 9.1 TaskPool 并发的 Sendable 约束（P1，必须遵守）⚠️
+
+HarmonyOS `TaskPool` 的 `@Concurrent` 任务**跨线程传参/返回值必须是 Sendable**（基本类型、`@Sendable` class、可序列化对象），**不能传**：闭包回调、`WebviewController`、`UIAbilityContext`、复杂业务对象。因此下载/解压的"进度回传"不能直接传 callback 进 TaskPool。落地范式：
+
+```typescript
+// 1) 重活在 @Concurrent 函数里跑，只接收/返回 Sendable 数据
+@Concurrent
+function unzipTask(zipPath: string, destDir: string): boolean { /* @ohos.zlib.decompressFile */ return true; }
+
+// 2) 进度/完成经 emitter 回 UI 线程（不跨线程传函数）
+@Concurrent
+function downloadTask(url: string, savePath: string, eventId: number): void {
+  // 边下边 emitter.emit({eventId}, { data: percent })  ← 仅传 Sendable 数字
+}
+// UI 线程：emitter.on({eventId}, e => updateProgressUI(e.data.percent));
+//          taskpool.execute(downloadTask, url, savePath, eventId);
+```
+
+> 要点：**TaskPool 只搬 Sendable 数据，UI 反馈一律走 `emitter`/`AppStorage`**。这条不遵守，编译期/运行期必报错。`context.filesDir` 等路径应在 UI 线程取好后以字符串传入。
+
+---
+
+## 10. 横切关注点
+
+| 关注点 | 设计 |
+|---|---|
+| **契约类型（SSOT）** | `contracts` HAR：`enum Handlers`（所有 handler 名常量，杜绝拼写漂移如 `finsh`/`getcameraaAddress`/`backgameData-`）；每个 DTO 一个 interface（§12 结构）；编译期保证 |
+| **日志/追踪** | `Logger`（分级）+ `BridgeTracer`：每条桥消息打 `traceId`，可还原"H5调用→handler→回传"全链路 |
+| **错误中心** | `Result<T>` 统一返回；`ErrorCenter` 收敛异常并按策略（弹窗/静默/上报） |
+| **事件总线** | `EventBus`/`emitter`：前后台、网络变化、容器间回传等解耦 |
+| **依赖注入** | 轻量 `DIContainer`（组装根 `AppModule` 集中装配），避免散落 new |
+| **权限** | `PermissionGuard` 统一申请存储/电话/定位/相机/麦克风，对齐《契约规范》§13 |
+| **安全** | 密钥下沉服务端；`file://` 跨域按官方安全实践；自定义协议白名单 |
+| **可测试** | 桥引擎、VersionResolver、MessageCodec 纯逻辑可单测；能力 Provider 以 mock bridge 测注册与回传 |
+
+---
+
+## 11. 契约可追溯性矩阵
+
+> 保证"设计覆盖契约 100%"，无遗漏。
+
+| 契约规范条目 | 落地模块 | 验收点 |
+|---|---|---|
+| §2 桥协议（yy://、_handleMessageFromNative、_fetchQueue、Message、注入时机） | `feature_bridge/BridgeController + MessageCodec + WebViewJavascriptBridge.js` | H5 `registerHandler/callHandler` 全部生效 |
+| §8 入站 44 handler | `feature_capabilities/*Provider.register()` | 逐一对照名称/参数/同步返回 |
+| §9 出站 ~21 handler | 各 Provider 在事件时 `bridge.callHandler` | 名称/data 结构/时机一致 |
+| §11.1 路径 A `SwitchOverGameData` | `BridgeGameContainer` + `NavProvider` | 同容器 loadUrl 切换 |
+| §11.2/§11.3 通用网页容器 | `GenericWebContainer + SettingsProxy` | `settings` 6 方法 + 3 直调函数 + 101 回传 |
+| §3 启动时序 | `StartupOrchestrator` | 状态机逐步 |
+| §4 配置/分层覆盖 | `ConfigManager + VersionResolver` | 两棵树 + 二级 url + 后层覆盖 |
+| §5 资源管理 | `ResourceManager + Unzipper + Downloader` | 路径/版本比较/下载解压 |
+| §6 app_data.js | `AppDataInjector` | 全局变量同名同义、加载前注入 |
+| §7 WebView 能力 | `BridgeGameContainer` 属性 | JS/DOM/file/mixed/cache/geo |
+| §10 设备能力 | 各 Provider | 分享/登录/支付/定位/音频/摇一摇/扫码/相机/震动/剪贴板/网络/电量/WiFi/电话 |
+| §13 常量/权限 | `ConfigManager + PermissionGuard` | 渠道账号、权限齐备 |
+| §14.2 补齐项 | 新增/增强 Provider | QQ/抖音回调、抖音登录、主动截图、密钥下沉 |
+
+---
+
+## 12. 实施路线图（里程碑）
+
+| 阶段 | 交付 | 关键验收 |
+|---|---|---|
+| **M0 脚手架** | `devecocli create` 多模块工程、CI、签名 | 空壳可跑 |
+| **M1 桥引擎（最高优先）** | `feature_bridge` + `IWebController` + 线程守卫 + 回显 handler；注入桥 JS | ① 最小回显 H5：`callHandler('getTime')` 能返回；**② 阻塞性验证：`yy://` 的 iframe 导航确被 `onLoadIntercept` 捕获**（否则立即切 §5.1 回退方案） |
+| **M2 容器 + 启动 + 资源** | 双容器、StartupOrchestrator、Config/Resource/AppData | 真机加载现有大厅 H5 `index.html`，能进子游戏；**阻塞性验证：`file://` 加载下 H5 的 XHR/fetch 取本地资源可用**（否则启用 §7.3 自定义协议方案） |
+| **M3 能力（本期范围）** | 分享/登录/定位/音频/摇一摇/扫码/相机/震动/剪贴板/网络/设备 等 Provider；**视频房、支付用占位桩（§6.5）**；闲聊不涉及 | 用真实 H5 跑通本期业务；**视频房/支付被调用时无报错、无卡死**（桩 + 默认 handler 兜底）；逐条对照可追溯性矩阵 |
+| **M4 通用网页容器** | `GenericWebContainer + SettingsProxy` | 活动页/收银台/客服打开、回传正常 |
+| **M5 性能 & 加固** | Web 保活、TaskPool、密钥下沉、可观测 | 子游戏切换流畅、冷启动达标、安全审查通过 |
+| **M6 暂缓能力集成（按需）** | 把 `RoomStubProvider`/`PayStubProvider` 换回真实 `RoomProvider`/`PayProvider`；如需再加抖音登录等补齐项 | 真实视频房/支付打通，**H5 仍零改动** |
+
+> **强烈建议**：M1 桥引擎必须先用一个**最小回显 H5** 单独验证，再接真实 H5；桥不稳，一切白搭。**两个"阻塞性验证"（`yy://` 拦截、`file://` 跨域）必须在 M1/M2 通过**——它们是整个适配最底层的两个不确定性，越早证伪越好。
+
+---
+
+## 13. 验收标准
+
+**功能验收（H5 零改动）**：
+- [ ] 现有大厅 H5 与全部子游戏 H5 **一行不改**即可运行。
+- [ ] 《契约规范》§8 全部入站 handler、§9 全部出站 handler 行为一致（名称/参数/数据结构/时机）。
+- [ ] 通用网页容器 `settings` 6 方法 + 3 直调函数 + 101 回传一致。
+- [ ] `app_data.js` 全局变量、入口 URL、`?Launchtype=` 参数一致。
+- [ ] **暂缓能力（视频房 `createRoom`/`exitRoom`/`getVideoinfo`/`DragViewvideoIsshow`、支付 `paybrowser`/`getGameplay`）被 H5 调用时：不报错、不卡死、不误触发出站推送**（占位桩 + 默认 handler 兜底，§6.5）。
+
+**质量验收**：
+- [ ] 桥引擎、VersionResolver、MessageCodec 单测覆盖率 ≥80%。
+- [ ] 冷启动到大厅首帧、子游戏切换时延达标（建议 <2s / <300ms，按机型基线）。
+- [ ] 下载/解压全程不阻塞 UI；渲染崩溃可自恢复。
+- [ ] 无客户端硬编码密钥；权限按需申请、合规。
+- [ ] 全链路日志可追踪一条桥消息。
+
+---
+
+> **一句话总结**：以 `feature_bridge`（100% 复刻 lzyzsd 协议）为基石，能力以 `CapabilityProvider` 插件化挂载，配置/资源/启动以领域服务编排，双容器分别承载"桥协议"与"settings 注入"两套契约——这套现代化 ArkTS 分层框架能在不改任何 H5 的前提下，优雅、高效地承载 TSGame 全部业务，并为后续能力补齐与多渠道演进留足空间。
+
+---
+
+## 附录 A：ArkTS / ArkUI 实现适配清单
+
+> 前文为"设计级"。本附录把设计落到 ArkTS/ArkUI 的**现实工程约束**上，照此即可从"设计就绪"过渡到"编码就绪"。
+
+### A.1 ArkUI `@Component struct` 与桥/控制器的协作
+- **持有方式**：`WebviewController` 与 `BridgeController` 作为 struct 的**普通成员变量**持有即可（非响应式，不要加 `@State`；它们的变化不应驱动 UI 重渲染）。需要驱动 UI 的状态（加载进度、loading 显隐）才用 `@State`/`@Local`。
+- **注入时机**：`onControllerAttached` 回调里才能安全调用 Controller 相关接口；**能力注册（`provider.register`）放这里**。`aboutToAppear` 只做无 Controller 依赖的设置（如 debug 开关）。
+- **生命周期解绑**：`aboutToDisappear` 中停止能力（`provider.onDestroy`）、清空 `responseCallbacks`/`registry`、解绑 Controller，防泄漏（对应 Android `onDestroy` 的 WebView 清理）。
+- **前后台**：在 `UIAbility.onForeground/onBackground` 或页面 `onPageShow/onPageHide` 调 `provider.onForeground/onBackground` 并 `callHandler('appservice','1'|'2')`。
+
+### A.2 ArkTS 严格语法注意
+- 全量类型标注，**禁用 `any`**；DTO 用 `interface`，handler 名用 `enum`/`const`（`contracts` HAR）。
+- 闭包/箭头函数可用，但**跨线程（TaskPool）的函数须 `@Concurrent` 且仅收发 Sendable**（见 §9.1）。
+- 动态对象访问受限：解析 H5 传入 JSON 后，**显式映射到 DTO**，不要依赖结构化鸭子类型。
+- 单例/DI：用模块级实例或轻量 `DIContainer`；避免在 struct 内散落 `new` 业务对象。
+
+### A.3 线程与并发（呼应 §5.5 / §9.1）
+| 场景 | 线程要求 | 手段 |
+|---|---|---|
+| `runJavaScript` 下发出站消息 | **必须 UI 线程** | `BridgeController.dispatch` 内置 UI 线程守卫 |
+| 能力异步回调（定位/支付/传感器/广播） | 任意线程 → 切 UI | `emitter`/UIContext 任务回 UI 线程再 `callHandler` |
+| 下载/解压/MD5/解密 | 子线程 | `TaskPool @Concurrent`，仅传 Sendable，进度经 `emitter` |
+| 大文件 IO | 子线程 | `@ohos.file.fs` 异步 API |
+
+### A.4 关键系统能力对照（编码备查）
+| 用途 | 模块 |
+|---|---|
+| Web 组件/控制器 | `@kit.ArkWeb`（`webview.WebviewController`、`Web`） |
+| 偏好存储（urlpath 等） | `@ohos.data.preferences` |
+| 文件 IO | `@ohos.file.fs` |
+| 解压 | `@ohos.zlib`（`decompressFile`） |
+| XML（version.xml） | `@ohos.xml`（`XmlPullParser`） |
+| 网络请求/下载 | `@ohos.net.http` 或 `@kit.RemoteCommunicationKit`（`rcp`） |
+| 本机端口服务（截图上传） | `@ohos.net.socket`(TCP) 自建 / NAPI 原生 server |
+| 并发 | `@ohos.taskpool` / `Worker` |
+| 事件 | `@ohos.events.emitter` |
+| 定位 | `@ohos.geoLocationManager` |
+| 电量/WiFi/网络 | `@ohos.batteryInfo` / `@ohos.wifiManager` / `@kit.NetworkKit` |
+| 设备/电话 | `@ohos.deviceInfo` / `@kit.TelephonyKit` |
+| 扫码/相机 | Scan Kit / Camera Picker |
+| 震动/传感器（摇一摇） | `@ohos.vibrator` / `@ohos.sensor` |
+| 剪贴板 | `@ohos.pasteboard` |
+| 音频 | `@kit.MediaKit`（`AVPlayer`/`SoundPool`） |
+
+> 注：具体 API 名以目标 SDK 版本为准，编码前用 `devecocli docs` 核对签名。
+
+---
+
+## 附录 B：生产加固与合规清单
+
+| 项 | 要求 |
+|---|---|
+| **远程调试** | `setWebDebuggingAccess(true)` **仅 debug 包**（`BuildProfile.DEBUG` 守卫）；release 必关 |
+| **密钥** | 微信 `AppSecret`/支付 `API_KEY` **不入客户端**；登录走 code、支付签名走服务端（《契约规范》§13） |
+| **明文 HTTP** | 远程配置/资源走 http 需在 `module.json5` 网络安全配置中显式放行域名；逐步迁 https |
+| **file:// 跨域** | 用官方方案（自定义协议/`onInterceptRequest`）而非放开全局，最小授权（§7.3） |
+| **自定义 scheme 注册** | `gamepaywelcome` 等外部唤起在 `module.json5` 的 `abilities.skills.uris` 声明 |
+| **权限合规** | 定位/相机/麦克风/电话**用时申请 + 文案说明**；高德等 SDK 隐私合规初始化（`updatePrivacyShow/Agree`）先于使用 |
+| **渲染兜底** | `onRenderExited` 重载页面，防子进程崩溃白屏 |
+| **数据安全** | KV/文件按需加密；日志脱敏（不打 openid/token 明文） |
+| **上架审核** | 准备隐私声明、权限用途清单，符合 HarmonyOS 应用市场审核要求 |
diff --git a/docs/设计文档/TSGame_原生与H5接口契约总规范.md b/docs/设计文档/TSGame_原生与H5接口契约总规范.md
new file mode 100644
index 0000000..a2cbde5
--- /dev/null
+++ b/docs/设计文档/TSGame_原生与H5接口契约总规范.md
@@ -0,0 +1,845 @@
+# TSGame 原生 ↔ H5 接口契约与启动流程总规范（跨平台适配版）
+
+> **文档目的**：本规范以现有 Android 工程的**真实代码**为唯一依据，抽象出"原生容器"与"H5 游戏内容"之间的**完整接口契约**和**启动/资源加载流程**。
+> 目标是：在一个全新的原生平台（HarmonyOS）上重新实现"原生容器"，使**现有 H5 一行代码都不改动**即可正常运行。
+>
+> **适配原则**：
+> - 本文档只规定"契约"（协议、接口名、参数结构、调用时机、数据流），**不规定原生内部如何实现**——原生侧（包括 HarmonyOS）可根据平台能力自由实现，只要对外行为与本契约一致即可。
+> - 文中所有接口名、参数字段、常量值均来自真实源码，并标注了来源文件与行号，便于核对。
+> - 凡现有 Android 代码中"未实现/已注释/无回传"的部分，本文明确标注，作为新平台需要**补齐或决策**的事项。
+
+---
+
+## 目录
+
+1. [总体架构](#1-总体架构)
+2. [核心：JS 通信桥协议（WebViewJavascriptBridge）](#2-核心js-通信桥协议webviewjavascriptbridge)
+3. [应用启动流程](#3-应用启动流程)
+4. [配置体系](#4-配置体系)
+5. [资源（大厅/子游戏）管理](#5-资源大厅子游戏管理)
+6. [H5 数据注入：app_data.js](#6-h5-数据注入app_datajs)
+7. [WebView 容器能力要求](#7-webview-容器能力要求)
+8. [接口契约一：H5 → 原生（入站 Handler 全集）](#8-接口契约一h5--原生入站-handler-全集)
+9. [接口契约二：原生 → H5（出站 Handler 全集）](#9-接口契约二原生--h5出站-handler-全集)
+10. [原生能力专题](#10-原生能力专题)
+11. [子游戏跳转与通用网页容器](#11-子游戏跳转与通用网页容器)
+12. [数据结构汇总](#12-数据结构汇总)
+13. [关键常量与第三方账号](#13-关键常量与第三方账号)
+14. [HarmonyOS 适配检查清单与待决策项](#14-harmonyos-适配检查清单与待决策项)
+
+---
+
+## 1. 总体架构
+
+整个 App 本质上是一个**多 WebView 容器 + 资源管理器**，所有业务逻辑（大厅、棋牌子游戏）都是 H5，原生只提供"启动引导 + 资源下载解压 + 设备能力桥接"。
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                        原生容器（可在任意平台重写）              │
+│                                                                │
+│  [启动引导页] ──► 读本地配置 ──► 请求远程配置 ──► 下载/解压资源 │
+│       │                                              │         │
+│       └──────────────► 注入 app_data.js ─────────────┘         │
+│                              │                                 │
+│                              ▼                                 │
+│   ┌────────────────────────────────────────────────────┐     │
+│   │              WebView 容器（大厅 / 子游戏）            │     │
+│   │   加载 file://.../index.html?Launchtype=X            │     │
+│   │                                                      │     │
+│   │   ◄──── JS 通信桥（WebViewJavascriptBridge） ────►   │     │
+│   │        H5 ⇄ 原生：登录/分享/支付/定位/音频/震动…     │     │
+│   └────────────────────────────────────────────────────┘     │
+│                              │                                 │
+│   设备能力：微信/QQ/抖音分享、微信支付登录、高德定位、          │
+│             录音、音效、摇一摇、扫码、相机、剪贴板、震动…       │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### 1.1 容器角色划分（现有 Android 实现）
+
+| 角色 | 现有 Android 类（仅作来源标注，新平台无需同名） | 说明 |
+|---|---|---|
+| 启动引导页 | `weclomeactivity1`（Launcher，强制横屏） | 读配置、请求远程配置、下载解压资源、注入 `app_data.js`，完成后跳大厅 |
+| 大厅容器 | `webviewActivity` | 加载大厅 H5（`.../gamehall/index.html`） |
+| 子游戏/内置网页容器 | `openwebActivity1` | 由大厅通过桥接口 `OpenurlTitleData` 打开任意 H5 url |
+| 微信回调容器 | `NewwebviewActivity` | 与大厅容器接口集几乎完全相同，承担微信 scheme 回调 |
+
+> **重要说明**：`webviewActivity` 与 `NewwebviewActivity` 注册的桥接口（44 个入站 handler）**名称、参数结构、回调名几乎完全一致**，差异仅 3 处（见 §8.x 标注）。新平台**只需实现一套统一的桥接口契约**即可同时覆盖大厅与子游戏容器。本文档给出的是这套统一契约。
+
+---
+
+## 2. 核心：JS 通信桥协议（WebViewJavascriptBridge）
+
+> 这是整个适配的**重中之重**。H5 完全依赖此协议与原生通信，**不可更改**。新平台必须 1:1 实现此协议，包括其 URL scheme、消息格式、JS 全局对象与注入时机。
+> 来源：`com/tagmae/jsbridge/`（`BridgeWebView`、`BridgeWebViewClient`、`BridgeUtil`、`Message`）。本协议是开源库 lzyzsd/JsBridge 的实现。
+
+### 2.1 协议总览
+
+> ⚠️ **重要范围说明**：本章描述的 `WebViewJavascriptBridge` 协议适用于**大厅容器与子游戏容器**（基于 `BridgeWebView`，即 `webviewActivity` / `NewwebviewActivity`）。
+> **另有一个独立的通用网页容器 `openwebActivity1`**（由桥接口 `OpenurlTitleData` 打开，用于活动页/收银台/客服等"打开网页"场景），它**不使用本协议**，而是用传统的"**JS 接口对象注入（`@JavascriptInterface`，对象名 `settings`）+ `javascript:` 直接函数调用**"。该容器的接口契约见 [§11.3](#113-通用网页容器-openwebactivity1-的独立接口契约)，新平台**两套机制都要实现**。
+
+在基于 `BridgeWebView` 的两个主容器里，业务通信**不使用**平台的"JS 接口注入"机制（如 Android `@JavascriptInterface`、HarmonyOS `javaScriptProxy`）作为通道——其中所有 `addJavascriptInterface(new settings(), "settings")` 均已注释失效，仅保留的崩溃监控用途与业务无关。**这两个主容器的业务通信 100% 走下述 URL scheme 拦截协议。**
+
+> 另：源码中存在 `ShareJavascriptInterface`（注入名 `NativeShare`，方法 `shareToQQ`/`shareToDouYin`），但其注入入口 `ShareActivityPatch` 在全工程**无任何引用，是死代码**，H5 无法依赖，新平台**无需实现**。
+
+通信靠两条单向通道拼成双向：
+
+1. **原生 → H5**：原生执行 JS：`WebViewJavascriptBridge._handleMessageFromNative('<消息JSON>')`。
+2. **H5 → 原生**：H5 改变一个隐藏 iframe 的 `src` 为 `yy://...` 触发导航；原生在"资源加载拦截/URL 跳转拦截"里识别 `yy://` 前缀并阻断真实导航，转而处理消息。
+
+### 2.2 URL scheme 约定（必须原样实现）
+
+来源：`BridgeUtil.java`
+
+| 常量 | 值 | 含义 |
+|---|---|---|
+| 协议前缀 | `yy://` | H5 发起的所有桥调用 |
+| 返回数据前缀 | `yy://return/` | H5 对原生调用的回执 / 取队列回执 |
+| 取消息队列 | `yy://return/_fetchQueue/` | 原生通知 H5"把待发消息队列交出来" |
+
+原生侧 URL 拦截逻辑（必须复刻）：
+```
+拦截到 url（需先 URLDecode）：
+  if url 以 "yy://return/" 开头:
+       → 解析出 functionName 与 data，执行对应回调，阻断导航
+  else if url 以 "yy://" 开头:
+       → 调用 _fetchQueue()（见下），阻断导航
+  else:
+       → 正常导航
+```
+
+### 2.3 原生 → H5 的两条 JS 调用（必须原样实现）
+
+来源：`BridgeUtil.java`
+- 下发单条消息：`javascript:WebViewJavascriptBridge._handleMessageFromNative('<JSON字符串>');`
+- 抽取 H5 待发队列：`javascript:WebViewJavascriptBridge._fetchQueue();`
+  - 该调用本身被当作一次"原生→H5"调用，其回执由 H5 通过 `yy://return/_fetchQueue/<JSON数组>` 送回原生。
+
+### 2.4 消息体（Message）JSON 结构
+
+来源：`Message.java`。原生与 H5 之间所有消息都序列化为如下结构（字段按需出现）：
+
+| 字段 | 类型 | 含义 |
+|---|---|---|
+| `handlerName` | String | 目标 handler 名（指定调用哪个已注册的 handler；无则走 defaultHandler） |
+| `data` | String | 业务数据载荷（**注意：可能是裸字符串，也可能是 JSON 字符串**，逐接口而定） |
+| `callbackId` | String | 本条消息期望对端回执时带回的 id（发起方生成） |
+| `responseId` | String | 回执消息：对应此前收到的 `callbackId` |
+| `responseData` | String | 回执消息的返回数据载荷 |
+
+原生侧生成 callbackId 的格式：`JAVA_CB_<自增id>_<时间戳>`（来源 `BridgeWebView.doSend`）。新平台可用任意唯一字符串格式，H5 不关心其内部格式，只负责原样回带。
+
+### 2.5 JS 端 API（H5 使用，原生必须保证这些 API 存在且行为一致）
+
+H5 通过全局对象 `window.WebViewJavascriptBridge` 调用以下方法（由注入的 `WebViewJavascriptBridge.js` 提供）：
+
+| JS API | 作用 |
+|---|---|
+| `registerHandler(handlerName, function(data, responseCallback){...})` | H5 注册一个 handler，供**原生调用**（即接收"原生→H5"消息）。`responseCallback(retData)` 用于把结果回给原生。 |
+| `callHandler(handlerName, data, function(responseData){...})` | H5 **调用原生**注册的 handler，`responseData` 回调接收原生的同步返回。 |
+| `init(function(message, responseCallback){...})` | 设置默认 handler（接收未指定 handlerName 的消息）。 |
+| `send(data, responseCallback)` | 向原生默认 handler 发消息。 |
+
+H5 监听桥就绪事件后才开始调用（典型写法，原生需保证此事件/回调时序）：
+```javascript
+function connectBridge(cb){
+  if (window.WebViewJavascriptBridge) { cb(WebViewJavascriptBridge); }
+  else { document.addEventListener('WebViewJavascriptBridgeReady',
+           function(){ cb(WebViewJavascriptBridge); }, false); }
+}
+```
+
+> 新平台需提供与 lzyzsd/JsBridge **同名同行为**的 `WebViewJavascriptBridge.js`，确保 H5 中已有的 `registerHandler`/`callHandler` 调用全部生效。建议直接复用该库的 `WebViewJavascriptBridge.js` 原文件。
+
+### 2.6 JS 注入时机（关键时序）
+
+来源：`BridgeWebViewClient.onPageFinished`
+- 在**每个页面加载完成（onPageFinished）时**，原生把 `WebViewJavascriptBridge.js` 内容注入页面（作为 JS 执行）。
+- 注入后，原生把"启动消息队列"（页面加载完成前积压的待发消息）逐条 `_handleMessageFromNative` 下发。
+
+新平台实现要点：
+1. 监听页面加载完成事件 → 注入桥 JS。
+2. 维护"启动前积压消息队列"：页面就绪前原生若调用 H5 handler，先入队，页面就绪后补发。
+3. 注入的 JS 解析时会**去除以 `//` 开头的注释行**（`BridgeUtil.assetFile2Str`），新平台若直接读取 js 文件注入，需保持等价（或直接内联完整 js）。
+
+### 2.7 一次完整调用的数据流示例
+
+**H5 调用原生（带返回）** —— 例：H5 获取系统时间
+```
+H5:   bridge.callHandler('getTime', '', function(ret){ /* ret = "1700000000000" */ });
+       └─ 桥生成 message {handlerName:'getTime', data:'', callbackId:'cb_1'}
+          入队 → 触发 iframe.src='yy://__queue__'
+原生: 拦截 yy:// → _fetchQueue() 取出该 message
+      → 找到名为 'getTime' 的 handler 执行 → responseCallback("1700000000000")
+      → 原生把 {responseId:'cb_1', responseData:'1700000000000'} 经
+        _handleMessageFromNative 下发
+H5:   桥按 responseId 找到 cb_1 回调并执行
+```
+
+**原生调用 H5（推送）** —— 例：定位结果推送
+```
+原生: callHandler('getlocationinfo', '<MaplocationInfo的JSON>', null)
+      → message {handlerName:'getlocationinfo', data:'<json>'} 经
+        _handleMessageFromNative 下发
+H5:   桥查到 H5 用 registerHandler('getlocationinfo', ...) 注册的处理函数并执行
+```
+
+---
+
+## 3. 应用启动流程
+
+> 来源：`weclomeactivity1.java`、`initwebviewutil`、`GameupdateUtil.java`、`webviewActivity.initwebview`。
+> 下述为**行为时序**，新平台按此顺序复刻即可，内部实现自由。
+
+### 3.1 启动总时序
+
+```
+启动引导页 onCreate
+  │  全屏、强制横屏、保持屏幕常亮
+  ▼
+读取本地配置（资源目录名编码，见 §4.1）
+  │  initfile = "gamehall"（gamestart 配置）
+  │  filestart = "FtJf...ziK"（gamedir 配置）
+  ▼
+申请运行时权限（存储 / 电话状态 / 定位）
+  ▼
+拼接远程配置 URL（见 §4.3）
+  │  configUrl = "http://" + (gameconfig 配置去'-'换'/') + ".txt"
+  ▼
+首次安装？
+  ├─ 是：把内置预置包（gamehall）拷贝到内部存储并解压
+  └─ 否：比较内置 version.xml 与已解压 version.xml 版本，必要时重新拷贝
+  ▼
+检测网络 → 请求远程配置（HTTP GET，禁缓存，URL 追加 "?a=<时间戳>"）
+  ▼
+解析远程配置（JSON）
+  ├─ 2.0 格式（含 gamelist）：拉取代理二级配置 + 游戏二级配置 → 分层版本计算
+  └─ 1.0 格式：单文件逐层匹配
+  ▼
+版本决策：远程 game_version > 本地 version.xml 的 version ？
+  ├─ 需要更新：下载 game_download 指向的 zip → 删旧目录 → 解压到资源目录
+  └─ 无需更新：直接用本地资源
+  ▼
+（如有）APK 自升级：app_version 高于本地 appversion → 下载 APK 安装
+  ▼
+注入 app_data.js（把配置写进大厅资源目录，见 §6）
+  ▼
+跳转大厅容器（不带 Intent extra；配置经 app_data.js 与桥接口获取）
+  ▼
+大厅容器加载 file://.../gamehall/index.html?Launchtype=0
+```
+
+### 3.2 阻断式提示
+
+远程配置 JSON 顶层若含非空 `showmessage` 字段，启动流程会**弹窗提示并阻断**（用于公告/停服）。配置内容长度过短（< 30 字符）时视为错误文案，直接弹窗。新平台需复刻此"全局公告阻断"行为。
+
+---
+
+## 4. 配置体系
+
+### 4.1 本地配置编码机制（资源目录名编码）
+
+> 来源：`getAllFilename(String name)`（`weclomeactivity1` / `webviewActivity` 均有同名实现）。
+
+现有 Android 把每个配置项做成一个**资源目录**，目录下放一个**以"配置值"命名的子文件夹**（外加一个占位文件 `BoolTest.java` 需被跳过）。读取逻辑：
+```
+列出 assets/<配置名>/ 下的条目
+  跳过名为 "BoolTest.java" 的占位文件
+  剩下那个"子文件夹的名字"即为配置值
+返回该名字（找不到则为空字符串）
+```
+
+> **HarmonyOS 适配建议**：这种"用目录名编码配置"的做法是历史包袱。新平台**推荐改为正规的键值配置文件**（如随包内置一个 JSON），只要能提供下表中的同名配置值即可，H5 完全无感知。
+
+### 4.2 配置项清单（本仓库实测值）
+
+| 配置键 | 本仓库实际值 | 含义 / 用途 |
+|---|---|---|
+| `agent` | `veRa0qrBf0df2K1G4de2tgfmVxB2jxpv` | 代理商 ID（远程配置分层匹配 key） |
+| `channel` | `FtJf073aa0d6rI1xD8J1Y42fINTm0ziK` | 渠道 ID（分层匹配 key） |
+| `gamedir` | `FtJf073aa0d6rI1xD8J1Y42fINTm0ziK` | 资源解压**父目录名** |
+| `gamestart` | `gamehall` | 资源解压后的**游戏目录名**（大厅入口所在目录） |
+| `appversion` | `49` | 当前 App 版本号（数字，与远程 `app_version` 比较决定是否升级 APK） |
+| `market` | `3` | 市场 ID（分层匹配 key；也经桥 `getmarketname` 暴露给 H5） |
+| `gameid` | （空，仅占位） | 游戏 ID（空时回退用 version.xml 中的 game id） |
+| `weburl` | （空） | 大厅 H5 远程地址；**空 → 本地 file:// 加载**（本仓库走本地） |
+| `gameconfig` | `tsgames.daoqi88.cn-config_test-update_jsonv2_test` | 远程配置地址（`-`→`/` 后拼 `.txt`） |
+| `other` | （空） | 业务自定义值，经桥 `getOther`/`getothername` 暴露给 H5 |
+| `tuiguang` | （目录不存在 → 空） | 推广/邀请码，写入 app_data.js 的 `app_invitationcode` |
+| `servertype` | （空，**无代码读取**） | 历史预留，启动流程不使用，可不实现 |
+| `gameserver` | （空，**无代码读取**） | 历史预留，启动流程不使用，可不实现 |
+
+### 4.3 远程配置请求
+
+**URL 拼装**（来源 `weclomeactivity1.init`）：
+```
+gameconfig 值 = "tsgames.daoqi88.cn-config_test-update_jsonv2_test"
+→ 把 '-' 替换为 '/'  = "tsgames.daoqi88.cn/config_test/update_jsonv2_test"
+→ configUrl = "http://" + 上一步 + ".txt"
+         = "http://tsgames.daoqi88.cn/config_test/update_jsonv2_test.txt"
+请求时再追加防缓存参数： configUrl + "?a=" + 当前毫秒时间戳
+请求方式：HTTP GET，强制不走缓存
+```
+
+**返回体**：一个 `.txt` 文件，内容为 **JSON**（解析前用 JSON 解析校验；长度 < 30 视为错误提示文案直接弹窗）。存在两套并存格式：
+
+#### 2.0 配置格式（主路径，含 `gamelist` 字段时）
+```jsonc
+{
+  "showmessage": "",            // 非空 → 弹窗阻断（公告/停服）
+  "agentlist": [
+    {
+      "agentid": "", "agentname": "",
+      "app_version": "", "app_download": "", "app_size": "",
+      "game_version": "", "game_download": "", "game_size": "",
+      "url": "",                // 指向"代理专属二级配置"地址，非空则二次请求
+      "channellist": [ /* 渠道层，结构含 marketlist */ ]
+    }
+  ],
+  "gamelist": [
+    {
+      "gameid": "", "url": "", // url 指向"游戏专属二级配置"，非空则二次请求
+      "agentlist": [ /* 内含 channellist → marketlist */ ]
+    }
+  ]
+}
+```
+
+解析流程：
+1. 用本机 `agent` 值在 `agentlist` 命中项；若其 `url` 非空 → 二次请求拉**代理二级配置**。
+2. 用本机 `gameid` 值在 `gamelist` 命中项；若其 `url` 非空 → 二次请求拉**游戏二级配置**。
+3. 两个二级配置都到齐后，做最终版本决策（见 §4.4）。
+
+#### 1.0 配置格式（兼容老格式，无 `gamelist` 时）
+单文件内嵌全部层级，直接在一个循环里逐层匹配，无二次请求。
+
+### 4.4 分层覆盖逻辑（agent → channel → market → game）
+
+> **此分层覆盖逻辑真实存在**，来源 `GameupdateUtil.agentUtil`（已核实）。匹配 key 为 `{agentid, gameid, channelid, marketid}`（来自本地配置）。
+
+- **代理配置树**：`agentid 命中` → 遍历 `channellist`(channelid 命中) → 遍历 `marketlist`(marketid 命中，可设 app 升级) → 遍历该市场 `gamelist`(gameid 命中，设 app/game 升级)。**越深层越后赋值，覆盖前层**。
+- **游戏配置树**：`gameid 命中` → `agentlist`(agentid) → `channellist`(channelid) → `marketlist`(marketid，可设 app+game 升级)。同样**后层覆盖前层**。
+- **最终合并**：app 升级与 game 升级各自取"代理树与游戏树中 version 更高"者的下载地址，再分别与本地版本比较。
+
+每层可携带的可覆盖字段：`app_version`、`app_download`、`app_size`、`game_version`、`game_download`、`game_size`、`url`、`showmessage`。
+
+> **与旧参考文档的差异提示**：旧版 `TSGame_应用启动流程详解.md` 中给出的配置 JSON（`data.agentlist[].channellist[].marketlist[]`、`config_download`、`configVersion` 等字段）是**示意性质，与真实字段名不完全一致**。请以本节真实字段（`agentlist` / `gamelist` 两棵树并存、二级 `url` 二次请求、`game_download`/`game_version` 等）为准。
+
+---
+
+## 5. 资源（大厅/子游戏）管理
+
+### 5.1 真实文件系统路径
+
+> 来源 `initwebviewutil.getdate`。
+
+```
+内部存储根 = <App内部files目录>            // 例如 Android: /data/data/<包名>/files
+父目录(upurlpath) = <files>/tsgames/<包名>/<启动毫秒时间戳>
+解压根(urlpath)   = <父目录>/<gamedir值>    // = .../<时间戳>/FtJf073aa0d6rI1xD8J1Y42fINTm0ziK
+游戏内容目录      = <解压根>/<gamestart值>  // = .../FtJf...ziK/gamehall
+大厅入口          = <解压根>/gamehall/index.html
+```
+
+两个路径以键值对持久化（供容器读取）：`urlpath`（解压根）、`upurlpath`（父目录）。
+> 注意：解压根含**启动时间戳**，意味着每次全新解压会落到新目录。新平台可沿用或简化为固定目录，对 H5 无影响（H5 只看到自己被以 `file://` 加载）。
+
+### 5.2 内置预置包（首次安装）
+
+- 现有工程随包内置 `gamehall` 目录，首启时整体拷贝到解压根，并对其中的 `.zip` / `.so` 解压，然后删除压缩包。
+- **本仓库内置包 `gamehall_42_0527.zip` 仅 553 字节，里面只有一个 `version.xml`，是占位/演示包**——真正可运行的大厅 H5（index.html 等）由远程 zip 下载提供。新平台需注意：**不能假设内置包里有完整大厅页面**。
+
+### 5.3 版本文件 version.xml
+
+> 资源目录与内置包内均含 `version.xml`，结构如下（实测）：
+```xml
+<game>
+  <agent   id="..." name="天盛网络"/>
+  <game    id="..." name="友乐游戏"/>
+  <channel id="..." name="友乐互动游戏"/>
+  <version value="42" name="1.42"/>
+</game>
+```
+- `version value` 为整数，用于与远程配置 `game_version` 比较（远程更高则下载更新）。
+- `agent/game/channel` 的 id 作为资源自带的归属标识。
+
+### 5.4 zip 下载与解压
+
+```
+下载 URL = 远程配置 game_download 字段值 + "?a=<时间戳>"
+下载到   = <App外部files目录>/dowlod_zip/<时间戳>Projects.zip   （目录名拼写即代码原样 "dowlod_zip"）
+解压步骤：
+  1. 删除旧的 <解压根>/gamehall 内容
+  2. 解压 zip 到 <解压根>/    （zip 内顶层即含 gamehall/...）
+  3. 删除 zip 文件
+  4. 进入"注入 app_data.js → 跳大厅"收尾
+```
+
+### 5.5 APK 自升级
+
+- 远程 `app_version` 高于本地 `appversion` 时，下载 `app_download` 指向的安装包并触发系统安装。
+- HarmonyOS 适配：改为对应平台的应用更新方式即可，与 H5 契约无关。
+
+---
+
+## 6. H5 数据注入：app_data.js
+
+> 来源 `weclomeactivity1.inith5data`。**这是把原生配置传给 H5 的关键机制之一，H5 直接读取这些全局变量，必须复刻。**
+
+跳转大厅前，原生在大厅资源目录生成/改写 `app_data.js`：
+```
+路径：<解压根>/gamehall/app_data.js
+```
+文件内容为一组全局 JS 变量声明（H5 直接引用），字段如下：
+
+| 全局变量 | 来源 | 含义 |
+|---|---|---|
+| `app_version` | version.xml 的 version | 资源版本号 |
+| `app_gameconfig` | `gameconfig` 配置 | 远程配置地址标识 |
+| `app_gamedir` | `gamedir` 配置 | 资源父目录名 |
+| `app_gamestart` | `gamestart` 配置 | 游戏目录名（gamehall） |
+| `app_agent` | `agent` 配置 | 代理商 ID |
+| `app_appversion` | `appversion` 配置 | App 版本号 |
+| `app_market` | `market` 配置 | 市场 ID |
+| `app_channel` | `channel` 配置 | 渠道 ID |
+| `app_invitationcode` | `tuiguang` 配置 | 推广/邀请码 |
+| `app_Launchtype` | 固定 `'0'`（大厅） | 启动类型 |
+| `app_gamename` | 资源/配置 | 游戏名 |
+| `app_getwifisignalLevel` | 运行时 | WiFi 信号等级初值 |
+
+> 新平台只需在加载大厅页面前，保证大厅目录下存在等价的 `app_data.js`（同名全局变量、同含义取值）。内部如何生成文件不限。
+
+---
+
+## 7. WebView 容器能力要求
+
+> 来源 `webviewActivity.initWebViewSettings` / `NewwebviewActivity.initWebViewSettings`。下列为 H5 正常运行所需的**能力要求**，新平台用等价配置满足即可。
+
+| 能力 | 要求 | 说明 |
+|---|---|---|
+| JavaScript | 必须启用 | — |
+| DOM Storage / 本地数据库 | 必须启用 | H5 用 localStorage 等持久化 |
+| 本地文件访问 | 必须允许 | 加载 `file://` 本地页面 |
+| `file://` 跨源访问 | 必须允许（universal access from file URLs） | H5 从 file 页面请求本地/远程资源 |
+| 混合内容（http+https） | 允许（always allow） | 本地页面内嵌 http 资源 |
+| 明文 HTTP 流量 | 允许 | 远程配置/资源走 http |
+| 缓存 | 不使用缓存（每次走网络/本地最新） | — |
+| 定位 | 启用（H5 geolocation + 桥定位） | — |
+| 缩放 | 关闭（禁缩放、禁内置缩放控件、禁 wide viewport） | 固定布局游戏 |
+| 多窗口 | 关闭 | — |
+| UserAgent | **未自定义**（用平台默认） | H5 不依赖特定 UA |
+| Cookie | 未特殊配置 | — |
+| 远程调试 | 启用（开发期） | — |
+
+容器还需提供：
+- **本机 HTTP 服务**：用于"截图分享上传"。容器启动一个本机 HTTP server，把地址（`http://<本机IP>:<端口>/testurl`）通过桥 `setPostUrl` 推给 H5（见 §9）。新平台需提供等价的本机上传端点能力，否则截图分享链路不通。
+
+---
+
+## 8. 接口契约一：H5 → 原生（入站 Handler 全集）
+
+> H5 通过 `bridge.callHandler('<名称>', '<data>', responseCallback)` 调用。
+> **data 列**标注是裸字符串还是 JSON 字符串；**同步返回列**标注是否通过 `responseCallback` 同步返回（裸字符串/JSON）；多数能力的结果是**异步**通过 §9 的出站 handler 推回。
+> 来源：`webviewActivity.initwebjh`（行 2185–3012）/ `NewwebviewActivity.initwebjh`（行 2164–3129）。两容器一致，差异在表后标注。
+
+### 8.1 账号 / 社交
+
+| Handler | data | 同步返回 | 异步回传 | 功能 |
+|---|---|---|---|---|
+| `accreditlogin` | 裸字符串（`"1"`=QQ，其他=微信；QQ 实为空实现） | 无 | `sharelogin` | 触发授权登录（实际仅微信） |
+| `friendsSharetypeUrlToptitleDescript` | JSON（`sharetypeBean`，见 §12） | 无 | `sharesuccess`（仅微信有结果） | 分享（微信/QQ/抖音） |
+| `getphoto` | 裸字符串（图片下载 JSON 数组） | 无 | `getphoto` | 批量下载图片/头像到本地 |
+
+### 8.2 支付
+
+| Handler | data | 同步返回 | 异步回传 | 功能 |
+|---|---|---|---|---|
+| `paybrowser` | 裸字符串（收银台 URL） | 无 | 无（H5 收银台页自理） | 浏览器方式支付（**当前生效**） |
+| `getGameplay` | JSON（`price/body/typeplay/type/user`） | 无 | `PayuserPaytypePaystate` | App 内微信支付（**仅旧版 `webviewActivity` 生效**；`NewwebviewActivity` 已注释） |
+
+### 8.3 设备 / 系统信息
+
+| Handler | data | 同步返回 | 异步回传 | 功能 |
+|---|---|---|---|---|
+| `getTime` | 忽略 | 裸字符串（毫秒时间戳） | — | 获取系统时间 |
+| `getphonestate` | 忽略 | 裸字符串 int（0 挂断/1 接起/2…） | — | 获取电话状态 |
+| `getbattery` | 忽略 | 无 | `getBattery` | 主动获取电量 |
+| `getwifiLevel` | 忽略 | 无 | `getwifiLevel` | 主动获取 WiFi 信号 |
+| `getnetwork` | 忽略 | 裸字符串（`1`无网/`2`WiFi/`3`移动） | — | 主动获取网络状态 |
+| `getcompareCode` | 忽略 | 裸字符串 int（1=本地版本>网络版本，0=否） | — | App 版本比较结果 |
+| `getphoneInfo` | 忽略 | 无 | `getphoneinfo` | 获取手机配置信息（型号/IMEI 等） |
+| `getmarketname` | 忽略 | 裸字符串（market 值） | — | 获取市场 ID |
+| `getothername` | 裸字符串（配置名） | 裸字符串（该配置值） | — | 获取任意本地配置值 |
+| `getOther` | 忽略 | 裸字符串（other 值） | — | 获取 other 配置值 |
+
+### 8.4 交互 / 反馈
+
+| Handler | data | 同步返回 | 异步回传 | 功能 |
+|---|---|---|---|---|
+| `orientation` | 裸字符串（`"1"`横屏，其他竖屏） | 无 | — | 切换屏幕方向 |
+| `vibrator` | 裸字符串 long（毫秒） | 无 | — | 震动 |
+| `repeatvibrator` | 裸字符串 int（`-1`否/`1`重复） | 无 | — | 重复震动 |
+| `canclevibrator` | 忽略 | 无 | — | 取消震动 |
+| `gameCopytext` | 裸字符串（文本） | 无 | — | 写入剪贴板 |
+| `gamepastetext` | 忽略 | 裸字符串（剪贴板内容） | — | 读取剪贴板 |
+| `notification` | 裸字符串 | 无 | — | 发送通知（**空实现，未落地**） |
+
+### 8.5 摇一摇
+
+| Handler | data | 异步回传 | 功能 |
+|---|---|---|---|
+| `startshake` | 忽略 | `shakeEnd` | 开始监听摇一摇 |
+| `SwitchShake` | 裸字符串（`"1"`开声音震动/其他关） | — | 摇一摇声音开关 |
+| `stopshake` | 忽略 | — | 停止监听 |
+
+### 8.6 定位
+
+| Handler | data | 同步返回 | 异步回传 | 功能 |
+|---|---|---|---|---|
+| `startlocation` | 裸字符串（`"1"`连续/其他单次） | 无 | `getlocationinfo` | 开启定位 |
+| `getlocationinfo` | 忽略 | JSON（`MaplocationInfo`；未就绪返回错误码 JSON） | — | 主动取最近一次定位 |
+
+### 8.7 音频
+
+| Handler | data | 异步回传 | 功能 |
+|---|---|---|---|
+| `prepareaudio` | 忽略 | — | 准备/开始录音（长按） |
+| `mediaTypeAudio` | JSON（`audiourl/type/user`） | `gameui_play_voice` / `gameui_stop_voice` | 播放语音消息 |
+| `srcIsloop` | JSON（`src/isloop`） | 无 | 播放游戏音效/背景乐 |
+| `voicePlaying` | 裸字符串（`"1"`开/其他静音） | — | 语音播放总开关 |
+| `getaudiourl` 录音结果 | （由 `prepareaudio` 触发） | `getaudiourl` | 录音上传后回传地址 |
+
+### 8.8 扫码 / 相机 / 浏览器 / 网页
+
+| Handler | data | 同步返回 | 异步回传 | 功能 |
+|---|---|---|---|---|
+| `opensaoma` | 忽略 | 无 | `getsaomaData` | 打开扫一扫 |
+| `opencamera` | 忽略 | 无 | `getcameraaAddress` | 打开相机拍照 |
+| `browser` | 裸字符串（URL） | 无 | — | 系统/QQ 浏览器打开链接 |
+| `OpenurlTitleData` | JSON（`url/title/data`） | 无 | `getWebdata` | 打开内置网页容器（子游戏跳转，见 §11） |
+| `openApplyDownloadpath` | JSON（`packagename/downloadpath`） | 无 | — | 按包名启动 App，失败则浏览器打开下载地址 |
+
+### 8.9 子游戏切换 / 房间（音视频）
+
+| Handler | data | 同步返回 | 异步回传 | 功能 |
+|---|---|---|---|---|
+| `SwitchOverGameData` | JSON（`webtype/Gamedirectory/gamedownloadurl/data`） | 无 | — | 切换子游戏（容器内切换） |
+| `getGameinstall` | 裸字符串（目录名） | 裸字符串（`1`已装/`0`未装） | — | 判断子游戏资源是否已就绪 |
+| `createRoom` | 裸字符串（`videoinfobean` JSON） | 无 | — | 加入/创建音视频房间（声网） |
+| `exitRoom` | 裸字符串 | 无 | — | 退出房间 |
+| `getVideoinfo` | 裸字符串（`Othervideoinfo` JSON） | 无 | `getVideoinfo` | 请求/绑定远端视频窗口 |
+| `DragViewvideoIsshow` | 裸字符串（`"1"`显示/其他隐藏） | 无 | — | 视频悬浮框显隐 |
+
+### 8.10 退出 / 返回
+
+| Handler | data | 异步回传 | 功能 | 备注 |
+|---|---|---|---|---|
+| `finsh` | 忽略 | — | 退出游戏 | 名字即代码原样（拼写如此） |
+| `backgameData` | 裸字符串（data） | — | 子游戏带数据返回大厅 | **仅 `NewwebviewActivity` 有**；以结果码 101 回传给上层容器 |
+| `getAddressBook` | 忽略 | （`getAddressbook` 已注释） | 获取通讯录 | **未实现** |
+
+### 8.11 两容器差异小结
+
+| 接口 | `webviewActivity`（大厅） | `NewwebviewActivity`（子游戏/微信回调） |
+|---|---|---|
+| `getGameplay`（App 内微信支付） | ✅ 生效 | ❌ 已注释（改用 `paybrowser`） |
+| `backgameData`（带数据返回） | ❌ 无 | ✅ 有 |
+| `getlocationinfo` 错误码 | 未就绪返回裸 `null` | 返回结构化错误码 JSON（`-1` 未就绪/`-2` 权限拒绝） |
+| 分享内部分流 | 直连微信 SDK 多分支 | 按 `sharefriend` 分流到统一分享面板 |
+| 其余 ~40 个 handler | 完全一致 | 完全一致 |
+
+> 适配结论：实现**统一一套**入站 handler，并对差异项采用更完整的一侧（如 `getlocationinfo` 用结构化错误码、同时支持 `paybrowser` 与 `backgameData`）即可兼容两个容器。
+
+---
+
+## 9. 接口契约二：原生 → H5（出站 Handler 全集）
+
+> 原生通过 `callHandler('<名称>', '<data>', null)` 调用；**H5 必须用 `registerHandler('<名称>', ...)` 注册才能收到**。
+> 来源：两容器内 `callHandler` 调用点。
+
+| Handler | data | 调用时机 |
+|---|---|---|
+| `appservice` | 裸字符串（`"1"`前台/`"2"`后台） | 页面首次加载到 100%、以及前后台切换（resume/pause/stop、息屏/解锁） |
+| `setPostUrl` | 裸字符串（`http://<本机IP>:<端口>/testurl`） | 页面加载完成时，下发截图上传地址 |
+| `getWebdata` | 裸字符串（网页回传 text / Intent 透传 data） | 页面首次加载完成；或内置网页关闭回传（结果码 101） |
+| `getphoto` | JSON 数组（`[{pid, photourl}]`） | 图片/头像下载完成 |
+| `sharelogin` | JSON（`openid/headimgurl/nickname/sex/city/province/unionid`） | 微信授权登录成功后 |
+| `sharesuccess` | JSON（`{success:int, type:int}`，success 2 成功/3 取消） | 分享结果回调（仅微信完整） |
+| `shakeEnd` | 空字符串 `""` | 摇一摇触发后约 1 秒 |
+| `getBattery` | 裸字符串 float（0~1） | H5 主动取电量时；或电量变化广播 |
+| `getwifiLevel` | JSON（`{ssidname:String, signalLevel:int(0~4)}`） | H5 主动取时；或 WiFi 变化广播 |
+| `getnetwork` | 裸字符串 int（`1`断网/`2`WiFi/`3`移动） | 网络状态变化广播 |
+| `getaudiourl` | JSON（`{audiourl:String, time:float}`；旧容器 `webviewActivity` 录音成功时**额外携带 `filepath:String`**，值与 `audiourl` 相同；取消时 audiourl="" time=0） | 录音上传完成 / 录音取消 |
+| `gameui_play_voice` | 裸字符串（`user` 透传） | 语音开始播放 |
+| `gameui_stop_voice` | 裸字符串（`user` 透传） | 语音播放完成 / 被打断 |
+| `getphoneinfo` | JSON（`phoneInfoBean`，见 §12） | H5 调 `getphoneInfo` 后 |
+| `getVideoinfo` | 裸字符串 int（远端 uid） | 音视频房间其他用户加入时 |
+| `PayuserPaytypePaystate` | JSON（`{user, state, typeplay, type, data}`，state 1 成功/0 取消） | App 内微信支付结果（仅旧版容器） |
+| `getlocationinfo` | JSON（`MaplocationInfo`；或错误码 JSON） | 定位成功（单次 1 次/连续每 5s）；或权限被拒 |
+| `phonestate` | 裸字符串 int（来电状态） | 来电状态广播 |
+| `getsaomaData` | 裸字符串（扫码结果） | 扫码返回 |
+| `getcameraaAddress` | 裸字符串（照片路径） | 拍照返回 |
+
+> 名称陷阱：`NewwebviewActivity` 中有一处出站调用名为 `backgameData-`（**末尾带连字符**，data 为空字符串），用于返回键确认对话框流程；与入站的 `backgameData`（无连字符）是两个不同名字。适配时按代码原样区分。
+
+---
+
+## 10. 原生能力专题
+
+> 本节给出各设备能力的"H5 触发 → 入参 → 回传时机/结构"，原生内部如何对接第三方 SDK 不限。
+
+### 10.1 分享（微信 / QQ / 抖音）
+- **触发**：`friendsSharetypeUrlToptitleDescript`，入参 `sharetypeBean`（§12）。
+  - `sharefriend=="2"` → 微信朋友圈直发；`=="1"` → 弹分享面板由用户选目标（微信好友/QQ/抖音）。
+  - `type`：`"1"`网页/文本，`"2"`Canvas 截图（原生实时截当前 WebView 的 canvas 转 base64），`"3"`图片链接，抖音另有 `"4"`视频。
+- **回传**：仅微信完整 → `sharesuccess`（`{success,type}`，2 成功/3 取消）。
+- **现状/待补**：QQ、抖音当前**无结果回传**（QQ 回调被注释，抖音仅 Toast / 走外部 App scheme）。若 H5 依赖分享回调，新平台需为三端补齐统一 `sharesuccess` 回传。
+
+### 10.2 微信登录
+- **触发**：`accreditlogin`（非 `"1"` 即微信），scope=`snsapi_userinfo`。
+- **回传**：`sharelogin`，回传**用户资料**（openid/unionid/nickname/headimgurl/sex/city/province），非 code。
+- **安全提示**：现有实现用客户端硬编码 AppSecret 换 token（见 §13），新平台**建议改为回传 code、由服务端换取**。
+
+### 10.3 支付
+- **当前生效**：`paybrowser`（data 为收银台 URL，原生开浏览器，无回传，H5 收银台自理）。
+- **旧版 App 内支付**：`getGameplay` → 微信 SDK → `PayuserPaytypePaystate` 回传结果（仅旧版容器）。`PayReq` 字段：`appId/partnerId/prepayId/packageValue("Sign=WXPay")/nonceStr/timeStamp/sign(MD5大写)`。
+
+### 10.4 抖音 / 快手登录
+- **未实现**：现有 `sgapi` 实为"闲聊（Xianliao）SDK"且整文件注释，无桥接入。新平台如需，须全新对接抖音开放平台/快手 SDK，建议回传 code 给 H5。
+
+### 10.5 截图 / Canvas
+- 截图当前**耦合在分享流程内部**，无独立 handler。原生注入 JS 调 H5 `canvas.toDataURL`（默认 image/jpeg 720×405；指定 id 则 png），失败回退原生绘制；结果直接交分享，不回传 H5。
+- **待补建议**：若 H5 需主动截图，新增 handler（如 `getCanvasBase64`，入参 canvasId/格式/尺寸，返回纯 base64 或 dataURL）。
+
+### 10.6 音频
+- 远程语音消息：`mediaTypeAudio` 播放 → `gameui_play_voice` / `gameui_stop_voice` 回传（透传 `user`）。
+- 游戏音效/背景乐：`srcIsloop`，`src` 为 wav 文件名（非 URL），路径 `<解压根>/<game>/assets/wav/<src>`；`isloop`：`0` 播一次 / `>0` 循环 / `<0` 停止。无回传。
+- 静音总开关：`voicePlaying`。
+- 录音：`prepareaudio` 录音 → 上传 → `getaudiourl` 回传 `{audiourl,time}`。
+
+### 10.7 摇一摇
+- `startshake` 开始 → 触发后约 1 秒 `callHandler('shakeEnd','')` → 自动重新监听。`SwitchShake` 控声音，`stopshake` 停止。
+- 灵敏度等参数原生内部决定（现有实现加速度阈值约 3500）。
+
+### 10.8 定位（高德）
+- `startlocation`（`"1"`连续/5s 间隔，其他单次）→ `getlocationinfo` 推 `MaplocationInfo`。
+- `getlocationinfo` 也可同步主动取（一名两用）。
+- 错误码约定：`0` 成功 / 高德原始码 / `-1` 未就绪 / `-2` 权限被拒。
+- 新平台用本平台定位服务实现，**只要回传 `MaplocationInfo` 同结构同字段即可**。
+
+---
+
+## 11. 子游戏跳转与通用网页容器
+
+> H5 从大厅进入"另一个页面"有**两条独立路径**，机制完全不同，新平台都要实现：
+> - **路径 A（容器内切换子游戏）**：`SwitchOverGameData` → 在**同一个 BridgeWebView 容器**内重载到另一个游戏目录，仍走 §2 Bridge 协议。
+> - **路径 B（打开通用网页）**：`OpenurlTitleData` → 打开**独立的通用网页容器 `openwebActivity1`**，该容器用 §11.3 的**另一套接口机制**（`settings` 对象注入 + `javascript:` 直调）。
+
+### 11.1 路径 A：容器内切换子游戏（SwitchOverGameData）
+
+> 来源：`webviewActivity`/`NewwebviewActivity` 的 `SwitchOverGameData` → `initgame()`。
+
+- H5 调用：`bridge.callHandler('SwitchOverGameData', JSON.stringify({webtype, Gamedirectory, gamedownloadurl, data}))`
+  - `webtype`：`"2"`竖屏 / `"3"`横屏
+  - `Gamedirectory`：目标游戏目录名
+  - `gamedownloadurl`：游戏 id（用于判断/下载）
+  - `data`：交换数据
+- 原生在**当前 BridgeWebView 容器内**重载到 `file://<解压根>/<Gamedirectory>/index.html?Launchtype=1`（必要时先下载解压该游戏 zip），**桥协议与全部 handler 不变**，对 H5 透明。
+
+**关键结论**：本路径下子游戏 H5 通常已包含在 §5 下载解压的整包内；原生按 `Gamedirectory` 切换目录加载，仍复用同一套 Bridge 接口。
+
+### 11.2 路径 B：打开通用网页（OpenurlTitleData）
+
+> 来源：`webviewActivity`/`NewwebviewActivity` 的 `OpenurlTitleData` → 打开 `openwebActivity1`。
+
+```
+大厅/游戏 H5 拼好目标地址（本地 file:// 或远程 http://）
+  ▼
+bridge.callHandler('OpenurlTitleData', JSON.stringify({url, title, data}))
+  ▼
+原生打开通用网页容器 openwebActivity1，加载该 url（Intent extra：url/title/data/orientation）
+  │   orientation："1"=竖屏，其他=横屏
+  ▼
+页面加载到 100% → 原生用【javascript: 直调】getWebdata('<data>') 把交互数据交给页面
+  ▼
+页面内 H5 调 settings.backgameData('<data>')（或返回键确认）→ 原生 setResult(101, data) 退出
+  ▼
+回到上层 Bridge 容器 → 上层收到出站 getWebdata（携带回传 data）
+```
+
+> 注意：`openwebActivity1` **不是 BridgeWebView**，页面里**无 `window.WebViewJavascriptBridge`**，H5 在该容器内只能用 §11.3 的 `settings` 接口和被原生 `javascript:` 直调的全局函数。
+
+### 11.3 通用网页容器 openwebActivity1 的独立接口契约
+
+> 来源：`openwebActivity1.java`。机制 = **普通 WebView + 注入对象 `settings`（`@JavascriptInterface`）+ 原生 `javascript:` 直接调用全局函数**。新平台需为该容器单独实现这套契约（等价于 HarmonyOS 的 `javaScriptProxy` + `runJavaScript`）。
+
+#### (1) H5 → 原生：全局注入对象 `settings`（对象名固定为 `settings`）
+
+H5 直接调用 `window.settings.<方法>(...)`：
+
+| 方法签名 | 参数 | 功能 |
+|---|---|---|
+| `settings.backgameData(data)` | `data`:String | 带数据返回上层容器（原生 `setResult(101,{data})` 并关闭本页） |
+| `settings.loadurl(urls)` | `urls`:String | 在本容器加载新 url |
+| `settings.browser(browserurl)` | `browserurl`:String | 用系统/QQ 浏览器打开链接 |
+| `settings.finishweb()` | 无 | 直接关闭本页 |
+| `settings.isexitdialogeshow()` | 无 | 开启"返回时弹退出确认框"行为 |
+| `settings.isbackfinishweb()` | 无 | 设置返回键改为交给 H5（触发下方 `gamebackkeydown()`）而非直接关闭 |
+
+#### (2) 原生 → H5：`javascript:` 直接调用的全局函数（H5 需在 window 上定义同名函数）
+
+| 全局函数（H5 须实现） | 参数 | 调用时机 |
+|---|---|---|
+| `getWebdata('<data>')` | 字符串 data（来自打开时传入的 `data`） | 页面首次加载到 100% 时 |
+| `gamebackkeydown()` | 无 | 按下返回键、且 H5 已通过 `settings.isbackfinishweb()` 接管返回键、且 WebView 可后退时 |
+| `backgameData()` | 无（**注意：与 H5→原生的 `settings.backgameData(data)` 同名但无参、方向相反**） | "返回退出确认框"点确认时，原生回调通知页面即将退出 |
+
+#### (3) 该容器的 WebView 设置差异（相对 §7 主容器）
+
+- **不注入** `WebViewJavascriptBridge.js`；无 `yy://` 拦截。
+- 缓存策略不同：有网时用默认缓存（`LOAD_DEFAULT`），无网时用缓存优先（`LOAD_CACHE_ELSE_NETWORK`）；启用 AppCache。
+- 同样启用：JavaScript、DOMStorage、文件访问、file:// 跨源访问、定位；禁缩放/禁多窗口。
+- WebViewClient 自行拦截 `weixin:` / `alipayqr:` / `alipays:` / `tel:` 等 scheme 跳转到系统处理。
+
+> 适配要点：新平台需提供**两类容器**——
+> ① BridgeWebView 容器（大厅+子游戏，§2 协议 + §8/§9 全部 handler）；
+> ② 通用网页容器（§11.3 的 `settings` 注入对象 6 方法 + `getWebdata`/`gamebackkeydown`/`backgameData` 三个 `javascript:` 直调）。
+> 两类容器都实现到位，现有 H5（含其打开的活动页/收银台/客服等）才能**零改动**运行。
+
+---
+
+## 12. 数据结构汇总
+
+> 字段名严格对应代码，新平台序列化必须保持**同名同语义**。
+
+### sharetypeBean（分享入参，全 String）
+```jsonc
+{
+  "sharefriend": "1",      // "1" 好友(弹面板) / "2" 朋友圈(直发微信)
+  "type": "1",             // "1" 网页/文本 / "2" Canvas截图 / "3" 图片链接 / "4" 视频(抖音)
+  "sharetype": "",         // 分享子类型
+  "webpageUrl": "https://...", // 分享链接 或 图片地址
+  "title": "标题",
+  "description": "描述"
+}
+```
+
+### MaplocationInfo（定位回传）
+```jsonc
+{
+  "latitude": 0.0, "longitude": 0.0,    // double
+  "address": "", "country": "", "province": "", "city": "",
+  "district": "", "street": "", "cityCode": "", "streetNum": "",
+  "adCode": "", "aoiName": "",          // 以上 String
+  "accuracy": 0.0,                       // float
+  "locationType": 0,                     // int
+  "errorCode": 0,                        // int：0 成功 / -1 未就绪 / -2 权限拒绝 / 其他=底层错误码
+  "errorMsg": ""                         // String
+}
+```
+
+### phoneInfoBean（手机信息回传，全 String）
+```jsonc
+{
+  "PhoneVersion": "", "PhoneAdresseMAC": "", "PhoneModel": "",
+  "PhoneDeviceBrand": "", "PhoneProvidersName": "",
+  "PhoneIMEI": "", "PhoneIMSI": ""
+}
+```
+
+### savephotoURLBean（图片下载，getphoto 回传数组元素）
+```jsonc
+{ "pid": "", "photourl": "" }
+```
+
+### videoinfobean（createRoom 入参，全 String）
+```jsonc
+{ "playerid":"", "roomid":"", "agentid":"", "gameid":"",
+  "left":"", "top":"", "pmw":"", "pmh":"", "width":"", "height":"" }
+```
+
+### Othervideoinfo（getVideoinfo 入参）
+```jsonc
+{ "playerid":"", "left":"", "top":"", "width":"", "height":"", "pmw":"", "pmh":"" }
+```
+
+### 支付相关
+- `getGameplay` 入参：`{ "price":"", "body":"", "typeplay":int, "type":"", "user":int }`
+- `PayuserPaytypePaystate` 回传：`{ "user":"", "state":int(1成功/0取消), "typeplay":"", "type":"", "data":"" }`
+
+### sharelogin（微信登录回传，全 String）
+```jsonc
+{ "openid":"", "headimgurl":"", "nickname":"", "sex":"", "city":"", "province":"", "unionid":"" }
+```
+
+### sharesuccess（分享回传）
+```jsonc
+{ "success": 2, "type": 1 }   // success: 2成功/3取消；type: 1好友/2朋友圈
+```
+
+---
+
+## 13. 关键常量与第三方账号
+
+> 来源：`simcpux/Constants.java`、`AndroidManifest.xml`。新平台需用自己的应用账号重新申请，下列仅说明依赖项。
+
+| 项 | 值 | 说明 |
+|---|---|---|
+| 微信 AppID | `wxd2bd650e06bdfe58` | 分享/登录/支付 |
+| 微信商户号 MCH_ID | `1448669802` | App 内支付 |
+| 微信 API_KEY | `ClMrQsAcidRa7uJT4TgHgVAOHbzQjdPa` | 支付签名（**应下沉服务端**） |
+| 微信 AppSecret | `1934a281c82ad1a059130fe51341b74b` | 登录换 token（**应下沉服务端**） |
+| 高德定位 API Key | `4f92bacc16cace69a6045a544d6e3c7d` | 定位 |
+| 微信回调 scheme | `wxd2bd650e06bdfe58` | 第三方回调 |
+| 自定义 scheme | `gamepaywelcome`、`gamepaywxd2bd650e06bdfe58` | H5/外部唤起原生页 |
+
+**关键权限**：存储读写、读电话状态、定位（精确+粗略）、安装应用、网络、相机、录音、允许明文 HTTP。
+
+> ⚠️ 安全提示：现有工程把微信 AppSecret / API_KEY 明文硬编码在客户端，存在风险。HarmonyOS 新版应将签名与换 token 逻辑下沉到服务端，登录改为回传 code。
+
+---
+
+## 14. HarmonyOS 适配检查清单与待决策项
+
+### 14.1 必做（保证 H5 零改动运行）
+
+- [ ] **实现 WebViewJavascriptBridge 协议**：URL scheme `yy://` 拦截、`_handleMessageFromNative` / `_fetchQueue`、Message JSON 结构、`onPageFinished` 注入 `WebViewJavascriptBridge.js`、启动消息队列补发（§2）。直接复用该库的 `WebViewJavascriptBridge.js`。
+- [ ] **实现全部入站 handler（§8）**：44 个，名称/参数结构/同步返回 1:1 对齐；差异项取更完整一侧。
+- [ ] **实现全部出站 handler 调用（§9）**：在对应时机以同名 `callHandler` 推送同结构 data。
+- [ ] **配置体系（§4）**：提供 §4.2 全部配置键取值（建议改用 KV 配置文件，无需沿用目录名编码）。
+- [ ] **远程配置请求与分层覆盖（§4.3/4.4）**：URL 拼装、二级 url 二次请求、agent→channel→market→game 后层覆盖、`showmessage` 阻断。
+- [ ] **资源管理（§5）**：内置包拷贝、version.xml 版本比较、远程 zip 下载/删旧/解压到资源目录。
+- [ ] **app_data.js 注入（§6）**：加载大厅前在大厅目录生成同名全局变量。
+- [ ] **大厅入口（§3）**：`weburl` 空 → `file://.../gamehall/index.html?Launchtype=0`；非空 → `http://<weburl去-换/>?Launchtype=0`。
+- [ ] **WebView 能力（§7）**：JS、DOMStorage、file/universal-file 访问、混合内容、明文 HTTP、禁缓存、禁缩放、定位。
+- [ ] **路径 A 子游戏切换（§11.1）**：`SwitchOverGameData` 在 BridgeWebView 容器内按目录重载、横竖屏切换。
+- [ ] **路径 B + 通用网页容器（§11.2/§11.3）**：`OpenurlTitleData` 打开独立网页容器；该容器实现 **`settings` 注入对象 6 方法**（`backgameData(data)`/`loadurl(urls)`/`browser(url)`/`finishweb()`/`isexitdialogeshow()`/`isbackfinishweb()`）+ **3 个 `javascript:` 直调全局函数**（`getWebdata(data)`/`gamebackkeydown()`/`backgameData()`）+ 结果码 101 回传上层 → 上层出站 `getWebdata`。**这是与主容器不同的第二套机制，勿遗漏。**
+- [ ] **本机 HTTP 上传端点 + `setPostUrl`（§7/§9）**：支撑截图分享上传。
+- [ ] **设备能力（§10）**：分享、微信登录/支付、定位、录音/音效、摇一摇、扫码、相机、震动、剪贴板、网络/电量/WiFi/电话状态。
+
+### 14.2 待决策 / 需补齐（现有 Android 即缺失，新平台应主动完善）
+
+| 事项 | 现状 | 建议 |
+|---|---|---|
+| QQ / 抖音分享结果回传 | 无回传 | 补齐统一 `sharesuccess` 回传 |
+| 抖音 / 快手登录 | 完全未实现（sgapi 是闲聊且注释） | 按需全新对接，回传 code |
+| 主动截图能力 | 仅耦合在分享内 | 新增独立 `getCanvasBase64` handler |
+| 通讯录 `getAddressBook` | 空实现 | 按需实现或保持空 |
+| `notification` 通知 | 空实现 | 按需实现 |
+| 微信 AppSecret/API_KEY 明文 | 客户端硬编码 | 下沉服务端，登录改 code 模式 |
+| `servertype` / `gameserver` 配置 | 有目录无代码读取 | 可不实现 |
+| App 内微信支付 vs 浏览器支付 | 新旧容器不一致 | 统一用 `paybrowser`，按需保留 App 内支付 |
+
+### 14.3 接口名"原样保留"陷阱清单（拼写以代码为准，不可纠正）
+
+- `finsh`（退出，非 finish）
+- `accreditlogin`、`friendsSharetypeUrlToptitleDescript`、`SwitchOverGameData`、`DragViewvideoIsshow`
+- `getcameraaAddress`（双 a）、`getsaomaData`、`opensaoma`
+- `PayuserPaytypePaystate`、`gameui_play_voice` / `gameui_stop_voice`
+- `canclevibrator`（非 cancel）、`repeatvibrator`
+- 出站 `backgameData-`（末尾连字符）≠ 入站 `backgameData`
+- 下载目录名 `dowlod_zip`（拼写如此）
+
+---
+
+> **结论**：H5 与原生之间的契约 = §2 桥协议 + §8 入站 44 handler + §9 出站约 21 handler + §6 `app_data.js` 注入 + §3~§5 启动与资源流程。新平台（HarmonyOS）只要让这套契约对外表现完全一致，现有 H5 即可**零改动**运行；原生内部实现方式不受任何限制。
diff --git a/entry/.gitignore b/entry/.gitignore
new file mode 100644
index 0000000..e2713a2
--- /dev/null
+++ b/entry/.gitignore
@@ -0,0 +1,6 @@
+/node_modules
+/oh_modules
+/.preview
+/build
+/.cxx
+/.test
\ No newline at end of file
diff --git a/entry/build-profile.json5 b/entry/build-profile.json5
new file mode 100644
index 0000000..6bd6457
--- /dev/null
+++ b/entry/build-profile.json5
@@ -0,0 +1,33 @@
+{
+  "apiType": "stageMode",
+  "buildOption": {
+    "resOptions": {
+      "copyCodeResource": {
+        "enable": false
+      }
+    }
+  },
+  "buildOptionSet": [
+    {
+      "name": "release",
+      "arkOptions": {
+        "obfuscation": {
+          "ruleOptions": {
+            "enable": false,
+            "files": [
+              "./obfuscation-rules.txt"
+            ]
+          }
+        }
+      }
+    },
+  ],
+  "targets": [
+    {
+      "name": "default"
+    },
+    {
+      "name": "ohosTest",
+    }
+  ]
+}
\ No newline at end of file
diff --git a/entry/hvigorfile.ts b/entry/hvigorfile.ts
new file mode 100644
index 0000000..b0e3a1a
--- /dev/null
+++ b/entry/hvigorfile.ts
@@ -0,0 +1,6 @@
+import { hapTasks } from '@ohos/hvigor-ohos-plugin';
+
+export default {
+  system: hapTasks, /* Built-in plugin of Hvigor. It cannot be modified. */
+  plugins: []       /* Custom plugin to extend the functionality of Hvigor. */
+}
\ No newline at end of file
diff --git a/entry/obfuscation-rules.txt b/entry/obfuscation-rules.txt
new file mode 100644
index 0000000..1e7e54e
--- /dev/null
+++ b/entry/obfuscation-rules.txt
@@ -0,0 +1,23 @@
+# Define project specific obfuscation rules here.
+# You can include the obfuscation configuration files in the current module's build-profile.json5.
+#
+# For more details, see
+#   https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/source-obfuscation
+
+# Obfuscation options:
+# -disable-obfuscation: disable all obfuscations
+# -enable-property-obfuscation: obfuscate the property names
+# -enable-toplevel-obfuscation: obfuscate the names in the global scope
+# -compact: remove unnecessary blank spaces and all line feeds
+# -remove-log: remove all console.* statements
+# -print-namecache: print the name cache that contains the mapping from the old names to new names
+# -apply-namecache: reuse the given cache file
+
+# Keep options:
+# -keep-property-name: specifies property names that you want to keep
+# -keep-global-name: specifies names that you want to keep in the global scope
+
+-enable-property-obfuscation
+-enable-toplevel-obfuscation
+-enable-filename-obfuscation
+-enable-export-obfuscation
\ No newline at end of file
diff --git a/entry/oh-package.json5 b/entry/oh-package.json5
new file mode 100644
index 0000000..248c3b7
--- /dev/null
+++ b/entry/oh-package.json5
@@ -0,0 +1,10 @@
+{
+  "name": "entry",
+  "version": "1.0.0",
+  "description": "Please describe the basic information.",
+  "main": "",
+  "author": "",
+  "license": "",
+  "dependencies": {}
+}
+
diff --git a/entry/src/main/ets/entryability/EntryAbility.ets b/entry/src/main/ets/entryability/EntryAbility.ets
new file mode 100644
index 0000000..091797f
--- /dev/null
+++ b/entry/src/main/ets/entryability/EntryAbility.ets
@@ -0,0 +1,48 @@
+import { AbilityConstant, ConfigurationConstant, UIAbility, Want } from '@kit.AbilityKit';
+import { hilog } from '@kit.PerformanceAnalysisKit';
+import { window } from '@kit.ArkUI';
+
+const DOMAIN = 0x0000;
+
+export default class EntryAbility extends UIAbility {
+  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
+    try {
+      this.context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET);
+    } catch (err) {
+      hilog.error(DOMAIN, 'testTag', 'Failed to set colorMode. Cause: %{public}s', JSON.stringify(err));
+    }
+    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onCreate');
+  }
+
+  onDestroy(): void {
+    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onDestroy');
+  }
+
+  onWindowStageCreate(windowStage: window.WindowStage): void {
+    // Main window is created, set main page for this ability
+    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
+
+    windowStage.loadContent('pages/Index', (err) => {
+      if (err.code) {
+        hilog.error(DOMAIN, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err));
+        return;
+      }
+      hilog.info(DOMAIN, 'testTag', 'Succeeded in loading the content.');
+    });
+  }
+
+  onWindowStageDestroy(): void {
+    // Main window is destroyed, release UI related resources
+    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onWindowStageDestroy');
+  }
+
+  onForeground(): void {
+    // Ability has brought to foreground
+    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onForeground');
+  }
+
+  onBackground(): void {
+    // Ability has back to background
+    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onBackground');
+  }
+}
\ No newline at end of file
diff --git a/entry/src/main/ets/entrybackupability/EntryBackupAbility.ets b/entry/src/main/ets/entrybackupability/EntryBackupAbility.ets
new file mode 100644
index 0000000..8e4de99
--- /dev/null
+++ b/entry/src/main/ets/entrybackupability/EntryBackupAbility.ets
@@ -0,0 +1,16 @@
+import { hilog } from '@kit.PerformanceAnalysisKit';
+import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit';
+
+const DOMAIN = 0x0000;
+
+export default class EntryBackupAbility extends BackupExtensionAbility {
+  async onBackup() {
+    hilog.info(DOMAIN, 'testTag', 'onBackup ok');
+    await Promise.resolve();
+  }
+
+  async onRestore(bundleVersion: BundleVersion) {
+    hilog.info(DOMAIN, 'testTag', 'onRestore ok %{public}s', JSON.stringify(bundleVersion));
+    await Promise.resolve();
+  }
+}
\ No newline at end of file
diff --git a/entry/src/main/ets/pages/Index.ets b/entry/src/main/ets/pages/Index.ets
new file mode 100644
index 0000000..8e2d24a
--- /dev/null
+++ b/entry/src/main/ets/pages/Index.ets
@@ -0,0 +1,23 @@
+@Entry
+@Component
+struct Index {
+  @State message: string = 'Hello World';
+
+  build() {
+    RelativeContainer() {
+      Text(this.message)
+        .id('HelloWorld')
+        .fontSize($r('app.float.page_text_font_size'))
+        .fontWeight(FontWeight.Bold)
+        .alignRules({
+          center: { anchor: '__container__', align: VerticalAlign.Center },
+          middle: { anchor: '__container__', align: HorizontalAlign.Center }
+        })
+        .onClick(() => {
+          this.message = 'Welcome';
+        })
+    }
+    .height('100%')
+    .width('100%')
+  }
+}
\ No newline at end of file
diff --git a/entry/src/main/module.json5 b/entry/src/main/module.json5
new file mode 100644
index 0000000..53024e8
--- /dev/null
+++ b/entry/src/main/module.json5
@@ -0,0 +1,50 @@
+{
+  "module": {
+    "name": "entry",
+    "type": "entry",
+    "description": "$string:module_desc",
+    "mainElement": "EntryAbility",
+    "deviceTypes": [
+      "phone"
+    ],
+    "deliveryWithInstall": true,
+    "installationFree": false,
+    "pages": "$profile:main_pages",
+    "abilities": [
+      {
+        "name": "EntryAbility",
+        "srcEntry": "./ets/entryability/EntryAbility.ets",
+        "description": "$string:EntryAbility_desc",
+        "icon": "$media:layered_image",
+        "label": "$string:EntryAbility_label",
+        "startWindowIcon": "$media:startIcon",
+        "startWindowBackground": "$color:start_window_background",
+        "exported": true,
+        "skills": [
+          {
+            "entities": [
+              "entity.system.home"
+            ],
+            "actions": [
+              "ohos.want.action.home"
+            ]
+          }
+        ]
+      }
+    ],
+    "extensionAbilities": [
+      {
+        "name": "EntryBackupAbility",
+        "srcEntry": "./ets/entrybackupability/EntryBackupAbility.ets",
+        "type": "backup",
+        "exported": false,
+        "metadata": [
+          {
+            "name": "ohos.extension.backup",
+            "resource": "$profile:backup_config"
+          }
+        ],
+      }
+    ]
+  }
+}
\ No newline at end of file
diff --git a/entry/src/main/resources/base/element/color.json b/entry/src/main/resources/base/element/color.json
new file mode 100644
index 0000000..3c71296
--- /dev/null
+++ b/entry/src/main/resources/base/element/color.json
@@ -0,0 +1,8 @@
+{
+  "color": [
+    {
+      "name": "start_window_background",
+      "value": "#FFFFFF"
+    }
+  ]
+}
\ No newline at end of file
diff --git a/entry/src/main/resources/base/element/float.json b/entry/src/main/resources/base/element/float.json
new file mode 100644
index 0000000..33ea223
--- /dev/null
+++ b/entry/src/main/resources/base/element/float.json
@@ -0,0 +1,8 @@
+{
+  "float": [
+    {
+      "name": "page_text_font_size",
+      "value": "50fp"
+    }
+  ]
+}
diff --git a/entry/src/main/resources/base/element/string.json b/entry/src/main/resources/base/element/string.json
new file mode 100644
index 0000000..f945955
--- /dev/null
+++ b/entry/src/main/resources/base/element/string.json
@@ -0,0 +1,16 @@
+{
+  "string": [
+    {
+      "name": "module_desc",
+      "value": "module description"
+    },
+    {
+      "name": "EntryAbility_desc",
+      "value": "description"
+    },
+    {
+      "name": "EntryAbility_label",
+      "value": "label"
+    }
+  ]
+}
\ No newline at end of file
diff --git a/entry/src/main/resources/base/media/background.png b/entry/src/main/resources/base/media/background.png
new file mode 100644
index 0000000..923f2b3
Binary files /dev/null and b/entry/src/main/resources/base/media/background.png differ
diff --git a/entry/src/main/resources/base/media/foreground.png b/entry/src/main/resources/base/media/foreground.png
new file mode 100644
index 0000000..97014d3
Binary files /dev/null and b/entry/src/main/resources/base/media/foreground.png differ
diff --git a/entry/src/main/resources/base/media/layered_image.json b/entry/src/main/resources/base/media/layered_image.json
new file mode 100644
index 0000000..fb49920
--- /dev/null
+++ b/entry/src/main/resources/base/media/layered_image.json
@@ -0,0 +1,7 @@
+{
+  "layered-image":
+  {
+    "background" : "$media:background",
+    "foreground" : "$media:foreground"
+  }
+}
\ No newline at end of file
diff --git a/entry/src/main/resources/base/media/startIcon.png b/entry/src/main/resources/base/media/startIcon.png
new file mode 100644
index 0000000..205ad8b
Binary files /dev/null and b/entry/src/main/resources/base/media/startIcon.png differ
diff --git a/entry/src/main/resources/base/profile/backup_config.json b/entry/src/main/resources/base/profile/backup_config.json
new file mode 100644
index 0000000..78f40ae
--- /dev/null
+++ b/entry/src/main/resources/base/profile/backup_config.json
@@ -0,0 +1,3 @@
+{
+  "allowToBackupRestore": true
+}
\ No newline at end of file
diff --git a/entry/src/main/resources/base/profile/main_pages.json b/entry/src/main/resources/base/profile/main_pages.json
new file mode 100644
index 0000000..1898d94
--- /dev/null
+++ b/entry/src/main/resources/base/profile/main_pages.json
@@ -0,0 +1,5 @@
+{
+  "src": [
+    "pages/Index"
+  ]
+}
diff --git a/entry/src/main/resources/dark/element/color.json b/entry/src/main/resources/dark/element/color.json
new file mode 100644
index 0000000..79b11c2
--- /dev/null
+++ b/entry/src/main/resources/dark/element/color.json
@@ -0,0 +1,8 @@
+{
+  "color": [
+    {
+      "name": "start_window_background",
+      "value": "#000000"
+    }
+  ]
+}
\ No newline at end of file
diff --git a/entry/src/mock/mock-config.json5 b/entry/src/mock/mock-config.json5
new file mode 100644
index 0000000..7a73a41
--- /dev/null
+++ b/entry/src/mock/mock-config.json5
@@ -0,0 +1,2 @@
+{
+}
\ No newline at end of file
diff --git a/entry/src/ohosTest/ets/test/Ability.test.ets b/entry/src/ohosTest/ets/test/Ability.test.ets
new file mode 100644
index 0000000..85c78f6
--- /dev/null
+++ b/entry/src/ohosTest/ets/test/Ability.test.ets
@@ -0,0 +1,35 @@
+import { hilog } from '@kit.PerformanceAnalysisKit';
+import { describe, beforeAll, beforeEach, afterEach, afterAll, it, expect } from '@ohos/hypium';
+
+export default function abilityTest() {
+  describe('ActsAbilityTest', () => {
+    // Defines a test suite. Two parameters are supported: test suite name and test suite function.
+    beforeAll(() => {
+      // Presets an action, which is performed only once before all test cases of the test suite start.
+      // This API supports only one parameter: preset action function.
+    })
+    beforeEach(() => {
+      // Presets an action, which is performed before each unit test case starts.
+      // The number of execution times is the same as the number of test cases defined by **it**.
+      // This API supports only one parameter: preset action function.
+    })
+    afterEach(() => {
+      // Presets a clear action, which is performed after each unit test case ends.
+      // The number of execution times is the same as the number of test cases defined by **it**.
+      // This API supports only one parameter: clear action function.
+    })
+    afterAll(() => {
+      // Presets a clear action, which is performed after all test cases of the test suite end.
+      // This API supports only one parameter: clear action function.
+    })
+    it('assertContain', 0, () => {
+      // Defines a test case. This API supports three parameters: test case name, filter parameter, and test case function.
+      hilog.info(0x0000, 'testTag', '%{public}s', 'it begin');
+      let a = 'abc';
+      let b = 'b';
+      // Defines a variety of assertion methods, which are used to declare expected boolean conditions.
+      expect(a).assertContain(b);
+      expect(a).assertEqual(a);
+    })
+  })
+}
\ No newline at end of file
diff --git a/entry/src/ohosTest/ets/test/List.test.ets b/entry/src/ohosTest/ets/test/List.test.ets
new file mode 100644
index 0000000..794c7dc
--- /dev/null
+++ b/entry/src/ohosTest/ets/test/List.test.ets
@@ -0,0 +1,5 @@
+import abilityTest from './Ability.test';
+
+export default function testsuite() {
+  abilityTest();
+}
\ No newline at end of file
diff --git a/entry/src/ohosTest/module.json5 b/entry/src/ohosTest/module.json5
new file mode 100644
index 0000000..509a3a2
--- /dev/null
+++ b/entry/src/ohosTest/module.json5
@@ -0,0 +1,11 @@
+{
+  "module": {
+    "name": "entry_test",
+    "type": "feature",
+    "deviceTypes": [
+      "phone"
+    ],
+    "deliveryWithInstall": true,
+    "installationFree": false
+  }
+}
diff --git a/entry/src/test/List.test.ets b/entry/src/test/List.test.ets
new file mode 100644
index 0000000..bb5b5c3
--- /dev/null
+++ b/entry/src/test/List.test.ets
@@ -0,0 +1,5 @@
+import localUnitTest from './LocalUnit.test';
+
+export default function testsuite() {
+  localUnitTest();
+}
\ No newline at end of file
diff --git a/entry/src/test/LocalUnit.test.ets b/entry/src/test/LocalUnit.test.ets
new file mode 100644
index 0000000..165fc16
--- /dev/null
+++ b/entry/src/test/LocalUnit.test.ets
@@ -0,0 +1,33 @@
+import { describe, beforeAll, beforeEach, afterEach, afterAll, it, expect } from '@ohos/hypium';
+
+export default function localUnitTest() {
+  describe('localUnitTest', () => {
+    // Defines a test suite. Two parameters are supported: test suite name and test suite function.
+    beforeAll(() => {
+      // Presets an action, which is performed only once before all test cases of the test suite start.
+      // This API supports only one parameter: preset action function.
+    });
+    beforeEach(() => {
+      // Presets an action, which is performed before each unit test case starts.
+      // The number of execution times is the same as the number of test cases defined by **it**.
+      // This API supports only one parameter: preset action function.
+    });
+    afterEach(() => {
+      // Presets a clear action, which is performed after each unit test case ends.
+      // The number of execution times is the same as the number of test cases defined by **it**.
+      // This API supports only one parameter: clear action function.
+    });
+    afterAll(() => {
+      // Presets a clear action, which is performed after all test cases of the test suite end.
+      // This API supports only one parameter: clear action function.
+    });
+    it('assertContain', 0, () => {
+      // Defines a test case. This API supports three parameters: test case name, filter parameter, and test case function.
+      let a = 'abc';
+      let b = 'b';
+      // Defines a variety of assertion methods, which are used to declare expected boolean conditions.
+      expect(a).assertContain(b);
+      expect(a).assertEqual(a);
+    });
+  });
+}
\ No newline at end of file
diff --git a/hvigor/hvigor-config.json5 b/hvigor/hvigor-config.json5
new file mode 100644
index 0000000..4481d31
--- /dev/null
+++ b/hvigor/hvigor-config.json5
@@ -0,0 +1,23 @@
+{
+  "modelVersion": "6.1.1",
+  "dependencies": {
+  },
+  "execution": {
+    // "analyze": "normal",                     /* Define the build analyze mode. Value: [ "normal" | "advanced" | "ultrafine" | false ]. Default: "normal" */
+    // "daemon": true,                          /* Enable daemon compilation. Value: [ true | false ]. Default: true */
+    // "incremental": true,                     /* Enable incremental compilation. Value: [ true | false ]. Default: true */
+    // "parallel": true,                        /* Enable parallel compilation. Value: [ true | false ]. Default: true */
+    // "typeCheck": false,                      /* Enable typeCheck. Value: [ true | false ]. Default: false */
+    // "optimizationStrategy": "memory"         /* Define the optimization strategy. Value: [ "memory" | "performance" ]. Default: "memory" */
+  },
+  "logging": {
+    // "level": "info"                          /* Define the log level. Value: [ "debug" | "info" | "warn" | "error" ]. Default: "info" */
+  },
+  "debugging": {
+    // "stacktrace": false                      /* Disable stacktrace compilation. Value: [ true | false ]. Default: false */
+  },
+  "nodeOptions": {
+    // "maxOldSpaceSize": 8192                  /* Enable nodeOptions maxOldSpaceSize compilation. Unit M. Used for the daemon process. Default: 8192*/
+    // "exposeGC": true                         /* Enable to trigger garbage collection explicitly. Default: true*/
+  }
+}
diff --git a/hvigorfile.ts b/hvigorfile.ts
new file mode 100644
index 0000000..47113e2
--- /dev/null
+++ b/hvigorfile.ts
@@ -0,0 +1,6 @@
+import { appTasks } from '@ohos/hvigor-ohos-plugin';
+
+export default {
+  system: appTasks, /* Built-in plugin of Hvigor. It cannot be modified. */
+  plugins: []       /* Custom plugin to extend the functionality of Hvigor. */
+}
\ No newline at end of file
diff --git a/oh-package-lock.json5 b/oh-package-lock.json5
new file mode 100644
index 0000000..c5a91ec
--- /dev/null
+++ b/oh-package-lock.json5
@@ -0,0 +1,28 @@
+{
+  "meta": {
+    "stableOrder": true,
+    "enableUnifiedLockfile": false
+  },
+  "lockfileVersion": 3,
+  "ATTENTION": "THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.",
+  "specifiers": {
+    "@ohos/hamock@1.0.0": "@ohos/hamock@1.0.0",
+    "@ohos/hypium@1.0.25": "@ohos/hypium@1.0.25"
+  },
+  "packages": {
+    "@ohos/hamock@1.0.0": {
+      "name": "@ohos/hamock",
+      "version": "1.0.0",
+      "integrity": "sha512-K6lDPYc6VkKe6ZBNQa9aoG+ZZMiwqfcR/7yAVFSUGIuOAhPvCJAo9+t1fZnpe0dBRBPxj2bxPPbKh69VuyAtDg==",
+      "resolved": "https://ohpm.openharmony.cn/ohpm/@ohos/hamock/-/hamock-1.0.0.har",
+      "registryType": "ohpm"
+    },
+    "@ohos/hypium@1.0.25": {
+      "name": "@ohos/hypium",
+      "version": "1.0.25",
+      "integrity": "sha512-l6uO2pjl8HyEKdekLqQt7tUpWbDqX/42zoAzkagtUVZAW9jT6lMvbe54MVjoLxq/RwQGygRvi6j4GpypSMFSHw==",
+      "resolved": "https://ohpm.openharmony.cn/ohpm/@ohos/hypium/-/hypium-1.0.25.har",
+      "registryType": "ohpm"
+    }
+  }
+}
\ No newline at end of file
diff --git a/oh-package.json5 b/oh-package.json5
new file mode 100644
index 0000000..01177cc
--- /dev/null
+++ b/oh-package.json5
@@ -0,0 +1,10 @@
+{
+  "modelVersion": "6.1.1",
+  "description": "Please describe the basic information.",
+  "dependencies": {
+  },
+  "devDependencies": {
+    "@ohos/hypium": "1.0.25",
+    "@ohos/hamock": "1.0.0"
+  }
+}