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

🚀 手把手教你从零实现 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" 获取完整源码和配置文件模板！