source-kb 0.2.2__py3-none-any.whl

skills/kb-search/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: kb-search
+description: |
+  源码知识库检索与问答。根据 kb-project.yaml 配置自动识别可用知识库。
+  触发词：/kb-search、知识库查询、搜索知识库。
+  不适用：知识库初始化（用 kb-init）、增量同步（用 kb-sync）、文档自检（用 kb-audit）。
+---
+
+# 知识库检索与问答
+
+两条检索路径：精确问题直读文档（快），模糊问题走向量检索（全）。
+
+## 硬规则（所有步骤始终生效，违反任何一条即为失败）
+
+- R1: 回答必须基于文档/源码，禁止编造 — 无法确认时写 `⚠️ 待验证`
+- R2: 引用跟踪最多 1 层，不递归 — 跟踪引用中的引用会导致上下文膨胀
+- R3: 大文档（≥2000 行）先读前 100 行目录区域再精确定位，不读全文
+- R4: 来源标注必须包含知识库/模块/文档/章节 — 格式：`📚 来源：{kb}/{module}/{doc} > {section}`
+- R5: 源码兜底时注明"来源：源码直读" — 与文档来源明确区分
+
+## 前置
+
+1. 读取 `kb-project.yaml`，获取可用知识库列表和 `knowledge_dir`（不存在则引导用户创建）
+2. 读取本 skill 的 `rules.md`（检索规则，~60 行）
+
+不再需要读取 `_shared/` 下的任何文件。所有执行规则已内嵌到本文件和 `rules.md` 中。
+
+## 流程
+
+### 1. 识别知识库
+
+从 `kb-project.yaml` 的 `knowledge_bases` 中列出可用知识库。如果用户指定了 `--kb`，直接使用；否则根据问题内容自动选择最相关的知识库。
+
+### 2. 路由判断
+
+根据问题特征选择检索路径：
+
+| 条件 | 路径 |
+|------|------|
+| 问题含具体类名、方法名或模块名 | → 步骤 3（文档直读） |
+| 用户指定了模块（如 `--module point-transaction`） | → 步骤 3（文档直读） |
+| 问题是概念性、流程性、跨模块问题 | → 步骤 4（向量检索） |
+| 无法判断 | → 步骤 4（向量检索） |
+
+### 3. 文档直读（精确问题优先路径）
+
+直接用 Read 工具读取知识库文档，零脚本调用。
+
+**3.1 定位模块**
+
+- 用户指定了模块 → 直接定位
+- 问题含模块名 → 匹配 `kb-project.yaml` 中的 repo name
+- 未指定 → 读取 `{knowledge_dir}/` 下各模块的 `index.md` 首段（模块概述），选择最相关的 1-2 个模块
+
+**3.2 定位文档**
+
+根据问题类型选择目标文档。路由规则基于 preset 的 `doc_types[].search_keywords` 配置：
+
+1. 列出 `{knowledge_dir}/{module}/` 下实际存在的 .md 文件
+2. 将用户问题关键词与各文档的 `search_keywords` 匹配，选择最相关的 1-2 个文档
+3. 无匹配时读取 index.md 的文档导航章节确定目标
+
+完整路由规则和复合查询路径见 `rules.md`。
+
+**3.3 章节定位**
+
+文档按标准规范编写（`##` 业务域 → `###` 类名 → `####` 方法名）：
+
+- 小文档（< 2000 行）：直接 Read 全文，在内容中定位
+- 大文档（≥ 2000 行）：先 Read 前 100 行（目录/概述区域），根据章节编号用 offset + limit 精确读取目标章节（R3）
+
+**3.4 引用跟踪**
+
+在目标文档中定位到相关章节后，如果章节内容包含引用链接（`详见 [xxx](./yyy.md#锚点)`），自动跟踪读取被引用文档的对应章节，合并后回答。
+
+引用跟踪最多 1 层（R2），不递归跟踪引用中的引用。复合查询路径参考见 `rules.md`。
+
+**3.5 回答**
+
+基于文档内容回答（R1）。如果文档内容不充分 → 进入步骤 4（向量检索）补充。
+
+### 4. 向量检索（模糊问题 / 兜底路径）
+
+```shell
+cd "{kb_project_yaml_dir}"
+source-kb search --kb {kb_name} "{query}"
+```
+
+- 检索结果充分 → 直接回答
+- 检索结果不充分 → 进入步骤 5（源码兜底）
+
+### 5. 源码兜底
+
+当文档直读和向量检索都无法回答时，或用户明确要求查看最新代码时：
+
+1. 从 `kb-project.yaml` 获取对应模块的 git 仓库信息（含 `branch`，默认 `main`）
+2. 优先从 `.source-cache/{module}/` 直接 Read 文件（如果缓存存在）
+3. 缓存不存在时用 `git show origin/{branch}:{filepath}` 读取源码
+4. 依赖模块源码（无 origin remote）用 `git show HEAD:{path}` 读取
+5. 单次读取 ≤ 200 行，大文件分段读取
+6. 基于源码内容回答，注明"来源：源码直读"（R5）
+
+源码缓存刷新（仅在用户要求最新代码时执行）：
+
+```shell
+git -C ".source-cache/{module}" fetch origin {branch} && git -C ".source-cache/{module}" reset --hard origin/{branch}
+```
+
+刷新失败（网络不可达等）→ 警告但继续使用现有缓存，不阻塞查询。
+
+### 6. 回答格式
+
+```markdown
+[回答内容]
+
+📚 来源：{kb_name}/{module_name}/{doc_name} > {section}
+```
+
+- 标题层级：`#` 文档标题 → `##` 章节 → `###` 子章节
+- 代码块带语言标注（```java、```sql 等）
+- 字段/参数列表用表格呈现
+- 来源标注必须包含知识库/模块/文档/章节（R4）
+
+## 降级策略
+
+| 场景 | 处理 |
+|------|------|
+| index.md 不存在 | 跳过文档直读，走向量检索 |
+| 目标文档不存在或为空 | 跳过文档直读，走向量检索 |
+| 文档中找不到相关章节 | 走向量检索 |
+| 向量检索无结果 | 走源码兜底 |
+| 源码仓库不可达 | 告知用户，建议检查环境 |
+
+## 触发方式
+
+- `/kb-search {问题}` — 自动选择知识库
+- `/kb-search --kb crm {问题}` — 指定知识库
+- `/kb-search --kb point --module point-transaction {问题}` — 指定模块

skills/kb-search/rules.md

@@ -0,0 +1,64 @@
+# kb-search 检索规则
+
+> 本文件供主会话在检索过程中参考，~60 行。所有规则自包含，不引用 `_shared/` 文件。
+
+## 1. 源码读取规则
+
+| 场景 | 方式 |
+|------|------|
+| 缓存存在 | 优先 Read `.source-cache/{module}/` 下的文件 |
+| 缓存不存在 | `git -C {repo} show origin/{branch}:{path}` |
+| 依赖模块（无 origin） | `git show HEAD:{path}` |
+
+- 单次读取 ≤ 200 行，大文件按 offset + limit 分段读取
+- 缓存刷新仅在用户要求最新代码时执行，失败不阻塞查询
+
+## 2. 文档路由
+
+根据 preset 的 `doc_types[].search_keywords` 字段匹配问题关键词到目标文档。
+
+路由流程：
+1. 从 `{knowledge_dir}/{module}/` 列出实际存在的 .md 文件
+2. 对每个文件，从 preset 的 doc_types 配置读取 `search_keywords`
+3. 将用户问题与 search_keywords 做关键词匹配，选择最相关的 1-2 个文档
+4. 如果无匹配，读取 index.md 的文档导航章节确定目标
+5. 跨模块问题 → `_shared/cross-module-calls.md`
+
+获取当前 preset 的路由映射（`{preset_name}` 从 `kb-project.yaml` 的 `knowledge_bases.{kb}.preset` 字段获取）：
+```shell
+python -c "from core.preset import load_preset, get_search_routing; import json; print(json.dumps(get_search_routing(load_preset('{preset_name}')), ensure_ascii=False, indent=2))"
+```
+
+## 3. 引用跟踪规则
+
+- 最多跟踪 1 层引用，不递归
+- 仅跟踪 `详见 [xxx](./yyy.md#锚点)` 格式的显式引用
+- 跟踪后合并两个来源回答，分别标注出处
+
+## 4. 复合查询路径表
+
+| 问题类型 | 主文档 | 可能跟踪的引用 |
+|---------|--------|--------------|
+| 业务流程中的缓存细节 | business-logic.md | → caching.md |
+| 业务流程中的消息体 | business-logic.md | → messaging.md |
+| 业务流程中的参数校验 | business-logic.md | → api-contracts.md |
+| 业务流程中的实体字段 | business-logic.md | → data-models.md |
+| 业务流程中的线程池配置 | business-logic.md | → architecture.md |
+| 接口的数据模型 | api-contracts.md | → data-models.md |
+| 接口的错误码定义 | api-contracts.md | → enums-and-constants.md |
+
+## 5. 大文件读取策略
+
+| 文档大小 | 策略 |
+|---------|------|
+| < 2000 行 | 直接 Read 全文，在内容中定位 |
+| ≥ 2000 行 | 先 Read 前 100 行（目录/概述区域），根据章节编号用 offset + limit 精确读取 |
+
+章节定位依据文档标准层级：`##` 业务域 → `###` 类名 → `####` 方法名。
+
+## 6. 源码缓存刷新规则
+
+- 默认不刷新，使用现有缓存
+- 用户明确要求"最新代码"时才执行 `fetch + reset`
+- 刷新失败 → 警告但继续使用现有缓存，不阻塞查询
+- 刷新命令：`git -C ".source-cache/{module}" fetch origin {branch} && git -C ".source-cache/{module}" reset --hard origin/{branch}`

skills/kb-sync/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: kb-sync
+description: |
+  知识库增量同步。监听 git 变动，增量更新知识库文档并重建变动模块索引。
+  触发词：/kb-sync、知识库同步、同步知识库、更新知识库。
+---
+
+# 知识库增量同步
+
+## 硬规则（所有步骤始终生效，违反任何一条即为失败）
+
+- R1: 禁止编造 — 所有内容必须有源码出处，无法确认时写 `⚠️ 待验证`
+- R2: 锁纪律 — `.kb-lock` 超时 30 分钟，无论成功失败必须释放
+- R3: 降级阈值 — 变动文件 > 20 个 → 释放锁，终止 sync，提示用户执行 `/kb-audit`
+- R4: 骨架读取上限 — >50KB 禁止子代理直接读，用 `.skeleton-summary.json`
+- R5: 单次写入 ≤150 行 — 超出分块追加，首次 Write 后续 Edit
+- R6: 每步必须过 Gate — 产出校验通过才能进入下一步，不跳过
+- R7: 基线更新前置条件 — 文档更新 + 覆盖率校验都成功后才更新基线 commit
+
+## 前置
+
+1. 读取 `kb-project.yaml`
+2. 读取 `presets/{preset}/audit_dimensions.md`（仅 grep 可选文档触发条件，不读全文）
+3. 读取本 skill 的 `rules.md`（主会话调度规则，~80 行）
+
+不再需要读取 `_shared/` 下的任何文件。所有执行规则已内嵌到 `rules.md` 和 `steps/` 中。
+
+## 工作流
+
+```
+Step 1: 检测 ──→ Gate 1 ──→ Step 2: 更新 ──→ Gate 2
+                                                 ↓
+Step 4: 收尾 ←── Gate 3 ←── Step 3: 校验
+```
+
+## 步骤索引（按需加载，不要一次性读取所有 step 文件）
+
+| 步骤 | 文件 | 说明 | Gate 条件 |
+|------|------|------|-----------|
+| Step 1 | steps/step-01-detect.md | 锁获取、pull、变动检测、分类 | 锁已获取 + 变动已分类 + ≤20 文件 |
+| Step 2 | steps/step-02-update.md | 骨架增量、文档更新、引用级联 | 所有目标文档已更新 |
+| Step 3 | steps/step-03-verify.md | 覆盖率校验、共享文档检查 | 覆盖率 ≥80% + 共享文档已检查 |
+| Step 4 | steps/step-04-finalize.md | 索引重建、基线更新、锁释放 | 索引可检索 + 锁已释放 |

skills/kb-sync/rules.md

@@ -0,0 +1,70 @@
+# kb-sync 主会话调度规则
+
+> 本文件供主会话在调度过程中参考，~80 行。所有规则自包含，不引用外部 `_shared/` 文件。
+
+## 1. 主会话 Context 纪律
+
+主会话的职责是**调度**，不是**阅读**。
+
+### 1.1 禁止读入的内容
+
+| 文件 | 正确做法 |
+|------|---------|
+| `_shared/doc-quality-standard.md` | 规则已内嵌到 steps/，主会话不读 |
+| `_shared/doc-subagent-rules.md` | 规则已内嵌到 rules.md + steps/，主会话不读 |
+| `_shared/doc-coverage-shared.md` | 覆盖率命令已写入 step-03，主会话不读 |
+| `audit_dimensions.md` | 只 grep 可选文档触发条件，不读全文 |
+| 骨架 JSON 全文 | 用 `--summary` 或脚本提取摘要 |
+| 已生成文档全文 | 只 grep `^## ` 标题，不读全文 |
+
+### 1.2 进度检查频率
+
+- 子代理启动后等待 5 分钟再首次检查
+- 之后每 5 分钟检查一次
+- 禁止在等待期间反复 glob 扫描目录
+
+## 2. 降级规则
+
+| 条件 | 处理 |
+|------|------|
+| 变动文件 > 20 个 | 释放锁 → 终止 sync → 提示用户执行 `/kb-audit --module {module}` |
+| 变动文件 > 10 个（骨架） | 跳过增量 delta，直接全量重新提取骨架 |
+| scan_repos.py 无变动 | 释放锁 → 正常结束，无需后续步骤 |
+
+## 3. 锁协议
+
+锁文件：`{knowledge_dir}/.kb-lock`
+
+- 获取：写入 `{"pid": <pid>, "timestamp": <time>, "operation": "kb-sync"}`
+- 超时：30 分钟（锁文件存在且超时 → 视为过期，删除重建）
+- 释放：流程结束（成功或失败）必须删除 `.kb-lock`
+
+## 4. 文档更新顺序（依赖链）
+
+当同一批变动同时影响多个文档时，按 `doc_types.yaml` 的 `depends_on` 字段拓扑排序更新。无依赖的文档先更新，有依赖的后更新。
+
+获取当前 preset 的更新顺序（`{preset_name}` 从 `kb-project.yaml` 的 `knowledge_bases.{kb}.preset` 字段获取）：
+```shell
+python -c "from core.preset import load_preset, get_dependency_chain; print(get_dependency_chain(load_preset('{preset_name}')))"
+```
+
+原因：
+- 被依赖的文档是下游文档的基础（如 data-models 被 api-contracts、caching、messaging 引用）
+- 中立文档的章节标题变更可能导致下游文档的引用锚点失效
+- 拓扑排序确保更新时引用目标已是最新版本
+
+## 5. 异常交互
+
+| 严重级别 | 前缀 | 处理 |
+|---------|------|------|
+| 成功 | ✅ | 继续 |
+| 需决策 | ⚠️ | 暂停，列选项，等用户回复 |
+| 致命 | ❌ | 终止，释放锁，报告原因 |
+
+自动降级（不询问用户）：骨架单文件解析失败、可选文档未触发、空模块跳过。
+
+## 6. 源码读取规则
+
+- 优先读 `.source-cache/{module}` 下的文件（缓存模式）
+- 缓存不存在时 fallback 到 `git show {commit}:{path}`
+- 禁止直接 clone 或 checkout 到工作目录

skills/kb-sync/scripts/rebuild_module.py

@@ -0,0 +1,91 @@
+"""
+知识库同步 - 模块级/文件级索引重建脚本（通用版）
+
+薄包装层：委托给 core.rag.build_index() 统一处理。
+
+用法：
+  # 模块级全量重建
+  python rebuild_module.py --kb my-project --module user-service
+
+  # 文件级增量重建
+  python rebuild_module.py --kb my-project --module user-service --files business-logic.md data-models.md
+
+  # 指定配置文件
+  python rebuild_module.py --config /path/to/kb-project.yaml --kb my-project --module user-service
+"""
+
+import sys
+from pathlib import Path
+
+sys.stdout.reconfigure(encoding="utf-8")  # type: ignore[union-attr]
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+PROJECT_ROOT = SCRIPT_DIR.parent.parent.parent  # source-kb/
+
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.append(str(PROJECT_ROOT))
+
+try:
+    from core.config import load_config, find_config
+except ImportError:
+    print("错误：无法导入 core 模块，请确认 source-kb 目录结构完整", file=sys.stderr)
+    sys.exit(1)
+
+
+def rebuild_module(config: dict, kb_name: str, module_name: str, files: list[str] | None = None):
+    """重建模块索引（委托给 core.rag.build_index）"""
+    from core.rag import load_documents, chunk_documents, build_index
+
+    kb_config = config.get_kb(kb_name) if hasattr(config, 'get_kb') else config["knowledge_bases"][kb_name]
+    collection_name = kb_config["collection"]
+    knowledge_dir = Path(kb_config["knowledge_dir"])
+    module_dir = knowledge_dir / module_name
+
+    if not module_dir.is_dir():
+        print(f"错误：模块目录不存在 {module_dir}")
+        sys.exit(1)
+
+    docs = load_documents(knowledge_dir, module=module_name, files=files)
+    if not docs:
+        print("  无文档文件")
+        return
+
+    print(f"  加载 {len(docs)} 个文档")
+
+    chunks = chunk_documents(
+        docs,
+        size=config.chunk_size if hasattr(config, 'chunk_size') else 512,
+        overlap=config.chunk_overlap if hasattr(config, 'chunk_overlap') else 100,
+        min_length=config.chunk_min_length if hasattr(config, 'chunk_min_length') else 50,
+    )
+    print(f"  生成 {len(chunks)} 个分块")
+
+    build_index(chunks, collection_name, kb_name=kb_name, module=module_name, files=files)
+
+    print(f"\n完成：{kb_name}/{module_name} 索引重建")
+
+
+def main():
+    """CLI 入口"""
+    import argparse
+
+    parser = argparse.ArgumentParser(description="模块级/文件级索引重建")
+    parser.add_argument("--config", help="kb-project.yaml 路径（默认自动查找）")
+    parser.add_argument("--kb", required=True, help="知识库名称")
+    parser.add_argument("--module", required=True, help="模块名称")
+    parser.add_argument("--files", nargs="+", help="指定重建的 .md 文件列表")
+
+    args = parser.parse_args()
+
+    config_path = Path(args.config) if args.config else None
+    config = load_config(config_path)
+
+    rebuild_module(config, args.kb, args.module, args.files)
+
+    import json as _json
+    print(_json.dumps({"status": "ok", "kb": args.kb, "module": args.module}, ensure_ascii=False))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()