Skip to content

[Feature]: 支持 OpenCode 2.0 插件 API #395

Closed

Description

@TokenRanOut

Problem

OpenCode 2.0 引入了全新的插件 API,V1 插件实现无法直接在 V2 中运行。

目前 opencode-acp@1.18.0 仍然使用 V1 插件 API,包括:

  • 从 @opencode-ai/plugin 导入 Plugin
  • 依赖 @opencode-ai/sdk
  • 默认导出 V1 异步插件函数
  • 返回以下 V1 Hook:
    • experimental.chat.system.transform
    • experimental.chat.messages.transform
    • experimental.text.complete
    • command.execute.before
    • event
    • config
    • 旧版 tool 对象
  • 读写 permission、agent、command 和 experimental.primary_tools 等 V1 配置字段

OpenCode 2.0 改为使用 @opencode/plugin、Plugin.define({ id, setup })、领域 Hook/Transform、结构化工具结果和有序权限规则,因此升级到 OpenCode 2.0 后无法继续使用 ACP。

虽然 OpenCode 2.0 已经内置检查点式上下文压缩,但 ACP 仍提供不同的能力,包括模型主动选择压缩范围、分层增量压缩、解压缩、上下文搜索及面向超长会话的上下文管理。

Proposed Solution

希望增加兼容 OpenCode 2.0 的插件实现。

建议包含以下内容:

  1. 使用 @opencode/plugin 和 Plugin.define 增加 V2 入口:

    export default Plugin.define({
      id: "opencode-acp",
      async setup(ctx) {
        // 注册 ACP 的 V2 功能
      },
    })
  2. 迁移上下文处理 Hook:

  • experimental.chat.system.transform
    → ctx.session.hook("context", ...)
  • experimental.chat.messages.transform
    → ctx.session.hook("context", ...)
  • 重新评估 experimental.text.complete 的用途,因为 V2 没有一一对应的 Hook。
  1. 通过 ctx.tool.transform(...) 注册以下 ACP 工具:
  • compress
  • decompress
  • search_context
  • acp_status
  • acp_context_recap
    工具参数改用 JSON Schema,执行结果改为 V2 结构化内容。
  1. 通过 ctx.command.transform(...) 注册 /acp 命令。
  2. 将 V1 的 event 回调迁移到 ctx.event.subscribe(...),并在插件卸载时正确终止订阅。
  3. 使用对应的 V2 领域 API 替代旧版 Client 和全局 Config 操作,例如:
  • ctx.session
  • ctx.catalog
  • ctx.permission
  • ctx.storage
  • ctx.tool
  • ctx.command
  1. 适配 V2 的有序权限规则,确保 ACP 工具可以正确配置 allow、ask 和 deny。
  2. 补充 OpenCode 2.0 配置文档,例如:
    {
    "plugins": ["opencode-acp"],
    "compaction": {
    "auto": false
    }
    }
    ACP 接管上下文管理时,应继续关闭 OpenCode 内置的自动压缩,避免两套压缩机制产生状态冲突。
  3. 增加 OpenCode 2.0 集成测试,覆盖:
  • 插件加载
  • 工具注册和执行
  • System Prompt 与消息上下文处理
  • 会话恢复和 Fork
  • 模型切换及上下文窗口识别
  • 权限的 allow、ask、deny
  • 插件卸载和重新加载
  • 关闭内置自动压缩后的运行情况
    如果需要继续兼容 V1,可以参考 OpenCode 官方方案,在同一个默认导出中同时提供 V1 的 server() 和 V2 的 setup()。
    如果双版本维护成本过高,也可以考虑为 OpenCode 2.0 发布新的主版本或独立发布通道。

Alternatives Considered

No response

Additional Context

相关文档:

Activity

  1. ranxianglei commented on Sep 12, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    [bot] 🏷

    收到,先做审核(查重 + 合理性验证),结论如下。

    1. 查重

    按 "OpenCode 2.0"、"plugin API V2"、"migration"、"Plugin.define" 等关键词检索了全部 issue(含已关闭)——无重复项,作为新功能请求处理。

    2. 合理性验证(已完成,非纸面评估)

    • OpenCode 2.0 及其 V2 SDK 是真实已发布的:npm 上 @opencode/plugin 已到 2.0.2;官方迁移指南明确警告 "V1 plugin implementations do not run in V2"。当前 npm latest 1.18.0 确认只有 V1 入口(对照源码逐条核对过)。
    • 我把 @opencode/plugin@2.0.2 的完整类型定义拉下来逐项核对了 issue 提出的 9 条映射:基本全部成立,有几处修正/补充:
    Issue 提案 核实结果
    system/messages.transform → ctx.session.hook("context") ✅ 成立。context 事件的 event.system / event.messages 是可变数组,ACP 的 prune / ID 注入 / nudge 管线可以平移
    text.complete 重新评估 ✅ 官方确认无直接对应。ACP 用它剥离模型输出中的幻觉 mNNNNN/bN 引用;请求侧的 stripHallucinations 已能处理陈旧引用,建议 V2 下移除该 hook,Phase 0 实测验证影响
    ctx.tool.transform 注册 5 个工具 ✅ 成立:JSON Schema input + 结构化 Result。另有 execute.before/after 工具钩子,compress 耗时追踪可改走工具钩子而非事件流
    ctx.command.transform 注册 /acp ✅ 成立且比 V1 简单:V2 命令原生支持 execute handler,不再需要 V1 那种「config 注册 template 命令 + command.execute.before 拦截」的组合拳
    event → ctx.event.subscribe ✅ async iterator 流,在 setup 返回的 cleanup 里用 AbortController 终止,生命周期语义清晰
    领域 API 替代 Client / 全局 Config ✅ 成立但注意:V2 没有可整体修改的全局 config 对象。V1 的单一 config hook 要拆成多个领域注册(tool/command/catalog transform + permission.evaluate 钩子);bili 代理自禁用检测改为从 ctx.catalog 读 provider 信息
    有序权限规则 allow/ask/deny ✅ ctx.permission 提供 rules/list API + evaluate 钩子(effect 可改写),可实现
    compaction.auto: false 文档 ✅ 与 V1 相同。额外发现:V2 的 SessionCompaction.result 字段允许插件直接提供压缩结果、跳过模型请求——这是未来与内置压缩集成的可能接口(本期不做,仅记录)

    验证中发现的新事实(issue 未覆盖):

    1. V2 按请求类型拆分钩子:context 对应 agent 主模型请求(官方文档:"runs immediately before an agent model request"),compaction / generate / title 各有独立钩子。对 ACP 这是利好——只注册 context 即可天然避免把 nudge/ID 注入泄漏到标题生成等辅助请求(精确语义在 Phase 0 确认)。
    2. 双入口的版本下限:官方迁移指南明确 object 形态入口(同时含 server() 和 setup())只在 OpenCode ≥ 1.18.29 被识别。即双入口方案会把最低支持版本抬到 1.18.29。

    3. 设计契合度

    ACP 的 lib/ 核心(压缩管线、状态持久化、消息处理、nudge 系统)与宿主版本无关,需要移植的只是适配层(index.ts + lib/hooks.ts 的接线 + 工具定义签名)。架构上适合「核心不动、加一个 V2 适配器」。

    4. 建议方案(分三阶段)

    • Phase 0 — 兼容性 spike(先做):最小 V2 骨架(Plugin.define + setup、一个测试工具、context hook、command transform、event 订阅、permission evaluate),部署到真实 OpenCode 2.0 实例,回答 7 个风险问题:① context 钩子的 kind 语义与触发时机;② 状态文件路径 ~/.local/share/opencode/storage/plugin/acp/{sessionId}.json 在 V2 宿底下是否不变(存量用户状态连续性依赖此);③ catalog 能否读到 provider.options.baseURL(代理检测依赖此);④ 5 个工具的 markdown 输出映射到结构化 Result 的具体形态;⑤ permission.evaluate 的 agent 字段是否覆盖子代理场景;⑥ 有无 completion 后置文本变换点(决定 text.complete 去留);⑦ model-limit 目录种子的等价手段(替代 hydrateModelLimitsFromClient)。产出 devlog spike 报告,不改生产代码。
    • Phase 1 — 适配器移植:抽适配层边界(核心接口化),增量移植:context hook(system+messages 管线)→ 5 个工具 → /acp 命令 → 事件订阅 → 权限/config 映射 → 代理守卫。
    • Phase 2 — 文档 + 集成测试 + 发布:EN/zh 文档(含 compaction.auto: false);按 issue 第 9 条的场景清单补 V2 集成测试(加载、工具执行、prompt/messages 处理、resume/fork、模型切换与上下文窗口识别、权限三态、卸载重载、内置压缩关闭);按选定策略发布。

    5. 需要你拍板的三件事

    1. 是否批准从 Phase 0 spike 开始?
    2. 分发策略:同包双入口(我推荐——官方认可的模式、用户零迁移成本、V1 路径保留到明确弃用为止)还是发新主版本 2.x(边界更干净,但过渡期双版本维护)?
    3. 双入口下最低支持 OpenCode 版本抬到 1.18.29 是否可接受?

    另注:本工作区 clone 停在 v1.15.0,npm latest 已是 1.18.0,动手前会先同步。


    一句话总结:已实证 OpenCode 2.0 V2 API 存在且 issue 九条映射基本成立(修正三点:text.complete 无对应建议移除、/acp 可走原生 execute、context 钩子按请求类型拆分对 ACP 是利好),推荐官方双入口模式并按 spike → 移植 → 测试/文档三阶段推进,等你拍板后开工。

  2. ranxianglei commented on Sep 12, 2026

    @ranxianglei
    Owner

    建议这个 issue 移交给 billion-context ,走通用实现

  3. ranxianglei commented on Sep 12, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    [bot] 🏷

    @Dog 这个建议我核实过了,与现有项目架构一致,我修正之前的推荐。

    核实结果(跨仓库查证)

    • 生态布局:acp-kernel(零依赖压缩内核,各适配器复用的 single source of truth)+ 按宿主薄适配层——billion-context-pi、billion-context-dsh 都是「kernel 原样复用 + 宿主胶水」模式;billion-context 通用代理定位是 "Any agent that can set a base URL — zero per-agent adapter code"。
    • 关键先例:billion-context-opencode(acp-kernel 版 opencode 插件,bili_ 前缀工具,npm 已发布)存在但已标记废弃,且注明与 opencode-acp 相互独立。即「kernel + opencode 适配器」这条路走过一次。
    • 通用代理对 OpenCode 2.0 立即可用:proxy 模式工作在 LLM wire 层(解析 Anthropic/OpenAI 请求流 → kernel 压缩 → 注入 4 个工具 → 改写响应),与宿主插件 API 版本无关;opencode-acp 文档本身就把「provider baseURL 直接指向代理」列为受支持用法(v1.14.27 的自禁用逻辑就是为它做的)。OpenCode 2.0 用户不改任何插件代码即可用上。
    • 查重:ranxianglei/billion-context 中检索无 OpenCode 2.0 相关 issue——移交的话需要新立一个。

    为什么修正推荐

    我第一轮「opencode-acp 内双入口移植 V2」只基于本仓库视角评估。跨项目看:opencode-acp 是 kernel 化之前的独立实现,把它移植到 V2 会延续第二套分叉实现,而组织内新增宿主的既有模式就是 kernel + 薄适配器(pi/dsh 先例)。@Dog 的方向更契合架构,维护成本也更低(kernel 演进所有宿主共享)。

    建议执行步骤(待拍板)

    1. 在 ranxianglei/billion-context 立 issue(按规范带来源标记「来源: opencode-acp#395 …」):① 验证纯代理模式在 OpenCode 2.0 下的实际表现(baseURL/auth/流式改写);② 评估原生 V2 插件适配器(billion-context-opencode 继任者,acp-kernel + V2 胶水)的必要性与时机;
    2. [Feature]: 支持 OpenCode 2.0 插件 API #395 标记移交给该 issue 后关闭(交叉引用);
    3. opencode-acp README 补一句:OpenCode 2.0 用户请走 billion-context(小文档改动)。

    两点诚实说明

    • 代理模式架构上与宿主版本无关,但尚无在 OpenCode 2.0 下实测的记录(V2 的 provider baseURL/auth 细节可能有差异)——这正是步骤 1 里第①项要解决的。
    • 若原始提出者 @TokenRanOut 明确要的是宿主内插件体验(/acp 命令、不依赖外部代理进程),那部分需求由步骤 1 的第②项(原生 V2 适配器评估)承接,不会丢。

    同意上述方向的话回复确认,我立即执行 1–3。


    一句话总结:查证确认 billion-context 通用代理(wire 层、与宿主插件 API 无关)对 OpenCode 2.0 开箱可用,且组织既有「acp-kernel + 薄适配器」模式比在本仓库内移植 V2 更契合架构,建议把本 issue 移交 billion-context 并关闭,待确认后执行。

  4. ranxianglei commented on Sep 12, 2026

    @ranxianglei
    Owner

    移交不关闭本 issue ,保持追踪。billion-context 那边 ework 会接单,增加启动器模式的 opencode v2

  5. ranxianglei commented on Sep 12, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    [bot] 🏷

    已执行移交(不关闭,保持追踪):

    • billion-context 侧 issue 已立:[Feature]: OpenCode V2 支持:验证纯代理模式 + 新增 V2 启动器模式(opencode-acp#395 移交) billion-context#735 —— 「OpenCode V2 支持:验证纯代理模式 + 新增 V2 启动器模式」。正文含完整背景、两项请求范围(① 纯代理模式在 OpenCode 2.0 下实测验证;② 新增 V2 启动器模式,acp-kernel + V2 胶水,参考 pi/dsh 适配器模式与废弃的 billion-context-opencode 结构)、验收标准(对应本 issue 第 9 项),以及我在本 issue 中已核实的 V2 API 对照表(官方迁移指南 + @opencode/plugin@2.0.2 类型定义),供接单 agent 直接参考。按规范带了来源标记。
    • [Feature]: 支持 OpenCode 2.0 插件 API #395 保持打开,作为 opencode-acp 侧的追踪项;本仓库维持 V1-only,不再做 V2 移植。
    • README 指向 billion-context 的说明暂缓——等 #735 的启动器模式落地后再补文档,避免记录未发布的能力;届时两个仓库一起更新。

    一句话总结:已在 billion-context 立新 issue #735 承接 OpenCode V2 支持(代理模式验证 + V2 启动器模式),本 issue 按指示保持打开做追踪、本仓库维持 V1-only,可以收尾等待另一侧进展。

  6. jensenojs commented on Sep 13, 2026

    @jensenojs

    蹲一手

  7. ranxianglei commented on Sep 19, 2026

    @ranxianglei
    Owner

    按 #442 决议(OpenCode V2 统一走 billion-context,本仓库维持 V1-only)收尾——本 issue 作为追踪项的使命已完成。

    追踪链已全部落地:

    • 移交目标已交付:billion-context#735 → billion-context#754(已合并)—— OpenCode 2.0 V2 启动器模式 + 纯代理模式实测验证。
    • 文档指引已合入本仓库 master(PR #441):README 顶部 2.x 提示 + 「该选哪个?」表拆分为 opencode 1.x(opencode-acp)/ opencode 2.0+(billion-context)+ 安装说明。

    OpenCode 2.x 用户现请直接使用 billion-context(bili opencode 或 bili plugin install opencode)。如需将本 issue 保留为永久参考,可直接重开。

  8. ranxianglei commented on Sep 19, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    已核实并关闭。

    收尾前逐项验证了追踪链:

    • billion-context#735 → 已关闭;承接 PR billion-context#754(feat: OpenCode 2.0 support — V2 launcher mode + pure-proxy validation (#735))→ 已合并 ✅
    • 本仓库 PR docs: point OpenCode 2.x users to billion-context #441(docs: point OpenCode 2.x users to billion-context)→ 已合入 master ✅

    以上与你的描述完全一致,#395 现按 #442 决议关闭。如需永久参考,直接重开即可。


    一句话总结:追踪链三项(#735、#754 合并、PR #441 合入)全部实证通过,本 issue 已完成使命,予以关闭。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions