前言¶
在 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 “一切皆插件” 的生态理念。
