Cline Protobuf 开发指南：从 .proto 定义到 Webview gRPC 调用的四步强类型通信层工作流

本篇基于 Cline 仓库自带的 Protobuf 开发指南（.clinerules/protobuf-development.md），完整讲解如何在 Cline 中新增一个 webview（前端）与 extension host（后端）之间通信的 gRPC 端点：包括 .proto 文件划分与命名规范、bun run protos 代码生成链路的底层实现、后端 handler 的落地位置，以及 React 侧生成式客户端的调用方式。读完你能独立走完「定义 RPC → 编译生成 → 实现后端 → 前端调用」的完整闭环，并理解每一环背后真实的源码结构。

概述：Cline 为什么用 Protobuf 定义前后端 API

Cline 使用 Protobuf 来定义 webview 与扩展宿主之间通信的强类型 API，保证高效且类型安全的跨进程通信。所有接口定义都集中在 apps/vscode/proto/ 目录中，并按两大域划分：

• cline/ 域：webview ↔ extension host 之间的业务 RPC，每个功能域一个独立 .proto 文件，目前共 18 个，如 account.proto、task.proto、ui.proto、mcp.proto、common.proto 等；
• host/ 域：Host Bridge 相关接口，如 workspace.proto、window.proto、env.proto、diff.proto 等 6 个文件。

所有 cline/ 域文件统一声明 package cline;（见 common.proto）。编译器和插件（protoc、ts-proto）均作为项目依赖内置，无需手动安装环境。

关键概念与最佳实践

文件结构：一个功能域一个 .proto 文件

指南建议每个功能域（feature domain）拥有自己的 .proto 文件，例如 account.proto、task.proto。仓库现状完全遵循这一约定：apps/vscode/proto/cline/ 下按 account、browser、checkpoints、commands、file、hooks、marketplace、mcp、models、remote_config、slash、state、task、ui、web、worktree 等域各自成文件，后端 handler 目录（apps/vscode/src/core/controller/ 下的 account、browser、checkpoints、…、ui、web、worktree 等子目录）也与之逐一对应，形成清晰的域映射。

消息设计：简单值用共享类型，复杂结构自建消息

• 简单、单值数据：统一使用 proto/cline/common.proto 中的共享类型。该文件定义了 EmptyRequest、Empty、StringRequest、Int64Request、BooleanRequest、Boolean、KeyValuePair 等通用消息，跨服务复用可保证一致性；
• 复杂数据结构：在所属功能域的 .proto 文件内自定义 message，例如 task.proto 中的 NewTaskRequest。

命名约定

对象	约定	实例
Service	PascalCaseService	AccountService（见 account.proto）
RPC 方法	camelCase	scrollToSettings、accountEmailIdentified
Message	PascalCase	StringRequest、KeyValuePair

服务端流式（Streaming）

当需要服务端向客户端流式推送时，在响应类型前加 stream 关键字。ui.proto 中的 UiService 是流式 RPC 的集中示例，如：

// Subscribe to partial message updates (streaming Cline messages as they're built)
rpc subscribeToPartialMessage(EmptyRequest) returns (stream ClineMessage);

// Subscribe to addToInput events (when user adds content via context menu)
rpc subscribeToAddToInput(EmptyRequest) returns (stream String);

指南原文引用了 account.proto 中的 subscribeToAuthCallback 作为流式示例；从当前仓库结构看，subscribeTo* 命名的流式订阅接口已成为各域 .proto 文件中的通用模式。

四步开发工作流：以 scrollToSettings 为例

以下完整走一遍指南给出的 scrollToSettings 示例，并补充每一步在仓库中对应的真实产物。

第 1 步：在 .proto 文件中定义 RPC

把新方法加到 apps/vscode/proto/ 下对应功能域的文件。以 ui.proto 为例：

service UiService {
  // ... other RPCs
  // Scrolls to a specific settings section in the settings view
  rpc scrollToSettings(StringRequest) returns (KeyValuePair);
}

这里使用了 common.proto 的通用消息：请求为 StringRequest（携带待滚动到的设置区块 ID），响应为 KeyValuePair（key 标识动作、value 携带参数），供 UI 侧统一消费。

第 2 步：编译定义，重新生成 TypeScript 代码

编辑完 .proto 后，运行：

bun run protos

该命令由 apps/vscode/package.json 映射到 node scripts/build-proto.mjs，真实生成链路在 build-proto.mjs 中，其执行流程为 cleanup → compileProtos → generateProtoBusSetup → generateHostBridgeClient：

1. protoc 二进制自举：protoc 取自项目依赖 grpc-tools 的捆绑二进制；若缺失（例如 bun install 跳过了 grpc-tools 的 install 生命周期脚本），脚本会自动通过 node-pre-gyp install 下载当前平台的预编译版本（见 build-proto.mjs#L47-L77），印证了指南「无需手动安装编译器」的说法；
2. 清理旧产物：先删除 src/shared/proto、src/generated 及历史上迁移过的生成文件，保证生成结果幂等（build-proto.mjs#L180-L232）；
3. 三轮 ts-proto 编译：用 globby 收集 proto/ 下全部 **/*.proto，以不同 outputServices 参数生成到不同目录（build-proto.mjs#L121-L160）：

输出目录	生成方式	用途
src/shared/proto	outputServices=generic-definitions	前后端共享的消息类型与通用服务定义
src/generated/grpc-js	outputServices=grpc-js	ProtoBus 服务端实现
src/generated/nice-grpc	outputServices=nice-grpc	Host Bridge 客户端实现（Promise 风格）

另生成 dist-standalone/proto/descriptor_set.pb 描述符集合（--include_imports）。核心 ts-proto 参数为：env=both,esModuleInterop=true,outputServices=generic-definitions,outputIndex=true,useOptionals=none,useDate=false（build-proto.mjs#L106-L113），其中 useOptionals=none 意味着标量与 message 字段除显式 optional 外均为必填； 4. 代码风格统一：package.json 中 postprotos 钩子会运行 biome 对 src/shared/proto、src/core/controller、src/hosts/、webview-ui/src/services、src/generated 做格式化，使生成代码与仓库风格一致。

两个适用前提值得注意：脚本支持 -v/--verbose 查看完整 protoc 命令行；在 macOS Apple Silicon 上，npm 版 protoc 不兼容 ARM64，脚本会检测 Rosetta 2，缺失时提示执行 softwareupdate --install-rosetta --agree-to-license 后重试（build-proto.mjs#L234-L262）。这些生成文件禁止手工编辑。

第 3 步：实现后端 Handler

Handler 按服务名分目录放在 apps/vscode/src/core/controller/[service-name]/ 下。scrollToSettings 的实现见 scrollToSettings.ts：

import { KeyValuePair, StringRequest } from "@shared/proto/cline/common"
import { Controller } from ".."

/**
 * Executes a scroll to settings action
 * @param controller The controller instance
 * @param request The request containing the ID of the settings section to scroll to
 * @returns KeyValuePair with action and value fields for the UI to process
 */
export async function scrollToSettings(_controller: Controller, request: StringRequest): Promise<KeyValuePair> {
	return KeyValuePair.create({
		key: "scrollToSettings",
		value: request.value || "",
	})
}

签名约定固定：(controller: Controller, request: <ReqType>) => Promise<<ResType>>，与 .proto 中 RPC 的请求/响应类型严格对应。从源码结构看，当前版本的 Controller 并非本地定义，而是由 SDK 适配层提供——controller/index.ts 直接 export { Controller } from "@/sdk/SdkController"，并注释说明这些 handler 模块充当 webview 与 SDK 之间的「thunking 层」；因此新增 handler 时，类型与实例均来自该 SDK 适配层。

第 4 步：在 Webview 中调用 RPC

在 webview-ui/ 的 React 组件里调用生成客户端即可，指南示例位于 webview-ui/src/components/browser/BrowserSettingsMenu.tsx：

import { UiServiceClient } from "../../../services/grpc"
import { StringRequest } from "../../../../shared/proto/common"

// ... inside a React component
const handleMenuClick = async () => {
    try {
        await UiServiceClient.scrollToSettings(StringRequest.create({ value: "browser" }))
    } catch (error) {
        console.error("Error scrolling to browser settings:", error)
    }
}

实际仓库中的导入路径以 @/services/grpc-client 等别名形式引用生成客户端（如 ClineAccountInfoCard.tsx 中 import { UiServiceClient } from "@/services/grpc-client"）。客户端基类 grpc-client-base.ts 中的 ProtoBusClient 展示了底层通信机制：为每次请求生成 uuid 作为 requestId，通过 window.postMessage 发送，并监听类型为 grpc_response、request_id 匹配的消息，再用对应 proto 解码器还原响应——一元调用即在此完成，流式 RPC 则复用同一套事件通道持续推送。

小结：新增 RPC 的检查清单

步骤	动作	落点
1	定义 service 方法	apps/vscode/proto/cline/<domain>.proto，简单值优先复用 common.proto
2	生成代码	bun run protos（勿手改 src/shared/proto、src/generated）
3	后端 handler	apps/vscode/src/core/controller/<service-name>/<method>.ts
4	前端调用	webview-ui/ 组件中 XxxServiceClient.<method>(...)

遵循「一域一文件、共享类型复用、服务/方法/消息三套命名约定、流式用 stream 关键字」这几条规则，并对照 ui.proto 与 controller 目录 的现有实现，就能把指南中的四步工作流落到当前仓库真实的代码结构上。