CoreCoder
一个可读、可改、可运行的极简 Python 编码智能体核心。
这个 Agent 能做什么，适合哪些场景？
CoreCoder 是一个约 1,081 行纯 Python 的命令行编码智能体，用于理解并改造编码智能体的基本实现。它以 Agent 主循环驱动模型调用：模型请求工具后，系统并行执行工具并将结果写回上下文，直至模型返回文本答复或达到轮数限制。项目提供交互式 REPL、单次提示模式、会话保存与恢复、上下文压缩、令牌与成本统计，以及可作为 Python 库导入的 Agent、LLM 和 Config。它能读写本地文件并执行 shell 命令，因此适合在本机受控代码仓库中运行，而不是作为隔离的生产执行环境。
通过 corecoder 启动 REPL，或使用 corecoder -p "..." 执行一次任务。Agent.chat() 将用户输入加入消息历史，调用 LLM.chat() 获取文本或工具调用；工具调用可并行运行，并将结果追加到上下文后继续下一轮。内置 bash、read_file、write_file、edit_file、glob、grep 和 agent 七种工具：可搜索文件名和内容、读取与写入文件、用唯一文本匹配进行替换并返回 diff、执行 shell 命令，以及启动不能继续生成子智能体的子智能体。context.py 按三档处理上下文压力，session.py 保存或恢复会话，/tokens 显示令牌用量与成本估算。
- 希望逐行学习编码智能体实现的 Python 开发者，可从 `agent.py` 的主循环开始阅读并设置断点修改。
- 需要让模型在本地小型项目中查找 TODO、修改函数并运行命令验证结果的开发者，可使用单次提示模式。
- 想在现有轻量编码智能体上增加测试、LSP 或网页访问工具的工程师，可基于 `tools/base.py` 新增工具。
- 使用 DeepSeek、Ollama 或其他 OpenAI 兼容服务的个人开发者，可通过环境变量切换模型端点。
- 希望把任务式代码操作嵌入自己的 Python 程序的开发者，可直接导入 `Agent` 和 `LLM`。
这个 Agent 有哪些优点和局限？
- 核心引擎约 1,081 行纯 Python，主循环、模型接口、上下文、工具和会话实现均可直接阅读和修改。
- 内置文件读写、内容搜索、文件匹配、唯一匹配编辑、shell 执行和子智能体，能完成完整的本地代码操作循环。
- 支持 OpenAI 兼容 API，并记录令牌用量和成本；可通过可选 LiteLLM 后端连接更多提供商。
- 上下文压缩分为工具输出裁剪、历史摘要和紧急压缩三档，而非一次性简单截断。
- bash 的危险命令防护是正则黑名单，文档明确说明它不是安全沙箱；面对不可信输入需要额外的 seccomp 或容器隔离。
- 重试机制只有指数退避，没有模型回退链或硬性费用上限。
- 子智能体采用同步执行，输出超过 5,000 个字符会截断，且子智能体不能继续创建子智能体。
- 项目明确不包含 MCP 或 RAG；大型仓库的检索式代码定位需要自行扩展。
如何安装或部署这个 Agent？
需要 Python 3.10+ 和可用模型凭据。克隆后执行：git clone https://github.com/he-yufeng/CoreCodercd CoreCoderpip install -e .
也可执行 pip install corecoder。默认 OpenAI 配置需要 OPENAI_API_KEY=sk-...；DeepSeek 示例为 OPENAI_API_KEY=sk-... OPENAI_BASE_URL=https://api.deepseek.com CORECODER_MODEL=deepseek-chat；本地 Ollama 示例为 OPENAI_API_KEY=ollama OPENAI_BASE_URL=http://localhost:11434/v1 CORECODER_MODEL=qwen2.5-coder。项目根目录的 .env 会在启动时加载。
如何使用这个 Agent？
交互使用：corecoder。一次性执行并退出：corecoder -p "add error handling to parse_config()"。REPL 中可用 /model <name> 切换模型、/compact 手动压缩上下文、/tokens 查看用量、/diff 查看本次会话改动，以及 /save 和 /sessions 管理会话。作为库使用时，可创建 LLM(model="deepseek-chat", api_key="sk-...", base_url="https://api.deepseek.com")，再调用 Agent(llm=llm).chat("find every TODO comment in this project and list them")。
这个 Agent 与同类方案有什么区别？
CoreCoder 将自己定位为可阅读和可 fork 的最小编码智能体核心，而非 Claude Code 或 aider 的生产级替代品。与 Claude Code 相比，其代码可在本机完整阅读和修改；与 aider 相比，它的实现规模更小；它借鉴 nanoGPT 的教学式极简定位，但目标是让智能体编辑代码而非训练 GPT。