从源码构建

完整的源码构建指南。

前置条件

所有平台

• Git — 版本控制
• CMake — 构建系统（3.15+）
• C++17 编译器 — GCC 7+、Clang 5+ 或 MSVC 2019+
• Node.js — 16+（插件系统需要）

Linux（Ubuntu / Debian）

sudo apt-get install -y \
  build-essential \
  cmake \
  git \
  libssl-dev \
  libcurl4-openssl-dev \
  nlohmann-json3-dev \
  libspdlog-dev \
  zlib1g-dev

macOS

# 受支持的 macOS 构建流依赖这些 Homebrew 包
brew install cmake ninja pkg-config git spdlog openssl@3 curl node

Windows（MSVC）

• Visual Studio 2019+ 或 Build Tools for Visual Studio
• CMake 3.15+
• Git for Windows

说明： 构建系统会自动定义 NOMINMAX（防止 Windows API 宏与 std::min/std::max 冲突），并自动链接 bcrypt 等用于 Windows 上 TLS/加密功能的系统库（例如与 mbedtls/OpenSSL 集成）。无需手动配置。

克隆仓库

git clone https://github.com/QuantClaw/QuantClaw.git
cd QuantClaw

# 可选：切换到指定版本
git checkout v0.3.0-alpha

构建步骤

Linux / macOS

mkdir build && cd build

# 标准构建
cmake ..
cmake --build . --parallel

# Debug 构建
cmake .. -DCMAKE_BUILD_TYPE=Debug
cmake --build . --parallel

# 指定编译器
cmake .. -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++
cmake --build . --parallel

在 macOS 上更推荐 ./scripts/build.sh。它会自动补齐缺失的 Homebrew 依赖，并把 OpenSSL / curl 的 Homebrew 前缀传给 CMake。

使用 build.sh（推荐）

项目提供了智能构建脚本：

# 标准构建
./scripts/build.sh

# Debug 构建
./scripts/build.sh --debug

# 构建并运行测试
./scripts/build.sh --tests

# 清理后重新构建
./scripts/build.sh -c

# 启用 AddressSanitizer
./scripts/build.sh --asan

Windows（MSVC）

mkdir build
cd build

REM 生成 Visual Studio 项目
cmake .. -G "Visual Studio 17 2022"

REM 编译 Release 版本
cmake --build . --config Release -j %NUMBER_OF_PROCESSORS%

vcpkg 依赖：

vcpkg install nlohmann-json openssl spdlog zlib
cmake .. -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake

运行测试

cd build

# 运行所有测试
./quantclaw_tests

# 通过 ctest 运行
ctest --output-on-failure

# 运行指定测试套件
./quantclaw_tests --gtest_filter=AgentLoopTest.*
./quantclaw_tests --gtest_filter=ConfigTest.*

构建 Docker 镜像

VERSION=$(cat scripts/DOCKER_VERSION)

# 生产镜像（三阶段构建）
docker build \
  -f scripts/Dockerfile \
  --build-arg VERSION=$VERSION \
  --build-arg BUILD_DATE=$(date -u +%Y-%m-%dT%H:%M:%SZ) \
  --build-arg VCS_REF=$(git rev-parse --short HEAD) \
  -t quantclaw:$VERSION \
  -t quantclaw:latest \
  .

# 测试镜像
docker build -f scripts/Dockerfile.test -t quantclaw-test:$VERSION .

# 开发镜像（含 gdb/valgrind）
docker build -f scripts/Dockerfile.dev -t quantclaw-dev:$VERSION .

安装

# 安装到系统（/usr/local/bin）
sudo cmake --install build/

# 或从 build 目录
cd build && sudo cmake --install .

代码格式化

# 格式化所有 C++ 源文件
./scripts/format-code.sh

# Dry-run（CI 使用）
./scripts/format-code.sh --check

# 在 Docker 中格式化（无需本地 clang-format）
./scripts/format-code-docker.sh

持续集成

CI 配置位于 .github/workflows/github-actions.yml，在每次 PR 时自动运行：

• C++ 代码格式检查（clang-format）
• 完整 C++ 测试套件（1009 项测试）
• Sidecar TypeScript 测试

故障排除

CMake 找不到依赖

cmake .. -DCMAKE_VERBOSE_MAKEFILE=ON

链接错误（OpenSSL）

# Ubuntu
sudo apt-get install libssl-dev

# macOS
brew install openssl@3 curl
cmake .. -DOPENSSL_ROOT_DIR="$(brew --prefix openssl@3)"

编译器版本过低

# 安装 GCC 11
sudo apt-get install gcc-11 g++-11
cmake .. -DCMAKE_C_COMPILER=gcc-11 -DCMAKE_CXX_COMPILER=g++-11

ZLIB / httplib 压缩链接错误

如果系统在某些环境下有 ZLIB 但在其他环境（如最小化 Docker 镜像或 CI）下没有，CMake 可能缓存了旧的 HTTPLIB_REQUIRE_ZLIB=ON。构建系统现在在找不到 ZLIB 时会显式将其强制设为 OFF，但若仍遇到 z 或 zlib 相关链接错误，请清除 CMake 缓存后重新配置：

# Linux/macOS
rm -rf build && mkdir build && cd build
cmake ..

# Windows (PowerShell)
Remove-Item -Recurse -Force build; mkdir build; cd build
cmake ..

# Windows (cmd)
rmdir /s /q build && mkdir build && cd build && cmake ..

---

下一步：参与贡献 或查看 CLI 参考。