Overview cn

Jianmu（建木）是一个面向 LLM Agent 的事件驱动、异步行为树运行时框架。它不仅让模型调用工具，更将 Agent 真正运行起来所需的关键能力——状态管理、中断恢复、安全约束、多 Agent 协作——统一到同一套执行模型中。本页帮助你理解 Jianmu 的核心定位、它解决的真实问题，以及它在 Agent 框架生态中的位置。

Jianmu 是什么¶

Jianmu 的名称取自中国神话中连通天地的神树"建木"，寓意它能成为连接 LLM 能力与现实任务执行的桥梁。从技术角度看，它是一个以 py_trees 行为树 为执行内核、以 Pydantic 类型化状态 为数据中枢、以 asyncio.Event 事件驱动调度 为唤醒机制的 Agent 运行时框架。

graph TD
    subgraph 上层应用
        A1[TUI Chat 终端]
        A2[Tree Studio 可视化]
        A3[Swarm Studio 多Agent]
        A4[Seedbot 产品入口]
    end

    subgraph Jianmu 核心运行时
        B1[Agent / AgentTeam<br/>外观模式]
        B2[ReactiveRunner<br/>事件驱动调度器]
        B3[StateManager<br/>类型化状态管理]
        B4[行为树执行引擎<br/>py_trees 异步扩展]
    end

    subgraph 运行时能力模块
        C1[Model Client<br/>统一模型调用]
        C2[Tool System<br/>工具抽象与执行]
        C3[Skill Catalog<br/>技能发现与路由]
        C4[Guard & Approval<br/>安全约束与审批]
        C5[Execution Sandbox<br/>隔离执行环境]
        C6[Memory & Checkpoint<br/>记忆与断点恢复]
        C7[Swarm Runtime<br/>多Agent协作]
        C8[RAG & MCP<br/>知识检索与外部协议]
        C9[Telemetry<br/>可观测性]
    end

    A1 --> B1
    A2 --> B1
    A3 --> B1
    A4 --> B1
    B1 --> B2
    B2 --> B3
    B2 --> B4
    B3 --> C6
    B2 --> C5
    B2 --> C7
    B1 --> C1
    B1 --> C3
    B4 --> C2
    B4 --> C4
    B4 --> C8
    B2 --> C9

上图展示了 Jianmu 的三层架构：上层应用 通过 Python API 或可视化界面与框架交互；核心运行时 负责 Agent 的组装、调度、状态管理和行为树执行；能力模块 提供可插拔的模型接入、工具系统、安全防护、记忆存储、多 Agent 协作等横向能力。

行为树：不只是"画树"¶

许多开发者对行为树的印象停留在游戏 AI 的可视化编辑器上，但 Jianmu 对行为树的用法有本质不同。它将行为树视为一种 执行语义的抽象：每一个节点代表一个可中断、可恢复、可观测的计算步骤。LLM 调用是一个节点，工具执行是一个节点，等待用户审批也是一个节点——这些异构操作在行为树中被统一建模，由 ReactiveRunner 以事件驱动的方式逐 tick 推进。

这种设计意味着：一个 ReAct 循环不是一个黑盒 while 循环，而是一棵由 LLM 节点、工具执行节点和条件判断节点组成的 可检查、可挂起、可从断点恢复的行为树。

Jianmu 解决什么问题¶

现有的 LLM Agent 框架通常能快速搭建一个"模型调用工具"的 Demo，但在真实场景中会暴露一系列结构性问题。下表对比了常见做法与 Jianmu 的方案：

真实场景中的痛点	常见框架的做法	Jianmu 的方案
Agent 执行长任务时崩溃，无法从中间恢复	从头重跑，浪费 token 和时间	`FileCheckpointer` 在每个 tick 保存状态快照，支持从任意断点恢复
工具调用缺少审批机制，模型可能执行危险操作	依赖 prompt 约束（不可靠）	`GuardEnforcer` 提供工具策略、预算控制、频率限制、确认拦截四层防护
状态散落在 prompt 字符串和临时变量中，难以追踪	隐式状态，调试困难	`StateManager` 基于 Pydantic 的类型化状态，所有消息、进度、挂起信息统一存储
Agent 等待用户输入或外部回调时，线程被阻塞	同步阻塞或复杂的回调嵌套	`ReactiveRunner` 基于 `asyncio.Event`，空闲时不消耗 CPU，事件到达时自动唤醒
从单 Agent 扩展到多 Agent 需要重新设计架构	缺乏原生多 Agent 支持	`AgentTeam` + `Swarm Runtime` 提供邮箱路由、角色注册、消息传递原语
工具执行环境影响宿主进程	工具在进程中直接执行	`LocalSandbox` 和 `DockerSandbox` 提供进程级和容器级隔离

核心设计原则¶

Jianmu 在架构上遵循四条原则，这四条原则贯穿了框架的每个模块：

状态驱动：Agent 的所有运行时信息——对话历史、任务进度、工具结果、挂起原因——都存入 StateManager 维护的 Pydantic 模型中。状态变更通过 reducer 机制合并，避免竞态条件。Ephemeral 注解标记的字段会在 step/run/call 边界自动重置，防止状态污染。
事件驱动调度：ReactiveRunner 不使用忙等循环。它订阅 StateManager 的变更通知和异步任务的完成信号，仅在事件到达时执行一次 tick_once()。如果树中所有节点都进入等待状态，调度器休眠，直到下一个事件唤醒它。
可中断可恢复：行为树的每个节点都是潜在的挂起点。当节点需要等待审批、用户输入或外部回调时，它通过 InteractionController 发出挂起信号，ReactiveRunner 保存 checkpoint 并退出。外部系统完成交互后，通过恢复接口重新注入结果，树从挂起点继续执行。
能力模块可插拔：模型 Provider、工具、Skill、Guard Checker、Execution Runner、Memory Backend 都通过 Protocol 或基类抽象，可以在不修改核心运行时的情况下替换或扩展。

何时选用 Jianmu¶

Jianmu 不是"又一个 LangChain 替代品"。它的设计重心不是 prompt 模板链，而是 Agent 运行时的工程可靠性。以下场景是 Jianmu 的优势领域：

长流程 Agent：跨多个步骤、多种工具、多个阶段的持续任务，需要中间状态追踪和断点恢复。
人机协作 Agent：需要人工审批、用户补充输入、外部系统回调的工作流。
安全敏感场景：工具调用需要策略检查、预算限制、频率控制和执行隔离。
多 Agent 系统：从单 Agent 起步，逐步演进到 Swarm 协作模式。
需要观测性的生产部署：TelemetryHub 提供 Span 追踪、事件日志和多 Sink 输出，支持运行时诊断。

如果你只需要单次 LLM 调用或简单的 RAG 流水线，更轻量的方案可能更合适。但一旦你的 Agent 需要"真正跑起来"——处理长任务、等待外部事件、在约束下安全执行——Jianmu 的分层架构能提供开箱即用的支撑。

项目结构一览¶

jianmu/                     # 核心框架包
├── engine/                 # 运行时引擎：调度、状态、Agent 外观、依赖注入
│   ├── runtime.py          # ReactiveRunner：事件驱动的 tick 调度
│   ├── agent.py            # Agent 外观：单 Agent 的组装入口
│   ├── state.py            # StateManager：类型化状态与 Ephemeral 机制
│   ├── behaviour.py        # AsyncBehaviour：py_trees 的异步节点基类
│   ├── deps.py             # RunContext：运行时依赖注入容器
│   ├── events.py           # RuntimeEventBus：运行时事件总线
│   └── interaction.py      # 挂起/恢复协议：审批、用户输入、外部回调
├── node/                   # 节点系统：LLM、Tool、Skill、Swarm 节点
│   ├── base.py             # Node / AsyncNode 基类
│   ├── presets/            # 预制模式：ReAct、Plan-Execute
│   ├── builtin/            # 内建节点：AgentLLM、ToolExecutor、SkillNode 等
│   └── composites.py       # 复合节点：LoopUntilSuccess 等
├── model/                  # 模型接入层：OpenAI / LiteLLM Provider 统一调用
├── tool/                   # 工具系统：Tool 基类、@tool 装饰器、ToolSet
├── skill/                  # 技能系统：SKILL.md 解析、行为树技能、Prompt 技能
├── guard/                  # 安全防护：策略检查、预算控制、审批流程
├── execution/              # 执行沙箱：LocalSandbox、DockerSandbox
├── memory/                 # 记忆系统：Checkpoint、上下文构建、长期记忆
├── swarm/                  # 多 Agent 协作：Swarm Runtime、角色、团队
├── mcp/                    # MCP 集成：客户端、Provider、Server
├── rag/                    # RAG 流水线：嵌入、检索、重排
├── telemetry/              # 可观测性：TelemetryHub、Span、多 Sink
├── message/                # 消息系统：消息存储、编码、保留策略
├── config/                 # 配置体系：jianmu.yaml 加载、约束、Prompt 预设
└── tree/                   # 行为树原语：py_trees 的重新导出层
apps/                       # 上层应用
├── tui_chat/               # 基于 Textual 的终端交互界面
├── tree_studio/            # 可视化工作流创建与调试
├── swarm_studio/           # 多 Agent 可视化编排
└── seedbot/                # 产品级 Agent 应用入口
examples/                   # 渐进式示例（12 步从入门到多 Agent）
tests/                      # 完整测试套件（100+ 测试文件）

继续阅读¶

现在你已经了解了 Jianmu 是什么以及它解决的问题，建议按以下顺序深入：

快速开始：安装、配置与最小 Agent 示例 — 在 5 分钟内运行你的第一个 Jianmu Agent，从 pip install 到第一个 ReAct 对话。
项目配置体系：jianmu.yaml 与 .env 协同工作 — 理解 Jianmu 的双层配置策略：静态项目配置与动态环境变量的职责分离。
渐进式示例导航：从 Hello World 到多 Agent 协作 — 沿 12 个渐进式示例，从最简 LLM 对话走到 Swarm 多 Agent 协作。
架构分层总览：运行时引擎 → 节点组合 → 能力模块 — 深入理解 Jianmu 三层架构的职责边界与交互关系。