[ADR-040] 扩展安装唯一形态是 Bundle:封死「第三方插件装进引擎 plugin[]」

[jinjunnn]

owner 裁决(2026-08-03)

Alpha 的扩展安装唯一形态是 Bundle。任何扩展安装都不得写入引擎的 plugin[]。

alpha.jsonc 的 plugin[] 不是产品面 —— 它是引擎的内部装载机制,
Alpha 对它唯一合法的用途是注入自己的引擎侧接缝(@alpha-code/ext)。

三条规则

1. profile = 载荷的种类;Bundle = 包的形状。
   信封的 root 是字符串(指向 components[] 里某个 id),components[] maxItems 16、
   每个组件各带自己的 profileId ⇒ 「单组件包」只是组件数为 1 的 Bundle,Bundle 不是一种 profile。
2. 外部 provider 的插件一律落 Bundle,接入点是发布端适配器(alpha-web#96/#98);
   宿主不认识任何 provider,只认 profile。禁止为 provider 新增 profile ——
   判据:新增理由里出现 provider 名字,就一定是形状问题。
3. 封死 plugin[]:catalog / package / Bundle / seed / vendored / 未策展 npm 导入
   一律禁止写入,且必须 fail-closed。咽喉点钉在 ext-config.ts / ext-install-planner.ts,
   要求新增写入点默认被挡(穷举 + 未知即拒,不是黑名单),并附可执行判据与绕过配方。

被否决的方案 C:opencode-plugin profile —— 判回滚

REQ-128 Phase 4 已实现它。它把「第三方 JS 以引擎同等权限执行」变成产品面,
代价是一整套只为它存在的机制:同权限执行的授权披露、ABI 预检、strict wrapper、双载闸、pre-switch probe。

owner 裁决:Alpha 的扩展是声明式的(skill / agent / mcp / Bundle),不接受任意第三方代码在引擎进程里跑。
⇒ 该 profile 与配套的 engine:config / engine:plugin host capability 全部回滚,宿主 profile 回到四个。

最大收益:整个「同权限执行第三方 JS」的安全面消失。

如实登记的负面

• 父票 alpha-work#49 的 AC2 / AC6 明文提及 managed OpenCode Plugin,必须改写;
• Phase 4 已合并代码要做外科式回滚,不是四个 git revert ——
  那些 commit 里混着与插件无关的真实修复必须保住:卸载目录删不掉不再谎报成功(#809)、
  else → mcp 兜底收口、alpha-web 的 E_HOST_PARSER_DRIFT 修复(主线曾连红一天多);
• Phase 3(本地 Claude 插件导入)不在 Bundle 这条路上,存在语义映射被写两遍的风险 ——
  本 ADR 不裁决如何收敛,但要求动 #96/#98 前先回答这个问题;
• 引擎自身对工作目录 {plugin,plugins}/*.{ts,js} 的自动发现不在我们控制内,如实登记为已知边界。

判据(新讨论照这个走)

1. 要不要在引擎进程里跑第三方代码? 要 ⇒ 直接拒绝,没有下一问。
2. 是多个不同种类的组件吗? 是 ⇒ Bundle,接入点在发布端适配器。
3. 都不是且现有 profile 无一描述得了 ⇒ 才考虑新 profile,理由不得出现 provider 名字。

Refs jinjunnn/alpha-work#49