第 00 步：安装与准备¶

这一节学什么¶

第一次使用 jianmu 前需要准备什么
Python 环境应该怎么建
从仓库运行和普通安装有什么区别
最小 .env 应该怎么写
第一个示例应该怎么跑
跑不起来时先检查什么

这一节先不讲完整配置系统¶

第一步的目标只有一个：

先把环境准备好，尽快跑通第一个例子

这里先不展开 jianmu.yaml、jianmu/config、provider 自动选择规则这些更系统的话题。那些内容放到后面的 configuration 步骤再讲。

先准备什么¶

Python 3.10+
一个可用的大模型服务
项目根目录下的 .env
可选 jianmu.yaml

先准备 Python 环境¶

jianmu 当前要求：

Python 3.10+

如果你只是想跑 Getting Started，我建议先单独建一个干净环境。

例如用 conda：

conda create -n jianmu python=3.10
conda activate jianmu

或者用 venv：

python -m venv .venv
source .venv/bin/activate

关键不是一定用哪种工具，而是：

不要直接把依赖装进一个杂乱的全局 Python 环境
先保证你运行 Getting Started 的解释器是明确且隔离的

安装方式怎么选¶

这里有两条常见路径。

路径 A：直接安装已发布包¶

如果你只是想体验 jianmu 的 Python API，可以先用最简单的方式：

pip install jianmu

路径 B：从仓库本地运行¶

如果你现在是在仓库里跑 docs/、examples/、apps/，更适合直接在仓库环境里安装依赖。

这个仓库当前使用 pyproject.toml 管理依赖。

一个简单做法是：

pip install -e .

如果你还要跑某些可选能力，通常还需要把对应 extras 补上：

pip install -e .[skill,tool]

这里要注意，skill 和 tool 不是“整个模块是否可用”的总开关。

它们更准确地说是两组附加依赖：

skill
主要补 SKILL.md frontmatter 解析、schema 校验这类依赖
tool
主要补 HTTP / web-search 相关工具依赖

所以不要把它理解成：

“不装 skill，整个 skill 都不能用”
“不装 tool，整个 tool 都不能用”

更准确的理解是：

基础安装先保证主路径能跑
遇到某些可选能力时，再按需补对应 extras

如果你的环境只使用 Poetry，也可以直接用 Poetry 安装项目依赖。

这一步的目标不是统一所有人的包管理习惯，而是让你先有一个能稳定运行示例的 Python 环境。

最小 `.env`¶

第一次上手最常见的是 OpenAI-compatible 路径。

最小 .env 示例：

OPENAI_API_KEY=your_api_key
BASE_URL=https://your-openai-compatible/v1
MODEL=Qwen/Qwen3.5-35B-A3B

你现在只需要先知道：

OPENAI_API_KEY：访问模型服务的密钥
BASE_URL：模型服务地址
MODEL：你准备调用的模型名

在当前框架里，MODEL 已经是一个统一的便捷默认值入口：

如果你没有在 jianmu.yaml 里显式写 models.default / react / plan_execute / evaluate
那配置加载阶段会用 MODEL 去补这些常见模型默认值

也就是说，Getting Started 阶段如果你忘了写 MODEL，框架不会立刻因为“缺少这个环境变量”报错，但会退回到项目配置或框架内建默认模型名。

如果那个默认模型和你的 provider 不匹配，才会在真正调用模型时失败。

可选的 `jianmu.yaml`¶

如果你只是先跑 Getting Started，很多时候只写 .env 就够了。

一个最小 jianmu.yaml 可以长这样：

paths:
  skills_dir: ./skills

models:
  default: Qwen/Qwen3.5-35B-A3B
  react: Qwen/Qwen3.5-35B-A3B

但这一步你不必先理解它所有字段的含义。

`.env` 应该放在哪¶

Getting Started 阶段，最稳的做法是：

因为默认的 provider 解析逻辑会先尝试从当前项目根加载 .env。

如果你明明写了 .env，但示例还是读不到：

先检查你是不是在错误的工作目录运行
再检查 .env 是否真的在项目根目录
再检查当前 shell 激活的 Python 环境是不是你刚准备的那个

如果跑不起来，先查什么¶

最先检查这几件事：

当前激活的是不是你刚准备的 Python 环境
jianmu 依赖是否已经正确安装
.env 是否放在项目根目录
OPENAI_API_KEY / BASE_URL / MODEL 是否真的有值
当前模型服务是否兼容 OpenAI chat-completions 接口

如果你能跑通下一节的最小聊天，就说明最基本的环境已经是通的。

下一步¶

step_01_minimal_chat