# Coding-Agent

**Repository Path**: belikeyou/coding-agent

## Basic Information

- **Project Name**: Coding-Agent
- **Description**: 不用任何 Agent 框架，用 ~2000 行 Python 从零实现一个能读代码、改文件、跑命令的 Coding Agent —— 亲手造一遍，你才真正理解 Claude Code / OpenCode 的工作原理们。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-26
- **Last Updated**: 2026-07-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 从零写一个 Coding Agent（中文教程）

> 不用任何 Agent 框架，用 ~2000 行 Python 从零实现一个能读代码、改文件、跑命令的 Coding Agent —— 亲手造一遍，你才真正理解 Claude Code / OpenCode 们的工作原理。

## 为什么要做这个教程

2026 年，Coding Agent 已经成为开发者的日常工具，但大多数人对它的理解停留在"魔法"层面。事实上，一个可用的 Coding Agent 的核心只有**一个循环**：

```mermaid
flowchart LR
    A[用户输入] --> B[调用 LLM]
    B --> C{模型想用工具吗?}
    C -- 是 --> D[执行工具<br/>读文件 / 改代码 / 跑命令]
    D -- 结果喂回 --> B
    C -- 否 --> E[输出最终回答]
```

其余的一切——上下文管理、权限控制、子 Agent、MCP——都是围绕这个循环的工程化。本教程带你逐章把它们全部亲手实现一遍。

**本教程的原则：**

- **零框架**：不用 LangChain / LangGraph，直接调用模型 API，让你看到每一个字节
- **每章可运行**：每一章都是一个能独立运行的完整版本，不是代码片段
- **对标 2026 年的真实架构**：MCP、并行子 Agent、上下文压缩、权限沙箱——业界正在用的设计，而不是玩具
- **中文优先**：所有讲解、注释、术语对照都用中文写作

## 开始之前

第一次接触？先读 **[准备工作](getting-started.md)**：Python 环境、API key 获取、跑完全书大概花多少钱。遇到问题先查 **[FAQ](faq.md)**，术语不熟悉查 **[术语表](glossary.md)**。

## 目录

### 第一部分 · 核心循环（一个周末就能跑起来）

| 章节 | 主题 | 你将实现 |
|---|---|---|
| [01](01-minimal-agent/) | 最小 Agent | 一个 ~150 行、会用工具的对话循环 |
| [02](02-file-tools/) | 文件工具三件套 | read / write / edit，以及为什么 edit 要用字符串替换 |
| [03](03-bash-tool/) | 执行命令 | bash 工具、超时控制、安全边界 |
| [04](04-search-tools/) | 搜索与导航 | glob / grep，让 agent 学会"看懂"一个陌生代码库 |

### 第二部分 · 从玩具到可用

| 章节 | 主题 | 你将实现 |
|---|---|---|
| [05](05-system-prompt/) | 系统提示词工程 | agent 的行为规范：何时提问、何时行动、如何汇报 |
| [06](06-streaming/) | 流式输出 | 打字机效果、工具调用的实时展示 |
| [07](07-context/) | 上下文管理 | token 预算、历史裁剪、自动压缩（compaction） |
| [08](08-permissions/) | 权限与确认 | 危险操作的审批机制：为什么 `rm -rf` 必须先问你 |

### 第三部分 · 进阶架构

| 章节 | 主题 | 你将实现 |
|---|---|---|
| [09](09-subagents/) | 子 Agent | 任务分解、并行执行、结果汇总 |
| [10](10-mcp/) | MCP | 接入 Model Context Protocol，连上外部工具生态 |
| [11](11-memory/) | 记忆 | 跨会话的持久化：agent 如何"记住"你的项目 |
| [12](12-eval/) | 评测 | 如何科学地知道你的 agent 变强了 |

## 学完之后，你的 agent 长这样

```mermaid
flowchart TB
    subgraph 交互层
        U[终端交互 / 流式输出 06] --> P[审批层 08]
    end
    subgraph 内核
        P --> L[Agent 循环 01<br/>系统提示词 05 + 上下文压缩 07]
        L --> T[本地工具 02-04<br/>read / write / edit / bash / glob / grep]
        L --> S[子 Agent 09<br/>只读并行调查]
        L --> M[MCP 工具 10<br/>外部工具生态]
    end
    subgraph 持久层
        L <--> Mem[记忆文件 11<br/>.agent-memory/]
    end
    E[评测 harness 12] -.考核.-> L
```

## 快速开始

```bash
git clone https://github.com/unlikeyou-dev/code.git
cd code/01-minimal-agent
pip install -r requirements.txt
export ANTHROPIC_API_KEY=sk-ant-...   # 在 https://platform.claude.com 获取
python agent.py
```

然后试着对它说：

```
帮我看看当前目录下有哪些文件，然后总结一下 agent.py 是做什么的
```

看着它自己决定调用 `list_files`、再调用 `read_file`、最后给出总结——这就是 Agent 的全部秘密。

## 适合谁读

- 想搞懂 Claude Code / OpenCode / Cursor Agent 底层原理的开发者
- 想在自己产品里嵌入 agent 能力、但不想背上框架黑盒的工程师
- 有 Python 基础、调用过任意一家 LLM API 即可，不需要机器学习背景

## 学习建议

- **动手 > 阅读**：每章代码不到 300 行，强烈建议对照 README 自己敲一遍，而不是直接运行
- **做每章的实验**：多数章节末尾有对比实验（比如删掉某条提示词看行为变化），它们比正文更能建立直觉
- **顺序阅读第一部分，之后可跳读**：05-12 章相对独立，按兴趣选择即可，但都依赖第一部分的循环骨架

## 贡献

欢迎提 issue / PR：指出错误、补充章节实验、分享你的改造。参见 [贡献指南](CONTRIBUTING.md)。

## 相关项目

站在巨人的肩膀上，也推荐这些优秀的同类资源（更多见[延伸阅读](resources.md)）：

- [How to Build a Coding Agent](https://github.com/ghuntley/how-to-build-a-coding-agent)（英文 workshop）
- [hello-agents](https://github.com/datawhalechina/hello-agents)（Datawhale 的通用 Agent 教程）

本教程的差异点：专注 **Coding Agent** 这一垂直场景、每章一个可独立运行的完整版本、覆盖 2026 年的现代架构（MCP / 子 Agent / 上下文压缩 / 权限沙箱）。

## License

代码采用 [MIT](LICENSE) 协议；文字内容采用 [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/deed.zh) 协议。