dsh-opencode-go-usage 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 opencode-go-usage contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+# dsh-opencode-go-usage
+
+English | [中文](README.zh.md)
+
+A [DSH](https://github.com/deepseek-ai/deepseek-harness) (DeepSeek Harness) plugin that watches your **OpenCode GO plan** quota — the $10/month subscription that gives you usage limits on open-source models (rolling 5-hour, weekly, and monthly windows).
+
+## Features
+
+- **Sidebar widget** — a live widget pinned at the bottom of the DSH web sidebar (`sidebar.footer.action` slot) showing three usage bars: rolling (5h), weekly, and monthly, each with a relative countdown to its window reset. When the sidebar is collapsed it shrinks to a compact percentage badge.
+- **`/opencode-go` chat command** — prints the same numbers as text inside any conversation.
+- **Same-origin proxy** — the host registers `GET /opencode-go/usage`, forwards to the official GO gateway with your API key. The key never reaches the browser and no CORS is involved.
+
+## How it works
+
+The plugin is a **dual-half DSH package**:
+
+| half | file | role |
+|---|---|---|
+| host (Node) | `lib/index.js` | registers the `/opencode-go/usage` web route (`ctx.webServer`) and the `/opencode-go` command (`ctx.commands`); resolves the key through DSH credentials; caches the upstream call (30 s) |
+| browser | `lib/client.js` | a hand-authored `window.__ModuleLoader__.load({ id, factory })` bundle that registers into the `sidebar.footer.action` list slot and polls the same-origin route every 60 s |
+
+`package.json` declares `"dsh": { "client": { "platform": "web" } }`, so DSH's client-modules node half scans it into the browser boot graph (`window.__DSH_BOOT__`) and serves the bundle at `/plugins/dsh-opencode-go-usage/client.js`.
+
+### How the sidebar widget loads under the official install
+
+`dsh plugin add` installs the package into the profile, which satisfies the host
+half (routes, command, settings). DSH's client-modules scanner can only resolve
+browser bundles from its own installation directory, so a profile-installed
+third-party package would normally lose its browser half — this plugin avoids
+that by **self-hosting** its bundle: the host registers the
+`/dsh-opencode-go-usage/client.js` route and injects its boot-graph row through the
+official `webServer.tapIndex` API. The sidebar widget therefore works from any
+installation location.
+
+## Requirements
+
+- DSH installed and the `web` profile booted at least once (`~/.dsh/profiles/web` exists)
+- Node.js ≥ 18 (for `fetch`)
+- An OpenCode GO subscription and its API key
+
+## Install (official DSH flow)
+
+Requirements: DSH installed with the `web` profile booted once, Node.js ≥ 18,
+an OpenCode GO subscription.
+
+```bash
+# 1. install the package into your web profile (pnpm; enable via corepack if needed)
+dsh plugin --profile web add dsh-opencode-go-usage
+
+# 2. store your GO API key as a DSH credential
+#    (create the key at https://opencode.ai/auth)
+#    → add to ~/.dsh/.credentials.yaml:
+#      OPENCODE_GO_API_KEY: sk-...
+
+# 3. restart `dsh web` and hard-refresh the browser page
+```
+
+That's it for the quota widget and `/opencode-go` command. The CLI reconciles
+the package's `dsh.bundle.patch` into the profile's bundle stack automatically
+— no manual `cordis.patch.yml` editing, no symlinks.
+
+Not published on npm yet? Install from a checkout instead:
+
+```bash
+dsh plugin --profile web add /path/to/dsh-opencode-go-usage
+```
+
+> New to DSH plugins? Follow the [user guide](docs/INSTALL.zh.md) (Chinese, step-by-step).
+
+## Usage
+
+- **Widget**: read it. Collapsed sidebar → percentage badge; expanded → three progress bars with reset countdowns.
+- **Command**: `/opencode-go` in any conversation prints the three windows as text.
+
+## Config reference
+
+| key | default | description |
+|---|---|---|
+| key | default | description |
+|---|---|---|
+| `apiKeyEnv` | `OPENCODE_GO_API_KEY` | credential reference / env var name for the API key |
+| `baseUrl` | `https://opencode.ai/zen/go` | gateway base URL |
+| `cacheMs` | `30000` | host-side upstream cache TTL |
+
+## The usage API
+
+`GET https://opencode.ai/zen/go/v1/usage` with `Authorization: Bearer <key>`:
+
+```json
+{
+  "usage": {
+    "rolling": { "status": "ok", "percent": 0,  "resetsAt": "2026-08-14T07:51:13Z" },
+    "weekly":  { "status": "ok", "percent": 1,  "resetsAt": "2026-08-17T00:00:00Z" },
+    "monthly": { "status": "ok", "percent": 22, "resetsAt": "2026-08-21T13:05:13Z" }
+  }
+}
+```
+
+## Developing / modifying the widget
+
+The browser half is a **hand-authored factory bundle** (`window.__ModuleLoader__.load`), because out-of-tree client plugins have no public build pipeline yet. It may only `require()` modules from the shell module table (`react`, `react/jsx-runtime`, and the registered client packages). Edit `lib/client.js` directly, then restart `dsh web` and refresh the page — the bundle revision hash changes and the shell loads the new file.
+
+Host changes (`lib/index.js`) need only a `dsh web` restart.
+
+## Troubleshooting
+
+- **Widget missing after restart** → hard-refresh the page (`Cmd/Ctrl+Shift+R`); the boot graph is injected per page load.
+- **`/opencode-go/usage` returns 502 with "no API key"** → configure the key in `~/.dsh/.credentials.yaml`.
+- **Gateway 401/403** → the key is invalid or the subscription lapsed; check the credential.
+- **Widget shows an error string** → hover the collapsed badge or read the error line in the expanded widget.
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,108 @@
+# dsh-opencode-go-usage
+
+[English](README.md) | 中文
+
+[DSH](https://github.com/deepseek-ai/deepseek-harness)(DeepSeek Harness)插件:监控你的 **OpenCode GO 套餐**额度 —— 10 美元/月的订阅,按模型提供滚动 5 小时 / 每周 / 每月三个窗口的用量限额。
+
+## 功能
+
+- **侧边栏小组件**:常驻 DSH Web 侧边栏底部(`sidebar.footer.action` 槽位),三条用量进度条:滚动窗口(5h)、周窗口、月窗口,每条带重置倒计时;侧边栏收起时收缩为紧凑的百分比徽标。
+- **`/opencode-go` 聊天命令**:在对话中以文本输出同样的三个窗口数字。
+- **同源代理**:host 端注册 `GET /opencode-go/usage`,携带你的 API key 转发到官方 GO 网关。key 永不进入浏览器,也没有 CORS 问题。
+
+## 工作原理
+
+这是一个**双端 DSH 插件包**:
+
+| 端 | 文件 | 职责 |
+|---|---|---|
+| host(Node) | `lib/index.js` | 注册 `/opencode-go/usage` Web 路由(`ctx.webServer`)与 `/opencode-go` 命令(`ctx.commands`);通过 DSH credentials 解析 key;上游调用带 30s 缓存 |
+| 浏览器 | `lib/client.js` | 手写的 `window.__ModuleLoader__.load({ id, factory })` bundle,注册进 `sidebar.footer.action` 列表槽,每 60s 轮询同源路由 |
+
+`package.json` 声明了 `"dsh": { "client": { "platform": "web" } }`,DSH 的 client-modules 节点端会把它扫描进浏览器启动图(`window.__DSH_BOOT__`),并在 `/plugins/dsh-opencode-go-usage/client.js` 提供该 bundle。
+
+### 官方安装下小组件如何加载
+
+`dsh plugin add` 把包装进 profile,满足 host 端(路由、命令、设置)。DSH 的
+client-modules 扫描器只能从 DSH 自己的安装目录解析浏览器 bundle,所以装在
+profile 里的第三方包通常拿不到浏览器端——本插件通过**自托管**解决:host 端
+注册 `/dsh-opencode-go-usage/client.js` 路由,并用官方 `webServer.tapIndex` API
+把 boot graph 行注入页面。因此侧边栏小组件在任何安装位置都能工作。
+
+## 环境要求
+
+- 已安装 DSH 且 `web` profile 至少启动过一次(`~/.dsh/profiles/web` 存在)
+- Node.js ≥ 18(需要 `fetch`)
+- OpenCode GO 订阅及其 API key
+
+## 安装(官方 DSH 流程)
+
+前置:已装 DSH 且 `web` profile 至少启动过一次;Node.js ≥ 18;有 OpenCode GO 订阅。
+
+```bash
+# 1. 安装到 web profile(依赖 pnpm,没有的话先 corepack enable)
+dsh plugin --profile web add dsh-opencode-go-usage
+
+# 2. 把 GO API key 存为 DSH credential
+#    (key 在 https://opencode.ai/auth 创建)
+#    → 在 ~/.dsh/.credentials.yaml 加一行:
+#      OPENCODE_GO_API_KEY: sk-...
+
+# 3. 重启 dsh web,浏览器硬刷新(Cmd/Ctrl+Shift+R)
+```
+
+到这一步,百分比小组件和 `/opencode-go` 命令就生效了。CLI 会自动把包的
+`dsh.bundle.patch` 合并进 profile 的 bundle 层栈——**不需要手改
+cordis.patch.yml,不需要软链**。
+
+还没发布 npm?从本地目录安装:
+
+```bash
+dsh plugin --profile web add /path/to/dsh-opencode-go-usage
+```
+
+> 第一次装 DSH 插件?直接看[使用者指南](docs/INSTALL.zh.md),一步步照着做就行。
+
+## 使用
+
+- **小组件**:直接看。侧边栏收起 → 百分比徽标;展开 → 三条进度条 + 重置倒计时。
+- **命令**:任意对话里输入 `/opencode-go` 输出三个窗口的文本。
+
+## 配置项
+
+| 键 | 默认 | 说明 |
+|---|---|---|
+| `apiKeyEnv` | `OPENCODE_GO_API_KEY` | API key 的 credential 引用 / 环境变量名 |
+| `baseUrl` | `https://opencode.ai/zen/go` | 网关 base URL |
+| `cacheMs` | `30000` | host 端上游缓存 TTL |
+
+## 用量 API
+
+`GET https://opencode.ai/zen/go/v1/usage`,带 `Authorization: Bearer <key>`:
+
+```json
+{
+  "usage": {
+    "rolling": { "status": "ok", "percent": 0,  "resetsAt": "2026-08-14T07:51:13Z" },
+    "weekly":  { "status": "ok", "percent": 1,  "resetsAt": "2026-08-17T00:00:00Z" },
+    "monthly": { "status": "ok", "percent": 22, "resetsAt": "2026-08-21T13:05:13Z" }
+  }
+}
+```
+
+## 开发 / 修改小组件
+
+浏览器端是**手写的 factory bundle**(`window.__ModuleLoader__.load`),因为目前第三方 client 插件还没有公开的构建流水线。它只能 `require()` shell 模块表里的模块(`react`、`react/jsx-runtime` 以及已注册的 client 包)。直接改 `lib/client.js`,然后重启 `dsh web` 并刷新页面 —— bundle 的 revision hash 会变化,shell 会加载新文件。
+
+host 端(`lib/index.js`)的改动只需重启 `dsh web`。
+
+## 常见问题
+
+- **重启后小组件不出现** → 硬刷新页面(`Cmd/Ctrl+Shift+R`);启动图是按页面加载注入的。
+- **`/opencode-go/usage` 返回 502 且提示 "no API key"** → 在 `~/.dsh/.credentials.yaml` 配置 key。
+- **网关 401/403** → key 无效或订阅过期;检查 credential。
+- **小组件显示错误串** → 悬停收起态徽标,或展开态小组件里的错误行。
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,12 @@
+# dsh-opencode-go-usage — profile bundle patch.
+#
+# `dsh plugin --profile web add dsh-opencode-go-usage` installs this package and,
+# because package.json declares `dsh.bundle.patch`, reconciles it into the
+# profile's `dsh.profile.bundles` layer stack automatically — no manual
+# cordis.patch.yml editing. This file is that bundle layer: it inserts the
+# plugin entry with schema defaults; user overrides live in the settings
+# namespace (Web Settings → Plugins → Plugin configuration) or in
+# `~/.dsh/settings.yaml` under `dsh-opencode-go-usage`.
+- insert:
+    - id: dsh-opencode-go-usage
+      name: dsh-opencode-go-usage

package/lib/client.js

@@ -0,0 +1,191 @@
+// dsh-opencode-go-usage — browser half.
+//
+// Hand-authored client bundle in the DSH module-loader factory format:
+// `window.__ModuleLoader__.load({ id, factory })`. The factory receives the
+// module-table `require`, so only shell-externalized modules may be imported
+// (react / react/jsx-runtime are in the static table). It registers a widget
+// into the sidebar's `sidebar.footer.action` list slot and polls the
+// same-origin proxy route owned by the host half — the GO API key never
+// enters the browser.
+window.__ModuleLoader__.load({
+	id: "dsh-opencode-go-usage",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+
+		let react_jsx_runtime = require("react/jsx-runtime");
+		let react = require("react");
+
+		// ── styles (injected once, same pattern as built-in client plugins) ──
+		const CSS_ID = "dsh-opencode-go-usage/widget.css";
+		if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=\"" + CSS_ID + "\"]") === null) {
+			const tag = document.createElement("style");
+			tag.dataset.plugin = "dsh-opencode-go-usage";
+			tag.dataset.pluginCss = CSS_ID;
+			tag.textContent = [
+				".ocg-widget{box-sizing:border-box;width:100%;min-width:0;padding:8px 6px;display:flex;flex-direction:column;gap:6px;border-top:1px solid var(--dsw-alias-border-l2);color:var(--dsw-alias-label-primary)}",
+				".ocg-widget:hover{background:var(--dsw-alias-interactive-bg-hover)}",
+				".ocg-head{display:flex;align-items:center;justify-content:space-between;gap:8px;font-size:12px;font-weight:600;line-height:18px}",
+				".ocg-refresh{cursor:pointer;border:none;background:none;padding:0;color:var(--dsw-alias-label-secondary);font-size:11px;line-height:18px}",
+				".ocg-refresh:hover{color:var(--dsw-alias-label-primary)}",
+				".ocg-row{display:flex;flex-direction:column;gap:3px;min-width:0}",
+				".ocg-row-label{display:flex;justify-content:space-between;gap:8px;font-size:11px;line-height:16px;color:var(--dsw-alias-label-secondary)}",
+				".ocg-row-label b{font-weight:500;color:var(--dsw-alias-label-primary)}",
+				".ocg-track{box-sizing:border-box;height:5px;border-radius:3px;background:var(--dsw-alias-border-l2);overflow:hidden}",
+				".ocg-fill{height:100%;border-radius:3px;transition:width .4s ease}",
+				".ocg-err{font-size:11px;line-height:16px;color:var(--dsw-alias-label-secondary);overflow:hidden;text-overflow:ellipsis;white-space:nowrap}",
+				".ocg-rail{box-sizing:border-box;width:36px;height:36px;display:flex;align-items:center;justify-content:center;border-radius:8px;font-size:10px;font-weight:700;color:var(--dsw-alias-label-primary);cursor:default}",
+				".ocg-rail:hover{background:var(--dsw-alias-interactive-bg-hover)}"
+			].join("");
+			document.head.appendChild(tag);
+		}
+
+		// ── data helpers ──
+		const WINDOWS = [
+			{ key: "rolling", label: "滚动窗口", hint: "5 小时" },
+			{ key: "weekly", label: "周窗口" },
+			{ key: "monthly", label: "月窗口" }
+		];
+
+		/** Short human relative time until `iso`. */
+		function timeUntil(iso) {
+			const target = new Date(iso).getTime();
+			if (!Number.isFinite(target)) return "";
+			const diff = target - Date.now();
+			if (diff <= 0) return "即将重置";
+			const mins = Math.floor(diff / 60000);
+			if (mins < 60) return mins + " 分后重置";
+			const hours = Math.floor(mins / 60);
+			if (hours < 24) return hours + " 小时 " + (mins % 60) + " 分后";
+			return Math.floor(hours / 24) + " 天 " + (hours % 24) + " 小时后";
+		}
+
+		/** Fill color by usage percent. */
+		function fillColor(percent) {
+			if (percent >= 90) return "#ff3b30";
+			if (percent >= 70) return "#ff9500";
+			return "#34c759";
+		}
+
+		// ── widget component ──
+		/**
+		 * @param {{ wide?: boolean }} props - owner share from the sidebar
+		 * (`sidebar.footer.action` is rendered with `{ wide }`).
+		 */
+		function Widget(props) {
+			const [data, setData] = react.useState(null);
+			const [error, setError] = react.useState(null);
+			const [stamp, setStamp] = react.useState(0);
+
+			react.useEffect(() => {
+				let alive = true;
+				const load = async () => {
+					try {
+						const res = await fetch("/opencode-go/usage", { cache: "no-store" });
+						const json = await res.json().catch(() => null);
+						if (!alive) return;
+						if (!res.ok || json === null || json.error) {
+							setError(String((json && json.error) || "HTTP " + res.status));
+							setData(null);
+						} else {
+							setData(json);
+							setError(null);
+						}
+					} catch (e) {
+						if (!alive) return;
+						setError(String((e && e.message) || e));
+						setData(null);
+					}
+				};
+				load();
+				const timer = window.setInterval(load, 60000);
+				return () => { alive = false; window.clearInterval(timer); };
+			}, [stamp]);
+
+			const monthly = data && data.usage ? data.usage.monthly : null;
+			const pct = monthly && typeof monthly.percent === "number" ? monthly.percent : null;
+
+			// Collapsed rail: a compact badge with the monthly percentage.
+			if (!props.wide) {
+				return react_jsx_runtime.jsx("div", {
+					className: "ocg-rail",
+					title: error ? ("OpenCode GO: " + error) : (pct === null ? "OpenCode GO" : "OpenCode GO 月用量 " + pct + "%"),
+					children: pct === null ? "GO" : pct + "%"
+				});
+			}
+
+			// Expanded footer widget: three window progress bars.
+			const rows = [];
+			for (const w of WINDOWS) {
+				const win = data && data.usage ? data.usage[w.key] : null;
+				if (!win || typeof win.percent !== "number") continue;
+				rows.push(react_jsx_runtime.jsx("div", {
+					className: "ocg-row",
+					children: [
+						react_jsx_runtime.jsx("div", {
+							className: "ocg-row-label",
+							children: [
+								react_jsx_runtime.jsx("b", { children: w.label }),
+								react_jsx_runtime.jsx("span", { children: (win.resetsAt ? timeUntil(win.resetsAt) : w.hint) })
+							]
+						}),
+						react_jsx_runtime.jsx("div", {
+							className: "ocg-track",
+							children: react_jsx_runtime.jsx("div", {
+								className: "ocg-fill",
+								style: {
+									width: Math.max(0, Math.min(100, win.percent)) + "%",
+									background: fillColor(win.percent)
+								}
+							})
+						}),
+						react_jsx_runtime.jsx("div", {
+							className: "ocg-row-label",
+							children: [
+								react_jsx_runtime.jsx("span", { children: win.status === "ok" ? "正常" : win.status }),
+								react_jsx_runtime.jsx("span", { children: win.percent + "%" })
+							]
+						})
+					]
+				}, w.key));
+			}
+
+			return react_jsx_runtime.jsx("div", {
+				className: "ocg-widget",
+				children: [
+					react_jsx_runtime.jsx("div", {
+						className: "ocg-head",
+						children: [
+							react_jsx_runtime.jsx("span", { children: "OpenCode GO" }),
+							react_jsx_runtime.jsx("button", {
+								className: "ocg-refresh",
+								onClick: () => setStamp(stamp + 1),
+								children: "刷新"
+							})
+						]
+					}),
+					error ? react_jsx_runtime.jsx("div", { className: "ocg-err", children: error }) : null,
+					!error && data === null ? react_jsx_runtime.jsx("div", { className: "ocg-err", children: "加载中…" }) : null,
+					rows.length > 0 ? react_jsx_runtime.jsx(react.Fragment, { children: rows }) : null
+				]
+			});
+		}
+
+		// ── cordis plugin entry ──
+		const inject = ["slots"];
+
+		function apply(ctx) {
+			ctx.effect(() => ctx.slots.register({
+				name: "sidebar.footer.action",
+				id: "dsh-opencode-go-usage",
+				order: 0,
+				label: "OpenCode GO 用量"
+			}, Widget), "dsh-opencode-go-usage: widget registration");
+		}
+
+		exports.apply = apply;
+		exports.inject = inject;
+		return module.exports;
+	}
+});

package/lib/index.js

@@ -0,0 +1,234 @@
+// @ts-check
+/**
+ * dsh-opencode-go-usage — host half.
+ *
+ * Watches your OpenCode GO plan quota through the official gateway endpoint
+ * (`https://opencode.ai/zen/go/v1/usage`). Proxied through a same-origin route
+ * so the browser widget never sees your API key and no CORS is involved.
+ *
+ * - `GET /opencode-go/usage` — quota proxy (rolling / weekly / monthly window
+ *   percentages from the official API).
+ * - `/opencode-go` chat command — prints the same numbers as text.
+ * - Browser bundle self-hosted at `/dsh-opencode-go-usage/client.js` with its boot
+ *   graph row injected through the official `webServer.tapIndex` API, so the
+ *   sidebar widget works from any installation location.
+ *
+ * Installation / configuration (official DSH flows):
+ *   - Install: `dsh plugin --profile web add dsh-opencode-go-usage` — the
+ *     `dsh.bundle.patch` declaration makes the CLI reconcile this package into
+ *     the profile's bundle layer stack automatically (no manual patch edits).
+ *   - Configure: the `dsh-opencode-go-usage` settings namespace (Web Settings →
+ *     Plugins → Plugin configuration, or `~/.dsh/settings.yaml`). The API key
+ *     itself lives in the credentials domain (`OPENCODE_GO_API_KEY`), never in
+ *     settings.
+ *
+ * Settings namespace `dsh-opencode-go-usage`:
+ *   - apiKeyEnv: credential ref / env var for the API key (default OPENCODE_GO_API_KEY)
+ *   - baseUrl:   GO gateway base (default https://opencode.ai/zen/go)
+ *   - cacheMs:   host-side cache TTL (default 30000)
+ */
+
+import { readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import z from "@deepseek-ai/schemastery";
+
+export const name = "dsh-opencode-go-usage";
+
+/** Required services: web routes, chat commands, credentials, settings. */
+export const inject = ["webServer", "commands", "credentials", "settings"];
+
+/** Settings namespace owned by this plugin. */
+export const namespace = "dsh-opencode-go-usage";
+
+const DEFAULT_BASE_URL = "https://opencode.ai/zen/go";
+const DEFAULT_API_KEY_ENV = "OPENCODE_GO_API_KEY";
+const DEFAULT_CACHE_MS = 30_000;
+
+/** Settings schema for this plugin's namespace. */
+export const Config = z.object({
+	apiKeyEnv: z.string().default(DEFAULT_API_KEY_ENV),
+	baseUrl: z.string().default(DEFAULT_BASE_URL),
+	cacheMs: z.number().default(DEFAULT_CACHE_MS)
+});
+
+/**
+ * Resolve the API key through the DSH credentials service
+ * (process env, `$DSH_HOME/.credentials.yaml`, `.env` layers).
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {string} refName
+ */
+async function resolveApiKey(ctx, refName) {
+	const hit = await ctx.credentials.resolve(refName);
+	return hit?.value ?? null;
+}
+
+/** Fetch the GO plan quota payload from the gateway. */
+async function fetchUsage(baseUrl, apiKey) {
+	const res = await fetch(`${baseUrl.replace(/\/+$/, "")}/v1/usage`, {
+		headers: { Authorization: `Bearer ${apiKey}` },
+		signal: AbortSignal.timeout(15_000)
+	});
+	if (!res.ok) {
+		const body = await res.text().catch(() => "");
+		throw new Error(`gateway ${res.status}: ${body.slice(0, 300)}`);
+	}
+	return await res.json();
+}
+
+/** Human-friendly chat output. */
+function renderUsageText(data) {
+	const u = data?.usage;
+	if (!u || typeof u !== "object") return "OpenCode GO: unexpected response shape.";
+	const lines = ["OpenCode GO 套餐用量:"];
+	const defs = [
+		["rolling", "滚动窗口 (5h)"],
+		["weekly", "周窗口"],
+		["monthly", "月窗口"]
+	];
+	for (const [key, label] of defs) {
+		const w = u[key];
+		if (!w || typeof w.percent !== "number") continue;
+		const status = w.status === "ok" ? "正常" : w.status;
+		const resets = w.resetsAt ? `重置于 ${new Date(w.resetsAt).toLocaleString("zh-CN")}` : "";
+		lines.push(`  ${label}: ${w.percent}% (${status})${resets ? `, ${resets}` : ""}`);
+	}
+	return lines.join("\n");
+}
+
+/** Short content hash used as the bundle revision. */
+function shortHash(input) {
+	return createHash("sha1").update(input).digest("hex").slice(0, 12);
+}
+
+/**
+ * Inject one graph row into the index.html boot manifest
+ * (`window.__DSH_BOOT__ = [...]`), skipping when the id is already present.
+ * @param {string} html
+ * @param {{ id: string, url: string, rev: string, inject?: string[], immediately?: boolean }} row
+ * @returns the transformed html.
+ */
+function injectGraphRow(html, row) {
+	const marker = "window.__DSH_BOOT__ = ";
+	const start = html.indexOf(marker);
+	if (start === -1) return html;
+	const bodyStart = start + marker.length;
+	const end = html.indexOf("</script>", bodyStart);
+	if (end === -1) return html;
+	let graph;
+	try {
+		graph = JSON.parse(html.slice(bodyStart, end).trim());
+	} catch {
+		return html;
+	}
+	if (!Array.isArray(graph)) return html;
+	if (graph.some((entry) => entry !== null && typeof entry === "object" && entry.id === row.id)) return html;
+	graph.push(row);
+	// Keep the same escaping client-modules uses so the payload cannot break
+	// out of the script element.
+	return html.slice(0, bodyStart) + JSON.stringify(graph).replaceAll("<", "\\u003c") + html.slice(end);
+}
+
+/**
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {Record<string, unknown>} rawConfig - loader entry config (becomes the settings `base` layer).
+ */
+export function apply(ctx, rawConfig = {}) {
+	// Register the settings namespace. The loader entry config (rawConfig) is
+	// handed to the settings seam as `base`, so a legacy manual patch keeps
+	// working while the user document (settings.yaml / Web UI) wins over it.
+	ctx.settings.register(namespace, Config, { base: rawConfig });
+
+	const readConfig = () => {
+		const stored = ctx.settings.get(namespace) ?? {};
+		return {
+			apiKeyEnv: stored.apiKeyEnv,
+			baseUrl: stored.baseUrl,
+			cacheMs: stored.cacheMs
+		};
+	};
+
+	// Host-side cache: one in-flight promise + a TTL, so several open tabs or
+	// the command never hammer the gateway.
+	/** @type {{ at: number, promise: Promise<unknown> } | null} */
+	let quotaCache = null;
+	const quotaOnce = () => {
+		const now = Date.now();
+		const config = readConfig();
+		if (quotaCache !== null && now - quotaCache.at < config.cacheMs) return quotaCache.promise;
+		const promise = (async () => {
+			const key = await resolveApiKey(ctx, config.apiKeyEnv);
+			if (key === null) throw new Error(`OpenCode GO: no API key (set credential ${config.apiKeyEnv})`);
+			return await fetchUsage(config.baseUrl, key);
+		})();
+		quotaCache = { at: now, promise };
+		promise.catch(() => { if (quotaCache?.promise === promise) quotaCache = null; });
+		return promise;
+	};
+
+	const handleUsage = async (_req, res) => {
+		res.setHeader("content-type", "application/json; charset=utf-8");
+		res.setHeader("cache-control", "no-store");
+		try {
+			const data = await quotaOnce();
+			res.end(JSON.stringify(data));
+		} catch (error) {
+			res.statusCode = 502;
+			res.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+		}
+	};
+
+	// Same-origin route the browser widget polls.
+	ctx.webServer.register({
+		kind: "exact",
+		path: "/opencode-go/usage",
+		handler: handleUsage
+	});
+
+	// ── self-host the browser bundle ───────────────────────────────────────
+	// client-modules can only resolve packages reachable from DSH's own
+	// installation; a profile-installed third-party package would lose its
+	// browser half. Instead we serve the bundle ourselves and inject its boot
+	// graph row through the official index-tap API, so the sidebar widget
+	// works from any installation location.
+	const bundlePath = new URL("./client.js", import.meta.url);
+	let bundleBytes = null;
+	try {
+		bundleBytes = readFileSync(bundlePath);
+	} catch {
+		// Package installed without lib/client.js — widget unavailable; the
+		// route and command above still work.
+	}
+	if (bundleBytes !== null) {
+		const rev = shortHash(bundleBytes);
+		ctx.webServer.register({
+			kind: "exact",
+			path: "/dsh-opencode-go-usage/client.js",
+			handler: async (_req, res) => {
+				res.setHeader("content-type", "text/javascript; charset=utf-8");
+				res.setHeader("cache-control", "no-cache");
+				res.end(bundleBytes);
+			}
+		});
+		ctx.webServer.tapIndex((html) => injectGraphRow(html, {
+			id: "dsh-opencode-go-usage",
+			url: `/dsh-opencode-go-usage/client.js?rev=${rev}`,
+			rev,
+			inject: ["@deepseek-ai/dsh-client-runtime"],
+			immediately: true
+		}));
+	}
+
+	// Chat command so the numbers are reachable from a conversation too.
+	ctx.commands.register({
+		name: "opencode-go",
+		description: "show OpenCode GO plan usage (rolling/weekly/monthly windows)",
+		handler: async () => {
+			try {
+				const data = await quotaOnce();
+				return { kind: "success", text: renderUsageText(data) };
+			} catch (error) {
+				return { kind: "error", text: error instanceof Error ? error.message : String(error) };
+			}
+		}
+	});
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "dsh-opencode-go-usage",
+  "version": "1.0.0",
+  "description": "DSH (DeepSeek Harness) plugin: OpenCode GO plan quota widget in the sidebar, same-origin usage proxy, and a /opencode-go chat command",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml"
+  ],
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "opencode",
+    "opencode-go",
+    "usage",
+    "quota",
+    "plugin",
+    "cordis"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "license": "MIT",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime"
+      ]
+    }
+  }
+}