CoreCoder实战教程：一个while循环如何驱动AI自动读文件、改代码、跑测试

CoreCoder 是一个核心约 1,000 行的极简 AI 编码智能体（AI coding agent），受 Claude Code 启发、可用任意 LLM 驱动。本教程带你从安装到上手，看清一个 while 循环如何让 AI 自动读文件、改代码、跑测试，并理解背后的权限与计划模式等安全机制。

为什么一个 while 循环能驱动 AI 编码智能体

先打破一个迷思：编码智能体不是魔法，核心就是一个「问模型 → 执行工具 → 把结果喂回去 → 再问」的循环：

def chat(self, user_input): self.messages.append(user_input) for _ in range(self.max_rounds): # 有轮次上限，不会失控 reply = self.llm.chat(self.messages, self.tools) if not reply.tool_calls: # 模型不再要工具 return reply.text # 干完了，交回答案 results = run_parallel(reply.tool_calls) # 有工具请求 → 执行 self.messages += results # 结果喂回去，继续下一轮

就这么点东西。剩下的上千行代码，都是为「循环遇见真实世界」兜底：模型返回半个 JSON 怎么办、上下文塞满了怎么办、十个工具同时跑怎么办。完整主循环就在 agent.py 的chat()方法里，不到 60 行，一口气读完。

五分钟安装运行 CoreCoder：新手快速上手指南

CoreCoder 是纯 Python 项目，pip一键装好：

pip install corecoder

它默认走 OpenAI 兼容接口，换模型只需改两个环境变量（可写在项目根目录的.env里，见 config.py）：

然后两种方式任选：

corecoder # 交互式 REPL，持续对话 corecoder -p "给 parse_config() 加错误处理" # 一次性任务，干完自动退出

💡没有 API key 也能玩：项目内置了离线演示 demo.py，用脚本化的假 LLM 走一遍真实主循环，跑python -m corecoder.demo就能看到 AI 写fib.py、写测试、跑 pytest 的全过程。

AI 自动读文件、改代码、跑测试：完整过程拆解

下面这张图是一次真实任务的完整轨迹：一句话让 CoreCoder 修buggy.py里的 bug，它自己决定先读文件、再精确改一处、然后运行验证，最后口头汇报——全程无人干预：

对照循环，这四步各发生什么：

1. 读文件— 模型第一轮回复带一个read_file工具调用，循环执行后把文件内容作为「工具结果」塞回上下文；
2. 改代码— 第二轮模型看到内容，发出edit_file调用。CoreCoder 用的是「唯一性搜索替换」而非行号（见 edit.py）：改错位置不可恢复，改错锚点模型能自我纠错；
3. 跑测试— 第三轮模型自己发起bash调用python buggy.py，用运行结果验证修复；
4. 汇报— 模型不再请求任何工具，循环自然退出，文本回复交还给你。

八个内建工具都放在 corecoder/tools/ 目录，每个文件不到 200 行：

🔧 模型一次返回多个工具调用时，CoreCoder 会用线程池并行执行（见 agent.py 的_exec_tools_parallel），读三个文件不用排队，长任务明显提速。

权限模式与计划模式：AI 智能体的安全机制

让 AI 自动跑命令，你敢吗？CoreCoder 的答案写在 permissions.py：

• 只读工具即点即跑，写文件、改代码、跑命令则先停下来问你：允许一次 / 始终允许 / 拒绝。「始终允许」按工具记住，存在~/.corecoder/permissions.json，重启后依然生效；
• 一次性模式（-p）默认拒绝一切改动，因为没有人在场可以问——拒绝会作为普通工具结果喂回模型，让它自行绕行，加--yes才放行（适合脚本和 CI）；
• 计划模式（/plan）：开启后智能体只能调查不能动手，改文件的请求会被当场拒绝，它转而给出编号计划；你敲approve批准后，它才执行。

动画演示的正是计划模式的完整流程：读文件放行 → 改文件被拒 → 提交计划 → 批准后编辑、测试一气呵成，且每次工具调用前后都有 hooks 钩子在观察。想自己体验无需联网：跑一下 examples/plan_hooks_demo.py。

从读到改：扩展 CoreCoder 的三条路

读懂之后，最自然的下一步是 fork 一个自己的（git clone https://gitcode.com/gh_mirrors/co/CoreCoder，然后pip install -e .）：

• 换你常用的模型：就是上面两个环境变量，所有模型适配都集中在 llm.py；
• 加一个自己的工具：照着 tools/base.py（32 行）写个新类即可，比如「跑测试」「调 LSP」，系列文章第 02 篇手把手带你写第一个；
• 改系统提示词：prompt.py 只有 41 行，改一句话就能看智能体性格变化，是「改一行、看效果」最便宜的地方。

项目内还附了 8 篇双语源码导读（article/00-index.md），从主循环、工具系统、上下文压缩到扩展机制，每个设计决策都对应到具体代码行。

常见问题

Q：CoreCoder 能跑本地模型吗？能。Ollama 一行环境变量接入，全程免费；LiteLLM 后端（pip install "corecoder[litellm]"）还能接 100 多家提供商。

Q：一次任务花多少钱？REPL 里敲/tokens实时查看 token 用量和美元估算，价格表可用~/.corecoder/pricing.json覆盖，新模型不用等发版。

Q：和 Claude Code 有什么区别？规模差几百倍，但核心是同一个 while 循环。CoreCoder 的定位是「可运行的教学参考」：每个设计决策压缩到最短可读的代码，让你断点、修改、重跑，再回头理解生产级智能体为什么那么复杂。

总结

一个 AI 编码智能体 = 一个有界循环 + 一套工具 + 一圈兜底工程。CoreCoder 用约 1,000 行核心代码把这条链路完整跑通：读文件、改代码、跑测试、派子任务、压上下文、算成本，全部真实可用。把它 clone 下来跑一次，你会对「智能体如何工作」建立起别人讲半天都讲不清的体感——然后 fork 它，做点更自己的东西。