@qthinker/opencode-deepseek-search 0.3.0 → 0.4.0

package/src/deepseek.ts

@@ -6,19 +6,31 @@
 // network access.
 
 import { t } from "./i18n/index.ts"
-import type { Language } from "./rpc.ts"
+import type { BalanceRead, Language } from "./rpc.ts"
 
 export const API_BASE = "https://api.deepseek.com"
 export const SEARCH_PATH = "/v1/tools/search"
 export const FETCH_PATH = "/v1/tools/fetch"
+// Account balance endpoint, per the official docs:
+// https://api-docs.deepseek.com/zh-cn/api/get-user-balance
+export const BALANCE_PATH = "/user/balance"
 
 export const SEARCH_TIMEOUT_MS = 15_000
 export const FETCH_TIMEOUT_MS = 30_000
+export const BALANCE_TIMEOUT_MS = 10_000
 const RETRY_DELAY_MS = 1_000
 const RETRY_DELAY_MAX_MS = 5_000
 export const MAX_QUERY_CHARS = 128
+export const MAX_ORI_CHARS = 128
 export const MAX_URL_CHARS = 8192
 
+// Optional request hints forwarded verbatim to the Search API. They are omitted
+// from the body when unset, so the documented API defaults still apply.
+export interface SearchExtras {
+  oriQuestion?: string
+  localization?: string
+}
+
 // Docs: back off and retry on 408/429/5xx only; other 4xx must not be retried.
 const RETRYABLE = new Set([408, 429, 500, 502, 503, 504])
 
@@ -27,6 +39,10 @@ export interface SearchResult {
   title?: string
   content?: string
   time: { published?: number }
+  // Internal quality signals: only formatSearchResults consumes them. They are
+  // stripped from the tool output before it leaves the plugin.
+  authority?: number
+  rerankScore?: number
 }
 
 export interface FetchResult {
@@ -128,7 +144,8 @@ function retryAfterMs(headers: Headers): number {
 
 // ---------- shared HTTP core: timeout, signal passthrough, single retry ----------
 
-export async function postJson(
+async function requestJson(
+  method: "POST" | "GET",
   path: string,
   body: unknown,
   apiKey: string,
@@ -140,10 +157,15 @@ export async function postJson(
   for (let attempt = 1; ; attempt++) {
     const merged = mergeAbort(signal, timeoutMs)
     try {
+      // GET reads a resource, so it sends no body and no content-type header.
+      const headers: Record<string, string> =
+        method === "POST"
+          ? { "content-type": "application/json", authorization: `Bearer ${apiKey}` }
+          : { authorization: `Bearer ${apiKey}` }
       const res = await fetch(`${API_BASE}${path}`, {
-        method: "POST",
-        headers: { "content-type": "application/json", authorization: `Bearer ${apiKey}` },
-        body: JSON.stringify(body),
+        method,
+        headers,
+        body: method === "POST" ? JSON.stringify(body) : undefined,
         signal: merged.signal,
       })
       if (res.ok) {
@@ -179,6 +201,27 @@ export async function postJson(
   }
 }
 
+export function postJson(
+  path: string,
+  body: unknown,
+  apiKey: string,
+  timeoutMs: number,
+  language: Language,
+  signal?: AbortSignal,
+): Promise<unknown> {
+  return requestJson("POST", path, body, apiKey, timeoutMs, language, signal)
+}
+
+export function getJson(
+  path: string,
+  apiKey: string,
+  timeoutMs: number,
+  language: Language,
+  signal?: AbortSignal,
+): Promise<unknown> {
+  return requestJson("GET", path, undefined, apiKey, timeoutMs, language, signal)
+}
+
 // ---------- DeepSeek Search -> WebSearch.Result[] ----------
 
 interface SearchRow {
@@ -187,6 +230,8 @@ interface SearchRow {
   snippet?: unknown
   summary?: unknown
   date?: unknown
+  authority?: unknown
+  rerank_score?: unknown
 }
 
 export function mapSearchResults(data: unknown): SearchResult[] {
@@ -205,19 +250,52 @@ export function mapSearchResults(data: unknown): SearchResult[] {
           ? r.snippet
           : undefined
     const published = typeof r.date === "string" ? Date.parse(r.date) : Number.NaN
-    out.push({
+    const result: SearchResult = {
       url: r.url,
       title: typeof r.title === "string" && r.title.length > 0 ? r.title : undefined,
       content,
       time: Number.isFinite(published) ? { published } : {},
-    })
+    }
+    // `authority` is an integer in -1..4 (-1 means unknown) and `rerank_score`
+    // a finite number in 0..3. Anything else is dropped, and absent keys stay
+    // absent so the output object keeps its exact shape.
+    if (
+      typeof r.authority === "number" &&
+      Number.isInteger(r.authority) &&
+      r.authority >= -1 &&
+      r.authority <= 4
+    ) {
+      result.authority = r.authority
+    }
+    if (
+      typeof r.rerank_score === "number" &&
+      Number.isFinite(r.rerank_score) &&
+      r.rerank_score >= 0 &&
+      r.rerank_score <= 3
+    ) {
+      result.rerankScore = r.rerank_score
+    }
+    out.push(result)
   }
   return out
 }
 
-export function buildSearchBody(query: string, count: number): { query: string; count: number } {
+export function buildSearchBody(
+  query: string,
+  count: number,
+  extras?: SearchExtras,
+): { query: string; count: number; ori_question?: string; localization?: string } {
   // need_content stays false: full page text must never enter search results.
-  return { query, count }
+  // ori_question/localization are omitted entirely when unset or blank, so the
+  // request keeps the documented API defaults.
+  const ori = extras?.oriQuestion?.trim()
+  const localization = extras?.localization?.trim()
+  return {
+    query,
+    count,
+    ...(ori ? { ori_question: ori.slice(0, MAX_ORI_CHARS) } : {}),
+    ...(localization ? { localization } : {}),
+  }
 }
 
 export async function deepseekSearch(
@@ -226,10 +304,11 @@ export async function deepseekSearch(
   count: number,
   language: Language,
   signal?: AbortSignal,
+  extras?: SearchExtras,
 ): Promise<SearchResult[]> {
   const data = await postJson(
     SEARCH_PATH,
-    buildSearchBody(query, count),
+    buildSearchBody(query, count, extras),
     apiKey,
     SEARCH_TIMEOUT_MS,
     language,
@@ -286,6 +365,52 @@ export async function deepseekFetch(
   return mapFetchResponse(data, url, maxChars, language)
 }
 
+// ---------- DeepSeek Balance -> BalanceRead ----------
+
+interface BalanceInfo {
+  currency?: unknown
+  total_balance?: unknown
+  granted_balance?: unknown
+  topped_up_balance?: unknown
+}
+
+function balanceText(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined
+}
+
+// `/user/balance` lists one entry per currency. The plugin bills in CNY, so that
+// entry wins when present; anything else is accepted only as a fallback.
+export function mapBalance(data: unknown): BalanceRead | undefined {
+  if (typeof data !== "object" || data === null) return undefined
+  const raw = data as { is_available?: unknown; balance_infos?: unknown }
+  const isAvailable = raw.is_available
+  if (typeof isAvailable !== "boolean") return undefined
+  const infos = raw.balance_infos
+  if (!Array.isArray(infos) || infos.length === 0) return undefined
+  const rows = infos as Array<BalanceInfo | null | undefined>
+  const entry = rows.find((row) => row?.currency === "CNY") ?? rows[0]
+  const currency = entry?.currency
+  if (currency !== "CNY" && currency !== "USD") return undefined
+  const totalBalance = balanceText(entry?.total_balance)
+  const grantedBalance = balanceText(entry?.granted_balance)
+  const toppedUpBalance = balanceText(entry?.topped_up_balance)
+  if (!totalBalance || !grantedBalance || !toppedUpBalance) return undefined
+  return { isAvailable, currency, totalBalance, grantedBalance, toppedUpBalance }
+}
+
+export async function deepseekBalance(
+  apiKey: string,
+  language: Language,
+  signal?: AbortSignal,
+): Promise<BalanceRead> {
+  const data = await getJson(BALANCE_PATH, apiKey, BALANCE_TIMEOUT_MS, language, signal)
+  const balance = mapBalance(data)
+  // No localizable message on purpose: the balance cache swallows this error, so
+  // it is a diagnostic string rather than user-facing copy.
+  if (!balance) throw new Error("DeepSeek balance response is missing required fields")
+  return balance
+}
+
 export function validateQuery(query: string, language: Language): string | undefined {
   if (query.length === 0) return t(language, "error.validate.queryEmpty")
   if (query.length > MAX_QUERY_CHARS)
@@ -302,10 +427,11 @@ export function formatSearchResults(results: readonly SearchResult[]): string {
   return results
     .map((result) => {
       const title = result.title ?? result.url
+      const authoritative = result.authority !== undefined && result.authority >= 3 ? " [authoritative]" : ""
       const published = result.time.published
         ? `\nPublished: ${new Date(result.time.published).toISOString()}`
         : ""
-      return `## [${title}](${result.url})${published}${result.content ? `\n\n${result.content}` : ""}`
+      return `## [${title}](${result.url})${authoritative}${published}${result.content ? `\n\n${result.content}` : ""}`
     })
     .join("\n\n")
 }

package/src/gui/index.tsx

@@ -40,9 +40,14 @@ export default Plugin.define({
     // `status` takes a required first argument: plain JSON Schema degrades the
     // input type to `unknown`, and the host validates the payload against the
     // method's object schema, so an omitted input is rejected as invalid.
-    async function refresh() {
+    //
+    // `force` asks the server to re-probe the account balance instead of serving
+    // the cache; only the panel's refresh button spends that request. The
+    // `changed` event sends `{}` exactly — an older server rejects unknown input
+    // properties, so a stray `force: false` would break it.
+    async function refresh(force = false) {
       try {
-        const next = readStatus(await rpc.status({}))
+        const next = readStatus(await rpc.status(force ? { force: true } : {}))
         if (next) {
           setStatus(next)
           setError(undefined)
@@ -68,13 +73,14 @@ export default Plugin.define({
       }
     }
 
-    // Mirrors the TUI card: no status or a stale error rereads, otherwise
-    // switch. A missing key still allows releasing the takeover (the shared
-    // model hides the button only where there is genuinely nothing to do).
+    // Mirrors the TUI card: no status or a stale error rereads (a retry is a
+    // user action, so it also re-probes the balance), otherwise switch. A
+    // missing key still allows releasing the takeover (the shared model hides
+    // the button only where there is genuinely nothing to do).
     function toggle() {
       const current = status()
       if (!current || error()) {
-        void refresh()
+        void refresh(true)
         return
       }
       void applyMode(current.mode === "deepseek" ? "native" : "deepseek")
@@ -91,7 +97,7 @@ export default Plugin.define({
           error={error()}
           busy={busy()}
           onToggle={toggle}
-          onRefresh={() => void refresh()}
+          onRefresh={(force) => void refresh(force)}
         />
       ),
     })

package/src/gui/panel.tsx

@@ -4,15 +4,20 @@ import type { JSX } from "solid-js"
 import { For, Show, createMemo, onCleanup, onMount } from "solid-js"
 import { usePlugin } from "@opencode/plugin/gui"
 import { t, type Key } from "../i18n/index.ts"
-import type { SearchStatus } from "../rpc.ts"
-import { sidebarRows, type SidebarRows } from "../status-view.ts"
+import type { BalanceStatus, Language, SearchStatus } from "../rpc.ts"
+import { CURRENCY_SYMBOL, sidebarRows, type SidebarRows } from "../status-view.ts"
 
 export interface DeepSeekPanelProps {
   readonly status: SearchStatus | undefined
   readonly error: string | undefined
   readonly busy: boolean
   readonly onToggle: () => void
-  readonly onRefresh: () => void
+  /**
+   * `force` re-probes the server's balance cache; only a user action (the
+   * refresh button) may set it. The 10s poll timer calls it bare, so the
+   * automatic path keeps sending `{}` and never bypasses the server TTL.
+   */
+  readonly onRefresh: (force?: boolean) => void
 }
 
 type Tone = SidebarRows["tone"]
@@ -67,6 +72,20 @@ function help(action: string, mono: string): JSX.Element {
   )
 }
 
+/**
+ * The balance tooltip carries the granted/topped-up split, because those are the
+ * two numbers behind the total. It is skipped when only one component is
+ * non-zero: there it would just restate the total. The currency code rides
+ * along only for USD, whose `$` needs no introduction.
+ */
+function balanceTip(balance: BalanceStatus, language: Language): string | undefined {
+  const hasGranted = Number.parseFloat(balance.grantedBalance) > 0
+  const hasTopped = Number.parseFloat(balance.toppedUpBalance) > 0
+  if (!hasGranted || !hasTopped) return undefined
+  const text = t(language, "balance.breakdown", { granted: balance.grantedBalance, topped: balance.toppedUpBalance })
+  return balance.currency === "USD" ? `${text} (USD)` : text
+}
+
 export function DeepSeekPanel(props: DeepSeekPanelProps): JSX.Element {
   const ctx = usePlugin()
   // The desktop plugin has no forced locale: the server resolves one and carries
@@ -77,6 +96,18 @@ export function DeepSeekPanel(props: DeepSeekPanelProps): JSX.Element {
   const ink = createMemo(() => INK[ctx.appearance.mode()])
   const mono = () => ctx.appearance.font("mono")
 
+  /**
+   * The account block mirrors the view model's own emit condition (enabled or
+   * native mode), so `rows().lines` ends with the balance row exactly when
+   * this is defined and the usage table must stop before it. The block renders
+   * from the structured payload, not from re-parsing the line.
+   */
+  const balance = createMemo<BalanceStatus | undefined>(() => {
+    const account = props.status?.balance
+    if (account === undefined || (rows().tone !== "on" && rows().tone !== "off")) return undefined
+    return account
+  })
+
   // Cross-half `changed` delivery is the one runtime behaviour this repo cannot
   // verify, so the panel rereads on its own timer while it is mounted — the same
   // fallback the TUI sidebar uses.
@@ -94,14 +125,14 @@ export function DeepSeekPanel(props: DeepSeekPanelProps): JSX.Element {
       }}
     >
       <header style={{ display: "flex", "align-items": "flex-start", gap: "8px" }}>
-        <span aria-hidden="true" style={{ "flex-shrink": 0, "font-size": "10px", "line-height": "20px", "font-weight": 700, color: ink()[rows().tone] }}>
+        <span aria-hidden="true" style={{ "flex-shrink": 0, "font-size": "12px", "line-height": "20px", width: "12px", "text-align": "center", "font-weight": 700, color: ink()[rows().tone] }}>
           {GLYPH[rows().tone]}
         </span>
         <h2 aria-live="polite" style={{ flex: 1, "min-width": 0, margin: 0, "font-size": "13px", "font-weight": 600, "line-height": "20px", "overflow-wrap": "anywhere" }}>
           {headline(rows().title, ink()[rows().tone])}
         </h2>
         <ctx.ui.Tooltip value={t(language(), "panel.tooltip.refresh")} placement="bottom">
-          <ctx.ui.IconButton icon="refresh" label={t(language(), "panel.tooltip.refresh")} size="small" onClick={props.onRefresh} />
+          <ctx.ui.IconButton icon="refresh" label={t(language(), "panel.tooltip.refresh")} size="small" onClick={() => props.onRefresh(true)} />
         </ctx.ui.Tooltip>
       </header>
 
@@ -116,31 +147,66 @@ export function DeepSeekPanel(props: DeepSeekPanelProps): JSX.Element {
         )
       ) : (
         <dl style={{ margin: "16px 0 0", "border-top": `1px solid ${ink().rule}`, "border-bottom": `1px solid ${ink().rule}` }}>
-          <For each={rows().lines}>
+          <For each={balance() !== undefined ? rows().lines.slice(0, -1) : rows().lines}>
             {(line, index) => {
               const parts = splitLine(line)
               return (
                 <div style={{ display: "flex", "align-items": "baseline", gap: "12px", padding: "10px 0", "border-top": index() > 0 ? `1px solid ${ink().rule}` : undefined }}>
-                  <dt style={{ "flex-shrink": 0, "font-size": "11px", "letter-spacing": "0.08em", "line-height": "1.9", opacity: 0.62 }}>
+                  <dt style={{ "flex-shrink": 0, "font-size": "11px", "letter-spacing": /^[\x20-\x7E]+$/.test(parts.label) ? "0.08em" : undefined, "line-height": "1.9", opacity: 0.62 }}>
                     {parts.label}
                   </dt>
                   <dd style={{
                     margin: 0, "margin-left": "auto", "min-width": 0, display: "flex", "flex-wrap": "wrap", "justify-content": "flex-end",
-                    "column-gap": "6px", "row-gap": "2px", "font-family": mono(), "font-size": "13px", "line-height": "1.55",
+                    "column-gap": "10px", "row-gap": "2px", "font-family": mono(), "font-size": "13px", "line-height": "1.55",
                     "font-variant-numeric": "tabular-nums", "text-align": "right",
                   }}>
                     <For each={parts.chunks}>
-                      {(chunk, i) => (
-                        <span style={{ "min-width": 0, "overflow-wrap": "anywhere", "font-weight": chunk.startsWith("¥") ? 500 : 400, opacity: chunk.startsWith("¥") ? 1 : 0.8 }}>
-                          {chunk}{i() < parts.chunks.length - 1 ? " ·" : ""}
-                        </span>
-                      )}
+                      {(chunk) => {
+                        // A money chunk must never wrap apart from its digits, and
+                        // it is the only chunk that reads at full weight.
+                        const money = /^[¥$]/.test(chunk)
+                        return (
+                          <span style={{ "min-width": 0, "overflow-wrap": "anywhere", "font-weight": money ? 500 : 400, opacity: money ? 1 : 0.8, "flex-shrink": money ? 0 : undefined }}>
+                            {chunk}
+                          </span>
+                        )
+                      }}
                     </For>
                   </dd>
                 </div>
               )
             }}
           </For>
+          {/* The account block closes the table like a receipt: the usage rows
+              above are local estimates for this machine, the balance under them
+              is the authoritative amount still on the account. */}
+          <Show when={balance()} keyed>
+            {(account) => {
+              const label = t(language(), "balance.label")
+              const tip = balanceTip(account, language())
+              const amount = (
+                <dd style={{
+                  margin: 0, "margin-left": "auto", "font-family": mono(), "font-size": "14px", "line-height": "1.55",
+                  "font-variant-numeric": "tabular-nums", "text-align": "right", "font-weight": 500, "flex-shrink": 0,
+                  color: account.isAvailable ? undefined : ink().warn,
+                }}>
+                  {CURRENCY_SYMBOL[account.currency] ?? ""}{account.totalBalance}
+                </dd>
+              )
+              return (
+                <div style={{ display: "flex", "align-items": "baseline", gap: "12px", padding: "10px 0 4px", "border-top": `1px solid ${ink().rule}` }}>
+                  <dt style={{ "flex-shrink": 0, "font-size": "11px", "letter-spacing": /^[\x20-\x7E]+$/.test(label) ? "0.08em" : undefined, "line-height": "1.9", opacity: 0.62 }}>
+                    {label}
+                  </dt>
+                  {tip !== undefined ? (
+                    <ctx.ui.Tooltip value={tip} placement="bottom">{amount}</ctx.ui.Tooltip>
+                  ) : (
+                    amount
+                  )}
+                </div>
+              )
+            }}
+          </Show>
         </dl>
       )}
 

package/src/i18n/en.ts

@@ -85,6 +85,10 @@ export const en = {
   "usage.label.total": "Total",
   "usage.summary.line": "Search {search} · Fetch {fetch} · empty/failed {skipped} · {cost}",
 
+  // ---------- account balance (the card row and the desktop tooltip) ----------
+  "balance.label": "Balance",
+  "balance.breakdown": "Granted {granted} · Topped up {topped}",
+
   // ---------- errors ----------
   "error.missingKey":
     "DeepSeek API key is not configured. Set the DEEPSEEK_API_KEY environment variable " +
@@ -131,17 +135,32 @@ export type Messages = Record<Key, string>
  * Usage-row ladder, richest first. Each entry is a complete row, so nothing is
  * ever left dangling and no number is ever cut from its unit. `{label}` is the
  * localized period label; `Search`/`Fetch` stay English in every language.
+ *
+ * Order is by what the row is worth, then by width, so it runs strictly
+ * descending (36/33/25/17/11 columns for a typical fixture). The amount
+ * outranks the words and the counters: the old ladder kept a wider words-only
+ * row and hid the cost until 36 columns, which is the number this card exists
+ * for, so those two rungs are gone. The amount-only row (which carries no count
+ * at all) is composed in `status-view.ts` and tried just before the last rung —
+ * an amount is worth more than a lone counter, but the ladder itself only holds
+ * rows that carry counts.
  */
 export const enUsageForms: readonly string[] = [
   "{label}  Search {search}  Fetch {fetch}  {cost}",
   "{label} Search {search} Fetch {fetch} {cost}",
-  "{label}  Search {search}  Fetch {fetch}",
-  "{label} Search {search} Fetch {fetch}",
   "{label}  {search}S  {fetch}F  {cost}",
   "{label}  {search}S  {fetch}F",
-  "{label}  {search}S",
+  "{label} {search}S",
 ]
 
+/**
+ * Balance-row ladder, verbose first: the terminal takes the compact form when
+ * the verbose one does not fit, a surface with an unbounded budget (the desktop)
+ * always reads the first. `{amount}` already carries the currency symbol — the
+ * view model composes it, because only it knows the currency code.
+ */
+export const enBalanceForms: readonly string[] = ["Balance {amount}", "Bal. {amount}"]
+
 /** Missing-key hint ladder, richest first. The env var name is always present. */
 export const enHintForms: readonly string[] = [
   "Set DEEPSEEK_API_KEY and restart",

package/src/i18n/index.ts

@@ -6,9 +6,9 @@
 // plugin or host imports, so every runtime can load this module.
 
 import { isLanguage, type Language } from "../rpc.ts"
-import { en, enHintForms, enUsageForms, type Key, type Messages } from "./en.ts"
-import { ja, jaHintForms, jaUsageForms } from "./ja.ts"
-import { zh, zhHintForms, zhUsageForms } from "./zh.ts"
+import { en, enBalanceForms, enHintForms, enUsageForms, type Key, type Messages } from "./en.ts"
+import { ja, jaBalanceForms, jaHintForms, jaUsageForms } from "./ja.ts"
+import { zh, zhBalanceForms, zhHintForms, zhUsageForms } from "./zh.ts"
 
 export type { Key, Messages }
 
@@ -19,12 +19,14 @@ export interface LocalePack {
   readonly usageForms: readonly string[]
   /** Missing-key hint ladder, richest first. */
   readonly hintForms: readonly string[]
+  /** Balance-row ladder, verbose first; `{amount}` carries the currency symbol. */
+  readonly balanceForms: readonly string[]
 }
 
 const PACKS: Readonly<Record<Language, LocalePack>> = {
-  en: { messages: en, usageForms: enUsageForms, hintForms: enHintForms },
-  ja: { messages: ja, usageForms: jaUsageForms, hintForms: jaHintForms },
-  "zh-CN": { messages: zh, usageForms: zhUsageForms, hintForms: zhHintForms },
+  en: { messages: en, usageForms: enUsageForms, hintForms: enHintForms, balanceForms: enBalanceForms },
+  ja: { messages: ja, usageForms: jaUsageForms, hintForms: jaHintForms, balanceForms: jaBalanceForms },
+  "zh-CN": { messages: zh, usageForms: zhUsageForms, hintForms: zhHintForms, balanceForms: zhBalanceForms },
 }
 
 export function pack(language: Language): LocalePack {

package/src/i18n/ja.ts

@@ -83,6 +83,10 @@ export const ja = {
   "usage.label.total": "合計",
   "usage.summary.line": "検索 {search} · 取得 {fetch} · 空/失敗 {skipped} · {cost}",
 
+  // ---------- アカウント残高（カードの行とデスクトップのツールチップ） ----------
+  "balance.label": "残高",
+  "balance.breakdown": "付与 {granted} · チャージ {topped}",
+
   // ---------- エラー ----------
   "error.missingKey":
     "DeepSeek APIキーが未設定です。環境変数 DEEPSEEK_API_KEY を設定してください" +
@@ -118,17 +122,22 @@ export const ja = {
   "error.fetch.truncated": "[DeepSeek Fetch 切り詰め] 元の本文は {raw} 文字で、上限 {max} 文字を超えています。先頭 {max} 文字のみ保持しました。",
 } satisfies Messages
 
-/** 使用量行の階段：完全な行から最も短い行まで。各段は単体で完結する。 */
+/**
+ * 使用量行の階段：価値の高い順、同じ価値なら幅の広い順。各段は単体で完結する。
+ * 金額は語や回数より上位なので、金額を含まない「語だけ」の段は廃止した。金額だけの
+ * 行は件数を持たないため status-view.ts 側で組み立て、最後の 1 段の直前に試す。
+ */
 export const jaUsageForms: readonly string[] = [
   "{label}  Search {search}  Fetch {fetch}  {cost}",
   "{label} Search {search} Fetch {fetch} {cost}",
-  "{label}  Search {search}  Fetch {fetch}",
-  "{label} Search {search} Fetch {fetch}",
   "{label}  {search}S  {fetch}F  {cost}",
   "{label}  {search}S  {fetch}F",
-  "{label}  {search}S",
+  "{label} {search}S",
 ]
 
+/** 残高行の階段：完全な形が先。`{amount}` は通貨記号込み。 */
+export const jaBalanceForms: readonly string[] = ["残高 {amount}"]
+
 /** APIキー未設定のヒント階段：最後の段でも何を設定するかは残る。 */
 export const jaHintForms: readonly string[] = [
   "DEEPSEEK_API_KEY を設定して再起動",

package/src/i18n/zh.ts

@@ -81,6 +81,10 @@ export const zh = {
   "usage.label.total": "累计",
   "usage.summary.line": "搜索 {search} · 抓取 {fetch} · 空/失 {skipped} · {cost}",
 
+  // ---------- 账户余额（卡片行与桌面端浮动提示） ----------
+  "balance.label": "余额",
+  "balance.breakdown": "赠金 {granted} · 充值 {topped}",
+
   // ---------- 错误信息 ----------
   "error.missingKey":
     "未配置 DeepSeek API Key：请设置环境变量 DEEPSEEK_API_KEY" +
@@ -113,17 +117,23 @@ export const zh = {
   "error.fetch.truncated": "[DeepSeek Fetch 截断提示] 原文共 {raw} 字符，超出上限 {max}，此处仅保留前 {max} 字符。",
 } satisfies Messages
 
-/** 用量行阶梯：从最完整到最紧凑；每一条都是完整的一行。 */
+/**
+ * 用量行阶梯：按价值从高到低排列，同等价值再按宽度从宽到窄；每一条都是完整的一行。
+ * 金额优先于文字与计数，因此删掉了不带金额的“纯文字”档——旧阶梯会为了更宽的
+ * 纯文字行而把金额藏到 36 列。只带金额的一行不含计数，改由 status-view.ts 组装，
+ * 并在最后一档之前尝试。
+ */
 export const zhUsageForms: readonly string[] = [
   "{label}  Search {search}  Fetch {fetch}  {cost}",
   "{label} Search {search} Fetch {fetch} {cost}",
-  "{label}  Search {search}  Fetch {fetch}",
-  "{label} Search {search} Fetch {fetch}",
   "{label}  {search}S  {fetch}F  {cost}",
   "{label}  {search}S  {fetch}F",
-  "{label}  {search}S",
+  "{label} {search}S",
 ]
 
+/** 余额行阶梯：完整写法在前；`{amount}` 已含货币符号。 */
+export const zhBalanceForms: readonly string[] = ["余额 {amount}"]
+
 /** 缺 key 提示阶梯：最后一档仍然指明要设置什么。 */
 export const zhHintForms: readonly string[] = [
   "设置 DEEPSEEK_API_KEY 后重启",