@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/Skills/rn-library-interface-analyzer/assets/REPORT_TEMPLATE.md

@@ -0,0 +1,148 @@
+# 接口规格说明文档模板
+
+本模板定义 RNLibraryInterfaceAnalyzer 最终输出的 `接口规格说明.md` 文档结构。
+
+> 脚本 `rn-render-spec-doc.cjs` 生成基础接口规格部分（第 1~4 节），AI 在此基础上补充第 5 节（鸿蒙化接口差异）。
+
+---
+
+## 文档结构
+
+```markdown
+# {libraryName} 接口规格说明
+
+## 1. 概述
+- 上游原库地址：{upstreamRepoUrl}
+- 鸿蒙化仓库地址：{ohosRepoUrl}
+- 库功能描述：（从 README 提取）
+
+## 2. 入口文件与分析范围
+
+**上游原库入口文件：** `index.js`（或实际路径，由脚本自动检测）
+
+**分析涉及的源文件：**
+- `src/index.ts`
+- `android/src/main/java/.../MyModule.java`
+- `ios/MyModule.m`
+- ...（脚本输出的 sources 列表）
+
+**鸿蒙化仓库入口文件：** `Index.ets`（或实际路径）
+
+## 3. JS/TS 层导出接口
+
+> 以下由 `rn-render-spec-doc.cjs` 自动生成，按类/模块分组
+
+### 3.1 类 (Classes)
+
+#### ClassName
+
+| 序号 | 类名/成员 | 方法/属性 | 功能描述 |
+|------|-----------|-----------|----------|
+| 1    | ClassName | constructor(param1: type1) | 构造函数 |
+| 2    |           | methodName(param: type): returnType | 方法描述 |
+| 3    |           | static staticMethod(): returnType | 静态方法 |
+| 4    |           | propertyName: type | 公开属性 |
+
+### 3.2 接口/类型 (Interfaces/Types)
+
+#### InterfaceName
+
+| 序号 | 字段名 | 类型 | 必填 | 描述 |
+|------|--------|------|------|------|
+| 1    | field1 | string | 是 | 字段描述 |
+| 2    | field2? | number | 否 | 可选字段 |
+
+### 3.3 枚举 (Enums)
+
+#### EnumName
+
+| 序号 | 成员名 | 值 | 描述 |
+|------|--------|-----|------|
+| 1    | MEMBER_A | 'A' | 描述 |
+
+### 3.4 函数 (Functions)
+
+| 序号 | 函数名 | 参数 | 返回值 | 描述 |
+|------|--------|------|--------|------|
+| 1    | funcName | (param: type) | returnType | 函数描述 |
+
+### 3.5 变量/常量 (Variables)
+
+| 序号 | 变量名 | 类型 | 描述 |
+|------|--------|------|------|
+| 1    | CONST_NAME | type | 常量描述 |
+
+### 3.6 TurboModule Spec
+
+> 如果库使用 TurboModule 架构，脚本会自动提取 Native*.ts 中的 Spec 接口
+
+#### ModuleName
+
+| 序号 | 方法名 | 参数 | 返回值 | 事件 | 说明 |
+|------|--------|------|--------|------|------|
+| 1    | nativeMethod | (param: type) | Promise<void> | 否 | 方法描述 |
+
+## 4. 原生模块导出接口（AI 补充）
+
+> 脚本仅提取 JS/TS 层和 TurboModule Spec。如果库包含旧式原生模块（iOS RCT_EXPORT_MODULE / Android ReactPackage），AI 需手动补充此节。
+
+### 4.1 iOS 原生模块
+
+#### ModuleName
+
+| 序号 | 方法名 | 参数 | 返回值 | 描述 |
+|------|--------|------|--------|------|
+| 1    | nativeMethod | (param: type) | Promise<void> | 方法描述 |
+
+### 4.2 Android 原生模块（与 iOS 差异）
+
+> 以下仅列出与 iOS 端差异的接口
+
+| 序号 | 方法名 | iOS 签名 | Android 签名 | 差异说明 |
+|------|--------|----------|--------------|----------|
+| 1    | methodName | (param: String) | (param: String, extra: String) | Android 端多一个参数 |
+
+## 5. 鸿蒙化接口差异（AI 补充）
+
+> 鸿蒙化库接口默认与原库一致，以下仅列出差异项
+>
+> **文档来源说明**：{说明文档来源}
+
+### 5.1 缺失接口 ❌
+
+| 序号 | 接口名 | 原库位置 | 文档是否标注 | 说明 |
+|------|--------|----------|--------------|------|
+| 1    | methodName | ClassName.methodName | ✅ 已标注 | 鸿蒙化版本未实现，文档标注为 No |
+
+### 5.2 新增接口 🆕
+
+| 序号 | 接口名 | 鸿蒙化位置 | 文档是否标注 | 说明 |
+|------|--------|------------|--------------|------|
+| 1    | ohosMethod | Index.ets | ✅ 已标注 | 鸿蒙平台特有 API |
+
+### 5.3 签名变更 ⚠️
+
+| 序号 | 接口名 | 原库签名 | 鸿蒙化签名 | 文档是否标注 | 变更说明 |
+|------|--------|----------|------------|--------------|----------|
+| 1    | methodName | (param: string): void | (param: number): void | ⚠️ 部分标注 | 参数类型变更 |
+
+> 💡 **文档是否标注列取值**：
+> - ✅ 已标注：文档已列出该接口，HarmonyOS Support 列为 `No`/`partially`
+> - ⚠️ 部分标注：文档列出接口但未说明差异
+> - ❌ 未标注：文档中完全未提及该接口
+> - — 不适用：该库无使用文档文件
+
+（若无差异，注明"鸿蒙化版本接口与上游原库完全一致"）
+```
+
+## 文档生成流程
+
+```
+rn-extract-interfaces.cjs → interface-spec.json
+                                      ↓
+rn-render-spec-doc.cjs  → 接口规格说明_基础.md（第 1~3 节）
+                                      ↓
+AI 补充第 4 节（原生模块，如需） + 第 5 节（鸿蒙化差异）
+                                      ↓
+                          接口规格说明.md（最终文档）
+```

package/vendor/Server/Skills/rn-library-interface-analyzer/references/DOC_ANNOTATION_GUIDE.md

@@ -0,0 +1,118 @@
+# 文档标注查询指南
+
+本文档详细说明如何对照鸿蒙 RN 三方库使用文档，标注差异接口的文档覆盖情况。
+
+## 文档来源确定
+
+**文档来源优先级**：
+
+1. **用户传入 `rndocUrl`**：若 `rndocUrl` 不为 null/空，使用该地址作为文档来源
+2. **鸿蒙化仓库 README.md**（默认回退）：若 `rndocUrl` 未提供，直接使用 `{ohosAnalysisRoot}/README.md`
+
+根据 `rndocUrl` 的输入类型，分别处理：
+
+| rndocUrl 输入类型 | 判断规则 | 处理方式 | 文档读取路径 |
+|----------|----------|----------|----------|
+| Git URL | 以 `http://`、`https://`、`git://`、`ssh://` 开头，或以 `.git` 结尾 | 克隆到 `{outputDir}/tmp/rndoc`，按 URL 格式解析规则提取分支/commit/子路径后 checkout | `{outputDir}/tmp/rndoc/{subpath}/` 下的 `.md` 文件 |
+| 本地路径 | 路径存在且非 Git URL | 直接读取目录文件 | `rndocUrl` 指向的目录下的 `.md` 文件 |
+| Web URL | 以 `http://` 或 `https://` 开头但非 Git 仓库地址（不含 `.git`、`/tree/`、`/blob/`） | 使用 web fetch 获取页面内容 | web fetch 返回的 Markdown 内容 |
+| 未提供（null/空） | — | 直接使用鸿蒙化仓库根目录 `README.md` | `{ohosAnalysisRoot}/README.md` |
+
+> ⚠️ 当 `rndocUrl` 为 Git URL 时，克隆必须存放到 `{outputDir}/tmp/rndoc`，禁止克隆到系统临时目录或其他外部路径。
+
+## 定位文档文件
+
+根据文档来源类型，在对应路径中查找匹配的 `.md` 文件：
+
+**rndocUrl 为 Git URL 或本地路径时**：
+
+- 优先精确匹配：`{libraryName}.md`（如 `react-native-touch-id` → `react-native-touch-id.md`）
+- 若未命中，尝试去除 `@scope/` 前缀后匹配
+- 若仍未命中，列出目录下所有 `.md` 文件，按名称相似度选取最接近的文件
+- 若无匹配的 `.md` 文件，列出目录下所有 `.md` 文件，选取最相关的（如 `README.md`）
+
+**rndocUrl 为 Web URL 时**：直接使用 web fetch 获取的内容作为文档。
+
+**rndocUrl 未提供时**：直接读取 `{ohosAnalysisRoot}/README.md`。
+
+**无文档可用**：若以上所有方式均无法获取到文档内容，则所有差异项的"文档是否标注"列统一填 `—`（无文档），并在差异表上方注明"该库暂无使用文档"，**跳过后续查询步骤**。
+
+## 文档结构说明（必读）
+
+文档的章节编号、标题用词、数量都因库而异，**不要假设固定结构**。所有判断都必须基于文档**实际内容**，而非预设的章节编号或关键词。
+
+**定位接口标注的唯一可靠依据**：表格中是否存在 **"HarmonyOS Support" 列**。凡是包含该列的表格，都是接口标注表；不含该列的表格（如纯说明性表格）不携带标注信息。
+
+- 文档中可能有一张或多张包含 "HarmonyOS Support" 列的表格（不同库的表格数量和划分方式不同，需逐张检查）。
+- 该列通常为表格最后一列，取值为（大小写不统一）：`yes` / `No` / `no` / `NO` / `partially`。
+- 接口章节开头通常有一段固定说明文字，解释上述取值含义：
+  > "HarmonyOS Support"列为 yes 表示 HarmonyOS 平台支持该属性；no 则表示不支持；partially 表示部分支持。
+- 除接口表格外，文档还可能包含"遗留问题"/"已知问题"类章节（通过 issue 链接补充提及某些接口的已知缺陷），编号和位置不固定，识别时同样以实际内容为准。
+
+> ⚠️ **关键**：文档通过 **"HarmonyOS Support" 列** 标注每个接口在鸿蒙平台的支持情况：
+> - `yes` —— 鸿蒙支持
+> - `No` / `no` / `NO` —— **鸿蒙不支持**（这就是对"缺失接口"的标注！）
+> - `partially` —— 部分支持（这就是对"签名变更/功能差异"的标注！）
+>
+> **该列的 `No` / `partially` 本身就是差异说明，等同于"已标注差异"，不要再去寻找额外的"不支持"文字描述。**
+
+> ⚠️ **无 "HarmonyOS Support" 列的文档处理**：若文档（如鸿蒙化仓库 README.md）中不包含 "HarmonyOS Support" 列表格，则无法通过表格列进行精确标注判定。此时应通读文档全文，检查文档是否以文字描述、已知问题列表、或其他形式提及差异接口。若文档以任意形式明确提及某接口的差异或不支持，记为 ⚠️ 部分标注；若完全未提及，记为 ❌ 未标注。
+
+## 查询步骤
+
+### 步骤 1：获取文档内容
+
+- **rndocUrl 为 Git URL**：克隆到 `{outputDir}/tmp/rndoc` 后读取本地文件
+- **rndocUrl 为本地路径**：直接读取本地文件
+- **rndocUrl 为 Web URL**：使用 web fetch 获取内容
+- **rndocUrl 未提供**：直接读取 `{ohosAnalysisRoot}/README.md`
+
+> ⚠️ **优先使用本地文件读取**，避免 web fetch。gitcode.com 等平台网页通常只渲染页面框架而不返回 Markdown 原文，web fetch 可靠性低。
+
+### 步骤 2：定位文档文件
+
+按上述规则定位具体的 `.md` 文件。若定位到多个相关文件，合并阅读所有文件内容。
+
+### 步骤 3：读取文档内容
+
+**通读全部内容**，定位所有包含 "HarmonyOS Support" 列的表格行（按列名定位，不依赖章节标题或编号）。逐行判断每行的 "HarmonyOS Support" 列取值。
+
+若文档不包含 "HarmonyOS Support" 列表格，则通读全文检查文字描述形式的差异标注。
+
+### 步骤 4：逐项核对标注
+
+**4a. 名称归一化匹配**
+
+文档中的接口名与源码提取的接口名格式可能不同，匹配前需归一化：
+- 方法名：文档写 `clearFormData()`，源码提取 `clearFormData` → 去除 `()` 后缀匹配
+- 可选属性：文档写 `saveFormDataDisabled?`，源码提取 `saveFormDataDisabled` → 去除 `?` 后缀匹配
+- 版本标记：文档写 `paymentRequestEnabled<sup>13.15.1+</sup>`，源码提取 `paymentRequestEnabled` → 去除 `<sup>...</sup>` 后匹配
+- 匹配方式：在文档全文中搜索归一化后的接口名（子串匹配即可）
+
+**4b. 判定规则**
+
+**有 "HarmonyOS Support" 列的文档**：
+
+| 差异类型 | HarmonyOS Support 列值 | 判定结果 |
+|----------|----------------------|----------|
+| 缺失接口 | `No` / `no` / `NO` | ✅ 已标注（文档明确标注不支持） |
+| 缺失接口 | `partially` | ⚠️ 部分标注（文档标注部分支持，但未说明完全缺失） |
+| 缺失接口 | `yes` | ⚠️ 部分标注（文档标注支持，与分析结论矛盾，可能文档过时） |
+| 新增接口 | 文档中提及且标注为 Harmony 特有 / `yes` | ✅ 已标注 |
+| 新增接口 | 文档中提及但未说明为 Harmony 特有 | ⚠️ 部分标注 |
+| 签名变更 | `partially` | ✅ 已标注（文档标注部分支持，通常对应签名/功能差异） |
+| 签名变更 | `yes` 且文档描述了鸿蒙侧行为差异 | ✅ 已标注 |
+| 签名变更 | `yes` 但未描述差异 | ⚠️ 部分标注 |
+| 任意类型 | 接口在文档中完全未出现 | ❌ 未标注 |
+
+**无 "HarmonyOS Support" 列的文档（如 README.md）**：
+
+| 差异类型 | 文档中是否提及 | 判定结果 |
+|----------|--------------|----------|
+| 任意类型 | 文档明确提及该接口在鸿蒙平台不支持/有差异 | ⚠️ 部分标注（文字描述不如表格列精确） |
+| 任意类型 | 文档提及该接口但未说明鸿蒙差异 | ⚠️ 部分标注 |
+| 任意类型 | 文档完全未提及该接口 | ❌ 未标注 |
+
+**额外检查**：若接口在接口表格中未找到，还需检查标题含「遗留问题」/「已知问题」的章节是否通过 issue 链接提及该接口。若遗留问题中提及，记为 ⚠️ 部分标注。
+
+> 💡 **示例**：`clearFormData` 是缺失接口，在文档「静态方法」章节的表格中找到行 `| clearFormData() | ... | function | No | Android | No |`，HarmonyOS Support 列为 `No` → 判定为 **✅ 已标注**。

package/vendor/Server/Skills/rn-library-interface-analyzer/references/SCRIPT_USAGE_GUIDE.md

@@ -0,0 +1,168 @@
+# 脚本使用指南
+
+本文档说明 `rn-extract-interfaces.cjs` 和 `rn-render-spec-doc.cjs` 两个脚本的使用方法。
+
+> 📌 两个脚本统一存放于 `3rdLibraryLoop/MCP/scripts/` 目录（SKILL 目录内不保存副本）。下文命令中的 `{mcpScriptsDir}` 指该目录，可从 SKILL 目录通过 `../../../MCP/scripts` 相对定位。
+
+## 脚本概览
+
+| 脚本 | 功能 | 输入 | 输出 |
+|------|------|------|------|
+| `rn-extract-interfaces.cjs` | 从 RN 三方库鸿蒙化仓库提取接口规格 | 库根目录路径 | JSON 接口规格文件 |
+| `rn-render-spec-doc.cjs` | 将接口规格渲染为 Markdown 文档 | JSON 规格文件或库根目录 | Markdown 文档 |
+
+## rn-extract-interfaces.cjs
+
+### 功能
+
+从 React Native 三方库的鸿蒙化仓库提取接口规格，自动完成以下工作：
+
+1. **拉取上游 npm 源码**：通过 `npm pack` 下载上游原库的已发布包（index.js / index.d.ts）
+2. **提取 TurboModule Spec**：从鸿蒙化仓库本地扫描 `Native*.ts` 文件，提取 TurboModule 接口定义
+3. **解析 JS 层导出**：自动检测导出模式（CommonJS / ES Module / Side-effect），提取类、接口、函数、变量等导出
+4. **解析类型定义**：从上游 `index.d.ts` 提取类和接口的方法签名
+
+### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `libroot` (或 `repoDir`) | string | ✅ | 库根目录路径（鸿蒙化仓库目录，包含 package.json） |
+| `output` | string | ❌ | 输出 JSON 文件路径（不指定则输出到 stdout） |
+| `version` | string | ❌ | 上游 npm 版本号（如 "2.2.0"，不指定则自动从 dependencies/README 推断） |
+
+### CLI 调用方式
+
+```bash
+node "{mcpScriptsDir}/rn-extract-interfaces.cjs" \
+  --repoDir "{ohosAnalysisRoot}" \
+  --output "{outputDir}/interface-spec.json" \
+  --version "2.2.0"
+```
+
+### 版本推断逻辑
+
+脚本按以下优先级自动推断上游版本号：
+
+1. 用户通过 `--version` 显式指定
+2. `package.json` 的 `dependencies` 中与库名匹配的依赖版本
+3. `README.md` 中的版本声明（如 `[react-native-xxx@2.2.0]`）
+4. 从鸿蒙化仓库自身版本号推断（去除 `-beta`/`-rc` 后缀）
+5. 降级到 `npm latest`
+
+### 输出 JSON 结构
+
+```json
+{
+  "libraryName": "react-native-xxx",
+  "libraryAlias": "xxx",
+  "entryFile": "upstream:react-native-xxx@2.2.0/index.js",
+  "exportStyle": "commonjs | es-module | side-effect | unknown",
+  "upstream": { "pkgName": "react-native-xxx", "version": "2.2.0", "isUpstream": true },
+  "extractedAt": "2026-08-15T...",
+  "summary": { "S": 3, "N": 15, "M": 0, "methods": 10, "properties": 0, "fields": 0 },
+  "sources": ["upstream:.../index.js", "upstream:.../index.d.ts"],
+  "interfaces": [
+    {
+      "className": "ModuleName",
+      "memberName": "methodName",
+      "fullName": "ModuleName.methodName",
+      "kind": "method | function | type | variable",
+      "isStatic": false,
+      "isReadonly": false,
+      "isOptional": false,
+      "isEvent": false,
+      "type": "turbo-module | es-export | commonjs-export | type-decl",
+      "layer": "turbo | js",
+      "signature": "methodName(param: type): returnType",
+      "params": [{ "name": "param", "type": "type", "optional": false, "description": "-" }],
+      "returnType": "returnType",
+      "description": "方法描述",
+      "source": "upstream:.../index.js:42",
+      "startLine": 42
+    }
+  ]
+}
+```
+
+### 接口类型说明
+
+| type 值 | 说明 | 来源 |
+|---------|------|------|
+| `turbo-module` | TurboModule Spec 方法 | 鸿蒙化仓库 `Native*.ts` |
+| `es-export` | ES Module 导出 | 上游 `index.js`/`index.ts` |
+| `commonjs-export` | CommonJS 导出 | 上游 `index.js` |
+| `side-effect` | 全局补丁 | 上游 `index.js` |
+| `type-decl` | 类型声明 | 上游 `index.d.ts` |
+
+## rn-render-spec-doc.cjs
+
+### 功能
+
+将接口规格数据渲染为 Markdown 格式的接口规格说明书文档。支持两种输入方式：
+
+1. **从 JSON 中间件渲染**：读取 `rn-extract-interfaces.cjs` 生成的 JSON 文件
+2. **直接从源码提取并渲染**：一步到位（内部调用 `generateRNSpec`）
+
+### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `spec` | string | ⚠️ | 已有的 interface-spec.json 路径（与 libroot 二选一） |
+| `libroot` (或 `repoDir`) | string | ⚠️ | 库根目录路径（直接从源码提取，与 spec 二选一） |
+| `output` | string | ❌ | 输出 Markdown 文件路径（不指定则输出到 stdout） |
+| `version` | string | ❌ | 上游 npm 版本号（仅 libroot 模式有效） |
+
+### CLI 调用方式
+
+**方式一：从 JSON 中间件渲染（推荐）**
+
+```bash
+node "{mcpScriptsDir}/rn-render-spec-doc.cjs" \
+  --spec "{outputDir}/interface-spec.json" \
+  --output "{outputDir}/接口规格说明.md"
+```
+
+**方式二：直接从源码提取并渲染（一步到位）**
+
+```bash
+node "{mcpScriptsDir}/rn-render-spec-doc.cjs" \
+  --libroot "{ohosAnalysisRoot}" \
+  --output "{outputDir}/接口规格说明.md" \
+  --version "2.2.0"
+```
+
+### 生成文档结构
+
+脚本生成的 Markdown 文档包含以下章节：
+
+1. **基本信息**：库名、导入别名、入口文件、导出模式、生成时间、源文件数
+2. **接口统计**：类/接口/模块总数、方法/属性/字段数量
+3. **按层级分布**：TurboModule 层 vs JS 层接口数量
+4. **按类分组的接口详情**：每个类/模块下分方法、函数、属性、字段、变量、类型别名、事件方法
+5. **源文件列表**：所有分析的源文件路径
+
+### 依赖关系
+
+```
+rn-render-spec-doc.cjs
+    └── require('./rn-extract-interfaces.cjs')  (loadSpec / generateRNSpec)
+```
+
+> ⚠️ 两个脚本同位于 `MCP/scripts/` 目录。`rn-render-spec-doc.cjs` 通过相对路径 `require('./rn-extract-interfaces.cjs')` 依赖提取脚本。
+
+## 环境要求
+
+- Node.js ≥ 14
+- npm（用于 `npm pack` 拉取上游源码）
+- 网络访问（npm registry）
+- 可选：TypeScript（用于 AST 级别的类型解析，脚本会自动尝试加载）
+
+## 常见问题
+
+| 问题 | 原因 | 解决方案 |
+|------|------|----------|
+| `npm pack` 失败 | 网络问题或包名错误 | 检查网络连接，确认包名正确 |
+| 上游版本不存在 | 版本号错误 | 脚本会自动降级到 `latest`，或通过 `--version` 指定正确版本 |
+| `index.d.ts` 未找到 | 上游包未包含类型声明 | 脚本会跳过类型定义提取，仅从 JS 层导出提取 |
+| TurboModule Spec 未找到 | 鸿蒙化仓库无 `Native*.ts` 文件 | 脚本会跳过 TurboModule 提取，仅从 JS 层导出提取 |
+| 导出模式为 `unknown` | 入口文件无法识别导出模式 | 检查 `package.json` 的 `main`/`module`/`source` 字段是否正确 |

package/vendor/Server/Skills/rn-library-interface-analyzer/references/URL_PARSING_RULES.md

@@ -0,0 +1,176 @@
+# URL 格式解析规则
+
+本文档详细说明 RNLibraryInterfaceAnalyzer 支持的输入 URL 格式与解析规则。
+
+## 输入形式
+
+| 输入形式 | 示例 | 获取方式 |
+|----------|------|----------|
+| **Git 仓库地址（完整 URL）** | `https://github.com/org/repo.git` | git clone 到指定目录后分析 |
+| **Git 仓库地址（带分支）** | `https://gitcode.com/org/repo/tree/branch_name` | 自动解析分支并切换 |
+| **Git 仓库地址（带分支和子路径）** | `https://gitcode.com/org/repo/tree/branch/subpath` | 使用 Sparse Checkout 只克隆指定子目录 |
+| **Git 仓库地址（带 commit）** | `https://github.com/org/repo/blob/913e7da456a6` | 克隆仓库后 checkout 到指定 commit |
+| **Git 仓库地址（带 commit 和子路径）** | `https://github.com/org/repo/blob/913e7da456a6/src` | 克隆仓库、checkout commit、Sparse Checkout 子目录 |
+| **本地路径** | `/path/to/some-library`、`node_modules/axios` | 直接读取目录文件 |
+| **npm 包名**（仅 upstreamRepoUrl） | `axios`、`lodash` | 查阅 `node_modules/` 或运行 `npm pack <包名>` 解包 |
+
+> ⚠️ `ohosRepoUrl` 不支持 npm 包名形式，鸿蒙化仓库必须通过 Git 或本地路径提供
+
+## URL 格式解析
+
+支持从 Web 页面 URL 直接复制使用，自动解析以下格式：
+
+### 格式 1：仅分支
+
+```
+https://gitcode.com/openharmony-sig/react-native-localization-settings/tree/ohos
+```
+
+解析为：
+- 仓库地址：`https://gitcode.com/openharmony-sig/react-native-localization-settings.git`
+- 分支：`ohos`
+- 子路径：无（分析整个仓库）
+
+### 格式 2：分支 + 子路径
+
+```
+https://gitcode.com/openharmony-sig/react-native-touch-id/tree/ohos/harmony
+```
+
+解析为：
+- 仓库地址：`https://gitcode.com/openharmony-sig/react-native-touch-id.git`
+- 分支：`ohos`
+- 子路径：`harmony`（只分析这个文件夹）
+
+### 格式 3：标准 Git URL（支持扩展参数）
+
+```
+https://github.com/org/repo.git#branch=develop
+https://github.com/org/repo.git#subpath=packages/core
+https://github.com/org/repo.git#branch=develop&subpath=packages/core
+```
+
+### 格式 4：Commit Hash
+
+```
+https://github.com/TencentCloud/cos-sdk-react-native-plugin/blob/913e7da456a653e8a910fa9c6d488cef41bcf37e
+```
+
+解析为：
+- 仓库地址：`https://github.com/TencentCloud/cos-sdk-react-native-plugin.git`
+- commit：`913e7da456a653e8a910fa9c6d488cef41bcf37e`
+- 子路径：无（分析整个仓库）
+
+> 识别规则：URL 中 `/blob/` 或 `/tree/` 或 `/commit/` 后的第一段，如果匹配正则 `[0-9a-f]{7,40}`（7~40 位十六进制字符），则判定为 commit hash 而非分支名。
+
+### 格式 5：Commit Hash + 子路径
+
+```
+https://github.com/TencentCloud/cos-sdk-react-native-plugin/blob/913e7da456a653e8a910fa9c6d488cef41bcf37e/src
+```
+
+解析为：
+- 仓库地址：`https://github.com/TencentCloud/cos-sdk-react-native-plugin.git`
+- commit：`913e7da456a653e8a910fa9c6d488cef41bcf37e`
+- 子路径：`src`（只分析这个文件夹）
+
+### 格式 6：GitHub Commit 页面 URL
+
+```
+https://github.com/org/repo/commit/913e7da456a6
+```
+
+解析为：
+- 仓库地址：`https://github.com/org/repo.git`
+- commit：`913e7da456a6`
+- 子路径：无
+
+## 判断输入类型
+
+根据参数值的格式判断输入类型：
+
+| 输入类型 | 判断规则 | 处理方式 |
+|----------|----------|----------|
+| Git URL | 以 `http://`、`https://`、`git://`、`ssh://` 开头，或以 `.git` 结尾 | 执行 Git 克隆流程 |
+| 本地路径 | 以 `/` 开头或包含路径分隔符且路径存在 | 直接作为 analysisRoot |
+| npm 包名 | 不以 `/` 或 `http` 开头的纯字母数字字符串 | npm 解包流程 |
+
+## 克隆命令参考
+
+### 按分支克隆（无 commit hash）
+
+```bash
+# 无子路径（完整克隆）
+mkdir -p {outputDir}/source/{target}
+git clone --depth=1 -b {branch} {baseUrl} {outputDir}/source/{target}
+
+# 有子路径（Sparse Checkout）
+mkdir -p {outputDir}/source/{target}
+cd {outputDir}/source/{target}
+git init
+git sparse-checkout init --cone
+git remote add origin {baseUrl}
+git sparse-checkout set {subpath}
+git fetch origin {branch} --depth=1
+git checkout {branch}
+```
+
+### 按 commit hash 克隆
+
+> ⚠️ 按 commit checkout 时**不能使用 `--depth=1`**，因为 shallow clone 不包含任意 commit 的历史。必须先完整克隆或 fetch 到该 commit，然后 checkout。
+
+```bash
+# 无子路径
+mkdir -p {outputDir}/source/{target}
+git clone {baseUrl} {outputDir}/source/{target}
+cd {outputDir}/source/{target}
+git checkout {commitHash}
+
+# 有子路径（Sparse Checkout + commit checkout）
+mkdir -p {outputDir}/source/{target}
+cd {outputDir}/source/{target}
+git init
+git sparse-checkout init --cone
+git remote add origin {baseUrl}
+git sparse-checkout set {subpath}
+git fetch origin
+git checkout {commitHash}
+```
+
+### 本地路径
+
+```bash
+ln -s {localPath} {outputDir}/source/{target}
+```
+
+### npm 包名（仅 upstreamRepoUrl）
+
+```bash
+if [ -d "node_modules/{packageName}" ]; then
+  ln -s node_modules/{packageName} {outputDir}/source/RN
+else
+  mkdir -p {outputDir}/source/RN
+  cd {outputDir}/source/RN
+  npm pack {packageName}
+  tar -xzf *.tgz
+  mv package/* .
+  rm -rf package *.tgz
+fi
+```
+
+## 获取失败处理
+
+| 错误类型 | 可能原因 | 解决方案 |
+|----------|----------|----------|
+| 认证失败 | 私有仓库或权限不足 | 提示用户配置 SSH 密钥或 HTTPS Token |
+| 分支不存在 | 分支名称错误 | `git branch -r` 列出远程分支，提示用户选择 |
+| commit 不存在 | commit hash 错误或 abbreviated hash 无法定位 | `git log --oneline -20` 列出近期 commit，提示用户确认；或尝试使用完整 40 位 hash |
+| 子路径不存在 | 路径错误或分支/commit 中无此目录 | 列出仓库根目录内容，提示确认路径 |
+| 网络超时 | 网络问题 | 提示检查网络或使用镜像站点 |
+| Sparse Checkout 失败 | Git 版本过低 | 提示升级 Git 到 2.25+ 或使用完整克隆 |
+| npm 包不存在 | 包名错误 | 提示用户确认包名，尝试 `npm search` |
+| 本地路径不存在 | 路径错误 | 提示用户确认路径 |
+| commit checkout 后仓库内容与预期不符 | commit hash 指向的代码版本不是适配基准 | 提示用户核实 commit hash 是否为鸿蒙化适配时对应的上游版本 |
+| rndocUrl 克隆失败 | Git 仓库不可访问 | 回退使用鸿蒙化仓库 README.md 作为文档来源 |
+| rndocUrl Web fetch 失败 | 页面不可访问或非 Markdown 内容 | 回退使用鸿蒙化仓库 README.md 作为文档来源 |
+| 鸿蒙化仓库无 README.md | 鸿蒙化仓库根目录缺少 README.md | 所有差异项标注 `—`（无文档） |