minibotclaw 0.1.7

A minimal, framework-free AI agent toolkit for learning, local automation, and MCP-powered workflows.

MiniBot

一个用纯 Python 构建的可学习、可扩展、本地优先 AI Agent

先跑起来，再看懂它。 MiniBot 提供 REPL、WebUI、Python SDK、MCP、Skills、Hooks、Memory 和 Team 协作能力，适合想快速搭建本地 Agent，又希望源码透明、容易改造的开发者。

[ 你可以用它 ]   本地 REPL • WebUI • Python SDK • MCP/Skills • 多代理协作

中文 | English

---

从命令行到 WebUI，再到 SDK 集成，MiniBot 提供一条连续的本地 Agent 开发路径。

---

⚡ MiniBot 能帮你做什么？

• 用 minibot 启动一个可交互的本地 Agent REPL。
• 用 minibot-web 启动 WebUI 和 API 服务，快速验证多轮对话、会话、平台连接。
• 在 Python 里直接 from minibot import Minibot，把 Agent 嵌入自己的脚本或应用。
• 通过 MCP、Skills、Hooks、Memory 与 Team 工具扩展能力，而不是被大框架锁住。

🎯 为什么不是另一个 Agent Demo？

• 先有完整入口，再讲原理：终端、WebUI、SDK 都能直接跑，不是只给一段伪代码。
• 源码透明：不依赖 LangChain、AutoGen 或 LangGraph，方便学习和二次改造。
• 本地优先：工作目录、Skills、Memory、Hooks、MCP 配置都落在文件系统里，便于追踪和控制。

🚀 30 秒上手

uv tool install minibotclaw

# 首次启动后按提示完成模型配置
# 终端 REPL
minibot

# WebUI
minibot-web

• WebUI：在 Config 页添加 Provider、导入模型，并给 Bot 选择聊天模型。
• CLI：启动后使用 /model config 交互式配置全局 .env。
• 手动：直接编辑全局 .env，默认路径是 ~/.minibot/.env。

最少需要配置的字段：

OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_API_KEY=sk-xxxx
MODEL_ID=gpt-4o-mini

👀 适合谁 / 不适合谁

适合你，如果你想要：

• 学清楚 Agent、Tool Calling、MCP、Skills 这些机制到底怎么落地。
• 在本地快速试验一个可控、可改、可嵌入 Python 项目的 Agent。
• 用尽量少的抽象层，把 REPL、WebUI、SDK 和平台接入串起来。

不太适合你，如果你更想要：

• 开箱即用的生产级安全沙箱和严格权限模型。
• 一个已经高度产品化、面向非技术用户的 Agent 平台。
• 大而全的生态抽象，而不是偏底层、偏可读性的实现。

---

🧐 为什么开发 MiniBot？

在当今的 AI 开发中，我们被各种框架包裹（LangChain, AutoGen 等），导致很多开发者或感兴趣的朋友并不清楚 Agent 到底是如何工作的。

MiniBot 的目标是 "De-mystify Agents"（揭秘 Agent）。通过阅读本项目源码，你将理解：

1. ReAct 循环的本质：如何用原生 Python while 循环和 OpenAI API 构建思考-行动链。
2. 工具调用的底层逻辑：如何通过 Python inspect 模块将函数自动转换为 JSON Schema。
3. MCP (Model Context Protocol)：如何在不依赖官方 SDK 的情况下实现 Client 端协议握手。
4. Skills 上下文管理：如何动态地从文件系统加载 Prompts 和知识库。

---

⚡ 核心架构与实现

MiniBot 采用极其精简的模块化设计，没有任何复杂的类继承链。

1. 🔍 Agent Core (无框架 ReAct)

摒弃复杂的 Chain/Graph 抽象，回归本质。

• 实现：src/minibot/agent.py
• 逻辑：维护一个纯粹的 List[Message] 消息队列，通过递归或循环处理 LLM 的 tool_calls 响应。

2. 🛠️ Native Tool System (原生工具链)

不使用 Pydantic 生成 Schema，而是直接解析 Python 函数签名。

• 实现：src/minibot/tools/
• 特性：支持 Bash 执行、文件 IO，以及动态注册机制。支持 元工具 (Meta-Tools)，即“创造工具的工具”。

3. 🔗 MCP Integration (模型上下文协议)

完全兼容 Claude 的 MCP 协议，连接万物。

• 实现：src/minibot/mcp/
• 亮点：实现了基于 stdio 和 sse 的传输层，自动将 MCP 资源适配为 Agent 可调用的 Tools。

4. 🎣 Hooks & Lifecycle (生命周期钩子)

基于简单的观察者模式实现的安全与监控层。

• 实现：src/minibot/hooks/
• 用途：在 pre_tool_call 拦截高危命令，在 post_agent_loop 记录审计日志。

5. 📚 Skill Loader (动态技能)

• 实现：src/minibot/skills/
• 逻辑：类似于 Claude 的 Project，自动读取 Markdown 文件并注入 System Prompt。

---

🚀 快速上手

我们使用 uv 进行现代化的 Python 包管理（当然也支持 pip）。

安装

uv tool install minibotclaw

# 运行 REPL
minibot

# 启动 WebUI
minibot-web

升级：

uv tool upgrade minibotclaw

从源码安装（开发用）：

git clone https://github.com/zyren123/minibot.git
cd minibot

# 极速安装依赖
uv sync

# WebUI 静态资源不再提交到仓库，源码运行前需要先构建一次
cd webui
npm install
npm run build
cd ..

配置

首次启动时，MiniBot 会自动在全局 app home 下生成 .env，默认位置是 ~/.minibot/.env。

你可以通过 WebUI 的 Config 页面或 CLI 的 /model config 来完成配置；如果你更喜欢手动编辑，最少需要这些字段：

OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_API_KEY=sk-xxxx
MODEL_ID=gpt-4o-mini
# 可选：开启 Rich 终端美化，体验类似 Claude Code
MINIBOT_RICH=1

启动 REPL

# PyPI / uv tool 安装
minibot

# 源码安装（uv sync）
uv run minibot

常用命令：

• /help
• /info
• /stream [on|off|status]

启动 WebUI（本机）

# PyPI / uv tool 安装
minibot-web

# 源码安装（需先执行一次 webui/npm run build）
uv run minibot-web

然后打开：http://127.0.0.1:7860/

开发模式（前后端分离）：

# Terminal A
uv run minibot-web --reload

# Terminal B
cd webui
npm install
npm run dev

飞书平台接入（WebSocket）

1. 在飞书开放平台创建企业自建应用，并开启机器人能力。
2. 为应用订阅 im.message.receive_v1 事件，并授予发送消息所需权限。
3. 启动 minibot-web，打开 WebUI 的 Platforms 标签页。
4. 新建一个 Feishu 平台连接，填写 App ID、App Secret，并绑定到目标 Bot。
5. 如果删除了该 Bot，平台连接会自动改绑到默认 Minibot，并从新会话继续处理后续消息。

当前限制：

• 仅支持飞书私聊文本消息。
• 使用长连接 WebSocket 模式，不依赖公网 webhook。
• 回复以最终文本消息返回，不做流式 token 推送或消息卡片。

SDK 使用（Python）

非流式：

from minibot import Minibot

agent = Minibot(system_prompt="你是一个中文助手。")
result = agent.chat_sync("你好")
print(result.assistant_text)

流式（事件）：

import asyncio
from minibot import Minibot

async def main():
    agent = Minibot()
    async for ev in agent.stream("给我讲个笑话"):
        if ev.get("type") == "assistant_delta":
            print(ev.get("delta_text", ""), end="", flush=True)

asyncio.run(main())

注册自定义工具（直接传 Python function）：

from minibot import Minibot

def echo(text: str) -> str:
    return text

agent = Minibot(tools=[echo])

---

💻 源码导读 (Where to Learn)

这是一份学习指南，告诉你代码的每一部分展示了什么概念：

src/minibot/
├── agent.py             # [核心] 看这里理解 LLM 的“思考-执行”循环是如何手写的
├── core/
│   └── client.py        # 封装 OpenAI SDK，处理流式输出和多模态
├── tools/
│   ├── base.py          # [重点] 如何用 inspect 库将 Python 函数转为 JSON Schema
│   └── registry.py      # 简单的字典查找表，实现工具分发
├── mcp/
│   ├── client.py        # [进阶] 手写 MCP 协议客户端，理解 JSON-RPC 2.0
│   └── transport.py     # 进程间通信 (Stdio/SSE) 的实现
├── skills/
│   └── loader.py        # 如何解析文件系统并动态构建 Prompt 上下文
└── hooks/
    └── executor.py      # 中间件模式的实现，用于安全拦截

---

🎮 交互示例

MiniBot 提供了一个基于 prompt_toolkit 和 Rich 的现代化终端界面。 没错，readme就是用minibot写的

---

🔧 扩展开发

1. 编写一个纯 Python 工具

不需要继承复杂的类，只需定义函数和类型注解：

from minibot.tools.base import BaseTool

class WeatherTool(BaseTool):
    name = "get_weather"
    description = "获取城市天气"

    # 类型注解会自动转换为 Tool Schema
    async def execute(self, city: str, unit: str = "celsius") -> str:
        # 这里写原生 Python 逻辑
        return f"{city} 的天气是 25度 ({unit})"

2. 接入 MCP Server

在 config/mcp_servers.yaml 中配置，无需改代码即可扩展能力（例如连接 GitHub, Postgres 等）：

servers:
  - name: github-mcp
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: "your-token"

---

👥 Agent Teams (MVP)

MiniBot 现已支持 in-process Agent Teams（会话内团队编排）：

• Lead 可通过工具自主决定是否创建团队、创建多少成员（默认 3，最大 6）
• Teammate 拥有完整工作能力（读写文件、bash、MCP、memory 等），但不能再创建成员（禁用 Task/TeamCreate/TeamShutdown）
• 任意成员可点对点通信（TeamMessage）或全队广播（TeamBroadcast）
• 提供轻量共享任务板（TeamTask：create/list/assign/claim/complete）
• 提供 TeamWait 用于 Lead 等待并汇总队友事件

可用 Team 工具

• TeamCreate
• TeamMembers
• TeamTask
• TeamMessage
• TeamBroadcast
• TeamWait (lead only)
• TeamShutdown (lead only)

当前限制

• 仅支持 单会话内 团队，不支持跨重启恢复
• 不支持 tmux/iTerm2 分屏模式（MVP 仅 in-process）
• 不支持嵌套团队（teammate 不可再派生代理）

相关配置

config/default.yaml:

llm:
  stream_enabled: true

teams:
  quiet_teammates: true
  debug_teammate_output: false

开启后 teammate 不会向终端输出 Thinking/Running 状态行与常规内容，避免并发输出污染主终端。 主 Agent（solo/lead）默认开启流式正文输出；若网关不支持流式，会自动回退为非流式输出。

---

🗺️ Roadmap

• 长期记忆支持: 基于本地文件系统的持久化上下文记忆
• Agent Teams (MVP): 会话内并发团队、消息总线、任务板、锁冲突保护
• Vision: 原生支持多模态图像理解
• Sandboxing: 基于 Docker 的工具执行沙箱
• Web Interface: 基于 FastAPI 的轻量级 API

---

🤝 贡献与协议

本项目采用 MIT License。

欢迎提交 PR！如果你想学习 Agent 原理，最好的方式就是尝试修改 src/minibot/agent.py 中的主循环逻辑。

---

Made with ❤️ by Engineers, for Engineers.