source-kb 0.2.2__py3-none-any.whl

mcp_server/tools/workflow.py

@@ -0,0 +1,166 @@
+"""Workflow guidance tools — orchestration instructions for agents."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+
+def register(mcp: FastMCP) -> None:
+    """Register workflow tools on the MCP server."""
+
+    @mcp.tool()
+    def get_workflow(workflow: str, step: str = "", context: str = "{}") -> str:
+        """Get workflow orchestration guidance. Returns step-by-step instructions for the agent to follow.
+
+        This is the core orchestration tool. The agent executes operations according to the returned
+        instructions and requests the next step after completing gate conditions.
+
+        Args:
+            workflow: Workflow name (kb-init | kb-sync | kb-search | kb-audit)
+            step: Step identifier. Empty = return overview + first step guidance.
+                  kb-init: step-01 | step-02 | step-03 | step-04 | step-05
+                  kb-sync: step-01 | step-02 | step-03 | step-04
+                  kb-audit: step-01 | step-02 | step-03 | step-04
+            context: JSON context, may contain {kb_name, module_name, capabilities: {can_spawn_subagents}}
+        """
+        from mcp_server.workflow_loader import (
+            load_workflow_overview,
+            load_step_with_metadata,
+            WORKFLOW_MAP,
+        )
+
+        try:
+            ctx = json.loads(context) if context else {}
+        except (json.JSONDecodeError, TypeError):
+            ctx = {}
+
+        if workflow not in WORKFLOW_MAP:
+            return json.dumps({
+                "error": f"Unknown workflow: {workflow}",
+                "available": list(WORKFLOW_MAP.keys()),
+            }, ensure_ascii=False, indent=2)
+
+        if not step:
+            result = load_workflow_overview(workflow, ctx)
+        else:
+            result = load_step_with_metadata(workflow, step, ctx)
+
+        return json.dumps(result, ensure_ascii=False, indent=2)
+
+    @mcp.tool()
+    def get_subagent_prompt(
+        kb_name: str,
+        module_name: str,
+        doc_type: str,
+        shard: int = 0,
+        extras: str = "{}",
+    ) -> str:
+        """Render a complete sub-agent prompt that can be passed directly to a sub-agent for document generation.
+
+        Internally calls core.prompt.renderer.render_prompt to assemble template + skeleton + file list +
+        execution instructions, returning a ready-to-use prompt text.
+
+        Args:
+            kb_name: Knowledge base name (key in kb-project.yaml)
+            module_name: Module name
+            doc_type: Document type (business-logic | api-contracts | data-models | ...)
+            shard: Shard index (0 = no sharding, 1+ = specific shard)
+            extras: Additional template variables in JSON format
+        """
+        from mcp_server import find_config
+        from core.config import load_config
+        from core.preset import load_preset, get_template_path
+        from core.prompt.renderer import render_prompt
+        from core.prompt.variables import ReferencePromptAssembler
+
+        config_path = find_config()
+        if not config_path:
+            return json.dumps({"error": "kb-project.yaml not found"}, ensure_ascii=False)
+
+        config = load_config(config_path)
+        kb_cfg = config.get_kb(kb_name)
+        preset_name = kb_cfg.get("preset", "generic")
+        preset = load_preset(preset_name)
+
+        # Resolve template path
+        template_name = get_template_path(preset, doc_type, preset_name)
+        if not template_name:
+            template_name = f"subagent-{doc_type}.md"
+
+        from core.preset import find_preset_template
+        from mcp_server import PROJECT_ROOT
+        template_path = find_preset_template(preset_name, template_name)
+        if not template_path:
+            candidate = PROJECT_ROOT / "skills" / "kb-init" / "templates" / template_name
+            if candidate.exists():
+                template_path = candidate
+
+        if not template_path:
+            return json.dumps({
+                "error": f"Template not found: {template_name}",
+                "searched": [
+                    f"presets/{preset_name}/templates/{template_name}",
+                    f"skills/kb-init/templates/{template_name}",
+                ],
+            }, ensure_ascii=False, indent=2)
+
+        try:
+            extra_vars = json.loads(extras) if extras else {}
+        except (json.JSONDecodeError, TypeError):
+            extra_vars = {}
+
+        # Handle shard file list override
+        if shard > 0:
+            base_dir = Path(config.raw.get("_config_dir", config.config_path.parent))
+            kb_dir = Path(kb_cfg["knowledge_dir"])
+            if not kb_dir.is_absolute():
+                kb_dir = (base_dir / kb_dir).resolve()
+            module_dir = kb_dir / module_name
+            shard_file = module_dir / ".meta" / "shards" / f"{doc_type}-shard-{shard}.txt"
+            if shard_file.exists():
+                extra_vars["file_list_override"] = str(shard_file)
+
+        # Render prompt
+        assembler = ReferencePromptAssembler(
+            project_root=config.config_path.parent,
+            preset=preset,
+        )
+
+        rendered = render_prompt(
+            template_path=template_path,
+            config=config.raw,
+            kb_name=kb_name,
+            module_name=module_name,
+            doc_type=doc_type,
+            assembler=assembler,
+            extras=extra_vars,
+            preset=preset,
+        )
+
+        # Compute output path
+        base_dir = config.config_path.parent
+        kb_dir = Path(kb_cfg["knowledge_dir"])
+        if not kb_dir.is_absolute():
+            kb_dir = (base_dir / kb_dir).resolve()
+        module_dir = kb_dir / module_name
+
+        # Get filename from preset
+        doc_types = preset.get("doc_types", {})
+        dt_cfg = doc_types.get(doc_type, {})
+        filename = dt_cfg.get("filename", f"{doc_type}.md") if isinstance(dt_cfg, dict) else f"{doc_type}.md"
+        output_path = module_dir / filename
+
+        # Estimate tokens (~4 chars per token)
+        estimated_tokens = len(rendered) // 4
+
+        return json.dumps({
+            "status": "ok",
+            "prompt": rendered,
+            "output_path": str(output_path),
+            "estimated_tokens": estimated_tokens,
+            "timeout_seconds": 300 if estimated_tokens < 50000 else 600,
+        }, ensure_ascii=False, indent=2)

mcp_server/workflow_loader.py

@@ -0,0 +1,204 @@
+"""Workflow content loader — reads skills/ files for get_workflow tool.
+
+Supports two modes:
+- Development: reads directly from skills/ directory on filesystem
+- Installed package: reads from package data via importlib.resources
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# Project root (where skills/ lives in development)
+_PROJECT_ROOT = Path(__file__).resolve().parent.parent
+
+WORKFLOW_MAP: dict[str, dict[str, str]] = {
+    "kb-init": {
+        "overview": "kb-init/SKILL.md",
+        "rules": "kb-init/rules.md",
+        "step-01": "kb-init/steps/step-01-scope.md",
+        "step-02": "kb-init/steps/step-02-source.md",
+        "step-03": "kb-init/steps/step-03-generate.md",
+        "step-04": "kb-init/steps/step-04-quality.md",
+        "step-05": "kb-init/steps/step-05-finalize.md",
+    },
+    "kb-sync": {
+        "overview": "kb-sync/SKILL.md",
+        "rules": "kb-sync/rules.md",
+        "step-01": "kb-sync/steps/step-01-detect.md",
+        "step-02": "kb-sync/steps/step-02-update.md",
+        "step-03": "kb-sync/steps/step-03-verify.md",
+        "step-04": "kb-sync/steps/step-04-finalize.md",
+    },
+    "kb-search": {
+        "overview": "kb-search/SKILL.md",
+        "rules": "kb-search/rules.md",
+    },
+    "kb-audit": {
+        "overview": "kb-audit/SKILL.md",
+        "rules": "kb-audit/rules.md",
+        "step-01": "kb-audit/steps/step-01-prepare.md",
+        "step-02": "kb-audit/steps/step-02-audit.md",
+        "step-03": "kb-audit/steps/step-03-verify.md",
+        "step-04": "kb-audit/steps/step-04-report.md",
+    },
+}
+
+# Tools needed per step (for agent guidance)
+STEP_TOOLS: dict[str, dict[str, list[str]]] = {
+    "kb-init": {
+        "step-01": ["discover", "detect_project", "init_project"],
+        "step-02": ["skeleton_extract", "classify_files"],
+        "step-03": ["dispatch_plan", "get_subagent_prompt", "generate_doc"],
+        "step-04": ["coverage_check", "check_progress"],
+        "step-05": ["coverage_check"],
+    },
+    "kb-sync": {
+        "step-01": ["discover"],
+        "step-02": ["skeleton_extract", "classify_files", "get_subagent_prompt", "generate_doc"],
+        "step-03": ["coverage_check"],
+        "step-04": [],
+    },
+    "kb-search": {
+        "overview": ["discover"],
+    },
+    "kb-audit": {
+        "step-01": ["skeleton_extract"],
+        "step-02": ["get_subagent_prompt", "generate_doc", "coverage_check"],
+        "step-03": ["coverage_check"],
+        "step-04": [],
+    },
+}
+
+
+def _skills_dir() -> Path:
+    """Locate skills/ directory."""
+    dev_path = _PROJECT_ROOT / "skills"
+    if dev_path.is_dir():
+        return dev_path
+    # Fallback: try importlib.resources for installed package
+    try:
+        from importlib import resources
+        ref = resources.files("skills")
+        # resources.files returns a Traversable; if it maps to a real dir, use it
+        if hasattr(ref, "_path"):
+            return Path(ref._path)
+        return Path(str(ref))
+    except (ImportError, ModuleNotFoundError, TypeError):
+        pass
+    return dev_path
+
+
+def load_step(workflow: str, step: str) -> str | None:
+    """Load a single step's markdown content.
+
+    Args:
+        workflow: Workflow name (kb-init, kb-sync, etc.)
+        step: Step identifier (overview, step-01, etc.)
+
+    Returns:
+        Markdown content string, or None if not found.
+    """
+    steps = WORKFLOW_MAP.get(workflow)
+    if not steps:
+        return None
+    rel_path = steps.get(step)
+    if not rel_path:
+        return None
+
+    full_path = _skills_dir() / rel_path
+    if full_path.exists():
+        return full_path.read_text(encoding="utf-8")
+    return None
+
+
+def load_workflow_overview(workflow: str, context: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Load workflow overview with metadata for agent consumption.
+
+    Returns a structured dict with instructions, available steps, and guidance.
+    """
+    steps = WORKFLOW_MAP.get(workflow)
+    if not steps:
+        return {
+            "error": f"Unknown workflow: {workflow}. Available: {list(WORKFLOW_MAP.keys())}"
+        }
+
+    overview_content = load_step(workflow, "overview")
+    rules_content = load_step(workflow, "rules")
+
+    available_steps = [s for s in steps.keys() if s.startswith("step-")]
+
+    result: dict[str, Any] = {
+        "workflow": workflow,
+        "instructions": overview_content or f"Workflow {workflow} overview not found.",
+        "available_steps": available_steps,
+        "next_step": available_steps[0] if available_steps else None,
+    }
+
+    if rules_content:
+        result["rules"] = rules_content
+
+    return result
+
+
+def load_step_with_metadata(workflow: str, step: str, context: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Load a step with full metadata for agent consumption.
+
+    Returns structured dict with instructions, gate conditions, next step, and tools needed.
+    """
+    content = load_step(workflow, step)
+    if content is None:
+        return {"error": f"Step '{step}' not found in workflow '{workflow}'."}
+
+    steps = WORKFLOW_MAP.get(workflow, {})
+    available_steps = sorted([s for s in steps.keys() if s.startswith("step-")])
+
+    # Determine next step
+    next_step = None
+    if step in available_steps:
+        idx = available_steps.index(step)
+        if idx + 1 < len(available_steps):
+            next_step = available_steps[idx + 1]
+
+    # Get tools needed for this step
+    tools = STEP_TOOLS.get(workflow, {}).get(step, [])
+
+    result: dict[str, Any] = {
+        "workflow": workflow,
+        "step": step,
+        "instructions": content,
+        "next_step": next_step,
+        "tools_needed": tools,
+    }
+
+    # Include rules if this is step-01 (agent needs them upfront)
+    if step == "step-01":
+        rules = load_step(workflow, "rules")
+        if rules:
+            result["rules"] = rules
+
+    return result
+
+
+def list_workflows() -> list[dict[str, Any]]:
+    """List all available workflows with brief descriptions."""
+    descriptions = {
+        "kb-init": "Initialize knowledge base: clone source -> extract skeleton -> generate docs -> quality check",
+        "kb-sync": "Incremental sync: detect changes -> update affected docs -> verify coverage",
+        "kb-search": "Knowledge base search: route questions to relevant docs, return answers with citations",
+        "kb-audit": "Quality audit: check each document against quality dimensions, generate audit report",
+    }
+    result = []
+    for name, steps in WORKFLOW_MAP.items():
+        step_count = len([s for s in steps if s.startswith("step-")])
+        result.append({
+            "name": name,
+            "description": descriptions.get(name, ""),
+            "steps": step_count,
+        })
+    return result

presets/generic/audit_dimensions.md

@@ -0,0 +1,132 @@
+# 通用检查维度
+
+> 语言无关的自检维度，配合 `doc-quality-standard.md` 和 `doc-coverage-shared.md` 使用。
+> 如需 Java/Spring Boot 特定维度，请使用 `presets/java-spring/audit_dimensions.md`。
+
+## source-tree-analysis.md
+
+修复标准见 `doc-quality-standard.md` 5.7 节（完整文件树 + 每文件详解格式 + 内容深度基准）。
+
+1. 文件完整性 — 文档列出的每个文件在源码中存在
+2. 目录结构 — 目录层级与实际一致
+3. 文件职责描述 — 描述与文件的实际功能匹配（检查注释、导出、继承）
+4. 文件数统计 — 文档中的计数与实际一致
+5. 新增/删除文件 — 源码变动在文档中反映
+
+## index.md
+
+修复标准见 `doc-quality-standard.md` 5.8 节（基本信息表 + 接口总览表 + 缓存策略概览表 + 文档导航 + 内容深度基准）。
+
+1. 链接有效性 — 所有 `[text](file.md)` 链接指向存在的文件
+2. 文件数/统计 — 引用的数量与实际一致
+3. 模块描述 — 概述与模块实际功能匹配
+4. 文档完整性 — 所有 .md 文件都在 index.md 中有链接
+
+## architecture.md
+
+对比源：依赖配置文件（`pom.xml`、`package.json`、`go.mod`、`requirements.txt` 等）、应用配置文件、框架初始化代码。
+
+1. 技术栈版本 — 框架、运行时、中间件版本与依赖配置一致
+2. 依赖清单 — 无遗漏的关键依赖
+3. 分层结构 — 模块分层与实际目录/包结构一致
+4. 中间件配置 — 数据库、缓存、消息队列等配置与实际一致
+5. 组件关系 — 远程调用、服务间依赖关系与源码一致
+6. 配置项 — 关键配置项在文档中有记录
+
+## data-models.md
+
+对比源：模型/实体定义目录（`domain/`、`models/`、`entities/`、`schemas/`、`types/` 等）。
+
+1. 实体完整性 — 每个模型/实体类在文档中有记录
+2. 字段一致性 — 字段名、类型与源码一致
+3. 表名映射 — 文档中的表名/集合名与 ORM 映射一致
+4. DTO/VO 覆盖 — 请求/响应数据结构在文档中有记录
+5. 枚举值 — 枚举/常量的所有值完整列出
+6. 继承/实现 — 继承关系、实现的接口与源码一致
+
+## api-contracts.md
+
+对比源：路由定义、控制器、API handler 目录。
+
+1. 接口完整性 — 每个 API 端点在文档中有记录
+2. URL 路径 — 路由路径与文档一致
+3. HTTP 方法 — GET/POST/PUT/DELETE 与源码一致
+4. 请求参数 — 参数名、类型、是否必填与源码一致
+5. 响应类型 — 返回值类型与文档一致
+6. 错误码 — 方法中返回的错误码在文档中有记录
+
+## business-logic.md
+
+按 `doc-quality-standard.md` 第 5 节 10 项维度，额外关注以下通用模式：
+
+1. 事务边界 — 事务注解/装饰器的传播级别、回滚规则
+2. 异步处理 — 异步任务的线程池/队列配置
+3. 定时任务 — cron 表达式、执行频率
+4. 消息消费 — topic、消费组、并发配置
+5. 缓存策略 — 缓存 key、TTL、失效策略
+6. 限流/熔断 — 资源名、降级策略
+7. 重试机制 — 重试次数、退避策略
+8. 外部配置 — 配置项 key、默认值
+
+## observability.md
+
+对比源：监控指标注册代码、日志配置文件、健康检查端点。
+
+1. 指标完整性 — 所有自定义监控指标在文档中有记录
+2. 指标名称 — metric name 与源码中注册的一致
+3. 告警阈值 — 阈值配置与源码/配置文件一致
+4. 日志配置 — 日志级别、格式、输出目标与配置一致
+5. 健康检查 — 自定义健康检查端点与源码一致
+
+## utils.md
+
+对比源：`util/`、`utils/`、`helper/`、`common/`、`lib/` 目录。
+
+1. 工具类完整性 — 有复杂逻辑的工具方法在文档中有记录
+2. 方法签名准确性 — 参数类型、返回类型与源码一致
+3. 边界行为 — null 处理、精度丢失、时区问题等隐式行为与源码一致
+4. 线程安全性 — 并发相关设计（如有）与源码一致
+5. 使用上下文 — 高频调用方法的典型调用场景与实际使用一致
+
+## 可选文档
+
+### 可选文档触发条件
+
+扫描源码时，命中以下模式则对应文档变为必需：
+
+| 文档 | 触发模式（任一命中即触发） |
+|------|------------------------|
+| messaging.md | 目录名含 `/consumer/`、`/listener/`、`/subscriber/`；文件名含 `*consumer*`、`*listener*`、`*producer*`、`*publisher*`；代码中引用 Kafka/RabbitMQ/Pulsar/RocketMQ 等消息队列客户端 |
+| caching.md | 目录名含 `/cache/`、`/redis/`；文件名含 `*cache*`、`*redis*`；代码中引用 Redis/Memcached/Caffeine 等缓存客户端 |
+| external-integrations.md | 代码中使用 HTTP 客户端库发起外部调用（排除内部服务间 RPC/Feign 调用） |
+
+检测命令示例：
+```shell
+# 检测消息队列使用（通用模式）
+git -C {repo} grep -rl "consumer\|listener\|producer\|publisher" {ref} -- "*/consumer/*" "*/listener/*" "*/mq/*"
+
+# 检测缓存使用（通用模式）
+git -C {repo} grep -rl "cache\|redis\|memcache" {ref} -- "*/cache/*" "*/redis/*"
+
+# 检测外部 HTTP 调用（通用模式）
+git -C {repo} grep -rl "HttpClient\|http\.request\|requests\.get\|fetch(" {ref}
+```
+
+### messaging.md
+
+1. Topic/Queue 完整性 — 所有消息生产/消费的 topic/queue 有记录
+2. 消息体结构 — 生产者发送的对象类型与文档一致
+3. 消费者分组 — 消费组 ID 与源码一致
+4. 生产/消费关系 — 哪个类生产、哪个类消费与源码一致
+
+### caching.md
+
+1. Key/Cache 完整性 — 所有缓存操作的 key pattern/cache name 有记录
+2. TTL — 过期时间与源码一致
+3. 数据类型 — 使用的数据结构类型与源码一致
+
+### external-integrations.md
+
+1. 集成方完整性 — 所有外部 HTTP/SDK 调用有记录
+2. 接口地址 — URL/配置项与源码一致
+3. 认证方式 — Token/签名/OAuth 与源码一致

presets/generic/doc_types.yaml

@@ -0,0 +1,152 @@
+# Generic Preset — doc_types 配置
+# 适用于非 Java 项目（Python, Go, Node.js, Rust 等）
+
+doc_types:
+  # Batch 1: 全局概览（无源码依赖）
+  source-tree-analysis:
+    filename: "source-tree-analysis.md"
+    batch: 1
+    global_view: true
+    conditional: false
+    search_keywords: ["目录结构", "文件树", "类职责", "包结构", "文件", "源码结构"]
+    size_expectations:
+      min: 500
+      warn_max: 30000
+      hard_max: 60000
+
+  # Batch 2: 数据层
+  data-models:
+    filename: "data-models.md"
+    batch: 2
+    conditional: false
+    search_keywords: ["表", "字段", "实体", "模型", "Schema", "类型定义"]
+    dedup_patterns: ["| 字段 | 类型 |", "字段表格"]
+    size_expectations:
+      min: 500
+      warn_max: 50000
+      hard_max: 80000
+
+  # Batch 3: API + 架构 + 可选文档
+  api-contracts:
+    filename: "api-contracts.md"
+    batch: 3
+    conditional: true
+    search_keywords: ["接口", "API", "参数", "错误码", "URL", "端点", "路由"]
+    depends_on: ["data-models"]
+    size_expectations:
+      min: 500
+      warn_max: 50000
+      hard_max: 80000
+
+  architecture:
+    filename: "architecture.md"
+    batch: 3
+    conditional: false
+    search_keywords: ["架构", "依赖", "配置", "技术栈", "中间件", "分层"]
+    size_expectations:
+      min: 500
+      warn_max: 40000
+      hard_max: 60000
+
+  external-integrations:
+    filename: "external-integrations.md"
+    batch: 3
+    conditional: true
+    search_keywords: ["外部调用", "HTTP", "SDK", "第三方", "远程服务"]
+    size_expectations:
+      min: 500
+      warn_max: 30000
+      hard_max: 50000
+
+  observability:
+    filename: "observability.md"
+    batch: 3
+    conditional: true
+    search_keywords: ["监控", "指标", "日志", "告警", "Metrics", "健康检查"]
+    size_expectations:
+      min: 500
+      warn_max: 30000
+      hard_max: 50000
+
+  # Batch 4: 业务逻辑 + 工具类
+  business-logic:
+    filename: "business-logic.md"
+    batch: 4
+    conditional: false
+    search_keywords: ["怎么实现", "流程", "调用链", "业务逻辑", "方法实现"]
+    depends_on: ["data-models", "api-contracts"]
+    size_expectations:
+      min: 1000
+      warn_max: 60000
+      hard_max: 100000
+    split_override:
+      readwrite:
+        max_lines: 8000
+        max_files_per_shard: 60
+
+  utils:
+    filename: "utils.md"
+    batch: 4
+    conditional: true
+    search_keywords: ["工具类", "工具方法", "Util", "Helper", "Common"]
+    depends_on: ["data-models"]
+    size_expectations:
+      min: 500
+      warn_max: 30000
+      hard_max: 50000
+
+  # Batch 5: 索引（全局汇总）
+  index:
+    filename: "index.md"
+    batch: 5
+    global_view: true
+    conditional: false
+    search_keywords: ["概览", "模块介绍", "有哪些功能", "导航", "索引"]
+    depends_on: ["business-logic", "architecture", "data-models"]
+    size_expectations:
+      min: 500
+      warn_max: 20000
+      hard_max: 40000
+
+# ============================================================
+# Split 阈值
+# ============================================================
+split:
+  output-only:
+    max_bytes: 307200
+    max_lines: 8000
+    max_files_per_shard: 80
+    llm_sample_limit: 200      # [CLI only] Max files sampled for LLM-based split grouping
+  readwrite:
+    max_bytes: 512000
+    max_lines: 10000
+    max_files_per_shard: 80
+  # [Both modes] Noise words filtered when deriving shard group names from class names
+  noise_words:
+    - service
+    - impl
+    - base
+    - controller
+    - manager
+    - handler
+    - listener
+    - api
+    - abstract
+    - default
+
+# ============================================================
+# Limits
+# ============================================================
+limits:
+  min_doc_size_bytes: 500
+  max_source_inline_bytes: 300000
+  max_skeleton_inline_bytes: 50000
+  spawn_timeout_default: 600
+  max_retries: 2
+  max_consecutive_failures: 3
+  failure_rate_threshold: 0.5
+  garbage_patterns:
+    - "<web_search>"
+    - "<read_file>"
+    - "<search_results>"
+    - "Search results for"