dsh-opencode-go-meter

Readme

# dsh-opencode-go-meter

[![npm](https://img.shields.io/npm/v/dsh-opencode-go-meter)](https://www.npmjs.com/package/dsh-opencode-go-meter)
[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/willwhi/dsh-opencode-go-meter/blob/main/LICENSE)
[![GitHub](https://img.shields.io/badge/GitHub-dsh--opencode--go--meter-181717?logo=github)](https://github.com/willwhi/dsh-opencode-go-meter)
[![awesome · DSH plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)

DeepSeek Harness（dsh）Web 界面插件：在**对话输入区**直接显示 [OpenCode Go](https://opencode.ai/docs/go/) 订阅用量（5h 滚动 / 每周 / 每月）与**真实花费金额（美元）**，并在弹窗内完成登录与凭据配置——无需接触终端、无需改代码。

```
OpenCode Go · 5h 滚动 9% · 每周 12% · 每月 6% · $1.23
```

## ✨ 特性

- **三个用量窗口** —— 5h 滚动 / 每周 / 每月 的百分比与重置倒计时，按阈值变色（≥80% 黄、≥90% / 限流红）。
- **真实花费** —— 月度合计美元金额（官方聚合接口，精确），弹窗内可展开**按天费用明细**柱状图。
- **双数据源自动回退** —— 官方配额 API（Bearer key）优先，失败自动回退仪表盘 SSR（auth cookie）。
- **凭据安全** —— API key / cookie 只在 Host 侧进程使用，浏览器只读取同源 JSON 端点。
- **开箱即用** —— 无配置时显示 `<noconfig>`，点「Go 用量」弹窗自动展开登录表单，1 分钟完成配置。
- **轻量** —— 前端 30s 轮询；host 60s 缓存 + 60s 失败冷却；单飞去重。

## 📦 安装

> 环境要求：DeepSeek Harness（web profile）`0.1.0-rc.6`+；`PATH` 上有 pnpm（dsh plugin 依赖）。

### 方式一：npm（已发布，最快）

```sh
dsh plugin --profile web add dsh-opencode-go-meter
```

### 方式二：GitHub（源码跟进 / 检查更新）

```sh
dsh plugin --profile web add github:willwhi/dsh-opencode-go-meter
```

### 方式三：tarball（离线安装 / 分发）

```sh
# 拿到 .tgz 后：
dsh plugin --profile web add ./dsh-opencode-go-meter-0.1.2.tgz
```

### 方式四：本地 link（开发调试）

```sh
git clone https://github.com/willwhi/dsh-opencode-go-meter.git
cd dsh-opencode-go-meter
dsh plugin --profile web add "link:$(pwd)"   # Windows PowerShell: link:绝对路径
```

### 验证安装（任选）

```sh
dsh --profile web --dump-config    # 输出应出现 "# == dsh-opencode-go-meter" 层
```

### 生效

重启 `dsh web`（结束当前进程 → 重新启动），浏览器**强制刷新**（Ctrl+Shift+R）。
成功标志：对话输入框下方出现 `OpenCode Go · …` 一行，输入框内出现「Go 用量」按钮。

## ⚙️ 首次配置（约 1 分钟，纯界面操作）

1. 浏览器打开 [opencode.ai](https://opencode.ai) 并登录 → 工作区 → **API Keys** → 复制 **Go API key**（`sk-opencode-…`）。
2. 回到 dsh，点输入框内「**Go 用量**」→ 弹窗自动展开登录表单。
3. 在 **① API Key** 粘贴 key → **保存并验证** → 用量立即出现。
4. （可选，推荐）**② 仪表盘凭据**：F12 → Application → Cookies 复制 `auth` 值 + 页面 URL 里的 `wrk_…` → **保存仪表盘凭据** → 出现月度费用与按天明细。

> 若本机已用过 opencode CLI（`opencode auth login`），API key 已被自动读取，步骤 1–3 可跳过。

### 配置方式对比

| 方式 | 内容 | 说明 |
| --- | --- | --- |
| 弹窗登录表单（推荐） | API key / cookie+workspaceID | 最快，无需碰文件；凭据仅写本机 |
| 配置文件 | `~/.dsh/opencode-go-meter.json` | `{ "cookie": "auth=…", "workspaceID": "wrk_…" }`（可含 `apiKey`/`baseUrl`/`timeoutMs`） |
| 复用 opencode CLI | `~/.local/share/opencode/auth.json` | 自动读取 `opencode-go` 条目的 key（回退 `opencode`） |

取值优先级 —— API key：`opencode-go-meter.json` 的 `apiKey` > `auth.json`；cookie/workspaceID：仅 `opencode-go-meter.json`。

> 完整配置细节、FAQ 与排查：见 [docs/使用指南.md](https://github.com/willwhi/dsh-opencode-go-meter/blob/main/docs/%E4%BD%BF%E7%94%A8%E6%8C%87%E5%8D%97.md)。

## 🖥️ 使用

- **摘要行**（输入框下方）：三窗口百分比 + 本月花费，颜色随健康度变化。
- **详情弹窗**（「Go 用量」按钮）：每窗口百分比进度条 + 重置倒计时 + 已花费；「按天费用明细」柱状图（最近 10 天）。
- **手动刷新**：弹窗右下角「刷新」。
- **改配置**：弹窗「登录」随时更新 key / cookie / workspaceID。

## 🔄 更新插件

- npm / GitHub 安装：重新执行安装命令即可拉取最新版本，然后重启 `dsh web`。
- link 开发安装：`git pull` 拉取最新代码，然后重启 `dsh web`。

## 🗑️ 卸载

```sh
dsh plugin --profile web remove dsh-opencode-go-meter
```

重启并刷新后界面恢复原样。卸载**不会**删除 `~/.dsh/opencode-go-meter.json` 与 `auth.json`。

## 🔧 工作原理（简述）

- **Host 半**（`index.js`）：所有抓取/解析/缓存都在 host 进程；向 `conversation.composer.dock` / `conversation.input.left` 对应的同源 JSON 端点（`/api/opencode-go-meter*`）提供数据；凭据永不进浏览器。
- **浏览器半**（`client.js`）：注册 dock 摘要行与「Go 用量」按钮，弹窗展示明细与登录表单；30s 轮询 + 1s 倒计时。
- **数据源**：官方配额 API → 仪表盘 SSR（用量窗口）；仪表盘请求记录 → 官方聚合 RPC（月度费用，按天/按模型）。

## 🔒 安全说明

- `auth` cookie 是**完整 OpenCode 用户会话**：插件只在 host 侧使用，绝不发送给浏览器、不写日志、不进错误信息。
- 建议为本机配置文件收紧权限（Unix：`chmod 600 ~/.dsh/opencode-go-meter.json`）。
- 零遥测、无第三方依赖（仅 dsh 自带运行时）。

## 📚 文档

- [docs/功能介绍.md](https://github.com/willwhi/dsh-opencode-go-meter/blob/main/docs/%E5%8A%9F%E8%83%BD%E4%BB%8B%E7%BB%8D.md) —— 功能细节、数据来源、阈值与缓存策略、与同类插件对比。
- [docs/使用指南.md](https://github.com/willwhi/dsh-opencode-go-meter/blob/main/docs/%E4%BD%BF%E7%94%A8%E6%8C%87%E5%8D%97.md) —— 安装、首次配置分步、配置方式对比、更新、FAQ、卸载、排查。

## 📄 License

[MIT](https://github.com/willwhi/dsh-opencode-go-meter/blob/main/LICENSE)