编辑文档 - OpenCode 这周连发 3 个版本 v1.17.5 / v1.17.6 / v1.17.7，看着啥都没改其实全是干货

标题

工具栏

点击或拖拽上传图片

支持 PNG, JPG, GIF, WebP 格式

内容 (Markdown 格式)

OpenCode 这一周连发 3 个版本——v1.17.5、v1.17.6、v1.17.7，全是 Bugfix 为主的小版本。看着像「啥都没改」，但翻完 changelog 发现，**有几个 fix 是真影响日常使用的**。

这篇挑我用过的几个 fix 说说。

## v1.17.5：MCP 终于不假死了

这个版本最重要的修是 **MCP 会话过期恢复**。

之前用 OpenCode 接 MCP 服务器，遇到一个很烦的问题：跑一段时间后 MCP 工具列表就空了，报错 `disconnected`，但重启又好了。一直以为是 MCP 服务器不稳定，最近翻 changelog 才看到原因——MCP 会话过期后 OpenCode 没恢复，留着个空连接挂在那。

v1.17.5 改成了过期自动恢复。跑了一下午没再出现「假死」。

另一个我立刻感受到的 fix：**`$ARGUMENTS` 文件内容重复注入**。

之前在自定义命令里用 `$ARGUMENTS` 引用文件路径，文件内容会被注入两次（用 `cat` 一遍，再用文件内容再补一遍）。命令行里看着输出冗余，prompt token 也多花一倍。v1.17.5 修了这个，命令输出干净了。

剩下的 v1.17.5 fix：

- 关闭的 MCP 客户端能正确清理了，不会留 stale 连接
- MCP 工具返回结构化输出，现在能正常展示
- 重复 renderable ID 修复（之前能导致 TUI 渲染崩）
- Snowflake Cortex provider 接入外置浏览器 OAuth
- v2 桌面端的颜色主题 oc-2 更新了一版
- 终端 resize 那个细缝改宽了，鼠标拖动不那么痛苦
- 顶栏 tab 溢出改为淡出，不再生硬裁断

## v1.17.6：一个 fix 解决一类问题

这个版本 changelog 极短——就一个 fix：

> Improved MCP server compatibility by declaring OpenCode's supported client capabilities.

看着是「声明一下支持的客户端能力」，但这个 fix 影响面比想象大。

MCP 协议里客户端要声明自己支持的能力（roots、sampling、experimental 等），之前 OpenCode 的声明不完整，**部分 MCP 服务器收到不完整的客户端能力声明后，会拒绝给某些功能**——比如拒绝给文件访问、拒绝给工具调用提示。

v1.17.6 补全了声明，再接那些挑剔的 MCP 服务器就稳了。我自己用的 `mcp-ocr-server` 之前偶尔报 `client not declared roots`，更新后没再出现。

## v1.17.7：影响最大的 fix 是「会话隔离」

这个版本 fix 最多，主要影响多会话用户。

**会话隔离 fix（影响最大）**：

之前在 OpenCode 桌面端开多个会话，会话之间偶尔会「串」——新会话 A 里编辑的内容，莫名出现在旧会话 B 的 draft 里。原因是新会话的 route 没正确切到自己的 draft server，部分请求被路由到了上一个会话的服务。

v1.17.7 修了，新会话的 route 严格 scope 在自己的 draft server。**用多会话的同学强烈建议更新**。

**MCP 工作区作为根目录**：

MCP 服务器现在能收到当前工作区作为 client root。这对文件操作的 MCP 工具特别有用——之前 MCP 工具要靠 `process.cwd()` 猜工作区，现在 OpenCode 主动告诉它，**绝对路径访问不再出错了**。

**ACP shell 工具改进**：

之前 ACP 调用 shell 工具时，命令和工作目录要在工具执行一会儿后才显示。现在从一开始就显示。命令行调试体感顺滑很多。

**SDK 改进**：

- SDK 客户端在 integrations 变化时自动刷新模型和 provider 可用性
- credential update/remove 调用现在接受 `location` 参数

**MCP debug 用最新协议版本**：

之前 MCP debug 用的协议版本是旧版（2024-11-05），MCP 服务器升级协议后 debug 信息对不上。v1.17.7 切到了 SDK 最新协议版本，debug 准确了。

## 哪些 fix 是「用过才知道重要」

把这 3 个版本合起来看，真正影响日常的 fix 是这几个：

| Fix | 影响范围 | 痛点 |
|-----|---------|------|
| **MCP 会话过期恢复** | 所有用 MCP 的用户 | 跑久了 MCP 工具列表变空 |
| **`$ARGUMENTS` 不重复注入** | 写自定义命令的人 | prompt token 多花一倍 |
| **MCP 工作区作为 client root** | 写文件操作 MCP 工具的人 | 绝对路径偶尔失效 |
| **新会话 route 隔离** | 桌面端多会话用户 | 串会话，draft 内容错位 |
| **MCP 客户端能力声明补全** | 接第三方 MCP 服务器 | 部分服务器拒绝给功能 |
| **ACP shell 工具早显示命令** | 用 ACP 调试的人 | 工具执行一会儿才看到命令 |

剩下那些 fix（resize gutter 改宽、tab 淡出、颜色主题更新）属于「生活质量」类，没那么痛但加起来体验好不少。

## 关于 OpenCode 这周发了 3 个版本

值得说一句的是，**OpenCode 团队这周发版本很克制**。v1.17.5 / v1.17.6 / v1.17.7 全是 patch 版本（0 → 0 → 0 那种小修），没有夹带新功能。每个版本就解决几个真问题，发完就走。

对比某些项目一个版本能塞 50 个新 feature 再带 50 个 bug 的风格，**这种「小步快跑 + 不夹带私货」的节奏对生产环境用户友好得多**。

我自己更新策略是：minor 版本跟，patch 版本有 changelog 提到我用的功能才更。这次 3 个版本我都更了，因为里面有几条是直接影响我工作流的。

## 怎么更

桌面端自动更新，会弹窗。CLI 用户：

```bash
# macOS / Linux
curl -fsSL https://opencode.ai/install | bash

# Windows (PowerShell)
irm https://opencode.ai/install.ps1 | iex
```

更完用 `opencode --version` 确认是 v1.17.7。

## 3 个版本合并 changelog

如果想一次看完所有改动，下面是 3 个版本的合并 changelog（去重后）：

**Core / Improvements**
- Snowflake Cortex provider 接入外置浏览器 OAuth
- v2 桌面端颜色主题 oc-2 更新
- v2 项目副本管理和会话移动流程改进
- MCP 服务器能收到当前工作区作为 client root
- SDK 客户端在 integrations 变化时自动刷新模型和 provider 可用性
- credential update/remove 调用接受 `location` 参数

**Core / Bugfixes**
- MCP 会话过期自动恢复
- 关闭的 MCP 客户端正确清理
- MCP 工具返回结构化输出可读
- 重复 renderable ID 修复
- `$ARGUMENTS` 文件内容不再重复注入
- MCP 客户端能力声明补全
- Plugin client 请求复用 active server，不再假设默认本地端口
- ACP shell 工具从开始就显示命令和工作目录
- Plugin 提供的 shell 环境变量应用到 PTY sessions
- 新会话 route 严格 scope 在自己的 draft server

**TUI / Bugfixes**
- `RunCommand` fetch 请求加 auth headers
- MCP debug 切到 SDK 最新协议版本

**Desktop / Bugfixes**
- 终端 resize 细缝改宽
- 顶栏 tab 溢出淡出
- 新会话 route 隔离

社区贡献者：@verdverm、@arvsrn、@Slickstef11、@santigc6、@OpeOginni。

摘要

标签多个标签用逗号分隔

分类