dsh-tool-hackernews

Readme

# dsh-tool-hackernews

English | [中文](README.zh.md)

Hacker News tool suite for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH) agents: `hn_top_stories`, `hn_search`, and `hn_item`. Built on the free [Algolia HN search API](https://hn.algolia.com/api) — **no API key required**.

## Tools

| Tool | Args | Behavior |
|---|---|---|
| `hn_top_stories` | `limit` (optional, 1–30) | The current Hacker News front page: titles, links, scores, comment counts, authors, relative times. |
| `hn_search` | `query` (required), `tag` (story/comment/poll/ask_hn/show_hn), `since_hours` (1–8760), `limit` (1–30) | Keyword search over HN, optionally restricted to a tag or to the last N hours. |
| `hn_item` | `id` (required), `max_comments` (0–100) | One story with a bounded top-level comment tree (HTML stripped, depth-indented) so context stays safe. |

All three tools are **read-only and concurrency-safe**, so DSH may schedule sibling calls in parallel. Each request carries the deployment's cooperative timeout budget and forwards the caller's `AbortSignal`.

## Install

DSH plugins install into a profile via `dsh plugin` (pnpm under the hood). From this GitHub repository:

```bash
dsh plugin --profile <name> add "github:tanf1ng/dsh-tool-hackernews"
```

Or from a local checkout with pnpm:

```bash
pnpm install
pnpm build
# then in the profile that should load it:
dsh plugin --profile <name> add "file:../../dsh-tool-hackernews"
```

Enable the plugin in the profile's `cordis.patch.yml` (or a product bundle):

```yaml
- id: tool-hackernews
  name: dsh-tool-hackernews
```

## Config

All keys optional:

| Key | Default | Meaning |
|---|---|---|
| `registerTopStories` | `true` | Register `hn_top_stories`. |
| `registerSearch` | `true` | Register `hn_search`. |
| `registerItem` | `true` | Register `hn_item`. |
| `topStoriesLimit` | `10` | Default result bound for `hn_top_stories`. |
| `searchLimit` | `8` | Default result bound for `hn_search`. |
| `maxComments` | `20` | Default comment bound for `hn_item`. |
| `fetchTimeoutMs` | `15000` | Per-request timeout budget (ms). |

## Development

```bash
pnpm install
pnpm build     # tsc -> lib/
pnpm test      # smoke test against a stub fetch (no network needed)
```

The package follows the official DSH tool-plugin pattern: a Cordis plugin (`name` / `inject` / `Config` / `apply`) that registers `defineTool` definitions on `ctx.tools`, with full parameter schemas, canonical output schemas, text renderers, and `presentCall` UI cards.

## License

MIT