内容
# roadmodel
一款根据给定提示推荐 **使用哪种人工智能模型、在哪个平台上以及采用何种设置** 的命令行工具。指向任务描述，它会返回一个包含六个字段的区块 — `模型 / 平台 / 最大模式 / 思考 / 对话 / 理由` — 基于捆绑的基准测试和定价目录（Cursor 定价、Artificial Analysis、LiveCodeBench、τ²-bench、SWE-bench、MMMU、LMArena）并根据您自己的订阅和 API 密钥进行筛选。为同时使用多个 AI 订阅（Claude Code、Cursor、Codex / ChatGPT、原始提供商 API）的开发者打造，提供确定性的答案以取代猜测。
[](https://pypi.org/project/roadmodel/)
[](https://pypi.org/project/roadmodel/)
[](LICENSE)
[](https://github.com/nathanramoscfa/roadmodel/actions/workflows/tests.yml)
[](https://github.com/nathanramoscfa/roadmodel/actions/workflows/phase-verify.yml)
## 安装
```sh
pip install roadmodel
```
Python 3.11 或更新版本。
## MCP 服务器
使用 `pip install "roadmodel[mcp]"` 安装 MCP 运行时，以启用 `roadmodel-mcp` 标准输入/输出服务器入口；普通的 `pip install roadmodel` 保持 SDK 可选，不安装 `mcp`。服务器向任何 MCP 兼容的客户端（Cursor、Claude Code、Claude Desktop、VS Code + Continue）公开三个工具 — `recommend_model`、`generate_phase_roadmap` 和 `read_catalog`。每个客户端的注册演练步骤位于 [docs/mcp-setup.md](docs/mcp-setup.md)；工具签名和返回模式在 [docs/mcp-tools.md](docs/mcp-tools.md) 中有文档记录。
## 规划工具包（$0 边际推荐）
要在另一个项目中为 **具有逐步骤模型推荐** 的项目/阶段路线图编写作者，导出 **规划工具包** 到该项目中，让编辑器中已经打开的 AI（例如，Claude Code 在空白计划上）运行选择器在其自身上下文中 — 无需每次调用 API 开支，只需您已经支付的编辑器会话。
**跨平台（推荐）。** 安装 roadmodel 后，一个命令在 Windows、macOS 或 Linux 上编写工具包 — 无需 shell 或网络：
```sh
cd /path/to/other-project
roadmodel export-kit # 写入 ./planning 包含选择器 + 成本规模 + 模板 + 使用方法 + 用户上下文
```
它使用安装的轮中捆绑的目录，因此请使用 `pip install -U roadmodel` 刷新并重新运行 `roadmodel export-kit` 在每个阶段的开始。标志：`--dest <subdir>`、`--force`（覆盖现有工具包 `user-context.md`）、`--user-context <path>`。
**Shell 替代（无安装）。** bash 脚本从此存储库的 `main` 分支获取工具包，而不是从安装的轮：
```sh
scripts/export-planning-kit.sh /path/to/other-project
```
标志：`--dest <subdir>`、`--ref <git-ref>`、`--local`（从本地检出复制而不是 GitHub）、`--user-context <path>`。在 Windows PowerShell 上，如果您手动获取文件，请调用 `curl.exe`（不是 `curl` 别名）；上面的 `export-kit` 命令完全避免了这种情况。
无论哪种方式，编辑器内的 AI 都运行算法本身，而不是调用推荐服务。当您想要在脚本或 CI 中获得确定性、结构化的建议时，请使用上面的 MCP 服务器。
## 快速入门
从全新安装到解析推荐区块的三个步骤。
**1. 为三个提供商之一导出 API 密钥。**此处显示 Anthropic；OpenAI 和 Google 的操作方法相同 — 请参阅 [docs/byo-key-setup.md](docs/byo-key-setup.md) 以获取完整指南。
```sh
export ANTHROPIC_API_KEY=sk-ant-...
```
**2. 运行 `roadmodel recommend` 一次以启动用户上下文文件。** 在第一次调用时，CLI 将捆绑模板的副本写入 `~/.config/roadmodel/user-context.md`（或 `$XDG_CONFIG_HOME/roadmodel/user-context.md` 当设置 `XDG_CONFIG_HOME` 时），打印一行标准错误通知，告诉您它做了什么，然后退出而不调用提供商。打开文件并用您的实际订阅金额和 API 密钥状态替换 `$XXX` 和 `Yes/No` 占位符。完整的字段演练步骤位于 [docs/user-context-setup.md](docs/user-context-setup.md)。
```sh
roadmodel recommend "重构 12 个文件中的身份验证中间件"
# 标准错误：已从捆绑模板创建 /home/you/.config/roadmodel/user-context.md。编辑它以获取您的实际订阅状态，然后重新运行。
$EDITOR ~/.config/roadmodel/user-context.md
```
**3. 重新运行。** 填写用户上下文后，相同的命令调用您选择的提供商并打印解析的六字段区块：
```sh
roadmodel recommend "重构 12 个文件中的身份验证中间件"
```
```
模型：claude-opus-4-7
平台：Claude Code
最大模式：开启
思考：高
对话：新建
理由：使用跨文件范围和复杂性高的编码代理基准对 Coding PRIMARY 进行编码。Opus 4.7 在编码代理基准上评级为 S 级，并且是目录中唯一评级为 S 级的长上下文召回模型。平台 Claude Code 由 claude.ai Max 资助（边际成本为 0 美元）；根据选择算法规则，对于复杂性高的编码，选择“思考高”。
```
传递 `--json` 以发出相同的字段作为机器可读的 JSON，或 `--file PATH` 从磁盘读取提示。
## 自带密钥设置
roadmodel 内部没有内置提供商密钥 — 它在每次推荐时调用 **您的** Anthropic / OpenAI / Google 帐户并为您的帐户付费。设置以下三个环境变量之一，CLI 自动选择该提供商：
| 提供商 | 环境变量 |
| --------- | ------------------- |
| Anthropic | `ANTHROPIC_API_KEY` |
| OpenAI | `OPENAI_API_KEY` |
| Google | `GOOGLE_API_KEY` |
完整指南 — 在每个提供商的控制台中生成密钥，将它们存储在 shell 配置文件或 `~/.config/roadmodel/config.toml` 中，优先级规则和验证烟雾调用 — 在 [docs/byo-key-setup.md](docs/byo-key-setup.md) 中。
## 用户上下文设置
roadmodel 读取用户特定的 Markdown 文件，描述您的活跃订阅、API 密钥、平台偏好顺序和预算状况，以便 `<access-selection>` 步骤可以选择 **平台** 和 **思考级别** 以及模型。解析的默认路径是 `~/.config/roadmodel/user-context.md`（或 `$XDG_CONFIG_HOME/roadmodel/user-context.md` 当设置 `XDG_CONFIG_HOME` 时）；使用 `--user-context PATH` 覆盖单个运行，或使用 `ROADMODEL_USER_CONTEXT=PATH` 覆盖整个 shell。完整的演练步骤 — 首次启动引导、完整优先级链、字段演练模式、何时更新 — 在 [docs/user-context-setup.md](docs/user-context-setup.md) 中。
## 子命令
| 命令 | 执行的操作 |
| -------------------------------- | ---------------------------------------------------------------------------------- |
| `roadmodel recommend PROMPT` | 为给定提示推荐一个六字段区块。 |
| `roadmodel recommend --file P` | 相同，但从文件 `P` 中读取提示文本。 |
| `roadmodel recommend --json` | 以 JSON 格式发出解析的六个字段，而不是标记文本区块。 |
| `roadmodel recommend --provider` | 覆盖哪个提供商回答（`anthropic` / `openai` / `google`）。 |
| `roadmodel recommend --model` | 覆盖所选提供商上的特定模型 ID。 |
| `roadmodel recommend --user-context PATH` | 覆盖此调用的用户上下文.md位置。 |
| `roadmodel catalog show` | 打印捆绑的 `model-selector.txt`（使用 `--doc tier-cost-scale` 获取价格文档）。 |
| `roadmodel catalog path` | 打印捆绑目录文档的磁盘路径（相同 `--doc` 标志）。 |
| `roadmodel context show` | 打印解析的用户上下文.md文件。 |
| `roadmodel context path` | 打印解析的用户上下文.md路径（或如果丢失则启动目标）。 |
| `roadmodel context init` | 从捆绑模板引导 `user-context.md`（使用 `--force` 覆盖）。 |
| `roadmodel version` | 打印已安装的版本。 |
## 工作原理
CLI 随附三个文档作为包数据：
[`model-selector.txt`](docs/model-selector.txt)（选择算法和每个模型的访问方法目录），
[`model-tier-cost-scale.md`](docs/model-tier-cost-scale.md)（每个令牌的价格和层级评级），以及
[`user-context.example.md`](docs/user-context.example.md)（用户状态模板）。在推荐时，`roadmodel recommend`
从磁盘读取您填写的 `user-context.md`，将三个文档合并成一个系统提示，并调用您配置的提供商。提供商根据 `model-selector.txt` 中的 `<output-format>` 规范返回一个 `MODEL / PLATFORM / MAX MODE / THINKING / CONVERSATION / RATIONALE` 区块。`MODEL` 通过 `<selection-algorithm>` 根据您的提示任务类别和复杂性进行选择；`PLATFORM` 和 `THINKING` 由 `<access-selection>` 步骤填充，该步骤依赖于您在 `user-context.md` 中声明的订阅和 API 密钥状态。
## 基准测试和评级
每个模型在 **S → D** 规模上具有每个类别的能力评级，推荐器根据公共基准测试（SWE-bench Verified、τ²-bench、Terminal-Bench、Humanity's Last Exam 等）为其理由提供依据。有关评级的含义和推荐器引用的每个基准测试的链接索引，请参阅 [**docs/benchmarks-and-ratings.md**](docs/benchmarks-and-ratings.md）。
## 项目状态
roadmodel 处于 **第 1 阶段** — 开源 CLI 发布。第 2 阶段在 CLI 之外添加 MCP 服务器；后续阶段在 `roadmodel.ai` 添加托管 SaaS。该项目以前名为 `model-selector`，在公开发布前更名为 `roadmodel`；捆绑文档文件的规范名称 `model-selector.txt` 被保留，以便现有项目中的引用继续有效。在 v1.0.0 之前，请期待 CLI 界面的破坏性更改随着第 2 阶段的实施而发生。
请参阅 [ROADMAP.md](ROADMAP.md) 以获取阶段计划和发货顺序。
## 贡献
有关分支命名、拉取请求范围、目录编辑过程和 [行为准则](CODE_OF_CONDUCT.md) 的详细信息，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。请根据 [SECURITY.md](SECURITY.md) 私下报告安全问题。
## 许可证
根据 [Apache License, Version 2.0](LICENSE) 授权。捆绑的第三方属性列在 [NOTICE](NOTICE) 中。
