---
name: knowledge-interaction-surfaces-vscode-bridge
description: >
  覆盖 Blade VS Code 扩展的激活、WebSocket RPC、端口发现、编辑器/选区/诊断/Diff
  操作和扩展打包。进入时机：修改 IDE 桥协议、`/ide` 连接、状态栏、端口文件、VS Code
  命令或 VSIX 构建。 不包含：ACP 标准宿主集成（见 ../acp-host-integration/）、LSP
  Session 智能（见 ../../extension-ecosystem/lsp-code-intelligence/）。关键词：
  blade-vscode, BLADE_IDE_PORT, ide-port, WebSocketServer, openFile, openDiff,
  getDiagnostics, /ide。
---

## Module Structure

VS Code 扩展是独立于 ACP 的轻量编辑器桥：扩展进程启动 WebSocket server，CLI 通过环境
变量或端口文件发现它，RPC 直接调用 VS Code API。

### Directory Layout
- `packages/vscode/src/extension.ts` — 扩展激活、WebSocket 生命周期与全部 RPC handler
- `packages/vscode/package.json` — 激活事件、命令、设置、构建和打包入口
- `packages/vscode/README.md` — 当前公开 RPC 和安装方式
- `packages/vscode/TODO.md` — 已知稳定性缺口与后续能力边界
- `packages/cli/src/slash-commands/ide.ts` — CLI 端口发现、连接探测和安装提示
- `packages/cli/src/ide/` — IDE 环境检测与扩展安装命令

### Key Entry Points
- `activate()` in `packages/vscode/src/extension.ts` — 注册 start/stop/status 并按配置自动启动
- `startServer()` in `packages/vscode/src/extension.ts` — 建立 WebSocket、写端口文件和终端环境配置
- `handleMessage()` in `packages/vscode/src/extension.ts` — RPC method 分派
- `handleConnect()` in `packages/cli/src/slash-commands/ide.ts` — CLI 侧发现并探测扩展端口

## Gotchas
- VS Code 桥不是 ACP：它使用自定义 WebSocket `{id, method, params}` 协议，不能把 ACP Session 方法或能力协商假设套到该连接 (`packages/vscode/src/extension.ts`, `packages/cli/src/acp/index.ts`)
- `/ide connect` 只建立一次 WebSocket 探测后立即关闭，却把模块级状态记为 connected；该状态不是持久连接健康度，也不会驱动后续 RPC (`packages/cli/src/slash-commands/ide.ts`)
- 当前 CLI 只实现端口发现和连接探测，仓库中没有消费 `openFile`、`openDiff`、selection 或 diagnostics RPC 的长连接客户端；扩展公开能力不能等同于 Agent 已接入能力 (`packages/cli/src/slash-commands/ide.ts`, `packages/vscode/src/extension.ts`)
- 端口发现先读 `BLADE_IDE_PORT`，再读单一 `~/.blade/ide-port`；多窗口会覆盖同一文件，CLI 也不会按 workspace 选择实例 (`packages/cli/src/slash-commands/ide.ts`, `packages/vscode/src/extension.ts`, `packages/vscode/TODO.md`)
- WebSocket server 未配置 host、认证或 origin 校验，消息参数使用 `any` 且无 schema；在扩大功能或网络暴露前必须先补协议校验与访问边界 (`packages/vscode/src/extension.ts`, `packages/vscode/TODO.md`)
- `openFile.options.line` 是 1-based 并在调用 VS Code API 前减一，而 selection/diagnostic 返回值是 VS Code 原生 0-based；调用方不能混用坐标系 (`packages/vscode/src/extension.ts`)
- `setTerminalEnv()` 更新的是 Workspace 级集成终端配置且异步 Promise 未等待，只影响之后创建的终端；当前终端仍依赖扩展进程环境或端口文件 (`packages/vscode/src/extension.ts`)
- `stopServer()` 删除全局端口文件但不验证其中 pid/port 是否仍属于当前窗口；这与单文件多窗口限制是同一个生命周期风险 (`packages/vscode/src/extension.ts`, `packages/vscode/TODO.md`)

## Architecture
- 扩展在 `onStartupFinished` 激活，状态栏同时作为状态展示和 `blade-code.status` 命令入口；`autoStart` 默认开启 (`packages/vscode/package.json`, `packages/vscode/src/extension.ts`)
- 单个扩展实例维护一个 WebSocketServer 和 client Set，每条请求独立响应 `{id,result}` 或 `{id,error}`；JSON 解析失败的响应使用 `id: null` (`packages/vscode/src/extension.ts`)
- RPC 只提供编辑器控制与观察：打开文件、列出 tab、读取选区/工作区/诊断、打开已有文件 diff 和显示通知，不拥有 Agent 或 Session 生命周期 (`packages/vscode/src/extension.ts`, `packages/vscode/README.md`)
- 扩展端把实际端口、进程 ID、启动时间和 workspaceFolders 写入 JSON 端口文件；CLI 目前只消费 port 和首个 workspace 展示 (`packages/vscode/src/extension.ts`, `packages/cli/src/slash-commands/ide.ts`)

## Decisions
- 扩展以 esbuild 打包为 Node CommonJS，并将 `vscode` 标为 external；VSIX 构建不复用 CLI/Vite bundle (`packages/vscode/package.json`, `packages/vscode/tsconfig.json`)
- 该桥保留为基础 RPC 原型，聊天、事件订阅、编辑应用、终端与协议版本化仍明确列在后续计划中；新增能力不应假设这些基础设施已经存在 (`packages/vscode/TODO.md`)

## Patterns
- start/stop/status 共享模块级 server 状态，重复 start 只提示当前端口，stop 会关闭全部 client、server、环境变量和端口文件 (`packages/vscode/src/extension.ts`)
- 编辑器数据统一返回文件系统路径而非 URI 字符串，diff 输入也要求两个本地路径；远程工作区支持需要重新定义该契约 (`packages/vscode/src/extension.ts`)
- IDE 检测与安装走 `code`、`code-insiders`、`cursor` CLI，不通过扩展 WebSocket；命令不存在时按未安装处理 (`packages/cli/src/ide/detectIde.ts`, `packages/cli/src/ide/ideInstaller.ts`)

## Dependencies
- 扩展运行依赖 VS Code Extension API 与 `ws`；开发和打包依赖 esbuild、TypeScript 与 `@vscode/vsce` (`packages/vscode/package.json`)