# 使用指南

安装和基本操作见[项目首页](../README.md)。本文介绍管理窗口、多来源连接、备份配置和常见问题。

## 管理对话

点击侧边栏底部的“管理对话”。每条记录展示标题、工作区、来源、大小、文件更新时间、会话 ID 和保护状态；每页显示 50 条。

可以按标题、工作区名称、路径或 ID 搜索，也可组合来源、工作区、状态、天数和大小筛选，按最近、最早、最大和标题排序。“重置筛选”恢复完整列表。

概览展示记录总量与占用；搜索栏下的快捷筛选可直接查看未归档、已归档、置顶、受保护或缺失记录，数量按完整名单计算。更多年龄、大小条件位于“更多筛选”中。来源名称展示在记录下方，悬停可查看完整路径。

同名、无标题、已归档，以及文件已缺失但索引仍有残留的记录，都可以在这里查找。空闲且可完整释放的会话会显示“已打开 · 空闲可删除”；运行中或无法安全释放的会话会标记原因并禁止删除。

“更新时间”取会话目录内非临时文件的最新修改时间，并非最后一条消息的精确时间。大小包含嵌套文件，不含投影缓存或已有备份；因此不等同于实际可释放空间。

## 多来源路径

### 添加与连接

1. 在管理窗口点击“管理来源路径”。
2. 填写名称和 **DSH 数据根目录的绝对路径**。该目录下应包含 `sessions` 文件夹。
3. 如需执行删除、归档或置顶，填写该目录所属宿主的本机 HTTP 地址，例如 `http://127.0.0.1:端口/?token=…`。该宿主也须安装并启用本插件；地址可从对应 Web 宿主的启动输出取得。
4. 点击“保存路径”。插件会核对连接地址与数据目录是否一致。

所有来源合并到同一列表，可用“来源路径”单独筛选。未连接宿主的来源可以查看和搜索，操作按钮保持禁用。同 ID 的记录按来源分别选择，预览和结果均展示来源。

### 编辑与移除

“编辑”可以修改名称或连接地址。编辑时地址留空会保留原有连接。“移除来源”只移除来源设置，不删除记录或备份。

来源设置保存在当前数据目录的 `storages/dsh-chat-prune-sources.json`，关闭窗口或重新打开页面后仍保留。认证地址保存在宿主侧，不回传到列表或表单；请勿将包含认证参数的地址公开。

每个来源通过自己的宿主更新索引、持有写入所有权，并在自己的 `deleted-sessions/` 下备份。某个来源暂时读取失败时会单独显示错误，其他来源仍可使用。

## 批量操作

1. 筛选后勾选记录或标题区域。表头的“本页”可选择或取消当前页，“选择全部筛选结果”会跨页选择全部可操作记录。部分选中时表头显示半选状态。翻页和排序保留选择，更改筛选会清空选择。
2. 选择归档、取消归档、置顶、取消置顶、删除、压缩、解压或导出压缩包。
3. 点击“预览所选操作”，核对完整目标清单、来源、大小和跳过数量。取消预览不会修改记录。
4. 确认后逐条执行。点击“停止后续任务”会等待当前请求完成，再停止尚未发出的请求；已完成的操作保留。
5. 底部显示已选数量与容量；执行期间显示进度。完成或停止后收起进度条，并提供成功、失败、跳过和未执行数量及明细。失败项保留选择，处理原因后可重新预览。

归档会保留记录并取消置顶；取消归档不会自动恢复置顶。归档中的会话需要先取消归档才能置顶。活动任务的归档由宿主拒绝，不会强制停止任务。

批量删除始终跳过置顶、运行中和无法安全释放的会话，默认勾选备份。预览后记录更新、被置顶或开始运行时，执行会拒绝对应记录并报告原因，不会扩大删除范围。请求超时或结果无法确认时停止后续操作，请先刷新确认实际结果。

## 保留规则

点击工具栏的“保留规则”，设置保留数量和天数，再点击“生成修剪候选”。例如每个工作区保留最近 10 条，只修剪早于 30 天的记录。

候选来自当前筛选范围，但“最近 N 条”按每个来源的整个工作区分别计算。置顶、受保护、记录缺失及更新时间未知的会话不会进入候选；未连接宿主的来源不会被自动选中。

生成候选不会修改数据，仍需预览并确认。最终确认前会重新计算保留规则，实际执行还会校验目标状态。

修改已生成计划的保留数量或天数时，候选选择会清空，并提示重新生成，避免按过期规则执行。

要清理缺失文件的残留索引，请使用“记录缺失”状态筛选并手动选择；这类记录不会自动混入旧记录候选。

## 压缩与迁移

### 手动压缩与按需恢复

勾选一条或多条对话，选择“压缩记录”，预览后确认。名单显示“已压缩”，记录占用显示压缩后的会话目录大小。压缩保留标题、事件和附件，置顶、归档及工作区关系不变；原生对话列表仍能展示这些记录。再次从原生列表打开时自动恢复文件，也可选择“解压记录”手动恢复。

宿主日志原本就使用 zstd，进一步节省空间主要取决于附件和投影缓存。压缩时移除可重建的投影缓存及缓存备份；若进一步压缩不能减少占用，会保留原文件并在操作结果中说明。运行中、无法完整释放或仍被其他写入者占用的会话会拒绝压缩。压缩后的记录需要本插件保持启用才能正常列出和按需恢复；卸载前可先批量解压。

### 自动压缩

展开“压缩与迁移”，输入“多少天未更新后自动压缩”，点击“保存自动压缩设置”。`0` 表示关闭，默认关闭；可设为 1–36500 天。宿主运行期间每分钟检查一次，不需要保持管理窗口打开；也可点击“立即检查自动压缩”查看本轮结果。

自动规则仅作用于当前数据来源，跳过已压缩、置顶、受保护、缺失和时间未知的记录。条件按会话目录文件的最新修改时间计算；按需解压会记录最近访问时间，防止刚打开的旧对话立刻再次压缩。设置保存在 `storages/dsh-chat-prune-compression.json`，重启后继续生效。

### 批量导出与新环境导入

1. 选择同一来源的一条或多条对话，选择“导出压缩包”，预览确认后下载 `.dsh-chat.gz`。已压缩记录也可直接导出，无需先解压。
2. 在新环境安装并启用插件，打开管理窗口的“压缩与迁移”。
3. 选择导出的文件，点击“导入对话压缩包”。插件校验完整压缩包后，通过宿主接口创建对话并恢复附件。
4. 导入的记录集中在当前环境的“导入的对话”工作区，保留原 ID、标题、事件内容、置顶和归档状态；会话工作路径映射到当前数据目录的 `imported-conversations/`，无需原机器的工作路径。

遇到已有 ID（包括大小写别名），会在导入开始前拒绝整个包，避免覆盖现有记录。导入逐条提交；磁盘或宿主在处理中失败时，已创建的记录会保留，界面报告中断原因。请刷新并检查结果后处理冲突，再重试。

每包最多 1000 条对话、20000 个文件、64 MiB 压缩数据和 256 MiB 解压 JSON；单条源会话目录最多 128 MiB。超限时请减少附件或分批导出。该格式是本插件的版本化对话包，不能导入任意 gzip/ZIP 文件；工作区内的外部项目文件不在导出范围。

## 备份设置

单条删除默认不备份，批量删除默认勾选“删除前备份”。开启全局备份后，单次请求不能关闭它。

先正常退出 DSH，再编辑安装目录中的：

```text
<DSH 数据目录>/profiles/<profile>/node_modules/dsh-chat-prune/cordis.patch.yml
```

将 `backup: false` 改为 `backup: true`，保存后重新打开 DSH。

| 设置 | 默认值 | 用途 |
|---|---|---|
| `backup` | `false` | 先完整备份会话目录，备份失败则不删除 |
| `allowRunning` | `false` | 建议保持默认；不能绕过宿主的写入所有权检查 |
| `icon` | `'trash'` | 保留配置项，目前提供垃圾桶图标 |

备份保存在各来源数据目录的 `deleted-sessions/`。每份备份附带 `restore.json`，记录原路径及恢复说明；备份不会自动清理。

恢复需要先退出 DSH，再手动恢复目录和索引，详见[备份与恢复](./technical-reference.md#备份与恢复)。关闭备份时，插件不提供恢复功能。

## 常见问题

### 键盘与窄屏操作

管理窗口打开后可直接搜索。在输入框外按 `/` 可回到搜索框；输入框中仍可正常输入斜线。Escape 取消批量预览并将焦点返回预览按钮；任务执行中按 Escape 会请求在当前操作完成后停止。

窄屏下工具栏使用带标签的图标按钮，状态筛选可横向滚动；会话列表有独立滚动区，筛选和来源设置在上方展开区域滚动，底部分页和批量操作保持可达。

### 对话首次加载失败

界面会显示连接错误和“重新加载”按钮，不会将读取失败显示为空目录。检查宿主是否正常运行后重试；已有名单刷新失败时仍保留原记录供核对。

### 看不到垃圾桶或管理入口

先展开工作区，再悬停具体会话行。安装或更新后完整退出并重新打开 DSH，确认插件已安装并启用在当前使用的 profile。

### 为什么提示“进行中或受保护”

运行中的任务和无法安全释放的会话会阻止删除。插件只能释放自己已跟踪的空闲生命周期句柄；取消任务或移除列表项不等于释放写入所有权。更新后请完整重启 DSH。

### 删除完成后列表还未更新

在管理窗口点击“刷新列表”确认结果，不必再次删除。若仍有残留，请提供脱敏后的错误信息和复现步骤。

### 标题显示为会话 ID

无标题、日志格式不兼容、Node.js 缺少 zstd 支持或标题扫描超出限制时，会使用会话 ID。记录仍可按 ID 管理。

### 如何反馈问题

在 [Issues](https://github.com/Cans518/dsh-chat-prune/issues) 中提供插件版本、DSH 版本、系统、操作步骤、预期与实际结果。日志和截图请去除认证地址、API Key、对话正文及个人路径。

返回[项目首页](../README.md)。