mistralai/mistral-vibe

# Mistral Vibe [](https://pypi.org/project/mistral-vibe) [](https://www.python.org/downloads/release/python-3120/) [](https://github.com/mistralai/mistral-vibe/actions/workflows/ci.yml) [](https://github.com/mistralai/mistral-vibe/blob/main/LICENSE) ``` ██████████████████░░ ██████████████████░░ ████ ██████ ████░░ ████ ██ ████░░ ████ ████░░ ████ ██ ██ ████░░ ██ ██ ██░░ ██████████████████░░ ██████████████████░░ ``` **Mistral 的开源 CLI 编程助手。** Mistral Vibe 是一个由 Mistral 模型驱动的命令行编程助手。它为你的代码库提供了一个对话式界面，让你能够通过强大的工具集，使用自然语言来探索、修改你的项目并进行交互。 ### 一键安装（推荐） **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 ``` ## 目录 - [功能](#features) - [内置 Agent](#built-in-agents) - [子 Agent 与任务委派](#subagents-and-task-delegation) - [交互式用户提问](#interactive-user-questions) - [终端要求](#terminal-requirements) - [快速开始](#quick-start) - [用法](#usage) - [交互模式](#interactive-mode) - [信任文件夹系统](#trust-folder-system) - [编程模式](#programmatic-mode) - [语音模式](#voice-mode) - [斜杠命令](#slash-commands) - [内置斜杠命令](#built-in-slash-commands) - [通过 Skills 自定义斜杠命令](#custom-slash-commands-via-skills) - [Skills 系统](#skills-system) - [创建 Skills](#creating-skills) - [Skill 发现](#skill-discovery) - [管理 Skills](#managing-skills) - [配置](#configuration) - [配置文件位置](#configuration-file-location) - [API Key 配置](#api-key-configuration) - [自定义 System Prompt](#custom-system-prompts) - [自定义 Agent 配置](#custom-agent-configurations) - [工具管理](#tool-management) - [MCP Server 配置](#mcp-server-configuration) - [会话管理](#session-management) - [更新设置](#update-settings) - [自定义 Vibe Home 目录](#custom-vibe-home-directory) - [编辑器/IDE](#editorsides) - [资源](#resources) - [数据收集与使用](#data-collection--usage) - [许可证](#license) ## 功能 - **交互式聊天**：一个对话式 AI agent，能理解你的请求并拆解复杂任务。 - **强大的工具集**：一套直接在聊天提示符中进行文件操作、代码搜索、版本控制和执行命令的工具。 - 读取、写入和修补文件（`read`、`write_file`、`edit`）。 - 执行 shell 命令（`bash`），并带有用于轮询和 stdin 辅助的实验性托管 PTY 模式。 - 使用 `grep` 递归搜索代码（支持 `ripgrep`）。 - 管理 `todo` 列表以跟踪 agent 的工作。 - 提出交互式问题以收集用户输入（`ask_user_question`）。 - 将任务委派给子 Agent 以进行并行工作（`task`）。 - **项目感知上下文**：Vibe 会自动扫描项目的文件结构和 Git 状态，以向 agent 提供相关上下文，从而增强其对代码库的理解。 - **高级 CLI 体验**：采用现代库构建，提供流畅高效的工作流程。 - 斜杠命令（`/`）和文件路径（`@`）的自动补全。 - 通过 `@` 提及添加图片附件 — `.png`、`.jpg`、`.jpeg`、`.gif`、`.webp` 文件将作为原生多模态内容发送至支持视觉的模型（例如 Mistral Medium 3.5）。 - 持久的命令历史记录。 - 漂亮的主题。 - **高度可配置**：通过简单的 `config.toml` 文件自定义模型、提供商、工具权限和 UI 偏好。 - **安全第一**：具有工具执行批准功能。 - **多个内置 Agent**：可以根据特定的工作流程选择不同的 agent 配置文件。 ### 内置 Agent Vibe 自带几个内置 agent 配置文件，每个都是为不同的用例设计的： - **`default`**：需要批准才能执行工具的标准 agent。最适合日常通用。 - **`plan`**：用于探索和规划的只读 agent。自动批准如 `grep` 和 `read` 等安全工具。 - **`accept-edits`**：仅自动批准文件编辑（`write_file`、`edit`）。适用于代码重构。 - **`auto-approve`**：自动批准所有工具执行。请谨慎使用。 使用 `--agent` 标志选择其他 agent： ``` vibe --agent plan ``` 要更改未传递 `--agent` 时使用的默认 agent，请在你的 `config.toml` 中设置 `default_agent`： ``` default_agent = "plan" ``` 有效值为 `default`、`plan`、`accept-edits`、`auto-approve`、 `lean`（仅在 `installed_agents` 中列出时有效），或者是 `~/.vibe/agents/` 或项目的 `.vibe/agents/` 目录中任意自定义 agent 文件的名称。诸如 `explore` 之类的子 Agent 不被接受。 ### 子 Agent 与任务委派 Vibe 支持用于委派任务的子 Agent。子 Agent 独立运行，可以在没有用户交互的情况下执行专门的工作，从而防止上下文过载。 `task` 工具允许 agent 将工作委派给子 Agent： ``` > Can you explore the codebase structure while I work on something else? 🤖 I'll use the task tool to delegate this to the explore subagent. > task(task="Analyze the project structure and architecture", agent="explore") ``` 通过在你的 agent 配置中添加 `agent_type = "subagent"` 来创建自定义子 Agent。Vibe 自带一个名为 `explore` 的内置子 Agent，它是一个用于代码库探索的只读子 Agent，在内部用于委派任务。 ### 交互式用户提问 `ask_user_question` 工具允许 agent 在工作期间向你提出澄清性问题。这可以实现更加互动和协作的工作流程。 ``` > Can you help me refactor this function? 🤖 I need to understand your requirements better before proceeding. > ask_user_question(questions=[{ "question": "What's the main goal of this refactoring?", "options": [ {"label": "Performance", "description": "Make it run faster"}, {"label": "Readability", "description": "Make it easier to understand"}, {"label": "Maintainability", "description": "Make it easier to modify"} ] }]) ``` agent 可以一次性提出多个问题，并以选项卡的形式显示。每个问题支持 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 key，提示你输入 - 将你的 API key 保存到 `~/.vibe/.env` 以供将来使用 或者，你可以使用 `vibe --setup` 单独配置你的 API key。 4. 开始与 agent 交互！ > 你能在项目中找到所有“TODO”这个词的实例吗？ 🤖 用户想要找到所有的“TODO”实例。`grep` 工具非常适合这个任务。我将使用它来搜索当前目录。 > grep(pattern="TODO", path=".") ... (grep 工具输出) ... 🤖 我在你的项目中找到了以下“TODO”注释。 ## 用法 ### 交互模式 只需运行 `vibe` 即可进入交互式聊天循环。 - **多行输入**：按 `Ctrl+J` 或特定终端的 `Shift+Enter` 插入换行符。 - **文件路径**：在你的 prompt 中使用 `@` 符号引用文件，实现智能自动补全（例如，`> 读取文件 @src/agent.py`）。 - **Shell 命令**：在任何命令前加上 `!` 可直接在你的 shell 中执行，绕过 agent（例如，`> !ls -l`）。 - **外部编辑器**：按 `Ctrl+G` 在外部编辑器中编辑你当前的输入。 - **工具输出切换**：按 `Ctrl+O` 切换工具输出视图。 - **Todo 视图切换**：按 `Ctrl+T` 切换 todo 列表视图。 - **调试控制台**：按 `Ctrl+\` 切换调试控制台。 - **Agent 选择**：按 `Shift+Tab` 循环切换 agent（default、plan、...）。 - **退出**：在输入框中输入 `/exit`、`exit`、`quit`、`:q` 或 `:quit`，或者在约 1 秒内按两次 `Ctrl+C` / `Ctrl+D`。设置 `ask_confirmation_on_exit = false`（或在 `/config` 中切换它）可以使 `Ctrl+D` 在第一次按下时退出；`Ctrl+C` 始终需要确认。 你可以使用以下命令以特定 prompt 启动 Vibe： ``` vibe "Refactor the main function in cli/main.py to be more modular." ``` ### 信任文件夹系统 Vibe 包含一个信任文件夹系统，以确保你仅在你信任的目录中运行 agent。当你在包含 `.vibe` 子文件夹的新目录中首次运行 Vibe 时，它可能会要求你确认是否信任该文件夹。 受信任的文件夹会在以后的会话中被记住。你可以通过其配置文件 `~/.vibe/trusted_folders.toml` 管理受信任的文件夹。 此安全功能有助于防止在敏感目录中意外执行。 ### 编程模式 你可以通过管道传递输入或使用 `--prompt` 标志以非交互方式运行 Vibe。这对于脚本编写非常有用。 ``` vibe --prompt "Refactor the main function in cli/main.py to be more modular." ``` 默认情况下，它使用你配置的 `default_agent`（除非更改，否则为 `default`）。 要在不提示的情况下批准所有工具调用，请传递 `--auto-approve` 或 `--yolo` （也可用于交互式会话）： ``` vibe --prompt "Refactor the main function in cli/main.py to be more modular." --auto-approve ``` #### 编程模式选项 使用 `--prompt` 时，你可以指定以下附加选项： - **`--max-turns N`**：限制助手机制回合的最大数量。会话将在 N 个回合后停止。 - **`--max-price DOLLARS`**：设置以美元计的最大成本限制。如果成本超过此限制，会话将被中断。 - **`--max-tokens N`**：设置会话的最大 LLM token 总预算，同时计算 prompt token 和 completion token。如果使用量超过此限制，会话将被中断。 - **`--agent NAME`**：为本次运行选择 agent 配置文件。 - **`--auto-approve`、`--yolo`**：批准所有工具调用而无需提示，包括在交互式会话中。可以与任何 `--agent` 值组合使用。 - **`--enabled-tools TOOL`**：启用特定工具。在编程模式下，这会禁用所有其他工具。可以多次指定。支持确切名称、glob 模式（例如 `bash*`）或带有 `re:` 前缀的正则表达式（例如 `re:^serena_.*$`）。 - **`--disabled-tools TOOL`**：在 `--enabled-tools` 过滤后禁用特定工具。可以多次指定。支持确切名称、glob 模式（例如 `bash*`）或带有 `re:` 前缀的正则表达式（例如 `re:^serena_.*$`）。 - **`--output FORMAT`**：设置输出格式。选项： - `text`（默认）：人类可读的文本输出 - `json`：最后将所有消息作为 JSON 输出 - `streaming`：每条消息以换行符分隔的 JSON 格式输出 示例： ``` vibe --prompt "Analyze the codebase" --max-turns 5 --max-price 1.0 --max-tokens 50000 --output json ``` ## 语音模式 语音模式允许你使用麦克风口述输入，而不是打字。 ### 激活语音模式 使用 `/voice` 斜杠命令打开或关闭语音模式： ``` > /voice ``` ### 录音快捷键 | 快捷键 | 操作 | | -------- | ---------------- | | `Ctrl+R` | 开始录音 | | 任意键 | 停止录音 | | `Escape` | 取消录音 | | `Ctrl+C` | 取消录音 | ## 斜杠命令 在会话期间使用斜杠命令进行元操作和配置更改。 ### 内置斜杠命令 Vibe 提供了几个内置的斜杠命令。在输入框中键入斜杠命令即可使用它们： ``` > /help ``` ### 通过 Skills 自定义斜杠命令 你可以通过 skills 系统定义自己的斜杠命令。Skills 是扩展 Vibe 功能的可重用组件。 要创建自定义斜杠命令： 1. 创建一个包含 `SKILL` 文件的 skill 目录 2. 在 skill 元数据中设置 `user-invocable = true` 3. 在你的 skill 中定义命令逻辑 示例 skill 元数据： ``` --- name: my-skill description: My custom skill with slash commands user-invocable: true --- ``` 自定义斜杠命令会与内置命令一起出现在自动补全菜单中。 ## Skills 系统 Vibe 的 skills 系统允许你通过可重用的组件扩展功能。Skills 可以添加新工具、斜杠命令和专门的行为。 Vibe 遵循 [Agent Skills 规范](https://agentskills.io/specification) 的 skill 格式和结构。 ### 创建 Skills Skills 在目录中定义，其中包含 YAML frontmatter 形式的元数据文件 `SKILL.md`。例如，`~/.vibe/skills/code-review/SKILL.md`： ``` --- name: code-review description: Perform automated code reviews license: MIT compatibility: Python 3.12+ user-invocable: true allowed-tools: - read - grep - ask_user_question --- # Code Review Skill This skill helps analyze code quality and suggest improvements. ``` ### Skill 发现 Vibe 从多个位置发现 skills： 1. **自定义路径**：通过 `config.toml` 中的 `skill_paths` 配置 2. **标准 Agent Skills 路径**（项目根目录，仅限受信任的文件夹）：`.agents/skills/` — [Agent Skills](https://agentskills.io) 标准 3. **本地项目 skills**（项目根目录，仅限受信任的文件夹）：你项目中的 `.vibe/skills/` 4. **全局 skills 目录**：`~/.vibe/skills/` 和 `~/.agents/skills/` ``` skill_paths = ["/path/to/custom/skills"] ``` ### 管理 Skills 在你的配置中使用模式启用或禁用 skills： ``` # 启用特定 skill enabled_skills = ["code-review", "test-*"] # 禁用特定 skill disabled_skills = ["experimental-*"] ``` Skills 支持与工具相同的模式匹配（确切名称、glob 模式和正则表达式）。 ## 配置 ### 配置文件位置 Vibe 通过 `config.toml` 文件进行配置。它首先在 `./.vibe/config.toml` 中查找此文件，然后回退到 `~/.vibe/config.toml`。 ### API Key 配置 要使用 Vibe，你需要一个 Mistral API key。你可以通过在 [https://console.mistral.ai](https://console.mistral.ai) 注册来获取一个。 你可以使用 `vibe --setup` 或通过以下方法之一配置你的 API key。 Vibe 支持多种配置 API key 的方式： 1. **交互式设置（首次使用推荐）**：当你第一次运行 Vibe 或你的 API key 缺失时，Vibe 会提示你输入。该 key 将安全地保存到 `~/.vibe/.env` 中以供以后的会话使用。 2. **环境变量**：将你的 API key 设置为环境变量： export MISTRAL_API_KEY="your_mistral_api_key" 3. **`.env` 文件**：在 `~/.vibe/` 中创建一个 `.env` 文件并添加你的 API key： MISTRAL_API_KEY=your_mistral_api_key Vibe 启动时会自动从 `~/.vibe/.env` 加载 API key。如果同时设置了环境变量和 `.env` 文件，则环境变量优先。 **注意**：`.env` 文件专门用于 API key 和其他提供商凭据。常规的 Vibe 配置应在 `config.toml` 中进行。 ### TLS 和企业证书颁发机构 默认情况下，Vibe 使用内置的 `certifi` 证书根进行出站 HTTPS 请求。如果你的组织在操作系统信任库中安装了私有证书颁发机构，你可以在 `config.toml` 中选择加入系统信任库： ``` enable_system_trust_store = true ``` `SSL_CERT_FILE` 和 `SSL_CERT_DIR` 仍然受支持，并将作为附加信任锚加载。 ### 自定义 System Prompt 你可以创建 `AGENTS.md` 文件来添加自定义指令。你也可以替换整个 system prompt。 将 `AGENTS.md` 文件放置在： - `~/.vibe/AGENTS.md` — 适用于所有项目的用户级指令 - 项目目录 — 项目特定指令，从 cwd 加载至信任根目录 优先级：更近的目录会覆盖更远的目录。`AGENTS.md` 中的指令会覆盖默认的 system prompt。仅为受信任的文件夹加载文件。 自定义 system prompt 将完全替换默认的（`prompts/cli.md`）。在 `~/.vibe/prompts/` 目录中创建一个包含你自定义 prompt 内容的 Markdown 文件。 要使用自定义 system prompt，请在你的配置中设置 `system_prompt_id` 以匹配文件名（不带 `.md` 扩展名）： ``` # 使用自定义 system prompt system_prompt_id = "my_custom_prompt" ``` 这将从 `~/.vibe/prompts/my_custom_prompt.md` 加载 prompt。 `.vibe/prompts/` 中的项目本地 prompt 也受支持，并且将覆盖具有相同名称的用户级 prompt。这适用于所有自定义 prompt（system 和 compaction）。 ### 自定义 Compaction Prompt Compaction 默认使用位于 `prompts/compact.md` 的内置 prompt。你可以使用与 system prompt 相同的解析规则，将其替换为来自 `~/.vibe/prompts/`（或 `.vibe/prompts/`）的自定义 prompt。 要使用自定义 compaction prompt，请在你的配置中设置 `compaction_prompt_id` 以匹配文件名（不带 `.md` 扩展名）： ``` # 使用自定义 compaction prompt compaction_prompt_id = "my_compaction_prompt" ``` 传递给 `/compact ...` 的任何额外指令都会附加在配置好的 compaction prompt 之后。 ### 自定义 Agent 配置 你可以通过在 `~/.vibe/agents/` 目录中添加特定于 agent 的 TOML 文件，为特定用例（例如红队测试、专门任务）创建自定义 agent 配置。 要使用自定义 agent，请带上 `--agent` 标志运行 Vibe： ``` vibe --agent my_custom_agent ``` Vibe 将在 agents 目录中查找名为 `my_custom_agent.toml` 的文件，并应用其配置。 自定义 agent 配置示例（`~/.vibe/agents/redteam.toml`）： ``` # 用于 red-teaming 的自定义 agent 配置 active_model = "mistral-medium-3.5" system_prompt_id = "redteam" # 为此 agent 禁用某些 tool disabled_tools = ["edit", "write_file"] # 为此 agent 覆盖 tool 权限 [tools.bash] permission = "always" [tools.read] permission = "always" ``` 注意：这意味着你已经设置了一个名为 `~/.vibe/prompts/redteam.md` 的红队 prompt。 ### 工具管理 内置的 `bash` 工具默认运行一次性的 shell 命令。设置 `experimental_bash_tool = true` 以在相同的 `bash` 工具名称下将其替换为实验性的托管 PTY 实现。在该模式下，`bash` 会返回一个 `session_id`、内联输出、用于通过 `bash_output` 轮询更多输出的游标， 以及一个位于 `~/.vibe/bash-tool/` 下的日志路径。长时间运行的命令可以通过 `background = true` 保持活跃状态，并且交互式命令可以使用 `bash_stdin` 进行驱动。两种实现都使用来自 `[tools.bash]` 的相同权限、允许列表和拒绝列表。 ``` experimental_bash_tool = true ``` #### 通过模式启用/禁用工具 你可以使用 `enabled_tools` 和 `disabled_tools` 控制哪些工具处于活动状态。 这些字段支持确切名称、glob 模式和正则表达式。 当两者都设置时，`enabled_tools` 首先缩小工具集范围，然后 `disabled_tools` 从该集合中移除匹配的工具。 示例： ``` # 仅启用以 "serena_" 开头的 tool (glob) enabled_tools = ["serena_*"] # Regex (前缀为 re:) — 匹配完整 tool 名称（不区分大小写） enabled_tools = ["re:^serena_.*$"] # 使用 glob 禁用某个组；保持其他所有内容启用 disabled_tools = ["mcp_*", "grep"] ``` 注意： - MCP 工具名称使用下划线，例如，使用 `serena_list` 而不是 `serena.list`。 - 正则表达式模式使用 fullmatch 对整个工具名称进行匹配。 ### MCP Server 配置 你可以配置 MCP (Model Context Protocol) 服务器以扩展 Vibe 的功能。在 `mcp_servers` 部分下添加 MCP server 配置： 对于托管的 OAuth MCP server，你可以从 Vibe 内部添加该服务器： ``` /mcp add https://mcp.linear.app/mcp /mcp add https://mcp.example.com/mcp --name docs --scope read --transport http --no-login ``` `/mcp add` 仅限 OAuth 使用。它会写入 `auth.type = "oauth"` 及可选的 scope，并默认开始登录。除非你传递了 `--transport http`， 否则它使用 `transport = "streamable-http"`。传递 `--no-login` 可在不 启动 OAuth 登录的情况下添加服务器。该快捷方式支持 `streamable-http` 和 `http` 传输。对于 API key/静态验证，请使用下方的静态验证示例 编辑 `config.toml`。 ``` # MCP server 配置示例 [[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 headers - `api_key_env`：包含 API key 的环境变量 - `command`：用于 stdio 传输运行的命令 - `args`：stdio 传输的附加参数 - `startup_timeout_sec`：服务器启动并初始化的超时时间（以秒为单位，默认为 10s） - `tool_timeout_sec`：工具执行的超时时间（以秒为单位，默认为 60s） - `env`：为 stdio 传输类型的 MCP server 设置的环境变量 HTTP MCP server 可以使用静态验证或 OAuth。静态验证使用 `config.toml` 中的 `api_key_env` / `headers`；OAuth 使用 `auth` 块： ``` [[mcp_servers]] name = "linear" transport = "streamable-http" url = "https://mcp.linear.app/mcp" [mcp_servers.auth] type = "oauth" scopes = [] ``` MCP 工具使用模式 `{server_name}_{tool_name}` 命名，并且可以像内置工具一样配置权限： ``` # 为特定 MCP tool 配置权限 [tools.fetch_server_get] permission = "always" [tools.my_http_server_query] permission = "ask" ``` MCP server 配置支持附加功能： - **环境变量**：为 MCP server 设置环境变量 - **自定义超时**：配置启动和工具执行超时 带有环境变量和超时的示例： ``` [[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 ``` ### Hooks（实验性） Hooks 将任意的 shell 命令接入 Vibe 的生命周期，以控制、审计或重写 agent 行为。**实验性**功能，受以下配置控制： ``` # config.toml enable_experimental_hooks = true # or env VIBE_ENABLE_EXPERIMENTAL_HOOKS=true ``` 声明在 `/.vibe/hooks.toml`（项目级别，首先加载；仅限受信任的）和 `~/.vibe/hooks.toml`（用户全局，随后加载；重名的 `name` 会被项目条目覆盖）： ``` [[hooks]] name = "deny-rm-rf" type = "before_tool" match = "bash" # tool-name matcher (fnmatch glob + `re:` regex escape, case-insensitive) command = "uv run python /path/to/guard-bash" timeout = 60.0 # seconds; default 60 for all hooks strict = false # tool hooks only: turn failures into denials (before) / text-clears (after) description = "Reject dangerous shell commands." ``` 子 Agent 继承父级的 hook 配置，因此策略具有传递性。 #### 共同基准 每个 hook 都会在 **stdin** (UTF-8) 上生成一个包含会话上下文的 JSON 调用：`session_id`、`parent_session_id`、`transcript_path`、`cwd`，外加区分 hook 类型的 `hook_event_name`。工具 hook 会添加特定于工具的字段（如下）。 每个 hook 都通过其 **exit code** 和 **stdout** 进行反馈。stdout 上的约定非常严格：要么为空（不执行任何操作），要么是符合以下 schema 的 JSON 对象。使用 **stderr** 输出诊断/调试日志。 - **Exit `0`，stdout 为空** — 透传。 - **Exit `0`，stdout 上有有效的 JSON 对象** — 结构化响应。通用顶级字段： - `system_message`（字符串，可选）— 在 UI 中显示给用户。 - `decision`（`"allow"` | `"deny"`，可选，默认为 `"allow"`）— `"deny"` 的影响取决于 hook 类型。 - `reason`（字符串，可选）— 伴随 `decision: "deny"` 出现。 - `hook_specific_output` 下的特定事件 payload。 - **Exit `0`，stdout 非空但不合规**（自由格式文本、损坏的 JSON、JSON 标量/数组、schema 不匹配） — 视为 hook 失败，解析错误作为消息。默认情况下发出警告；在工具 hook 上设置为 `strict = true` 时，会升级为拒绝/清除。 - **任何非零 exit / 超时 / 启动失败** — 同样的失败路径。诊断信息取自 stderr（如果不可用则回退到 stdout，然后是 exit code）。 每个级别都允许未知的 JSON 字段（向前兼容）。对于当前 hook 类型没有意义的字段将被静默忽略。 #### `post_agent_turn` 在没有待处理工具调用的情况下，每次助手回合结束后触发。 - **接收**（除了会话上下文之外）：没有额外字段。 - **可以返回**： - `decision: "deny"` + `reason` — `reason` 将作为要求重试的新用户消息注入。每个用户回合的每个 hook 最多限制 **3 次重试**；进一步的拒绝将成为终端警告。 - `system_message` — 仅限 UI 显示。 #### `before_tool` 每次工具调用时触发，**在**用户权限提示**之前**。第一次拒绝会短路该调用的剩余 `before_tool` hooks。 - **接收**（除了会话上下文之外）：`tool_name`、`tool_call_id`、`tool_input`（模型的原始参数）。 - **可以返回**： - `decision: "deny"` + `reason` — 拒绝工具调用；`reason` 成为 LLM 看到的工具错误。 - `hook_specific_output.tool_input`（对象） — 对模型参数进行**完全替换**。会根据工具的 schema 重新验证（验证失败 → 合成拒绝）。重写在多个 hook 之间从左到右组合。重写后的参数也是权限提示显示的内容、工具运行时使用的内容，以及后续 LLM 回合在助手消息中看到的内容。 - `system_message` — 仅限 UI 显示。 #### `after_tool` **当且仅当工具主体实际运行时**，每次工具调用才会。`tool_status` 为 `success`、`failure` 或 `cancelled`（在工具主体执行期间的取消 — 此取消被屏蔽，因此审计 hooks 仍然会运行）。当工具从未执行时不触发：`before_tool` 拒绝、在批准提示处被用户拒绝、权限为 `NEVER`，或者在主体开始之前被取消。 - **接收**（除了会话上下文之外）：`tool_name`、`tool_call_id`、`tool_input`（重写后）、`tool_status`、`tool_output`（结构化结果字典；失败时为 null）、`tool_output_text`（LLM 将看到的运行文本，可被之前的 hooks 更改）、`tool_error`、`duration_ms`。 - **可以返回**： - `decision: "deny"` + `reason` — 用 `reason` 替换 `tool_output_text`。流水线继续执行；后续 hooks 会看到该替换。 - `hook_specific_output.additional_context`（字符串） — **附加**（带有 `\n` 分隔符）到 `tool_output_text`。与同一 hook 的 deny 组合：deny 首先替换，然后将 `additional_context` 附加到替换的内容中。 - `system_message` — 仅限 UI 显示。 ### 会话管理 #### 会话延续与恢复 Vibe 支持从之前的会话继续： - **`--continue`** 或 **`-c`**：从最近保存的会话继续 - **`--resume`**：打开交互式会话选择器 - **`--resume SESSION_ID`**：通过 ID 恢复特定会话（支持部分匹配） - **`/resume`** 或 **`/continue`**：从 Vibe 内部打开会话选择器；按两次 `D` 删除本地保存的会话。当前活动会话无法从此选择器中删除。 ``` # 从上一个 session 继续 vibe --continue # 打开 session 选择器 vibe --resume # 恢复特定 session vibe --resume abc123 ``` 必须在你的配置中启用会话日志记录，这些功能才能正常工作。 #### 工作目录控制 使用 `--workdir` 选项指定工作目录： ``` vibe --workdir /path/to/project ``` 当你想要从与当前目录不同的位置运行 Vibe 时，这非常有用。 使用 `--add-dir`（可重复使用）可以在会话期间向 agent 提供额外的目录： ``` vibe --add-dir /path/to/other-project --add-dir /path/to/library ``` 每个路径都被隐式信任（无信任提示），并将其 `AGENTS.md` 和 `.vibe/` 配置（tools、skills、agents、prompts、hooks）贡献给会话。文件工具权限将每个 `--add-dir` 路径视为与你的主工作目录相同 — 在其中进行读取和写入不需要“工作目录之外”的提示。嵌套路径会折叠：传递 `/repo` 和 `/repo/sub` 相当于只传递 `/repo`。 使用 `--worktree NAME` 创建（或重用）[git worktree](https://git-scm.com/docs/git-worktree) 并在其中运行： ``` vibe --worktree my-feature ``` 该 worktree 位于 `$VIBE_HOME/worktrees/-/NAME` 下，并被检出到一个名为 `NAME` 的分支上（如果不存在则创建，如果存在则附加）。Vibe 在会话开始前 `cd` 进入该目录，并在会话期间信任它（无信任提示）。如果你从子目录启动 Vibe，Vibe 会进入 worktree 内对应的子目录。 只有当现有的 worktree 属于同一个 git 存储库并且被检出在分支 `NAME` 上时，它们才会被重用；否则 Vibe 会退出并报错，而不是在错误的检出中运行。 自动清理仅适用于 Vibe 本次运行创建的 worktree，并且仅当会话实际启动时 — 启动失败（配置错误、没有会话的 `--continue`）绝不会删除任何内容，而被重用的 worktree 则始终保持在原位。当交互式会话退出时，如果没有未提交的更改、未跟踪的文件或超出 worktree 会话开始时 commit 的提交，Vibe 会自动删除该 worktree 目录。如果存在上述任何内容，Vibe 会询问是保留还是移除该 worktree。当 Vibe 创建了该分支时，它会连同 worktree 一起被删除；如果分支已经存在并且仅仅是被附加，则除非你确认删除，否则将保留该分支。保留会维持目录和分支不变，以便你以后再次访问；移除会强制删除它们，丢弃更改、未跟踪的文件和提交。编程运行（`vibe -p ... --worktree NAME`）不会自动清理，因为没有退出提示；请使用 `git worktree remove` 手动移除它们。当使用 `--setup` 和 `--check-upgrade` 时，将忽略 `--worktree`。 会话是按目录划分的，因此 `-c`/`--continue` 和 `--resume` 选择器只能看到在该 worktree 中启动的会话。要在不同 worktree 之间迁移会话，请使用 `--resume ` 显式地通过 ID 恢复它。 ### 更新设置 Vibe 在会话期间最多每天检查一次 PyPI。当发现较新的版本时，下一次启动会在打开聊天之前显示更新提示，提供立即更新（通过 `uv tool upgrade mistral-vibe` 或 `brew upgrade mistral-vibe`）或继续使用当前版本的选项。 运行 `vibe --check-upgrade` 可立即检查 PyPI，如果存在较新版本则提示安装，然后退出。 要完全禁用每日检查，请将此内容添加到你的 `config.toml` 中： ``` enable_update_checks = false ``` ### 通知设置 当 agent 需要你的关注时（等待批准、提出问题或任务完成），Vibe 可以通知你。当你切换到另一个窗口而让 agent 工作时，这非常有用。 要禁用通知： ``` enable_notifications = false ``` ### 自定义 Vibe Home 目录 默认情况下，Vibe 将其配置存储在 `~/.vibe/` 中。你可以通过设置 `VIBE_HOME` 环境变量来覆盖它： ``` export VIBE_HOME="/path/to/custom/vibe/home" ``` 这会影响 Vibe 查找以下内容的位置： - `config.toml` - 主配置文件 - `.env` - API key - `connector_bootstrap_cache.json` - 短期的连接器发现缓存 - `agents/` - 自定义 agent 配置 - `prompts/` - 自定义 system 和 compaction prompt - `tools/` - 自定义工具 - `logs/` - 会话日志 ## 编辑器/IDE Mistral Vibe 可以在支持 [Agent Client Protocol](https://agentclientprotocol.com/overview/clients) 的文本编辑器和 IDE 中使用。有关各种编辑器和 IDE 的设置说明，请参阅 [ACP 设置文档](docs/acp-setup.md)。 ## 资源 - [更新日志](CHANGELOG.md) - 了解每个版本中的新功能 - [贡献指南](CONTRIBUTING.md) - 功能请求、反馈和错误报告的指南 ## 数据收集与使用 使用 Vibe 受我们的[隐私政策](https://legal.mistral.ai/terms/privacy-policy) 约束，并可能包括收集和处理与你的服务使用情况相关的数据（例如使用数据），以便运行、维护和改进 Vibe。你可以在你的 `config.toml` 中通过设置 `enable_telemetry = false` 来禁用遥测和崩溃报告。 ## 许可证 版权所有 2025 Mistral AI 根据 Apache License, Version 2.0（“许可证”）获得许可； 除非遵守许可证，否则你不得使用此文件。 你可以从以下网址获取许可证副本： ``` http://www.apache.org/licenses/LICENSE-2.0 ``` 除非适用法律要求或书面同意，否则根据许可证分发的软件 均按“原样”提供，不附带任何明示或暗示的保证或条件。 有关完整的许可证文本，请参阅 [LICENSE](LICENSE) 文件。

标签：AI编程助手, API密钥扫描, DLL 劫持, Mistral, Python, Python安全, SOC Prime, 大语言模型, 开发工具, 无后门, 逆向工具