@leo000001/opencode-quota-sidebar 3.0.9 → 4.0.0

package/CHANGELOG.md

@@ -8,7 +8,6 @@
 - Parse Kimi's `5h` and `Weekly` windows, including reset timestamps, and render them like other subscription providers.
 - Accept OpenCode provider discovery responses that expose Kimi API keys through provider `key` fields.
 - Add built-in MiniMax Coding Plan quota support, including global endpoint matching and pricing aliases.
-- Add built-in XYAI quota support with login-based session auth and legacy alias compatibility.
 - Keep session measured cost aligned with OpenCode root-session `message.cost` while still including descendant subagent usage in API-equivalent cost.
 - Support OpenCode long-context pricing tiers via `context_over_200k` when estimating API-equivalent cost.
 - Bump the usage billing cache version so `/qday`, `/qweek`, and `/qmonth` recompute historical API cost with the updated rules.

package/README.md

@@ -16,7 +16,7 @@ The screenshot above comes from [`./assets/OpenCode-Quota-Sidebar.png`](./assets
 - Renders dedicated `TITLE`, `USAGE`, and `QUOTA` blocks in the TUI sidebar
 - Keeps the shared `session.title` on a compact single line instead of pushing multiline telemetry into every client
 - Aggregates usage for `session`, `day`, `week`, and `month`
-- Supports provider quota/balance fetchers for OpenAI, Copilot, Anthropic, Kimi, Zhipu, MiniMax, RightCode, and XYAI
+- Supports provider quota/balance fetchers for OpenAI, Copilot, Anthropic, Kimi, Zhipu, MiniMax, and RightCode
 - Can include descendant subagent sessions in session-scoped usage/quota totals
 - Exposes `quota_summary` and `quota_show` tools for reports and title toggling
 
@@ -46,24 +46,23 @@ Session-scoped aggregation can include descendant subagent sessions when `sideba
 
 Built-in quota adapters:
 
-| Provider            | Endpoint family                                            | Auth                  | Quota shape                | Notes                                                     |
-| ------------------- | ---------------------------------------------------------- | --------------------- | -------------------------- | --------------------------------------------------------- |
-| OpenAI Codex        | `chatgpt.com/backend-api/wham/usage`                       | OAuth                 | Multi-window subscription  | Reads ChatGPT usage windows such as short-term + weekly   |
-| GitHub Copilot      | `api.github.com/copilot_internal/user`                     | OAuth                 | Monthly subscription       | Uses the Copilot internal user endpoint                   |
-| Anthropic           | `api.anthropic.com/api/oauth/usage`                        | OAuth                 | Multi-window subscription  | Supports plan-based usage windows                         |
-| Kimi For Coding     | `api.kimi.com/coding/v1/usages`                            | API key               | Multi-window subscription  | Typically `5h` + weekly windows                           |
-| Zhipu Coding Plan   | `bigmodel.cn/api/monitor/usage/quota/limit`                | API key               | Token quota                | Coding-plan style quota window                            |
-| MiniMax Coding Plan | `www.minimaxi.com/v1/api/openplatform/coding_plan/remains` | API key               | Multi-window subscription  | Typically `5h` + weekly windows                           |
-| RightCode           | `www.right.codes/account/summary`                          | API key               | Daily quota and/or balance | Prefix-based subscription matching, with balance fallback |
-| XYAI                | `new.xychatai.com/frontend-api/*`                          | Login -> session auth | Daily balance              | Disabled by default, configured in `quota.providers.xyai` |
+| Provider            | Endpoint family                                            | Auth    | Quota shape                | Notes                                                                                                                            |
+| ------------------- | ---------------------------------------------------------- | ------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| OpenAI Codex        | `chatgpt.com/backend-api/wham/usage`                       | OAuth   | Multi-window subscription  | Reads ChatGPT usage windows such as short-term + weekly; Pro plans may also expose Codex Spark limits (`additional_rate_limits`) |
+| GitHub Copilot      | `api.github.com/copilot_internal/user`                     | OAuth   | Monthly subscription       | Uses the Copilot internal user endpoint                                                                                          |
+| Anthropic           | `api.anthropic.com/api/oauth/usage`                        | OAuth   | Multi-window subscription  | Supports plan-based usage windows                                                                                                |
+| Kimi For Coding     | `api.kimi.com/coding/v1/usages`                            | API key | Multi-window subscription  | Typically `5h` + weekly windows                                                                                                  |
+| Zhipu Coding Plan   | `bigmodel.cn/api/monitor/usage/quota/limit`                | API key | Token quota                | Coding-plan style quota window                                                                                                   |
+| MiniMax Coding Plan | `www.minimaxi.com/v1/api/openplatform/coding_plan/remains` | API key | Multi-window subscription  | Typically `5h` + weekly windows                                                                                                  |
+| RightCode           | `www.right.codes/account/summary`                          | API key | Daily quota and/or balance | Prefix-based subscription matching, with balance fallback                                                                        |
 
 Generic providers without a built-in quota endpoint can still contribute usage totals, but they will not show quota/balance unless an adapter exists.
 
 Provider notes:
 
 - OpenAI, Copilot, and Anthropic quota support is based on OAuth/session auth, not generic API-key billing endpoints
+- **OpenAI Codex Spark**: OpenAI Pro subscriptions may expose additional per-feature windows (e.g. `GPT-5.3-Codex-Spark`) in the `additional_rate_limits` field of the `wham/usage` response. When present, the plugin automatically parses and renders these as extra windows under the OpenAI quota line. No extra config is required. Code review quota (`code_review_rate_limit`) is not displayed yet.
 - RightCode can show both a daily allowance line and a balance line
-- XYAI requires login credentials in config so the plugin can obtain and cache session auth
 - Copilot quota is supported, but API-equivalent cost is intentionally not shown because runtime pricing is not reliable enough
 
 ## Display Rules
@@ -98,7 +97,7 @@ For OpenCode `>=1.2.15`, keep server plugins in `opencode.json` and TUI plugins
 
 ## Sidebar Demo
 
-Typical TUI sidebar layout:
+Typical TUI sidebar layout (with Codex Spark windows):
 
 ```text
 TITLE
@@ -110,6 +109,8 @@ USAGE
 QUOTA
   OAI 5h80 R3h20m
       W70 R2D04h
+      Sk5h100 R1h00m
+      SkW100 R3D04h
   Cop M78 R12D00h
   RC D$88.9/$60 E6D00h
      B260
@@ -121,31 +122,41 @@ Compact shared title example:
 Fix quota adapter matching | OAI 5h80 R3h20m W70 R2D04h | RC D$88.9/$60 B260 | Cd66% | Est$12.8
 ```
 
-Another compact title example with multiple providers:
-
-```text
-Add XYAI quota adapter | Ant 5h100 W77 O7d60 | Cop M78 R04-01 | Cd52% | Est$2.34
-```
-
 ## Tool Report Demo
 
-Example `quota_summary` markdown output shape:
+Example historical `quota_summary` markdown output shape:
 
 ```md
-## Session Usage
+## Quota History - Daily since 2026-02-18
+
+### Quota Status
+
+- OpenAI: 5h | 80.0% | reset 3h20m; Weekly | 70.0% | reset 2D04h
+- Copilot: Monthly | 78.0% | reset 12D00h
+- RightCode: Daily $88.9/$60 | reset 6D00h
+
+### Totals
+
+| Metric       | Total | Avg/Period |
+| ------------ | ----: | ---------: |
+| Requests     |   184 |       26.3 |
+| Total Tokens |  277k |      39.6k |
+| Cache Hit    | 63.1% |      58.4% |
+| API Cost     | $12.8 |      $1.83 |
+
+### Provider Breakdown
 
-- Requests: 184
-- Input: 189k
-- Output: 53.2k
-- Cache Read: 31.4k
-- Cache Write: 3.2k
-- Cost as API: $12.8
+| Provider  | Req | Input | Output | Total | Share | Cache Hit | API Cost |
+| --------- | --: | ----: | -----: | ----: | ----: | --------: | -------: |
+| OpenAI    | 140 |  160k |    61k |  221k | 79.8% |     66.2% |    $10.4 |
+| Anthropic |  44 |   29k |  27.1k | 56.1k | 20.2% |     51.3% |    $2.34 |
 
-## Quota
+### Period Detail
 
-- OpenAI: 5h 80% (reset 3h20m), Weekly 70% (reset 2D04h)
-- Copilot: Monthly 78% (reset 12D00h)
-- RightCode: Daily $88.9/$60 (exp 6D00h), Balance $260
+| Period       | Requests | Input | Output | Cache | Cache Hit | Total | API Cost |
+| ------------ | -------: | ----: | -----: | ----: | --------: | ----: | -------: |
+| 2026-02-18   |       12 | 18.3k |   4.2k |  8.9k |     32.7% | 31.4k |    $1.12 |
+| 2026-02-24\* |       17 |  8.1k |   2.0k |  3.4k |     66.0% | 13.5k |    $0.88 |
 ```
 
 The tool already returns full markdown. Clients should display that report directly instead of replacing it with a short summary.
@@ -185,6 +196,8 @@ Quota tokens:
 - `D`: daily window
 - `W`: weekly window
 - `M`: monthly window
+- `Sk5h`: OpenAI Codex Spark short window (e.g. 5h)
+- `SkW`: OpenAI Codex Spark weekly window
 - `R3h20m`: resets in `3h20m`
 - `R2D04h`: resets in `2D04h`
 - `E6D00h`: expires in `6D00h`
@@ -192,6 +205,8 @@ Quota tokens:
 Example compact quota fragments:
 
 - `OAI 5h80 R3h20m`: OpenAI short window, 80% remaining, resets in `3h20m`
+- `OAI Sk5h100 R1h00m`: OpenAI Codex Spark 5h window, 100% remaining, resets in `1h00m`
+- `OAI SkW100 R3D04h`: OpenAI Codex Spark weekly window, 100% remaining, resets in `3D04h`
 - `Cop M78 R12D00h`: Copilot monthly quota, 78% remaining, resets in `12D00h`
 - `RC D$88.9/$60 E6D00h B260`: RightCode daily quota plus balance
 
@@ -223,13 +238,10 @@ See [`quota-sidebar.config.example.json`](./quota-sidebar.config.example.json) f
 Important config notes:
 
 - `sidebar.titleMode`: `auto`, `compact`, or `multiline`
-- `sidebar.showCost`: controls API-equivalent cost in sidebar, title, markdown report, and toast
+- `sidebar.showCost`: controls API-equivalent cost in sidebar, title, markdown report, toast, and CLI output
 - `sidebar.wrapQuotaLines`: wraps long quota lines with indentation instead of dropping fields
 - `sidebar.includeChildren`: includes descendant subagent sessions for `period=session`
-- `quota.providers.xyai.enabled`: must be explicitly enabled if you want XYAI quota
-- `quota.providers.xyai.login.username/password`: used to fetch and refresh XYAI session auth
-
-Config is layered. The later source overrides the earlier one:
+  Config is layered. The later source overrides the earlier one:
 
 1. global config
 2. worktree config
@@ -258,25 +270,48 @@ Behavior notes:
 
 - `quota_summary` returns the full markdown report body
 - `quota_summary` can show a toast in addition to returning markdown
+- `quota_summary` accepts `period`, `since`, `last`, `toast`, and `includeChildren`
 - `quota_summary(includeChildren=true)` only changes `period=session`
+- `day/week/month` scans all sessions in the selected time range, so child sessions are included when they have activity in that range
+- `day/week/month` does not do parent-tree rollup; child sessions are counted as independent sessions, not merged through `includeChildren`
+- `since` and `last` are mutually exclusive
+- `period=session` does not accept `since` or `last`
 - `quota_show(enabled=true|false)` can explicitly force a state instead of toggling
+- Historical reports support both absolute `since` and relative `last`
+- `since` accepts `YYYY-MM` or `YYYY-MM-DD`
+- `last` accepts a positive integer and is relative to the current period: `day=7`, `week=8`, `month=6`
+- Empty `period=day|week|month` means the current natural day/week/month
 
 Example command aliases:
 
+For direct in-chat history output, define command aliases that call `quota_summary`.
+The old TUI history popup path was removed; history now goes through the tool report directly.
+These aliases are still OpenCode command templates, so they expand into prompt text before the model/tool chain runs. For the cleanest direct output path, prefer the standalone CLI.
+
+Examples:
+
+- `quota_summary(period=day)` -> today
+- `quota_summary(period=week)` -> this week
+- `quota_summary(period=month)` -> this month
+- `quota_summary(period=day,last=7)` -> last 7 days
+- `quota_summary(period=week,last=8)` -> last 8 weeks
+- `quota_summary(period=month,last=6)` -> last 6 months
+- `quota_summary(period=month,since=2026-01)` -> since Jan 2026
+
 ```json
 {
   "command": {
     "qday": {
-      "description": "Show today's usage and quota",
-      "template": "Call tool quota_summary with period=day and toast=true."
+      "description": "Today / last N days / since date",
+      "template": "Run /qday for opencode-quota-sidebar. Call tool quota_summary exactly once and return its full report directly. If `$ARGUMENTS` is empty: period=day, toast=true. If `$ARGUMENTS` is a positive integer: period=day, last=<that integer>, toast=true. If `$ARGUMENTS` matches YYYY-MM-DD: period=day, since=<that date>, toast=true. Otherwise briefly explain: empty, positive integer, or YYYY-MM-DD."
     },
     "qweek": {
-      "description": "Show this week's usage and quota",
-      "template": "Call tool quota_summary with period=week and toast=true."
+      "description": "This week / last N weeks / since date",
+      "template": "Run /qweek for opencode-quota-sidebar. Call tool quota_summary exactly once and return its full report directly. If `$ARGUMENTS` is empty: period=week, toast=true. If `$ARGUMENTS` is a positive integer: period=week, last=<that integer>, toast=true. If `$ARGUMENTS` matches YYYY-MM-DD: period=week, since=<that date>, toast=true. Otherwise briefly explain: empty, positive integer, or YYYY-MM-DD."
     },
     "qmonth": {
-      "description": "Show this month's usage and quota",
-      "template": "Call tool quota_summary with period=month and toast=true."
+      "description": "This month / last N months / since month",
+      "template": "Run /qmonth for opencode-quota-sidebar. Call tool quota_summary exactly once and return its full report directly. If `$ARGUMENTS` is empty: period=month, toast=true. If `$ARGUMENTS` is a positive integer: period=month, last=<that integer>, toast=true. If `$ARGUMENTS` matches YYYY-MM: period=month, since=<that month>, toast=true. Otherwise briefly explain: empty, positive integer, or YYYY-MM."
     },
     "qtoggle": {
       "description": "Toggle sidebar usage display on/off",
@@ -286,6 +321,86 @@ Example command aliases:
 }
 ```
 
+## CLI
+
+The package exposes a standalone CLI dashboard. After installing globally or making the `bin` available:
+
+```bash
+# Current period (single snapshot)
+opencode-quota day          # today
+opencode-quota week         # this week (Monday-based)
+opencode-quota month        # this month
+
+# Multi-period history
+opencode-quota day 7        # last 7 days
+opencode-quota week 8       # last 8 weeks
+opencode-quota month 6      # last 6 months
+
+# Absolute start date
+opencode-quota day --since 2026-04-01
+opencode-quota week --since 2026-04-01
+opencode-quota month --since 2026-01
+
+# Also accepted as positional (equivalent to --since)
+opencode-quota day 2026-04-01
+opencode-quota month 2026-01
+```
+
+When called without `last` or `--since`, the CLI renders a single-period snapshot (`QUOTA + TOTALS + PROVIDERS`). When called with `last` or `--since`, it renders multi-period history with a larger multi-line `TREND` block.
+
+### CLI semantics
+
+- `day` = current natural day; `week` = current natural week (Monday-based); `month` = current natural month
+- A positional integer maps to `last=<N>` (number of periods back from now)
+- A positional date string maps to `--since` (`YYYY-MM-DD` for day/week, `YYYY-MM` for month)
+- `--since` and `--last` are mutually exclusive
+- `last` is limited to 90 for day, reasonable ranges for week/month
+
+### Trend section
+
+The `TREND` block appears only in multi-period mode. Each metric (`Requests`, `Tokens`, `Cache`, `Cost`) is rendered as a small multi-line bar chart:
+
+- one summary line: the current value only
+- one bar row per visible period (latest 8 periods max), ordered oldest-to-newest
+- the current period is marked with `*`
+
+Interpretation example:
+
+```text
+Requests 12.3k
+  04-08   | ███░░░░░░░░░░░░░░░ | 4.1k
+  04-09   | ██████░░░░░░░░░░░░ | 8.2k
+  04-10*  | █████████████░░░░░ | 12.3k
+```
+
+This means the current bucket has `12.3k` requests, and the bar rows below show the relative size of each visible bucket from oldest to newest.
+
+### Connection behavior
+
+- The CLI talks to the local OpenCode API at `http://localhost:4096` by default
+- Set `OPENCODE_BASE_URL` to override (e.g. `http://192.168.1.10:4096`)
+- If no server is running and `OPENCODE_BASE_URL` is not set, the CLI attempts to start one:
+  - **Linux/macOS**: runs `opencode serve --hostname=127.0.0.1 --port=4096`
+  - **Windows**: tries `opencode.cmd`, then `opencode` via `shell: true`, then `bash -lc opencode`
+- The auto-start waits up to 10 seconds for the server to print `opencode server listening on <url>`
+- If auto-start fails, check that `opencode` is in your `PATH`
+- On Windows, the `shell: true` path is usually the most reliable when `opencode.cmd` is not directly spawnable from Node
+
+### Platform notes
+
+- **Terminal encoding**: the dashboard uses Unicode box-drawing and block elements (`█░`). Requires a UTF-8 capable terminal. Windows users should use Windows Terminal, PowerShell 7+, or a terminal that supports UTF-8. Classic cmd.exe with legacy codepages (CP437/CP850) may render garbled characters.
+- **Alignment**: weekly/monthly trend labels can still be truncated when the visible label is very long (for example long absolute week ranges). This is a known presentation tradeoff in the current terminal renderer.
+- **Windows PATH**: the CLI tries multiple command forms to find `opencode`. If none work, ensure `opencode` or `opencode.cmd` is on your PATH, or start the server manually and set `OPENCODE_BASE_URL`.
+- **Node.js**: requires `>=18`
+
+### Environment variables
+
+| Variable                     | Default                   | Purpose                                                                          |
+| ---------------------------- | ------------------------- | -------------------------------------------------------------------------------- |
+| `OPENCODE_BASE_URL`          | `http://localhost:4096`   | OpenCode API endpoint; set this if the server is remote or on a non-default port |
+| `OPENCODE_QUOTA_CONFIG_HOME` | `~/.config/opencode`      | Global config directory override                                                 |
+| `OPENCODE_QUOTA_DATA_HOME`   | `~/.local/share/opencode` | Global data directory override                                                   |
+
 ## Development
 
 ```bash

package/README.zh-CN.md

@@ -13,7 +13,7 @@ OpenCode 插件：在 TUI sidebar 中显示 token 用量和 provider quota，同
 - 在 TUI sidebar 中渲染结构化的 `TITLE`、`USAGE`、`QUOTA` 三个区块
 - 让共享 `session.title` 保持紧凑单行，而不是把多行遥测数据写进所有客户端都共用的标题
 - 统计 `session`、`day`、`week`、`month` 四种范围的 usage
-- 内置支持 OpenAI、Copilot、Anthropic、Kimi、Zhipu、MiniMax、RightCode、XYAI 的 quota / balance 获取
+- 内置支持 OpenAI、Copilot、Anthropic、Kimi、Zhipu、MiniMax、RightCode 的 quota / balance 获取
 - session 级统计可选聚合 descendant subagent sessions
 - 提供 `quota_summary` 和 `quota_show` 两个工具
 
@@ -43,23 +43,22 @@ OpenCode 插件：在 TUI sidebar 中显示 token 用量和 provider quota，同
 
 内置 quota adapter 如下：
 
-| Provider            | Endpoint family                                            | 鉴权方式            | 展示形态        | 说明                                               |
-| ------------------- | ---------------------------------------------------------- | ------------------- | --------------- | -------------------------------------------------- |
-| OpenAI Codex        | `chatgpt.com/backend-api/wham/usage`                       | OAuth               | 多窗口订阅额度  | 读取 ChatGPT usage 窗口，例如短窗口 + 周窗口       |
-| GitHub Copilot      | `api.github.com/copilot_internal/user`                     | OAuth               | 月度额度        | 使用 Copilot internal user 接口                    |
-| Anthropic           | `api.anthropic.com/api/oauth/usage`                        | OAuth               | 多窗口订阅额度  | 支持 plan-based usage windows                      |
-| Kimi For Coding     | `api.kimi.com/coding/v1/usages`                            | API key             | 多窗口订阅额度  | 通常为 `5h` + weekly                               |
-| Zhipu Coding Plan   | `bigmodel.cn/api/monitor/usage/quota/limit`                | API key             | token quota     | coding plan 风格额度                               |
-| MiniMax Coding Plan | `www.minimaxi.com/v1/api/openplatform/coding_plan/remains` | API key             | 多窗口订阅额度  | 通常为 `5h` + weekly                               |
-| RightCode           | `www.right.codes/account/summary`                          | API key             | 日额度和/或余额 | 按 prefix 匹配订阅，失败时回退为 balance           |
-| XYAI                | `new.xychatai.com/frontend-api/*`                          | 登录态 session auth | 日额度 / 日余额 | 默认关闭，需要在 `quota.providers.xyai` 中显式开启 |
+| Provider            | Endpoint family                                            | 鉴权方式 | 展示形态        | 说明                                                                                                            |
+| ------------------- | ---------------------------------------------------------- | -------- | --------------- | --------------------------------------------------------------------------------------------------------------- |
+| OpenAI Codex        | `chatgpt.com/backend-api/wham/usage`                       | OAuth    | 多窗口订阅额度  | 读取 ChatGPT usage 窗口，例如短窗口 + 周窗口；Pro 订阅可能额外提供 Codex Spark 限额（`additional_rate_limits`） |
+| GitHub Copilot      | `api.github.com/copilot_internal/user`                     | OAuth    | 月度额度        | 使用 Copilot internal user 接口                                                                                 |
+| Anthropic           | `api.anthropic.com/api/oauth/usage`                        | OAuth    | 多窗口订阅额度  | 支持 plan-based usage windows                                                                                   |
+| Kimi For Coding     | `api.kimi.com/coding/v1/usages`                            | API key  | 多窗口订阅额度  | 通常为 `5h` + weekly                                                                                            |
+| Zhipu Coding Plan   | `bigmodel.cn/api/monitor/usage/quota/limit`                | API key  | token quota     | coding plan 风格额度                                                                                            |
+| MiniMax Coding Plan | `www.minimaxi.com/v1/api/openplatform/coding_plan/remains` | API key  | 多窗口订阅额度  | 通常为 `5h` + weekly                                                                                            |
+| RightCode           | `www.right.codes/account/summary`                          | API key  | 日额度和/或余额 | 按 prefix 匹配订阅，失败时回退为 balance                                                                        |
 
 补充说明：
 
 - 没有内置 quota adapter 的 generic provider 仍然可以参与 usage 聚合，但不会显示 quota/balance
 - OpenAI、Copilot、Anthropic 的 quota 支持依赖 OAuth / session auth，而不是通用 API key 账单接口
+- **OpenAI Codex Spark**：OpenAI Pro 订阅的 `wham/usage` 响应中可能包含 `additional_rate_limits` 字段，其中带有 `GPT-5.3-Codex-Spark` 等额外功能窗口。插件会自动解析并将其显示在 OpenAI quota 行下，无需额外配置。`code_review_rate_limit`（代码审查额度）目前暂不展示。
 - RightCode 可能同时显示 daily allowance 和 balance 两行
-- XYAI 需在配置中提供登录信息，插件会自行获取并缓存 session auth
 - Copilot 支持 quota 展示，但当前不会显示 API-equivalent cost，因为 pricing metadata 不够稳定
 
 ## 展示规则
@@ -79,7 +78,7 @@ title 相关补充：
 
 ## Sidebar 示例
 
-典型的 TUI sidebar 布局：
+典型的 TUI sidebar 布局（含 Codex Spark 窗口）：
 
 ```text
 TITLE
@@ -91,6 +90,8 @@ USAGE
 QUOTA
   OAI 5h80 R3h20m
       W70 R2D04h
+      Sk5h100 R1h00m
+      SkW100 R3D04h
   Cop M78 R12D00h
   RC D$88.9/$60 E6D00h
      B260
@@ -102,31 +103,41 @@ compact shared title 示例：
 Fix quota adapter matching | OAI 5h80 R3h20m W70 R2D04h | RC D$88.9/$60 B260 | Cd66% | Est$12.8
 ```
 
-另一个多 provider 示例：
-
-```text
-Add XYAI quota adapter | Ant 5h100 W77 O7d60 | Cop M78 R04-01 | Cd52% | Est$2.34
-```
-
 ## Tool Report 示例
 
-`quota_summary` 返回的 markdown 大致会是这样的结构：
+历史 `quota_summary` markdown 大致会是这样的结构：
 
 ```md
-## Session Usage
+## Quota History - Daily since 2026-02-18
+
+### Quota Status
+
+- OpenAI: 5h | 80.0% | reset 3h20m; Weekly | 70.0% | reset 2D04h
+- Copilot: Monthly | 78.0% | reset 12D00h
+- RightCode: Daily $88.9/$60 | reset 6D00h
+
+### Totals
+
+| Metric       | Total | Avg/Period |
+| ------------ | ----: | ---------: |
+| Requests     |   184 |       26.3 |
+| Total Tokens |  277k |      39.6k |
+| Cache Hit    | 63.1% |      58.4% |
+| API Cost     | $12.8 |      $1.83 |
+
+### Provider Breakdown
 
-- Requests: 184
-- Input: 189k
-- Output: 53.2k
-- Cache Read: 31.4k
-- Cache Write: 3.2k
-- Cost as API: $12.8
+| Provider  | Req | Input | Output | Total | Share | Cache Hit | API Cost |
+| --------- | --: | ----: | -----: | ----: | ----: | --------: | -------: |
+| OpenAI    | 140 |  160k |    61k |  221k | 79.8% |     66.2% |    $10.4 |
+| Anthropic |  44 |   29k |  27.1k | 56.1k | 20.2% |     51.3% |    $2.34 |
 
-## Quota
+### Period Detail
 
-- OpenAI: 5h 80% (reset 3h20m), Weekly 70% (reset 2D04h)
-- Copilot: Monthly 78% (reset 12D00h)
-- RightCode: Daily $88.9/$60 (exp 6D00h), Balance $260
+| Period       | Requests | Input | Output | Cache | Cache Hit | Total | API Cost |
+| ------------ | -------: | ----: | -----: | ----: | --------: | ----: | -------: |
+| 2026-02-18   |       12 | 18.3k |   4.2k |  8.9k |     32.7% | 31.4k |    $1.12 |
+| 2026-02-24\* |       17 |  8.1k |   2.0k |  3.4k |     66.0% | 13.5k |    $0.88 |
 ```
 
 这个工具本身就返回完整 markdown，调用方应该直接展示，而不是再压缩成一句话摘要。
@@ -170,6 +181,8 @@ Quota token：
 - `D`：daily window
 - `W`：weekly window
 - `M`：monthly window
+- `Sk5h`：OpenAI Codex Spark 短窗口（如 5h）
+- `SkW`：OpenAI Codex Spark 周窗口
 - `R3h20m`：还剩 `3h20m` 重置
 - `R2D04h`：还剩 `2D04h` 重置
 - `E6D00h`：还剩 `6D00h` 到期
@@ -177,6 +190,8 @@ Quota token：
 compact quota 片段示例：
 
 - `OAI 5h80 R3h20m`：OpenAI 短窗口剩余 80%，还剩 `3h20m` 重置
+- `OAI Sk5h100 R1h00m`：OpenAI Codex Spark 5h 窗口剩余 100%，还剩 `1h00m` 重置
+- `OAI SkW100 R3D04h`：OpenAI Codex Spark 周窗口剩余 100%，还剩 `3D04h` 重置
 - `Cop M78 R12D00h`：Copilot 月额度剩余 78%，还剩 `12D00h` 重置
 - `RC D$88.9/$60 E6D00h B260`：RightCode 日额度 + 余额
 
@@ -230,13 +245,10 @@ OpenCode `>=1.2.15` 时，server 插件放在 `opencode.json`，TUI 插件放在
 重要配置项：
 
 - `sidebar.titleMode`：`auto`、`compact`、`multiline`
-- `sidebar.showCost`：控制 sidebar、title、markdown report、toast 中的 API-equivalent cost 可见性
+- `sidebar.showCost`：控制 sidebar、title、markdown report、toast 和 CLI 中的 API-equivalent cost 可见性
 - `sidebar.wrapQuotaLines`：长 quota 行是否自动续行并缩进
 - `sidebar.includeChildren`：`period=session` 时是否聚合 descendant subagent sessions
-- `quota.providers.xyai.enabled`：是否启用 XYAI quota
-- `quota.providers.xyai.login.username/password`：XYAI 登录信息，用于换取和刷新 session auth
-
-配置采用分层覆盖，后层配置覆盖前层配置：
+  配置采用分层覆盖，后层配置覆盖前层配置：
 
 1. 全局配置
 2. worktree 配置
@@ -265,25 +277,48 @@ usage 聚合采用增量模式。插件会为每个 session 维护 cursor，优
 
 - `quota_summary` 返回完整 markdown report
 - `quota_summary` 可以同时触发 toast 展示
+- `quota_summary` 参数为 `period`、`since`、`last`、`toast`、`includeChildren`
 - `quota_summary(includeChildren=true)` 只影响 `period=session`
+- `day/week/month` 会扫描所选时间范围内的全部 sessions，所以 child sessions 只要在该范围内有 activity 就会被统计进去
+- `day/week/month` 不做 parent 树 rollup；child sessions 会作为独立 sessions 计入，而不是通过 `includeChildren` 合并到 parent
+- `since` 和 `last` 互斥
+- `period=session` 不支持 `since` / `last`
 - `quota_show(enabled=true|false)` 可以显式指定目标状态，而不是只做 toggle
+- 历史报告同时支持绝对时间 `since` 和相对区间 `last`
+- `since` 支持 `YYYY-MM` 或 `YYYY-MM-DD`
+- `last` 需要正整数，并按当前 period 相对计算：`day=7`、`week=8`、`month=6`
+- 空参数的 `period=day|week|month` 表示当前自然日 / 自然周 / 自然月
 
 命令别名示例：
 
+如果你想直接走工具输出查看历史，可以在配置里声明调用 `quota_summary` 的命令别名。
+旧的 TUI 历史弹窗路径已经移除，历史查看统一回到 tool report。
+这些别名本质上仍然是 OpenCode 的 command template，因此会先展开为提示词，再进入模型 / tool 链路。若想要更直接、更干净的输出路径，优先使用独立 CLI。
+
+示例：
+
+- `quota_summary(period=day)` -> 今天
+- `quota_summary(period=week)` -> 本周
+- `quota_summary(period=month)` -> 本月
+- `quota_summary(period=day,last=7)` -> 最近 7 天
+- `quota_summary(period=week,last=8)` -> 最近 8 周
+- `quota_summary(period=month,last=6)` -> 最近 6 个月
+- `quota_summary(period=month,since=2026-01)` -> 从 2026-01 开始
+
 ```json
 {
   "command": {
     "qday": {
-      "description": "Show today's usage and quota",
-      "template": "Call tool quota_summary with period=day and toast=true."
+      "description": "Today / last N days / since date",
+      "template": "Run /qday for opencode-quota-sidebar. Call tool quota_summary exactly once and return its full report directly. If `$ARGUMENTS` is empty: period=day, toast=true. If `$ARGUMENTS` is a positive integer: period=day, last=<that integer>, toast=true. If `$ARGUMENTS` matches YYYY-MM-DD: period=day, since=<that date>, toast=true. Otherwise briefly explain: empty, positive integer, or YYYY-MM-DD."
     },
     "qweek": {
-      "description": "Show this week's usage and quota",
-      "template": "Call tool quota_summary with period=week and toast=true."
+      "description": "This week / last N weeks / since date",
+      "template": "Run /qweek for opencode-quota-sidebar. Call tool quota_summary exactly once and return its full report directly. If `$ARGUMENTS` is empty: period=week, toast=true. If `$ARGUMENTS` is a positive integer: period=week, last=<that integer>, toast=true. If `$ARGUMENTS` matches YYYY-MM-DD: period=week, since=<that date>, toast=true. Otherwise briefly explain: empty, positive integer, or YYYY-MM-DD."
     },
     "qmonth": {
-      "description": "Show this month's usage and quota",
-      "template": "Call tool quota_summary with period=month and toast=true."
+      "description": "This month / last N months / since month",
+      "template": "Run /qmonth for opencode-quota-sidebar. Call tool quota_summary exactly once and return its full report directly. If `$ARGUMENTS` is empty: period=month, toast=true. If `$ARGUMENTS` is a positive integer: period=month, last=<that integer>, toast=true. If `$ARGUMENTS` matches YYYY-MM: period=month, since=<that month>, toast=true. Otherwise briefly explain: empty, positive integer, or YYYY-MM."
     },
     "qtoggle": {
       "description": "Toggle sidebar usage display on/off",
@@ -293,6 +328,86 @@ usage 聚合采用增量模式。插件会为每个 session 维护 cursor，优
 }
 ```
 
+## CLI
+
+这个包同时提供一个独立 CLI dashboard。全局安装或让 `bin` 可执行后：
+
+```bash
+# 当前周期（单次快照）
+opencode-quota day          # 今天
+opencode-quota week         # 本周（周一起算）
+opencode-quota month        # 本月
+
+# 多周期历史
+opencode-quota day 7        # 最近 7 天
+opencode-quota week 8       # 最近 8 周
+opencode-quota month 6      # 最近 6 个月
+
+# 绝对起始日期
+opencode-quota day --since 2026-04-01
+opencode-quota week --since 2026-04-01
+opencode-quota month --since 2026-01
+
+# 位置参数也接受日期字符串（等同于 --since）
+opencode-quota day 2026-04-01
+opencode-quota month 2026-01
+```
+
+不带 `last` 或 `--since` 时，CLI 渲染单周期快照（`QUOTA + TOTALS + PROVIDERS`）。带 `last` 或 `--since` 时渲染多周期历史，并额外展示更大的多行 `TREND` 区块。
+
+### CLI 语义
+
+- `day` = 当前自然日；`week` = 当前自然周（周一起算）；`month` = 当前自然月
+- 位置参数正整数映射为 `last=<N>`（从当前往回数 N 个周期）
+- 位置参数日期字符串映射为 `--since`（day/week 用 `YYYY-MM-DD`，month 用 `YYYY-MM`）
+- `--since` 和 `--last` 互斥
+- `last` 对 day 限制 90，week/month 也有合理范围限制
+
+### Trend 区块
+
+`TREND` 区块仅在多周期模式下出现。每个指标（`Requests`、`Tokens`、`Cache`、`Cost`）都会渲染为一个小型多行柱状图：
+
+- 一行摘要：当前值
+- 每个可见周期一行柱状条（最多展示最近 8 个周期）
+- 当前周期用 `*` 标记
+
+解读示例：
+
+```text
+Requests 12.3k
+  04-08   | ███░░░░░░░░░░░░░░░ | 4.1k
+  04-09   | ██████░░░░░░░░░░░░ | 8.2k
+  04-10*  | █████████████░░░░░ | 12.3k
+```
+
+这表示当前 bucket 有 `12.3k` 请求，下面的柱状条则按时间顺序展示各个可见 bucket 的相对大小。
+
+### 连接行为
+
+- CLI 默认连接本地 OpenCode API `http://localhost:4096`
+- 通过 `OPENCODE_BASE_URL` 覆盖（例如 `http://192.168.1.10:4096`）
+- 如果没有运行中的 server 且未设置 `OPENCODE_BASE_URL`，CLI 会尝试自动启动：
+  - **Linux/macOS**：运行 `opencode serve --hostname=127.0.0.1 --port=4096`
+  - **Windows**：依次尝试 `opencode.cmd`、`opencode`（通过 `shell: true`）、`bash -lc opencode`
+- 自动启动等待最多 10 秒，直到 server 输出 `opencode server listening on <url>`
+- 如果自动启动失败，请确认 `opencode` 在你的 `PATH` 中
+- 在 Windows 上，如果 `opencode.cmd` 不能被 Node 直接 spawn，`shell: true` 通常是更可靠的兜底路径
+
+### 平台说明
+
+- **终端编码**：dashboard 使用 Unicode 绘框字符和方块元素（`█░`），需要支持 UTF-8 的终端。Windows 用户应使用 Windows Terminal、PowerShell 7+ 或其他支持 UTF-8 的终端。经典 cmd.exe 使用传统代码页（CP437/CP850）时可能显示乱码。
+- **对齐**：当 week/month 的可见标签非常长时（例如完整绝对日期范围），CLI 的 trend 标签仍可能被截断。这是当前终端 renderer 的已知展示取舍。
+- **Windows PATH**：CLI 会尝试多种命令形式来找到 `opencode`。如果全部失败，请确认 `opencode` 或 `opencode.cmd` 在 PATH 中，或手动启动 server 后设置 `OPENCODE_BASE_URL`。
+- **Node.js**：需要 `>=18`
+
+### 环境变量
+
+| 变量                         | 默认值                    | 用途                                               |
+| ---------------------------- | ------------------------- | -------------------------------------------------- |
+| `OPENCODE_BASE_URL`          | `http://localhost:4096`   | OpenCode API 端点；server 在远程或非默认端口时设置 |
+| `OPENCODE_QUOTA_CONFIG_HOME` | `~/.config/opencode`      | 全局配置目录覆盖                                   |
+| `OPENCODE_QUOTA_DATA_HOME`   | `~/.local/share/opencode` | 全局数据目录覆盖                                   |
+
 ## 开发
 
 ```bash

package/SECURITY.md

@@ -25,7 +25,7 @@ We will acknowledge reports as quickly as possible and provide a remediation tim
 - Keep debug logs free of secrets.
 - Prefer fail-closed behavior for writes (already enforced via symlink checks and atomic writes).
 - Quota fetching may contact provider-operated endpoints such as OpenAI, GitHub,
-  Anthropic, Kimi, Zhipu, MiniMax, RightCode, and XYAI; review any new
+  Anthropic, Kimi, Zhipu, MiniMax, and RightCode; review any new
   provider integration for outbound data exposure and header/token handling.
 - Some quota integrations rely on beta or internal-style endpoints; document
   instability risks clearly and avoid assuming long-term API compatibility.

package/dist/cli.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { type HistoryPeriod } from './period.js';
+type CliCommand = {
+    period: HistoryPeriod;
+    since?: string;
+    last?: number;
+};
+type CliServerCommand = {
+    command: string;
+    args: string[];
+    shell?: boolean;
+};
+export declare function parseCliArgs(argv: string[]): CliCommand;
+export declare function cliBaseUrl(): string;
+export declare function cliServerCommandCandidates(platform?: NodeJS.Platform): CliServerCommand[];
+export declare function runCli(argv: string[]): Promise<string>;
+export declare function cliExitCodeForError(message: string): 0 | 1;
+export {};