前言¶
在 DSH 的 Composer 中引用當前會話工作區的文件或目錄時，通常需要手動輸入路徑或進行復制粘貼。dsh-at-mention 插件通過在輸入框觸發 @ 符號，直接提供文件和目錄的模糊搜索與補全功能，模擬了 Claude Code / Codex Desktop 的交互體驗。
插件介紹¶
名稱：dsh-at-mention
定位：DSH profile bundle
核心價值：向 Composer 添加 @-file mentions，提供優先級模糊搜索與鍵盤補全。
維護者：ShiraGawaAnri
許可證：MIT
核心功能¶
該插件專注於當前會話工作區內的文件與目錄索引，並提供以下能力：
-
當前會話工作區作用域
搜索範圍限定在當前會話的header.cwd目錄及其子目錄。切換工作區時，索引會自動切換（使用 LRU 緩存管理最多 3 個工作區，無需重新掃描）。 -
優先級模糊搜索
搜索結果的排序優先級如下：- 精確匹配
- 名稱前綴
- 名稱子串
- 路徑前綴
- 路徑子串
- 模糊子序列
淺層目錄和較短路徑的匹配項會獲得更高排名。
-
鍵盤導航
↑/↓：移動光標選擇候選項Tab/Enter：確認選擇Esc：關閉菜單
注意：Tab鍵在無匹配時也會被消費，確保焦點不會意外跳離。
-
空格分隔連續提及
支持@a @b（兩個獨立的提及）和@a@b（單個 token）的語法，與內置觸發規則一致。 -
純文本提及
選中的文件會以純文本形式插入（例如@relative/path）。該文本可被複制或後續編輯，且作爲純文本在 Linux 和 Windows 間保持可移植性。 -
完整路徑 Tooltip
當候選項的文本被截斷時，鼠標懸停可查看完整的絕對路徑和相對路徑。 -
持久化設置
在 Settings -> @ 提及 中，可以配置啓用狀態、最大結果數、插入路徑樣式、模糊搜索/大小寫敏感/包含目錄/尾隨空格選項、排除目錄、索引文件上限、自動刷新間隔，以及手動重建索引按鈕和實時索引狀態。 -
跨平臺索引
- Linux / WSL / macOS：使用
find命令進行快速索引。 - Windows：當
find不可用時，使用純readdir回退方案。
默認排除目錄包括.git、.godot、.import、node_modules、.codegraph、.kimi-code（支持自定義）。
- Linux / WSL / macOS：使用
安裝與啓用¶
安裝該插件需要具備一個可用的 DSH 安裝環境（dsh web）以及路徑中的 pnpm（dsh plugin 會轉發至 pnpm）。
dsh plugin --profile web add ./dsh-at-mention
安裝命令會運行 pnpm 並將插件的 cordis.patch.yml 追加到 profile 的補丁堆棧中。安裝完成後，需要重啓 Web 應用（客戶端包和路由在啓動時已綁定）。
若需移除：
dsh plugin --profile web remove @dsh-external/dsh-at-mention
典型用法¶
在 Composer 的輸入框中輸入 @ 即可打開優先級模糊搜索菜單。
- 使用
↑和↓鍵在列表中移動。 - 按
Tab或Enter選中文件並插入提及文本。 - 按
Esc關閉菜單。
提及語法示例：
* @a @b：表示兩個獨立的提及
* @a@b：表示一個單一的 token
配置與 API¶
插件的配置和狀態通過以下 API 路由（同源）進行管理：
GET /_dsh/at-mention/api?q=&sessionId=&root=：對當前會話工作區索引進行模糊搜索。GET /_dsh/at-mention/api/settings：獲取當前設置快照。POST /_dsh/at-mention/api/settings：保存設置（參數格式：{ action: 'save', value: {...} }）。GET /_dsh/at-mention/api/status：查詢索引狀態（根目錄、數量、構建時間、錯誤信息）。POST /_dsh/at-mention/api/rebuild：重建當前工作區的索引。
POST 路由拒絕跨站請求（CSRF）。
注意事項¶
- 插件在當前 dsh 進程權限下運行，請確保安裝前檢查源碼與許可證。
- 插件插入的提及文本爲純文本（
@relative/path），模型在會話中會將其解析爲當前工作區的文件引用，相對路徑在 Linux 和 Windows 之間保持兼容。 - 當 mention 菜單處於打開狀態時，內置的
/命令菜單不受影響，但內置的@觸發菜單會被隱藏（兩者共享@觸發）。
結語¶
dsh-at-mention 通過提供優先級排序的模糊搜索、鍵盤補全以及純文本化的引用方式，優化了在 DSH Composer 中引用本地文件的工作流。這符合 DSH “一切皆插件” 的生態理念。
