mini-cc

一个极简架构的轻量级 AI 编程智能体，剖析、学习和复刻大厂 Agent 架构的开源教学项目。

由于部分商标保护和合规原因，本项目已更名为 mini-cc。它旨在用最简单的代码复刻原版 Claude Code CLI 的核心交互、工具调用机制（Tool Use）、沙盒执行与记忆压缩策略。它支持多模型提供商（Anthropic、OpenAI 以及所有兼容 OpenAI 接口的模型如 Qwen、DeepSeek 等），提供读取文件、写入文件和执行 Bash 终端命令的能力。

通过本项目，你可以学习到 Agent 的核心事件循环、工具定义与分发、多模型的适配，以及如何构建一个炫酷的终端 React UI。

🌟 核心特性

本项目目前已在 TypeScript 版本中实现了以下核心特性：

• 多模型支持：支持 Anthropic API 和 OpenAI 兼容接口，可自由切换 Claude、DeepSeek、Qwen、Kimi 等多种大模型。
• 纯函数式 Agent 循环：清晰展示大模型如何自主调用工具、思考（CoT）和反馈。支持如 Qwen 等模型的推理思考过程（reasoning_content）实时展示。
• Tool Use (工具调用)：
  • BashTool：执行系统终端命令（支持 npm、git、文件操作等）。
  • FileReadTool：读取本地文件，提供上下文。
  • FileWriteTool：覆盖写入本地文件，实现代码自动修改。
• 安全的 Bash 沙盒：实现了命令执行包装器的剥离与高危破坏性命令（如 rm -rf /）拦截。
• .ai_memory 记忆引擎：实现两步法则的上下文记录和过长 Token 截断机制，防止 Token 爆炸。
• MCP 插件集成：支持模型上下文协议，实现工具的无缝扩充（例如安全执行网络请求与系统操作）。
• 炫酷的终端 UI：基于 React (Ink) 构建，拥有虚拟滚动和流畅的流式打字机输出效果。
• 趣味彩蛋：内置 /buddy 伴侣系统（基于 Mulberry32 与反作弊算法）和 /voice 模拟语音对讲。

🛠️ 架构图解

Agent 循环与工具调用 (Tool Use)

系统通过 AgentTool (Agent 分身术) 和基于 stdio 的进程隔离通信，把复杂的命令执行下发给不同子工具。主控节点持续将结果追加进 messages，一旦遇到 tool_calls 即打断当前生成，进入异步工具调用，结果产生后再唤醒生成，形成自动循环。

.ai_memory 记忆与上下文压缩

为了防止 Token 爆炸，程序维护了一套本地的文件系统记忆：

1. 压缩层 (compact.ts)：自动剥离图片和超长文档。
2. 防爆舱 (truncateHeadForPTLRetry)：如果 API 报出 Prompt Too Long，强制削减最老的历史。
3. 两步法则：在工作区生成 .ai_memory，记录核心的约定与项目架构级长效记忆。

MCP (Model Context Protocol) 插件架构

大模型调用工具的请求，会通过 MCPTool.ts 进行透明代理，转发至远程或本地的 MCP 插件服务，实现跨进程和跨应用的安全隔离执行。

📚 文档指南

为了帮助开发者更深入地理解本项目的架构设计与核心实现，我们提供了详细的文档。你可以在 docs 目录下找到这些内容：

• 00. 项目大纲
• 01. 核心架构
• 02. 查询引擎 (Query Engine)
• 03. 工具系统 (Tool System)
• 04. 记忆与上下文 (Memory & Context)
• 05. MCP与插件系统 (MCP & Plugins)
• 06. UI 与 Ink (UI & Ink)
• 07. 优化与部署 (Optimization & Deployment)
• 08. 电子宠物彩蛋 (Buddy Easter Egg)
• 09. 安全与沙盒 (Security & Sandbox)
• 10. 终极 Agent 能力

📁 语言实现版本

本项目采用多语言架构，计划使用多种编程语言实现相同的功能。目前已包含：

• TypeScript 实现 (✅ 已完成) —— 📖 查看 TS 版文档
• Python 实现 (✅ 已完成) —— 📖 查看 Python 版文档
• Go 实现 (✅ 已完成) —— 📖 查看 Go 版文档
• Rust 实现 (✅ 已完成) —— 📖 查看 Rust 版文档

🚀 快速开始

TypeScript 版本

方法一：全局安装 (推荐)

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

方法二：源码构建 & Bun 二进制打包

如果你希望自己修改代码，或者将其打包为一个无需 Node 环境即可运行的单一二进制文件：

git clone https://github.com/you-want/mini-cc.git
cd mini-cc/typescript
npm install
npm run build

# 运行
npm start
# 或者构建独立二进制可执行文件（需安装 Bun）
bun build --compile src/main.ts --outfile mini-cc

Python 版本

方法一：全局安装 (推荐)

pip install you-want-mini-cc
mini-cc

方法二：源码构建

git clone https://github.com/you-want/mini-cc.git
cd mini-cc/python
python -m venv venv
source venv/bin/activate
pip install -e .

# 运行
mini-cc

Go 版本

方法一：全局安装 (推荐)

只要你的电脑上安装了 Go 环境 (>=1.21)，就可以通过一行命令从 GitHub 源码直接拉取并编译成全局二进制命令：

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

方法二：源码构建

git clone https://github.com/you-want/mini-cc.git
cd mini-cc/go
go mod tidy
go build -o mini-cc cmd/mini-cc/main.go

# 运行
./mini-cc

Rust 版本

方法一：全局一键安装 (推荐)

只要你的电脑上安装了 Rust 环境 (1.70+)，可以通过 Cargo 直接全局安装二进制：

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

方法二：源码构建

git clone https://github.com/you-want/mini-cc.git
cd mini-cc/rust
cargo build --release

# 运行
./target/release/minicc

配置 API Key

初次运行 mini-cc (TS/Python/Go/Rust 任何一个版本)，如果未检测到 API Key，程序会自动弹出交互式配置引导，帮助你一键设置并保存在全局目录 ~/.mini-cc-env 中。

⚠️ 未检测到 API Key，进入初始化配置向导...
? 请输入您的 OPENAI_API_KEY: **********
? 请输入模型名称 (默认: qwen3.6-plus): qwen3.6-plus
? 如果您使用的是兼容接口，请输入 BASE_URL (可选): https://dashscope.aliyuncs.com/compatible-mode/v1
✓ 配置已成功保存至 ~/.mini-cc-env

💻 交互示例

启动程序后，你可以直接在终端中输入自然语言指令。例如：

• "帮我创建一个 hello.js 文件，内容是输出 Hello World。"
• "列出当前目录下有哪些文件？"
• "读取 package.json，并告诉我项目名称是什么。"

程序会思考并调用相应的工具自动执行你的需求，最终将结果反馈给你。

🎮 趣味指令

在聊天输入框内输入以下指令可触发彩蛋：

• /clear：清空当前会话上下文。
• /buddy：召唤基于系统种子生成的数字伴侣（小黄鸭/小章鱼），拥有隐藏稀有度属性。
• /voice：进入模拟语音对讲模式（按住空格说话）。

🛡️ 高级架构演示 (Mocks)

部分在官方版里极为底层的能力（如跨平台截屏、接管 Chrome 浏览器扩展抓取 AppData 数据、基于 CCR 云端集群推演）为了保证本项目轻量跨平台，在 src/architecture-mocks 中作为架构演练展示，暂不含实体功能（详见该目录声明）。

📄 开源协议

本项目基于 MIT 协议 开源，欢迎自由学习、修改和分发。