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项目已正式开源。
AI辅助编程的最后一公里：项目知识库
在前文《从Vibe到Spec:让AI编程更可控的结构化思考》中提到，目前AI辅助编程的最佳实践是Spec Coding——通过结构化的需求文档、技术方案、任务拆分来驾驭AI，而非纯粹的Vibe Coding。
但这里有个关键问题：需求质量。
如果项目需求不够规范，后续无论AI能力多强，生成的代码质量都会大打折扣。此时，便会想到，能否让AI辅助完善需求？
当然可以，但前提是AI需先理解需求的背景知识：功能模块原有的逻辑细节是什么？历史上是如何演进的？有哪些潜在问题？
这便依赖于项目知识库。
目前，Devin.ai的DeepWiki在项目知识库方面表现出色。只需将Github仓库链接中的github改为deepwiki，即可看到其自动生成的详细项目知识库，效果相当不错。官方还提供了MCP Server支持知识库问答。
但存在以下问题：
- 项目必须开源且托管在Github上：许多公司内部项目无法满足此条件。
- 未开源：无法自行部署。
- 开源版本效果一般：Github上虽有open-deepwiki实现，但效果与官方版差距不小。
这催生了一个想法：能否利用Claude Agent SDK打造一套实用的DeepWiki工具?
claude-deep-wiki：设计思路
构思既定，在着手开发前，首先明确了几个核心目标和设计原则。
核心目标
期望实现的效果是：
- 分析任何代码仓库（不限于Github，私有仓库也能用）
- 生成面向业务的知识库（而非技术API文档，而是产品经理也能看懂的功能描述）
- 支持165+编程语言（受益于Tree-sitter库）
- 防止AI编造（通过代码验证机制确保分析结果真实可靠）
设计理念：多Agent协作
如果让单个AI一口气分析完整个代码仓库，基本不可行，先不说上下文是否能容纳如此多内容，最终输出结果大概率也不可控，可能遗漏重要模块，或编造一些不存在的功能。
更好的方式是：让不同的Agent各司其职，像一个专业团队那样协作。
设计了三个专职Agent：
- 结构扫描Agent：负责扫描代码仓库、识别模块层次、依赖关系。
- 语义分析Agent：负责深入理解代码的业务逻辑和功能价值。
- 文档生成Agent：负责将分析结果转化为产品功能文档。
这三个Agent按流水线方式工作，每个阶段的输出都是下一个阶段的输入。
有了这个多Agent架构，接下来的问题是：如何让这些Agent拥有稳定的代码分析能力？之前提到，无法将所有代码一次性提供给AI。
核心技术：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="扫描代码仓库结构,返回目录树、文件统计和语言分布信息"
)
async def 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", ...)
async def extract_imports_tool(args):
...
@tool(name="analyze_code_block", ...)
async def analyze_code_tool(args):
...
@tool(name="build_dependency_graph", ...)
async def build_dependency_tool(args):
...
@tool(name="search_code_patterns", ...)
async def search_patterns_tool(args):
...
@tool(name="validate_analysis_result", ...)
async def 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个工具分别负责：
-
scanrepositorystructure：扫描目录结构，统计文件类型
-
extractimportsand_exports：提取文件的导入导出关系（主要基于Tree-sitter AST解析）
-
analyzecodeblock：深度分析代码片段，提取结构化信息（函数、类、导入导出等）
-
builddependencygraph：构建模块依赖图，分析循环依赖
-
searchcodepatterns：搜索特定代码模式（API路由、数据库模型等）
-
validateanalysisresult：验证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，其功能包括：
- 估算token消耗：按
字符数 / 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
为何按关联度分组?
代码分析时需要上下文支持。例如，若将chatService.ts和chatUtils.ts分至不同批次，AI将无法识别它们的调用关系，从而影响分析质量。
每个批次分析完后，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, "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 not in doc:
issues.append(f"缺少章节: {section}")
return issues
如果发现问题，会输出警告，方便手动修正。
最终输出的PRD文档，能够最大限度保障其完全面向业务人员，几乎不含技术术语。
防止AI编造的机制
三个阶段的流程看起来很完整，但一个关键问题是：如何确保AI的分析是真实可靠的？
这应该是所有DeepWiki类工具都要面对的难题。
为此，设计了两层防护机制：
第一层：结构验证
所有的函数名、类名、导入关系都是通过Tree-sitter从AST中提取的，这些是编译器级别的真实数据，AI无法编造。
@tool(name="validate_analysis_result")
async def 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还提供了多种权限模式，有助于控制代理的安全性。
