Gemini CLI Companion 插件接口规范

最后更新：2025 年 9 月 15 日

本文定义了 IDE Companion 插件与 Gemini CLI 的接口契约。VS Code 官方扩展已实现所有功能（原生 diff、上下文感知），若你希望为 JetBrains、Sublime 等其他编辑器开发类似能力，请遵循本规范。

I. 通信接口

Gemini CLI 与 IDE 插件通过本地通信通道交互。

1. 传输层：基于 HTTP 的 MCP

插件 必须 启动本地 HTTP 服务器并实现 Model Context Protocol (MCP)：

  • 协议：建议使用成熟的 MCP SDK；
  • 端点：可在单一端点（如 /mcp）上处理全部请求；
  • 端口：必须 监听系统动态分配的端口（绑定到 0）。

2. 发现机制：端口文件

为便于 CLI 发现 IDE 实例与端口，插件需创建“发现文件”：

  • CLI 如何寻找文件：CLI 会沿着进程树获取 IDE 的 PID，并查找包含该 PID 的文件；

  • 文件位置：os.tmpdir()/gemini/ide/，若不存在需自行创建；

  • 命名规则：gemini-ide-server-${PID}-${PORT}.json

    • ${PID}：IDE 进程 PID；
    • ${PORT}：MCP 服务器监听端口；

  • 文件内容：必须是如下 JSON：

    {
  "port": 12345,
  "workspacePath": "/path/to/project1:/path/to/project2",
  "authToken": "a-very-secret-token",
  "ideInfo": {
    "name": "vscode",
    "displayName": "VS Code"
  }
}
    • port：MCP 服务端口；
    • workspacePath：所有打开的工作区根路径（绝对路径），多路径以系统路径分隔符拆分（类 Unix 用 :, Windows 用 ;）。CLI 会检查当前目录是否在该路径列表下，否则拒绝连接；
    • authToken：随机生成的密钥，CLI 会在请求头 Authorization: Bearer <token> 中携带；插件 必须 验证该 Token；
    • ideInfo：IDE 信息，如 name: vscode，displayName: VS Code。

  • 推荐：除发现文件外，插件可在集成终端中设置 GEMINI_CLI_IDE_SERVER_PORT 环境变量，帮助多窗口场景下的连接判定。

II. 上下文接口

插件 可以 在用户操作变更时向 CLI 推送上下文信息。

ide/contextUpdate 通知

当用户活动发生变化（打开/关闭/聚焦文件、光标或选区变化等），建议（50ms 去抖）发送 ide/contextUpdate 通知，携带 IdeContext：

interface IdeContext {
  workspacePaths: string[];
  openFiles: IdeFileContext[];
}

interface IdeFileContext {
  path: string;
  isActive: boolean;
  cursor?: { line: number; column: number };
  selectedText?: string;
  timestamp: number;
}

CLI 会根据 timestamp 排序，最多保留 10 个文件，并截断选中文本至 16KB。建议插件在发送前自行限制数据大小。

III. Diff 接口

为支持交互式修改，插件需实现 diff 能力。

openDiff 工具

  • 用途：在 IDE 中打开可编辑的 diff 视图；

  • 请求体：

    interface OpenDiffRequest {
  filePath: string;    // 待修改文件绝对路径
  newContent: string;  // 建议的新内容
}

  • 响应：返回 CallToolResult；成功时 content 为空；失败时设置 isError: true 并在 content 中写明错误。

closeDiff 工具

  • 用途：关闭某个 diff 视图；

  • 请求体：

    interface CloseDiffRequest {
  filePath: string;
}

  • 响应：成功时返回文件关闭前的最终内容；失败时设置 isError: true 并写明错误。

ide/diffAccepted 通知

当用户接受修改时 必须 发送该通知，内容包含文件路径与最终内容：

{
  filePath: string;
  content: string;
}

ide/diffRejected 通知

用户拒绝修改时 必须 发送，仅需携带文件路径：

{
  filePath: string;
}

IV. 生命周期管理

插件需在 IDE 生命周期内合理管理资源与发现文件：

  • 激活（IDE 启动/插件启用）：
    1. 启动 MCP 服务；
    2. 创建发现文件；
  • 停用（IDE 关闭/插件禁用）：
    1. 停止 MCP 服务；
    2. 删除发现文件。