安装

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 init

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

路径	用途
`marivo.toml`	项目 manifest。项目名默认取目录名。
`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 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

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

部署与开发

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__)"