OpenCode插件系列: opencode-visual-cache

类型: TUI Sidebar Visualization Plugin

仓库: https://github.com/Hotakus/opencode-visual-cache

1. 这是什么插件？

opencode-visual-cache 是一个为OpenCode添加Token缓存可视化能力的TUI侧边栏插件。核心概念：

• 不像传统cost tracker只显示累计数字
• 它在侧边栏实时显示缓存命中率进度条
• 自动适配主题色，低饱和Morandi风格设计
• 支持中/英双语，多币种费用展示

想象一下：就像有一个实时仪表盘，告诉你每次API调用省了多少钱。

与传统Cost Tracker的区别：

2. 用来做什么？

使用它来：

• ✅ 实时监控缓存命中率 — 进度条 + 百分比，一眼看出优化效果
• ✅ 追踪Token明细 — 缓存读 / 缓存写 / 未命中 / 输出，分角色统计
• ✅ 计算费用节省 — Session累计费用 + 缓存命中带来的节省金额
• ✅ 查看模型定价 — 输入 / 缓存读 / 缓存写单价，从provider动态读取
• ✅ 多币种展示 — USD / CNY / EUR / JPY / GBP / KRW，自动汇率换算
• ✅ 技能占用分析 — 检测session中已加载的skill及估算Token占用
• ✅ 独立折叠区块 — 明细、模型、分布、技能各自独立折叠
• ✅ 语言即时切换 — 中/英双语，无需重启

典型场景：

你："优化prompt以减少token消耗"Visual Cache:- 改写前 → 命中率 45%，费用 $2.30- 改写后 → 命中率 78%，费用 $1.15- 🔔 节省 $1.15，命中率提升 +33%

3. 如何使用？

安装

方式一：OpenCode命令安装（推荐）

按 Ctrl + P 打开命令面板，搜索 install plugin，输入：

opencode-visual-cache@latest

方式二：手动安装

npm install -g opencode-visual-cache@latest

在 ~/.config/opencode/tui.jsonc 中添加：

{  "$schema": "https://opencode.ai/tui.json",  "plugin": ["opencode-visual-cache@latest"]}

重启 OpenCode，侧边栏即可看到缓存统计面板。

运行

插件启动后自动显示在侧边栏，支持以下斜杠命令：

环境变量

CACHE_TUI_LANG 可强制指定语言：

# macOS / LinuxCACHE_TUI_LANG=en opencode

# Windows PowerShell$env:CACHE_TUI_LANG="en"; opencode

模型与提供商兼容性

插件完全模型无关——通过 OpenCode SDK 标准接口读取 token 数据与 provider 定价（api.state.provider），支持所有 OpenCode 兼容的模型（Claude / GPT / DeepSeek / Gemini 等），无需为不同模型额外配置。

4. 何时使用？

在以下情况使用：

• ✅ 使用付费模型（Claude / GPT / DeepSeek）且关心成本
• ✅ 需要优化prompt，希望看到缓存命中率的实时变化
• ✅ 使用长上下文对话，想了解token分布情况
• ✅ 需要监控skill加载情况及token占用
• ✅ 偏好非侵入式可视化（侧边栏常驻，不打断工作流）

不要在以下情况使用：

• ❌ 使用完全免费的模型（成本节省为0，价值有限）
• ❌ 不关心API成本或token使用情况
• ❌ 侧边栏空间极度紧张（虽可折叠，但仍占用少量空间）
• ❌ 使用 oh-my-opencode 且已启用其内置cost tracking（可能存在重叠）

⚠️ 重要注意事项

Token分布估算

分布面板中各分项的精度不同——「总计」取自 API 精确值，其余分项为字符级 BPE 估算：

分项之和通常小于总计——差值来自 OpenCode 运行时注入的系统提示组成部分（环境信息、Skill 目录、工具 Schema 定义等）。这些内容不在 agent 配置的 prompt 字段中，插件无法估算，属于预期行为。

OpenCode插件缓存问题

由于 OpenCode已知问题 #6774，插件缓存会锁死在首次安装时的版本。更新时需要手动清除缓存：

# macOS / Linuxrm -rf ~/.cache/opencode/packages/opencode-visual-cache@latest

# WindowsRemove-Item -Recurse -Force "$env:USERPROFILE\.cache\opencode\packages\opencode-visual-cache@latest"

然后重新安装并重启。

定价说明

插件假设提供商定价均为美元（USD）。目前主流AI API（OpenAI / Anthropic / Google / DeepSeek / xAI等）的国际版均以USD计价。如果你使用的提供商以人民币或其他货币计价，请将汇率设为 1。

🔗 有用链接

• 仓库: https://github.com/Hotakus/opencode-visual-cache
• English README: https://github.com/Hotakus/opencode-visual-cache/blob/master/README_EN.md