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.
Install
Configure
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
Document metadata field whose value is the document’s path in the mount. A document without it is mounted under its document name.
Attempts per request, the first included. A 429, a 5xx or a transport error is retried.
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.
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
slug metadata field; without one, the
file takes the document name.
/makes folders. No empty segment,.or...- Each slug is unique across the dataset.
- A slug is never also a folder:
guidesandguides/quickstart.mdcannot 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.loadtakes a liveDifyVFSin its third argument:Workspace.load(snapshot, {}, { '/knowledge': knowledge }).
Search
Thesearch CLI asks Dify’s dataset retrieval API.
Register it on the workspace:
--method takes semantic (the default), fulltext, hybrid or keyword.
--top-k defaults to 10 and is capped at 100. --threshold is between 0 and
- A search under a path filters retrieval by the slug field, or by
document_namefor a document without a slug, which needs Built-in Fields turned on in the dataset’s metadata settings.
Browser
The sameDifyVFS runs in the browser from @struktoai/mirage-browser.
- 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 an agent reads with Dify mounted at/<path>.
- Rendered
- Raw
Virtual Filesystem
VFS Layout
/<path>- Every file is plain text assembled from the document’s Dify segments, whatever its original extension.
Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:
Run
man <cmd> or <cmd> --help for one command’s usage.