# DSH 会话搜索

[English](<README.md>) | 简体中文

在所有或指定工作区、会话中搜索已存储的 DeepSeek Harness（DSH）对话文本，支持精确、正则表达式、拼写容错及词内子序列匹配。通过侧边栏放大镜或 **Ctrl+F / ⌘F** 打开。

每个插件包版本的改动见双语[更新日志](<CHANGELOG.md>)。

本项目为独立社区插件，并非 DSH 官方插件。**插件包版本：1.3.6。**

## 功能

- **全部或多个工作区与会话**；可筛选的复选选择器按最近用户活动展示完整对话。工作区与会话范围取交集，未选表示全部。
- **消息时间筛选**：今天、最近 24 小时、最近 7 天、本月或自定义本地日期。
- 可在插件设置页保存配置档级的**实时搜索 / 按回车或点击搜索**触发方式。
- 类似 VS Code 的 **Aa（区分大小写）**、**ab（全字匹配）**、**.*（正则表达式）**，可组合使用。
- 默认**精确匹配**，也可选择**拼写容错**或**子序列**两种模糊模式。
- **时间线**与可折叠的**按会话**视图；会话分组显示完整匹配消息数。
- **最新优先 / 最早优先**，按匹配消息时间而非无关的会话活动排序。
- 可选包含**子代理对话**和**已归档会话**，并显示相应标记。
- 默认**仅搜索模型最终回复**；也可包含已存储的输入、中间回复、工具调用/结果及推理。
- 紧凑的主题适配搜索卡片、分组的工作区/会话筛选、可折叠搜索提示，以及靠近结果的视图与排序控件。
- 高亮摘要、分页、打开对话按钮、中英文界面与 DSH 主题支持。窄面板下控件自动堆叠，并尊重减少动画的系统设置。
- 提供与界面共享引擎的只读代理工具 **`search_session_text`**。
- 本地运行，不依赖独立搜索服务、全文索引、第三方依赖或构建步骤。

## 环境要求与兼容性

开发参考环境：**DSH Desktop runtime 0.2.1-rc.3**。这并不表示最低兼容版本，也不保证兼容所有 DSH 版本。插件需要 DSH 的会话查询/控制服务、插件管理及 Web UI 插件接口；这些接口可能随版本变化。

开发检查和测试需要 **Node.js 22+**。DSH 桌面版使用自带运行时，单独安装 Node 不会更改桌面版运行时。

## 安装

### npm 作用域发行包

本 npm 发行包为 **`@lizimin/dsh-session-search`**，源码仓库仍为 Ziminli/dsh-session-search。在 DSH 的**插件 → 添加插件**中输入：

```text
@lizimin/dsh-session-search
```

使用 DSH CLI 时可运行 `dsh plugin --profile <你的配置档> add @lizimin/dsh-session-search`。这是 DSH 插件包，不是独立搜索命令。不要与无作用域 GitHub/本地副本同时启用；它们共享路由、工具、服务及界面槽位。本发行包已同步作用域包名、Cordis 行、客户端模块和设置目标，搜索行为与 v1.3.6 相同。


### DSH 桌面版

1. 打开**插件 → 添加插件**（或**安装第三方插件**）。
2. 输入仓库地址：
   ```text
   https://github.com/Ziminli/dsh-session-search
   ```
3. 检查来源和信任提示后安装；如有需要，启用插件包。按照插件管理器返回的说明重启或重新加载。

### 本地目录 / 代理工具

克隆或下载仓库，通过 DSH 插件管理器安装该**插件包目录的绝对路径**。具备相应权限的代理可调用 `plugin_manager` 工具：

```json
{
  "action": "install_bundle",
  "target": "/absolute/path/to/dsh-session-search"
}
```

这是工具输入，不是终端命令。请替换为实际绝对路径；Windows 环境需包含盘符。请使用插件管理器，不要手动修改配置档清单或组合配置文件。安装影响当前 DSH 配置档，而非仅当前对话。

**不要同时启用多个会话搜索副本。** 请先禁用现有本地 `@local/dsh-session-search` 插件包。公开包不会自动迁移或删除旧包；重复的快捷键、界面注册、路由、服务及工具名可能冲突。仓库名称不表示本包已在 npm 发布。

## 使用

1. 点击侧边栏放大镜或按 **Ctrl+F / ⌘F**。默认输入后防抖 300 毫秒自动搜索。点击右上角**设置**可直接打开**插件 → 会话搜索**，不改变当前选中的对话。在该页将**搜索触发方式**改为**仅按回车 / 点击搜索时**并保存，可要求手动提交。此模式下文本与所有筛选条件一起等待提交，旧结果在修改后隐藏。
2. 默认**所有工作区**。打开工作区选择器，通过复选框选择一个或多个工作区；更改后清空已选会话。**清除选择（全部）**恢复所有工作区。**未分组 / 无工作区**包含不属于注册工作区的对话。会话选项及跨工作区结果显示工作区名称，悬停可查看路径。
3. 保持**所有会话**、复选多个对话，或点击结果中的**搜索此会话**。按标题或 ID 筛选选项，**全选当前列表**可追加当前筛选出的项。每项代表完整对话，按最近用户活动排序；分叉和未命名对话仍可选择。工作区与会话范围取交集。
4. 调整匹配、范围及**消息时间**。提供今天、最近 24 小时、最近 7 天、本月等预设。自定义起止日期采用浏览器本地时区，结束日期包含当地整天，也可仅设单侧边界。按消息自身时间戳筛选，而非会话活动时间；加载更多时相对时间窗口保持固定。默认启用**仅搜索模型最终回复**，默认不包含子代理及归档会话。
5. 选择结果顺序；搜索所有会话时可切换**时间线 / 按会话**。分组按最新匹配消息排序，选择最早优先时按最早匹配消息排序。同一消息内文本重复出现只计一次。
6. 展开分组，通过**加载更多结果 / 加载更多会话**分页（每页 40 条）。分组计数包含全部匹配事件，而不仅是已加载页面。
7. 其他位置发生新活动、重命名、删除或归档后，点击**刷新会话**。**打开对话**跳转到未归档对话，并沿用该结果的精确/正则/模糊匹配选项，将显示文本中的匹配临时标黄。按 **Esc** 或标题栏的**清除高亮**按钮移除。已归档对话需先在 DSH 侧边栏或归档管理中恢复；搜索本身不会恢复会话。

高亮对话保持原生 Conversation 模式与已选会话界面，因此文件、链接等会话操作仍可使用。插件仅在高亮期间临时替换对话外壳，通过独立的会话子插槽复用共享内容工厂；清除高亮、按 Esc 或切换到另一会话时释放替换项并恢复原有外壳，不重复声明原有插槽。高亮仅影响显示，不修改已保存消息、选中/复制行为或原有 Chat 渲染器。只处理当前渲染且未隐藏的文本块，不包括尚未加载的历史或折叠内容；加载更早消息或展开内容后会刷新。时间及最终回复筛选用于选择搜索结果，不限制打开后标黄的显示文本。Markdown 渲染可能改变空白或移除语法，因此按显示文本匹配且不能跨不同块级元素。打开结果时保留事件序号，并在挂载 Chat 前加载至该事件。兼容适配器识别精确对应的 Chat 消息行（不会选择附近但无关的事件），滚动至消息行及其首个已渲染匹配，并优先将高亮预算用于该消息；用户开始操作后停止自动滚动。目前 Chat 没有公开的选定事件展开/定位 API，折叠的思考/工具结果或 Chat 标记变化仍可能阻止定位，此时标题栏会明确提示，而不是跳到其他消息；展开相关内容后可显示匹配。依赖浏览器 CSS Custom Highlight API，不支持时明确提示；Host 匹配限时 100 毫秒，扫描上限为 500 文本块 / 200,000 UTF-16 单元 / 2,048 高亮区域，部分覆盖及错误在标题栏提示。“高亮已达上限”仅指本轮显示扫描的性能预算，不表示搜索结果缺失或消息被修改。查询仅临时保留，不保存或加入 URL。

按 Escape 或关闭按钮返回对话。查询及选项在客户端模块仍加载时保留；面板保持挂载时切换视图会保留已加载页面和展开状态。这些状态不保证在应用重启后保留；保存的搜索触发方式会持久化到配置档。插件接管 Ctrl+F/⌘F 期间，如需浏览器原生页面查找，请使用浏览器菜单。

## 匹配规则与搜索内容

| 开关 | 含义 |
| --- | --- |
| **Aa — 区分大小写** | 精确区分大小写；关闭时使用 Unicode 不区分大小写匹配。 |
| **ab — 全字匹配** | 完整匹配两侧不能紧邻 Unicode 字母、数字或下划线；不是自然语言分词。 |
| **.* — 正则表达式** | JavaScript Unicode 正则源码，不加 `/` 分隔符或末尾标志；大小写由 Aa 控制。 |

默认全部关闭：标点按字面匹配，查询词之间的空白可灵活匹配。查询最多 1,024 个 UTF-16 代码单元。表达式无效或超过**每会话 100 毫秒**匹配时限时，整个搜索会明确报错，不会静默遗漏匹配。零宽匹配显示为细竖线。匹配针对完整存储消息执行；摘要和高亮只是有限预览，不表示长消息中每一次出现。

### 模糊模式

在**文本匹配**中选择**拼写容错 / 子序列**；默认仍是**精确**。选择模糊模式会关闭正则，启用正则会恢复精确模式。HTTP/工具接口会拒绝同时启用 `useRegex: true` 与非 `off` 的 `fuzzy`。

模糊搜索有结果、但所选范围内没有任何精确匹配时，结果上方会提示**“未找到精确匹配。以下为模糊匹配结果。”**精确检查遵循大小写、全字、范围及内容设置，在分页前检查完整消息。加载中、发生错误、部分会话无法读取或没有模糊结果时不显示该提示。两种视图都以水平分隔线区分设置/说明与搜索结果。

- **拼写容错**：`wrokspace` 或 `workspce` 可找到 `workspace`。对完整 Unicode 字母/数字/下划线词进行插入、删除、替换及相邻字符交换匹配（optimal string alignment）。查询词长度 1–3 个 Unicode 字符允许 0 次编辑，4–7 允许 1 次，8 字符以上允许 2 次；高亮完整匹配词。
- **子序列**：`wrkspc` 可找到 `workspace`。字符必须在**同一个词内**依序出现，不跨整条消息任意散布匹配；高亮实际选中的字符。候选词长度不超过 `4 × 查询词长度 + 8` 个 Unicode 字符，以减少噪声。
- 多个查询词按顺序形成**连续短语**，空白灵活匹配，标点按字面匹配。词是连续的 Unicode 字母/数字/下划线，不是自然语言分词；模糊搜索不提供语义或同义词检索。
- 可继续使用区分大小写和全字匹配。模糊词本身已匹配完整词；全字开关另外检查完整短语的外部边界，包括以标点开头或结尾的短语。
- 模糊查询最多 **128 个 Unicode 码点 / 16 个词**，同时受通用 1,024 UTF-16 单元限制。两种模式保留时间排序、完整分组计数、范围筛选及相同的每会话硬性匹配时限，不按相关性排序。

**最终回复**指成功完成轮次中，最后一条未中断且不包含工具调用的助手消息里的文本块；不包含进度文本、推理、工具调用/结果、未完成或中断轮次及仅以工具结束的情况。分类依据持久化事件推断，而非存储的 final/commentary 通道标记。

取消**仅搜索模型最终回复**后，可搜索已存储的用户/系统/开发者输入、中间助手文本、推理、工具调用/结果及失败尝试文本。插件不会获取未存储的供应商隐藏数据、识别图片文字或打开附件，也不会单独索引原始供应商封装及已提交消息的重复流式片段。

分页前会扫描全部符合条件的会话，以保证可读会话的全局时间排序与分组计数完整。大型历史可能较慢，后续分页也会重新读取历史。无法读取的会话会明确提示结果不完整；单会话读取失败会直接报错。匹配结果或相关元数据变化会使续页游标失效，请重新搜索。

## 代理工具

`search_session_text` 支持：

- `action: "search"`（默认）：返回匹配回复/事件的摘要、事件序号及 UTF-16 高亮范围。
- `action: "groups"`：分页返回会话分组；`total` 为分组数，`totalMatches` 为匹配事件总数。
- `action: "sessions"`：返回符合条件的会话目录，不执行文本匹配。

`workspaceId` 可将上述三个动作限定在指定工作区；省略即搜索所有工作区。通过 `sessions` 响应的 `workspaces` 目录获取 ID，其中 `__ungrouped__` 表示未分组。响应包含工作区范围信息，每个会话、匹配和分组均携带 `workspaceId`、`workspaceTitle`、`workspacePath`。无效工作区及不属于所选工作区的会话会直接报错，不会静默扩大搜索范围。优先使用侧边栏注册的工作区归属，回退规则为 cwd 与唯一工作区根目录精确匹配；有歧义或不匹配的对话保留为未分组，子代理继承父会话的工作区。续页游标与工作区范围绑定。

选项包括 `query`、`workspaceIds`（最多 200 项）、`sessionIds`（最多 1,000 项）、`after` / `before`（Unix 毫秒时间戳，起始包含、截止不包含）、`includeSubagents`、`includeArchived`、`content`（`final` 或 `all`）、`order`（`newest` 或 `oldest`）、`matchCase`、`wholeWord`、`useRegex`、`fuzzy`（`off`、`typo` 或 `subsequence`）。数组为空或省略表示全部；同一列表内取并集，两类范围间取交集。兼容旧 `workspaceId` / `sessionId`，但不能与对应非空复数字段同时使用。无效或不可用的选择会报错，绝不静默扩大范围。时间筛选排除时间戳缺失的消息，在匹配、分组计数及分页前执行，不过滤会话目录。续页时将 `nextCursor` 作为 `cursor`，并保持动作、查询和选项不变。工具是否可用取决于当前代理和 DSH 策略。

`session_search_settings` 传 `{}` 读取已保存的触发方式；传 `{ "searchMode": "live" }` 或 `{ "searchMode": "submit" }` 保存，通过与插件设置界面相同的操作完成。这只更改配置，不更改对话。设置 HTTP 接口支持所有者身份验证后的 GET/POST，写入要求 JSON，失败会明确返回。

## 隐私与安全

搜索在当前 DSH 配置档内本地运行，不会修改、继续运行、恢复或删除会话。HTTP 接口要求 DSH 所有者身份认证并禁用响应缓存；摘要按纯文本渲染，不会执行会话提供的 HTML。正则匹配在 Host 端限时运行，不在浏览器执行。

结果可能包含敏感标题、ID、路径、提示词、工具输出和存储的推理。**代理工具结果可能进入模型上下文并发送给所配置的模型供应商。** 查询也可能出现在请求日志中。分享前请检查内容，不要在问题报告中上传私人历史或凭据。

## 开发

```sh
npm run check
npm test
npm pack --dry-run
```

无需安装依赖或构建。语法检查及合成数据测试不等于视觉正确或兼容其他 DSH 版本；请在目标应用中验证安装、代表性搜索、快捷键及明暗主题显示。

运行时文件：[index.js](<index.js>)（Host/HTTP/工具）、[settings.js](<settings.js>)（验证及持久化触发方式）、[search.js](<search.js>)（匹配/排序/分组/分页）、[session-catalog.js](<session-catalog.js>)（目录/事件提取）、[client.js](<client.js>)（界面/快捷键）。展示资源包括插件包补丁、本地化元信息和原创 SVG 图标。内部历史游标/VM 版本标记是实现标识，不是公开包版本。

[反馈问题](https://github.com/Ziminli/dsh-session-search/issues)时请提供 DSH/运行时版本及最小合成示例，不要提交私人对话导出。

## 发版与社区收录

每次插件包版本变化都必须在 [CHANGELOG.md](<CHANGELOG.md>) 添加面向用户的更新条目；`npm run check` 会检查当前版本是否已有条目。发布相应的 `vX.Y.Z` Git 标签和 GitHub Release，发布说明引用该条目。仅本地使用的开发版本在历史中明确标注。

可直接复制的[社区收录条目](<docs/community-listing.yml>) 遵循[社区贡献指南](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/blob/main/contributing.md)：中英文各一句、句号结尾、功能描述属实、仓库地址准确，并使用 `session` 分类。投稿时需另向社区仓库提交 PR，仅新增 `data/plugins/Ziminli__dsh-session-search.yml`，内容复制自该模板；不要手改其自动生成的 README。本仓库内的文件只是模板，**不表示已投稿或已收录**。社区还会检查仓库是否满一天、`dsh-plugin` topic、可安装的 `dsh.bundle` manifest 及真实可用代码。导出的 SVG 用于 DSH 界面；社区的可选 `icon` 字段要求 GitHub 托管位图，因此本模板省略该字段。

## 许可证

[MIT](<LICENSE>) © 2026 Zimin Li。所含原创 SVG 图标使用同一许可证。