安装

Marivo 需要 Python 3.12 或更高版本。

从 PyPI 安装基础库：

pip install marivo

根据要连接的数据源安装后端扩展：

后端	安装命令
DuckDB	`pip install "marivo[duckdb]"`
MySQL	`pip install "marivo[mysql]"`
Postgres	`pip install "marivo[postgres]"`
ClickHouse	`pip install "marivo[clickhouse]"`
Trino	`pip install "marivo[trino]"`
所有已打包的后端	`pip install "marivo[all]"`

初始化一个项目

用 CLI 在当前目录中初始化一个新项目：

marivo --version
marivo init

marivo init 会创建项目骨架，并安装 Marivo 的智能体技能：

路径	用途
`marivo.toml`	项目 manifest。项目名默认使用目录名；本地遥测默认 `enabled = "on"`。
`models/`	编写数据源与语义声明的位置。
`.marivo/`	项目本地状态：会话、证据以及缓存的元数据。
`.agents/skills/marivo-semantic`、`.agents/skills/marivo-analysis`	面向读取 `.agents/skills` 的智能体的通用 Marivo 技能入口。
`.claude/skills/marivo-semantic`、`.claude/skills/marivo-analysis`	面向 Claude 代码的 Marivo 技能（以符号链接接入项目）。
`.codex/skills/marivo-semantic`、`.codex/skills/marivo-analysis`	面向 Codex 的兼容技能入口。

init 是幂等的：已存在的文件不会被改动，并会报告为已跳过。因此可以安全地重复运行，例如在升级到附带新版技能的 Marivo 之后。重复运行只会补齐缺失的部分。使用 marivo init --force 可删除上述工件并从头重建。

初始化完成后，会得到一个可以直接开始编写的项目：

your-project/
  marivo.toml
  models/
  .marivo/
  .agents/skills/  # marivo-semantic, marivo-analysis
  .claude/skills/   # marivo-semantic, marivo-analysis
  .codex/skills/    # marivo-semantic, marivo-analysis

如果语义层对象由其他仓库维护，可以把这些仓库中的已编写 models/ 目录加入 marivo.toml：

[semantic]
layer_paths = [
  "../sales-domain/models",
  "/opt/company/finance-domain/models",
]

当前项目的 models/ 会始终优先加载。相对路径按 marivo.toml 所在目录解析；绝对路径按原样使用。每个外部 models/ 根都必须同时包含 datasources/ 与 semantic/。所有根中的数据源名称、领域名称与语义 ID 必须全局唯一；出现重复将导致加载失败。marivo doctor、语义预览、对象验证与分析会话在解析语义对象时会使用这些配置层中的数据源。

把 .marivo/ 加入 .gitignore；对 marivo.toml 和 models/ 做版本控制（参见快速开始）。

本地使用遥测

Marivo 会在项目状态目录下写入 OpenTelemetry 形态的本地 JSONL 使用事件：

.marivo/telemetry/events.jsonl

遥测只保存在本地：Marivo 不会上传这些事件。事件覆盖 marivo init、分析意图、 discover/变换辅助函数，以及 escape-hatch promotions。记录只包含低基数字段，例如事件名称、意图家族、状态、duration、错误 class 和分析会话 id。它不会包含 SQL 文本、数据源 hosts、credentials、指标 ids、维度 ids、会话名称、会话问题或 frame 数据。

可以通过环境变量在当前进程中关闭本地遥测：

MARIVO_TELEMETRY=off marivo init

也可以在 marivo.toml 中配置项目默认值：

[telemetry]
enabled = "off" # "on" 或 "off"

MARIVO_TELEMETRY=on|off 会覆盖当前进程中的项目配置。如果两者都没有设置，本地遥测默认使用 "on"。

部署与开发

Marivo 是 Python 库，不是托管服务。部署 Marivo 项目时，需要在智能体的运行环境中安装库，提交数据源和语义声明，并通过 *_env 字段引用环境变量来提供数据源密钥。

从当前仓库进行本地开发：

python3 -m venv .venv
.venv/bin/pip install -e ".[dev,duckdb,trino]"
.venv/bin/python -c "import marivo; print(marivo.__name__)"