Minecraftbe/dsh-toolfold

中文 | English

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

---

目录

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

---

安装

推荐（通过 npm）

dsh plugin --profile web add dsh-toolfold

其他方式

# 从 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 并刷新浏览器即可生效。可通过以下命令确认配置已生效：

dsh --profile web --dump-config

卸载

dsh plugin --profile web remove dsh-toolfold

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

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

---

快速上手

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

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

---

初次使用·默认行为说明

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

❓ 思考内容怎么消失了？

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

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

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

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

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

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

---

功能特性

核心折叠行为

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

动画与体验

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

性能与资源

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

---

设置说明

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

设置项

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

---

存储位置

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

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

  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) 完成。