企业官网建设流程全解析

• 跨平台
• 前端
• 移动开发
• OpenHarmony

本文以 CPF-Flutter/flutter_flutter（Flutter SDK 与 Engine 的 OpenHarmony 适配仓库）中的find-release技能文档为主体，完整讲解"给定一个 commit SHA，如何确定它最早进入哪个 Flutter/Dart 发布版本"这一典型问题的解决流程：包括参数提取、find_release.dart工具的调用方式与输出字段解读，并结合当前仓库中 技能定义、依赖声明文件 与 技能规范说明 说明该技能在本仓库中的落地细节。读完本文，你可以独立完成一次"commit → 首发 release"的查询，并理解该技能在 Agent Skills 体系中的位置与校验方式。

一、find-release 技能的定位：Agent Skills 体系中的一个专用工作流

find-release技能定义在 SKILL.md 中，其 frontmatter 元信息声明了名称与适用场景：

• name:find-release
• description: 查找包含指定 commit 的最低 Dart 与 Flutter 发布版本。只要用户询问"某个 commit 何时进入了 Flutter 或 Dart 的发布版本"、询问特定 SHA 对应的发布版本，或想知道某个 commit 是否已包含在 Flutter/Dart 项目的stable、beta、dev渠道中，都应使用此技能。

从源码结构看，该文件位于.agents/skills/目录，与flutter-pr-checks-finder、rebuilding-flutter-tool等技能并列。.agents/skills/README.md 对该目录的规范要求包括：技能命名遵循 Claude 命名规范、技能内容遵循 agentskills.io 的开放标准、"一个 CLI 工具对应一个技能"、脚本优先使用 Dart 编写等。此外，仓库还提供了dart_skills_lint工具用于校验技能文件（可检查行尾空白、绝对路径、相对路径是否指向存在的文件），校验命令在dev/tools目录下执行：

dart run dart_skills_lint:cli --skills-directory ../../.agents/skills \ --check-trailing-whitespace --check-absolute-paths --check-relative-paths

有一个值得注意的细节：dart_skills_lint_ignore.json 中，find-release技能被显式豁免了check-relative-paths（相对路径存在性检查）这一条规则。原因是该技能文档中引用的find_release.dart工具位于 Dart SDK 检出目录之下（见下文），该目录属于 gclient 依赖、在纯框架检出中并不存在实体文件。这从配置层面印证了：该工具文件并非本仓库直接检入的源码，而是随 Dart SDK 依赖提供的——这也正是技能文档要求通过环境变量FIND_RELEASE_TOOL_PATH覆盖工具路径的原因。

二、技能工作流程：三步完成"commit → 首发 release"查询

技能文档（SKILL.md）给出的完整工作流分为三个阶段：提取信息、执行搜索、解读并汇报结果。

第一步：从用户请求中提取关键信息

1. commit SHA：从用户的请求中识别目标提交，例如02abc57（短 SHA 或完整 SHA 均可，由工具内部完成匹配）。
2. 目标渠道（channel）：取值限定为stable、beta、dev三者之一。如果用户没有指定渠道，技能要求对每个渠道分别尝试。

第二步：执行 find_release.dart 工具

技能文档明确要求"先确保find_release.dart工具可用，再用其路径执行，从而保证命令在仓库工作区内的任意目录都能运行"。工具默认位于工作区根目录下的engine/src/flutter/third_party/dart/tools/find_release.dart；如果工作区根目录不是默认布局（例如本适配仓库这类以 gclient 管理引擎依赖的检出），则需设置环境变量FIND_RELEASE_TOOL_PATH指向工具的绝对路径。

标准命令格式为：

dart run ${FIND_RELEASE_TOOL_PATH:-engine/src/flutter/third_party/dart/tools/find_release.dart} --commit=<SHA> --channel=<CHANNEL>

参数说明：

当前仓库中该工具路径的来源：在本仓库的 DEPS 文件中，engine/src/flutter/third_party/dart被声明为 gclient 依赖，指向 Dart SDK 仓库（Var('dart_git') + '/sdk.git@' + Var('dart_revision')，其中dart_revision固定为a29e08c72e2ce21813c1edf50cbcdfcac7a7acdd，见 DEPS）；OpenHarmony 侧的 DEPS_ohos 同样声明了该依赖（第 303 行）。因此：

• find_release.dart工具由 Dart SDK 检出提供，只有执行过gclient sync之后该目录才会实际存在；
• 在本适配仓库中，引擎依赖的同步入口是engine/ohos脚本（其底层调用python3 ./src/flutter/attachment/scripts/ohos.py），gclient 引导文件为 engine/scripts/ohos.gclient（其deps_file指向DEPS_ohos）；
• 如果当前检出没有执行引擎依赖同步，engine/src/flutter/third_party/dart/tools/find_release.dart将不存在，此时按技能文档的建议，应设置FIND_RELEASE_TOOL_PATH指向一个含该工具的完整工作区中的绝对路径再执行。

第三步：解读并汇报结果

工具执行后的输出与汇报规则在技能文档中有明确约定：

1. 所属仓库：工具会报告该 commit 在哪个仓库中被找到——dart-lang/sdk或flutter/flutter。
2. Lowest release tag：包含该 commit 的最低 git 发布标签（tag）。
3. Lowest Flutter release / Lowest Dart release：针对指定渠道（stable/beta/dev）给出的最低 Flutter 发布版本号和/或最低 Dart 版本号。

汇报时应将上述发现清晰呈现给用户；如果 commit 未找到、或尚未进入该渠道的任何发布版本，应如实告知，而不是给出推测性结论。

边界情况处理（技能文档明确要求）：

• SHA 无效或未找到 → 建议用户核对 SHA 是否正确；
• 渠道参数无效 → 工具默认回落到stable，同时需通知用户这一默认行为。

三、文档内置示例：两个典型问答场景

技能文档自带两个端到端示例，直接说明了"用户提问 → Agent 动作"的对应关系：

• 场景 1：用户问 "When did commit 02abc57 land in stable?"（commit 02abc57 何时进入 stable？）。 Agent 执行：

  dart run ${FIND_RELEASE_TOOL_PATH:-engine/src/flutter/third_party/dart/tools/find_release.dart} --commit=02abc57 --channel=stable

  并向用户汇报返回的发布版本号。

• 场景 2：用户问 "Is 02abc57 in beta?"（02abc57 是否在 beta 中？）。 Agent 执行同样的命令，仅将参数改为--channel=beta，再依据输出判断该 commit 是否已包含在 beta 渠道的发布中。

这两个示例覆盖了技能最核心的两类诉求：回溯查询（某 commit 首次随哪个版本发布）与归属查询（某 commit 是否已进入指定渠道）。

四、在 CPF-Flutter/OpenHarmony 适配仓库中的使用要点

结合本仓库的实际结构，使用find-release技能时有三点值得注意：

1. 工具路径依赖 gclient 检出：与上文一致，find_release.dart随 Dart SDK 依赖（DEPS、DEPS_ohos）提供。在仅拉取框架代码的检出中执行命令会报"文件不存在"，这是预期行为而非命令写错——正确做法是按技能文档设置FIND_RELEASE_TOOL_PATH环境变量指向完整工作区。
2. 引擎同步入口：本仓库构建 OpenHarmony 版 Flutter Engine 的依赖同步通过engine/ohos脚本完成，gclient 配置见 engine/scripts/ohos.gclient（指向 gitcode 上的 openharmony-tpc/flutter_flutter 仓库、使用DEPS_ohos作为依赖文件）。完成同步后即可直接使用默认的相对路径执行工具，无需额外设置环境变量。
3. 技能文件的合规性：.agents/skills/README.md要求技能文件通过dart_skills_lint校验；本技能因引用了 gclient 依赖路径而豁免了相对路径存在性检查（见 dart_skills_lint_ignore.json）。若你参考本技能编写新技能，建议优先引用仓库内实际存在的文件路径，避免类似的豁免配置。

五、小结与延伸阅读

find-release技能把"commit → 首发 release"这类高频版本回溯问题固化成了三步标准流程：提取 SHA 与渠道 →dart run find_release.dart --commit=... --channel=...→ 按"所属仓库 / Lowest release tag / Lowest Flutter/Dart release"三个字段汇报，并对无效 SHA、无效渠道等边界情况给出了明确处置策略。它演示了 Flutter 仓库 Agent Skills 体系"一工具一技能、结构化指令、明确输出契约"的设计范式。

延伸阅读路径（均为仓库根目录相对路径）：

• 技能本体：.agents/skills/find-release/SKILL.md
• 技能目录规范与校验工具：.agents/skills/README.md、.agents/skills/dart_skills_lint_ignore.json
• 工具来源的依赖声明：DEPS（第 59 行dart_revision、第 296–297 行 Dart SDK 检出声明）、DEPS_ohos
• OpenHarmony 引擎依赖同步入口：engine/ohos、engine/scripts/ohos.gclient
• 同类技能参考：.agents/skills/flutter-pr-checks-finder/SKILL.md

• 跨平台
• 前端
• 移动开发
• OpenHarmony