dsh-commandcode-quota 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-commandcode-quota 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

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+# dsh-commandcode-quota
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A **Command Code balance and quota panel** for DeepSeek Harness (DSH).
+
+The plugin renders a compact status row directly underneath the DSH composer:
+
+- **5-hour, weekly and monthly usage windows** as live percentages
+- **Available balance**
+- Click the row to expand the full breakdown: used / limit / remaining / reset time, total spend, tokens, success rate, subscription and account information
+
+It is **single-account by design**. There is no account switcher, and your API key never reaches the browser.
+
+## Requirements
+
+- DeepSeek Harness with the Web client (`dsh web` or the desktop app)
+- Node.js 20 or newer
+- A Command Code API key
+
+## Install
+
+### From npm (recommended)
+
+```bash
+dsh plugin add dsh-commandcode-quota
+```
+
+DSH expands the bundled `cordis.patch.yml` into your profile, so no manual patch editing is needed.
+
+### From a local checkout
+
+```bash
+dsh plugin add file:/path/to/dsh-commandcode-quota
+```
+
+### Manual junction (desktop app)
+
+The Electron desktop profile is managed by the application and does not run the `dsh plugin add` reconciliation, so register it yourself.
+
+Link the package into the shared resolution pool:
+
+```powershell
+New-Item -ItemType Junction `
+  -Path "$env:USERPROFILE\.dsh\profiles\node_modules\dsh-commandcode-quota" `
+  -Target "C:\path\to\dsh-commandcode-quota"
+```
+
+Then add this to `~/.dsh/profiles/<profile>/cordis.patch.yml`:
+
+```yaml
+- insert:
+    - id: dsh-commandcode-quota
+      name: 'dsh-commandcode-quota'
+      config:
+        apiKeyEnv: COMMANDCODE_API_KEY
+```
+
+> The junction name must be exactly the package name, otherwise the host cannot resolve the import.
+
+After installing or changing the plugin, reload the plugin tree (the plugin page's refresh action, or a client restart).
+
+## Configuration
+
+| Key | Default | Description |
+|---|---|---|
+| `apiKeyEnv` | `COMMANDCODE_API_KEY` | Credential entry resolved through DSH's credentials service |
+| `fallbackEnv` | — | Optional second entry, used only when the first one is missing |
+| `baseURL` | `https://api.commandcode.ai` | Command Code API origin |
+| `timeoutMs` | `30000` | Per-request timeout in milliseconds |
+
+Credentials live in `~/.dsh/.credentials.yaml`, or in DSH Settings → Credentials. Never commit them.
+
+## How it works
+
+The package has two halves:
+
+- **Host half** (`src/index.js`) resolves the key through the DSH credentials service and registers a read-only HTTP endpoint that fans out to the Command Code API, then aggregates the responses into a single payload. The key is read on every request and never serialized to the client.
+- **Client half** (`src/client.js`) registers a status row into the composer dock slot, polls the host endpoint, and renders it with DSH theme tokens so light and dark themes both work.
+
+Data comes from four Command Code endpoints, each called with `Authorization: Bearer <key>`:
+
+| Endpoint | Used for |
+|---|---|
+| `GET /alpha/billing/credits` | Balance and the 5-hour / weekly limits |
+| `GET /alpha/usage/summary` | Spend, tokens and success rate |
+| `GET /alpha/billing/subscriptions` | Subscription status and period boundaries |
+| `GET /alpha/whoami` | Account information |
+
+The monthly window is composed from the usage total plus the remaining credits, with the reset time taken from the subscription period.
+
+### Behaviour under failure
+
+- The four requests run in parallel, so total latency is the slowest one rather than the sum.
+- A connection-level failure is retried once; a deliberate timeout is not retried.
+- On failure the panel falls back to the last successful value (kept in-process for 6 hours) and reports it as stale.
+- An HTTP 401 is never masked by cached data, because it means the credential itself is wrong.
+
+## Development
+
+```bash
+npm test                        # host and client unit tests; no network, no DSH process
+node --check src/index.js       # host half syntax
+node --check src/client.js      # client half syntax
+```
+
+The tests stub the credentials service, the web server, `fetch` and React, so they run offline and never touch a live DSH instance.
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,109 @@
+# dsh-commandcode-quota
+
+一个面向 DeepSeek Harness（DSH）的 **Command Code 余额与额度面板**插件。
+
+插件会在 DSH 输入框正下方渲染一行常驻状态栏：
+
+- **5 小时、每周、每月**三个额度窗口的实时百分比
+- **可用余额**
+- 点击状态栏展开完整明细：已用 / 上限 / 剩余 / 重置时间、总消耗、Tokens、成功率，以及订阅和账户信息
+
+**刻意做成单账号**：没有账号切换，API key 也不会进入浏览器。
+
+## 环境要求
+
+- 带 Web 客户端的 DeepSeek Harness（`dsh web` 或桌面端）
+- Node.js 20 及以上
+- 一个 Command Code API key
+
+## 安装
+
+### 从 npm 安装（推荐）
+
+```bash
+dsh plugin add dsh-commandcode-quota
+```
+
+DSH 会把包内自带的 `cordis.patch.yml` 展开进你的 profile，不需要手工改补丁。
+
+### 从本地目录安装
+
+```bash
+dsh plugin add file:/path/to/dsh-commandcode-quota
+```
+
+### 手动链接（桌面端）
+
+桌面端的 Electron profile 由应用托管，不会走 `dsh plugin add` 的展开流程，需要自己注册。
+
+先把包链接进共享解析池：
+
+```powershell
+New-Item -ItemType Junction `
+  -Path "$env:USERPROFILE\.dsh\profiles\node_modules\dsh-commandcode-quota" `
+  -Target "C:\path\to\dsh-commandcode-quota"
+```
+
+再往 `~/.dsh/profiles/<profile>/cordis.patch.yml` 里加：
+
+```yaml
+- insert:
+    - id: dsh-commandcode-quota
+      name: 'dsh-commandcode-quota'
+      config:
+        apiKeyEnv: COMMANDCODE_API_KEY
+```
+
+> 链接名必须和包名完全一致，否则宿主端解析不到这个 import。
+
+安装或改动插件后，重载插件树（插件页的「刷新」，或重启客户端）才生效。
+
+## 配置
+
+| 配置项 | 默认值 | 说明 |
+|---|---|---|
+| `apiKeyEnv` | `COMMANDCODE_API_KEY` | 通过 DSH 凭据服务解析的凭据条目名 |
+| `fallbackEnv` | 无 | 可选的备用条目，仅在首选缺失时使用 |
+| `baseURL` | `https://api.commandcode.ai` | Command Code API 地址 |
+| `timeoutMs` | `30000` | 单次请求超时（毫秒） |
+
+凭据写在 `~/.dsh/.credentials.yaml`，或在 DSH 设置 → 凭据里添加。**不要提交到仓库。**
+
+## 工作原理
+
+包分宿主端和客户端两半：
+
+- **宿主端**（`src/index.js`）通过 DSH 凭据服务解析 key，注册一个只读 HTTP 端点，并发请求 Command Code API 后聚合成一个响应。key 每次请求现读，绝不序列化给客户端。
+- **客户端**（`src/client.js`）往输入框的 dock 槽位注册状态栏，轮询宿主端点，并全部使用 DSH 主题 token 渲染，自动适配深色/浅色主题。
+
+数据来自四个 Command Code 接口，均带 `Authorization: Bearer <key>`：
+
+| 接口 | 用途 |
+|---|---|
+| `GET /alpha/billing/credits` | 余额，以及 5 小时 / 每周限额 |
+| `GET /alpha/usage/summary` | 消耗、Tokens、成功率 |
+| `GET /alpha/billing/subscriptions` | 订阅状态与周期起止 |
+| `GET /alpha/whoami` | 账户信息 |
+
+每月窗口是合成值：已用取用量汇总，总额为已用加剩余额度，重置时间取订阅周期末。
+
+## 失败时的行为
+
+- 四个请求并发发出，总耗时等于最慢的一个，而不是四者之和。
+- 连接级失败重试一次；主动超时不重试。
+- 请求失败时回退到上次成功的值（进程内保留 6 小时），并标记为陈旧数据。
+- HTTP 401 不会被缓存掩盖——它意味着凭据本身有问题，必须让用户看到。
+
+## 开发
+
+```bash
+npm test                        # 宿主端与客户端单元测试；不联网、不依赖运行中的 DSH
+node --check src/index.js       # 宿主端语法检查
+node --check src/client.js      # 客户端语法检查
+```
+
+测试对凭据服务、Web 服务器、`fetch` 和 React 都使用了替身，因此可离线运行，也不会碰到真实的 DSH 实例。
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,21 @@
+# dsh-commandcode-quota 补丁层：向 profile 注册 Command Code 额度看板。
+# 注册 ID 与包名一致；用 `dsh plugin add` 安装时本层会被展开到 profile。
+#
+# 默认从凭据条目 COMMANDCODE_API_KEY 读取 key。要换条目名、加回退条目或改用
+# 其它地址，在你自己的 profile 补丁里按同样结构覆盖：
+#
+#   - id: dsh-commandcode-quota
+#     name: 'dsh-commandcode-quota'
+#     config:
+#       apiKeyEnv: MY_COMMANDCODE_KEY
+#       fallbackEnv: MY_BACKUP_KEY         # 可选：首选缺失时回退
+#       baseURL: https://api.commandcode.ai
+#
+# 凭据写在 ~/.dsh/.credentials.yaml，或在 DSH 设置 → 凭据 里添加。
+# 改完需要重载插件树（插件页「刷新」或重启客户端）才生效。
+- insert:
+    - id: dsh-commandcode-quota
+      name: 'dsh-commandcode-quota'
+      config:
+        apiKeyEnv: COMMANDCODE_API_KEY
+        baseURL: https://api.commandcode.ai

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Command Code Quota",
+    "description": "View Command Code balance, quotas and usage below the DeepSeek Harness input, including monthly, five-hour and weekly windows."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Command Code Quota",
+    "description": "在 DeepSeek Harness 输入框下方查看 Command Code 余额、额度与用量，支持月度、5 小时和每周窗口。"
+  }
+}

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "dsh-commandcode-quota",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Command Code balance and quota panel for DeepSeek Harness: a status row under the composer showing balance and the 5-hour, weekly and monthly windows.",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "command-code",
+    "commandcode",
+    "balance",
+    "usage",
+    "quota",
+    "status-bar"
+  ],
+  "files": [
+    "src/",
+    "locale/",
+    "test/",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./client": "./src/client.js",
+    "./locale/*": "./locale/*",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "test": "node test/host.test.cjs && node test/client.test.cjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fuqiancheng/dsh-commandcode-quota.git"
+  },
+  "homepage": "https://github.com/fuqiancheng/dsh-commandcode-quota#readme",
+  "bugs": {
+    "url": "https://github.com/fuqiancheng/dsh-commandcode-quota/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-credentials": "*"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-credentials": {
+      "optional": true
+    }
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-ui-conversation"
+      ],
+      "platform": "web"
+    }
+  }
+}