# v1: 模型即代理

**~200 行代码，4 个工具，所有编程 Agent 的本质。**

Claude Code 的秘密？**没有秘密。**

剥去 CLI 外观、进度条、权限系统，剩下的出奇简单：一个让模型持续调用工具直到任务完成的循环。

## 核心洞察

传统助手：
```
用户 -> 模型 -> 文本回复
```

Agent 系统：
```
用户 -> 模型 -> [工具 -> 结果]* -> 回复
                     ^_________|
```

星号很重要。模型**反复**调用工具，直到它决定任务完成。这将聊天机器人转变为自主代理。

**核心洞察**：模型是决策者，代码只提供工具并运行循环。

## 四个核心工具

Claude Code 有约 20 个工具，但 4 个覆盖 90% 的场景：

| 工具 | 用途 | 示例 |
|------|------|------|
| `bash` | 运行命令 | `npm install`, `git status` |
| `read_file` | 读取内容 | 查看 `src/index.ts` |
| `write_file` | 创建/覆盖 | 创建 `README.md` |
| `edit_file` | 精确修改 | 替换一个函数 |

有了这 4 个工具，模型可以：
- 探索代码库（`bash: find, grep, ls`）
- 理解代码（`read_file`）
- 做出修改（`write_file`, `edit_file`）
- 运行任何东西（`bash: python, npm, make`）

## Agent 循环

整个 Agent 在一个函数里：

```python
def agent_loop(messages):
    while True:
        # 1. 询问模型
        response = client.messages.create(
            model=MODEL, system=SYSTEM,
            messages=messages, tools=TOOLS
        )

        # 2. 打印文本输出
        for block in response.content:
            if hasattr(block, "text"):
                print(block.text)

        # 3. 如果没有工具调用，完成
        if response.stop_reason != "tool_use":
            return messages

        # 4. 执行工具，继续循环
        results = []
        for tc in response.tool_calls:
            output = execute_tool(tc.name, tc.input)
            results.append({"type": "tool_result", "tool_use_id": tc.id, "content": output})

        messages.append({"role": "assistant", "content": response.content})
        messages.append({"role": "user", "content": results})
```

**为什么这能工作：**
1. 模型控制循环（持续调用工具直到 `stop_reason != "tool_use"`）
2. 结果成为上下文（作为 "user" 消息反馈）
3. 记忆自动累积（messages 列表保存历史）

## 系统提示词

唯一需要的"配置"：

```python
SYSTEM = f"""You are a coding agent at {WORKDIR}.

Loop: think briefly -> use tools -> report results.

Rules:
- Prefer tools over prose. Act, don't just explain.
- Never invent file paths. Use ls/find first if unsure.
- Make minimal changes. Don't over-engineer.
- After finishing, summarize what changed."""
```

没有复杂逻辑，只有清晰的指令。

## 为什么这个设计有效

**1. 简单**
没有状态机，没有规划模块，没有框架。

**2. 模型负责思考**
模型决定用哪些工具、什么顺序、何时停止。

**3. 透明**
每个工具调用可见，每个结果在对话中。

**4. 可扩展**
添加工具 = 一个函数 + 一个 JSON schema。

## 缺少什么

| 特性 | 为什么省略 | 添加于 |
|------|-----------|--------|
| 待办追踪 | 非必需 | v2 |
| 子代理 | 复杂度 | v3 |
| 权限 | 学习目的信任模型 | 生产版 |

关键点：**核心是微小的**，其他都是精化。

## 更大的图景

Claude Code、Cursor Agent、Codex CLI、Devin——都共享这个模式：

```python
while not done:
    response = model(conversation, tools)
    results = execute(response.tool_calls)
    conversation.append(results)
```

差异在于工具、显示、安全性。但本质始终是：**给模型工具，让它工作**。

---

**模型即代理。这就是全部秘密。**

[← 返回 README](../README_zh.md) | [下一篇: v2 →](./v2-结构化规划.md)