MasterAgent

环境要求

• 已安装 git、CMake 和 C++ 编译器（需支持 Release 构建）
• 系统有 make 及 nproc 等多核构建工具（Linux 环境）
• 可选：Node.js/npm，用于安装 @sparx/cli 命令行工具
• 可选：llama.cpp（llama-server）与 GGUF 模型文件，用于本地推理

安装与启动步骤

1. 1克隆仓库

   从 GitHub 拉取 MasterAgent 源码并进入项目目录，后续编译都在此目录进行。

   git clone https://github.com/OpenSparX/MasterAgent.git && cd MasterAgent

   复制

2. 2编译项目

   用 CMake 生成 Release 构建目录并多核编译，产出 build 下的可执行文件与测试。

   cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build -j$(nproc)

   复制

3. 3运行测试

   执行编译好的测试套件，含 speculative、CRDT、Merkle、embedding 等战略特性。

   ctest --test-dir build --output-on-failure

   复制

4. 4确定性模式跑评测

   不装模型也能用：确定性技能照常工作，可先跑全部评测脚本验证环境。

   cd MasterAgent && ./eval/run_all.sh

   复制

5. 5安装 npm CLI

   可选，官方另一种快速体验方式，全局安装 @sparx/cli 后直接运行 sparx run。

   npm install -g @sparx/cli
   sparx run

   复制

6. 6启动本地模型

   可选，先单独安装 llama.cpp，再加载 GGUF 模型并监听 8080 端口作为推理后端。

   llama-server -m your-model.gguf --port 8080

   复制

7. 7连接模型运行 CLI

   把编译出的 sparx CLI 指向本地 llama-server 的 127.0.0.1:8080 端点进行推理。

   ./build/cli/sparx run --endpoint 127.0.0.1:8080

   复制

关键配置

如何确认成功

执行 ctest 后终端显示 “100% tests passed, 0 tests failed out of 5”；或 sparx run 输出 route=deterministic 即表示运行正常。

常见问题

注意事项

• 项目处于 Alpha 阶段，核心内核可用但 API 不稳定，不建议用于生产环境。
• 官方同时使用 OAK（Open Agent Kernel）这一名称，README 中两者指同一项目。
• 本地推理需自行安装 llama.cpp 并准备 GGUF 模型文件，仓库不附带模型。
• 命令中的端口 8080 与模型名 your-model.gguf 为示例值，请按实际环境替换。