mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-23 08:45:50 +00:00
351 lines
8.7 KiB
Markdown
351 lines
8.7 KiB
Markdown
# VSCode IDE Bridge 设计文档
|
||
|
||
**日期：** 2026-04-07
|
||
|
||
## 1. 背景
|
||
|
||
当前仓库已经具备一套较完整的 IDE 接入链路：
|
||
|
||
- CLI 能发现 `ws-ide` / `sse-ide` 类型的 IDE 连接
|
||
- CLI 能接收 `selection_changed` 并将其注入为 `<ide_selection>` 上下文
|
||
- CLI 能调用 `openDiff`、`close_tab`、`closeAllDiffTabs` 等 IDE RPC
|
||
- `/ide`、diff 预览、选区提示、已打开文件提示都依赖这套链路
|
||
|
||
但当前仓库中没有可直接使用的 VSCode 扩展实现，导致本地 VSCode 无法真正把这些能力提供给 CLI。目标不是重做一个聊天面板，而是补齐一个兼容现有 CLI 协议的 VSCode 扩展，让 CLI “像连接到原生 IDE 扩展一样”工作。
|
||
|
||
## 2. 目标
|
||
|
||
构建一个独立的 VSCode 扩展，在本地暴露一个与当前 CLI 兼容的 `ws-ide` 服务，完成以下能力：
|
||
|
||
1. 让 CLI 能自动发现 VSCode
|
||
2. 让 VSCode 当前文件和选区变化能进入 CLI 的 IDE 上下文链路
|
||
3. 让 CLI 发起的 diff 预览能在 VSCode 中打开和关闭
|
||
4. 保持实现最小、可调试、可逐步扩展
|
||
|
||
## 3. 非目标
|
||
|
||
第一版明确不做以下内容：
|
||
|
||
- 不实现 VSCode 聊天面板
|
||
- 不接入远程工作区、Codespaces、Dev Container、SSH Remote
|
||
- 不兼容多台机器之间的桥接
|
||
- 不实现复杂的会话恢复或扩展端持久化缓存
|
||
- 不覆盖官方扩展的所有功能
|
||
|
||
## 4. 总体方案
|
||
|
||
采用“独立 sidecar 扩展 + 本地 WebSocket IDE Bridge”的方式。
|
||
|
||
### 4.1 连接模型
|
||
|
||
VSCode 扩展启动后：
|
||
|
||
1. 在 `127.0.0.1` 上启动一个随机可用端口的 WebSocket 服务
|
||
2. 生成与 CLI 现有 IDE 发现逻辑兼容的 lockfile
|
||
3. 等待 CLI 以 `ws-ide` MCP 客户端身份连接
|
||
4. 扩展在该 WebSocket 连接上暴露 MCP Server，负责把 IDE 事件推送给 CLI，并响应 CLI 发来的 MCP tool 调用
|
||
|
||
### 4.2 复用现有 CLI 能力
|
||
|
||
扩展尽量不改 CLI 的上层交互，只复用现有协议：
|
||
|
||
- VSCode -> CLI：`selection_changed`、`ide_connected` 通知
|
||
- CLI -> VSCode：通过 MCP tool 调用 `openDiff`、`close_tab`、`closeAllDiffTabs`
|
||
|
||
这样可以最大化复用：
|
||
|
||
- `src/hooks/useIdeSelection.ts`
|
||
- `src/utils/attachments.ts`
|
||
- `src/utils/messages.ts`
|
||
- `src/hooks/useDiffInIDE.ts`
|
||
- `/ide` 命令及 IDE 状态展示
|
||
|
||
## 5. 协议设计
|
||
|
||
### 5.1 Lockfile
|
||
|
||
扩展写出的 lockfile 需要满足 CLI 的 IDE 自动发现逻辑。内容至少包含：
|
||
|
||
- `workspaceFolders`
|
||
- `pid`
|
||
- `ideName`
|
||
- `transport: "ws"`
|
||
- `runningInWindows`
|
||
- `authToken`
|
||
|
||
文件名使用端口号，例如 `<port>.lock`。
|
||
|
||
### 5.2 鉴权
|
||
|
||
扩展启动时生成一次随机 `authToken`：
|
||
|
||
- 写入 lockfile
|
||
- CLI 连接 `ws-ide` 时通过 `X-Claude-Code-Ide-Authorization` 头带上
|
||
- 扩展端校验成功后才允许建立 MCP/WebSocket 会话
|
||
|
||
第一版只允许本地回环地址，不暴露到公网。
|
||
|
||
### 5.3 VSCode -> CLI 通知
|
||
|
||
#### `selection_changed`
|
||
|
||
在下列事件触发后发送：
|
||
|
||
- `window.onDidChangeTextEditorSelection`
|
||
- `window.onDidChangeActiveTextEditor`
|
||
- 扩展激活完成后的初始同步
|
||
|
||
消息字段包含：
|
||
|
||
- `selection.start.line`
|
||
- `selection.start.character`
|
||
- `selection.end.line`
|
||
- `selection.end.character`
|
||
- `text`
|
||
- `filePath`
|
||
|
||
若当前没有活动选区：
|
||
|
||
- `selection` 允许为 `null`
|
||
- 仍尽量发送 `filePath`
|
||
|
||
这样 CLI 至少可以知道“用户当前打开的是哪个文件”。
|
||
|
||
### 5.4 CLI -> VSCode MCP tools
|
||
|
||
#### `openDiff`
|
||
|
||
入参：
|
||
|
||
- `old_file_path`
|
||
- `new_file_path`
|
||
- `new_file_contents`
|
||
- `tab_name`
|
||
|
||
行为：
|
||
|
||
- 读取当前磁盘文件内容作为左侧内容
|
||
- 使用临时文档或内存文档构造右侧内容
|
||
- 在 VSCode 中打开 diff 视图
|
||
- 记录 `tab_name -> 资源引用` 映射
|
||
|
||
#### `close_tab`
|
||
|
||
入参：
|
||
|
||
- `tab_name`
|
||
|
||
行为：
|
||
|
||
- 根据映射关闭对应 diff 视图
|
||
- 清理映射与临时资源
|
||
|
||
#### `closeAllDiffTabs`
|
||
|
||
行为：
|
||
|
||
- 关闭所有由本扩展打开的 diff 标签
|
||
- 清理内部状态
|
||
|
||
## 6. 扩展内部结构
|
||
|
||
建议新增独立包：`packages/vscode-ide-bridge`
|
||
|
||
目录结构如下：
|
||
|
||
```text
|
||
packages/vscode-ide-bridge/
|
||
package.json
|
||
tsconfig.json
|
||
src/
|
||
extension.ts
|
||
server/
|
||
bridgeServer.ts
|
||
lockfile.ts
|
||
workspaceInfo.ts
|
||
selectionPublisher.ts
|
||
diffController.ts
|
||
protocol.ts
|
||
util/
|
||
randomToken.ts
|
||
disposables.ts
|
||
test/
|
||
selectionPublisher.test.ts
|
||
lockfile.test.ts
|
||
bridgeServer.test.ts
|
||
diffController.test.ts
|
||
```
|
||
|
||
各模块职责如下：
|
||
|
||
- `extension.ts`
|
||
VSCode 扩展入口，负责激活、停用、启动 bridge、注册命令。
|
||
|
||
- `bridgeServer.ts`
|
||
本地 WebSocket 服务与消息路由层，负责握手、鉴权、连接管理，以及把单个 WebSocket 连接桥接为 MCP transport。
|
||
|
||
- `lockfile.ts`
|
||
负责写 lockfile、更新 lockfile、删除 lockfile。
|
||
|
||
- `workspaceInfo.ts`
|
||
负责采集工作区目录、平台信息、活动编辑器文件路径。
|
||
|
||
- `selectionPublisher.ts`
|
||
监听 VSCode 编辑器事件，并把选区信息转换为 `selection_changed`。
|
||
|
||
- `diffController.ts`
|
||
处理 `openDiff` / `close_tab` / `closeAllDiffTabs` 这三个 MCP tools，维护临时资源和 tab 映射。
|
||
|
||
- `protocol.ts`
|
||
统一定义扩展端需要识别和发送的消息结构，避免字符串散落。
|
||
|
||
## 7. 命令与可观察性
|
||
|
||
虽然主流程是自动连接，但第一版仍建议提供两个调试命令：
|
||
|
||
- `Claude Code Bridge: Restart`
|
||
- `Claude Code Bridge: Show Status`
|
||
|
||
状态信息至少包含：
|
||
|
||
- 当前监听端口
|
||
- lockfile 路径
|
||
- 是否有 CLI 已连接
|
||
- 当前工作区数量
|
||
- 最近一次选区推送时间
|
||
|
||
另外建议注册一个 output channel：
|
||
|
||
- `Claude Code IDE Bridge`
|
||
|
||
用于输出：
|
||
|
||
- 启动日志
|
||
- 鉴权失败
|
||
- lockfile 写入失败
|
||
- diff 打开失败
|
||
- 连接断开原因
|
||
|
||
## 8. 错误处理策略
|
||
|
||
### 8.1 端口占用
|
||
|
||
- 自动尝试新的随机端口
|
||
- 更新 lockfile
|
||
- 在 output channel 中记录端口变化
|
||
|
||
### 8.2 lockfile 写入失败
|
||
|
||
- bridge 不进入 ready 状态
|
||
- 弹出 VSCode 错误通知
|
||
- output channel 记录完整错误
|
||
|
||
### 8.3 WebSocket 鉴权失败
|
||
|
||
- 拒绝连接
|
||
- 记录远端地址和失败原因
|
||
|
||
### 8.4 活动编辑器为空
|
||
|
||
- 发送空选区状态或仅跳过通知
|
||
- 不抛异常、不打断 bridge 生命周期
|
||
|
||
### 8.5 diff 打开失败
|
||
|
||
- 返回明确错误结果给 CLI
|
||
- 不留下半开的临时资源
|
||
|
||
### 8.6 扩展退出
|
||
|
||
- 关闭 WebSocket server
|
||
- 删除 lockfile
|
||
- 释放临时文档资源
|
||
- 清空 tab 映射
|
||
|
||
## 9. 测试方案
|
||
|
||
### 9.1 单元测试
|
||
|
||
覆盖以下逻辑：
|
||
|
||
- lockfile 内容生成与路径选择
|
||
- 选区对象到协议消息的转换
|
||
- tab 映射和关闭逻辑
|
||
- 鉴权令牌校验
|
||
|
||
### 9.2 集成测试
|
||
|
||
通过 Node/WebSocket 客户端模拟 CLI：
|
||
|
||
- 连接本地 bridge server
|
||
- 验证鉴权成功与失败
|
||
- 验证 `selection_changed` 是否按预期发送
|
||
- 验证 `openDiff` / `close_tab` 是否触发预期行为
|
||
|
||
### 9.3 手工验证
|
||
|
||
手工验证路径：
|
||
|
||
1. 启动 VSCode 扩展
|
||
2. 启动 `claude-code-best`
|
||
3. 执行 `/ide`
|
||
4. 确认 CLI 能识别到 VSCode
|
||
5. 在 VSCode 中选中一段代码并提问
|
||
6. 确认 CLI 能注入 `<ide_selection>`
|
||
7. 触发一次 IDE diff
|
||
8. 确认 diff 标签可打开、保存、关闭
|
||
|
||
## 10. 风险与取舍
|
||
|
||
### 10.1 MCP 完整兼容风险
|
||
|
||
仓库当前 CLI 连接 `ws-ide` 时使用的是 MCP 客户端通路，因此扩展端若实现过薄，可能在握手或工具注册阶段与 CLI 预期不一致。
|
||
|
||
**取舍：**
|
||
第一版只实现 CLI 当前实际会调用到的最小工具与通知，不尝试泛化为完整 MCP server，但协议层要留出扩展空间。
|
||
|
||
### 10.2 VSCode diff 资源回收
|
||
|
||
VSCode diff 视图不是纯命名 tab，直接按 `tab_name` 定位关闭可能和实际标签生命周期有偏差。
|
||
|
||
**取舍：**
|
||
扩展内部维护显式映射，以资源 URI 为主、`tab_name` 为辅，不依赖 UI 文本匹配。
|
||
|
||
### 10.3 多工作区与路径兼容
|
||
|
||
Windows、WSL、单根工作区、多根工作区在路径表示上会不同。
|
||
|
||
**取舍：**
|
||
第一版先以本机本地工作区为主，路径统一走绝对路径；WSL/Windows 转换尽量复用 CLI 现有约定，不在扩展端重新发明路径映射。
|
||
|
||
## 11. 分阶段交付
|
||
|
||
### 第一阶段
|
||
|
||
目标：打通本地 VSCode 与 CLI 的最小闭环。
|
||
|
||
范围：
|
||
|
||
- 启动 `ws-ide`
|
||
- 写 lockfile
|
||
- 发送 `selection_changed`
|
||
- 实现 `openDiff`
|
||
- 实现 `close_tab`
|
||
- 实现 `closeAllDiffTabs`
|
||
- 提供状态命令和日志输出
|
||
|
||
### 第二阶段
|
||
|
||
目标：增强稳定性和调试能力。
|
||
|
||
范围：
|
||
|
||
- 更细的错误提示
|
||
- 更稳定的 tab 生命周期管理
|
||
- 更多 IDE 状态信息展示
|
||
- 更完整的集成测试
|
||
|
||
## 12. 结论
|
||
|
||
推荐按本设计实现独立的 VSCode IDE Bridge 扩展，并让它完全对齐当前 CLI 已有的 `ws-ide` 连接与 IDE 上下文/差异视图协议。这样能在不大改 CLI 上层逻辑的前提下，把 VSCode 选区、当前文件和 diff 预览能力真正打通。
|