dsh-toolfold 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -1,6 +1,44 @@
 # Changelog
 
-所有显著变更将记录于此。格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+所有显著变更将记录于此。版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+
+## [0.1.9] - 2026-09-05
+
+> ⚠️ **版本支持**：本节改动将随 `0.1.9` 发布；自 `0.1.9` 起，本插件仅支持 DSH `>= 0.1.2-rc.1` 且 `< 0.1.3`（安装节有同样提示）。
+
+### 缺陷修复
+- **折叠条行距对齐官方**：`.ccxBar` 去掉上下 `3px` 透明内边距（`padding:0`）。条是无边框无背景元素，透明 padding 会被读成行间白边——实测每侧多出 3px（条↔行 30px、条↔条 33px，而官方行↔行字墨边距 27px = 流 `margin-top:16px` + 24px 行盒内字墨各 ~5.5px）。官方行本身零内边距，去掉后折叠条回到同一节奏。
+- **思考行复活**：答案流进曾被清空隐藏的思考行时自动恢复可见，不再误判为空行。
+- **关引擎保留卡片样式**：引擎规则与卡片 chrome 拆成两个 style 标签，停用折叠不再剥掉卡片外观。
+- **压掉 16px 空带**：隐藏思考的 wrapper 一并折叠，回答上方不再留空。
+
+### 功能变更
+- **思考显示三档下拉**（自动跟随官方折叠 / 始终保留 / 始终隐藏，默认自动）：原来自动开着时保留是个摆设，现在没有无效组合；老配置自动沿用，可回滚。设置卡与 README 已同步。
+- **总开关**：一键停用/恢复全部折叠（关闭后聊天回到产品默认显示，卡片常驻随时可重开）。
+- **跟随官方 Compact 折叠**：官方收起整块过程时思考自动保留可见（即下拉的默认档）。
+- **版本不匹配警告**：运行的 DSH 超出支持范围时，设置卡显示 ⚠ 图标（hover 看详情）并打一条一次性 console 警告。
+- **适配 DSH 0.1.2**：`settingsNamespace()` helper 被移除，改用裸字符串命名空间；新增 `engines.dsh` 下限，删除 `dsh-settings` peer 依赖。
+
+### 工程变更
+- **浏览器半模块化**：`lib/client.js`（约 2244 行单文件）与字符串手术生成的 `lib/dynamic-body.js` 重构为 `src/client/` 下的模块源（`settings` / `bridge` / `styles` / `engine` / `card` / `react-env` / `index`），由 tsdown 构建（`tsdown.config.mjs`，与 host 半共三个 entry）：
+  - `lib/client.js(.map)` —— 安装通道 loader 产物（`window.__ModuleLoader__.load`，经 `exports["./client"]` 加载），行为与旧文件一致；
+  - `lib/dynamic-body.js(.map)` —— 动态通道 body（同一模块图去掉 loader 包装），供动态插件会话与 `tools/live-probe.mjs` 使用；
+  - React 不再静态导入：构建 wrapper 将通道提供的 React 种入 `globalThis.__dshToolfoldReact`（安装通道 `require('react')` / 动态通道闭包参数 `React`），无 React 的无头环境仅跳过设置卡片注册。
+- **构建期产物**（删除旧生成器 `lib/build-dynamic.cjs`）：`lib/client.js` / `lib/dynamic-body.js`（及 `.map`）已 gitignore，由 `prepare: pnpm build`（tsdown）重建——`pnpm publish` 与 git-hosted 安装都会先跑 prepare 再打包，`files` 白名单只含构建产物（`lib/index.js`、`lib/client.js`，不含 src / map）。`package.json` 增加 `prepare` / `build` / `build:watch` 脚本与 `tsdown` devDependency。改动流程：只改 `src/` → `pnpm build` → 验证。
+- **host 半搬家**：`lib/index.js` → `src/host/index.js`（与 `src/client/` 对称；ESM，无需 scoped package.json），由 tsdown 第三个 entry（`platform: 'node'`，`schemastery` 保持 external）构建回 `lib/index.js`——`main` / `exports["."]` / `files` 指向不变。至此 `lib/` 下 100% 生成物，`.gitignore` 收成一行 `lib/`（源码层/产物层不再混放）。
+- **工具去本机硬编码**：`jsdom`（29.1.1）与 `playwright`（1.61.1）收为 devDependencies，`tools/engine-smoke.mjs` / `tools/live-probe.mjs` 改按包名解析；live-probe 的 Chrome 路径改为 `CHROME_PATH` 环境变量优先，否则按平台取第一个存在的默认位置。`pnpm install` 后 `test:engine` / `probe:live` 开箱即用。
+- **新增 `pnpm-lock.yaml`**：安装可重复。
+- **发布管线**：Publish 前加 `pnpm install`；dry-run 校验 + `--provenance` OIDC 可信发布；发布条件收窄为仅 release 触发（取消手动发布）；`engines.dsh` 上限收窄到 `<0.1.3`。
+
+## [0.1.8] - 2026-08-28
+
+### Fixed
+- 修复运行时收起"先动一下再突然收起"：当模型产生大量工具调用、且它们是最新信息时，run 在收起动画期间仍在增长。旧实现（自 0.1.3 起）假定行集合固定：折叠条点击闭包持有的是创建时的旧 run 快照，动画只覆盖原始行，随后按旧行数计时的完成定时器把整个增长后的 run 一次性合并，新流入的行瞬间消失。现点击改为操作当前 run（`bar._ccxRun`）而非创建时快照；`syncBars` 将动画期间新增的行折入同一瀑布（`extendCollapse`：rise 类 + 高度收缩 + 各自 stagger）并重排完成定时器（`armCollapseFinish`），最后一行动画结束才应用合并。（`lib/client.js`, `lib/dynamic-body.js`）
+
+### Changed
+- npm 发布工作流增加 OIDC 权限（`id-token: write`、`contents: read`），发布改用 OIDC 身份认证（移除 `NODE_AUTH_TOKEN` 环境变量），并禁用 `package-manager-cache`。
+- `package.json` 增加 `repository` 字段指向 GitHub 仓库。
+- 重构 README：重组章节（安装、快速开始、默认行为、功能、设置、性能、限制），新增"默认行为 – 首次使用"说明（为什么思考会消失、为什么调用默认分组，以及快速修复指引），补充安装方法与徽章，并同步翻译为 `README.en.md`。
 
 ## [0.1.7] - 2026-08-26
 
@@ -54,6 +92,8 @@
 - 首个可用版本：连续 `tool-call` 折叠为最后一条的单行摘要 + “已折叠 N 个工具调用”，支持 `durMs / keepThink / splitThink / stats` 四项设置（DSH `settings` 服务 → `~/.dsh/settings.yaml`，回退到 Host 路由与 `localStorage`）与瀑布动画。
 - `toolfold` 远端包与一键安装、设置双半通信（Host `GET/POST /api/dsh-toolfold/settings` + Client 桥）。
 
+[0.1.9]: https://github.com/Minecraftbe/dsh-toolfold/compare/v0.1.8...v0.1.9
+[0.1.8]: https://github.com/Minecraftbe/dsh-toolfold/compare/v0.1.7...v0.1.8
 [0.1.7]: https://github.com/Minecraftbe/dsh-toolfold/compare/v0.1.6...v0.1.7
 [0.1.6]: https://github.com/Minecraftbe/dsh-toolfold/compare/v0.1.5...v0.1.6
 [0.1.5]: https://github.com/Minecraftbe/dsh-toolfold/compare/v0.1.4...v0.1.5

package/README.en.md

@@ -1,136 +1,176 @@
 # dsh-toolfold · Tool Call Folding
 
-> A DSH Web GUI plugin delivering a **Codex-like folding experience**: runs of consecutive
-> **tool calls** fold into a single compact bar showing a one-line summary of the **last call** —
-> click to expand/collapse. It replaces no built-in renderer, and uninstalling restores the UI
-> completely.
-
-![Folding demo](assets/demo-fold.gif)
-<!-- 🖼️ IMAGE SLOT: assets/demo-fold.gif — record 6–10s: a run of tool calls auto-folds into one bar → click to expand (cards waterfall down) → click to collapse (cards rise, heights shrink), 16:9, ≤2MB -->
-
-## Highlights
-
-- **Runs of tool calls fold into one bar**: consecutive tool calls collapse into a single bar
-  showing the **last call's** one-line summary, labelled "已折叠 N 个工具调用 · 点击展开"
-  (N folded calls · click to expand);
-- **Thinking separates call groups (default on)**: settled think blocks SPLIT the calls around
-  them into independent bars — calls before and after a completed think never merge into one bar;
-  turn it off to restore the original fold, where thinking folds WITH the surrounding tool group;
-- **Thinking hidden by default, keepable**: settled think blocks are hidden outright by default;
-  with "保留思考" enabled they never disappear — shown between the folded bars in split mode, or
-  **re-inserted in their original order** between the calls on expand in merge mode;
-- **In-progress thinking stays visible**: streaming think blocks render as their own row until
-  they complete, then follow the "split thinking" setting;
-- **Spring waterfall animations**: cards cascade down on expand (spring overshoot) and rise with a
-  synchronized height shrink on collapse — content below follows continuously, no end snap;
-  disabled automatically under `prefers-reduced-motion`;
-- **Bottom-pinned expand**: expanding near the bottom pins the bar's viewport position, so the
-  chat's auto-scroll never shoves it off the top of the screen;
-- **Near-zero performance cost**: no page-wide observer, zero work while content streams, and
-  everything pauses when the tab is hidden — measured ≈0.03% of one core while idle
-  (see [Performance](#performance)).
-
-![Expand / collapse animation](assets/expand-collapse.gif)
-<!-- 🖼️ IMAGE SLOT: assets/expand-collapse.gif — close-up of one 3–4 call run expanding (waterfall + label slide) and collapsing (rise + height shrink), square or 4:3, ≤2MB -->
+[![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
+
+English | [中文](README.md)
+
+> A DSH Web GUI plugin that provides a **simple tool call collapsing**: consecutive **tool calls** are collapsed into a single compact bar showing only a one‑line summary of the last call. Click to expand/collapse.  
+> It does not replace any built‑in renderer, and uninstallation restores the UI completely.
+
+![Demo folding effect](assets/demo-fold.gif)
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Default Behaviour – First Use](#default-behaviour--first-use)
+- [Features](#features)
+- [Settings](#settings)
+  - [Options](#options)
+  - [Storage Location](#storage-location)
+- [Performance](#performance)
+- [Limitations & Compatibility](#limitations--compatibility)
+
+---
 
 ## Installation
 
-### One-line GitHub install
+### Recommended (via npm)
 
 ```sh
-dsh plugin --profile web add github:Minecraftbe/dsh-toolfold
+dsh plugin --profile web add dsh-toolfold
 ```
 
-### Install from source
+### Alternative Methods
 
 ```sh
+# From GitHub
+dsh plugin --profile web add github:Minecraftbe/dsh-toolfold
+
+# From source
 git clone https://github.com/Minecraftbe/dsh-toolfold.git
 dsh plugin --profile web add ./dsh-toolfold
 ```
 
-After installing, **restart dsh and refresh the browser** to activate (bundle layers are composed
-at boot). Verify the plugin reached the final config with:
+After installation, **restart dsh and refresh your browser** – the plugin will be active. You can verify that it is included in the final bundle with:
 
 ```sh
 dsh --profile web --dump-config
 ```
 
-> If an earlier version was mounted manually with a `toolfold` row in `cordis.patch.yml`,
-> remove that row before switching to this channel to avoid double-mounting.
-
-### Uninstall
+### Uninstallation
 
 ```sh
 dsh plugin --profile web remove dsh-toolfold
 ```
 
-After a restart the UI is completely restored.
+After restart, the interface returns to its original state.
+
+> ⚠️ **Version support**: starting from `0.1.9`, this plugin only supports DSH `>= 0.1.2-rc.1` and `< 0.1.3`. On DSH versions outside this range, the settings card shows a version-mismatch warning and folding may not work correctly.
+
+---
+
+## Quick Start
+
+Once installed, consecutive tool calls are automatically folded into a single bar in any DSH conversation.
+
+- **Click the fold bar** to expand or collapse the tool‑call cards (keyboard `Enter` / `Space` also work)
+- **The bar shows**: a one‑line summary of the last call plus the label “N tool calls folded · click to expand”
+
+![Expand/collapse animation](assets/expand-collapse.gif)
+
+---
+
+## Default Behaviour – First Use
+
+The plugin works immediately after installation, but you might notice two things that seem “unexpected” at first. Both are intentional defaults and can be changed easily.
+
+### ❓ Why did my thinking content disappear?
+
+**Reason**: “Thinking display” defaults to “Auto-follow official fold” — completed thinking is hidden unless the official Compact view folds the whole process block.
 
-## Usage & Settings
+**How to restore**: go to `Settings → Plugins → Tool Fold` and set **“Thinking display”** to **“Always keep”**.
 
-Settings: **Settings → Plugins → 工具折叠** (the card matches the built-in plugin cards and follows
-the light/dark theme).
+### ❓ Why are my tool calls split into two separate fold bars?
+
+**Reason**: “Split thinking across call groups” is on by default (`splitThink: true`). The plugin treats a completed thinking block as a logical separator, folding calls before and after it independently.
+
+**How to merge them**: go to `Settings → Plugins → Tool Fold` and turn off **“Split thinking across call groups”**.
+
+> Ongoing (streaming) thinking is always visible regardless of these settings, and will only be processed according to the rules once it finishes.
+
+---
+
+## Features
+
+### Core Folding Behaviour
+
+- **Automatic folding of consecutive tool calls** – adjacent tool calls are collapsed into one bar, showing only the last call’s summary line and the number of folded items.
+- **Thinking splits call groups (enabled by default)** – a completed thinking block separates the tool calls before and after it into two independent fold bars; they are never merged across a thinking block.
+- **Thinking display (three modes)** – “Auto-follow official fold” by default: thinking is kept when the official view folds the whole process block, hidden otherwise; “Always keep” shows it between fold bars (split mode) or interpolated back on expansion; “Always hide” never shows completed thinking.
+- **Ongoing thinking always visible** – streaming thinking remains visible until it finishes, then follows the above rules.
+
+### Animation & Experience
+
+- **Spring‑loaded waterfall animation** – cards drop one by one on expand (with spring bounce), and on collapse they rise while heights shrink synchronously, so content below moves continuously without jumping.
+- **Sticks to the bottom without pushing out** – when expanding near the bottom, the fold bar’s viewport position is pinned so that automatic scrolling does not push it off screen.
+- **Respects system preferences** – if the system has “Reduce motion” enabled, animations are automatically disabled.
+
+### Performance & Resource Usage
+
+- **Near‑zero performance impact** – no page‑wide observers, zero engine work during streaming, and all activity is paused when the tab is hidden. Measured idle overhead is about 0.03% of a single CPU core.
+- **Optional real‑time stats** – enable “Performance stats” in the settings card to see per‑step timings and verify overhead.
+
+---
+
+## Settings
+
+Settings are found at: **Settings → Plugins → Tool Fold** (the card looks like other built‑in plugin cards and follows the light/dark theme).
 
 ![Settings card](assets/settings.png)
-<!-- 🖼️ IMAGE SLOT: assets/settings.png — screenshot of the expanded "工具折叠" card in Settings → Plugins (duration slider + keep-think toggle + stats toggle + storage-location hint), light theme, PNG/WebP ≤1MB -->
 
-| Setting | Description |
+### Options
+
+| Option | Description |
 | --- | --- |
-| **展开动画时长** (expand duration) | Per-card duration of the expand/collapse waterfall, 0–1000ms, default 240ms; 0 = instant |
-| **保留思考** (keep thinking) | Settled thinking is hidden by default; on: it never disappears — shown between the folded bars in split mode, or re-inserted in its original order between the calls on expand in merge mode |
-| **思考分隔调用组** (split call groups) | On (default): settled thinking splits the calls around it into independent bars; Off: thinking folds with the surrounding tool group (legacy behavior) |
-| **性能统计** (performance stats) | Shows the plugin's own live cost in the card (cumulative counts and ms/s for observer callbacks / engine refreshes / merge passes / safety rescans / summary clones, plus the streaming batches ignored by the zero-cost short-circuit) |
+| **Expand animation duration** | Duration of the expand/collapse animation per card (0–1000 ms, default 240 ms; 0 = instant) |
+| **Thinking display** | How completed thinking is shown: auto-follow official fold (default) / always keep / always hide |
+| **Split thinking across call groups** | Enabled by default: a completed thinking block separates tool calls before and after it into independent fold bars. Disabled: thinking is folded together with the surrounding call group (legacy behaviour) |
+| **Performance stats** | Show real‑time plugin timing in the card (cumulative count and ms/s for observation callbacks, engine refresh, merge recalculation, safe rescan, summary cloning, plus the number of streaming batches short‑circuited with zero overhead) |
+
+---
 
-Interactions: click the bar to expand/collapse; `Enter` or `Space` works too.
+### Storage Location
 
-### Where settings live
+Plugin settings are persisted automatically, with the following priority:
 
-- **Installed (bundle) mode**: the DSH **settings service** persists them to
-  `~/.dsh/settings.yaml` (namespace `toolfold`) — the same document the product and other
-  plugins use, host-side, so they survive browser/device changes. The card footer shows
-  "设置保存在 DSH 主机配置". The file is editable directly:
+- **Primary (installed/bundle mode)** – stored via the DSH **settings service** in `~/.dsh/settings.yaml` (namespace `toolfold`). They follow the dsh host, so they persist across browsers/devices. You can also edit the file manually:
 
   ```yaml
   toolfold:
-    durMs: 240        # expand animation duration, 0–2000ms
-    keepThink: false  # keep settled thinking visible (between bars / on expand)
-    splitThink: true  # settled thinking splits call groups into independent bars (default true)
-    stats: false      # performance meter
+    durMs: 240        # expand animation duration 0–2000 ms
+    thinkMode: auto   # completed-thinking display: auto-follow official fold / keep always / hide always
+    splitThink: true  # whether to split call groups by thinking
+    stats: false      # whether to enable performance stats
   ```
 
-- **When no DSH settings service is detected** (remote browsers and other setups without the DSH
-  settings bridge): degrades to browser `localStorage` (key `dsh-toolfold.settings.v1`) and the
-  card says "仅保存在本浏览器"; the legacy key `dsh-codex-collapse.settings.v1` migrates
-  automatically on first load.
+- **Fallback (when settings service is unavailable)** – falls back to browser `localStorage` (key `dsh-toolfold.settings.v1`), so settings are only kept in that browser. The old key `dsh-codex-collapse.settings.v1` is automatically migrated on first load.
 
-![Keep-thinking comparison](assets/keep-think.gif)
-<!-- 🖼️ IMAGE SLOT: assets/keep-think.gif — same run expanded twice, "keep thinking" off vs on, showing the think block hidden vs re-inserted in order, ≤2MB -->
+The settings card shows the current storage method (“Settings saved in DSH host config” or “Saved only in this browser”).
+
+---
 
 ## Performance
 
-- **Measured on the live GUI (8s idle window)**: engine total ≈1.6–2.8ms (≈0.3ms/s, ≈0.03% of one
-  core); a 5s CPU sample in the same window shows **zero samples from the engine** — the page's long
-  tasks (141–686ms) come from page load, product rendering, and other plugins;
-- **Zero work while streaming**: text/think token mutations are short-circuited in O(1) and never
-  trigger a recompute (≈0.1–0.4µs per node);
-- **Hidden tab = literally zero**: all observers and timers disconnect on hide and re-attach with a
-  reconciliation pass on return;
-- Turn on "性能统计" to watch every cost item live inside the settings card.
-
-## Notes & Limitations
-
-- Folding works on the rendered DOM and depends on stable product markers; if the product markup
-  changes, the worst case is that folding stops applying — the chat itself is never harmed;
-- **In-progress thinking** and **AI text output** separate runs; **settled thinking** also
-  separates runs by default ("思考分隔调用组" on) — with it off, settled thinking folds with the
-  surrounding tool group instead;
-- Expanded state is remembered per session flow + node key; reopening a session with the same keys
-  restores it;
-- Settings are owned by the DSH host config (`~/.dsh/settings.yaml`); browser `localStorage` is
-  only the fallback when the host bridge is unreachable (then each browser needs its own setup);
-- Requires `MutationObserver` and `requestAnimationFrame`; without them it degrades to "fold once on
-  initial render".
+- **Measured on a real GUI page (8 s idle window)** – total engine time ~1.6–2.8 ms (~0.3 ms/s, ~0.03% single‑core); during a 5‑s CPU profile, engine functions appeared zero times.
+- **Zero work during streaming** – streaming thinking/text tokens are short‑circuited with O(1) checks and do not trigger any recalculation (~0.1–0.4 µs per node).
+- **Hidden tab = literally zero** – all observers and timers are disconnected when the tab is hidden; they are re‑attached and a single reconciliation run is performed when the tab becomes visible again.
+- Enable **“Performance stats”** in the settings card to see detailed timings for every plugin operation.
+
+---
+
+## Limitations & Compatibility
+
+- **DOM‑based** – folding relies on stable product DOM markers. If markers change, the worst case is that folding stops working – it will not break the chat.
+- **Splitting rules**:
+  - Ongoing thinking and plain text output separate tool call groups.
+  - Completed thinking also separates groups by default (when “Split thinking across call groups” is on); when off, thinking is folded together with its surrounding call group.
+- **State memory** – expand/collapse state is remembered per conversation flow and node key; re‑opening a conversation with the same key restores the state.
+- **Browser requirements** – needs `MutationObserver` and `requestAnimationFrame`. If unsupported, it falls back to “fold once on initial render”.
+- **Settings storage** – uses the DSH host config (`~/.dsh/settings.yaml`) when available; only falls back to `localStorage` when the host bridge is unreachable (in which case settings are browser‑local only).
 
 ---
 
-This project was entirely completed by dsh + deepseek v4 flash(max).
+> This project is entirely built with dsh + deepseek v4 flash(max).

package/README.md

@@ -1,56 +1,54 @@
 # dsh-toolfold · 工具调用折叠
 
-> DSH Web GUI 插件，提供**类 Codex 的工具折叠体验**：把连续的**工具调用**折叠成一条简洁的
-> 折叠条，只展示最后一个调用的一行摘要，点击即可展开/收起。
-> 不替换任何内置渲染器，卸载后界面完全恢复原样。
+[![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)
-<!-- 🖼️ 图片位：assets/demo-fold.gif —— 建议录制 6~10s：多个工具调用自动折成一条 → 点击展开（卡片瀑布落下）→ 点击收起（卡片上行、高度收缩），16:9，≤2MB -->
-
-## 特性一览
-
-- **连续工具调用折叠为一条**：相邻的工具调用整段收起，条内直接显示**最后一个调用**的一行
-  摘要，并标注「已折叠 N 个工具调用 · 点击展开」；
-- **思考分隔调用组（默认开启）**：已完成的思考会把前后两组工具调用**隔开、各自独立折叠**，
-  不会把思考前后的调用合并成一条；关闭后恢复原折叠方式——思考并入所在工具组一起折叠；
-- **思考默认隐藏，可保留**：已完成的思考默认隐藏（不占版面）；开启「保留思考」后思考不再
-  消失——分隔模式下显示在两条折叠条之间，合并模式下展开时按**原顺序插回调用之间**；
-- **进行中的思考独立显示**：流式思考保持原样可见，完成后按「思考分隔」设置处理；
-- **弹性瀑布动画**：展开时卡片自上而下逐张落下（spring 回弹），收起时逐张上行且行高度同步收缩，
-  下方内容连续上移、结尾无跳变；系统开启「减少动态效果」时动画自动关闭；
-- **贴底不顶出**：靠近底部展开时，折叠条视口位置被钉住，不会因聊天自动滚动被顶出屏幕；
-- **接近零性能占用**：无页面级观察器、流式期间引擎零工作、标签页隐藏时全部暂停——
-  实机测量空闲开销约 0.03% 单核（详见[性能](#性能)）。
 
-![展开/收起动画](assets/expand-collapse.gif)
-<!-- 🖼️ 图片位：assets/expand-collapse.gif —— 建议：单段 3~4 个调用的展开（瀑布落下 + 标签滑左）与收起（上行 + 高度收缩）特写，正方形或 4:3，≤2MB -->
+---
 
-## 安装
+## 目录
 
+- [安装](#安装)
+- [快速上手](#快速上手)
+- [初次使用·默认行为说明](#初次使用默认行为说明)
+- [功能特性](#功能特性)
+- [设置说明](#设置说明)
+  - [设置项](#设置项)
+  - [存储位置](#存储位置)
+- [性能](#性能)
+- [限制与兼容性](#限制与兼容性)
 
+---
 
-### GitHub 一行安装
+## 安装
+
+### 推荐（通过 npm）
 
 ```sh
-dsh plugin --profile web add github:Minecraftbe/dsh-toolfold
+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 并刷新浏览器**即可生效（bundle 层在启动时合成）。可用以下命令确认已进入
-最终配置：
+安装后**重启 dsh 并刷新浏览器**即可生效。可通过以下命令确认配置已生效：
 
 ```sh
 dsh --profile web --dump-config
 ```
 
-> 早期版本若曾在 `cordis.patch.yml` 手工加过 `toolfold` 行，先删除该行再切换，避免双挂载。
-
 ### 卸载
 
 ```sh
@@ -59,62 +57,119 @@ dsh plugin --profile web remove dsh-toolfold
 
 重启后界面完全恢复原样。
 
-## 使用与设置
+> ⚠️ **版本支持**：自 `0.1.9` 起，本插件仅支持 DSH `>= 0.1.2-rc.1` 且 `< 0.1.3`。在此范围之外的 DSH 上，设置卡片会显示版本不匹配警告，折叠功能可能无法正常工作。
+
+---
+
+## 快速上手
+
+安装完成后，在 DSH 对话界面中，连续的工具调用会自动折叠为一条折叠条。
+
+- **点击折叠条**：展开或收起工具调用卡片（键盘 `Enter` / `Space` 同样有效）
+- **折叠条显示**：最后一个工具调用的一行摘要 + “已折叠 N 个工具调用 · 点击展开”
+
+![展开/收起动画](assets/expand-collapse.gif)
+
+---
+
+## 初次使用·默认行为说明
+
+插件安装后立即生效，你可能首先注意到两个“异常”现象——这都是默认设置所致，可按需调整。
+
+### ❓ 思考内容怎么消失了？
+
+**原因**：默认「思考显示」为「自动跟随官方折叠」——官方未收起整块过程时，已完成的思考默认隐藏以节省空间。
 
-设置入口：**设置 → 插件 → 工具折叠**（卡片外观与内置插件卡片一致，跟随深浅主题）。
+**改回**：`设置 → 插件 → 工具折叠` → 「思考显示」选「始终保留」。
+
+### ❓ 工具调用为什么被切成了两段？
+
+**原因**：默认开启「思考分隔调用组」（`splitThink: true`），插件把思考视为逻辑分界线，将前后的工具调用各自独立折叠。
+
+**改回**：`设置 → 插件 → 工具折叠` → 关闭「思考分隔调用组」。
+
+> 进行中的思考不受任何开关影响，始终保持可见，完成后再按规则处理。
+
+---
+
+## 功能特性
+
+### 核心折叠行为
+
+- **连续工具调用自动折叠**：相邻工具调用整段收起，仅显示最后一个调用的摘要行，并标注折叠数量
+- **思考分隔调用组（默认开启）**：已完成的思考会将前后两组工具调用**隔开、各自独立折叠**，不会跨思考合并
+- **思考显示（三档）**：默认「自动跟随官方折叠」——官方收起整块过程时保留思考，其余时候隐藏；也可切「始终保留」（分隔模式下显示在两条折叠条之间，合并模式下展开时插回调用之间）或「始终隐藏」
+- **进行中的思考独立显示**：流式思考始终保持可见，完成后按上述规则处理
+
+### 动画与体验
+
+- **弹性瀑布动画**：展开时卡片逐张落下（带 spring 回弹），收起时逐张上行且高度同步收缩，下方内容连续上移、无跳变
+- **贴底不顶出**：靠近底部展开时，折叠条视口位置固定，不会因自动滚动被顶出屏幕
+- **尊重系统偏好**：系统开启「减少动态效果」时，动画自动关闭
+
+### 性能与资源
+
+- **接近零性能占用**：无页面级观察器，流式期间引擎零工作，标签页隐藏时全部暂停（空闲开销约 0.03% 单核）
+- **实时性能统计**（可选）：在设置卡片内显示插件各环节耗时，便于验证开销
+
+---
+
+## 设置说明
+
+设置入口：**设置 → 插件 → 工具折叠**（卡片外观与内置插件一致，跟随深浅主题）。
 
 ![设置卡片](assets/settings.png)
-<!-- 🖼️ 图片位：assets/settings.png —— 截图建议：设置 → 插件 页内「工具折叠」卡片展开态（时长滑块 + 保留思考开关 + 性能统计开关 + 存储位置提示），浅色主题，PNG/WebP ≤1MB -->
+
+### 设置项
 
 | 设置项 | 说明 |
 | --- | --- |
-| **展开动画时长** | 展开/收起瀑布动画的单卡时长，0–1000ms，默认 240ms；0 为瞬时切换 |
-| **保留思考** | 已完成的思考默认隐藏；开启后思考保留——分隔模式下显示在两条折叠条之间，合并模式下展开时按原顺序插回调用之间 |
-| **思考分隔调用组** | 开启（默认）：已完成的思考把前后两组工具调用隔开、各自独立折叠；关闭：思考并入所在工具组一起折叠（旧行为） |
-| **性能统计** | 在卡片内实时显示插件自身耗时（观察回调/引擎刷新/合并重算/安全重扫/摘要克隆的累计次数与 ms/s，以及被零开销短路忽略的流式批次），用于验证插件开销 |
+| **展开动画时长** | 单张卡片的展开/收起动画时长（0–1000ms，默认 240ms；设为 0 为瞬时切换） |
+| **思考显示** | 已完成思考的显示方式：自动跟随官方折叠（默认）/ 始终保留 / 始终隐藏 |
+| **思考分隔调用组** | 开启（默认）：已完成的思考把前后两组工具调用隔开、各自独立折叠；关闭：思考并入所在工具组一起折叠 |
+| **性能统计** | 在卡片内实时显示插件自身耗时（观察回调/引擎刷新/合并重算/安全重扫/摘要克隆的累计次数与耗时，以及被零开销短路忽略的流式批次） |
 
-交互方式：点击折叠条展开/收起；键盘 `Enter` 或 `Space` 同样有效。
+---
+
+### 存储位置
 
-### 设置存到哪里
+插件设置会自动持久化，优先级如下：
 
-- **已安装（bundle）模式**：设置由 DSH **设置服务**持久化到
-  `~/.dsh/settings.yaml`（命名空间 `toolfold`），与产品和其他插件的设置在同一个文档里，
-  随 dsh 主机走，换浏览器/设备不丢失；卡片底部会显示「设置保存在 DSH 主机配置」。
-  也可以直接手工编辑该文件：
+- **优先（已安装模式）**：由 DSH **设置服务**写入 `~/.dsh/settings.yaml`（命名空间 `toolfold`），随主机走，换浏览器/设备不丢失。手工编辑示例：
 
   ```yaml
   toolfold:
     durMs: 240        # 展开动画时长 0–2000ms
-    keepThink: false  # 是否保留已完成的思考（显示在折叠条之间 / 展开时插回）
-    splitThink: true  # 是否让已完成的思考隔开前后两组工具调用（默认 true）
+    thinkMode: auto   # 已完成思考的显示方式：auto 自动跟随官方折叠 / keep 始终保留 / hide 始终隐藏
+    splitThink: true  # 是否让已完成的思考隔开前后两组工具调用
     stats: false      # 是否开启性能统计
   ```
 
-- **未检测到 DSH 设置服务时**（远程浏览器等未接入 DSH 设置服务的场景）：降级为浏览器
-  `localStorage`（键 `dsh-toolfold.settings.v1`），卡片会显示「仅保存在本浏览器」；
-  旧版键 `dsh-codex-collapse.settings.v1` 首次加载自动迁移。
+- **降级（无设置服务时）**：退化为浏览器 `localStorage`（键 `dsh-toolfold.settings.v1`），仅保存在当前浏览器。旧版键 `dsh-codex-collapse.settings.v1` 会在首次加载时自动迁移。
+
+设置卡片底部会显示当前使用的存储位置（“设置保存在 DSH 主机配置”或“仅保存在本浏览器”）。
 
-![保留思考对比](assets/keep-think.gif)
-<!-- 🖼️ 图片位：assets/keep-think.gif —— 建议：同一段调用分别以「保留思考 关 / 开」各演示一次展开，展示思考不显示 / 按原顺序插回，≤2MB -->
+---
 
 ## 性能
 
-- **实测（真实 GUI 页面，空闲窗口 8s）**：引擎总耗时约 1.6–2.8ms（≈0.3ms/s，约 0.03% 单核）；
-  同窗口 5s CPU 采样中引擎函数零样本，页面长任务（141–686ms）来自页面加载与产品/其他插件渲染；
-- **流式零工作**：思考/文本 token 流式变更被 O(1) 短路直接忽略，不触发任何重算（约 0.1–0.4µs/节点）；
-- **标签页隐藏 = 字面零占用**：隐藏时断开全部观察器与定时器，回到可见时重挂并补一次对账；
-- 打开「性能统计」即可在设置卡片内实时查看插件自身的每一项耗时。
+- **实测数据（真实 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 相同时会恢复展开状态；
-- 设置以 DSH 主机配置（`~/.dsh/settings.yaml`）为准；仅当主机桥不可达时才退化为浏览器
-  `localStorage`（此时换浏览器/设备需重新设置）；
-- 需要浏览器支持 `MutationObserver` 与 `requestAnimationFrame`；不支持时退化为「初始渲染折叠一次」。
+- **基于 DOM 标记**：折叠依赖产品稳定的渲染标记；若标记变动，最坏情况是折叠停止生效，但不会破坏聊天。
+- **分隔规则**：
+  - 进行中的思考与 AI 文字输出会隔开工具调用
+  - 已完成的思考默认也隔开（「思考分隔调用组」开启时）；关闭后已完成的思考并入所在工具组一起折叠
+- **状态记忆**：展开状态按会话流 + 节点 key 记忆；会话重开且 key 相同时会恢复展开状态。
+- **浏览器要求**：需要支持 `MutationObserver` 与 `requestAnimationFrame`；不支持时退化为“初始渲染折叠一次”。
+- **设置存储**：以 DSH 主机配置（`~/.dsh/settings.yaml`）为准；仅当主机桥不可达时才退化为 `localStorage`（换浏览器/设备需重新设置）。
 
 ---
 
-本项目完全由 dsh + deepseek v4 flash(max) 完成。
+> 本项目完全由 dsh + deepseek v4 flash(max) 完成。