一个用于学习 AI Agent 架构的极简项目。它从消息入口开始,经过 AgentCore 组装上下文,调用兼容 OpenAI 格式的模型接口,并在需要时执行工具,最后把结果发回给用户。
这个项目的目标不是做一个功能很重的助手,而是把 Agent 从 0 到 1 的关键模块拆清楚:消息渠道、模型调用、工具系统、短期记忆、长期记忆、插件扩展、运行轨迹。
- 清晰分层:Channel -> Bus -> AgentCore -> Provider + Tools
- Telegram 优先:日常使用通过 Telegram Bot 聊天
- CLI 保留:用于本地调试和后续扩展
- 人工审批流:敏感操作(shell 命令、文件写入、POST/PUT/DELE 8000 TE 请求)需用户确认才能执行,防止误操作
- 工具调用:文件读写、Web 抓取/搜索、HTTP 请求、Shell 命令、记忆读写
- 上下文预算管理:自动按 Token 预算分配系统提示、工具描述、会话历史的空间,超限自动截断旧消息
- 技能系统:
skills/目录下的 .md 文档即技能,agent 用load_skill/list_skills自学,用learn_skill从网络下载新技能 - 多步规划:复杂任务先
create_plan列步骤,逐步推进,中途可revise_plan补充 - 凭证管理:安全存储 API Key、Token,不污染长期记忆
- MCP 工具:通过标准 MCP 协议连接外部工具服务器,零代码扩展工具集
- 记忆体系:JSONL 会话历史 + Markdown 长期记忆
- 插件系统:在
plugins/下新增插件即可扩展工具 - Trace 调试:通过
/trace查看最近一次 Agent 执行轨迹 - Docker 部署:支持容器化运行和数据持久化
mini-agent/
|-- main.py # 入口
|-- config.py # 环境变量配置
|-- bus.py # 消息定义
|-- agent_core.py # Agent 核心循环
|-- plugin_loader.py # 插件加载器
|-- channels/
| |-- base.py # 渠道抽象
| |-- cli.py # CLI 渠道
| |-- telegram.py # Telegram Bot 渠道
|-- provider/
| |-- deepseek.py # 模型接口封装
|-- tools/
| |-- base.py # 工具基类(含人工确认标记)
| |-- registry.py # 工具注册表
| |-- confirm.py # 人工审批流(Human-in-the-Loop)
| |-- filesystem.py # 文件工具
| |-- http.py # HTTP 请求工具
| |-- web.py # Web 抓取/搜索工具
| |-- shell.py # Shell 工具
| |-- memory_tool.py # 长期记忆工具
| |-- skill.py # 技能文档读取 + learn_skill
| |-- credential_tool.py # 凭证管理工具
| |-- plan.py # 多步规划工具(Plan/Execute)
|-- skills/
| |-- joke-teller.md # 示例技能:讲笑话
|-- mcp_client/
| |-- manager.py # MCP 客户端管理器
| |-- servers.json # MCP Server 配置
|-- memory/
| |-- session.py # 短期会话历史
| |-- long_term.py # 长期记忆和角色身份
| |-- context_manager.py # 上下文预算管理(Token 分配/截断)
| |-- trace.py # Agent 执行轨迹
|-- plugins/
| |-- example/ # 示例插件
|-- security/
| |-- workspace.py # 工作目录路径沙箱
|-- Dockerfile
|-- docker-compose.yml
|-- requirements.txt
通过环境变量配置:
| 变量 | 必填 | 说明 |
|---|---|---|
DEEPSEEK_API_KEY |
是 | DeepSeek API 密钥 |
TELEGRAM_TOKEN |
Telegram 模式必填 | Telegram Bot Token |
DEEPSEEK_BASE_URL |
否 | API 地址,默认 https://api.datahome73.com/v1 |
DEEPSEEK_MODEL |
否 | 模型名,默认 deepseek-v4-flash |
WORKSPACE_DIR |
否 | 数据目录,默认 /app/data |
MAX_TOOL_ITERATIONS |
否 | 最大工具调用轮数,默认 10 |
SESSION_HISTORY_SIZE |
否 | 每次带入的最近消息数,默认 20 |
CONTEXT_MAX_TOKENS |
否 | 上下文总预算,默认 32768 |
CONTEXT_SYSTEM_MAX_TOKENS |
否 | 系统提示+记忆预算,默认 4096 |
CONTEXT_TOOLS_MAX_TOKENS |
否 | 工具描述预算,默认 4096 |
CONTEXT_HISTORY_MAX_TOKENS |
否 | 会话历史预算,默认 24576 |
CONTEXT_MIN_HISTORY |
否 | 最少保留的历史消息数,默认 2 |
CONTEXT_MAX_HISTORY |
否 | 最多保留的历史消息数,默认 100 |
CRON_ENABLED |
否 | 是否开启定时任务 |
CRON_INTERVAL |
否 | 定时任务间隔,例如 1d、2h、30m |
CRON_PROMPT |
否 | 定时任务发给 Agent 的提示词 |
CRON_CHAT_ID |
否 | 定时任务要投递到的 Telegram chat id |
export DEEPSEEK_API_KEY=sk-xxx
export TELEGRAM_TOKEN=xxx
python main.py telegramDocker Compose:
cp .env.example .env
# 编辑 .env,填入 DEEPSEEK_API_KEY 和 TELEGRAM_TOKEN
docker compose up -dCLI 主要用于本地调试:
export DEEPSEEK_API_KEY=sk-xxx
python main.py cli输入 /quit 退出。
Trace 用来观察 Agent 每一轮到底做了什么。它会记录:
- 用户输入
- LLM 每轮返回的是文本还是工具调用
- 工具名称和参数
- 工具返回结果摘要
- 最终回复
- 错误信息
在 Telegram 中发送:
/trace
Bot 会返回当前 Telegram 会话最近一次 Agent 执行轨迹。CLI 中也可以输入 /trace 查看最近一次本地会话轨迹。
Trace 文件会写入工作目录:
<WORKSPACE_DIR>/traces/<session_id>/last.json
<WORKSPACE_DIR>/traces/<session_id>/<timestamp>.json
last.json 始终指向这个会话最近一次运行,带时间戳的 JSON 用于长期排查和教学回放。
显示最近一次 Agent 处理的 Token 预算分配情况:
📊 上下文使用报告
总计: 4520 / 32768 token (13%)
├ 身份+记忆: 680
├ 工具描述: 2100
├ 会话历史: 1200 (6 条消息)
└ 当前输入: 540
在 Telegram 或 CLI 中输入 /stats 即可查看。如果上下文使用超过 90%,说明长对话中的旧消息可能会被自动截断。
ContextManager 负责在每次 Agent 处理消息时,按 Token 预算分配各部分的上下文空间。它是 Agent 稳定运行长对话的关键——没有它,旧会话消息会无限膨胀消耗 Token。
系统将上下文分为 4 个分区,各有独立预算:
| 分区 | 默认预算 | 内容 |
|---|---|---|
| 身份+记忆 | 4096 token | 角色身份设定 + 长期记忆 |
| 工具描述 | 4096 token | 所有工具的 description 和参数 schema |
| 会话历史 | 24576 token | 最近 N 轮对话历史 |
| 当前输入 | 自动 | 当前用户消息 |
总预算默认 32768 token(可通过 CONTEXT_MAX_TOKENS 调整)。超预算时从最旧的会话消息开始丢弃,确保最近的对话始终保留。
Telegram 或 CLI 中输入 /stats 查看当前分配情况。
| v Channel(telegram/cli) | v InboundMessage | v AgentCore |-- 加载短期会话历史 |-- 加载长期记忆和身份设定 |-- 组装 system/user messages |-- 调用 Provider |-- 如有 tool_calls,则执行工具并把结果放回上下文 |-- 循环直到模型输出最终回答 |-- 保存会话历史和 trace | v OutboundMessage | v Telegram / CLI 回复用户
## 人工审批流(Human-in-the-Loop)
某些操作有潜在安全风险,Agent 不能擅自执行——需要先停住、问用户、等批准。
### 敏感工具
| 工具 | 触发条件 |
|------|---------|
| `run_command` | 任何命令 |
| `write_file` | 任何文件写入 |
| `http_request` | POST / PUT / DELETE / PATCH |
### 工作流程
用户: "帮我删除 /tmp/test.txt"
↓
Agent 检测到 run_command 是敏感工具
↓
⏸️ 挂起操作 → 返回确认提示
↓
用户: "是"
↓
### 交互效果
当 Agent 调用敏感工具时,不直接执行,而是回复确认提示:
> ⚠️ **需要你确认这个操作:**
>
> 工具:`run_command`
> 参数:`cmd=rm /tmp/test.txt`
>
> 回复「**是**」确认执行,或「**否**」取消。
用户回复「是」后,Agent 执行该操作并继续完成后续逻辑。回复「否」则取消操作。
### 设计要点
- **会话级隔离**:不同聊天会话的挂起状态互不干扰
- **跳过循环**:用户确认后,自动放行下一轮 LLM 迭代中的敏感工具调用(仅一轮),避免连续确认循环
- **语义解析**:支持中英文确认/否定词(是/否/yes/no/确认执行/取消 等)
- **正常恢复**:确认操作后,消息上下文完整保留,LLM 自然延续之前的思路
- **双重路径**:非流式和流式(CLI / Telegram)都支持
### 扩展
如果需要自定义敏感规则,修改工具的 `requires_confirmation` 字段即可:
```python
# 整个工具标记为敏感
shell_tool = Tool(..., requires_confirmation=True)
# 按参数动态判断
http_request_tool = Tool(
...,
requires_confirmation=lambda args: args.get("method", "GET") in ("POST", "PUT", "DELETE"),
)
工具由 tools.base.Tool 定义,并注册到 ToolRegistry。每个工具都包含:
name:工具名description:给模型看的能力说明parameters:JSON Schema 参数定义fn:实际执行函数
AgentCore 会把工具转换成 OpenAI function calling 格式传给模型。
插件可以在不修改核心代码的情况下扩展 Agent 能力。每个插件是一个 plugins/<name>/ 目录,并导出 Plugin 类。
from tools.base import Tool
class Plugin:
name = "my_plugin"
description = "我的插件说明"
def on_load(self, context: dict):
pass
def get_tools(self) -> list[Tool]:
return [my_tool]启动时,PluginLoader 会自动扫描 plugins/,加载插件并注册工具。
技能系统让 Agent 能读取 skills/ 下的 .md 文档来学习新能力——不再需要修改代码。
list_skills() # → 列出所有可用技能
load_skill("name") # → 读取 skills/name.md 返回完整内容Agent 在启动时被告知"遇到不熟悉的任务,先用 list_skills 看看有没有对应技能,再用 load_skill 学习"。每个 skill 是纯 Markdown,带 YAML frontmatter:
---
name: joke-teller
description: "讲笑话 — 用户说'讲个笑话'时用"
---
# 讲笑话
当用户让你讲笑话时,从下面的列表中选一个回复。
1. 为什么程序员总是分不清万圣节和圣诞节?
因为 Oct 31 == Dec 25。
...Agent 可以用 learn_skill(url) 从任意 URL 下载 .md 技能文档到 skills/ 目录:
learn_skill("https://example.com/skills/meyo-registration.md", name="meyo-registration")
参数 name 可选,不传则自动从 URL 文件名或文档 frontmatter 推断。下载后立即可用 load_skill 加载。
敏感信息(API Key、Token、密码)不适合放在长期记忆里。凭证管理系统把它们存为 <WORKSPACE_DIR>/credentials.json,独立于记忆文件。
| 工具 | 功能 |
|---|---|
save_credential(name, value) |
保存一条凭证(同名覆盖) |
get_credential(name) |
读取凭证的值 |
list_credentials() |
列出所有凭证名称(不显示值) |
delete_credential(name) |
删除一条凭证 |
你提供 API Key → agent 调用 save_credential 存到文件
需要调用外部 API → agent 调用 get_credential 读取密钥 → 用 http_request 调用
对于需要多步骤的复杂任务(如调研分析、多步代码修改、报告撰写),Agent 通过规划工具让执行过程可追踪、可调整。
收到复杂请求
→ create_plan 列出步骤
→ 按顺序执行第 1 步 → complete_step #1
→ 执行第 2 步 → complete_step #2
→ (可选)revise_plan 发现遗漏,插入新步骤
→ 继续执行 → complete_step ...
→ 全部完成,总结回复用户
| 工具 | 功能 |
|---|---|
create_plan(goal, steps) |
创建多步计划,自动激活第一步 |
complete_step(step_id, summary) |
标记某步完成,自动激活下一步 |
revise_plan(after_step_id, new_steps) |
在指定步骤后插入新步骤 |
get_plan() |
查看当前计划的完整进度 |
- 简单任务跳过:单步工具调用不需要规划,只在 3+ 步且有依赖关系时使用
- 进度自动推进:
complete_step自动激活下一步,LLM 无需手动设置下一步 - 计划在上下文中:每一步的完成状态通过工具调用结果返回对话,LLM 自然可见
- Trace 可见:
/trace中显示计划进度摘要 - 中途可调整:
revise_plan让 LLM 能灵活应对执行途中的新发现
MCP(Model Context Protocol)是开放的 AI 工具协议。mini-agent 通过 mcp_client/ 连接外部 MCP Server,把它们的工具注册到 ToolRegistry 中——不改代码,加配置就行。
编辑 mcp_client/servers.json,添加想用的 MCP Server:
{
"servers": [
{
"name": "filesystem",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
},
{
"name": "github",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_TOKEN": "xxx" }
}
]
}启动时读取 servers.json
→ 每个 server 启动子进程(stdio)
→ MCP 协议握手,获取工具列表
→ 包装成 mcp_{server}_{tool} 格式
→ 注册到 ToolRegistry
→ Agent 直接用
配置一个 filesystem server 就获得 14 个文件操作工具(read_file、write_file、search_files 等),配 GitHub server 就获得仓库/PR/Issue 全套工具。已有 1000+ 社区 MCP Server 可用。
运行后,WORKSPACE_DIR 下会生成:
memory.md # 长期记忆
identity.md # 角色身份
sessions/*.jsonl # 会话历史
traces/*/last.json # 最近一次执行轨迹
credentials.json # 凭证存储(API Key、Token)
- 先读
bus.py,理解消息结构。 - 再读
agent_core.py,理解 Agent 的 LLM <-> Tool 循环(特别是审批流的挂起/恢复逻辑)。 - 然后读
tools/,理解工具如何暴露给模型(特别是tools/base.py的确认标记、tools/confirm.py的审批管理器、tools/skill.py的技能系统和tools/plan.py的规划系统)。 - 接着读
memory/,理解短期记忆、长期记忆、context_manager.py的 Token 预算管理、trace.py的执行轨迹。 - 最后读
channels/telegram.py,理解真实用户入口如何接入 Agent。