dsh-opg-usage

Readme

# dsh-opg-usage

DSH (DeepSeek Harness) Web 插件：实时查看 **OpenCode Go** 套餐的使用额度与剩余额度。

一个可拖拽、可收缩的浮动胶囊，展示 **滚动窗口 / 本周 / 本月** 三个额度窗口的已用百分比、剩余百分比与重置倒计时。

## 功能特性

- 右上角浮动胶囊，默认显示 `Go · 周 X% · 月 Y%`，绿/黄/红圆点提示额度健康度（>50% 黄、>80% 红）
- 点击胶囊展开完整面板：三窗口已用/剩余百分比、进度条、状态徽章、重置倒计时
- 按住胶囊或面板标题栏可自由拖拽位置（自动限制在视口内）
- 每 60 秒自动刷新，支持手动刷新（⟳），连接异常时显示具体原因并可重试
- 浮于所有界面之上——包括展开的 better-sidebar 右侧面板（`shell.overlay` 层级已抬升）
- 浅色 / 深色主题自适应（使用 DSH 主题 token）

## 安装

在 DSH web profile（`~/.dsh/profiles/<name>/package.json`）中添加依赖并登记 bundles：

```json
{
  "dependencies": {
    "dsh-opg-usage": "github:M4sh1r0-444/dsh-opg-usage"
  },
  "dsh": {
    "profile": {
      "bundles": [ "...", "dsh-opg-usage" ]
    }
  }
}
```

然后在 profile 目录执行 `pnpm install`，重启 DSH 即可。插件会自动挂载宿主端并接入 Web 客户端，无需其它配置。

## 使用

- **胶囊**：点击展开 / 收起；按住拖动调整位置
- **面板**：⟳ 手动刷新；「收起」折叠回胶囊
- 数据来自 OpenCode 官方额度接口 `https://opencode.ai/zen/go/v1/usage`
- 凭据自动读取 `~/.local/share/opencode/auth.json` 中的 `opencode-go` 项（`sk-` API key），无需手动配置

## 隐私说明

- 所有请求在本机完成：Host 进程直接请求 opencode.ai，不经过任何第三方
- API key 仅用于请求 OpenCode 官方接口，不写日志、不上传

## 架构

- `lib/index.js`（Host 半）：注册 `GET /og-usage/api/usage` 路由 —— 读取 auth.json → 请求 OpenCode 官方额度接口 → 返回归一化 JSON（`rolling` / `weekly` / `monthly` 的 `percent` / `remaining` / `resetsAt`）
- `lib/client.js`（Client 半）：`window.__ModuleLoader__.load(...)` 格式的浏览器 bundle，注册到 `shell.overlay` 槽位，轮询该路由并渲染可拖拽胶囊
- 纯 JavaScript，无构建步骤，无第三方运行时依赖（宿主侧仅用 Node 内置 `fetch`）

## License

MIT