dsh-plugin-billing-card 0.1.0 → 0.2.0

package/README.md

@@ -2,19 +2,27 @@
 
 在 DeepSeek Harness 的输入框下方实时显示**当前会话**的 token 用量与估算费用，按模型分项统计，
 默认内置 DeepSeek 官方价格（含**峰谷分时计价**），并保留完整的扩展能力：价格表、峰谷规则、
-其他模型/提供商都可以在插件配置里追加，不需要改代码。
+其他模型/提供商都可以在插件配置里追加，不需要改代码。0.2.0 起同时统计 **DeepSeek 官方网页搜索 /
+抓取 API** 的调用次数与按次费用（Search 服务端调用免费至 2026-11-01 00:00，之后按每 1000 次
+5 元估算）。
+
+> npm：[`dsh-plugin-billing-card@0.2.0`](https://www.npmjs.com/package/dsh-plugin-billing-card)
+> · `tofu-box@1.2.1` 起包含本版本（伞包 1.2.0 含 0.1.0）。
 
 - **Host 半**：注册一个客户端可见的 Session 投影单元 `billingUsage`，在提交事件时折叠
-  `assistant/message` / `assistant/attempt` 中模型上报的 `usage`，按 `request/header` 归属模型路由，
+  `assistant/message` / `assistant/attempt` 中模型上报的 `usage`（按 `request/header` 归属模型路由），
+  并折叠 `tool/call` / `tool/result` 里的 `web_search` / `web_fetch` 调用来估算按次费用；
   纯函数、可重放、不产生任何模型调用。
 - **Client 半**：在 `conversation.composer.dock`（输入框下方的环境条目区）新增一个
-  `billing-card` 条目；平时是一枚小药丸（金额 + token 数），点开后是分模型明细卡片。
+  `billing-card` 条目；平时是一枚只显示估算费用的小药丸（token 总量已由 DSH 自带用量药丸显示，
+  这里不重复），点开后是明细卡片。
 
-> 显示的是**按 token 数与价格表计算的估算值**，不是官方账单。实际扣费以 DeepSeek 账单为准。
+> 显示的是**按 token 数、按次价格与价格表计算的估算值**，不是官方账单。实际扣费以 DeepSeek 账单为准。
 
 ## 显示内容
 
-药丸（收起态）：`¥0.0123 · 15.2K tok`，鼠标悬停/读屏可读到完整摘要（金额、token、缓存命中率）。
+药丸（收起态）：`¥0.0123`。只显示估算费用——会话 token 总量与缓存命中率已由 DSH 自带的用量药丸
+显示，不重复占位。鼠标悬停/读屏可读到「预估费用 ¥…」。
 
 卡片（展开态）：
 
@@ -22,31 +30,31 @@
 - token 汇总：缓存未命中输入、缓存命中输入（及命中率）、输出、合计。
 - 按模型分项：模型名、token 数、估算费用；没有配置价格的模型显示「未配置价格」，
   token 仍计入合计，但不计入费用。
+- 联网搜索小节（本会话有搜索/抓取调用时出现）：搜索调用次数、provider 请求数、预计计费请求数、
+  搜索费用；直连 Fetch API 的抓取次数与费用。搜索仍处免费期时显示「免费期内（11/1 起 …）」。
 
 会话还没有任何已结算的 token 用量时，卡片不显示（不会占位、不会报错）。
 
 ## 安装
 
-推荐先在一个**独立的开发 profile** 里安装与验证，不要装进你日常使用的 `desktop` profile：
+已发布 npm：`dsh-plugin-billing-card@0.2.0`，同时也是 `tofu-box` 伞包（1.2.1 起）的成员。
+插件行 id 为 `billing-card`，Client 半是手写浏览器模块，无需构建步骤。
 
 ```bash
-# 1. 从官方 web 模板新建一个独立 profile（只在不存在时创建；不会打开浏览器）
-dsh --profile billing-dev --from-default-profile web --dump-config
-
-# 2. 安装本插件（本地目录，link 方式；无需构建步骤）
-dsh plugin --profile billing-dev add D:\program\dsh-plugins\dsh-plugin-billing-card
-
-# 3. 启动 web profile（--no-open 不会抢占浏览器/桌面焦点；端口按需修改）
-dsh --profile billing-dev --no-open --port 58121
-```
+# 1) 单装（npm）
+dsh plugin --profile <你的profile> add dsh-plugin-billing-card
 
-启动日志会打印带一次性 `?token=` 的地址，用浏览器打开即可；插件行 id 为 `billing-card`，
-包名为 `dsh-plugin-billing-card`。验证完成后，也可以把它装进你自己的正式 profile：
+# 2) 或装整套伞包（自动包含本插件）
+dsh plugin --profile <你的profile> add tofu-box
 
-```bash
+# 3) 开发/未发版：从本仓库本地目录安装（link 方式，改代码不用重装）
 dsh plugin --profile <你的profile> add D:\program\dsh-plugins\dsh-plugin-billing-card
 ```
 
+> 建议先在一个**独立 profile** 里验证，不要装进你日常使用的 `desktop` profile：用官方 web 模板新建
+> `dsh --profile billing-dev --from-default-profile web --dump-config`，装好后
+> `dsh --profile billing-dev --no-open --port 58121` 启动（日志会打印带一次性 `?token=` 的地址）。
+
 > 新装的 Client 模块需要页面刷新一次才会加载；旧会话的投影基线也在刷新/重连后才会带上
 > `billingUsage`，刷新后输入框下方就会出现计费药丸。
 
@@ -95,6 +103,34 @@ plugin_manager install_bundle target = D:\program\dsh-plugins\dsh-plugin-billing
 > 价格来源：DeepSeek 官方「模型 & 价格」页（中文 / 英文），核对时间 2026-10-17。
 > 官方保留调价权利，请以官网与你的实际结算为准；调价后覆盖本插件配置即可。
 
+## 联网搜索 / 抓取计费（0.2.0）
+
+官方口径（Search / Fetch API，2026-10-17 上线）：
+
+- 按**成功请求次数**计费：每 1,000 次成功请求 **5 元 / $0.75**；失败、空结果、超时不计费，
+  `count` 只控制返回条数、不影响单价。
+- 在 DeepSeek Harness / Claude Code / Codex 中由**服务端工具调用**触发的 Search / Fetch 目前免费，
+  **北京时间 2026-11-01 00:00 起**按次收费。DSH 的 `web_search` 走服务端 `web_search` 工具；
+  而 `web_fetch` 是直连 `POST https://api.deepseek.com/v1/tools/fetch` 的普通 API 请求，
+  不属于服务端工具调用，按官方规则自上线起计费。
+- 本插件从会话日志统计（不额外发请求）：
+  - `web_search`：每次工具调用按**去重后的 query 数**计为 provider 请求数（工具本身就是每个
+    query 发一个请求）；一次调用成功且结果源非空时，这些 query 计为「预计计费请求」。
+  - `web_fetch`：按 HTTP 200 的成功抓取计为 Fetch API 计费请求。
+- 费用 = 预计计费请求数 × `search.perRequest`（默认 0.005 元/次，美元 0.00075/次）。
+- 搜索仍在免费期时，卡片显示「免费期内（11/1 起 ¥…）」；抓取费用始终按已计费估算显示。
+
+已知限制（估算口径）：
+
+- 服务端一次 provider 请求内部可能触发 1 次以上 Search（`max_uses`，默认 5），日志不记录实际
+  次数，因此「预计计费」是**下限估算**。
+- 多 query 批量搜索失败时，已成功的那部分可能已被官方计费，但这里整单失败、不计费；
+  空结果的成功调用不计费（与官方一致）。
+- 服务端搜索附带的辅助模型 token 费用不写入会话日志，本卡片不统计。
+- 统计假设 `web_search` / `web_fetch` 由 DeepSeek 官方 provider 提供（出厂 profile 即如此）。
+  若你改配了 Exa / Perplexity 搜索或本地 HTTP 抓取，请把 `search.enabled` 设为 `false`，
+  否则按次费用会误计。
+
 ## 配置
 
 配置写在插件行 `billing-card` 的 `config` 里（profile 的 `cordis.patch.yml` 对整行 `config`
@@ -124,6 +160,13 @@ plugin_manager install_bundle target = D:\program\dsh-plugins\dsh-plugin-billing
       windows: [['09:00', '12:00'], ['14:00', '18:00']]
       holidays: []                 # 例：['2026-10-01', '2026-10-02']；列出的当地日期全天按空闲计价
       multiplier: 2
+
+    # 联网搜索 / 抓取按次计价（0.2.0 起，默认即下方值）
+    search:
+      enabled: true                # false = 完全关闭搜索/抓取统计
+      perRequest: 0.005            # 每次成功请求的价格（当前币种）；默认 CNY 0.005 / USD 0.00075
+      searchFreeUntil: 2026-10-31T16:00:00.000Z  # 搜索服务端调用的免费截止（北京时间 11/1 00:00）；null = 已计费
+      trackFetch: true             # 是否统计直连 DeepSeek Fetch API 的 web_fetch 调用
 ```
 
 ### 支持其他提供商 / 模型
@@ -166,7 +209,7 @@ plugin_manager install_bundle target = D:\program\dsh-plugins\dsh-plugin-billing
 - **法定节假日不会自动识别**：官方规则里中国法定节假日按空闲计价，插件无法内置年年变化的
   节假日表，请在 `peak.holidays` 里按需填写；不填写时只按「周一至周五 + 时间窗口」判断。
 - 金额为估算值，浮点计算后仅用于展示（保留 2–4 位小数）；并发上限、搜索/抓取等按次计费的
-  接口不在统计范围。
+  接口按上面的口径估算，不是账单金额。
 
 ## 结构
 

package/billing-core.js

@@ -45,7 +45,34 @@ const PRICE_RULE_FIELDS = Object.freeze([
 ])
 
 /** Recognized top-level config fields; anything else is a typo. */
-const CONFIG_FIELDS = Object.freeze(['currency', 'pricing', 'peak'])
+const CONFIG_FIELDS = Object.freeze(['currency', 'pricing', 'peak', 'search'])
+
+/** Recognized `search` policy fields. */
+const SEARCH_FIELDS = Object.freeze(['enabled', 'perRequest', 'searchFreeUntil', 'trackFetch'])
+
+/**
+ * Official DeepSeek Search / Fetch per-request prices, in the configured
+ * currency: 5 CNY per 1,000 successful requests, $0.75 per 1,000.
+ */
+const DEFAULT_SEARCH_PER_REQUEST = Object.freeze({ CNY: 0.005, USD: 0.00075 })
+
+/**
+ * DeepSeek keeps server-side Search / Fetch calls free through Beijing
+ * 2026-11-01 00:00 (2026-10-31T16:00:00Z); direct API requests are billed from
+ * launch. Only the server-side search window is configurable here.
+ */
+const DEFAULT_SEARCH_FREE_UNTIL = '2026-10-31T16:00:00.000Z'
+
+/** The all-zero search counters of a fresh fold state. */
+const ZERO_SEARCH_COUNTERS = Object.freeze({
+  calls: 0,
+  requests: 0,
+  billable: 0,
+  emptyCalls: 0,
+  failedCalls: 0,
+  fetchCalls: 0,
+  fetchBillable: 0,
+})
 
 /** Recognized `peak` policy fields. */
 const PEAK_FIELDS = Object.freeze([
@@ -196,6 +223,65 @@ function resolveCurrency(value, path) {
   return /** @type {'CNY'|'USD'} */ (value)
 }
 
+/**
+ * Resolve one optional boolean flag.
+ * @param {unknown} value - configured flag or `undefined`.
+ * @param {string} path - config path of the flag.
+ * @param {boolean} fallback - value used when the flag is absent.
+ * @returns {boolean} the effective flag.
+ */
+function resolveBoolean(value, path, fallback) {
+  if (value === undefined) return fallback
+  if (typeof value !== 'boolean') failConfig(`${path} must be a boolean`)
+  return value
+}
+
+/**
+ * Resolve one optional ISO-8601 timestamp, where `null` disables the window.
+ * @param {unknown} value - configured timestamp, `null`, or `undefined`.
+ * @param {string} path - config path of the value.
+ * @param {string} fallback - ISO-8601 timestamp used when the value is absent.
+ * @returns {number|null} epoch milliseconds, or `null` when the window is disabled.
+ */
+function resolveTimestamp(value, path, fallback) {
+  if (value === undefined) return Date.parse(fallback)
+  if (value === null) return null
+  if (typeof value !== 'string' || value.length === 0) failConfig(`${path} must be an ISO-8601 timestamp or null`)
+  const parsed = Date.parse(value)
+  if (!Number.isFinite(parsed)) failConfig(`${path} must be an ISO-8601 timestamp or null`)
+  return parsed
+}
+
+/**
+ * Validate the optional `search` policy and apply every default. The policy
+ * covers DeepSeek's per-request Search / Fetch billing: one price for both
+ * APIs, a free window for server-side search calls only, and a switch for the
+ * direct Fetch API path used by the runtime's web fetch tool.
+ * @param {unknown} rawSearch - raw `config.search` value.
+ * @param {'CNY'|'USD'} currency - configured billing currency.
+ * @returns {{ enabled: boolean, perRequest: number, searchFreeUntil: number|null, trackFetch: boolean }} resolved policy.
+ */
+function resolveSearchConfig(rawSearch, currency) {
+  if (rawSearch === undefined) {
+    return {
+      enabled: true,
+      perRequest: DEFAULT_SEARCH_PER_REQUEST[currency],
+      searchFreeUntil: Date.parse(DEFAULT_SEARCH_FREE_UNTIL),
+      trackFetch: true,
+    }
+  }
+  if (!isPlainObject(rawSearch)) failConfig('config.search must be a plain object')
+  rejectUnknownKeys(rawSearch, SEARCH_FIELDS, 'config.search')
+  return {
+    enabled: resolveBoolean(rawSearch.enabled, 'config.search.enabled', true),
+    perRequest: rawSearch.perRequest === undefined
+      ? DEFAULT_SEARCH_PER_REQUEST[currency]
+      : finiteNonNegative(rawSearch.perRequest, 'config.search.perRequest'),
+    searchFreeUntil: resolveTimestamp(rawSearch.searchFreeUntil, 'config.search.searchFreeUntil', DEFAULT_SEARCH_FREE_UNTIL),
+    trackFetch: resolveBoolean(rawSearch.trackFetch, 'config.search.trackFetch', true),
+  }
+}
+
 /**
  * Convert `HH:MM` to a minute-of-day offset.
  * @param {string} time - validated `HH:MM` string.
@@ -411,7 +497,7 @@ function buildBuiltinRules(peakMultiplier) {
  * negative prices, bad currencies, `HH:MM` times, weekdays, or holiday dates
  * throw an `Error` whose message names the config path.
  * @param {unknown} [rawConfig] - raw row config from the profile composition.
- * @returns {{ currency: 'CNY'|'USD', rules: Array<Record<string, number|string>>, builtinRules: Array<Record<string, number|string>>, peak: { enabled: boolean, utcOffsetMinutes: number, weekdays: number[], windows: Array<[string, string]>, holidays: string[], multiplier: number } }} resolved config.
+ * @returns {{ currency: 'CNY'|'USD', rules: Array<Record<string, number|string>>, builtinRules: Array<Record<string, number|string>>, peak: { enabled: boolean, utcOffsetMinutes: number, weekdays: number[], windows: Array<[string, string]>, holidays: string[], multiplier: number }, search: { enabled: boolean, perRequest: number, searchFreeUntil: number|null, trackFetch: boolean } }} resolved config.
  */
 export function resolveBillingConfig(rawConfig = {}) {
   if (!isPlainObject(rawConfig)) failConfig('config must be a plain object')
@@ -420,9 +506,10 @@ export function resolveBillingConfig(rawConfig = {}) {
     ? DEFAULT_CURRENCY
     : resolveCurrency(rawConfig.currency, 'config.currency')
   const peak = resolvePeakPolicy(rawConfig.peak)
+  const search = resolveSearchConfig(rawConfig.search, currency)
   const rules = resolvePriceRules(rawConfig.pricing, currency, peak.multiplier)
   const builtinRules = buildBuiltinRules(peak.multiplier)
-  return { currency, rules, builtinRules, peak }
+  return { currency, rules, builtinRules, peak, search }
 }
 
 // --------------------------------------------------------------------------
@@ -660,6 +747,139 @@ function addBuckets(routes, routeKey, provider, model, tier, buckets) {
   return { ...routes, [routeKey]: { ...entry, [tier]: next } }
 }
 
+// --------------------------------------------------------------------------
+// Search / fetch fold
+// --------------------------------------------------------------------------
+
+/**
+ * Count the distinct non-blank queries of one `web_search` tool call. The tool
+ * collapses exact duplicate queries before dispatching one provider request per
+ * distinct query, so this count is that call's provider-request count.
+ * @param {unknown} argumentsValue - raw `arguments` JSON string or parsed object.
+ * @returns {number|null} distinct query count, or `null` when the payload is not a valid search call.
+ */
+function searchQueriesOf(argumentsValue) {
+  let args = argumentsValue
+  if (typeof args === 'string') {
+    try {
+      args = JSON.parse(args)
+    } catch {
+      return null
+    }
+  }
+  if (!isPlainObject(args) || !Array.isArray(args.queries)) return null
+  const queries = new Set()
+  for (const query of args.queries) {
+    if (typeof query === 'string' && query.trim().length > 0) queries.add(query)
+  }
+  return queries.size === 0 ? null : queries.size
+}
+
+/**
+ * Read the tool call id off one persisted `tool/result` message.
+ * @param {Record<string, any>} message - the tool message.
+ * @returns {string|undefined} the call id, when the message carries one.
+ */
+function resultCallId(message) {
+  if (typeof message.toolCallId === 'string' && message.toolCallId.length > 0) return message.toolCallId
+  const source = message.source
+  if (isPlainObject(source) && typeof source.callId === 'string' && source.callId.length > 0) return source.callId
+  return undefined
+}
+
+/**
+ * Fold one `tool/call` event into the search / fetch counters. A search call
+ * records one provider request per distinct query (the tool dispatches one per
+ * query, and the current runtime logs no separate request event) under the call
+ * id until the result arrives; a fetch call only records its call id (its
+ * result meta carries the status).
+ * @param {{ search: Record<string, any> }} state - current state.
+ * @param {{ data?: any }} event - committed `tool/call` event.
+ * @param {{ trackFetch: boolean }} searchPolicy - resolved search policy.
+ * @returns {typeof state} the next state, or the same reference for other tools.
+ */
+function applySearchToolCall(state, event, searchPolicy) {
+  const data = event.data
+  if (!isPlainObject(data)) return state
+  if (typeof data.callId !== 'string' || data.callId.length === 0) return state
+  const search = state.search
+  if (data.name === 'web_search') {
+    const queries = searchQueriesOf(data.arguments)
+    if (queries === null) return state
+    return {
+      ...state,
+      search: {
+        ...search,
+        calls: search.calls + 1,
+        requests: search.requests + queries,
+        pending: { ...search.pending, [data.callId]: queries },
+      },
+    }
+  }
+  if (data.name === 'web_fetch' && searchPolicy.trackFetch === true) {
+    return {
+      ...state,
+      search: {
+        ...search,
+        fetchCalls: search.fetchCalls + 1,
+        pendingFetch: { ...search.pendingFetch, [data.callId]: 1 },
+      },
+    }
+  }
+  return state
+}
+
+/**
+ * Fold one `tool/result` event that completes a tracked search or fetch call.
+ *
+ * A search result is billable only when the call succeeded with a non-empty
+ * merged source list: the provider returns sources only when the Search API
+ * returned results, and an empty source list is the tool's "No results found"
+ * success. A fetch result is billable only with HTTP 200 and no tool error.
+ * The pending entry is removed on the first result, so a compaction-pruner
+ * replacement result for the same call is ignored.
+ * @param {{ search: Record<string, any> }} state - current state.
+ * @param {{ data?: any }} event - committed `tool/result` event.
+ * @param {{ trackFetch: boolean }} searchPolicy - resolved search policy.
+ * @returns {typeof state} the next state, or the same reference for other calls.
+ */
+function applySearchToolResult(state, event, searchPolicy) {
+  const data = event.data
+  if (!isPlainObject(data) || !isPlainObject(data.message)) return state
+  const message = data.message
+  const callId = resultCallId(message)
+  if (callId === undefined) return state
+  const search = state.search
+  if (Object.hasOwn(search.pending, callId)) {
+    const queries = search.pending[callId]
+    const pending = { ...search.pending }
+    delete pending[callId]
+    const next = { ...search, pending }
+    if (message.isError === true) {
+      return { ...state, search: { ...next, failedCalls: next.failedCalls + 1 } }
+    }
+    const sources = isPlainObject(data.meta) && Array.isArray(data.meta.sources) ? data.meta.sources : null
+    if (sources === null) return { ...state, search: { ...next, failedCalls: next.failedCalls + 1 } }
+    if (sources.length === 0) return { ...state, search: { ...next, emptyCalls: next.emptyCalls + 1 } }
+    return { ...state, search: { ...next, billable: next.billable + queries } }
+  }
+  if (searchPolicy.trackFetch === true && Object.hasOwn(search.pendingFetch, callId)) {
+    const pendingFetch = { ...search.pendingFetch }
+    delete pendingFetch[callId]
+    const meta = isPlainObject(data.meta) ? data.meta : null
+    const billable = message.isError !== true && meta !== null && meta.statusCode === 200
+    return {
+      ...state,
+      search: {
+        ...search,
+        pendingFetch,
+        fetchBillable: search.fetchBillable + (billable ? 1 : 0),
+      },
+    }
+  }
+  return state
+}
+
 // --------------------------------------------------------------------------
 // Fold transitions
 // --------------------------------------------------------------------------
@@ -742,22 +962,28 @@ function applyUsage(state, event, peakPolicy) {
     routes,
     current: state.current,
     last: { turn: data.turn, step: data.step, routeKey, tier, buckets },
+    search: state.search,
   }
 }
 
 /**
  * The projection fold: the one transition from committed event to state.
- * @param {{ routes: Record<string, any>, current: { provider: string, model: string }|null, last: any }} state - state covering all prior events.
+ * @param {{ routes: Record<string, any>, current: { provider: string, model: string }|null, last: any, search: Record<string, any> }} state - state covering all prior events.
  * @param {any} event - the next committed Session event.
- * @param {{ enabled: boolean, utcOffsetMinutes: number, weekdays: number[], windows: Array<[string, string]>, holidays: string[], multiplier: number }} peakPolicy - resolved peak policy.
+ * @param {ReturnType<typeof resolveBillingConfig>} resolvedConfig - resolved config.
  * @returns {typeof state} the next state; the same reference when the event is not this unit's.
  */
-function applyEvent(state, event, peakPolicy) {
+function applyEvent(state, event, resolvedConfig) {
   if (!isPlainObject(event) || typeof event.type !== 'string') return state
   if (event.type === 'request/header') return applyRequestHeader(state, event)
   if (event.type === 'llm/retry-started') return applyRetryStarted(state, event)
+  const searchPolicy = resolvedConfig.search
+  if (searchPolicy !== undefined && searchPolicy.enabled === true) {
+    if (event.type === 'tool/call') return applySearchToolCall(state, event, searchPolicy)
+    if (event.type === 'tool/result') return applySearchToolResult(state, event, searchPolicy)
+  }
   if (event.type !== 'assistant/message' && event.type !== 'assistant/attempt') return state
-  return applyUsage(state, event, peakPolicy)
+  return applyUsage(state, event, resolvedConfig.peak)
 }
 
 // --------------------------------------------------------------------------
@@ -843,6 +1069,54 @@ function viewRoute(entry, resolvedConfig) {
   }
 }
 
+/**
+ * Coerce one persisted search counter into a non-negative integer. Missing,
+ * non-finite, and negative values count as 0.
+ * @param {unknown} value - raw counter.
+ * @returns {number} the counter value.
+ */
+function counterValue(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? Math.floor(value) : 0
+}
+
+/**
+ * Build the wire view of the search / fetch cost section. Counts are always
+ * present; costs are estimates from the resolved per-request price. The search
+ * cost is the post-free-window estimate (the client decides how to label it
+ * while `searchFreeUntil` is still in the future), while the fetch cost is the
+ * direct Fetch API spend, which is billable from launch.
+ * @param {{ search?: Record<string, any> }} state - fold state.
+ * @param {ReturnType<typeof resolveBillingConfig>} resolvedConfig - resolved config.
+ * @returns {Record<string, any>} the `search` wire section.
+ */
+function searchView(state, resolvedConfig) {
+  const policy = resolvedConfig.search
+  const search = isPlainObject(state) && isPlainObject(state.search) ? state.search : {}
+  const trackFetch = policy.trackFetch === true
+  const calls = counterValue(search.calls)
+  const requests = counterValue(search.requests)
+  const billable = counterValue(search.billable)
+  const fetchCalls = trackFetch ? counterValue(search.fetchCalls) : 0
+  const fetchBillable = trackFetch ? counterValue(search.fetchBillable) : 0
+  const searchCost = billable * policy.perRequest
+  const fetchCost = fetchBillable * policy.perRequest
+  return {
+    enabled: policy.enabled === true,
+    perRequest: policy.perRequest,
+    searchFreeUntil: policy.searchFreeUntil,
+    calls,
+    requests,
+    billable,
+    emptyCalls: counterValue(search.emptyCalls),
+    failedCalls: counterValue(search.failedCalls),
+    fetchCalls,
+    fetchBillable,
+    searchCost,
+    fetchCost,
+    totalCost: searchCost + fetchCost,
+  }
+}
+
 /**
  * Project one fold state to the client wire view.
  *
@@ -850,9 +1124,9 @@ function viewRoute(entry, resolvedConfig) {
  * object. Only routes with at least one token are listed; unpriced routes keep
  * their tokens in `totals` but carry `priced: false`, `pricing: null`, and zero
  * cost fields. Costs are raw floats in the configured currency.
- * @param {{ routes: Record<string, { provider: string, model: string, peak: Record<string, number>, offPeak: Record<string, number> }> }} state - fold state.
+ * @param {{ routes: Record<string, { provider: string, model: string, peak: Record<string, number>, offPeak: Record<string, number> }>, search?: Record<string, any> }} state - fold state.
  * @param {ReturnType<typeof resolveBillingConfig>} resolvedConfig - resolved config.
- * @returns {{ version: 1, currency: string, routes: Array<Record<string, any>>, totals: Record<string, number> }} the wire view.
+ * @returns {{ version: 1, currency: string, routes: Array<Record<string, any>>, totals: Record<string, number>, search: Record<string, any> }} the wire view.
  */
 export function billingView(state, resolvedConfig) {
   const currency = isPlainObject(resolvedConfig) ? resolvedConfig.currency : DEFAULT_CURRENCY
@@ -891,7 +1165,7 @@ export function billingView(state, resolvedConfig) {
     if (route.priced) totals.pricedRoutes += 1
     else totals.unpricedRoutes += 1
   }
-  return { version: 1, currency, routes, totals }
+  return { version: 1, currency, routes, totals, search: searchView(state, resolvedConfig) }
 }
 
 // --------------------------------------------------------------------------
@@ -1010,6 +1284,50 @@ function lastSampleIssue(value) {
   return bucketIssue(value.buckets, 'state.last.buckets')
 }
 
+/**
+ * Describe why a value is not a valid `state.search` pending map.
+ * @param {unknown} value - candidate pending map.
+ * @param {string} path - field path for the issue description.
+ * @returns {string|null} the issue, if any.
+ */
+function searchPendingIssue(value, path) {
+  if (!isPlainObject(value)) return `${path} must be a plain object`
+  for (const [callId, entry] of Object.entries(value)) {
+    if (callId.length === 0) return `${path} keys must be non-empty call ids`
+    const issue = integerIssue(entry, `${path}[${JSON.stringify(callId)}]`)
+    if (issue !== null) return issue
+  }
+  return null
+}
+
+/**
+ * Describe why a value is not a valid `state.search` counter block.
+ * @param {unknown} value - candidate search state.
+ * @returns {string|null} the issue, if any.
+ */
+function searchStateIssue(value) {
+  if (!isPlainObject(value)) return 'state.search must be a plain object'
+  const fields = [
+    'calls',
+    'requests',
+    'billable',
+    'emptyCalls',
+    'failedCalls',
+    'fetchCalls',
+    'fetchBillable',
+    'pending',
+    'pendingFetch',
+  ]
+  if (!hasExactKeys(value, fields)) return `state.search must carry exactly ${fields.join(', ')}`
+  for (const field of fields) {
+    if (field === 'pending' || field === 'pendingFetch') continue
+    const issue = integerIssue(value[field], `state.search.${field}`)
+    if (issue !== null) return issue
+  }
+  return searchPendingIssue(value.pending, 'state.search.pending')
+    ?? searchPendingIssue(value.pendingFetch, 'state.search.pendingFetch')
+}
+
 /**
  * Describe why a value is not a valid `billingUsage` fold state. Used by
  * `stateSchema` before a persisted checkpoint seeds a fold.
@@ -1018,13 +1336,13 @@ function lastSampleIssue(value) {
  */
 function stateIssue(value) {
   if (!isPlainObject(value)) return 'state must be a plain object'
-  if (!hasExactKeys(value, ['routes', 'current', 'last'])) return 'state must carry exactly routes, current, and last'
+  if (!hasExactKeys(value, ['routes', 'current', 'last', 'search'])) return 'state must carry exactly routes, current, last, and search'
   if (!isPlainObject(value.routes)) return 'state.routes must be a plain object'
   for (const [routeKey, route] of Object.entries(value.routes)) {
     const issue = stateRouteIssue(route, `state.routes[${JSON.stringify(routeKey)}]`)
     if (issue !== null) return issue
   }
-  return currentRouteIssue(value.current) ?? lastSampleIssue(value.last)
+  return currentRouteIssue(value.current) ?? lastSampleIssue(value.last) ?? searchStateIssue(value.search)
 }
 
 /**
@@ -1114,6 +1432,47 @@ function totalsIssue(value, path) {
   return integerIssue(value.unpricedRoutes, `${path}.unpricedRoutes`)
 }
 
+/**
+ * Describe why a value is not a valid `search` section of the wire view.
+ * @param {unknown} value - candidate search section.
+ * @returns {string|null} the issue, if any.
+ */
+function searchViewIssue(value) {
+  if (!isPlainObject(value)) return 'view.search must be a plain object'
+  const fields = [
+    'enabled',
+    'perRequest',
+    'searchFreeUntil',
+    'calls',
+    'requests',
+    'billable',
+    'emptyCalls',
+    'failedCalls',
+    'fetchCalls',
+    'fetchBillable',
+    'searchCost',
+    'fetchCost',
+    'totalCost',
+  ]
+  if (!hasExactKeys(value, fields)) return `view.search must carry exactly ${fields.join(', ')}`
+  if (typeof value.enabled !== 'boolean') return 'view.search.enabled must be a boolean'
+  const perRequestIssue = numberIssue(value.perRequest, 'view.search.perRequest')
+  if (perRequestIssue !== null) return perRequestIssue
+  if (value.searchFreeUntil !== null) {
+    const issue = numberIssue(value.searchFreeUntil, 'view.search.searchFreeUntil')
+    if (issue !== null) return issue
+  }
+  for (const field of ['calls', 'requests', 'billable', 'emptyCalls', 'failedCalls', 'fetchCalls', 'fetchBillable']) {
+    const issue = integerIssue(value[field], `view.search.${field}`)
+    if (issue !== null) return issue
+  }
+  for (const field of ['searchCost', 'fetchCost', 'totalCost']) {
+    const issue = numberIssue(value[field], `view.search.${field}`)
+    if (issue !== null) return issue
+  }
+  return null
+}
+
 /**
  * Describe why a value is not a valid wire view for this projection.
  * @param {unknown} value - candidate view.
@@ -1121,8 +1480,8 @@ function totalsIssue(value, path) {
  */
 function viewIssue(value) {
   if (!isPlainObject(value)) return 'view must be a plain object'
-  if (!hasExactKeys(value, ['version', 'currency', 'routes', 'totals'])) {
-    return 'view must carry exactly version, currency, routes, and totals'
+  if (!hasExactKeys(value, ['version', 'currency', 'routes', 'totals', 'search'])) {
+    return 'view must carry exactly version, currency, routes, totals, and search'
   }
   if (value.version !== 1) return 'view.version must be 1'
   if (!CURRENCIES.includes(/** @type {string} */ (value.currency))) return "view.currency must be 'CNY' or 'USD'"
@@ -1131,7 +1490,7 @@ function viewIssue(value) {
     const issue = viewRouteIssue(value.routes[index], `view.routes[${index}]`)
     if (issue !== null) return issue
   }
-  return totalsIssue(value.totals, 'view.totals')
+  return totalsIssue(value.totals, 'view.totals') ?? searchViewIssue(value.search)
 }
 
 /** Validates one persisted `billingUsage` fold state. */
@@ -1156,7 +1515,6 @@ const viewSchema = structuralSchema('billingUsage view', viewIssue)
  * @returns {{ key: string, stateVersion: number, stateSchema: { parse: Function, safeParse: Function }, init: () => object, apply: (state: object, event: unknown) => object, wire: { viewSchema: { parse: Function, safeParse: Function }, view: (state: object) => object } }} the projection definition.
  */
 export function createBillingProjection(resolvedConfig) {
-  const peakPolicy = resolvedConfig.peak
   let cachedState
   let cachedView
   const view = (state) => {
@@ -1167,10 +1525,15 @@ export function createBillingProjection(resolvedConfig) {
   }
   return {
     key: BILLING_PROJECTION_KEY,
-    stateVersion: 1,
+    stateVersion: 2,
     stateSchema,
-    init: () => ({ routes: {}, current: null, last: null }),
-    apply: (state, event) => applyEvent(state, event, peakPolicy),
+    init: () => ({
+      routes: {},
+      current: null,
+      last: null,
+      search: { ...ZERO_SEARCH_COUNTERS, pending: {}, pendingFetch: {} },
+    }),
+    apply: (state, event) => applyEvent(state, event, resolvedConfig),
     wire: { viewSchema, view },
   }
 }

package/client.js

@@ -43,10 +43,20 @@ window.__ModuleLoader__.load({
       'routes.unknownModel': '未知模型',
       'unpriced.badge': '未配置价格',
       'unpriced.hint': '仅统计 token',
+      'search.title': '联网搜索',
+      'search.calls': '网页搜索',
+      'search.callsValue': '{calls} 次（{requests} 个请求）',
+      'search.billable': '预计计费',
+      'search.billableValue': '{count} 次',
+      'search.cost': '搜索费用',
+      'search.freeValue': '免费期内（11/1 起 {cost}）',
+      'search.freeNote': '服务端搜索调用免费至 2026-11-01 00:00，之后按官方每 1000 次价格估算。',
+      'search.fetch': '网页抓取',
+      'search.fetchValue': '{count} 次 · {cost}',
+      'search.fetchNote': '网页抓取为直连 DeepSeek Fetch API，按次计费。',
       'footer.estimate': '费用为按配置价格表估算的预估值，非实际账单。',
       'footer.config': '价格与峰谷时段可在插件配置中调整。',
-      'pill.aria': '预估费用 {cost}，{tokens}，缓存命中率 {percent}%',
-      'pill.ariaNoCache': '预估费用 {cost}，{tokens}',
+      'pill.aria': '预估费用 {cost}',
     }
 
     const ENGLISH = {
@@ -63,10 +73,20 @@ window.__ModuleLoader__.load({
       'routes.unknownModel': 'Unknown model',
       'unpriced.badge': 'Unpriced',
       'unpriced.hint': 'Tokens only',
+      'search.title': 'Web search',
+      'search.calls': 'Search',
+      'search.callsValue': '{calls} calls ({requests} provider requests)',
+      'search.billable': 'Estimated billable',
+      'search.billableValue': '{count} requests',
+      'search.cost': 'Search cost',
+      'search.freeValue': 'Free until Nov 1 (then {cost})',
+      'search.freeNote': 'Server-side search calls are free until 2026-11-01 00:00 Beijing; afterward priced at the official per-1,000-request rate.',
+      'search.fetch': 'Web fetch',
+      'search.fetchValue': '{count} requests · {cost}',
+      'search.fetchNote': 'Web fetch calls the DeepSeek Fetch API directly and is billed per request.',
       'footer.estimate': 'Costs are estimates from the configured price table, not an actual bill.',
       'footer.config': 'Pricing and peak windows are configurable in the plugin config.',
-      'pill.aria': 'Estimated cost {cost}, {tokens}, cache hit {percent}%',
-      'pill.ariaNoCache': 'Estimated cost {cost}, {tokens}',
+      'pill.aria': 'Estimated cost {cost}',
     }
 
     /** Locale ids the browser client ships; `bind`'s fallback chain anchors on them. */
@@ -182,7 +202,7 @@ window.__ModuleLoader__.load({
      * missing projection, a future version, or a fresh Session leaves the
      * slot empty instead of throwing.
      * @param view - `useProjection('billingUsage')` result.
-     * @returns `{ currency, routes, totals }` or null.
+     * @returns `{ currency, routes, totals, search }` or null.
      */
     function renderableView(view) {
       if (view === null || typeof view !== 'object') return null
@@ -190,10 +210,12 @@ window.__ModuleLoader__.load({
       const totals = view.totals
       if (totals === null || typeof totals !== 'object') return null
       if (!(finite(totals.total) > 0)) return null
+      const search = view.search !== null && typeof view.search === 'object' ? view.search : null
       return {
         currency: view.currency,
         routes: Array.isArray(view.routes) ? view.routes : [],
         totals,
+        search,
       }
     }
 
@@ -302,14 +324,13 @@ window.__ModuleLoader__.load({
 
       if (!visible) return null
 
-      const { currency, routes, totals } = data
+      const { currency, routes, totals, search } = data
       const percent = cacheHitPercent(totals)
       const costText = formatCost(totals.cost, currency)
       const tokenCount = value => t('tokens.count', { count: formatCount(value) })
-      const totalTokensText = tokenCount(totals.total)
-      const ariaLabel = percent === null
-        ? t('pill.ariaNoCache', { cost: costText, tokens: totalTokensText })
-        : t('pill.aria', { cost: costText, tokens: totalTokensText, percent })
+      // The dock row already shows the Session's official token count, so the
+      // pill carries only the thing that row cannot: the estimated cost.
+      const ariaLabel = t('pill.aria', { cost: costText })
 
       const panelStyle = position === null
         ? { visibility: 'hidden' }
@@ -362,8 +383,44 @@ window.__ModuleLoader__.load({
             priced ? null : h('span', { className: 'bc-route-hint' }, t('unpriced.hint')))))
       }
 
-      const panel = open ? ReactDOM.createPortal(
-        h('div', {
+      // Search / fetch section: the DeepSeek per-request API spend the token
+      // fold cannot see. Hidden until this Session actually searched or fetched.
+      const searchCalls = search === null ? 0 : finite(search.calls)
+      const fetchCalls = search === null ? 0 : finite(search.fetchCalls)
+      const showSearch = search !== null
+        && search.enabled === true
+        && (searchCalls > 0 || fetchCalls > 0)
+      const searchRows = []
+      const searchNotes = []
+      if (showSearch) {
+        const freeUntil = typeof search.searchFreeUntil === 'number' ? search.searchFreeUntil : null
+        const freePeriod = freeUntil !== null && Date.now() < freeUntil
+        const pushSearchRow = (key, label, value) => {
+          searchRows.push(h('dt', { key: `search-${key}-label`, className: 'bc-row-label' }, label))
+          searchRows.push(h('dd', { key: `search-${key}-value`, className: 'bc-row-value' }, value))
+        }
+        pushSearchRow('calls', t('search.calls'), t('search.callsValue', {
+          calls: formatCount(searchCalls),
+          requests: formatCount(finite(search.requests)),
+        }))
+        pushSearchRow('billable', t('search.billable'), t('search.billableValue', {
+          count: formatCount(finite(search.billable)),
+        }))
+        const searchCostText = formatCost(finite(search.searchCost), currency)
+        pushSearchRow('cost', t('search.cost'), freePeriod
+          ? t('search.freeValue', { cost: searchCostText })
+          : searchCostText)
+        if (fetchCalls > 0) {
+          pushSearchRow('fetch', t('search.fetch'), t('search.fetchValue', {
+            count: formatCount(finite(search.fetchBillable)),
+            cost: formatCost(finite(search.fetchCost), currency),
+          }))
+        }
+        if (freePeriod) searchNotes.push(t('search.freeNote'))
+        if (fetchCalls > 0) searchNotes.push(t('search.fetchNote'))
+      }
+
+      const panel = open ? ReactDOM.createPortal(        h('div', {
           ref: panelRef,
           className: 'bc-panel',
           role: 'dialog',
@@ -384,6 +441,15 @@ window.__ModuleLoader__.load({
               h('div', { className: 'bc-section-title' }, t('routes.title')),
               routeRows)
             : null,
+          showSearch
+            ? h('div', { className: 'bc-search' },
+              h('div', { className: 'bc-section-title' }, t('search.title')),
+              h('dl', { className: 'bc-rows' }, searchRows),
+              searchNotes.map((note, index) => h('p', {
+                key: `search-note-${index}`,
+                className: 'bc-note bc-search-note',
+              }, note)))
+            : null,
           h('div', { className: 'bc-footer' },
             h('p', { className: 'bc-note' }, t('footer.estimate')),
             h('p', { className: 'bc-note' }, t('footer.config')))),
@@ -402,9 +468,7 @@ window.__ModuleLoader__.load({
           onClick: toggle,
         },
           billingIcon(),
-          h('span', { className: 'bc-pill-cost' }, costText),
-          h('span', { className: 'bc-pill-sep', 'aria-hidden': 'true' }, '·'),
-          h('span', { className: 'bc-pill-tokens' }, totalTokensText)),
+          h('span', { className: 'bc-pill-cost' }, costText)),
         panel)
     }
 
@@ -415,8 +479,6 @@ window.__ModuleLoader__.load({
 .bc-pill:focus-visible{outline:2px solid var(--dsw-alias-brand-primary);outline-offset:2px}
 .bc-icon{width:14px;height:14px;flex:none}
 .bc-pill-cost{color:var(--dsw-alias-label-primary);font-variant-numeric:tabular-nums}
-.bc-pill-sep{margin:0 6px;color:var(--dsw-alias-separator-primary)}
-.bc-pill-tokens{min-width:0;overflow:hidden;text-overflow:ellipsis}
 .bc-panel{position:fixed;z-index:1100;box-sizing:border-box;width:300px;max-width:calc(100vw - 16px);max-height:min(70vh,520px);overflow:auto;overscroll-behavior:contain;padding:14px;border:1px solid var(--dsw-alias-border-l2);border-radius:12px;background:var(--dsw-alias-bg-overlay);color:var(--dsw-alias-label-primary);font-family:inherit;font-size:12px;line-height:18px;text-align:left;cursor:default}
 .bc-head{display:flex;align-items:baseline;justify-content:space-between;gap:12px}
 .bc-title{font-size:13px;font-weight:600;color:var(--dsw-alias-label-primary)}
@@ -427,6 +489,8 @@ window.__ModuleLoader__.load({
 .bc-row-label{min-width:0;margin:0;color:var(--dsw-alias-label-secondary)}
 .bc-row-value{min-width:0;margin:0;color:var(--dsw-alias-label-primary);font-variant-numeric:tabular-nums;text-align:right;overflow-wrap:anywhere}
 .bc-routes{margin-top:12px}
+.bc-search{margin-top:12px}
+.bc-search-note{margin:6px 0 0}
 .bc-section-title{margin-bottom:2px;color:var(--dsw-alias-label-secondary);font-size:11px;line-height:16px;letter-spacing:.02em}
 .bc-route{padding:6px 0 2px;border-top:1px solid var(--dsw-alias-border-l1)}
 .bc-route-head{display:flex;align-items:baseline;justify-content:space-between;gap:8px;min-width:0}

package/cordis.patch.yml

@@ -7,8 +7,8 @@
 # activity/usage pills, not in place of them).
 #
 # Tunables live in the row config and survive upgrades; see README.md for the
-# `currency`, `pricing`, and `peak` fields. Override the whole config of this
-# row from the profile's cordis.patch.yml:
+# `currency`, `pricing`, `peak`, and `search` fields. Override the whole config
+# of this row from the profile's cordis.patch.yml:
 #
 #   - id: billing-card
 #     config:
@@ -18,6 +18,10 @@
 #           inputPerM: 1
 #           cacheReadPerM: 0.02
 #           outputPerM: 4
+#       search:
+#         perRequest: 0.005            # CNY per successful Search / Fetch request
+#         searchFreeUntil: 2026-10-31T16:00:00.000Z   # or null when billed already
+#         trackFetch: true             # count direct Fetch API calls too
 #
 # The row below starts with no config so the built-in DeepSeek defaults apply.
 - insert:

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "dsh-plugin-billing-card",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "license": "MIT",
   "keywords": ["dsh-plugin", "deepseek-harness", "dsh", "billing", "token", "usage", "cost", "deepseek"],
   "publishConfig": { "registry": "https://registry.npmjs.org" },
   "repository": { "type": "git", "url": "git+https://github.com/tofu-zyc/dsh-plugin-tofu-box.git", "directory": "dsh-plugin-billing-card" },
   "bugs": { "url": "https://github.com/tofu-zyc/dsh-plugin-tofu-box/issues" },
   "homepage": "https://github.com/tofu-zyc/dsh-plugin-tofu-box/tree/main/dsh-plugin-billing-card",
-  "description": "计费卡片：在输入框下方实时统计当前会话各模型的 token 用量，并按可配置的价格表（默认 DeepSeek 官方峰谷价，CNY/USD）估算费用。Host 端注册 billingUsage 会话投影（纯函数、可重放），Client 端是输入框下方的药丸与分模型明细卡片；价格表和峰谷规则可通过插件配置扩展以支持其他模型/提供商。",
+  "description": "计费卡片：在输入框下方实时统计当前会话各模型的 token 用量，并按可配置的价格表（默认 DeepSeek 官方峰谷价，CNY/USD）估算费用；同时统计 DeepSeek 官方网页搜索 / 抓取 API 的调用次数与按次费用（Search 服务端调用免费至 2026-11-01 00:00，之后按每 1000 次 5 元估算）。Host 端注册 billingUsage 会话投影（纯函数、可重放），Client 端是输入框下方的药丸与明细卡片；价格表、峰谷规则和搜索计价可通过插件配置扩展以支持其他模型/提供商。",
   "type": "module",
   "main": "index.js",
   "exports": {