Bonsai：Rust 行为树库（含 Python 绑定）

安装与使用

README 将使用方式分为 Rust 与 Python 两条路径，二者发布渠道不同：

• Rust：库已发布到 crates.io，推荐做法是在 Cargo.toml 中加入依赖，例如 bonsai-bt = "*"。实际工程中通常会把版本号收敛为具体版本，以避免上游变动带来的不确定性。
• Python：库以 bonsai-bt 之名发布在 PyPI 上，执行 pip install bonsai-bt 即可安装；Python 侧的示例放在仓库的 bonsai-py/ 目录中。

环境方面，README 的徽章标明最低支持 Rust 1.72（对应 Rust 的最小支持版本策略 RFC 2495），低于该版本的工具链不在支持范围内。API 文档托管在 docs.rs 的 bonsai-bt 页面，仓库内另有 docs/concepts/README.md 讲解概念、examples/README.md 汇总示例、DEVELOPMENT.md 作为开发指南，以及一块公开的 Kanban 看板用于跟踪任务。README 顶部还提供了行为树的快速入门视频链接，适合在动手前建立直观印象。

行为树的核心概念

README 给出的定义很朴素：行为树是一种数据结构，用来规定某些“行为”可以如何发生，以及它们执行的先后顺序。它的价值在于让复杂系统同时保持模块化与反应式——前者让行为可以被拆分成小块并自由组合、复用，后者让系统能根据条件变化及时切换策略，而不是把逻辑写成一团难以维护的分支判断。

在执行语义上，行为树是一棵由节点构成的树，每个节点代表一个过程（process）。过程结束时会上报 Success 或 Failure，父节点据此决定接下来选择哪个子过程；如果过程尚未结束，则上报 Running，表示“还在进行中”。正是这三种信号构成了整棵树调度的基础，父节点无须了解子节点的内部实现，只需根据返回结果做选择。

常用组合节点一览

README 用一组简洁的伪代码说明了常见控制节点的语义，这些也是理解该库 API 的入口：

• Sequence([A, B])：A 成功后再执行 B，即顺序执行。
• Select([A, B])：优先尝试 A，若 A 失败再尝试 B，即选择/回退。
• If(condition, A, B)：条件成功则执行 A，否则执行 B。
• Invert(A)：对 A 的结果取反，成功变失败、失败变成功。
• AlwaysSucceed(A)：无论子节点结果如何，都强制返回成功。
• Timeout(seconds, A)：运行 A，但若其 Running 状态超过时限则判为失败。
• While(LoopCondition, [A, B])：在 A、B 之间检查循环条件，条件成立则重复执行。
• While(WaitForever, [A, B])：以“永远等待”为条件，等价于无限循环。
• WhileAll(LoopCondition, [A, B])：等 A、B 全部成功完成后，才检查条件节点。
• WhenAll([A, B])：并行运行 A、B，等待两者都成功。
• WhenAny([A, B])：并行运行，等待任意一个成功。
• Race([A, B])：并行运行，任意一个结束即返回，不论成功还是失败。
• After([A, B])：并行运行，但要求 A 先于 B 成功。

README 提示可以查阅 Behavior 枚举以获得更完整的信息——也就是说，上述只是常用集合，实际可用的节点类型以源码中的枚举定义为准。

长耗时任务与响应性

行为树要始终保持“响应”，关键在于树遍历本身不能被阻塞：树中创建的动作应当尽可能瞬时完成，否则一次耗时调用就会拖住整棵树的推进，让其他分支失去及时响应的机会。

对于确实需要数秒甚至数分钟才能完成的任务或函数——无论 async 还是同步实现——README 建议把这些作业派发到后台线程执行，再通过 channel 获取任务状态。这样行为树一侧只负责轮询或接收状态，从而维持轻量的遍历节奏。仓库 examples 目录中的 async drone 示例演示了这一思路，可作为把长任务与行为树解耦的参考实现。

示例与延伸阅读

若要上手，README 指向的入口依次是：examples/README.md 中的示例集合、docs/concepts/README.md 中的概念讲解、bonsai-py/ 中的 Python 用法，以及 DEVELOPMENT.md 中的开发说明。README 末尾还有 “Honorable Mentions / similar crates” 一类的相邻项目推荐，便于对比不同实现的设计取舍。

需要提醒的是，README 主要给出语义层面的说明与最小安装指引，并未在同一页内覆盖全部 API、性能特征或各引擎集成的细节；涉及确定性保证的具体机制、并发模型与 ROS/ROS2、Bevy、Piston 等方向的可用性，建议以 docs.rs 文档、源码与示例为准逐项核验。