@dingpenghui/dsh-web-search-serper

English | 中文

Overview

@dingpenghui/dsh-web-search-serper is a web search provider plugin backed by the Serper.dev API, designed for the DeepSeek Harness (DSH) web capability seam (ctx.web).

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
• 🔧 Zero-config Integration — One line to connect with DSH

---

Quick Start

Install

pnpm add @dingpenghui/dsh-web-search-serper
# or
npm install @dingpenghui/dsh-web-search-serper

Configure

Add to your DSH cordis.patch.yml (profile patch layer):

- id: web
  config:
    searchProvider: serper

- insert:
    - id: web-search-serper
      name: '@dingpenghui/dsh-web-search-serper'

No config is required: the API key is resolved per search in this order:

1. row config.apiKey (explicit, when you add a config block to the row);
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: — hot-reloaded, no restart on change).

To pin the key in the composition instead, add a row config block:

- insert:
    - id: web-search-serper
      name: '@dingpenghui/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
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 '@dingpenghui/dsh-web-search-serper'

// Use in a Cordis plugin
apply(ctx, {
  apiKey: 'your-api-key',
  gl: 'cn',
})

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 unavailable	Check if API Key is valid
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 in configuration

---

Related Projects

• DeepSeek Harness — DSH main project
• Serper.dev — Google Search API service
• @dsh-web-search-exa — Exa search provider
• @dsh-web-search-perplexity — Perplexity search provider

---

License

MIT License — See LICENSE file

---

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

Support

For issues and questions:

• Submit a GitHub Issue
• Check the Documentation