@dsh-external/dsh-at-mention

Readme

[中文](README.zh.md) | [English](README.md)

# dsh-at-mention

A DSH profile bundle that adds **@-file mentions** to the composer, with an
interaction model similar to Claude Code / Codex Desktop. Typing `@` in the
input box opens a prioritized fuzzy search over files and directories **in the
current session workspace**.

## Features

- **Per-session workspace scope**: `@` only surfaces files/directories of the
  session's own workspace (`header.cwd`); switching workspaces switches the
  index automatically (LRU cache for up to 3 workspaces, no rescanning).
- **Prioritized fuzzy search**: exact name > name prefix > name substring >
  path prefix > path substring > fuzzy subsequence; shallower directories and
  shorter paths rank higher, matches at path-segment boundaries get a bonus.
- **Keyboard**: ↑/↓ to move, **Tab / Enter** to pick, **Esc** to close
  (Tab is consumed even with no matches, so focus never jumps away).
- **Space-separated consecutive mentions**: `@a @b` is two mentions, `@a@b`
  is a single token (mirrors the built-in trigger rules).
- **Plain-text mentions**: picking inserts `@relative/path ` (configurable:
  absolute path, trailing space on/off). The inserted text can be copied or
  edited later and remains a valid mention.
- **Hover a candidate** to see its full path (absolute + relative) in the
  tooltip when the row text is truncated.
- **Durable settings** in Settings → **@ 提及**: enable, max results, insert
  path style, fuzzy / case-sensitive / directories / trailing space,
  excluded directories, index file cap, auto-refresh interval, and a
  manual **rebuild index** button with live index status.
- **Cross-platform indexing**: `find` fast path on Linux/WSL/macOS, with a
  pure `readdir` fallback anywhere `find` is missing (e.g. native Windows).
  Default exclusions: `.git`, `.godot`, `.import`, `node_modules`,
  `.codegraph`, `.kimi-code` (editable).

## Installation

Prerequisites: a working DSH installation (`dsh web`) and `pnpm` on PATH
(`dsh plugin` forwards to pnpm).

```powershell
# 1. Unzip, e.g. to D:\plugins\dsh-at-mention

# 2. Install into the web profile
dsh plugin --profile web add file:D:/plugins/dsh-at-mention

# or from the parent directory of the unzipped folder:
dsh plugin --profile web add ./dsh-at-mention
```

`dsh plugin add` runs pnpm in the profile directory and appends the bundle's
`cordis.patch.yml` to the profile patch stack. Restart the web app afterwards
(the client bundle and routes are wired at boot).

Removal:

```powershell
dsh plugin --profile web remove @dsh-external/dsh-at-mention
```

## API routes (same-origin, for reference)

| Route | Purpose |
| --- | --- |
| `GET /_dsh/at-mention/api?q=&sessionId=&root=` | Fuzzy search over the session workspace index |
| `GET /_dsh/at-mention/api/settings` | Current settings snapshot |
| `POST /_dsh/at-mention/api/settings` | Save settings (`{ action: 'save', value: {...} }`) |
| `GET /_dsh/at-mention/api/status` | Index status (root, count, builtAt, error) |
| `POST /_dsh/at-mention/api/rebuild` | Rebuild the current workspace index |

POST routes reject cross-site requests.

## Notes

- The mention text itself is plain text (`@relative/path`), so the model in
  the session resolves it against the session workspace; relative paths are
  portable across Linux and Windows.
- While the mention menu is open, the built-in trigger menu is hidden (it
  shares the `@` trigger); the `/` command menu is unaffected.