superagents-lab/dsh-s1

Native s1 tools for the DeepSeek Harness (DSH).

Unlike the MCP server (search1api-mcp, a generic bridge that surfaces as mcp__search1api__*) or the CLI skill (which teaches the model to shell out to s1), this package registers first-class DSH tools named s1_* — same layer as read, bash, subagent, workflow. Calls run in-process against the official @search1api/client SDK.

Tools

Tool	Backed by	Status
s1_search	Search1API.search()	✅
s1_news	Search1API.news()	✅
s1_ask	Search1API.ask()	Ready
s1_crawl	Search1API.crawl()	✅
s1_sitemap	Search1API.sitemap()	✅
s1_trending	Search1API.trending()	✅

Not yet implemented: s1_screenshot (needs DSH attachment/image support) and s1_deepcrawl (long-polling task).

Skill

The package also bundles a s1 skill (ctx.skills.register), which teaches the model how to pick the right tool and tune parameters — quick lookup vs deep research, source/recency signals, Chinese-query engine choice, and when to follow a search result with s1_crawl. It is registered with the tools and can be disabled independently via skill: false.

Architecture

@search1api/client  (official SDK, in-process)
        │ import
dsh-s1              (Cordis plugin: name/inject/apply)
        │ loaded by the `s1-tools` row in cordis.patch.yml
ctx.tools.register(defineTool({ name: "s1_search", ... }))
        │
DSH model sees `s1_search` as a native tool

The package is both the bundle (its dsh.bundle.patch → cordis.patch.yml) and the plugin (its main entry exports name/inject/apply). The patch inserts a single loader row that references the package itself:

- insert:
    - id: s1-tools
      name: 'dsh-s1'

Install into a DSH profile

First publish (or npm link / local path) the package, then:

dsh plugin --profile web add dsh-s1

For a local checkout, use a path spec (the plugin command anchors relative paths to your invoking directory):

cd /Volumes/More/Products/search1api/ecosystem/dsh-s1
npm run build                      # produce lib/index.js + lib/index.d.ts
cd ~/.dsh
dsh plugin --profile web add file:/Volumes/More/Products/search1api/ecosystem/dsh-s1

dsh plugin reconciles dsh.profile.bundles: because this package declares dsh.bundle.patch, it is appended to the profile's bundle stack automatically.

Authentication

The SDK reads its key lazily, so a missing key fails the tool call (not plugin activation). There is exactly one credential variable:

export S1_KEY=...

OAuth (roadmap — not implemented yet)

s1's API accepts Authorization: Bearer <token> for both an API key and an OAuth access token, so the transport layer is token-agnostic. The OAuth flow (browser login, PKCE, token storage, refresh) currently lives only in search1api-cli (s1 login + auth.ts); @search1api/client does not yet expose it. The DSH plugin will support OAuth by reusing or sinking that flow, rather than re-implementing it — tracked separately from this skeleton.

Config

Key	Default	Description
search	true	Register s1_search.
news	true	Register s1_news.
ask	true	Register s1_ask (5 credits per call).
crawl	true	Register s1_crawl.
sitemap	true	Register s1_sitemap.
trending	true	Register s1_trending.
skill	true	Register the bundled s1 skill.

Development

npm install
npm run typecheck
npm run build

Current API capabilities

Search supports bingcn, yandex, and grokipedia; sogou is removed. Search and news support day, week, month, and year. Search accepts page on engines with native pagination.

The default Ask tool accepts only a natural-language query. The server chooses engines and a time window and returns query, intent, ranked results, and errors. Ask results include source and relevance; this endpoint returns search results rather than a generated answer. Each call costs 5 credits. Use ordinary search when the engine and keywords are known.

Engine-specific search/news attributes stay inside optional per-result metadata: GitHub uses kind, stars, language, and num_comments; Hacker News news results use story_url, points, and num_comments. published_date stays optional at the result top level. Zero counts are preserved and unavailable fields are omitted. Credit Grokipedia results as "Powered by xAI".

s1_ask is enabled by default; set ask: false to disable it. Requires @search1api/client>=0.4. Citable output maps link to url while keeping dates, metadata and Ask scores.