dsh-search-first

Readme

# Search First 

[中文](./README_zh.md)

**Search first, verify facts, reply last — enforced by DSH.**

[![Search First — demo walkthrough](./assets/enable-button.png)](https://youtu.be/rGc5OCydHyY)

▶ Demo walkthrough: https://youtu.be/rGc5OCydHyY
> A DeepSeek Harness (dsh) Cordis plugin that **forces multi-source web search before the model answers**.
> On `agent/pre-step`, when **Search First** is enabled, 
> it runs Query Extraction → Unified Search Engine (AnySearch / TinyFish / Tavily) → fetch → organize → cache + `runs/` persistence → inject the organized live leeds guiding verification next, then returns control to the agent loop. Final answers stay with the LLM.

## Features

1. The sub-model used for query extraction is configurable.
2. Guides the host model to use standardized citations, as shown below.
   ![Custom HTML citation tags](./assets/sf_tag.png)
3. Models and ranks multi-source search results, and selectively fetches pages back to the host model.

## Installation

Prerequisites: a mounted `dsh` web profile (dsh ≥ 0.1.1-rc.2), Node ≥ 22.

```bash
# install from the GitHub repo:
dsh plugin --profile web add https://github.com/v587d/dsh-search-first.git
```

Uninstall: `dsh plugin --profile web remove dsh-search-first` (then restart).

### Build from source

```bash
pnpm install
pnpm check      # vitest + typecheck (host + client)
pnpm build      # lib/ (host ESM + d.ts) + lib/client.js (browser bundle)
pnpm test
```

## Quick start
> [!IMPORTANT]
> Export at least **one** API key ([AnySearch](https://anysearch.com/) / [Tinyfish](https://www.tinyfish.ai/) / [Tavily](https://www.tavily.com/)) before running.  
> **Free tier is ENOUGH**.

1. Restart `dsh web` after installing.
2. Open Settings → **Search first** → **Search APIs** → **Test all connections**
   (configure keys first via step 3, or the probe reports a key-missing result).
3. Provide at least one provider key — add it to `$DSH_HOME/.credentials.yaml`
   or `export TAVILY_API_KEY` / `ANYSEARCH_API_KEY` / `TINYFISH_API_KEY` in the
   environment. AnySearch also works anonymously (Bearer header omitted).
4. Back in a session, the **Search First** toggle under the input box decides
   per session (right-click the toggle to return to the global default).




## Configuration (Settings → Search first)

| Section | Fields |
|---|---|
| General | default enabled, failure policy (`continue` / `block`), injection mode, overall timeout |
| Query Extraction | explicit provider/model (empty = follow session model), timeout, max tokens |
| Cache | dir (empty = `$DSH_HOME/search-first`; root applies after restart), search/fetch TTL, clear button |
| Limits | max search results, max fetch pages, max inject chars |
| Search APIs | mode (sequential failover / parallel fan-out + merge), big-three enable/credential-ref/priority, per-provider timeout, `ctx.web` fallback, local HTTP fallback, **Test all connections** |

## License

MIT — see [LICENSE](./LICENSE).