# IDE Companion 协议

> 实现端口发现、逐请求认证、上下文通知与异步 diff 结果。

- 网址：https://funcoding.ai/agents/qwen-code/integrations/companion-protocol/
- 核实日期：2026-10-08（命令、配置和价格以官方文档为准）
- 官方来源：[Qwen Code 官方文档：IDE Companion Specification](https://github.com/QwenLM/qwen-code/blob/main/docs/users/ide-integration/ide-companion-spec.md)

---
这是开发编辑器 Companion 的接口契约，不是 ACP 配置。插件运行本地 HTTP MCP 服务，使用动态端口（监听 port 0），并在集成终端注入该实际端口。

## 服务发现与认证

QWEN_CODE_IDE_SERVER_PORT 指向 ~/.qwen/ide/<PORT>.lock。插件创建目录和 JSON 文件，包含 port、workspacePath、authToken、ppid、ideName。

workspacePath 是工作区绝对根路径列表，Linux/macOS 用冒号分隔，Windows 用分号；CLI 当前目录不在任一工作区内会拒绝连接。ppid 按规范记录 IDE 进程的父进程 ID。

每次启动生成唯一秘密 authToken。CLI 在每个请求附 Authorization: Bearer，服务端必须每次验证，不能只在握手检验。旧于 v0.5.1 的临时目录发现文件仅供兼容，新实现不依赖它们。

## 上下文通知

ide/contextUpdate 可在文件打开、关闭、聚焦、光标或选择变化时发送，官方建议防抖 50ms。

workspaceState 下可有 openFiles 和 isTrusted。每项文件包含绝对 path、最近聚焦 Unix timestamp，可附 isActive、cursor.line/character 和 selectedText；光标坐标从一开始。

只包括磁盘实际存在文件。CLI 按 timestamp 排序，只把最近项作为活动文件，其余 cursor/selection 会清除；最终截到十个文件和 16KB 选区。插件本身也应限量，不能通过多次 isActive:true 让多个选区都成为当前焦点。

## 打开 diff 与结果是两件事

openDiff 接收 filePath 和 newContent。成功打开后立即返回 content:[]，失败则 isError:true 加错误文字；这个确认只说明视图已打开，不能当作用户接受。

接受后异步发送 ide/diffAccepted，含 filePath 与最终完整 content。用户可能在界面改过内容，因此最终 content 不一定等于原 newContent。拒绝则发 ide/diffRejected，带 filePath。

closeDiff 接收 filePath，成功时返回单个 TextContent，内容是关闭前的最终文件文本；失败返回 isError:true 与说明。实现 diff 能力时需按规范注册 openDiff/closeDiff 并处理这些结果。

## 生命周期

激活先启动 MCP，再创建发现文件；停用先停止服务并删除发现文件。不能让退出后的旧 lock 继续指向被其他进程复用的端口，也不能把“lock 文件存在”当作服务仍活跃的唯一证据。

用户侧行为见[Companion 使用](https://funcoding.ai/agents/qwen-code/integrations/ide-companion/)。协议文档标注的最后更新时间较早，开发新实现还应对照目标 CLI 版本，而不是把它当永久冻结协议。