Companion 插件接口与发现文件

本页面向插件作者，依据官方标注更新于 2025-09-15 的 Companion 规范。它是本地 MCP/HTTP 接口，与 ACP stdio 接口不同；实现前应核对目标 CLI 版本。

本地服务与发现

插件启动 MCP HTTP 服务，监听动态端口（端口 0）。在 os.tmpdir()/gemini/ide/ 创建 gemini-ide-server-${PID}-${PORT}.json，PID 对应父 IDE 进程。

发现文件包含 port、workspacePath、authToken、ideInfo。workspacePath 是绝对工作区根列表，Linux/macOS 用冒号、Windows 用分号分隔；CLI 验证当前目录属于其中一个工作区。

每次请求认证

插件生成唯一秘密 authToken，CLI 在请求中发送 Authorization Bearer。服务必须逐次验证并拒绝未授权请求。示例 token 只是占位，不能在实际插件复用固定值。

推荐同时给集成终端设置 GEMINI_CLI_IDE_SERVER_PORT，作为同工作区多窗口选择依据；发现文件仍是主要机制。

上下文通知

ide/contextUpdate 可在文件打开、关闭、聚焦、光标或选区变化时发送，规范建议 50ms debounce。workspaceState 可含 openFiles 和 isTrusted。

文件含绝对 path、最近聚焦 Unix timestamp、可选 isActive、cursor 与 selectedText。cursor 行列均一基；只发送磁盘存在文件，排除无路径草稿和设置页等虚拟文档。

CLI 按 timestamp 排序，只保留最近文件的活动光标/选区，再截断为 10 文件和 16KB 选区。插件也应限制输入量。

Diff 工具

openDiff 接收 filePath 与 newContent，成功立即返回 content: []，失败返回 isError 和文字。立即返回只确认视图打开，不表示用户接受。

closeDiff 接收 filePath，成功返回关闭前最终内容的单个 TextContent；失败同样给错误。

异步接受与拒绝

用户接受后发送 ide/diffAccepted，载荷含 filePath 与最终 content，必须包含用户在 diff 中的手工修改。拒绝发送 ide/diffRejected 和 filePath。不能把最初 newContent 当成所有接受结果。

生命周期

激活时先启动服务再建立发现文件；停用时停止服务并删除文件。残留文件会影响后续发现，清理逻辑应随插件生命周期处理。