Claude Agent SDK实战：打造开源版DeepWiki

前一段时间，Anthropic发布了Claude Sonnet 4.5，日常使用中我明显感觉它编码的稳定性相较于4.0有了显著提升。

同时发布的还有全新的Claude Agent SDK。这个SDK其实就是将Claude Code底层强大的Agent能力抽象出来，可以为任何应用场景赋能AI。

Claude Code的强大我在前文《Coding之外:Claude Code如何充当我的工作助手》也有聊到，它内置18个工具，包括本地文件检索、命令执行、任务规划、架构分析等。再结合MCP、自定义指令、子代理、多模态支持等完整的生态系统，让它成为了一个不局限于编程领域的全能AI助手。

说白了，有了Claude Agent SDK，咱们就能复制Claude Code的能力，为自己的业务场景定制专属的AI Agent。

今天的文章就来聊聊我是如何用这个SDK打造一个开源版DeepWiki的。

“

claude-deep-wiki项目已开源：https://github.com/skindhu/claude-deep-wiki

AI辅助编程的最后一公里：项目知识库

我在前文《从Vibe到Spec:让AI编程更可控的结构化思考》中提到过，目前AI辅助编程的最佳实践是Spec Coding —— 通过结构化的需求文档、技术方案、任务拆分来驾驭AI，而不是纯粹的Vibe Coding。

但这里有个关键问题：需求质量。

如果项目需求不够规范，后续无论AI能力多强，生成的代码质量都会大打折扣。这时候，我们就会想到，能否让AI能辅助完善需求？

当然可以，但前提是AI得先理解咱们需求的背景知识：这个功能模块原有的逻辑细节是什么？历史上是如何演进的？有哪些坑？

这就依赖于项目知识库。

我个人觉得目前做得最好的是Devin.ai的DeepWiki。你只需要把Github仓库链接中的github改成deepwiki，就能看到它自动生成的详细项目知识库，效果挺不错。官方还提供了MCP Server支持知识库问答。

但问题来了：

1. 项目必须开源且托管在Github上：很多公司内部项目根本做不到
2. 没有开源：你想自己部署都不行
3. 开源版本效果一般：Github上有人实现了open-deepwiki，但效果和官方版差距不小

这让我萌生了一个想法：能不能用Claude Agent SDK自己打造一套好用的DeepWiki工具?

claude-deep-wiki：设计思路

有了想法就干。在动手之前，我先明确了几个核心目标和设计原则。

核心目标

我希望实现的效果是：

• 分析任何代码仓库（不限于Github，私有仓库也能用）
• 生成面向业务的知识库（不是技术API文档，而是产品经理也能看懂的功能描述）
• 支持165+编程语言（受益于Tree-sitter库）
• 防止AI编造（通过代码验证机制确保分析结果真实可靠）

设计理念：多Agent协作

如果让单个AI一口气分析完整个代码仓库，基本不可行，先不说上下文是否能容纳这么多内容，最终输出的结果大概率也不可控，可能遗漏重要模块，或编造一些不存在的功能。

更好的方式是：让不同的Agent各司其职，像一个专业团队那样协作。

我设计了三个专职Agent：

1. 结构扫描Agent：负责扫描代码仓库、识别模块层次、依赖关系
2. 语义分析Agent：负责深入理解代码的业务逻辑和功能价值
3. 文档生成Agent：负责将分析结果转化为产品功能文档

这三个Agent按流水线方式工作，每个阶段的输出都是下一个阶段的输入。

有了这个多Agent架构，接下来的问题是：如何让这些Agent拥有稳定地代码分析能力？ 刚刚也说了，我们不能一股脑把所有的代码全部塞给它。

核心技术：SDK内置MCP Server

Claude Agent SDK比较强大的地方，就是支持创建in-process MCP Server，不需要启动子进程，直接在同一个进程里运行。

这样，我就可以用@tool装饰器快速定义自己的工具集，然后通过create_sdk_mcp_server把它们打包成一个MCP Server，让Agent调用。

我定义了6个核心工具：

from claude_agent_sdk import tool, create_sdk_mcp_server

@tool(
    name="scan_repository_structure",
    description="扫描代码仓库结构,返回目录树、文件统计和语言分布信息"
)

asyncdef scan_repo_tool(args: Dict[str, Any]) -> Dict[str, Any]:
    """扫描仓库结构"""
    result = scan_repository_structure(
        repo_path=args["repo_path"],
        max_depth=args.get("max_depth", 5)
    )
    return {"content": [{"type": "text", "text": json.dumps(result)}]}

@tool(name="extract_imports_and_exports", ...)
asyncdef extract_imports_tool(args): ...

@tool(name="analyze_code_block", ...)
asyncdef analyze_code_tool(args): ...

@tool(name="build_dependency_graph", ...)
asyncdef build_dependency_tool(args): ...

@tool(name="search_code_patterns", ...)
asyncdef search_patterns_tool(args): ...

@tool(name="validate_analysis_result", ...)
asyncdef validate_analysis_tool(args): ...

# 创建MCP Server
mcp_server = create_sdk_mcp_server(
    name="code-analysis-tools",
    tools=[
        scan_repo_tool,
        extract_imports_tool,
        analyze_code_tool,
        build_dependency_tool,
        search_patterns_tool,
        validate_analysis_tool
    ]
)

这6个工具分别负责：

• scan_repository_structure：扫描目录结构，统计文件类型

• extract_imports_and_exports：提取文件的导入导出关系（主要基于Tree-sitter AST解析）

• analyze_code_block：深度分析代码片段，提取结构化信息（函数、类、导入导出等）

• build_dependency_graph：构建模块依赖图，分析循环依赖

• search_code_patterns：搜索特定代码模式（API路由、数据库模型等）

• validate_analysis_result：验证AI分析结果是否准确（防止编造）

关键点在于：这些工具直接调用Tree-sitter解析AST，提取的都是真实代码结构，AI无法编造。

三阶段分析流程

有了工具集和多Agent架构，接下来就是具体的执行流程了。整个分析过程我分为三个阶段，每个阶段由对应的Agent负责，层层递进。

阶段1：结构扫描 - 搞清楚有什么

结构扫描Agent的任务很明确，就是搞清楚这个项目有哪些模块，它们之间的依赖关系是什么。

但这里有个关键设计：分三步走，提升可调试行，同时避免一次性塞爆上下文。

class StructureScannerAgent:
    async def scan_repository(self, repo_path: str):
        # 步骤1: 扫描结构,识别模块(1次工具调用)
        structure = await self._scan_and_identify_modules(repo_path)

        # 步骤2: 提取依赖关系(N次工具调用)
        dependencies = await self._analyze_file_dependencies(structure, repo_path)

        # 步骤3: 整合数据,精确分层(0次工具调用)
        final = await self._finalize_structure(structure, dependencies)

步骤1：扫描与识别

只调用1次scan_repository_structure工具，快速扫描目录结构。这一步Claude只看目录名和文件名，就能识别出模块:

• src/services/chatService.ts → "聊天服务模块"
• src/components/Button/ → "按钮组件"
• src/utils/validator.ts → "验证工具"

同时我让Claude为每个模块选出5-10个关键文件，比如入口文件、管理类、核心业务逻辑文件等。

步骤2：依赖分析

针对步骤1选出的关键文件，逐个调用extract_imports_and_exports工具提取导入导出关系。这一步是纯事实提取，AI无法编造:

# chatService.ts的导入导出
{
  "imports": ["axios", "./chatUtils", "../config"],
  "exports": ["ChatService", "sendMessage"],
  "language": "typescript"
}

步骤3：综合分析

拿到了模块列表和依赖关系,最后一步是整合数据。Agent会让Claude分析:

• 模块分层：被多个模块依赖的是core层，依赖core的是business层
• 依赖关系图：谁依赖谁，有没有循环依赖
• 文件映射：每个文件属于哪个模块

输出是一个完整的项目结构，包括模块清单、依赖图、分层信息。

为什么分三步?

说白了，就是为了准确性。如果让AI一次性扫描全部代码，它可能会遗漏关键信息。分步进行，每步任务明确，结果更可靠，过程中出问题的可调试性也更高。

阶段2：语义分析 - 理解做什么

结构扫描只是识别了“有哪些模块”，但还不知道“这些模块干什么”。语义分析Agent就是来回答这个问题的。

这个阶段有两个关键设计：两轮分析 + 智能分批。

先不急着读每个文件，而是让Claude看模块的整体结构，理解业务价值：

prompt = f"""
你是资深架构师。请分析模块'{module_name}'的业务价值。

关键文件:
- src/services/chatService.ts
- src/utils/chatUtils.ts

请回答:
1. 这个模块的业务目的是什么?
2. 核心功能有哪些?
3. 和其他模块如何交互?

Claude会返回：

{
  "business_purpose": "智能客服对话引擎,处理用户问答交互",
  "core_features": [
    "实时消息收发",
    "内容安全过滤",
    "多格式消息支持"
  ],
  "external_interactions": [
    "调用后端AI服务",
    "使用状态管理存储对话"
  ]
}

有了这个概览，第二轮分析就有了上下文。

第二轮：细节挖掘（批处理）

这里是整个项目最复杂的部分。一个模块可能有几十甚至上百个文件，全部塞给Claude会超过上下文限制。

我的解法是：智能分批 + 按关联度分组。

我设计了FileAnalysisBatchManager ，它会：

1. 估算token消耗：按字符数 / 3来大致估算，咱们也不需要非常准确
2. 按关联度分组：互相导入的文件尽量分到同一批
3. 控制批次大小：每批不超过150K tokens，这样可以为200k上下文留一些安全边际

class FileAnalysisBatchManager:
    def create_file_batches(self, files):
        """按关联度智能分批"""
        # 1. 计算文件间的关联度(基于导入关系)
        cohesion_scores = self._calculate_cohesion(files)

        # 2. 贪心分批:优先将高关联度文件放同一批
        batches = []
        for file in sorted(files, key=lambda f: cohesion_scores[f], reverse=True):
            # 找能容纳这个文件的批次
            for batch in batches:
                if batch['tokens'] + file['tokens'] < 150000:
                    batch['files'].append(file)
                    break
            else:
                # 创建新批次
                batches.append({'files': [file], 'tokens': file['tokens']})

        return batches

为什么按关联度分组?

我这里的思考是，Claude分析代码时需要上下文。例如，如果把chatService.ts和chatUtils.ts分到不同批次，Claude就看不到它们的调用关系，分析质量会下降。

每个批次分析完后，Agent会合并结果：

# 批次1结果
{
"files_analysis": [
    {"file": "chatService.ts", "functions": [...]},
    {"file": "chatUtils.ts", "functions": [...]}
  ]
}

# 批次2结果
{
"files_analysis": [
    {"file": "messageFilter.ts", "functions": [...]}
  ]
}

# 智能合并
merged = {
"files_analysis": [...],  # 所有文件的分析
"cross_file_relationships": [...],  # 跨文件关系
"summary": {"total_functions": 4:扫描与识别5, "total_classes": 12}
}

阶段3：文档生成 - 翻译成业务表述

前两个阶段已经把所有技术细节都分析清楚了,但这些内容对于产品经理或业务人员来说还是太技术化。

文档生成Agent主要做三件事：智能分组 → 生成PRD → 生成索引。

步骤1：产品功能域分组

这一步比较有意思，Agent会让Claude扮演资深产品经理，将技术模块重新组织：

prompt = f"""
你是资深产品经理。请将以下技术模块按产品功能域分组:

技术模块:
- components: 通用UI组件
- pages: 各业务页面
- services: API服务调用
- stores: 状态管理
- assets: 静态资源

分组原则:
1. 按业务价值,不是技术架构
2. 每个功能域对应一个独立的产品能力
3. 基础模块可以被多个功能域复用
"""

这里我考虑的关键点是，最终文档的呈现结构应该是基于业务价值，而不是技术架构。

这就是为什么最终文档产品经理能看懂，因为它是用户视角组织的，而不是从代码结构组织的。

步骤2：生成PRD文档

对每个功能域，Agent会生成一份完整的PRD，包含4个标准章节:

“

第1章：功能域概述

• 功能定位（这是干什么的）
• 业务价值（能带来什么好处）
• 核心能力列表（提供哪些能力）
• 子域结构（如果功能域很大,如何进一步划分）

第2章：功能详细说明

• 每个核心能力的详细描述
• 使用场景举例
• 业务流程图（用Mermaid绘制）
• 业务规则和异常处理

第3章：跨功能交互

• 对外交互（和其他功能域如何协作）

• 数据依赖（依赖哪些外部数据或服务）

第4章：业务约束与限制

• 性能约束、并发限制等

如果功能域包含的文件太多，还会分批生成再智能合并：

async def _generate_prd_multi_batch(self, domain_info, modules_data):
    """大功能域分批生成"""
    # 批次1:生成完整框架 + 部分详细内容
    batch1 = await self._generate_first_batch(domain_info, modules_data[:10])

    # 批次2-N:只生成详细内容
    batch2 = await self._generate_continuation(domain_info, modules_data[10:20])

    # 智能合并:将批次2的内容插入批次1的"功能详细说明"章节
    merged = self._merge_prd_batches([batch1, batch2])

步骤3：质量验证

生成完文档后，Agent会自动检查质量:

def _validate_prd_quality(self, doc):
    """验证PRD质量"""
    issues = []

    # 检查是否包含技术术语(不应该有)
    tech_terms = ['function', 'class', 'API', 'parameter']
    for term in tech_terms:
        if term in doc:
            issues.append(f"包含技术术语: {term}")

    # 检查必要章节
    required = ['功能详细说明', '业务流程']
    for section in required:
        if section notin doc:
            issues.append(f"缺少章节: {section}")

    return issues

如果发现问题，会输出警告，方便我们手动修正。

最终输出的PRD文档，就可以尽量保障是完全面向业务人员的，几乎没有技术术语。

防止AI编造的机制

三个阶段的流程看起来很完整，但有个关键问题：如何确保AI的分析是真实可靠的？

这应该是所有DeepWiki类工具都要面对的难题。

为此，我设计了两层防护：

第一层：结构验证

所有的函数名、类名、导入关系都是通过Tree-sitter从AST中提取的，这些是编译器级别的真实数据,AI无法编造。

@tool(name="validate_analysis_result")
asyncdef validate_analysis_tool(args):
    """验证AI分析结果"""
    analysis = args["analysis"]
    source_code = args["source_code"]

    # 1. 用Tree-sitter解析源代码,提取真实结构
    actual_functions = extract_functions_from_ast(source_code)
    actual_classes = extract_classes_from_ast(source_code)

    # 2. 检查AI声称的函数是否都存在
    claimed_functions = set(f["name"] for f in analysis["functions"])
    fake_functions = claimed_functions - actual_functions

    if fake_functions:
        return {
            "is_valid": False,
            "errors": [f"编造的函数: {list(fake_functions)}"]
        }

    return {"is_valid": True}

第二层：交叉验证

在语义分析阶段，Agent会先让Claude分析代码，然后立即调用validate_analysis_result工具验证。如果发现编造，会要求重新分析。

# 分析代码
analysis = await self._analyze_code(file_content)

# 立即验证
validation = await self._validate_analysis(analysis, file_content)

if not validation["is_valid"]:
    # 重新分析或标记错误
    self._log(f"验证失败: {validation['errors']}")

有了这两层防护，我基本消除了AI编造的风险。实测下来，验证失败率不到5%，而且一旦发现问题立即重新分析，这样就能尽量保障最终输出的准确率。

Claude Agent SDK的设计哲学

说完了具体的实现，再聊聊这个过程中我对Claude Agent SDK的一些理解。

Claude Agent SDK的设计哲学，就是对开发者仅暴露出一个结构化的代理循环：收集上下文、执行操作、验证工作和重复。

其它复杂的细节，如工具调用的序列化和反序列化、多轮对话的状态管理、MCP协议的实现细节全部在SDK底层默默做好。而针对不同的工具调用，SDK还提供了多种权限模式，能帮助我们尽量控制代理的安全性。