跳转到主要内容
Mirobody 是一个 C++11 代码库，用 CMake 和 Ninja 构建（Windows 上加 vcpkg）。在它上面做开发，意味着安装原生工具链、构建 mirobody 目标、运行 Catch2 测试套件。

​
前置条件

C++11 工具链

GCC ≥ 4.8.1 / Clang ≥ 3.3 / Apple Clang / MSVC 2017+

CMake + Ninja

CMake 和 Ninja 生成器

原生库

libwebsockets、libcurl、OpenSSL、rapidjson、yaml-cpp、hiredis、图像编解码器

一个数据库客户端

默认 PostgreSQL 后端用 libpq（或 SQLite 客户端）

Git

用于版本控制

Catch2 v3

用于单元测试套件（find_package(Catch2 3)）

​
搭建

1

克隆仓库

git clone https://github.com/thetahealth/mirobody.git
cd mirobody
2

安装原生依赖

vcpkg 仅用于 Windows；Linux 和 macOS 用系统包管理器。
sudo apt install build-essential cmake ninja-build pkg-config \
                 libwebsockets-dev libcurl4-openssl-dev libssl-dev \
                 rapidjson-dev libyaml-cpp-dev libhiredis-dev libpq-dev \
                 libjpeg-dev libpng-dev libtiff-dev libwebp-dev

# 测试套件所需的 Catch2 v3
sudo apt install catch2
在 Windows 上，安装 Visual Studio（使用 C++ 的桌面开发 + C++ CMake 工具）。vcpkg 会自动从 vcpkg.json 拉取每一个依赖 —— 包括 Catch2。参见 安装指南。
3

构建

build.sh 包装脚本会配置（Release、PostgreSQL 后端、测试默认开启）并构建：
./build.sh              # -> build/mirobody  和  build/tests/mirobody_tests
用一个 token（sqlite、legacy、mysql、duckdb、ck）选择其他 SQL 后端；每个后端有各自的 build[_<backend>] 目录，因此多个可以共存：
./build.sh sqlite       # -> build_sqlite/
./build.sh clean        # 清空并重新配置
或者直接驱动 CMake 以获得更精细的控制（Debug 构建、额外标志）：
cmake -S . -B build -G Ninja \
    -DCMAKE_BUILD_TYPE=Debug \
    -DMIROBODY_DATABASE_BACKEND=POSTGRESQL
cmake --build build
4

配置并运行

cp config.example.yml config.yml
在 config.yml 里设置一个 LLM 密钥（以及默认后端所需的 PG_* 连接），然后运行：
./mirobody --config config.yml
服务器在 http://localhost:8080 启动。完整键列表见 配置。
要一个无需外部数据库的零依赖开发循环，构建 SQLite 后端（./build.sh sqlite）并运行 ./build_sqlite/mirobody。

​
常用 CMake 选项

选项默认用途
MIROBODY_DATABASE_BACKENDPOSTGRESQL链接哪个 SQL 后端（SQLITE、MYSQL、DUCKDB、CLICKHOUSE、POSTGRESQL_LEGACY）
MIROBODY_BUILD_TESTSON构建 Catch2 测试套件
MIROBODY_BUILD_TOOLSON构建 cli/ 调试二进制
MIROBODY_ENABLE_PDFOFF经 PDFium 的 PDF 文本抽取
MIROBODY_ENABLE_OCROFF经 Tesseract 的 OCR（隐含 PDF）
MIROBODY_ENABLE_XLSOFF经 libxls 的旧版 .xls
MIROBODY_BUILD_SHARED / _PYTHON / _JNI视情况构建共享库 / Python wheel / JNI shim，替代（或并列于）二进制

​
运行测试

测试是一个 Catch2 可执行文件（mirobody_tests），经 catch_discover_tests 注册到 CTest。 
# 构建（测试默认开启）
./build.sh

# 经 CTest 运行
ctest --test-dir build --output-on-failure

# 或直接运行二进制（Catch2 过滤器 / 标签）
./build/tests/mirobody_tests
./build/tests/mirobody_tests "[fhir]"      # 仅 fhir 测试
./build/tests/mirobody_tests --list-tests
测试源码位于 tests/ 下（chat/、fhir/、circle/、jwt/、cache/ 等子目录，外加一个 e2e/ 套件）。

​
调试 CLI

桌面构建会在 cli/ 下产出独立的各子系统 CLI（用 -DMIROBODY_BUILD_TOOLS=OFF 切换），它们绕过 HTTP/WS 服务器 —— 便于单独把玩某一个部分：
  • LLM 客户端 —— openai_chat、openai_responses、openai_realtime、gemini、gemini_live、mirothinker
  • 存储 —— aws_s3、aliyun_oss、azure_blob
  • 转码器 —— image、document、file_parser
  • FHIR —— fhir normalize "<5.6 mg/dL"，以及 fhir token <user_id> --config <yaml> 为 FHIR 路由铸出一个 bearer JWT
  • 鉴权 —— jwt_keygen（RS256 / JWKS 的 RSA 密钥对）、google_jwt、firebase_jwt
  • 其他 —— mcp、agent、vendor
各二进制的标志和凭据见仓库中的 cli/README.md。

​
新增一个 Agent 或 MCP 工具

两者都在编译期自注册 —— 没有运行时插件目录：
  • Agent —— 唯一的 agent 是 res/agents/base.cpp。res/agents/ 下的每个 .cpp 都会被 glob 进构建。
  • MCP 工具 —— 在 res/mcp_tools/ 里丢一个 .cpp，用一行 MIROBODY_REGISTER_TOOL(...) 声明它的参数表，然后重新构建。最小示例见 res/mcp_tools/echo.cpp 和 新增工具。
# 在 res/ 下加完文件后，重新构建即可
./build.sh

​
项目结构

mirobody/
├── src/            # C++ 内核（server、chat、llm、mcp、fhir、health/vendor、database、storage…）
│   ├── mirobody.h  # 公开 C ABI
│   └── main.cpp    # 独立服务器入口
├── res/            # 编译/托管的资源：agents/、mcp_tools/、mcp_resources/、sql/、htdoc/
├── tests/          # Catch2 单元测试（build/tests/mirobody_tests）
├── cli/            # 独立的各子系统调试二进制
├── htdoc/          # Web 客户端源码（webpack -> res/htdoc）
├── bindings/       # Java / Go / C# / Node / Rust FFI 示例
├── android/  ios/  electron/  qt/  miniapp/   # 宿主应用 / 客户端
├── CMakeLists.txt  build.sh  build.cmd
└── config.example.yml
完整目录树以及其他构建工件见 安装指南 → 仓库结构。

​
下一步

参与贡献

如何提交变更

测试

编写并运行测试

Provider 集成

接入新的健康数据源

部署

发布你的构建