# @trujaycc/dsh-ui-easyfold

[English](README.md) | 中文

dsh Web GUI 的"轻松折叠"插件：两个纯浏览器侧行为，让长内容的展开阅读与折叠更省事。

## 问题

部分折叠组件存在阅读工效问题：当折叠的内容很长时，用户展开内容并向下滚动阅读，折叠按钮会随内容一起滚出屏幕；此时想要收起内容，必须先滚回内容顶部才能点中折叠按钮，阅读位置因此被打断。

![问题示意：展开长内容后，折叠按钮随滚动移出屏幕](screenshots/pic1.png)

![插件效果：展开长内容后，折叠吸顶随时可收起](screenshots/pic1.png)

## 插件处理

本插件从两个行为层面解决上述问题，全部在浏览器侧完成：

- **折叠行吸顶** — 内容展开期间，折叠行吸附在对话滚动区顶部，滚动阅读时始终可见、可点击；整个内容滚出视图后自动解除吸顶，不影响页面布局。
- **折叠滚动回正** — 折叠一个已吸顶的组件（点击、Enter 或空格）时，滚动位置回正到折叠行所在位置——即吸顶行原本占据的位置。视口因此保持在组件节点处，而不是落到节点下方；对仍在视口内的行折叠则原地不动。

## 受影响的 UI 部件

| 部件                    | 状态   |
| ----------------------- | ------ |
| Think（思考过程折叠行） | 已实现 |
| 其他长内容折叠部件      | 待实现 |

## 安装

```sh
pnpm dsh plugin --profile web add @trujaycc/dsh-ui-easyfold
```

重启 `pnpm dsh web`

卸载：

```sh
pnpm dsh plugin --profile web remove @trujaycc/dsh-ui-easyfold
```

## 开发

```sh
pnpm install
pnpm run typecheck
pnpm test
pnpm run build    # 产出 lib/index.js 与 lib/client.js（ModuleLoader 握手格式）
```

客户端 bundle 的 `react` 从 dsh Web loader 的平台模块表解析；本包不声明其他运行时依赖。发布前想先本地验证，可按路径或 tarball 安装：

```sh
pnpm pack
pnpm dsh plugin --profile web add ./trujaycc-dsh-ui-easyfold-0.1.0.tgz
```

## Model Experience

无。纯展示层客户端插件：不提供宿主服务、工具或会话事件，任何内容都不会进入模型请求或会话日志。

#### KV Cache 影响

无。

## Known Limitations and Deferred Work

- **产品 DOM 契约耦合** — 两个行为都通过 dsh Web 聊天 DOM 的稳定属性挂接（`data-conversation-scroll`、`data-variant="think"`、`data-open`、`data-disclosure-row`）。产品标记变更会静默地使它们失效。
- **仅首个滚动区** — 回正逻辑只作用于文档中第一个 `data-conversation-scroll`；并排的会话窗口（子代理视图）只有一个行为所有者。
- **有限的提交等待** — 回正最多等待八个动画帧用于产品 React 提交；超过该窗口的延迟提交会跳过校正（不会损坏滚动，只是不回拉）。