dsh-ragflow

English | 中文

RAGFlow knowledge-base retrieval for the DeepSeek Harness. It gives the
agent a ragflow_retrieve tool that queries your RAGFlow datasets and returns document chunks with
similarity scores and source names.

Design

The package follows the Harness three-role capability
pattern: one seam, one provider, one consumer —
shipped as one package with four plugin entry points (the fourth is the configuration page over the
same values), so a profile can override, replace, or drop any single role without touching the
others.

The provider and the consumer depend only on the Service Definition, never on each other. Replacing
the backend means replacing one row:

- id: ragflow-http
  name: 'your-own-ragflow-provider'

Prerequisites

1. A running RAGFlow instance — self-hosted or cloud. Defaults to http://localhost:9380.
2. An API key — create one in RAGFlow.
3. A dataset with parsed documents — RAGFlow rejects a retrieval that names no dataset and no
   document, so at least one dataset id must be configured.

Install

dsh plugin --profile web add "github:staff-os/dsh-ragflow#main"

dsh plugin add forwards the source to pnpm as-is, so any pnpm-recognized source works:

dsh plugin --profile web add link:/path/to/dsh-ragflow   # local development

lib/ is committed, so no build script runs at install time and pnpm needs no build allowance.
Restart dsh web afterwards, then verify the four rows landed:

dsh --profile web --dump-config | grep ragflow

Configure

Three ways in, one set of values. The configuration page is the easy one; the environment and the
YAML rows remain exactly what they were.

The configuration page

With dsh web running, open http://127.0.0.1:3080/ragflow (whatever port the web surface
printed). It edits the endpoint, the datasets, the retrieval options, and the tool bound, and it
stores the API key through the credential service — the key never reaches a settings file, and the
field reports only whether one is configured.

Every field is leave empty to inherit: the box holds your own override, the placeholder names the
value in effect without one. Clearing a box is how a field goes back to inheriting the composition
row, the environment variable, or the schema default. Test retrieval runs one live retrieval so
a saved endpoint can be confirmed rather than assumed.

The page is served on loopback only, whatever dsh web --host binds, because it reads deployment
configuration and writes a credential. Move it with the row's path, or take it out entirely:

# ~/.dsh/profiles/web/cordis.patch.yml
- id: ragflow-config
  disabled: true

Saved values land in ~/.dsh/settings.yaml under the ragflow-http and tool-ragflow namespaces,
which layer over the composition rows: schema defaults, then the cordis.patch.yml entry, then
your saved section. They apply to the next retrieval without a restart — except timeoutMs, which
the tool registry reads once when the tool registers.

Environment variables

Set the environment the plugin reads — no YAML and no page needed for the common case:

export RAGFLOW_API_KEY=ragflow-xxx
export RAGFLOW_BASE_URL=http://your-ragflow-host:9380     # optional, defaults to localhost:9380
export RAGFLOW_DATASET_IDS=dataset_id_1,dataset_id_2      # required unless set in YAML

The API key resolves through the DSH credentials service when one is mounted
(~/.dsh/.credentials.yaml), and through the launch environment otherwise. Never inline a key in a
config file.

The launch environment is a snapshot taken when the process starts, so editing a variable never
reaches a running dsh — restart it from a shell that already carries the new value. On Windows
that is easy to get wrong: editing System variables in the GUI only writes the registry, and
every process already running keeps its old block — Explorer included, so anything started from the
Start menu or a shortcut inherits Explorer's stale copy until you restart Explorer or sign out and
back in. The page reports what the process actually sees, which makes it the quickest way to tell a
stale environment from a wrong value.

To override a row, restate it in your profile's cordis.patch.yml — a patch replaces a row's whole
config rather than merging into it, so state every key that row needs:

# ~/.dsh/profiles/web/cordis.patch.yml
- insert:
    - id: ragflow-http
      name: '@deepseek-ai/dsh-ragflow/http'
      config:
        baseURL: http://your-ragflow-host:9380
        datasetIds: ['dataset_id_1']
        similarityThreshold: 0.3
        vectorTopK: 1024

@deepseek-ai/dsh-ragflow (seam)

@deepseek-ai/dsh-ragflow/http (provider)

@deepseek-ai/dsh-ragflow/tool (consumer)

@deepseek-ai/dsh-ragflow/config (configuration page)

Retrieval flow

1. The model calls ragflow_retrieve with a question.
2. The tool validates it and calls ctx.ragflow.retrieve({ question, maxChunks }, signal).
3. The seam selects the usable provider and forwards the request.
4. The provider posts to /api/v1/retrieval and normalizes data.chunks[].
5. The seam caps the result to maxChunks; the tool renders it as cited text plus structured
   metadata that survives session replay.

An empty result is a result: the tool tells the model the knowledge base has nothing relevant and
not to invent a citation.

Develop

pnpm install
pnpm test        # vitest
pnpm typecheck   # tsc --noEmit
pnpm build       # tsdown → lib/{index,http,tool,config}.js

lib/ is committed; rebuild and commit it with any src/ change.

Troubleshooting

Known limitations

• Retrieval only — no dataset or document management (create, upload, parse).
• The page is this plugin's own, not a card in DSH's Settings → Plugins tab: that tab renders
  only the settings namespaces the host api-proxy allowlists (WEB_SETTINGS_NAMESPACES), which a
  plugin distributed outside the harness repository cannot join without patching a released
  package. If that allowlist ever moves to settings.register(), these same namespaces become a
  card there with no change here.
• No streaming; the full response is awaited.
• The result renders as the generic search card, not a bespoke citation card.
• RAGFlow's cross_languages, metadata_condition, highlight, and use_kg options are not
  surfaced yet.