@ohos-cpf/3rdloop 0.0.12 → 0.0.13

package/vendor/Server/Skills/flutter-build-test/assets/README_SECTION_TEMPLATE.md

@@ -0,0 +1,78 @@
+# README.OpenHarmony(_CN).md 段落模板
+
+> 按编译矩阵结果填充。`{占位符}` 来自 build-matrix-results.json 与本机环境信息。完整规范见 [文档修改规范](../references/DOC_UPDATE_GUIDE.md)。
+
+---
+
+## 1. 下载安装 + TAG 对应表
+
+```markdown
+## 下载安装
+
+进入到工程目录并在 pubspec.yaml 中添加以下依赖：
+
+```yaml
+dependencies:
+  {库名}:
+    git: 
+      url: https://gitcode.com/CPF-Flutter/fluttertpc_{库名}.git
+      # ref: 根据下方表格选择不同框架适配的TAG版本
+      ref: {最高支持版本对应的TAG}
+```
+
+执行命令
+
+```bash
+flutter pub get
+```
+
+> TAG 命名规则：`原库版本-ohos-版本号-betax`，不同 TAG 之间的变更详见 CHANGELOG.OpenHarmony.md。
+
+| Flutter 框架版本 | TAG 名称 | 分支名 |
+| --- | --- | --- |
+| 3.7 | {支持则填TAG，否则 ------} | {支持则填分支，否则 ------} |
+| 3.22 | {支持则填TAG，否则 ------} | {支持则填分支，否则 ------} |
+| 3.27 | {支持则填TAG，否则 ------} | {支持则填分支，否则 ------} |
+| 3.32 | {支持则填TAG，否则 ------} | {支持则填分支，否则 ------} |
+| 3.35 | {支持则填TAG，否则 ------} | {支持则填分支，否则 ------} |
+| 3.41 | {支持则填TAG，否则 ------} | {支持则填分支，否则 ------} |
+```
+
+---
+
+## 2. 约束与限制
+
+```markdown
+## 约束与限制
+
+### 兼容性
+
+在以下版本中已测试通过：
+
+- Flutter: {3.22.3-ohos-1.0.6 形式的版本串}, DevEco Studio: {6.0.2 release(6.0.2.640)}, SDK: {6.0.2(22)}, ROM: {5.1.0.120 SP3};
+
+（每个支持版本一行，全部来自 build-matrix-results.json 的 pass 条目；无真机时省略 ROM 字段并在报告注明）
+
+### 权限要求
+
+（保留文档既有内容；新建文档时按库实际权限需求填写，参考：）
+
+本插件需要 {权限用途说明}，需要在应用中配置相应权限。
+
+**在 entry 目录下的 module.json5 中添加权限**
+
+（保留既有权限配置说明；无则按库实际需求编写）
+```
+
+---
+
+## 3. 填充数据来源对照
+
+| 占位符 | 来源 |
+|--------|------|
+| TAG 名称 | `git describe --tags --abbrev=0` / `git tag --list '*ohos*'` / CHANGELOG.OpenHarmony.md / pubspec.yaml version |
+| 分支名 | `git branch --show-current` |
+| 版本支持结论 | `{outputDir}/build-matrix-results.json` 中各版本 `status` |
+| Flutter 版本串 | 对应版本 pass 条目的 `flutterVersion` + ohos 版本号 |
+| DevEco Studio / SDK | `{outputDir}/env-doctor.txt`、`devecocli --version`、`DEVECO_SDK_HOME` 目录 |
+| ROM | `hdc shell param get const.product.software.version`（真机连接时） |

package/vendor/Server/Skills/flutter-build-test/references/BUILD_TROUBLESHOOTING.md

@@ -0,0 +1,128 @@
+# 编译排错手册（多版本矩阵失败诊断）
+
+> **判定纪律**：本 Skill 的定位是**验证库在哪些 Flutter 版本可用**，不是适配修复。环境类问题修复后重试；版本不兼容如实记录为"不支持"。混淆二者会导致错误的版本支持结论。
+
+---
+
+## 1. 失败分类与处理策略
+
+`build-matrix.cjs` 自动分类（结果 JSON 的 `failure.type` 字段），人工复核按下表：
+
+| failure.type | 特征（日志关键词） | 定性 | 处理 |
+|--------------|-------------------|------|------|
+| `sdk-constraint` | `requires SDK version` / `current Dart SDK version` | **版本不兼容** | 记为不支持；不修改 pubspec 约束（改了就不是"原库在该版本可用"） |
+| `dependency-conflict` | `version solving failed` / `Because X depends on Y` | **版本不兼容** | 记为不支持；禁止用 dependency_overrides 强行求解 |
+| `pubspec-invalid` | `Error on line N ... pubspec.yaml` | 版本不兼容（语法/字段该版本不支持） | 记为不支持 |
+| `ohos-arkts-error` | `ArkTS` / `.ets(N,M)` / `hvigor ERROR` / `napi_` | **版本不兼容**（代码使用了新版本才有的 API/语法） | 记为不支持；不改库源码 |
+| `signing-error` | `请通过DevEco Studio...配置调试签名` / `.p12` / profile | **配置问题** | 默认 `--no-codesign` 规避；需签名产物时人工配置 DevEco 签名后 `--codesign` 重测；禁止记为不支持 |
+| `network` | `Failed to fetch` / `timed out` / `ECONNREFUSED` | **环境问题** | 检查镜像变量（flvm doctor）→ 重试；禁止记为不支持 |
+| `toolchain-env` | `hvigorw not found` / `JAVA_HOME` 缺失 | **环境问题** | `flvm init --deveco` 修复工具链 → 重试 |
+| `hvigor-crash` | `ProcessException: hvigorw ... exit code 255` | **待人工判定**（工具链或工程与该版本不兼容） | 读日志定位崩溃阶段（assembleHar/assembleHap）；同一错误在其他版本不出现则倾向版本不兼容 |
+| `flvm-install` / `flvm-version-mismatch` | 脚本 env-error | **环境问题** | 按 [FLVM 使用指南](FLVM_GUIDE.md) §5 排查 → 重试 |
+| `artifact-missing` | 命令成功但无 hap | 可疑结果 | 人工核对日志；按 fail 记录并注明 |
+| `unknown` | 未命中任何模式 | 待人工判定 | 读 `logs/{版本}.log` 尾部 200 行定性后归类 |
+
+**重试方式**：排除环境问题后 `--resume --versions <版本>` 续跑（已通过/已定性失败的版本自动跳过）。
+
+---
+
+## 2. 环境问题 vs 版本不兼容的判别标准
+
+> 🔴 同一环境故障会在多个版本上**重复出现相同报错**。看到多版本同因失败，先怀疑环境。
+
+| 判别维度 | 环境问题 | 版本不兼容 |
+|----------|----------|-----------|
+| 报错阶段 | 任何阶段（尤其 fetch/工具链） | pub get 的 SDK/依赖约束、build 阶段的编译错误 |
+| 报错内容 | 网络超时、命令不存在、变量缺失 | Dart 语言/API/依赖解析的具体版本约束 |
+| 版本分布 | 多版本同报错（含最新版本也可能失败） | 通常老版本失败、新版本通过（或反之），呈版本相关性 |
+| 验证方式 | 修复环境后同版本重试通过 | 换最新支持版本（如 3.41）验证环境本身正常 |
+
+---
+
+## 3. 高频失败场景速查
+
+### 3.1 Dart SDK 约束（3.7 最常见）
+
+```
+The current Dart SDK version is 2.19.2.
+Because xxx requires SDK version >=3.5.0 <4.0.0, version solving failed.
+```
+
+→ 库 pubspec.yaml 的 `environment.sdk` 下限高于 3.7 自带的 Dart 2.19。**定性：3.7 不支持**，不动 pubspec。
+
+### 3.2 依赖解析冲突
+
+```
+Because example depends on xxx from path which depends on yyy ^2.0.0, ...
+version solving failed
+```
+
+→ 该 Flutter 版本的依赖生态无法满足约束。**定性：该版本不支持**。
+
+### 3.3 鸿蒙工程编译错误（新版本 Flutter 才出现的 API）
+
+```
+ERROR: ArkTS:ERROR File: .../xxx.ets
+Property 'yyy' does not exist on type 'zzz'
+```
+
+→ 库的 ohos 实现使用了该版本 Flutter ohos SDK 未提供的接口。**定性：该版本不支持**（这正是多版本验证要发现的差异）。
+
+### 3.4 hvigor/ohpm 环境问题
+
+```
+hvigorw: command not found / Error: JAVA_HOME is not defined
+```
+
+→ 工具链未配置。`flvm doctor` 定位缺失项 → `flvm init --deveco <path>` → `--resume` 重试。
+
+### 3.5 ohpm 源/网络问题
+
+```
+Fetch error: ... ECONNREFUSED / ohpm INSTALL FAILED
+```
+
+→ 检查 ohpm registry（`ohpm config get registry`，应为华为源）与网络代理 → 重试。
+
+### 3.6 签名错误与 `--no-codesign` 版本差异（重要）
+
+```
+请通过DevEco Studio打开ohos工程后配置调试签名(File -> Project Structure -> Signing Configs 勾选Automatically generate signature)
+```
+
+→ 根因：flutter ohos 工具的 `checkOhosSignedInfo` 检测到 `build-profile.json5` 的 `app.signingConfigs` 为空列表时直接拒绝（见 flutter_tools 源码 `ohos/hvigor.dart`）。
+
+**`--no-codesign` 参数的版本支持差异**（build-matrix.cjs 已自动探测处理）：
+
+| Flutter 版本 | `--no-codesign` 支持 | 无签名构建行为 |
+|--------------|---------------------|----------------|
+| 3.7 / 3.27 | ❌ 不支持（参数报错） | 构建后强制签名检查，空 signingConfigs 时 flutter 工具退出非零；**hvigor 编译链已完成且产出 unsigned hap 时按通过计**（脚本自动判定） |
+| 3.22 / 3.35 / 3.41 | ✅ 支持 | `--no-codesign` 直接产出 unsigned hap，正常通过 |
+
+→ 需要签名产物时由人工在 DevEco 中勾选 Automatically generate signature 后用 `--codesign` 重测；默认无签名模式已足以验证编译链。
+
+### 3.7 example 缺少 ohos 目录
+
+→ 在 example 目录执行 `flutter create --platforms ohos .` 生成（当前 Flutter 须为 OHOS fork），生成后重跑 `locate-example.cjs` 确认；生成工程需人工确认可用性（非原始工程，报告中注明）。
+
+---
+
+## 4. 构建加速与稳定性
+
+| 项 | 建议 |
+|----|------|
+| 引擎预热 | flvm 共享引擎缓存，首次某版本构建慢属正常；`--install-timeout` 默认 3600s |
+| 会话超时 | 6 版本全量可能 >1h：用 `--versions` 分批 + `--resume` 续跑（结果增量落盘） |
+| hvigor daemon | 构建卡死疑似 daemon 遗留时：`hvigorw --stop`（或杀 hvigor 进程）后重试 |
+| 磁盘 | 多版本 + 引擎缓存占用大，提前确认磁盘余量（`flvm doctor`） |
+| pubspec.lock | 脚本默认备份后删除、结束时恢复原件（fresh-resolve，保证每版本独立求解）；`--no-fresh-resolve` 可关闭 |
+
+---
+
+## 5. 检查清单
+
+- [ ] 每个失败版本已定性（版本不兼容 / 环境问题 / 可疑待人工）
+- [ ] 环境类失败已修复并 `--resume` 重试，重试结果已更新
+- [ ] `env-error` 条目清零（或已在报告中说明无法修复的环境限制）
+- [ ] 至少一个版本通过（全部失败时先怀疑环境，再怀疑库本身）
+- [ ] 每版本日志 `logs/{版本}.log` 完整（含 flvm use / flutter --version / pub get / build 全程）

package/vendor/Server/Skills/flutter-build-test/references/DOC_UPDATE_GUIDE.md

@@ -0,0 +1,119 @@
+# 文档修改规范（README.OpenHarmony 与 buildEnv.sh）
+
+> 按编译矩阵实测结果回写仓库文档。**铁律：写入的每一个版本结论必须有对应的实测记录（build-matrix-results.json），禁止未经实测的推断值。**
+
+参考实例：
+- README：https://gitcode.com/CPF-Flutter/fluttertpc_file_picker/blob/master/README.OpenHarmony_CN.md
+- buildEnv：https://gitcode.com/CPF-Flutter/fluttertpc_flutter_udid/blob/br_v4.1.1_ohos_dev/buildEnv.sh
+
+---
+
+## 1. README.OpenHarmony_CN.md 修改规范
+
+### 1.1 三处必改
+
+| # | 位置 | 内容 |
+|---|------|------|
+| 1 | 下载安装章节的 TAG 表 | **TAG 对应表**：逐版本标注 TAG 与分支（不支持的版本填 `------`） |
+| 2 | 约束与限制 → 兼容性 | **已测试通过清单**：每个支持版本一行环境元组 |
+| 3 | （表已存在时）ref 示例 | pubspec.yaml `ref:` 注释指向默认推荐 TAG |
+
+### 1.2 TAG 对应表规则
+
+```markdown
+| Flutter 框架版本 | TAG 名称 | 分支名 |
+| --- | --- | --- |
+| 3.7 | ------ | ------ |
+| 3.22 | 2.2.1-ohos-1.0.0 | br_3.27_dev |
+```
+
+- **行覆盖全部 6 个框架版本**（3.7/3.22/3.27/3.32/3.35/3.41），不遗漏不增删
+- 支持的版本：TAG 名称 + 分支名；不支持的版本：两列均填 `------`
+- TAG 名称获取（按优先级）：
+  1. `git describe --tags --abbrev=0`（最近 TAG）
+  2. `git tag --list '*ohos*' | tail -5` 人工确认最新的 ohos TAG
+  3. 无 TAG：从 `CHANGELOG.OpenHarmony.md` 最新条目或 `pubspec.yaml` 的 `version`（如 `2.2.1-ohos-1.0.0`）取值
+  4. 均无：填 `未发布` 并在报告注明
+- 分支名 = `git branch --show-current`（当前检出分支，如 `br_3.27_dev`）
+- TAG 命名规则说明（表上方保留）：`原库版本-ohos-版本号-betax`，不同 TAG 变更见 CHANGELOG.OpenHarmony.md
+
+### 1.3 约束与限制 → 兼容性规则
+
+```markdown
+## 约束与限制
+
+### 兼容性
+
+在以下版本中已测试通过：
+
+- Flutter: 3.22.3-ohos-1.0.6, DevEco Studio: 6.0.2 release(6.0.2.640), SDK: 6.0.2(22), ROM: 5.1.0.120 SP3;
+- Flutter: 3.27.4-ohos-1.0.6, DevEco Studio: 6.0.2 release(6.0.2.640), SDK: 6.0.2(22), ROM: 5.1.0.120 SP3;
+```
+
+- 每个支持版本一行，以 `;` 结尾
+- 字段来源：
+  - `Flutter` = `{flutter完整版本}-{ohos版本}`（`flutter --version` 输出中提取，如 `3.22.3-ohos-1.0.6`；ohos 版本号取自版本串或 flvm 分支对应关系）
+  - `DevEco Studio` = `devecocli --version` 或 DevEco 关于页（如 `6.0.2 release(6.0.2.640)`）
+  - `SDK` = `{SDK版本}({API版本})`（`DEVECO_SDK_HOME` 下目录名 + `hdc shell param get const.ohos.apiversion`，无设备时用 SDK 目录名推断）
+  - `ROM` = `hdc shell param get const.product.software.version`（**仅真机连接时填写**；无设备省略 ROM 字段并在报告注明"ROM 未实测"）
+- 保留该章节既有其余内容（权限要求等），**只增改版本相关部分**
+
+### 1.4 修改边界（红线）
+
+| 禁止 | 说明 |
+|------|------|
+| 删除既有章节 | 权限要求、使用示例、接口说明、遗留问题等一律保留 |
+| 写入未实测的版本 | 支持结论只能来自 build-matrix-results.json 的 pass 条目 |
+| 篡改 TAG/分支 | TAG 与分支必须来自 git 实际状态 |
+| 只改中文版 | `README.OpenHarmony.md`（英文版）存在时必须镜像同步（英文措辞、结构一致） |
+
+### 1.5 README 不存在时
+
+按 [README 段落模板](../assets/README_SECTION_TEMPLATE.md) 新建最小可用文档（标题、简介、下载安装 + TAG 表、约束与限制），其余章节标注"待补充"。
+
+---
+
+## 2. buildEnv.sh 修改规范
+
+### 2.1 结构（目标形态）
+
+```bash
+#!/bin/bash
+  # Copyright (C) 2026 Huawei Device Co., Ltd.
+  # ... Apache License 头 ...
+
+  BUILD_PKG_DIR=example
+  FLUTTER_SDK_VERSION=oh-3.35.7-dev
+```
+
+### 2.2 变量取值规则
+
+| 变量 | 取值 | 说明 |
+|------|------|------|
+| `FLUTTER_SDK_VERSION` | 最高支持版本**实测通过**的 flvm 分支名（results JSON 中该版本 pass 条目的 `branch` 字段） | 按分支实际支持的版本回写；如 3.22/3.27 通过、3.32+ 失败 → 填 3.27 的分支 `oh-3.27.4-dev` |
+| `BUILD_PKG_DIR` | Phase 1 定位的实际 example 相对路径（如 `example`、`YFree_Flute/Lite/example`） | 原值正确则不动；仅当定位结果与原值不一致且经确认后修正 |
+
+- **所有版本均失败时不修改 `FLUTTER_SDK_VERSION`**，在报告中标注"无可回写版本"
+- 保留 License 头与既有结构，只改变量行
+- 文件不存在时按 [buildEnv 模板](../assets/BUILDENV_TEMPLATE.md) 新建并赋可执行权限
+
+### 2.3 使用 update-buildenv.cjs
+
+```bash
+node {skillDir}/scripts/update-buildenv.cjs --source {libRoot} --results {outputDir}/build-matrix-results.json
+```
+
+- `--branch <分支>`：显式覆盖（仅调用方明确指定时）
+- `--pkg-dir <路径>`：显式修正 BUILD_PKG_DIR（默认仅在原值缺失时补写）
+- 变更对照输出到 `{outputDir}/buildenv-update-report.json`，报告中引用
+
+---
+
+## 3. 修改前后自检
+
+- [ ] TAG 对应表覆盖全部 6 版本，支持/不支持与 results JSON 一一对应
+- [ ] 兼容性行数 = pass 版本数，环境元组来自实测环境
+- [ ] 英文版（若存在）已同步
+- [ ] 既有章节无删除
+- [ ] buildEnv.sh 只改变量行，License 头完整，`FLUTTER_SDK_VERSION` 与最高 pass 版本分支一致
+- [ ] 变更已记入最终报告（前后对照）

package/vendor/Server/Skills/flutter-build-test/references/FLVM_GUIDE.md

@@ -0,0 +1,89 @@
+# FLVM 使用指南
+
+> flvm（Flutter 多版本管理器）：https://gitcode.com/lalhanOrz/flvm
+> 基于 git worktree + 共享引擎缓存，专为 OHOS Flutter fork（https://gitcode.com/CPF-Flutter/flutter_flutter.git）的多版本切换设计。
+
+---
+
+## 1. 命令速查
+
+| 命令 | 说明 |
+|------|------|
+| `flvm init [dir]` | 初始化，`<dir>` 自定义存储目录（默认 `~/.flvm`） |
+| `flvm init --deveco <path>` | 附带自动配置 TOOL_HOME/JDK/ohpm/hvigor 等 OHOS 环境变量 |
+| `flvm init --url <git-url>` | 指定 Flutter 仓库地址（默认 OHOS fork） |
+| `flvm use <query>` | 切换版本（未安装自动安装，支持模糊匹配；无参数显示当前版本） |
+| `flvm list` / `flvm ls` | 列出已安装版本 |
+| `flvm list -r` | 显示远程可安装的分支 |
+| `flvm remove <query>` | 删除已安装版本（共享缓存默认保留） |
+| `flvm sync` | 同步所有已安装 Flutter 版本到各自分支最新提交（保留缓存，秒级完成） |
+| `flvm doctor` | 环境体检：flvm 状态 + Flutter 镜像 + OHOS 工具链（build hap 依赖） |
+| `flvm update` | 更新 flvm 自身 |
+
+---
+
+## 2. 版本-分支映射表
+
+> 以 `flvm list -r` 实际输出为准（下表为 2026-09 实测快照）。映射过期时同步修正 `scripts/build-matrix.cjs` 的 `PREFERRED_BRANCHES` 表。
+
+| 主版本 | 补丁版本 | 可用分支 | build-matrix 首选 |
+|--------|----------|----------|-------------------|
+| 3.7 | 3.7.12 | `br_3.7.12-ohos-1.1.3`、`br_3.7.12-ohos-dev`、`oh-3.7.12-dev-6.0` 等 | `br_3.7.12-ohos-1.1.3` |
+| 3.22 | 3.22.3 | `oh-3.22.3-release`、`oh-3.22.3-dev`、`oh-3.22.0-dev` 等 | `oh-3.22.3-release` |
+| 3.27 | 3.27.4 / 3.27.0 | `oh-3.27.4-dev`、`oh-3.27.0-release` | `oh-3.27.4-dev` |
+| 3.32 | 3.32.0 / 3.32.4 | `oh-3.32.0-release`、`oh-3.32.4-dev` | `oh-3.32.0-release` |
+| 3.35 | 3.35.7 | `oh-3.35.7-dev`、`oh-3.35.7-release` | `oh-3.35.7-dev` |
+| 3.41 | 3.41.9 | `oh-3.41.9-release`、`oh-3.41.9-dev` | `oh-3.41.9-release` |
+
+**选择依据**：CPF-Flutter 仓库 buildEnv.sh 实证使用 `oh-3.35.7-dev` 形式；3.22/3.32/3.41 存在 release 分支时优先 release，3.27/3.35 按社区惯例使用 dev 分支（补丁版本更新）。`flvm use` 支持分支名关键词精确匹配。
+
+---
+
+## 3. 首次初始化（新环境）
+
+```bash
+# macOS
+flvm init --deveco "/Applications/DevEco-Studio.app/Contents"
+
+# Windows（DevEco 安装目录）
+flvm init --deveco "D:\DevEco-Studio"
+```
+
+- flvm 自动写入国内镜像环境变量（`PUB_HOSTED_URL=https://pub.flutter-io.cn` 等）；用 `--no-mirror` 可关闭
+- 用 `--no-shell` 可不修改 shell 配置（需自行配置 PATH）
+- 初始化后**重开终端**（或 source 配置文件）确保 PATH 生效
+
+---
+
+## 4. 版本切换与验证
+
+```bash
+flvm use oh-3.35.7-dev     # 精确分支
+flvm use 3.35              # 模糊匹配（多候选时可能命中非预期分支，矩阵测试慎用）
+flutter --version          # 切换后必须校验：主.次版本号与预期一致
+```
+
+> ⚠️ **flvm use 切换的是全局 Flutter**（worktree 指针），因此多版本矩阵测试**必须串行**；`build-matrix.cjs` 已内置切换后版本校验，不匹配记为 `env-error`。
+
+---
+
+## 5. 常见问题
+
+| 现象 | 原因 | 处理 |
+|------|------|------|
+| `flvm: command not found` | 未安装 / PATH 未生效 | `npm install -g flvm` 或从仓库安装；重开终端 |
+| `flvm use` 报未初始化 | 未执行 `flvm init` | `flvm init --deveco <DevEco路径>` |
+| 切换后 `flutter --version` 版本不对 | PATH 中其他 flutter 优先 | `which -a flutter` 排查；确保 flvm 的 bin 目录（如 `~/.flvm/bin`）在 PATH 前部 |
+| `flutter build hap` 报缺少 ohpm/hvigor/java | OHOS 工具链未配置 | `flvm doctor` 定位缺失项 → 重跑 `flvm init --deveco` |
+| 镜像超时 | PUB_HOSTED_URL 未设置 | 按 `flvm doctor` 提示设置 `https://pub.flutter-io.cn` / `https://storage.flutter-io.cn` |
+| 磁盘占用大 | 多版本引擎缓存 | `flvm remove <版本>`（缓存默认保留可手动清理） |
+| 分支映射表过期 | flvm 远程分支更新 | 以 `flvm list -r` 实际输出为准，修正 `build-matrix.cjs` 的 `PREFERRED_BRANCHES` |
+
+---
+
+## 6. 检查清单
+
+- [ ] `flvm doctor` 全部 ✓（至少 Flutter 镜像 + OHOS 工具链通过）
+- [ ] `flvm list` 能列出已安装版本
+- [ ] 切换后 `flutter --version` 主.次版本与预期一致
+- [ ] `flutter doctor -v` 无阻塞性错误（OHOS 工具链由 flvm doctor 覆盖）