起因
Claude Code 这一年多在工程师群体里口碑炸裂，核心不在模型，在 Agent 内核: 工具调用、权限管控、错误自愈、子任务隔离、子 Agent 协作 —— 把这些做扎实，模型才能干活。
我顺着把这套体系拆解了一遍，把核心理念重写成了一个 任意厂商可换、任意工具可注册、任意业务可嵌入 的 Python 框架:mega_agent。
它做什么
python
from mega_agent import agent_loop, TOOL_HANDLERS
# 注册你自己的业务工具
TOOL_HANDLERS["query_user"] = lambda inp: my_db.fetch(inp["user_id"])
# 一行跑起来
msgs = agent_loop("查一下用户 u123 最近的活动并总结")
就这么多。背后内核会替你处理：LLM 调用 / 工具派发 / 权限分级 / 错误兜底 / 重试预算 / 子 Agent 并发 / 任务图调度 / 收件箱合流 …… 一直循环到 LLM 输出 end_turn。
7 个值得借鉴的设计
-
Errors are observations —— 工具异常不让 loop 崩，而是封装成
is_error=true的结果让 LLM 在下一轮自己应对。这是 Agent 鲁棒性的基石。 -
外部信号汇聚单通道 —— 后台子进程结果、子 Agent 回信、重试告警 …… 全部以
<tag>...</tag>块注入下一轮用户消息。只有一个输入面,LLM 处理逻辑因此异常简单。 -
三态权限闸 ——
allow / ask / deny, 按工具名前缀 (read/list/get/...vsdelete/remove/drop/...) 和 bash 命令形态 (rm -rf/dd if=/mkfs/shutdown) 自动分级。生产场景必不可少。 -
重试预算自动禁用 —— 连续失败 N 次的工具被禁用，下一轮通过
<retry-budget>标签告诉 LLM 换路。避免无限循环踩同一个坑。 -
Git Worktree 隔离子任务 —— 每个子 Agent 在真实的
git worktree add出来的独立分支上工作，多人改文件零冲突，worktree_closeout收尾时一键删分支或保留。 -
多 Agent 协作 + JSONL 收件箱 —— 主 Agent 用
spawn起子线程跑 teammate, 角色化的 6 种消息类型 (chat /result/shutdown /plan_approval ...),autonomous=true的子 Agent 还会自己从任务图里 claim 匹配自己 role 的任务。 -
加密 Profile + 语义路由 —— 多 key 用 Fernet + PBKDF2-HMAC-SHA256 (20 万轮) 加密落盘；
@code派给 Claude、@write派给 GPT-4o、默认走自建网关 —— 路由表也是持久化的。
工程化亮点
-
13 个小模块, 一下午读完 (
kernel / llm / permissions / hooks / retry / tasks / worktree / background / teams / mcp / profiles / tools / cli) - 29 个内置工具(文件 IO / Shell / 任务图 / Worktree / 后台 + Cron / 多 Agent / MCP)
- 3 种 LLM 后端:Anthropic 原生 / OpenAI 兼容网关 (LiteLLM / OpenRouter /vLLM/ 自建均可)/ Mock 测试桩
-
MCP 一行接入:
mcp.register("github", ["mcp-server-github"]) - 5 个可运行示例: 从最小嵌入到 hooks 审计 / 多路由 / 单测一应俱全
- 热路径仅依赖标准库,SDK 与加密库都是软导入，装哪个用哪个
你能拿它干什么
- 想 学 Agent 工程化设计 —— 直接读源码，13 个模块的边界划分都是现成的
- 想 快速搭一个内部 Agent 服务 ——
from mega_agent import agent_loop, 套上自己业务工具就能上线 - 想 基于它魔改 —— LLM 后端 / 存储 / 权限 UI / 系统提示词都有清晰的扩展点
仓库
🔗 github.com/wangxfholly/agent_basicMIT License · Python 3.10+ · v0.2.0
设计可借鉴，代码可直接用，欢迎 Star / Issue / PR。
