前言¶

用 DSH 干活久了，会话记录越攒越多。「上次那个报错是怎么解决的」「之前那版配置写在哪」——答案多半躺在历史会话里，但 agent 本身看不见它们。手动翻会话文件要面对格式与压缩细节；自己写脚本扫文件，又碰不到当前正在进行中的这个会话。

dsh-session-search-pro 换了一条路：不直接读会话文件，而是走 harness 内置的 sessionQuery 服务，把「搜索、列出、读取会话」封装成三个 agent 工具。下面介绍它的能力、安装方式，以及在默认（stock）配置下的实际表现。

这是什么¶

dsh-session-search-pro 由 LeslieWylie 维护，MIT 许可证，当前版本 0.2.0。定位一句话：面向 DeepSeek Harness 的跨会话索引搜索，可搜索过去与当前的 DSH 会话。

几个设计点：

• 零运行时依赖：不需要 ripgrep，不做 zstd 解析，没有本地数据库。
• 只读：从不写入会话，自身也不维护数据库或缓存。
• fails closed：sessionQuery 完全不可用时只记一条警告，不注册任何工具——避免装上一堆一用就抛错的工具。
• 只覆盖 DSH 单一运行时，不搜索 codex / claude / pi / opencode 等外部来源。需要跨运行时会话搜索的话，README 中对比了直接扫描会话文件的另一条路线（Tieboyh 的 dsh-session-search），可以按需选择。

三个 agent 工具¶

agent_session_search：跨会话全文搜索¶

跨所有 DSH 会话做全文搜索，每条命中附带最佳匹配片段。参数：

• query（必填）：要找的文本。字面匹配——正则元字符没有特殊含义；大小写不敏感；空白灵活。
• limit：最多返回的会话数，1–50。默认取插件配置的 maxResults（默认 10）。
• maxScan：回退扫描时最多打开的会话数，1–500。默认取 maxScan（默认 200），走索引时忽略。

返回值带 engine: "index" | "scan" 字段，标明这次查询走了哪条路径；扫描路径还会附带 scanned 和 truncated。当前进行中的会话也在搜索范围内。

agent_session_list：列出会话¶

列出过去与当前会话。参数：

• limit：最多返回数，1–100，默认 20。
• cwd：对会话工作目录做子串过滤，比如只看某个项目目录下的会话。
• sort："newest" 或 "oldest"，默认 newest。

agent_session_read：按 id 读会话¶

按 sessionId 读取单个会话的标题、元数据和按序事件。参数：

• sessionId（必填）：会话 id，例如 "a4d75296-fc89-44b1"。
• maxEvents：最多返回的事件数，1–200，默认 50，最新的在前。

单个事件的长文本会截断为 4,000 字符。

stock 配置下的两条搜索路径¶

agent_session_search 有两条引擎路径，调用时自动选择。

索引路径：stock 的 dsh-base bundle 中，sessionQuery 的具体后端是 @deepseek-ai/dsh-session-query-sqlite，基于 SQLite FTS5。索引可用时插件走它，返回 engine: "index"。

但 stock 配置下这个后端默认 openAt: never，此时引擎会抛 SESSION_QUERY_SEARCH_DISABLED。本插件的做法是：准确捕获这个错误，回退为按最新优先逐个扫描会话，返回 engine: "scan"；如果抛的是别的错误——后端真的故障了——就直接把错误报出来，而不是拿一次更慢的扫描去扫同一个坏掉的存储。

性能上作者实测过：索引路径 17ms，回退扫描 3,042ms。索引值得开，只是它不能是唯一路径。0.1.0 及更早的版本就假定索引必然存在，stock 默认安装下所有查询都返回 {"error": "session search is disabled…"}——因为不抛错，看起来像在正常工作。当前 0.2.0 用的就是上面的回退逻辑。想打开索引，需要在部署层调整 session-query-sqlite 的 openAt 配置，具体见插件 README。

安装与启用¶

插件尚未发布到 npm，需直接从 GitHub 安装。环境要求：node ^22.19.0 || >=24.0.0；peerDependencies 为 @deepseek-ai/cordis ^4.0.1 与 @deepseek-ai/dsh-tools ^0.1.0-rc.6。

标准安装分三步：先编辑 profile 的 package.json，把插件加进 dependencies 并在 dsh.profile.bundles 注册；然后重装依赖；最后重启 profile。

// ~/.dsh/profiles/<profile>/package.json
{
  "dependencies": {
    "dsh-session-search-pro": "github:LeslieWylie/dsh-session-search-pro"
  },
  "dsh": {
    "profile": {
      "bundles": ["dsh-session-search-pro"]
    }
  }
}

cd ~/.dsh/profiles/<profile> && pnpm install
dsh --profile <profile>

不想跟踪默认分支，可以固定标签，写法如 github:LeslieWylie/dsh-session-search-pro#v0.1.0。注意别固定到 0.1.0——前面说过，那个版本及更早在 stock 配置下所有查询都会返回错误。

想先试用、不动 profile 配置：插件自带 cordis.patch.yml，装进 node_modules 后用启动器的 --patch 挂载运行一次即可。

cd ~/.dsh/profiles/<profile> && pnpm add github:LeslieWylie/dsh-session-search-pro
dsh --profile <profile> --patch ./node_modules/dsh-session-search-pro/cordis.patch.yml

插件配置写在 cordis.patch.yml 的 bundle 行，只有两个键：

• maxResults：默认 10，agent_session_search 调用方未传 limit 时的默认值。
• maxScan：默认 200，回退扫描最多打开的会话数。

经过上面的步骤，重启 profile 后工具即可使用。

典型用法¶

插件进 bundle 后，三个工具自动对 agent 可见，不需要手动调用。直接用自然语言说：

“Search my past sessions for anything about session search” → agent_session_search
“List my recent sessions in ~/Desktop” → agent_session_list
“Read session a4d75296-fc89-44b1 for me” → agent_session_read

模型会自己选对应的工具。

适用场景与注意¶

适合谁：

• 长期使用 DSH、希望 agent 能引用过往会话上下文的开发者。
• 没开索引的 stock 配置也能用——回退扫描保证搜索可用，只是从毫秒级变成秒级。
• 需要搜索当前进行中的会话。

注意：

• 只覆盖 DSH 单一运行时；codex / claude / pi / opencode 等外部来源的会话不在此插件范围内。
• 插件以当前 dsh 进程的权限运行，且安装来源是 GitHub 仓库而非 npm。安装前建议先把源码和许可证（MIT）过一遍，确认可信再挂进 profile。

小结¶

dsh-session-search-pro 把「翻历史会话」变成 agent 的一个工具调用：索引在就走 SQLite FTS5，不在就退回有界扫描；stock 配置开箱即用，服务完全不可用时宁可不注册工具也不给坏的。

• 社区目录页（独立站点，与 DeepSeek / 幻方无官方从属关系）：https://www.skillhub.cn/plugins/LeslieWylie/dsh-session-search-pro
• 源码仓库：https://github.com/LeslieWylie/dsh-session-search-pro