实战三：Mini-Coder (简易版 Cursor)

这一节不打算做一个“看起来很全”的 Agent，而是故意做一个很小、但逻辑完整的版本。原因很简单：真正理解 Coding Agent，靠的不是背概念，而是亲手把最小闭环跑通。

一个最小可用的 Coding Agent，至少要做到三件事：

• 看懂目录和文件
• 读到实际代码
• 在改完之后留下可验证的结果

#1. 核心思路

Coding Agent 需要三个核心工具：

1. List Files: 看看目录里有什么。
2. Read File: 读取代码内容。
3. Write File: 修改代码。

这个版本先故意不做太多事情，比如不接浏览器、不接 Git、不做多轮规划。先把最小链路搭起来，后面再慢慢加能力。

#2. 定义工具 (Python 版)

python复制
import os

def list_files(directory="."):
    """列出指定目录下的文件"""
    return str(os.listdir(directory))

def read_file(file_path):
    """读取文件内容"""
    if not os.path.exists(file_path):
        return "Error: File not found"
    with open(file_path, "r") as f:
        return f.read()

def write_file(file_path, content):
    """(覆盖)写入文件内容"""
    with open(file_path, "w") as f:
        f.write(content)
    return f"Successfully wrote to {file_path}"

这里要有一个现实提醒：write_file 这种直接覆盖写入，在教学里够用，但在真实项目里其实很危险。生产环境更常见的做法会是：

• 先读取原文件
• 生成 diff 或 patch
• 通过 patch 应用修改
• 再执行验证步骤

因为一旦让 Agent 直接整文件覆盖，出错时很难回滚。

#3. 编写 Agent 提示词 (System Prompt)

Prompt 的作用，不是让它“像高级程序员一样说话”，而是限制它按一个靠谱的顺序做事。

python复制
SYSTEM_PROMPT = """
你是一个全栈开发工程师 Agent。你的任务是帮助用户修改代码。

你的工作流程：
1. 探索：先查看目录结构，定位相关文件。
2. 阅读：读取需要修改的文件内容。
3. 思考：分析代码逻辑，设计修改方案。
4. 执行：调用 write_file 工具应用修改。

约束：
- 修改前必须先读取文件，不要猜测内容。
- 每次只修改一个文件，修改后等待用户反馈。
"""

#4. 组装与运行

你可以用任意 Agent 框架来组装，重点不在库，而在执行顺序。下面用伪代码表示：

python复制
agent = Agent(
    model="claude-3-5-sonnet", # 推荐用 Sonnet，写代码能力最强
    tools=[list_files, read_file, write_file],
    system_prompt=SYSTEM_PROMPT
)

# 任务：给 hello.py 增加一个打招呼的函数
agent.run("请检查当前目录下的 hello.py，给它增加一个 greet(name) 函数")

#Agent 的执行轨迹 (Trace)

1. Thought: 我需要先看看 hello.py 是否存在。
2. Action: list_files(".")
3. Observation: ['hello.py', 'README.md']
4. Thought: 文件存在，我需要读取它的内容。
5. Action: read_file("hello.py")
6. Observation: print("Hello World")
7. Thought: 原代码很简单。我要添加 greet 函数。
8. Action: write_file("hello.py", "def greet(name):\n print(f'Hello {name}')\n\nprint('Hello World')")
9. Final Answer: 修改已完成。

#5. 进阶：把玩具工具换成真实工具层

手写 list_files、read_file、write_file 很适合入门，但一旦进入真实项目，很快就会不够用。

这时更合理的升级方向通常是接入更标准的工具层，比如文件系统 server、搜索能力、测试执行器，或者基于 MCP 的工具接入。

1. 安装 Server: npm install -g @modelcontextprotocol/server-filesystem
2. 连接 Agent: 配置 Agent 通过 Stdio 连接该 Server。
3. 优势: 安全性更高（可以限制目录访问权限），且支持更多高级操作（如搜索、Diff）。

一旦走到这一步，你的 Agent 就开始从“教学 demo”进入“能在真实仓库里做点事情”的阶段了。

#小结

一个最小可用的 Coding Agent，核心并不复杂：

1. 能先探索环境，再决定修改点。
2. 能读取真实文件，而不是凭空猜代码。
3. 能在修改后执行验证，而不是只输出“我已经改好了”。

如果你后面想继续增强它，优先级通常是：

1. 加 diff/patch，不要直接整文件覆盖。
2. 加测试和 linter，让它能自我验证。
3. 加更好的上下文选择，别每次把整个仓库塞进去。