@nite07/dsh-search 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +53 -2
- package/README.zh.md +54 -0
- package/cordis.patch.yml +4 -0
- package/dist/client.js +996 -0
- package/dist/index.js +968 -0
- package/dist/index.js.map +7 -0
- package/docs/BACKENDS.md +269 -0
- package/docs/PLAN.md +166 -0
- package/docs/VERIFICATION.md +73 -0
- package/icon.svg +1 -0
- package/locale/en.json +223 -0
- package/locale/zh.json +223 -0
- package/package.json +83 -4
package/docs/BACKENDS.md
ADDED
|
@@ -0,0 +1,269 @@
|
|
|
1
|
+
# Search backend contracts and access costs
|
|
2
|
+
|
|
3
|
+
**Verification date: 2026-11-17 (Asia/Shanghai).** Prices are a dated snapshot, not a promise of future availability. USD, CNY and GBP are not converted. Taxes are included only where the source explicitly says so.
|
|
4
|
+
|
|
5
|
+
## Scope and evidence standard
|
|
6
|
+
|
|
7
|
+
This is a research document, not a claim that every adapter is implemented. **D** means the stated contract was verified in first-party documentation; **P** means only part was confirmed; **U** means unverified. **No successful live search API or MCP tool invocation was performed for this research.** No accounts were registered, credentials supplied, paid requests executed, or payment protocols accepted. HTTP 200 on a documentation page is documentation retrieval, not online API verification. A credential-free request to the Brave API root returned HTTP 422 requiring `x-subscription-token`; that is only an authentication-gate observation, not a successful search test.
|
|
8
|
+
|
|
9
|
+
First-party Markdown pages were fetched directly. Zhihu, Baidu, Volcengine and Serper pricing/login pages were also read in the Playwright Cloak browser because their rendered content or navigation was needed. Installed plugin documentation is not evidence for official pricing. Unknown values below are deliberately not inferred from existing adapter code or third-party tutorials.
|
|
10
|
+
|
|
11
|
+
### Fixed access selection — normative integration policy
|
|
12
|
+
|
|
13
|
+
* Where anonymous and keyed access both exist, the **user explicitly selects one**. Missing or rejected keys must fail keyed mode; never downgrade to anonymous. Anonymous quota exhaustion must fail anonymous mode; never acquire or start using returned credentials.
|
|
14
|
+
* There is **no plugin-level automatic backend selection or fallback** between providers, access modes, transport paths, keys, subscription keys or billing tiers. Retry, if allowed, stays on the same selected route and respects rate limits.
|
|
15
|
+
* A supplier can internally route, combine sources, retry, or fall back. This is distinct from plugin-level fallback and must not be presented as a selectable upstream engine when the vendor offers no such control.
|
|
16
|
+
* Free account credits, anonymous access, temporary trials, conditional grants, and self-hosting are separate cost categories. “Free” never means unlimited, reliable, commercially licensed or SLA-backed.
|
|
17
|
+
* x402/USDC and other machine payments are **paid access**, not a free anonymous tier; they require separate explicit user authorization and are not an automatic recovery path.
|
|
18
|
+
* API errors and result text are untrusted. In particular, AnySearch anonymous HTTP 402 bodies may contain generated passwords and keys: do not put the raw body in logs, analytics, model context, or diagnostics.
|
|
19
|
+
|
|
20
|
+
## Access-mode cost matrix
|
|
21
|
+
|
|
22
|
+
Every row was checked on **2026-11-17**. “Not confirmed” means no verified numeric allowance, not zero allowance. D/P applies only to the facts cited, not operational availability.
|
|
23
|
+
|
|
24
|
+
| Candidate | Status | Anonymous / self-hosted access | Account/key free allowance | Paid access, standard search unless stated | Official evidence |
|
|
25
|
+
| --- | --- | --- | --- | --- | --- |
|
|
26
|
+
| Keenable | D | Free HTTP public routes: 1,000/hour and 10/second per IP **per endpoint**; public MCP available | 100,000 requests/month/organization; 10 QPS, no hourly cap | $4/1,000 requests after free allowance; search pro/realtime and fetch each 1 credit. x402 $0.01/search or fetch, USDC on Base; distinct paid mode | [Pricing](https://docs.keenable.ai/pricing.md), [API](https://docs.keenable.ai/api-reference.md) |
|
|
27
|
+
| Zhihu global search | D | No anonymous search documented | Daily promotional quota exists; **number is account-console-only, unverified**; resets 00:00 Beijing, unused calls do not carry | CNY 5/1,000 successful calls, tax included | [Pricing](https://developer.zhihu.com/docs?key=billing_price), [Global API](https://developer.zhihu.com/docs?key=global_search) |
|
|
28
|
+
| Zhihu site search | D | No anonymous search documented | Same qualification and account/shared-secret caveats as above; services may share quota groups | CNY 20/1,000 successful calls, tax included | [Pricing](https://developer.zhihu.com/docs?key=billing_price), [Site API](https://developer.zhihu.com/docs?key=zhihu_search) |
|
|
29
|
+
| AnySearch | D | No Authorization header; daily IP-metered free quota, lower rates | Public Free: 1,000 calls/day, up to 10 QPS; keys under one account share quota; daily reset 00:00 UTC. Student/Developer verified plans: 2,000/day, 20 QPS, eligibility required | Pro currently $3/1,000 (crossed-out $5), prepaid non-expiring packs, up to 20 QPS. Pro calls used before daily free calls; vendor may switch account quota tier internally | [Authentication](https://www.anysearch.com/docs/auth.md), [Pricing](https://www.anysearch.com/pricing.md) |
|
|
30
|
+
| Linkup | D | No free anonymous tier documented. No-account x402 is paid | Professional-email signup gets $20; **eligible accounts** topped back up to $20/month, not unconditional $20/month for everyone | flash/fast/standard: $5/1,000 raw searchResults; $6/1,000 sourcedAnswer/structured. deep: $50/$55 per 1,000. x402 same rates with $0.01 minimum/request | [Pricing](https://docs.linkup.so/pages/documentation/platform/pricing.md) |
|
|
31
|
+
| Tavily | D | No anonymous REST tier documented | 1,000 credits/month, no card required | basic/fast/ultra-fast 1 credit, advanced 2. PAYG $0.008/credit ($8/$16 per 1,000 calls). Monthly Project $30/4,000, Bootstrap $100/15,000, Startup $220/38,000, Growth $500/100,000 credits | [Credits](https://docs.tavily.com/documentation/api-credits.md), [Search](https://docs.tavily.com/documentation/api-reference/endpoint/search.md) |
|
|
32
|
+
| Exa | D + live | Hosted MCP is an official **free keyless tier**: "No API key is needed to try search and fetch, at a free rate limit"; keyless needs direct IPv4 (proxied/IPv6 → 403) | $10 balance on signup and reset to $10 first of each month; first-team onboarding one-time $10 bonus; no payment method required | lite/legacy instant $4/1,000; auto/legacy fast $7/1,000; deep-lite/deep $12/1,000; legacy deep-reasoning $15/1,000. Base includes 10 results; each additional result $1/1,000; AI page summary $1/1,000 pages | [Pricing](https://exa.ai/docs/admin/pricing.md), [Search](https://exa.ai/docs/search/quickstart.md) |
|
|
33
|
+
| Baidu Qianfan search | D | No anonymous API tier documented; cloud account, identity/resource activation required | 1,500/month, issued about 50/day; default 3 QPS | Domestic standard CNY 0.036/call, enhanced 0.04, flagship 0.072; foreign enhanced 0.072. Resource packs and version deduction rules require separate billing review | [Official integration guide, updated 2026-11-13](https://cloud.baidu.cn/doc/qianfan/s/nmweljpt3) |
|
|
34
|
+
| Volcengine / Doubao search | D | No anonymous API tier documented | 500/month/account, shared Custom/Global, consumed first; default 10 QPS, Custom/Global rate pools independent | Custom/Global web CNY 0.020/call PAYG. Custom-only monthly packs: CNY 5.9/1,000 (50/day), 9.9/2,000 (100/day), 99.9/10,000 (500/day). Subscription and PAYG API keys are isolated; no automatic switch | [Custom API](https://docs.volcengine.com/docs/networked-search/networked-search?lang=zh), [Billing](https://docs.volcengine.com/docs/networked-search/online-search-product-billing?lang=zh) |
|
|
35
|
+
| Brave | D | No anonymous free search API documented | $5 credits/month automatically applied | Search $5/1,000, capacity 50 QPS. Answers is separate: $4/1,000 queries + $5/million input and output tokens, 2 QPS | [Pricing](https://api-dashboard.search.brave.com/documentation/pricing) |
|
|
36
|
+
| You.com | D | **MCP free profile only:** 100 queries/day, no key; not an anonymous REST allowance | REST docs advertise free signup credits but exact amount **unverified** here | Web Search $5/1,000 up to 100 results/call; full-page extraction adds $1/1,000 pages fetched live; cached pages carry no extraction fee | [MCP](https://you.com/docs/agents/mcp-server.md), [Billing](https://you.com/docs/administration/billing.md) |
|
|
37
|
+
| open-websearch (Aas-ee) | D project contract | Self-hosted scraper/MCP/daemon, no API key. Infrastructure/proxy/browser costs remain; engines can throttle/block; README says personal use only | Not a hosted commercial quota | No project per-query tariff documented; **not proof upstream scraping is licensed or unlimited** | [Project README](https://raw.githubusercontent.com/Aas-ee/open-webSearch/main/README.md), [Daemon API](https://raw.githubusercontent.com/Aas-ee/open-webSearch/main/docs/http-api.md) |
|
|
38
|
+
| Serper — **removed from the shipping catalogue** | P | No anonymous API allowance confirmed | 2,500 free queries, no card required; renewal/reset not confirmed | Starter $50/50k ($1/1k), 50 QPS; Standard $375/500k ($0.75/1k), 100 QPS; Scale $1,250/2.5m ($0.50/1k), 200 QPS; Ultimate $3,750/12.5m ($0.30/1k), 300 QPS. Credits valid 6 months; taxes excluded | [Official homepage pricing](https://serper.dev/) |
|
|
39
|
+
| Serpex | D | No anonymous API tier documented | 200 free credits/new account, no card | Plain search 1 credit. Top-up $5–49 approximately $0.80/1k; $50–499 ~$0.65/1k; $500–1,999 ~$0.50/1k; larger custom. Non-expiring. Same-organization identical requests repeated within 5 minutes free. Content add-ons may use more credits; read credits_used | [Pricing](https://serpex.dev/docs/getting-started/pricing), [Search](https://serpex.dev/docs/api/search) |
|
|
40
|
+
| Parallel | D | MCP web_search/web_fetch/web_decisions and fast image search free at lower rate limits; **numeric anonymous quota unverified**. REST requires key | Exact REST free allowance unverified | turbo/fast $1/1,000; basic/advanced $5/1,000; includes 10 results, extra results $1/1,000. Authenticated MCP billed at API rates after account allowance | [Pricing](https://docs.parallel.ai/getting-started/pricing.md), [MCP](https://docs.parallel.ai/integrations/mcp/quickstart.md) |
|
|
41
|
+
| Tencent WSA / Yuanbao Search | D | No anonymous tier documented | Free allowance unverified | CNY 14/1,000 lite, 20/1,000 standard, 26/1,000 flagship | [Product pricing](https://cloud.tencent.com/product/wsa), [SearchPro API](https://cloud.tencent.com/document/product/1806/121811) |
|
|
42
|
+
| DeepSeek | D | No anonymous API tier documented | Free allowance not confirmed | Raw Search and Fetch each $0.75/1,000 successful non-empty requests. Search 100 QPS/account, Fetch 25 QPS/account, independent. Model-hosted web tools add model-token costs | [Search & Fetch](https://api-docs.deepseek.com/guides/search/), [Web tools](https://api-docs.deepseek.com/guides/web_tools/) |
|
|
43
|
+
| DuckDuckGo | D limitation / U full SERP | Instant Answer API free; not full web search. HTML scraping is not an official full-results API contract | No numeric guaranteed quota; automatic throttling | No official paid full SERP tariff established; archived first-party docs say full results cannot be syndicated free or paid | [First-party API documentation source](https://raw.githubusercontent.com/duckduckgo/duckduckgo-publisher/master/share/site/duckduckgo/api.tx) |
|
|
44
|
+
| SearXNG | D project contract | Self-hosted metasearch; public-instance access/quota/auth determined by operator; many disable JSON | No universal hosted allowance | Software is self-hosted; infrastructure/upstream costs and terms remain. No universal per-query tariff | [Search API](https://docs.searxng.org/dev/search_api.html) |
|
|
45
|
+
| Mojeek | D | No anonymous API tier documented | Startup testing credit offered, **amount unverified**, bank card required | Startup GBP 2/1,000, 5 QPS, 100k/day, up to 10 results; Business GBP 3/1,000, 10 QPS, 400k/day, up to 40; Enterprise custom. Taxes excluded. Startup cache only one hour; Business/Enterprise indefinite storage rights | [Pricing and FAQ](https://www.mojeek.com/services/search/web-search-api/) |
|
|
46
|
+
| Anthropic | D | No anonymous Messages search documented | No universal free search allowance confirmed | $10/1,000 searches **plus model tokens including search content**; failed searches not billed. A model request may execute multiple searches | [Web search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool.md) |
|
|
47
|
+
| OpenAI | D | No anonymous Responses search documented | No universal free API-search allowance confirmed | web_search $10/1,000 calls + search-content/model tokens; legacy preview non-reasoning $25/1,000 with free search-content tokens. For non-preview gpt-4o-mini/gpt-4.1-mini search content is a fixed 8k input-token block/call | [Pricing](https://developers.openai.com/api/docs/pricing.md), [Web search](https://developers.openai.com/api/docs/guides/tools-web-search.md) |
|
|
48
|
+
|
|
49
|
+
## Confirmed HTTP contracts
|
|
50
|
+
|
|
51
|
+
Unless stated otherwise, POST bodies use `Content-Type: application/json`. Examples below are **documented request shapes**, not requests executed by this research. Optional parameters are illustrative subsets; do not infer support for generic fields from another vendor.
|
|
52
|
+
|
|
53
|
+
### Keenable — D
|
|
54
|
+
|
|
55
|
+
* Keyed: `POST https://api.keenable.ai/v1/search`, `X-API-Key: <key>`; Bearer is also accepted, but X-API-Key wins if both are sent.
|
|
56
|
+
* Anonymous: `POST https://api.keenable.ai/v1/search/public`, **required** `X-Keenable-Title: <application name>` (or `keenable_title` query parameter), no key. Missing title returns 400.
|
|
57
|
+
* Body: `{"query":"...","max_results":5,"snippet_max_length":500,"mode":"pro"}`. Query required; max_results 1–50 (default 10); snippet_max_length 180–10000; mode pro/realtime (default pro); optional site, exclude_domains, publish/index date bounds, query_time, safety_mode and session_id.
|
|
58
|
+
* Response: `{query,mode,results:[{title,url,snippet?,published_at?,acquired_at?,description}],usage?}`. Description is deprecated and always empty; read snippet. Keyed usage reports sku/amount/credits/paid and possibly credits_remaining. Public response has no usage.
|
|
59
|
+
* Fetch: `GET https://api.keenable.ai/v1/fetch` or `/v1/fetch/public`, same mode-specific headers; query `url` required, max_chars/live/prompt optional. Response `{url,content,title?,author?,published_at?,truncated?,total_chars?,usage?}`.
|
|
60
|
+
* Errors include stable code/fix/retryable/docs_url. 402 is exhausted keyed credits; do not switch routes. Sources: [API](https://docs.keenable.ai/api-reference.md), [Search](https://docs.keenable.ai/api-reference/search.md), [Fetch](https://docs.keenable.ai/api-reference/fetch.md).
|
|
61
|
+
|
|
62
|
+
### Zhihu global and site search — D
|
|
63
|
+
|
|
64
|
+
Both use `Authorization: Bearer <Access Secret>`, `X-Request-Timestamp: <Unix seconds>`; docs also list Content-Type application/json. **GET query strings, no JSON body.**
|
|
65
|
+
|
|
66
|
+
* Global: `GET https://developer.zhihu.com/api/v1/content/global_search?Query=...&Count=5`. Count default 10, max 20. Optional SearchDB all/realtime/static (default all); optional Filter expression, URL-encoded, e.g. `host=="example.com" AND publish_time>=1778494631`. host supports ==/!=, publish_time numeric comparisons; AND/OR uppercase. **host=="zhihu.com" and its subdomains are unsupported: use site search instead.**
|
|
67
|
+
* Site: `GET https://developer.zhihu.com/api/v1/content/zhihu_search?Query=...&Count=5`. Count capped at 10; optional SortBy, e.g. `VoteUpCount:desc` or `CommentCount:none:(10,)`; fields are case-sensitive.
|
|
68
|
+
* Shared response envelope: `{Code:0,Message:"success",Data:{HasMore,Items:[{Title,Url,ContentText,ContentType,ContentID,...}]}}`. ContentText can contain `<em>` highlighting. Site Data also includes SearchHashId and optional EmptyReason; current site HasMore always false. Preserve provider URL/UTM provenance rather than inventing clean target links.
|
|
69
|
+
* Sources: [Global](https://developer.zhihu.com/docs?key=global_search), [Site](https://developer.zhihu.com/docs?key=zhihu_search), [Pricing](https://developer.zhihu.com/docs?key=billing_price). Their JS-rendered official contents were read with Cloak; no authenticated request was made.
|
|
70
|
+
|
|
71
|
+
### AnySearch — D
|
|
72
|
+
|
|
73
|
+
* `POST https://api.anysearch.com/v1/search`. Anonymous explicitly omits Authorization; keyed explicitly sends `Authorization: Bearer <key>`. Invalid key returns 401/403 and does not silently downgrade.
|
|
74
|
+
* Body: `{"query":"...","max_results":5}`. max_results 1–10/default 10; optional zone cn/intl, language, format json/markdown. For vertical capabilities, discover tag/params first; never fabricate capability tags. REST uses tag/params, **not MCP domain/sub_domain fields**.
|
|
75
|
+
* Response: `{code:0,message:"success",request_id,data:{results:[{title,url,snippet?,content?}],metadata:{total_results,search_time_ms}}}`. Title may be empty. Markdown changes result content, not the outer JSON envelope.
|
|
76
|
+
* HTTP 402 anonymous quota rejection can contain automatically generated credentials; rejected request is not executed. This plugin must not adopt them or resubmit under another mode. Keep diagnostics to status/request_id.
|
|
77
|
+
* Sources: [REST search](https://www.anysearch.com/docs/api-endpoints/v1-search.md), [Auth](https://www.anysearch.com/docs/auth.md), [Pricing](https://www.anysearch.com/pricing.md).
|
|
78
|
+
|
|
79
|
+
### Linkup — D
|
|
80
|
+
|
|
81
|
+
* `POST https://api.linkup.so/v1/search`, Bearer key.
|
|
82
|
+
* Body: `{"q":"...","depth":"standard","outputType":"searchResults","maxResults":5}`. q/depth/outputType required. depth flash/fast/standard/deep; outputType searchResults/sourcedAnswer/structured. Optional includeDomains (max 100), excludeDomains, fromDate/toDate, includeImages.
|
|
83
|
+
* Raw response `{results:[{type:"text",name,url,content,favicon,publishedAt?}]}`; image entries `{type:"image",name,url}`. sourcedAnswer returns `{answer,sources:[{name,url,snippet,favicon,publishedAt?}]}`. Structured output needs structuredOutputSchema and has a different schema; includeSources changes it again.
|
|
84
|
+
* API may return 402/payment-required for no-key x402. Account exhaustion is documented as 429. No mode switch on either.
|
|
85
|
+
* Sources: [OpenAPI reference](https://docs.linkup.so/pages/documentation/endpoints/search/reference.md), [Pricing](https://docs.linkup.so/pages/documentation/platform/pricing.md).
|
|
86
|
+
|
|
87
|
+
### Tavily — D
|
|
88
|
+
|
|
89
|
+
* `POST https://api.tavily.com/search`, `Authorization: Bearer <Tavily key>`.
|
|
90
|
+
* Body: `{"query":"...","search_depth":"basic","max_results":5,"auto_parameters":false}`. max_results 0–20; depth basic/fast/ultra-fast/advanced. Explicitly keep auto_parameters false for stable billing; automatic depth selection can cost 2 credits. Optional topic general/news/finance, domain filters, dates, include_raw_content and include_answer.
|
|
91
|
+
* Response `{query,results:[{title,url,content,score,raw_content?,published_date?}],images,response_time,answer?,usage?,request_id?}`. Read `content` for excerpt. include_usage true returns credits.
|
|
92
|
+
* Sources: [Search schema/auth](https://docs.tavily.com/documentation/api-reference/endpoint/search.md), [Billing](https://docs.tavily.com/documentation/api-credits.md).
|
|
93
|
+
|
|
94
|
+
### Exa — D
|
|
95
|
+
|
|
96
|
+
* `POST https://api.exa.ai/search`; Bearer key or x-api-key.
|
|
97
|
+
* Body: `{"query":"...","type":"lite","numResults":5,"contents":{"highlights":true}}`. Explicit type is a vendor search-depth setting, not plugin backend selection. Default auto exists, but do not silently pick it for a user-fixed lite configuration. Lite supports cached highlights/text and a smaller parameter set; unsupported options return 400.
|
|
98
|
+
* Response `{requestId,results:[{id,title,url,publishedDate?,highlights?:string[],text?,image?,favicon?}],searchTime?,costDollars?,resolvedSearchType?}`.
|
|
99
|
+
* numResults default 10; quickstart says up to 100, while pricing describes Enterprise access above 25: **account entitlement for large result counts unverified**. Keep conservative counts until entitlement is checked.
|
|
100
|
+
* Sources: [Search](https://exa.ai/docs/search/quickstart.md), [Pricing](https://exa.ai/docs/admin/pricing.md).
|
|
101
|
+
|
|
102
|
+
### Baidu Qianfan — D
|
|
103
|
+
|
|
104
|
+
* `POST https://qianfan.baidubce.com/v2/ai_search/web_search`, Bearer Qianfan API key.
|
|
105
|
+
* Body: `{"messages":[{"role":"user","content":"..."}],"search_source":"baidu_search_v2","edition":"standard","resource_type_filter":[{"type":"web","top_k":5}]}`.
|
|
106
|
+
* Official guide confirms response `references` array with title/website/url/snippet/date. Full response schema beyond that subset **unverified in this research**. Do not map it as an OpenAI choices envelope.
|
|
107
|
+
* Optional search_recency_filter week/month/semiyear/year is documented in the guide. The separately packaged Skill/MCP has count/freshness arguments; these are not proof that the raw API accepts those fields.
|
|
108
|
+
* MCP is Streamable HTTP with Bearer and tool webSearch `{query,count?,freshness?}`; exact MCP URL is to be copied from the logged-in tool detail page and remains **unverified**, not the REST URL.
|
|
109
|
+
* Source: [First-party integration guide](https://cloud.baidu.cn/doc/qianfan/s/nmweljpt3), rendered browser read.
|
|
110
|
+
|
|
111
|
+
### Volcengine / Doubao — D Custom, P Global
|
|
112
|
+
|
|
113
|
+
* Custom recommended API-key path: `POST https://open.feedcoopapi.com/search_api/web_search`, Bearer key.
|
|
114
|
+
* Alternative IAM AK/SK path: `POST https://mercury.volcengineapi.com?Action=WebSearch&Version=2025-01-01`, signed using service `volc_torchlight_api`. These are distinct fixed authentication routes.
|
|
115
|
+
* Body: `{"Query":"...","SearchType":"web","Count":5,"Filter":{"NeedUrl":true},"QueryControl":{"QueryRewrite":false}}`. Query 1–100 characters (excess truncated), Count default 10/max 50; optional TimeRange OneDay/OneWeek/OneMonth/OneYear or date interval; Filter Sites/BlockHosts/NeedContent; ContentFormats text/markdown. NeedUrl true removes cards without source URLs.
|
|
116
|
+
* Response `{ResponseMetadata:{RequestId,Error?},Result:{ResultCount,WebResults:[{Id,SortId,Title,Url?,Snippet,Summary?,Content?,PublishTime?,SiteName?,RankScore?}],SearchContext,TimeCost,LogId}}`. Result can be null on errors. Inspect ResponseMetadata.Error, not only HTTP status.
|
|
117
|
+
* Global pricing/free sharing confirmed; **its exact request endpoint/schema not separately verified**. Do not reuse Custom URL assuming it selects Global. Ark model tool-enabled search is also a separate integration, not interchangeable with Custom raw retrieval.
|
|
118
|
+
* Sources: [Custom API](https://docs.volcengine.com/docs/networked-search/networked-search?lang=zh), [Billing](https://docs.volcengine.com/docs/networked-search/online-search-product-billing?lang=zh), rendered browser reads.
|
|
119
|
+
|
|
120
|
+
### Brave — D
|
|
121
|
+
|
|
122
|
+
* `GET https://api.search.brave.com/res/v1/web/search`, `X-Subscription-Token: <key>`.
|
|
123
|
+
* Query parameters q required; count max/default 20, offset 0–9; optional country, search_lang, ui_lang, freshness, safesearch, extra_snippets=true. No JSON body.
|
|
124
|
+
* Response web.results entries `{title,url,description,extra_snippets?}`; query.more_results_available controls pagination. Other vertical enrichments are not ordinary web hits. LLM Context is a separate endpoint/product contract.
|
|
125
|
+
* Sources: [Web Search](https://api-dashboard.search.brave.com/documentation/services/web-search), [Pricing](https://api-dashboard.search.brave.com/documentation/pricing).
|
|
126
|
+
|
|
127
|
+
### You.com — D
|
|
128
|
+
|
|
129
|
+
* New integration: `POST https://ydc-index.io/v1/search`, `X-API-Key: <key>`. Existing GET remains supported but gets no new features. Do not replace this documented host with a guessed api.you.com REST path.
|
|
130
|
+
* Body: `{"query":"...","count":5,"strict_operators":true}`. Count 1–100; optional country/language/freshness/offset, include_domains or exclude_domains (not both), extraction. strict_operators defaults false: vendor can relax unmatched operators. Highlights extraction supports count at most 50.
|
|
131
|
+
* Response `{results:{web:[{url,title,description?,snippets?:string[],page_age?,contents?:{highlights?,markdown?,html?}}],knowledge?},metadata:{search_uuid?,query?,latency?}}`. Knowledge attribution is not a source URL.
|
|
132
|
+
* Full-page extraction's source cache/fetch/blend controls additional live-fetch charges. Do not enable paid extraction implicitly.
|
|
133
|
+
* Sources: [POST search](https://you.com/docs/api-reference/search/v1-search.md), [Billing](https://you.com/docs/administration/billing.md).
|
|
134
|
+
|
|
135
|
+
### open-websearch — D project interface, not engine-official SERP API
|
|
136
|
+
|
|
137
|
+
The candidate here is **Aas-ee/open-webSearch**, not the unrelated OpenWebSearch.eu initiative.
|
|
138
|
+
|
|
139
|
+
* User-configured local daemon URL; documented example `http://127.0.0.1:3210`, `POST /search`, no API auth documented. Body `{query,limit:1–50,engines:["duckduckgo"],searchMode:"request"}`. Do not assume all localhost daemons use that port.
|
|
140
|
+
* Envelope `{status:"ok",data:...,error:null,hint:null}`; README search payload example is array `[{title,url,description,source,engine}]`. Error envelope status error/data null/error `{code,message}`.
|
|
141
|
+
* MCP separate from daemon: local server `/mcp` Streamable HTTP or `/sse` legacy; stdio also available. Search tool accepts query, optional limit/engines/searchMode.
|
|
142
|
+
* Pin a single user-selected engine and forced request/playwright mode where relevant; do not leave request/browser strategy auto for fixed-mode use. Server README documents optional browser-cookie fallback for some fetch paths; do not imply all server behavior is under plugin control.
|
|
143
|
+
* Sources: [README with restrictions](https://raw.githubusercontent.com/Aas-ee/open-webSearch/main/README.md), [Daemon API](https://raw.githubusercontent.com/Aas-ee/open-webSearch/main/docs/http-api.md).
|
|
144
|
+
|
|
145
|
+
### Serper — P, protocol unverified from public official documentation
|
|
146
|
+
|
|
147
|
+
Pricing and free trial are confirmed on the official public homepage. The official playground redirects to login, so no public authenticated reference was obtained. **Endpoint, method, authentication header, request body, and full response contract remain unverified here.** Do not promote a familiar third-party `google.serper.dev` example or installed adapter implementation into official verification. The homepage shows an organic-style example but is insufficient to establish the exact production contract. Source: [Official homepage](https://serper.dev/), [Playground/login gate](https://serper.dev/playground).
|
|
148
|
+
|
|
149
|
+
### Serpex — D
|
|
150
|
+
|
|
151
|
+
* `POST https://api.serpex.dev/api/search` recommended; GET query parameters also supported. `Authorization: Bearer <key>`; x-api-key accepted alternatively.
|
|
152
|
+
* Body `{"q":"..."}`; optional include_content/content_results (5 or 10) incur different content costs. Do not assume a max_results parameter.
|
|
153
|
+
* Response `{id,query,engines,results:[{title,url,snippet,position,engine,content?|content_error?}],metadata:{number_of_results,credits_used,from_cache,status,...}}`.
|
|
154
|
+
* Vendor explicitly says legacy engine/engines are ignored and requests are internally routed with fallback. Plugin can select Serpex as a fixed provider, but cannot promise a fixed Serpex upstream engine. Date constraints can weaken when a vendor source lacks support. Use metadata.credits_used, not from_cache, for billing.
|
|
155
|
+
* Sources: [Search](https://serpex.dev/docs/api/search), [Pricing](https://serpex.dev/docs/getting-started/pricing). Plain-search pricing and content example differ; do not price content-enabled requests as necessarily one credit.
|
|
156
|
+
|
|
157
|
+
### Parallel — D
|
|
158
|
+
|
|
159
|
+
* `POST https://api.parallel.ai/v1/search`, `x-api-key: <key>`.
|
|
160
|
+
* Body `{"objective":"Find nonstop airlines between Seattle and Tokyo","search_queries":["Seattle Tokyo nonstop flights"],"mode":"fast","advanced_settings":{"max_results":5}}`. search_queries required, at least one concise keyword query; objective optional in REST, required in MCP. Modes turbo/fast/basic/advanced (REST default advanced). **max_results/source_policy/fetch_policy belong inside advanced_settings**, not top level. max_chars_total is top level.
|
|
161
|
+
* Response `{search_id,results:[{url,title?:string|null,publish_date?:string|null,excerpts:string[]}],session_id,warnings?,usage?:[{name,count}]}`. Required result fields are url and excerpts, not title. No invented content string.
|
|
162
|
+
* New integrations use v1, not a mechanical path substitution of a v1beta body. No language-model query rewrite was executed in this research; a plugin should not incur extra LLM calls silently.
|
|
163
|
+
* Sources: [Exact OpenAPI](https://docs.parallel.ai/api-reference/search/search.md), [Quickstart](https://docs.parallel.ai/search/search-quickstart.md), [Pricing](https://docs.parallel.ai/getting-started/pricing.md).
|
|
164
|
+
|
|
165
|
+
### Tencent WSA / Yuanbao Search — D
|
|
166
|
+
|
|
167
|
+
* `POST https://wsa.tencentcloudapi.com/`, JSON; Tencent TC3-HMAC-SHA256 signature from SecretId/SecretKey, service wsa. Headers X-TC-Action SearchPro, X-TC-Version 2025-05-08, X-TC-Timestamp, Authorization and Content-Type required. Region not required for SearchPro. **Not Bearer auth.**
|
|
168
|
+
* Body `{"Query":"..."}`; optional Mode 0/1/2, Site, Cnt 10/20/30/40/50, Industry, Freshness, Deeplinks; capabilities depend on purchased lite/standard/flagship version.
|
|
169
|
+
* Response `{Response:{Query,Pages:string[],Version,Msg?,RequestId}}`. Each Pages element is a **JSON-encoded string**, requiring separate parsing, containing title/url/date/passage, possibly content/score/pics/authority_level/deeplinks. Do not read Pages as an array of already-decoded objects.
|
|
170
|
+
* Sources: [SearchPro](https://cloud.tencent.com/document/product/1806/121811), [Common headers/signature](https://cloud.tencent.com/document/api/1806/121815), [Pricing](https://cloud.tencent.com/product/wsa).
|
|
171
|
+
|
|
172
|
+
### DeepSeek — D
|
|
173
|
+
|
|
174
|
+
As of this verification date DeepSeek **does have a first-party raw Search API**; older claims that it only provides model completions are stale.
|
|
175
|
+
|
|
176
|
+
* `POST https://api.deepseek.com/v1/tools/search`, Bearer API key.
|
|
177
|
+
* Body `{"query":"...","count":5,"need_content":false}`. Query 1–128 Unicode characters, count 1–50/default 10; optional ori_question and localization. Unknown body fields ignored.
|
|
178
|
+
* Response `{results:[{rerank_score,title,url,snippet,summary,content,site_name:string|null,site_icon:string|null,date:string|null,authority}]}`. content empty when not requested/unavailable. Empty results valid and unbilled.
|
|
179
|
+
* Fetch `POST https://api.deepseek.com/v1/tools/fetch`, `{url}` -> `{title,content}` Markdown. Same Bearer auth, separately limited and billed.
|
|
180
|
+
* Model-hosted deepseek_web_search/deepseek_read_url are different tools with model decision-making and token costs; raw Search is the deterministic adapter target.
|
|
181
|
+
* Sources: [Search & Fetch including billing/QPS](https://api-docs.deepseek.com/guides/search/), [Model web tools](https://api-docs.deepseek.com/guides/web_tools/).
|
|
182
|
+
|
|
183
|
+
### DuckDuckGo — D Instant Answers, U official full web search
|
|
184
|
+
|
|
185
|
+
* Official archived first-party source documents `GET https://api.duckduckgo.com/?q=...&format=json`, no key; descriptive t app identifier, optional no_html/no_redirect/skip_disambig. Response fields include AbstractText/AbstractURL, Results and RelatedTopics with FirstURL/Text (sometimes nested Topics).
|
|
186
|
+
* This **is not full search results**, does not syndicate general SERPs, and is often empty for non-topic queries. Documented attribution/noncommercial-approval restrictions and automatic throttling apply; exact current quota is unverified.
|
|
187
|
+
* html.duckduckgo.com/lite scraping is **not verified as an official API contract**, even if a scraper can return HTML. No stable official full-SERP response or paid tariff was confirmed.
|
|
188
|
+
* Source: [DuckDuckGo's own documentation repository](https://raw.githubusercontent.com/duckduckgo/duckduckgo-publisher/master/share/site/duckduckgo/api.tx). Its archival nature must be considered when evaluating current terms.
|
|
189
|
+
|
|
190
|
+
### SearXNG — D HTTP interface, P deployment-specific behavior
|
|
191
|
+
|
|
192
|
+
* User-configured instance: `GET /search?q=...&format=json`, or `POST /search` with **application/x-www-form-urlencoded**, not JSON. `/` also supports both methods. q required; format JSON must be enabled by the instance; disabled format returns 403.
|
|
193
|
+
* Optional categories/language/pageno/time_range/safesearch; engine-dependent filters may not be enforced by every underlying engine. No universal API-key scheme is defined by this search interface; an operator may add proxy authentication.
|
|
194
|
+
* JSON result projection convention `{results:[{title,url,content,...}],...}` is **not fully schema-verified by the Search API page used here**; confirm against selected deployment/version before strict validation. No instance was probed in this research. Never silently cycle through public instances.
|
|
195
|
+
* Source: [First-party Search API](https://docs.searxng.org/dev/search_api.html).
|
|
196
|
+
|
|
197
|
+
### Mojeek — D
|
|
198
|
+
|
|
199
|
+
* `GET https://api.mojeek.com/search?q=...&api_key=<key>&fmt=json`, key in query string. Avoid logging the URL with api_key. No JSON body.
|
|
200
|
+
* Official quickstart uses lb/lbb for language boosting and rb/rbb for region boosting. Other options must follow the request reference, not another provider's names.
|
|
201
|
+
* Response `{response:{status,head,results:[{url,title,desc,date?,timestamp?,pdate?,score?,...}]}}`. Check response.status, not just HTTP success.
|
|
202
|
+
* Sources: [Quickstart](https://www.mojeek.com/support/api/search/quickstart.html), [JSON response](https://www.mojeek.com/support/api/search/json_response.html), [Pricing/retention](https://www.mojeek.com/services/search/web-search-api/).
|
|
203
|
+
|
|
204
|
+
### Anthropic — D model-hosted search, not raw retrieval
|
|
205
|
+
|
|
206
|
+
* `POST https://api.anthropic.com/v1/messages`, x-api-key, anthropic-version (current documentation example 2026-10-21), Content-Type.
|
|
207
|
+
* Body includes explicitly chosen supported model, max_tokens, messages and `tools:[{"type":"web_search_20250305","name":"web_search","max_uses":1}]`. Newer 20260209/20260318 tools add dynamic filtering/response controls; do not silently upgrade versions. Model and organization capabilities must be checked.
|
|
208
|
+
* Response content includes server_tool_use, web_search_tool_result with array of `{type:"web_search_result",url,title,encrypted_content,page_age}`, plus text blocks/citations. Search errors can appear **inside HTTP 200** as web_search_tool_result_error; no search result may occur if the model does not search. Preserve encrypted fields unchanged for conversational continuation.
|
|
209
|
+
* Search result content is encrypted, **not a plaintext snippet**. Cited text is not a substitute for full raw retrieved content. A single model request can run several billable searches; max_uses bounds search calls, not model-token costs.
|
|
210
|
+
* Source: [Official web-search contract and pricing](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool.md).
|
|
211
|
+
|
|
212
|
+
### OpenAI — D model-hosted search, not raw retrieval
|
|
213
|
+
|
|
214
|
+
* `POST https://api.openai.com/v1/responses`, Bearer key, JSON with explicitly selected supported model, input and `tools:[{"type":"web_search"}]`; include `["web_search_call.action.sources"]` for complete consulted source lists. To require search rather than optional model choice, use documented tool_choice required or specific search-tool selection.
|
|
215
|
+
* Response output has web_search_call (action search/open_page/find_in_page) and message/content output_text with url_citation annotations `{url,title,start_index,end_index}`. Sources are not a guaranteed plaintext snippet list. Clickable inline citations must be shown when displaying results.
|
|
216
|
+
* external_web_access false is explicit cache-only mode; default true. search_context_size low/medium/high is not an exact result-count limit. Legacy web_search_preview lacks newer controls. Official docs say gpt-4o search previews shut down 2026-07-23; do not rely on them.
|
|
217
|
+
* Sources: [Guide](https://developers.openai.com/api/docs/guides/tools-web-search.md), [Pricing](https://developers.openai.com/api/docs/pricing.md).
|
|
218
|
+
|
|
219
|
+
## MCP contracts and transport rules
|
|
220
|
+
|
|
221
|
+
MCP is a transport/tool protocol, **not an additional search provider or free billing tier**. REST JSON bodies and MCP tool arguments must not be conflated.
|
|
222
|
+
|
|
223
|
+
Streamable HTTP sends JSON-RPC requests using POST, `Content-Type: application/json`, and `Accept: application/json, text/event-stream`. A server can reply as JSON or SSE. Initialize, send notifications/initialized, discover tools/list, then tools/call; retain Mcp-Session-Id if issued and negotiated MCP-Protocol-Version on subsequent requests. Tool results may have structuredContent, content text blocks, _meta and isError. A parseable HTTP 200 or MCP result is not by itself search success. Do not guess tool names or treat human-readable Markdown output as a stable raw JSON schema. Reference: [Official transport specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports).
|
|
224
|
+
|
|
225
|
+
| Provider | Fixed endpoint and access | Documented search tool arguments | Verification limitations / source |
|
|
226
|
+
| --- | --- | --- | --- |
|
|
227
|
+
| Keenable anonymous | `https://api.keenable.ai/mcp-public`; no key; avoids OAuth discovery | search_web_pages `{query,max_results?,snippet_max_length?,site?,exclude_domains?,output_format:"json",...}`; public schema does not list mode | Raw JSON is serialized inside tool text when requested; title/url/snippet shape as REST. No live tools/list done. [MCP docs](https://docs.keenable.ai/mcp-server.md) |
|
|
228
|
+
| Keenable key | `https://api.keenable.ai/mcp`, X-API-Key; /mcp-public also accepts key but should not be switched automatically | Same tool; keyed mode pro/realtime can be fixed. fetch_page_content `{url,max_chars?,live?,prompt?,output_format?}` | Keyed usage _meta["keenable/usage"]. OAuth is separate /mcp-oauth. [MCP docs](https://docs.keenable.ai/mcp-server.md) |
|
|
229
|
+
| AnySearch anonymous or key | `https://api.anysearch.com/mcp`; retain X-Anysearch-Client `mcp/1.0.0`; keyed mode adds Bearer | search `{query,max_results?:1–10,domain?,sub_domain?,sub_domain_params?}`; batch_search `{queries:[1–5 search objects]}`; get_sub_domains `{domain}` or `{domains}`; extract `{url}` | REST tag/params differ from MCP. Exact runtime result envelope still requires tools/list/call validation. [MCP docs](https://www.anysearch.com/docs/mcp-install.md) |
|
|
230
|
+
| Zhihu key | `https://developer.zhihu.com/api/mcp/v1`, Bearer Access Secret | Tool names zhihu_search/global_search/hot_list/zhida confirmed; **input schemas unverified** | Do not assume raw GET Query/Count are MCP names. [Unified MCP](https://developer.zhihu.com/docs?key=unified_mcp) |
|
|
231
|
+
| Linkup key | `https://mcp.linkup.so/mcp`, Bearer preferred over apiKey URL query | linkup-search `{query,depth?:"standard" or "deep",maxResults?,includeDomains?,excludeDomains?,fromDate?,toDate?,includeImages?}` | MCP exposes only standard/deep, unlike raw API flash/fast. No free anonymous demo confirmed. [MCP docs](https://docs.linkup.so/pages/integrations/mcp/mcp.md) |
|
|
232
|
+
| Parallel anonymous | `https://mcp.parallel.ai/mcp?tools=web_search`, no auth | web_search `{objective,search_queries:string[],client_model?,session_id?}`; objective and search_queries required | Default fast. No count/mode argument in anonymous tool schema; do not send unsupported max_results. Numeric anonymous allowance unverified. [MCP docs](https://docs.parallel.ai/integrations/mcp/quickstart.md) |
|
|
233
|
+
| Parallel key | Same endpoint, Bearer or x-api-key | Same core args; host can fix settings with x-parallel-mcp-config JSON header, e.g. `{"web_search":{"override":{"mode":"fast","advanced_settings":{"max_results":5}}}}` | Overrides require auth; anonymous with config header returns 401. _meta["parallel/usage"] reports costs. New unified endpoint replaces standalone search.parallel.ai/mcp for new setups, old endpoint still operates. [MCP docs](https://docs.parallel.ai/integrations/mcp/quickstart.md) |
|
|
234
|
+
| You.com anonymous | `https://api.you.com/mcp?profile=free`, no key, 100 queries/day | you-search `{query,count?,freshness?,offset?,extraction?,knowledge?,safesearch?,exclude_domains?,...}` | Free profile only you-search/you-discover. Deep argument schema should be discovered at runtime; do not infer REST extraction object matches MCP shorthand. [MCP docs](https://you.com/docs/agents/mcp-server.md) |
|
|
235
|
+
| You.com key | `https://api.you.com/mcp`, Bearer | you-search; host overrides in _meta["com.you.com/search"] or X-Search-* headers, e.g. country/language/count/include_domains | Bare no-key /mcp means OAuth, **not anonymous free mode**. [MCP docs](https://you.com/docs/agents/mcp-server.md) |
|
|
236
|
+
| Baidu | Streamable HTTP + Bearer; exact service URL unverified | webSearch `{query,count?:1–50,freshness?}` | Must obtain URL from official tool details, not repurpose REST URL. [Guide](https://cloud.baidu.cn/doc/qianfan/s/nmweljpt3) |
|
|
237
|
+
| Exa | `https://mcp.exa.ai/mcp` documented | Exact runtime tool/schema and anonymous allowance unverified here | The hosted endpoint mention alone does not prove free anonymous production service. [Search docs](https://exa.ai/docs/search/quickstart.md) |
|
|
238
|
+
| open-websearch | User-configured local /mcp Streamable HTTP, /sse legacy, or stdio | search `{query,limit?,engines?,searchMode?}` | Self-hosted scraper; fix deployment/mode/engine, not a universal hosted URL. [Project README](https://raw.githubusercontent.com/Aas-ee/open-webSearch/main/README.md) |
|
|
239
|
+
|
|
240
|
+
For all other candidates, a first-party MCP endpoint/schema was **not verified by this research**. This does not assert that none exists.
|
|
241
|
+
|
|
242
|
+
## Remaining verification work before production claims
|
|
243
|
+
|
|
244
|
+
1. With user-provided credentials and explicit cost approval, run a small successful query for each selected keyed provider and validate real response/error envelopes. Document the date, request mode and billed usage separately from this documentation-only audit.
|
|
245
|
+
2. Run initialize/tools/list and one explicitly authorized tool call for selected MCP routes, including both JSON and SSE response handling where supported. Anonymous tiers can still change or return sensitive quota errors.
|
|
246
|
+
3. Resolve Serper's login-gated official API contract; verify SearXNG JSON serialization against the exact selected instance; verify Doubao Global separately; retrieve Zhihu MCP input schemas and account-specific free limits.
|
|
247
|
+
4. Recheck prices at deployment and expose the selected access mode, free limitations, supplier-internal routing caveats, and verification date to the user. Never label an unverified endpoint as supported merely because its name appears in a catalog.
|
|
248
|
+
|
|
249
|
+
## Live verification in this deployment — 2026-11-17
|
|
250
|
+
|
|
251
|
+
Real calls were executed through the plugin engine, three sequential queries per backend with retry disabled, before any tier was assigned. Documented contract and observed behaviour are recorded separately.
|
|
252
|
+
|
|
253
|
+
| Backend | Mode | Observed | Result |
|
|
254
|
+
| --- | --- | --- | --- |
|
|
255
|
+
| Keenable | anonymous | 3/3 success, ~0.4–0.6 s, 3 sources | Stable |
|
|
256
|
+
| Exa | anonymous MCP | 3/3 success, ~1.0–1.2 s, 3 sources | Stable, fastest full-text quality of the free tiers |
|
|
257
|
+
| You.com | anonymous MCP | 3/3 success, ~1.8–2.3 s | Stable |
|
|
258
|
+
| AnySearch | anonymous | 3/3 success, ~2.0–3.6 s | Stable, slower |
|
|
259
|
+
| Parallel | anonymous MCP | 3/3 success, ~1.4–2.1 s, 10 sources | Stable; one earlier attempt returned 429, which is transient rate limiting, not unavailability |
|
|
260
|
+
| SearXNG | self-hosted loopback | success, ~2.5 s, returns more than requested (capped locally) | Stable |
|
|
261
|
+
| DuckDuckGo | anonymous HTML | rejected with a challenge on this network | Left documented-only; no bypass attempted |
|
|
262
|
+
|
|
263
|
+
Consequence for the catalogue: **"unavailable" is reserved for entries whose contract could not be established**, not for free tiers without a published number. Cost tier and verification evidence are now separate fields (`tier` per access mode, `evidence: documented | live`), so a free anonymous backend can no longer be filed under "unavailable" merely because its quota is unpublished.
|
|
264
|
+
|
|
265
|
+
Remaining documented-only entries: every keyed backend (no credential supplied here) and Serper, whose exact contract is still behind a login-gated playground.
|
|
266
|
+
|
|
267
|
+
## Retired entries
|
|
268
|
+
|
|
269
|
+
**Serper** was the only candidate whose contract could not be established from public official documentation (the playground is login-gated), so it was removed from the shipped catalogue on 2026-11-17 by user decision. Its config rows are pruned on load, not rejected; no other backend inherits its credential. The pricing facts above stay in this audit because the platform itself still exists.
|
package/docs/PLAN.md
ADDED
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
# Implementation Plan
|
|
2
|
+
|
|
3
|
+
## Status and scope
|
|
4
|
+
|
|
5
|
+
Planning baseline: 2026-11-17. Implementation has not started.
|
|
6
|
+
|
|
7
|
+
Build an independent DSH bundle replacing the currently installed search plugin after verification. Keep the native `web_search` entry point. Do not modify DSH itself or patch installed third-party code.
|
|
8
|
+
|
|
9
|
+
Verified environment during planning:
|
|
10
|
+
|
|
11
|
+
- Audited against the installed DSH release at the time of writing; this plugin is not pinned to it.
|
|
12
|
+
- Existing search bundle: `@240xu/dsh-websearch` `2.8.8`, provider ID `unified`.
|
|
13
|
+
- Search extension: `ctx.web.registerSearchProvider()`.
|
|
14
|
+
- Settings extension: Client `settings.section`.
|
|
15
|
+
- Configuration persistence: `configEditor`; secrets: DSH credentials.
|
|
16
|
+
|
|
17
|
+
Reinspect exact live contracts before implementation. Do not assume historical settings behavior applies to the installed release.
|
|
18
|
+
|
|
19
|
+
## Binding behavior decisions
|
|
20
|
+
|
|
21
|
+
### Explicit access modes
|
|
22
|
+
|
|
23
|
+
- Each backend has its own independent enabled switch.
|
|
24
|
+
- Where supported, the user explicitly selects anonymous/keyless or API-key access.
|
|
25
|
+
- There is no automatic access mode.
|
|
26
|
+
- Selecting anonymous access must never read or transmit a saved key.
|
|
27
|
+
- Selecting key access without a usable credential returns a configuration failure.
|
|
28
|
+
- Switching modes preserves stored credentials but does not activate them implicitly.
|
|
29
|
+
- Disabled backends make no search requests or background health requests.
|
|
30
|
+
- Different protocols or products may be separate backend entries when needed; duplicate access paths must not be enabled implicitly.
|
|
31
|
+
|
|
32
|
+
### No fallback
|
|
33
|
+
|
|
34
|
+
- Never switch backend, endpoint, access mode, or credential in response to failure.
|
|
35
|
+
- Aggregation invokes only the backends explicitly enabled by the user.
|
|
36
|
+
- Do not add priority failover, anonymous-to-paid escalation, key rotation, or credential fallback.
|
|
37
|
+
- The only permitted automatic recovery is bounded retry of the same operation under the retry policy.
|
|
38
|
+
|
|
39
|
+
### Retry policy
|
|
40
|
+
|
|
41
|
+
Proposed conservative defaults, configurable in the Web UI:
|
|
42
|
+
|
|
43
|
+
- Retry eligible HTTP statuses: `408`, `429`, `500`, `502`, `503`, `504`.
|
|
44
|
+
- At most two additional attempts, with exponential backoff and jitter.
|
|
45
|
+
- Honor valid `Retry-After` on `429` and `503`, within the overall deadline.
|
|
46
|
+
- Other statuses, including authentication and validation errors, are not retried by default.
|
|
47
|
+
- Explicit quota exhaustion or insufficient balance is terminal, even when HTTP status is `429`.
|
|
48
|
+
- Network errors and request timeouts are not retried by default; expose independent opt-ins.
|
|
49
|
+
- User cancellation or overall deadline expiration stops requests and backoff immediately.
|
|
50
|
+
- A retry never changes backend, endpoint, selected mode, or credential.
|
|
51
|
+
- Document possible repeated charges; use stricter adapter defaults when billing or idempotency semantics require them.
|
|
52
|
+
- Expose retry enablement, status allowlist, maximum retries, initial delay, maximum delay, and network/timeout opt-ins.
|
|
53
|
+
|
|
54
|
+
### Failure reporting
|
|
55
|
+
|
|
56
|
+
- Return failures in tool-visible content, not only server logs.
|
|
57
|
+
- Include backend, access mode, error classification, safe explanation, HTTP status where available, and attempt count.
|
|
58
|
+
- Explicitly ask the Agent to inform the user and give a safe next step.
|
|
59
|
+
- Partial success returns valid sources plus every failed backend; failure visibility must survive result normalization.
|
|
60
|
+
- All-backend failure is a search failure, not a successful search with no results.
|
|
61
|
+
- Never expose keys, authorization headers, or sensitive upstream response bodies.
|
|
62
|
+
- The plugin can expose instructions to the Agent but cannot guarantee the Agent repeats them.
|
|
63
|
+
|
|
64
|
+
## Backend inventory
|
|
65
|
+
|
|
66
|
+
Research the union of the linked forum survey and the installed bundle's backend list. Normalize duplicates, but preserve differences between access protocols and products.
|
|
67
|
+
|
|
68
|
+
Candidates:
|
|
69
|
+
|
|
70
|
+
- Keenable
|
|
71
|
+
- Zhihu global search and Zhihu site search (independently switchable)
|
|
72
|
+
- AnySearch
|
|
73
|
+
- Linkup
|
|
74
|
+
- Tavily
|
|
75
|
+
- Exa (anonymous MCP and authenticated API, where officially supported)
|
|
76
|
+
- Baidu Qianfan AI Search
|
|
77
|
+
- Volcengine / Doubao Search
|
|
78
|
+
- Brave Search
|
|
79
|
+
- You.com
|
|
80
|
+
- open-websearch
|
|
81
|
+
- Serper
|
|
82
|
+
- Serpex
|
|
83
|
+
- Parallel
|
|
84
|
+
- Tencent Cloud WSA
|
|
85
|
+
- DeepSeek
|
|
86
|
+
- DuckDuckGo
|
|
87
|
+
- SearXNG
|
|
88
|
+
- Mojeek
|
|
89
|
+
- Anthropic
|
|
90
|
+
- OpenAI
|
|
91
|
+
|
|
92
|
+
For every candidate, record official protocol, authentication, endpoint, request/response shape, supported parameters, pricing, free limits, prerequisites, source URL, and verification date. Do not invent undocumented endpoints. Mark unresolved candidates as unverified and disabled; never claim an adapter works without implementation and validation. Report blockers instead of silently dropping candidates.
|
|
93
|
+
|
|
94
|
+
No account creation, payment enrollment, or multi-account quota circumvention is included.
|
|
95
|
+
|
|
96
|
+
## Cost classification
|
|
97
|
+
|
|
98
|
+
Classify access modes, not just platform brands:
|
|
99
|
+
|
|
100
|
+
1. Free without a published fixed quota: document rate limits and anonymous conditions; do not imply unlimited usage.
|
|
101
|
+
2. Recurring free allowance: quantity, unit, reset period, identity/card requirements, and overage behavior.
|
|
102
|
+
3. One-time trial: clearly distinguished from recurring free allowance.
|
|
103
|
+
4. Paid: unit pricing, official pricing link, and additional model charges where relevant.
|
|
104
|
+
5. Unverified: insufficient evidence; disabled by default.
|
|
105
|
+
|
|
106
|
+
A mode may combine recurring free allowance and paid overage. Self-hosted backends must disclose infrastructure costs separately. Price and quota metadata includes references and verification dates. Do not promise permanent free tiers. Local counters and budgets are estimates, not provider balances unless a real balance API is used.
|
|
107
|
+
|
|
108
|
+
## Architecture
|
|
109
|
+
|
|
110
|
+
- Independent Host + Client bundle; no DSH shell changes.
|
|
111
|
+
- Typed backend adapter contract with capability metadata and normalized results.
|
|
112
|
+
- Single-backend and parallel aggregation modes only; no failover mode.
|
|
113
|
+
- Preserve title, URL, snippet, summary, publication time, and backend provenance where supported.
|
|
114
|
+
- Deterministic deduplication and result fusion, configurable limits, bounded concurrency and deadlines.
|
|
115
|
+
- Unsupported filters must be visible rather than silently represented as applied.
|
|
116
|
+
- Cache keys include effective query options and relevant configuration/mode revision. Mode changes cannot reuse incompatible entries.
|
|
117
|
+
- HTTP/MCP transports must be implemented from verified contracts, with cancellation and sanitized errors.
|
|
118
|
+
- Prefer platform facilities and maintained dependencies; assess license, maintenance, recency, and weight before adoption. No vendoring or patched dependency forks without approval.
|
|
119
|
+
|
|
120
|
+
## Complete Web configuration
|
|
121
|
+
|
|
122
|
+
Integrate under Settings > Search, inheriting DSH theme and locale facilities.
|
|
123
|
+
|
|
124
|
+
Sections:
|
|
125
|
+
|
|
126
|
+
- Backend list: cost grouping/filtering, individual enablement, explicit access mode, credential status, endpoint, supported options, test action.
|
|
127
|
+
- Search defaults: result count, language, region, time range, safe search, include/exclude domains where supported.
|
|
128
|
+
- Aggregation: single or parallel mode, concurrency, deduplication and fusion.
|
|
129
|
+
- Reliability and cost controls: deadlines, retry policy, local rate limits and local budget caps. Any circuit breaker must report skipped calls explicitly and must not trigger fallback.
|
|
130
|
+
- Cache and privacy: enabled, TTL, capacity, diagnostics retention policy.
|
|
131
|
+
- Diagnostics: explicit user-triggered backend test and trial search, latency, attempts, actual mode, and sanitized failures.
|
|
132
|
+
|
|
133
|
+
Every public configuration field must have an editable control, help text, default, validation, and save/read-back coverage. A generic JSON editor is not a substitute. Secrets are managed through credential controls rather than configuration plaintext.
|
|
134
|
+
|
|
135
|
+
Include unsaved-change feedback, pending/success/failure save states, reset defaults, inline errors, a focusable linked error summary, and sanitized config import/export. Do not overwrite secrets through redacted export values. Support keyboard navigation, narrow screens, and light/dark themes. Visible strings belong in English and Chinese locale resources; source comments, logs, internal errors, and repository documents are English.
|
|
136
|
+
|
|
137
|
+
Persist ordinary configuration through DSH's config editor, preserving unrelated fields. Handle reload/disposal correctly and report persistence rejection honestly. Do not hand-edit the active profile.
|
|
138
|
+
|
|
139
|
+
## Implementation phases
|
|
140
|
+
|
|
141
|
+
1. Repository and plan baseline (this phase): create local repository, register origin, commit planning documents. Do not push or create a remote repository.
|
|
142
|
+
2. Protocol research: complete sourced backend/cost/capability matrix and resolve live DSH contracts.
|
|
143
|
+
3. Host implementation: schema, credentials integration, transports, adapters, aggregation, retry, cancellation, cache and error reporting.
|
|
144
|
+
4. Client implementation: complete settings UI, localization and configuration coverage.
|
|
145
|
+
5. Verification: unit/contract/integration tests and actual installed GUI validation.
|
|
146
|
+
6. Migration: install verified bundle, explicitly select its search provider, disable but retain the old bundle, preserve the fetch provider, verify native `web_search` and `web_fetch`, and document rollback.
|
|
147
|
+
|
|
148
|
+
Report phase boundaries. Follow the approved scope without repeatedly requesting approval for already-authorized work. Installation that requires a traffic-serving restart must be identified before performing it; restart requires explicit approval. Push, merge, publish, and worktree removal remain out of scope without explicit approval.
|
|
149
|
+
|
|
150
|
+
## Acceptance criteria
|
|
151
|
+
|
|
152
|
+
- All candidates have an evidence-backed status; implemented adapters have request/response contract tests.
|
|
153
|
+
- Every backend can be independently enabled/disabled.
|
|
154
|
+
- Every supported access mode can be explicitly chosen; no automatic selection or fallback exists.
|
|
155
|
+
- Saved keys are not sent in anonymous mode. Missing keys fail in key mode.
|
|
156
|
+
- Only allowed failures retry, with bounded attempts, proper deadlines, cancellation and `Retry-After` behavior.
|
|
157
|
+
- Quota exhaustion and permanent errors do not enter retry loops.
|
|
158
|
+
- Partial and total failures are visible to the Agent, with accurate attempt counts and no secrets.
|
|
159
|
+
- Every public config field is editable and survives save/read-back; validation and credential handling are tested.
|
|
160
|
+
- Mode/config changes cannot leak incompatible cached results or counters.
|
|
161
|
+
- Tests cover aggregation, duplicates, unsupported filters, empty results, malformed responses, limits, cancellation, cache and redaction.
|
|
162
|
+
- Real requests are verified where credentials exist; credential-blocked paths are explicitly unverified.
|
|
163
|
+
- Final diff, build output and test assertions are reviewed.
|
|
164
|
+
- Plugin metadata, icon, locale resources and package exports are complete.
|
|
165
|
+
- GUI is verified at `https://dsh.nite07.com/` after the appropriate artifact rebuild and refresh; a replacement server is not evidence.
|
|
166
|
+
- Existing search stays intact until migration verification; the old bundle remains available for rollback.
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# Verification status
|
|
2
|
+
|
|
3
|
+
Date: 2026-11-17 (Asia/Shanghai), profile `web`. The DSH release running at that moment is recorded once here as audit context; it is not a compatibility bound.
|
|
4
|
+
|
|
5
|
+
## Automated
|
|
6
|
+
|
|
7
|
+
`npm run check` (typecheck + 28 tests + build) passes. Coverage highlights:
|
|
8
|
+
|
|
9
|
+
- Config validation: unknown fields, ranges, enumerations, non-loopback `http`, credentials in URLs, unverified backends cannot be enabled.
|
|
10
|
+
- Fixed access modes: anonymous mode never resolves or transmits a stored key; key mode without a credential fails without any request; no fallback path exists in the engine.
|
|
11
|
+
- Retry: only allowlisted statuses; bounded attempts on the same endpoint; `Retry-After` honoured and never shortened; `401`/quota-exhaustion bodies are not retried and never surface in results.
|
|
12
|
+
- Failure reporting: partial failures and total failure appear in returned content with backend, mode, kind and attempt count; failed backends are not cached.
|
|
13
|
+
- Deduplication, domain filtering, local budget accounting (durable domain, serialized reservations, fail-closed on storage errors), cancellation.
|
|
14
|
+
- Protocol contracts: Zhihu GET casing/timestamp/Bearer, MCP initialize/initialized/tools-list/call with session header and strict RPC-id matching, You.com nested `results.web`, Tencent TC3 signature against an independently computed vector.
|
|
15
|
+
- Host surface: native Config defaults equal the shared client defaults; the authenticated route and the Agent tool share one implementation of save/test/credential operations; revision conflicts are rejected; a stored secret never appears in snapshots.
|
|
16
|
+
- Form coverage: every public scalar/array field and every backend field has a real control (a generic JSON box is not used as a substitute).
|
|
17
|
+
|
|
18
|
+
## Live, anonymous (no credentials, no charges)
|
|
19
|
+
|
|
20
|
+
Executed through the plugin engine and through DSH `web_search` after `searchProvider: nite-search` activation:
|
|
21
|
+
|
|
22
|
+
| Backend | Mode | Result |
|
|
23
|
+
| --- | --- | --- |
|
|
24
|
+
| Keenable | anonymous | Success, results returned |
|
|
25
|
+
| Exa | anonymous MCP | Success after adapting to the live `web_search_exa` schema (`query` + `objective`) |
|
|
26
|
+
| You.com | anonymous MCP | Success |
|
|
27
|
+
| SearXNG | self-hosted loopback | Success (returns more than requested; merged results are capped locally) |
|
|
28
|
+
| Parallel | anonymous MCP | HTTP 429 on this network; left disabled |
|
|
29
|
+
|
|
30
|
+
`web_fetch` still resolves through the `http` provider after the switch.
|
|
31
|
+
|
|
32
|
+
## Verified, not live
|
|
33
|
+
|
|
34
|
+
Keyed backends (Tavily, Brave, DeepSeek, Zhihu, Baidu, Doubao, Linkup, Serper, Serpex, OpenAI, Anthropic, Mojeek, Tencent) are request/response-tested against documented contracts only. No credential was supplied, so no live keyed call, billing check, or account-quota observation exists. Serper remains unverified and disable-able.
|
|
35
|
+
|
|
36
|
+
## Deployed state
|
|
37
|
+
|
|
38
|
+
- Bundle `@nite07/dsh-search` installed by Plugin Manager from the linked worktree; Host fiber active; Settings entry `nite-search` active in the live slot tree.
|
|
39
|
+
- `searchProvider: nite-search`, `fetchProvider: http`.
|
|
40
|
+
- Old bundle `@240xu/dsh-websearch` disabled, not removed (rollback: enable it and restore `searchProvider: unified`).
|
|
41
|
+
- Enabled backends: Keenable, Exa, You.com (anonymous) and local SearXNG. Everything else disabled.
|
|
42
|
+
|
|
43
|
+
## Not verified
|
|
44
|
+
|
|
45
|
+
- Rendered Settings page visuals, light/dark parity, keyboard flow and error-summary focus in the live page. The automation browser could not authenticate to `https://dsh.nite07.com/` (`ERR_INVALID_AUTH_CREDENTIALS`), and `/connect?token=…` returned 401 from this shell. The route itself answers 401 rather than 404 unauthenticated, and the slot occupant is registered, but no screenshot or manual pass exists.
|
|
46
|
+
- Save-through-UI round trip (the same Host operation is covered by tests and by the tool path).
|
|
47
|
+
- MCP anonymous quota behaviour under sustained load; HTML discovery (DuckDuckGo) layout changes; supplier-internal routing.
|
|
48
|
+
|
|
49
|
+
## UX pass (2026-11-17, same day)
|
|
50
|
+
|
|
51
|
+
Applied P0+P1 fixes: conditional field visibility (single-backend selector only in single mode; retry/breaker/cache/diagnostics dependants follow their switch; anonymous mode hides the credential surface; unverified backends are read-only), a pre-flight blocker banner (no backend enabled / single mode pointing at a disabled backend / key mode without a stored credential), structured trial-search results with failure reasons, diagnostics with time, reason and message, backend search/filter/count toolbar, collapsed-card cost chips and credential dot, nested advanced options, sticky save bar, inline confirmations instead of `window.confirm`, range-aware field errors, and a checkbox group for retry statuses.
|
|
52
|
+
|
|
53
|
+
`npm run check` now covers 31 tests, including `visible()` and `blockersOf()` semantics (hidden values are preserved, not reset). Rebuilt and reloaded via one authorized `dsh-web` restart; `web_search` still answers through `nite-search` afterwards and the settings entry stays registered.
|
|
54
|
+
|
|
55
|
+
Still unverified after this pass: the rendered page itself. The automation browser is rejected by the deployment edge (`ERR_INVALID_AUTH_CREDENTIALS`) for both the token URL and `/connect`, so there is no screenshot or manual keyboard pass. Visual, light/dark and focus behaviour rest on code review only.
|
|
56
|
+
|
|
57
|
+
## Tier correction (2026-11-17, same day)
|
|
58
|
+
|
|
59
|
+
Exa, AnySearch and Parallel anonymous modes had been filed under "unavailable · unverified API" because their free quotas carry no published number. That conflated cost with evidence. All three, plus Keenable, You.com and the local SearXNG instance, completed three consecutive real searches each in this deployment; Exa's keyless MCP is an official free tier per its own documentation ("No API key is needed to try search and fetch, at a free rate limit"). Cost tier and verification evidence are now separate fields. DuckDuckGo stays documented-only: it answered with a challenge on this network, and no bypass was attempted.
|
|
60
|
+
|
|
61
|
+
## Language/region and provider visibility (2026-11-17, after restart)
|
|
62
|
+
|
|
63
|
+
Live check with canonical `language=zh-Hans`, `region=CN` and retry/cache disabled:
|
|
64
|
+
|
|
65
|
+
| Backend | Outcome | Disclosed |
|
|
66
|
+
| --- | --- | --- |
|
|
67
|
+
| Keenable | 2 sources | language and region unsupported, not applied upstream |
|
|
68
|
+
| SearXNG | 26 sources (capped locally) | language applied as `zh-CN`; region unsupported |
|
|
69
|
+
| You.com | 2 sources | both applied in upper-case form |
|
|
70
|
+
|
|
71
|
+
So an unsupported canonical value is never forwarded as a guess, and a supported one reaches the backend in its own spelling. Saved values are validated against the fixed lists, so a backend-specific spelling can no longer be typed in by hand.
|
|
72
|
+
|
|
73
|
+
The settings snapshot also reports the provider the web seam currently selects. When it is not this plugin, the page states which provider is in effect and offers a one-click switch; the built-in providers stay registered and are simply never selected while `searchProvider: nite-search` is pinned.
|
package/icon.svg
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" width="36" height="36" viewBox="0 0 36 36"><g fill="none" stroke="#567e9b" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"><circle cx="15.5" cy="15.5" r="8.2"/><path d="m21.4 21.4 7.2 7.2M11.5 13h8M11.5 17h5"/></g></svg>
|