跳转到主要内容

​
前置条件

开始搭建开发环境前，请确保你已安装：

Python 3.12+

运行应用程序所需

Node.js 18+

图表渲染和服务器端渲染 (SSR) 所需

Docker & Docker Compose

用于运行 PostgreSQL 和 Redis

系统构建工具

gcc, gfortran 以及科学计算库

Git

用于版本控制

代码编辑器

VS Code, PyCharm 或你偏好的 IDE

​
快速搭建

1

克隆仓库

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

安装系统依赖

xcode-select --install
brew install gcc gfortran fftw hdf5 openblas lapack
3

创建虚拟环境

python3.12 -m venv .venv
source .venv/bin/activate  # Windows 用户: .venv\Scripts\activate
4

安装 Python 依赖

pip install mirobody -r requirements.txt
mirobody 包包含核心实用程序。使用 -e . 进行开发模式安装是可选的。
5

安装 Node.js 依赖

npm install @antv/gpt-vis-ssr ws
图表渲染服务所需。
6

启动后台服务

docker-compose up -d postgres redis
你也可以使用自己现有的 PostgreSQL 和 Redis 实例。
7

配置环境变量

cp .env.example .env
cp config.yaml config.localdb.yaml
编辑 .env：
ENV=localdb
根据你的环境编辑 config.localdb.yaml：
# 至少需要一个 LLM API 密钥
GOOGLE_API_KEY: ''
OPENAI_API_KEY: ''
OPENROUTER_API_KEY: ''

# 数据库设置
PG_HOST: 'localhost'
PG_PORT: 5432
PG_USER: 'holistic_user'
PG_PASSWORD: 'holistic_password'
PG_DBNAME: 'holistic_db'
PG_SCHEMA: 'theta_ai'

# Redis 设置
REDIS_HOST: 'localhost'
REDIS_PORT: 6379
REDIS_DB: 0
REDIS_PASSWORD: ''

# MCP 和 Agent 目录
MCP_TOOL_DIRS:
  - mirobody/pub/tools
  - mirobody/pub/tools_health

MCP_RESOURCE_DIRS:
  - mirobody/pub/resources

AGENT_DIRS:
  - mirobody/pub/agents
8

运行应用

python main.py
服务器应在 http://localhost:18080 启动。
如果使用 WSL 运行，可以通过 Windows 浏览器访问 http://localhost:18080。

​
开发工具

​
推荐的 VS Code 扩展

.vscode/extensions.json
{
  "recommendations": [
    "ms-python.python",
    "ms-python.vscode-pylance",
    "ms-python.black-formatter",
    "charliermarsh.ruff",
    "tamasfe.even-better-toml",
    "redhat.vscode-yaml"
  ]
}

​
代码格式化

# 安装开发依赖
pip install black ruff pytest pytest-asyncio

# 格式化代码
black .

# 代码检查 (Lint)
ruff check .

​
运行测试

# 运行所有测试
pytest

# 运行并生成覆盖率报告
pytest --cov=connect --cov-report=html

# 运行特定的测试文件
pytest tests/test_provider_garmin.py

# 运行集成测试
pytest -m integration

​
项目结构

mirobody-health/
├── mirobody/                # 主应用程序包
│   ├── chat/               # 聊天和 Agent 服务
│   │   ├── adapters/      # 协议适配器 (HTTP, WebSocket)
│   │   ├── agent.py       # Agent 注册和加载
│   │   ├── service.py     # 聊天服务路由
│   │   └── unified_chat_service.py  # 核心聊天逻辑
│   ├── mcp/                # MCP 协议实现
│   │   ├── service.py     # JSON-RPC 处理器
│   │   ├── tool.py        # 工具加载和执行
│   │   └── resource.py    # 资源管理
│   ├── pulse/              # 健康数据平台
│   │   ├── theta/         # OAuth 提供商 (Garmin, Whoop 等)
│   │   ├── apple/         # Apple 健康平台
│   │   ├── core/          # 核心健康服务
│   │   ├── file_parser/   # 文件解析处理器
│   │   └── router/        # API 路由
│   ├── pub/                # 公共工具和 Agent
│   │   ├── tools/         # 通用 MCP 工具
│   │   ├── tools_health/  # 健康相关 MCP 工具
│   │   ├── resources/     # MCP 资源
│   │   └── agents/        # Agent 实现
│   ├── server/             # HTTP 服务器
│   ├── user/               # 身份验证
│   └── utils/              # 实用工具
├── database/               # 数据库架构和迁移
│   └── resource/          # SQL 初始化文件
├── compose.yaml           # Docker Compose 配置
├── config.yaml            # 基础配置 (不可修改)
├── config.localdb.yaml    # 你的环境配置
├── .env                   # 环境变量
├── main.py                # 应用程序入口
├── requirements.txt       # Python 依赖
├── package.json           # Node.js 依赖
└── run.sh                 # 部署脚本

​
核心目录

包含 Agent 编排、消息历史记录以及 HTTP (SSE) 和 WebSocket 协议适配器的聊天服务。
MCP 协议实现，包含 JSON-RPC 2.0 处理器、工具/资源加载和身份验证。
健康数据平台，包含 OAuth 提供商、Apple 健康集成、文件处理和数据聚合。
可通过 MCP 发现的公共工具、资源和 Agent。在此处添加自定义工具。

​
下一步

参与贡献

了解如何为项目做出贡献

测试指南

为你的代码编写测试

Provider 集成

添加新的 Provider 集成

部署指南

部署你的改动