dsh-research-refs

Readme

# dsh-research-refs

A [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/DeepSeek-Harness) plugin that turns messy pasted citations into uniformly formatted references. Derived from the opencode `research-refs` skill and rebuilt as a deterministic tool chain — parsing, verification, deduplication and formatting are done by code, while the skill only orchestrates the flow.

## Features

Four tools plus one orchestration skill:

| Tool | Purpose |
|---|---|
| `refs_parse` | Split messy citation text into individual entries (numbering → blank lines → type-marker strategies), best-effort field parsing; entries with missing fields or uncertain splits carry `flags` |
| `refs_verify` | Verify and complete via Crossref: with a DOI, query `works/{DOI}` to fill volume/issue/pages, journal and year; without a DOI, search by title + authors (similarity ≥ 0.9 auto-applied, otherwise the top 5 candidates are returned for the user to choose). Chinese references are marked "not verifiable online" |
| `refs_dedup` | Automatic deduplication: identical DOI, or title similarity ≥ 0.85 with the same first-author surname; keeps the most complete / already-verified entry and reports what was removed |
| `refs_format` | Output in GB/T 7714-2015 / APA / Vancouver; English authors normalized to "SURNAME Initials" (e.g. ZHANG S), Chinese authors keep their full names; ends with a pending-items list; optionally writes a `.md` file |

The `research-refs` skill teaches the model to orchestrate the pipeline as "parse → confirm with the user → verify (candidate selection) → dedup → ask for style → output", and enforces the iron rules: **never fabricate fields** — anything unverifiable is marked pending.

## Install

```bash
npm i github:Parker-xia/dsh-research-refs
```

## Add to your composition

Append to your DSH composition (`cordis.yml` or an agent preset's `agent.cordis.yml`):

```yaml
- id: research-refs
  name: 'dsh-research-refs'
```

Or use the bundle patch mechanism (`dsh bundle patch`, see `cordis.patch.yml`).

**Tested against `@deepseek-ai/dsh@0.1.0-rc.6`** — the preview moves fast, so pin this version or check GitHub Discussions when upgrading. Requires the host `tools` service; `fs` / `skills` are optional (the capability degrades gracefully and is flagged when missing).

**Online verification is self-sufficient**: `refs_verify` uses Node's native `fetch` (always present on DSH's Node ≥ 22 engine) to talk to Crossref directly — it does **not** require the host to configure any web fetch provider, and it does not register one (so it can never conflict with a host provider). If native `fetch` is unavailable (e.g. inside the dynamic sandbox), it automatically falls back to the `ctx.web` service.

## Usage

Paste a messy block of citations and say something like "clean up these references". The agent loads the skill and reports at every step of the pipeline:

```
You: clean up these references:
    1. Zhang S et al. 2021. Deep learning for CT reconstruction...
    2. Wang S (2024) Image reconstruction algorithms...

Agent: [refs_parse] 2 entries split, all fields recognized...
       [refs_verify] #1 verified (DOI), #2 candidates awaiting choice...
       [refs_dedup] 2 kept, none removed
       [refs_format] GB/T 7714-2015 output...
```

## License

MIT