dsh-websearch-quota

Websearch Quota

DSH Web 插件：composer dock 徽章，显示此机器还剩多少免费网页搜索额度（Firecrawl 无密钥限制窗口、实际密钥余额、本地调用记录）。

目标 Profile

插件会安装到这里；不确定时保持 web。

npx -y @deepseek-ai/dsh plugin --profile web add github:fuyu1993/dsh-websearch-quota#82dd6b2c8e8ae43a49c989e371baaa15c353cef3

兼容性与来源证明

Websearch Quota 以 dsh-websearch-quota 发布，当前版本为 0.1.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。

DSH 兼容范围: *
运行环境: web
发布来源: github
Registry 更新时间: 2026/10/20

版本

0.1.0stable

2026/10/20

DeepSeek Harness Plugin Hub

← Plugins

dsh-websearch-quota

Websearch Quota

DSH Web 插件：composer dock 徽章，显示此机器还剩多少免费网页搜索额度（Firecrawl 无密钥限制窗口、实际密钥余额、本地调用记录）。

目标 Profile

插件会安装到这里；不确定时保持 web。

npx -y @deepseek-ai/dsh plugin --profile web add github:fuyu1993/dsh-websearch-quota#82dd6b2c8e8ae43a49c989e371baaa15c353cef3

README

dsh-websearch-quota

基于 modsearch 做的免费额度次数查询的小插件。

给 DSH（DeepSeek Harness）Web GUI 加一个常驻小徽章，回答一个问题：这台机器现在还能免费用多少次 web 搜索？

徽章挂在输入框下方的环境行（client slot conversation.composer.dock），点开是一张明细卡片：限流窗口、本机记账、真实余额、手动探测。

┌─ 输入框 ─────────────────────────────────────────────┐
│                                                      │
└──────────────────────────────────────────────────────┘
 ● 免费搜索 · 15h57m 后恢复        ← 徽章（常驻）

一句话立场：Firecrawl keyless（@liustack/modsearch 的默认免费引擎）官方不提供剩余次数。所以本插件不编数字，只显示三类能证实的信息：限流窗口（还能不能用、多久恢复）、本机记账（这台机器实际用了几次）、带 key 时的真实余额。

徽章与面板

徽章状态

状态	徽章文字	含义
限流中	`免费搜索 · 15h57m 后恢复`	观测到过 Firecrawl keyless 的 429，倒计时到响应里 `retry_after_seconds` 给出的恢复时刻
有 key 余额	`免费搜索 · 剩余 842`	配了 Firecrawl / Tavily key 时显示真实剩余额度，取余额最低的那个引擎
可用	`免费搜索 · 可用`	上次观测时 keyless 可用（悬停显示本机今日调用次数）
未探测	`免费搜索 · 未探测`	还没有任何限流证据，只按本机记账显示今日次数
待连接	`免费搜索 · 待连接`	宿主半段没起来（快照请求失败）

明细卡片

点击徽章展开，自上而下：

Firecrawl keyless 状态：限流窗口 + 恢复的具体时刻，并注明是精确窗口（来自 429 的 retry_after_seconds）还是估算窗口（没有任何秒数时的 45 分钟兜底）。
本机今日调用：N 次，以及其中搜索 / 抓取各几次、出错几次。
本机本月调用、自设预算剩余（配了 dailyBudget 才有）、最近一次调用（工具名 + 时间）。
各引擎一行：Firecrawl、Tavily、Exa、Antigravity CLI 的可用性、真实余额（有 key 时）、以及一句说明。
modsearch 自身冷却：~/.modsearch/state.json 里的条目，明确标注「不是真实恢复时间」。
探测按钮：限流中显示「检测是否已恢复」（免费），可用时显示「试搜一次（会消耗额度）」。
数据来源脚注：三行，说明每个数字是怎么来的。

交互

点击徽章开 / 关卡片；Esc 或点击卡片外部关闭；键盘 Enter / Space 也能打开。
卡片 30 秒自动轮询一次；标签页切到后台时停止轮询，切回立即刷新。
卡片里的倒计时每秒走一格。
「刷新」按钮会强制重新查询带 key 的余额（绕过 5 分钟缓存）。

安装

前置条件：

DSH Web 形态（dsh.client.platform 为 web），登录态可访问 GUI。
建议同时装有 @liustack/modsearch（徽章监控的就是它的免费引擎）；没装也能用，只是引擎行会显示「未配置」。

方式 A：GUI 插件页安装（最省事）

在 DSH GUI 的插件管理里安装本地包：

plugin_manager install_bundle   target: link:/绝对路径/dsh-websearch-quota

或从 npm 装（已发布时）：

plugin_manager install_bundle   target: dsh-websearch-quota

装完确认它在 dsh.profile.bundles 里并且处于启用状态。

方式 B：命令行（非 Electron 托管的 profile）

dsh plugin --profile <profile名> add link:/绝对路径/dsh-websearch-quota

然后把包名加进该 profile package.json 的 dsh.profile.bundles 数组：

{
  "dependencies": {
    "dsh-websearch-quota": "link:/绝对路径/dsh-websearch-quota"
  },
  "dsh": {
    "profile": {
      "bundles": ["...", "dsh-websearch-quota"]
    }
  }
}

只加依赖、不加 bundle 时状态是 installed: true, enabled: false——包在，但不会加载。

方式 C：手工编辑（Electron App 托管的 profile）

Electron App 独占管理自己的 profile，dsh plugin --profile desktop ... 会被拒绝：

profile "desktop" is managed exclusively by the Electron application

改 ${DSH_HOME}/profiles/<profile>/package.json 即可（上面方式 B 的两处改动），保存后 App 会热应用：

宿主半段注册路由（诊断日志出现 route-registered）；
浏览器半段注册到 conversation.composer.dock。

改动前建议备份 package.json；撤销时还原备份并刷新页面。

启用 / 禁用 / 卸载

操作	做法
禁用	插件页关闭，或从 `dsh.profile.bundles` 里删掉包名
卸载	插件页卸载，或删依赖 + 删 bundle 条目 + 删 `node_modules` 里的链接
保留账本	卸载不会删 `<DSH_HOME>/websearch-quota/state.json`，需要清空请手动删

配置

配置写在 bundle 行上（cordis.patch.yml 的 config: 块），全部可选：

- insert:
    - id: dsh-websearch-quota
      name: 'dsh-websearch-quota'
      config:
        dailyBudget: 50
        probeEnabled: true

键	默认	作用
`dailyBudget`	`null`	自设每日预算（次数），面板显示「剩余 X / N」
`probeEnabled`	`true`	`false` 隐藏探测按钮，`POST /probe` 返回 403
`probeMinIntervalMs`	`30000`	两次探测的最小间隔
`keyQuotaTtlMs`	`300000`	带 key 真实余额的缓存时长（5 分钟）
`trackTools`	`["web_search","web_fetch","x_search","read_page"]`	计入账本的工具集合
`stateFile`	`<DSH_HOME>/websearch-quota/state.json`	本地账本路径
`modsearchConfigPath`	`~/.modsearch/config.json`	读 API key 的位置
`modsearchStatePath`	`~/.modsearch/state.json`	读 modsearch 冷却的位置

工具 → 用途的归类：web_search → 搜索，x_search → X 搜索，web_fetch / read_page → 抓取。

数据来源与诚实边界

1. Firecrawl keyless：没有剩余次数可读

响应头里没有 x-ratelimit-*；
keyless 调 GET /v2/team/credit-usage 返回 401 This endpoint is not supported by the keyless free tier；
上限官方只说是「每 IP 每天」（requests 与 credits 双限额），数值从未公布。

所以插件对 keyless 只做两件事：

解析 429：从响应体 / 头里取 retry_after_seconds（也支持 Resets in 16h47m、try again in 90 seconds 等写法），得到恢复时刻；一个秒数都取不到时才用 45 分钟估算，并在面板里标注「约」。
本机记账：tools/result 事件里观测到的 web 工具调用，跨会话累计。

网上常见的「modsearch keyless 1000 次/月」其实是 Firecrawl 带 key 的 Free plan 额度，不是 keyless 层。

2. `~/.modsearch/state.json` 的冷却不能当配额源

modsearch 把 keyless 的普通 429 归类成「持续性限额」时，会写一个固定 45 分钟的冷却（DEFAULT_COOLDOWN_MS），而不是真实恢复时间；cooldown: "off" 还能整体关掉。插件把这份冷却放在「参考」一栏并明确标注；徽章用的是自己观测到的窗口，两者冲突时以前者为准。

3. 带 key 才有真实余额

引擎	接口	字段
Firecrawl	`GET https://api.firecrawl.dev/v2/team/credit-usage`	`data.remainingCredits` / `data.planCredits` / 账期
Tavily	`GET https://api.tavily.com/usage`	`key.usage` / `key.limit` / `account.plan_usage` / `account.plan_limit`
Exa	—	无公开余额接口（唯一 usage API 需要 Team Management 的 service key）

key 的读取顺序：~/.modsearch/config.json 的 engines.<engine>.apiKey（支持逗号分隔多个 key，取第一个）→ 环境变量 FIRECRAWL_API_KEY / TAVILY_API_KEY / EXA_API_KEY。

4. 计量范围

账本只统计本机、本 DSH profile、本插件安装之后的调用。别的机器、别的客户端、直接 curl 的调用都不在内。

本地状态与隐私

账本写在 <DSH_HOME>/websearch-quota/state.json（DSH_HOME 默认 ~/.dsh），只在本机，不上传任何地方；写入是原子写（先写 .tmp 再 rename），并且 1.5 秒防抖。
记录内容只有：日期分桶的调用计数、最近调用时间、限流窗口与一段特征文本（evidence，截断到 240 字符）。
所有对外字符串都会过 redactSecrets：fc- / tvly- / exa- / sk- 前缀的 key 以及 32 字符以上的长串会被替换成 ***。API key 本身从不写入账本、从不返回给浏览器。
诊断日志 $TMPDIR/dsh-websearch-quota.log 一行一事件，只记事件名与必要的错误信息，永不抛错。

HTTP 接口

挂载在宿主 webServer 上的 prefix 路由，每个 handler 都自己复核对端是回环 socket（connection.requestRejection），并沿用宿主的 Host / Origin 与会话校验：

方法	路径	说明
`GET`	`/websearch-quota`	快照（限流窗口、账本、真实余额、modsearch 冷却）
`GET`	`/websearch-quota/health`	同上（探活）
`GET`	`/websearch-quota?refresh=1`	强制刷新带 key 的余额（绕过缓存）
`POST`	`/websearch-quota/probe`	手动探测一次 Firecrawl keyless（受 `probeMinIntervalMs` 节流）

快照主要字段：

{
  "ok": true,
  "version": "0.1.0",
  "now": 1791882532528,
  "ledger": {
    "today": { "day": "2026-10-13", "calls": 2, "search": 2, "fetch": 0, "x": 0, "errors": 1, "credits": null },
    "monthCalls": 2, "allTime": 2, "trackedDays": 1,
    "lastCallAt": 1791882532528, "lastSuccessAt": null,
    "dailyBudget": null, "remainingToday": null
  },
  "keyless": {
    "state": "limited",              // limited | ok | unknown
    "until": 1791940002528,
    "remainingMs": 57470000,
    "exact": true,                    // false = 45 分钟估算窗口
    "source": "tool-result",          // tool-result | probe
    "evidence": "…429 body…",
    "probe": { "enabled": true, "running": false, "lastAt": 1791882469000, "lastStatus": 429, "lastMessage": "…", "allowedInMs": 0 }
  },
  "engines": [
    { "id": "firecrawl", "kind": "keyless", "status": "limited", "remaining": null, "limit": null, "detail": "16h47m 后恢复（09:06）", "note": "官方未公开 keyless 每日剩余额度；search ≈ 2 credits / 10 条，scrape 1 credit" }
    // tavily / exa / agy 同理：status ∈ ok | limited | unknown | error | missing-key | missing
  ],
  "modsearch": { "configFound": false, "engine": null, "keylessFetch": null, "keysConfigured": [], "cooldowns": [] },
  "config": { "dailyBudget": null, "trackTools": ["…"], "keyQuotaTtlMs": 300000 },
  "paths": { "stateFile": "…", "modsearchConfig": "…", "diagnostics": "…" },
  "sources": ["…三行数据来源…"]
}

错误码：401/403 unauthorized（非回环 / 会话校验失败）、403 probe-disabled、405 method-not-allowed（探测用了 GET）、429 rate-limited（探测太频繁）、404 unknown-action。

故障排查

症状	原因	处理
徽章一直是「待连接」	宿主半段没加载，或快照请求被拒	看 `$TMPDIR/dsh-websearch-quota.log` 有没有 `route-registered`；确认包在 `dsh.profile.bundles` 里且启用
完全没有徽章	浏览器半段没加载	刷新页面；确认 App 日志里 client bundle 被加载（`dsh.client.platform: web`）
徽章显示「未探测」很久	确实没遇到过 429，也没有 key	正常状态；想看当前能不能用就点「试搜一次」
探测按钮返回 429	探测太频繁（默认 30 秒）或 keyless 真在限流	等倒计时结束；`rate-limited` 是插件自己的节流
探测按钮返回 403	`probeEnabled: false`	改配置为 `true`
带 key 余额显示「查询失败」	key 无效 / 网络不通 / 该 key 权限不足	面板会显示厂商返回的原文（已脱敏）；`?refresh=1` 重试
账本数字比实际少	只统计 `trackTools` 里的工具，且只从现在开始	用 `trackTools` 加工具；历史调用无法回溯
profile 的 pnpm 装不上	例如 `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION`	与该包无关；按 pnpm 提示 `pnpm clean --lockfile && pnpm install` 重建 lockfile，或直接用 `link:` 本地安装

开发与测试

npm test     # quota 16 例 + host 10 例 + client 44 项检查

Node 24 下 node --test test/ 会把目录当模块解析（MODULE_NOT_FOUND），所以脚本里写死了测试文件。

文件	职责
`lib/quota.js`	纯逻辑：工具名归类、限流特征识别与窗口解析、账本聚合、格式化、脱敏。无 IO、无 DSH 依赖
`lib/index.js`	宿主半段：`tools/result` 观察者、本地账本落盘、厂商余额查询、`webServer` 路由
`lib/client.js`	浏览器半段：手写 lazy-CJS（`window.__ModuleLoader__.load`），`ctx.inject(['slots'])` 注册徽章，无构建步骤

改动的生效方式：

lib/client.js：刷新页面即可（bundle 版本按 mtime/size 计算）。
lib/index.js：宿主 ESM 模块有缓存，需重启 App（或重启 dsh web）。重新安装/禁用再启用不会命中新代码。

数据流：

tools/result (web_search / web_fetch / x_search / read_page)
        │
        ├─→ applyCall()  ──→ state.json（账本 + 429 窗口）
        │
GET /websearch-quota ──→ snapshot() ──→ 徽章 + 明细卡片
POST /websearch-quota/probe ──→ applyProbe() ──→ state.json

许可证

MIT

兼容性与来源证明

Websearch Quota 以 dsh-websearch-quota 发布，当前版本为 0.1.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。

DSH 兼容范围: *
运行环境: web
发布来源: github
Registry 更新时间: 2026/10/20

版本

0.1.0stable

2026/10/20

README

dsh-websearch-quota

基于 modsearch 做的免费额度次数查询的小插件。

给 DSH（DeepSeek Harness）Web GUI 加一个常驻小徽章，回答一个问题：这台机器现在还能免费用多少次 web 搜索？

徽章挂在输入框下方的环境行（client slot conversation.composer.dock），点开是一张明细卡片：限流窗口、本机记账、真实余额、手动探测。

┌─ 输入框 ─────────────────────────────────────────────┐
│                                                      │
└──────────────────────────────────────────────────────┘
 ● 免费搜索 · 15h57m 后恢复        ← 徽章（常驻）

一句话立场：Firecrawl keyless（@liustack/modsearch 的默认免费引擎）官方不提供剩余次数。所以本插件不编数字，只显示三类能证实的信息：限流窗口（还能不能用、多久恢复）、本机记账（这台机器实际用了几次）、带 key 时的真实余额。

徽章与面板

徽章状态

状态	徽章文字	含义
限流中	`免费搜索 · 15h57m 后恢复`	观测到过 Firecrawl keyless 的 429，倒计时到响应里 `retry_after_seconds` 给出的恢复时刻
有 key 余额	`免费搜索 · 剩余 842`	配了 Firecrawl / Tavily key 时显示真实剩余额度，取余额最低的那个引擎
可用	`免费搜索 · 可用`	上次观测时 keyless 可用（悬停显示本机今日调用次数）
未探测	`免费搜索 · 未探测`	还没有任何限流证据，只按本机记账显示今日次数
待连接	`免费搜索 · 待连接`	宿主半段没起来（快照请求失败）

明细卡片

点击徽章展开，自上而下：

Firecrawl keyless 状态：限流窗口 + 恢复的具体时刻，并注明是精确窗口（来自 429 的 retry_after_seconds）还是估算窗口（没有任何秒数时的 45 分钟兜底）。
本机今日调用：N 次，以及其中搜索 / 抓取各几次、出错几次。
本机本月调用、自设预算剩余（配了 dailyBudget 才有）、最近一次调用（工具名 + 时间）。
各引擎一行：Firecrawl、Tavily、Exa、Antigravity CLI 的可用性、真实余额（有 key 时）、以及一句说明。
modsearch 自身冷却：~/.modsearch/state.json 里的条目，明确标注「不是真实恢复时间」。
探测按钮：限流中显示「检测是否已恢复」（免费），可用时显示「试搜一次（会消耗额度）」。
数据来源脚注：三行，说明每个数字是怎么来的。

交互

点击徽章开 / 关卡片；Esc 或点击卡片外部关闭；键盘 Enter / Space 也能打开。
卡片 30 秒自动轮询一次；标签页切到后台时停止轮询，切回立即刷新。
卡片里的倒计时每秒走一格。
「刷新」按钮会强制重新查询带 key 的余额（绕过 5 分钟缓存）。

安装

前置条件：

DSH Web 形态（dsh.client.platform 为 web），登录态可访问 GUI。
建议同时装有 @liustack/modsearch（徽章监控的就是它的免费引擎）；没装也能用，只是引擎行会显示「未配置」。

方式 A：GUI 插件页安装（最省事）

在 DSH GUI 的插件管理里安装本地包：

plugin_manager install_bundle   target: link:/绝对路径/dsh-websearch-quota

或从 npm 装（已发布时）：

plugin_manager install_bundle   target: dsh-websearch-quota

装完确认它在 dsh.profile.bundles 里并且处于启用状态。

方式 B：命令行（非 Electron 托管的 profile）

dsh plugin --profile <profile名> add link:/绝对路径/dsh-websearch-quota

然后把包名加进该 profile package.json 的 dsh.profile.bundles 数组：

{
  "dependencies": {
    "dsh-websearch-quota": "link:/绝对路径/dsh-websearch-quota"
  },
  "dsh": {
    "profile": {
      "bundles": ["...", "dsh-websearch-quota"]
    }
  }
}

只加依赖、不加 bundle 时状态是 installed: true, enabled: false——包在，但不会加载。

方式 C：手工编辑（Electron App 托管的 profile）

Electron App 独占管理自己的 profile，dsh plugin --profile desktop ... 会被拒绝：

profile "desktop" is managed exclusively by the Electron application

改 ${DSH_HOME}/profiles/<profile>/package.json 即可（上面方式 B 的两处改动），保存后 App 会热应用：

宿主半段注册路由（诊断日志出现 route-registered）；
浏览器半段注册到 conversation.composer.dock。

改动前建议备份 package.json；撤销时还原备份并刷新页面。

启用 / 禁用 / 卸载

操作	做法
禁用	插件页关闭，或从 `dsh.profile.bundles` 里删掉包名
卸载	插件页卸载，或删依赖 + 删 bundle 条目 + 删 `node_modules` 里的链接
保留账本	卸载不会删 `<DSH_HOME>/websearch-quota/state.json`，需要清空请手动删

配置

配置写在 bundle 行上（cordis.patch.yml 的 config: 块），全部可选：

- insert:
    - id: dsh-websearch-quota
      name: 'dsh-websearch-quota'
      config:
        dailyBudget: 50
        probeEnabled: true

键	默认	作用
`dailyBudget`	`null`	自设每日预算（次数），面板显示「剩余 X / N」
`probeEnabled`	`true`	`false` 隐藏探测按钮，`POST /probe` 返回 403
`probeMinIntervalMs`	`30000`	两次探测的最小间隔
`keyQuotaTtlMs`	`300000`	带 key 真实余额的缓存时长（5 分钟）
`trackTools`	`["web_search","web_fetch","x_search","read_page"]`	计入账本的工具集合
`stateFile`	`<DSH_HOME>/websearch-quota/state.json`	本地账本路径
`modsearchConfigPath`	`~/.modsearch/config.json`	读 API key 的位置
`modsearchStatePath`	`~/.modsearch/state.json`	读 modsearch 冷却的位置

工具 → 用途的归类：web_search → 搜索，x_search → X 搜索，web_fetch / read_page → 抓取。

数据来源与诚实边界

1. Firecrawl keyless：没有剩余次数可读

响应头里没有 x-ratelimit-*；
keyless 调 GET /v2/team/credit-usage 返回 401 This endpoint is not supported by the keyless free tier；
上限官方只说是「每 IP 每天」（requests 与 credits 双限额），数值从未公布。

所以插件对 keyless 只做两件事：

解析 429：从响应体 / 头里取 retry_after_seconds（也支持 Resets in 16h47m、try again in 90 seconds 等写法），得到恢复时刻；一个秒数都取不到时才用 45 分钟估算，并在面板里标注「约」。
本机记账：tools/result 事件里观测到的 web 工具调用，跨会话累计。

网上常见的「modsearch keyless 1000 次/月」其实是 Firecrawl 带 key 的 Free plan 额度，不是 keyless 层。

2. `~/.modsearch/state.json` 的冷却不能当配额源

3. 带 key 才有真实余额

引擎	接口	字段
Firecrawl	`GET https://api.firecrawl.dev/v2/team/credit-usage`	`data.remainingCredits` / `data.planCredits` / 账期
Tavily	`GET https://api.tavily.com/usage`	`key.usage` / `key.limit` / `account.plan_usage` / `account.plan_limit`
Exa	—	无公开余额接口（唯一 usage API 需要 Team Management 的 service key）

4. 计量范围

账本只统计本机、本 DSH profile、本插件安装之后的调用。别的机器、别的客户端、直接 curl 的调用都不在内。

本地状态与隐私

账本写在 <DSH_HOME>/websearch-quota/state.json（DSH_HOME 默认 ~/.dsh），只在本机，不上传任何地方；写入是原子写（先写 .tmp 再 rename），并且 1.5 秒防抖。
记录内容只有：日期分桶的调用计数、最近调用时间、限流窗口与一段特征文本（evidence，截断到 240 字符）。
所有对外字符串都会过 redactSecrets：fc- / tvly- / exa- / sk- 前缀的 key 以及 32 字符以上的长串会被替换成 ***。API key 本身从不写入账本、从不返回给浏览器。
诊断日志 $TMPDIR/dsh-websearch-quota.log 一行一事件，只记事件名与必要的错误信息，永不抛错。

HTTP 接口

挂载在宿主 webServer 上的 prefix 路由，每个 handler 都自己复核对端是回环 socket（connection.requestRejection），并沿用宿主的 Host / Origin 与会话校验：

方法	路径	说明
`GET`	`/websearch-quota`	快照（限流窗口、账本、真实余额、modsearch 冷却）
`GET`	`/websearch-quota/health`	同上（探活）
`GET`	`/websearch-quota?refresh=1`	强制刷新带 key 的余额（绕过缓存）
`POST`	`/websearch-quota/probe`	手动探测一次 Firecrawl keyless（受 `probeMinIntervalMs` 节流）

快照主要字段：

{
  "ok": true,
  "version": "0.1.0",
  "now": 1791882532528,
  "ledger": {
    "today": { "day": "2026-10-13", "calls": 2, "search": 2, "fetch": 0, "x": 0, "errors": 1, "credits": null },
    "monthCalls": 2, "allTime": 2, "trackedDays": 1,
    "lastCallAt": 1791882532528, "lastSuccessAt": null,
    "dailyBudget": null, "remainingToday": null
  },
  "keyless": {
    "state": "limited",              // limited | ok | unknown
    "until": 1791940002528,
    "remainingMs": 57470000,
    "exact": true,                    // false = 45 分钟估算窗口
    "source": "tool-result",          // tool-result | probe
    "evidence": "…429 body…",
    "probe": { "enabled": true, "running": false, "lastAt": 1791882469000, "lastStatus": 429, "lastMessage": "…", "allowedInMs": 0 }
  },
  "engines": [
    { "id": "firecrawl", "kind": "keyless", "status": "limited", "remaining": null, "limit": null, "detail": "16h47m 后恢复（09:06）", "note": "官方未公开 keyless 每日剩余额度；search ≈ 2 credits / 10 条，scrape 1 credit" }
    // tavily / exa / agy 同理：status ∈ ok | limited | unknown | error | missing-key | missing
  ],
  "modsearch": { "configFound": false, "engine": null, "keylessFetch": null, "keysConfigured": [], "cooldowns": [] },
  "config": { "dailyBudget": null, "trackTools": ["…"], "keyQuotaTtlMs": 300000 },
  "paths": { "stateFile": "…", "modsearchConfig": "…", "diagnostics": "…" },
  "sources": ["…三行数据来源…"]
}

故障排查

症状	原因	处理
徽章一直是「待连接」	宿主半段没加载，或快照请求被拒	看 `$TMPDIR/dsh-websearch-quota.log` 有没有 `route-registered`；确认包在 `dsh.profile.bundles` 里且启用
完全没有徽章	浏览器半段没加载	刷新页面；确认 App 日志里 client bundle 被加载（`dsh.client.platform: web`）
徽章显示「未探测」很久	确实没遇到过 429，也没有 key	正常状态；想看当前能不能用就点「试搜一次」
探测按钮返回 429	探测太频繁（默认 30 秒）或 keyless 真在限流	等倒计时结束；`rate-limited` 是插件自己的节流
探测按钮返回 403	`probeEnabled: false`	改配置为 `true`
带 key 余额显示「查询失败」	key 无效 / 网络不通 / 该 key 权限不足	面板会显示厂商返回的原文（已脱敏）；`?refresh=1` 重试
账本数字比实际少	只统计 `trackTools` 里的工具，且只从现在开始	用 `trackTools` 加工具；历史调用无法回溯
profile 的 pnpm 装不上	例如 `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION`	与该包无关；按 pnpm 提示 `pnpm clean --lockfile && pnpm install` 重建 lockfile，或直接用 `link:` 本地安装

开发与测试

npm test     # quota 16 例 + host 10 例 + client 44 项检查

Node 24 下 node --test test/ 会把目录当模块解析（MODULE_NOT_FOUND），所以脚本里写死了测试文件。

文件	职责
`lib/quota.js`	纯逻辑：工具名归类、限流特征识别与窗口解析、账本聚合、格式化、脱敏。无 IO、无 DSH 依赖
`lib/index.js`	宿主半段：`tools/result` 观察者、本地账本落盘、厂商余额查询、`webServer` 路由
`lib/client.js`	浏览器半段：手写 lazy-CJS（`window.__ModuleLoader__.load`），`ctx.inject(['slots'])` 注册徽章，无构建步骤

改动的生效方式：

lib/client.js：刷新页面即可（bundle 版本按 mtime/size 计算）。
lib/index.js：宿主 ESM 模块有缓存，需重启 App（或重启 dsh web）。重新安装/禁用再启用不会命中新代码。

数据流：

tools/result (web_search / web_fetch / x_search / read_page)
        │
        ├─→ applyCall()  ──→ state.json（账本 + 429 窗口）
        │
GET /websearch-quota ──→ snapshot() ──→ 徽章 + 明细卡片
POST /websearch-quota/probe ──→ applyProbe() ──→ state.json

许可证

MIT

Websearch Quota

兼容性与来源证明

版本

相关插件

Websearch Quota

README

dsh-websearch-quota

目录

徽章与面板

徽章状态

明细卡片

交互

安装

方式 A：GUI 插件页安装（最省事）

方式 B：命令行（非 Electron 托管的 profile）

方式 C：手工编辑（Electron App 托管的 profile）

启用 / 禁用 / 卸载

配置

数据来源与诚实边界

1. Firecrawl keyless：没有剩余次数可读

2. ~/.modsearch/state.json 的冷却不能当配额源

3. 带 key 才有真实余额

4. 计量范围

本地状态与隐私

HTTP 接口

故障排查

开发与测试

许可证

兼容性与来源证明

版本

相关插件

相关插件

相关插件

README

dsh-websearch-quota

目录

徽章与面板

徽章状态

明细卡片

交互

安装

方式 A：GUI 插件页安装（最省事）

方式 B：命令行（非 Electron 托管的 profile）

方式 C：手工编辑（Electron App 托管的 profile）

启用 / 禁用 / 卸载

配置

数据来源与诚实边界

1. Firecrawl keyless：没有剩余次数可读

2. ~/.modsearch/state.json 的冷却不能当配额源

3. 带 key 才有真实余额

4. 计量范围

本地状态与隐私

HTTP 接口

故障排查

开发与测试

许可证

2. `~/.modsearch/state.json` 的冷却不能当配额源

2. `~/.modsearch/state.json` 的冷却不能当配额源