对照组：你到底需要多复杂的东西

前置：前面任意两篇。

读完前五篇容易产生一种错觉：做这件事就得五万行代码、四十个中间件、十一个应用。

但 MiniMax 的 Mini-Agent 核心只有 523 行，也能跑。

那中间那几万行到底加了什么？这一篇拿三个不同体量的项目当标尺，把「从能跑到能卖」的差额一条条列出来 —— 有些你现在就该加，有些要等真有用户了再说。

一、三个参照系

前五篇拆的都是复杂系统（Kimi CLI 五万行、DeerFlow 40+ 中间件、Suna 11 个应用）。这三个项目用来标定坐标系的另外几端：

项目	Star	语言	体量	定位	活跃度
Mini-Agent（MiniMax）	2,972	Python	核心 523 行	最小可用基线	活跃
OpenHands SDK	1,007	Python	1,261 个文件	生产内核，安全见长	活跃
JoyAgent（京东）	11,872	Java	多模块	企业落地起点	⚠️ 停更 2026-02-12

对照价值：用「复杂系统减去 Mini-Agent」，就得到「从能跑到能卖」之间的确切差额。

用「复杂系统减去 Mini-Agent」是判断自己需要多复杂的最快方法：右侧那些能力，缺哪一项会让你的场景真正出事，就补哪一项，而不是照着最复杂的实现全抄。

二、最小基线：Mini-Agent 的 523 行

git clone --depth 1 https://github.com/MiniMax-AI/Mini-Agent.git

项	值
仓库	MiniMax-AI/Mini-Agent
Star	2,972
体量	mini_agent/ 全部 1,949 行，核心 agent.py 523 行

主循环就是教科书那个样子：

mini_agent/agent.py:321-352（节选）

async def run(self, cancel_event: Optional[asyncio.Event] = None) -> str:
    """Execute agent loop until task is complete or max steps reached."""
    ...
    step = 0
    while step < self.max_steps:
        # Check for cancellation at start of each step
        if self._check_cancelled():
            self._cleanup_incomplete_messages()
            return "Task cancelled by user."

        # Check and summarize message history to prevent context overflow
        await self._summarize_messages()

        # Get tool list for LLM call
        tool_list = list(self.tools.values())
        response = await self.llm.generate(messages=self.messages, tools=tool_list)

mini_agent/agent.py:53

max_steps: int = 50,

默认 50 步。 这个数字很有意思，横向对照一下：

	步数	性质
Mini-Agent	50	默认上限
Manus	约 50	官方公布的实测均值
DeerFlow	150 / 60	子 Agent 上限
Kimi CLI	1000	单轮上限

Mini-Agent 的默认值刚好卡在 Manus 的实测均值上。 大概不是巧合——50 步就是「一个中等任务」的自然量级。

2.1 它有什么，没什么

它的官方定位就是 "a minimal yet professional single agent demo"——注意是 single agent，从没自称多智能体框架。

2.2 什么时候这就够了

如果你的场景满足下面这些，523 行真的够用，别过度设计：

• 单用户或小团队内部用，不是对外服务
• 任务时长在分钟级，不是小时级
• 跑在可信环境里（自己的机器），不需要沙箱
• 成本可控（用的人少），不需要预算兜底

用法建议：想搞懂 Agent 原理，先读这 523 行，比读任何框架文档都快。

三、生产内核：OpenHands 把力气花在了安全上

git clone --depth 1 https://github.com/OpenHands/software-agent-sdk.git

3.1 先纠正一个常见误读

仓库	Star	实际是什么
OpenHands/OpenHands	84,444	TypeScript 应用层，Agent 循环不在这
OpenHands/software-agent-sdk	1,007	真正的 Agent 内核，1,261 个 Python 文件

很多人拿那 84k star 说事，然后进去找 Agent 循环——找不到。

这在这个领域越来越常见：star 数和技术内核不在同一个仓库。Kimi 也是这样（CLI 和模型分开），Suna 也是（包的是 OpenCode）。

看这个领域的项目，先确认内核在哪个仓库。

3.2 子 Agent：定义格式已经收敛了

openhands/sdk/subagent/ 下只有四个文件。定义方式是 Markdown + frontmatter：

openhands/sdk/subagent/schema.py:346-348（节选）

model: str = str(fm.get("model", "inherit"))
...
tools: list[str] = _extract_tools(fm)

openhands/sdk/subagent/registry.py:174（注释）

- `model: inherit` preserves the parent LLM; an explicit model name ...

注意 model: inherit 这个约定——四家用的是同一个词：

	定义格式	模型字段	工具字段
Claude Code	Markdown + YAML frontmatter	model: inherit	tools / disallowedTools
OpenHands SDK	Markdown + frontmatter	model: inherit	tools
DeerFlow	Python dataclass	model: "inherit"	tools / disallowed_tools
Kimi CLI	YAML（带 extend 继承）	default_model	allowed_tools / exclude_tools

四家独立实现，收敛到同一个形状。 这说明这个抽象基本已经定型了——你要自己做一套，照着抄就行，不用再设计。

3.2 真正的差异化：security 模块

这是 OpenHands 和别家最不一样的地方：

openhands/sdk/security/
├── analyzer.py               ← 风险分析
├── llm_analyzer.py           ← 用 LLM 判断风险
├── risk.py                   ← 风险等级
├── confirmation_policy.py    ← 什么情况需要人工确认
├── shell_parser.py           ← shell 命令解析
├── _shell_ast.py             ← ★ shell 抽象语法树
├── defense_in_depth/         ← 纵深防御
├── ensemble.py               ← 多个分析器投票
├── toolshield_helpers.py
├── toolshield_llm_analyzer.py
└── grayswan/                 ← 对抗性测试

_shell_ast.py 是个强烈的信号：它不是用正则匹配 rm -rf，而是把 shell 命令解析成抽象语法树再判断风险。

为什么正则不行：

ensemble.py 是多个分析器投票，defense_in_depth/ 是纵深防御，grayswan/ 指向对抗性测试。这一整套是「让 Agent 在别人的机器上跑命令」必须付的代价。

3.3 两条安全路线的对比

对照 Suna 的做法：

	OpenHands	Suna
安全边界在哪	命令级别：分析每条命令要干什么	容器级别：把 Agent 关进沙箱
主要成本	误报率调优（永无止境）	基础设施（真金白银）
挡不住什么	分析器漏判的新手法	沙箱内可做的一切破坏
适合	Agent 要碰用户真实环境	Agent 只在隔离环境干活

两条路都对，选哪条取决于 Agent 要不要碰用户的真实文件系统。 如果碰，光有沙箱不够；如果不碰，命令级分析是多余的复杂度。

顺带一提，agent/parallel_executor.py 的存在说明 OpenHands 支持并行工具执行，跟 Manus 的「一次一个工具」 是相反取向。

四、Java 阵营：JoyAgent-JDGenie

项	值
仓库	jd-opensource/joyagent-jdgenie
Star	11,872
语言	Java
⚠️ 活跃度	最后 push 2026-02-12，已停更半年

4.1 三进程分工很务实

genie-backend/   ← Java，Agent 编排主体
genie-tool/      ← Python，工具执行
genie-client/    ← 客户端
ui/

Java 做编排、Python 做工具。 Java 生态在服务治理、事务、权限这些企业能力上强，Python 生态在 AI 工具链上强，各取所长。

国内不少企业内部落地会走这条路，因为存量系统是 Java 的，Agent 要接的那些内部服务也都是 Java 的。

4.2 编排：经典的 Plan-Execute-Summary 三段式

genie-backend/src/main/java/com/jd/genie/agent/agent/ 下的类：

BaseAgent.java          ← 基类
ReActAgent.java         ← ReAct 抽象
ReactImplAgent.java     ← ReAct 实现
PlanningAgent.java      ← 规划
ExecutorAgent.java      ← 执行
SummaryAgent.java       ← 总结
AgentContext.java       ← 共享上下文

注意 AgentContext 是共享的。 这跟前面五家「每个子 Agent 一份独立上下文」完全不同。

五、两种「多 Agent」，别搞混

JoyAgent 这个设计引出一个重要区分。「多 Agent」这个词底下其实是两种完全不同的东西：

	阶段式	委派式
「一个 Agent」是	任务的一个阶段	一个外包出去的子任务
上下文	共享	隔离
解决的问题	让每个阶段的提示词更专注	防止上下文被垃圾撑爆
代表	JoyAgent、早期 MetaGPT、ChatDev	Kimi CLI、Claude Code、Manus、DeerFlow
年代	2023–2024 主流	当下主流

为什么阶段式在退场，两个原因：

① 共享上下文在长任务里会无限膨胀。 这正是 02 第一节那个问题——阶段式没有解决它，只是把一个大上下文分给三个角色轮流用。

② 规划阶段不需要看到执行阶段的细节。 执行时读进来的一堆文件内容，对规划毫无用处，还会干扰判断。Manus 干脆把规划提到循环外面，就是这个道理的极端版本。

这是个很好用的判龄工具：看一个 Agent 项目的多 Agent 是「规划-执行-总结」还是「主 Agent 派子 Agent」，基本能判断它是哪一代的设计。

JoyAgent 停更在 2026 年 2 月，某种程度上也是这代架构的时间戳。

要不要用它：Java 团队需要一个现成起点的话，它的工程结构（Java/Python 分进程）仍有参考价值。但半年没更新意味着模型侧的新能力（交错思考、并行工具调用）它都没跟上，别指望直接上生产。

六、三个参照系合起来看

	Mini-Agent	OpenHands SDK	JoyAgent
定位	教学基线	生产内核	企业落地起点
体量	523 行核心	1,261 个 py 文件	Java 多模块
子 Agent	没有	Markdown frontmatter	阶段式，共享上下文
差异化	极简可读	shell 语法树安全分析	Java + Python 分进程
活跃度	活跃	活跃	停更半年
什么时候看	想搞懂原理	想抄一套生产实现	Java 团队找参考

七、小结：你到底需要多复杂

按这个顺序自问，在哪一步停下就用哪一档：

• 只是自己用，任务几分钟？ → Mini-Agent 那 523 行就够，别上子 Agent
• 上下文经常被探索过程撑爆？ → 加子 Agent 委派（02）
• 任务要跑几十分钟以上？ → 加上下文工程那六条（03）
• 子任务之间有共享状态？ → 考虑开隔离的口子（04）
• 要对外服务、多个用户？ → 加限流、预算、死循环检测（05）
• Agent 要跑任意命令？ → 沙箱（06）或命令级安全分析（本篇第二节）
• 要几十上百路并行？ → 重隔离，一子 Agent 一机器（03）

三条能带走的结论：

1. 「star 最多的仓库」不等于「代码在的仓库」。 看内核在哪。
2. 子 Agent 的定义格式已经收敛：Markdown/YAML frontmatter + model: inherit + tools/disallowed_tools。四家独立收敛，直接抄。
3. 「阶段式多 Agent」正在退场，「委派式」是当下主流。 这也是判断项目新旧的一个快捷方式。

八、参考

• Mini-Agent：https://github.com/MiniMax-AI/Mini-Agent
• OpenHands SDK（内核）：https://github.com/OpenHands/software-agent-sdk
• OpenHands 主仓（应用层）：https://github.com/OpenHands/OpenHands
• JoyAgent-JDGenie：https://github.com/jd-opensource/joyagent-jdgenie
• 下一篇：08 单 Agent 还是多 Agent——全专题结论，两家生产结论正面对撞