mini-cc：用最少的代码，复刻一个“真正能干活”的 AI 编程智能体（并且把架构讲明白）

如果你关注 AI 编程助手，或许已经体验或了解过不少产品：它们可以聊天、补全内容和生成代码。但继续深入追问时，问题便会出现：

• Agent 究竟如何循环？为何会在持续输出时中断并调用工具？
• Tool Use 如何完成定义与分发？怎样接入文件读写和 Bash 执行？
• 如何记忆长上下文？又怎样防止 Token 数量失控？
• 为什么终端中的 React UI 可以保持如此流畅？

多数项目不是工程化程度过高、难以入门，就是抽象层级太高，看完后依旧不敢动手编写自己的 Agent。

为填补这一学习断层，mini-cc被设计成采用极简架构的轻量级 AI 编程智能体。作为一个开源教学项目，它以“剖析、学习和复刻大厂 Agent 架构”为定位：尽量减少代码量，同时重现 Claude Code CLI 的关键机制与核心交互，并用文档梳理重点，让你能够“读得懂、改得动、复刻得出”。

项目地址：github.com/you-want/mi…（欢迎 Star）

通过它可以获得什么？

将现代 AI 编程 Agent 拆分为清晰可见的关键模块，才是mini-cc的价值所在；它并非仅仅增加了一个“能聊天的 CLI”：

1. 一套 Agent Loop 可以形成闭环：先由模型生成，接着发现 tool_calls并执行工具，再将结果写回 messages，然后进入下一轮生成。
2. AI 编程助手最核心的动作由 Bash / 读文件 / 写文件覆盖，它们共同组成一套工具系统（Tool Use），并且能够扩展。
3. 一套强调实用性的记忆及上下文压缩策略：.ai_memory + 通过压缩与截断，处理长任务“能够运行却无法持久运行”的问题。
4. 一个面向实际使用的终端 UI：虚拟滚动和流式输出打字机体验均通过 React（Ink）实现，无论日常使用还是演示，操作都会更顺手。
5. 多语言实现对照：同一套设计思想提供 TypeScript、Python、Go、Rust 多种版本，方便使用自己熟悉的语言完成复刻。

核心亮点汇总（它为何值得加入你的收藏夹）

1) 支持多模型：可接入 Claude、OpenAI及兼容 OpenAI 接口的模型

在 Claude、DeepSeek、Qwen、Kimi 等模型间进行切换，使mini-cc成为个人“模型试验台”；这种用法得益于它对 Anthropic API 及 OpenAI 兼容接口的支持。

2) 纯函数式 Agent 循环：清晰讲解并简洁实现事件循环

该项目着重以更清楚的方式呈现 Agent Loop，包括工具调用怎样触发、各环节如何串联，以及执行结果怎样回填上下文。此类“产品界面看不到，却对学习最关键”的机制，正是mini-cc关注的重点。

它还同时支持推理模型的 reasoning_content 展示，使你能够在终端观察“模型怎样思考及推动任务”，前提是所使用的模型提供该字段。

3) Tool Use：只需三件套便能让 Agent 开始工作

• BashTool：执行系统终端命令（npm / git / 脚本等）
• FileReadTool：将本地文件读取为上下文
• FileWriteTool：通过覆盖写入文件完成自动修改

构建 AI 编程助手时，性价比最高的起点就是这三种工具；它们组成了“读代码 → 跑命令 → 改代码”这一核心工作流。

4) Bash 沙盒：在执行前阻挡危险命令

项目不仅剥离了命令执行包装器，还会拦截高危破坏性命令，例如 rm -rf /），从而让学习与二次开发过程更加安心。

5) .ai_memory 记忆引擎：为长任务留出一条“活路”

mini-cc 通过本地文件系统记忆 + 上下文压缩/截断策略（例如 Prompt Too Long 时削减最老历史），降低“对话越长越容易崩”的概率。

6) MCP 插件生态：通过标准协议扩展工具

借助项目支持的 MCP（Model Context Protocol），能力可以延伸至更多外部工具/服务；同时，隔离执行能够减少耦合并降低风险。

快速开始（四种语言中任选一种）

TypeScript（推荐）

执行全局安装：

npm install -g @you-want/mini-ccmini-cc

源码构建（可选）：

git clone https://github.com/you-want/mini-cc.gitcd mini-cc/typescriptnpm installnpm run buildnpm start

Python

pip install you-want-mini-ccmini-cc

Go

go install github.com/you-want/mini-cc/go/cmd/mini-cc@latestmini-cc

Rust

cargo install --git https://github.com/you-want/mini-cc.git --bin miniccminicc

第一次运行：一分钟把 API Key 配好

首次启动时，如果没有检测到 API Key，mini-cc 会弹出交互式配置引导，并保存到全局目录（例如 ~/.mini-cc-env）。你只需要按提示输入：

• OPENAI_API_KEY
• 某个 Qwen / DeepSeek 模型对应的模型名称
• BASE_URL（当所用接口兼容 OpenAI 时）

完成配置之后，就可以直接输入指令并开始使用。

它如何做到“像工程师一样”工作？（简短交互示例）

启动工具后，你可以使用自然语言输入要求，如同与一位“可以读写文件、能够运行命令”的工程师进行协作，例如：

• “输出 Hello World的 hello.js 文件，请帮我创建。”
• “请列出当前目录包含哪些文件？”
• “项目名称是什么，请读取 package.json后回答。”

遇到复杂任务时，它会反复调用工具，按照读文件 → 跑测试 → 写代码修复的流程持续推进，直至完成。这正是 Agent 的独特之处，也是阅读源码时最值得掌握的部分。

用三个关键词快速理解架构

1) Agent Loop：工具调用如何与生成闭合循环

核心做法是将模型输出视为“能够被中断的流”：一旦检测到 tool_calls，工具会在生成暂停后开始执行，完成后生成过程再恢复。Agent 能否“持续推进”，取决于这一循环是否稳定。

2) Memory & Context：长效记忆、压缩与截断

Token 预算是工程实践中绕不开的问题，为此mini-cc设置了“防爆舱 + 两步法则（ + 压缩层”.ai_memory）”整套组合方案纳入其中，用户可以直接借鉴，也可以按实际需求加以改造。

3) MCP：以标准协议拓展工具边界

如果需要增加安全网络请求、系统操作或外部应用等能力，MCP是一条更容易维护的路线，工具扩展不必再依靠“在仓库中硬塞大量适配器”。

学习路径：由掌握使用进阶到自行编写

项目在 docs/ 目录中提供完整学习指南，内容涵盖架构、工具系统、记忆、安全、UI以及优化部署，适合按照以下方式学习：

1. 先完成运行：选择一个语言版本安装，确保能够正常对话并调用工具。
2. 理解主循环：追踪一次调用链，路径从 Query Engine/主入口展开。
3. 理解工具系统：从渲染回填和执行反向查看参数校验与工具定义。
4. 接着自行添加一个工具，例如 GitStatusTool / HttpFetchTool（同时配合相应的安全策略）。
5. 做一次“最小产品化”：先跑 CI，再加入发布脚本、配置和日志。

它适合哪些人？

• 开发者若要系统掌握记忆压缩 / Tool Use / Agent 架构
• 适合希望复刻一套“可以在终端中工作”的 AI 编程助手的人
• 希望将工具能力标准化，并研究 MCP 插件化的人
• 适合希望比较 TypeScript、Python、Go、Rust 实现差异的人

参与项目贡献

mini-cc采用 MIT 协议开源，用户能够自由学习、修改和分发，同时也欢迎通过以下方式参与：

• 提交 PR：修复 bug、完善文档或补充示例
• 让能力边界在安全有保障的情况下扩展：补全更多工具
• 增加更多语言或平台适配：进一步提升项目的易用性与可移植性

结语：将“黑盒式的 AI 产品”拆解为“白盒式的工程能力”

“使用工具、管理上下文、持续推进复杂任务”的能力，必然与“写代码”能力一起构成 AI 编程助手的未来，而且前者不再只是附属能力。

mini-cc是一个相当友好的起点，适合那些不愿只停留在“用过某个产品”层面，而希望把这些能力沉淀为可由自己掌控的工程资产的人。