@ohos-cpf/3rdloop 0.0.1 → 0.0.3

package/vendor/Server/Skills/rn-library-issue-generalizer/SKILL.md

@@ -1,274 +1,274 @@
----
-name: rn-library-issue-generalizer
-description: 将 RN 三方库鸿蒙化历史问题案例（问题描述+修复 PR 链接）泛化为机制层检视规则，问题拆分后直接写入分级知识库（一级 INDEX 索引 + 二级 rules/cases 目录），实现一个案例防范一类问题。当需要从已修复问题中提炼可复用检视规则、扩充 RN 库已知问题知识库、或对新修复 PR 做归类沉淀时使用。离线运营工具，产出标记 draft 状态的条目供人工审核激活，供已知问题检视 SKILL 消费。
-license: Apache-2.0
-compatibility: 需要网络访问 GitCode（获取 PR 元数据与 diff）、Python ≥ 3.8（运行 scripts/fetch-pr-info.py，无第三方依赖）、对知识库目录（knowledgeDir）的文件读写权限
-metadata:
-  author: CPPAgent
-  version: "2.0.0"
-  category: rn-library-check
----
-
-# rn-library-issue-generalizer — 问题案例泛化器
-
-将**具体的**问题案例（现象描述 + 修复 PR）提炼为**机制层的检视规则**：案例归档为 few-shot 参考，规则用于未来所有库的已知问题检视——**一个案例，防范一类问题**。问题拆分（一案例 → 多规则）后，产出**直接写入分级知识库目录**。
-
-> ⚠️ **核心原则**：
-> 1. **泛化三约束**：规则体必须 ①**去库化**（不出现具体库名/API 名）②**上升到机制层**（描述检查方法，而非修复某个 bug）③**可判定**（每个检查点 Agent 读源码后能给出 是/否/疑似）
-> 2. **规则数量收敛**：优先将案例归入已有规则（增厚 few-shot）；只有确认现有规则的问题本质无法覆盖时才新建规则
-> 3. **直接写入分级目录 + draft 状态标记**：新建/修订的规则与案例**直接写入知识库分级目录**（rules/、cases/、INDEX.md），但状态标记为 `draft`；经人工审核后将状态改为 `active` 方可被检视 SKILL 消费
-> 4. **案例信息完整保留**：具体库名、PR 链接、修复方式只出现在案例文件中，作为 few-shot 与修复指引
-> 5. **所有文件存放在 knowledgeDir 下**：禁止写入系统临时目录或其他外部路径
-
----
-
-## 任务参数
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `issueList` | ✅ | 案例清单。三种格式任选：① JSON 数组 `[{"description": "...", "prUrl": "..."}]` ② 清单文件路径（每行一条：`问题描述 <空格/Tab> PR链接`，兼容 Markdown 链接 `[描述](url)` 与裸 URL） ③ 多行文本（同②格式） |
-| `knowledgeDir` | ✅ | 知识库根目录绝对路径（如 `BadCase/rn`）。目录无 `INDEX.md` 时视为**冷启动**，自动初始化分级结构；已有 `INDEX.md` 时读取现有规则执行归类比对（Phase 4） |
-| `gitcodeToken` | ❌ | GitCode API Token。访问私有仓库或遇速率限制时使用 |
-
----
-
-## 输入依赖
-
-无前置 SKILL。可作为独立任务调用。
-
-- **可选输入**：现有分级知识库（`knowledgeDir` 下已有 `INDEX.md` + `rules/` + `cases/`），格式参见 [规则条目编写指南](references/RULE_TEMPLATE_GUIDE.md)
-
----
-
-## 目录结构约定
-
-> ⚠️ **所有新增/修改文件**都必须存放在 `{knowledgeDir}` 内。知识库采用**分级结构**（一级索引 + 二级知识）：
-
-```
-{knowledgeDir}/                       # 通常为 BadCase/rn/
-├── INDEX.md                          # 一级：分类 + 规则/案例索引（不含具体知识）
-├── rules/                            # 二级：规则知识
-│   └── R-{XX}-{规则名}.md            #   检查点/特征 + 案例索引行
-├── cases/                            # 二级：案例知识（格式二：代码证据式）
-│   └── KI-{XXX}-{库名现象}.md        #   元数据/现象/根因/错误代码/正确代码/修复方式
-├── pr-info/                          # 案例原始 PR diff 证据材料
-│   └── {repo}-{number}.md（+ .json）
-└── generalization-log.md             # 运行产出：泛化过程日志（追加式）
-```
-
-**分级规则**：
-- **一级 INDEX.md** 只含分类、索引表（编号/名称/严重级别/文件链接），Agent 预筛时只读此文件
-- **二级 rules/** 每规则一文件，含完整检查知识 + 案例索引行（不含案例详情）
-- **二级 cases/** 每案例一文件（格式二），一案例挂多条规则时只存一份，规则文件通过索引引用
-- **pr-info/** 是案例的证据材料，案例文件中链接引用
-
-**状态机制**（draft → active）：
-- 本 SKILL 新建/修订的规则与案例，frontmatter 或元数据中状态标记为 `draft`
-- 人工审核通过后，将状态改为 `active`（规则文件改 `- **状态**: active`；案例文件元数据加 `status: active`）
-- 检视 SKILL 只消费 `active` 状态的规则与案例
-
----
-
-## 工作流程概览
-
-```
-Phase 1: 案例解析与 PR 材料获取（写入 pr-info/）
-    ↓
-Phase 2: 根因分析（现象 → 根因 → 修复机制）
-    ↓
-Phase 3: 泛化提炼（去库化 / 机制化 / 可判定化）
-    ↓
-Phase 4: 知识库归类比对（读 INDEX + rules/，归入已有规则 or 新建规则）
-    ↓
-Phase 5: 直接写入分级目录（rules/ + cases/ + INDEX.md，draft 状态）与自检
-    ↓
-Phase 6: 输出与审核指引（审核通过后翻 active）
-```
-
----
-
-## Phase 1：案例解析与 PR 材料获取
-
-### 1.0 初始化知识库目录
-
-检查 `{knowledgeDir}` 是否已有 `INDEX.md`：
-- **已有** → 读取 INDEX.md 的规则/案例索引，进入正常流程（Phase 4 执行归类比对）
-- **没有** → 冷启动：创建 `INDEX.md`（空索引骨架）+ `rules/` + `cases/` + `pr-info/` 目录
-
-### 1.1 解析 issueList
-
-- **JSON 数组**：直接使用 `description` + `prUrl` 字段
-- **文本/文件**：逐行解析，提取「描述文本」与「GitCode PR 链接」。示例行：
-
-```
-【DTSE代提】【react-native-webview】视频无法横屏    https://gitcode.com/CPF-RN/rntpc_react-native-webview/pull/121
-```
-
-- 解析失败的行（无 PR 链接 / 链接非 gitcode.com）记入 `generalization-log.md` 的"无效条目"章节，**不中断流程**
-- 按 PR 链接去重；`pr-info/` 下已存在同名材料文件的跳过重复获取
-- **案例编号分配**：新案例编号 = INDEX.md 案例索引中现有最大 KI 编号 +1（冷启动从 KI-001 开始）
-
-### 1.2 获取 PR 材料
-
-对每个案例运行脚本（在 SKILL 根目录下执行）：
-
-```bash
-python3 scripts/fetch-pr-info.py '{"prUrl": "https://gitcode.com/owner/repo/pull/123", "outputDir": "{knowledgeDir}", "token": "{gitcodeToken 可选}"}'
-```
-
-脚本输出 `{knowledgeDir}/pr-info/{repo}-{number}.md`（可读摘要：标题/描述/变更文件/diff）与 `.json`（原始数据）。
-
-> 脚本用法、API 端点、降级策略详见 [PR 材料获取指南](references/PR_FETCH_GUIDE.md)
-
-### 1.3 获取失败降级
-
-脚本获取失败时（私有仓库 / 网络受限 / PR 已删除）：
-
-1. 标记该案例为 **材料不足**
-2. Phase 2 仅基于问题描述分析，泛化质量会下降
-3. 在最终草稿的"审核要点"中明确标注：`该规则未验证修复 diff，审核时需人工确认问题本质归纳是否准确`
-
----
-
-## Phase 2：根因分析
-
-对每个案例，从三个层次分析并记入 `generalization-log.md`：
-
-| 层次 | 内容 | 示例（thumbImageUrl 案例） |
-|------|------|---------------------------|
-| **现象层** | 用户可感知的症状，保留原始描述 | 分享时图片下载报错，无法跳转微信 |
-| **根因层** | 代码机制层面的缺陷描述 | 缩略图下载失败码直接出现在主流程 reject 路径上，附属操作失败阻断了核心流程 |
-| **修复机制** | 从 PR diff 提炼修复**模式**（不是逐行复述 diff） | 缩略图下载失败时置空 thumb 字段、记录日志并继续调起主流程 |
-
-**要求**：
-- 根因层必须落到"机制"：回答"这类问题为什么会发生"，而不是"这个 bug 在哪一行"
-- 修复机制必须可迁移：换个库遇到同类问题，这个修法依然有指导意义
-- diff 材料充足时，定位修复前后的关键差异（错误路径处理 / 配置补全 / 入口修正等）
-
----
-
-## Phase 3：泛化提炼
-
-将根因层泛化为规则。**必须通过泛化三约束**，对照反例自检：
-
-| 反例类型 | 错误示范 | 问题 |
-|----------|----------|------|
-| ❌ 过拟合 | "检查视频全屏时是否处理横屏旋转" | 等于没泛化，只防住原案例本身 |
-| ❌ 过泛化 | "检查异常处理是否完善" | 废话型规则，无法判定，Agent 只能泛泛而谈 |
-| ✅ 合格 | "主流程中每个附属操作失败时，是否隔离降级而非阻断主流程" | 机制层描述 + 读源码可判定 |
-
-**泛化操作要点**：
-1. **去库化**：把案例中的具体库名、组件名、API 名替换为"能力/角色"描述（`react-native-webview` → "含 WebView 能力的库"；`shareWebpage` → "主流程接口"）
-2. **机制化**：从"这个 bug 怎么修"上升到"这类问题怎么查"——产出的是检查方法，不是修复补丁
-3. **可判定化**：每个检查点改写为动词开头的源码检查动作（识别/列出/逐项检查/验证），确保 Agent 执行时能给出 是/否/疑似 结论
-
-> 字段级编写规范、更多正反例、首批规则参考示例详见 [规则条目编写指南](references/RULE_TEMPLATE_GUIDE.md)
-
----
-
-## Phase 4：知识库归类比对
-
-### 4.1 读取现有知识库
-
-读取 `{knowledgeDir}/INDEX.md` 的规则索引，获取现有规则列表（编号、规则名、分类、严重级别）。需要比对"问题本质"细节时，按索引链接读取对应 `rules/R-XX-*.md` 文件。
-
-冷启动（INDEX 无规则）时跳过比对，全部走新建分支。
-
-### 4.2 归类判定
-
-对每条泛化后的规则草稿，按以下顺序判定：
-
-1. **语义比对**：草稿的"问题本质"与现有规则的"问题本质"是否描述同一类机制缺陷？
-2. **命中** → 该案例**挂载**到已有规则（增厚 few-shot，**不新建规则**），必要时补充/修订该规则的检查点
-3. **未命中** → 新建规则草稿，分配下一个可用编号（R-{现有最大编号+1}），并确定其所属分类（现有分类优先，必要时新建分类）
-
-**边界处理**：
-- 同一案例可能触及多条规则（既是"降级缺失"又是"能力声明不匹配"）→ 允许一案例挂多条规则，但**新建规则要保持克制**
-- 修订已有规则的检查点时，必须在 `generalization-log.md` 中明确标注"修订项"及理由，供人工审核
-
-### 4.3 记录归类依据
-
-每条归类判定（命中/未命中的理由）写入 `generalization-log.md`，供人工审核追溯。
-
----
-
-## Phase 5：直接写入分级目录与自检
-
-> 问题拆分完成后，产出**直接写入知识库分级目录**（不生成单文件草稿快照），所有新建/修订条目标记 `draft` 状态。
-
-### 5.1 写入规则文件（rules/）
-
-- **新建规则**：按 [规则条目模板](assets/rule-template.md) 生成，写入 `rules/R-{XX}-{规则名}.md`，状态标记 `draft`
-- **修订已有规则**（挂载案例时）：在原文件"来源案例"索引表追加案例行；如需补充检查点，在原检查点列表追加并标注 `（{日期} 新增，draft 待审）`
-
-### 5.2 写入案例文件（cases/）
-
-- 按 [案例条目模板](assets/case-template.md) 生成（**格式二：代码证据式**），写入 `cases/KI-{XXX}-{库名现象}.md`
-- **一案例一文件**：复合问题案例（挂多条规则）只写一份，元数据 `rule` 字段逗号分隔多条规则编号
-
-**案例代码证据要求**（格式二核心）：
-- `verified: diff` 的案例**必须**包含"错误代码（修复前）"与"正确代码（修复后）"两个片段，从 PR diff 实际提取，禁止凭描述臆造
-- 每段 ≤15 行，只保留命中判定关键行；错误代码用 `// ←` 标注缺陷点，正确代码用 `①②③` 标注修复步骤
-- 元数据行必填：`rule` · `verified` · `source` · `severity`
-
-### 5.3 更新一级索引（INDEX.md）
-
-- **规则分类索引表**：新建规则追加行（含所属分类）；新建分类时增加分类小节
-- **案例索引表**：新案例追加行（编号/库/现象/所属规则/验证方式/案例文件链接）
-- **变更记录表**：追加本次运行记录（日期 + 新建规则数/挂载案例数/修订项摘要）
-
-### 5.4 自检清单
-
-对每条产出逐项自检（不通过则回到 Phase 3 修订）：
-
-| # | 检查项 |
-|---|--------|
-| 1 | 规则体（来源案例区之外）无具体库名 / API 名 |
-| 2 | 每个检查点可独立判定（读源码能给出 是/否/疑似） |
-| 3 | 适用范围含可执行的预筛特征（依赖/文件/API 特征） |
-| 4 | 与现有规则无"问题本质"层面的重叠 |
-| 5 | 案例信息完整（现象 / 根因 / 修复方式 / PR 链接） |
-| 6 | 严重级别有判定依据（high=功能不可用；medium=特定场景失效；low=体验问题） |
-| 7 | INDEX.md 索引行与实际文件一一对应（链接可跳转） |
-| 8 | 新建/修订条目状态均为 `draft` |
-
----
-
-## Phase 6：输出与审核指引
-
-### 6.1 审核指引（写入 generalization-log.md）
-
-每次运行在 `generalization-log.md` **追加**一节，包含：
-
-```markdown
-# 泛化运行 — {日期}
-
-## 产出清单
-- 新建规则: {R-XX 列表 + 文件路径}
-- 新建案例: {KI-XXX 列表 + 文件路径}
-- 挂载案例: {KI-XXX → R-XX 映射}
-- 修订规则: {R-XX + 修订内容}
-
-## 审核要点
-- 泛化度存疑项: {列出过拟合/过泛化风险条目及原因}
-- 材料不足项: {未获取到 diff 的案例清单}
-- 规则重叠风险: {与现有规则边界模糊的条目}
-
-## 审核操作指引
-1. 逐条审阅 draft 状态的规则/案例文件
-2. 审核通过 → 规则文件改 `- **状态**: active`；案例文件元数据加 `status: active`
-3. 审核不通过 → 修订文件内容或删除文件，并同步删除 INDEX.md 对应索引行
-```
-
-### 6.2 输出确认
-
-完成后输出确认信息：处理案例数、新建规则数、挂载案例数、材料不足数、写入的文件列表（含 INDEX.md 变更摘要）。
-
----
-
-## 与其他 SKILL 的关系
-
-| SKILL | 关系 |
-|-------|------|
-| `rn-library-known-issue-check`（已知问题检视） | **消费者**：读 INDEX.md 预筛 → 按 `active` 状态规则执行检查，案例作为 few-shot |
-| RN 仓库检视流水线 | 间接关系：本 SKILL 为离线运营工具，**不参与**在线扫描流水线；其产出经人工审核激活后供检视 SKILL 使用 |
+---
+name: rn-library-issue-generalizer
+description: 将 RN 三方库鸿蒙化历史问题案例（问题描述+修复 PR 链接）泛化为机制层检视规则，问题拆分后直接写入分级知识库（一级 INDEX 索引 + 二级 rules/cases 目录），实现一个案例防范一类问题。当需要从已修复问题中提炼可复用检视规则、扩充 RN 库已知问题知识库、或对新修复 PR 做归类沉淀时使用。离线运营工具，产出标记 draft 状态的条目供人工审核激活，供已知问题检视 SKILL 消费。
+license: Apache-2.0
+compatibility: 需要网络访问 GitCode（获取 PR 元数据与 diff）、Python ≥ 3.8（运行 scripts/fetch-pr-info.py，无第三方依赖）、对知识库目录（knowledgeDir）的文件读写权限
+metadata:
+  author: CPPAgent
+  version: "2.0.0"
+  category: rn-library-check
+---
+
+# rn-library-issue-generalizer — 问题案例泛化器
+
+将**具体的**问题案例（现象描述 + 修复 PR）提炼为**机制层的检视规则**：案例归档为 few-shot 参考，规则用于未来所有库的已知问题检视——**一个案例，防范一类问题**。问题拆分（一案例 → 多规则）后，产出**直接写入分级知识库目录**。
+
+> ⚠️ **核心原则**：
+> 1. **泛化三约束**：规则体必须 ①**去库化**（不出现具体库名/API 名）②**上升到机制层**（描述检查方法，而非修复某个 bug）③**可判定**（每个检查点 Agent 读源码后能给出 是/否/疑似）
+> 2. **规则数量收敛**：优先将案例归入已有规则（增厚 few-shot）；只有确认现有规则的问题本质无法覆盖时才新建规则
+> 3. **直接写入分级目录 + draft 状态标记**：新建/修订的规则与案例**直接写入知识库分级目录**（rules/、cases/、INDEX.md），但状态标记为 `draft`；经人工审核后将状态改为 `active` 方可被检视 SKILL 消费
+> 4. **案例信息完整保留**：具体库名、PR 链接、修复方式只出现在案例文件中，作为 few-shot 与修复指引
+> 5. **所有文件存放在 knowledgeDir 下**：禁止写入系统临时目录或其他外部路径
+
+---
+
+## 任务参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `issueList` | ✅ | 案例清单。三种格式任选：① JSON 数组 `[{"description": "...", "prUrl": "..."}]` ② 清单文件路径（每行一条：`问题描述 <空格/Tab> PR链接`，兼容 Markdown 链接 `[描述](url)` 与裸 URL） ③ 多行文本（同②格式） |
+| `knowledgeDir` | ✅ | 知识库根目录绝对路径（如 `BadCase/rn`）。目录无 `INDEX.md` 时视为**冷启动**，自动初始化分级结构；已有 `INDEX.md` 时读取现有规则执行归类比对（Phase 4） |
+| `gitcodeToken` | ❌ | GitCode API Token。访问私有仓库或遇速率限制时使用 |
+
+---
+
+## 输入依赖
+
+无前置 SKILL。可作为独立任务调用。
+
+- **可选输入**：现有分级知识库（`knowledgeDir` 下已有 `INDEX.md` + `rules/` + `cases/`），格式参见 [规则条目编写指南](references/RULE_TEMPLATE_GUIDE.md)
+
+---
+
+## 目录结构约定
+
+> ⚠️ **所有新增/修改文件**都必须存放在 `{knowledgeDir}` 内。知识库采用**分级结构**（一级索引 + 二级知识）：
+
+```
+{knowledgeDir}/                       # 通常为 BadCase/rn/
+├── INDEX.md                          # 一级：分类 + 规则/案例索引（不含具体知识）
+├── rules/                            # 二级：规则知识
+│   └── R-{XX}-{规则名}.md            #   检查点/特征 + 案例索引行
+├── cases/                            # 二级：案例知识（格式二：代码证据式）
+│   └── KI-{XXX}-{库名现象}.md        #   元数据/现象/根因/错误代码/正确代码/修复方式
+├── pr-info/                          # 案例原始 PR diff 证据材料
+│   └── {repo}-{number}.md（+ .json）
+└── generalization-log.md             # 运行产出：泛化过程日志（追加式）
+```
+
+**分级规则**：
+- **一级 INDEX.md** 只含分类、索引表（编号/名称/严重级别/文件链接），Agent 预筛时只读此文件
+- **二级 rules/** 每规则一文件，含完整检查知识 + 案例索引行（不含案例详情）
+- **二级 cases/** 每案例一文件（格式二），一案例挂多条规则时只存一份，规则文件通过索引引用
+- **pr-info/** 是案例的证据材料，案例文件中链接引用
+
+**状态机制**（draft → active）：
+- 本 SKILL 新建/修订的规则与案例，frontmatter 或元数据中状态标记为 `draft`
+- 人工审核通过后，将状态改为 `active`（规则文件改 `- **状态**: active`；案例文件元数据加 `status: active`）
+- 检视 SKILL 只消费 `active` 状态的规则与案例
+
+---
+
+## 工作流程概览
+
+```
+Phase 1: 案例解析与 PR 材料获取（写入 pr-info/）
+    ↓
+Phase 2: 根因分析（现象 → 根因 → 修复机制）
+    ↓
+Phase 3: 泛化提炼（去库化 / 机制化 / 可判定化）
+    ↓
+Phase 4: 知识库归类比对（读 INDEX + rules/，归入已有规则 or 新建规则）
+    ↓
+Phase 5: 直接写入分级目录（rules/ + cases/ + INDEX.md，draft 状态）与自检
+    ↓
+Phase 6: 输出与审核指引（审核通过后翻 active）
+```
+
+---
+
+## Phase 1：案例解析与 PR 材料获取
+
+### 1.0 初始化知识库目录
+
+检查 `{knowledgeDir}` 是否已有 `INDEX.md`：
+- **已有** → 读取 INDEX.md 的规则/案例索引，进入正常流程（Phase 4 执行归类比对）
+- **没有** → 冷启动：创建 `INDEX.md`（空索引骨架）+ `rules/` + `cases/` + `pr-info/` 目录
+
+### 1.1 解析 issueList
+
+- **JSON 数组**：直接使用 `description` + `prUrl` 字段
+- **文本/文件**：逐行解析，提取「描述文本」与「GitCode PR 链接」。示例行：
+
+```
+【DTSE代提】【react-native-webview】视频无法横屏    https://gitcode.com/CPF-RN/rntpc_react-native-webview/pull/121
+```
+
+- 解析失败的行（无 PR 链接 / 链接非 gitcode.com）记入 `generalization-log.md` 的"无效条目"章节，**不中断流程**
+- 按 PR 链接去重；`pr-info/` 下已存在同名材料文件的跳过重复获取
+- **案例编号分配**：新案例编号 = INDEX.md 案例索引中现有最大 KI 编号 +1（冷启动从 KI-001 开始）
+
+### 1.2 获取 PR 材料
+
+对每个案例运行脚本（在 SKILL 根目录下执行）：
+
+```bash
+python3 scripts/fetch-pr-info.py '{"prUrl": "https://gitcode.com/owner/repo/pull/123", "outputDir": "{knowledgeDir}", "token": "{gitcodeToken 可选}"}'
+```
+
+脚本输出 `{knowledgeDir}/pr-info/{repo}-{number}.md`（可读摘要：标题/描述/变更文件/diff）与 `.json`（原始数据）。
+
+> 脚本用法、API 端点、降级策略详见 [PR 材料获取指南](references/PR_FETCH_GUIDE.md)
+
+### 1.3 获取失败降级
+
+脚本获取失败时（私有仓库 / 网络受限 / PR 已删除）：
+
+1. 标记该案例为 **材料不足**
+2. Phase 2 仅基于问题描述分析，泛化质量会下降
+3. 在最终草稿的"审核要点"中明确标注：`该规则未验证修复 diff，审核时需人工确认问题本质归纳是否准确`
+
+---
+
+## Phase 2：根因分析
+
+对每个案例，从三个层次分析并记入 `generalization-log.md`：
+
+| 层次 | 内容 | 示例（thumbImageUrl 案例） |
+|------|------|---------------------------|
+| **现象层** | 用户可感知的症状，保留原始描述 | 分享时图片下载报错，无法跳转微信 |
+| **根因层** | 代码机制层面的缺陷描述 | 缩略图下载失败码直接出现在主流程 reject 路径上，附属操作失败阻断了核心流程 |
+| **修复机制** | 从 PR diff 提炼修复**模式**（不是逐行复述 diff） | 缩略图下载失败时置空 thumb 字段、记录日志并继续调起主流程 |
+
+**要求**：
+- 根因层必须落到"机制"：回答"这类问题为什么会发生"，而不是"这个 bug 在哪一行"
+- 修复机制必须可迁移：换个库遇到同类问题，这个修法依然有指导意义
+- diff 材料充足时，定位修复前后的关键差异（错误路径处理 / 配置补全 / 入口修正等）
+
+---
+
+## Phase 3：泛化提炼
+
+将根因层泛化为规则。**必须通过泛化三约束**，对照反例自检：
+
+| 反例类型 | 错误示范 | 问题 |
+|----------|----------|------|
+| ❌ 过拟合 | "检查视频全屏时是否处理横屏旋转" | 等于没泛化，只防住原案例本身 |
+| ❌ 过泛化 | "检查异常处理是否完善" | 废话型规则，无法判定，Agent 只能泛泛而谈 |
+| ✅ 合格 | "主流程中每个附属操作失败时，是否隔离降级而非阻断主流程" | 机制层描述 + 读源码可判定 |
+
+**泛化操作要点**：
+1. **去库化**：把案例中的具体库名、组件名、API 名替换为"能力/角色"描述（`react-native-webview` → "含 WebView 能力的库"；`shareWebpage` → "主流程接口"）
+2. **机制化**：从"这个 bug 怎么修"上升到"这类问题怎么查"——产出的是检查方法，不是修复补丁
+3. **可判定化**：每个检查点改写为动词开头的源码检查动作（识别/列出/逐项检查/验证），确保 Agent 执行时能给出 是/否/疑似 结论
+
+> 字段级编写规范、更多正反例、首批规则参考示例详见 [规则条目编写指南](references/RULE_TEMPLATE_GUIDE.md)
+
+---
+
+## Phase 4：知识库归类比对
+
+### 4.1 读取现有知识库
+
+读取 `{knowledgeDir}/INDEX.md` 的规则索引，获取现有规则列表（编号、规则名、分类、严重级别）。需要比对"问题本质"细节时，按索引链接读取对应 `rules/R-XX-*.md` 文件。
+
+冷启动（INDEX 无规则）时跳过比对，全部走新建分支。
+
+### 4.2 归类判定
+
+对每条泛化后的规则草稿，按以下顺序判定：
+
+1. **语义比对**：草稿的"问题本质"与现有规则的"问题本质"是否描述同一类机制缺陷？
+2. **命中** → 该案例**挂载**到已有规则（增厚 few-shot，**不新建规则**），必要时补充/修订该规则的检查点
+3. **未命中** → 新建规则草稿，分配下一个可用编号（R-{现有最大编号+1}），并确定其所属分类（现有分类优先，必要时新建分类）
+
+**边界处理**：
+- 同一案例可能触及多条规则（既是"降级缺失"又是"能力声明不匹配"）→ 允许一案例挂多条规则，但**新建规则要保持克制**
+- 修订已有规则的检查点时，必须在 `generalization-log.md` 中明确标注"修订项"及理由，供人工审核
+
+### 4.3 记录归类依据
+
+每条归类判定（命中/未命中的理由）写入 `generalization-log.md`，供人工审核追溯。
+
+---
+
+## Phase 5：直接写入分级目录与自检
+
+> 问题拆分完成后，产出**直接写入知识库分级目录**（不生成单文件草稿快照），所有新建/修订条目标记 `draft` 状态。
+
+### 5.1 写入规则文件（rules/）
+
+- **新建规则**：按 [规则条目模板](assets/rule-template.md) 生成，写入 `rules/R-{XX}-{规则名}.md`，状态标记 `draft`
+- **修订已有规则**（挂载案例时）：在原文件"来源案例"索引表追加案例行；如需补充检查点，在原检查点列表追加并标注 `（{日期} 新增，draft 待审）`
+
+### 5.2 写入案例文件（cases/）
+
+- 按 [案例条目模板](assets/case-template.md) 生成（**格式二：代码证据式**），写入 `cases/KI-{XXX}-{库名现象}.md`
+- **一案例一文件**：复合问题案例（挂多条规则）只写一份，元数据 `rule` 字段逗号分隔多条规则编号
+
+**案例代码证据要求**（格式二核心）：
+- `verified: diff` 的案例**必须**包含"错误代码（修复前）"与"正确代码（修复后）"两个片段，从 PR diff 实际提取，禁止凭描述臆造
+- 每段 ≤15 行，只保留命中判定关键行；错误代码用 `// ←` 标注缺陷点，正确代码用 `①②③` 标注修复步骤
+- 元数据行必填：`rule` · `verified` · `source` · `severity`
+
+### 5.3 更新一级索引（INDEX.md）
+
+- **规则分类索引表**：新建规则追加行（含所属分类）；新建分类时增加分类小节
+- **案例索引表**：新案例追加行（编号/库/现象/所属规则/验证方式/案例文件链接）
+- **变更记录表**：追加本次运行记录（日期 + 新建规则数/挂载案例数/修订项摘要）
+
+### 5.4 自检清单
+
+对每条产出逐项自检（不通过则回到 Phase 3 修订）：
+
+| # | 检查项 |
+|---|--------|
+| 1 | 规则体（来源案例区之外）无具体库名 / API 名 |
+| 2 | 每个检查点可独立判定（读源码能给出 是/否/疑似） |
+| 3 | 适用范围含可执行的预筛特征（依赖/文件/API 特征） |
+| 4 | 与现有规则无"问题本质"层面的重叠 |
+| 5 | 案例信息完整（现象 / 根因 / 修复方式 / PR 链接） |
+| 6 | 严重级别有判定依据（high=功能不可用；medium=特定场景失效；low=体验问题） |
+| 7 | INDEX.md 索引行与实际文件一一对应（链接可跳转） |
+| 8 | 新建/修订条目状态均为 `draft` |
+
+---
+
+## Phase 6：输出与审核指引
+
+### 6.1 审核指引（写入 generalization-log.md）
+
+每次运行在 `generalization-log.md` **追加**一节，包含：
+
+```markdown
+# 泛化运行 — {日期}
+
+## 产出清单
+- 新建规则: {R-XX 列表 + 文件路径}
+- 新建案例: {KI-XXX 列表 + 文件路径}
+- 挂载案例: {KI-XXX → R-XX 映射}
+- 修订规则: {R-XX + 修订内容}
+
+## 审核要点
+- 泛化度存疑项: {列出过拟合/过泛化风险条目及原因}
+- 材料不足项: {未获取到 diff 的案例清单}
+- 规则重叠风险: {与现有规则边界模糊的条目}
+
+## 审核操作指引
+1. 逐条审阅 draft 状态的规则/案例文件
+2. 审核通过 → 规则文件改 `- **状态**: active`；案例文件元数据加 `status: active`
+3. 审核不通过 → 修订文件内容或删除文件，并同步删除 INDEX.md 对应索引行
+```
+
+### 6.2 输出确认
+
+完成后输出确认信息：处理案例数、新建规则数、挂载案例数、材料不足数、写入的文件列表（含 INDEX.md 变更摘要）。
+
+---
+
+## 与其他 SKILL 的关系
+
+| SKILL | 关系 |
+|-------|------|
+| `rn-library-known-issue-check`（已知问题检视） | **消费者**：读 INDEX.md 预筛 → 按 `active` 状态规则执行检查，案例作为 few-shot |
+| RN 仓库检视流水线 | 间接关系：本 SKILL 为离线运营工具，**不参与**在线扫描流水线；其产出经人工审核激活后供检视 SKILL 使用 |

package/vendor/Server/Skills/rn-library-issue-generalizer/assets/case-template.md

@@ -1,45 +1,45 @@
-<!-- 案例条目模板：生成 cases/KI-{XXX}-{库名现象}.md 独立文件 -->
-<!-- 案例编号 KI-XXX 全局唯一，三位数字递增 -->
-<!-- 格式二（代码证据式）：错误/正确代码对照是 few-shot 判断的核心依据，必须从实际 PR diff 提取 -->
-
-# KI-{XXX} {库名}：{问题现象简述}
-
-- **元数据**: `rule: {R-XX[, R-XX]}` · `verified: {diff|description-only}` · `source: {dtse|community-issue|self-check}` · `severity: {high|medium|low}` · `status: {draft|active}`
-- **PR**: {修复 PR 完整链接}（{状态}，{核心变更文件数}）
-- **diff 材料**: [../pr-info/{repo}-{number}.md](../pr-info/{repo}-{number}.md)
-
-## 现象
-
-{原始 issue 描述，保留具体信息}
-
-## 根因
-
-{该案例的机制层根因，与所属规则的"问题本质"呼应}
-
-## 错误代码（修复前{，注明文件与关键缺陷点}）
-
-```{语言}
-{从 PR diff 的删除行/上下文提取，只保留命中判定的关键行，≤15 行；
- 无法获取 diff 时省略本字段并在元数据标记 verified: description-only}
-```
-
-## 正确代码（修复后{，注明关键修复点}）
-
-```{语言}
-{从 PR diff 的新增行提取，只保留体现修复模式的关键行，≤15 行；
- 可用注释标注 ①②③ 分步说明修复链路}
-```
-
-## 修复方式
-
-{从 PR diff 提炼的可迁移修复模式}
-
-<!--
-字段说明：
-- rule: 所属规则编号（一案例可挂多条规则，逗号分隔；每条规则文件中放索引行，案例文件只存一份）
-- verified: diff=基于实际 patch 验证（有错误/正确代码）；description-only=仅基于描述（无代码字段）
-- source: dtse=DTSE代提；community-issue=社区 issue；self-check=内部自检发现
-- severity: 该案例的严重级别（可能与规则默认级别不同）
-- status: draft=泛化产出待审核；active=人工审核通过（检视 SKILL 只消费 active）
-- 错误/正确代码约束：每段 ≤15 行；只留命中判定关键行；语言标注正确（typescript/cpp 等）
--->
+<!-- 案例条目模板：生成 cases/KI-{XXX}-{库名现象}.md 独立文件 -->
+<!-- 案例编号 KI-XXX 全局唯一，三位数字递增 -->
+<!-- 格式二（代码证据式）：错误/正确代码对照是 few-shot 判断的核心依据，必须从实际 PR diff 提取 -->
+
+# KI-{XXX} {库名}：{问题现象简述}
+
+- **元数据**: `rule: {R-XX[, R-XX]}` · `verified: {diff|description-only}` · `source: {dtse|community-issue|self-check}` · `severity: {high|medium|low}` · `status: {draft|active}`
+- **PR**: {修复 PR 完整链接}（{状态}，{核心变更文件数}）
+- **diff 材料**: [../pr-info/{repo}-{number}.md](../pr-info/{repo}-{number}.md)
+
+## 现象
+
+{原始 issue 描述，保留具体信息}
+
+## 根因
+
+{该案例的机制层根因，与所属规则的"问题本质"呼应}
+
+## 错误代码（修复前{，注明文件与关键缺陷点}）
+
+```{语言}
+{从 PR diff 的删除行/上下文提取，只保留命中判定的关键行，≤15 行；
+ 无法获取 diff 时省略本字段并在元数据标记 verified: description-only}
+```
+
+## 正确代码（修复后{，注明关键修复点}）
+
+```{语言}
+{从 PR diff 的新增行提取，只保留体现修复模式的关键行，≤15 行；
+ 可用注释标注 ①②③ 分步说明修复链路}
+```
+
+## 修复方式
+
+{从 PR diff 提炼的可迁移修复模式}
+
+<!--
+字段说明：
+- rule: 所属规则编号（一案例可挂多条规则，逗号分隔；每条规则文件中放索引行，案例文件只存一份）
+- verified: diff=基于实际 patch 验证（有错误/正确代码）；description-only=仅基于描述（无代码字段）
+- source: dtse=DTSE代提；community-issue=社区 issue；self-check=内部自检发现
+- severity: 该案例的严重级别（可能与规则默认级别不同）
+- status: draft=泛化产出待审核；active=人工审核通过（检视 SKILL 只消费 active）
+- 错误/正确代码约束：每段 ≤15 行；只留命中判定关键行；语言标注正确（typescript/cpp 等）
+-->