source-kb 0.2.2__py3-none-any.whl

skills/kb-init/steps/step-03-generate.md

@@ -0,0 +1,307 @@
+# Step 3: 文档生成（子代理编排）
+
+## 3.1 跨模块依赖排序
+
+多模块时从 pom.xml 构建依赖 DAG，拓扑排序生成（被依赖的先生成）。后生成模块可引用先生成模块的中立文档。
+
+## 3.2 批次编排
+
+对每个模块，按 `doc_types.yaml` 的 `batch` 字段分组生成文档：
+
+- 同 batch 内的文档可并行生成（除非有 `depends_on` 约束）
+- `conditional: true` 的文档需先判断是否触发（骨架中存在相关文件/注解）
+- 跨 batch 必须串行（后续 batch 依赖前序 batch 的输出）
+
+获取当前模块的具体批次计划：
+```shell
+source-kb dispatch \
+  --config kb-project.yaml --kb {kb} --module {module}
+```
+
+## 3.3 拆分决策
+
+### 3.3.1 智能拆分优先级链
+
+拆分决策按以下优先级链执行，前序成功则跳过后续：
+
+| 优先级 | 策略 | 触发条件 | LLM 成本 |
+|--------|------|---------|---------|
+| 1 | 缓存命中 | 骨架 hash 未变 | 0 |
+| 2 | 社区检测 | 骨架含 imports/fields 数据 | 0 |
+| 3 | Agent 智能分组 | delegated 模式，社区检测未产出有效方案 | 0（Agent 自身能力） |
+| 4 | 代码规则拆分 | Agent 分组未执行或失败 | 0 |
+| 5 | 简单拆分 | 以上全部失败 | 0 |
+
+**Agent 智能分组**（优先级 3，Agent 模式专用）：
+
+当 `source-kb dispatch` 输出中出现"待 Agent 分组"时：
+
+1. 读取 `.meta/split-requests/{doc-type}-grouping-request.json`
+2. 根据文件列表和约束条件，按业务域将文件分组
+3. 输出分组结果为 JSON 文件（格式见 request 中的 `output_format`）
+4. 执行验证和回填：
+   ```shell
+   source-kb split-apply \
+     --module-dir "{module_dir}" --doc-type {doc_type} \
+     --groups "{groups_json_path}"
+   ```
+5. 验证通过 → 分片文件写入 `.meta/shards/`
+6. **重新执行 `source-kb dispatch`** 刷新 `dispatch-plan.md` 和 `dispatch-tasks.json`（Agent 模式专属，因为首次 preview 时分组尚未完成；CLI 模式内联调用 LLM，无需此步）：
+   ```shell
+   source-kb dispatch \
+     --config kb-project.yaml --kb {kb} --module {module}
+   ```
+7. 继续 Gate 3A
+8. 验证失败 → 根据错误信息调整分组，重新执行 split-apply
+9. 连续 2 次失败 → fallback 到代码规则拆分（重新执行 `split-files`）
+
+**约束（程序化校验，不通过则拒绝）**：
+- 单分片 ≤ 80 文件
+- 单分片行数 ≤ max_lines（Agent 模式 10000）
+- 最大/最小分片比 < 3x
+- 所有文件必须被分配（不能遗漏）
+- 不能有重复分配
+
+### 3.3.2 拆分阈值
+
+> **唯一规则源**：`core/skeleton/split.py`
+> 拆分判断优先级：**字节数 > 行数 > 文件数**（文件数仅作上限保护）。
+
+**Agent 模式（readwrite）：**
+
+| 业务代码行数 | 策略 |
+|-------------|------|
+| ≤ 6000 | 单代理 |
+| 6001-12000 | 拆 2 个子代理 |
+| 12001-18000 | 拆 3 个子代理 |
+| > 18000 | 拆 4 个子代理 |
+
+**CLI 模式（output-only）：**
+
+| 业务代码行数 | 策略 |
+|-------------|------|
+| ≤ 4000 | 单代理 |
+| 4001-8000 | 拆 2 个子代理 |
+| 8001-12000 | 拆 3 个子代理 |
+| > 12000 | 拆 4 个子代理 |
+
+**硬约束**：业务代码行数超过模式阈值时必须拆分，禁止因并发限制降级为单代理。
+
+### 3.3.3 架构/模型代理拆分
+
+| 文档类型 | 拆分条件 | 策略 |
+|---------|---------|------|
+| architecture | 输入 > 20KB | 20-40KB 拆 2 个，> 40KB 拆 3 个 |
+| data-models | 骨架 > 100KB | 100-200KB 拆 2 个，> 200KB 拆 3-4 个 |
+
+## 3.4 构造分派计划
+
+### 3.4.1 执行模式选择
+
+| 场景 | 使用模式 | 说明 |
+|------|---------|------|
+| AI Agent 在执行 | `--mode readwrite` | 子代理通过工具读写文件 |
+| 通过 CLI 执行 | `--mode output-only` | CLI 调用 LLM API |
+
+**重要：严格按照指定的执行模式执行，不要串台！**
+
+### 3.4.2 Agent 模式构造步骤
+
+> **⛔ 反模式警告：以下行为绝对禁止**
+> - 主会话读取源码文件内容（.java/.xml/.yml）
+> - 主会话读取骨架 JSON 的具体条目（只看统计数字）
+> - 主会话自己写 knowledge/ 下的 .md 文档
+> - 以"效率""精简""context限制"为由跳过子代理
+> - 合并多个子代理为一个以"减少调用次数"
+> - 在 Gate 3A 用户确认前执行任何子代理
+
+**逐步执行：**
+
+1. **生成分派预览**：
+   ```shell
+   source-kb dispatch \
+     --config kb-project.yaml --kb {kb} --module {module}
+   ```
+
+2. **渲染每个子代理的 prompt**（必须 `--mode readwrite`）：
+   ```shell
+   source-kb render \
+     --template subagent-{type}.md \
+     --module {module} --config kb-project.yaml --kb {kb} \
+     --doc-type {doc_type} --mode readwrite \
+     --extra high_methods="..." generated_docs="..."
+   ```
+
+3. **第三批业务代理额外传入**：
+   - `generated_docs`：已生成的第二批文档 `## ` 标题列表
+   - `high_methods`：从 step-02 覆盖率预检提取的 high 方法列表
+
+4. **分片场景的文件清单处理**：
+   当 dispatch-preview 显示某个 doc-type 需要拆分（如 business-logic 拆 5 个）时：
+   - 工具链会在 `.meta/shards/` 下生成分片文件清单（如 `business-logic-shard-01.txt`）
+   - 渲染 prompt 时通过 `--extra file_list_override=".meta/shards/business-logic-shard-01.txt"` 传入
+   - 子代理只读取自己分片的文件清单，不读完整 file-list
+   - 每个分片子代理输出到独立文件（如 `business-logic-shard-01.md`），最后由 §3.7 合并
+
+4. **检查拆分需求**（按 §3.3 规则）
+
+5. **不立即执行** — 将 task 加入分派计划，等 Gate 3A 确认
+
+### 3.4.3 CLI 模式构造步骤
+
+```shell
+source-kb pipeline init --kb {kb} --module {module}
+```
+
+CLI 自动处理拆分决策、并发控制、超时、重试。需要 `LLM_BASE_URL`/`LLM_API_KEY`/`LLM_MODEL` 环境变量。
+
+## Gate 3A: 分派预览确认
+
+所有模块的子代理 task 构造完毕后，**禁止立即执行**。先向用户展示分派计划。
+
+### 展示格式
+
+```
+模块: {module_name}（{source_file_count} 源码文件，{total_lines} 行）
+
+| 批次 | 子代理 | 产出文档 | 输入文件数 | 输入总行数 | 拆分策略 |
+|------|--------|---------|-----------|-----------|---------|
+| 1 | structure | source-tree-analysis.md | 12 | 3200 | 单代理 |
+| 2A | model | data-models.md | 8 | 2100 | 单代理 |
+| 2B | architecture | architecture.md | 15 | 1200 | 单代理 |
+| 3 | business-order | business-logic.md (shard 1) | 14 | 4100 | 社区检测 拆2 |
+| 3 | business-payment | business-logic.md (shard 2) | 12 | 4025 | |
+| 4 | index | index.md | — | — | 单代理 |
+```
+
+### 用户审查关注点
+
+- 输入总字节 > 500KB（Agent）或 > 300KB（CLI）的分片是否已拆分
+- 同一文档各分片字节数是否均衡（最大/最小比 < 3x）
+- 业务代理行数 > 阈值是否已拆分
+- 拆分策略是否合理（社区检测 > LLM > 代码规则）
+- 单代理输入文件数是否 ≤ 80
+
+### 用户操作
+
+- `继续` → 执行所有子代理任务，进入 §3.5
+- 指出具体问题 → 调整分派计划后重新展示
+- `跳过 {module}` → 标记 SKIPPED
+
+## 3.5 执行生成
+
+### Agent 模式
+
+按批次顺序执行子代理任务：
+
+1. 逐批创建子代理，每个子代理接收渲染后的 prompt
+2. 子代理作为文档生成第一责任人：读取源码 → 分析 → 生成文档 → 写入文件
+3. 当前批次所有子代理完成后，进入下一批次
+4. **主会话不直接生成文档**，只负责调度和进度监控
+
+**禁止在 Agent 模式下调用 `source-kb pipeline --action init`**（CLI 模式用于无 Agent 环境）。
+
+### CLI 模式
+
+```shell
+source-kb pipeline init --kb {kb} --module {module}
+```
+
+### 进度监控
+
+每批次子代理启动后执行：
+
+```shell
+source-kb validate consistency --module-dir "{knowledge_dir}"
+```
+
+**卡死检测**：心跳超过 30 秒无更新 → 判定卡死 → 按 §3.6 失败恢复处理。
+
+## 3.6 失败恢复
+
+每批子代理返回后：
+
+1. 扫描 `.meta/progress/` 目录，判定各文档状态
+2. **空转检测**：子代理返回但文档不存在或 < 1KB → 空转
+3. 空转处理：
+   - 分析原因（输入过大？模型不足？偶发？）
+   - 按拆分规则重新拆分 → 再次执行
+   - 连续 2 次空转 → 标记 `FAILED`，继续后续文档
+4. **禁止主会话降级补写**（R6）
+
+| 状态 | 判定条件 | 处理 |
+|------|---------|------|
+| ✅ 完成 | progress 含 DONE + 文档 > 1KB | 跳过 |
+| ⚠️ 空转 | 子代理返回但文档不存在或 < 1KB | 拆分重试 |
+| ⚠️ 中断 | progress 含 START 无 DONE | 拆分重试 |
+| ❌ 报错 | progress 含 ERROR | 分析原因后重试 |
+
+## 3.7 分片合并
+
+所有子代理完成后，合并分片文档：
+
+```shell
+# 自动合并所有分片（CLI 模式由 pipeline 自动执行）
+source-kb merge --dir "{module_dir}"
+
+# 指定前缀和顺序（如 architecture）
+source-kb merge --prefix architecture --order stack,infra --dir "{module_dir}"
+```
+
+合并成功后，**必须删除分片源文件**（避免索引污染和目录混乱）：
+
+```shell
+# 删除已合并的分片 .md 文件（保留 .meta/shards/ 下的文件清单作为审计记录）
+rm -f "{module_dir}"/*-shard-*.md
+```
+
+验证：合并后的主文档存在且 > 1KB，分片文件已删除。
+
+## 3.8 合并后精炼
+
+所有文档生成完毕后（无论是否有分片），执行规则化精炼（去重 + 术语一致性 + 锚点补充）：
+
+```shell
+# Agent 模式：对所有生成的文档执行精炼
+source-kb post-merge --module-dir "{module_dir}"
+```
+
+精炼内容：
+- **去重**：移除合并时产生的重复段落（>80 字符的语义重复）
+- **术语一致性**：将别名替换为标准术语（基于骨架 JavaDoc 提取的术语表）
+- **锚点补充**：为二级标题添加 HTML 锚点，支持交叉引用跳转
+
+> ⚠️ 即使所有文档都是单代理生成（无分片），精炼仍然有价值——锚点补充和术语一致性检查对单代理文档同样适用。
+
+## 3.9 质量反馈记录（可选）
+
+生成完成后记录拆分质量分数，供下次优化拆分参数：
+
+```shell
+python -c "
+from core.skeleton.split_feedback import record_split_result
+from pathlib import Path
+record_split_result(
+    module_dir=Path('{module_dir}'),
+    doc_type='business-logic',
+    strategy='community',  # 或 'llm' / 'package-fallback'
+    resolution=1.0,
+    n_splits=3,
+    coverage_score=0.85,  # 从 step-04 coverage_check 获取
+    quality_score=0.90,   # 从 step-04 validate 获取
+)
+"
+```
+
+## Gate 3B 检查清单
+
+执行以下检查，全部通过后进入 step-04：
+
+- [ ] 所有预期文档状态为 DONE 或 FAILED
+- [ ] FAILED 文档已记录原因（将在最终报告中汇报用户）
+- [ ] 分片文档已合并（§3.7，仅拆分场景）
+- [ ] 合并后精炼已执行（§3.8，**所有文档都需要**，包括单代理生成的）
+- [ ] 进度文件状态一致（无 START 无 DONE 的残留）
+- [ ] 每个生成的 .md 文件 > 1KB
+
+全部通过 → 加载 `step-04-quality.md`

skills/kb-init/steps/step-04-quality.md

@@ -0,0 +1,92 @@
+# Step 4: 质量校验
+
+所有文档生成完毕后，依次执行以下校验。任一校验不通过 → 修复后重新校验，不跳过（R5）。
+
+## 4.1 覆盖率校验
+
+```shell
+# 单文件骨架
+source-kb validate coverage check \
+  --skeleton {module_dir}/.skeleton.json --docs-dir {module_dir} --type {module_type}
+
+# 分片目录骨架
+source-kb validate coverage check \
+  --skeleton-dir {module_dir}/.skeleton/ --docs-dir {module_dir} --type {module_type}
+```
+
+| 覆盖率 | 处理 |
+|--------|------|
+| ≥ 80% | ✅ 通过 |
+| 60%-80% | 自动补充（最多 2 轮），仍不达标 → ⚠️ 询问用户 |
+| < 60% | ❌ 询问用户 |
+
+注意：`coverage_check.py` 扫描 `--docs-dir` 下所有 .md 文件，`architecture.md` 中的配置类方法、`data-models.md` 中的枚举方法都计入覆盖率。
+
+## 4.1b 数值抽样校验
+
+覆盖率校验通过后，执行骨架感知的数值抽样：
+
+```shell
+# 数值抽样校验（枚举值 + 字段名随机抽样验证）
+source-kb validate sampling --module-dir "{module_dir}"
+```
+
+校验内容：
+- 从骨架随机抽取 3-5 个枚举值，检查是否出现在 `enums-and-constants.md`
+- 从骨架随机抽取 3-5 个实体字段名，检查是否出现在 `data-models.md`
+- `api-contracts.md` 的 H2 章节数与骨架 Controller 数量比对（偏差 > 50% 报警）
+
+| 抽样命中率 | 处理 |
+|-----------|------|
+| 100% | 通过 |
+| 60%-100% | ⚠️ 警告，人工确认是否为文档遗漏 |
+| < 60% | 定位遗漏章节，补充后重新校验 |
+
+## 4.2 引用完整性校验
+
+1. 提取 business-logic.md 中所有 `](./` 和 `](../` 格式的 Markdown 链接
+2. 验证目标文件存在
+3. 含 `#锚点` 的链接，验证目标文档中存在对应 `##`/`###` 标题
+4. 死链 > 0 → 修复锚点或降级为文件级链接，修复后重新校验
+
+## 4.3 重复内容检测
+
+当 business-logic.md > 50KB 时执行：
+
+| 检测模式 | 阈值 | 疑似重复 |
+|---------|------|---------|
+| 缓存 Key 常量模式 | 出现 > 3 次 | 与 caching.md 重复 |
+| JSON 示例代码块 | > 5 个 | 与 messaging.md 重复 |
+| 字段表格头 `\| 字段 \| 类型 \|` | > 3 个 | 与 data-models.md 重复 |
+| 中间件配置参数 | 出现 > 3 次 | 与 architecture.md 重复 |
+
+命中 → 定位重复段落，替换为引用链接。
+
+## 4.4 文档产出质量校验
+
+```shell
+# 校验单个模块
+source-kb validate structure \
+  --module-dir "{module_dir}"
+
+# 校验整个知识库
+source-kb validate structure \
+  --kb-dir "{knowledge_dir}"
+```
+
+校验维度：文件完整性、体量阈值、必需章节、跨文档引用、markdown 结构。
+
+| 评分 | 处理 |
+|------|------|
+| A/B 级 | ✅ 通过 |
+| C 级（1-2 错误） | ⚠️ 修复后重新校验 |
+| D 级（≥ 3 错误） | ❌ 必须修复后才能进入 Step 5 |
+
+## Gate 4 检查清单
+
+- [ ] 方法覆盖率 ≥ 80%（或用户已确认接受当前覆盖率）
+- [ ] 引用完整性校验通过（无死链）
+- [ ] 重复内容检测通过（或已替换为引用链接）
+- [ ] 产出质量校验 A/B 级
+
+全部通过 → 加载 `step-05-finalize.md`

skills/kb-init/steps/step-05-finalize.md

@@ -0,0 +1,132 @@
+# Step 5: 收尾
+
+## 5.1 清理进度文件
+
+覆盖率校验通过后，先终止残留心跳进程，再删除进度标记文件：
+
+```shell
+# 1. 终止残留心跳进程 + 标记过期进度（主会话统一执行，不依赖子代理自行清理）
+source-kb validate consistency \
+  --module-dir "{module_dir}" --preset "{preset}" --cleanup
+
+# 2. 删除已完成的进度文件和 PID 文件
+source-kb validate consistency --module-dir "{module_dir}" --cleanup
+```
+
+保留 `.meta/progress/business-logic-{domain}` 作为业务代理分片的审计记录。
+
+## 5.1b 过期文件检测 [必须]
+
+> ⚠️ **此步骤不可跳过。** 重新生成时，旧文件可能因 skip 规则变更或模块类型调整而不再适用，残留会导致索引污染和文档导航混乱。
+
+扫描 `{module_dir}` 下已有的 `.md` 文件，对比本次 dispatch 计划中预期生成的文档列表，找出"存在但不在计划中"的过期文件。
+
+```shell
+source-kb stale-files \
+  --config kb-project.yaml --kb {kb} --module {module}
+```
+
+### 判定规则
+
+| 文件状态 | 判定 | 处理 |
+|---------|------|------|
+| 在 dispatch 计划中且已生成 | 正常 | 保留 |
+| 在 dispatch 计划中但未生成（FAILED） | 失败 | 已在 Gate 3B 记录 |
+| **不在 dispatch 计划中但文件存在** | 过期/遗留 | → 提示用户 |
+| `.meta/` 下的文件 | 元数据 | 始终保留 |
+| `index.md` | 索引 | 始终保留（即使不在计划中） |
+
+### 用户交互
+
+当检测到过期文件时，向用户展示：
+
+```
+⚠️ 检测到以下文件不在本次生成计划中（可能是历史遗留或 skip 规则变更导致）：
+
+| 文件 | 大小 | 最后修改 | 可能原因 |
+|------|------|---------|---------|
+| api-contracts.md | 7.2KB | 2025-04-10 | base-lib 模块已跳过此文档类型 |
+| messaging.md | 3.1KB | 2025-03-20 | 本次文件分类未触发消息队列文档 |
+
+操作选项：
+1. 全部删除（推荐：保持目录整洁，避免索引污染）
+2. 全部保留（文件不会被索引，但保留在目录中）
+3. 逐个确认
+```
+
+### 自动处理（无需用户确认）
+
+以下情况自动跳过，不提示用户：
+- 文件在 `.meta/` 目录下
+- 文件名以 `.` 开头（隐藏文件）
+- 文件为 `README.md`
+
+## 5.2 共享文档生成
+
+所有模块文档生成完毕后，在 `{knowledge_dir}/_shared/` 下生成跨模块汇总文档：
+
+| 文件 | 触发条件 |
+|------|---------|
+| project-overview.md | 始终生成 |
+| cross-module-calls.md | 模块数 ≥ 2 |
+| error-codes.md | 任一模块有错误码定义 |
+| database-ddl.md | 任一模块有数据模型 |
+
+**生成方式**：主会话串行生成，不委派子代理。原因：
+1. 主会话已持有所有模块文档的上下文
+2. 后台子代理写盘权限不稳定
+3. 共享文档数量少，串行效率足够
+
+## 5.3 失败回滚
+
+开始前如果 knowledge 目录已有 git 仓库且工作区 clean → `git commit` 当前状态作为快照。工作区有未提交变更 → 先 `git stash`。
+
+- git clone 失败 → 跳过该模块
+- 文档生成崩溃 → 已写盘的保留
+- 失败后可 `git reset --hard` 或 `git stash pop` 回滚
+
+## 5.4 释放知识库锁
+
+**无论成功还是失败，必须执行**（R10）：
+
+```shell
+rm -f "{knowledge_dir}/.kb-lock"
+```
+
+## 5.5 构建索引
+
+### Embedding 服务预检
+
+```shell
+source-kb validate links --config kb-project.yaml --module-dir "{module_dir}"
+```
+
+| 退出码 | 处理 |
+|--------|------|
+| 0 | ✅ 继续构建索引 |
+| 1（模型未找到） | ⚠️ 提示 `ollama pull {model}` |
+| 2（服务不可达） | ⚠️ 提示检查 `embedding.base_url` 和 Ollama 服务状态 |
+
+预检失败不阻塞文档生成，仅阻塞索引构建。
+
+### 构建索引
+
+```shell
+# 构建/重建索引
+source-kb index --kb {kb}
+```
+
+## 5.6 验证检索
+
+```shell
+source-kb search --kb {kb} "查询词"
+```
+
+## 5.7 最终报告
+
+向用户汇报：
+- 成功生成的模块和文档列表
+- FAILED 的文档及原因
+- 覆盖率数据
+- 索引构建状态
+- 需要用户手动处理的遗留项

skills/kb-init/templates/core/execution-modes.md

@@ -0,0 +1,29 @@
+# 执行模式指导
+
+本文件定义两种执行模式的声明式指导，由 `render_prompt.py --mode` 注入到子代理 prompt 中。
+模板本身只包含平台无关的内容规则，执行模式指导在渲染时按需注入。
+
+## 模式判定
+
+| 条件 | 执行模式 | 说明 |
+|------|---------|------|
+| 通过 CLI pipeline 执行 | `output-only` | CLI 捕获输出并写入文件 |
+| 通过 Agent 手动引导执行 | `readwrite` | Agent 通过工具读写文件 |
+
+使用 `render_prompt.py --mode` 显式指定，或由调用方自行判断。
+
+## 两种模式的区别
+
+### output-only（输出即文档）
+
+子代理只需要输出 markdown 文本，不需要任何文件操作。
+所有源码信息已内嵌在 prompt 中（骨架 + 源码内容）。
+
+### readwrite（读写文件）
+
+子代理需要通过工具读取源码、分块写入文档。
+写盘纪律：
+- 每完成一个 `##` 章节就写盘一次
+- 首次创建文件，后续追加
+- 单次写入不超过 150 行
+- 每次写盘后读取前 5 行确认写入成功

skills/kb-init/templates/core/output-only.md

@@ -0,0 +1,4 @@
+## 执行方式
+
+直接输出完整的 markdown 文档内容，不要输出解释、确认或其他非文档内容。
+所有需要的源码信息已在下方「源码骨架」和「源码文件内容」章节中提供，禁止引用未提供的文件。

skills/kb-init/templates/core/readwrite.md

@@ -0,0 +1,33 @@
+## 执行方式
+
+你需要根据文件清单读取源码文件，分析内容并生成文档。
+
+### 文件读取
+
+源码缓存目录：`{source_cache_path}`
+文件清单：在「需要读取的源码文件」章节中提供
+
+读取规则：
+1. 根据文件清单逐个读取源码文件
+2. 分析文件内容，提取所需信息
+3. 禁止读取未在清单中的文件
+4. 直接分析源码，所有数值参数必须从源码确认
+
+### 关键原则
+
+1. **禁止编造**：所有内容必须有源码出处
+2. **直接分析**：基于原始源码文件内容
+3. **聚焦任务**：只生成当前文档类型的内容
+4. **验证数值**：配置参数必须从源码验证
+
+### 写盘纪律
+
+- 每完成一个 `##` 章节就写盘一次
+- 首次创建文件使用 Write，后续追加使用 Edit
+- 单次写入不超过 150 行
+- 每次写盘后读取前 5 行确认写入成功
+
+### 输出文件
+
+`{output_path}/{doc_type}.md`（如果分片则覆盖为具体文件名）
+