# 使用说明 · dsh-conversation-trash

一句话：给 DSH 侧栏加「删除对话」——**软删除进回收站，8 秒内可撤销**，子代理会话跟着删，分叉不动。

---

## 1. 已经装好了（当前状态）

```
%USERPROFILE%\.dsh\profiles\desktop\node_modules\dsh-conversation-trash\   ← 插件本体
%USERPROFILE%\.dsh\profiles\desktop\cordis.patch.yml                    ← 追加了一条 loader 条目
%USERPROFILE%\.dsh\profiles\desktop\cordis.patch.yml.bak-20261018-201315 ← 改之前的备份
```

**还差一步：完全退出 DSH 再打开。**
托盘图标 → 退出（不是关窗口），等进程结束，再启动。

> 重启会结束当前这个对话会话。重启前可以先复制走需要的结论。

---

## 2. 怎么用

### 删除一条对话

1. 左侧会话列表，鼠标移到某一行 → 右侧出现 `…`
2. 点 `…` → **删除对话**（红色，在「归档会话」下面）
3. 确认框会显示：
   - 会话标题
   - 「同时会删除它们的 N 个子代理会话」（有子代理时）
   - 「正在运行的工作会先被停止」
4. 点 **移入回收站**

结果：这一行立刻从默认列表消失；右下角出现 `已删除「标题」 · 撤销`。

### 撤销

8 秒内点 toast 里的 **撤销**。会话目录移回原处、取消归档，行回到列表原位。

超过 8 秒：到回收站目录手工恢复（见第 4 节）。

### 它到底做了什么

| 步骤 | 动作 |
|---|---|
| 1 | `archiveSession(id, { stopActivity: true })`：停掉正在跑的回合/子代理/定时任务，并把行从默认列表隐藏 |
| 2 | 把 `~/.dsh/sessions/<工作区>/session-<id>/` 移到 `~/.dsh/session-trash/<id>/` |
| 3 | 在 `~/.dsh/session-trash/index.json` 记一条：标题、父会话、删除时间、大小 |

所以「删了」是**真的从会话目录里移走**，不是只藏起来。

---

## 3. 恢复 / 彻底删除

目前 UI 只做到「删除 + 撤销」，彻底删除走 Host 的 HTTP 接口（同源、仅本机可调）。

在本机 PowerShell 里：

```powershell
# 看看回收站里有什么
Invoke-RestMethod -Method Get -Uri "http://127.0.0.1:65162/dsh-conversation-trash/list" | ConvertTo-Json -Depth 5

# 恢复某一条（父会话会连同子代理一起回来）
Invoke-RestMethod -Method Post -Uri "http://127.0.0.1:65162/dsh-conversation-trash/restore" `
  -ContentType "application/json" -Body '{"sessionId":"<会话id>"}'

# 彻底删除某一条
Invoke-RestMethod -Method Post -Uri "http://127.0.0.1:65162/dsh-conversation-trash/purge" `
  -ContentType "application/json" -Body '{"sessionId":"<会话id>"}'

# 清空回收站
Invoke-RestMethod -Method Post -Uri "http://127.0.0.1:65162/dsh-conversation-trash/purge-all" `
  -ContentType "application/json" -Body '{}'
```

> 端口以实际为准：DSH 每次启动的 Web 端口可能不同，看窗口标题栏/设置里的地址。
> 恢复后如果列表没变，切一下工作区或刷新页面。

---

## 4. 数据在哪，能不能手工救

```
~/.dsh/session-trash/<session-id>/      ← 被删会话的原始日志（zstd 压缩的 jsonl）
~/.dsh/session-trash/index.json         ← 回收站索引
~/.dsh/sessions/<workspace>/session-<id>/ ← 原始位置，恢复时移回来
```

手工恢复（插件坏了也能用）：

1. 退出 DSH
2. 把 `~/.dsh/session-trash/<id>/` 整个文件夹移回 `~/.dsh/sessions/<原工作区>/session-<id>/`
3. 编辑 `~/.dsh/session-trash/index.json`，删掉对应条目
4. 启动 DSH；如果它还显示「已归档」，在侧栏视图选项里选「全部对话（显示已归档）」→ 取消归档

---

## 5. 常见问题

**启动后菜单里没有「删除对话」**
- 确认是双击启动的桌面版，不是命令行 `dsh web`
- 打开 设置 → 插件，看有没有 `session-trash` 这一项；没有就说明 patch 没被读到
- 看 `%USERPROFILE%\.dsh\logs`（或控制台）里有没有 `[session-trash]` 开头的报错

**菜单用着用着突然消失（尤其在装/更新了市场插件之后）**
- 原因：插件市场的安装动作会跑一次 `pnpm install`，它会把「不在 profile `package.json` 里」的包当成多余包清掉。手放进 `node_modules` 的插件正好落在这一类。
- 修复：重跑一次安装脚本（新版本会把插件登记进 `package.json` 的 `dependencies`）：
  ```powershell
  powershell -ExecutionPolicy Bypass -File "<插件目录>\install.ps1"
  ```
  然后完全退出 DSH 再启动。
- 判断是不是这个原因：`cordis.patch.yml` 里还有 `name: dsh-conversation-trash`，但 `node_modules\dsh-conversation-trash` 不见了 —— 就是这个。

**所有终端命令都报「因为在此系统上禁止运行脚本」**
- 不是本插件的问题。是 `dsh-ops` 的 `prepare-workspace.ps1` 被执行策略挡了，DSH 每次跑命令前都要先执行它。
- 修法（普通 PowerShell 窗口里执行一次）：
  ```powershell
  Set-ExecutionPolicy -Scope CurrentUser RemoteSigned -Force
  ```

**删完 toast 说「已删除」，但对话还在列表里**
- 旧版本在 session id 带 `session-` 前缀时会静默失败（只写了一条 `moved:false` 的记录）。现在已修：host 会统一去掉前缀；如果仍然只归档、没移走日志，toast 会明确说「已标记删除，日志将在下次启动时移走」。

**删除时提示「删除失败」**
- 多半是会话日志被占用（Windows 文件锁）。插件会把这次移动标记为 pending，**下次启动时自动补做**
- 期间该会话仍会出现在「全部对话（显示已归档）」里，这是预期

**删除后它还留在「显示已归档」里**
- 正常。归档状态是我们用来隐藏行的手段，日志已经移走了；重启后它会彻底消失

**删掉的正好是当前正在看的对话**
- 行会消失、归档门会拦住新回合，但主区域不会自动跳走。点一下别的对话或新建一个即可

**想整体回滚**
```powershell
powershell -ExecutionPolicy Bypass -File "<插件目录>\uninstall.ps1"
```
回收站里的数据不会被删，留在 `~/.dsh/session-trash`，可以按第 4 节处理。

---

## 6. 想改文案 / 改行为

| 想改什么 | 改哪 |
|---|---|
| 菜单文字、确认框文案 | `lib/client.cjs` 顶部的 `TEXT.zh` / `TEXT.en` |
| 撤销时长（现在 8 秒） | `lib/client.cjs` 的 `UNDO_HOLD_MS` |
| 菜单排序（现在 500，归档是 400） | `lib/client.cjs` 里 `order: 500` |
| 子代理是否级联 / 分叉是否保留 | `lib/index.mjs` 的 `descendantsOf()` |
| 文件占用重试节奏 | `lib/index.mjs` 的 `MOVE_RETRY_DELAYS_MS` |

改完把 `lib/` 重新复制到 profile（或重跑 `install.ps1`），再重启 DSH。

---

## 7. 自检（不启动 DSH 也能跑）

```powershell
$node = "C:\Users\Lenovo\.dsh\dsh-runtimes\dsh-primary-runtime\dependencies\node\bin\node.exe"
& $node test/smoke.mjs        # 假 HOME 里跑完整删除/恢复/清空 + 防盗链
& $node test/client-shape.mjs # 浏览器包注册了哪两个 slot
& $node test/dry-run.mjs      # 只读地扫真实 ~/.dsh，确认能找到会话目录
```