source-kb 0.2.2__py3-none-any.whl

skills/kb-init/rules.md

@@ -0,0 +1,187 @@
+# kb-init 主会话调度规则
+
+> 本文件供主会话在调度过程中参考。子代理规则已内嵌到 `templates/` 模板中。
+
+## 1. 核心原则
+
+主会话是**调度员**，通过工具链脚本获取信息、派发子代理、监控进度。
+子代理是**执行者**，负责读源码、分析内容、生成文档。
+
+### 1.1 硬规则速查
+
+| 编号 | 规则 | 违反后果 |
+|------|------|---------|
+| R1 | 禁止编造，所有内容必须有源码出处 | 文档作废 |
+| R4 | prompt 必须通过 render_prompt 渲染 | 重新构造 |
+| R5 | 每步必须过 Gate | 回退重做 |
+| R6 | 禁止降级补写，失败→拆分重试 | 流程违规 |
+| R8 | 文件清单预提取，子代理不做文件发现 | 子代理空转 |
+| R9 | Write-as-you-go，每 1-2 个包立即写盘 | 超时丢失 |
+| R10 | 锁纪律，无论成功失败必须释放 `.kb-lock` | 死锁 |
+| R11 | 禁止走捷径，不得跳过子代理或合并任务 | 质量降级 |
+
+### 1.2 主会话操作边界
+
+**允许**：
+- 执行工具链脚本（render_prompt、render_dispatch_plan、extract_file_list、plan_subagents、check_progress、coverage_check）
+- 读取脚本输出的统计数据（文件数、方法数、行数、覆盖率）
+- 创建目录结构、管理锁文件
+- 派发子代理（invokeSubAgent）
+- 读取流程控制文件（step/rules/SKILL）
+
+**禁止**：
+- 读取 `.java` 源码文件内容
+- 读取骨架 JSON 的具体条目（统计数字和 summary 除外）
+- 直接写 `knowledge/` 下的 .md 文档
+- 在子代理失败后自己补写文档内容
+- 合并多个子代理为一个以"减少调用次数"
+- 在 Gate 3A 用户确认前执行子代理
+
+### 1.3 工具链保障
+
+以下信息获取已由工具链自动处理，主会话无需手动操作：
+
+| 需求 | 命令 | 说明 |
+|------|------|------|
+| 骨架提取 | `source-kb extract` | 自动选择解析器 |
+| 骨架统计 | `source-kb query stats` | 文件数/方法数/行数 |
+| 文件分类 | `source-kb file-list` | 按 doc-type 预提取 |
+| 覆盖率检查 | `source-kb file-list --coverage-check` | 确认无遗漏 |
+| 低置信度审计 | `source-kb audit` | 识别可能分错的文件 |
+| 全局元数据 | `source-kb metadata` | 术语表 + 依赖摘要 |
+| 分派计划 | `source-kb dispatch` | 一键生成表格 |
+| 过期文件检测 | `source-kb stale-files` | 识别遗留文件 |
+| prompt 渲染 | `source-kb render --mode readwrite` | 自动注入骨架 + 元数据 |
+| 合并后精炼 | `source-kb post-merge` | 去重 + 术语一致性 + 锚点 |
+| 拆分反馈 | `source-kb record-feedback` | 记录质量分数 |
+| 数值抽样 | `source-kb validate sampling` | 枚举值/字段名抽样验证 |
+
+## 2. 拆分规则
+
+### 2.1 拆分阈值
+
+> **唯一规则源**：`core/skeleton/split.py`
+> 判断优先级：**字节数 > 行数 > 文件数**（文件数仅作上限保护）。
+
+| 模式 | 字节上限 | 行数上限 | 文件数上限 |
+|------|---------|---------|-----------|
+| Agent（readwrite） | 500KB | 10000 行（business-logic: 6000） | 80/分片 |
+| CLI（output-only） | 300KB | 8000 行（business-logic: 2000） | 80/分片 |
+
+### 2.2 智能拆分优先级链
+
+拆分决策按以下优先级链执行，前序成功则跳过后续：
+
+| 优先级 | 策略 | 条件 | 成本 |
+|--------|------|------|------|
+| 1 | 缓存命中 | 骨架 hash 未变 | 0 |
+| 2 | 社区检测 | 骨架含 imports/fields | 0 |
+| 3 | LLM 智能拆分 | 社区检测无有效方案 | ~$0.01 |
+| 4 | 代码规则拆分 | LLM 失败 | 0 |
+| 5 | 简单拆分 | 以上全部失败 | 0 |
+
+**社区检测**（`split_by_community.py`）：
+- 从骨架 imports、@Autowired 字段、extends/implements、方法体调用构建依赖图
+- 检测 Kafka topic / Feign client 共享的隐式依赖
+- Louvain 社区检测算法识别高内聚文件组
+- resolution 参数从历史反馈自动优化
+
+### 2.3 业务代理拆分（强制）
+
+**硬约束**：超过阈值必须拆分，禁止因并发限制降级为单代理。
+
+| 模式 | ≤阈值 | 2倍阈值 | 3倍阈值 | >3倍 |
+|------|-------|--------|--------|------|
+| Agent | 1 代理 | 2 代理 | 3 代理 | 4-6 代理 |
+| CLI | 1 代理 | 2 代理 | 3 代理 | 4-6 代理 |
+
+```shell
+# 获取拆分方案（通过 dispatch-preview 间接调用 split_plan）
+source-kb dispatch \
+  --kb {kb} --module {module_name} --mode {mode}
+```
+
+### 2.4 文件清单覆盖验证 + 置信度审计（必须执行）
+
+文件清单提取后，必须运行 coverage-check 确认所有文件已被分类（详见 step-02 §2.7）：
+
+```shell
+source-kb file-list \
+  --skeleton "{module_dir}/.meta/skeleton/skeleton.json" \
+  --preset "{preset}" --coverage-check \
+  --module-dir "{module_dir}" \
+  --output "{module_dir}/.meta/file-lists/coverage-report.txt"
+```
+
+**Phase A — 未分类文件**：
+- Uncovered = 0 → 继续
+- Uncovered > 0 → 分派子代理分类，追加到 file-lists，规则持久化需用户确认（详见 step-02 §2.7）
+
+**Phase B — 低置信度审计**：
+- 运行置信度评估（`find_suspicious_files(entries, preset, threshold=0.7)`）
+- suspicious = 0 → 继续
+- suspicious > 0 → 分派子代理审计，修正 file-lists，写入 exclude_if 规则（详见 step-02 §2.7b）
+
+### 2.5 特殊文档拆分
+
+| 文档类型 | 拆分条件 | 策略 |
+|---------|---------|------|
+| architecture | 输入 > 20KB | 20-40KB 拆 2，> 40KB 拆 3 |
+| data-models | 骨架 > 100KB | 100-200KB 拆 2，> 200KB 拆 3-4 |
+
+### 2.6 全局元数据注入
+
+每个分片 prompt 自动注入（由 `render_prompt` 调用 `global_metadata.py`）：
+- **术语表**：类名 + JavaDoc 首行，确保各分片术语一致
+- **依赖摘要**：核心类的注入关系图
+- **交叉引用提示**：哪些类属于其他文档类型
+
+### 2.7 合并后精炼
+
+分片合并后自动执行（`post_merge.py`）：
+- 重复段落检测与移除（>80 字符的语义重复）
+- 术语一致性修复（别名→标准名替换）
+- 章节锚点补充（GitHub-style slugify）
+
+Agent 模式需手动执行（见 step-03 §3.8）。
+
+## 3. 失败恢复
+
+### 3.1 状态判定
+
+```shell
+source-kb validate consistency \
+  --module-dir "{module_dir}" --preset "{preset}" --cleanup
+```
+
+| 状态 | 判定条件 | 处理 |
+|------|---------|------|
+| ✅ 完成 | progress 含 DONE + 文档 > 1KB | 跳过 |
+| ⚠️ 空转 | 子代理返回但文档不存在或 < 1KB | 拆分重试 |
+| ⚠️ 中断 | progress 含 START 无 DONE | 拆分重试 |
+| ❌ 报错 | progress 含 ERROR | 分析原因后重试 |
+
+### 3.2 恢复策略
+
+1. 分析空转原因（输入过大？模型能力不足？偶发？）
+2. 按拆分规则重新拆分 → 再次执行
+3. 连续 2 次空转 → 标记 `FAILED`，继续后续文档
+4. **禁止主会话降级补写**（R6）
+
+## 4. 锁协议
+
+锁文件：`{knowledge_dir}/.kb-lock`
+
+- 获取：写入 `{"pid": <pid>, "timestamp": <time>, "operation": "kb-init"}`
+- 超时：120 分钟（超时 → 视为过期，删除重建）
+- 释放：流程结束（成功或失败）必须删除
+
+## 5. 异常交互
+
+| 严重级别 | 前缀 | 处理 |
+|---------|------|------|
+| 成功 | ✅ | 继续 |
+| 需决策 | ⚠️ | 暂停，列选项，等用户回复 |
+| 致命 | ❌ | 终止，释放锁，报告原因 |
+
+**自动降级**（不询问用户）：单个 JAR 下载失败、骨架单文件解析失败、可选文档未触发、空模块跳过。

skills/kb-init/steps/step-01-scope.md

@@ -0,0 +1,62 @@
+# Step 1: 范围与准备
+
+## 1.1 获取知识库锁
+
+按 `rules.md` §4 锁协议获取 `{knowledge_dir}/.kb-lock`，超时 120 分钟。
+
+```shell
+# 检查锁文件
+cat "{knowledge_dir}/.kb-lock" 2>/dev/null
+# 不存在或已超时 → 创建
+echo '{"pid": '$$', "timestamp": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'", "operation": "kb-init"}' > "{knowledge_dir}/.kb-lock"
+```
+
+## 1.2 读取配置
+
+```
+读取 kb-project.yaml 配置文件
+```
+
+从中提取：
+- `knowledge_dir`：知识库输出目录
+- `preset`：语言 preset（如 `java-spring`）
+- `repos`：模块列表（name、url/local、branch、type）
+- `maven_repo`（如有）：私服配置
+
+## 1.3 配置校验（CP-0）
+
+逐项校验，失败按严重级别处理：
+
+| 检查项 | 校验方式 | 失败处理 |
+|--------|---------|---------|
+| `knowledge_dir` 可写 | 尝试创建目录 | ❌ 致命：提示修改路径 |
+| `preset` 存在 | 检查 `presets/{preset}/` | ❌ 致命：列出可用 preset |
+| Python 版本 3.10-3.12 | `py -3.12 --version` 或 `python3 --version` | ❌ 致命：tree-sitter-languages 不支持 3.13+，提示安装 3.12 |
+| `tree-sitter-languages` 已安装 | `py -3.12 -c "import tree_sitter_languages"` | ❌ 致命：提示 `py -3.12 -m pip install tree-sitter-languages` |
+| `maven_repo.url` 可达 | HTTP HEAD（5s 超时） | ⚠️ 询问用户（跳过/修正/终止） |
+| `maven_repo.auth` 有效 | 认证请求 | ⚠️ 询问用户 |
+
+> **Python 版本约束**：`tree-sitter-languages` 仅支持 Python 3.10-3.12。Windows 上使用 `py -3.12` 启动器，Linux/macOS 使用 `python3.12`。`source-kb` CLI 命令已通过 `pip install source-kb` 安装，直接使用 `source-kb {subcommand}` 即可。
+
+> **tree-sitter 是质量底线**：没有 tree-sitter，骨架提取会降级到 regex，导致：
+> - 无 imports 数据 → 无依赖图 → 无社区检测拆分
+> - 无 annotation_values → 无 Kafka/Feign 隐式依赖检测
+> - 无 JavaDoc 提取 → 无全局术语表
+> - 方法边界不准确 → 复杂度评分失真
+
+## 1.4 确定范围
+
+- 用户指定 `--kb` → 直接使用
+- 未指定 → 列出可用知识库让用户选择
+- 用户指定 `--module` → 单模块模式
+- 未指定 → 全自动执行所有模块
+
+## Gate 1 检查清单
+
+- [ ] `.kb-lock` 已创建
+- [ ] `kb-project.yaml` 配置有效
+- [ ] `tree-sitter-languages` 已安装（质量底线）
+- [ ] 目标知识库和模块列表已确定
+- [ ] preset 目录存在
+
+全部通过 → 加载 `step-02-source.md`

skills/kb-init/steps/step-02-source.md

@@ -0,0 +1,410 @@
+# Step 2: 源码获取与骨架提取
+
+## 执行顺序总览
+
+```
+2.1 获取源码 [必须]
+  → 2.2 源码构建 [条件: build.enabled=true]
+  → 2.3 依赖解析 [条件: 有 maven_repo]
+  → 2.4 提取骨架 [必须]
+  → 2.5 依赖骨架 [条件: 有 deps 目录]
+  → 2.6 文件清单提取 [必须]
+  → 2.7 未分类文件处理 [必须]
+  → 2.8 覆盖率预检 [必须]
+  → 2.9 全局元数据预生成 [必须]
+  → 2.10 兄弟模块依赖 [必须]
+  → Gate 2
+```
+
+### 条件步骤速查
+
+| 步骤 | 执行条件 | 不满足时输出 |
+|------|---------|-------------|
+| 2.2 | `preset.yaml` → `build.enabled: true` | `[跳过] 2.2：build.enabled=false` |
+| 2.3 | `kb-project.yaml` 含 `maven_repo` | `[跳过] 2.3：无 maven_repo 配置` |
+| 2.5 | `.source-cache/{module}-deps/` 存在 | `[跳过] 2.5：无依赖源码` |
+
+### 必须执行清单（Agent 逐条对照）
+
+- [ ] 2.1 获取源码 + CP-1
+- [ ] 2.4 提取骨架 + CP-3
+- [ ] 2.6 文件清单提取（全部 doc-type）
+- [ ] 2.7 未分类文件处理（coverage-check → Uncovered=0）
+- [ ] 2.7b 低置信度分类审计（suspicious=0 或已修正）
+- [ ] 2.8 覆盖率预检
+- [ ] 2.9 全局元数据预生成（`.meta/global-metadata.md`）
+- [ ] 2.10 兄弟模块依赖
+
+---
+
+## 2.1 获取源码 [必须]
+
+### 多仓库模式（默认）
+
+```shell
+git clone --depth 1 --single-branch -b {branch} "{url_or_local}" ".source-cache/{module_name}"
+# 已存在时：
+git -C ".source-cache/{module_name}" pull
+```
+
+### 单仓库多模块模式（`structure: "monorepo"`）
+
+仓库只 clone 一次到 `.source-cache/{repo_name}/`，后续各模块共享同一份源码：
+
+```shell
+# 首次 clone（整个仓库）
+git clone --depth 1 --single-branch -b {branch} "{url}" ".source-cache/{repo_name}"
+# 已存在时：
+git -C ".source-cache/{repo_name}" pull
+```
+
+各模块的源码路径为 `.source-cache/{repo_name}/{module_path}`（`module_path` 来自 `kb-project.yaml` 的 `modules[].path`）。
+
+> **跨平台**：PowerShell 中去掉 `#` 注释行。
+
+安全校验：`{module_name}` 不得含 `..`、`/`、`\`。
+
+**CP-1 检查**：
+
+| 结果 | 处理 |
+|------|------|
+| `.git` 存在 + 源码文件 > 0 | ✅ 继续 |
+| `.git` 存在 + 源码文件 = 0 | ⚠️ 询问用户 |
+| `.git` 不存在 | ❌ 询问用户 |
+
+---
+
+## 2.2 源码构建 [条件: `build.enabled: true`]
+
+> 不满足条件 → 输出 `[跳过] 2.2：build.enabled=false`，进入 2.3
+
+```shell
+cd ".source-cache/{module_name}"
+mvn compile -DskipTests -q
+```
+
+| 结果 | 处理 |
+|------|------|
+| exit 0 | ✅ jQAssistant 可用 |
+| exit ≠ 0 / 超时 | ⚠️ 不阻塞，降级到 tree-sitter |
+| 无 pom.xml | 跳过 |
+
+---
+
+## 2.3 依赖解析 [条件: 有 `maven_repo`]
+
+> 不满足条件 → 输出 `[跳过] 2.3：无 maven_repo 配置`，进入 2.4
+
+详见 `presets/{preset}/workflow-extensions.md` §1。
+
+**CP-2**：`resolve_jar_sources.py` 输出 JSON 的 `status`/`failed`。部分失败 → ⚠️ 询问用户。
+
+---
+
+## 2.4 提取骨架 [必须]
+
+根据文件数选择模式：
+
+| 文件数 | 模式 | 命令 |
+|--------|------|------|
+| < 50 | 单文件 | `--compact` |
+| 50-150 | 按包分片 | `--split-by-package` |
+| > 150 | 概要 + 完整 | `--summary` 然后 `--compact` |
+
+```shell
+# > 150 文件时执行两次：
+source-kb extract \
+  --repo "{repo}" --preset {preset} --summary \
+  --output "{module_dir}"
+
+source-kb extract \
+  --repo "{repo}" --preset {preset} \
+  --output "{module_dir}"
+
+# < 150 文件时执行一次（默认 compact）：
+source-kb extract \
+  --repo "{repo}" --preset {preset} \
+  --output "{module_dir}"
+```
+
+> **单仓库多模块**：添加 `--subpath {module_path}` 限定提取范围到模块子目录。
+> 例如：`--subpath services/user-service`。骨架中的文件路径为模块相对路径。
+
+> **注意**：`--output` 接受的是**模块目录**（如 `knowledge/promotion/promotion-common`），
+> 脚本会自动在 `.meta/skeleton/` 下生成 `skeleton.json` 和 `skeleton-summary.json`。
+
+**CP-3 检查**：
+- `status: "ok"` + `methods > 0` → ✅ 继续
+- `methods = 0` → 自动降级（跳过业务文档）
+- 脚本异常 → ❌ 询问用户
+
+**骨架大小 → 子代理读取策略**（R2）：
+
+| 大小 | 读取方式 |
+|------|---------|
+| < 50KB | 直接读 skeleton.json |
+| 50-200KB | 只读 summary.json |
+| > 200KB | 只读 summary，分批 offset/limit |
+
+---
+
+## 2.5 依赖骨架 [条件: 有 deps 目录]
+
+> 不满足条件 → 输出 `[跳过] 2.5：无依赖源码`，进入 2.6
+
+详见 `presets/{preset}/workflow-extensions.md` §7。
+
+---
+
+## 2.6 文件清单提取 [必须]
+
+为**所有** doc-type 提取文件清单，同时判断可选文档触发条件。
+
+```shell
+# 一次性提取所有类型（bash 示例）
+for DOC_TYPE in source-tree-analysis data-models enums-and-constants business-logic \
+  api-contracts architecture utils messaging caching external-integrations \
+  scheduled-tasks database-access aop-and-interceptors async-and-events error-handling security observability; do
+    source-kb file-list \
+      --skeleton "{module_dir}/.meta/skeleton/skeleton.json" \
+      --preset "{preset}" --doc-type "$DOC_TYPE" \
+      --source-cache ".source-cache/{module_name}" \
+      --output "{module_dir}/.meta/file-lists/${DOC_TYPE}.txt"
+done
+```
+
+**触发判定**：文件数 > 0 → 该文档需要生成。文件数 = 0 → 跳过。
+
+> 不要用 grep 检测触发条件。`extract_file_list` 基于骨架注解精确匹配，排除测试文件。
+
+---
+
+## 2.7 未分类文件处理 [必须]
+
+> ⚠️ **此步骤不可跳过。** 未分类文件 = 子代理遗漏源码 = 文档覆盖率不达标。
+
+### 执行 coverage-check
+
+```shell
+source-kb file-list \
+  --skeleton "{module_dir}/.meta/skeleton/skeleton.json" \
+  --preset "{preset}" --coverage-check \
+  --module-dir "{module_dir}" \
+  --output "{module_dir}/.meta/file-lists/coverage-report.txt"
+```
+
+### 判定与处理
+
+| 结果 | 处理 |
+|------|------|
+| Uncovered = 0 | ✅ 进入 2.8 |
+| 全部在 `coverage_skip_patterns` 中（如 `.mvn/`） | ✅ 跳过 |
+| 存在非跳过的 Uncovered 文件 | → 执行分类（见下方） |
+
+### 分类流程（分派子代理执行）
+
+> 主会话是调度员，不直接判断文件归属。分类判断由子代理完成。
+
+1. **构建分类 prompt**：主会话从骨架提取未分类文件的摘要（类名、注解、方法名、字段类型、路径），拼接现有分类规则，构建 prompt
+2. **分派子代理**：通过 `invokeSubAgent` 派发分类任务，子代理返回 JSON 格式的分类结果
+3. **追加到 file-lists**（立即执行）：主会话将分类结果中的文件路径追加到对应的 `.meta/file-lists/{doc-type}.txt`
+4. **规则持久化**（⚠️ 需用户确认）：
+   - 向用户展示建议的规则及影响范围
+   - 用户确认 → 写入 `presets/{preset}/custom_rules.yaml`
+   - 用户拒绝 → 只保留 file-list 追加（仅影响本次执行）
+5. **验证**：重新运行 coverage-check 确认 Uncovered = 0
+
+**子代理分类 Prompt 格式**：
+
+System:
+```
+你是一个 Java/Spring Boot 源码分类专家。
+对无法被现有规则自动分类的源码文件进行判断。
+每个文件必须归入至少一个分类。优先归入现有分类。
+输出严格 JSON 格式。
+```
+
+User（主会话拼接）：
+- 现有分类规则摘要（从 preset.yaml 的 file_classification 提取）
+- 未分类文件骨架摘要（每个文件：路径、类名、注解、方法名前8个、字段类型前5个）
+- 输出格式要求（见下方）
+
+**子代理输出格式**：
+```json
+{
+  "classifications": [
+    {
+      "file": "com/example/handler/OrderHandler.java",
+      "category": "service",
+      "reason": "处理订单业务逻辑",
+      "rule_suggestion": {
+        "target_category": "service",
+        "action": "patterns_append",
+        "value": "/handler/"
+      }
+    }
+  ]
+}
+```
+
+**规则精确度要求**（决定是否适合持久化）：
+
+| 规则类型 | 精确度 | 适合持久化 | 示例 |
+|---------|--------|-----------|------|
+| class_annotations | 高 | ✅ | `@TypeHandler` |
+| field_types | 高 | ✅ | `TypeHandler` |
+| 带包名前缀 pattern | 中 | ⚠️ 需确认 | `/dao/handlers/` |
+| 纯目录名 pattern | 低 | ❌ 不推荐 | `/handlers/` |
+
+---
+
+## 2.7b 低置信度分类审计 [必须]
+
+> ⚠️ **此步骤不可跳过。** 规则命中但命中错误 = 文件出现在错误的文档中 = 文档质量下降。
+
+### 目的
+
+2.7 解决"漏网之鱼"（未分类文件），2.7b 解决"错误分类"——规则命中了但命中错了。
+
+典型误判场景：
+- `RedisLockHelper.java` 在 `/util/` 路径 → 被归入 util，实际应归 cache
+- `KafkaProducerConfig.java` 在 `/producer/` 路径 → 被归入 kafka，实际是 config
+- `DataSourceConfig.java` 有 `@Data` 注解 → 被归入 model，实际是 config
+
+### 执行置信度评估
+
+```python
+from core.skeleton.classify import find_suspicious_files
+from core.preset import load_preset
+from core.skeleton.query import load_skeleton
+from pathlib import Path
+
+preset = load_preset("{preset}")
+entries = load_skeleton(Path("{module_dir}/.meta/skeleton/skeleton.json"))
+suspicious = find_suspicious_files(entries, preset, threshold=0.7)
+# suspicious: list[ConfidenceEntry]，每项有属性：
+#   .file: str          — 文件路径
+#   .categories: list   — 命中的分类列表
+#   .confidence: float  — 置信度分数
+#   .match_reasons: list — 命中原因
+#   .suspicious_signals: list — 可疑信号
+```
+
+### 判定与处理
+
+| 结果 | 处理 |
+|------|------|
+| suspicious = 0 | ✅ 进入 2.8 |
+| suspicious > 0 | → 分派子代理审计 |
+
+### 子代理审计 Prompt
+
+**System**：
+```
+你是一个 Java/Spring Boot 源码分类审计专家。
+以下文件已被规则自动分类，但置信度较低。请审查分类是否正确。
+如果正确放入 confirmed，如果错误放入 corrections。
+输出严格 JSON 格式。
+```
+
+**User**（由主会话拼接）：
+1. 可用分类列表
+2. 每个可疑文件的信息：
+   - 文件路径
+   - 当前分类 + 命中原因（如 "patterns 兜底"）
+   - 置信度分数 + 可疑信号
+   - 类名、注解、方法名（前6个）、字段类型（前5个）
+
+**输出格式**：
+```json
+{
+  "corrections": [
+    {
+      "file": "com/example/util/RedisLockHelper.java",
+      "current_category": "util",
+      "correct_category": "cache",
+      "reason": "核心逻辑是 Redis 分布式锁",
+      "rule_suggestion": {
+        "target_category": "util",
+        "action": "add_exclude_if",
+        "condition": "field_types_contains",
+        "value": "RedissonClient"
+      }
+    }
+  ],
+  "confirmed": ["file1.java", "file2.java"]
+}
+```
+
+### 结果处理
+
+1. **修正文件清单**：将 corrections 中的文件从错误分类的 file-list 移除，添加到正确分类的 file-list
+2. **写入 exclude_if 规则**：将 `rule_suggestion` 写入 `presets/{preset}/custom_rules.yaml`
+3. **验证**：重新运行置信度评估确认无新增低置信度文件
+
+---
+
+## 2.8 覆盖率预检 [必须]
+
+```shell
+source-kb validate coverage check \
+  --skeleton {module_dir}/.meta/skeleton/skeleton.json \
+  --docs-dir {module_dir} --type {module_type}
+```
+
+**目的**：
+- 确认每个 public 方法有文档归属
+- 识别 high 复杂度方法（子代理必须读源码的方法）
+
+**high 方法识别条件**：
+- `complexity: "high"`
+- 含 Lua 脚本（constants 含 SCRIPT/LUA/ARGV/KEYS）
+- 含内嵌 SQL（constants 含 SELECT/INSERT/UPDATE/DELETE）
+- 分布式 ID/池化（方法名含 generate/pool/allocate/batch 且 line_count > 3）
+- 状态机（branches > 5 且多枚举引用）
+- 复杂 @Bean（line_count > 20）
+- medium 且 line_count > 20
+
+> 初始化阶段覆盖率 = 0% 是预期的（尚无文档），此步骤主要提取 high 方法列表。
+
+---
+
+## 2.9 全局元数据预生成 [必须]
+
+骨架提取完成后，预生成全局元数据文件（术语表 + 依赖摘要），供后续所有子代理 prompt 共享：
+
+```shell
+source-kb metadata \
+  --module-dir "{module_dir}" --module-name "{module_name}"
+```
+
+输出：`{module_dir}/.meta/global-metadata.md`
+
+**作用**：避免每个子代理渲染 prompt 时重复加载 2MB+ 骨架 JSON。Step 3 的 `render_prompt` 会自动读取此文件注入 prompt。
+
+> CLI 模式由 `PregenerateMetadataStep` 自动执行，Agent 模式需手动执行此命令。
+
+---
+
+## 2.10 兄弟模块依赖 [必须]
+
+从本模块 pom.xml 提取 `<dependency>` 的 artifactId，与 `kb-project.yaml` 中同知识库的 repos 交叉匹配。
+
+匹配到的兄弟模块信息将写入子代理 prompt（通过 render_prompt 自动注入）。
+
+---
+
+## Gate 2 检查清单
+
+| # | 检查项 | 对应步骤 |
+|---|--------|---------|
+| 1 | 源码已获取（CP-1 通过） | 2.1 |
+| 2 | 骨架已提取且 methods > 0（CP-3 通过） | 2.4 |
+| 3 | 所有 doc-type 文件清单已生成 | 2.6 |
+| 4 | **未分类文件 Uncovered = 0** | 2.7 |
+| 5 | **低置信度文件已审计（无未处理的 corrections）** | 2.7b |
+| 6 | 覆盖率预检完成 + high 方法列表已提取 | 2.8 |
+| 7 | 全局元数据已预生成（`.meta/global-metadata.md` 存在） | 2.9 |
+| 8 | 兄弟模块依赖已识别 | 2.10 |
+
+**全部通过 → 加载 `step-03-generate.md`**