@ohos-cpf/3rdloop 0.0.11 → 0.0.13

package/lib/cli.js

@@ -150,7 +150,7 @@ export async function runCli(argv) {
             return cmdKnowledgeImpl({ rest, user3libHome, dataDir, jsonMode });
 
         case 'serve':
-            return cmdServe({ rest, jsonMode, dataDir, user3libHome });
+            return cmdServe({ flags, jsonMode, dataDir, user3libHome });
 
         case 'update':
             return cmdUpdate({ flags, rest, jsonMode, out });
@@ -265,7 +265,7 @@ async function cmdUpdate({ flags, rest, jsonMode, out }) {
 
 // ─── serve（同时启动 Server HTTP 后端 + Web 前端）─────────────────
 
-async function cmdServe({ flags, rest, jsonMode, dataDir, user3libHome }) {
+async function cmdServe({ flags, jsonMode, dataDir, user3libHome }) {
     const { cmdServe: impl } = await import('./serve.js');
     return impl({ rest: flags.rest, jsonMode, dataDir, user3libHome });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ohos-cpf/3rdloop",
-    "version": "0.0.11",
+    "version": "0.0.13",
     "description": "3rdLibraryLoop 三方库自动化检视 CLI：嵌入式复用核心引擎，任务生命周期管理（submit/run/wait/progress/abort/list/result/doctor）",
     "type": "module",
     "license": "MIT",

package/vendor/Server/Routes/controllers/LoopEngineController.js

@@ -120,6 +120,33 @@ class LoopEngineController {
         return this.storage;
     }
 
+    /**
+     * 判断磁盘上的任务是否为"单次执行任务"。
+     *
+     * 单次执行任务由 FlexRunnerController.startSingle 在启动时写入精简版
+     * loop.json（isSingleExecution=true，见其「写精简版 loop.json」逻辑）；
+     * 大循环任务的 loop.json（LoopEngine 写入）无此标记。
+     * 用于 progress 的"单次执行"分支判定，避免把"收尾轮只有 1 个步骤"的
+     * 大循环任务误判为单次执行。
+     *
+     * 无 loop.json / 读取失败时保守返回 true（维持单次执行判定旧行为，
+     * 不影响真正的单次执行任务）。
+     *
+     * @param {string} taskId
+     * @returns {Promise<boolean>}
+     * @private
+     */
+    async _isSingleExecutionOnDisk(taskId) {
+        try {
+            const storage = this._getStorage();
+            const loop = await storage.json('task').read(`${taskId}/loop`);
+            if (!loop) return true;
+            return loop.isSingleExecution === true;
+        } catch {
+            return true;
+        }
+    }
+
     // ─── HTTP Handlers ─────────────────────────────────────────────────
 
     /**
@@ -309,9 +336,15 @@ class LoopEngineController {
 
                 if (orch) {
                     const orchProgress = orch.getProgress();
-                    // 判断是否为单次执行（步骤数为 1 且 loopCount === 0）
-                    const isSingle = orchProgress &&
-                        Array.isArray(orchProgress.steps) && orchProgress.steps.length === 1;
+                    // 判断是否为单次执行：步骤数为 1、loopCount === 0，且磁盘 loop.json
+                    // 不存在或标记 isSingleExecution=true（单次执行任务由 startSingle 写入该标记）。
+                    // 不能仅凭"步骤数为 1"判定——大循环任务重规划后的收尾轮常只有 1 个步骤，
+                    // 服务重启 restoreFromDisk 后内存中恰是这种快照，会被误判为单次执行，
+                    // 导致 progress 返回合成的单轮视图，前端丢失完整多轮历史。
+                    const isSingle = orchProgress
+                        && Array.isArray(orchProgress.steps) && orchProgress.steps.length === 1
+                        && (orchProgress.loopCount ?? 0) === 0
+                        && (await this._isSingleExecutionOnDisk(taskId));
 
                     if (isSingle) {
                         // 构造兼容 LoopEngine.getProgress 的响应格式

package/vendor/Server/Routes/controllers/OrchestratorController.js

@@ -767,6 +767,155 @@ class OrchestratorController {
         }
     }
 
+    /**
+     * 跨机迁移路径自愈（幂等，best-effort）。
+     *
+     * 背景：任务目录可能从其他机器整体拷贝过来（共享/排查场景），其中
+     * orchestration.json / orchestration_loop{N}.json / loop.json 持久化的
+     * taskDir / steps[].resultPath / skillDirectory 是异机绝对路径（如
+     * C:\Users\...），在本机不可用：isLoopTask 判断恒 false（任务被错误
+     * 注册为 orchestrator，大循环历史页看不到）、详情页报告链接 404、
+     * 步骤重执行提示的工作目录错误。
+     *
+     * 本机规范位置是 db/task/{taskId}/（storage 适配器的读写基准），按
+     * 「同相对路径」原则将旧前缀重映射为本机路径：
+     *   - data.taskDir / steps[].taskDir      → db/task/{taskId}
+     *   - steps[].resultPath                  → db/task/{taskId}/<相对路径>
+     *   - data.skillDirectory（异机无效时）   → 服务端默认 SKILL 根目录
+     *
+     * 同时回写自愈后的快照（JsonAdapter 原子写），使直接读盘的消费方
+     * （getStepInfoByLoop / LoopEngine.restoreLoop 等）一并修复。
+     *
+     * @param {string} taskId
+     * @param {object} state - orchestration.json 反序列化对象（原地修改）
+     * @returns {Promise<object>} 自愈后的 state
+     * @private
+     */
+    async _healCrossMachinePaths(taskId, state) {
+        if (!this.storage || !state) return state;
+        const localTaskDir = path.join(this.storage.manager.rootDir, 'task', taskId);
+
+        const oldDir = state.taskDir;
+        // 同机恢复（含自定义 taskDir）、无 taskDir、或本机规范目录不存在 → 无需自愈
+        if (!oldDir || path.resolve(oldDir) === path.resolve(localTaskDir)) return state;
+        let oldExists = false;
+        try { oldExists = fs.existsSync(oldDir); } catch { /* 非法路径视为不存在 */ }
+        if (oldExists || !fs.existsSync(localTaskDir)) return state;
+
+        this._remapStateToLocal(state, localTaskDir);
+
+        // 回写主快照；running 状态保持原样（与 restoreState 的"保留崩溃现场快照"语义一致）
+        if (state.status !== 'running') {
+            try {
+                await this.storage.json('task').write(`${taskId}/orchestration`, state);
+                console.log(
+                    `[OrchestratorController] 已自愈异机路径并回写: taskId=${taskId}, ${oldDir} → ${localTaskDir}`
+                );
+            } catch (err) {
+                console.warn(`[OrchestratorController] 自愈回写 orchestration.json 失败: taskId=${taskId}, ${err.message}`);
+            }
+        }
+
+        // 历史轮次快照与 loop.json 同步自愈（直接读盘的消费方）
+        await this._healTaskSnapshotFiles(taskId, localTaskDir);
+        return state;
+    }
+
+    /**
+     * 自愈任务目录下的历史轮次快照（orchestration_loop{N}.json）与 loop.json。
+     * 这些文件由消费方直接从磁盘读取（getStepInfoByLoop / LoopEngine.restoreLoop），
+     * 仅修内存实例无法覆盖。running 状态的快照保持原样（崩溃现场语义）。
+     *
+     * @param {string} taskId
+     * @param {string} localTaskDir - 本机任务目录（db/task/{taskId}）
+     * @returns {Promise<void>}
+     * @private
+     */
+    async _healTaskSnapshotFiles(taskId, localTaskDir) {
+        try {
+            const names = fs.readdirSync(localTaskDir);
+            const targets = names.filter(n => /^orchestration_loop\d+\.json$/.test(n) || n === 'loop.json');
+            for (const name of targets) {
+                const key = `${taskId}/${name.replace(/\.json$/, '')}`;
+                let data;
+                try {
+                    data = await this.storage.json('task').read(key);
+                } catch { continue; }
+                if (!data || data.status === 'running') continue;
+                if (!this._remapStateToLocal(data, localTaskDir)) continue;
+                try {
+                    await this.storage.json('task').write(key, data);
+                    console.log(`[OrchestratorController] 已自愈异机路径并回写: ${name}, taskId=${taskId}`);
+                } catch (err) {
+                    console.warn(`[OrchestratorController] 自愈回写 ${name} 失败: taskId=${taskId}, ${err.message}`);
+                }
+            }
+        } catch (err) {
+            console.warn(`[OrchestratorController] 扫描轮次快照失败: taskId=${taskId}, ${err.message}`);
+        }
+    }
+
+    /**
+     * 将单个快照对象内的异机路径重映射为本机路径（原地修改）。
+     * 依据快照自身的 taskDir 前缀匹配（兼容正反斜杠分隔符）。
+     *
+     * @param {object} data - orchestration / loop 快照对象
+     * @param {string} localTaskDir - 本机任务目录（db/task/{taskId}）
+     * @returns {boolean} 是否发生了修改
+     * @private
+     */
+    _remapStateToLocal(data, localTaskDir) {
+        if (!data || typeof data !== 'object') return false;
+
+        const oldDir = data.taskDir;
+        if (typeof oldDir !== 'string' || !oldDir) return false;
+        const oldPrefix = oldDir.replace(/\\/g, '/').replace(/\/+$/, '');
+        const localPrefix = localTaskDir.replace(/\/+$/, '');
+        if (!oldPrefix || oldPrefix === localPrefix) return false;
+
+        const remap = (p) => {
+            if (typeof p !== 'string' || !p) return p;
+            const np = p.replace(/\\/g, '/');
+            if (np === oldPrefix) return localTaskDir;
+            if (np.startsWith(oldPrefix + '/')) {
+                return path.join(localTaskDir, np.slice(oldPrefix.length + 1));
+            }
+            return p;
+        };
+
+        // skillDirectory：异机路径本机无效时，回退到服务端默认 SKILL 根目录
+        const healSkillDir = (sd) => {
+            if (typeof sd !== 'string' || !sd || !this.skillDirectory) return sd;
+            try {
+                return fs.existsSync(sd) ? sd : this.skillDirectory;
+            } catch {
+                return this.skillDirectory;
+            }
+        };
+
+        let changed = false;
+        if (data.taskDir !== localTaskDir) { data.taskDir = localTaskDir; changed = true; }
+        if (data.skillDirectory) {
+            const next = healSkillDir(data.skillDirectory);
+            if (next !== data.skillDirectory) { data.skillDirectory = next; changed = true; }
+        }
+        if (Array.isArray(data.steps)) {
+            for (const s of data.steps) {
+                if (!s || typeof s !== 'object') continue;
+                if (s.taskDir !== localTaskDir) { s.taskDir = localTaskDir; changed = true; }
+                if (s.resultPath) {
+                    const next = remap(s.resultPath);
+                    if (next !== s.resultPath) { s.resultPath = next; changed = true; }
+                }
+                if (s.skillDirectory) {
+                    const next = healSkillDir(s.skillDirectory);
+                    if (next !== s.skillDirectory) { s.skillDirectory = next; changed = true; }
+                }
+            }
+        }
+        return changed;
+    }
+
     /**
      * 判断 running 状态的持久化任务是否有仍存活的"外部属主进程"。
      *
@@ -861,6 +1010,9 @@ class OrchestratorController {
                     continue;
                 }
 
+                // ── 跨机路径自愈：异机拷贝的任务目录内是异机绝对路径，重映射为本机路径 ──
+                await this._healCrossMachinePaths(taskId, state);
+
                 const wasRunning = state.status === 'running';
                 const orch = this._createOrchestrator();
                 await orch.restoreState(state);
@@ -934,22 +1086,54 @@ class OrchestratorController {
             // finally 未执行，task_type 可能停留在被编排 load() 覆盖后的
             // 'orchestrator' —— 修正为 'loop'，否则大循环历史页
             // （taskType='loop' 过滤）看不到该任务。
-            const isLoopTask = state.taskDir
-                && fs.existsSync(path.join(state.taskDir, 'loop.json'));
+            // 注意不能只看 state.taskDir：跨机拷贝的任务目录里持久化的是
+            // 异机绝对路径（本机 existsSync 恒 false），需同时检查本机
+            // 规范路径 db/task/{taskId}/loop.json。
+            const loopFileLocal = this.storage
+                ? path.join(this.storage.manager.rootDir, 'task', taskId, 'loop.json')
+                : null;
+            const isLoopTask = Boolean(
+                (state.taskDir && fs.existsSync(path.join(state.taskDir, 'loop.json')))
+                || (loopFileLocal && fs.existsSync(loopFileLocal))
+            );
+
+            // 大循环任务的对外状态/标题以 loop.json 为准（编排只是单轮载体）：
+            // 终态（passed/failed/...）、标题（用户原始任务描述）、创建时间
+            // 均取 loop 快照，与其他大循环任务的注册口径一致。
+            let loopState = null;
+            if (isLoopTask) {
+                try {
+                    loopState = await this.storage.json('task').read(`${taskId}/loop`);
+                } catch { /* ignore */ }
+            }
+            const finalStatus = (isLoopTask && loopState?.status) ? loopState.status : status;
+            const title = (isLoopTask && loopState?.taskDescription)
+                ? String(loopState.taskDescription).slice(0, 200)
+                : String(firstStep.taskDescription || taskId).slice(0, 200);
+            const description = (isLoopTask && loopState?.taskDescription)
+                ? loopState.taskDescription
+                : (firstStep.taskDescription || '');
+            const createdAt = (isLoopTask && loopState?.startTime)
+                ? loopState.startTime
+                : (state.startTime || new Date().toISOString());
+            if (isLoopTask && loopState) {
+                metadata.currentLoop = loopState.currentLoop ?? 0;
+                metadata.maxLoops = loopState.maxLoops ?? 3;
+            }
 
             if (!existing) {
-                // 老任务未入库（TaskRegistryStore 上线前创建）：补录摘要，保留原始创建时间
+                // 老任务未入库（TaskRegistryStore 上线前创建 / 跨机拷贝）：补录摘要，保留原始创建时间
                 await registry.upsert({
                     taskId,
                     taskType: isLoopTask ? 'loop' : 'orchestrator',
-                    status,
-                    title: (firstStep.taskDescription || taskId).slice(0, 200),
-                    description: firstStep.taskDescription || '',
-                    createdAt: state.startTime || new Date().toISOString(),
+                    status: finalStatus,
+                    title,
+                    description,
+                    createdAt,
                     metadata
                 });
             } else {
-                const patchBody = { status, metadata };
+                const patchBody = { status: finalStatus, metadata };
                 if (isLoopTask && existing.task_type !== 'loop') {
                     patchBody.task_type = 'loop';
                 }
@@ -957,7 +1141,7 @@ class OrchestratorController {
             }
             console.log(
                 `[OrchestratorController] 注册表已修正: taskId=${taskId}, ` +
-                `${existing ? existing.status : '(未入库)'} → ${status}`
+                `${existing ? existing.status : '(未入库)'} → ${finalStatus}`
             );
         } catch (err) {
             console.warn(`[OrchestratorController] 恢复后回写注册表失败: taskId=${taskId}, ${err.message}`);

package/vendor/Server/Skills/flutter-build-test/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: flutter-build-test
+description: 对 Flutter 三方库（OHOS 鸿蒙化仓库）执行多版本编译验证：定位 example 工程并确认含 ohos 工程代码，使用 flvm 在 3.7/3.22/3.27/3.32/3.35/3.41 六个 Flutter 版本间切换并逐版本编译 hap，判定该三方库可在哪些版本使用；随后按编译结果更新 README.OpenHarmony(_CN).md（版本支持、TAG 对应表、约束与限制）与 buildEnv.sh（FLUTTER_SDK_VERSION）。当需要验证 Flutter 三方库在哪些鸿蒙 Flutter 版本可用、或将编译验证结果回写仓库文档与构建环境脚本时使用。
+license: Apache-2.0
+compatibility: 需要 Node.js、flvm（Flutter 多版本管理器 https://gitcode.com/lalhanOrz/flvm）、OHOS Flutter SDK、DevEco Studio 工具链（java/ohpm/hvigor/hdc）、git，需可访问 pub.flutter-io.cn 镜像
+metadata:
+  author: LoopEngine
+  version: "1.0.0"
+  category: flutter-testing
+---
+
+# Flutter 三方库多版本编译验证
+
+本 Skill 对 Flutter 三方库鸿蒙化仓库执行**多版本编译验证闭环**：定位 example 工程（含 ohos 工程代码校验）→ flvm 切换 6 个 Flutter 版本（3.7/3.22/3.27/3.32/3.35/3.41）逐版本编译 hap → 判定可用版本范围 → 按结果更新 README.OpenHarmony(_CN).md 与 buildEnv.sh → 输出编译验证报告。
+
+> ⚠️ **核心原则**：
+> 1. 本 Skill 的定位是**验证**而非适配——除环境类问题（镜像、DevEco 路径、工具链）外，**不做代码级修复**；版本不兼容导致的编译失败如实记录
+> 2. **环境问题导致的失败不能记为"该版本不支持"**——必须先排除环境因素再下结论（区分标准见 [编译排错手册](references/BUILD_TROUBLESHOOTING.md)）
+> 3. 六个版本**必须串行**测试（flvm use 切换的是全局 Flutter），每版本独立记录结果
+> 4. 文档与 buildEnv.sh 的修改必须与编译结果**逐字对应**，禁止写入未经实测的版本结论
+
+---
+
+## 任务参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `libRoot` | string | ✅ | Flutter 三方库仓库根目录（含 `pubspec.yaml`，通常含 `example/`、`ohos/`、`README.OpenHarmony_CN.md`、`buildEnv.sh`） |
+| `versions` | string | ❌ | 待验证版本列表，逗号分隔；缺省 `3.7,3.22,3.27,3.32,3.35,3.41` |
+| `buildMode` | string | ❌ | 编译模式 `debug`/`release`；缺省 `debug` |
+| `codesign` | boolean | ❌ | 是否产出签名 hap；缺省 false（`--no-codesign`，无头验证编译链无需 DevEco 签名配置） |
+| `outputDir` | string | ❌ | 结果输出目录；缺省 `{libRoot}/flutter-build-test/` |
+| `updateDocs` | boolean | ❌ | 是否执行 Phase 3/4 文档回写；缺省 true |
+
+---
+
+## 输入依赖
+
+- **前置SKILL**: 无（可作为独立任务调用；仓库已克隆到本地即可）
+- **输入文件**:
+  - 库工程：`{libRoot}/pubspec.yaml`、`{libRoot}/example/`（含 `ohos/` 子目录的鸿蒙工程）
+  - 环境脚本（若存在）：`{libRoot}/buildEnv.sh`
+  - 文档（若存在）：`{libRoot}/README.OpenHarmony_CN.md`、`{libRoot}/README.OpenHarmony.md`
+
+---
+
+## 工作流程概览
+
+```
+Phase 1: 环境检查与 example 工程定位（flvm doctor + locate-example.cjs）
+    ↓
+Phase 2: 多版本编译矩阵（build-matrix.cjs：flvm 切换 + flutter build hap × 6 版本）
+    ↓
+Phase 3: 更新 README.OpenHarmony(_CN).md（TAG 对应表 + 约束与限制）
+    ↓
+Phase 4: 更新 buildEnv.sh（FLUTTER_SDK_VERSION / BUILD_PKG_DIR）
+    ↓
+Phase 5: 输出编译验证报告
+```
+
+---
+
+## Phase 1：环境检查与 example 工程定位
+
+### 1.1 环境体检（不通过禁止进入 Phase 2）
+
+```bash
+flvm doctor
+```
+
+确认以下各项（✓ 为通过，! 为警告可继续，✗ 必须修复）：
+
+| 检查项 | 不通过时的处理 |
+|--------|---------------|
+| flvm 已安装 | `npm install -g flvm`（或从 https://gitcode.com/lalhanOrz/flvm 克隆安装） |
+| flvm 已 init | `flvm init --deveco "/Applications/DevEco-Studio.app/Contents"`（Windows 为 DevEco 安装目录；详见 [FLVM 使用指南](references/FLVM_GUIDE.md)） |
+| Flutter 镜像（PUB_HOSTED_URL） | 按 flvm doctor 提示设置 `https://pub.flutter-io.cn` |
+| OHOS 工具链（java/TOOL_HOME/ohpm/hvigor/node/hdc） | 安装/修复 DevEco Studio 后重跑 `flvm init --deveco <path>` |
+
+将 `flvm doctor` 完整输出保存到 `{outputDir}/env-doctor.txt`（环境信息将写入最终报告）。
+
+### 1.2 定位 example 工程并校验 ohos 工程代码
+
+```bash
+node {skillDir}/scripts/locate-example.cjs --source {libRoot}
+```
+
+脚本行为：
+- 优先读取 `{libRoot}/buildEnv.sh` 的 `BUILD_PKG_DIR`（部分库的 example 不在根下，如 `YFree_Flutter/Lite/example`）
+- 扫描根目录及两层深度内含 `pubspec.yaml` 的 example 类目录（`example/`、`Example/`、`example_app/` 等）
+- 对每个候选校验：存在 `pubspec.yaml` **且** `ohos/` 子目录含鸿蒙工程特征（`build-profile.json5` / `oh-package.json5` / `AppScope/`）
+- 输出 JSON：`exampleDir`（绝对路径）、`ohosDir`、`buildPkgDir`（buildEnv.sh 实际值）、`hasOhos`
+
+**结果判定**：
+
+| 情况 | 处理 |
+|------|------|
+| 找到含 ohos 的 example | 记录 `exampleDir`，进入 Phase 2 |
+| 有 example 但无 `ohos/` 目录 | 可尝试 `flutter create --platforms ohos .`（在 example 目录下，需当前 Flutter 为 OHOS fork）生成后重跑定位；仍失败 → 终止并报告"缺少鸿蒙工程代码" |
+| 无任何 example 目录 | 终止并报告"未找到 example 工程" |
+
+> 🔴 **禁止**以根目录 `ohos/`（插件平台代码）替代 example 工程作为编译目标——那是库的鸿蒙实现代码（相当于 `android/`），不是可编译的应用工程。
+
+---
+
+## Phase 2：多版本编译矩阵
+
+### 2.1 执行编译矩阵脚本
+
+```bash
+node {skillDir}/scripts/build-matrix.cjs --source {libRoot} --mode {buildMode} --output {outputDir}
+```
+
+常用参数：
+
+| 参数 | 说明 |
+|------|------|
+| `--versions "3.7,3.22"` | 只测指定版本（会话超时时可分批执行） |
+| `--resume` | 断点续跑：跳过 results JSON 中已有最终结论的版本 |
+| `--example <dir>` | 显式指定 example 目录（覆盖定位结果/buildEnv.sh） |
+| `--build-timeout <sec>` | 单版本编译超时；缺省 1800 |
+| `--install-timeout <sec>` | flvm 版本安装超时；缺省 3600 |
+
+> ⚠️ **外层命令超时必须放大**：6 版本全量串行可能耗时 1 小时以上（含 flvm 版本安装与引擎缓存预热）。建议外层 timeout 设为 3600000ms 以上，或用 `--versions` 分批 + `--resume` 续跑。
+
+脚本每个版本的执行序列：
+
+1. `flvm use <分支名>` 切换版本（分支映射见下表，未安装自动安装；失败时回退模糊匹配 `flvm use <主.次>`）
+2. `flutter --version` 校验实际版本与预期一致（主.次版本号比对）
+3. 在 example 目录：`flutter clean`（忽略失败）→ 备份并删除 `pubspec.lock`（保证每版本独立求解依赖）→ `flutter pub get`
+4. `flutter build hap --{mode} --no-codesign` 编译（默认不签名——无头验证只需编译链通过；`--codesign` 需工程已配置 DevEco 调试签名，否则 flutter 工具直接报错）
+5. 校验 hap 产物存在（`example/ohos/entry/build/**/outputs/**/*.hap`）
+6. 按错误特征分类失败原因，结果**增量写入** `{outputDir}/build-matrix-results.json`，日志存 `{outputDir}/logs/{版本}.log`
+
+**版本-分支映射表**（脚本内置，与 flvm 远程分支对应）：
+
+| 主版本 | 首选分支 | 回退分支 |
+|--------|----------|----------|
+| 3.7 | `br_3.7.12-ohos-1.1.3` | `br_3.7.12-ohos-dev` |
+| 3.22 | `oh-3.22.3-release` | `oh-3.22.3-dev` |
+| 3.27 | `oh-3.27.4-dev` | `oh-3.27.0-release` |
+| 3.32 | `oh-3.32.0-release` | `oh-3.32.4-dev` |
+| 3.35 | `oh-3.35.7-dev` | `oh-3.35.7-release` |
+| 3.41 | `oh-3.41.9-release` | `oh-3.41.9-dev` |
+
+> 映射表过期时（flvm 远程分支更新），以 `flvm list -r` 实际输出为准修正脚本 `PREFERRED_BRANCHES` 表。
+
+### 2.2 失败诊断与环境因素排除
+
+对每个失败版本，按 [编译排错手册](references/BUILD_TROUBLESHOOTING.md) 分类处理：
+
+| 失败类别 | 是否重试 | 是否计入"版本不支持" |
+|----------|----------|---------------------|
+| 环境类（镜像/网络/工具链/hvigor 缓存/Java） | 修复环境后重试 | 否（修复后通过则记为支持） |
+| SDK 约束不兼容（Dart SDK 版本过低/过高） | 否 | 是 |
+| 依赖冲突（version solving failed） | 否 | 是 |
+| 鸿蒙工程编译错误（ArkTS/NAPI/hvigor 业务报错） | 否 | 是 |
+| hvigor 任务异常退出（exit 255 等） | 否（人工判定） | 结合日志定性（工具链 vs 版本不兼容） |
+| 签名错误（仅 `--codesign` 模式） | 换默认无签名模式重试 | 否 |
+
+> 🔴 **判定纪律**：同一环境问题（如 ohpm 源不可达）在多个版本上重复失败时，只诊断一次、修复一次、全部重试；禁止把环境故障逐版本重复记为"不支持"。
+
+### 2.3 版本支持结论
+
+全部版本测完后，从 `{outputDir}/build-matrix-results.json` 提取：
+
+- **支持版本列表**：`status == "pass"` 的版本（含 `pass` 所用的 flvm 分支名，供 Phase 3/4 使用）
+- **最高支持版本**：支持列表中版本号最大者（决定 buildEnv.sh 的 `FLUTTER_SDK_VERSION`）
+- **逐版本失败原因**：写入报告
+
+---
+
+## Phase 3：更新 README.OpenHarmony(_CN).md
+
+> 详细修改规范与完整模板参见 [文档修改规范](references/DOC_UPDATE_GUIDE.md) 与 [README 段落模板](assets/README_SECTION_TEMPLATE.md)。参考实例：https://gitcode.com/CPF-Flutter/fluttertpc_file_picker/blob/master/README.OpenHarmony_CN.md
+
+按 Phase 2 结论修改文档，**三处必改**：
+
+### 3.1 TAG 对应表（补充支持使用的版本）
+
+在"下载安装"章节的 TAG 表中，按版本支持结论逐行更新：
+
+```markdown
+| Flutter 框架版本 | TAG 名称 | 分支名 |
+| --- | --- | --- |
+| 3.7 | ------ | ------ |
+| 3.22 | {TAG} | {分支} |
+| 3.27 | {TAG} | {分支} |
+```
+
+- 支持的版本：`{TAG}` = 当前仓库 ohos TAG（`git describe --tags --abbrev=0` 或 `git tag --list '*ohos*'`，无 TAG 时从 CHANGELOG.OpenHarmony.md / pubspec.yaml version 推断并标注）；`{分支}` = `git branch --show-current`
+- 不支持的版本：填 `------`
+- 表格行覆盖全部 6 个框架版本（3.7/3.22/3.27/3.32/3.35/3.41），不遗漏
+
+### 3.2 约束与限制（兼容性）
+
+在"约束与限制 → 兼容性"中，将"已测试通过"清单替换为实测结果：
+
+```markdown
+### 兼容性
+
+在以下版本中已测试通过：
+
+- Flutter: {flutter版本+ohos版本}, DevEco Studio: {版本}, SDK: {API版本}({SDK版本}), ROM: {ROM版本};
+```
+
+- 每个支持版本一行，环境信息取自 `{outputDir}/env-doctor.txt` 与本机 DevEco Studio（`devecocli --version`、`DEVECO_SDK_HOME` 下 sdk 版本目录）；ROM 版本在有真机时经 `hdc shell param get const.product.software.version` 获取，无设备则省略 ROM 字段并在报告注明
+- 保留该章节其余内容（权限要求等），**只增改版本相关部分，禁止删除既有内容**
+
+### 3.3 英文版同步
+
+`README.OpenHarmony.md`（英文版）存在时，镜像同步 3.1/3.2 两处修改（英文措辞，表格结构一致）。README 均不存在时，按 [README 段落模板](assets/README_SECTION_TEMPLATE.md) 新建。
+
+---
+
+## Phase 4：更新 buildEnv.sh
+
+```bash
+node {skillDir}/scripts/update-buildenv.cjs --source {libRoot} --results {outputDir}/build-matrix-results.json
+```
+
+脚本行为（参考实例：https://gitcode.com/CPF-Flutter/fluttertpc_flutter_udid/blob/br_v4.1.1_ohos_dev/buildEnv.sh）：
+
+1. 读取 `{libRoot}/buildEnv.sh`（不存在时按 [buildEnv 模板](assets/BUILDENV_TEMPLATE.md) 新建，含 Apache 头）
+2. `FLUTTER_SDK_VERSION` ← 最高支持版本实测通过的 flvm 分支名（取自 results JSON 的 `branch` 字段，如 `oh-3.35.7-dev`）——**按分支实际支持的版本回写**
+3. `BUILD_PKG_DIR` ← Phase 1 定位的实际 example 相对路径（原值正确则不动）
+4. 保留 License 头部与既有结构，只改上述两个变量行
+5. 输出变更对照到 `{outputDir}/buildenv-update-report.json`
+
+> 用 `--branch` 可显式覆盖（仅当调用方明确指定时使用）。所有支持版本均失败时不修改 `FLUTTER_SDK_VERSION`，在报告中标注。
+
+---
+
+## Phase 5：输出编译验证报告
+
+`write_file` `{outputDir}/flutter-build-test-report.md`，模板参见 [编译验证报告模板](assets/BUILD_REPORT_TEMPLATE.md)，内容必须包含：
+
+1. **环境信息**：flvm 版本、Flutter 已装版本、DevEco Studio / SDK / ROM（引用 env-doctor.txt）
+2. **编译矩阵结果表**：版本 | flvm 分支 | pub get | build hap | 结论 | 失败原因摘要
+3. **版本支持结论**：支持版本列表 + 最高支持版本
+4. **文档更新记录**：README.OpenHarmony(_CN).md 修改点（TAG 对应表前后对照）、buildEnv.sh 变更对照（引用 buildenv-update-report.json）
+5. **仓库状态说明**：测试期间的临时改动——pubspec.lock 已由脚本恢复原文件；`build/`、`.dart_tool/` 等未跟踪产物遗留于 example 目录（建议 `flutter clean` 或按需保留）；flutter 工具会自动修改 `example/ohos/build-profile.json5`、`oh-package.json5` 注册插件模块（属构建正常副作用，`build-matrix-results.json` 的 `repoChangesDuringBuild` 字段已记录，报告中如实列出，调用方要求干净仓库时可 `git checkout` 恢复）
+6. **遗留问题**：环境类失败、待人工复核项
+
+---
+
+## 参考资料
+
+- 共享脚本：`scripts/locate-example.cjs` / `scripts/build-matrix.cjs` / `scripts/update-buildenv.cjs`
+- flvm 工具：https://gitcode.com/lalhanOrz/flvm（`flvm --help` / [FLVM 使用指南](references/FLVM_GUIDE.md)）
+- 文档范例：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

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

@@ -0,0 +1,42 @@
+# buildEnv.sh 模板
+
+> `buildEnv.sh` 不存在时按此模板新建（与 CPF-Flutter 社区仓库保持一致，参考 fluttertpc_flutter_udid）。`{占位符}` 由 update-buildenv.cjs 填充。本文件是**目标仓库的交付物模板**（Bash 脚本），非本 SKILL 的可执行脚本。
+
+---
+
+## 模板内容
+
+```bash
+#!/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相对路径，通常为 example}
+  FLUTTER_SDK_VERSION={最高支持版本实测通过的 flvm 分支名，如 oh-3.35.7-dev}
+```
+
+## 填充规则
+
+| 变量 | 取值 |
+|------|------|
+| `BUILD_PKG_DIR` | Phase 1 定位的 example 相对路径（`example` / `YFree_Flutter/Lite/example` 等） |
+| `FLUTTER_SDK_VERSION` | build-matrix-results.json 中最高 pass 版本的 `branch` 字段（如 `oh-3.35.7-dev`、`oh-3.27.4-dev`） |
+
+## 使用方式
+
+```bash
+node {skillDir}/scripts/update-buildenv.cjs --source {libRoot} --results {outputDir}/build-matrix-results.json
+```
+
+脚本内置本模板，自动完成新建/更新并赋予可执行权限（0755）。