source-kb 0.2.2__py3-none-any.whl

skills/kb-sync/steps/step-01-detect.md

@@ -0,0 +1,72 @@
+# Step 1: 检测
+
+## 1.1 获取知识库锁
+
+按 `rules.md` §3 锁协议获取 `{knowledge_dir}/.kb-lock`，超时 30 分钟。
+
+```shell
+# 检查锁文件
+cat "{knowledge_dir}/.kb-lock" 2>/dev/null
+# 不存在或已超时 → 创建
+echo '{"pid": '$$', "timestamp": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'", "operation": "kb-sync"}' > "{knowledge_dir}/.kb-lock"
+```
+
+## 1.2 更新源码缓存
+
+如果模块有 `.source-cache`，先更新：
+
+```shell
+git -C .source-cache/{module} pull
+```
+
+没有缓存则按以下方式创建：
+
+```shell
+git clone --depth 1 --branch {branch} {repo_url} .source-cache/{module}
+```
+
+## 1.3 检测变动
+
+```shell
+source-kb scan-repos --config kb-project.yaml
+```
+
+可选参数：`--kb {kb}`、`--module {module}`、`--force`
+
+无变动 → 释放锁（跳到 step-04 §4.3），正常结束。
+
+## 1.4 变动分类
+
+按 preset 的 `file_classification` 分类变动文件 → 确定需更新的文档列表。
+
+分类结果示例：
+- `model` 类文件变动 → data-models.md
+- `controller` / `api` 类文件变动 → api-contracts.md
+- `service` 类文件变动 → business-logic.md
+- `config` / `aspect` 类文件变动 → architecture.md
+
+## 1.5 降级检查
+
+变动文件 > 20 个 → **降级为 kb-audit 完整流程**：
+1. 释放锁（删除 `.kb-lock`）
+2. 提示用户执行 `/kb-audit --module {module}`
+3. kb-sync 流程终止，不继续后续步骤
+
+## 1.6 可选文档触发检查
+
+如果变动文件中新增了中间件使用（如新引入 `@KafkaListener`、`@RabbitListener`），按 `audit_dimensions.md` 的触发条件检测：
+
+- 命中且对应可选文档不存在 → 标记为待新建（在 Step 2 中创建）
+- 命中且文档已存在 → 加入更新列表
+- 未命中 → 跳过
+
+## Gate 1 检查清单
+
+- [ ] `.kb-lock` 已创建
+- [ ] 源码缓存已更新
+- [ ] `scan_repos.py` 已执行，变动文件已列出
+- [ ] 变动文件已按 preset 分类
+- [ ] 变动文件 ≤ 20 个（否则已降级终止）
+- [ ] 可选文档触发条件已检查
+
+全部通过 → 加载 `step-02-update.md`

skills/kb-sync/steps/step-02-update.md

@@ -0,0 +1,71 @@
+# Step 2: 更新
+
+## 2.1 骨架增量提取
+
+无论变动文件数量多少，都更新骨架以保持最新。
+
+### 增量模式（变动文件 ≤ 10 个）
+
+```shell
+# 提取变动文件的骨架到 delta
+source-kb extract \
+  --repo "{repo}" --preset {preset} --files {changed_files...} --compact \
+  --output "{module_dir}/.skeleton-delta.json"
+
+# 合并 delta 到已有骨架
+source-kb merge-delta \
+  --delta "{module_dir}/.skeleton-delta.json" --target "{module_dir}"
+```
+
+脚本自动检测目标格式（`.skeleton.json` 单文件或 `.skeleton/` 分片目录），按文件路径替换同名条目、追加新条目，完成后删除 delta 文件。可先用 `--dry-run` 预览合并计划。
+
+### 全量模式（变动文件 > 10 个）
+
+跳过 delta 合并，直接全量重新提取：
+
+```shell
+source-kb extract \
+  --repo "{repo}" --preset {preset} --full --compact --output "{module_dir}"
+```
+
+## 2.2 文档更新
+
+按 `rules.md` §4 依赖链顺序更新文档（从 `doc_types.yaml` 的 `depends_on` 字段拓扑排序）。
+
+只更新 Step 1 分类中确定需要更新的文档，跳过无关文档。
+
+### 更新方式
+
+- 定位文档中对应章节，**只重写匹配章节**，不改动其他部分
+- 新增内容追加到对应章节末尾
+- 删除的源码对应内容标记为 `~~已移除~~` 或直接删除
+
+### 源码读取规则
+
+- 优先读 `.source-cache/{module}` 下的文件（缓存模式）
+- 缓存不存在时 fallback 到 `git show {commit}:{path}`
+
+### 写入纪律
+
+- 格式遵循 preset 的文档格式规范（表格对齐、代码块标注语言、锚点命名）
+- 内容深度遵循业务视角组织原则（不是代码翻译，是业务逻辑说明）
+- Write-as-you-go：每处理完一个文档立即写盘，不攒到最后
+
+## 2.3 引用级联检查
+
+当中立文档（data-models / api-contracts / caching / messaging / architecture）发生**章节结构变更**（`##`/`###` 标题增删或重编号）时：
+
+1. 提取被修改文档的所有 `##`/`###` 标题（修改前 vs 修改后）
+2. 如果标题发生变更 → 在 business-logic.md 中搜索指向该文档的锚点链接
+3. 失效的锚点 → 自动修复（更新为新锚点）或降级为文件级链接（去掉 `#锚点` 部分）
+
+注意：纯内容修改（字段表增删行、配置值变更）不影响锚点，无需级联。只有章节标题变更才需要级联检查。
+
+## Gate 2 检查清单
+
+- [ ] 骨架已更新（delta 合并或全量重提取）
+- [ ] 所有目标文档已按依赖顺序更新
+- [ ] 引用级联检查已完成（如有章节标题变更）
+- [ ] 每个文档更新后已立即写盘
+
+全部通过 → 加载 `step-03-verify.md`

skills/kb-sync/steps/step-03-verify.md

@@ -0,0 +1,47 @@
+# Step 3: 校验
+
+## 3.1 覆盖率校验
+
+文档更新后，执行覆盖率校验确认质量：
+
+```shell
+source-kb validate coverage check \
+  --skeleton "{module_dir}/.skeleton.json" --docs-dir "{module_dir}" --type {module_type}
+```
+
+### 阈值
+
+- 覆盖率 ≥ 80% → 通过
+- 覆盖率 < 80% → 补充缺失方法，重新校验直到达标
+
+### 补充策略
+
+1. 从校验输出中提取未覆盖的方法列表
+2. 按优先级排序：`high` complexity > `medium` > `low`
+3. 定位对应文档章节，补充缺失方法的说明
+4. 重新执行覆盖率校验
+
+## 3.2 共享文档更新检测
+
+如果变动涉及模块间调用关系、错误码、数据模型等，检查 `{knowledge_dir}/_shared/` 下的共享文档是否需要同步更新。
+
+### 检测规则
+
+| 共享文档 | 检测方式 | 触发条件 |
+|---------|---------|---------|
+| `cross-module-calls.md` | grep architecture.md | 新增/修改 Feign 或 Dubbo 接口声明 |
+| `error-codes.md` | grep api-contracts.md | 新增/修改错误码表 |
+| `database-ddl.md` | grep data-models.md | 新增/修改 `@TableName` 注解对应的表 |
+
+### 更新方式
+
+- 命中 → 定位共享文档中对应章节，增量更新
+- 未命中 → 跳过
+
+## Gate 3 检查清单
+
+- [ ] 覆盖率 ≥ 80%
+- [ ] 共享文档检测已执行（cross-module-calls / error-codes / database-ddl）
+- [ ] 需要更新的共享文档已更新
+
+全部通过 → 加载 `step-04-finalize.md`

skills/kb-sync/steps/step-04-finalize.md

@@ -0,0 +1,52 @@
+# Step 4: 收尾
+
+## 4.1 Embedding 服务预检
+
+索引重建前先确认 Embedding 服务可用：
+
+```shell
+source-kb validate links --config kb-project.yaml
+```
+
+预检失败 → ⚠️ 暂停，提示用户检查 Embedding 服务配置，不执行索引重建。文档更新仍然保留，下次 sync 可补建索引。
+
+## 4.2 索引重建
+
+文件级增量重建（只重建有修改的文档）：
+
+```shell
+source-kb rebuild \
+  --config kb-project.yaml --kb {kb} --module {module} --files {modified.md...}
+```
+
+## 4.3 基线更新
+
+**前置条件**（R7）：只有文档更新（Step 2）和覆盖率校验（Step 3）都成功后，才更新基线 commit。
+
+如果 Step 2 文档更新失败或 Step 3 覆盖率不达标 → 不更新基线。下次 sync 会重新处理这批变动。
+
+```shell
+# 仅在上述步骤全部成功后执行
+source-kb scan-repos --config kb-project.yaml --update-state --kb {kb} --module {module} {commit}
+```
+
+## 4.4 释放锁
+
+**必须执行**（R2），无论前面步骤成功或失败：
+
+```shell
+rm -f "{knowledge_dir}/.kb-lock"
+```
+
+## 完成报告
+
+流程结束后输出摘要：
+
+| 项目 | 状态 |
+|------|------|
+| 变动文件数 | {n} 个 |
+| 更新文档 | {doc_list} |
+| 覆盖率 | {coverage}% |
+| 共享文档更新 | {shared_docs} |
+| 索引重建 | ✅ / ⚠️ 跳过 |
+| 基线更新 | ✅ / ⚠️ 跳过（原因） |

source_kb-0.2.2.dist-info/METADATA

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: source-kb
+Version: 0.2.2
+Summary: Auto-generate structured knowledge base documents from source code. Supports AI agent mode (skill-based) and MCP server interface.
+License-Expression: MIT
+Keywords: knowledge-base,documentation,code-analysis,llm,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: filelock>=3.12.0
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == "mcp"
+Provides-Extra: skeleton
+Requires-Dist: tree-sitter<0.22.0,>=0.21.0; extra == "skeleton"
+Requires-Dist: tree-sitter-languages>=1.10.0; extra == "skeleton"
+Provides-Extra: rag
+Requires-Dist: chromadb>=0.4.0; extra == "rag"
+Provides-Extra: full
+Requires-Dist: mcp>=1.0.0; extra == "full"
+Requires-Dist: chromadb>=0.4.0; extra == "full"
+Requires-Dist: tree-sitter<0.22.0,>=0.21.0; extra == "full"
+Requires-Dist: tree-sitter-languages>=1.10.0; extra == "full"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Dynamic: license-file
+
+# source-kb
+
+English | [中文](README.md)
+
+Auto-generate structured knowledge base documents from source code, build vector indexes, and support RAG retrieval.
+
+## Features
+
+- **CLI toolchain**: skeleton extraction, prompt rendering, intelligent splitting, quality validation, vector indexing — all standalone Python scripts
+- **MCP Server**: zero-friction integration with any MCP-compatible AI Agent
+- **Platform-agnostic**: works in Kiro / Cursor / Claude Code / Windsurf / any AI Agent
+- **LLM-agnostic**: without an Agent, use CLI pipeline with any OpenAI-compatible API (Anthropic / OpenAI / DeepSeek / Ollama / vLLM, etc.)
+- **Intelligent subagent splitting**: semantic grouping by business domain (LLM-based) or package-aware greedy algorithm (code-based)
+- **Two-phase generation**: outline first, then expand — eliminates information isolation between shards
+- **Method-level source injection**: prioritized by complexity (high=full body / medium=first 20 lines / low=signature only)
+- **Real-time quality validation**: each subagent output is verified immediately, with automatic retry on failure
+- **Document deduplication**: LLM-powered post-merge dedup (internal redundancy + cross-doc ownership)
+- Any language support via preset system (java-spring built-in)
+- Source code access through git remote (multi-repo & monorepo)
+- Lightweight self-built RAG engine (ChromaDB + pluggable embedding)
+
+## Quick Start
+
+### Option 1: MCP Server (recommended)
+
+Configure the MCP server in your AI Agent (Kiro / Claude Code / Cursor / Windsurf):
+
+```json
+{
+  "mcpServers": {
+    "source-kb": {
+      "command": "uvx",
+      "args": ["--from", "git+https://your-repo/source-kb.git", "source-kb-mcp"]
+    }
+  }
+}
+```
+
+Or for local development:
+
+```json
+{
+  "mcpServers": {
+    "source-kb": {
+      "command": "python",
+      "args": ["-m", "mcp_server"],
+      "cwd": "/path/to/source-kb"
+    }
+  }
+}
+```
+
+Once configured, the Agent discovers all tools automatically. Just ask:
+
+```
+Generate knowledge base documentation for this project
+```
+
+The Agent will call `discover()` → `detect_project()` → `get_workflow("kb-init")` to orchestrate the entire flow.
+
+**Non-Java project?** Works the same way. `detect_project()` auto-detects project type; unrecognized projects use the `generic` preset:
+
+```
+Generate knowledge base documentation for this Python/Go/Node.js project
+```
+
+You can also specify the preset manually:
+
+```bash
+# Use generic preset (works for any language)
+source-kb extract --repo .source-cache/my-app --preset generic --output knowledge/my-app
+```
+
+> The generic preset uses path-based rules + regex parser for file classification — no tree-sitter required. For higher accuracy, create a custom preset following `presets/java-spring/` as reference.
+
+### Option 2: Manual Skill Mode
+
+If your Agent doesn't support MCP, load skill files manually:
+
+```
+Please read skills/kb-init/SKILL.md and follow the steps to initialize the knowledge base.
+```
+
+Or add the guide to your project rules file (`.kiro/steering/`, `.cursorrules`, etc.). See [Getting Started](docs/getting-started.md).
+
+### Option 3: CLI Mode (no Agent)
+
+```bash
+export LLM_BASE_URL="https://api.anthropic.com"
+export LLM_MODEL="claude-sonnet-4-6"
+export LLM_API_KEY="sk-xxx"
+source-kb pipeline --kb my-project --action init
+```
+
+> Full guide: [Getting Started](docs/getting-started.md).
+
+## CLI Quick Reference
+
+```bash
+# Skeleton extraction
+source-kb extract --repo .source-cache/xxx --preset java-spring --summary --output knowledge/xxx
+
+# Prompt rendering
+source-kb render --template presets/java-spring/templates/subagent-business.md --module xxx --kb yyy --doc-type business-logic --mode readwrite
+
+# File list extraction
+source-kb file-list --skeleton knowledge/xxx/.meta/skeleton/skeleton.json --preset java-spring --doc-type business-logic --output knowledge/xxx/.meta/file-lists/business-logic.txt
+
+# Coverage validation
+source-kb validate coverage check --skeleton knowledge/xxx/.meta/skeleton/skeleton.json --docs-dir knowledge/xxx --type service
+
+# Index & search
+source-kb index --kb my-project
+source-kb search --kb my-project "query"
+```
+
+## MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| `discover` | Detect project state and available workflows |
+| `detect_project` | Scan project structure, recommend config |
+| `init_project` | Generate kb-project.yaml |
+| `get_workflow` | Get step-by-step orchestration instructions |
+| `get_subagent_prompt` | Render sub-agent prompt for doc generation |
+| `skeleton_extract` | Extract code skeleton (AST-level structure) |
+| `classify_files` | Classify source files into doc types |
+| `dispatch_plan` | Compute generation plan (batches, splits) |
+| `coverage_check` | Validate documentation coverage |
+| `check_progress` | Monitor sub-agent generation progress |
+| `generate_doc` | Direct LLM generation (fallback for agents without sub-agents) |
+| `list_presets` | List available language presets |
+
+## Skills
+
+| Skill | Purpose |
+|-------|---------|
+| kb-init | Generate all docs from source + build index |
+| kb-audit | Compare docs vs source, fix inconsistencies |
+| kb-sync | Detect git changes, incrementally update docs and index |
+| kb-search | Vector retrieval + contextual answers |
+
+Skill files are Agent operation guides — no platform-specific instructions.
+
+## Requirements
+
+- Python 3.10~3.12 (⚠️ 3.13 not supported — tree-sitter-languages has no prebuilt wheel)
+- Git
+- Embedding backend (Ollama / OpenAI-compatible / DashScope / ChromaDB built-in)
+
+## Documentation
+
+- [Getting Started](docs/getting-started.md) — Installation, configuration, first run
+- [Configuration Reference](docs/configuration.md) — Full kb-project.yaml field reference
+- [Custom Presets](docs/custom-presets.md) — Create and customize language presets
+- [Design Document](docs/design-v5.md) — Architecture design and technical decisions
+- [CLI vs Agent Mode](docs/cli-vs-agent-mode-analysis.md) — Two modes compared
+- [Preset Development](docs/presets.md) — Built-in preset internals