dsh-file-reference-local/packages/context/file-reference-localOfficial
Local-filesystem ctx.fileReferences provider with bounded fuzzy indexes
ⓘ This plugin is a sub-package of the deepseek-ai/deepseek-harness monorepo — stars and activity count the whole repository.
- Language
- TypeScript
- License
- MIT
- Branch
- master
Install
$ dsh plugin --profile web add npm:@deepseek-ai/dsh-file-reference-localRun the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial
Install via your agent
Install the DeepSeek Harness plugin deepseek-ai/deepseek-harness/packages/context/file-reference-local for me: review the repository at https://github.com/deepseek-ai/deepseek-harness first, then run the install command and verify the plugin loads successfully.
Paste this instruction to the DSH Web GUI assistant — it will install and verify for you.
English | 中文
Local-filesystem implementation of ctx.fileReferences. It maintains one bounded WorkspaceFileSearch per agent, rooted at that session's cwd and falling back to the host process cwd. The index ranks direct directory listings for queries containing /, otherwise fuzzy-ranks a bounded recursive index; it never follows directory symlinks.
Tool-result events invalidate the addressed agent's reusable index so later completion observes likely workspace mutations. Agent disposal releases that index and its scoped prompt contribution; plugin disposal awaits every prompt fiber and releases all cached searches.
Configuration
| Key | Default | Contract |
|---|---|---|
maxResults | 20 | Maximum ranked candidates returned for one query. |
maxEntries | 10000 | Maximum files and directories indexed per agent workspace. |
excludedDirectories | [".git", "node_modules"] | Directory basenames omitted from traversal and candidates. |
Every numeric value must be a positive safe integer. Excluded names must be non-empty basenames without / or \.
Model Experience
File-reference guidance when read is available
What the model sees
When the addressed agent has an effective read tool, the provider contributes this stable system-prompt section:
File-reference instruction
Paths prefixed with @ are files explicitly referenced by the user. Use the read tool when their contents are needed; do not claim to have inspected a file before reading it.
Token effect
Conditional and fixed: the one sentence is present while read is visible to the addressed agent; candidate lookup itself adds no tokens, and a selected path contributes only its ordinary user-message characters.
KV Cache effect
The stable sentence joins the system-prompt prefix. Mounting or removing this provider, or changing whether read is visible, changes that prefix; queries, candidates, and index invalidations do not.
Known Limitations and Deferred Work
- Host-local namespace — the provider scans the Harness host filesystem, so remote or virtual
readimplementations require a provider whose namespace matches the tool. - Bounded advisory index — very large workspaces may omit paths after
maxEntries, and excluded or unreadable directories do not appear. - No ignore-file semantics —
.gitignoreand other project ignore files do not influence discovery; only configured directory basenames are excluded.
Read the usage guide →
Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.
Listing badge
[](https://deepseek-plugin.org/plugins/deepseek-ai/deepseek-harness/packages/context/file-reference-local)Paste this markdown into your GitHub README to link back to this listing. The badge only states the listing — not a security endorsement.