OpenCode Usage

English | 简体中文

在 VS Code 状态栏上实时查看 OpenCode workspace 用量配额

---

⚠️ 免责声明

本扩展仅供技术交流与学习参考，非官方出品，与 OpenCode 没有任何关联或附属关系。使用者应自行遵守 OpenCode 的服务条款。本扩展不会修改、绕过或破坏 OpenCode 的任何安全机制，所有数据均通过用户已认证的会话获取。如因使用本扩展导致的任何问题，开发者不承担任何责任。

---

📖 简介

OpenCode Usage 是一款轻量级 VS Code 扩展，它将 OpenCode workspace 的用量数据直接展示在 VS Code 状态栏上。无需频繁切换到浏览器，即可掌握 Rolling（滚动）、Weekly（每周）、Monthly（每月） 三种粒度的用量信息。

OpenCode 是一个面向 AI 辅助编程的云端开发平台，提供基于 workspace 的资源配额管理。

---

✨ 功能特性

• 状态栏实时展示 — 右下角图标，一目了然
• 多维度用量查询 — Rolling / Weekly / Monthly 三种配额进度
• 浏览器登录 — 通过 Playwright 自动启动本地 Chrome/Edge，交互式登录后自动提取凭据
• 智能错误分类 — 凭据过期、网络异常、数据解析失败分别提示引导
• 中英双语 — 通过 VS Code 设置即时切换（zh-CN / en）
• 一键重置 — 清除凭据和缓存，重新登录

---

🚀 快速开始

安装

从 VSIX 安装（推荐测试）

1. 在 Releases 页面下载最新 .vsix 文件
2. 在 VS Code 中按 Ctrl+Shift+P → Extensions: Install from VSIX... → 选择下载的文件

从 VS Code Marketplace 安装

即将上架，敬请期待。

从源码构建

git clone https://github.com/biubushy/opencode-usage-vsix.git
cd opencode-usage-vsix
npm ci
npm run build
npm run package    # 产出 opencode-usage.vsix

---

使用指南

1️⃣ 首次使用 — 浏览器登录

安装后，VS Code 右下角状态栏会出现 $(graph) OpenCode 图标。

步骤	说明
点击图标	弹出 QuickPick 操作菜单
选择「🔑 浏览器登录」	扩展会自动启动本机 Chrome 或 Edge 浏览器，跳转到 opencode.ai/auth
在浏览器中登录	输入你的 OpenCode 账号完成认证
在 VS Code 中点击「✅ 继续」	登录成功后请及时切回 VS Code，点击通知栏的「✅ 继续」完成凭据提取

⚠️ 重要：在浏览器中完成登录后，扩展会通过系统通知提醒你返回 VS Code 点击「继续」。若通知超时，可点击状态栏图标重新触发提取流程。

2️⃣ 查看用量

登录成功后，悬停在状态栏图标上即可看到用量详情：

三种配额说明：

配额类型	含义
Rolling	滚动用量（基于某个固定时间窗口）
Weekly	本周已用量 / 总配额
Monthly	本月已用量 / 总配额

每一项显示 使用百分比 和 重置倒计时。

3️⃣ 刷新数据

点击状态栏图标 → 选择「🔄 刷新数据」，手动拉取最新用量。

扩展也会在 VS Code 启动时自动刷新一次。

4️⃣ 切换语言

点击状态栏图标 → 选择「🌐 Switch to English」或「🌐 切换到中文」，即时切换。

5️⃣ 重置插件

点击状态栏图标 → 选择「🗑️ 重置插件」，清除所有已保存的凭据和缓存数据。

⌨️ 命令

命令 ID	标题	触发方式
opencode-usage.showUsage	OpenCode: Quick Actions	点击状态栏图标
opencode-usage.refreshCache	OpenCode: Refresh Usage Cache	命令面板 / QuickPick

---

🧩 架构概览

┌─────────────────────────────────────────────┐
│                 UI Layer                     │
│   StatusBar + QuickPick + Markdown Tooltip   │
│   src/extension.ts        (入口 & 交互)       │
├─────────────────────────────────────────────┤
│               Domain Layer                   │
│   src/api/opencodeClient.ts  RPC 客户端      │
│   src/api/responseParser.ts  Seroval → JSON  │
│   src/auth/browserAuth.ts   Playwright 登录  │
├─────────────────────────────────────────────┤
│               Data Layer                     │
│   VS Code Configuration (settings.json)      │
│     └─ cookie / workspaceId / locale         │
├─────────────────────────────────────────────┤
│         Cross-cutting: Locale                │
│   src/locale.ts    zh-CN / en   ~50 条翻译    │
└─────────────────────────────────────────────┘

数据流

用户点击状态栏
  └─ QuickPick 菜单
       ├─ 🔑 浏览器登录
       │   └─ Playwright 启动本地 Chrome/Edge
       │   └─ 用户手动在浏览器中登录
       │   └─ 提取 auth cookie + workspaceId → 写入 settings.json
       │   └─ 自动刷新用量缓存
       │
       ├─ 🔄 刷新数据
       │   └─ https GET → opencode.ai/_server (SolidStart RPC)
       │   └─ 参数使用 Seroval 编码
       │   └─ 响应经 5 步解码 → JSON
       │   └─ 缓存 rollingUsage / weeklyUsage / monthlyUsage
       │
       ├─ 🗑️ 重置 → 清除凭据 + 缓存
       │
       └─ 🌐 切换语言 → 切换 locale

关键技术

技术	用途
VS Code Extension API	StatusBar、QuickPick、MarkdownString、Configuration
Playwright	启动浏览器进行交互式登录，提取 Cookie 和 Workspace ID
Seroval 解码	逆向解析 OpenCode _server RPC 的非标准 JS 响应
esbuild	将 TypeScript 源码捆绑为单文件 CJS 扩展
Vitest	单元测试框架

Seroval 解码管道

responseParser.ts 实现了 5 步顺序敏感的变换，将 SolidStart 的 Seroval 序列化输出转为标准 JSON：

原始 JS 响应
  → fixBooleans (!0 → true, !1 → false)
  → fixNewDate ("new Date(...)" → 纯字符串)
  → stripRefs (移除 $R[n]= 引用赋值)
  → quoteKeys (为对象键添加双引号)
  → JSON.parse

---

🛠️ 开发指南

环境要求

• Node.js 18+
• npm 9+
• VS Code 1.85+
• Google Chrome 或 Microsoft Edge（用于浏览器登录）

本地开发

# 安装依赖
npm ci

# 编译（watch 模式，配合 F5 调试）
npm run watch

# 或者单次编译
npm run build

在 VS Code 中按 F5 打开扩展开发宿主窗口即可调试。

代码质量

npm run lint        # ESLint 检查
npm test            # Vitest 单元测试
npm run test:watch  # 测试监听模式

测试覆盖

当前测试覆盖 responseParser.ts 纯逻辑层（seroval → JSON 解码），不依赖 VS Code API，可在 CI 中快速运行。

 ✓ parseResponse > parses a valid seroval response
 ✓ parseResponse > handles new Date() strings
 ✓ parseResponse > strips $R[n]= reference assignments
 ✓ parseResponse > handles nested objects
 ✓ parseResponse > rejects malformed response (missing markers)
 ✓ parseResponse > rejects invalid JSON after transforms

打包

npm run package   # 产出 opencode-usage.vsix

---

🤖 CI/CD

本项目使用 GitHub Actions 进行持续集成与交付。

事件	操作
push / PR 到 main	运行 lint → build → test
推送 v* 标签	同上 + vsce package → 自动创建 GitHub Release 并上传 .vsix

工作流文件：.github/workflows/ci.yml

---

📸 截图

功能	预览
状态栏图标
QuickPick 菜单
用量 Tooltip
浏览器登录
登录完成通知

---

📄 许可证

MIT

---

🔗 相关链接

• OpenCode 官网
• VS Code Extension API
• Playwright