面向开发者的 AI 编程助手，基于 Agent Loop 架构实现 LLM 多轮推理与工具调用的自动化执行，通过流式并行工具、上下文压缩和语义记忆检索机制，解决上下文溢出与跨会话知识丢失问题。
- Agent Loop 多轮推理：基于 ReAct 模式的自主推理-行动循环，LLM 自动规划、调用工具、处理结果并迭代
- 双后端支持：同时支持 Anthropic Claude 和 OpenAI 兼容 API，可切换不同模型
- 流式并行工具执行：流式接收 LLM 响应时，对并发安全的工具提前启动执行，减少等待延迟
- 4 层上下文压缩：预算截断 → 旧结果裁剪 → 微压缩 → LLM 摘要，确保长对话不超出上下文窗口
- 语义记忆检索：基于 LLM-as-Router 的记忆选择器，跨会话保留用户偏好和项目知识
- 5 级权限模式：default / plan / acceptEdits / bypassPermissions / dontAsk，灵活控制工具执行权限
- MCP 协议扩展：通过 JSON-RPC 2.0 over stdio 连接 MCP 服务器，动态扩展工具能力
- 子 Agent 系统：支持 explore / plan / general 三种子 Agent 类型，以及用户自定义 Agent
- 技能系统：基于 Markdown + YAML Frontmatter 的可插拔技能模板，支持 inline 和 fork 两种执行模式
- 计划模式：只读规划 → 用户审批 → 自动执行的工作流
Python 3.11+、asyncio、Anthropic/OpenAI Async SDK（Streaming）、MCP（JSON-RPC 2.0）、Rich CLI
- Python >= 3.11
- Anthropic API Key 或 OpenAI 兼容 API Key
# 1. 克隆仓库
git clone https://github.com/raaaaap/mini-claude-code.git
cd mini-claude-code
# 2. 创建虚拟环境（推荐）
python -m venv .venv
# Windows 激活
.venv\Scripts\Activate.ps1
# Linux/macOS 激活
# source .venv/bin/activate
# 3. 安装依赖
pip install -r requirements.txt
# 或使用可编辑安装（开发推荐）
pip install -e .# 复制环境变量模板
cp .env.example .env
# 编辑 .env 文件，填入你的 API Key
# ANTHROPIC_API_KEY=sk-ant-xxxxx或直接在终端中设置：
# Linux/macOS
export ANTHROPIC_API_KEY=sk-ant-xxxxx
# Windows PowerShell
$env:ANTHROPIC_API_KEY = "sk-ant-xxxxx"# 一次性模式
mini-claude-py "hello"
# 交互式 REPL
mini-claude-py
# 也可以用 python -m 方式运行
python -m mini_claude "hello"
# 跳过所有确认
mini-claude-py --yolo "list files"
# 计划模式（只读规划）
mini-claude-py --plan "how would you refactor this?"
# 使用 OpenAI 兼容后端
$env:OPENAI_API_KEY = "sk-xxx"
mini-claude-py --api-base https://api.openai.com/v1 --model gpt-4o "hello"$ mini-claude-py
Mini Claude Code — A minimal coding agent
Type your request, or 'exit' to quit.
Commands: /clear /plan /cost /compact /memory /skills
> 帮我读取 main.py 文件的内容
📖 read_file main.py
1 | def main():
2 | print("Hello, World!")
...
> 把 print 语句改成 logging
🔧 edit_file main.py
Successfully edited main.py
@@ -1,3 +1,3 @@
- print("Hello, World!")
+ import logging
+ logging.info("Hello, World!")
> /cost
Tokens: 1234 in / 567 out (~$0.0072)| 命令 | 说明 |
|---|---|
/clear |
清空对话历史 |
/plan |
切换计划模式（只读 ↔ 正常） |
/cost |
显示 Token 用量和费用 |
/compact |
手动压缩对话上下文 |
/memory |
查看已保存的记忆 |
/skills |
查看可用技能 |
/<技能名> |
调用指定技能 |
mini-claude [选项] [提示词]
选项：
--yolo, -y 跳过所有确认提示（bypassPermissions 模式）
--plan 计划模式：只读，描述变更但不执行
--accept-edits 自动批准文件编辑，仍需确认危险命令
--dont-ask 自动拒绝所有需要确认的操作（适用于 CI）
--thinking 启用扩展思维（仅 Anthropic）
--model, -m 指定模型（默认：claude-opus-4-6）
--api-base URL 使用 OpenAI 兼容 API 端点
--resume 恢复上次会话
--max-cost USD 费用上限
--max-turns N 最大 Agent 轮次
--help, -h 显示帮助
import asyncio
from mini_claude.agent import Agent
async def main():
agent = Agent(
model="claude-sonnet-4-6",
api_key="your-api-key",
permission_mode="bypassPermissions",
)
await agent.chat("读取 README.md 并总结")
usage = agent.get_token_usage()
print(f"Token 用量: {usage['input']} 输入 / {usage['output']} 输出")
asyncio.run(main())mini-claude-code/
├── mini_claude/ # 核心源码
│ ├── __init__.py # 包初始化，版本号
│ ├── __main__.py # CLI 入口与 REPL 交互循环
│ ├── agent.py # Agent 核心循环、双后端、4 层压缩
│ ├── tools.py # 10 个工具定义 + 5 种权限模式
│ ├── ui.py # 终端 UI 渲染（Rich）
│ ├── prompt.py # 系统提示词构造与模板插值
│ ├── session.py # 会话持久化（JSON 文件存储）
│ ├── memory.py # 4 类型文件记忆系统 + 语义检索
│ ├── skills.py # 技能系统（Frontmatter 解析 + 模板）
│ ├── subagent.py # 子 Agent（explore/plan/general）
│ ├── mcp_client.py # MCP 协议客户端（JSON-RPC 2.0）
│ └── frontmatter.py # YAML Frontmatter 解析器
├── tests/ # 测试目录
├── examples/ # 使用示例
├── pyproject.toml # 项目配置与构建信息
├── requirements.txt # Python 依赖列表
├── .env.example # 环境变量模板
├── .gitignore # Git 忽略规则
├── LICENSE # MIT 许可证
├── CONTRIBUTING.md # 贡献指南
└── README.md # 项目说明文档
实现 Agent Loop 的核心逻辑，包含：
- 双后端流式调用（Anthropic / OpenAI）
- 流式并行工具执行（content_block_stop 回调）
- 4 层上下文压缩管线
- 预算控制与费用追踪
- 计划模式的进入/退出/审批流程
- 子 Agent 和技能的 fork 执行
提供 10 个内置工具：read_file、write_file、edit_file、list_files、grep_search、run_shell、skill、web_fetch、enter_plan_mode、exit_plan_mode、agent
5 种权限模式：default（默认确认）、plan（只读）、acceptEdits（自动批准编辑）、bypassPermissions（跳过所有确认）、dontAsk（自动拒绝）
4 种记忆类型：user（用户偏好）、feedback（纠正反馈）、project（项目知识）、reference（外部资源）
语义检索流程：扫描记忆头 → 构建 manifest → LLM 选择相关记忆 → 注入用户消息
通过 JSON-RPC 2.0 over stdio 连接 MCP 服务器，支持：
- 自动发现和注册 MCP 工具
- 工具调用路由（
mcp__服务器名__工具名） - 多服务器并发管理
class Agent:
def __init__(
self,
*,
permission_mode: str = "default", # 权限模式
model: str = "claude-opus-4-6", # 模型名称
api_base: str | None = None, # OpenAI 兼容 API 地址
anthropic_base_url: str | None = None, # Anthropic API 地址
api_key: str | None = None, # API 密钥
thinking: bool = False, # 是否启用扩展思维
max_cost_usd: float | None = None, # 费用上限（美元）
max_turns: int | None = None, # 最大轮次
confirm_fn: Callable | None = None, # 自定义确认回调
custom_system_prompt: str | None = None, # 自定义系统提示词
custom_tools: list | None = None, # 自定义工具列表
is_sub_agent: bool = False, # 是否为子 Agent
)| 方法 | 说明 |
|---|---|
chat(user_message: str) |
主入口，发送用户消息并处理 Agent Loop |
run_once(prompt: str) -> dict |
子 Agent 入口，执行一次后返回结果 |
abort() |
中止当前执行 |
clear_history() |
清空对话历史 |
show_cost() |
显示 Token 用量和费用 |
compact() |
手动压缩对话上下文 |
toggle_plan_mode() -> str |
切换计划模式 |
get_token_usage() -> dict |
获取 Token 用量统计 |
restore_session(data: dict) |
恢复会话数据 |
set_confirm_fn(fn) |
设置自定义确认回调函数 |
set_plan_approval_fn(fn) |
设置计划审批回调函数 |
from mini_claude.tools import execute_tool, check_permission
# 执行工具
result = await execute_tool("read_file", {"file_path": "main.py"})
# 检查权限
perm = check_permission("run_shell", {"command": "rm -rf /"}, mode="default")
# 返回: {"action": "confirm", "message": "rm -rf /"}from mini_claude.memory import save_memory, list_memories, delete_memory
# 保存记忆
filename = save_memory("项目架构", "使用 FastAPI + SQLite", "project", "项目采用 FastAPI 框架...")
# 列出所有记忆
memories = list_memories()
# 删除记忆
delete_memory("project_项目架构.md")from mini_claude.mcp_client import McpManager
manager = McpManager()
await manager.load_and_connect() # 连接所有配置的 MCP 服务器
tools = manager.get_tool_definitions() # 获取所有 MCP 工具定义
result = await manager.call_tool("mcp__server__tool", {"arg": "value"})
await manager.disconnect_all() # 断开所有连接# 安装测试依赖
pip install pytest pytest-asyncio
# 运行所有测试
pytest tests/ -v
# 运行特定测试文件
pytest tests/test_frontmatter.py -v测试文件放在 tests/ 目录下，文件名以 test_ 开头。示例：
import pytest
from mini_claude.frontmatter import parse_frontmatter, format_frontmatter
def test_parse_frontmatter():
content = "---\nname: test\ntype: user\n---\nHello world"
result = parse_frontmatter(content)
assert result.meta["name"] == "test"
assert result.meta["type"] == "user"
assert result.body == "Hello world"
def test_parse_no_frontmatter():
content = "Just plain text"
result = parse_frontmatter(content)
assert result.meta == {}
assert result.body == "Just plain text"
def test_format_frontmatter():
result = format_frontmatter({"name": "test"}, "Hello")
assert result == "---\nname: test\n---\n\nHello"设置 OPENAI_API_KEY 和 OPENAI_BASE_URL 环境变量，或使用 --api-base 参数：
mini-claude-py --api-base https://api.openai.com/v1 --model gpt-4o "hello"在项目目录下创建 .claude/skills/<技能名>/SKILL.md：
---
name: commit
description: 生成 Git 提交信息
user-invocable: true
context: fork
---
根据当前 git diff 生成规范的提交信息...在 .claude/settings.json 或 .mcp.json 中添加：
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
}
}
}本项目灵感来源于 Claude Code，旨在以最简代码实现其核心架构，帮助开发者理解 AI Agent 的工作原理。