dsh-client-ui-conversation-outline

Readme

# dsh-conversation-outline

> 对话大纲 —— 一个静态 DSH Web 插件：在 [DSH-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar)
> 侧边栏注册「对话大纲」tab，把当前会话按轮次结构化展示，为每一轮用 LLM 生成一句话标题，并支持点击跳转到对应消息。

[![License: MIT](https://img.shields.io/github/license/YesSanSan/dsh-conversation-outline)](LICENSE)
[![GitHub release](https://img.shields.io/github/v/release/YesSanSan/dsh-conversation-outline)](https://github.com/YesSanSan/dsh-conversation-outline/releases)
[![dsh-plugin](https://img.shields.io/badge/GitHub-dsh--plugin-blue)](https://github.com/topics/dsh-plugin)
[![better-sidebar](https://img.shields.io/badge/better--sidebar-%5E0.12.0-6e56cf)](https://github.com/omdsh-dev/DSH-better-sidebar)

[English](README.en.md)

## 概览

**适合谁**：使用 DeepSeek Harness Web（`npx @deepseek-ai/dsh web`）、希望快速
浏览当前会话结构、不用来回滚动长对话的用户。

**解决什么问题**：

- **按轮次结构化大纲** —— 用户消息、助手回复、工具调用（连续调用自动合并为可折叠分组）、
  压缩检查点、错误行，全部按轮次分组展示。
- **一键跳转** —— 点击任意条目，自动加载历史并滚动到聊天视图 / 轨迹视图的对应行。
- **每轮一句话标题** —— Host 直接调用 `llm.stream` 生成（不创建 subagent），
  按内容指纹缓存；分支会话前缀相同即可复用标题。
- **标题生成完全并行** —— 已结束轮次即时生成，即使 agent 仍在处理后续轮次；
  只有当前进行中的轮次等待本轮结束。
- **可配置** —— 标题模型、推理等级、并发数、单次超时、失败重试、禁用开关，
  全部在齿轮设置中持久化。
- **窄面板自动收缩** —— 面板变窄（≤360px）时，行内类型标签（用户/助手/工具等）
  自动从文字收缩为图标（悬停显示文字），与轨迹视图行为一致。

## 效果图

<p align="center">
  <img src="assets/screenshot-outline.png" alt="对话大纲效果图" width="320">
</p>

> 右侧边栏中的「对话大纲」面板：按轮次折叠展示，每轮带 LLM 标题，点击任意条目可跳转到对应消息。

## 兼容性

| 项目 | 值 |
|---|---|
| 平台 | DSH web（`npx @deepseek-ai/dsh web`） |
| 客户端平台 | `dsh.client.platform = "web"` |
| 依赖 | [dsh-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar) **v0.12.0+**（`settings.render` 与 `pluginSettings`） |
| Peer 依赖 | `@deepseek-ai/dsh-client-runtime`、`@deepseek-ai/dsh-client-ui-primitives`、`dsh-better-sidebar`（可选 peer） |
| 最后验证 | DSH web profile + better-sidebar v0.12.0（本地构建），2025 |

> npm 上的 `dsh-better-sidebar` 可能仍是 `0.11.0`；v0.12.0 功能需从源码构建后链接到 profile
> （见 [better-sidebar 文档](https://github.com/omdsh-dev/DSH-better-sidebar)）。

## 安装

### 方式一：一行命令（推荐）

直接安装到你的 web profile，无需手动 clone：

```powershell
npx @deepseek-ai/dsh plugin --profile web add github:YesSanSan/dsh-conversation-outline#main
```

> git 托管插件安装时会执行构建脚本，pnpm 默认拦截；若提示需要 allowBuilds，
> 把 pnpm 打印的 key 加入 `<profile>/pnpm-workspace.yaml` 的 `allowBuilds` 后重跑即可。
> 本插件是纯 JS 静态包，通常无需构建脚本。

### 方式二：clone 后本地安装

```powershell
git clone https://github.com/YesSanSan/dsh-conversation-outline
cd dsh-conversation-outline
npx @deepseek-ai/dsh plugin --profile web add .
```

### 重启与启用

重启 DSH：

```powershell
npx @deepseek-ai/dsh web
```

打开 better-sidebar 的 **+ 菜单**，选择「对话大纲」。

### 卸载

```powershell
npx @deepseek-ai/dsh plugin --profile web remove dsh-client-ui-conversation-outline
```

## 快速开始

1. 安装插件后启动 `npx @deepseek-ai/dsh web`。
2. 打开任意会话，在侧边栏 + 菜单添加「对话大纲」tab。
3. 大纲展示每轮及其 LLM 标题；点击条目即可跳转。
4. 可选：齿轮设置里选择标题模型 / 推理等级，或调整超时与重试。

## 配置

持久化到 better-sidebar `pluginSettings['conversation-outline']`
（`localStorage` 键 `dsh-conversation-outline-settings:v1` 作为旧版回退）。

| 键 | 默认 | 范围 | 含义 |
| --- | --- | --- | --- |
| `model` | `''` | — | 标题模型；空 = 跟随主会话模型 |
| `reasoningEffort` | `''` | off / low / medium / high / max | 推理等级；空 = 跟随会话 |
| `maxConcurrency` | `3` | 1–8 | 客户端并发生成标题的 worker 数 |
| `timeoutSeconds` | `60` | 5–300 | 单次尝试超时；对**整个尝试**生效（`Promise.race` 强制） |
| `maxRetries` | `2` | 0–5 | 失败重试次数（退避 0.8s 起，封顶 5s） |
| `disabled` | `false` | — | 完全禁用标题生成 |

## 权限与数据

- **会话日志**：Host 通过 `ctx.sessionQuery`（`readSession` / `listEvents`）只读当前会话日志构建大纲，不回写。
- **LLM 调用**：标题生成只把当前轮可见文本（用户 + 助手块，去掉工具调用，截断）发送到配置的模型路由，提示词为固定短摘要指令。
- **浏览器存储**：标题缓存于 `localStorage`（`dsh-conversation-outline-titles:v1`）；设置在 `pluginSettings` + `localStorage`。
- **不读取任何凭据**；除配置的模型 provider 外无其他网络访问。

## 故障排查

| 现象 | 含义 / 处理 |
| --- | --- |
| 标题一直「等待本轮结束...」 | 该轮尚无 `turn/end` 事件，是当前运行中的轮次；本轮结束后自动生成。 |
| 「未生成 · title timeout after ...」 | 单次尝试超过 `timeoutSeconds`（网络/模型卡顿）。调大超时或检查模型路由。 |
| 「未生成 · signals[0] is not of type AbortSignal」 | 静态 Host（Node）有真实 `AbortController`，正常不应出现；如出现请附日志反馈。 |
| 更新后标题不生效 | 静态包与 Host 半需要**完整重启** `npx @deepseek-ai/dsh web`，再刷新浏览器。 |
| 没有「对话大纲」tab | 确认 better-sidebar v0.12.0+ 且插件已安装（`dsh --profile web --dump-config`）。 |
| 失败标题缓存 60 秒 | 瞬时错误缓存 60s 后自动重试；确定性错误（无文本 / 无 Agent / 无模型参数）永久返回。 |

## 开发

见 [docs/PLUGIN_DEV_NOTES.md](docs/PLUGIN_DEV_NOTES.md)：WebUI 关键接口（slots、
会话快照、锚点）、目录行为与最容易踩的坑。`dev/dynamic/` 保留早期动态插件原型供对比，
正式交付以仓库根目录静态包为准。

```powershell
npm run check        # node --check index.js && node --check client.js
```

贡献方式：fork → 修改 → `npm run check` → 提 PR。客户端是手写
`window.__ModuleLoader__.load` bundle，无需构建步骤。

## 许可证与安全

[MIT](LICENSE)。安全问题请通过
[Issues](https://github.com/YesSanSan/dsh-conversation-outline/issues) 私密反馈，
或先邮件联系作者，再公开披露。

---

已收录于 [awesome-dsh-plugins](https://github.com/AdamPlatin123/awesome-dsh-plugins)
插件生态目录（`dsh-plugin` topic）。收录 ≠ 兼容性审计；安装前请自行审查源码。