dsh-plugin-at-mention

Codex-style @ file mentions for the DeepSeek Harness web GUI: type @ in the composer, search the workspace files (and directories) as you type, and pick one — the literal @path text lands in the draft and ships to the model, which resolves the mention with its own read tools.

Developed against the DeepSeek Harness web client (task01) and reviewed/hardened in task02 (typecheck fixes, export-barrel completion, and a breadth-first walk fix). The code is published here as the plugin's source; it is designed to be mounted inside a deepseek-harness checkout.

How it works

composer "@" → input-trigger pipeline → ui-file-mention source
                                        → workspace.search RPC (sessionId + query)
                                        → host resolves session cwd from the session header
                                        → bounded breadth-first tree walk (this repo: host/)
                                        → ranked candidates (basename-prefix > basename-substring > path-substring)
                                        → pick inserts "@path " literal (plain-text reference)

• No context injection: mentions are plain text; the model reads the file itself with its own tools (the harness's plain-text-reference decision).
• No chip decoration: workspace trees are unbounded and change under the session, so the source implements no lexicon roll.
• Bounded per keystroke: one RPC per keystroke; each host walk is capped (50 results, 4000 visited nodes, 16 levels, .git/node_modules skipped) and abortable via the carrier AbortSignal.

Layout

Path	Contents
client/	The browser plugin @deepseek-ai/dsh-client-ui-file-mention: the @ source registration, locale dictionaries, node half, invariant companion, tests, package metadata.
host/	Self-contained extraction of the workspace.search walk core (mentionSearch + ranking + bounds), plus the RPC handler as wired in the harness.
e2e/	Browser end-to-end scenario (file-mentions.e2e.ts) and its golden aria snapshot.
docs/	The feature Agent Note (EN + ZH).

Mounting inside deepseek-harness

The plugin ships as a client package plus a host RPC. To integrate it into a deepseek-harness checkout:

1. Package — place client/ at packages/client/ui-file-mention/ (it is a standard dsh client plugin package: dsh.client manifest, tsdown client bundle, invariant companion).
2. Registration (three surfaces, all required) — add the package to tsconfig.client.json references, add a dsh.client row to packages/bundle/web-app/cordis.patch.yml, and declare the dependency in packages/bundle/web-app/package.json.
3. Host RPC — implement workspace.search in createApiProxy (packages/host/apiproxy/src/api-proxy.ts) using mentionSearch from host/workspace-search.ts; register the method in api/rpc-map.ts, the request/value schemas in api/workspace.schema.ts, and the carrier routes in fetch/client.ts + fetch/handler.ts. The workspace domain types (WorkspaceSearchEntry/WorkspaceSearchResult) must be re-exported through the connection and api-remotes client barrels.
4. Rebuild — rebuild the client bundle (pnpm --filter @deepseek-ai/dsh-client-ui-file-mention bundle) and the web frontend before probing a live dsh web server (the registry serves lib/client.js, not sources).

Development notes

• Breadth-first walk — the visited-node cap spreads across the tree so an alphabetically-last subtree cannot starve matches in early directories (.agents, apps) on large trees. This was a bug found in review (the original depth-first LIFO walk returned zero results for @skills on the deepseek-harness repo itself); see docs/2026-08-14-file-mentions-web-composer.md.
• Tests — client/tests/browser-plugin.client.spec.ts covers source registration, locale dictionaries, HMR-safety disposal, candidate mapping, and pick outcomes. The harness-side host spec (api-proxy-workspace-search.spec.ts) exercises the walk against a real temp tree, including the visited-cap regression test.
• Known limitations — plain-text mentions (no context injection), no chip decoration, one bounded walk per keystroke (a per-session cached index is deferred work).

License

MIT — see LICENSE. Copyright (c) 2026 Jack-c101. The plugin was developed for and derived from DeepSeek Harness (Copyright (c) 2026 DeepSeek, MIT), whose license is reproduced in full alongside.