前言¶

在 DeepSeek Harness（DSH）的 Web 界面里，@ 是引用文件和会话的主要入口。默认实现下，每敲一个字符都要向 Host 发一次请求，由 Host 端过滤候选；工作区文件多、历史会话多时，菜单打开和过滤的延迟会明显堆积。

dsh-better-at 的做法是把文件索引和会话索引提前拉到浏览器，过滤和排序全部在本地完成，同时保留原生 @ 引用的行为和 mention 格式。下面介绍这个插件。

这是什么¶

dsh-better-at 是一个面向 DSH Web GUI 的插件，定位是「@ 文件/会话引用的本地缓存加速」，由 Ruiming-cn 维护，MIT 许可证，当前版本 0.2.0。

它保留原生 DSH @ 引用行为——层级式的工作区文件/文件夹引用和 DSH 会话引用——只是把「每次按键都请求 Host」变成「初始化时拉一次索引，之后本地过滤」。实现上不修改 Harness 源码，由一个树外 Host Remote 加一个浏览器 client bundle 组成。

核心功能¶

• 会话级预热：首次 @ 之前预加载工作区文件索引与 DSH 会话索引，加快首次打开速度。
• 本地按键过滤：初始加载后，输入过滤与候选排序完全在浏览器本地完成，不再每次按键请求 Host。预热后的首个 @ 通常直接由内存返回，后续按键是对缓存索引做 O(N) 字符串打分。
• 层级文件/文件夹引用：空查询或路径查询显示直接子项；纯模糊查询在整个工作区搜索文件 basename。
• DSH 会话引用：完整会话元数据在本地建索引，按工作目录亲和度排序，与原生排序一致。
• 原生 mention 兼容：包装现有的 reference source 并保留其 onPick/codec，文件与会话 mention 保持原始序列化形式（@path、@"path"、@[label](dsh-session:...)）。

整体结构如下（来自仓库 README）：

DSH Web @ menu
      │  candidates() · local filter/rank
      ▼
dsh-better-at client cache
      │  listFiles / listSessions (once per TTL)
      ▼
DSH Host betterAt Remote
      ├── bounded workspace file/directory index
      └── full DSH session index + canonical mentions

Host 侧提供两个接口：

• betterAt/listFiles：遍历当前工作区一次，返回有上限的文件/目录索引。默认只排除 .git 和 node_modules，与原生文件引用搜索的行为一致。
• betterAt/listSessions：通过 ctx.sessionQuery 读取完整会话数据，为浏览器生成原生 dsh-session: mention。

缓存策略与代价¶

缓存是这类插件的核心，先说清楚参数：

• 文件索引按会话缓存 30 秒；会话索引全局缓存 5 分钟。
• 两者都采用 stale-while-revalidate：缓存过期时先返回旧快照，再在后台刷新，刷新期间菜单不会空白。

代价是一个小的实时性窗口：文件变更最长约 30 秒才出现在候选里，会话元数据最长约 5 分钟。对引用场景来说，这通常是可以接受的折衷。

安装与启用¶

前提：DSH Web 需具备原生 @ reference source；本地开发/构建需要 Node.js。lib/ 已提交到仓库，profile 安装本身不需要本地构建步骤。

1、从 GitHub 源码安装：

dsh plugin --profile web add github:Ruiming-cn/dsh-better-at

2、也可以用 GitHub release tarball：

dsh plugin --profile web add https://github.com/Ruiming-cn/dsh-better-at/archive/refs/tags/v0.2.0.tar.gz

3、或者从本地检出安装：

dsh plugin --profile web add .

安装后需重启 dsh web 生效。如果要本地开发或跑测试，仓库提供了 npm install --legacy-peer-deps 和 npm run check（含 typecheck、test、build 脚本）。

典型用法¶

装好后按原来的习惯使用 @ 即可：

• @ 打开快速文件/文件夹 + 会话选择器；
• @src/ 浏览 src/ 目录内部；
• @README 对文件 basename 做模糊搜索；
• @refactor 按 id、cwd 或 label 过滤 DSH 会话。

选中之后走原生 composer 行为：文件变成原子文件引用（或可编辑的目录路径），DSH 会话变成原生会话引用。

配置¶

插件只提供两个配置项，通过 profile patch 设置，示例文件为 ~/.dsh/profiles/web/cordis.patch.yml：

- id: dsh-better-at
  config:
    maxEntries: 10000
    ignoreDirs:
      - .git
      - node_modules

• maxEntries：默认 10000，索引工作区条目的硬上限，遍历超出时会报告截断。
• ignoreDirs：默认 ['.git', 'node_modules']，这些目录名从不被索引或遍历。

兼容性与边界¶

• 符号链接不被索引或遍历，与原生文件引用搜索行为一致。
• 当前会话会从 DSH 会话候选中排除，避免自引用——原生会话引用协议会拒绝这种情况。
• 浏览器集成使用与 dsh-skill-fuzzy 相同的私有 inputTriggers.live.sources 包装模式；若未来 Harness 版本改变了这个内部结构且 Remote 不可用，插件会降级为原生 candidates 路径。
• 依赖前文的私有包装模式，意味着它对 Harness 内部实现有一定耦合，版本升级后值得验证一遍。

适用场景与安全提醒¶

适合的人群：工作区文件多、历史会话多，经常在 DSH Web 里用 @ 引用文件或会话，对菜单响应速度敏感的使用者。反过来，如果你的工作区很小、@ 菜单本来就不慢，收益有限，还要接受最长 30 秒/5 分钟的新鲜度窗口，可以先观察再决定。

一点提醒：DSH 的理念是「一切皆插件」，插件以当前 dsh 进程的权限运行。安装第三方插件前，建议阅读其源码并确认许可证（本项目为 MIT），评估无误后再装。

结尾¶

回顾一下：dsh-better-at 通过会话级预热加浏览器本地过滤，去掉了 @ 菜单的逐键 Host 往返，同时保留原生 mention 形式与排序，配置只有 maxEntries 和 ignoreDirs 两项，装完重启 dsh web 即可。

• 社区目录页：https://www.skillhub.cn/plugins/Ruiming-cn/dsh-better-at
• GitHub 仓库：https://github.com/Ruiming-cn/dsh-better-at

文中目录页来自社区维护的独立站点，与 DeepSeek、幻方无官方从属关系。