modelquota 0.1.0 → 0.1.1

package/README.md

@@ -2,6 +2,8 @@
 
 opencode 插件：在 TUI 右侧栏实时显示**当前正在使用的模型供应商**的套餐余量。
 
+> 📖 完整使用教程和发布说明见：[docs/PUBLISH.md](docs/PUBLISH.md)
+
 ## 功能
 
 - **按当前模型显示**：右侧栏只显示当前会话正在使用的模型对应供应商（跟随模型切换，发消息后立即更新）

package/docs/PUBLISH.md

@@ -0,0 +1,186 @@
+# modelquota 发布与使用指南
+
+opencode 插件：在 TUI 右侧栏实时显示**当前正在使用的模型供应商**的套餐余量。
+
+- **npm 包名**：`modelquota`
+- **当前版本**：0.1.0
+- **维护者**：liuqingshan
+- **仓库**：D:\Jared\plan\modelquota（本地开发目录）
+
+---
+
+## 一、发布流程（维护者用）
+
+### 1. 准备
+
+```bash
+npm config set registry https://registry.npmjs.org   # 发布必须用官方源
+npm login                                             # 或用 Access Token
+```
+
+### 2. 改版本号
+
+每次发布前，在 `package.json` 里把 `version` 改成新版本号（语义化版本）：
+
+```json
+"version": "0.2.0"
+```
+
+### 3. 发布
+
+```bash
+npm run build       # 编译 TS → dist/（prepublishOnly 会自动跑，可省略）
+npm publish         # 发布到 npm
+```
+
+发布前会自动执行 `prepublishOnly`（编译 dist），`files` 只包含 `dist/` 和 `README.md`，不会泄漏源码和密钥。
+
+### 4. 验证
+
+```bash
+curl -s https://registry.npmjs.org/modelquota | grep -o '"latest":"[^"]*"'
+```
+
+### 5. 注意事项
+
+- **npm 包名占用**：`modelquota` 在发布前未被占用（2026-08-02 验证）
+- **2FA**：npm 新政策要求发布时 2FA。本项目发布用 **Granular Access Token**（Permissions 选 Read and write，勾选 Bypass 2FA），token 已配置在 `~/.npmrc`，换机器需要重新生成
+- **registry**：发布必须用官方源 `https://registry.npmjs.org`，日常下载可以切回国内镜像
+- **不要发布的内容**：src/ 源码、scripts/、tsconfig、任何含 API key / cookie 的文件（`files` 字段已排除）
+
+---
+
+## 二、使用教程（别人怎么用）
+
+### 1. 安装（需要 opencode 1.18+）
+
+在 `~/.config/opencode/opencode.json`（全局）或项目 `opencode.json` 的 `plugin` 数组加：
+
+```json
+{
+  "plugin": ["modelquota"]
+}
+```
+
+TUI 插件需要单独注册，在 `~/.config/opencode/tui.json` 加：
+
+```json
+{
+  "plugin": ["modelquota"]
+}
+```
+
+重启 opencode 生效。
+
+### 2. 配置供应商 API Key
+
+**无需额外配置**——直接复用 opencode 现有的 provider 配置。在 opencode.json 的 `provider` 里配置了对应供应商，插件就会自动查询显示（有 key 才显示）：
+
+| 供应商 | provider id | 显示内容 |
+|--------|------------|---------|
+| DeepSeek | `deepseek` | 余额（CNY） |
+| Kimi For Coding | `kimiforcoding` | 周 / 5h 配额（次）+ 并发 |
+| MiniMax | `minimax` | 5h / 周 已用百分比 + 加成 x1.5 |
+| 智谱 GLM | `zhipu` | 5h / 周 已用百分比 |
+| OpenCode Go | （见下文） | 5h / 周 / 月 已用百分比 |
+
+示例（opencode.json）：
+
+```json
+{
+  "provider": {
+    "deepseek": {
+      "npm": "@ai-sdk/openai-compatible",
+      "options": {
+        "apiKey": "sk-你的key",
+        "baseURL": "https://api.deepseek.com/v1"
+      }
+    },
+    "kimiforcoding": {
+      "npm": "@ai-sdk/anthropic",
+      "options": {
+        "apiKey": "sk-kimi-你的key",
+        "baseURL": "https://api.kimi.com/coding/v1"
+      }
+    },
+    "minimax": {
+      "npm": "@ai-sdk/openai-compatible",
+      "options": {
+        "apiKey": "sk-cp-你的key",
+        "baseURL": "https://api.minimaxi.com/v1"
+      }
+    },
+    "zhipu": {
+      "npm": "@ai-sdk/openai-compatible",
+      "options": {
+        "apiKey": "你的智谱key",
+        "baseURL": "https://open.bigmodel.cn/api/paas/v4"
+      }
+    }
+  }
+}
+```
+
+### 3. OpenCode Go 用量（需要额外配置）
+
+OpenCode Go 没有公开的 API 查询接口，插件通过浏览器登录态 cookie 调用官方控制台的 server action 获取用量。
+
+在 `~/.config/opencode/modelquota.json` 配置：
+
+```json
+{
+  "opencodeGo": {
+    "cookie": "你的 auth cookie",
+    "serverId": "控制台 server action 的 id",
+    "workspaceId": "你的 workspace id"
+  }
+}
+```
+
+**获取方法**：
+
+1. 浏览器登录 https://opencode.ai/auth
+2. 打开 https://opencode.ai/workspace/<你的workspaceID>/go 页面
+3. 按 F12 → Network 面板，刷新页面，找到 `_server?id=xxx&args=...` 的请求
+4. 取数：
+   - `id=` 后面的值 → `serverId`
+   - 请求头 Cookie 里的 `auth=xxx` → `cookie`
+   - URL 中的 `wrk_xxx` → `workspaceId`
+
+> cookie 有效期约 1 年，过期后重新抓取一次即可。
+> 未配置或 cookie 过期时，面板会显示友好提示（区分"未配置 / 登录过期 / 接口异常"）。
+
+### 4. 使用效果
+
+- 右侧栏只显示**当前会话正在使用的模型**对应供应商（跟随模型切换）
+- 发消息后立即更新当前供应商
+- 统一"已用视角"：>80% 红 / >50% 黄
+
+---
+
+## 三、工作原理
+
+```
+┌─────────────────────────┐     mirror JSON      ┌─────────────────────────┐
+│  server plugin          │  ───────────────────▶ │  TUI plugin             │
+│  循环查各供应商套餐 API   │  ~/.local/share/     │  渲染到 sidebar_content │
+│  写快照 + 当前模型       │  opencode/storage/   │  slot（跟随当前模型）    │
+└─────────────────────────┘  modelquota/<hash>.json                        │
+```
+
+- 当前模型通过 `chat.message` 事件实时记录（每次发消息更新）
+- TUI 端从 sync 缓存（Solid 响应式）读取消息流，自动跟随模型切换
+- mirror 文件原子写入，避免读取半截 JSON
+
+## 四、开发
+
+```bash
+npm install
+npm run typecheck   # 类型检查
+npm run build       # 编译到 dist/
+npm run deploy      # 部署到本地全局插件目录（开发用）
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modelquota",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "opencode 插件：在 TUI 右侧栏显示当前使用的模型供应商套餐余量",
   "keywords": [
@@ -28,7 +28,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",