安装

Marivo 需要 Python 3.10 或更高版本。

选择安装方式

下面两种方式选一种即可。安装脚本适合希望尽快开始的用户；手动安装适合需要自行管理 Python 环境和数据源依赖的项目。

方式一：使用安装脚本

先进入要作为 Marivo 项目的目录，然后运行：

curl -fsSL https://marivo.io/install.sh | bash

脚本会先确保已安装 uv，再用它安装受管的 Python 3.10 并创建或复用 .venv，随后安装 marivo[duckdb,trino,clickhouse] 并运行 marivo init。它支持 macOS、Linux、WSL，以及窗口上的 Git Bash、MSYS2 或 Cygwin；默认不包含 MySQL，需在准备好本机 client 前置依赖后再手动安装 marivo[mysql]。仅当需要安装 uv 时才需要 PowerShell。完成后直接跳到确认安装结果，不要再执行下面的手动安装步骤。

方式二：手动安装

如果需要自行控制虚拟环境和数据源后端，请按顺序完成以下步骤。

使用 uv 创建并激活 Python 3.10 或更高版本的虚拟环境：

uv venv --python 3.10 --seed
source .venv/bin/activate

在窗口 Bash shell 中，请使用 source .venv/Scripts/activate 激活环境。

安装项目所用数据源后端对应的扩展：

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

确认安装的版本：

marivo --version

可选：固化项目配置并安装智能体技能链接：

marivo init

如果当前工作目录不是项目根目录，可以使用 marivo init --project-root <项目目录>。

Marivo 运行不依赖这个命令。未执行时，当前目录是默认项目根，项目名默认使用目录名，外部语义层路径默认为空，本地遥测默认为 on；authoring 和运行操作会按需创建所需的 models/ 与 .marivo/ 子目录。

marivo init 是幂等的：已存在的文件不会被改动，并会报告为已跳过，因此可以在升级后安全地重复运行。重复运行只会补齐缺失的内容。使用 marivo init --force 会删除生成的工件并从头重建。

智能体可以使用什么

路径	用途
`marivo.toml`	可选的项目清单，用于覆盖默认配置。
`models/`	数据源和语义声明，首次编写时创建。
`.marivo/`	项目本地的会话、证据、遥测和缓存元数据，首次写入状态时创建。
`.agents/skills/`	为兼容的智能体提供 `marivo-semantic` 和 `marivo-analysis` 技能链接。
`.claude/skills/`	为 Claude 代码提供同一组技能链接。
`.codex/skills/`	为 Codex 提供同一组技能链接。

执行 marivo init 后，可选脚手架如下：

your-project/
  marivo.toml
  models/
  .marivo/
  .agents/skills/
  .claude/skills/
  .codex/skills/

确认安装结果

安装完成后，可以向智能体提出下面这项有明确边界的准备请求：

检查这个 Marivo 项目的有效配置，并告诉我开始使用现有语义层或新建语义层之前还缺少什么。凭据只检查环境变量名和配置状态，不要索取、显示或提交凭据值。

这样可以把项目准备、读取业务数据和决定业务含义分成不同的步骤。

如果智能体由其他运行时启动，优先使用该运行时选定的项目解释器。对于常规的项目本地安装， macOS、Linux 和 WSL 优先使用 .venv/bin/python，Windows 优先使用 .venv/Scripts/python.exe。使用选定的解释器运行 <selected-python> -m marivo doctor，并继续用于后续 help 和执行。

继续之前需要检查什么

继续之前，请确认：

已选择预期的 Doctor 项目根；--project-root 优先于 MARIVO_PROJECT_ROOT，两者都没有时， Doctor 直接使用当前目录，不搜索祖先 manifest；
已存在的 marivo.toml 有效；缺少 manifest 时使用默认配置；
所选宿主依赖文件系统技能发现时，所需技能路径可用；需要时运行 marivo init 安装；
项目需要的数据源后端扩展已经安装；
凭据通过经过批准、由环境变量提供的字段传入，而不是以明文形式提交到项目文件中。

完成这些检查后，进入快速开始，选择复用现有语义层，还是创建新语义层。所选项目路径准备就绪且业务含义得到确认后，再进行第一次分析。

即使 marivo.toml、models/ 和 .marivo/ 都不存在，项目也是有效的空起点。Doctor 会把有效默认配置、缺少声明目录和尚无状态分别显示为 informational 或 skipped，且不会创建本地状态或遥测；显式非法配置、layer path、后端和凭据等真实问题仍会保留为诊断 failure 或 warning。