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:

1. row config.apiKey (explicit, when you add a config block to the row — editable on the plugin detail page, hot-applied after save);
2. the SERPER_API_KEY environment variable of the DSH host process;
3. 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

1. Visit https://serper.dev
2. Register for a free account
3. Get your API Key from the Dashboard
4. 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

1. Free tier limit — 2,500 monthly queries, paid plans for higher usage
2. Google Search only — Does not support Bing, Baidu, or other search engines
3. No generated answers — Returns search results only, no AI-generated summaries
4. API Key required — Must provide a valid Serper API Key via config, environment, or credential reference

---

Related Projects

• DeepSeek Harness — DSH main project
• Serper.dev — Google Search API service

---

License

MIT License — See LICENSE file