@ohos-cpf/3rdloop 0.0.1

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

@@ -0,0 +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 使用 |

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

@@ -0,0 +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 等）
+-->

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

@@ -0,0 +1,25 @@
+<!-- 规则条目模板：新建规则时复制本模板，填充所有字段后直接写入 rules/R-{XX}-{规则名}.md -->
+<!-- 状态标记：draft（泛化产出待审核）/ active（人工审核通过，检视 SKILL 消费）/ deprecated（废弃，注明原因） -->
+
+# R-{XX} {规则名，"类"结尾，≤20字，不含具体库名}
+
+- **状态**: active
+- **严重级别**: {high|medium|low}（{判定依据：high=核心功能不可用；medium=特定场景失效；low=体验问题}）
+- **适用范围**: {哪类库适用}
+  - 预筛特征: {可执行的预筛条件，如：依赖特征 / 文件特征 / API 特征，命中才进入深度检查}
+- **问题本质**: {一句话机制层描述，为什么这类问题会发生；禁止出现具体库名/API 名}
+- **检查点**:
+  1. {动词开头，读源码后可独立判定是/否/疑似}
+  2. {...}
+  3. {...}
+- **错误特征**: {源码中命中此类问题的典型形态，供模式匹配}
+- **正确特征**: {修复后的代码形态，供对照判定}
+
+## 来源案例
+
+<!-- 案例索引行：详情在 cases/ 下的独立文件（格式二），此处只放索引 -->
+<!-- 一案例挂多条规则时，各规则文件中都放索引行，案例文件只存一份 -->
+
+| 编号 | 库 | 现象 | 案例文件 |
+|------|-----|------|----------|
+| KI-{XXX} | {库名} | {现象简述} | [KI-{XXX}-{库名现象}.md](../cases/KI-{XXX}-{库名现象}.md) |

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

@@ -0,0 +1,61 @@
+# PR 材料获取指南
+
+> `scripts/fetch-pr-info.py` 用于获取 GitCode PR 的元数据与 diff，为根因分析提供修复前后对照材料。
+
+---
+
+## 1. 调用方式
+
+```bash
+python3 scripts/fetch-pr-info.py '{"prUrl": "https://gitcode.com/owner/repo/pull/123", "outputDir": "/absolute/path", "token": "可选"}'
+```
+
+参数（JSON 字符串）：
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `prUrl` | ✅ | GitCode PR 地址，`https://gitcode.com/{owner}/{repo}/pull/{number}` |
+| `outputDir` | ✅ | 知识库根目录（knowledgeDir），材料写入 `{knowledgeDir}/pr-info/` |
+| `token` | ❌ | GitCode API Token，私有仓库/限流时使用 |
+
+---
+
+## 2. 产出文件
+
+| 文件 | 内容 | 用途 |
+|------|------|------|
+| `pr-info/{repo}-{number}.md` | 可读摘要：标题、描述、状态、变更文件列表、逐文件 diff | Agent 根因分析的主要输入 |
+| `pr-info/{repo}-{number}.json` | API 原始响应 | 排查/二次解析用 |
+
+---
+
+## 3. API 端点
+
+GitCode 兼容 GitHub API v3 风格（`https://gitcode.com/api/v5`）：
+
+| 数据 | 端点 |
+|------|------|
+| PR 元数据 | `GET /repos/{owner}/{repo}/pulls/{number}` |
+| 变更文件 | `GET /repos/{owner}/{repo}/pulls/{number}/files`（含 patch 字段） |
+
+- 无 Token 有速率限制；批量获取案例材料时建议传 `token`
+- `files` 接口分页（per_page=100，page 递增），脚本已处理
+
+---
+
+## 4. 降级策略
+
+| 情况 | 处理 |
+|------|------|
+| 私有仓库 401/404 | 脚本返回失败标记；Phase 1.3 走"材料不足"分支 |
+| 速率限制 403/429 | 有 token 时自动重试（间隔递增，最多 3 次）；仍失败走降级 |
+| PR 超大（files>300 或 patch 过大） | 脚本截断 diff 并在摘要中标注"diff 已截断"，保留变更文件全列表 |
+| 网络不可达 | 脚本返回失败标记；走降级分支 |
+
+**降级分支要求**（见 SKILL.md Phase 1.3）：基于问题描述做有限泛化，草稿"审核要点"中必须标注该规则未验证修复 diff。
+
+---
+
+## 5. 本地已有材料复用
+
+若 `{outputDir}/pr-info/{repo}-{number}.md` 已存在，脚本直接跳过获取（幂等）。批量重跑时不会重复请求 API。

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

@@ -0,0 +1,165 @@
+# 规则条目编写指南
+
+> 知识库采用"规则层 + 案例层"两层知识 + "一级索引 + 二级知识"分级存储：**规则**是检查的执行单元（数量收敛），**案例**挂在规则下作为 few-shot 参考与修复指引（持续增厚）。
+
+---
+
+## 1. 知识库分级结构
+
+```
+BadCase/rn/
+├── INDEX.md              # 一级：分类 + 规则/案例索引（Agent 预筛只读此文件）
+├── rules/                # 二级：规则知识（每规则一文件）
+│   └── R-XX-{规则名}.md
+├── cases/                # 二级：案例知识（每案例一文件，格式二）
+│   └── KI-XXX-{库名现象}.md
+└── pr-info/              # 案例原始 PR diff 证据材料
+```
+
+**分级规则**：
+- **一级 INDEX.md**：只含分类、索引表（编号/名称/严重级别/文件链接），不含具体知识；规则分类按问题域划分（媒体与窗口类/资源加载类/流程健壮性类/异步与回调类/工程规范类等，可扩展）
+- **二级 rules/**：每规则一文件，含完整检查知识 + 案例索引行（不含案例详情）
+- **二级 cases/**：每案例一文件；一案例挂多条规则时只存一份，各规则文件放索引行引用
+- **pr-info/**：案例的证据材料，案例文件中链接引用
+
+**INDEX.md 结构**：
+
+```markdown
+# RN 三方库鸿蒙化已知问题知识库 — 一级索引
+
+## 一、规则分类索引
+### {分类名}
+| 编号 | 规则名 | 严重级别 | 案例数 | 规则文件 |
+
+## 二、案例索引
+| 编号 | 库 | 现象简述 | 所属规则 | 验证方式 | 案例文件 |
+
+## 三、变更记录
+| 日期 | 变更 | 说明 |
+```
+
+---
+
+## 2. 规则条目字段规范
+
+| 字段 | 必填 | 约束 |
+|------|------|------|
+| `编号` | ✅ | `R-XX` 两位数字递增，不复用已删除编号 |
+| `规则名` | ✅ | "XX类"结尾的类别名，≤20 字，不含具体库名 |
+| `适用范围` | ✅ | 含**可执行的预筛特征**：依赖特征（package.json 中的依赖名模式）、文件特征（存在某类文件）、API 特征（代码中出现某类调用）。预筛目的是让检视 SKILL 快速判断该规则与当前库是否相关 |
+| `问题本质` | ✅ | 一句话机制层描述：这类问题**为什么**会发生。禁止出现具体库名/API 名 |
+| `检查点` | ✅ | 2-5 条，动词开头（识别/列出/逐项检查/验证），每条读源码后可独立给出 是/否/疑似 |
+| `错误特征` | ✅ | 源码中命中此类问题的典型形态描述（供 Agent 模式匹配） |
+| `正确特征` | ✅ | 修复后的代码形态描述（供 Agent 对照判定） |
+| `严重级别` | ✅ | high / medium / low，及判定依据。high=核心功能不可用；medium=特定场景失效；low=体验问题 |
+| `来源案例` | ✅ | ≥1 条案例（见第 3 节），冷启动时至少 1 条 |
+
+---
+
+## 3. 案例条目字段规范（格式二：代码证据式）
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `案例编号` | ✅ | `KI-XXX` 三位数字递增，全局唯一 |
+| `元数据` | ✅ | 一行式：`rule`（所属规则编号，多条逗号分隔）· `verified`（diff / description-only）· `source`（dtse / community-issue / self-check）· `severity`（high / medium / low）· `status`（draft / active，审核后翻 active） |
+| `库与现象` | ✅ | 保留原始具体信息：库名 + 问题现象（可用原始 issue 描述） |
+| `根因` | ✅ | 该案例的机制层根因（与规则"问题本质"呼应） |
+| `错误代码` | ✅* | 修复前代码片段，从 PR diff 删除行/上下文提取，≤15 行，只保留命中判定关键行（`verified: diff` 时必填） |
+| `正确代码` | ✅* | 修复后代码片段，从 PR diff 新增行提取，≤15 行，可用 ①②③ 注释标注修复链路（`verified: diff` 时必填） |
+| `修复方式` | ✅ | 从 PR diff 提炼的修复模式（可迁移的描述，非逐行复述） |
+| `PR 链接` | ✅ | 修复 PR 完整 URL |
+| `diff 材料` | ✅ | 链接到 `pr-info/{repo}-{number}.md` |
+
+> \* `verified: description-only` 的案例（未获取到 diff）省略代码字段，审核时需重点标注。
+
+**代码证据编写要求**：
+1. **必须来自实际 diff**，禁止凭描述臆造代码——这是"不能只通过描述判断问题"约束的落地
+2. 每段 ≤15 行：只保留体现缺陷模式/修复模式的关键行，删除无关上下文
+3. 语言标注正确（`typescript`/`cpp` 等），ArkTS 代码用 `typescript` 标注
+4. 错误代码中用 `// ←` 箭头注释标出缺陷点；正确代码中用 `①②③` 标注修复步骤
+5. 修复跨多文件时（如 JS 层 + ArkTS 层），两个片段可合并展示并注明各自来源文件
+
+---
+
+## 4. 泛化质量正反例
+
+### 4.1 错误特征/正确特征写法
+
+❌ **过拟合**（只防住原案例）：
+```
+错误特征: 视频全屏时未调用 setPreferredOrientation
+```
+✅ **机制层**：
+```
+错误特征: 库对外声明的能力（全屏/旋转/后台运行等）在鸿蒙侧实现中找不到对应的
+系统调用或配置项，能力声明与实现之间存在断层
+```
+
+### 4.2 检查点写法
+
+❌ **不可判定**：
+```
+检查点: 检查异常处理是否完善
+```
+✅ **可判定**：
+```
+检查点:
+1. 识别库的核心主流程（对外承诺的主功能调用链）
+2. 列出主流程中的附属操作（非核心必需的下载/统计/日志步骤）
+3. 逐项检查附属操作的异常分支：失败时是隔离降级继续，还是 reject/throw 阻断主流程
+```
+
+### 4.3 适用范围写法
+
+❌ **不可预筛**：
+```
+适用范围: 所有库
+```
+✅ **可预筛**：
+```
+适用范围: 主流程中包含网络下载、图片处理、统计上报等附属步骤的库
+（预筛特征: 代码中出现 Promise.all 包装非核心请求 / reject 路径包含附属操作错误码）
+```
+
+---
+
+## 5. 首批规则参考（4 案例泛化示例）
+
+以下为 4 个种子案例的泛化结果示例，供冷启动与后续泛化对齐风格。**正式规则以人工审核后的规则库为准。**
+
+### R-01 能力声明与实现匹配类
+- **适用范围**: 对外声明媒体/窗口/系统能力（全屏、旋转、后台播放、画中画等）的库（预筛特征: README/接口文档含能力声明关键词；JS 层暴露 fullscreen/orientation 相关接口）
+- **问题本质**: 库对外声明的某项能力，在鸿蒙侧实现中缺少对应的系统调用或配置支撑，能力声明与实现之间存在断层
+- **检查点**: ①列出库对外声明的每项能力 ②逐项在鸿蒙侧实现（ArkTS/C++/配置文件）中定位支撑代码 ③无支撑的能力标记为命中
+- **来源案例**: KI-001 webview 视频无法横屏（PR#121）
+
+### R-02 非标准 URI/路径形态覆盖类
+- **适用范围**: 加载本地/网络资源的库（图片、音频、字体、bundle 资源）（预筛特征: 存在 URI 解析/路径拼接逻辑）
+- **问题本质**: 资源加载只覆盖了标准形态（http/https/固定本地路径），遗漏鸿蒙化环境特有的路径形态（热更新沙箱路径、bundle 内资源、content:// 等）
+- **检查点**: ①定位所有资源 URI 解析入口 ②枚举其处理的路径形态分支 ③比对鸿蒙运行环境实际会产生的路径形态，缺失的标记为命中
+- **来源案例**: KI-002 fastImage 热更新图片加载失败（PR#102）
+
+### R-03 附属操作失败降级类
+- **适用范围**: 主流程中包含附属步骤（缩略图、统计、日志、预加载）的库（预筛特征: 主调用链中存在非核心的网络请求或文件操作）
+- **问题本质**: 非关键路径操作的失败被传播到主流程，导致核心功能被附属操作阻断
+- **检查点**: ①识别核心主流程 ②列出主流程中的附属操作 ③逐项检查附属操作异常分支是否隔离降级
+- **来源案例**: KI-003 wechat-lib thumbImageUrl 下载失败阻断分享（PR#15）
+
+### R-04 发布产物自洽类
+- **适用范围**: 所有发布到 OHPM 的库（预筛特征: 存在 oh-package.json5）
+- **问题本质**: 包元信息（version/main/types/files）与实际发布产物不一致，或与官方接入文档不匹配，导致按文档接入直接失败
+- **检查点**: ①核对 oh-package.json5 的 main/types 指向的文件是否存在 ②核对 version 与产物内容是否对应 ③按官方文档的接入步骤走查一遍入口链路
+- **来源案例**: KI-004 geolocation 3.1.1 版本文件不对（PR#24）
+
+---
+
+## 6. 知识库维护约定
+
+1. **直接写入分级目录**：泛化产出直接写入 `rules/`、`cases/` 并更新 `INDEX.md`，不生成单文件草稿快照
+2. **draft → active 状态机制**：新建/修订条目标记 `draft`；人工审核通过后规则文件改 `- **状态**: active`、案例文件元数据加 `status: active`；检视 SKILL 只消费 `active` 条目
+3. **规则只增不删**：失效规则标记 `deprecated` 并注明原因，保留编号
+4. **案例持续挂载**：新案例优先归入已有规则；归入时检查是否需要补充该规则的检查点（追加项标注日期与 draft 待审）
+5. **每次变更记录**：INDEX.md 变更记录表追加（日期 + 新建/挂载/修订摘要）
+6. **编号稳定**：规则编号、案例编号一经合入不再变更，检视报告通过编号引用
+7. **文件命名**：规则 `R-XX-{规则名}.md`、案例 `KI-XXX-{库名现象}.md`，命名与 INDEX 索引一致
+8. **一案例一文件**：复合问题案例（挂多条规则）只存一份案例文件，各规则文件放索引行