🚀 手把手教你从零实现 Claude Code

dev派
0 阅读8分钟

🚀 手把手教你从零实现 Claude Code

导语：Claude Code 是 Anthropic 推出的命令行 AI 编程工具，能帮你自动读写文件、执行命令、管理项目。今天，我们用 200 行 Python 代码，手把手教你实现一个功能完整的克隆版！无需复杂框架，纯原生实现。

一、项目概览：这个 AI 助手能做什么？

这个名为 agent-claudecode.py 的项目，是一个基于大语言模型的自主编程 Agent。它能：

功能模块具体能力应用场景
文件操作读、写、编辑文件自动修改配置、生成代码模板
代码搜索Glob 文件匹配、Grep 文本搜索在项目中快速定位代码
命令执行运行 Shell 命令自动执行构建、测试、Git 操作
任务规划将复杂任务拆解为步骤多步骤的自动化工作流
记忆系统保存历史任务和结果保持上下文连续性
规则系统加载自定义规则文件团队编码规范约束
技能系统加载预定义技能(JSON)复用常见任务模板
MCP 扩展接入外部工具生态连接数据库、API 等外部服务

核心架构图：

用户指令 → LLM 决策 → 工具调用 → 执行反馈 → 记忆保存
                ↓
        [规则 + 技能 + MCP 扩展]

二、环境准备：5 分钟搭建开发环境

2.1 安装依赖

只需要两个 Python 库：

pip install openai python-dotenv
  • openai：调用大模型 API（支持 OpenAI 格式，兼容通义千问、DeepSeek 等）
  • python-dotenv（可选）：管理环境变量

2.2 配置 API 密钥

创建 .env 文件或在终端设置：

export OPENAI_API_KEY="your-api-key"
export OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"# 通义千问示例
export OPENAI_MODEL="qwen-plus"# 或其他模型如 gpt-4o、deepseek-chat

支持的主流模型：

  • 通义千问（阿里云）：qwen-plus, qwen-max
  • DeepSeek：deepseek-chat, deepseek-coder
  • OpenAI：gpt-4o, gpt-4-turbo
  • 其他兼容 OpenAI API 格式的服务

三、核心原理解析：Agent 是如何工作的？

3.1 基础工具集（Tools）

代码定义了 7 个基础工具，这是 Agent 的"手脚"：

base_tools = [
    {"type": "function", "function": {"name": "read", ...}},    # 读取文件
    {"type": "function", "function": {"name": "write", ...}},   # 写入文件
    {"type": "function", "function": {"name": "edit", ...}},    # 编辑文件（精确替换）
    {"type": "function", "function": {"name": "glob", ...}},    # 文件路径匹配
    {"type": "function", "function": {"name": "grep", ...}},    # 文本搜索
    {"type": "function", "function": {"name": "bash", ...}},    # 执行命令
    {"type": "function", "function": {"name": "plan", ...}}     # 任务规划
]

工具设计的精妙之处：

  • edit 工具要求 old_string 必须唯一出现，防止误替换
  • glob 按修改时间排序，优先展示最新文件
  • bash 和 grep 都有 30 秒超时，防止命令卡死

3.2 执行循环（ReAct 模式）

Agent 采用 ReAct（推理+行动）  架构：

def run_agent_step(messages, tools, max_iterations=5):
    for _ in range(max_iterations):
        # 1. LLM 决策：分析当前状态，决定调用哪个工具
        response = client.chat.completions.create(...)
        
        # 2. 执行工具：调用本地 Python 函数
        function_response = available_functions[function_name](**function_args)
        
        # 3. 反馈观察：将执行结果返回给 LLM
        messages.append({"role": "tool", "content": function_response})
        
        # 4. 循环直到 LLM 认为任务完成（不再调用工具）
        if not message.tool_calls:
            return message.content

为什么设置 max_iterations=5？

  • 防止无限循环和 token 消耗爆炸
  • 复杂任务应使用 plan 工具拆解，而非单次循环硬撑

四、四大进阶系统详解

4.1 记忆系统（Memory）

解决的问题：多轮对话中，Agent 忘记之前的操作。

实现机制：

  • 文件：agent_memory.md（Markdown 格式，便于人工查看）
  • 策略：保留最近 50 行历史（防止上下文过长）
  • 格式：时间戳 + 任务描述 + 执行结果
## 2026-03-16 14:30:25
**Task:** 创建 Flask 项目结构
**Result:** 已创建 app.py、requirements.txt、templates/ 目录

使用场景：

# 第二次运行时，Agent 会自动读取记忆
python agent-claudecode.py "继续完善昨天的 Flask 项目"

4.2 规则系统（Rules）

解决的问题：统一团队编码规范，让 AI 按规则办事。

使用方法：

  1. 创建目录：.agent/rules/
  2. 添加规则文件：.agent/rules/python-style.md
# Python 编码规范
- 使用 4 空格缩进，不使用 Tab
- 函数必须有类型注解
- 导入顺序：标准库 → 第三方库 → 本地模块
- 异常处理必须记录日志，不能裸 except

代码加载逻辑：

def load_rules():
    for rule_file in Path(RULES_DIR).glob("*.md"):
        # 将所有 .md 文件合并到 System Prompt

效果：LLM 在生成代码时，会自动遵循这些规范！

4.3 技能系统（Skills）

解决的问题：复用常见任务，避免重复描述。

技能定义格式（.agent/skills/web-scraper.json）：

{
  "name": "web_scraper",
  "description": "创建 Python 网页爬虫模板",
  "template": "使用 requests + BeautifulSoup，添加随机 User-Agent，包含异常重试机制"
}

使用方式：

python agent-claudecode.py "使用 web_scraper 技能创建一个爬取豆瓣电影的脚本"

Agent 会自动将技能描述注入上下文，让 LLM 按模板生成代码。

4.4 MCP 扩展系统（Model Context Protocol）

解决的问题：连接外部工具生态（数据库、浏览器、API 等）。

MCP 是什么？  由 Anthropic 推出的开放协议，标准化 AI 与外部工具的通信。

配置示例（.agent/mcp.json）：

{
  "mcpServers": {
    "sqlite": {
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "data.db"],
      "tools": [
        {
          "name": "query",
          "description": "执行 SQL 查询",
          "parameters": {"sql": {"type": "string"}}
        }
      ]
    },
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"],
      "disabled": false
    }
  }
}

工作原理：

def load_mcp_tools():
    # 读取 mcp.json，将每个 server 的 tools 转换为 OpenAI 函数格式
    # 最终合并到 all_tools 列表中

强大之处：无需修改代码，只需添加配置即可扩展能力！

五、任务规划模式：处理复杂工作流

5.1 为什么要规划？

当任务需要多步骤时（如"创建 Django 项目并配置 Docker"），一次性生成容易出错。

5.2 规划模式的工作流程

# 启用规划模式
python agent-claudecode.py --plan "创建一个完整的 Python 爬虫项目"

执行过程：

[Plan] Breaking down: 创建一个完整的 Python 爬虫项目
[Plan] Created 4 steps
  1. 创建项目目录结构和 requirements.txt
  2. 编写基础爬虫模块，包含请求和解析功能
  3. 添加数据存储功能（CSV/JSON）
  4. 创建配置文件和启动脚本

[Step 1/4] 创建项目目录结构和 requirements.txt
...（执行结果）

[Step 2/4] 编写基础爬虫模块...
...（执行结果）

代码实现关键点：

def plan(task):
    # 调用 LLM 生成 JSON 格式的步骤列表
    response = client.chat.completions.create(
        response_format={"type": "json_object"},  # 强制返回 JSON
        messages=[{"role": "system", "content": "Break task into 3-5 steps..."}]
    )
    steps = json.loads(response.choices[0].message.content)["steps"]
    
    # 递归执行每个步骤（注意：plan 工具会被移除，防止嵌套规划）
    for step in steps:
        result, messages = run_agent_step(messages, [t for t in tools if t["function"]["name"] != "plan"])

六、实战演示：5 个典型应用场景

场景 1：快速项目初始化

python agent-claudecode.py --plan "创建一个 FastAPI 项目，包含 JWT 认证、PostgreSQL 连接、Docker 配置"

Agent 自动执行：

  1. 创建 main.py 带 JWT 中间件
  2. 创建 models.py 配置 SQLAlchemy
  3. 创建 Dockerfile 和 docker-compose.yml
  4. 创建 .env.example 模板

场景 2：代码审查与重构

python agent-claudecode.py "读取 src/legacy.py，将其重构为类结构，并添加类型注解"

场景 3：批量文件处理

python agent-claudecode.py "找到所有 test_*.py 文件，在每个文件开头添加 # -*- coding: utf-8 -*-"

场景 4：数据分析任务

python agent-claudecode.py "读取 data.csv，统计各列缺失值比例，生成清洗脚本"

场景 5：结合 MCP 的高级场景

# 假设配置了 SQLite MCP
python agent-claudecode.py "查询数据库中最近 7 天的用户注册数，并生成可视化图表代码"

七、源码精读：关键设计细节

7.1 参数解析的健壮性

def parse_tool_arguments(raw_arguments: str) -> dict[str, Any]:
    try:
        parsed = json.loads(raw_arguments)
        return parsed if isinstance(parsed, dict) else {}
    except json.JSONDecodeError as error:
        # 即使 JSON 解析失败，也不让 Agent 崩溃
        return {"_argument_error": f"Invalid JSON arguments: {error}"}

7.2 编辑操作的安全性

def edit(path, old_string, new_string):
    content = f.read()
    if content.count(old_string) != 1:
        return f"Error: old_string must appear exactly once"# 严格校验
    # 只有唯一匹配时才替换，防止批量误改

7.3 全局状态管理

current_plan = []    # 当前执行的计划步骤
plan_mode = False# 是否处于规划模式（防止嵌套规划）

使用全局变量控制执行流，简单但有效（适合单线程 CLI 工具）。

八、扩展与定制：打造你的专属 Agent

8.1 添加自定义工具

在 base_tools 列表中添加定义，在 available_functions 中实现逻辑：

# 1. 定义工具 Schema
{"type": "function", "function": {"name": "fetch_url", "description": "获取网页内容", ...}}

# 2. 实现工具函数
def fetch_url(url):
    import requests
    return requests.get(url).text

# 3. 注册到可用函数
available_functions = {..., "fetch_url": fetch_url}

8.2 接入更多 MCP 服务

推荐 MCP 生态：

  • @modelcontextprotocol/server-filesystem：文件系统访问
  • @modelcontextprotocol/server-github：GitHub API 操作
  • @modelcontextprotocol/server-puppeteer：浏览器自动化
  • mcp-server-sqlite：SQLite 数据库

8.3 改进记忆系统

当前是简单文本文件，可升级为：

  • 向量数据库：使用 ChromaDB 语义检索历史记录
  • 结构化存储：改用 SQLite 或 JSONL 格式
  • 记忆压缩：让 LLM 定期总结历史，减少 token 消耗

九、总结与展望

这个项目展示了构建 AI Agent 的最小可行架构（MVP）：

组件复杂度价值
基础工具⭐⭐核心能力
记忆系统⭐⭐上下文连续性
规则/技能⭐⭐⭐可配置性
MCP 扩展⭐⭐⭐生态连接
任务规划⭐⭐⭐⭐复杂任务处理

下一步优化方向：

  1. 并行工具调用：支持一次执行多个独立工具
  2. 人机协作：关键操作前请求确认（--confirm 模式）
  3. IDE 集成：开发 VS Code 插件版本
  4. 多 Agent 协作：多个 Agent 分别负责代码、测试、文档

十、完整代码与使用

将文章开头的代码保存为 agent-claudecode.py，即可立即使用：

# 基础用法
python agent-claudecode.py "你的任务描述"

# 规划模式（复杂任务）
python agent-claudecode.py --plan "多步骤任务描述"

# 查看帮助
python agent-claudecode.py

项目结构建议：

your-project/
├── agent-claudecode.py    # 主程序
├── .agent/
│   ├── rules/             # 自定义规则
│   ├── skills/            # 技能定义
│   └── mcp.json           # MCP 配置
└── agent_memory.md        # 自动生成的记忆文件

关注公众号【dev派】，回复 "agent" 获取完整源码和配置文件模板！

avatar
文章
阅读
粉丝