opencode-quota 是 OpenCode 生态中最受欢迎的quota 用量查询插件，它能实时监控 GitHub Copilot、OpenAI、Kimi Code、Alibaba Coding Plan 等数十家 AI 供应商的配额与 Token 消耗，且做到"零上下文污染"。它最核心的工程决策，是把整个插件拆成了Server 插件与 TUI 插件的双插件分离架构：一个负责"算数"，一个负责"画图"，中间只靠一份契约式 RPC 通信。本文将带你快速看懂这套架构的设计思路与实现细节。

一、架构总览：为什么要拆成两个插件

很多 OpenCode 插件是"单体"的：读凭证、算数据、画界面全塞在一个入口里。opencode-quota 却刻意一分为二：

拆分的直接收益有三点：

• 单一数据源：所有配额数字只由 Server 插件计算一次，TUI、Web、Desktop 客户端看到的都是同一份结果，不会出现界面之间数字打架。
• 多端覆盖：OpenCode 2 的 Web 和 Desktop 没有 UI 插槽，TUI 插件在那边装不上，但 Server 插件依然能让/quota等斜杠命令在聊天里出报告。
• 凭证隔离：登录态只在 Server 侧读取（通过 src/lib/opencode-auth.ts 的ctx.integration），UI 侧完全不碰敏感数据。

这条规则被写进了项目贡献规范 CONTRIBUTING.md 的 "Server vs. TUI" 条目："Server 插件计算所有文本；TUI 插件只绘制 RPC 返回的内容，且永远不 import 任何 provider 或 credential 代码。"

二、Server 插件：配额数据的唯一计算中心

打开 src/plugin.ts 可以看到，QuotaToastPlugin在setup阶段做了四件事：

1. 注册 Quota RPC（第 151 行起）：这是两个插件之间的"唯一对话通道"，surface、footer、writeExport、command四个方法全部在这里提供实现。
2. 注册quota_status诊断工具：模型可以直接调用它做安装自检。
3. 注册 12 个斜杠命令：/quota、/tokens_weekly等，由 Web、Desktop 和 TUI 的/菜单共用，命令清单集中定义在 src/lib/quota-dialog-command-specs.ts。
4. 挂接会话钩子：在context、compaction、generate、title、retry等钩子上做两件事——把配额报告从模型请求里剪掉（零污染的关键），以及在配额重置后自动重试失败请求。

配额的"文案生产"集中在 src/lib/quota-surface-data.ts：侧边栏面板、Toast、提示栏状态行、Home 页脚这四种"表面"（surface）的文本都在这里算好，供 RPC 直接返回。

三、TUI 插件：一个"只画不算"的纯渲染层

TUI 插件基于 Solid + opentui 构建（构建脚本 scripts/prepare-tui-dist.mjs 用 Babel 单独编译 JSX），它通过 OpenCode 的四个 UI 插槽把内容"贴"进界面：

• sidebar.content→ 可折叠的Quota 侧边栏面板
• prompt.footer/home.footer.status→ 输入框下方的紧凑配额行
• app→ 会话空闲、压缩完成、AI 提问时的Toast 通知

值得注意的工程细节：TUI 里的每个视图都带一套刷新合并机制（src/tui-v2.tsx 的createViewRefresh）——60 秒定时刷新、会话事件触发刷新，且旧请求的结果会被版本号丢弃，避免界面闪跳。所有数据请求都通过context.client.rpc(QuotaRpc)发出，并带 60 秒超时。

四、Quota RPC：两个插件之间的契约

真正体现"分离设计"精髓的，是 src/rpc.ts 中定义的QuotaRpc。它不是实现代码，而是一份纯类型契约：

• surface：按表面（sidebar/idle/compacted/question）返回配额消息文本；
• footer：返回底部状态行的若干行；
• writeExport：按需写出配额导出文件；
• command：执行 12 个配额命令之一并返回结构化报告文档。

契约对每个输入输出都附带校验函数（Standard Schema），OpenCode 会在两端自动验证。因为 RPC 文件里对 OpenCode 包只做type-only 导入，TUI 侧加载它时不会把任何服务端依赖带进来——这就是"契约文件可以双端共享、实现文件绝不共享"的分界线。

命令的输出同时携带纯文本（给 Web/Desktop 聊天用）和结构化ReportDocument（给 TUI 对话框渲染表格用），一套数据、两种呈现，见 src/lib/report-document.ts。

五、零上下文污染：报告永远不进模型

项目的核心卖点是 "zero context window pollution"。实现方式很精巧：

1. 斜杠命令生成的报告被投递为一条带元数据标记的用户消息（标记常量见 src/lib/quota-report-message.ts）；
2. Server 插件在context、compaction、generate钩子上运行withoutQuotaReports()，把报告从即将发给模型的历史中完整剪除；
3. 压缩检查点会复制文本但丢失元数据，所以每条报告还被包上首尾哨兵行[OpenCode Quota report]，保证即使元数据丢失也能按文本切掉。

结果是：你在任何客户端都能看到完整报告，但模型永远看不见它——不花一个 Token。

六、边界如何被测试"焊死"

好架构靠约束维持。opencode-quota 用两个专门的边界测试确保插件永不"越界"：

• tests/tui-dist-import-graph.test.ts：静态遍历dist/tui.js的 import 图，断言 TUI 构建产物不可达任何登录读取器与providers/模块；
• tests/plugin.command-handled-boundary.test.ts：mock 掉凭证读取函数后跑完整 TUI 生命周期，断言它们在 setup、各表面渲染、命令执行中一次都未被调用。

配合 CONTRIBUTING.md 中"每个 slash 命令、quota_status工具和 RPCcommand方法都必须走buildQuotaDialogCommandOutput()"的单路径规则，双插件边界在 CI 里是防篡改的。

七、快速上手：三步用起来

1️⃣ 安装插件（需 OpenCode 2.0.16+、Node 22.13+）：

npx @slkiser/opencode-quota init

2️⃣ 重启 OpenCode，输入/quota查看当前配额，或打开侧边栏面板常驻显示。

3️⃣ 如需自定义展示风格、启用的供应商或导出文件，参考 docs/readme/configuration.md；排查登录或供应商问题可运行/quota_status，详见 docs/readme/troubleshooting.md。

总结

opencode-quota 的双插件分离架构，本质是把"数据计算"与"界面渲染"用一份可校验的RPC 契约切开：Server 插件垄断凭证与计算，TUI 插件退化为纯绘制层，再由边界测试把这条线焊死。这套模式不仅让插件同时覆盖 TUI、Web、Desktop 三种形态，也为多供应商配额统计这种"数据密集型插件"提供了一个非常值得借鉴的架构范本。