Positron 构建中 Copilot Chat 标签选择：基于 API Proposal 版本兼容性检查的完整实战指南

• 开发工具
• 代码编辑器
• 数据科学

在 Positron（基于 Code OSS 的下一代数据科学 IDE）中集成 GitHub Copilot Chat 时，每次跟随上游 Code OSS 更新或升级microsoft/vscode-copilot-chat扩展后，都必须为构建挑选一个"引擎与 API Proposal 双重兼容"的发布标签。本文基于仓库内.claude/skills/pick-copilot-tag技能文档及其配套脚本，完整讲解兼容性判定原理、check-proposals.sh的四种使用模式、输出解读与排错方法，帮助你快速定位"最新可用标签"并理解构建失败（API proposals not compatible）的根因。

为什么要"挑选" Copilot Chat 标签

Positron 的发布构建会把GitHub.copilot-chat列入严格校验名单，而vscode-copilot-chat是一个随 VS Code 主线高频迭代的扩展仓库，其每个 release tag 都绑定一个engines.vscode范围，并在package.json的enabledApiProposals数组中声明它所依赖的未稳定 API（Proposed API）。Positron 的 Code OSS 基线与 copilot-chat 的 tag 之间没有一一对应关系，因此需要回答三个问题：

1. 哪个 tag 系列（如v0.37）与当前 Positron 的 Code OSS 引擎版本兼容？
2. 该系列内哪个具体 tag 的enabledApiProposals与 Positron 编译进构建的 Proposal 集合完全一致？
3. 若没有完全一致的 tag，具体是哪些 Proposal 新增或升版导致的冲突？

pick-copilot-tag技能正是为此设计的。它在以下场景中适用（见 SKILL.md）：

• 一次上游 Code OSS 更新后，需要决定合并哪个 copilot-chat tag；
• 发布构建拒绝 copilot-chat 并报出API proposals not compatible错误；
• 升级 copilot-chat 时需要寻找最新兼容 tag。

兼容性检查的底层原理

要正确使用该技能，需要先理解 VS Code 生态中的 Proposed API 版本机制（完整说明见 references/proposal-compatibility.md）。

Proposal 与版本号

VS Code 扩展可以使用尚未定稿的 "proposed APIs"，每个 Proposal 可选携带一个版本号，例如chatProvider@4。在 Positron 侧，这些 Proposal 及其版本被编译进构建产物sharedProcessMain.js，其源头是源码树中的 extensionsApiProposals.ts（该文件由上游 Code OSS 生成，顶部标注THIS IS A GENERATED FILE. DO NOT EDIT DIRECTLY.，仓库当前版本中可以看到chatHooks、chatParticipantPrivate等 Proposal 定义）。

严格版本强制的开关

Positron 的 product.json 中存在一个extensionsEnabledWithApiProposalVersion列表，当前内容为：

"extensionsEnabledWithApiProposalVersion": [ "GitHub.copilot-chat" ]

凡是进入该列表的扩展，将受到严格版本强制（strict version enforcement）：扩展package.json中每个带版本的 Proposal，都必须与 Positron 构建内编译的版本完全一致。判定规则为：

• 开发构建（quality: null）完全跳过此项检查；
• 发布构建强制执行，不匹配将阻止扩展激活，并报出如下错误：

ERR: This extension is using the API proposals 'X' and 'Y' that are not compatible with the current version of VS Code.

失败的两类根因

1. 上游新增 Proposal：例如chatHooks@6在 v0.37.6 中被加入，但 Positron 完全没有chatHooks；
2. 上游升版 Proposal：例如chatParticipantPrivate@12升到@13，而 Positron 仍停留在@12。

两者都会触发同一个激活错误，肉眼无法区分，必须靠脚本输出定位。

前置条件

在 Positron 仓库根目录执行检查前，需要满足（见 SKILL.md 的 Prerequisites 章节）：

• GitHub CLI（gh）已安装并完成认证（脚本通过gh api访问microsoft/vscode-copilot-chat与posit-dev/positron的 GitHub API）；
• jq与python3可用（分别用于解析package.json与用正则提取 Proposal 版本）。

工作流第一步：运行兼容性检查

技能文档给出了四种检查模式，脚本本身还支持参数组合。所有模式统一从 Positron 仓库根目录调用 scripts/check-proposals.sh。

模式一：默认源码树检查

不带任何参数运行，脚本会自动完成四件事：读取仓库根目录 package.json 获取 Code OSS 版本（当前仓库为1.134.0）、从源码树提取 Proposal、自动发现兼容的 tag 系列并逐一检查：

.claude/skills/pick-copilot-tag/scripts/check-proposals.sh

模式二：检查已构建的 App

针对已打包的 Positron 应用而非源码树进行检查（脚本会深入 App 包查找sharedProcessMain.js，从中用正则提取name: { proposal: "...", version: N }结构的 Proposal 列表）：

.claude/skills/pick-copilot-tag/scripts/check-proposals.sh --app /Applications/Positron.app

模式三：检查指定 Positron 发布版本

传入形如2026.03.0或2026.03.0-212的版本号，脚本会从 GitHub 上该版本的 release tag 同时抓取 Proposal 列表与 Code OSS 版本（来自该 tag 的package.json）：

.claude/skills/pick-copilot-tag/scripts/check-proposals.sh --positron-version 2026.03.0

模式四：检查指定 tag 系列

跳过自动发现，只检查v0.37这一个系列：

.claude/skills/pick-copilot-tag/scripts/check-proposals.sh --tag-series v0.37

辅助标志

• -v/--verbose：显示完整的 Proposal 列表而非仅显示数量；
• --pre-releases：同时检查基于日期的预发布 tag（默认只检查正式 release）；
• 标志可组合使用，例如--positron-version 2026.03.0 --tag-series v0.37。

完整参数语义如下表（对应 check-proposals.sh 中的 flag 解析逻辑）：

需要注意，--positron-version与--app互斥（脚本会直接报错Use --positron-version ... or --app ..., but not both），且--positron-version仅接受YYYY.MM.PATCH或YYYY.MM.PATCH-BUILD格式，例如2026.03.0。

脚本内部是如何工作的

为了准确解读输出，值得深入 check-proposals.sh 的实现（以下均可从源码结构确认）。

三路 Proposal 来源

脚本用同一个name@version提取逻辑（基于正则(\w+)\s*:\s*\{[^}]*version\s*:\s*(\d+)或 App 内的(\w+):\s*\{\s*proposal:\s*"[^"]+"\s*,\s*version:\s*(\d+)\s*\}）从三个来源之一解析 Positron 侧 Proposal：

• resolve_proposals_from_source：直接解析仓库内 extensionsApiProposals.ts；
• resolve_proposals_from_app：解析 App 包内sharedProcessMain.js（兼容压缩与美化两种 JS 形态）；
• resolve_proposals_from_tag：经gh api抓取posit-dev/positron指定 tag 的该文件。

引擎兼容的 tag 系列自动发现

discover_tag_series会列出microsoft/vscode-copilot-chat最近 5 个 minor 系列（按版本排序取尾 5 个），读取每个系列.0tag 的engines.vscode（如^1.109.0），将其 minor 版本与 Positron 的 Code OSS minor 版本比较，输出三档结论：

• -> ^1.108.0 (compatible)：该系列正式版可直接检查；
• -> ... (pre-releases may be compatible)：.0需要更新的引擎，但该系列内更早的日期型预发布可能仍兼容旧引擎；
• -> ... (needs Code OSS >= x.y.z)：引擎不兼容，跳过。

候选系列按新到旧排序，并在找到兼容正式版后停止向下检查（预发布不会终止搜索，因为正式版优先级更高）。

逐 tag 判定 OK / BAD / SKIP

check_tag_list对每个 tag 做两步判定：

1. 引擎检查：若 tag 的引擎 minor 大于 Positron 的 Code OSS minor，则整批输出SKIP汇总（如SKIP v0.37.6 .. v0.37.9 (3 tags, needs Code OSS >= 1.110.0)），避免刷屏；
2. Proposal 检查：将 tag 的enabledApiProposals中带@的条目与 Positron Proposal 逐一比对：
   • 完全命中 → 输出OK <tag>，并记为最新兼容 tag；
   • 不命中 → 输出BAD <tag>，并进一步区分两种缺失形态：
     • chatHooks@6 (not in Positron)：Positron 中根本没有该 Proposal；
     • chatParticipantPrivate@13 (Positron has chatParticipantPrivate@12)：Positron 有同名但版本更低。

正式版与预发布的区分规则

同一系列内，脚本按 patch 位数区分两类 tag：1～3 位数字为正式 release（如v0.37.5），4 位及以上为日期型预发布（如v0.37.20240915）。默认只检查正式版，预发布仅在--pre-releases时检查，并分别记录_LATEST_OK与_LATEST_PRERELEASE。

工作流第二步：解读输出并给出结论

技能文档要求以三段式汇报结果：最新兼容 tag（降序版本中第一个 OK）、新 tag 中破坏兼容性的具体 Proposal 变化、以及升级建议。以文档中的示例输出为例：

Positron proposals: 9 versioned (from src/vs/.../extensionsApiProposals.ts) Code OSS version: 1.109.0 Checking recent tag series for engine compatibility: v0.36 -> ^1.108.0 (compatible) v0.37 -> ^1.109.0 (compatible) v0.38 -> ^1.110.0 (needs Code OSS >= 1.110.0) --- v0.37 --- Releases (10 tags): BAD v0.37.9 chatHooks@6 (not in Positron) chatParticipantPrivate@13 (Positron has chatParticipantPrivate@12) BAD v0.37.6 chatHooks@6 (not in Positron) OK v0.37.5 Pre-releases (41 tags, skipped -- use --pre-releases to check) Latest compatible release: v0.37.5

该示例揭示了几个关键结论：

• 引擎匹配是必要条件而非充分条件：v0.37 系列全部声明^1.109.0，与 Positron 的 Code OSS1.109.0匹配，但系列内部仍有 BAD tag；
• 同一系列内也会漂移：Microsoft 会在 release 分支之间 cherry-pick 新特性，导致 v0.37.6 起引入chatHooks@6并升级chatParticipantPrivate，从而破坏兼容性；
• 最终答案：最新兼容正式版为v0.37.5，高于它的 tag 全部需要更新 Positron 侧 Proposal 后方可合并。

为什么只看 engine 版本不够：两类陷阱

references/proposal-compatibility.md 专门强调，仅比较engines.vscode会得出错误结论，存在两种误导场景：

1. 系列内部漂移：同一 minor 系列（如 v0.37.0 到 v0.37.9）声明相同的引擎范围（如^1.109.0），但补丁之间 cherry-pick 的特性可能引入新 Proposal 或升版既有 Proposal；
2. 跨系列重叠：多个 minor 系列可能指向同一引擎范围。例如 v0.37.x 与 v0.38.x 都声明^1.109.0，但 v0.38 使用了来自预发布版 VS Code 的 Proposal（chatHooks、升级的chatParticipantPrivate），这些并不存在于稳定的 1.109 基线上。

因此，唯一可靠的检查方式是逐一比对enabledApiProposals数组，这正是本技能脚本的核心工作。对照仓库源码可以验证这一机制的落地：Positron 侧 Proposal 的"真源"是 extensionsApiProposals.ts（其中包含chatHooks、chatParticipantPrivate的定义，供构建期编译进sharedProcessMain.js），而启用严格校验的扩展名单在 product.json 的extensionsEnabledWithApiProposalVersion中。

实战建议与常见误区

• 优先使用源码树模式（无参数）：它同时覆盖 Proposal 与 Code OSS 版本两个维度，且无需预先打包或等待 release 发布；--app与--positron-version用于验证"已发布物"的现场排障。
• 组合使用--positron-version与--tag-series：先确认目标 Positron 版本对应的 Proposal 集合，再锁定单一系列快速迭代排查，避免全量扫描。
• 不要把SKIP误认为 BAD：SKIP意味着引擎本身不兼容（如需要 Code OSS >= 1.110.0），与 Proposal 冲突的BAD是不同层级的失败，处理路径也不同——前者需要先升级 Positron 的 Code OSS 基线，后者需要移植对应 Proposal 或回退 tag。
• 正式版优先于预发布：脚本默认跳过预发布 tag，只有找不到兼容正式版时才考虑--pre-releases，避免把日期型快照带进发布构建。
• 升级建议的写法：报告时明确"合并 v0.37.5 即可；若要升级到 v0.37.9，需要先在 Positron 侧补齐chatHooks@6并把chatParticipantPrivate升到@13"，让后续的移植工作有明确的验收清单。

通过本技能与配套脚本，Positron 的维护者可以在每次上游 Code OSS 更新后，用一次命令完成 copilot-chat 标签的兼容性筛选，把"激活报错后盲猜版本"的排障过程，变成可重复、可审计、输出可直接落地的确定性流程。

• 开发工具
• 代码编辑器
• 数据科学