@ohos-cpf/3rdloop 0.0.12 → 0.0.13

package/vendor/Server/Skills/flutter-build-test/scripts/update-buildenv.cjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+/**
+ * update-buildenv.cjs — 按编译矩阵结果更新 buildEnv.sh
+ *
+ * 行为:
+ *   1. 读取 {libRoot}/buildEnv.sh（不存在则按模板新建，含 Apache License 头）
+ *   2. FLUTTER_SDK_VERSION ← 最高支持版本实测通过的 flvm 分支名（来自 build-matrix-results.json）
+ *   3. BUILD_PKG_DIR ← 实际 example 相对路径（原值正确则不动，可 --pkg-dir 显式指定）
+ *   4. 只改变量行，保留 License 头与既有结构
+ *   5. 输出变更对照到 {outputDir}/buildenv-update-report.json
+ *
+ * 用法:
+ *   node update-buildenv.cjs --source <libRoot> --results <build-matrix-results.json> \
+ *     [--branch <flvm分支>] [--pkg-dir <example相对路径>] [--example <example绝对路径>]
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// ── 参数解析 ─────────────────────────────────────────────
+
+function parseArgs(argv) {
+  if (argv.length > 0 && typeof argv[0] === 'string' && argv[0].startsWith('{')) {
+    try { return JSON.parse(argv[0]); } catch (e) { return {}; }
+  }
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    switch (argv[i]) {
+      case '--source': args.source = argv[++i]; break;
+      case '--results': args.results = argv[++i]; break;
+      case '--branch': args.branch = argv[++i]; break;
+      case '--pkg-dir': args.pkgDir = argv[++i]; break;
+      case '--example': args.example = argv[++i]; break;
+    }
+  }
+  return args;
+}
+
+// ── buildEnv.sh 模板（新建时使用） ────────────────────────
+
+const BUILDENV_TEMPLATE = [
+  '#!/bin/bash',
+  '  # Copyright (C) 2026 Huawei Device Co., Ltd.',
+  '  # Licensed under the Apache License, Version 2.0 (the "License");',
+  '  # you may not use this file except in compliance with the License.',
+  '  # You may obtain a copy of the License at',
+  '  #',
+  '  #     http://www.apache.org/licenses/LICENSE-2.0',
+  '  #',
+  '  # Unless required by applicable law or agreed to in writing, software',
+  '  # distributed under the License is distributed on an "AS IS" BASIS,',
+  '  # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.',
+  '  # See the License for the specific language governing permissions and',
+  '  # limitations under the License.',
+  '  #/',
+  '  ',
+  '  BUILD_PKG_DIR=example',
+  '  FLUTTER_SDK_VERSION=oh-3.35.7-dev',
+  '',
+].join('\n');
+
+// ── 主流程 ───────────────────────────────────────────────
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const libRoot = args.source ? path.resolve(args.source) : null;
+  if (!libRoot || !fs.existsSync(libRoot)) {
+    console.error('[update-buildenv] 错误: --source 必须为存在的目录');
+    process.exit(1);
+  }
+
+  // 读取编译结果，确定最高支持版本分支
+  let results = null;
+  if (args.results && fs.existsSync(args.results)) {
+    try { results = JSON.parse(fs.readFileSync(args.results, 'utf-8')); } catch (e) {
+      console.error(`[update-buildenv] 错误: results 文件解析失败: ${args.results}`);
+      process.exit(1);
+    }
+  }
+
+  let targetBranch = args.branch || null;
+  let bestVersion = null;
+  if (!targetBranch && results) {
+    const pass = Object.values(results.versions || {}).filter((v) => v.status === 'pass' && v.branch);
+    if (pass.length > 0) {
+      pass.sort((a, b) => parseFloat(a.version) - parseFloat(b.version));
+      bestVersion = pass[pass.length - 1];
+      targetBranch = bestVersion.branch;
+    }
+  }
+
+  if (!targetBranch) {
+    console.error('[update-buildenv] 错误: 无法确定目标分支（results 中无通过版本且未指定 --branch）');
+    console.error('[update-buildenv] 所有版本均失败时不应修改 FLUTTER_SDK_VERSION，请在报告中标注');
+    process.exit(1);
+  }
+
+  // 确定 BUILD_PKG_DIR
+  let pkgDir = args.pkgDir || null;
+  if (!pkgDir && results && results.exampleDir && results.libRoot) {
+    const rel = path.relative(path.resolve(results.libRoot), path.resolve(results.exampleDir));
+    if (rel && !rel.startsWith('..')) pkgDir = rel.split(path.sep).join('/');
+  }
+  if (!pkgDir && args.example) {
+    const rel = path.relative(libRoot, path.resolve(args.example));
+    if (rel && !rel.startsWith('..')) pkgDir = rel.split(path.sep).join('/');
+  }
+
+  const envFile = path.join(libRoot, 'buildEnv.sh');
+  const existed = fs.existsSync(envFile);
+  const before = existed ? fs.readFileSync(envFile, 'utf-8') : null;
+
+  // 解析现有值
+  const oldPkgDir = before ? ((before.match(/^\s*BUILD_PKG_DIR\s*=\s*(.+)$/m) || [])[1] || '').trim().replace(/^["']|["']$/g, '') : null;
+  const oldSdk = before ? ((before.match(/^\s*FLUTTER_SDK_VERSION\s*=\s*(.+)$/m) || [])[1] || '').trim().replace(/^["']|["']$/g, '') : null;
+
+  let content;
+  if (existed) {
+    content = before;
+    // FLUTTER_SDK_VERSION 必改（保留行首缩进）
+    if (/^\s*FLUTTER_SDK_VERSION\s*=.*$/m.test(content)) {
+      content = content.replace(/^(\s*)FLUTTER_SDK_VERSION\s*=.*$/m, `$1FLUTTER_SDK_VERSION=${targetBranch}`);
+    } else {
+      content = `${content.replace(/\s*$/, '')}\nFLUTTER_SDK_VERSION=${targetBranch}\n`;
+    }
+    // BUILD_PKG_DIR：显式指定或原值缺失才改（保留行首缩进）
+    if (pkgDir && (!oldPkgDir || oldPkgDir !== pkgDir)) {
+      if (args.pkgDir || !oldPkgDir) {
+        if (/^\s*BUILD_PKG_DIR\s*=.*$/m.test(content)) {
+          content = content.replace(/^(\s*)BUILD_PKG_DIR\s*=.*$/m, `$1BUILD_PKG_DIR=${pkgDir}`);
+        } else {
+          content = `${content.replace(/\s*$/, '')}\nBUILD_PKG_DIR=${pkgDir}\n`;
+        }
+      }
+    }
+  } else {
+    content = BUILDENV_TEMPLATE;
+    if (pkgDir && pkgDir !== 'example') {
+      content = content.replace('BUILD_PKG_DIR=example', `BUILD_PKG_DIR=${pkgDir}`);
+    }
+    content = content.replace('FLUTTER_SDK_VERSION=oh-3.35.7-dev', `FLUTTER_SDK_VERSION=${targetBranch}`);
+  }
+
+  fs.writeFileSync(envFile, content, 'utf-8');
+  fs.chmodSync(envFile, 0o755);
+
+  // 变更报告
+  const report = {
+    file: envFile,
+    created: !existed,
+    changes: [
+      { key: 'FLUTTER_SDK_VERSION', before: oldSdk, after: targetBranch, changed: oldSdk !== targetBranch },
+    ],
+    buildPkgDir: { before: oldPkgDir, after: pkgDir || oldPkgDir, changed: !!pkgDir && oldPkgDir !== pkgDir && (args.pkgDir || !oldPkgDir) },
+    basis: bestVersion ? { highestPassVersion: bestVersion.version, branchUsed: bestVersion.branch } : { explicitBranch: args.branch },
+  };
+  const outputDir = args.results ? path.dirname(path.resolve(args.results)) : libRoot;
+  const reportFile = path.join(outputDir, 'buildenv-update-report.json');
+  fs.writeFileSync(reportFile, JSON.stringify(report, null, 2), 'utf-8');
+
+  console.log(`[update-buildenv] ${existed ? '已更新' : '已新建'}: ${envFile}`);
+  console.log(`[update-buildenv] FLUTTER_SDK_VERSION: ${oldSdk || '(无)'} → ${targetBranch}`);
+  if (bestVersion) console.log(`[update-buildenv] 依据: 最高支持版本 ${bestVersion.version}（实测通过分支 ${bestVersion.branch}）`);
+  if (report.buildPkgDir.changed) console.log(`[update-buildenv] BUILD_PKG_DIR: ${oldPkgDir || '(无)'} → ${report.buildPkgDir.after}`);
+  else console.log(`[update-buildenv] BUILD_PKG_DIR: 保持 ${oldPkgDir || pkgDir || 'example'}`);
+  console.log(`[update-buildenv] 变更报告: ${reportFile}`);
+}
+
+main();

package/vendor/Server/Skills/flutter-code-use/SKILL.md

@@ -0,0 +1,316 @@
+---
+name: flutter-code-use
+description: Flutter 三方插件 HarmonyOS(ohos) 平台适配编码指导。读取 .ohos-adaptation 分析产物确定 plugin_type，按类型分发加载 MethodChannel/EventChannel/FFI/PlatformView/Texture/纯 Dart/联合插件/Monorepo 指导文件，严格按「工程配置→编码实现→编译错误修复」三部分执行，并用官方文档查证 Kit API 与运行时权限。当需要为 Flutter 插件新增 ohos 平台实现、编写 ohos/ 目录原生 ArkTS 代码、配置 ohos 工程产物，或修复 ohos 适配编译错误时使用。
+license: Apache-2.0
+compatibility: 需要 Flutter OHOS 分支 SDK（支持 --platforms ohos 与 Platform.isOhos）、DevEco Studio + OHOS SDK、hvigor/ohpm 构建环境；可选 MCP Gateway 运行中（script_deveco_docs 文档查证、kb_search 知识库检索）
+metadata:
+  author: LoopEngine
+  version: "1.0.0"
+  category: code-generation
+---
+
+# Flutter Code Use — Flutter 插件鸿蒙适配编码指导
+
+本技能用于**为 Flutter 三方插件编写 HarmonyOS(ohos) 平台适配代码**。核心流程：解析插件类型 → 分发加载类型指导 → 工程配置 → 编码实现 → 编译验证修复 → 交付自检。
+
+> ⚠️ **核心原则：所有适配代码必须同时满足三条底线——① 公开 API 兼容（保持原 Flutter 公开调用方式与行为不变，辅助承载层/桥接层可封装在插件内部，不因适配改变对外契约）；② 按类型分发（严格按分发表加载指导文件并执行其三部分结构，不凭记忆臆造工程配置）；③ API 使用有据可查（HarmonyOS Kit 的 import 路径、签名、权限、API Level 经官方文档查证，user_grant 权限必须实现完整运行时申请流程）。**
+
+> 📁 **路径约定**：本SKILL内所有文件引用路径均相对本SKILL根目录（如 `references/method-channel.md`）。
+
+---
+
+## 任务参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `repoPath` | string | ✅ | Flutter 插件仓库根目录（含 `pubspec.yaml`），适配代码写入该仓库 |
+| `analysisFile` | string | ❌ | 分析产物路径，默认 `{repoPath}/.ohos-adaptation/01-analysis.json`。不存在时现场回源码判定插件类型 |
+| `planningFile` | string | ❌ | 规划产物路径，默认 `{repoPath}/.ohos-adaptation/02-planning.json`。FFI 类型必读（`ffi_strategy`/`ffi_strategy_caveat` 字段） |
+
+---
+
+## 输入依赖
+
+- **前置SKILL**: 无。可作为独立任务调用；若上游分析/规划阶段已产出 `.ohos-adaptation/*.json` 则直接消费
+- **输入文件**: 插件仓库（`pubspec.yaml`、`lib/`、`android/`/`ios/` 原生实现等）；`.ohos-adaptation/01-analysis.json`（如已产出，关注 `plugin_type`、平台能力、依赖、权限、native 代码和 Example 覆盖范围）
+
+---
+
+## 工作流程概览
+
+```
+Phase 1: 输入解析与插件类型识别
+    ↓
+Phase 2: 指导文件分发加载（类型分发表 + 组合能力/仓库形态/API 陷阱信号）
+    ↓
+Phase 3: 工程配置（第一部分）
+    ↓
+Phase 4: 编码实现（第二部分，含通用硬规则与 API 查证）
+    ↓
+Phase 5: 编译验证与错误修复（第三部分）
+    ↓
+Phase 6: 交付自检
+```
+
+---
+
+## Phase 1：输入解析与插件类型识别
+
+### 1.1 读取分析产物
+
+读取 `analysisFile`（默认 `.ohos-adaptation/01-analysis.json`），提取：
+
+| 字段 | 用途 |
+|------|------|
+| `plugin_type` | Phase 2 分发入口（类型分发表） |
+| 平台能力 / native 代码 | 组合能力信号判定（Phase 2.2） |
+| 依赖 / 权限 | 工程配置输入（ohpm 依赖映射、`requestPermissions`） |
+| Example 覆盖范围 | 验证阶段回归范围 |
+
+FFI 类型（`plugin_type` 为 `ffi`）另读 `planningFile` 的 `ffi_strategy` 与 `ffi_strategy_caveat` 字段。
+
+### 1.2 类型缺失时回源码判定
+
+`plugin_type` 为 `unknown` 或无分析产物时，回源码判定：
+
+| 源码信号 | 判定类型 |
+|----------|---------|
+| `MethodChannel(`/`MethodCall` | method-channel（主通道） |
+| `EventChannel(` | event-channel |
+| `dart:ffi` / `DynamicLibrary` / `Cargo.toml` / `CMakeLists.txt` | ffi |
+| `PlatformViewFactory` / `registerViewFactory` / `viewType` | platform-view |
+| `TextureRegistry` / `createSurface` / `surfaceId` | texture |
+| 无 `android/`、`ios/` 目录且纯 Dart | pure-dart |
+
+### 1.3 适配边界判定
+
+- 目标库为 rhttp 或基于 flutter_rust_bridge 的 HTTP 客户端 → 补读 [references/ffi-rhttp-guide.md](references/ffi-rhttp-guide.md)（实战验证的决策路径）
+- FFI 不可适配判定（预编译二进制无源码且无 arm64、深度依赖 Android/iOS 专有系统库、ABI 不兼容）→ 按 [references/ffi.md](references/ffi.md) 的「FFI 不可适配判定」节处理，标记 `not_supported` 并在分析/规划产物中记录原因
+- **必须先查 `flutter-adapted-library` Skill 数据库**，确认是否已有适配版本，避免重复适配
+
+---
+
+## Phase 2：指导文件分发加载
+
+> **目标：只加载必需的指导文件（渐进式披露），不要全量加载。**
+
+### 2.1 类型分发表（基础入口，只加载一份）
+
+| `plugin_type` | 加载文件 | 说明 |
+|---------------|----------|------|
+| `plugin_method_channel` | [references/method-channel.md](references/method-channel.md) | MethodChannel 主通道插件 |
+| `plugin_event_channel` | [references/event-channel.md](references/event-channel.md) | EventChannel 流式数据插件 |
+| `ffi` | [references/ffi.md](references/ffi.md) | dart:ffi C/C++ 插件（先分诊再加载配方，见 2.4） |
+| `plugin_platform_view` | [references/platform-view.md](references/platform-view.md) | PlatformView 原生视图插件 |
+| `plugin_texture` | [references/texture.md](references/texture.md) | 外接纹理插件（视频/相机） |
+| `dart` | [references/pure-dart.md](references/pure-dart.md) | 纯 Dart 包 |
+| `plugin_mixed` | 先读 method-channel.md，再按能力补读相关文件 | 多种能力混合的插件 |
+| `unknown` | 先回源码判断类型（Phase 1.2），再加载对应文件 | 类型暂不明确的插件 |
+
+### 2.2 组合能力信号补读
+
+`plugin_type` 只决定基础指导入口，不代表完整实现边界。出现下列信号时**必须**额外读取对应文件，不要只靠基础类型文件自行推断：
+
+| 信号 | 补读文件 |
+|------|---------|
+| `PlatformView`、`viewType`、`registerViewFactory`、原生视图嵌入、ArkUI 承载组件 | [references/platform-view.md](references/platform-view.md) |
+| `Texture`、`TextureRegistry`、`surfaceId`、外接纹理、渲染表面、预览层 | [references/texture.md](references/texture.md) |
+| `EventChannel`、监听器、持续回调、状态流、进度流 | [references/event-channel.md](references/event-channel.md) |
+| `ffi`、`so`、`napi`、`CMake`、C/C++ 复用 | [references/ffi.md](references/ffi.md) |
+
+主方案由多种能力共同组成时，把基础类型文件作为脚手架，再组合辅助类型文件完成实现；不要因存在辅助实现层而改变原 Flutter 公开 API。
+
+### 2.3 仓库形态补读
+
+| 信号 | 补读文件 |
+|------|---------|
+| 联合插件、federated plugin、`platform_interface`、多个平台实现包 | [references/federated.md](references/federated.md) |
+| 多包仓库、workspace、melos、多个 package 共同发布 | [references/monorepo.md](references/monorepo.md) |
+
+### 2.4 FFI 策略配方分发
+
+FFI 类型须先执行 [references/ffi.md](references/ffi.md) 的 §0 分诊（按 `ffi_strategy` 加载唯一配方）+ §G 反检验清单（校验策略与仓库实际内容一致）+ §F caveat 长尾处理：
+
+| `ffi_strategy` | 加载配方 |
+|---|---|
+| `compile_from_source` | [references/ffi-compile-from-source.md](references/ffi-compile-from-source.md) |
+| `rust_cross_compile` | [references/ffi-rust-cross-compile.md](references/ffi-rust-cross-compile.md) |
+| `prebuilt_bundle` | [references/ffi-prebuilt-bundle.md](references/ffi-prebuilt-bundle.md) |
+| `fetch_at_build` | [references/ffi-fetch-at-build.md](references/ffi-fetch-at-build.md) |
+
+配方中触发 `@Native` 绑定翻译时补读 [references/ffi-binding-translate.md](references/ffi-binding-translate.md)。
+
+### 2.5 API 陷阱信号补读
+
+插件涉及以下场景时，必须额外读取 [references/ohos-api-pitfalls.md](references/ohos-api-pitfalls.md) 的对应章节：
+
+| 场景信号 | 加载章节 | 说明 |
+|----------|----------|------|
+| SoundPool、短音频、提示音、beep | 第 1 章：音频 — SoundPool | 默认音量为 0、callback 形式优先 |
+| AVPlayer、音频播放、视频播放、预加载 | 第 2 章：音频 — AVPlayer 状态机 | prepare 期间不能调 play/seek、onError 回环 |
+| Toast、轻提示、showToast、弹窗提示 | 第 3 章：UI 提示 | 系统 Toast 与 CustomDialog 选型、SDK 版本边界 |
+| 异步 API、Promise、callback | 第 4 章：异步 API | callback 与 Promise 行为差异 |
+| MethodChannel 无参方法、生命周期回调 | 第 5 章：参数安全 | call.args 可能为 null |
+| 传感器 | 第 6 章：传感器 | SensorResponse 必须属性访问、后台禁止调用传感器 |
+| `url_launcher`、`launchUrl`、WebView、外部浏览器、默认打开模式 | 第 9 章：平台敏感默认模式 | 禁止依赖 OHOS 隐式默认映射，必须显式选择打开方式 |
+| 状态栏、导航栏、fullscreen、avoid area、window、windowStage | 第 11 章：Window / WindowStage 生命周期 | `mainWindow` 不能只在 attach 时初始化一次，业务调用时要懒获取 |
+| Share Kit、系统分享、ACTION_SEND、分享面板、ShareCompat | 第 12 章：Share Kit | UTD 类型、SharedRecord 类型、HAR import 限制 |
+| AVTranscoder、视频转码、视频压缩、AVMetadataExtractor、AVFileDescriptor、fdSrc | 第 13 章：MediaKit — AVFileDescriptor 与 AVTranscoder | fdSrc 必须含 offset/length，视频尺寸必须偶数且在合法范围内 |
+| PixelMap、图片编码、图片解码、Clipboard 图片、截图、Image.memory、ImagePacker、createImageSource、readPixelsToBuffer | 第 15 章：图片处理 — PixelMap 与 ImagePacker | readPixelsToBuffer 是裸像素，createImageSource 需要 ArrayBuffer |
+
+---
+
+## Phase 3：工程配置（第一部分）
+
+> **目标：基于脚手架做增量配置，禁止凭空手写工程文件。**
+
+### 3.1 脚手架生成
+
+`ohos/` 目录由 Flutter OHOS SDK 的 `flutter create` 自动生成：
+
+```bash
+flutter create -t plugin --platforms ohos .        # 普通插件
+flutter create -t plugin_ffi --platforms ohos .    # FFI 插件
+```
+
+**不要手动创建** `build-profile.json5`、`hvigorfile.ts`、`module.json5` 等配置文件，只对生成结果做自定义配置。
+
+### 3.2 通用配置要点
+
+以下为各类型共性的配置项（详细步骤以已加载类型文件的「第一部分：工程配置」为准）：
+
+| 配置项 | 要点 |
+|--------|------|
+| `pubspec.yaml` | `flutter create` 不会自动添加 ohos 平台声明，须手动补 `platforms.ohos`（`package`/`pluginClass`，FFI 为 `ffiPlugin: true`） |
+| `ohos/oh-package.json5` | 按需追加 ohpm 三方依赖；`@ohos/flutter_ohos` 由构建工具自动注入，**禁止手动添加**（FFI 场景生成 `file:./libs/flutter.har` 时必须移除） |
+| `build-profile.json5` | Bytecode HAR 依赖须开 `useNormalizedOHMUrl`；依赖要求更高 SDK 时升级 `compatibleSdkVersion`；FFI 须补 `externalNativeOptions` |
+| `modelVersion` 一致性 | `example/ohos/hvigor/hvigor-config.json5` 与两级 `oh-package.json5` 的 `modelVersion` 必须完全一致，否则 hvigor 构建直接阻断 |
+| `module.json5` | 按 `requestPermissions` 声明权限（清单来自分析产物 + Phase 4.2 查证结论） |
+
+---
+
+## Phase 4：编码实现（第二部分）
+
+> 📐 本阶段生成的 ArkTS/ETS 代码须遵循已加载类型文件的「第二部分：编码实现」中的代码结构、import 语句、核心模式与类型映射。
+
+### 4.1 公开 API 兼容
+
+- Dart 层公开 API（类名、方法签名、行为语义）保持与上游一致，ohos 实现只做内部承载
+- 平台检测统一使用 `Platform.isOhos`（与 Android 合并处理），**禁止**排除法（`!isAndroid && !isIOS`）或 `Platform.operatingSystem == 'ohos'` 字符串比较
+
+### 4.2 通用硬规则（全类型适用）
+
+**Kit 导入**：业务代码中使用 HarmonyOS Kit 模块时，在文件顶部静态导入（如 `import { dataSharePredicates } from '@kit.ArkData';`）。禁止在 MethodChannel、回调、循环或业务方法内部使用 `await import('@kit.Xxx')` 动态导入。
+
+**运行时权限**：`module.json5` 中声明的权限属于 `user_grant` 类型时，必须实现完整申请流程：实现 `AbilityAware` → 获取 `UIAbilityContext` → 调用 `requestPermissionsFromUser()` → 处理用户拒绝。仅调用 `verifyAccessToken()` 不够（只检查不申请）。常见 `user_grant` 权限：`CAMERA`、`MICROPHONE`、`READ_PASTEBOARD`（API 12+）、`ACCESS_BLUETOOTH`、`APPROXIMATELY_LOCATION`、`LOCATION`、`READ_IMAGEVIDEO`、`WRITE_IMAGEVIDEO`、`READ_AUDIO`、`WRITE_AUDIO`。
+
+**位置权限特别规则**：涉及 `geoLocationManager`、定位、位置监听、Location Kit 时，`ohos.permission.APPROXIMATELY_LOCATION` 是基础可用权限，`ohos.permission.LOCATION` 是精确定位增强权限。用户只授权模糊位置时也应允许单次定位和位置监听继续执行；权限状态查询、`authResults` 处理、EventChannel 启动前校验均按 `APPROXIMATELY_LOCATION || LOCATION` 任一授权判断，不能只看 `LOCATION` 或固定数组下标。
+
+**FFI `.so` 命名**（FFI 类型）：OHOS 安装器只识别 `.so` 后缀，会丢弃 `libxxx.so.2` 等带版本号文件；打包前必须重命名为 `libxxx.so`，详见 [references/ffi.md](references/ffi.md) §H。
+
+### 4.3 Kit API 查证（MCP，按优先级）
+
+| 优先级 | 工具 | 适用 |
+|--------|------|------|
+| 1 | MCP Gateway `script_deveco_docs`（action=search / read） | 检索+精读 HarmonyOS 官方 API 参考：import 路径（`@kit.*`/`@ohos.*`）、方法签名、枚举成员、权限、API Level |
+| 2 | MCP Gateway `kb_search` / `kb-server_search_knowledge` | 补充鸿蒙平台经验知识与已知陷阱 |
+| 3 | MCP Gateway `script_flutter_extract_interfaces` | 提取插件 Dart 公开接口规格，核对公开 API 兼容性（Phase 4.1） |
+
+查证结论以表格记录（功能点 / import 路径 / 关键签名 / 权限 / since / 结论），作为编码依据；禁止凭记忆臆造 Kit API。
+
+### 4.4 实现与落盘
+
+按已加载类型文件的「第二部分」执行代码结构、import、核心模式与类型映射；组合型插件以基础类型文件为脚手架，组合辅助类型文件完成实现。
+
+---
+
+## Phase 5：编译验证与错误修复（第三部分）
+
+> **目标：编译通过是交付的硬性前置条件。**
+
+### 5.1 验证命令
+
+| 类型 | 命令 | 通过标准 |
+|------|------|---------|
+| 含原生实现的插件 | `flutter build hap --debug`（ohos 实现包目录下；Windows 环境用 powershell/cmd 执行） | 构建成功无 ERROR |
+| 纯 Dart 包 | `flutter pub get` | 成功且无 Dart 分析错误（无需 `flutter build hap`） |
+| 依赖调整后 | `ohpm install` 后重新编译 | 同上 |
+
+### 5.2 错误修复
+
+优先查已加载类型文件的「第三部分：常见编译错误与修复」（各类型特有错误的修复方案速查）；未覆盖的错误按以下顺序排查：
+
+1. 对照 Phase 2.5 已识别场景，查 [references/ohos-api-pitfalls.md](references/ohos-api-pitfalls.md) 对应章节
+2. 用 `script_deveco_docs` 查证 API 正确用法（import 路径、签名、`@since` 版本）
+3. 检查工程配置项（Phase 3.2 通用要点：modelVersion 一致性、useNormalizedOHMUrl、externalNativeOptions）
+
+### 5.3 修复循环纪律
+
+```
+LOOP（上限 5 轮）:
+  1. 编译验证（5.1）
+  2. 收集全部 ERROR（一次修复全部已知错误，避免逐个重跑）
+  3. 按速查表/陷阱文档/API 查证修复
+  4. 重新验证
+  5. 构建通过 → 进入 Phase 6
+超过 5 轮未通过：停止并向用户报告当前错误清单与已尝试方案
+```
+
+---
+
+## Phase 6：交付自检
+
+### 6.1 交付前自查清单
+
+**公开 API 兼容**
+- [ ] Dart 层公开 API（类名/方法签名/行为）与上游一致，无因适配引入的破坏性变更
+- [ ] 平台检测统一 `Platform.isOhos`，无排除法、无字符串比较
+
+**工程配置**
+- [ ] `pubspec.yaml` 已声明 ohos 平台；`module.json5` 权限齐全（含 Phase 4.3 查证结论）
+- [ ] `modelVersion` 三处一致；Bytecode HAR / FFI `externalNativeOptions` 按需配置
+- [ ] 未手动创建脚手架本应生成的工程文件
+
+**编码规范**
+- [ ] Kit 模块全部文件顶部静态导入，无动态 `await import`
+- [ ] `user_grant` 权限实现完整运行时申请流程（含用户拒绝处理）
+- [ ] 位置权限按 `APPROXIMATELY_LOCATION || LOCATION` 任一授权判断
+- [ ] 已按 Phase 2.5 信号表规避对应 API 陷阱
+
+**编译验证**
+- [ ] Phase 5.1 验证命令通过（`flutter build hap --debug` / `flutter pub get`）
+- [ ] 所有系统 API 经文档查证，无臆造 API、无 deprecated 接口
+
+### 6.2 输出交付物
+
+- ohos 平台适配代码（`ohos/` 目录、`pubspec.yaml` 变更等）
+- API 查证结论表（Phase 4.3）
+- 验证结果：验证命令、最终状态、修复的错误清单
+- 未实现或降级处理的功能点说明（如有，含 `not_supported` 判定原因）
+
+---
+
+## 参考资料
+
+**类型指导（Phase 2.1 分发）**
+- [MethodChannel 插件鸿蒙适配](references/method-channel.md) — 主通道插件完整三部分指导
+- [EventChannel 插件鸿蒙适配](references/event-channel.md) — 流式数据插件（监听器生命周期、背压）
+- [PlatformView 插件鸿蒙适配](references/platform-view.md) — 原生视图嵌入（ArkUI 承载）
+- [Texture 插件鸿蒙适配](references/texture.md) — 外接纹理（视频/相机预览）
+- [纯 Dart 包鸿蒙适配](references/pure-dart.md) — 平台判断兼容、依赖链检查
+- [FFI 插件鸿蒙适配路由](references/ffi.md) — §0 分诊 / §F caveat / §G 反检验 / §H 全模式通用规则
+
+**FFI 配方（Phase 2.4 分发）**
+- [ffi-compile-from-source](references/ffi-compile-from-source.md) — C/C++ 源码编译接入
+- [ffi-rust-cross-compile](references/ffi-rust-cross-compile.md) — Rust 交叉编译（含 TLS/HTTP3 风险缓解）
+- [ffi-prebuilt-bundle](references/ffi-prebuilt-bundle.md) — 预编译 .so 打包
+- [ffi-fetch-at-build](references/ffi-fetch-at-build.md) — 构建期下载
+- [ffi-binding-translate](references/ffi-binding-translate.md) — @Native 绑定翻译
+- [ffi-rhttp-guide](references/ffi-rhttp-guide.md) — rhttp 实战案例（flutter_rust_bridge HTTP 客户端）
+
+**仓库形态（Phase 2.3 补读）**
+- [联合插件适配](references/federated.md) — platform_interface / 多平台实现包
+- [Monorepo 适配](references/monorepo.md) — workspace / melos 多包仓库
+
+**陷阱参考（Phase 2.5 按需）**
+- [OHOS API 陷阱](references/ohos-api-pitfalls.md) — 音频/UI 提示/异步/参数安全/传感器/Window/Share Kit/MediaKit/图片处理等 15 章陷阱与修复