Wiki
BehaviorTree.CPP v4.10.0
本文由簡體中文內容確定性轉換，並受版本化術語表保護。
1.BehaviorTree.CPP v4.10.0 學習路線
本教程面向第一次接觸行為樹的讀者，從基本概念開始，逐步寫出能夠運行的 C++ 程序，再學習任務組合和圖形調試。示例統一使用 BehaviorTree.CPP 4.10.0、C++20、Ubuntu 22.04 和 VSCode CMake Tools。
2.先從一個導航任務認識行為樹
假設機械人收到一個目標，需要先檢查電量，再前往目標，最後報告到達：
一次导航任务
├── 检查电量是否足够
├── 前往指定目标
└── 报告任务完成這張圖先表達任務由哪些步驟組成。實際執行時，還要決定：電量不足後怎麼辦，導航沒有結束時怎樣繼續檢查，導航失敗時是否重試，取消任務時怎樣停止。
行為樹（Behavior Tree，簡稱 BT）用有層次的節點組織這些條件和操作。上層節點決定執行順序與方案選擇，下面的節點完成具體檢查或動作。 各類節點怎樣處理成功、失敗和運行中的結果，會從“基本概念”開始逐步介紹。
BehaviorTree.CPP 是實現行為樹的 C++ 庫。 本教程用 C++ 編寫節點邏輯，用 XML 文件組織節點，再由主程序驅動整棵樹執行。 學會編寫和運行程序後，再使用 Groot2 編輯樹結構、觀察節點狀態和回放日誌。
3.學習前需要準備什麼
需要具備 C++ 基礎，能夠閲讀函數、類、繼承、枚舉和 std::string。工程構建使用 CMake工程模板；不熟悉模板時，可以先看它的目錄結構和 Configure、Build、運行操作。
前兩篇先建立行為樹概念，不需要提前準備 BT 工程。到“第一個完整程序”時，會從獲取模板、創建文件開始，完整説明依賴配置、編寫代碼、構建運行和斷點觀察。
示例使用模擬電量、目標和導航進度，在獨立 CMake 程序中運行，不需要提前啓動 ROS 2 或連接機械人。先把樹的執行與數據傳遞看清楚，再考慮將模擬操作替換成真實模塊。
4.從概念到完整任務
| 文檔 | 主要內容 | 階段 |
|---|---|---|
| 基本概念 | tick、五種狀態與四類節點 | 概念 |
| 控制與裝飾規則 | 順序、備選、響應式檢查、重試、重複和超時 | 概念 |
| 第一個完整程序 | 固定版本依賴、註冊節點、加載 XML、條件與目標傳遞 | 基礎實踐 |
| 節點之間傳數據 | 自定義類型、端口默認值與外部 Blackboard | 基礎實踐 |
| 持續任務與中止 | 回調調用鏈、多次 tick、條件變化和主動停止 | 基礎實踐 |
| 組合實際任務 | 子樹隔離與映射、多 XML 文件、有限重試及失敗報告 | 基礎實踐收尾 |
| 腳本與前後置條件 | Script、條件屬性、SKIPPED 與中止後的任務結果 | 進階實踐 |
| 全局Blackboard與數據更新 | 全局層、更新序號、時間戳與數據處理策略 | 進階實踐 |
| Groot2 | 節點模型、圖形編輯、實時監控和日誌回放 | 工具實踐 |
已經學過 v3.8.7 時，可以先讀 區別與遷移，再運行組合任務與進階實踐。新讀者直接按表格順序學習，不需要先完成 v3。
5.練習工程怎樣逐步建立
第一個工程在“第一個完整程序”中從 CMake 模板建立，命名為 bt4_first_tree。先運行一個打印動作，再在同一個工程裏逐步加入電量檢查、目標輸入和節點之間的數據傳遞。
後續主題會在已經完成的本系列工程上建立副本，讓不同練習分別保存在自己的文件夾中：
| 學習主題 | 工程目錄 | 從哪裏開始 |
|---|---|---|
| 第一個完整程序 | bt4_first_tree |
獲取 CMake 模板，按本篇步驟建立第一個 BT 工程 |
| 節點之間傳數據 | bt4_ports |
複製本系列“第一個完整程序”中建立的 bt4_first_tree |
| 持續任務與中止 | bt4_running |
複製本系列“節點之間傳數據”中的 bt4_ports |
| 組合實際任務 | bt4_mission |
複製本系列“持續任務與中止”中的 bt4_running |
| 腳本與前後置條件 | bt4_script |
同樣從“持續任務與中止”的 bt4_running 建立副本 |
| 全局 Blackboard 與數據更新 | bt4_updates |
複製“腳本與前後置條件”中的 bt4_script，複用構建配置 |
| Groot2 | bt4_groot |
從“持續任務與中止”的 bt4_running 建立副本，增加監控與日誌 |
bt4_ 是本系列練習目錄的命名前綴。具體複製哪個文件夾、怎樣修改項目名、哪些文件需要替換，都在對應篇章中説明，不必現在一次建好這些工程。
複製工程後，副本中的舊 build、install 目錄需要清理，因為它們記錄的是原工程的構建路徑和結果。隨後通過 Configure、Build 為新工程重新生成。CMake 配置與 XML 路徑的具體作用，會在第一個程序中解釋。
6.每一步怎樣學習
先運行當前程序，看到輸出並理解執行過程，再增加下一項功能。需要觀察調用和數據時，按文中的位置設置斷點，查看節點狀態、輸入值和成員變量。
修改 C++ 後，保存並 Build，再 Launch；只修改 XML 時，保存後重新 Launch。各篇都會給出本次應看到的結果和對照操作，截圖位置供學習時補齊。
基礎實踐從一個動作逐步擴展到完整運輸任務。之後再學習腳本條件、共享外部數據和 Groot2，讓任務表達、數據處理與運行觀察連成完整流程。
7.本組驗證範圍
完整程序已在 Ubuntu 22.04 的 Humble 容器中，以 CMake 3.22.1、GCC 11.4 和 C++20 編譯運行。依賴模塊分別驗證了固定 4.10.0 源碼嵌入與精確安裝包查找；源碼驗證使用已下載並核對哈希的標籤內容。驗證程序輸出的庫版本為 4.10.0。
已檢查同步示例、端口固定值與默認值、缺失或錯誤輸入、條件中止、主動停止、普通與響應式 Sequence、兩段導航重試、錯誤子樹映射、腳本跳過與失敗、全局數據重複讀取及同值重新寫入。Groot2 的模型加載、編輯、實時連接和成功／中止日誌讀取也已驗證。
驗證範圍是教程的獨立模擬程序。真實 ROS 2 Action 或 Nav2 的接入屬於後續集成工作。截圖預留供學習時補齊，按自己的實際運行情況推進。
官方網頁當前版本標籤不一定與 4.10.0 相同，函數聲明、控制節點行為和構建開關以本教程固定版本的源碼與運行結果為準。庫自身使用 C++17，練習程序使用 C++20。