Claude Agent SDK + LLM-wiki，就是最强大的agentic RAG

开源地址：https://github.com/liangdabiao/llm-wiki-claude-agent-sdk-agentic-rag

本项目基础是基于开源项目：https://github.com/kenneth-liao/claude-agent-sdk-intro ， 前6个课程是属于原项目， 而我基于项目进一步发展成：Claude Agent SDK + LLM-wiki，最强大的agentic RAG 。 本项目主要展示了我制作的 llm-wiki 怎样通过 Claude Agent SDK 转为 agentic rag， 效果非常好的。 核心文件是： 7_wiki_writer.py ， wiki_writer_api.py 。

使用演示：

python 7_wiki_writer.py --request "整理一个AI学习路线图给我"

如下图，claude agent sdk 自己规划工作计划，自己执行，自己agentic agent工作，最后给我返回工作结果。

🤔 什么是 LLM-wiki？

LLM Wiki：用大语言模型把你的零散知识，自动整理成一部结构化的“个人百科全书”。传统的做法是，每次你想问 AI 一个问题，AI 都要重新翻一遍你的所有资料，找到相关的再回答你（这叫 RAG，检索增强生成）。这就好比你每次问图书管理员一个问题，他都要把整个图书馆的书重新翻一遍。Karpathy 说，这太蠢了。正确的做法是：让 AI 当一个“知识编译器”，先把你的所有资料读一遍，整理成一本结构清晰、彼此关联的百科全书。以后你再提问，AI 直接翻这本百科书就行了。

原来的RAG系统的完整链路是这样的：ingest → chunk → index → retrieve → rerank → prompt-pack → generate → cite ， Karpathy 大神的确非常深刻，过去几年最重要的ai概念都是他总结出来，都是看起来很简单，但是达到了最本质。llm wiki被大大低估了，这个东西就是开发ai的根。 我给你看看， 其实k大神的意思是这些， 这个wiki格式是非常重要，ai就是靠这个组织了整个知识 所以，它一下子解决了rag全部问题，我已经不再用rag了，因为这个才是答案。 除了rag，它可以一键生成wiki网站，真正的知识库 幸好我测试多个，现在知道这个好东西，基于这个东西，我可以搞很多厉害的项目，因为 理解越深，生成越深，本质就是这样搞ai 。 目前项目的wiki文件夹就是放wiki资料的地方，我暂时放了 鱼皮大牛 写的一些开源文章，用来测试效果。

🤔 什么是 Claude Agent SDK？

简单说，这是一个让AI拥有"手脚"的工具箱：

• 普通AI = 只会给建议的顾问
• Agent SDK加持的AI = 能直接帮你干活的工程师

它能让Claude不仅会"思考"，还能"动手做事"——比如读取文件、修改代码、运行命令等。

🧐 Claude Agent SDK vs Claude Code

核心区别

维度	Claude Code	Claude Agent SDK
本质	交互式CLI工具	编程开发SDK
使用方式	终端命令行交互	代码中调用
适用场景	日常开发、快速原型	构建自动化系统、集成到产品
灵活性	预设工作流	完全自定义工作流
控制粒度	粗粒度（任务级）	细粒度（步骤级）

详细对比

🖥️ Claude Code - 交互式开发助手

作用：作为日常开发的AI助手，帮助你快速完成编码任务

特点：

• 🎯 交互式体验：直接在终端或IDE中对话
• ⚡ 快速上手：无需编程，输入命令即可使用
• 🛠️ 内置工具：默认支持读文件、写代码、运行命令
• 🧠 智能决策：自主判断下一步该做什么

适用场景：

• 快速编写代码片段
• 修复简单的Bug
• 生成文档和注释
• 日常开发辅助

🧰 Claude Agent SDK - 构建自动化系统

作用：将Claude的能力集成到你的应用程序中，构建自动化系统

特点：

• 🚀 可编程：用代码完全控制AI的行为
• 🧩 可扩展：自定义工具和工作流
• 🎯 精准控制：细粒度控制每一步操作
• 🔌 可集成：嵌入到现有系统中

适用场景：

• 构建AI驱动的自动化工具
• 集成到产品中提供AI功能
• 构建复杂的多Agent系统
• 批量处理任务

🤝 协作关系

Claude Agent SDK 是 Claude Code 的编程接口包装：

• Claude Code 是引擎，提供核心AI能力
• Agent SDK 是驱动程序，让你能在代码中调用引擎
• 两者结合，既可以快速交互，也可以构建复杂系统

来源：掘金文章、Anthropic文档

🎯 基础的1-6章节将学到什么

核心技能

• ✅ 让AI自动读文件、写代码、改文档
• ✅ 构建能记住上下文的对话式AI助手
• ✅ 让AI学会使用外部工具（比如浏览器、数据库）

项目实战

• 🚀 实战：学习使用 7_wiki_writer.py：命令行版Wiki文章rag生成器
• 🌐 学习使用 wiki_writer_api.py：API版Wiki文章rag生成服务
• ⚙️ 精细控制AI的行为（比如只允许读特定目录）
• 🧩 组合多个AI完成更复杂的工作流

🛠️ 前置要求

必装工具

1. Python 3.13+：编程语言
2. uv：Python 包管理器（替代 pip）

   # 安装 uv
   curl -LsSf https://astral.sh/uv/install.sh | sh

3. Claude Code：AI Agent 核心引擎

   npm install -g @anthropic-ai/claude-code

可选工具（高级功能需要）

• Chrome 浏览器：用于网页交互（模块 5-6）
• Node.js：用于运行浏览器自动化（模块 5-6）

API 密钥（二选一）

1. Anthropic API 密钥：官方 API（在 console.anthropic.com 获取）
2. 第三方 API：比如 DeepSeek（免费额度更高），兼容 claude api则可以。

🚀 快速开始

1. 克隆项目

git clone https://github.com/liangdabiao/llm-wiki-claude-agent-sdk-agentic-rag
cd llm-wiki-claude-agent-sdk-agentic-rag

2. 一键安装依赖

# 创建虚拟环境并安装所有依赖
uv sync

3. 激活虚拟环境

# Windows PowerShell
\.venv\Scripts\Activate.ps1

# Linux/Mac
source .venv/bin/activate

🎯 核心项目介绍

1. 7_wiki_writer.py - 命令行版Wiki文章rag生成器

📋 功能特点

• Agentic工作方式：不需要手动指定调用流程，Claude会自主判断并调用Skill
• 交互式模式：支持实时对话，输入需求即可生成Wiki文章
• 命令行模式：适合批量处理和脚本集成
• 自动调用Skill：自动识别并调用llm-wiki-skill查询知识库

🚀 使用方法

# 交互式模式（推荐）
python 7_wiki_writer.py --interactive

# 命令行模式
python 7_wiki_writer.py --request "查询关于DeepSeek使用技巧的内容"

💡 RAG工作原理

1. 分析用户请求，判断是否需要调用llm-wiki-skill
2. 自动搜索wiki目录中的相关内容
3. 读取并整理相关文件
4. 生成结构化的回答

---

2. wiki_writer_api.py - API版Wiki文章RAG生成服务

📋 功能特点

• FastAPI服务：基于FastAPI构建的高性能HTTP服务
• SSE流式响应：支持Server-Sent Events，实时返回生成进度
• 同步响应：支持直接返回完整结果
• 健康检查：内置健康检查端点
• 跨域支持：配置CORS，支持前端调用

🚀 启动服务

# 开发模式（自动重载）
uvicorn wiki_writer_api:app --host 0.0.0.0 --port 8000 --reload

# 生产模式
uvicorn wiki_writer_api:app --host 0.0.0.0 --port 8000

📡 API端点

GET  /health                    - 健康检查
POST /api/v1/wiki/generate      - 流式生成 (SSE)
POST /api/v1/wiki/generate/sync - 同步生成 (JSON)

📝 请求示例

# 流式生成请求
curl -X POST "http://localhost:8000/api/v1/wiki/generate" \
  -H "Content-Type: application/json" \
  -d '{
      "request": "查询关于DeepSeek使用技巧的内容",
      "model": "deepseek-chat",
      "stream": true
  }'

# 同步生成请求
curl -X POST "http://localhost:8000/api/v1/wiki/generate/sync" \
  -H "Content-Type: application/json" \
  -d '{
      "request": "查询关于DeepSeek使用技巧的内容",
      "model": "deepseek-chat"
  }'

🔑 .env 配置 API 密钥（二选一）

方案 A：使用官方 Anthropic API

# 创建 .env 文件
ANTHROPIC_API_KEY=your_anthropic_api_key

方案 B：使用第三方 API（推荐 DeepSeek）

DeepSeek 提供免费额度更高的 API，配置示例：

# DeepSeek API 配置
ANTHROPIC_AUTH_TOKEN=sk-your_deepseek_api_key
ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
MODEL=deepseek-v4-flash

📝 关键配置说明

1. 环境变量区别

• ANTHROPIC_AUTH_TOKEN：用于第三方 API（如 DeepSeek）
• ANTHROPIC_API_KEY：仅用于官方 Anthropic API

2. DeepSeek 模型选择

模型名称	特点	推荐场景
deepseek-v4-flash	快速、经济	日常使用（推荐）
deepseek-v4-pro	性能更强	复杂任务
deepseek-chat	兼容旧版	迁移项目
deepseek-reasoner	推理模式	需要深度思考的任务

3. 环境变量加载问题

如果系统已存在同名环境变量，.env 文件中的值可能被覆盖。解决方法：

from dotenv import load_dotenv
import os

# 强制从 .env 文件加载，覆盖系统环境变量
load_dotenv(override=True)

# 读取配置
MODEL = os.getenv("MODEL", "haiku")
AUTH_TOKEN = os.getenv("ANTHROPIC_AUTH_TOKEN")
BASE_URL = os.getenv("ANTHROPIC_BASE_URL", "https://api.anthropic.com")

# 创建 Agent 配置
options = ClaudeAgentOptions(
    model=MODEL,
    env={
        "ANTHROPIC_AUTH_TOKEN": AUTH_TOKEN,
        "ANTHROPIC_BASE_URL": BASE_URL,
    }
)

4. 验证配置

使用 curl 测试 DeepSeek API 是否可访问：

curl -X POST "https://api.deepseek.com/anthropic/v1/messages" \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-your_deepseek_api_key" \
  -d '{"model": "deepseek-chat", "max_tokens": 100, "messages": [{"role": "user", "content": "Hi"}]}'

5. 版本要求

确保 Claude Code CLI 版本 >= 2.0.0：

claude --version

6. 项目配置说明

本项目所有 Python 文件已优化为支持第三方 API：

• ✅ 使用 load_dotenv(override=True) 确保 .env 配置优先
• ✅ 模型从环境变量读取，支持 MODEL 环境变量
• ✅ 兼容官方和第三方 API 格式

🎉 第一个 Agent 示例

# 20行代码创建一个自动修Bug的AI
from claude_agent_sdk import query, ClaudeAgentOptions

async def fix_bug():
    async for message in query(
        prompt="找到并修复auth.py中的bug",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Bash"]  # 允许读文件、改代码、运行命令
        )
    ):
        print(message)  # AI会自动读取文件、找到bug、修复它

📚 学习路径

入门阶段

1. 运行 7_wiki_writer.py 熟悉Agentic工作方式
2. 尝试不同的查询请求，观察AI如何调用Skill
3. 理解llm-wiki-skill的工作原理

进阶阶段

1. 启动 wiki_writer_api.py 服务
2. 使用Postman或curl测试API接口
3. 尝试集成到前端项目中

高级阶段

1. 自定义llm-wiki-skill的功能
2. 添加新的工具和能力
3. 构建复杂的多Agent工作流