dsh-file-path

中文说明

A DeepSeek Harness (dsh) plugin that lets the Web composer accept files and
folders the built-in attachment path does not support — PDFs, archives, Office
documents, large files, whole directories — by inserting their absolute
paths as plain text instead of uploading them as message attachments.

This is a community plugin. It is not an official DeepSeek plugin and is not
affiliated with or endorsed by DeepSeek.

Why

dsh's version-one attachment path accepts PNG, JPEG, WebP, and GIF only.
Dropping a PDF into the composer currently announces "only images are
supported" and drops the file. Browsers do not expose the absolute host path of
a dragged File for security reasons, so a web page cannot read the path out
of the drag event — even when the page is served by a local CLI.

dsh-file-path recovers the original path using the local dsh host itself:

1. You drag or paste a non-image file into the composer.
2. The browser half computes the file's SHA-256 and calls the local
   filePathBridge/resolvePath RPC on the dsh process.
3. The host half searches the session workspace and configured roots
   (~ by default) for a same-name, same-size, same-hash file and returns its
   original absolute path. Nothing is copied or written.
4. The composer inserts that absolute path directly. If no original is found
   (for example the file lives on another drive outside the search roots), a
   dialog asks for the absolute path manually, with an explicit
   "Copy to workspace" fallback available as a second action — never automatic.

A paperclip button in the composer tool row also opens a dialog for manually
typing an absolute or workspace-relative path.

Install

Pack and install the built tarball:

npm run build
npm pack
dsh plugin --profile web add ./dsh-file-path-0.1.x.tgz

Or install a published version:

dsh plugin --profile web add dsh-file-path

Or install from git (the prepare script builds the artifacts; pnpm ≥10 asks
you to allow that build once, and dsh prints the exact allowBuilds snippet):

dsh plugin --profile web add github:<you>/dsh-file-path#<commit-sha>

Then boot dsh web as usual:

dsh --profile web --port 3080

The Web profile already contains the Web app bundle. For a custom profile,
make sure @deepseek-ai/dsh-web-app is in dsh.profile.bundles before
dsh-file-path.

Usage

• Drag or paste a non-image file anywhere on the page. The plugin looks up
  its original absolute path by name + size + head/tail SHA-256 samples
  (64KB each) and inserts that path directly. Large files are never read in
  full, so an 800MB archive resolves in milliseconds.
• Drag a folder (Chromium/Edge File System Access): the plugin walks the
  dropped directory, builds a directory fingerprint, and inserts the matched
  absolute folder path. Nothing is copied.
• If the original path is outside the search roots, a dialog asks for the
  absolute path manually. A secondary "Copy to workspace" action is available
  for unresolved FILES, but it is never triggered automatically.
• Click the paperclip button in the composer tool row to insert a manually
  typed path (absolute or relative to the session workspace).
• Supported images (PNG/JPEG/WebP/GIF) keep the normal dsh image behavior. A
  mixed drop routes images to the default composer intake and resolves only the
  rest.
• The plugin clears dsh's full-page drop overlay when it takes over a drop, so
  the "drag images here" screen never remains stuck.

Configuration

The bundle patch inserts one host row. Override its config in the profile's
cordis.patch.yml or any later layer:

- id: file-path
  config:
    importSubdir: .dsh-files          # fallback copy location
    maxFileBytes: 104857600           # decoded bytes per fallback import
    searchRoots:                      # original-path search roots
      - '~'
      # - /mnt
    searchMaxEntries: 50000           # directory entries visited per lookup
    searchSkipNames:                  # directory basenames skipped
      - .git
      - node_modules
      - .npm
      - .cache
      - .dsh
      - .Trash
    maxResolveBytes: 4294967296        # max file size for hash lookup

• searchRoots entries must be absolute or start with ~. The session
  workspace is always searched first. Symlinks are not followed.
• importSubdir must be one relative segment (no /, \, ..). Invalid
  values fail the plugin load loudly.
• Lookup caps are per call: searchMaxEntries bounds traversal and
  maxResolveBytes bounds the hashed candidate size.

How it is built

• Host half (lib/index.js): a self-contained Cordis service registered as
  ctx.filePathBridge. It registers strict Typert Remote descriptors for
  filePathBridge/resolvePath, filePathBridge/importFile, and
  filePathBridge/describe, so wire input is schema-validated on both sides.
  resolvePath walks the search roots for a content-identical file and returns
  its absolute path. importFile is the explicit fallback: it writes the
  decoded base64 payload below importSubdir with a
  temporary-file-plus-rename publication path.
• Browser half (lib/client.js): a dsh.client module that mounts the
  three Remote methods, registers locale dictionaries, and contributes a small
  control to the conversation.input.right slot. Capture-phase document
  listeners take over drops and file-only pastes that contain a non-image;
  all-image batches pass through untouched, images inside a mixed batch are
  re-dispatched to the default composer listener, and a synthetic dragend
  resets the default drop overlay.

Security notes

• resolvePath only reports the path of a file whose exact bytes the browser
  already sent as the lookup digest; it never writes and never returns a path
  that does not match the dropped content.
• The explicit fallback import only writes into the live session's own
  workspace, under the configured single-segment importSubdir; path
  traversal through the file name is stripped.
• The dsh Web transport's loopback/browser-trust fence still applies to
  /api/filePathBridge/*.
• Installing a plugin means executing its code inside the local dsh process.
  Review the source and pin versions just as you would for any plugin.

Development

Requires Node >=22.19.

npm install
npm run check        # typecheck + tests + build
npm test             # host service and composer control tests
npm pack             # built tarball

The build script (scripts/build.mjs) emits the ESM host half and the
window.__ModuleLoader__.load CJS-factory browser half; tsc emits the
declaration files under lib/types.

License

MIT