mini-claude-code 0.2.0

A simplified AI Agent framework for learning Claude Code architecture

mini-claude-code

一个用于学习 AI Agent 架构的 Python 项目。
目标是用最小可读实现复刻「带工具调用的终端助手」核心流程。

界面预览

特性亮点

• 双 Provider：支持 Anthropic / OpenAI，统一走 LLMProvider 抽象层
• OpenAI 兼容平台接入：支持 OPENAI_BASE_URL（如 147api）
• Agentic Loop：流式输出 + 工具调用 + 多轮迭代
• 多工具系统：bash / read_file / write_file / glob
• 两套终端体验：simple（Rich REPL）与 tui（Textual 界面）
• Buddy 电子宠物：多角色设定（外表/特性/故事/数值），按 username+hostname 永久分配，不可切换
• 思考动画 + 工具反馈：thinking 时动态表情，工具调用成功/失败会影响心情与信任值
• 运行时配置管理：/show-config、/set-config，并自动持久化到 .env
• 工具可视化与手动调用：/tools、/tool <name> <json-args>
• TUI 交互增强：Tab 命令补全、配置键补全、↑↓ 输入历史
• 可读性导向：代码结构清晰，适合学习和二次改造

快速开始

1. 安装

方式 1（推荐，uv）：

uv venv
source .venv/bin/activate
uv pip install -e .

方式 2（pip）：

python -m venv .venv
source .venv/bin/activate
pip install -e .

2. 配置环境变量

cp .env.example .env

至少配置以下变量之一：

• ANTHROPIC_API_KEY（当 LLM_PROVIDER=anthropic）
• OPENAI_API_KEY（当 LLM_PROVIDER=openai）

常用配置：

LLM_PROVIDER=anthropic
ANTHROPIC_MODEL=claude-sonnet-4-5-20251022
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o
# OPENAI_BASE_URL=https://api.147ai.cn/v1
MAX_ITERATIONS=10
WORK_DIR=.
UI_MODE=simple

说明：

• UI_MODE=tui 时启动 Textual TUI
• 默认 UI_MODE=simple 为 Rich REPL
• 使用 147api 等聚合平台时：
  • LLM_PROVIDER=openai
  • OPENAI_API_KEY=<平台 key>
  • OPENAI_BASE_URL=<平台 OpenAI 兼容 base url>（通常带 /v1）

3. 运行

mini-claude

或：

python -m mini_claude.main

交互命令

• /exit：退出
• /clear：清空上下文历史
• /history：显示当前上下文估算 token 数
• /buddy：查看 buddy 当前状态与名册
• /profile：查看 buddy 完整介绍页（含属性数值可视化）
• /pet：抚摸 buddy，提升信任值
• /feed：投喂 buddy，恢复能量
• /show-config [KEY]：查看全部或单个运行时配置
• /set-config <KEY> <VALUE>：修改配置，并写回 .env
• /tools：查看已注册工具列表
• /tool <NAME> <JSON_ARGS>：手动调用工具（调试/教学很有用）

示例：

/show-config
/set-config MAX_ITERATIONS 20
/tools
/tool bash {"command":"ls -la"}

支持的运行时配置键：

• LLM_PROVIDER
• ANTHROPIC_API_KEY
• ANTHROPIC_MODEL
• OPENAI_API_KEY
• OPENAI_MODEL
• OPENAI_BASE_URL
• MAX_ITERATIONS
• WORK_DIR
• system_prompt

Agentic Loop 核心

QueryEngine.run() 关键流程：

1. 记录用户输入到上下文
2. 流式调用 LLM 并实时输出文本
3. 收集工具调用请求
4. 并发执行工具并写回结果
5. 在 max_iterations 内循环，直到模型结束当前回合

该结构支持一个回合内的「思考 -> 调工具 -> 再思考」迭代。

项目结构

src/mini_claude/
	main.py                  # 程序入口，组装 Provider / Tool / UI
	core/
		config.py              # 运行时配置管理（show/set-config + .env 持久化）
		context_manager.py     # 上下文与消息管理
		query_engine.py        # Agentic Loop 核心
		types.py               # 全局类型定义
	llm/
		provider.py            # LLM 抽象接口
		anthropic_provider.py  # Anthropic 实现
		openai_provider.py     # OpenAI/OpenAI-compatible 实现
	tools/
		base.py                # Tool 抽象基类
		registry.py            # 工具注册与调度
		bash.py                # Bash 执行
		read_file.py           # 文件读取
		write_file.py          # 文件写入
		glob_tool.py           # Glob 搜索
	ui/
		buddy.py               # Buddy 电子宠物系统
		simple_repl.py         # Rich 终端 REPL
		tui/
			app.py               # Textual TUI

开发

安装开发依赖：

pip install -e .[dev]

类型检查：

mypy src

测试：

pytest

许可证

本项目使用 MIT License，详见 LICENSE 文件。