安装与环境

iamai 使用 uv 管理 Python 环境，并通过 maturin 构建 Rust 扩展。 这意味着开发环境需要同时具备 Python 和 Rust 工具链。

本地开发

在仓库根目录执行：

uv sync

这会安装运行时依赖、开发依赖，并构建可编辑安装的 iamai 包。

验证安装

uv run python -m iamai --config examples/echo-runtime/config.terminal.toml config-check

如果输出 ok 和插件列表，说明 Python 包、Rust 扩展和配置装配都已经可用。

文档环境

文档依赖在独立的 docs 依赖组里：

uv sync --group docs
uv run sphinx-build -b html docs docs/_build/html

CI 中会使用 -W --keep-going 构建文档。任何 Sphinx warning 都会让文档任务失败。

常见问题

ModuleNotFoundError: iamai._core

Rust 扩展没有构建或当前 Python 环境没有安装项目。重新执行 uv sync。

config-check 找不到插件

检查 plugins、plugin_dirs 和 python_paths。默认情况下路径必须位于配置根目录内。

uv 缓存目录没有权限

在受限环境中可以临时设置 UV_CACHE_DIR=/tmp/uv-cache。