he-yufeng/CoreCoder

CoreCoder——一个微型、可读的编程智能体引擎

它是什么 — CoreCoder 是一个 2,800 行的纯 Python 实现的代码编辑 AI 智能体。它将“编程助手”的概念简化为基本要素：一个 while 循环，将用户的提示发送给 LLM，让模型调用一些工具（文件读写、shell、grep 等），将工具结果反馈到对话中，并重复此过程，直到模型返回最终答案。所有这些都编写得可以用一个下午读完，并且易于分叉。

它为什么重要 — 大多数商业智能体（如 Claude Code、Cursor 等）将其核心逻辑隐藏在数十万行闭源代码背后。CoreCoder 在单一、注释完善的代码库中展示了整个流水线——模型包装器、成本跟踪、三级上下文压缩、并行工具执行、子智能体生成、权限提示和 REPL。这使其成为任何想要了解真实世界编程智能体工作原理或构建自己定制版本的人的实际参考。

关键组件

• agent.py – 驱动对话的主循环（约 240 行）。
• llm.py – 流式 OpenAI 兼容客户端、重试逻辑和令牌成本核算。
• context.py – 三级上下文裁剪（机械截断、模型摘要、激进截断）。
• tools/ – 八个内置工具（bash、read_file、write_file、edit_file、glob、grep、todo_write、agent）以及可选的 MCP 扩展。
• cli.py – 带有斜杠命令（/model、/plan、/undo、/tokens 等）的交互式 REPL。
• hooks.py、permissions.py、checkpoints.py – 安全门禁、同意处理和撤销支持。

如何试用

# 克隆并以可编辑模式安装
git clone https://github.com/he-yufeng/CoreCoder
cd CoreCoder
pip install -e .

# 或者直接安装已发布的包
pip install corecoder

# 设置您的 LLM 凭据（OpenAI 示例）
export OPENAI_API_KEY=sk-...
# 可选：选择模型
export CORECODER_MODEL=gpt-5.5   # 默认

# 运行交互式 REPL
corecoder

# 一次性使用（为函数添加错误处理并退出）
corecoder -p "为 parse_config() 添加错误处理"

REPL 在任何修改性工具（write_file、edit_file、bash、子智能体）运行之前会请求同意，除非您使用 --yes 启动它。

扩展 / 分叉

1. 更换模型 – 只需更改 CORECODER_MODEL 环境变量或传递自定义 LLM 实例。
2. 添加工具 – 在 tools/ 中创建一个新文件，继承自 tools/base.py，实现 run()，并在 agent.py 中注册。
3. 编辑系统提示 – 修改 prompt.py（41 行）以更改智能体的个性或指令。
4. 作为库嵌入 –

   from corecoder import Agent, LLM
   llm = LLM(model="deepseek-chat", api_key="sk-…")
   print(Agent(llm=llm).chat("列出此仓库中的所有 TODO 注释"))
   

5. 探索文章 – 仓库包含一个八部分的双语“源码阅读系列”，逐行讲解每个子系统。

谁应该关注它

• 希望为构建或研究编程智能体提供具体、开源参考的研究人员或工程师。
• 有兴趣定制工具集、添加 RAG 或将引擎集成到更大的类似 IDE 产品中的开发者。
• 教授 LLM 驱动的智能体的教育工作者；极简的代码库非常适合课堂演示。

---

CoreCoder 是一个功能完整、经过测试（227 项测试）的 Python 包，它展示了编程助手如何端到端工作，同时保持足够小以便阅读、修改和扩展。