pi-deepseek-web-search

A pi extension that gives any model in your pi sessions a DeepSeek-backed web search tool, bridging the DeepSeek /responses API server-side web search.

中文说明

Features

• Forced search — every call executes a real web search (tool_choice: { type: "web_search" }); the model cannot skip it
• Synthesized answer with citations returned by DeepSeek, plus a record of the executed search actions
• Configurable via env vars, project config file, or global config file (in that order of precedence)
• TTL result cache — repeated identical queries within the TTL hit the cache and cost nothing
• Real cost reporting — token prices are configurable (USD per 1M tokens), official peak/off-peak pricing is enabled by default, and the reported Usage.cost reflects the actual estimated spend
• Model selectable — use deepseek-v4-flash (default), deepseek-v4-pro, or another Responses API model name via config
• Generated JSON Schema — the config file definition is a single source of truth (src/config-schema.ts); English and Chinese schemas are generated from it (see Schema)

Install

Published to npm with SLSA provenance via OIDC Trusted Publishing. In any pi project:

pi install npm:pi-deepseek-web-search

Then run /reload in the pi session.

Alternatively, for local development of this package: pi install ., or symlink/copy src/index.ts into your project's .pi/extensions/.

Configuration

Config is read from, in order of precedence (later sources override earlier ones):

1. Environment variables
2. Project config file: .pi/deepseek-web-search.json
3. Global config file: ~/.pi/agent/deepseek-web-search.json

Config is cached in the extension process per working directory. After changing config files or environment variables, restart pi (or run /deepseek-search status to force a reload) before searching again. If no API key is configured here, the tool falls back to the DeepSeek provider API key already configured in pi.

Example (~/.pi/agent/deepseek-web-search.json)

{
  "$schema": "./npm/node_modules/pi-deepseek-web-search/schema/deepseek-web-search.config.schema.en.json",
  "apiKey": "sk-...",
  "model": "deepseek-v4-flash",
  "reasoningEffort": "high",
  "prices": {
    "inputPerMillion": 0.22,
    "cachedInputPerMillion": 0.007,
    "outputPerMillion": 0.66
  }
}

$schema is only used by editors for autocomplete/validation and is ignored at runtime. The path above works when the package is installed in the project's node_modules (relative to .pi/); adjust it for other install locations. Use the .en.json schema for English comments, or the .zh.json one for Chinese.

Config fields

Environment variable equivalents: DEEPSEEK_API_KEY, DEEPSEEK_BASE_URL, DEEPSEEK_MODEL, DEEPSEEK_REASONING_EFFORT, DEEPSEEK_MAX_OUTPUT_TOKENS, DEEPSEEK_TIMEOUT_MS, DEEPSEEK_CACHE_TTL_MS, DEEPSEEK_MAX_RESULT_CHARS, DEEPSEEK_PRICE_INPUT, DEEPSEEK_PRICE_CACHED_INPUT, DEEPSEEK_PRICE_OUTPUT.

Numeric environment variables accept canonical decimal strings only, for example 30000 or 1.5; forms such as +1, .5, 1e3, 30_000, and 30s are rejected. Price environment variables are interpreted as USD per 1M tokens.

Pricing and peak hours

From 2026-08-17 00:00 Beijing time, DeepSeek uses peak/off-peak pricing. Defaults follow the official pricing page:

All values are USD per 1M tokens. On weekdays, peak hours are Beijing time 09:00–12:00 and 14:00–18:00, and peak price = off-peak × 2. From 2026-08-23 00:00 Beijing time, Saturday and Sunday are off-peak all day. The official schedule is enabled by default; set prices.peak only to override it:

"prices": {
  "peak": {
    "multiplier": 2,
    "hours": [["09:00", "12:00"], ["14:00", "18:00"]],   // half-open [start, end)
    "weekendOffPeak": true
  }
}

• The per-model pro prices above are preconfigured under prices.models."deepseek-v4-pro" and apply automatically when model is set to deepseek-v4-pro
• weekendOffPeak defaults to true; set it to false only when a custom price schedule should retain weekend peak pricing
• The Usage.cost reported by the tool reflects the computed estimate using the request start time; cached hits report no cost (no API call happened). details.usage still keeps the first search's raw usage record for inspection

Model support

deepseek-v4-flash and deepseek-v4-pro both support the Responses API. DeepSeek also lists the experimental vision model deepseek-v4-flash-vision-exp; the model field is intentionally free-form, so it can be selected without a schema update. This plugin sends text queries only and does not support image input.

The two primary aliases currently point to DeepSeek-V4-Flash-0731 and DeepSeek-V4-Pro-0813; call names remain unchanged. deepseek-v4-flash is the default. Pro prices switch automatically via prices.models; the vision model uses the same official pricing as flash, so the existing top-level price fallback applies without a dedicated override.

Usage

Ask the model a time-sensitive or external question; it will invoke deepseek_web_search automatically:

What is the weather in Beijing today?

The tool returns DeepSeek's synthesized answer with citations plus the executed search actions. Results are cached per working directory, base URL, model:mode:query for cacheTtlMs.

The /deepseek-search command shows config status (key configured, model, cache size) and can clear the cache.

Schema

The config file definition is maintained once in src/config-schema.ts (TypeBox) and everything else is derived:

• ConfigFileShape type (via Static<>)
• Runtime validation (via Check/Errors)
• Two generated JSON Schema files:
  • schema/deepseek-web-search.config.schema.en.json (English comments)
  • schema/deepseek-web-search.config.schema.zh.json (Chinese comments)

Regenerate after changing the definition:

pnpm gen:schema

Generated files are committed and a test asserts they stay in sync with the definition.

Development

pnpm check     # tsc --noEmit
pnpm lint      # eslint
pnpm test      # vitest
pnpm gen:schema

FAQ

• Why not the built-in web search tool? This tool is useful when you want search backed by the DeepSeek API (e.g., to reuse an existing DeepSeek account/balance, or when the session model lacks a built-in search).
• Does it return a list of sources? DeepSeek's search runs server-side; the answer contains inline citations, and the tool additionally records the executed search actions (searched:/opened: lines) in the returned content.
• How much does it cost? DeepSeek charges per token; the tool reports an estimated Usage.cost based on your configured prices. See the official pricing page.
• I get an "API key is not configured" error — set DEEPSEEK_API_KEY or add apiKey to the config file.