SoarGroup/Soar
GitHub: SoarGroup/Soar
Soar 是一个用于构建智能系统的通用认知架构框架，解决复杂决策和学习问题。
Stars: 421 | Forks: 83
# 索尔
[](https://github.com/SoarGroup/Soar/actions/workflows/cmake-multi-platform.yml)
[](https://github.com/SoarGroup/Soar/actions/workflows/build.yml)
这是 Soar 的代码库，Soar 是一种认知架构，用于开发展现出智能行为的系统。有关此项目的更多信息，请访问：
- [Soar 主页](http://soar.eecs.umich.edu/)
- [GitHub 项目页面](https://github.com/SoarGroup/Soar)
请注意，面向最终用户的 Soar 发行版中附带的自述文件位于 [Release-Support](https://github.com/SoarGroup/Release-Support/blob/master/txt/README.md) 仓库中。
## Soar 构建版本
您可以在两个地方获取 Soar 的二进制构建版本：
- [官方发布版本](http://soar.eecs.umich.edu/articles/downloads/soar-suite)
— 多平台 zip 包，包含 `bin/win_x86-64`、`bin/linux_x86-64`、`bin/mac_x86-64` 和 `bin/mac_ARM64`（Apple Silicon）。
- 最新开发构建：基于 CMake 的发布流水线 ([`cmake-multi-platform.yml`](https://github.com/SoarGroup/Soar/actions/workflows/cmake-multi-platform.yml?query=branch%3Adevelopment)) 会为每个平台生成构件，包括 ARM64 macOS。SCons CI ([`build.yml`](https://github.com/SoarGroup/Soar/actions/workflows/build.yml?query=branch%3Adevelopment)) 也保持最新，但不生成 ARM64 macOS 构件 — 请在 Apple Silicon 上使用 `cmake-multi-platform.yml` 或从源代码构建。
## Soar 性能
使用因子分解压力测试自动计算了一些性能统计数据。您可以在 [Performance.md](https://github.com/SoarGroup/Soar/blob/development/Performance.md) 中逐提交查看性能。
免责声明：这些是最坏情况的测试。平均性能可能高得多。此外，这些测试表明，即使在最坏情况下，Soar 也超越了其 50 毫秒响应时间的目标（在这些测试中，每次决策的最大值约为 30 毫秒）。
## 开发
Soar 支持两种构建系统：`CMake`（参见 [使用 CMake 构建](#build-with-cmake)）和 `scons`（参见 [使用 scons 构建](#build-with-scons)）。两者保持同步，并生成二进制兼容的构件，这些构件位于相同的 `out/` 目录和多平台安装布局中。发布 zip 包由基于 CMake 的 [`cmake-multi-platform.yml`](.github/workflows/cmake-multi-platform.yml) 工作流构建。
下表比较了截至 9.6.5 版本，两种构建系统支持的 Soar 构建特性。
| 特性 | Scons | CMake |
| ----------------------------- | ----- | ----- |
| Soar 动态库 | ✅ | ✅ |
| Soar 静态库 | ❌ | ✅ |
| Soar CLI | ✅ | ✅ |
| 单元测试 | ✅ | ✅ |
| 性能测试 | ✅ | ✅ |
| 外部库测试 | ✅ | ✅ |
| SVS | ✅ | ✅ |
| SWIG Python | ✅ | ✅ |
| SWIG Java | ✅ | ✅ |
| SWIG JavaScript | ❌ | ✅ |
| SWIG C# | ✅ | ✅ |
| SWIG Tcl | ✅ | ✅ |
| Python 包 `soar-sml` | ✅ | ❌ |
| 生成 `compile_commands.json` | ✅ | ✅ |
| 发布版 | ✅ | ✅ |
| 调试版 | ✅ | ✅ |
| 带地址消毒器的调试版 | ❌ | ✅ |
| Conan 包管理器集成 | ❌ | ✅ |
| macOS | ✅ | ✅ |
| Linux | ✅ | ✅ |
| Windows | ✅ | ✅ |
| Java 调试器构建 | ✅ | ✅ |
### 前置条件
以下说明较为简略，可能已过时；编译 Soar 源代码的最权威指南始终是 CI 构建脚本。基于 CMake 的发布流水线是 [`cmake-multi-platform.yml`](.github/workflows/cmake-multi-platform.yml)；SCons CI 位于 [`build.yml`](.github/workflows/build.yml)。
要编译 Soar，您需要以下列出的依赖项。请注意，安装命令并不完整，例如缺少 Mac 的说明并不意味着该依赖项在 Mac 上不需要，等等：
- C/C++ 编译器
- Mac: `xcode-select --install`
- Linux: `sudo apt-get install build-essential`
- Python
- Mac: `brew install python`
- Java
- 我们推荐使用 [SDKMan](https://sdkman.io/)。调试器等至少需要 Java 11，但最好安装最新的 LTS 版本。推荐 Temurin。
要编译额外的 SML 包装库，您需要以下内容：
- pkg-config
- Mac: `brew install pkg-config`
- Linux: `sudo apt install pkgconf`
- SWIG
- Mac: `brew install swig`
- Linux: `sudo apt install swig`
- Python 开发头文件（仅用于 Python 包装器）
- Linux: `sudo apt install python3-dev`
- C# 编译器 (`csc`)（仅用于 C# 包装器）
- Mac: `brew install mono`
- Tcl（仅用于 Tcl 包装器和 TclSoarlib）
- Mac: `brew install tcl-tk`
### 使用 Scons 构建
该项目支持生成 `compile_commands.json`，该文件可用于例如 VSCode 与 C/C++ 插件配合提供智能提示。要生成此文件，请使用 `cdb` 目标运行 scons：
```
python3 scons/scons.py --scu --opt --verbose cdb
```
M 系列 Mac 用户注意：您需要确保为 ARM64 架构编译，而不是 x86_64。有时用户安装的 Python 处于兼容模式，导致为错误的架构编译。您可以使用以下命令检查您的 Python 构建的目标架构：
```
import sysconfig
>>> print(sysconfig.get_config_vars())
```
您也可以使用 `clang --version` 检查 `clang` 的默认编译目标。
要为本地开发编译所有内容，可以使用以下命令：
```
python3 scons/scons.py --scu --dbg --verbose all
```
调试模式会启用调试，但也会激活断言，这对于尽早发现错误很重要。`--scu`（单一编译单元）可以简化调试体验。
如果您想要优化构建，可以使用：
```
python3 scons/scons.py --opt --verbose all
```
### 使用 CMake 构建
需要具备以下先决条件：
- CMake (>= 3.21)
- Python 3，包括 `pip`，用于 [Conan](https://conan.io) 包管理器 (`pip install conan`)。
- 一个 C/C++ 工具链（Visual Studio 2022 / Xcode 命令行工具 / GCC 或 Clang）。
- 用于 Java 调试器和 SWIG-Java 绑定：JDK 11 或更新版本（推荐 Temurin）。
- 用于 SWIG 绑定：SWIG（Windows 用户可通过 `choco install swig` 安装）。
安装好依赖项后，为每种构建类型安装一次 Conan 依赖（这会从 Conan Center 获取 `sqlite3`、`asio` 和 `eigen`）：
```
conan install . --build=missing
conan install . --build=missing -s build_type=Debug
```
然后选择一个与您想要构建的内容相匹配的预设。日常开发和 CI 最常用的预设有：
| 预设 | 构建内容 |
| ------------------- | ------------------------------------------------------ |
| `Release-test` | 发布版 Soar + 单元测试 |
| `Release-svs-test` | 带 SVS 的发布版 Soar + 单元测试 |
| `Release-swig` | 发布版 Soar + Java 调试器 + 所有 SWIG 绑定 |
| `Debug-test` | 调试版 Soar + 单元测试（断言开启） |
| `Debug-test-asan` | 调试版 Soar + 单元测试 + AddressSanitizer |
| `Debug-swig-full` | 调试版 Soar + Java 调试器 + 所有 SWIG 绑定 |
配置并构建一个预设：
```
cmake --preset Release-test
cmake --build --preset Release-test
```
或者一步运行完整的配置/构建/测试工作流：
```
cmake --workflow --preset Release-test-workflow
```
`compile_commands.json` 会自动生成，并被 VS Code 的 C/C++ 扩展、clangd 和其他工具识别，无需进一步配置。VS Code CMake Tools 扩展直接与这些预设集成。
查看完整预设列表：
```
cmake --list-presets
cmake --workflow --list-presets
```
底层定义请参见 [`CMakePresets.json`](./CMakePresets.json)，一次性包装脚本请参见 [`build.sh`](./build.sh) / [`build.bat`](./build.bat)。
## 许可证
Soar 在以下 [LICENSE](https://github.com/SoarGroup/Soar/blob/development/LICENSE.md) 下可用。此许可证是 [BSD](http://opensource.org/licenses/BSD-2-Clause)。
标签：AI框架, ASM汇编, Bash脚本, CMake, JS文件枚举, SCons, 人工智能, 压力测试, 多平台构建, 性能测试, 数据可视化, 智能代理, 智能系统, 智能行为, 用户模式Hook绕过, 系统开发, 认知架构, 认知科学, 逆向工具