Cline 开源贡献开发指南：Bun 单体仓库中的本地开发、测试与 PR 提交全流程

本文基于 Cline 仓库根目录的 CONTRIBUTING.md 整理并扩展，面向准备参与 Cline 开源贡献的开发者：读完你可以完整掌握从克隆仓库、安装 Bun 工具链、生成 Protocol Buffer 文件到 F5 调试启动 VS Code 扩展的本地开发环境搭建方法，以及单元/集成/Playwright E2E 三层测试体系与代码质量提交规范，能够独立完成一个符合 Cline CI 要求的高质量 Pull Request。

仓库结构与技术栈前提

Cline 是一个以 Bun workspace 组织的单体仓库（monorepo）。从根目录 package.json 可以看到，workspaces 字段纳入了以下主要代码区：

• sdk/packages/*：SDK 核心包（@cline/core、@cline/agents、@cline/llms、@cline/shared 等）；
• apps/*：各应用形态，包括 VS Code 扩展（apps/vscode）、CLI（apps/cli）、Cline Hub（apps/cline-hub）及示例应用（apps/examples/*）；
• apps/vscode/webview-ui、sdk/examples 等也作为独立 workspace 参与依赖管理。

环境版本有明确约束：根 package.json 中 engines 声明 bun: 1.3.13、node: >=22，且 packageManager 字段固定为 bun@1.3.13。因此开发前需先安装 Bun 运行时。VS Code 扩展本体位于 apps/vscode/package.json，包名为 claude-dev、显示名 Cline，engines.vscode 要求 ^1.101.0。

贡献行为方面，所有成员须遵守仓库的 CODE_OF_CONDUCT.md。

Issue 先行：Bug 报告与功能贡献流程

按照 CONTRIBUTING.md 的约定，贡献流程有明确的“Issue 先行”原则：

Bug 报告

• 提交前先在仓库 issues 中搜索是否已存在同类问题，避免重复提交；
• 使用仓库提供的 issue 模板填写复现步骤与环境信息；
• 安全漏洞属于特例：不应在公开 issues 中暴露，而应通过 GitHub 的私有安全通告（security advisories）渠道提交。

功能与新特性

• 除小型 bug 修复、错别字、措辞微调、简单类型修复等不影响功能的小改动外，所有贡献都必须先创建 GitHub Issue；
• 特性类贡献先在 Discussions 的 Feature Requests 板块确认是否已有同类想法，若为新想法则创建功能请求；
• 必须等待核心维护者批准后才可以开始实现；
• 未经批准的 Issue 直接开 PR，可能会被直接关闭。

寻找切入点

• 新手可以从带 good first issue 或 help wanted 标签的 issue 入手，这些是维护者专门为新贡献者挑选的任务；
• 文档贡献始终被欢迎：仓库的 docs/ 目录包含 CLI、SDK、企业方案、Provider 配置等 Mdx 文档，修错别字、改进现有指南、新增教程都可以作为起点。

本地开发环境搭建

标准安装步骤

CONTRIBUTING.md 给出的开发环境初始化流程如下（需要 git-lfs 支持）：

# 1. 克隆仓库
git clone https://github.com/cline/cline.git

# 2. 用 VS Code 打开项目
code cline

# 3. 安装 bun（https://bun.com）

# 4. 安装扩展与 webview 依赖，并构建 SDK
cd apps/vscode && bun run install:all && cd ../..
cd sdk && bun run build && cd ..

# 5. 生成 Protocol Buffer 文件（首次构建前必须执行）

# 6. 按 F5（或 Run -> Start Debugging）启动，VS Code 会新开一个加载了扩展的窗口

关于第 6 步的补充：调试配置由仓库根目录下的 .vscode/launch.json 提供；如果构建过程中 esbuild 报错，文档提示可能需要安装 esbuild problem matchers 扩展。

关键脚本与源码对应关系

结合 apps/vscode/package.json 中的 scripts 字段，可以精确理解文档中每条命令背后的实际动作：

命令	实际执行内容	作用
bun run install:all	bun install	安装扩展及 workspace 依赖
bun run protos	node scripts/build-proto.mjs	生成 Protocol Buffer 文件，首次构建前必需
bun run dev	bun run protos && bun run watch	生成 protos 后进入 watch 模式（推荐终端工作流）
bun run watch	并行执行 watch:esbuild（esbuild.mjs --watch）与 watch:tsc（tsc --noEmit --watch）	增量编译 + 类型监听
bun run test	bun run test:unit && bun run test:integration	先跑 Bun 单元测试，再跑 vscode-test 集成测试
bun run test:unit	bun scripts/run-bun-unit-tests.ts	运行单元测试
bun run test:integration	bun run compile-tests && vscode-test	编译测试代码后以 VS Code 测试宿主运行
bun run lint	biome lint ... && bun run lint:proto	Biome 代码风格检查 + proto 文件 lint
bun run format:fix	biome check ... --changed --since main --write	自动格式化相对 main 变更的文件
bun run ci:check-all	并行执行 check-types lint format	与 CI 门禁一致的全量检查

由此可以还原推荐的终端开发工作流（文档原文为 "Terminal Workflow"）：

• 首次开发用 bun run dev（生成 protos + watch 模式）；
• protos 已生成后用 bun run watch 即可。

Protocol Buffer 生成细节

扩展与 webview 之间通过 Protocol Buffers 通信。仓库中 apps/vscode/proto/cline/ 与 apps/vscode/proto/host/ 目录下存放着 .proto 源文件。protos 脚本执行 scripts/build-proto.mjs 生成代码，并且 postprotos 钩子会自动用 Biome 格式化 src/shared/proto、src/core/controller、src/hosts/ 等生成物所在目录。这也是为什么文档强调“生成 protos 是首次构建前的强制步骤”：check-types 脚本的第一步同样会先执行 bun run protos，类型检查依赖生成产物。

推荐扩展

打开项目时 VS Code 会提示安装一组推荐扩展（清单维护在仓库 .vscode/ 配置中）。这些扩展是开发所必需的，文档建议接受全部安装提示；如果此前忽略了弹窗，可在 Extensions 面板中手动补装。

Linux 专用系统依赖

在 Linux 上运行 VS Code 扩展的集成测试时，需要以下系统库（提供 GUI 组件与测试环境所需系统服务）：

sudo apt update
sudo apt install -y \
  dbus \
  libasound2 \
  libatk-bridge2.0-0 \
  libatk1.0-0 \
  libdrm2 \
  libgbm1 \
  libgtk-3-0 \
  libnss3 \
  libx11-xcb1 \
  libxcomposite1 \
  libxdamage1 \
  libxfixes3 \
  libxkbfile1 \
  libxrandr2 \
  xvfb

以上列表以 Debian/Ubuntu 系 apt 包名为准（其他发行版需按对应包管理器映射，如 libasound2 在新版发行版中可能是 libasound2t64 命名变体）。

测试体系：从单元测试到 Playwright E2E

单元与集成测试

• 在 apps/vscode 下运行 bun run test 即执行文档要求的“本地跑全部测试”：先是 test:unit（通过 scripts/run-bun-unit-tests.ts 调度），再是 test:integration（vscode-test 在真实 VS Code 宿主中运行集成用例）；
• 仓库根目录 package.json 的 test:unit 脚本则展示了 monorepo 级别的并行测试方式：@cline/agents、@cline/llms、@cline/core、@cline/cli、@cline/cline-hub、@cline/vscode 六个包各自并发执行 test；
• 贡献规范要求：为新功能补测试、改动影响到既有测试时必须同步更新、按场合同时覆盖单元测试与集成测试。

E2E 测试（Playwright）

Cline 使用 Playwright 编写了模拟真实用户操作 VS Code 的 E2E 测试，测试文件位于 apps/vscode/src/test/e2e/，当前包含 auth.test.ts、chat.test.ts、editor.test.ts、file-edit.test.ts、history.test.ts、hooks.test.ts 等用例，完整文档见 apps/vscode/src/test/e2e/README.md。

运行命令（对应 apps/vscode/package.json 中的脚本）：

bun run test:e2e                # 安装 Playwright 浏览器 + 打包测试 vsix + 构建 + 运行全部 E2E
bun run e2e                     # 不重建环境直接运行（playwright test -c playwright.config.ts）
bun run test:e2e -- --debug     # 进入 Playwright 交互调试器

其中 test:e2e 的完整链路为 playwright install && vsce package --no-dependencies ... && node src/test/e2e/utils/build.mjs && playwright test，即先构建一个带 Cline 扩展的测试 vsix 包，再由 Playwright 驱动一个真实 VS Code 实例。

编写 E2E 测试的约定：

• 单根工作区用例使用 e2e fixture，多根工作区使用 e2eMultiRoot fixture（定义在 utils/helpers.ts）；
• fixture 向测试注入 sidebar（Cline 侧边栏 Frame）、helper（E2ETestHelper 工具类）、page（主窗口 Page）、server（Mock API 服务）等对象；
• 基本测试骨架（摘自 E2E README）：

import { expect } from "@playwright/test"
import { e2e } from "./utils/helpers"

e2e("Test description", async ({ sidebar, helper }) => {
  await helper.signin(sidebar)

  const inputbox = sidebar.getByTestId("chat-input")
  await inputbox.fill("Hello, Cline!")
  await sidebar.getByTestId("send-button").click()

  await expect(sidebar.getByText("API Request...")).toBeVisible()
})

测试环境组成（可推断自 fixture 目录 fixtures/ 与 README 描述）：

• 自动化的 VS Code 配置：禁用更新/工作区信任/欢迎页，加载扩展开发模式，使用临时用户数据目录；
• 运行在 http://localhost:7777 的 Mock API 服务器，为 Cline 后端调用提供模拟响应（认证、chat completions、用户管理）；
• 单根与多根两种测试工作区（fixtures/workspace/、fixtures/multiroots.code-workspace 等）；
• 失败测试自动录制视频到 test-results/。

调试模式能力：--debug 会启动 Playwright Inspector，支持逐步执行、元素检查与选择器校验，也可用 Record 功能直接录制交互并自动生成测试代码；--headed 可查看可见窗口。此外还支持 --grep "Chat" 按模式过滤、指定单文件运行（bun run e2e -- auth.test.ts）；相关环境变量包括 CLINE_E2E_TESTS_VERBOSE（详细日志）、CI（调整超时与报告）、GRPC_RECORDER_ENABLED（gRPC 调用录制）。

选择器最佳实践：优先使用 getByTestId / getByRole 等语义化选择器，避免脆弱的 CSS 类名选择器；异步操作用 expect(...).toBeVisible() 等待而非固定延时。

代码质量与 PR 提交规范

格式化与 Lint

项目统一使用 Biome（配置见 apps/vscode/biome.jsonc 与根 biome.json）：

• bun run lint：检查代码风格并附带 proto lint（scripts/proto-lint.sh）；
• bun run format / bun run format:fix：检查或自动修复，默认作用于相对 main 变更的文件；
• 提交 PR 前必须执行 bun run format:fix，并处理 linter 报出的全部警告/错误，CI 的 lint 与 format 门禁不通过则无法合入；
• 根目录还有 fix 脚本（biome check --write --unsafe）可一次性修复 sdk/ 与 apps/ 下的全部问题。

提交与 PR 清单

文档给出的贡献者提交规范可归纳为：

1. PR 聚焦：一个 PR 只包含一个特性或一个 bug 修复；较大改动拆分为多个相关的小 PR；commit 按可独立评审的逻辑切分。
2. 提交信息：使用 Conventional Commits 风格前缀（feat:、fix:、docs: 等），并在 commit 中用 #issue-number 关联相关 issue。
3. 版本号与 Changelog：贡献者不需要在 PR 中创建 changelog-entry 文件，版本与 changelog 由维护者在发布流程中统一处理。
4. 提交前检查：rebase 到最新 main、确认分支可成功构建、全部测试通过、清理调试代码与临时 console 日志。
5. PR 描述：清楚说明改动内容、给出可复现的测试步骤、列出破坏性变更、UI 改动附截图。
6. 授权协议：提交 PR 即表示同意代码以项目同款的 Apache 2.0 许可证（见 LICENSE）发布。

CI 侧的检查逻辑与本地 bun run ci:check-all（并行执行 check-types、lint、format）一致，因此本地跑通这三项基本等价于通过静态检查门禁。

总结

Cline 的贡献流程可以概括为一条清晰链路：Issue 先行并获批 → 按 monorepo 约定安装依赖（install:all + sdk build + protos）→ 用 bun run dev/F5 本地调试 → 单测/集成/E2E 三层验证 → Biome 格式化与 lint 清零 → 聚焦型 PR。对新手而言，最务实的起步路径是从 good first issue 标签或 docs/ 文档改进入手，完整跑通一次 PR 流程后再进入核心代码。