@f-light/dsh-diffstream

Readme

# dsh-diffstream

在 DSH web GUI 的对话流中直接展示代码改动，让你随时清楚 agent 改动了哪些文件、改了什么、执行到了什么位置。

## ✨ 功能

### 1. 工具卡片内嵌行级 diff（流式动画）

每次 `edit` / `write` 工具执行完成后，改动内容直接渲染在对应的工具卡片内部——绿色 `+` 新增行、红色 `−` 删除行，带行号与上下文；diff 以**流式逐行动画**展开（支持 1x / 2x / 立即 速度控制），视觉效果与 assistant 消息的流式输出同步，改动展开到哪一行 = 执行到了什么位置。

![工具卡片内嵌 diff](docs/screenshots/tool-card-diff.png)

### 2. 回合尾部改动汇总

每个已完成的回合尾部追加「📋 本回合改动汇总」卡片：文件级列表（路径、新增/修改/删除状态标签、`+N −M` 增删统计、头部徽标），点击文件行展开该文件的完整行级 diff；同一文件多次编辑自动合并统计。

![回合尾部改动汇总](docs/screenshots/turn-summary.png)

### 3. git 优先、参数回退

- 汇总卡片优先使用**真实 git diff**（含上下文 hunk，经 Host RPC 获取），非 git 项目或 git 命令失败时**静默回退**为工具参数 diff（视觉一致，功能不中断）；
- 大文件（>200 行）自动截断，可点击展开全部；
- diff 卡片**自动滚动**：动画播放期间自动跟随最新行滚动到底部（手动上滚时暂停跟随）；
- 无文件产出的回合自动让位官方 `ProducedFiles` 展示（chain 回退），互不干扰；
- 动画按工具调用 `callId` 去重，历史回合（刷新后）直接完整显示，不重播。

## 📦 安装

本插件以独立 npm 包提供，通过 profile 的 `cordis.patch.yml` 注入，无需修改 dsh 源码。

```bash
# 1. 将包放入 web profile 的 node_modules（或 pnpm link 本地路径）
cd ~/.dsh/profiles/web
pnpm add @f-light/dsh-diffstream
```

```yaml
# 2. 在 ~/.dsh/profiles/web/cordis.patch.yml 追加插件行
- insert:
    - id: diffstream
      name: '@f-light/dsh-diffstream'
```

```bash
# 3. 重启 dsh web 生效
dsh --profile web
```

## 🔧 工作原理

```
浏览器端 (lib/client.js)
├─ tool.call.toolview (key: edit / write)   ← 接管工具卡片，内嵌行级 diff + 流式动画
└─ conversation.chat.turnTail (chain, priority -1)
   └─ 汇总卡片：参数 diff（会话快照提取）→ git hunk（Host RPC 成功时优先）
Host 端 (lib/index.js)
└─ harness.handle('diffstream/git-status')  ← shell 执行 git status/diff，解析结构化 hunks
```

- **diff 引擎**：纯客户端 LCS 行级对比（零依赖、零延迟、不读磁盘），仅使用工具调用参数（`old_string` / `new_string` / `content`）与 git 输出；
- **数据回退矩阵**：

| 场景 | 工具卡片（内嵌） | 回合汇总 |
|---|---|---|
| git 项目 | 参数 diff（实时逐条） | git hunk（含上下文） |
| 非 git 项目 | 参数 diff | 参数累计 diff |
| git 命令失败/超时 | 不受影响 | 回退参数累计 diff |
| 大文件（>200 行） | 截断 + 展开 | 同左 |
| 工具执行失败 | 错误态，无 diff | 不计入汇总 |

## 🛠 开发

```bash
# 动态原型（当前会话）：通过 DSH 的 Cordis 动态插件工具定义并运行
# 固化 bundle 结构：
#   lib/index.js   Host 半（git RPC）
#   lib/client.js  浏览器半（window.__ModuleLoader__.load 格式）
#   docs/screenshots/  功能截图（headless Edge 渲染）
```

## License

MIT