code-server 实时协作实战：用 Duckly 与 CodeTogether 扩展实现跨 IDE 结对编程

在浏览器中运行的 code-server 并非“孤岛”——借助第三方 VS Code 扩展，它完全支持多人实时协作。本篇围绕仓库文档 docs/collaboration.md 展开，讲解如何通过 Duckly 和 CodeTogether 两款扩展在 code-server 中搭建实时代码共享与结对编程环境，并结合源码说明 --install-extension、--enable-proposed-api 等关键参数的底层实现链路，读完即可在 code-server 实例上独立完成协作会话的搭建。

为什么 code-server 需要第三方扩展来协作

code-server 基于 VS Code 构建，因此可以复用 VS Code 扩展生态。官方协作方案的思路是：协作能力不在 code-server 内核中实现，而是由第三方扩展提供，code-server 只负责提供“从 Open VSX 安装扩展”和“运行扩展所需的环境开关（如 proposed API）”。

这意味着两个前提：

1. 扩展必须来自 Open VSX（code-server 默认扩展市场），而不是微软官方市场；
2. 部分扩展依赖 VS Code 的 proposed API，需要显式开启。

下面两条协作路线（Duckly、CodeTogether）都建立在这两个前提之上。

共同基础：从 Open VSX 安装扩展的机制

两种方案的安装命令看起来相似，都是：

SERVICE_URL=https://open-vsx.org/vscode/gallery \
  ITEM_URL=https://open-vsx.org/vscode/item \
  code-server --install-extension <publisher.name>

理解这条命令，需要看三处仓库实现：

默认市场指向 Open VSX。 patches/marketplace.diff 将 VS Code 的 extensionsGallery 配置覆盖为 Open VSX 的接口地址（serviceUrl、itemUrl 等），并支持通过环境变量 EXTENSIONS_GALLERY（一个 JSON 字符串）覆盖为自定义市场。src/node/main.ts 在启动时检测该变量并记录日志：

if (process.env.EXTENSIONS_GALLERY) {
  logger.info("Using custom extensions gallery")
  logger.debug(`  - ${process.env.EXTENSIONS_GALLERY}`)
}

所以安装命令里显式设置 SERVICE_URL / ITEM_URL 环境变量的写法，本质上与 EXTENSIONS_GALLERY 一样，都是告诉扩展管理器“去哪里找市场接口”。集成测试 test/integration/installExtension.test.ts 验证了这一链路：当设置 EXTENSIONS_GALLERY: "{}"（空配置）时，执行 --install-extension 会抛出 "No extension gallery service configured" 错误——即市场配置不可用时扩展安装会直接失败，这一点在排查安装问题时值得注意。

--install-extension 会派生独立的 VS Code CLI 进程。 在 src/node/main.ts 中，shouldSpawnCliProcess 通过检测 --list-extensions、--install-extension、--uninstall-extension、--locate-extension 等扩展类参数，决定走 CLI 分支：

export const shouldSpawnCliProcess = (args: UserProvidedArgs): boolean => {
  return (
    !!args["list-extensions"] ||
    !!args["install-extension"] ||
    !!args["uninstall-extension"] ||
    !!args["locate-extension"]
  )
}

命中后由 runCodeCli 加载 VS Code 模块并调用 spawnCli 执行实际的扩展安装（见 src/node/main.ts）。而 --install-extension 本身的参数定义在 src/node/cli.ts，其格式为 publisher.name，可通过 @version 指定版本（例如 vscode.csharp@1.2.3），也支持直接传入 .vsix 文件。

方案一：Duckly 实时代码共享

Duckly 提供跨 IDE 的实时代码共享，能力包括（引自 docs/collaboration.md）：

• 跨 IDE 支持（可与使用 JetBrains、VS Code 等不同 IDE 的人协作）
• 实时输入同步
• P2P 加密传输
• 语音与音频聊天
• 终端共享

安装 Duckly 扩展

Duckly 通过扩展提供实时共享功能，需要先从 Open VSX 安装 gitduck.code-streaming：

SERVICE_URL=https://open-vsx.org/vscode/gallery \
  ITEM_URL=https://open-vsx.org/vscode/item \
  code-server --install-extension gitduck.code-streaming

安装完成后刷新 code-server 窗口，侧边栏/命令面板中应能看到 Duckly 扩展的入口。

发起共享

由于 code-server 基于 VS Code，后续使用流程与 VS Code 中相同：按 Duckly 官方的 “Pair programming with VS Code” 指引操作即可，跳过其中“安装扩展”这一步（因为你已经通过上面的 CLI 命令完成了安装）。典型流程是：在扩展面板中启动 Duckly 会话 → 生成共享链接 → 其他参与者（无论使用 VS Code 还是 JetBrains 系 IDE）打开链接加入。

方案二：CodeTogether 实时结对

CodeTogether 定位为实时跨 IDE 的结对编程工具，其官方特性清单（引自 docs/collaboration.md）：

• 跨 IDE 支持：VS Code、Eclipse、IntelliJ 及其衍生 IDE（浏览器或桌面均可）
• 实时编辑：共享光标或独立光标，适合结对（pairing）、围读（mobbing）、群攻（swarming）等多种协作模式
• P2P 加密：服务器无法解密流量
• 提供 SaaS 与私有化部署两种选项
• 共享服务器、终端和控制台
• 单元测试支持，适配 Red / Green / Refactor 的 TDD 流程
• 可通过浏览器或任意 IDE 加入会话
• 免费的 1 小时会话（4 人）
• 提供付费与免费多种订阅计划

安装 CodeTogether 扩展

第 1 步：从 Open VSX 安装扩展

SERVICE_URL=https://open-vsx.org/vscode/gallery \
  ITEM_URL=https://open-vsx.org/vscode/item \
  code-server --install-extension genuitecllc.codetogether

第 2 步：开启 proposed API

CodeTogether 依赖 VS Code 的 proposed API 才能运行，需要启动 code-server 时传入：

code-server --enable-proposed-api genuitecllc.codetogether

该参数在 code-server 中被定义为 string[] 类型，可以一次传入多个扩展 ID 分别启用（见 src/node/cli.ts 的参数描述：“Enable proposed API features for extensions. Can receive one or more extension IDs to enable individually.”）。参数经 src/node/cli.ts 的 toCodeArgs 透传给 VS Code server 进程，最终由 VS Code 的 proposed API 环境开关消费。

另一种做法是写入 code-server 的配置文件。按 docs/FAQ.md 的说明，code-server 启动时会在 ~/.config/code-server/config.yaml 生成默认配置，配置文件中每个 key 直接对应一个命令行 flag，且命令行传入的 flag 优先于配置文件。因此只需在 config.yaml 中加上：

enable-proposed-api:
  - genuitecllc.codetogether

配置位置可用 --config flag 或 $CODE_SERVER_CONFIG 环境变量覆盖，默认位置遵循 $XDG_CONFIG_HOME。

第 3 步：刷新窗口并开始会话

刷新 code-server 窗口后，点击侧边栏的 CodeTogether 图标，即可作为 host 发起会话或加入他人会话。

源码补充：code-server 对 proposed API 的额外处理

从补丁文件 patches/proposed-api.diff 的结构可以看出，code-server 对上游 VS Code 做了一处针对性修改：将 isProposedApiEnabled 改为无条件返回 true，并把“是否对全部扩展启用 proposed API”的判断前置为 true || ...。补丁注释说明其动机是：某些扩展没有正确声明所需 API（注释中提到的 Jupyter 扩展就曾遇到该问题），导致即使传入 --enable-proposed-api 也无法生效。可以推断：在当前 code-server 构建中，--enable-proposed-api 更多起到“显式声明”与配置持久化的作用，而实际门控已被放宽。如果你在升级 code-server 后遇到 CodeTogether 的 proposed API 相关报错，可结合该补丁与升级文档核对行为差异。

小结

code-server 的协作方案可以归纳为“一个市场 + 一个开关”：

• 扩展来源：默认 Open VSX 市场（patches/marketplace.diff 中的默认配置），安装走 --install-extension 派生的 VS Code CLI 流程（src/node/main.ts）；
• Duckly：安装 gitduck.code-streaming，刷新窗口后按 VS Code 流程发起共享，适合跨 IDE 的实时共享与语音协作；
• CodeTogether：安装 genuitecllc.codetogether 并启用 --enable-proposed-api（命令行或 config.yaml 均可），从侧边栏图标发起或加入会话，适合结构化的结对与 TDD 协作。

两条路线均不改变 code-server 内核，部署成本低；排查问题时重点检查市场环境变量（SERVICE_URL / ITEM_URL / EXTENSIONS_GALLERY）与扩展安装日志即可覆盖绝大多数失败场景。