贡献指南 - Mirobody

欢迎贡献者！

Mirobody 是一个用 CMake 构建的 C++11 引擎。本指南涵盖如何构建它、修改工作流以及 PR 规范。

贡献方式

新增一个 vendor

在 src/health/vendor/ 中新增一个 vendor::Vendor —— 参见 Provider 集成

新增一个 MCP 工具

在 res/mcp_tools/ 中新增一个 .cpp，使用 MIROBODY_REGISTER_TOOL 宏

修复 Bug

反馈并修复问题

完善文档

改进本文档

构建引擎

Mirobody 在 Linux / WSL / macOS 上针对系统安装的库进行构建；Windows 上使用 vcpkg。

安装依赖

Debian / Ubuntu / WSL：

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

macOS（Homebrew）：

brew install cmake ninja pkg-config libwebsockets curl openssl@3 \
  rapidjson yaml-cpp hiredis libpq jpeg-turbo libpng libtiff webp

另请为你构建的数据库后端安装对应的 -dev 包（默认是 Postgres）。完整清单见仓库 README 的 “Building” 一节。

构建

./build.sh            # host arch, PostgreSQL backend, into ./build
./mirobody            # run it (reads ./config.yml)

build.sh 可按任意顺序接收一个架构和/或后端选择器，另加 clean：

./build.sh sqlite         # SQLite backend -> ./build_sqlite
./build.sh arm64 mysql    # cross combo, its own build dir
./build.sh clean          # wipe the build dir and reconfigure

在 Windows 上，使用 build.cmd（Visual Studio + vcpkg，会自动拉取依赖）→ build\mirobody.exe。

可选特性（默认关闭）

某些能力是 CMake 选项，除非你启用，否则关闭：

cmake -DMIROBODY_ENABLE_PDF=ON -DMIROBODY_ENABLE_OCR=ON ...   # PDF (PDFium) + OCR (Tesseract)
cmake -DMIROBODY_ENABLE_XLS=ON ...                            # legacy .xls (vendored libxls)

（经 xlnt 的 .xlsx 与 CSV 在找到 xlnt 时始终构建。OCR 需要 PDF。）

其他构建产物：build-shared.sh（libmirobody C-ABI 共享库）、build-python.sh（Python wheel，经 pybind11 从源码构建），以及 Android（Gradle + NDK）/ iOS（mirobody.xcframework）目标。还有一个多阶段 Dockerfile。

修改工作流

Fork 并创建分支

git checkout -b feat/your-change

完成你的修改

遵循既有结构 —— 一个文件一个关注点，头部注释说明”为什么”。若你新增一个自注册单元（MCP 工具或 agent），把 .cpp 投放到匹配的 res/ 目录；构建会拾取它。

构建并测试

./build.sh
ctest --test-dir build            # or: ./build/tests/mirobody_tests

参见测试。

提交并推送

git add -A
git commit -m "feat: describe your change"
git push origin feat/your-change

发起 Pull Request

附上清晰的描述：它做了什么、为什么，以及如何测试。

代码规范

C++11。 与周边风格保持一致；代码库倚重标准库、rapidjson 和轻薄的内部封装（client::HttpClient、storage::*），而非重型框架。
头部注释解释意图 —— 尤其是为何某处是桩或权宜之计。新的 vendor 桩必须记录其原因（受限 / 契约不匹配 / 无此端点）。
不要捏造契约。 若某个线路格式无法公开确认，请留下一个诚实的桩（抛出带原因的 VendorError/DocumentError），而不是猜测。
为你改动的行为新增或更新测试（Catch2，位于 tests/ 下）。

Pull Request 规范

标题格式

Conventional commits：feat:、fix:、docs:、refactor:、test:、chore:。

描述内容

该 PR 做了什么、为什么
如何构建 / 测试它
链接相关 issues

Checklist

有问题？

GitHub Issues

Bug 反馈与功能请求

Mirobody 支持

直接的技术支持

感谢你的贡献！

​欢迎贡献者！

​贡献方式