@yinxe/opencode-tui-usage 1.0.0 → 1.0.2

package/README.md

@@ -19,20 +19,20 @@ OpenCode TUI 插件，在侧边栏显示用量和额度信息，支持多额度
 ### 从 npm 安装（推荐）
 
 ```bash
-npm install @yinx-in/opencode-tui-usage
+npm install @yinxe/opencode-tui-usage
 ```
 
 ### 从 GitHub Packages 安装
 
 ```bash
 # 设置 registry
-npm config set @yinx-in:registry https://npm.pkg.github.com
+npm config set @yinxe:registry https://npm.pkg.github.com
 
 # 登录（需要 GitHub Personal Access Token）
 echo "YOUR_GITHUB_TOKEN" | npm login --registry=https://npm.pkg.github.com --username=YOUR_GITHUB_USERNAME --email=you@example.com
 
 # 安装
-npm install @yinx-in/opencode-tui-usage
+npm install @yinxe/opencode-tui-usage
 ```
 
 ### 配置插件
@@ -42,7 +42,7 @@ npm install @yinx-in/opencode-tui-usage
 ```json
 {
   "$schema": "https://opencode.ai/tui.json",
-  "plugin": ["@yinx-in/opencode-tui-usage"]
+  "plugin": ["@yinxe/opencode-tui-usage"]
 }
 ```
 
@@ -270,15 +270,15 @@ build → publish-npm + publish-github
      - Secret: 你的 npm access token
 
 3. **scoped 包配置**
-   - 包名 `@yinx-in/opencode-tui-usage` 已在 package.json 中配置
+   - 包名 `@yinxe/opencode-tui-usage` 已在 package.json 中配置
    - `publishConfig.registry` 指定发布到哪个 registry
 
 ### 发布地址
 
 | 平台 | 包名 | 地址 |
 |------|------|------|
-| npm | `@yinx-in/opencode-tui-usage` | https://www.npmjs.com/package/@yinx-in/opencode-tui-usage |
-| GitHub Packages | `@yinx-in/opencode-tui-usage` | https://github.com/Yinxe/opencode-tui-usage/packages |
+| npm | `@yinxe/opencode-tui-usage` | https://www.npmjs.com/package/@yinxe/opencode-tui-usage |
+| GitHub Packages | `@yinxe/opencode-tui-usage` | https://github.com/Yinxe/opencode-tui-usage/packages |
 
 ## License
 

package/dist/components.d.ts

@@ -5,16 +5,28 @@ export interface LabelValueProps {
     value: string | number;
     labelColor?: string;
 }
+/**
+ * 标签-值组件
+ * 显示格式：标签: 值
+ */
 export declare function LabelValue(props: LabelValueProps): JSX.Element;
 export interface TitleProps {
     text: string;
     color?: string;
 }
+/**
+ * 标题组件
+ * 显示带颜色的文本
+ */
 export declare function Title(props: TitleProps): JSX.Element;
 export interface ProgressBarProps {
     value: number;
     color?: string;
     width?: number;
 }
+/**
+ * 进度条组件
+ * 显示格式：[■■■■■■■■□□] 或类似
+ */
 export declare function ProgressBar(props: ProgressBarProps): JSX.Element;
 //# sourceMappingURL=components.d.ts.map

package/dist/components.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"components.d.ts","sourceRoot":"","sources":["../src/components.tsx"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAEpC,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,GAAG,CAAC,OAAO,CAQ9D;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,GAAG,CAAC,OAAO,CAEpD;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,GAAG,CAAC,OAAO,CAchE"}
+{"version":3,"file":"components.d.ts","sourceRoot":"","sources":["../src/components.tsx"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAEpC,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,GAAG,CAAC,OAAO,CAQ9D;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,GAAG,CAAC,OAAO,CAEpD;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,GAAG,CAAC,OAAO,CAehE"}

package/dist/components.jsx

@@ -1,3 +1,7 @@
+/**
+ * 标签-值组件
+ * 显示格式：标签: 值
+ */
 export function LabelValue(props) {
     return (<box flexDirection="row" gap={1}>
       <text fg={props.labelColor}>{props.label}</text>
@@ -5,11 +9,20 @@ export function LabelValue(props) {
       <text>{props.value}</text>
     </box>);
 }
+/**
+ * 标题组件
+ * 显示带颜色的文本
+ */
 export function Title(props) {
     return <text fg={props.color}>{props.text}</text>;
 }
+/**
+ * 进度条组件
+ * 显示格式：[■■■■■■■■□□] 或类似
+ */
 export function ProgressBar(props) {
     const width = props.width ?? 20;
+    // 计算填充和空白的字符数
     const filled = Math.round((props.value / 100) * width);
     const empty = filled === 0 ? width - 1 : width - filled;
     const barColor = props.color ?? '#6bcf7f';

package/dist/context-usage.d.ts

@@ -5,5 +5,14 @@ export interface ContextUsageViewProps {
     api: TuiPluginApi;
     sessionId: string;
 }
+/**
+ * Context Usage 视图组件
+ * 显示当前会话最新一条 assistant 消息的 context tokens 使用情况
+ *
+ * Context Tokens 计算方式：
+ * contextTokens = input + output + reasoning + cache.read + cache.write
+ *
+ * 注意：AI 回复期间 tokens 可能为 0，此时跳过该消息
+ */
 export declare function ContextUsageView(props: ContextUsageViewProps): JSX.Element;
 //# sourceMappingURL=context-usage.d.ts.map

package/dist/context-usage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-usage.d.ts","sourceRoot":"","sources":["../src/context-usage.tsx"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAKpC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,YAAY,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,GAAG,CAAC,OAAO,CAiE1E"}
+{"version":3,"file":"context-usage.d.ts","sourceRoot":"","sources":["../src/context-usage.tsx"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAKpC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,YAAY,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,GAAG,CAAC,OAAO,CAyE1E"}

package/dist/context-usage.jsx

@@ -2,6 +2,15 @@ import { createSignal, createEffect } from "solid-js";
 import { Show } from "solid-js";
 import { ProgressBar } from "./components.jsx";
 import { formatNumber, formatPercent } from "./formatters.js";
+/**
+ * Context Usage 视图组件
+ * 显示当前会话最新一条 assistant 消息的 context tokens 使用情况
+ *
+ * Context Tokens 计算方式：
+ * contextTokens = input + output + reasoning + cache.read + cache.write
+ *
+ * 注意：AI 回复期间 tokens 可能为 0，此时跳过该消息
+ */
 export function ContextUsageView(props) {
     const [contextData, setContextData] = createSignal(null);
     createEffect(() => {
@@ -14,22 +23,30 @@ export function ContextUsageView(props) {
         let latestTokens = 0;
         let latestTime = -Infinity;
         let limit = 0;
+        // 遍历所有消息，找到最新一条有有效 tokens 的 assistant 消息
         for (const msg of messages) {
             if (msg.role !== "assistant" || !msg.tokens)
                 continue;
+            // 计算总 tokens（input + output + reasoning + cache）
             const tokens = msg.tokens.input +
                 msg.tokens.output +
                 msg.tokens.reasoning +
                 msg.tokens.cache.read +
                 msg.tokens.cache.write;
+            // AI 回复期间 tokens 可能为 0，跳过
             if (tokens <= 0)
                 continue;
+            // 使用消息完成时间或创建时间来判断新旧
             const time = msg.time.completed ?? msg.time.created;
             if (time > latestTime) {
                 latestTime = time;
                 latestTokens = tokens;
+                // 从 provider 列表中查找对应模型的 context limit
                 const provider = props.api.state.provider.find((p) => p.id === msg.providerID);
-                const model = provider?.models[msg.modelID];
+                if (!provider) {
+                    continue;
+                }
+                const model = provider.models[msg.modelID];
                 limit = model?.limit?.context ?? 0;
             }
         }

package/dist/formatters.d.ts

@@ -1,5 +1,30 @@
+/**
+ * 格式化工具函数
+ */
+/**
+ * 格式化数字为大写缩写
+ * 例如：1000 -> "1.0K", 1000000 -> "1.0M"
+ */
 export declare function formatNumber(n: number): string;
+/**
+ * 格式化金额为美元字符串
+ * 自动去掉尾部的零
+ * 例如：0.000001 -> "$0.000001", 0.001000 -> "$0.001"
+ */
 export declare function formatCost(cost: number): string;
+/**
+ * 格式化时间间隔为 mm:ss 或 hh:mm:ss 格式
+ * 例如：45 -> "45s", 90 -> "1:30", 3661 -> "1:01:01"
+ */
 export declare function formatDuration(totalSeconds: number): string;
+/**
+ * 格式化百分比
+ * 例如：45.6 -> "46%"
+ */
 export declare function formatPercent(value: number): string;
+/**
+ * 格式化时间间隔为紧凑格式（用于额度显示）
+ * 例如：45 -> "45s", 90 -> "2m", 3600 -> "1h", 86400 -> "1d"
+ */
+export declare function formatDurationCompact(seconds: number): string;
 //# sourceMappingURL=formatters.d.ts.map

package/dist/formatters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formatters.d.ts","sourceRoot":"","sources":["../src/formatters.ts"],"names":[],"mappings":"AAAA,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAI9C;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI/C;AAED,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAa3D;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD"}
+{"version":3,"file":"formatters.d.ts","sourceRoot":"","sources":["../src/formatters.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAI9C;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI/C;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAa3D;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAK7D"}

package/dist/formatters.js

@@ -1,3 +1,10 @@
+/**
+ * 格式化工具函数
+ */
+/**
+ * 格式化数字为大写缩写
+ * 例如：1000 -> "1.0K", 1000000 -> "1.0M"
+ */
 export function formatNumber(n) {
     if (n >= 1000000)
         return (n / 1000000).toFixed(1) + "M";
@@ -5,12 +12,21 @@ export function formatNumber(n) {
         return (n / 1000).toFixed(1) + "K";
     return n.toString();
 }
+/**
+ * 格式化金额为美元字符串
+ * 自动去掉尾部的零
+ * 例如：0.000001 -> "$0.000001", 0.001000 -> "$0.001"
+ */
 export function formatCost(cost) {
     if (cost === 0)
         return "$0";
     const formatted = cost.toFixed(6).replace(/\.?0+$/, "");
     return "$" + formatted;
 }
+/**
+ * 格式化时间间隔为 mm:ss 或 hh:mm:ss 格式
+ * 例如：45 -> "45s", 90 -> "1:30", 3661 -> "1:01:01"
+ */
 export function formatDuration(totalSeconds) {
     if (totalSeconds < 60) {
         return `${totalSeconds}s`;
@@ -25,6 +41,23 @@ export function formatDuration(totalSeconds) {
     const s = totalSeconds % 60;
     return `${h}:${m.toString().padStart(2, "0")}:${s.toString().padStart(2, "0")}`;
 }
+/**
+ * 格式化百分比
+ * 例如：45.6 -> "46%"
+ */
 export function formatPercent(value) {
     return `${Math.round(value)}%`;
 }
+/**
+ * 格式化时间间隔为紧凑格式（用于额度显示）
+ * 例如：45 -> "45s", 90 -> "2m", 3600 -> "1h", 86400 -> "1d"
+ */
+export function formatDurationCompact(seconds) {
+    if (seconds < 60)
+        return `${seconds}s`;
+    if (seconds < 3600)
+        return `${Math.round(seconds / 60)}m`;
+    if (seconds < 86400)
+        return `${Math.round(seconds / 3600)}h`;
+    return `${Math.round(seconds / 86400)}d`;
+}

package/dist/quota/config.d.ts

@@ -1,4 +1,14 @@
 import type { ProviderRegistry, ProviderConfig } from "./types.js";
+/**
+ * 读取并解析 usage.provider.json 配置文件
+ * @returns Provider 注册表，如果文件不存在或解析失败则返回空对象
+ */
 export declare function readProviderConfig(): ProviderRegistry;
+/**
+ * 根据 provider 名称获取对应配置
+ * @param registry Provider 注册表
+ * @param providerName Provider 名称
+ * @returns 对应的配置，如果不存在则返回 undefined
+ */
 export declare function getProviderConfig(registry: ProviderRegistry, providerName: string): ProviderConfig | undefined;
 //# sourceMappingURL=config.d.ts.map

package/dist/quota/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/quota/config.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AASnE,wBAAgB,kBAAkB,IAAI,gBAAgB,CAWrD;AAED,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,gBAAgB,EAC1B,YAAY,EAAE,MAAM,GACnB,cAAc,GAAG,SAAS,CAI5B"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/quota/config.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAWnE;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,gBAAgB,CAUrD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,gBAAgB,EAC1B,YAAY,EAAE,MAAM,GACnB,cAAc,GAAG,SAAS,CAE5B"}

package/dist/quota/config.js

@@ -1,13 +1,17 @@
 import { readFileSync } from "fs";
 import { resolve, join } from "path";
+/** OpenCode 配置目录路径 */
 const HOME_DIR = process.env.HOME || process.env.USERPROFILE || "";
 const OPENCODE_CONFIG_DIR = join(HOME_DIR, ".config", "opencode");
+/**
+ * 读取并解析 usage.provider.json 配置文件
+ * @returns Provider 注册表，如果文件不存在或解析失败则返回空对象
+ */
 export function readProviderConfig() {
     try {
         const configPath = resolve(OPENCODE_CONFIG_DIR, "usage.provider.json");
         const content = readFileSync(configPath, "utf-8");
         const data = JSON.parse(content);
-        console.log("[QuotaService] Config content:", JSON.stringify(data));
         return data.providers || {};
     }
     catch (error) {
@@ -15,8 +19,12 @@ export function readProviderConfig() {
         return {};
     }
 }
+/**
+ * 根据 provider 名称获取对应配置
+ * @param registry Provider 注册表
+ * @param providerName Provider 名称
+ * @returns 对应的配置，如果不存在则返回 undefined
+ */
 export function getProviderConfig(registry, providerName) {
-    console.log("[QuotaService] Looking up provider:", providerName);
-    console.log("[QuotaService] Registry keys:", Object.keys(registry));
     return registry[providerName];
 }

package/dist/quota/index.d.ts

@@ -0,0 +1,5 @@
+export { QuotaService } from "./service.js";
+export { QuotaProvider, resolveEnvVar } from "./provider.js";
+export type { QuotaUsage, QuotaData, QuotaResult, ProviderConfig, ProviderRegistry } from "./types.js";
+export { readProviderConfig, getProviderConfig } from "./config.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/quota/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/quota/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC7D,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACvG,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC"}

package/dist/quota/index.js

@@ -0,0 +1,4 @@
+// Quota 模块统一导出
+export { QuotaService } from "./service.js";
+export { resolveEnvVar } from "./provider.js";
+export { readProviderConfig, getProviderConfig } from "./config.js";

package/dist/quota/provider.d.ts

@@ -1,9 +1,28 @@
 import type { QuotaData, ProviderConfig } from "./types.js";
+/**
+ * 额度 Provider 接口
+ * 所有额度数据提供者需实现此接口
+ */
 export interface QuotaProvider {
+    /** Provider 唯一标识，需与 usage.provider.json 中的 key 匹配 */
     readonly name: string;
+    /**
+     * 初始化 Provider
+     * @param config 从 usage.provider.json 读取的 provider 配置
+     * @param credentials 凭证信息（暂未使用）
+     */
     init(config: ProviderConfig, credentials: Record<string, unknown>): void;
+    /**
+     * 获取额度数据
+     * @returns 额度数据，获取失败返回 null
+     */
     fetchQuota(): Promise<QuotaData | null>;
-    resolveEnvVar(value: string | undefined): string | undefined;
 }
+/**
+ * 解析环境变量引用
+ * 支持 ${ENV_VAR} 格式，从 process.env 读取实际值
+ * @param value 可能是 ${ENV_VAR} 格式的字符串
+ * @returns 解析后的值，如果未找到环境变量则返回 undefined
+ */
 export declare const resolveEnvVar: (value: string | undefined) => string | undefined;
 //# sourceMappingURL=provider.d.ts.map

package/dist/quota/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/quota/provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,IAAI,CAAC,MAAM,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAEzE,UAAU,IAAI,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAExC,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;CAC9D;AAED,eAAO,MAAM,aAAa,GAAI,OAAO,MAAM,GAAG,SAAS,KAAG,MAAM,GAAG,SAOlE,CAAC"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/quota/provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5D;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;OAIG;IACH,IAAI,CAAC,MAAM,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAEzE;;;OAGG;IACH,UAAU,IAAI,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;CACzC;AAED;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,OAAO,MAAM,GAAG,SAAS,KAAG,MAAM,GAAG,SAOlE,CAAC"}

package/dist/quota/provider.js

@@ -1,3 +1,9 @@
+/**
+ * 解析环境变量引用
+ * 支持 ${ENV_VAR} 格式，从 process.env 读取实际值
+ * @param value 可能是 ${ENV_VAR} 格式的字符串
+ * @returns 解析后的值，如果未找到环境变量则返回 undefined
+ */
 export const resolveEnvVar = (value) => {
     if (!value)
         return undefined;

package/dist/quota/providers/minimax.d.ts

@@ -1,5 +1,9 @@
 import type { QuotaData, ProviderConfig } from "../types.js";
 import { QuotaProvider } from "../provider.js";
+/**
+ * MiniMax 额度 Provider 基类
+ * 用于处理 MiniMax 的 coding plan 额度数据
+ */
 declare class MiniMaxQuotaProvider implements QuotaProvider {
     readonly name: string;
     private apiKey;
@@ -8,13 +12,14 @@ declare class MiniMaxQuotaProvider implements QuotaProvider {
     constructor(name: string, baseUrl: string);
     init(config: ProviderConfig, _credentials: Record<string, unknown>): void;
     fetchQuota(): Promise<QuotaData | null>;
-    resolveEnvVar(value: string | undefined): string | undefined;
+    /** 将 API 响应映射为 QuotaData 格式 */
     private mapResponseToQuotaData;
-    private formatDuration;
 }
+/** MiniMax CN (国内版) Provider */
 export declare class MiniMaxCNQuotaProvider extends MiniMaxQuotaProvider {
     constructor();
 }
+/** MiniMax IO (海外版) Provider */
 export declare class MiniMaxIOQuotaProvider extends MiniMaxQuotaProvider {
     constructor();
 }

package/dist/quota/providers/minimax.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"minimax.d.ts","sourceRoot":"","sources":["../../../src/quota/providers/minimax.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAiB,MAAM,gBAAgB,CAAC;AAwB9D,cAAM,oBAAqB,YAAW,aAAa;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAS;gBAEX,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;IAMzC,IAAI,CAAC,MAAM,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAKnE,UAAU,IAAI,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IA8C7C,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS;IAI5D,OAAO,CAAC,sBAAsB;IA8C9B,OAAO,CAAC,cAAc;CAMvB;AAED,qBAAa,sBAAuB,SAAQ,oBAAoB;;CAI/D;AAED,qBAAa,sBAAuB,SAAQ,oBAAoB;;CAI/D"}
+{"version":3,"file":"minimax.d.ts","sourceRoot":"","sources":["../../../src/quota/providers/minimax.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAiB,MAAM,gBAAgB,CAAC;AA2B9D;;;GAGG;AACH,cAAM,oBAAqB,YAAW,aAAa;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAS;gBAEX,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;IAMzC,IAAI,CAAC,MAAM,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAKnE,UAAU,IAAI,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAiD7C,+BAA+B;IAC/B,OAAO,CAAC,sBAAsB;CAgD/B;AAED,gCAAgC;AAChC,qBAAa,sBAAuB,SAAQ,oBAAoB;;CAI/D;AAED,gCAAgC;AAChC,qBAAa,sBAAuB,SAAQ,oBAAoB;;CAI/D"}

package/dist/quota/providers/minimax.js

@@ -1,4 +1,9 @@
 import { resolveEnvVar } from "../provider.js";
+import { formatDurationCompact } from "../../formatters.js";
+/**
+ * MiniMax 额度 Provider 基类
+ * 用于处理 MiniMax 的 coding plan 额度数据
+ */
 class MiniMaxQuotaProvider {
     name;
     apiKey;
@@ -11,7 +16,7 @@ class MiniMaxQuotaProvider {
     }
     init(config, _credentials) {
         const apiKeyRaw = config.apiKey;
-        this.apiKey = resolveEnvVar(apiKeyRaw) || resolveEnvVar(config.apiKeyEnvVar);
+        this.apiKey = resolveEnvVar(apiKeyRaw);
     }
     async fetchQuota() {
         if (!this.apiKey) {
@@ -19,6 +24,7 @@ class MiniMaxQuotaProvider {
             return null;
         }
         try {
+            // 调用 MiniMax 额度查询 API
             const response = await fetch(`${this.baseUrl}/v1/api/openplatform/coding_plan/remains`, {
                 method: "GET",
                 headers: {
@@ -31,10 +37,12 @@ class MiniMaxQuotaProvider {
                 return null;
             }
             const data = (await response.json());
+            // 检查业务状态码
             if (data.base_resp?.status_code !== 0) {
                 console.error(`${this.logTag} API error: ${data.base_resp?.status_msg}`);
                 return null;
             }
+            // 只保留 MiniMax-M 开头的模型（coding plan 模型）
             const codingPlanModels = data.model_remains.filter((m) => m.model_name.startsWith("MiniMax-M"));
             if (codingPlanModels.length === 0) {
                 console.warn(`${this.logTag} No coding plan models found`);
@@ -47,9 +55,7 @@ class MiniMaxQuotaProvider {
             return null;
         }
     }
-    resolveEnvVar(value) {
-        return resolveEnvVar(value);
-    }
+    /** 将 API 响应映射为 QuotaData 格式 */
     mapResponseToQuotaData(models) {
         let totalRollingAvailable = 0;
         let totalRollingLimit = 0;
@@ -57,6 +63,7 @@ class MiniMaxQuotaProvider {
         let totalWeeklyAvailable = 0;
         let totalWeeklyLimit = 0;
         let weeklyResetMs = 0;
+        // 累加所有模型的额度
         for (const m of models) {
             totalRollingAvailable += m.current_interval_usage_count;
             totalRollingLimit += m.current_interval_total_count;
@@ -65,6 +72,7 @@ class MiniMaxQuotaProvider {
             rollingResetMs = Math.max(rollingResetMs, m.end_time);
             weeklyResetMs = Math.max(weeklyResetMs, m.weekly_end_time);
         }
+        // 计算已用量和百分比
         const rollingUsed = Math.max(0, totalRollingLimit - totalRollingAvailable);
         const weeklyUsed = Math.max(0, totalWeeklyLimit - totalWeeklyAvailable);
         const rollingPercent = totalRollingLimit > 0
@@ -73,36 +81,30 @@ class MiniMaxQuotaProvider {
         const weeklyPercent = totalWeeklyLimit > 0
             ? Math.round((weeklyUsed / totalWeeklyLimit) * 100)
             : 0;
+        // 计算距离重置的时间
         const now = Date.now();
         const rollingResetSec = Math.max(0, Math.floor((rollingResetMs - now) / 1000));
         const weeklyResetSec = Math.max(0, Math.floor((weeklyResetMs - now) / 1000));
         return {
             rolling: {
                 usage: rollingPercent,
-                reset: this.formatDuration(rollingResetSec),
+                reset: formatDurationCompact(rollingResetSec),
             },
             weekly: {
                 usage: weeklyPercent,
-                reset: this.formatDuration(weeklyResetSec),
+                reset: formatDurationCompact(weeklyResetSec),
             },
             monthly: undefined,
         };
     }
-    formatDuration(seconds) {
-        if (seconds < 60)
-            return `${seconds}s`;
-        if (seconds < 3600)
-            return `${Math.round(seconds / 60)}m`;
-        if (seconds < 86400)
-            return `${Math.round(seconds / 3600)}h`;
-        return `${Math.round(seconds / 86400)}d`;
-    }
 }
+/** MiniMax CN (国内版) Provider */
 export class MiniMaxCNQuotaProvider extends MiniMaxQuotaProvider {
     constructor() {
         super("minimax-cn-coding-plan", "https://www.minimaxi.com");
     }
 }
+/** MiniMax IO (海外版) Provider */
 export class MiniMaxIOQuotaProvider extends MiniMaxQuotaProvider {
     constructor() {
         super("minimax-coding-plan", "https://api.minimax.io");

package/dist/quota/providers/opencode-go.d.ts

@@ -1,5 +1,9 @@
 import type { QuotaData, ProviderConfig } from "../types.js";
 import { QuotaProvider } from "../provider.js";
+/**
+ * OpenCode Go 额度 Provider
+ * 通过 opencode.ai 网页 API 获取用户额度信息
+ */
 export declare class OpenCodeGoQuotaProvider implements QuotaProvider {
     readonly name = "opencode-go";
     private cookie;
@@ -8,7 +12,5 @@ export declare class OpenCodeGoQuotaProvider implements QuotaProvider {
     private baseUrl;
     init(config: ProviderConfig, _credentials: Record<string, unknown>): void;
     fetchQuota(): Promise<QuotaData | null>;
-    resolveEnvVar(value: string | undefined): string | undefined;
-    private formatDuration;
 }
 //# sourceMappingURL=opencode-go.d.ts.map

package/dist/quota/providers/opencode-go.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"opencode-go.d.ts","sourceRoot":"","sources":["../../../src/quota/providers/opencode-go.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAiB,MAAM,gBAAgB,CAAC;AAiB9D,qBAAa,uBAAwB,YAAW,aAAa;IAC3D,QAAQ,CAAC,IAAI,iBAAiB;IAE9B,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,SAAS,CAAsE;IACvF,OAAO,CAAC,OAAO,CAAyB;IAExC,IAAI,CAAC,MAAM,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAKnE,UAAU,IAAI,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAsE7C,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS;IAI5D,OAAO,CAAC,cAAc;CAMvB"}
+{"version":3,"file":"opencode-go.d.ts","sourceRoot":"","sources":["../../../src/quota/providers/opencode-go.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAiB,MAAM,gBAAgB,CAAC;AAG9D;;;GAGG;AACH,qBAAa,uBAAwB,YAAW,aAAa;IAC3D,QAAQ,CAAC,IAAI,iBAAiB;IAE9B,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,WAAW,CAAqB;IAExC,OAAO,CAAC,SAAS,CAAsE;IACvF,OAAO,CAAC,OAAO,CAAyB;IAExC,IAAI,CAAC,MAAM,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAMnE,UAAU,IAAI,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;CAkF9C"}

package/dist/quota/providers/opencode-go.js

@@ -1,11 +1,18 @@
 import { resolveEnvVar } from "../provider.js";
+import { formatDurationCompact } from "../../formatters.js";
+/**
+ * OpenCode Go 额度 Provider
+ * 通过 opencode.ai 网页 API 获取用户额度信息
+ */
 export class OpenCodeGoQuotaProvider {
     name = "opencode-go";
     cookie;
     workspaceId;
+    // 服务端点 ID，用于调用 opencode.ai 的内部 RPC 服务
     serviceId = "c7389bd0e731f80f49593e5ee53835475f4e28594dd6bd83eb229bab753498cd";
     baseUrl = "https://opencode.ai";
     init(config, _credentials) {
+        // 从配置中读取 cookie 和 workspaceId，支持 ${ENV_VAR} 格式
         this.cookie = resolveEnvVar(config.cookie);
         this.workspaceId = resolveEnvVar(config.workspaceId);
     }
@@ -14,6 +21,7 @@ export class OpenCodeGoQuotaProvider {
             console.warn("[OpenCodeGoQuotaProvider] Missing cookie or workspaceId");
             return null;
         }
+        // 构建 RPC 调用参数
         const args = JSON.stringify({
             t: { t: 9, i: 0, l: 1, a: [{ t: 1, s: this.workspaceId }], o: 0 },
             f: 31,
@@ -41,11 +49,22 @@ export class OpenCodeGoQuotaProvider {
                 return null;
             }
             const text = await response.text();
+            // 从响应文本中用正则提取 rolling/weekly/monthly 额度数据
+            // 响应格式如: rollingUsage:$R[1]={status:"active",resetInSec:3600,usagePercent:45}
             const rollingMatch = text.match(/rollingUsage:\$R\[1\]=\{status:"([^"]+)",resetInSec:(\d+),usagePercent:(\d+)\}/);
             const weeklyMatch = text.match(/weeklyUsage:\$R\[2\]=\{status:"([^"]+)",resetInSec:(\d+),usagePercent:(\d+)\}/);
             const monthlyMatch = text.match(/monthlyUsage:\$R\[3\]=\{status:"([^"]+)",resetInSec:(\d+),usagePercent:(\d+)\}/);
-            if (!rollingMatch || !weeklyMatch || !monthlyMatch) {
-                console.error("[OpenCodeGoQuotaProvider] Failed to parse response:", text.substring(0, 200));
+            // 分别检查每个字段的解析结果，提供更详细的错误信息
+            if (!rollingMatch) {
+                console.error("[OpenCodeGoQuotaProvider] Failed to parse rollingUsage");
+                return null;
+            }
+            if (!weeklyMatch) {
+                console.error("[OpenCodeGoQuotaProvider] Failed to parse weeklyUsage");
+                return null;
+            }
+            if (!monthlyMatch) {
+                console.error("[OpenCodeGoQuotaProvider] Failed to parse monthlyUsage");
                 return null;
             }
             const rollingUsage = { status: rollingMatch[1], resetInSec: parseInt(rollingMatch[2], 10), usagePercent: parseInt(rollingMatch[3], 10) };
@@ -54,14 +73,15 @@ export class OpenCodeGoQuotaProvider {
             return {
                 rolling: {
                     usage: rollingUsage.usagePercent,
-                    reset: this.formatDuration(rollingUsage.resetInSec),
+                    reset: formatDurationCompact(rollingUsage.resetInSec),
                 },
                 weekly: {
                     usage: weeklyUsage.usagePercent,
-                    reset: this.formatDuration(weeklyUsage.resetInSec),
+                    reset: formatDurationCompact(weeklyUsage.resetInSec),
                 },
+                // 如果 monthly 状态是 "unlimited" 则不显示
                 monthly: monthlyUsage.status !== "unlimited"
-                    ? { usage: monthlyUsage.usagePercent, reset: this.formatDuration(monthlyUsage.resetInSec) }
+                    ? { usage: monthlyUsage.usagePercent, reset: formatDurationCompact(monthlyUsage.resetInSec) }
                     : undefined,
             };
         }
@@ -70,16 +90,4 @@ export class OpenCodeGoQuotaProvider {
             return null;
         }
     }
-    resolveEnvVar(value) {
-        return resolveEnvVar(value);
-    }
-    formatDuration(seconds) {
-        if (seconds < 60)
-            return `${seconds}s`;
-        if (seconds < 3600)
-            return `${Math.round(seconds / 60)}m`;
-        if (seconds < 86400)
-            return `${Math.round(seconds / 3600)}h`;
-        return `${Math.round(seconds / 86400)}d`;
-    }
 }

package/dist/quota/service.d.ts

@@ -1,18 +1,47 @@
 import type { QuotaResult } from "./types.js";
 import type { QuotaProvider } from "./provider.js";
+/**
+ * 额度服务 - 管理所有 Provider 的注册和调用
+ */
 export declare class QuotaService {
+    /** 已注册的 Provider 映射表 */
     private providers;
+    /** 从配置文件加载的 Provider 注册表 */
     private providerRegistry;
+    /** 当前活跃的 Provider 名称 */
     private activeProviderName;
+    /** 当前活跃的 Provider 实例 */
     private activeProvider;
+    /** 刷新次数计数器 */
     private refreshCount;
     constructor();
+    /**
+     * 注册一个 Provider
+     * @param provider Provider 实例
+     */
     registerProvider(provider: QuotaProvider): void;
+    /**
+     * 设置当前活跃的 Provider
+     * 会调用 Provider 的 init 方法进行初始化
+     * @param providerName Provider 名称
+     * @returns 是否设置成功（Provider 是否已注册）
+     */
     setActiveProvider(providerName: string): boolean;
+    /** 获取当前活跃的 Provider 名称 */
     getActiveProviderName(): string | null;
+    /**
+     * 检查某个 Provider 是否已注册
+     * @param providerName Provider 名称
+     */
     isProviderSupported(providerName: string): boolean;
+    /** 获取所有已注册的 Provider 名称列表 */
     getRegisteredProviderNames(): string[];
+    /** 获取所有已配置的 Provider 名称列表（从配置文件） */
     getConfiguredProviderNames(): string[];
+    /**
+     * 获取当前 Provider 的额度数据
+     * @returns 额度结果，包含 provider 名称、额度数据和刷新计数
+     */
     fetchQuota(): Promise<QuotaResult | null>;
 }
 //# sourceMappingURL=service.d.ts.map

package/dist/quota/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/quota/service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAKnD,qBAAa,YAAY;IACvB,OAAO,CAAC,SAAS,CAAyC;IAC1D,OAAO,CAAC,gBAAgB,CAAwB;IAChD,OAAO,CAAC,kBAAkB,CAAuB;IACjD,OAAO,CAAC,cAAc,CAA8B;IACpD,OAAO,CAAC,YAAY,CAAK;;IAQzB,gBAAgB,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI;IAI/C,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO;IAmBhD,qBAAqB,IAAI,MAAM,GAAG,IAAI;IAItC,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO;IAIlD,0BAA0B,IAAI,MAAM,EAAE;IAItC,0BAA0B,IAAI,MAAM,EAAE;IAIhC,UAAU,IAAI,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;CAahD"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/quota/service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAKnD;;GAEG;AACH,qBAAa,YAAY;IACvB,wBAAwB;IACxB,OAAO,CAAC,SAAS,CAAyC;IAC1D,4BAA4B;IAC5B,OAAO,CAAC,gBAAgB,CAAwB;IAChD,wBAAwB;IACxB,OAAO,CAAC,kBAAkB,CAAuB;IACjD,wBAAwB;IACxB,OAAO,CAAC,cAAc,CAA8B;IACpD,cAAc;IACd,OAAO,CAAC,YAAY,CAAK;;IASzB;;;OAGG;IACH,gBAAgB,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI;IAI/C;;;;;OAKG;IACH,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO;IAoBhD,0BAA0B;IAC1B,qBAAqB,IAAI,MAAM,GAAG,IAAI;IAItC;;;OAGG;IACH,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO;IAIlD,6BAA6B;IAC7B,0BAA0B,IAAI,MAAM,EAAE;IAItC,oCAAoC;IACpC,0BAA0B,IAAI,MAAM,EAAE;IAItC;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;CAgBhD"}

package/dist/quota/service.js

@@ -1,20 +1,39 @@
 import { readProviderConfig, getProviderConfig } from "./config.js";
 import { MiniMaxCNQuotaProvider, MiniMaxIOQuotaProvider } from "./providers/minimax.js";
 import { OpenCodeGoQuotaProvider } from "./providers/opencode-go.js";
+/**
+ * 额度服务 - 管理所有 Provider 的注册和调用
+ */
 export class QuotaService {
+    /** 已注册的 Provider 映射表 */
     providers = new Map();
+    /** 从配置文件加载的 Provider 注册表 */
     providerRegistry = readProviderConfig();
+    /** 当前活跃的 Provider 名称 */
     activeProviderName = null;
+    /** 当前活跃的 Provider 实例 */
     activeProvider = null;
+    /** 刷新次数计数器 */
     refreshCount = 0;
     constructor() {
+        // 注册支持的 Provider
         this.registerProvider(new MiniMaxCNQuotaProvider());
         this.registerProvider(new MiniMaxIOQuotaProvider());
         this.registerProvider(new OpenCodeGoQuotaProvider());
     }
+    /**
+     * 注册一个 Provider
+     * @param provider Provider 实例
+     */
     registerProvider(provider) {
         this.providers.set(provider.name, provider);
     }
+    /**
+     * 设置当前活跃的 Provider
+     * 会调用 Provider 的 init 方法进行初始化
+     * @param providerName Provider 名称
+     * @returns 是否设置成功（Provider 是否已注册）
+     */
     setActiveProvider(providerName) {
         const provider = this.providers.get(providerName);
         if (!provider) {
@@ -25,32 +44,47 @@ export class QuotaService {
         if (!config) {
             console.warn(`[QuotaService] No config for provider: ${providerName}`);
         }
+        // 初始化 Provider，传入配置
         provider.init(config || {}, {});
         this.activeProviderName = providerName;
         this.activeProvider = provider;
         return true;
     }
+    /** 获取当前活跃的 Provider 名称 */
     getActiveProviderName() {
         return this.activeProviderName;
     }
+    /**
+     * 检查某个 Provider 是否已注册
+     * @param providerName Provider 名称
+     */
     isProviderSupported(providerName) {
         return this.providers.has(providerName);
     }
+    /** 获取所有已注册的 Provider 名称列表 */
     getRegisteredProviderNames() {
         return Array.from(this.providers.keys());
     }
+    /** 获取所有已配置的 Provider 名称列表（从配置文件） */
     getConfiguredProviderNames() {
         return Object.keys(this.providerRegistry);
     }
+    /**
+     * 获取当前 Provider 的额度数据
+     * @returns 额度结果，包含 provider 名称、额度数据和刷新计数
+     */
     async fetchQuota() {
         if (!this.activeProvider) {
             return null;
         }
         this.refreshCount++;
         const quota = await this.activeProvider.fetchQuota();
+        if (!quota) {
+            return null;
+        }
         return {
             provider: this.activeProviderName,
-            quota: quota,
+            quota,
             refreshCount: this.refreshCount,
         };
     }

package/dist/quota/types.d.ts

@@ -1,20 +1,46 @@
+/**
+ * 单个时间维度的额度使用情况
+ */
 export interface QuotaUsage {
+    /** 已使用百分比 (0-100) */
     usage: number;
+    /** 距离重置的倒计时字符串，如 "2h", "30m", "5d" */
     reset: string;
 }
+/**
+ * 额度数据结构
+ * 包含 Rolling(滚动周期)、Weekly(每周)、Monthly(每月) 三种维度的使用量
+ */
 export interface QuotaData {
+    /** 滚动周期额度（如当天 0 点开始的计数） */
     rolling: QuotaUsage | undefined;
+    /** 本周额度 */
     weekly: QuotaUsage | undefined;
+    /** 本月额度，部分 provider 可能无此维度 */
     monthly: QuotaUsage | undefined;
 }
+/**
+ * 完整的额度查询结果
+ */
 export interface QuotaResult {
+    /** Provider 名称 */
     provider: string;
+    /** 额度数据 */
     quota: QuotaData;
+    /** 当前会话的刷新次数计数 */
     refreshCount: number;
 }
+/**
+ * 单个 Provider 的配置格式
+ * 具体字段由各 Provider 自己定义，如 apiKey、cookie 等
+ */
 export interface ProviderConfig {
     [key: string]: unknown;
 }
+/**
+ * Provider 注册表
+ * key 为 provider 名称，value 为对应的配置
+ */
 export interface ProviderRegistry {
     [providerName: string]: ProviderConfig;
 }

package/dist/quota/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/quota/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,UAAU,GAAG,SAAS,CAAC;IAChC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC;IAC/B,OAAO,EAAE,UAAU,GAAG,SAAS,CAAC;CACjC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,SAAS,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,CAAC,YAAY,EAAE,MAAM,GAAG,cAAc,CAAC;CACxC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/quota/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,qBAAqB;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,2BAA2B;IAC3B,OAAO,EAAE,UAAU,GAAG,SAAS,CAAC;IAChC,WAAW;IACX,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC;IAC/B,8BAA8B;IAC9B,OAAO,EAAE,UAAU,GAAG,SAAS,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,kBAAkB;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW;IACX,KAAK,EAAE,SAAS,CAAC;IACjB,kBAAkB;IAClB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,CAAC,YAAY,EAAE,MAAM,GAAG,cAAc,CAAC;CACxC"}

package/dist/session-info.d.ts

@@ -1,6 +1,10 @@
 /** @jsxImportSource @opentui/solid */
 import type { TuiPluginApi } from "@opencode-ai/plugin/tui";
 import type { JSX } from "solid-js";
+/**
+ * Session Info 视图组件
+ * 显示当前会话的基本信息：Session ID、Branch、Provider、Model、消息数等
+ */
 export declare function SessionInfoView(props: {
     api: TuiPluginApi;
     sessionId: string;

package/dist/session-info.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-info.d.ts","sourceRoot":"","sources":["../src/session-info.tsx"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAcpC,wBAAgB,eAAe,CAAC,KAAK,EAAE;IACrC,GAAG,EAAE,YAAY,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,GAAG,CAAC,OAAO,CA2Ed"}
+{"version":3,"file":"session-info.d.ts","sourceRoot":"","sources":["../src/session-info.tsx"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAepC;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IACrC,GAAG,EAAE,YAAY,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,GAAG,CAAC,OAAO,CAgFd"}

package/dist/session-info.jsx

@@ -1,5 +1,9 @@
 import { createSignal, createEffect, Show } from "solid-js";
 import { LabelValue } from "./components.jsx";
+/**
+ * Session Info 视图组件
+ * 显示当前会话的基本信息：Session ID、Branch、Provider、Model、消息数等
+ */
 export function SessionInfoView(props) {
     const [data, setData] = createSignal(null);
     createEffect(() => {
@@ -8,9 +12,14 @@ export function SessionInfoView(props) {
         const todos = props.api.state.session.todo(sessionId);
         const diff = props.api.state.session.diff(sessionId);
         const vcs = props.api.state.vcs;
-        const lastAssistantMsg = [...messages]
-            .reverse()
-            .find((m) => m.role === "assistant");
+        // 从后向前查找最后一个 assistant 消息以获取 provider 和 model 信息
+        let lastAssistantMsg = null;
+        for (let i = messages.length - 1; i >= 0; i--) {
+            if (messages[i].role === "assistant") {
+                lastAssistantMsg = messages[i];
+                break;
+            }
+        }
         const lastModelInfo = lastAssistantMsg && "modelID" in lastAssistantMsg
             ? {
                 providerID: lastAssistantMsg.providerID,

package/dist/tokens-usage.d.ts

@@ -1,6 +1,7 @@
 /** @jsxImportSource @opentui/solid */
 import type { JSX } from "solid-js";
 import type { TuiPluginApi } from "@opencode-ai/plugin/tui";
+/** 单个模型的 token 统计 */
 export interface TokenStats {
     providerID: string;
     modelID: string;
@@ -16,5 +17,10 @@ export interface TokensUsageViewProps {
     api: TuiPluginApi;
     sessionId: string;
 }
+/**
+ * Tokens Usage 视图组件
+ * 统计当前会话中所有 assistant 消息的 token 消耗
+ * 按模型分组显示累计数据
+ */
 export declare function TokensUsageView(props: TokensUsageViewProps): JSX.Element;
 //# sourceMappingURL=tokens-usage.d.ts.map

package/dist/tokens-usage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tokens-usage.d.ts","sourceRoot":"","sources":["../src/tokens-usage.tsx"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAIpC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAG5D,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,YAAY,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAYD,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,GAAG,CAAC,OAAO,CAsIxE"}
+{"version":3,"file":"tokens-usage.d.ts","sourceRoot":"","sources":["../src/tokens-usage.tsx"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAIpC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAG5D,qBAAqB;AACrB,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,YAAY,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAaD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,GAAG,CAAC,OAAO,CAsIxE"}

package/dist/tokens-usage.jsx

@@ -1,6 +1,7 @@
 import { createSignal, createEffect, Show, For } from "solid-js";
 import { Title } from "./components.jsx";
 import { formatNumber, formatCost } from "./formatters.js";
+/** 内联指标组件：显示 "标签: 值" 格式 */
 function InlineMetric(props) {
     return (<box flexDirection="row" gap={0}>
       <text fg={props.color}>{props.label}</text>
@@ -8,6 +9,11 @@ function InlineMetric(props) {
       <text>{props.value}</text>
     </box>);
 }
+/**
+ * Tokens Usage 视图组件
+ * 统计当前会话中所有 assistant 消息的 token 消耗
+ * 按模型分组显示累计数据
+ */
 export function TokensUsageView(props) {
     const [stats, setStats] = createSignal([]);
     const [totals, setTotals] = createSignal(null);
@@ -21,14 +27,15 @@ export function TokensUsageView(props) {
             setIsLoading(false);
             return;
         }
+        // 按 (providerID, modelID) 分组统计
         const grouped = new Map();
-        let lastInput = 0;
         messages.forEach((msg) => {
             if (msg.role !== "assistant")
                 return;
             const assistantMsg = msg;
             if (!assistantMsg.tokens)
                 return;
+            // 以 providerID::modelID 作为分组 key
             const key = `${assistantMsg.providerID || "unknown"}::${assistantMsg.modelID || "unknown"}`;
             if (!grouped.has(key)) {
                 grouped.set(key, {
@@ -43,6 +50,7 @@ export function TokensUsageView(props) {
                     messageCount: 0,
                 });
             }
+            // 累加各项数据
             const stat = grouped.get(key);
             stat.totalCost += assistantMsg.cost || 0;
             stat.input += assistantMsg.tokens.input || 0;
@@ -51,8 +59,8 @@ export function TokensUsageView(props) {
             stat.cacheRead += assistantMsg.tokens.cache?.read || 0;
             stat.cacheWrite += assistantMsg.tokens.cache?.write || 0;
             stat.messageCount += 1;
-            lastInput = assistantMsg.tokens.input || 0;
         });
+        // 计算总计
         let totalInput = 0, totalOutput = 0, totalReasoning = 0;
         let totalCacheRead = 0, totalCacheWrite = 0, totalCost = 0;
         grouped.forEach((stat) => {
@@ -71,7 +79,6 @@ export function TokensUsageView(props) {
             cacheRead: totalCacheRead,
             cacheWrite: totalCacheWrite,
             cost: totalCost,
-            currentInput: lastInput,
         });
         setIsLoading(false);
     });

package/dist/usage.d.ts

@@ -13,5 +13,9 @@ export interface UsageViewProps {
     api: TuiPluginApi;
     sessionId: string;
 }
+/**
+ * Usage Quota 视图组件
+ * 显示 Rolling/Weekly/Monthly 三种维度的额度使用情况
+ */
 export declare function UsageView(props: UsageViewProps): JSX.Element;
 //# sourceMappingURL=usage.d.ts.map

package/dist/usage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../src/usage.tsx"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAIpC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAIpD,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE;QACZ,UAAU,IAAI,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;QAC1C,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC;QACjD,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC;QACnD,0BAA0B,IAAI,MAAM,EAAE,CAAC;QACvC,0BAA0B,IAAI,MAAM,EAAE,CAAC;KACxC,CAAC;IACF,GAAG,EAAE,YAAY,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAoCD,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,GAAG,CAAC,OAAO,CA2N5D"}
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../src/usage.tsx"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAIpC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAKpD,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE;QACZ,UAAU,IAAI,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;QAC1C,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC;QACjD,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC;QACnD,0BAA0B,IAAI,MAAM,EAAE,CAAC;QACvC,0BAA0B,IAAI,MAAM,EAAE,CAAC;KACxC,CAAC;IACF,GAAG,EAAE,YAAY,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAyCD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,GAAG,CAAC,OAAO,CA4N5D"}

package/dist/usage.jsx

@@ -1,7 +1,12 @@
 import { createSignal, createEffect, onCleanup } from "solid-js";
 import { Title, ProgressBar } from "./components.jsx";
 import { formatDuration } from "./formatters.js";
+/** 额度刷新间隔（秒） */
 const REFRESH_INTERVAL = 60;
+/**
+ * 空状态组件
+ * 根据不同情况显示对应的提示信息
+ */
 function EmptyState(props) {
     if (!props.provider) {
         return <text fg="#888">No LLM activity detected</text>;
@@ -20,6 +25,10 @@ function EmptyState(props) {
     }
     return <text fg="#888">No quota data available</text>;
 }
+/**
+ * Usage Quota 视图组件
+ * 显示 Rolling/Weekly/Monthly 三种维度的额度使用情况
+ */
 export function UsageView(props) {
     const [result, setResult] = createSignal(null);
     const [loading, setLoading] = createSignal(true);
@@ -28,20 +37,26 @@ export function UsageView(props) {
     const [refreshCountdown, setRefreshCountdown] = createSignal(REFRESH_INTERVAL);
     const [providerSupported, setProviderSupported] = createSignal(true);
     const [fetchError, setFetchError] = createSignal(null);
+    // 请求 ID 计数器，用于处理竞态条件
+    let currentRequestId = 0;
+    // 从 v1.0.0 恢复的刷新逻辑：只在 provider/model 组合变化时刷新
     const doRefresh = () => {
         const providerID = currentProvider();
         if (!providerID)
             return;
+        const requestId = ++currentRequestId;
         setLoading(true);
         setFetchError(null);
         const supported = props.quotaService.setActiveProvider(providerID);
         setProviderSupported(supported);
         if (!supported) {
-            setLoading(false);
             setResult(null);
+            setLoading(false);
             return;
         }
         props.quotaService.fetchQuota().then((data) => {
+            if (requestId !== currentRequestId)
+                return;
             if (data && data.quota) {
                 setResult(data);
             }
@@ -50,10 +65,15 @@ export function UsageView(props) {
             }
             setLoading(false);
         }).catch((error) => {
+            if (requestId !== currentRequestId)
+                return;
+            console.error("[UsageView] Failed to fetch quota:", error);
             setFetchError(String(error));
+            setResult(null);
             setLoading(false);
         });
     };
+    // Effect 1: 检测 session 消息，提取 provider/model
     createEffect(() => {
         const sessionId = props.sessionId;
         const messages = props.api.state.session.messages(sessionId);
@@ -64,9 +84,14 @@ export function UsageView(props) {
             setProviderSupported(false);
             return;
         }
-        const lastAssistantMsg = [...messages]
-            .reverse()
-            .find((m) => m.role === "assistant");
+        // 从后向前查找最后一个 assistant 消息
+        let lastAssistantMsg = null;
+        for (let i = messages.length - 1; i >= 0; i--) {
+            if (messages[i].role === "assistant") {
+                lastAssistantMsg = messages[i];
+                break;
+            }
+        }
         if (!lastAssistantMsg) {
             setCurrentProvider(null);
             setCurrentModel(null);
@@ -74,7 +99,7 @@ export function UsageView(props) {
             setProviderSupported(false);
             return;
         }
-        if (!("providerID" in lastAssistantMsg)) {
+        if (!("providerID" in lastAssistantMsg) || typeof lastAssistantMsg.providerID !== "string") {
             setCurrentProvider(null);
             setCurrentModel(null);
             setFetchError(null);
@@ -82,12 +107,16 @@ export function UsageView(props) {
             return;
         }
         const providerID = lastAssistantMsg.providerID;
-        const modelID = "modelID" in lastAssistantMsg
+        const modelID = "modelID" in lastAssistantMsg && typeof lastAssistantMsg.modelID === "string"
             ? lastAssistantMsg.modelID
             : "";
-        setCurrentProvider(providerID);
-        setCurrentModel(modelID);
+        // 检查是否真的发生了变化
+        if (providerID !== currentProvider() || modelID !== currentModel()) {
+            setCurrentProvider(providerID);
+            setCurrentModel(modelID);
+        }
     });
+    // Effect 2: 监听 provider 变化，触发额度获取
     createEffect(() => {
         const providerID = currentProvider();
         if (!providerID) {
@@ -96,30 +125,9 @@ export function UsageView(props) {
             setProviderSupported(false);
             return;
         }
-        setLoading(true);
-        setFetchError(null);
-        const supported = props.quotaService.setActiveProvider(providerID);
-        setProviderSupported(supported);
-        if (!supported) {
-            setResult(null);
-            setLoading(false);
-            return;
-        }
-        props.quotaService.fetchQuota().then((data) => {
-            if (data && data.quota) {
-                setResult(data);
-            }
-            else {
-                setResult(null);
-            }
-            setLoading(false);
-        }).catch((error) => {
-            console.error("[UsageView] Failed to fetch quota:", error);
-            setFetchError(String(error));
-            setResult(null);
-            setLoading(false);
-        });
+        doRefresh();
     });
+    // Effect 3: 倒计时定时器，归零时触发刷新
     createEffect(() => {
         setRefreshCountdown(REFRESH_INTERVAL);
         const id = setInterval(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yinxe/opencode-tui-usage",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "OpenCode TUI 额度显示插件 - 在侧边栏显示用量和额度信息",
   "repository": "github:Yinxe/opencode-tui-usage",
   "type": "module",