perf: /quota 单次 token 成本降约 43%

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "command-code-usage",
       "source": "./command-code-usage",
-      "version": "1.1.0",
+      "version": "1.2.0",
       "description": "See your Command Code plan usage — 5-hour and weekly rolling windows, monthly credits or balance — right inside the conversation, with a remaining-requests estimate and a burn-rate warning. Requires a Command Code plan.",
       "displayName": "Command Code Usage",
       "category": "utilities",

CHANGELOG.md

@@ -3,6 +3,15 @@
 All notable changes to this project are documented here.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [1.2.0] — 2026-09-21
+
+### Changed
+- **`/quota` costs about 43% fewer tokens.** The command body was cut from 731 to 311 characters,
+  and the agent is now told not to restate the panel — it is already visible from the tool call.
+  Measured cost per invocation dropped from roughly 680 to 390 tokens.
+- Documented the cost, and the zero-token alternative (`--serve` in the built-in browser pane), in
+  both READMEs.
+
 ## [1.1.0] — 2026-09-21
 
 Cross-agent support, so the plugin is not tied to one editor.

README.md

@@ -137,6 +137,32 @@ You can also skip the command entirely and just ask:
 The bundled skill teaches the agent to fetch the panel and to answer "is it enough" from the
 remaining-requests estimate rather than from the monthly balance.
 
+## Token cost, and the zero-token alternative
+
+A custom command is ultimately a prompt. `/quota` injects its body, the agent runs the script, and
+the panel text passes through the model. Measured, one invocation costs roughly **390 tokens**: about
+100 for the command body, 80 for the tool call, 180 for the panel text, 40 for the reply. The body is
+deliberately short and the agent is told **not to restate the panel** — it is already visible from the
+tool call. (The first version restated it and cost about 680.)
+
+**To spend no tokens at all**, run the panel as a local page and open it in ZCode's built-in browser
+pane:
+
+```bash
+node command-code-usage/scripts/cc-usage.mjs --serve
+# then open http://127.0.0.1:8787/
+```
+
+It refreshes every 30 seconds, shows the same ring gauges, and never touches the model. This is the
+only zero-token option available: ZCode exposes no plugin-contributed in-app widget, and a hook cannot
+display content either — the hook record it renders carries status, duration and name, with no output
+field (verified in `resources/glm/zcode.cjs`).
+
+ZCode *does* support inline shell expansion in command bodies (`` !`cmd` `` or a fenced `!` block),
+which runs locally before the prompt is built. It is not used here: on Windows that shell is
+`cmd.exe`, not bash, so it would only work with a hard-coded script path and would fail hard for
+marketplace installs. Not worth the fragility for the ~80 tokens it would save.
+
 ## How the two useful numbers are derived
 
 **"Room for ≈ N more requests"** = remaining allowance ÷ your average cost per request *this

README.zh-CN.md

@@ -127,6 +127,29 @@ ZCode 在**会话启动时**对命令与技能清单做快照。应用运行期
 
 插件里的技能会教 agent 取面板，并且**用剩余次数估算**而不是月度余额来回答「够不够」。
 
+## Token 成本，以及零成本的替代方式
+
+自定义命令本质上就是一段 prompt。`/quota` 会注入命令正文，agent 运行脚本，面板文本再经过模型。
+实测一次调用约 **390 tokens**：命令正文约 100、工具调用约 80、面板文本约 180、回复约 40。
+正文刻意写得很短，并且明确要求 agent **不要复述面板**——工具调用的输出本来就显示在界面上。
+（第一版会复述，约 680 tokens。）
+
+**想完全不花 token**，就把面板当成本地页面、在 ZCode 内置浏览器面板里打开：
+
+```bash
+node command-code-usage/scripts/cc-usage.mjs --serve
+# 然后打开 http://127.0.0.1:8787/
+```
+
+每 30 秒自动刷新，环形仪表盘和对话里的一样，完全不经过模型。这是目前唯一零 token 的方式：
+ZCode 没有给插件留应用内组件位，hook 也显示不了内容——它渲染的那条记录只有状态、耗时和名称，
+**没有输出字段**（我在 `resources/glm/zcode.cjs` 里核对过）。
+
+ZCode 的命令正文**确实支持内联 shell 展开**（`` !`cmd` `` 或 ```` ```! ```` 围栏块），会在
+构建 prompt 之前本地执行。这里没用它，是因为 **Windows 上那个 shell 是 `cmd.exe` 而不是 bash**，
+只有把脚本路径写死才可用，而走市场安装的路径是动态的、会直接硬失败。为了省那约 80 tokens
+不值得引入这种脆弱性。
+
 ## 两个有用的数是怎么来的
 
 **「还能跑约 N 次」** = 剩余额度 ÷ 本周期均单价。均单价取自**你自己**这个周期的实际用量，

command-code-usage/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "command-code-usage",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "See your Command Code plan usage — 5-hour and weekly rolling windows, monthly credits or balance — right inside the conversation, with a remaining-requests estimate and a burn-rate warning. Requires a Command Code plan.",
   "author": {
     "name": "Jovan1666",

command-code-usage/.zcode-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "command-code-usage",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "See your Command Code plan usage — 5-hour and weekly rolling windows, monthly credits or balance — right inside the conversation, with a remaining-requests estimate and a burn-rate warning. Requires a Command Code plan.",
   "author": {
     "name": "Jovan1666",

command-code-usage/README.md

@@ -133,6 +133,29 @@ Neither runs on its own; they exist for the cases described here.
   parser, so a "my command does not show up" report can come with evidence. It reads files and
   prints a report; it writes nothing.
 
+## Token cost, and the zero-token alternative
+
+A custom command is ultimately a prompt: the body is injected, the agent runs the script, and the
+panel text passes through the model. Measured, one `/quota` costs roughly **390 tokens** — about 100
+for the command body, 80 for the tool call, 180 for the panel text, 40 for the reply. The body is
+deliberately short and the agent is told **not to restate the panel**, because the tool result is
+already visible. (The first version restated it and cost about 680.)
+
+**To spend no tokens at all**, run the panel as a local page and open it in the agent's built-in
+browser pane:
+
+```bash
+node <plugin>/scripts/cc-usage.mjs --serve    # then open http://127.0.0.1:8787/
+```
+
+It refreshes every 30 seconds, shows the same ring gauges, and never touches the model.
+
+ZCode exposes no plugin-contributed in-app widget, and a hook cannot display content either — the
+hook record it renders carries status, duration and name, with no output field. Inline shell expansion
+in command bodies (`!`cmd`` or a fenced `!` block) does exist, but on Windows that shell is `cmd.exe`
+rather than bash, so it would need a hard-coded script path and would fail for marketplace installs.
+Not used here.
+
 ## Troubleshooting
 
 | Symptom | Cause and fix |

command-code-usage/README_CN.md

@@ -122,6 +122,26 @@ key 只会出现在 `Authorization: Bearer` 请求头里。**本插件不写入
 - `scripts/verify-discoverable.cjs` —— 只读诊断工具，复刻了 ZCode 自己的命令解析器，
   这样「我的命令不出现」这类问题可以带着证据来报。它只读文件、打印报告，不写任何东西。
 
+## Token 成本，以及零成本的替代方式
+
+自定义命令本质上是一段 prompt：正文被注入，agent 运行脚本，面板文本再经过模型。实测一次
+`/quota` 约 **390 tokens**——命令正文约 100、工具调用约 80、面板文本约 180、回复约 40。
+正文刻意写得很短，并明确要求 agent **不要复述面板**，因为工具调用的结果本来就显示在界面上。
+（第一版会复述，约 680 tokens。）
+
+**想完全不花 token**，把面板当成本地页面、在 agent 的内置浏览器面板里打开：
+
+```bash
+node <插件目录>/scripts/cc-usage.mjs --serve    # 然后打开 http://127.0.0.1:8787/
+```
+
+每 30 秒自动刷新，环形仪表盘与对话里一致，完全不经过模型。
+
+ZCode 没有给插件留应用内组件位，hook 也显示不了内容——它渲染的记录只有状态、耗时和名称，
+没有输出字段。命令正文的内联 shell 展开（`!`cmd`` 或 ```` ```! ```` 围栏块）确实存在，
+但 Windows 上那个 shell 是 `cmd.exe` 而非 bash，只有写死脚本路径才可用、走市场安装会直接失败，
+所以这里没有采用。
+
 ## 排查
 
 | 现象 | 原因与处理 |

command-code-usage/commands/quota.md

@@ -1,31 +1,13 @@
 ---
-description: 查看 Command Code 额度用到什么程度（5 小时窗口 / 每周窗口 / 余额）
-argument-hint: "[--md | --compact | --json | --verbose | --demo hot]"
+description: 查看 Command Code 额度用量（5 小时窗口 / 每周窗口 / 余额）
+argument-hint: "[--md | --compact | --json | --demo hot]"
 ---
 
-查看 Command Code 额度用量。
-
-执行下面整段（已包含脚本定位，直接整段运行即可）：
-
 ```bash
 CC_SCRIPT="@@CC_USAGE_SCRIPT@@"
-if [ ! -f "$CC_SCRIPT" ]; then
-  for d in "$HOME/.zcode" "$HOME/.claude" "$HOME/.agents" "$HOME/.codex"; do
-    CC_SCRIPT=$(find "$d" -type f -name cc-usage.mjs -print -quit 2>/dev/null)
-    [ -n "$CC_SCRIPT" ] && break
-  done
-fi
-[ -f "$CC_SCRIPT" ] || { echo "找不到 cc-usage.mjs，插件可能未正确安装或已被移动。"; exit 2; }
+[ -f "$CC_SCRIPT" ] || CC_SCRIPT=$(find "$HOME/.zcode" "$HOME/.claude" "$HOME/.agents" "$HOME/.codex" -type f -name cc-usage.mjs -print -quit 2>/dev/null)
 node "$CC_SCRIPT" $ARGUMENTS
 ```
 
-然后把输出**原样放进代码块**给用户：数字、进度条、重置倒计时都不要改写，也不要把面板重排成你自己画的表格。
-
-面板本身已经把结论说完了，正常情况下**不要再加解释**。只有两种情况各补一句：
-
-- 出现 `⚠` 告警行时，说清是哪个窗口、大概什么时候耗尽；
-- 用户问「够不够跑完某个任务」时，引用面板里的「还能跑约 N 次」结合任务规模判断，并提醒该估算基于他本周期实际的模型组合。
-
-若命令报错，把报错原文给用户，并按提示排查（凭证来源见 README）。
-
-用户明确想要图形化大图时才用 `--html --open` 或 `--serve`；不要主动建议打开网页，面板在对话里就能看完。
+面板已经在上面了。**不要再重复输出一遍**——用 1 到 3 行给出结论即可：
+最紧的是哪个窗口、还剩多少、什么时候重置。出现 `⚠` 告警时才多说一句风险。

command-code-usage/commands/usage.md

@@ -1,31 +1,13 @@
 ---
-description: 查看 Command Code 额度用到什么程度（5 小时窗口 / 每周窗口 / 余额）
-argument-hint: "[--md | --compact | --json | --verbose | --demo hot]"
+description: 查看 Command Code 额度用量（5 小时窗口 / 每周窗口 / 余额）
+argument-hint: "[--md | --compact | --json | --demo hot]"
 ---
 
-查看 Command Code 额度用量（`/quota` 的等价写法）。
-
-执行下面整段（已包含脚本定位，直接整段运行即可）：
-
 ```bash
 CC_SCRIPT="@@CC_USAGE_SCRIPT@@"
-if [ ! -f "$CC_SCRIPT" ]; then
-  for d in "$HOME/.zcode" "$HOME/.claude" "$HOME/.agents" "$HOME/.codex"; do
-    CC_SCRIPT=$(find "$d" -type f -name cc-usage.mjs -print -quit 2>/dev/null)
-    [ -n "$CC_SCRIPT" ] && break
-  done
-fi
-[ -f "$CC_SCRIPT" ] || { echo "找不到 cc-usage.mjs，插件可能未正确安装或已被移动。"; exit 2; }
+[ -f "$CC_SCRIPT" ] || CC_SCRIPT=$(find "$HOME/.zcode" "$HOME/.claude" "$HOME/.agents" "$HOME/.codex" -type f -name cc-usage.mjs -print -quit 2>/dev/null)
 node "$CC_SCRIPT" $ARGUMENTS
 ```
 
-然后把输出**原样放进代码块**给用户：数字、进度条、重置倒计时都不要改写，也不要把面板重排成你自己画的表格。
-
-面板本身已经把结论说完了，正常情况下**不要再加解释**。只有两种情况各补一句：
-
-- 出现 `⚠` 告警行时，说清是哪个窗口、大概什么时候耗尽；
-- 用户问「够不够跑完某个任务」时，引用面板里的「还能跑约 N 次」结合任务规模判断，并提醒该估算基于他本周期实际的模型组合。
-
-若命令报错，把报错原文给用户，并按提示排查（凭证来源见 README）。
-
-用户明确想要图形化大图时才用 `--html --open` 或 `--serve`；不要主动建议打开网页，面板在对话里就能看完。
+面板已经在上面了。**不要再重复输出一遍**——用 1 到 3 行给出结论即可：
+最紧的是哪个窗口、还剩多少、什么时候重置。出现 `⚠` 告警时才多说一句风险。

command-code-usage/scripts/cc-usage.mjs

@@ -29,7 +29,7 @@ import path from 'node:path';
 import http from 'node:http';
 import { exec } from 'node:child_process';
 
-const VERSION = '1.1.0';
+const VERSION = '1.2.0';
 const DEFAULT_API_BASE = 'https://api.commandcode.ai';
 const PROVIDER_MATCH = /commandcode\.ai/i;
 

marketplace.json

@@ -14,7 +14,7 @@
         "en": "See your Command Code plan usage — 5-hour and weekly rolling windows, monthly credits or balance — right inside the conversation, with a remaining-requests estimate and a burn-rate warning. Requires a Command Code plan.",
         "zh-CN": "在对话里直接查看 Command Code 套餐用量——5 小时与每周滚动窗口、月度额度或余额，含剩余次数估算与超限预警。需要 Command Code 套餐。"
       },
-      "version": "1.1.0",
+      "version": "1.2.0",
       "author": {
         "name": "Jovan1666",
         "url": "https://github.com/Jovan1666"