dsh-web-search-serper
English | 中文
Overview
@dingpenghui/dsh-web-search-serper is a web search provider plugin backed by the Serper.dev API, for the current DeepSeek Harness (DSH) web capability seam (ctx.web, @deepseek-ai/dsh-web 0.2.0-rc.x).
Serper.dev is an official Google Search partner providing fast, structured Google search results API. Free tier: 2,500 queries per month, no credit card required.
Features
- 🚀 Fast Search — 1-2 second response times using Google's real index
- 📊 Structured Results — JSON format, easy to parse
- 🔒 Privacy Friendly — No user tracking, no cookie collection
- 💰 Generous Free Tier — 2,500 monthly queries at no cost
- 🌍 Multi-language Support — Results from countries/regions worldwide
- 🔧 One-line Insert — a single row in your profile
cordis.patch.yml; key resolved lazily per search (config → env → credential store), no restart on change
Quick Start
Install
# 作为 profile bundle 装入（推荐）：
# 1. 在 profile 的 package.json `dependencies` 加：
# "dsh-web-search-serper": "link:<本目录绝对路径>"
# 2. 同步 `dsh.profile.bundles` 加 "dsh-web-search-serper"
# 与 cordis.patch.yml 加 insert 行（或直接复制本包自带 cordis.patch.yml 的内容）
pnpm install
pnpm run build
Configure
Add to your DSH cordis.patch.yml (profile patch layer):
- insert:
- id: web-search-serper
name: 'dsh-web-search-serper'
No config is required: the API key is resolved lazily per search in this order:
- row
config.apiKey (explicit, when you add a config block to the row — editable on the plugin detail page, hot-applied after save);
- the
SERPER_API_KEY environment variable of the DSH host process;
- a
SERPER_API_KEY reference in the DSH credential store
($DSH_HOME/.credentials.yaml refs: — resolved per search, no restart on change).
To pin the key and options in the composition instead:
- insert:
- id: web-search-serper
name: 'dsh-web-search-serper'
config:
apiKey: your-serper-api-key
gl: cn # Optional: set default country code
Get API Key
- Visit https://serper.dev
- Register for a free account
- Get your API Key from the Dashboard
- Free tier: 2,500 queries per month
Configuration Options
| Field | Type | Required | Default | Description |
|---|
apiKey | string | No | $SERPER_API_KEY, then credential reference SERPER_API_KEY | Serper API key (secret, volatile) |
baseURL | string | No | https://google.serper.dev | API endpoint base |
gl | string | No | - | Country code (e.g., us, cn, jp) |
cr | string | No | - | Region code (e.g., us; sent as the cr parameter) |
numResults | number | No | omitted (Serper defaults to 10) | Default result count, capped at 100 |
Usage Examples
Basic Search
import { apply } from 'dsh-web-search-serper'
// Used by the Cordis loader; no direct calls needed in most deployments.
// In a Cordis plugin:
// apply(ctx)
Search via ctx.web
const result = await ctx.web.search({
query: 'latest AI developments 2026',
maxResults: 5,
})
console.log(result.sources)
// [
// { url: '...', title: '...', snippet: '...' },
// ...
// ]
Error Handling
| Error Code | Meaning | Resolution |
|---|
WEB_PROVIDER_CONFIGURED_MISSING | Configured provider not registered | Check if plugin is loaded correctly |
WEB_PROVIDER_CONFIGURED_UNAVAILABLE | Provider registered but no key available | Check API key: config / $SERPER_API_KEY / credential reference |
WEB_ABORTED | Request was aborted | Check AbortSignal |
WEB_PROVIDER_ERROR | API request failed | Check network / API key / rate limits |
Limitations & Known Issues
- Free tier limit — 2,500 monthly queries, paid plans for higher usage
- Google Search only — Does not support Bing, Baidu, or other search engines
- No generated answers — Returns search results only, no AI-generated summaries
- API Key required — Must provide a valid Serper API Key via config, environment, or credential reference
Related Projects
License
MIT License — See LICENSE file
