一个轻量级、可扩展的 AI Agent 框架
作者: 徐啸寅
QuantManus 是一个基于大语言模型（LLM）的智能 Agent 框架，专注于任务规划与执行、持久化记忆和技能扩展。
通过规划-执行-反思闭环和可插拔的技能系统，QuantManus 能够自动分解复杂任务、调用工具完成操作，并在跨会话间保持上下文连续性。
- 智能任务规划 — 自动分解复杂任务为可执行步骤，简单问题直接回答（无需规划）
- 持久化记忆系统 — 两层持久化架构（MEMORY.md + HISTORY.md），会话跨轮次保持连续性
- 技能扩展系统 — 通过
~/.quantmanus/skills/目录加载技能，支持依赖检查与按需注入 - 动态反思机制 — 基于工具执行结果精确触发反思，仅在实际报错时调整计划
- 工具调用系统 — 支持 OpenAI Function Calling 协议，内置文件读写、目录列出、Python 执行等工具
- Bootstrap 自定义 — 通过工作空间下的
bootstrap/目录自定义 Agent 身份与行为
QuantManus 通过**技能（Skills）**扩展 Agent 的能力。技能是独立的 Markdown 文件，为 Agent 提供特定领域的专业知识和行为指导。
官方技能仓库：Awsome-QuantManus-SKILLS
技能安装到全局目录 ~/.quantmanus/skills/ 下，目录结构如下：
~/.quantmanus/skills/
├── skill-name-a/
│ └── SKILL.md
├── skill-name-b/
│ └── SKILL.md
└── ...
每个 SKILL.md 文件使用 YAML frontmatter 声明元信息：
---
description: "技能描述"
requires: '{"bins": ["pytest"], "env": ["API_KEY"]}'
always: false
---
# 技能正文内容...| 字段 | 说明 |
|---|---|
description |
技能描述，用于 System Prompt 中的技能摘要 |
requires |
依赖声明（可执行文件 bins 和环境变量 env），不满足时技能不可用 |
always |
设为 true 时技能全文始终注入 System Prompt，否则由 LLM 按需读取 |
更多技能和编写指南请参阅 Awsome-QuantManus-SKILLS。
cd quantmanus
pip install -e .安装完成后，可以在任意目录下直接运行 quantmanus 命令。
quantmanus首次运行会自动进入配置引导：
首次运行，需要配置 API 信息。
请输入 API Key: sk-xxxxxxxx
请输入 Base URL (回车使用默认):
请输入模型名称 (回车使用默认):
配置已保存！
配置保存在 ~/.quantmanus/config.json，之后运行不会再询问。
QuantManus 以当前目录作为工作空间。不同目录下的会话数据和记忆互相独立：
cd ~/my-project
quantmanus # 工作空间 = ~/my-project
cd ~/another-project
quantmanus # 工作空间 = ~/another-project，独立的会话# 交互式对话模式
quantmanus
# 单次任务模式
quantmanus "创建一个hello.txt文件"交互模式下可用命令：
| 命令 | 说明 |
|---|---|
exit / quit |
保存会话并退出 |
clear |
清空对话历史（归档到长期记忆） |
new |
开始新会话 |
sessions |
查看所有保存的会话 |
memory |
查看长期记忆内容 |
stats |
查看记忆统计 |
debug |
切换调试模式 |
┌──────────────────────────────────────────────────────┐
│ 用户输入 │
└──────────────┬───────────────────────────────────────┘
↓
┌──────────────────────────────────────────────────────┐
│ SimpleAgent │
│ ┌────────────┐ ┌────────────┐ ┌────────────────┐ │
│ │ Planner │→ │PlanExecutor│→ │ _think_and_act │ │
│ │ 智能路由: │ │ 步骤执行 │ │ LLM循环 │ │
│ │ 直接回答 / │ │ 边界约束 │ │ 工具调用 │ │
│ │ 制定计划 │ │ 反思机制 │ │ │ │
│ └────────────┘ └────────────┘ └────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 记忆与上下文 │ │
│ │ Session (会话历史) ←→ ContextBuilder (上下文) │ │
│ │ MemoryStore (MEMORY.md + HISTORY.md) │ │
│ │ SkillsLoader (技能摘要 + 按需注入) │ │
│ └─────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────┘
↓
┌──────────────────────────────────────────────────────┐
│ 工具层 │
│ ReadFile │ WriteFile │ ListDir │ Python │ ... │
└──────────────────────────────────────────────────────┘
采用两层持久化架构：
| 层级 | 文件 | 作用 |
|---|---|---|
| 会话历史 | sessions/*.jsonl |
完整对话记录，JSONL 格式，支持增量写入 |
| 长期记忆 | memory/MEMORY.md |
LLM 整合的关键事实摘要，覆盖式更新 |
| 时间线日志 | memory/HISTORY.md |
grep 可搜索的历史日志，追加式写入 |
工作原理：
Session在内存中管理对话消息，任务结束时持久化到磁盘ContextBuilder每次 LLM 调用前动态构建消息列表（System Prompt + 长期记忆 + 技能 + 会话历史）- 当未整合消息数超过阈值时，
MemoryStore通过 LLM 将旧消息整合到 MEMORY.md 和 HISTORY.md
在工作空间的 bootstrap/ 目录下放置 Markdown 文件，可自定义 Agent 的身份和行为：
| 文件 | 用途 |
|---|---|
IDENTITY.md |
Agent 身份定义 |
SOUL.md |
Agent 性格与行为风格 |
USER.md |
用户偏好信息 |
AGENTS.md |
多 Agent 协作配置 |
TOOLS.md |
工具使用说明 |
quantmanus/
├── core/ # 核心模块
│ ├── agent.py # Agent 核心类（任务路由、执行循环、会话管理）
│ ├── llm_client.py # LLM 客户端（实时计时）
│ ├── planner.py # 规划器（智能路由：直接回答 / 制定计划）
│ ├── plan_executor.py # 计划执行器（步骤边界约束、精确反思触发）
│ ├── session.py # 会话持久化（JSONL 格式）
│ ├── memory_store.py # 持久化记忆（MEMORY.md + HISTORY.md）
│ ├── context_builder.py # 上下文构建（System Prompt + Bootstrap + 技能）
│ ├── skills_loader.py # 技能加载器（扫描、依赖检查、摘要构建）
│ ├── memory_manager.py # 旧版内存记忆管理
│ ├── message.py # 消息类
│ └── logger.py # 日志工具
├── tools/ # 工具模块
│ ├── base_tool.py # 工具基类 & ToolResult
│ ├── file_tool.py # 文件操作（读取、写入、删除、目录列出）
│ ├── python_tool.py # Python 代码执行
│ └── system_tool.py # 系统工具
├── config/ # 配置模块
│ └── config.py # 全局配置管理（~/.quantmanus/）
├── examples/ # 示例代码
├── main.py # 主入口 & CLI 命令入口
├── pyproject.toml # 打包配置（pip install -e .）
├── requirements.txt # 依赖列表
└── README.md
运行时目录：
| 位置 | 内容 |
|---|---|
~/.quantmanus/config.json |
全局配置（API Key、模型等） |
~/.quantmanus/skills/ |
全局技能目录 |
当前目录/sessions/ |
当前工作空间的会话数据 |
当前目录/memory/MEMORY.md |
长期事实记忆 |
当前目录/memory/HISTORY.md |
时间线日志 |
当前目录/bootstrap/ |
自定义 Bootstrap 文件 |
from core import SimpleAgent, LLMClient
from tools import ReadFileTool, WriteFileTool, ListDirectoryTool, PythonExecuteTool
# 1. 创建 LLM 客户端
llm_client = LLMClient(
model="gpt-4o",
api_key="your-api-key",
base_url="https://api.openai.com/v1"
)
# 2. 创建工具列表
tools = [
ReadFileTool(),
WriteFileTool(),
ListDirectoryTool(),
PythonExecuteTool(),
]
# 3. 创建 Agent
agent = SimpleAgent(
name="QuantManus",
llm_client=llm_client,
tools=tools,
system_prompt="你是一个智能助手",
enable_planning=True,
use_persistence=True,
)
# 4. 运行任务
result = agent.run("帮我执行 data_analysis.py")
print(result)
result = agent.run("上一步的输出结果是什么？") # 能正确回忆
print(result)from tools import BaseTool, ToolResult
class MyCustomTool(BaseTool):
def __init__(self):
super().__init__(
name="my_tool",
description="这是一个自定义工具"
)
def get_parameters(self):
return {
"type": "object",
"properties": {
"param1": {
"type": "string",
"description": "参数1描述"
}
},
"required": ["param1"]
}
def execute(self, param1: str):
result = f"处理: {param1}"
return ToolResult(success=True, output=result)
# 使用
tools = [MyCustomTool(), ReadFileTool()]
agent = SimpleAgent(..., tools=tools)
本项目采用 MIT 许可证。
徐啸寅
Made with ❤️ by 徐啸寅