@qthinker/opencode-deepseek-search 0.2.1 → 0.3.2

package/src/index.ts

@@ -16,6 +16,7 @@ import { Plugin } from "@opencode/plugin"
 import type { Result as ToolResult, ToolContext } from "@opencode/plugin/promise/tool"
 import type { RpcRegistration } from "@opencode/plugin/promise/rpc"
 import {
+  deepseekBalance,
   deepseekFetch,
   deepseekSearch,
   formatSearchResults,
@@ -24,7 +25,8 @@ import {
   validateUrl,
   type SearchResult,
 } from "./deepseek.ts"
-import { DeepSeekRpc, type ModeSwitchResult, type SearchStatus } from "./rpc.ts"
+import { resolveLanguage, t } from "./i18n/index.ts"
+import { DeepSeekRpc, type BalanceRead, type ModeSwitchResult, type SearchStatus } from "./rpc.ts"
 import {
   USAGE_KEY,
   applyTally,
@@ -56,11 +58,13 @@ const SEARCH_TOOL_DESCRIPTION =
   "Search the web using DeepSeek Search. Use this for current information beyond knowledge cutoff." +
   `\n\nThe current year is ${new Date().getFullYear()}. Use this year when searching for recent information or current events.`
 
-function readModeAction(input: unknown): ModeAction {
+// Pure parser: the caller decides how to surface an invalid value (tool error
+// vs. RPC result), so the message can be localized at that call site.
+function readModeAction(input: unknown): { action: ModeAction } | { invalid: string } {
   const raw = (input as { mode?: unknown } | undefined)?.mode
-  if (raw === undefined || raw === null || raw === "") return "status"
-  if (raw === "status" || raw === "deepseek" || raw === "native" || raw === "config") return raw
-  throw new Error(`mode 只能是 status / deepseek / native / config，收到：${String(raw)}`)
+  if (raw === undefined || raw === null || raw === "") return { action: "status" }
+  if (raw === "status" || raw === "deepseek" || raw === "native" || raw === "config") return { action: raw }
+  return { invalid: String(raw) }
 }
 
 
@@ -95,6 +99,18 @@ export default Plugin.define({
   id: "deepseek-search",
   async setup(ctx) {
     const opt = (ctx.options ?? {}) as Record<string, unknown>
+    // Resolved once per setup: every tool output and the RPC status payload use
+    // this single language, so surfaces can never disagree.
+    const pick = resolveLanguage(opt.language, {
+      LC_ALL: readEnvValue("LC_ALL"),
+      LANG: readEnvValue("LANG"),
+    })
+    const language = pick.language
+    if (pick.problem !== undefined)
+      console.error(
+        `[deepseek-search] invalid language option ${JSON.stringify(pick.problem)}; ` +
+          `valid values: en / ja / zh-CN. Using ${language}.`,
+      )
     const configMode: Mode = str(opt.mode) === "native" ? "native" : "deepseek"
     // Precedence: a persisted `deepseek_mode` switch wins over the config file
     // until it is cleared with `mode: "config"`.
@@ -143,10 +159,10 @@ export default Plugin.define({
     }
 
     const runSearch = async (query: string, signal: AbortSignal): Promise<SearchResult[]> => {
-      const problem = validateQuery(query)
+      const problem = validateQuery(query, language)
       if (problem) throw new Error(problem)
       try {
-        const results = await deepseekSearch(query, apiKey, count, signal)
+        const results = await deepseekSearch(query, apiKey, count, language, signal)
         tally(results.length > 0 ? "search" : "empty")
         return results
       } catch (e) {
@@ -176,7 +192,7 @@ export default Plugin.define({
 
     const deepseekSearchExecute = async (input: unknown, context: ToolContext): Promise<ToolResult> => {
       const query = readQuery(input)
-      const problem = validateQuery(query)
+      const problem = validateQuery(query, language)
       if (problem) throw new Error(problem)
       await ctx.permission.assert({
         sessionID: context.sessionID,
@@ -217,38 +233,38 @@ export default Plugin.define({
       return true
     }
 
-    const describeMode = (): string =>
-      `当前搜索后端: ${mode}（来源: ${overrideMode ? "deepseek_mode 开关，已持久化" : "配置文件 options.mode"}）` +
-      (mode === "deepseek"
-        ? searchToolPatched
-          ? " · 内置 websearch 已由 DeepSeek 接管"
-          : " · 未找到内置 websearch 工具，实际未能接管"
-        : " · 内置 websearch 保持原生")
+    const describeMode = (): string => {
+      const source = overrideMode ? t(language, "mode.source.override") : t(language, "mode.source.config")
+      const suffix =
+        mode === "deepseek"
+          ? searchToolPatched
+            ? t(language, "mode.suffix.patched")
+            : t(language, "mode.suffix.notPatched")
+          : t(language, "mode.suffix.native")
+      return t(language, "mode.report", { mode, source, suffix })
+    }
 
     // Shared by the `deepseek_mode` tool and the RPC `setMode` method. The
     // returned strings are the tool's documented output, word for word.
     const switchMode = async (action: Exclude<ModeAction, "status">): Promise<string> => {
       if (!pristine) {
-        return (
-          `未找到内置 ${SEARCH_TOOL} 工具，无法在运行时切换。` +
-          `请改用配置文件把 options.mode 设为 "${action === "config" ? configMode : action}"。`
-        )
+        return t(language, "mode.notFound", {
+          tool: SEARCH_TOOL,
+          mode: action === "config" ? configMode : action,
+        })
       }
       if (action === "config") {
         await ctx.storage.remove(MODE_KEY)
         overrideMode = undefined
         await applySearchMode(configMode)
         notifyChanged()
-        return `${describeMode()}\n\n已清除持久化开关，回到配置文件设置（${configMode}）。`
+        return `${describeMode()}\n\n${t(language, "mode.configCleared", { mode: configMode })}`
       }
       await ctx.storage.set(MODE_KEY, action)
       overrideMode = action
       await applySearchMode(action)
       notifyChanged()
-      return (
-        `${describeMode()}\n\n已持久化：重启 OpenCode 后仍为 ${action}。` +
-        '要恢复配置文件设置，调用 deepseek_mode 并传 mode: "config"。'
-      )
+      return `${describeMode()}\n\n${t(language, "mode.persisted", { mode: action })}`
     }
 
     // ---------- tools ----------
@@ -289,11 +305,11 @@ export default Plugin.define({
         },
         execute: async (input, context) => {
           const url = String((input as { url?: unknown } | undefined)?.url ?? "").trim()
-          const problem = validateUrl(url)
+          const problem = validateUrl(url, language)
           if (problem) throw new Error(problem)
           try {
-            await context.progress({ status: `DeepSeek Fetch 抓取中: ${url}` })
-            const result = await deepseekFetch(url, apiKey, fetchMaxChars, context.signal)
+            await context.progress({ status: t(language, "progress.fetch", { url }) })
+            const result = await deepseekFetch(url, apiKey, fetchMaxChars, language, context.signal)
             tally(result.empty ? "empty" : "fetch")
             return {
               content: result.markdown,
@@ -322,10 +338,10 @@ export default Plugin.define({
         execute: async (input) => {
           const reset = Boolean((input as { reset?: unknown } | undefined)?.reset)
           const report = await withLedger(async (ledger) => {
-            const text = formatUsage(ledger, pricePerThousand, mode)
+            const text = formatUsage(ledger, pricePerThousand, mode, language)
             if (!reset) return text
             await ctx.storage.set(USAGE_KEY, emptyLedger())
-            return `${text}\n\n已清零本地统计。`
+            return `${text}\n\n${t(language, "usage.reset")}`
           })
           return { content: report }
         },
@@ -351,20 +367,61 @@ export default Plugin.define({
           additionalProperties: false,
         },
         execute: async (input) => {
-          const action = readModeAction(input)
+          const parsed = readModeAction(input)
+          if ("invalid" in parsed) throw new Error(t(language, "mode.invalid", { raw: parsed.invalid }))
+          const action = parsed.action
           if (action === "status") return { content: describeMode() }
           return { content: await switchMode(action) }
         },
       })
     })
 
+    // ---------- account balance cache ----------
+    // The sidebars poll `status`, so the balance is cached for a minute: at most
+    // one upstream probe per TTL, shared by every caller. Failures keep the last
+    // good snapshot and back off instead of retrying on every poll.
+    const BALANCE_TTL_MS = 60_000
+    let balanceCache: { value: BalanceRead; at: number } | undefined
+    let balanceInFlight: Promise<void> | undefined
+    let lastBalanceAttemptAt = 0
+    // Never rejects: the balance is decoration on `status`, not a feature that
+    // may break it, so every failure is swallowed here.
+    const refreshBalance = (force: boolean): Promise<void> => {
+      if (!apiKey) return Promise.resolve()
+      if (balanceInFlight) return balanceInFlight
+      const startedAt = Date.now()
+      if (!force) {
+        if (balanceCache && startedAt - balanceCache.at < BALANCE_TTL_MS) return Promise.resolve()
+        if (startedAt - lastBalanceAttemptAt < BALANCE_TTL_MS) return Promise.resolve()
+      }
+      lastBalanceAttemptAt = startedAt
+      const run = (async (): Promise<void> => {
+        try {
+          const value = await deepseekBalance(apiKey, language)
+          balanceCache = { value, at: Date.now() }
+          notifyChanged()
+        } catch {
+          /* keep the previous snapshot */
+        } finally {
+          balanceInFlight = undefined
+        }
+      })()
+      balanceInFlight = run
+      return run
+    }
+
     // ---------- RPC contract (TUI / desktop sidebars) ----------
     // Both sidebars read `status` and call `setMode`; nothing else crosses the
     // process boundary, so the plugin's state stays the single source of truth.
     rpcRegistration = await ctx.rpc.register(DeepSeekRpc, {
       // Reads through `withLedger` so it observes the same serialized chain.
-      status: async (): Promise<SearchStatus> =>
-        withLedger((ledger): SearchStatus => {
+      status: async (input: unknown): Promise<SearchStatus> => {
+        // A manual refresh (the sidebar's refresh button) may ask for a fresh
+        // probe; timer paths send `{}` so old servers still accept the input.
+        const force = (input as { force?: unknown } | undefined)?.force === true
+        // Kicked, not awaited: `status` must stay fast even when the probe hangs.
+        void refreshBalance(force)
+        return withLedger((ledger): SearchStatus => {
           const todayKey = dayKey()
           return {
             mode,
@@ -372,7 +429,8 @@ export default Plugin.define({
             patched: searchToolPatched,
             hasKey: Boolean(apiKey),
             pricePerThousand,
-            ...usageSummaryLines(ledger, todayKey),
+            language,
+            ...usageSummaryLines(ledger, language, todayKey),
             // Same ledger read as the strings above, exposed as numbers so the
             // sidebars can lay them out for their own width.
             counts: {
@@ -380,17 +438,20 @@ export default Plugin.define({
               month: sumDays(ledger, (k) => k.startsWith(todayKey.slice(0, 7))),
               total: sumDays(ledger, () => true),
             },
+            // Absent until the first successful probe; `fetchedAt` is stamped by
+            // the cache, so clients can render staleness.
+            balance: balanceCache ? { ...balanceCache.value, fetchedAt: balanceCache.at } : undefined,
           }
-        }),
+        })
+      },
       // The input is plain JSON Schema, hence `unknown`: report, never throw.
       setMode: async (input: unknown): Promise<ModeSwitchResult> => {
-        let action: ModeAction
-        try {
-          action = readModeAction(input)
-        } catch (e) {
-          return { ok: false, mode, message: e instanceof Error ? e.message : String(e) }
+        const parsed = readModeAction(input)
+        if ("invalid" in parsed) {
+          return { ok: false, mode, message: t(language, "mode.invalid", { raw: parsed.invalid }) }
         }
-        if (action === "status") return { ok: false, mode, message: "status 只读取当前模式，不做切换。" }
+        const action = parsed.action
+        if (action === "status") return { ok: false, mode, message: t(language, "mode.statusOnly") }
         const message = await switchMode(action)
         // `!pristine` means switchMode could not apply the change; its message says why.
         return { ok: Boolean(pristine), mode, message }
@@ -403,16 +464,16 @@ export default Plugin.define({
         `apiKey=${apiKey ? "present" : "MISSING"} count=${count} ` +
         `searchTool=${searchToolPatched ? "deepseek" : "untouched"}`,
     )
-    if (!apiKey) console.error(`[deepseek-search] ${missingKeyMessage()}`)
+    if (!apiKey) console.error(`[deepseek-search] ${missingKeyMessage("en")}`)
     if (overrideMode && overrideMode !== configMode)
       console.error(
-        `[deepseek-search] 注意：存在持久化开关 mode=${overrideMode}，已覆盖配置文件里的 ${configMode}；` +
-          `调用 deepseek_mode 传 "config" 可清除。`,
+        `[deepseek-search] note: a persisted mode=${overrideMode} overrides the config file's ${configMode}; ` +
+          `call deepseek_mode with "config" to clear it.`,
       )
     if (mode === "deepseek" && !searchToolPatched)
       console.error(
-        `[deepseek-search] 警告：未找到内置 ${SEARCH_TOOL} 工具，搜索仍走内置后端。` +
-          `可在 opencode.jsonc 设置 "websearch": { "provider": "${PROVIDER_ID}" } 强制路由。`,
+        `[deepseek-search] warning: built-in ${SEARCH_TOOL} tool not found; search still uses the built-in backend. ` +
+          `Set "websearch": { "provider": "${PROVIDER_ID}" } in opencode.jsonc to force the route.`,
       )
   },
 })

package/src/rpc.ts

@@ -13,6 +13,17 @@ import type { Rpc } from "@opencode/plugin/rpc"
 
 export const DEEPSEEK_RPC_ID = "deepseek-search"
 
+/**
+ * UI languages the plugin ships. The server resolves one of them once and puts
+ * it in `status`, so the tools and both sidebars always speak the same language.
+ */
+export type Language = "en" | "ja" | "zh-CN"
+export const LANGUAGE_VALUES = ["en", "ja", "zh-CN"] as const
+
+export function isLanguage(value: unknown): value is Language {
+  return value === "en" || value === "ja" || value === "zh-CN"
+}
+
 // Shared by the today/month/total slots of `status.counts`.
 const USAGE_COUNTS_SCHEMA = {
   type: "object",
@@ -27,11 +38,36 @@ const USAGE_COUNTS_SCHEMA = {
   additionalProperties: false,
 } as const
 
+// Account balance snapshot in `status.balance`. `currency` deliberately has no
+// enum: a value the server could not normalize must not fail the whole payload
+// at output-schema validation time.
+const BALANCE_SCHEMA = {
+  type: "object",
+  properties: {
+    isAvailable: { type: "boolean" },
+    currency: { type: "string" },
+    totalBalance: { type: "string" },
+    grantedBalance: { type: "string" },
+    toppedUpBalance: { type: "string" },
+    fetchedAt: { type: "number" },
+  },
+  required: ["isAvailable", "currency", "totalBalance", "grantedBalance", "toppedUpBalance", "fetchedAt"],
+  additionalProperties: false,
+} as const
+
 export const DeepSeekRpc = {
   id: DEEPSEEK_RPC_ID,
   methods: {
     status: {
-      input: { type: "object", properties: {}, additionalProperties: false },
+      input: {
+        type: "object",
+        properties: {
+          // Only a manual refresh sends `{ force: true }`; timer paths MUST send
+          // `{}`, because older servers reject unknown input properties.
+          force: { type: "boolean" },
+        },
+        additionalProperties: false,
+      },
       output: {
         type: "object",
         properties: {
@@ -43,6 +79,9 @@ export const DeepSeekRpc = {
           today: { type: "string" },
           month: { type: "string" },
           total: { type: "string" },
+          // Declared but not required: older servers omit it, and readStatus
+          // falls back to English without failing the rest of the payload.
+          language: { type: "string", enum: ["en", "ja", "zh-CN"] },
           counts: {
             type: "object",
             properties: {
@@ -53,6 +92,9 @@ export const DeepSeekRpc = {
             required: ["today", "month", "total"],
             additionalProperties: false,
           },
+          // Optional like `counts`: absent while the first probe is in flight, on
+          // servers without the endpoint, or when the API key is missing.
+          balance: BALANCE_SCHEMA,
         },
         required: ["mode", "source", "patched", "hasKey", "pricePerThousand", "today", "month", "total"],
         additionalProperties: false,
@@ -93,6 +135,24 @@ export interface UsageCounts {
   costMicro: number
 }
 
+/**
+ * DeepSeek account balance as reported by `GET /user/balance`.
+ *
+ * `fetchedAt` is epoch milliseconds attached by the server when it caches the
+ * snapshot, so sidebars can show staleness without trusting client clocks.
+ */
+export interface BalanceStatus {
+  isAvailable: boolean
+  currency: string
+  totalBalance: string
+  grantedBalance: string
+  toppedUpBalance: string
+  fetchedAt: number
+}
+
+/** The wire shape of a balance probe, before the cache stamps `fetchedAt`. */
+export type BalanceRead = Omit<BalanceStatus, "fetchedAt">
+
 export interface SearchStatus {
   mode: "deepseek" | "native"
   source: "override" | "config"
@@ -102,8 +162,16 @@ export interface SearchStatus {
   today: string
   month: string
   total: string
+  /**
+   * UI language resolved by the server. Required by this interface: `readStatus`
+   * always fills it (English when the server is older or sends garbage), so
+   * every surface has one value to render with.
+   */
+  language: Language
   /** Structured counters, so each surface can format for its own width. Optional for older servers. */
   counts?: { today: UsageCounts; month: UsageCounts; total: UsageCounts }
+  /** Last cached balance probe. Absent until the first successful fetch. */
+  balance?: BalanceStatus
 }
 
 export interface ModeSwitchResult {
@@ -131,16 +199,41 @@ function readUsageCounts(value: unknown): UsageCounts | undefined {
   return { search, fetch, empty, failed, costMicro } as UsageCounts
 }
 
+/** Strict read of a cached balance snapshot: all six fields, currency normalized. */
+function readBalance(value: unknown): BalanceStatus | undefined {
+  if (!isRecord(value)) return undefined
+  const { isAvailable, currency, totalBalance, grantedBalance, toppedUpBalance, fetchedAt } = value
+  if (typeof isAvailable !== "boolean") return undefined
+  if (currency !== "CNY" && currency !== "USD") return undefined
+  for (const text of [totalBalance, grantedBalance, toppedUpBalance]) {
+    if (typeof text !== "string" || text.length === 0) return undefined
+  }
+  if (typeof fetchedAt !== "number" || !Number.isFinite(fetchedAt) || fetchedAt < 0) return undefined
+  return { isAvailable, currency, totalBalance, grantedBalance, toppedUpBalance, fetchedAt } as BalanceStatus
+}
+
 /** Defensive read of an RPC `status` result. Never throws. */
 export function readStatus(raw: unknown): SearchStatus | undefined {
   if (!isRecord(raw)) return undefined
-  const { mode, source, patched, hasKey, pricePerThousand, today, month, total, counts } = raw
+  const { mode, source, patched, hasKey, pricePerThousand, today, month, total, language, counts, balance } = raw
   if (!isMode(mode)) return undefined
   if (source !== "override" && source !== "config") return undefined
   if (typeof patched !== "boolean" || typeof hasKey !== "boolean") return undefined
   if (typeof pricePerThousand !== "number" || !Number.isFinite(pricePerThousand)) return undefined
   if (typeof today !== "string" || typeof month !== "string" || typeof total !== "string") return undefined
-  const status: SearchStatus = { mode, source, patched, hasKey, pricePerThousand, today, month, total }
+  const status: SearchStatus = {
+    mode,
+    source,
+    patched,
+    hasKey,
+    pricePerThousand,
+    today,
+    month,
+    total,
+    // An older server has no language; a malformed one is not worth failing the
+    // whole payload over. Both fall back to English.
+    language: isLanguage(language) ? language : "en",
+  }
   // Old servers omit `counts`; a malformed triple is dropped without failing the rest.
   if (isRecord(counts)) {
     const todayCounts = readUsageCounts(counts.today)
@@ -148,6 +241,10 @@ export function readStatus(raw: unknown): SearchStatus | undefined {
     const totalCounts = readUsageCounts(counts.total)
     if (todayCounts && monthCounts && totalCounts) status.counts = { today: todayCounts, month: monthCounts, total: totalCounts }
   }
+  // A missing balance stays absent (no probe yet, no key, older server); a
+  // malformed one is dropped without failing the rest of the payload.
+  const balanceStatus = readBalance(balance)
+  if (balanceStatus) status.balance = balanceStatus
   return status
 }