Mistral Vibe

██████████████████░░
██████████████████░░
████  ██████  ████░░
████    ██    ████░░
████          ████░░
████  ██  ██  ████░░
██      ██      ██░░
██████████████████░░
██████████████████░░

Mistral 的开源命令行编码助手。

Mistral Vibe 是一款由 Mistral 模型驱动的命令行编码助手。它为您的代码库提供了一个对话式界面，使您能够使用自然语言通过一套强大的工具来探索、修改和与您的项目进行交互。

[!WARNING] Mistral Vibe 在 Windows 上可以运行，但我们官方支持并主要针对 UNIX 环境。

一行安装（推荐）

Linux 和 macOS

curl -LsSf https://mistral.ai/vibe/install.sh | bash

Windows

首先，安装 uv

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

然后，使用以下 uv 命令。

使用 uv

uv tool install mistral-vibe

使用 pip

pip install mistral-vibe

目录

• 功能
  • 内置代理
  • 子代理与任务委派
  • 交互式用户提问
• 终端要求
• 快速入门
• 使用方法
  • 交互模式
  • 信任文件夹系统
  • 程序化模式
• 语音模式
• 斜杠命令
  • 内置斜杠命令
  • 通过技能自定义斜杠命令
• 技能系统
  • 创建技能
  • 技能发现
  • 管理技能
• 配置
  • 配置文件位置
  • API 密钥配置
  • 自定义系统提示
  • 自定义代理配置
  • 工具管理
  • MCP 服务器配置
  • 会话管理
  • 更新设置
  • 自定义 Vibe 主目录
• 编辑器/IDE
• 资源
• 数据收集与使用
• 许可证

功能

• 交互式聊天：一个能够理解您的请求并分解复杂任务的对话式 AI 代理。
• 强大的工具集：一套用于文件操作、代码搜索、版本控制和命令执行的工具，直接从聊天提示中即可使用。
  • 读取、写入和修补文件（read_file、write_file、search_replace）。
  • 在有状态的终端中执行 shell 命令（bash）。
  • 使用 grep 递归搜索代码（支持 ripgrep）。
  • 管理 todo 列表以跟踪代理的工作。
  • 提出交互式问题以收集用户输入（ask_user_question）。
  • 将任务委派给子代理以并行处理（task）。
• 项目感知上下文：Vibe 会自动扫描您的项目文件结构和 Git 状态，为代理提供相关上下文，从而更好地理解您的代码库。
• 先进的 CLI 体验：基于现代库构建，提供流畅高效的工作流程。
  • 对斜杠命令（/）和文件路径（@）的自动补全。
  • 持久化的命令历史。
  • 美丽的主题。
• 高度可配置：通过简单的 config.toml 文件自定义模型、提供商、工具权限和 UI 偏好。
• 安全第一：具备工具执行审批功能。
• 多种内置代理：您可以选择适合特定工作流的不同代理配置文件。

内置代理

Vibe 配备了多个内置代理配置文件，每个都专为不同的用例设计：

• default：标准代理，需要批准才能执行工具。最适合一般用途。
• plan：只读代理，用于探索和规划。会自动批准 grep 和 read_file 等安全工具。
• accept-edits：仅自动批准文件编辑（write_file、search_replace）。适用于代码重构。
• auto-approve：自动批准所有工具执行。请谨慎使用。

使用 --agent 标志选择不同的代理：

vibe --agent plan

子代理与任务委派

Vibe 支持子代理来进行任务委派。子代理独立运行，可以在无需用户干预的情况下完成专业工作，从而避免上下文过载。

task 工具允许代理将工作委派给子代理：

> 你能在我在做其他事情的时候帮我探索一下代码库结构吗？

🤖 我会使用 task 工具把这个任务委派给 explore 子代理。

> task(task="分析项目结构和架构", agent="explore")

您可以通过在代理配置中添加 agent_type = "subagent" 来创建自定义子代理。Vibe 自带一个名为 explore 的内置子代理，这是一个只读子代理，用于代码库探索，内部用于任务委派。

交互式用户提问

ask_user_question 工具允许代理在工作过程中向您提出澄清问题。这使得工作流程更具互动性和协作性。

> 你能帮我重构这个函数吗？

🤖 在继续之前，我需要更好地了解你的需求。

> ask_user_question(questions=[{
    "question": "这次重构的主要目标是什么？",
    "options": [
        {"label": "性能", "description": "让它运行得更快"},
        {"label": "可读性", "description": "让它更容易理解"},
        {"label": "可维护性", "description": "让它更容易修改"}
    ]
}])

代理可以一次提出多个问题，并以标签页的形式显示。每个问题支持 2-4 个选项，以及一个用于自由文本回答的“其他”选项。

终端要求

Vibe 的交互式界面需要一个现代终端模拟器。推荐的终端模拟器包括：

• WezTerm（跨平台）
• Alacritty（跨平台）
• Ghostty（Linux 和 macOS）
• Kitty（Linux 和 macOS）

大多数现代终端应该都能正常工作，但较旧或极简的终端模拟器可能会出现显示问题。

快速入门

1. 导航到你的项目根目录：

   cd /path/to/your/project
   

2. 运行 Vibe：

   vibe
   

3. 如果这是你首次运行 Vibe，它会：

   • 在 ~/.vibe/config.toml 创建一个默认配置文件
   • 如果尚未配置 API 密钥，则提示你输入 API 密钥
   • 将你的 API 密钥保存到 ~/.vibe/.env 以便日后使用

   或者，你也可以使用 vibe --setup 单独配置 API 密钥。

4. 开始与代理交互吧！

   > 你能找到项目中所有“TODO”这个词的实例吗？
   
   🤖 用户想找到所有“TODO”的实例。`grep` 工具非常适合完成这项任务。我将使用它来搜索当前目录。
   
   > grep(pattern="TODO", path=".")
   
   ... (grep 工具的输出) ...
   
   🤖 我在你的项目中找到了以下“TODO”注释。
   

使用方法

交互模式

只需运行 vibe 即可进入交互式聊天循环。

• 多行输入：按 Ctrl+J 或 Shift+Enter 可以在部分终端中插入换行符。
• 文件路径：在提示中使用 @ 符号引用文件，以实现智能自动补全（例如：> 阅读文件 @src/agent.py）。
• Shell 命令：在任何命令前加上 !，即可直接在 Shell 中执行该命令，绕过代理（例如：> !ls -l）。
• 外部编辑器：按 Ctrl+G 可以在外部编辑器中编辑当前输入。
• 工具输出切换：按 Ctrl+O 可以切换工具输出视图。
• 待办事项列表切换：按 Ctrl+T 可以切换待办事项列表视图。
• 自动批准切换：按 Shift+Tab 可以开启或关闭自动批准模式。

你可以通过以下命令启动带有初始提示的 Vibe：

vibe "将 cli/main.py 中的主函数重构得更加模块化。"

注意：--auto-approve 标志会自动批准所有工具执行，无需提示。在交互模式下，你也可以使用 Shift+Tab 来切换自动批准的开启或关闭状态。

受信文件夹系统

Vibe 包含一个受信文件夹系统，以确保你只在信任的目录中运行代理。当你首次在一个包含 .vibe 子文件夹的新目录中运行 Vibe 时，它可能会要求你确认是否信任该文件夹。

受信文件夹会在后续会话中被记住。你可以通过其配置文件 ~/.vibe/trusted_folders.toml 管理受信文件夹。

此安全功能有助于防止在敏感目录中意外执行。

编程模式

你可以通过管道输入或使用 --prompt 标志以非交互方式运行 Vibe。这对于编写脚本非常有用。

vibe --prompt "将 cli/main.py 中的主函数重构得更加模块化。"

默认情况下，它会使用自动批准模式。

编程模式选项

使用 --prompt 时，你可以指定额外的选项：

• --max-turns N：限制助手的最大回合数。会话将在 N 回合后停止。
• --max-price DOLLARS：设置以美元计价的最大成本限制。如果成本超过此限额，会话将被中断。
• --enabled-tools TOOL：启用特定工具。在编程模式下，这会禁用所有其他工具。可以多次指定。支持精确名称、通配符模式（如 bash*）或带有 re: 前缀的正则表达式（如 re:^serena_.*$）。
• --output FORMAT：设置输出格式。选项如下：
  • text（默认）：人类可读的文本输出
  • json：在最后以 JSON 格式输出所有消息
  • streaming：每条消息以换行符分隔的 JSON 格式输出

示例：

vibe --prompt "分析代码库" --max-turns 5 --max-price 1.0 --output json

语音模式

[!警告] 语音模式目前处于实验阶段，未来版本可能会发生变化。

语音模式允许你使用麦克风口述输入，而不是手动键入。

激活语音模式

通过 /voice 斜杠命令可以开启或关闭语音模式：

> /voice

录音快捷键

快捷键	动作
Ctrl+R	开始录音
任意键	停止录音
Escape	取消录音
Ctrl+C	取消录音

斜杠命令

在会话期间，可以使用斜杠命令进行元操作和配置更改。

内置斜杠命令

Vibe 提供了若干内置斜杠命令。只需在输入框中键入这些命令即可使用：

> /help

通过技能自定义斜杠命令

你可以通过技能系统定义自己的斜杠命令。技能是可重用的组件，用于扩展 Vibe 的功能。

要创建自定义斜杠命令：

1. 创建一个包含 SKILL.md 文件的技能目录
2. 在技能元数据中设置 user-invocable = true
3. 在你的技能中定义命令逻辑

技能元数据示例：

---
name: my-skill
description: 我的自定义技能，包含斜杠命令
user-invocable: true
---

自定义斜杠命令会与内置命令一起出现在自动补全菜单中。

技能系统

Vibe 的技能系统允许你通过可重用组件扩展功能。技能可以添加新工具、斜杠命令以及专门的行为。

Vibe 遵循 Agent Skills 规范 来定义技能的格式和结构。

创建技能

技能是在包含 SKILL.md 文件的目录中定义的，该文件包含 YAML 前言形式的元数据。例如，~/.vibe/skills/code-review/SKILL.md：

---
name: code-review
description: 执行自动化代码审查
license: MIT
compatibility: Python 3.12+
user-invocable: true
allowed-tools:
  - read_file
  - grep
  - ask_user_question
---

# 代码审查技能

此技能有助于分析代码质量并提出改进建议。

技能发现

Vibe 会从多个位置发现技能：

1. 自定义路径：在 config.toml 中通过 skill_paths 配置
2. 标准 Agent Skills 路径（仅限项目根目录和受信文件夹）：.agents/skills/ — Agent Skills 标准
3. 本地项目技能（仅限项目根目录和受信文件夹）：你项目的 .vibe/skills/
4. 全局技能目录：~/.vibe/skills/

skill_paths = ["/path/to/custom/skills"]

管理技能

可以通过配置中的模式来启用或禁用技能：

# 启用特定技能
enabled_skills = ["code-review", "test-*"]

# 禁用特定技能
disabled_skills = ["experimental-*"]

技能支持与工具相同的模式匹配（精确名称、通配符模式和正则表达式）。

配置

配置文件位置

Vibe 通过 config.toml 文件进行配置。它首先会在 ./.vibe/config.toml 中查找该文件，如果不存在，则会回退到 ~/.vibe/config.toml。

API 密钥配置

要使用 Vibe，您需要一个 Mistral API 密钥。您可以通过在 https://console.mistral.ai 上注册来获取密钥。

您可以通过 vibe --setup 或以下方法之一来配置您的 API 密钥。

Vibe 支持多种配置 API 密钥的方式：

1. 交互式设置（建议首次使用用户）：当您首次运行 Vibe 或者 API 密钥缺失时，Vibe 会提示您输入密钥。该密钥将被安全地保存到 ~/.vibe/.env 中，以供后续会话使用。

2. 环境变量：将您的 API 密钥设置为环境变量：

   export MISTRAL_API_KEY="your_mistral_api_key"
   

3. .env 文件：在 ~/.vibe/ 目录下创建一个 .env 文件，并添加您的 API 密钥：

   MISTRAL_API_KEY=your_mistral_api_key
   

   Vibe 会在启动时自动从 ~/.vibe/.env 加载 API 密钥。如果同时设置了环境变量和 .env 文件，环境变量的优先级更高。

注意：.env 文件专门用于存储 API 密钥和其他提供商凭据。通用的 Vibe 配置应放在 config.toml 中。

自定义系统提示

您可以创建自定义系统提示来替换默认提示（prompts/cli.md）。在 ~/.vibe/prompts/ 目录下创建一个包含自定义提示内容的 Markdown 文件。

要使用自定义系统提示，请在您的配置中将 system_prompt_id 设置为与文件名匹配（不包括 .md 后缀）：

# 使用自定义系统提示
system_prompt_id = "my_custom_prompt"

这将会加载 ~/.vibe/prompts/my_custom_prompt.md 中的提示。

自定义代理配置

您可以为特定用例（例如红队演练、专业任务）创建自定义代理配置，方法是在 ~/.vibe/agents/ 目录下添加代理专用的 TOML 文件。

要使用自定义代理，请使用 --agent 标志运行 Vibe：

vibe --agent my_custom_agent

Vibe 会查找代理目录中名为 my_custom_agent.toml 的文件，并应用其配置。

自定义代理配置示例（~/.vibe/agents/redteam.toml）：

# 红队演练的自定义代理配置
active_model = "devstral-2"
system_prompt_id = "redteam"

# 禁用此代理的一些工具
disabled_tools = ["search_replace", "write_file"]

# 覆盖此代理的工具权限
[tools.bash]
permission = "always"

[tools.read_file]
permission = "always"

注意：这意味着您已经设置了一个名为 ~/.vibe/prompts/redteam.md 的红队提示。

工具管理

使用模式启用或禁用工具

您可以使用 enabled_tools 和 disabled_tools 控制哪些工具处于激活状态。这些字段支持精确名称、通配符模式和正则表达式。

示例：

# 仅启用以 "serena_" 开头的工具（通配符）
enabled_tools = ["serena_*"]

# 正则表达式（前缀为 re:）——匹配完整工具名称（不区分大小写）
enabled_tools = ["re:^serena_.*$"]

# 使用通配符禁用一组工具；其他工具保持启用状态
disabled_tools = ["mcp_*", "grep"]

注意事项：

• MCP 工具名称使用下划线，例如 serena_list 而不是 serena.list。
• 正则表达式模式会使用 fullmatch 匹配完整工具名称。

MCP 服务器配置

您可以配置 MCP（模型上下文协议）服务器来扩展 Vibe 的功能。在 mcp_servers 部分添加 MCP 服务器配置：

# MCP 服务器配置示例
[[mcp_servers]]
name = "my_http_server"
transport = "http"
url = "http://localhost:8000"
headers = { "Authorization" = "Bearer my_token" }
api_key_env = "MY_API_KEY_ENV_VAR"
api_key_header = "Authorization"
api_key_format = "Bearer {token}"

[[mcp_servers]]
name = "my_streamable_server"
transport = "streamable-http"
url = "http://localhost:8001"
headers = { "X-API-Key" = "my_api_key" }

[[mcp_servers]]
name = "fetch_server"
transport = "stdio"
command = "uvx"
args = ["mcp-server-fetch"]
env = { "DEBUG" = "1", "LOG_LEVEL" = "info" }

支持的传输方式：

• http：标准 HTTP 传输
• streamable-http：支持流式传输的 HTTP 传输
• stdio：标准输入输出传输（用于本地进程）

关键字段：

• name：服务器的简短别名（用于工具名称）
• transport：传输类型
• url：HTTP 传输的基 URL
• headers：附加 HTTP 头
• api_key_env：包含 API 密钥的环境变量
• command：用于 stdio 传输的命令
• args：stdio 传输的附加参数
• startup_timeout_sec：服务器启动和初始化的超时时间（默认 10 秒）
• tool_timeout_sec：工具执行的超时时间（默认 60 秒）
• env：为 stdio 类型的 MCP 服务器设置的环境变量

MCP 工具的命名采用 {server_name}_{tool_name} 模式，并且可以像内置工具一样配置权限：

# 为特定 MCP 工具配置权限
[tools.fetch_server_get]
permission = "always"

[tools.my_http_server_query]
permission = "ask"

MCP 服务器配置还支持其他功能：

• 环境变量：为 MCP 服务器设置环境变量
• 自定义超时：配置服务器启动和工具执行的超时时间

带有环境变量和超时的示例：

[[mcp_servers]]
name = "my_server"
transport = "http"
url = "http://localhost:8000"
env = { "DEBUG" = "1", "LOG_LEVEL" = "info" }
startup_timeout_sec = 15
tool_timeout_sec = 120

会话管理

会话继续和恢复

Vibe 支持从之前的会话继续：

• --continue 或 -c：从最近保存的会话继续
• --resume SESSION_ID：按 ID 恢复特定会话（支持部分匹配）

# 继续上次会话
vibe --continue

# 恢复特定会话
vibe --resume abc123

要使这些功能生效，必须在您的配置中启用会话日志记录。

工作目录控制

使用 --workdir 选项指定工作目录：

vibe --workdir /path/to/project

这在您希望从当前目录以外的位置运行 Vibe 时非常有用。

更新设置

自动更新

Vibe 包含自动更新功能，可使您的安装保持最新状态。此功能默认已启用。

要禁用自动更新，请在 config.toml 中添加以下内容：

enable_auto_update = false

通知设置

Vibe 可以在代理需要您注意时（等待批准、提问或任务完成）向您发送通知。这在您切换到其他窗口而代理仍在工作时非常有用。

要禁用通知：

enable_notifications = false

自定义 Vibe 主目录

默认情况下，Vibe 会将其配置存储在 ~/.vibe/ 目录下。你可以通过设置 VIBE_HOME 环境变量来覆盖此路径：

export VIBE_HOME="/path/to/custom/vibe/home"

这将影响 Vibe 查找以下内容的位置：

• config.toml - 主配置文件
• .env - API 密钥
• agents/ - 自定义智能体配置
• prompts/ - 自定义系统提示
• tools/ - 自定义工具
• logs/ - 会话日志

编辑器/IDE

Mistral Vibe 可以在支持 Agent Client Protocol 的文本编辑器和 IDE 中使用。有关各种编辑器和 IDE 的设置说明，请参阅 ACP 设置文档。

资源

• CHANGELOG - 查看每个版本的新功能
• CONTRIBUTING - 功能请求、反馈和错误报告的指南

数据收集与使用

使用 Vibe 需遵守我们的 隐私政策，并且可能包括收集和处理与您使用本服务相关的数据，例如使用数据，以运行、维护和改进 Vibe。您可以在 config.toml 文件中将 enable_telemetry = false 来禁用遥测功能。

许可证

版权所有 2025 年 Mistral AI

依照 Apache License, Version 2.0（“许可证”）授权； 除非符合许可证规定，否则不得使用本文件。 您可以在以下网址获取许可证副本：

http://www.apache.org/licenses/LICENSE-2.0

除非适用法律另有要求或双方另有约定，否则软件按“原样”分发，不提供任何形式的保证或条件。 完整的许可证文本请参阅 LICENSE 文件。

Mistral Vibe 快速上手指南

环境准备

系统要求

• 操作系统：Linux/macOS（Windows 支持但非官方推荐）
• Python 版本：3.12+

前置依赖

• uv（推荐）或 pip
• 一个现代终端模拟器（如 WezTerm、Alacritty、Ghostty、Kitty）

安装步骤

使用 uv 安装（推荐）

Windows 用户需先安装 uv

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

然后安装 Mistral Vibe：

uv tool install mistral-vibe

使用 pip 安装

pip install mistral-vibe

Linux/macOS 一键安装（推荐）

curl -LsSf https://mistral.ai/vibe/install.sh | bash

基本使用

1. 进入项目根目录：

   cd /path/to/your/project
   

2. 启动 Vibe：

   vibe
   

3. 首次运行时会：

   • 创建配置文件 ~/.vibe/config.toml
   • 提示输入 API Key（可使用 vibe --setup 配置）

4. 开始交互：

   > Can you find all instances of the word "TODO" in the project?
   
   🤖 The user wants to find all instances of "TODO". The `grep` tool is perfect for this. I will use it to search the current directory.
   
   > grep(pattern="TODO", path=".")