IDE Companion 协议

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

This page has not been translated into English yet. The original Chinese version is shown below.

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

服务发现与认证

QWEN_CODE_IDE_SERVER_PORT 指向 ~/.qwen/ide/.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 让多个选区都成为当前焦点。

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 使用。协议文档标注的最后更新时间较早，开发新实现还应对照目标 CLI 版本，而不是把它当永久冻结协议。