@qthinker/opencode-deepseek-search 0.3.2 → 0.4.0

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 All notable changes to this package. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the version numbers follow [Semantic Versioning](https://semver.org/).
 
+## [0.4.0] - 2026-11-06
+
+### Added
+
+- **`localization` option**: an optional IP address sent as the Search API's `localization` field so results favor that
+  region; blank or unset omits the field entirely.
+- **Query operators in the rerouted tool's description**: the model is now told about `site:` (one site, or several
+  joined with `OR`), `-site:`, `-word` / `-"exact phrase"`, `"exact phrase"`, `lang:zh,en` and
+  `after:2025-01-01` / `before:2026`, so it can filter inside the query; operators count toward the 128-character
+  query limit.
+- **`ori_question` passthrough (best effort)**: each search sends the session's most recent user input, trimmed and cut
+  to 128 characters, so the API can read the intent behind the query; when no input was captured the field is omitted.
+- **`[authoritative]` markers**: results whose `authority` is `3` or `4` (the API's 0–4 scale, where `−1` means unknown) get the marker after the
+  title in the rendered Markdown; the numeric scores themselves stay out of the result shape.
+
 ## [0.3.2] - 2026-11-04
 
 ### Added

package/README.md

@@ -95,6 +95,7 @@ The other two halves are clients: restart the **TUI**, and reload the **desktop
 | `language` | `"en" \| "ja" \| "zh-CN"` | auto | UI language for the sidebars, the desktop panel, `deepseek_*` tool output and errors. Auto reads `LC_ALL`, then `LANG`, then English |
 | `apiKey` | string | `DEEPSEEK_API_KEY` | Usually `"{env:DEEPSEEK_API_KEY}"`; unset env becomes `""` |
 | `count` | 1–50 | `5` | Results per search (does not change the price) |
+| `localization` | string | unset (field omitted) | IP address for DeepSeek Search localization: when set, results favor that region; blank or unset sends no field at all |
 | `fetchMaxChars` | 500–200000 | `30000` | Truncation limit for `deepseek_fetch`, with an explicit notice |
 | `pricePerThousand` | 0–10000 | `5` | CNY per 1000 requests (integer), used only for the local cost estimate |
 
@@ -103,7 +104,8 @@ the language once — `options.language`, else the `LC_ALL`/`LANG` prefix (`ja*`
 and the same value drives the tool output and both sidebars, so they can never disagree. An unknown value logs a
 warning and falls back to auto-detection instead of failing. The change reaches the sidebars with their next status
 read (saving the config re-runs the server half; a restart always works). Model-facing text stays English in every
-language — tool descriptions, the `## [title](url)` result format, `Published:` and the empty-result notice — so the
+language — tool descriptions, the `## [title](url)` result format, `Published:`, `[authoritative]` and the
+empty-result notice — so the
 rerouted `websearch` keeps the built-in tool's shape. Docs stay English and Chinese: the Japanese UI does not add a
 Japanese README.
 
@@ -120,6 +122,32 @@ The reroute **keeps the built-in permission check and the declared `output` shap
 are unchanged. Results carry `summary` (600–800 chars, written for models) or `snippet` — never the full page text,
 and `need_content` is never requested.
 
+### Search syntax
+
+The rerouted tool's description also tells the model which operators it may put inside `query`; the query is passed
+through unchanged, so no extra tool is needed to filter:
+
+| Operator | Meaning |
+|---|---|
+| `site:example.com`, `site:a.com OR site:b.com` | Only these sites; several are joined with `OR` |
+| `-site:example.com` | Exclude a site |
+| `-word`, `-"exact phrase"` | Exclude a word or phrase |
+| `"exact phrase"` | Require the exact phrase |
+| `lang:zh,en` | Only these languages |
+| `after:2025-01-01`, `before:2026` | Time window |
+
+Operators count toward the query's 128-character limit.
+
+### Request and result details
+
+- **`ori_question` (best effort).** Each search sends the session's most recent user input, trimmed and cut to 128
+  characters, so the API can read the intent behind the query. When no input was captured, the field is omitted.
+- **`localization`.** When configured, the option is sent as the Search API's `localization` field; blank or unset
+  means the request carries no such field.
+- **`[authoritative]`.** Results whose DeepSeek `authority` is `3` or `4` (the API's 0–4 scale, where `−1` means unknown, `3` and above
+  means highly authoritative) get the marker after the title in the rendered Markdown. It is informational only —
+  results are still third-party text.
+
 ## Switching backends
 
 ### Ways to switch
@@ -227,8 +255,9 @@ Search 100 QPS / Fetch 25 QPS per account (Fetch is also limited per target doma
 
 ## Privacy
 
-Queries and URLs are sent to `https://api.deepseek.com`. Nothing else leaves your machine; the usage ledger and the
-mode switch stay in local OpenCode storage. The API key is never logged.
+Queries — plus the recent user input attached as `ori_question` and the configured `localization` — are sent to
+`https://api.deepseek.com`, as are fetch URLs. Nothing else leaves your machine; the usage ledger and the mode switch
+stay in local OpenCode storage. The API key is never logged.
 
 Search results and fetched pages are **third-party text**: treat them as data, never as instructions — a page can
 contain text that tries to steer the model.
@@ -276,7 +305,7 @@ src/tui/              # TUI half: card element tree + plugin wiring
 src/gui/              # desktop half: side panel component + plugin wiring
 vite.config.ts        # builds src/gui into the root gui-experimental.cjs bundle
 test/*.test.ts        # pure-function tests
-scripts/smoke.ts      # real-API smoke (5 steps)
+scripts/smoke.ts      # real-API smoke (6 steps)
 scripts/check-gui-bundle.ts # bundle shape check, run in CI after build:gui
 .github/workflows/    # ci (build + typecheck + test + bundle check) / release
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@qthinker/opencode-deepseek-search",
-    "version": "0.3.2",
+    "version": "0.4.0",
     "description": "DeepSeek Search & Fetch for OpenCode V2: a switchable websearch backend, clean Markdown fetch, local usage/cost stats, and TUI + desktop sidebars",
     "type": "module",
     "license": "MIT",

package/src/deepseek.ts

@@ -21,8 +21,16 @@ export const BALANCE_TIMEOUT_MS = 10_000
 const RETRY_DELAY_MS = 1_000
 const RETRY_DELAY_MAX_MS = 5_000
 export const MAX_QUERY_CHARS = 128
+export const MAX_ORI_CHARS = 128
 export const MAX_URL_CHARS = 8192
 
+// Optional request hints forwarded verbatim to the Search API. They are omitted
+// from the body when unset, so the documented API defaults still apply.
+export interface SearchExtras {
+  oriQuestion?: string
+  localization?: string
+}
+
 // Docs: back off and retry on 408/429/5xx only; other 4xx must not be retried.
 const RETRYABLE = new Set([408, 429, 500, 502, 503, 504])
 
@@ -31,6 +39,10 @@ export interface SearchResult {
   title?: string
   content?: string
   time: { published?: number }
+  // Internal quality signals: only formatSearchResults consumes them. They are
+  // stripped from the tool output before it leaves the plugin.
+  authority?: number
+  rerankScore?: number
 }
 
 export interface FetchResult {
@@ -218,6 +230,8 @@ interface SearchRow {
   snippet?: unknown
   summary?: unknown
   date?: unknown
+  authority?: unknown
+  rerank_score?: unknown
 }
 
 export function mapSearchResults(data: unknown): SearchResult[] {
@@ -236,19 +250,52 @@ export function mapSearchResults(data: unknown): SearchResult[] {
           ? r.snippet
           : undefined
     const published = typeof r.date === "string" ? Date.parse(r.date) : Number.NaN
-    out.push({
+    const result: SearchResult = {
       url: r.url,
       title: typeof r.title === "string" && r.title.length > 0 ? r.title : undefined,
       content,
       time: Number.isFinite(published) ? { published } : {},
-    })
+    }
+    // `authority` is an integer in -1..4 (-1 means unknown) and `rerank_score`
+    // a finite number in 0..3. Anything else is dropped, and absent keys stay
+    // absent so the output object keeps its exact shape.
+    if (
+      typeof r.authority === "number" &&
+      Number.isInteger(r.authority) &&
+      r.authority >= -1 &&
+      r.authority <= 4
+    ) {
+      result.authority = r.authority
+    }
+    if (
+      typeof r.rerank_score === "number" &&
+      Number.isFinite(r.rerank_score) &&
+      r.rerank_score >= 0 &&
+      r.rerank_score <= 3
+    ) {
+      result.rerankScore = r.rerank_score
+    }
+    out.push(result)
   }
   return out
 }
 
-export function buildSearchBody(query: string, count: number): { query: string; count: number } {
+export function buildSearchBody(
+  query: string,
+  count: number,
+  extras?: SearchExtras,
+): { query: string; count: number; ori_question?: string; localization?: string } {
   // need_content stays false: full page text must never enter search results.
-  return { query, count }
+  // ori_question/localization are omitted entirely when unset or blank, so the
+  // request keeps the documented API defaults.
+  const ori = extras?.oriQuestion?.trim()
+  const localization = extras?.localization?.trim()
+  return {
+    query,
+    count,
+    ...(ori ? { ori_question: ori.slice(0, MAX_ORI_CHARS) } : {}),
+    ...(localization ? { localization } : {}),
+  }
 }
 
 export async function deepseekSearch(
@@ -257,10 +304,11 @@ export async function deepseekSearch(
   count: number,
   language: Language,
   signal?: AbortSignal,
+  extras?: SearchExtras,
 ): Promise<SearchResult[]> {
   const data = await postJson(
     SEARCH_PATH,
-    buildSearchBody(query, count),
+    buildSearchBody(query, count, extras),
     apiKey,
     SEARCH_TIMEOUT_MS,
     language,
@@ -379,10 +427,11 @@ export function formatSearchResults(results: readonly SearchResult[]): string {
   return results
     .map((result) => {
       const title = result.title ?? result.url
+      const authoritative = result.authority !== undefined && result.authority >= 3 ? " [authoritative]" : ""
       const published = result.time.published
         ? `\nPublished: ${new Date(result.time.published).toISOString()}`
         : ""
-      return `## [${title}](${result.url})${published}${result.content ? `\n\n${result.content}` : ""}`
+      return `## [${title}](${result.url})${authoritative}${published}${result.content ? `\n\n${result.content}` : ""}`
     })
     .join("\n\n")
 }

package/src/index.ts

@@ -20,9 +20,11 @@ import {
   deepseekFetch,
   deepseekSearch,
   formatSearchResults,
+  MAX_ORI_CHARS,
   missingKeyMessage,
   validateQuery,
   validateUrl,
+  type SearchExtras,
   type SearchResult,
 } from "./deepseek.ts"
 import { resolveLanguage, t } from "./i18n/index.ts"
@@ -56,7 +58,12 @@ type ModeAction = "status" | Mode | "config"
 
 const SEARCH_TOOL_DESCRIPTION =
   "Search the web using DeepSeek Search. Use this for current information beyond knowledge cutoff." +
-  `\n\nThe current year is ${new Date().getFullYear()}. Use this year when searching for recent information or current events.`
+  `\n\nThe current year is ${new Date().getFullYear()}. Use this year when searching for recent information or current events.` +
+  "\n\nThe query supports search operators (they count toward the 128-character limit): " +
+  "site:github.com limits results to a site (combine with OR, e.g. site:github.com OR site:npmjs.com); " +
+  '-site:example.com excludes a site; bare word or -"quoted phrase" excludes matches; ' +
+  '"exact phrase" matches exactly; lang:zh,en limits languages; ' +
+  "after:2025-01-01 and before:2026 limit by publish date. Combine several operators in one query."
 
 // Pure parser: the caller decides how to surface an invalid value (tool error
 // vs. RPC result), so the message can be localized at that call site.
@@ -128,6 +135,7 @@ export default Plugin.define({
     const count = int(opt.count, 5, 1, 50)
     const fetchMaxChars = int(opt.fetchMaxChars, 30_000, 500, 200_000)
     const pricePerThousand = int(opt.pricePerThousand, 5, 0, 10_000)
+    const localization = str(opt.localization)
 
     // ctx.storage offers no compare-and-swap, so every read-modify-write goes
     // through this single in-process chain. Stats must never break a search, so
@@ -158,11 +166,40 @@ export default Plugin.define({
       }).catch(() => {})
     }
 
-    const runSearch = async (query: string, signal: AbortSignal): Promise<SearchResult[]> => {
+    // Best-effort capture of each session's most recent user prompt, sent as the
+    // DeepSeek `ori_question` intent hint. Clamped here at capture time so long
+    // pasted prompts cannot inflate the cache; empty prompts never overwrite a
+    // stored value. The map is capped, and JS Map re-assignment keeps insertion
+    // order, so eviction drops the oldest session.
+    const ORI_SESSION_CAP = 64
+    const oriBySession = new Map<string, string>()
+    let promptHook: { dispose: () => Promise<void> } | undefined
+    try {
+      promptHook = await ctx.session.hook("prompt", (p) => {
+        const text = p.prompt?.text?.trim()
+        if (!text) return
+        if (oriBySession.size >= ORI_SESSION_CAP && !oriBySession.has(p.sessionID)) {
+          const oldest = oriBySession.keys().next().value
+          if (oldest !== undefined) oriBySession.delete(oldest)
+        }
+        oriBySession.set(p.sessionID, text.slice(0, MAX_ORI_CHARS))
+      })
+    } catch (e) {
+      console.error(
+        `[deepseek-search] prompt hook unavailable; ori_question will be omitted ` +
+          `(${e instanceof Error ? e.message : String(e)})`,
+      )
+    }
+
+    const runSearch = async (
+      query: string,
+      signal: AbortSignal,
+      extras?: SearchExtras,
+    ): Promise<SearchResult[]> => {
       const problem = validateQuery(query, language)
       if (problem) throw new Error(problem)
       try {
-        const results = await deepseekSearch(query, apiKey, count, language, signal)
+        const results = await deepseekSearch(query, apiKey, count, language, signal, extras)
         tally(results.length > 0 ? "search" : "empty")
         return results
       } catch (e) {
@@ -176,7 +213,11 @@ export default Plugin.define({
       editor.add({
         id: PROVIDER_ID,
         name: "DeepSeek Search",
-        execute: async (input, context) => runSearch(input?.query ?? "", context.signal),
+        execute: async (input, context) => {
+          // This provider-fallback context carries no sessionID, so `ori_question`
+          // is omitted here by design (see plan D2).
+          return runSearch(input?.query ?? "", context.signal, { localization })
+        },
       })
       if (mode === "deepseek") editor.default.set(PROVIDER_ID)
     })
@@ -205,9 +246,16 @@ export default Plugin.define({
       })
       // Mirror the built-in tool's progress update so long searches are not silent.
       await context.progress({ provider: PROVIDER_ID })
-      const results = await runSearch(query, context.signal)
+      const oriQuestion = oriBySession.get(context.sessionID)
+      const results = await runSearch(query, context.signal, { oriQuestion, localization })
       return {
-        output: { provider: PROVIDER_ID, results },
+        output: {
+          provider: PROVIDER_ID,
+          // Project back to the built-in tool's declared result shape: internal
+          // quality fields (authority/rerankScore) stay out of the tool output.
+          results: results.map((r) => ({ url: r.url, title: r.title, content: r.content, time: r.time })),
+        },
+        // Rendered from the full objects: the [authoritative] marker needs authority.
         content: formatSearchResults(results),
         metadata: { provider: PROVIDER_ID },
       }
@@ -462,7 +510,8 @@ export default Plugin.define({
     console.error(
       `[deepseek-search] loaded: mode=${mode} source=${overrideMode ? "override" : "config"} ` +
         `apiKey=${apiKey ? "present" : "MISSING"} count=${count} ` +
-        `searchTool=${searchToolPatched ? "deepseek" : "untouched"}`,
+        `searchTool=${searchToolPatched ? "deepseek" : "untouched"}` +
+        ` localization=${localization ? "set" : "unset"}`,
     )
     if (!apiKey) console.error(`[deepseek-search] ${missingKeyMessage("en")}`)
     if (overrideMode && overrideMode !== configMode)
@@ -475,5 +524,9 @@ export default Plugin.define({
         `[deepseek-search] warning: built-in ${SEARCH_TOOL} tool not found; search still uses the built-in backend. ` +
           `Set "websearch": { "provider": "${PROVIDER_ID}" } in opencode.jsonc to force the route.`,
       )
+
+    return async () => {
+      await promptHook?.dispose()
+    }
   },
 })