# dsh-curate 使用手册

本文是 [README](../README.md) 的展开版，说明编辑、压缩、草稿、备份和错误处理的具体行为。适用于 0.7.6。

## 安装

要求：

- DSH `0.2.1-rc.x`（已声明并测试 `0.2.1-rc.2`）；
- Node.js ≥ 22；
- 仅验证 DeepSeek 模型。

从 GitHub 安装：

```bash
dsh plugin --profile web add github:111222cjyq/dsh-curate
```

本地开发：

```bash
git clone https://github.com/111222cjyq/dsh-curate
cd dsh-curate
npm ci
npm run build
dsh plugin --profile web add "$PWD"
```

安装或升级后：

1. 完整重启 `dsh web`（不是只刷新页面）；
2. 硬刷新浏览器页面；
3. 打开会话，确认头部出现「整理上下文」。

**不要**在会话打开时反复 disable/enable 插件：DSH 的 live session 会持有消息投影对象，完整重启才能安全重建。

## 工作台

### 按轮整理

工作台把当前模型可见的 surface 按轮分组；系统提示不进入工作台，最后一条消息固定保留。

- **最近保留 N 轮**：默认把最近 N 轮设为「重要」，但可以手动覆盖；
- **组头按钮**：整轮批量设置「重要 / 默认 / 次要」；
- **单条语气**：每条消息头部可单独覆盖；
- **混合**：同一轮里可同时出现保留、摘要和丢弃。

### 重要 / 默认 / 次要

| 语气 | 压缩时的行为 |
| --- | --- |
| 重要 | 原文保留，不进入压缩区间 |
| 默认 | 生成常规摘要并替换该区间 |
| 次要 | 直接丢弃，只写一条极短省略标记，不生成摘要 |

工具调用与对应的工具结果自动归为同一语气单元，避免压缩时拆开。

### 视图

- **全部内容**：显示工具结果、工具调用、注入上下文和思维链；
- **仅对话文本**：只显示用户/助手文字，隐藏工具/上下文/思维链；
- **压缩摘要只看对话文本**：只影响「默认」摘要的输入，不影响压缩范围；「次要」始终直接丢弃；
- **查看完整原文**：展开渲染后的消息；`编辑` 进入编辑器。

## 编辑消息

编辑入口：消息右上角「编辑」，或预览行的铅笔。编辑器顶部和底部都有「取消编辑 / 保存修改」。

### 保存与应用的三个层次

| 操作 | 位置 | 作用 |
| --- | --- | --- |
| 保存修改 | 编辑器顶部/底部 | 暂存这条消息，不写会话 |
| 保存当前内容 | 工作台底部 | 保存整个工作台的本地草稿，不写会话 |
| 修改并应用到上下文 | 工作台底部 | 真正写入会话 |

暂存成功后：

- 消息旁显示「已修改（待应用）」；
- 底部按钮从「应用到上下文」变为「修改并应用到上下文」；
- 如果按钮不可点，通常是**没有暂存修改**；先编辑并点「保存修改」。

### 可编辑内容

- **用户消息**：通过官方 surface replacement 写入；模型读到新措辞，不产生新用户输入；
- **助手正文 / 思维链**：通过 `plugin:dsh-curate/patch` 记录 + 消息投影替换；改写思维链时会去掉旧签名；
- **工具结果**：只改文本块，保留 `toolCallId`、`isError` 和配对关系；
- **注入上下文**：runtime context、summary、checkpoint 等文本块可改；
- **附件**：原样保留，不能在编辑器中增删；
- **系统提示 / 工具调用参数**：只读。

### 真实 Chat 显示

写入后，真实 Chat 会通过只读的 `GET /dsh-curate/changes` 装饰显示：

- 默认显示「写入上下文」的版本；
- 标题旁「修改后 N / 原文 N」切换显示；
- 「已修改 · N 处」标记显示改动数量；
- 改动词句高亮，纯删除显示「原文删除 N 字」；
- 点击标记打开「原文 / 写入上下文 / 改动」详情，可复制全文；
- 显示层只读，不写会话；关闭插件或刷新页面恢复宿主原始 HTML。

## 压缩

两种方式：

1. **按整理结果压缩**：只对「默认 / 次要」区间操作；模型仅为「默认」区间生成摘要，「次要」直接省略。可先应用暂存修改再压缩；
2. **官方 `/compact`**：调用当前 agent 预设的官方压缩命令，范围由官方压缩器决定，不按卡片标记。

确认前必须勾选「我理解不可撤销」；压缩后工作台重新读取会话。

**不可撤销**：会话内不能恢复被压缩的原始顺序、角色和工具配对。原文在 append-only 日志和本地备份里，但不会自动重建。

## 草稿

- 语气、视图、暂存修改自动保存到浏览器 localStorage；
- 会话增长后重新打开时，按消息序号恢复仍存在消息上的标注；
- 如果目标消息已不在当前 surface，横幅提示「旧草稿无法恢复」，并提供「清除旧草稿」；
- 清除旧草稿只删除本地草稿，不写会话。

## 配置

宿主默认优先使用该会话最近一次请求的 provider/model；也可以显式配置：

```yaml
- id: dsh-curate
  config:
    provider: deepseek-official
    model: deepseek-v4-flash
```

官方 `/compact` 使用当前 agent 预设的命令，不受该配置影响。

## 备份与审计

默认备份目录：

```text
~/.local/share/dsh-curate/backups/<sessionId>/
```

- 目录 `0700`，文件 `0600`，默认每会话保留 20 份；
- 可通过 `DSH_CURATE_BACKUP_DIR` 覆盖根目录，通过 `DSH_CURATE_BACKUP_KEEP` 调整保留份数；
- 每次写入前备份：`<time>-<random>-edit.json` / `apply.json` / `compact.json`；
- 会话日志记录 `plugin:dsh-curate/edit-plan`、`edit-applied`、`plan`、`applied`、`compact` 审计事件。

## 错误处理

| 提示 / 状态 | 含义 / 处理 |
| --- | --- |
| `409 stale` | 打开工作台后会话又有新消息；刷新上下文后重新编辑/应用 |
| `busy` | 会话正在生成或压缩；等当前 turn 结束 |
| `patch-unavailable` / `unsupported` | 当前宿主缺少消息投影或插件记录能力；升级/重启 DSH |
| `not-editable` | 目标消息不可编辑；刷新后重试 |
| `session message projection ... was removed or replaced` | 旧会话的投影对象已失效；完整重启 `dsh web` |
| `应用失败：备份写入失败` | 备份目录不可写；检查权限/磁盘，写入被取消 |
| `没有待应用修改` | 编辑器内容未保存或没有暂存编辑；点「保存修改」 |
| `旧草稿无法恢复` | 草稿目标消息已不在 surface；清除旧草稿后重新编辑 |

## 非目标

- 不自动调度压缩；
- 不修改其他插件或 profile；
- 不做跨会话批量整理；
- 不支持工作台增删附件；
- 不提供会话级撤销；
- 不在主对话区做逐条消息编辑入口；
- 不保证非 DeepSeek 模型的兼容性。