@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/Skills/flutter-code-check/references/CHECKLIST.md

@@ -0,0 +1,190 @@
+# Flutter 代码检视清单
+
+本文档包含 Flutter 三方库 PR 代码检视的完整检查项。
+
+---
+
+## 1. 非兼容变更（Breaking Changes）
+
+- [ ] 是否删除或重命名了公开 Plugin API / MethodChannel 方法名
+- [ ] 是否修改了 Dart 侧 `MethodChannel.invokeMethod` 的方法名或参数结构
+- [ ] 是否修改了 `result.success()` 的返回数据格式（影响 Dart 侧解析）
+- [ ] 是否修改了 `oh-package.json5` 中影响依赖解析的字段
+
+---
+
+## 2. Flutter Plugin 协议合规性（ohos/ ArkTS 实现）
+
+- [ ] Plugin 入口类是否继承并正确实现了 `FlutterPlugin` 接口
+- [ ] `onAttachedToEngine(binding: FlutterPluginBinding)` 中完成了 Channel 注册和资源初始化
+- [ ] `onDetachedFromEngine(binding: FlutterPluginBinding)` 中释放了所有 Channel 和监听器
+- [ ] `MethodCallHandler.onMethodCall` 覆盖了所有 Dart 侧声明的方法
+- [ ] `onMethodCall` 含 `else` 分支调用 `result.notImplemented()`
+- [ ] `result.success()` / `result.error()` / `result.notImplemented()` 调用后有 `return`，防止重复回调
+- [ ] EventChannel（如有）的 `StreamHandler.onListen` / `onCancel` 对称实现
+
+---
+
+## 3. ArkTS 语言约束
+
+- [ ] 无 `any` 类型使用（禁止 `as any`、隐式 any）
+- [ ] 无 `eval()`、`Function()` 动态代码执行
+- [ ] 无 `prototype` 动态修改
+- [ ] 装饰器使用正确（`@Component`、`@State`、`@Observed` 等）
+- [ ] 是否使用已废弃的 OHOS API（`@deprecated` 标注的接口）
+- [ ] 泛型类型参数明确，避免推导歧义
+
+---
+
+## 4. OpenHarmony API 兼容性
+
+- [ ] 新增 API 使用是否超出工程 `minAPIVersion`
+- [ ] 是否使用了 OHOS 专有 API 但未做平台判断
+- [ ] 权限申请是否正确（`requestPermissionsFromUser`）
+- [ ] `OH_*` C API 的返回值是否有检查（Native 模块场景）
+
+---
+
+## 5. 异步处理
+
+- [ ] 所有异步 OHOS API 调用均有 `await` 或 `.then()` 处理
+- [ ] `try/catch` 覆盖所有 `await` 调用，catch 块有实质性错误处理
+- [ ] 未处理的 Promise rejection（`.catch()` 或 `try/catch` 必须存在）
+- [ ] 大量数据处理是否使用 Worker/TaskPool 而非主线程执行
+- [ ] 并行异步操作使用 `Promise.all`，避免不必要的顺序 await
+
+---
+
+## 6. 事件监听器管理（on/off 对称性）
+
+- [ ] 每个 `on('eventName', handler)` 有对应 `off('eventName', handler)`
+- [ ] 监听器在 `onDetachedFromEngine` 或设备销毁时被移除
+- [ ] 重连场景中同一事件多次调用 `on` 不会造成监听器堆积
+- [ ] EventChannel 的 `onCancel` 中清理了所有底层事件订阅
+
+---
+
+## 7. C++ Native 实现
+
+- [ ] NAPI 导出函数命名与 ArkTS 侧调用一致
+- [ ] `napi_create_*` 创建的对象在不需要时正确释放
+- [ ] `napi_ref` 在不需要时调用 `napi_delete_reference`
+- [ ] 跨线程回调使用 `napi_threadsafe_function` 或 `uv_async_send`
+- [ ] 共享数据结构有互斥锁保护
+- [ ] C++ 异常捕获并转为 NAPI 错误
+- [ ] `malloc`/`new` 有对应 `free`/`delete`
+
+---
+
+## 8. 错误处理
+
+- [ ] `result.error()` 调用后有 `return`，避免后续代码继续执行
+- [ ] 错误信息包含错误码（`e.code`）和错误描述（`e.message`）
+- [ ] switch-case 中每个 case 末尾有 `break`（避免 fall-through）
+- [ ] 提前 `return` 不会跳过必要的资源清理
+
+---
+
+## 9. 内存与资源管理
+
+- [ ] `onDetachedFromEngine` 中清理了 MethodChannel、EventChannel 的 handler
+- [ ] 定时器（`setInterval`/`setTimeout`）有对应 `clearInterval`/`clearTimeout`
+- [ ] `ArrayBuffer` / `Uint8Array` 大数据用完后无强引用持有
+- [ ] Map / Set 数据结构在不再需要时及时 `delete` / `clear`
+
+---
+
+## 10. 跨平台一致性对比（ohos vs android/iOS）
+
+> PR 中仅包含鸿蒙代码提交，需从克隆的仓库中读取 `android/` 和 `ios/` 的已有实现进行对比。
+
+- [ ] ohos `onMethodCall` 的 case 分支与 android `onMethodCall` 完全对应，无缺失方法
+- [ ] 同一 MethodChannel 方法名在 ohos 注册与 android 注册一致（Dart 侧共用同一 Channel）
+- [ ] 同一方法中，ohos 解析 `call.argument` 的类型与 android 一致（如 `bool` vs `string` 的致命错误）
+- [ ] `result.success()` 返回值的数据结构与 android 对齐（字段名、类型、嵌套层级）
+- [ ] `result.error()` 的 code 和 message 与 android 对齐，确保 Dart 侧异常处理逻辑一致
+- [ ] android 有实现但 ohos 为 Stub（返回固定值无实际操作）的方法已标记并记录
+- [ ] EventChannel（如有）的事件名和事件数据格式与 android 一致
+- [ ] 新增的 ohos 方法在 android 中是否也存在对应实现，避免鸿蒙侧单方面新增
+
+---
+
+## 11. Dart 接口层（lib/ 目录）
+
+> **核心原则**：鸿蒙适配 PR 中 Dart 代码不应修改。以下检查项用于验证现有 Dart 代码的正确性，若发现 PR 修改了 Dart 代码，必须转入第 15 节进行必要性审查。
+
+- [ ] Platform Interface 方法签名与鸿蒙侧 `onMethodCall` 实现一致
+- [ ] 是否有鸿蒙平台判断：`Platform.isOHOS` 或 `defaultTargetPlatform == TargetPlatform.ohos`
+- [ ] 公共 API 有完整的文档注释（Dart doc）
+- [ ] 异步方法返回 `Future<T>`，同步方法有明确说明
+- [ ] Dart 侧 `MethodChannel` 注册名与 ohos 侧注册名一致
+- [ ] Dart 侧 `invokeMethod` 调用的方法名在 ohos `onMethodCall` 中均有对应 case 分支
+
+---
+
+## 12. 安全性
+
+- [ ] 无硬编码的密钥、Token、密码等敏感信息
+- [ ] 网络请求是否校验 HTTPS 证书（禁止忽略证书错误）
+- [ ] 用户输入是否有校验和过滤（防注入）
+- [ ] 文件路径是否有安全校验（防路径穿越）
+- [ ] 敏感数据不在日志中输出
+
+---
+
+## 13. 构建配置
+
+- [ ] `oh-package.json5` 新增依赖合理，来源可信，无 `*` 通配版本
+- [ ] `CMakeLists.txt` 链接的系统库均为必要依赖
+- [ ] `minAPIVersion` / `targetAPIVersion` 变更合理
+- [ ] 不存在不必要的依赖或版本锁定过死
+
+---
+
+## 14. 代码规范
+
+- [ ] 命名遵循驼峰规则（变量/方法小驼峰，类/接口大驼峰）
+- [ ] 无冗余的 `console.log` 调试代码遗留
+- [ ] 公共 API 有完整 JSDoc / Dart doc 注释
+- [ ] 文件头版权声明完整
+
+---
+
+## 15. Dart 改动必要性审查（lib/ 目录变更）
+
+> **前提**：鸿蒙适配 PR 的本质是为已有库增加 ohos 平台实现，Dart 代码理论上不应修改。若 PR 包含 `lib/` 目录的变更，必须逐项进行必要性审查。
+
+### 15.1 变更识别
+
+- [ ] 已完整列出 PR 中所有 `lib/**/*.dart` 文件的变更点
+- [ ] 已区分每处变更是「新增代码」还是「修改/删除已有代码」
+- [ ] 已记录每处变更涉及的文件、行号、变更类型
+
+### 15.2 必要性判定
+
+- [ ] 每处 Dart 变更是否为鸿蒙适配的**唯一实现方式**（无法在 ohos 侧单独完成）
+- [ ] 新增 `Platform.isOHOS` / `TargetPlatform.ohos` 条件分支 — ✅ 通常必要
+- [ ] 新增 ohos 平台注册逻辑 — ✅ 通常必要
+- [ ] 修改 `MethodChannel` 名称 — ❌ 应在 ohos 侧注册相同 Channel 名
+- [ ] 修改 `invokeMethod` 的参数结构 — ❌ 应在 ohos 侧适配参数解析
+- [ ] 修改 `result` 返回值的解析/类型 — ❌ 应在 ohos 侧返回与 android 相同格式
+- [ ] 修改 Platform Interface 方法签名 — ❌ 应通过 ohos Plugin 实现适配
+- [ ] 删除或注释已有功能代码 — ❌ 鸿蒙适配不应删除已有功能
+- [ ] 新增 `import 'dart:io'`（原无此依赖） — ⚠️ 需评估是否影响 Web 平台编译
+- [ ] 新增公共 API 方法 — ⚠️ 需评估是否为通用需求还是仅 ohos 使用
+- [ ] 修改 `pubspec.yaml` 依赖 — ⚠️ 需评估新增依赖的必要性
+
+### 15.3 跨平台影响评估
+
+- [ ] Dart 变更是否在 `Platform.isOHOS` 条件分支内，确保不影响 android/iOS 运行时行为
+- [ ] 修改后的 `MethodChannel.invokeMethod` 参数是否仍与 android 侧实现兼容
+- [ ] 修改后的返回值解析逻辑是否仍与 android 侧 `result.success()` 返回格式兼容
+- [ ] Platform Interface 的默认实现行为是否被改变（影响未注册平台的行为）
+- [ ] 公共 API 签名若变更，`pubspec.yaml` 版本号是否对应升 major（语义化版本）
+- [ ] 新增的 `import` 或依赖是否引入了 android/iOS/Web 平台的编译或运行时问题
+
+### 15.4 替代方案建议
+
+- [ ] 对于「不应修改」的变更，已给出 ohos 侧的替代实现方案
+- [ ] 对于「需评估」的变更，已分析替代方案并给出推荐
+- [ ] 替代方案不引入新的跨平台兼容性问题

package/vendor/Server/Skills/flutter-code-check/references/PLATFORMS.md

@@ -0,0 +1,134 @@
+# 平台 API 参考
+
+本文档详细说明各代码托管平台的 API 调用方式和 patch 下载方法。
+
+---
+
+## GitCode 平台
+
+### 1. PR 元数据 API
+
+```bash
+curl -s "https://api.gitcode.com/api/v5/repos/{owner}/{repo}/pulls/{prNumber}?access_token={accessToken}"
+```
+
+响应字段提取：
+
+| 字段 | JSON 路径 | 说明 |
+|------|-----------|------|
+| PR 标题 | `title` | |
+| 目标分支 | `base.ref` | 即 `targetBranch` |
+| Head SHA | `head.sha` | PR 最新提交 hash |
+| 作者 | `user.name` / `user.email` | |
+| 创建时间 | `created_at` | |
+| PR 状态 | `state` | open/merged/closed |
+
+### 2. Commit Patch API（推荐）
+
+> **核心接口**：直接获取 PR head commit 的 patch 文件。
+
+```bash
+curl -s "https://api.gitcode.com/api/v5/repos/{owner}/{repo}/commit/{head.sha}/patch?access_token={accessToken}" -o {outputDir}/pr.patch
+```
+
+**关键注意**：
+- 路径使用 `commit`（单数），不是 `commits`（复数）
+- `{head.sha}` 从 PR 元数据 API 获取
+
+**Patch 文件格式**：
+```
+From <commit-hash> Mon Sep 17 00:00:00 2001
+From: <author> <email>
+Date: <date>
+Subject: [PATCH] <commit message>
+
+<file change statistics>
+
+diff --git a/<file> b/<file>
+...
+```
+
+**从 Patch 提取信息**：
+- Commit 作者、日期、message（头部元数据）
+- 修改文件列表（扫描 `diff --git a/<file> b/<file>` 行）
+- 文件变更统计（`<file> | <added> +, <removed> -` 行）
+- 具体代码变更（diff hunks）
+
+---
+
+## GitHub 平台
+
+### 1. PR 元数据 API
+
+```bash
+curl -s "https://api.github.com/repos/{owner}/{repo}/pulls/{prNumber}"
+```
+
+### 2. Patch URL
+
+```bash
+curl -L -o pr.patch "https://github.com/{owner}/{repo}/pull/{prNumber}.patch"
+curl -L -o pr.diff "https://github.com/{owner}/{repo}/pull/{prNumber}.diff"
+```
+
+---
+
+## Gitee 平台
+
+### 1. PR 元数据 API
+
+```bash
+curl -s "https://gitee.com/api/v5/repos/{owner}/{repo}/pulls/{prNumber}?access_token={accessToken}"
+```
+
+### 2. Patch URL
+
+```bash
+curl -L -o pr.patch "https://gitee.com/{owner}/{repo}/pulls/{prNumber}.patch"
+```
+
+---
+
+## GitLab 平台
+
+### 1. Patch URL
+
+```bash
+curl -L -o pr.patch "https://gitlab.com/{owner}/{repo}/-/merge_requests/{prNumber}.patch"
+```
+
+---
+
+## 仓库克隆策略
+
+### GitCode
+
+```bash
+# 克隆目标分支
+git clone --depth=50 --branch {targetBranch} https://gitcode.com/{owner}/{repo}.git {outputDir}/source/
+
+# 拉取 PR HEAD
+git ls-remote origin  # 查找 refs/merge-requests/{prNumber}/head
+git fetch origin refs/merge-requests/{prNumber}/head:pr{prNumber}
+```
+
+### 其他平台
+
+```bash
+git clone --depth=50 --branch {targetBranch} https://{platform}/{owner}/{repo}.git {outputDir}/source/
+```
+
+若指定分支克隆失败，去掉 `--branch` 参数克隆默认分支。
+
+---
+
+## 文件类型识别
+
+| 路径/扩展名 | 类型 | 检视优先级 |
+|-------------|------|------------|
+| `ohos/src/main/ets/**/*.ets` | ArkTS Plugin 实现 | **最高** |
+| `ohos/src/main/cpp/**` | C++ Native | **高** |
+| `ohos/CMakeLists.txt` / `*.cmake` | 构建系统 | 中 |
+| `ohos/oh-package.json5` | 包依赖 | 中 |
+| `lib/**/*.dart` | Dart 接口层 | 中 |
+| `example/**` | 示例工程 | 低 |

package/vendor/Server/Skills/flutter-code-check/scripts/validate-skill.cjs

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+/**
+ * @tool validate-skill
+ * @description 校验 SKILL 目录是否符合 Agent Skills 规范，检查 frontmatter、结构、渐进式披露。跨平台（Windows/macOS/Linux），仅需 Node.js。
+ * @param skillDir: string - SKILL 目录绝对路径
+ * @hidden
+ * validate-skill.cjs
+ *
+ * 用法:
+ *   # CLI 模式
+ *   node validate-skill.cjs /path/to/skill
+ *
+ *   # MCP Gateway 模式（第一个参数为 JSON 字符串）
+ *   node validate-skill.cjs '{"skillDir":"/path/to/skill"}'
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// ── 参数解析（兼容 MCP Gateway JSON 模式与 CLI 模式） ──────
+
+function parseArgs(argv) {
+  if (argv.length === 0) return {};
+  const first = argv[0];
+  if (typeof first === 'string' && first.startsWith('{')) {
+    try { return JSON.parse(first); } catch (e) { return {}; }
+  }
+  return { skillDir: first };
+}
+
+// ── 输出统计 ─────────────────────────────────────────────
+
+let PASS = 0;
+let FAIL = 0;
+let WARNINGS = 0;
+
+function checkPass(msg) { console.log(`  ✅ ${msg}`); PASS += 1; }
+function checkFail(msg) { console.log(`  ❌ ${msg}`); FAIL += 1; }
+function checkWarn(msg) { console.log(`  ⚠️  ${msg}`); WARNINGS += 1; }
+
+// ── Frontmatter 解析 ─────────────────────────────────────
+
+/**
+ * 解析 SKILL.md 的 frontmatter 与 body。
+ * 返回 { frontmatter: object|null, bodyLines: string[] }
+ */
+function parseFrontmatter(content) {
+  const lines = content.split(/\r?\n/);
+  if (!lines[0] || lines[0].trim() !== '---') {
+    return { frontmatter: null, bodyLines: lines };
+  }
+  let end = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === '---') { end = i; break; }
+  }
+  if (end === -1) {
+    return { frontmatter: null, bodyLines: lines };
+  }
+  const fmLines = lines.slice(1, end);
+  const fm = {};
+  let currentKey = null;
+  for (const line of fmLines) {
+    const m = line.match(/^([a-zA-Z_][\w-]*):\s*(.*)$/);
+    if (m) {
+      currentKey = m[1];
+      fm[currentKey] = m[2].trim();
+    } else if (currentKey && /^\s+\S/.test(line)) {
+      fm[currentKey] += '\n' + line.trim();
+    }
+  }
+  return { frontmatter: fm, bodyLines: lines.slice(end + 1) };
+}
+
+// ── 主流程 ───────────────────────────────────────────────
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const skillDir = args.skillDir || '';
+
+  if (!skillDir) {
+    console.log('Usage: node validate-skill.cjs <skillDir>');
+    console.log('Error: skillDir parameter is required');
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(skillDir) || !fs.statSync(skillDir).isDirectory()) {
+    console.log(`Error: Directory does not exist: ${skillDir}`);
+    process.exit(1);
+  }
+
+  console.log('=== SKILL 规范校验 ===');
+  console.log(`目录: ${skillDir}`);
+  console.log('');
+
+  // ─── 1. SKILL.md 存在性 ───
+  console.log('--- 1. 文件结构检查 ---');
+  const skillFile = path.join(skillDir, 'SKILL.md');
+  if (fs.existsSync(skillFile) && fs.statSync(skillFile).isFile()) {
+    checkPass('SKILL.md 存在');
+  } else {
+    checkFail('SKILL.md 不存在');
+    console.log('无法继续校验，SKILL.md 是必需文件');
+    process.exit(1);
+  }
+
+  const content = fs.readFileSync(skillFile, 'utf-8');
+  const { frontmatter, bodyLines } = parseFrontmatter(content);
+
+  // ─── 2. Frontmatter 检查 ───
+  console.log('');
+  console.log('--- 2. Frontmatter 检查 ---');
+
+  if (frontmatter) {
+    checkPass('YAML frontmatter 存在');
+  } else {
+    checkFail('缺少 YAML frontmatter（文件应以 --- 开头并以 --- 结束头部）');
+  }
+
+  const nameField = frontmatter ? String(frontmatter.name || '') : '';
+  if (nameField) {
+    checkPass(`name 字段存在: ${nameField}`);
+
+    // name 字符集校验
+    if (/^[a-z0-9]+(-[a-z0-9]+)*$/.test(nameField)) {
+      checkPass('name 字符集合规（仅小写字母/数字/连字符）');
+    } else {
+      checkFail('name 字符集不合规：应仅含 a-z/0-9/-，不能首尾连字符或连续连字符');
+    }
+
+    // name 长度校验
+    const nameLen = nameField.length;
+    if (nameLen >= 1 && nameLen <= 64) {
+      checkPass(`name 长度合规 (${nameLen} 字符)`);
+    } else {
+      checkFail(`name 长度不合规：应在 1-64 字符之间（当前 ${nameLen}）`);
+    }
+
+    // name 匹配目录名
+    const dirName = path.basename(path.resolve(skillDir));
+    if (nameField === dirName) {
+      checkPass(`name 匹配父目录名 (${dirName})`);
+    } else {
+      checkFail(`name 不匹配父目录名：name='${nameField}' vs 目录='${dirName}'`);
+    }
+  } else {
+    checkFail('name 字段缺失');
+  }
+
+  const descField = frontmatter ? String(frontmatter.description || '') : '';
+  if (descField) {
+    const descLen = descField.length;
+    if (descLen <= 1024) {
+      checkPass(`description 长度合规 (${descLen} 字符)`);
+    } else {
+      checkFail(`description 过长：应 ≤1024 字符（当前 ${descLen}）`);
+    }
+  } else {
+    checkFail('description 字段缺失或为空');
+  }
+
+  if (frontmatter && frontmatter.license) {
+    checkPass('license 字段存在');
+  } else {
+    checkWarn('license 字段缺失（推荐添加）');
+  }
+
+  if (frontmatter && frontmatter.metadata) {
+    checkPass('metadata 字段存在');
+  } else {
+    checkWarn('metadata 字段缺失（推荐添加 author/version）');
+  }
+
+  // ─── 3. Body 检查 ───
+  console.log('');
+  console.log('--- 3. Body 内容检查 ---');
+
+  const bodyLineCount = bodyLines.length;
+  if (bodyLineCount <= 500) {
+    checkPass(`body 行数合规 (${bodyLineCount} 行, ≤500)`);
+  } else {
+    checkWarn(`body 行数较多 (${bodyLineCount} 行，推荐 < 500，考虑拆分到 references/)`);
+  }
+
+  if (/任务参数|## .*参数|\|\s*参数/.test(content)) {
+    checkPass('包含任务参数说明');
+  } else {
+    checkWarn('未找到任务参数表（推荐添加）');
+  }
+
+  if (/工作流程|Phase|## Phase/.test(content)) {
+    checkPass('包含工作流程概览');
+  } else {
+    checkWarn('未找到工作流程概览（推荐添加）');
+  }
+
+  // ─── 4. 渐进式披露检查 ───
+  console.log('');
+  console.log('--- 4. 渐进式披露检查 ---');
+
+  const refsDir = path.join(skillDir, 'references');
+  if (fs.existsSync(refsDir) && fs.statSync(refsDir).isDirectory()) {
+    const refFiles = fs.readdirSync(refsDir)
+      .filter((f) => f.endsWith('.md') && fs.statSync(path.join(refsDir, f)).isFile());
+    checkPass(`references/ 目录存在 (${refFiles.length} 个文档)`);
+
+    // 检查引用深度（一层）
+    const nestedDirs = fs.readdirSync(refsDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory()).length;
+    if (nestedDirs === 0) {
+      checkPass('references 保持一层深度');
+    } else {
+      checkFail(`references 存在嵌套子目录 (${nestedDirs} 个)，应保持一层深度`);
+    }
+  } else {
+    checkWarn('无 references/ 目录（详细内容建议拆分到此目录）');
+  }
+
+  const assetsDir = path.join(skillDir, 'assets');
+  if (fs.existsSync(assetsDir) && fs.statSync(assetsDir).isDirectory()) {
+    checkPass('assets/ 目录存在');
+  } else {
+    checkWarn('无 assets/ 目录（如需模板/资源可添加）');
+  }
+
+  const scriptsDir = path.join(skillDir, 'scripts');
+  if (fs.existsSync(scriptsDir) && fs.statSync(scriptsDir).isDirectory()) {
+    checkPass('scripts/ 目录存在');
+  } else {
+    checkWarn('无 scripts/ 目录（如需可执行脚本可添加）');
+  }
+
+  // 检查文件引用使用相对路径
+  const absRefs = (content.match(/\]\(\/[^)]+\)/g) || []).length;
+  if (absRefs === 0) {
+    checkPass('文件引用使用相对路径');
+  } else {
+    checkFail(`发现 ${absRefs} 个绝对路径引用，应使用相对路径`);
+  }
+
+  // ─── 5. 总结 ───
+  console.log('');
+  console.log('=== 校验总结 ===');
+  console.log(`  ✅ 通过: ${PASS}`);
+  console.log(`  ❌ 失败: ${FAIL}`);
+  console.log(`  ⚠️  警告: ${WARNINGS}`);
+  console.log('');
+
+  if (FAIL === 0) {
+    console.log('ALL CHECKS PASSED');
+    process.exit(0);
+  } else {
+    console.log(`VALIDATION FAILED: ${FAIL} 个必须修复的问题`);
+    process.exit(1);
+  }
+}
+
+main();

package/vendor/Server/Skills/flutter-interface/README.md

@@ -0,0 +1,75 @@
+# Flutter Interface Analyzer
+
+一个符合 [Agent Skills](https://agentskills.io) 规范的 skill，用于分析 Flutter 三方库的对外接口能力并生成标准化文档。
+
+## 功能特性
+
+- 基于脚本自动提取 Dart 源码接口（`flutter-extract-interfaces.cjs`）
+- 自动渲染接口规格说明书 Markdown 文档（`flutter-render-spec-doc.cjs`）
+- 支持 Git 仓库克隆（含 Sparse Checkout 稀疏检出）
+- 支持 monorepo 多子包结构和 export 链追踪
+- 自动过滤私有成员（`_` 前缀）和 export hide/show
+- 提取 `///` 文档注释作为功能描述
+- 输出 JSON 中间件，可供下游覆盖率分析复用
+
+## 目录结构
+
+```
+flutter-interface/
+├── SKILL.md                          # Skill 主文件（工作流指令）
+├── README.md                         # 本文件
+└── references/
+    ├── GIT_CLONE_GUIDE.md            # Git Clone 操作指南
+    ├── SCRIPT_REFERENCE.md           # 脚本参数与故障排查
+    ├── EXAMPLES.md                   # 分析示例
+    └── TEMPLATE.md                   # 文档输出模板
+```
+
+> 脚本不保存在本 SKILL 内，统一位于仓库的 `MCP/scripts/` 目录（`flutter-extract-interfaces.cjs`、`flutter-render-spec-doc.cjs`），通过相对路径 `{{skillDir}}/../../../MCP/scripts/` 引用。
+
+## 快速开始
+
+### 脚本驱动分析（推荐）
+
+```bash
+# 1. 提取接口到 JSON
+node "{{skillDir}}/../../../MCP/scripts/flutter-extract-interfaces.cjs" --repoDir /path/to/flutter_lib --output spec.json
+
+# 2. 渲染为 Markdown 文档
+node "{{skillDir}}/../../../MCP/scripts/flutter-render-spec-doc.cjs" --spec spec.json --output 接口规格说明.md
+```
+
+### 一步到位
+
+```bash
+# 直接从源码生成文档（不保留 JSON 中间件）
+node "{{skillDir}}/../../../MCP/scripts/flutter-render-spec-doc.cjs" --libroot /path/to/flutter_lib --output 接口规格说明.md
+```
+
+### 从 Git 仓库分析
+
+按照 [SKILL.md](SKILL.md) 中的 Phase 1 执行 Git Clone，然后运行脚本提取接口。
+
+详细的 Git Clone 操作参见 [GIT_CLONE_GUIDE.md](references/GIT_CLONE_GUIDE.md)。
+
+## 核心脚本
+
+| 脚本 | 用途 | 输入 | 输出 |
+|------|------|------|------|
+| `flutter-extract-interfaces.cjs` | 从 Dart 源码提取接口 | 库源码目录 | interface-spec.json |
+| `flutter-render-spec-doc.cjs` | 渲染接口文档 | JSON 或源码目录 | Markdown 文档 |
+
+> 脚本位于仓库的 `MCP/scripts/` 目录（本 SKILL 不保存副本），通过相对路径 `{{skillDir}}/../../../MCP/scripts/` 引用。
+
+脚本详细参数和故障排查参见 [SCRIPT_REFERENCE.md](references/SCRIPT_REFERENCE.md)。
+
+## 分析原则
+
+- **脚本优先**：接口提取由脚本自动完成，AI 不手动逐文件读取源码
+- **只分析公开接口**：脚本自动过滤 `_` 前缀私有成员和 export hide/show
+- **忠实于源码**：所有接口信息来自脚本解析实际源码，不允许推断或捏造
+- **JSON 中间件复用**：`interface-spec.json` 可供下游覆盖率分析复用
+
+## 支持的语言
+
+- **Dart/Flutter**（完整支持，基于 `flutter-extract-interfaces.cjs` 正则解析引擎）