> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Dify

> Virtualize a Dify Knowledge dataset from Node or the browser.

`DifyVFS` mounts a Dify Knowledge dataset, read-only, as a tree of text files.
Each document is one file, assembled from its segments. Set up the API key and the dataset as in [Dify setup](https://docs.mirage.strukto.ai/home/setup/dify.md).

## Install

```bash theme={null}
npm install @struktoai/mirage-node
```

## Configure

```ts theme={null}
import { DifyVFS, MountMode, Workspace } from '@struktoai/mirage-node'

const knowledge = new DifyVFS({
  apiKey: process.env.DIFY_API_KEY!,
  baseUrl: process.env.DIFY_BASE_URL!,
  datasetId: process.env.DIFY_DATASET_ID!,
})
const ws = new Workspace({ '/knowledge': knowledge }, { mode: MountMode.READ })

const result = await ws.shell('find /knowledge -type f && grep -rn billing /knowledge')
console.log(result.stdoutText)
await ws.close()
```

`slugMetadataName` picks the document metadata field that holds each path
(default `slug`). `maxConcurrency`, `retryAttempts` and `retryMaxDelay` bound
the requests in flight and the retries after a 429, a 5xx or a transport
error.

### Fields

**apiKey** `string` *required*

Dify Knowledge API key, sent as `Authorization: Bearer`.

**baseUrl** `string` *required*

Dify API root, such as `https://api.dify.ai/v1`.

**datasetId** `string` *required*

ID of the Knowledge dataset the mount shows.

**slugMetadataName** `string` (default: 'slug')

Document metadata field whose value is the document's path in the mount. A document without it is mounted under its document name.

**maxConcurrency** `number` (default: 10)

The most Dify API requests in flight at once.

**retryAttempts** `number` (default: 4)

Attempts per request, the first included. A 429, a 5xx or a transport error is retried.

**retryMaxDelay** `number` (default: 30)

Longest wait in seconds before a retry, whether from backoff or `Retry-After`.

**timeout** `number` (default: DEFAULT\_TIMEOUT)

Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.

Fields marked secret are redacted in snapshots.

## Authentication

The mount sends a Dify Knowledge API key, created under **Knowledge**,
**Service API**. The key reaches either every knowledge base or only the one
mounted, and that knowledge base keeps **API Access** on.

## Layout

```text theme={null}
/knowledge/
  README.md
  guides/
    api.md
    quickstart.md
  policies/
    support.md
```

A document's path is the value of its `slug` metadata field; without one, the
file takes the document name.

| Dify document | Metadata | Mirage path |
| - | - | - |
| `Quickstart` | `slug=guides/quickstart.md` | `/knowledge/guides/quickstart.md` |
| `README.md` | no slug | `/knowledge/README.md` |

* `/` makes folders. No empty segment, `.` or `..`.
* Each slug is unique across the dataset.
* A slug is never also a folder: `guides` and `guides/quickstart.md` cannot
  both be documents.
* Only enabled, fully indexed, unarchived documents appear.

## Behavior

* **Read-only:** no command changes the dataset.
* **Plain text:** a file is its completed, enabled segments joined by line
  breaks, whatever the original format.
* **Tree refresh:** listings are reused until the index expires, so a document
  edited in Dify can show its old path and metadata until then.
* **Snapshots:** a snapshot leaves out the API key, so `Workspace.load` takes a
  live `DifyVFS` in its third argument:
  `Workspace.load(snapshot, {}, { '/knowledge': knowledge })`.

### Search

The `search` CLI asks Dify's dataset retrieval API.
Register it on the workspace:

```ts theme={null}
import { SEARCH } from '@struktoai/mirage-node'

ws.registerCli('search', SEARCH)
```

```bash theme={null}
search "how do I reset my password" /knowledge/
search --method hybrid --top-k 5 "billing policy" /knowledge/policies/
```

`--method` takes `semantic` (the default), `fulltext`, `hybrid` or `keyword`.
`--top-k` defaults to 10 and is capped at 100. `--threshold` is between 0 and

1. A search under a path filters retrieval by the slug field, or by
   `document_name` for a document without a slug, which needs **Built-in Fields**
   turned on in the dataset's metadata settings.

## Browser

The same `DifyVFS` runs in the browser from `@struktoai/mirage-browser`.

```bash theme={null}
npm install @struktoai/mirage-browser
```

```ts theme={null}
import { DifyVFS, MountMode, Workspace } from '@struktoai/mirage-browser'

const knowledge = new DifyVFS({
  apiKey: DIFY_API_KEY,
  baseUrl: 'https://api.dify.ai/v1',
  datasetId: DIFY_DATASET_ID,
})
const ws = new Workspace({ '/knowledge': knowledge }, { mode: MountMode.READ })
```

* The page calls the Dify API directly, so it must accept requests from the
  page's origin.
* The API key is visible to anyone who loads the page: give it access to the
  mounted knowledge base only.

## VFS.md

The [VFS.md](https://docs.mirage.strukto.ai/home/setup/vfs-md.md) an agent reads with Dify mounted at `/<path>`.

> [tab] Rendered
>
> **Virtual Filesystem**
>
> | Path | Description |
> | - | - |
> | `/<path>` | `dify`, read |
>
> **VFS Layout**
>
> **`/<path>`**
>
> * Every file is plain text assembled from the document's Dify segments,
>   whatever its original extension.
>
> **Supported Unix Commands for VFS**
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | - | - |
> | `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). |
>
> **Limitations of Unix Commands for VFS**
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | - | - |
> | `/<path>` | Read only: no command changes files. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.

> [tab] Raw
>
> ```markdown theme={null}
> ---
> name: workspace-filesystem
> description: The virtual filesystem layout of this workspace.
> ---
>
> # Virtual Filesystem
>
> | Path | Description |
> | --- | --- |
> | `/<path>` | `dify`, read |
>
> ## VFS Layout
>
> ### `/<path>`
>
> - Every file is plain text assembled from the document's Dify segments,
>   whatever its original extension.
>
> ## Supported Unix Commands for VFS
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | --- | --- |
> | `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). |
>
> ## Limitations of Unix Commands for VFS
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | --- | --- |
> | `/<path>` | Read only: no command changes files. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.