开始使用

安装指南

安装 Mirobody Python 引擎的三条路径：Docker Compose、本地 Python 环境，或 PyPI 包。

Mirobody 是一个 Python 应用：一个 Starlette/FastAPI HTTP 服务，加一个后台 worker，底下是 PostgreSQL（带 pgvector）和 Redis。安装它有三条路径。

Docker Compose

一条命令，四个容器。快速开始走的就是这条路。

本地 Python

从源码运行引擎，数据库和缓存仍留在 Docker 里。

PyPI 包

pip install mirobody，把它嵌进你自己的服务。

前置条件

要求	用在哪	说明
Python ≥ 3.12	本地开发、PyPI 包	`requires-python = ">=3.12"`。Docker 镜像自带解释器。
Docker + Docker Compose	三条路径都要	就算走本地 Python 那条，PostgreSQL 和 Redis 也仍然运行在 Docker 里。
Git + Git LFS	克隆仓库	`mirobody/res/` 下的术语包与指标资源是 LFS 对象。克隆之前先运行一次 `git lfs install`。

Docker Compose

git lfs install
git clone https://github.com/thetahealth/mirobody.git
cd mirobody
./deploy.sh

deploy.sh 做四件事，每件都是幂等的：已经存在的文件、没有变过的镜像，都不会被动：

创建 .env

写入 ENV（默认 localdb）和一个生成出来的 32 字符 CONFIG_ENCRYPTION_KEY。

创建 config.{env}.yaml

预置一个随机 JWT_KEY、演示登录验证码，以及 LLM key 和 MCP_PUBLIC_URL 的注释占位。

构建镜像

一个内联 Dockerfile，基于 ubuntu:24.04，内含 Python 虚拟环境（仓库里没有 Dockerfile，也没有 Node.js：引擎运行期不依赖任何 JavaScript）。如果 hub.docker.com 不通，镜像改从 docker.1ms.run 镜像源拉。

启动整套服务

先把上一套停掉、腾出 18080 / 18082 / 18089 三个端口，然后 docker compose up -d --remove-orphans，并在前台跟踪日志。

四个服务会起来，定义在 compose.yaml 里：

服务	镜像	宿主端口	角色
`pg`	`pgvector/pgvector:pg17-trixie`	18082 → 5432	带 pgvector 的 PostgreSQL
`redis`	`redis:7.0-alpine`	18089 → 6379	缓存与任务队列
`mirobody`	本地构建	18080	HTTP 服务：`python -m mirobody serve`
`mirobody_worker`	同一个镜像	—	后台任务：`python -m mirobody worker`

这些容器运行在一个固定的桥接网络 10.108.0.0/24 上，这也是 config.yaml 里预置 PG_HOST: 10.108.0.2 和 REDIS_HOST: 10.108.0.9 的原因。仓库本身以 bind mount 挂进容器的 /app，所以在宿主机上改一个 .py 文件或 config.{env}.yaml、再重启容器就够了，不需要重新构建。

docker compose ps                                  # 现在运行着什么
docker compose logs -f mirobody                    # 服务日志
docker compose restart mirobody mirobody_worker    # 让配置改动生效
docker compose down                                # 全部停掉

首次对着一个空库启动时，服务会自己建好 schema 并执行 mirobody/schema/ 下的 SQL，没有单独的迁移步骤。

本地 Python 开发

从源码运行引擎，PostgreSQL 和 Redis 仍留在 Docker 里。

启动依赖的后端服务

docker compose up -d pg redis

创建虚拟环境并安装

python3 -m venv venv
source venv/bin/activate          # Windows 下：venv\Scripts\activate

pip install --upgrade pip
pip install -e '.[agents]'     # 只要引擎：pip install -e .

pip install -e . 装到的是引擎，也就是作为库的 ① 采集与 ② 标准化。对话服务、MCP 端点与两个 agent 在 [agents] extra 里，它会把 [server] 一起带上。见引擎即库。

写好 .env

ENV 必须设置，服务启动时靠它挑配置文件。

echo "ENV=localdb" > .env
echo "CONFIG_ENCRYPTION_KEY=$(openssl rand -hex 16)" >> .env

把配置指向发布出来的端口

config.yaml 里的默认值是 compose 网络上的容器地址。运行在宿主机上的进程要走发布出来的端口去访问同一批服务，而且它自己也需要一个端口：在 Docker 之外，HTTP_PORT 会回退到 80。

HTTP_PORT: 18080

PG_HOST: 127.0.0.1
PG_PORT: 18082

REDIS_HOST: 127.0.0.1
REDIS_PORT: 18089

运行

mirobody serve          # HTTP 服务
mirobody worker         # 后台 worker，另开一个终端

python -m mirobody serve 是同一件事，容器里运行的就是它。

两条命令都把配置文件名当参数收；一个都不给时，回退到工作目录下的 config.yaml 加 config.{env}.yaml。未安装 [agents] extra 时，它们会打印一行「该装什么」就退出，而不是在 import 链深处抛 ModuleNotFoundError。

可选 extras

Extra	安装	带进来什么
`server`	`pip install -e ".[server]"`	FastAPI、uvicorn、`psycopg`、SQLAlchemy、Redis、aioboto3、WebAuthn、邮件，也就是 HTTP 面
`agents`	`pip install -e ".[agents]"`	`[server]` 再加 LangChain、deepagents、`langchain-quickjs`、LangGraph 的 Postgres checkpointer
`cn`	`pip install -e ".[cn]"`	阿里云 OSS（`oss2`）与火山引擎 Ark SDK
`test`	`pip install -e ".[test]"`	`pytest`、`pytest-asyncio`、`pytest-sugar`、`import-linter`，见开发环境搭建
`indicator-build`	`pip install -e ".[indicator-build]"`	重建术语包本身；只用这些包的人一样都不需要

PyPI 包

引擎以 mirobody 的名字发布在 PyPI 上：

pip install mirobody

这样获得的是可导入的包，不是仓库。compose.yaml 和 config.yaml 模板都在仓库根目录，不随 wheel 分发，所以配置文件要你自己在工作目录里备好。wheel 里确实带了命令行（mirobody serve）；而当你想把自己的 router 和内置路由挂在一起时，Server.start 也在：

import asyncio
from mirobody.server import Server

async def main():
    # 你自己的 FastAPI router 可以和内置路由挂在一起。
    await Server.start(yaml_files=["config.yaml"], fastapi_routers=[])

asyncio.run(main())

worker 是同样的形状，from mirobody.server import Worker 加 Worker.start(...)。不论启动哪一个，ENV 都仍然必须先在环境变量里。

仓库结构

包的结构就是那三个步骤，加上支撑它们的基础设施。

mirobody/ 仓库根目录

mirobody/ 可安装的包

engine.py 公开 API：resolve() 离线解析，parse_file() 一次调用

cli.py mirobody parse | resolve | serve | worker

pulse/ ① 采集 —— 所有信号，一个入口

providers/ mirobody_garmin_connect · mirobody_oura · mirobody_whoop · mirobody_pgsql · platform/

apple/ 端上批量样本导入（样本批次 + CDA）

file_parser/ pdf · 图片 · excel · csv · 音频 · 基因 · 文本

ingest/ StandardPulseData —— 通用交换格式

standardize/ 标准指标目录与单位

aggregate/ 按天聚合

insight/ AI 洞察，会回写进记录

gate_tests/ 每家厂商载荷一份快照

indicator/ ② 标准化 —— 概念图、解析、UCUM、分类体系

agent/ ③ 问答 —— 所有对话相关的部分

deep_agent.py DeepAgent：tool loop 在这边运行

base_agent.py BaseAgent：由服务商运行，走 /mcp

chat/ 会话 · 消息 · 历史 · 分享 · 画像

tools/ MCP 工具面

skills/ Agent Skills（SKILL.md）

prompts/ Jinja 系统提示词

resources/ MCP UI 组件

server/ HTTP 生命周期与 FastAPI 路由（server/routers/）

mcp/ MCP JSON-RPC 服务；工具与资源的发现

task/ 后台 worker（指标同步、画像刷新）

user/ 账号、认证、关爱圈授权

utils/ 配置、LLM 客户端、db、locales —— 叶子，不 import 其上层的任何模块

schema/ 首次启动时执行的 SQL

res/ 随包分发的术语包（Git LFS）

frontend/ 自带的 Web 客户端，固定构建产物，在包之外

examples/ 五个可直接运行的脚本，01 到 05

docs/ 长文指南（不随 wheel 分发）

config.yaml 设置模板 —— 不要改

compose.yaml pg · redis · mirobody · mirobody_worker

deploy.sh 一条命令完成 Docker 部署

pyproject.toml 包元数据、extras，以及 import-linter 契约

包的结构就是那三个步骤，加上支撑它们的基础设施。

验证安装

健康检查

curl http://localhost:18080/api/health

返回一段 JSON：服务名与版本号，加上启动时发现的工具、资源和 agent 的数量。

MCP 发现

curl -X POST http://localhost:18080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

列出已注册的工具及其 JSON schema。

日志

Docker 下用 docker compose logs -f mirobody。从源码运行时日志输出到控制台；设置 LOG_NAME 和 LOG_DIR 可以改成写文件。

故障排查

启动时在 mirobody/res/ 下的某个资源文件上失败

克隆时未安装 Git LFS，或者没初始化，那些文件获得的是文本指针。在仓库里运行 git lfs install，然后 git lfs pull。

18080、18082 或 18089 端口已被占用

deploy.sh 启动前会停掉发布这些端口的容器，但占着端口的非 Docker 进程它动不了。腾出端口，或者改 compose.yaml 里的映射和 HTTP_PORT。

从源码运行，服务监听在 80 端口

config.yaml 里的 HTTP_PORT 是注释掉的，回退值就是 80。走 Docker 那条路时它由容器环境变量给出；从源码运行就要自己在 config.{env}.yaml 里设 HTTP_PORT。

本地 Python 运行起来后数据库连接被拒

PG_HOST: 10.108.0.2 和 REDIS_HOST: 10.108.0.9 是 compose 桥接网络上的地址。从宿主机访问要用 127.0.0.1 加发布出来的 18082、18089 端口。

ENV 没有设置

服务启动时读 ENV 来选择 config.{env}.yaml。deploy.sh 会把它写进 .env；如果你是从源码或 PyPI 包运行的，就要自己建这个文件，或者自己导出这个环境变量。

下一步

配置

三层配置、哪些值会被加密，以及各组配置键。

快速开始

从克隆到登录进去的最短路径。

架构概览

上面这些部件在运行时是怎么拼起来的。

开发环境搭建

动手改引擎本身。