Python API¶
适用对象：Python 框架使用者 / 扩展开发者 / 核心维护者
是否必读：按需
相关文档：docs/concepts/*.md, docs/getting_started/*.md
1. 这组文档解决什么问题¶
这部分文档面向 jianmu 的 Python 包公开 API，而不是应用层 HTTP 接口。
它的目标是回答三类问题：
- 这个模块应该从哪里导入
- 这个对象是不是稳定公开 API
- 这个对象应该怎么用，而不是去翻内部实现
2. 文档组织原则¶
API 文档按公开导入入口组织，而不是按源码文件组织。
优先级如下：
jianmu/__init__.pyjianmu/tree/__init__.pyjianmu/<module>/__init__.py- 这些入口 re-export 的稳定对象
这意味着像 jianmu.node.builtin.*、jianmu.swarm.runtime.* 这样的内部实现模块，默认不直接作为主 API 页面暴露，除非它们已经被公开入口重新导出。
3. 推荐阅读顺序¶
如果你是第一次接触 jianmu，建议按下面顺序阅读：
jianmujianmu.treejianmu.nodejianmu.tooljianmu.modeljianmu.messagejianmu.memoryjianmu.skilljianmu.swarmjianmu.executionjianmu.guard
其余模块通常按具体需求查阅。
4. 自动生成与手写说明的边界¶
这一组文档采用“手写说明 + API 参考块”的方式：
- 手写部分负责解释模块职责、边界、推荐用法和注意事项
- 自动生成部分负责展示类、函数、签名和 docstring
这样做的原因是：jianmu 的公开面经过 __init__.py 精选过，纯自动生成会把大量内部实现细节一起暴露出来，不利于使用者理解。
5. 使用约定¶
- 示例中的导入路径优先使用公开入口
- 如果某个对象依赖可选包，会在对应页面注明
- 如果某个对象更适合作为内部扩展点而不是日常用户 API，也会在页面中明确标注
6. 导入路径约定¶
jianmu只放框架核心原语jianmu.tree只放行为树原语jianmu.<module>放对应能力域的稳定公开入口jianmu.<module>.builtin主要是内建实现的组织层，不作为主推荐导入路径
换句话说，新代码应优先写成：
from jianmu import StateManagerfrom jianmu.tree import Sequencefrom jianmu.node import Logfrom jianmu.tool import CalculatorTool
而不是默认写成：
from jianmu.node.builtin import Logfrom jianmu.tool.builtin import CalculatorTool
7. alias 约定¶
少数公开名是语义 alias，而不是独立定义。例如：
jianmu.Node是jianmu语义上的同步节点基类名jianmu.AsyncNode是推荐给用户理解的异步节点名
这类 alias 会继续作为公开名出现，但文档会优先解释它们的语义角色，而不是把它们当作全新的底层实现类型。
8. 入口索引¶
- 根入口：
jianmu - 行为树原语：
jianmu.tree - 配置：
jianmu.config - 运行时核心：
jianmu.engine - 执行与沙箱：
jianmu.execution - 约束与审批：
jianmu.guard - MCP：
jianmu.mcp - 记忆：
jianmu.memory - 消息：
jianmu.message - 模型：
jianmu.model - 节点：
jianmu.node - RAG：
jianmu.rag - Skill：
jianmu.skill - Swarm：
jianmu.swarm - Telemetry：
jianmu.telemetry - Tool：
jianmu.tool
9. 当前分层¶
当前 Python API 建议按下面的心智模型理解：
jianmu：框架核心原语，例如状态、运行器、装饰器和高频 presetjianmu.tree：行为树原语，承接常用py_trees组合子、状态和装饰器jianmu.node：jianmu语义节点与内建节点- 其余一级模块：按能力域组织，例如
tool、message、memory、guard
如果旧代码仍从 jianmu 顶层导入树原语，这通常只是兼容迁移路径，不代表它仍是推荐写法。