knowledge-interaction-surfaces-vscode-bridge

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)