4. Webview ↔ Extension 双向通信的完整设计

难度：⭐⭐⭐ | 核心素材：sidebar.tssetupMessageHandlers() + app.js/handlers.js postMessage 调用

问题背景

VS Code 扩展的 Webview 和 Extension Host 是两个独立进程，它们之间只能通过 postMessage 通信。这带来了两个挑战：

1. 异步性
   ：消息是单向推送的，没有返回值
2. 类型安全
   ：postMessage 接受 any，容易写错消息格式

CodeHi 通过一套消息类型约定 + 路由表模式解决了这两个问题。

通信架构

┌──────────────────────┐         ┌──────────────────────────┐
│   Webview (前端)       │  postMessage  │   Extension Host (后端)    │
│                       │ ◄──────────► │                           │
│  app.js               │              │  sidebar.ts               │
│  handlers.js           │              │   setupMessageHandlers()  │
│  popover.js            │              │                           │
│  modal-*.js            │              │                           │
└──────────────────────┘              └──────────────────────────┘

消息类型全景

前端 → 后端（用户操作）

后端 → 前端（状态推送）

后端：消息路由表

// sidebar.ts — setupMessageHandlers
webviewView.webview.onDidReceiveMessage(async (msg: any) => {
switch (msg.type) {

// --- 会话 ---
case'clearChat':
this.chatHistory = [];
this.saveHistoryToLocal();
            webviewView.webview.postMessage({ type: 'clearChatUI' });
return;

case'abort':
this.llmClient.abort();
return;

case'userInput':
awaitthis.handleUserInput(webviewView, msg);
return;

// --- 写入开关 ---
case'setWriteEnabled':
            tools.setWriteEnabled(msg.enabled);
            webviewView.webview.postMessage({
type: 'writeToggleState',
enabled: tools.isWriteEnabled()
            });
return;

// --- Provider 管理 ---
case'addCustomProvider':
try { awaitthis.providerManager.addCustomProvider(msg.provider); }
catch (err: any) {
                webviewView.webview.postMessage({
type: 'addProviderFailed',
error: err.message
                });
            }
return;

case'deleteCustomProvider':
try { awaitthis.providerManager.deleteCustomProvider(msg.providerName); }
catch (err: any) {
this.showSystemMessage(webviewView, '❌ 删除失败: ' + err.message, true);
            }
return;

// ... 更多 case ...
    }
});

前端：消息路由表（字符串 key）

// handlers.js
const messageHandlers = {

'clearChatUI': function(data) {
        result.innerHTML = '';
finalizeCurrentStream();
        currentAiMsgDiv = null;
        activeToolCards = {};
        refMgr.clearAllRefs();
// ...
    },

'streamChunk': function(data) {
if (!currentAiMsgDiv) return;
if (!currentAnswerDiv) {
            currentAnswerDiv = document.createElement('div');
            currentAnswerDiv.className = 'answer-content';
            currentAiMsgDiv.appendChild(currentAnswerDiv);
            streamBuffer = '';
        }
        streamBuffer += data.content;
if (!streamRafId) {
            streamRafId = requestAnimationFrame(() => {
                currentAnswerDiv.innerHTML = marked.parse(streamBuffer);
                scrollMgr.syncScrollToBottom();
            });
        }
    },

// ... 14 个 handler ...
};

window.addEventListener('message', (event) => {
const handler = messageHandlers[event.data.type];
if (handler) {
handler(event.data);
    }
// 不认识的 type 静默忽略（留给 popover.js 处理）
});

为什么用字符串 key 路由表而不是 if/else？

// ❌ if/else 链 — 难维护
if (msg.type === 'clearChatUI') { ... }
elseif (msg.type === 'streamChunk') { ... }
elseif (msg.type === 'toolCallResult') { ... }
// 30 行 if/else... 添加新类型需要找位置插入

// ✅ 字符串 key 路由表 — grep 友好
const handlers = {
'clearChatUI': function(data) { ... },
'streamChunk': function(data) { ... },
'toolCallResult': function(data) { ... },
};
// 添加新类型：加一个 key 即可
// 查找某个 handler：直接 grep 字符串
// 一眼看清支持哪些类型

关键设计细节

1. 消息无返回值，用新消息响应

// ❌ 不能这样写（postMessage 是单向的）
const result = await webview.postMessage(...);

// ✅ 正确做法：发送一条新消息作为响应
webviewView.webview.postMessage({
type: 'writeToggleState',
enabled: tools.isWriteEnabled()
});

2. 错误单独走消息通道

// 操作失败时，发送专门的系统消息
catch (err: any) {
this.showSystemMessage(webviewView, '❌ 删除失败: ' + err.message, true);
}

3. 静默忽略未知消息

const handler = messageHandlers[event.data.type];
if (handler) {
handler(event.data);
}
// 不认识的 type 静默忽略（留给其他脚本处理）

这允许 popover.js 和 handlers.js 共享同一个 message 事件，互不干扰。

4. 选区监听是持续推送

// sidebar.ts — 每次光标移动都推送
vscode.window.onDidChangeTextEditorSelection(() => {
const info = getEditorSelectionInfo();
    webviewView.webview.postMessage({
type: 'updateSelectionRef',
label: info?.path || null
    });
});

通信时序图：一次 sendMessage

User              Webview              Extension             LLM
 │                  │                     │                   │
 │ 输入+点击发送     │                     │                   │
 │─────────────────►│                     │                   │
 │                  │ postMessage          │                   │
 │                  │ {userInput}          │                   │
 │                  │────────────────────►│                   │
 │                  │                     │ resolveReferences │
 │                  │                     │ buildSystemPrompt │
 │                  │                     │ trimHistory       │
 │                  │                     │                   │
 │                  │                     │ chatAgentLoop ───►│
 │                  │ ◄── streamChunk ────│ ◄── SSE tokens ──│
 │                  │ ◄── streamChunk ────│ ◄── SSE tokens ──│
 │                  │ ◄── streamChunk ────│ ◄── SSE tokens ──│
 │                  │                     │                   │
 │                  │ ◄── toolCallResult ─│ 执行工具           │
 │                  │ ◄── toolCallResult ─│ 执行工具           │
 │                  │                     │                   │
 │                  │ ◄── requestEnd ─────│ LLM 最终回答 ◄────│
 │                  │                     │                   │
 │ ◄── 看到结果     │                     │                   │

最佳实践总结

下一篇：#5 Clean Architecture 在 VS Code 插件中的落地

💡 CodeHi 正在 VS Code Marketplace 可安装 — 一个安全的多 Provider AI 编程助手，支持写入开关、Checkpoint 回滚、25+ 工具调用。