MiniCC

极简教学版 AI 编程助手（TUI），参考 Claude Code 的交互形态，用更少的代码把核心机制讲清楚：工具调用、事件驱动 UI、子代理与 MCP。

v0.3.x 起对外只保证 TUI 行为 稳定，内部模块/API 允许 breaking change。

已实现能力（当前）

基础 Coding 能力

• 文件相关：读/写/精确替换编辑（read_file / write_file / edit_file）
• 代码检索：glob + 内容搜索（glob_files / grep_search）
• Shell：前台执行与后台任务（bash / bash_output / kill_shell）
• 任务列表：模型可写 todo，TUI 实时展示（todo_write）

子代理（SubAgent）

• task(wait=True)：默认等待子代理完成并返回结果，主 Agent 可以直接整合继续推理
• task(wait=False)：后台启动多个子任务
• wait_subagents()：等待所有后台子任务结束并汇总输出

MCP（Model Context Protocol）

• 启动阶段预加载 MCP servers 与 toolsets（不再运行中懒加载）
• toolsets 会注入主 Agent 与子代理（避免每次创建重复加载）
• 缺少可选依赖时默认降级为空；可用 MINICC_MCP_STRICT=1 强制启动失败（适合 CI/严格环境）

TUI 体验（Textual）

• 流式输出 + 自动滚动到末尾
• 工具调用行：直接消费 agent.run_stream_events() 的 ToolCall/ToolResult 事件（running/completed/failed）
• 多行输入：Ctrl+J 换行；Enter 发送
• @ 引用文件：输入 @ + 片段弹出候选，↑/↓ 选择，Enter/Tab 插入路径
• ask_user 面板：工具向用户发起选择题/多选题并阻塞等待

快速开始

安装

# uv
uv pip install minicc

# pip
pip install minicc

配置 API Key

export ANTHROPIC_API_KEY="sk-ant-xxx"
# 或
export OPENAI_API_KEY="sk-xxx"

启动

minicc
# 或
python -m minicc

也可以直接运行（无需手动安装）：

uvx minicc

配置

~/.minicc/config.json

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "api_key": null,
  "base_url": null,
  "prompt_cache": {
    "instructions": false,
    "messages": false,
    "tool_definitions": false
  }
}

MCP（可选）

配置文件位置优先级：

1. 工作目录下的 .minicc/mcp.json
2. 全局 ~/.minicc/mcp.json

启用 MCP 需要安装可选依赖：

pip install "minicc[mcp]"
# 或
uv pip install "minicc[mcp]"

严格模式（配置错误/缺依赖时直接失败）：

export MINICC_MCP_STRICT=1

系统提示词

~/.minicc/AGENTS.md：自定义系统提示词（建议写清“可选方案/等待子代理/何时 ask_user”）。

快捷键

快捷键	功能
Enter	发送消息
Ctrl+J	输入框换行
Ctrl+C	退出
Ctrl+L	清屏
Esc	取消/关闭候选

项目结构（v0.3.x）

minicc/
├── cli.py       # 入口（仅启动 TUI）
├── core/        # 运行时/模型/事件总线/MCP 预加载
├── tools/       # 工具实现（按职责拆分）
└── tui/         # Textual TUI（消费 stream events + event_bus）

开发

git clone https://github.com/TokenRollAI/minicc.git
cd minicc
uv sync
uv run minicc

Textual 开发模式：

uv run textual run --dev minicc.tui.app:MiniCCApp
textual console

运行测试：

.venv/bin/pytest -q

Roadmap（TODO）

• Slash Command：如 /help、/clear、/model、/tasks、/mcp 等
• 自定义 SubAgent：不同职责/不同系统提示词/不同工具集的 agent profile
• WebSearch / Fetch：联网检索与抓取（含缓存与引用）
• Skills：可复用技能包（如“重构”“修复测试”“写文档”等工作流）
• llmdoc：更完整的 Document-Driven Development（新增更多指南/参考/架构图）

文档（llmdoc）

• llmdoc/index.md：文档索引
• llmdoc/guides/usage.md：使用指南
• llmdoc/guides/testing.md：测试指南

License

MIT