Turtle
38c7a9fbf4
* feat(release): publish package source, declaration maps, and documentation Every release member publishes its TypeScript source and the declaration maps that resolve into it, and @deepseek-ai/dsh publishes the repository Markdown documentation staged from docs/ at prepack time. The ./src/* export most members already declared now resolves for an installed consumer, and a consumer editor follows a declaration to the implementation. Bundled JavaScript maps stay unpublished; the vendored family and the Desktop runtime file policy are unchanged. Rationale: .agents/notes/implemented/process/2026-10-08-published-source-and-docs.md * feat(release): publish JavaScript maps and compress bundles Every emitted JavaScript map ships beside the bundle it describes, and the workspace build and the client preset compress bundles without mangling identifiers. The documentation payload now mirrors the website publication manifest and is removed again by `postpack`; Desktop and the Python executable exclude the published source, documentation, and maps; `clean` removes a staged copy. Typert's publication contract gains the Remote declaration map. * fix(release): keep node bundles readable for the worker image The browser worker image lowers `yield*` only as a whole statement and rewrites `for await` loops by their source layout, so compressed node-side entries either fail that lowering or lower to unparseable code. Only the browser bundles keep compression, which removes about a third of their text. The bundle-purity assertion now matches the module-loader call regardless of the quote style compression picks, and the release-pack fixture exercises the installed package's new documentation requirement. * feat(release): publish the whole documentation tree `@deepseek-ai/dsh` copies `docs/` in full instead of the website's page set: the maintainer documents, the generated migration records, the translation guidelines, and the `*.i18n.yaml` consistency records ship with the installed package, so the documentation's own links resolve without a checkout. * feat(release): publish the upgrade guides with the documentation The staged documentation keeps the website's page set and adds every `docs/upgrade-guide/` document, which is what an installed reader consults when a released change breaks something. The rest of the maintainer tree stays out. * test(release): expect source and maps in master's new payload cases * feat(release): keep installed docs and source readable in Desktop Desktop keeps the published src/ and docs/ trees inside app.asar, and every model shell call receives DSH_INSTALL_DIR and DSH_NODE_EXECUTABLE so an agent can read them through Electron's Node mode. Staging also generates docs/upgrade-guide/README.md, an index of the upgrade guides grouped by the release they upgrade from. Minified client bundles print string literals with backticks: the worker image packer now recognizes those chunk requests, client license banners are prepended after minification so their text survives, and the affected artifact tests accept either quote. * test(desktop): read archived docs through the Windows PowerShell form Regenerate the config catalog for the shifted shell-env source line. * test(desktop): wait for the GUI-subsystem Electron process from PowerShell * build(release): publish source and maps from the message-quotes package * build(release): publish source and maps from packages new on master * build(release): publish source and maps from the tool-office package
description, kind
| description | kind |
|---|---|
| File-reference discovery and @file mention grammar for host-backed UIs, for users and maintainers choosing the seam or pairing it with a provider. | package-reference |
@deepseek-ai/dsh-file-reference
English | 中文
Summary
Host-backed user interfaces use dsh-file-reference to offer @file completion: a UI asks for path candidates for the addressed agent, the model types @path or @"path with spaces", and picking a candidate inserts the matching mention as ordinary prompt text. The seam itself owns no filesystem access — a concrete provider such as @deepseek-ai/dsh-file-reference-local supplies candidates, ranking, caching, and invalidation. Selecting a candidate never reads or attaches file contents; the model must call a filesystem tool to inspect a file. Session Controller exposes the same discovery to browser consumers through the fileReferences/list Remote.
Table of Contents
- Use this package
- Understand the implementation
- Further Exploration
- Model Experience
- Known Limitations and Deferred Work
- Dev Note
Use this package
Choose this package when a host-backed UI (web or terminal) should offer @file completion, and pair it with a provider whose namespace matches the agent's effective read tool. Mounting the seam without a provider gives the UI an empty completion surface.
Mention grammar
An @path token at the start of input or after whitespace triggers completion; an @ inside another token, such as an email address, does not. @"path with spaces" opens a quoted mention, and a directory candidate keeps that quote open after its trailing slash so completion can descend another level. Completed directory chips close the quote after the trailing slash. Relative mentions resolve from the workspace root; absolute mentions retain the host path. The formatter rejects paths with control characters or embedded quotes that the grammar cannot represent safely.
Getting candidates
ctx.fileReferences.list(agent, query, signal) returns path-only file and directory candidates for one agent's working directory, deterministically ranked by the provider. Directory mentions render with a trailing / so completion can descend another level. Browser consumers call the Session Controller adapter as ctx.remote.fileReferences.list; the trailing signal cancels a slow autocomplete.
Pairing with a provider
For a local filesystem, mount @deepseek-ai/dsh-file-reference-local; other namespaces (remote or virtual filesystems) need a provider whose discovery matches the effective tool. When the addressed agent can call read, a provider may install the stable FILE_REFERENCE_PROMPT guidance that tells the model to read a referenced file before claiming to have inspected it.
Understand the implementation
Implementation internals — click to expand
This section explains the design of the seam; the observable behavior is covered in Use this package.
Design concept
The package separates an abstract discovery service from a shared, browser-safe mention grammar, with providers owning namespace access, ranking, caching, and invalidation. The service remains wire-neutral; dsh-api-session-controller owns the fileReferences/list Remote adapter and delegates to the active provider after resolving its Agent.
Source map
| File | Role |
|---|---|
src/index.ts |
Abstract FileReferenceService and FILE_REFERENCE_PROMPT |
src/grammar.ts |
activeAtToken recognition and formatFileMention rendering |
src/types.ts |
FileReferenceCandidate path-only result type |
Main flow
The UI recognizes an active @ token through activeAtToken, calls list with the query text, and renders the ranked candidates. On selection, formatFileMention emits the matching prompt spelling (@path, @"path with spaces", or an open @"dir/ for a quoted directory). No file content is read at any point; providers may additionally install the stable FILE_REFERENCE_PROMPT section when the addressed agent has a read tool.
Further Exploration
Read these pages when the package-level contract is not enough. They move from the shipped provider to the shared reference surface and the tools the candidates point at.
- Local file-reference provider — the shipped local-workspace implementation of this seam.
- Session-reference subsystem — the shared file-reference and session-reference contracts behind host UIs.
- Context group map — sibling request-context packages.
- Filesystem tool catalog — the
readtool that referenced paths are meant for.
Model Experience
Indirectly, through the composed provider, which owns the file-reference guidance that this package's discovery seam and grammar delegate to it.
KV Cache effect
The interface and grammar add no request tokens; a provider-owned prompt section determines whether the reusable prefix changes.
Known Limitations and Deferred Work
These limits define when the seam is a poor fit. They are current package constraints.
- Path candidates are advisory — the seam does not prove that a later model-facing filesystem tool can access the same namespace; deployments must align the provider with the effective
readimplementation. - No file-content reference object — selected files remain ordinary prompt text and require an explicit model tool call before their contents become model-visible.
Dev Note
Working context for maintainers — click to expand
None.