编辑文档 - OpenCode v1.17.5 / v1.17.6 / v1.17.7 连发，这周碰到的几个 fix 帮了我大忙

标题

工具栏

点击或拖拽上传图片

支持 PNG, JPG, GIF, WebP 格式

内容 (Markdown 格式)

周一收到 OpenCode 桌面端弹窗更新，顺手点了。v1.17.5。

跑了一下午发现一个老问题没了——之前我接的 `mcp-ocr-server` 跑 2 小时左右工具列表会空，得手动重启会话。当天没出现，我也没多想。

周三又收到一个更新 v1.17.6。打开 changelog 看了一下，**就一行字**：

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

差点就关掉。但出于习惯我去查了查这个 fix 到底改了什么。

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

我接的那个 OCR 服务器之前偶尔报 `client not declared roots`，更新后没再出现。

周四又收到 v1.17.7。这次 changelog 长一些，看完发现有一个 fix 是真影响我。

## v1.17.7 那个 fix 让我立刻就更了

我平时桌面端习惯开两三个会话——一个写文章、一个跑实验、一个挂着查资料。

之前偶尔碰到一个诡异的事：A 会话刚改完一段 draft，切到 B 会话发现 draft 里出现了 A 的内容。我一直以为是自己复制粘贴搞错了。

v1.17.7 changelog 里有一条：

> The new session route now stays scoped to its own draft server, so prompts and state target the right workspace.

**啊，是 bug。** 新会话的 route 没正确切到自己的 draft server，部分请求被路由到了上一个会话。

修完串会话的事没了。这种 fix 不报出来我可能永远都以为是自己的手误。

## 顺便把另外两个版本也翻了

### v1.17.5 那个我自己用上的 fix

我有个自定义命令是 `cat $1 | ...`，之前用 `$ARGUMENTS` 引用文件路径，文件内容会被注入两次——用 `cat` 读一遍，再用文件内容再补一遍。命令行里输出看着很冗余，prompt token 也多花一倍。

v1.17.5 改了。

这个 fix 没记入 changelog 大字——埋在「Bugfixes」列表里：

> Fixed commands using `$ARGUMENTS` so file contents are not injected twice

要不是翻 changelog 这种小修我真不会注意到。

另一个我天天在用的修：v1.17.5 改宽了终端 resize 那个细缝。**之前鼠标拖起来真的很痛苦**，现在好多了。这条是社区贡献者提的 PR。

### v1.17.7 几个值得说的小修

**MCP 工作区作为 client root**：

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 准确了。

## 这 3 个版本教会我什么

翻完整 3 个 changelog 我才意识到，**OpenCode 团队这周发的全是 patch 版本（0 → 0 → 0），没夹带新功能**。每个版本就解决几个真问题，发完就走。

这种节奏对生产环境用户特别友好。我之前的更新策略是 minor 跟、patch 看 changelog。这次 3 个 patch 我都更了，因为里面有几条直接影响工作流——

- v1.17.5 的 `$ARGUMENTS` 修复（每天用）
- v1.17.5 的 MCP 会话恢复（每天用）
- v1.17.6 的 MCP 客户端能力声明（每天用）
- v1.17.7 的会话 route 隔离（每天用）

全是「用上了就回不去」的修。

## 怎么更

桌面端自动更新，会弹窗。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

最后贴一下合并 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。

摘要

标签多个标签用逗号分隔

分类