小冰 (Xiao Bing) 🧊👶

基于 MiniMax Mini-Agent 的增强版 AI 助手
_{Built on MiniMax's open-source Mini-Agent framework}

---

🙏 致谢开源社区: 本项目基于 MiniMax-AI/Mini-Agent 开源框架进行二次开发。感谢 MiniMax 团队和所有开源贡献者，正是你们的开放精神让更多人能够自由地构建和定制 AI 助手。

---

📖 什么是小冰？

小冰（Xiao Bing） 是一个在 MiniMax Mini-Agent 开源框架基础上进行深度定制的增强版 AI 助手。她是冰儿（Ice Agent）的"小弟"，由 MiniMax M2 系列大模型驱动。

小冰不是简单的 Mini-Agent 副本——她拥有一系列独特的增强能力，使其成为一个更强大、更智能、更可靠的 AI 助手。

✨ 核心增强能力

1. 🧠 语义向量记忆 (Vector Memory)

mcp_servers/vector_memory_server.py

传统 Agent 只能靠 Session Notes 记住信息。小冰内置了基于 sentence-transformers (all-MiniLM-L6-v2) 的向量记忆系统：

• 语义搜索：不只是关键词匹配，而是按语义含义查找记忆
• 自动索引：所有记忆自动建立语义索引，秒级检索
• 分类存储：按类别组织记忆（用户偏好、项目信息、技能等）
• 持续学习：每次交互都能积累新记忆

# 记住一个事实
remember(content="用户喜欢1080P以上的视频", category="user_preference")

# 用自然语言搜索记忆
recall(query="用户喜欢什么画质的视频", top_k=5)

2. 🌐 Web 搜索集成 (MCP Web Search)

mcp_servers/web_search_server.py

通过 MCP (Model Context Protocol) 集成了实时 Web 搜索能力：

• 联网搜索：获取最新信息，不受训练数据时间限制
• 网页抓取：提取任意 URL 的可读内容
• API 兼容：支持 Tavily Search API（可替换为其他搜索引擎）

3. 🎭 多角色系统 (Multi-Personality)

config/system_prompt_*.md

小冰支持即插即用的多角色系统，每个角色有独立的人格设定：

• 小冰 (默认)：冰儿的小弟，高效执行者
• Feynman：物理学家思维者
• Jobs：产品经理思维者
• Musk：愿景驱动思考者

切换角色只需修改配置中的 system_prompt_path：

system_prompt_path: "system_prompt_feynman.md"  # 切换为物理学家模式

4. 🐛 中文编码修复 (UTF-8 Patch)

patches/utf8_encoding_fix.patch

修复了 Mini-Agent 原版在 Windows 环境下的中文乱码问题：

• 文件读写强制 UTF-8 编码
• Note Tool 中文内容完美显示
• Recall Memory 中文搜索正常工作

5. 📊 Token 限制扩展 (Token Limit Support)

patches/token_limit_support.patch

原版 Mini-Agent 未提供 token 限制配置。小冰增加了：

• YAML 配置中的 token_limit 字段
• Agent 构造时自动应用限制
• 防止上下文溢出和 API 调用失败

6. 🔄 智能重试机制 (Smart Retry)

retry:
  enabled: true
  max_retries: 5          # 最多重试 5 次
  initial_delay: 1.0      # 初始等待 1 秒
  max_delay: 60.0         # 最大等待 60 秒
  exponential_base: 2.0   # 指数退避: 1s → 2s → 4s → 8s → ...

7. 🛠️ MCP 双服务器架构

小冰运行两个独立的 MCP 服务器：

• Web Search Server：提供 web_search 和 web_fetch 工具
• Vector Memory Server：提供 remember、recall、rebuild_memory_index 工具

两者均通过标准 MCP 协议通信，可独立重启或替换。

📦 安装

前置要求

• Python 3.10+
• uv (Python 包管理器)
• Git

快速开始

# 1. 克隆小冰
git clone https://github.com/guanlan2/xiaobing.git
cd xiaobing

# 2. 安装 Mini-Agent（上游项目）
git clone https://github.com/MiniMax-AI/Mini-Agent.git
cd Mini-Agent
uv tool install -e .
cd ..

# 3. 安装 MCP 服务器依赖
pip install sentence-transformers tavily-python mcp numpy

# 4. 配置 API Key
# 编辑 config/config.yaml，填入你的 API Key
# 编辑 mcp_servers/web_search_server.py，填入你的 Tavily API Key

# 5. 启动小冰
mini-agent --workspace ./workspace

⚙️ 配置

config.yaml

# API 配置
api_key: "YOUR_API_KEY_HERE"       # ← 替换为你的 API Key
api_base: "https://api.minimaxi.com"
model: "MiniMax-M2.5"
provider: "anthropic"

# 重试配置
retry:
  enabled: true
  max_retries: 3
  initial_delay: 1.0
  max_delay: 60.0
  exponential_base: 2.0

# Agent 配置
max_steps: 100
token_limit: 200000               # ← 小冰新增：Token 限制
workspace_dir: "./workspace"
system_prompt_path: "system_prompt.md"

# 工具配置
tools:
  enable_file_tools: true
  enable_bash: true
  enable_note: true
  enable_skills: true
  skills_dir: "./skills"
  enable_mcp: true                # ← 小冰新增：MCP 支持
  mcp_config_path: "mcp.json"
  mcp:
    connect_timeout: 60.0
    execute_timeout: 120.0
    sse_read_timeout: 180.0

mcp.json

{
  "servers": [
    {
      "name": "web-search",
      "command": "python",
      "args": ["mcp_servers/web_search_server.py"]
    },
    {
      "name": "vector-memory",
      "command": "python",
      "args": ["mcp_servers/vector_memory_server.py"]
    }
  ]
}

🏗️ 架构对比

特性	Mini-Agent 原版	小冰 增强版
文件操作	✅	✅
Bash 执行	✅	✅
Session Notes	✅	✅
技能系统	✅	✅
语义向量记忆	❌	✅ NEW
Web 实时搜索	❌	✅ NEW
多角色系统	❌	✅ NEW
中文编码修复	❌ (GBK问题)	✅ FIXED
Token 限制	❌	✅ NEW
MCP 双服务器	❌	✅ NEW
智能重试	基础	✅ ENHANCED

📁 项目结构

xiaobing/
├── README.md                          # 本文件
├── config/
│   ├── config.yaml                    # 主配置模板
│   ├── config_feynman.yaml            # 物理学家模式配置
│   ├── config_jobs.yaml               # 产品经理模式配置
│   ├── config_musk.yaml               # 愿景者模式配置
│   ├── mcp.json                       # MCP 服务器配置
│   ├── system_prompt.md               # 默认人格：小冰
│   ├── system_prompt_feynman.md       # 物理学家人格
│   ├── system_prompt_jobs.md          # 产品经理人格
│   └── system_prompt_musk.md          # 愿景者人格
├── mcp_servers/
│   ├── web_search_server.py           # Web 搜索 MCP 服务器
│   └── vector_memory_server.py        # 向量记忆 MCP 服务器
├── patches/
│   ├── utf8_encoding_fix.patch        # UTF-8 编码修复
│   └── token_limit_support.patch      # Token 限制支持
├── docs/
│   ├── ARCHITECTURE.md                # 架构详解
│   └── PATCHES.md                     # 补丁说明
└── bootstrap.bat                      # Windows 一键启动脚本

🔧 补丁说明

小冰对上游 Mini-Agent 进行了以下改动，详见 patches/ 目录：

1. UTF-8 编码修复 (patches/utf8_encoding_fix.patch)

   • 修复位置: note_tool.py (read_text, write_text, RecallNoteTool)
   • 问题: Windows 默认 GBK 编码导致中文乱码
   • 解决: 显式指定 UTF-8

2. Token 限制支持 (patches/token_limit_support.patch)

   • 修复位置: config.py, cli.py, agent.py
   • 问题: 缺少 token 限制导致上下文溢出
   • 解决: 添加 token_limit 配置项并生效

⚠️ 注意事项

• API Key 安全：发布版本已移除所有真实 API Key。使用前请自行配置。
• 向量模型：首次启动会自动下载 all-MiniLM-L6-v2 (22MB)
• MCP 超时：首次启动可能因模型加载而超时，重启即可

📄 许可证

本项目继承上游 MiniMax-AI/Mini-Agent 的 MIT 许可证。

🙏 致谢

• MiniMax — 开源 Mini-Agent 框架
• sentence-transformers — 向量嵌入
• Tavily — Web 搜索 API
• MCP 协议社区 — 标准化工具通信
• 冰儿 🧊 — 创造小冰的姐姐

---

_{小冰是冰儿的小弟。干活的，不是聊天的。完成任务，干净利落。🧊👶}