dsh-toolfold

Readme

# dsh-toolfold · 工具调用折叠

[![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)

中文 | [English](README.en.md)

> DSH Web GUI 插件，提供**简单的工具调用折叠体验**：把连续的**工具调用**折叠成一条简洁的折叠条，只展示最后一个调用的一行摘要，点击即可展开/收起。不替换任何内置渲染器，卸载后界面完全恢复原样。

![折叠效果演示](assets/demo-fold.gif)

---

## 目录

- [安装](#安装)
- [快速上手](#快速上手)
- [初次使用·默认行为说明](#初次使用默认行为说明)
- [功能特性](#功能特性)
- [设置说明](#设置说明)
  - [设置项](#设置项)
  - [存储位置](#存储位置)
- [性能](#性能)
- [限制与兼容性](#限制与兼容性)

---

## 安装

### 推荐（通过 npm）

```sh
dsh plugin --profile web add dsh-toolfold
```

### 其他方式

```sh
# 从 GitHub 安装
dsh plugin --profile web add github:Minecraftbe/dsh-toolfold

# 从源码安装
git clone https://github.com/Minecraftbe/dsh-toolfold.git
dsh plugin --profile web add ./dsh-toolfold
```

安装后**重启 dsh 并刷新浏览器**即可生效。可通过以下命令确认配置已生效：

```sh
dsh --profile web --dump-config
```

### 卸载

```sh
dsh plugin --profile web remove dsh-toolfold
```

重启后界面完全恢复原样。

> ⚠️ **版本支持**：本插件支持的 DSH 区间以 `package.json` 中 `engines.dsh` 声明为准。在此范围之外的 DSH 上，设置卡片会显示版本不匹配警告（hover 提示 live 区间），折叠功能可能无法正常工作。

---

## 快速上手

安装完成后，在 DSH 对话界面中，连续的工具调用会自动折叠为一条折叠条。

- **点击折叠条**：展开或收起工具调用卡片（键盘 `Enter` / `Space` 同样有效）
- **折叠条显示**：最后一个工具调用的一行摘要 + “已折叠 N 个工具调用 · 点击展开”

![展开/收起动画](assets/expand-collapse.gif)

---

## 初次使用·默认行为说明

插件安装后立即生效，你可能首先注意到两个“异常”现象——这都是默认设置所致，可按需调整。

### ❓ 思考内容怎么消失了？

**原因**：默认「思考显示」为「自动跟随官方折叠」——官方未收起整块过程时，已完成的思考默认隐藏以节省空间。

**改回**：`设置 → 插件 → 工具折叠` → 「思考显示」选「始终保留」。

### ❓ 工具调用为什么被切成了两段？

**原因**：默认开启「思考分隔调用组」（`splitThink: true`），插件把思考视为逻辑分界线，将前后的工具调用各自独立折叠。

**改回**：`设置 → 插件 → 工具折叠` → 关闭「思考分隔调用组」。

> 进行中的思考不受任何开关影响，始终保持可见，完成后再按规则处理。

---

## 功能特性

### 核心折叠行为

- **连续工具调用自动折叠**：相邻工具调用整段收起，仅显示最后一个调用的摘要行，并标注折叠数量
- **思考分隔调用组（默认开启）**：已完成的思考会将前后两组工具调用**隔开、各自独立折叠**，不会跨思考合并
- **思考显示（三档）**：默认「自动跟随官方折叠」——官方收起整块过程时保留思考，其余时候隐藏；也可切「始终保留」（分隔模式下显示在两条折叠条之间，合并模式下展开时插回调用之间）或「始终隐藏」
- **进行中的思考独立显示**：流式思考始终保持可见，完成后按上述规则处理

### 动画与体验

- **弹性瀑布动画**：展开时卡片逐张落下（带 spring 回弹），收起时逐张上行且高度同步收缩，下方内容连续上移、无跳变
- **贴底不顶出**：靠近底部展开时，折叠条视口位置固定，不会因自动滚动被顶出屏幕
- **尊重系统偏好**：系统开启「减少动态效果」时，动画自动关闭

### 性能与资源

- **接近零性能占用**：无页面级观察器，流式期间引擎零工作，标签页隐藏时全部暂停（空闲开销约 0.03% 单核）
- **实时性能统计**（可选）：在设置卡片内显示插件各环节耗时，便于验证开销

---

## 设置说明

设置入口：**设置 → 插件 → 工具折叠**（卡片外观与内置插件一致，跟随深浅主题）。

![设置卡片](assets/settings.png)

### 设置项

| 设置项 | 说明 |
| --- | --- |
| **展开动画时长** | 单张卡片的展开/收起动画时长（0–1000ms，默认 240ms；设为 0 为瞬时切换） |
| **思考显示** | 已完成思考的显示方式：自动跟随官方折叠（默认）/ 始终保留 / 始终隐藏 |
| **思考分隔调用组** | 开启（默认）：已完成的思考把前后两组工具调用隔开、各自独立折叠；关闭：思考并入所在工具组一起折叠 |
| **性能统计** | 在卡片内实时显示插件自身耗时（观察回调/引擎刷新/合并重算/安全重扫/摘要克隆的累计次数与耗时，以及被零开销短路忽略的流式批次） |

---

### 存储位置

插件设置会自动持久化，优先级如下：

- **优先（已安装模式）**：由 DSH **设置服务**写入 `~/.dsh/settings.yaml`（命名空间 `toolfold`），随主机走，换浏览器/设备不丢失。手工编辑示例：

  ```yaml
  toolfold:
    durMs: 240        # 展开动画时长 0–2000ms
    thinkMode: auto   # 已完成思考的显示方式：auto 自动跟随官方折叠 / keep 始终保留 / hide 始终隐藏
    splitThink: true  # 是否让已完成的思考隔开前后两组工具调用
    stats: false      # 是否开启性能统计
  ```

- **降级（无设置服务时）**：退化为浏览器 `localStorage`（键 `dsh-toolfold.settings.v1`），仅保存在当前浏览器。旧版键 `dsh-codex-collapse.settings.v1` 会在首次加载时自动迁移。

设置卡片底部会显示当前使用的存储位置（“设置保存在 DSH 主机配置”或“仅保存在本浏览器”）。

---

## 性能

- **实测数据（真实 GUI 页面，空闲窗口 8s）**：引擎总耗时约 1.6–2.8ms（≈0.3ms/s，约 0.03% 单核）；同窗口 5s CPU 采样中引擎函数零样本。
- **流式零工作**：思考/文本 token 流式变更被 O(1) 短路忽略，不触发任何重算（约 0.1–0.4µs/节点）。
- **标签页隐藏 = 零占用**：隐藏时断开全部观察器与定时器，恢复可见时重挂并补一次对账。
- 打开「性能统计」即可在设置卡片内查看各项耗时明细。

---

## 限制与兼容性

- **基于 DOM 标记**：折叠依赖产品稳定的渲染标记；若标记变动，最坏情况是折叠停止生效，但不会破坏聊天。
- **分隔规则**：
  - 进行中的思考与 AI 文字输出会隔开工具调用
  - 已完成的思考默认也隔开（「思考分隔调用组」开启时）；关闭后已完成的思考并入所在工具组一起折叠
- **状态记忆**：展开状态按会话流 + 节点 key 记忆；会话重开且 key 相同时会恢复展开状态。
- **浏览器要求**：需要支持 `MutationObserver` 与 `requestAnimationFrame`；不支持时退化为“初始渲染折叠一次”。
- **设置存储**：以 DSH 主机配置（`~/.dsh/settings.yaml`）为准；仅当主机桥不可达时才退化为 `localStorage`（换浏览器/设备需重新设置）。

---

> 本项目完全由 dsh + deepseek v4 flash(max) 完成。