dsh-dify

English | 中文

Dify agent and knowledge-base capability for the DeepSeek Harness. It gives the agent two tools — dify_chat that calls a Dify agent app, and dify_retrieve that queries a Dify knowledge base (dataset) for relevant chunks.

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.

Role	Module	Plugin name	Responsibility
Service Definition	src/index.ts	@deepseek-ai/dsh-dify	Owns ctx.dify: provider registry, order-independent selection
Service Provider	src/http.ts	@deepseek-ai/dsh-dify/http	Calls Dify Service API (/chat-messages, /datasets/{id}/retrieve), resolves credentials, normalizes results
Consumer	src/tool.ts	@deepseek-ai/dsh-dify/tool	The model-facing tools: dify_chat, dify_retrieve — schema, prompt guidance, presentation
Consumer	src/config.ts	@deepseek-ai/dsh-dify/config	The person-facing configuration page over the same settings and credential seams

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

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

Prerequisites

1. A running Dify instance — self-hosted or cloud. Defaults to https://api.dify.ai/v1.
2. A Dify API key — create one for your app in Dify.
3. A Dify agent app — for dify_chat to call.
4. A Dify knowledge base (dataset) — for dify_retrieve to query. At least one dataset id must be configured.

Install

dsh plugin --profile web add "github:staff-os/dsh-dify#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-dify   # 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 dify

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/dify (whatever port the web surface printed). It edits the endpoint, the default dataset, and the tool timeout, 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 connection runs one live chat 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: dify-config
  disabled: true

Environment variables

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

export DIFY_API_KEY=app-xxx
export DIFY_BASE_URL=https://your-dify-host/v1     # optional, defaults to https://api.dify.ai/v1
export DIFY_DATASET_ID=dataset_id_1                 # required for dify_retrieve unless set in YAML
export DIFY_USER=end-user-id                        # optional, defaults to dsh-user

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.

@deepseek-ai/dsh-dify (seam)

Config	Default	Description
provider	auto	Provider id to pin. Unset auto-selects when exactly one is usable. Also $DSH_DIFY_PROVIDER.

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

Config	Default	Description
apiKey	—	Literal key. Prefer apiKeyEnv.
apiKeyEnv	DIFY_API_KEY	Credential reference resolved per operation.
baseURL	$DIFY_BASE_URL → https://api.dify.ai/v1	Endpoint base; /chat-messages and /datasets/... are appended.
user	$DIFY_USER → dsh-user	Dify end-user identifier sent on every request.
datasetId	$DIFY_DATASET_ID	Default dataset for dify_retrieve.

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

Config	Default	Description
timeoutMs	60000	Cooperative per-call timeout budget. Read at registration: a change applies at the next start.

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

Config	Default	Description
path	/dify	Pathname the page and its JSON endpoints (/state, /save, /probe) are served under.

Call flow

dify_chat

1. The model calls dify_chat with a query and optional conversationId.
2. The tool validates it and calls ctx.dify.chat({ query, conversationId }, signal).
3. The seam selects the usable provider and forwards the request.
4. The provider posts to POST /chat-messages in blocking mode.
5. The tool renders the answer text.

dify_retrieve

1. The model calls dify_retrieve with a query and optional datasetId.
2. The tool validates it and calls ctx.dify.retrieve({ query, datasetId }, signal).
3. The seam selects the usable provider and forwards the request.
4. The provider posts to POST /datasets/{id}/retrieve and normalizes records[].
5. The tool renders the chunks as cited text plus structured metadata.

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.

Dify API reference

• Agent API
• Chat Messages
• Knowledge Base Retrieval

Troubleshooting

Symptom	Cause	Fix
DIFY_SCOPE_MISSING	No dataset id in scope	Set datasetId or $DIFY_DATASET_ID
DIFY_PROVIDER_CREDENTIAL_MISSING	No key for the credential reference	Set $DIFY_API_KEY, or match apiKeyEnv to your credentials key
DIFY_PROVIDER_UNAUTHORIZED	Dify rejected the key	Reissue the key in Dify
DIFY_PROVIDER_UNAVAILABLE	Provider row missing or its options invalid	Check --dump-config for the dify-http row
DIFY_PROVIDER_AMBIGUOUS	Two usable providers registered	Pin one with the seam's provider
dify_chat / dify_retrieve absent from the tool list	Bundle not loaded	dsh --dump-config | grep dify; restart dsh web
The page answers NOT_LOOPBACK	Reached over a LAN address	Open it from the host itself, or tunnel the port
The page answers SETTINGS_CONFLICT	The settings document moved since the page loaded	Reload the page and reapply

Known limitations

• Blocking mode only — no SSE streaming. The full response is awaited.
• dify_chat does not forward file inputs or vision attachments.
• dify_retrieve does not support multi-dataset search or attachment_ids.
• The configuration page does not list available Dify apps or datasets for selection.