@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/Skills/rnoh-lib-version-diff/scripts/package.json

@@ -0,0 +1,5 @@
+{
+  "type": "commonjs",
+  "private": true,
+  "comment": "Override parent package.json type:module to allow CommonJS require() in .js scripts"
+}

package/vendor/Server/Skills/rnoh-lib-version-diff/templates/report-template.md

@@ -0,0 +1,137 @@
+# 三方库版本分析报告：{repo-name}
+
+**生成日期：** {YYYY-MM-DD}
+**鸿蒙化仓库：** {owner}/{repo}
+**上游 npm 包名：** {package-name}
+
+---
+
+## 基本信息
+
+| 项目 | 值 |
+|------|-----|
+| 鸿蒙化仓库 | {owner}/{repo} |
+| 上游仓库 | {upstream-url} |
+| 上游 npm 包名 | {package-name} |
+| 当前 RNOH 版本 | {当前分支版本，如 0.77} |
+| 目标 RNOH 版本 | {目标版本，如 0.84} |
+| 升级类型 | 类型 A（上游版本升级 + 框架适配） / 类型 B（纯框架适配） |
+| 库类型 libraryType | {native-harmony / js-only-harmony / pure-js} |
+
+---
+
+## 版本差距
+
+| 项目 | 值 |
+|------|-----|
+| 鸿蒙化基线版本 | v{version} |
+| npm 最新版本 | v{version} |
+| 版本状态 | {落后 N 个小版本 / ✅ 最新 / 超前} |
+| 最近版本列表 | {v1}, {v2}, {v3}, ... |
+
+---
+
+## 差异概览（仅类型 A）
+
+- 变更文件数：{N} 个
+- 新增文件：{N} 个
+- 删除文件：{N} 个
+- 修改文件：{N} 个
+- 净增行数：+{N} / -{N}
+
+### 变更摘要（按模块分类）
+
+| 模块 | 变更说明 | 影响程度 | 文件数 |
+|------|----------|----------|--------|
+| JS/TS 公共 API | {说明} | 高/中/低 | {n} |
+| TurboModule Spec | {说明} | 高/中/低 | {n} |
+| Android 原生 | {说明} | 高/中/低 | {n} |
+| iOS 原生 | {说明} | 高/中/低 | {n} |
+| 构建/依赖 | {说明} | 高/中/低 | {n} |
+| 文档/测试/CI | {说明} | 高/中/低 | {n} |
+
+---
+
+## 升级风险评估
+
+| 风险等级 | 判定依据 |
+|----------|----------|
+| 🟢 低风险 | 仅补丁版本差距，无 breaking change |
+| 🟡 中风险 | 小版本差距，有 API 变更但向后兼容 |
+| 🔴 高风险 | 大版本差距，有 breaking change 或原生层重构 |
+
+**当前评估：** {风险等级} — {判定依据说明}
+
+---
+
+## 鸿蒙 API 核查（涉及原生能力时必填）
+
+> 凡涉及原生能力的需适配项，须使用 `devecocli docs search` 完成核查后再写结论。
+> 纯 JS 库标注「不适用 API 核查」并跳过下表。流程见 [references/OHOS_API_LOOKUP.md](../references/OHOS_API_LOOKUP.md)。
+
+| 上游能力 | 上游实现摘要 | 鸿蒙 Kit/API | 能力对比 | 约束与风险 | 可行性 | 建议动作 | 核查状态 |
+|----------|--------------|-------------|----------|------------|--------|----------|----------|
+| {capability} | {android_ios_summary} | {kit + api + 搜索关键词} | 一致/子集/无对等 | {docs_constraints} | ✅/⚠️/🔶/❌ | {harmony_files_strategy} | 分析中/已完成 |
+
+---
+
+## 鸿蒙化适配分析
+
+> 判断规则见 [references/OHOS_ADAPTATION.md](../references/OHOS_ADAPTATION.md)。
+
+### 需适配项
+
+| 序号 | 上游变更 | 鸿蒙侧动作 | 优先级 | 适配依据 |
+|------|----------|------------|--------|----------|
+| 1 | {upstream_change} | {ohos_action} | 高/中/低 | {引用 API 核查表行号} |
+
+### 无需适配项
+
+- {no_adapt_item_1}
+
+### RNOH 框架版本变化（类型 B 或跨版本升级时填写）
+
+| 项目 | 当前版本 | 目标版本 |
+|------|----------|----------|
+| react-native | ... | ... |
+| react | ... | ... |
+| @react-native-oh/react-native-harmony | ... | ... |
+| CLI | ... | ... |
+
+### 需关注的适配点
+
+（列出 ETS 业务代码、Package 注册代码、C++ 层依赖的 RNOH API，
+以及 generated/ 代码需重新 codegen 的说明）
+
+---
+
+## 差异文件位置（仅类型 A）
+
+> 工作目录：`{output-dir}`
+
+| 文件 | 完整路径 | 说明 |
+|------|----------|------|
+| 源码目录 (基线) | `{output-dir}/{b1}/` | 基线版本源码导出 |
+| 源码目录 (目标) | `{output-dir}/{b2}/` | 目标版本源码导出 |
+| diff patch | `{output-dir}/diff_{b1}_{b2}.patch` | JS/TS 核心文件变更补丁 |
+| 变更摘要 | `{output-dir}/summary_{b1}_{b2}.md` | 按文件统计增删行数 |
+| 接口差异检查清单 | `{output-dir}/api-diff_{b1}_{b2}.md` | TurboModule Spec 差异 |
+| 适配分析报告 | `{output-dir}/structure_{b1}_{b2}.md` | 接口驱动的适配分析 |
+
+---
+
+## 升级步骤建议
+
+1. 从当前分支创建新的目标分支
+2. {类型 A：应用上游 diff patch 合并 JS 变更 / 类型 B：跳过}
+3. 更新 package.json / oh-package.json5 中的 RNOH 依赖版本
+4. 使用目标版本 CLI 重新执行 codegen
+5. 验证 RNOH API 兼容性（ETS/C++ 层）
+6. {类型 A：适配鸿蒙原生层变更 / 类型 B：跳过}
+7. 编译构建验证 + 功能测试
+
+---
+
+## 下一步建议
+
+→ 使用 code-adapt skill 进行代码适配与编译验证

package/vendor/Server/Skills/rnoh-lib-xts-coverage/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: rnoh-lib-xts-coverage
+description: 分析 RN 鸿蒙三方库现有测试用例对接口的覆盖情况。通过 rn-analyze-test-coverage.cjs 脚本一步完成接口提取、测试覆盖率匹配和 Markdown 报告生成。当需要对 RN 鸿蒙三方库的测试用例进行接口覆盖率分析时调用。
+license: Apache-2.0
+compatibility: 需要 Node.js 运行环境
+metadata:
+  version: "1.1.0"
+  category: rn-testing
+  language: JavaScript/TypeScript
+  useWhen: 分析 RN 鸿蒙三方库测试用例对接口的覆盖情况
+  consumed-by: rnohLibTestAlignSkill
+---
+
+# RN 鸿蒙三方库测试用例接口覆盖率分析
+
+通过 `rn-analyze-test-coverage.cjs` 脚本一步完成接口提取、测试覆盖率匹配和 Markdown 报告生成，无需中间文件。
+
+> ⚠️ **核心约束**：基于静态 import 和接口调用分析，动态调用（`obj[methodName]()`）无法识别。
+
+---
+
+## 脚本依赖
+
+本 Skill 直接调用以下本地脚本完成全部分析工作：
+
+```
+3rdLibraryLoop/MCP/scripts/rn-analyze-test-coverage.cjs
+```
+
+**调用方式**：通过 `node` 命令行直接执行，使用 `--` 参数传参。
+
+---
+
+## 任务参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `libroot` | string | ✅* | 库根目录路径（RN 三方库的鸿蒙化仓库目录，包含 `package.json`） |
+| `spec` | string | ✅* | 已有的 interface-spec.json 路径（与 `libroot` 二选一） |
+| `output` | string | ❌ | 输出 Markdown 报告路径，默认 `03-{库名}-Test覆盖率报告.md` |
+| `title` | string | ❌ | 报告标题 |
+| `mode` | string | ❌ | 匹配模式: `auto`(默认) \| `ast` \| `regex` |
+| `version` | string | ❌ | 上游 npm 版本号（如 `4.7.3`），未指定时自动从 dependencies/README 推断；⚠️ 勿用库自身 `package.json.version`（RNOH 库 version 常为团队自编版本号，非上游版本） |
+| `src` | string | ❌ | 测试源码目录覆盖，默认自动检测 |
+| `local-spec` | boolean | ❌ | 启用本地 `src/` 作为接口规格来源（默认从上游 npm 提取），用于 RNOH 扩展型库避免本地独有 API 盲区 |
+
+> `libroot` 与 `spec` 至少提供一个。提供 `spec` 时跳过接口提取步骤直接使用；仅提供 `libroot` 时脚本自动从源码提取接口（必要时拉取上游 npm 源码）。
+
+**派生变量**：
+- `skillDir`：本 Skill 所在目录
+- `scriptPath`：分析脚本路径 = `{{skillDir}}/../../../MCP/scripts/rn-analyze-test-coverage.cjs`
+
+---
+
+## 执行命令
+
+```bash
+node "{{skillDir}}/../../../MCP/scripts/rn-analyze-test-coverage.cjs" \
+  --libroot "{{libroot}}" \
+  [--output "{{output}}"] [--title "{{title}}"] [--mode auto|ast|regex] [--version "{{上游版本}}"] [--src "{{测试源码目录}}"] [--local-spec]
+```
+
+或从已有 interface-spec.json 生成：
+
+```bash
+node "{{skillDir}}/../../../MCP/scripts/rn-analyze-test-coverage.cjs" \
+  --spec "{{spec}}" --libroot "{{libroot}}" [--output "{{output}}"]
+```
+
+其中：
+- `{{skillDir}}` = SKILL.md 所在目录
+- `{{libroot}}` = RN 三方库的鸿蒙化仓库根目录
+- `{{workspaceRoot}}` = `3rdLibraryLoop` 工作区根目录
+
+---
+
+## 脚本自动完成
+
+1. 获取接口规格（从 `--spec` 指定的 JSON 读取，或从 `libroot` 源码自动提取，必要时拉取上游 npm 源码 `index.js`/`index.d.ts` 及本地 TurboModule Spec `Native*.ts`）
+2. 自动检测测试源码目录（按优先级查找）：
+   - `example/src/test`、`example/src/tests`、`example/__tests__`
+   - `example/src/`（递归）、`example/src/*/`（RN3rdTemplate RNTesterList 模式 A：`example/src/<LibName>/`）
+   - `demo/__tests__`、`demo/src/test`、`demo/src/tests`
+   - `__tests__`、`test`、`tests`
+3. 递归扫描测试源码目录下所有 `.ts`、`.tsx`、`.js`、`.jsx`、`.ets` 文件（排除 `node_modules`、`harmony`、`android`、`ios`、`__mocks__`）
+4. 提取 `import { ... } from 'lib'` 语句（ES Module 默认/命名/别名/混合导入、CommonJS require、side-effect import）
+5. AST/正则双层匹配：静态方法、实例方法（追踪变量声明与类型）、链式调用、对象字面量属性、默认导入命名空间宽松兜底
+6. 直接渲染输出 Markdown 覆盖率报告
+
+---
+
+## 库源码目录结构约定
+
+```
+{{libroot}}/
+  ├── package.json                     ← 库 package.json（依赖中含上游 npm 包名）
+  ├── src/                             ← JS 层导出源码
+  ├── harmony/                         ← 鸿蒙化原生代码（ArkTS/C++，扫描时排除）
+  ├── __tests__/                       ← 测试源码（自动检测目录之一）
+  └── example/
+      ├── __tests__/                   ← 测试源码（自动检测目录之一）
+      ├── src/test/                    ← 测试源码（自动检测目录之一）
+      └── ...
+```
+
+> 脚本自动检测测试目录，无需手动指定 `--src`；如自动检测失败或多目录共存，可用 `--src` 显式指定。
+> ⚠️ 使用 `rn-lib-add-example`（RN3rdTemplate 模板）创建的 example 工程，其 demo 位于 `example/src/<LibName>/`，需显式 `--src example/src`（或 `--src example/src/<LibName>`）。
+
+---
+
+## 输入依赖
+
+- **前置SKILL**: rnoh-lib-code-adapt（可选；测试源码通常来自 rnoh-lib-test-align 的移植产物）
+- **输入文件**: 库源码目录（含 `package.json` 和测试源码目录）
+- **输出文件**: Markdown 覆盖率报告（脚本直接生成）
+
+---
+
+## 输出
+
+生成 Markdown 报告，包含以下章节：
+- **基本信息**：库名、源文件数、生成时间
+- **覆盖率总览**：方法级覆盖率百分比、S/N/M 统计、进度条
+- **按接口类型统计**：method/constructor/property/field/enumValue/function/variable/type 分类别覆盖率
+- **类级覆盖率**：按类分组的覆盖明细（按覆盖率升序排列）
+- **未覆盖接口详情**：按类分组的未覆盖接口清单（含参数、返回类型、说明）
+- **已覆盖接口详情**：按类分组的已覆盖接口清单（含签名和覆盖来源文件）
+- **文件覆盖详情**：每个测试文件覆盖的接口数和接口列表
+- **覆盖率提升建议**：按优先级排列的未覆盖接口补充清单
+
+> 当未找到测试源文件时，报告会标注「无测试文档声明」并列出所有接口为未覆盖。
+
+---
+
+## 注意事项
+
+1. **确定性**：所有计数和匹配由脚本完成，同一组输入必定产生相同输出
+2. **子目录排除**：自动排除 `node_modules`、`harmony`、`android`、`ios`、`__mocks__` 等目录
+3. **构造函数和枚举**：已在接口提取阶段排除
+4. **动态调用限制**：`obj[methodName]()` 无法识别；**命令式组件**（`forwardRef` + `useImperativeHandle` + `ref.current.method()`）的 ref 调用同样无法被 AST 归因，覆盖率会被低估。对这类库应更看重 field/props 层与 Hook 层指标，方法层覆盖率仅供参考
+5. **模式选择**：`auto` 优先 AST 匹配（需 TypeScript 模块），失败时降级正则；`ast` 强制 AST；`regex` 强制正则
+6. **版本推断**：未传 `--version` 时，脚本从 `package.json` 的 `dependencies` 或 README 自动推断上游 npm 版本号
+   > ⚠️ **版本核对**：RNOH 库的 `package.json.version` 常为团队自编版本号（非上游 npm 版本），勿直接用作 `--version`。执行前应先 `npm view <上游包名> versions --json` 核对真实可用版本，选择与本地 `src/` API 风格匹配的主版本线（看标志性导出符号，如 v4 的 `useCameraDevice`/`takePhoto` vs v5 的 `useCamera`/`CameraController`）。
+   > ⚠️ **降级风险**：若指定 `--version` 在 npm 不存在而脚本自动降级到 `latest`，且 `latest` 主版本号与指定版本不同（跨 major），可能导致拉取到重构后完全不兼容的 API 面（如 vision-camera 4.x→5.x）。务必核对降级后的 API 一致性，必要时显式指定同主版本最大号。
+7. **本地扩展 API 盲区**：接口规格默认取自上游 npm，本地 RNOH 扩展 API（未出现在上游导出中）不计入分母，覆盖率被轻微高估且扩展 API 不会出现在未覆盖清单中。使用 `--local-spec` 以本地 `src/index.tsx` 导出为规格来源可缓解此盲区。

package/vendor/Server/Skills/skill-generator/SKILL.md

@@ -0,0 +1,365 @@
+---
+name: skill-generator
+description: 按照Agent Skills规范生成高质量的SKILL，自动调用MCP脚本与鸿蒙知识库补充能力，生成渐进式披露结构（SKILL.md+references+assets+scripts）。当需要创建新SKILL、规范化已有SKILL、或为某个重复性任务封装可复用技能时使用。
+license: Apache-2.0
+compatibility: 需要MCP Gateway运行中（脚本工具+知识库工具），需要文件写入权限到Server/Skills目录
+metadata:
+  author: LoopEngine
+  version: "1.0.0"
+  category: meta-skill
+---
+
+# Skill Generator — SKILL 生成器
+
+本技能用于**按规范生成新SKILL**。它不是一个简单的模板填充器，而是一个结构化生成流程：
+理解需求 → 检索MCP能力 → 查询知识库 → 编写SKILL.md → 拆分references。
+
+> ⚠️ **核心原则：生成的每个SKILL必须同时满足规范合规、渐进式披露、MCP能力复用三条底线。**
+
+---
+
+## 任务参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `skillName` | string | ✅ | SKILL名称（kebab-case，如 `arkts-api-audit`） |
+| `skillPurpose` | string | ✅ | SKILL要解决什么问题（自然语言描述） |
+| `outputDir` | string | ✅ | 输出目录绝对路径（通常为 `Server/Skills/{skillName}`） |
+| `domainContext` | string | ❌ | 领域上下文（如"鸿蒙ArkTS三方库"），用于知识库检索 |
+| `existingSkillPath` | string | ❌ | 已有SKILL路径（规范化场景），不提供则全新生成 |
+
+---
+
+## 输入依赖
+
+无前置SKILL。可作为独立任务调用。
+
+---
+
+## 工作流程概览
+
+```
+Phase 1: 需求理解与规范校验
+    ↓
+Phase 2: MCP能力检索（脚本工具 + 知识库）
+    ↓
+Phase 3: 鸿蒙知识库查询（当通用知识不够具体时）
+    ↓
+Phase 4: SKILL结构设计与SKILL.md编写
+    ↓
+Phase 5: references/assets/scripts 拆分（渐进式披露）
+    ↓
+Phase 6: 规范合规性自检
+    ↓
+Phase 7: 最终输出
+```
+
+---
+
+## Phase 1：需求理解与规范校验
+
+### 1.1 解析SKILL名称
+
+验证 `skillName` 是否满足 [Agent Skills规范](https://agentskills.io/specification)：
+
+| 规则 | 校验 |
+|------|------|
+| 长度 | 1-64 字符 |
+| 字符集 | 仅小写字母 `a-z`、数字 `0-9`、连字符 `-` |
+| 首尾 | 不能以 `-` 开头或结尾 |
+| 连续 | 不能有连续 `--` |
+| 目录匹配 | name 必须等于父目录名 |
+
+> 名称不合规时，**必须先修正再继续**，不允许跳过。
+
+### 1.2 理解SKILL目标
+
+从 `skillPurpose` 提取：
+- **核心任务**：SKILL做什么
+- **触发场景**：什么时候用（写入 description 的"when to use"部分）
+- **输入产出**：接收什么、输出什么
+- **领域关键词**：用于Phase 2/3的检索词
+
+### 1.3 读取已有SKILL（规范化场景）
+
+如果提供了 `existingSkillPath`，读取现有 `SKILL.md`，分析：
+- frontmatter 是否合规
+- body 是否过长（>500行需拆分）
+- 是否缺少 references/scripts 辅助文件
+- 渐进式披露是否到位
+
+> 规范化场景下，Phase 4 的工作变为"重构"而非"从零编写"。
+
+---
+
+## Phase 2：MCP能力检索
+
+> **目标：检查MCP Gateway中是否有可复用的脚本工具或下游工具，避免SKILL中重复造轮子。**
+
+### 2.1 检索脚本工具
+
+MCP Gateway 的 `scripts/` 目录下每个脚本都自动注册为工具（前缀 `script_`）。
+调用 `gateway_list_tools` 工具获取完整工具列表，筛选 `source: script` 的工具。
+
+**现有脚本工具示例**：
+| 工具名 | 脚本 | 能力 |
+|--------|------|------|
+| `script_rn_scan_exports` | rn-scan-exports.cjs | 扫描RN三方库导出接口/TurboModule Spec |
+| `script_rn_extract_interfaces` | rn-extract-interfaces.cjs | 提取RN三方库接口信息 |
+
+### 2.2 检索下游MCP工具
+
+MCP Gateway 聚合了下游 Server（工具名前缀为 `{serverName}_`）：
+
+| 前缀 | 来源 | 典型工具 |
+|------|------|----------|
+| `kb-server_` | 鸿蒙知识库 | 知识检索、文档查询 |
+| `gitcode_` | GitCode MCP | 仓库操作、PR管理、代码搜索 |
+
+### 2.3 匹配与引用
+
+将SKILL需求与检索到的工具匹配：
+
+- **匹配到脚本工具** → 在SKILL的对应Phase中引用 `script_{工具名}`，说明调用方式和参数
+- **匹配到下游工具** → 在SKILL中引用 `{serverName}_{工具名}`，说明用途
+- **未匹配到** → 记录为"能力缺口"，考虑在 Phase 5 中创建新脚本补充
+
+> 详细检索方法参见 [MCP能力检索指南](references/MCP_TOOL_DISCOVERY.md)
+
+---
+
+## Phase 3：鸿蒙知识库查询
+
+> **触发条件：当 `domainContext` 涉及鸿蒙/OpenHarmony/ArkTS，且大模型通用知识不够贴合具体场景时。**
+
+### 3.1 构建检索查询
+
+从 Phase 1.2 提取的领域关键词 + `domainContext` 组合检索词。
+
+示例：
+- domainContext = "鸿蒙ArkTS三方库内存泄漏检测"
+- 检索词 = `["ArkTS 内存泄漏", "OpenHarmony 内存检测", "ArkTS 生命周期泄漏"]`
+
+### 3.2 调用知识库工具
+
+调用 `kb-server_` 前缀的知识检索工具（具体工具名通过 Phase 2.2 获取）。
+
+**调用要点**：
+- 一次查询一个关键词，避免长查询导致召回率下降
+- 对返回结果提取：知识点、最佳实践、注意事项、代码示例
+- 若返回结果不相关，调整关键词重试（最多3轮）
+
+### 3.3 知识融合
+
+将知识库返回的内容与SKILL设计融合：
+- **检查清单** → 补充到 references 的检查项中
+- **代码示例** → 补充到 assets 的模板中
+- **注意事项** → 补充到 SKILL.md body 的对应Phase中（简洁引用，不照搬全文）
+
+> 知识库查询的详细操作参见 [知识库查询指南](references/KB_QUERY_GUIDE.md)
+
+---
+
+## Phase 4：SKILL结构设计与SKILL.md编写
+
+### 4.1 目录结构设计
+
+按照规范设计目录：
+
+```
+{skillName}/
+├── SKILL.md              # 必需：元数据 + 指令
+├── references/           # 可选：详细参考文档
+│   ├── REFERENCE.md      # 技术参考
+│   └── {domain}.md       # 领域特定文档
+├── assets/               # 可选：模板、资源
+│   └── {template}.md     # 输出模板
+└── scripts/              # 可选：可执行脚本
+    └── {helper}.cjs      # 辅助脚本（Node.js，跨平台）
+```
+
+> ⚠️ **脚本语言要求：必须使用跨平台脚本语言（Node.js `.cjs` 或 Python `.py`），禁止使用 Bash `.sh`**，确保在 Windows 和 macOS 上均可直接运行。
+
+### 4.2 编写 frontmatter
+
+```yaml
+---
+name: {skillName}
+description: {做什么}. Use when {什么时候用}. {关键词}.
+license: Apache-2.0
+compatibility: {环境要求}
+metadata:
+  author: {作者}
+  version: "1.0.0"
+---
+```
+
+**description 编写要点**：
+- ≤1024 字符
+- 必须包含"做什么"+"什么时候用"
+- 包含领域关键词，便于Agent匹配
+
+### 4.3 编写 body
+
+**body 结构模板**：
+
+```markdown
+# {Skill标题}
+
+{一句话定位}
+
+> ⚠️ **核心原则：{本SKILL的关键约束}**
+
+---
+
+## 任务参数
+
+| 参数 | 必需 | 说明 |
+|------|------|------|
+| ... | ✅ | ... |
+
+---
+
+## 输入依赖
+
+- 前置SKILL: {或"无"}
+- 输入文件: {或"无"}
+
+---
+
+## 工作流程概览
+
+Phase 1 → Phase 2 → ... → Phase N
+
+---
+
+## Phase 1：{阶段名}
+
+### 1.1 {步骤}
+{详细指令，引用references时用相对路径链接}
+
+> 详细步骤参见 [参考文档](references/REFERENCE.md)
+
+---
+
+## Phase N：{最终阶段}
+{输出产物说明}
+```
+
+**body 长度约束**：
+- 推荐 < 500 行
+- 推荐 < 5000 tokens
+- 超过时**必须**将详细内容拆分到 references/
+
+> 完整编写规范参见 [SKILL编写规范](references/SKILL_SPEC.md)
+
+---
+
+## Phase 5：渐进式披露拆分
+
+> **目标：确保SKILL.md保持精炼，详细内容按需加载。**
+
+### 5.1 拆分原则
+
+| 内容类型 | 放置位置 | 加载时机 |
+|----------|----------|----------|
+| 核心流程步骤 | SKILL.md body | SKILL激活时 |
+| 详细检查清单 | references/ | 按需读取 |
+| 完整代码模板 | assets/ | 按需读取 |
+| 可执行辅助逻辑 | scripts/ | 按需执行 |
+| 领域知识参考 | references/ | 按需读取 |
+
+### 5.2 文件引用规范
+
+- 使用**相对路径**（从SKILL根目录起）
+- 保持**一层深度**：`references/REF.md` ✅，`references/a/b/REF.md` ❌
+- 引用格式：`参见 [参考文档](references/REFERENCE.md)`
+
+### 5.3 补充脚本（能力缺口填补）
+
+如果 Phase 2.3 识别到能力缺口，在此创建新脚本：
+
+**脚本语言必须跨平台**（Windows/macOS/Linux 均可运行）：
+- ✅ **Node.js（`.cjs`）**：首选，与项目 MCP scripts 惯例一致
+- ✅ **Python（`.py`）**：次选，需 Python 3 环境
+- ❌ **Bash（`.sh`）**：禁止，Windows 无原生支持
+
+脚本头部注释约定：
+```javascript
+#!/usr/bin/env node
+/**
+ * @tool {工具名}
+ * @description {描述}
+ * @param {参数名}: {类型} - {说明}
+ */
+```
+
+脚本放入 SKILL 的 `scripts/` 目录，并在 SKILL.md 中说明调用方式。
+若脚本需要注册到 MCP Gateway，复制到 `MCP/scripts/` 目录。
+
+---
+
+## Phase 6：规范合规性自检
+
+生成完成后，执行合规性检查：
+
+### 6.1 frontmatter 检查
+
+| 检查项 | 规则 |
+|--------|------|
+| `name` | ✅ 合规字符集、长度、匹配目录名 |
+| `description` | ✅ ≤1024字符、含"做什么"+"何时用" |
+| `license` | ✅ 存在 |
+| `metadata` | ✅ 含 author、version |
+
+### 6.2 结构检查
+
+| 检查项 | 规则 |
+|--------|------|
+| SKILL.md 存在 | ✅ |
+| body < 500行 | ✅（超过则拆分） |
+| references 一层深度 | ✅ |
+| 文件引用用相对路径 | ✅ |
+
+### 6.3 内容检查
+
+| 检查项 | 规则 |
+|--------|------|
+| 有任务参数表 | ✅ |
+| 有工作流程概览 | ✅ |
+| MCP工具引用正确 | ✅（工具名前缀正确） |
+| 知识库内容已融合 | ✅（如适用） |
+
+> 完整检查清单参见 [合规检查清单](references/COMPLIANCE_CHECKLIST.md)
+
+可运行校验脚本进行自动化检查（跨平台，仅需 Node.js）：
+
+```bash
+node {outputDir}/scripts/validate-skill.cjs {outputDir}
+```
+
+---
+
+## Phase 7：最终输出
+
+确认输出目录包含所有文件：
+
+```
+{outputDir}/
+├── SKILL.md                    # ✅ 主文件
+├── references/                 # ✅ 参考文档（至少1个）
+│   ├── SKILL_SPEC.md
+│   ├── MCP_TOOL_DISCOVERY.md
+│   ├── KB_QUERY_GUIDE.md
+│   └── COMPLIANCE_CHECKLIST.md
+├── assets/                     # ✅ 模板资源
+│   └── SKILL_TEMPLATE.md
+└── scripts/                    # ✅ 校验脚本（Node.js，跨平台）
+    └── validate-skill.cjs
+```
+
+输出完成确认信息，包含：
+- 生成的文件列表
+- frontmatter 摘要（name、description）
+- 引用的MCP工具列表
+- 融合的知识库要点