Matcha CLI · 0.04

Matcha CLI 0.04

发布于 2026-10-09

为编辑器接入打下 CLI 一侧的基础，扩充了 Skills、MCP 与模型上下文窗口的使用方式，并改进了终端输入、后台任务和长会话的日常体验。

这一版还修复了配置目录回归和多处服务商可用性问题。本地运行，自带 API Key，模型请求仍发往你选择的服务商。

编辑器接入

这些是 CLI 通过 ACP / stdio 提供给编辑器客户端的协议能力。IDE 插件尚未发布，客户端需要按协商结果启用相应界面。
隔离 Chat：CLI 把允许的文本文件复制到独立工作区，助手只在副本内读写，编辑器可以获取相对固定基线的变更。创建副本不会直接修改原项目。
编辑器可以接收助手的提问、选项和计划审批。取消、拒绝、无效或过期的回复不会被当作批准，也不会自动开始下一轮推理。
隔离会话支持列表、分页、按标题或摘要搜索、重命名、分支和删除。删除只清理受管理的副本，不会动原项目文件。
空闲会话可以切换模型、推理强度和允许的权限模式。恢复隔离会话时，权限重新从 Ask 开始。
文本变更支持预览、确认应用、状态查询和撤销，涵盖新增、修改和删除。应用或撤销前，CLI 会重新核对来源与文件内容；你已经继续编辑过的文件不会被直接覆盖。多文件操作不保证整体原子完成，会逐文件报告结果。
连接中断后不会自动重发上一条消息。恢复失败、会话忙碌和无效会话都会返回明确错误。

Skills 与指令 Profile

编辑器可以读取本地定义目录：Skill、指令 Profile 和子助手 Persona 的名称、说明、来源、可用状态与拒绝原因。目录不返回定义正文、原始配置或凭据。
目录沿用 CLI 的发现与优先级规则，覆盖项目、用户、已配置路径和允许的本地插件；.matcha 优先，旧目录只读兼容。
用户显式调用 Skill 时，CLI 会先检查定义版本与来源再展开指令。未知的斜杠命令不会自动变成普通推理输入。
空闲会话可以选择附加指令 Profile，在下一轮加入你选择的指令。选择会随会话恢复；定义被修改、移除或禁用后需要重新选择。Profile 不会替换系统提示词、服务商、工具、权限或工作区范围。

服务商与模型选择

新增 /context-window。当前模型声明了多个可选上下文窗口时，可以在会话中选择；/model 也可以先选窗口，再选推理强度。只有一个窗口的模型不显示该选项。
推理强度菜单使用模型目录提供的选项与推荐值，配置别名会继承相应菜单。
新增 matcha auth status --json，供编辑器读取当前服务商、凭据来源和可配置状态。返回值不含 API Key、尾号或 endpoint URL，也不代表凭据已经验证。
新增或完善逐模型的请求体大小限制、限流重试阈值、Responses API 的 reasoning_summary 和 mTLS 客户端证书配置。实际支持范围取决于对应服务商与 API。
修复显式 chat_completions 配置被同名模型覆盖，以及并发启动时模型目录缓存互相覆盖的问题。

MCP 与本地扩展

编辑器可以管理本地 stdio MCP：查看来源、启用状态、进程与工具状态和诊断结果，也可以显式添加、修改、移除、启用、禁用、重启和运行 doctor。读取状态不会启动服务器、调用工具或刷新认证。
修改需要会话空闲、配置版本最新并经过确认；项目级写入仍要求工作区信任。启用不会自动启动服务器，保存成功也不等于连接成功，两者分别报告。
MCP 环境凭据通过 matcha mcp credentials 在隐藏的终端输入中录入。取消时不会提交暂存值，配置快照也不公开命令参数、环境值、URL、header 或 OAuth 材料。
HTTP MCP 可以配置 bearer_token_file，每次请求重新读取 token 文件，方便轮换凭据。
普通会话里的 MCP 支持多轮提问和结构化 JSON 工具结果；取消或超时时会通知服务器停止工作。内置工具与 MCP 工具重名时，内置工具优先。
修复本地插件 hooks 在新会话中需要额外 reload、助手定义中的 MCP 配置被普通配置覆盖，以及 Skill 刷新后模型仍使用旧列表的问题。

助手、长任务与工作树

新增 matcha worktree create [name] [--ref REF]，先创建受管理的工作树，再自己进入或启动会话。matcha -p 支持 --worktree。
子助手可以继承父模型，并可在 /settings 中配置；允许的本地自定义助手定义可以用来显式创建子助手。
插话可以打断子助手的长时间等待，界面也更清楚地区分插话、排队和引导消息。主助手会先回应插话，再继续原任务。
后台 shell 命令显示为带实时输出的任务行，恢复会话时会带回后台任务状态。修复重复提醒、前台命令被误报为后台任务，以及关闭会话后取消状态不对的问题。
上下文压缩会保留最近消息和此前图片的引用；因限流失败的压缩可以重试，/compact 的附加说明会传给压缩后端。长会话清理也会保留仍被引用的压缩检查点，降低恢复和回退时缺失历史的风险。
多个并行工具修改同一文件时按顺序执行，其余无冲突的工具继续并发。

终端体验

新增 terminal 主题，使用终端自身的前景色和透明背景。/theme 搜索认得透明、深色、系统等别名。
Ctrl+P 可以在欢迎页直接打开命令面板；Tab 在输入框、滚动区和 dock 之间切换，Ctrl+G 显示或隐藏 dock。欢迎页输入框随多行内容增高。
/btw 可以在消息中途识别侧问，并保留随附的图片。
改进软换行后的上下移动、排队消息编辑后的焦点和草稿取回后的光标位置。
修复粘贴了错误图片、输入法提交时附带旧剪贴板图片，以及图片在全屏重绘或历史取回后丢失的问题；无法发送的附件会给出提示。
文件编辑 diff 显示真实行号，权限提示会自动展开待编辑内容。长命令参数可以换行，计划评论可以直接删除。
改进 Markdown 表格链接、标题颜色、Swift 高亮与 Mermaid 复杂图表的显示；大文件的语法高亮占用更少内存。
/memory 面板可以搜索笔记正文，窄终端下显示更好。
减少 tmux 和空闲 Dashboard 的重复绘制，滚动、后台任务刷新和终端输出阻塞时响应更快。

行为变化

Esc 不再取消正在执行的一轮，界面提示改用 Ctrl+C。matcha -p 被中断时会做会话收尾并返回相应退出码。
/loop 的定时任务统一在后台运行，不再向当前对话插入定时轮次。
权限模式 Auto 在 TUI 中显示为 Auto-review。进入和退出计划模式时，会继续显示并恢复原来的权限状态。
源码工具链升级到 Rust 1.94.0。

发布前修复

配置目录回归：同步上游后，运行时配置读取，以及 mcp add、服务商选择、设置保存等写入，一度改走旧目录，忽略了 ~/.matcha/config.toml 和 MATCHA_HOME。现已恢复：当前配置只从 MATCHA_HOME 或 ~/.matcha 读取和写入，旧目录仅用于一次性复制迁移，不会被写入或删除。项目级 mcp add 写入 .matcha/config.toml。
服务商可用性（0.03 已存在）：无头 -p、ACP 和 TUI 曾拒绝通过 matcha login 或官方环境变量配置的 OpenAI、Anthropic、Google、OpenAI-compatible Key，也拒绝无需 Key 的 Ollama 与 LM Studio，并提示没有配置服务商。现在与推理实际使用的凭据保持一致。
服务商级 Key（0.03 已存在）：[model_providers.<id>] 里的 api_key / env_key，包括自定义 OpenAI-compatible 服务商与 xAI，现在用于目录模型的推理，与模型目录请求使用同一份凭据；[model.<id>] 级凭据仍然优先。选择非 xAI 服务商时，不再探测、广播或发送环境中的 XAI_API_KEY。
xAI 推理地址（0.03 已存在）：通过 Key 选中 xAI 时，MATCHA_MODELS_BASE_URL 与 MATCHA_XAI_API_BASE_URL 现在会生效，请求不再回落到公共 xAI 地址。显式的 [model_providers.xai] base_url 仍然优先。
无头退出码（0.03 已存在）：工具需要审批而 -p 无法询问时，这一轮现在以退出码 1 结束，并在 stderr 说明需要审批的工具；输出格式不变。
会话标题模型（0.03 已存在）：没有选择 xAI、也没有配置 session_summary_model 时，会话标题改用当前会话模型，不再向其他服务商发送 xAI 模型 ID。
matcha trace 与 matcha setup 明确说明上传和托管配置在本构建不可用。模型不再获得反馈发送和图像、视频生成工具。

从旧版本升级

已安装 0.03 的官方安装，可以运行 matcha update --check 查看本版，再通过 matcha update（或在 TUI 中 /update 后确认）安装。Matcha 不会自动下载或安装。
用户数据继续位于 ~/.matcha（或 MATCHA_HOME）。Linux、Windows 与 macOS Intel 仍是尽力支持，本版没有新增平台支持声明。