dsh-think-flow

dsh-think-flow · 思维链可视化

在 DSH Web 的右侧栏开一个「思维链」标签页， 把模型的实时思考按 turn → step →（思考原文 + 工具调用） 聚合成能读的结构： 每一步在干嘛、调了什么工具、它在读哪个文件、哪一段正在等外部接口。

---

它解决什么问题

DSH 的主对话界面不显示思维链。 而模型的思考恰恰是最值得看的东西： 它决定得对不对、有没有绕路、卡在哪一步。

但直接把思考流倒出来是没法读的。这是真实会话里量出来的一个 turn：

所以这个面板做了五件事，每一件都对应上面某个数字：

• 按 step 聚合，不逐字渲染。reasoning 每秒几百个事件，逐事件重绘会把面板刷成幻灯片。 宿主侧按 step 折叠 + 120ms 合并推送（sseThrottleMs）。
• 分层折叠。53 步全展开要滚几十屏；把"同一类活动"合并成阶段块。默认只展开最新一轮， 那一轮里只展开当前所在阶段；更早的轮次收成一行，点开才看。 例外：实时看过的那一轮不自动收 —— 生成中收起来会把前面那些组缩成一行标题， 生成完再收又会把读到一半的位置顶掉；要收手动点组头。
• 显式画出「在等工具」。实测两步之间能有 47 秒模型零输出（联网检索中）—— 不画出来，界面在这 47 秒里与卡死无法区分。
• 轮次可回溯。正文只常驻最近 20 轮，更早的走全轮目录按需折回来； 翻到 100 轮之前也不用把它全塞进内存。
• 思考可以变中文。英文 CoT 按段落机翻（官方 translator 服务，Bing/Google 匿名端点）， 翻好一段显示一段；关掉就是原文。见 中文思考（机翻）。

长什么样

本轮结束后补一块**「这一轮想完了」**：多少步、思考多少 Token、调了多少次工具，以及 思考花在哪了（读代码 / 跑命令 / 改文件 / 外部检索 / 问用户的比例）。 分布用同一色相只变深浅，不给每个阶段编一个颜色。

工具失败照宿主的判定显示（isError + error.code）：行里一枚红标， 为什么失败在展开区紧跟它自己那条工具行（上图 ✗ INVALID_ARGS …）。 红只给错误文本，工具名不动 —— 失败的是这次调用，不是这个工具。

上面这些图不是另画的示意图：由 npm run shots 用构建产物里真正的组件渲染、 配宿主主题包里整段抓出来的真 token、headless Chrome 拍下来，宽度就是右侧栏真实的 380px。 数据来自 scripts/preview/demo-data.mjs，是合成的一段会话。

安装

# 从 npm（推荐）
dsh plugin --profile web add @yfwu2020/dsh-think-flow

# 或从 GitHub Release 的 tgz（同一个产物，不走 npm）
dsh plugin --profile web add /path/to/yfwu2020-dsh-think-flow-0.3.3.tgz

# 或从本地目录（开发用：改完不用重装，只重建）
dsh plugin --profile web add link:/path/to/dsh-think-flow

装完在 DSH 里落成三处：

打开方式有两个：会话头部那个折线图标，或者右侧栏标签条上的「思维链」。

⚠️ 装完要重建进程：host 半是新的 bundle，需要重启 dsh web，之后硬刷新浏览器 （Cmd/Ctrl+Shift+R）。此后只改 client 半的改动会被 client-hmr 就地替换，不用刷新。

要求：DSH 运行时 >=0.1.7-rc（见 package.json 的 peerDependencies）。 0.1.7-rc 起 createSystemMessage 去掉了插件署名参数；更旧的运行时上行为不一致。

⚠️ npm 上 @deepseek-ai/* 这些包的 latest 还停在更旧的 0.0.1-rc.x，缺 WebServer 等 API —— 从源码构建时按 package.json 里钉的版本装，别用 latest。

配置项

改 profile 的 cordis.patch.yml 里 id: think-flow 那一行的 config:（覆盖，不要再 insert）：

- id: think-flow
  config:
    maxTurnsPerSession: 20

三条策略要一起看（它们管的是同一块内存）：

turns（正文）        maxTurnsPerSession = 20   ← 常驻
  └ 更早的轮次按需折进来 = 冷轮正文
       ├ coldTtlMs    = 7,200,000   空闲 2 小时收回
       └ maxColdChars = 4,000,000   字符超了从最旧的丢
index（全轮骨架）    maxIndexTurns = 2000      ← 目录读它；正文丢了它还在

时间策略管"不用了就还回来"，但它没有内存上界（两小时里连开几百个老轮次会一直涨）， 字符上限补的正是那个洞 —— 所以两条都建议留着。

清理全是自动的，没有手动入口（要手动只能删文件或重启进程）。除上面那些， 还有两处硬编码上限：trace.attempts 是 128 条 FIFO；订阅者的增量队列由节流窗口清空。 另外卸载插件不会删 ~/.dsh/think-flow/（标题缓存与译文缓存留着，重装即复用）。

中文思考（机翻）

模型的思考原文是英文。面板头部那枚「中文」按钮把它按段落翻成中文。 按钮上永远只有两个字，状态靠亮 / 呼吸区分（点一下依次是 关 → 开 → 实时 → 关， 选择记在浏览器里；鼠标悬停会说明"现在是什么状态、点一下会发生什么"）：

呼吸只用来提示"实时"。系统开了「减少动态效果」时呼吸会停，但实时态仍是实心蓝， 和「开」的淡蓝分得开 —— 状态不依赖动画存在。

• 翻译不花模型调用。走的是官方的 translator 服务（Bing / Google 匿名端点）， 和宿主里那个 @deepseek-ai/dsh-experimental-cot-translation-bundle 是同一个底座。
• 翻好一段显示一段。整段思考不会等翻完才出现：已定型的段落显示译文， 正在流式增长的那一段先显示原文，段落一停就补翻。
• 只翻看得见的字。宿主不主动翻整轮思考 —— 一次 turn 实测 7 万字，全翻是上百次 网络请求；「开」模式下更是只有你点开的那一步会翻。
• 本来就是中文的段落不送翻（避免"中文翻中文"）。
• 原文永远在：切到「关」立刻回到英文原文，会话日志一个字节都没改。

🔒 翻译意味着把段落发给第三方（Bing / Google 的匿名翻译端点）。不想外发就切到 「关」—— 之后面板一个翻译请求都不发，宿主也不会主动翻任何东西。

⚠️ 需要宿主装 @deepseek-ai/dsh-experimental-translator（装 @deepseek-ai/dsh-experimental-cot-translation-bundle 就会带上它）。 没装时开关禁用并给出原因，插件其余功能完全不受影响。

译文缓存两层的上限都是硬的：浏览器内存 3000 段（LRU，页面刷新即清空）、 宿主内存/磁盘 4000 段（maxTranslationEntries，落盘到 ~/.dsh/think-flow/translations.json，约 1MB 量级）。越界按最近使用淘汰； 被淘汰的段落下次显示时重新翻（宿主磁盘里还有的话直接命中，不走网络）。 卸载插件不会删缓存文件。

面板怎么用

几个不显眼但有用的：

• 容量条（每行那根灰条）宽度 = 该步思考 Token 数。谁想得多一眼看得出来，不用印数字。
• 状态字形：✓ 完成 · ▸ 进行中 · ◐ 等工具 · ■ 被中断。
• 派生标题：模型标题的替补。没生成标题时，行里显示的是按工具参数算出来的短标题 （读 client.js、跑构建、改 index.js ×3）—— 所以任何时刻都看得出"这一步机械地做了什么"。 相邻的同类调用会合并成 ×N，杀掉重复又保住"调了几次"。
• 命令自带的英文说明会翻成中文贴在派生标题后面（跑构建 · 跑构建确认没回归）。 说明在 tool/call 那一刻采集 —— 参数会被截断，那是唯一能保住它的时机。
• 底部留白 150px：让最后一个内容还能往上滑一点，不然贴底那行永远被挡着。

会话四态

会话读不到和"还没开始"是两件事，面板分开说（状态随快照下发）：

有实时事件进来时 unreadable 会回到 live，不会一直挂着。

历史回看是怎么做的

事件是实时的、不回放，所以插件加载之前、以及更早的会话，内存里什么都没有。 现在打开面板时先补历史：/trace、/stream、/titles 三条路都会先 hydrate() —— 但只在该会话内存里还没有任何 turn 时做，绝不覆盖实时状态；读盘失败（会话不存在 / 被别的进程锁住）静默降级，实时数据照常返回。

一个关键差别：落盘的是组装结果，不是流帧。实时路径收到的是 reasoning-delta 增量， 历史路径读的是 assistant/message 里组装好的整块 —— 后者覆盖前者。覆盖是刻意的： 同一步重试会有多条 assistant/message，以最终那条为准更正确，顺带把流式缺口也补上了。

过期自愈：本进程不是驱动者时，重折一遍日志

hydrate() 只在内存里空的时候做，可本进程不一定是这个会话的驱动者：换个客户端 接着看（dsh web → 桌面版）、或者上一轮是在另一个进程里被打断的 —— 那之后这个进程 再也收不到任何实时事件，打开面板那一刻折出来的"还在跑"就永远没人更正 （实测：那一轮 19:54 就中断了，21:53 面板还挂着"已等 59'46""，而且刷新页面也好不了）。

所以补一条：看着还在跑 + 这个进程好久没动静就把日志重折一遍，对不上就推一份新快照。 代价用退避兜住（resyncSilenceMs 为基数，15s → 30s → 60s…，封顶 resyncMaxGapMs）， 真的在等一个长工具时，几次之后就是 5 分钟才读一遍日志。 ⚠️ 这里刻意不用"一段沉默期最多折几次就停手"：本进程不是驱动者时沉默期永远不会结束， 硬上限等于过一阵子永久停止自愈（改之前先写成了硬上限，真机立刻踩到）。

并发也收口了：hydrate() 是单飞的（同一会话同一时刻只有一趟）。两个面板同时连上来时， 之前会各自清空重建、后一趟把前一趟的"实时事件排队表"覆盖掉 —— 中间到的轮结束/工具结果 就再也没人补放，内存里那份永远停在"还在跑"。

接口

宿主半注册在 /think-flow/api/* 下（curl -s localhost:3080/think-flow/api/ping 可自检）：

快照刻意只带"当前步"的原文：一个 turn 实测 7 万字，53 步全带原文每次连接要传几 MB。 其余步骤只给 Token 数与状态，展开时走 /step，之后走缓存。

骨架（index[]）里每一轮还带一个 seq：这一轮 turn/start 的事件序号。它只有一个用途 —— 面板里点轮次号时，客户端拿它调宿主的 session.loadThrough(seq)，把主会话的历史一次翻到 这一轮（和宿主自己的「轮次导航」刻度是同一个调用）。所以"跳到某一轮"在大轮号上也点得动， 不必一页一页翻。

它是怎么工作的

┌─ 宿主半  src/index.ts → src/host/* + trace/titles/translate ─────────┐
│                                                                       │
│  ctx.on('agent/assistant-stream')  ─┐                                 │
│  ctx.on('session/event')           ─┴→ 折成 turn → step →（思考+工具） │
│                                        每个会话一份，LRU 上限 32       │
│                                              │                        │
│                        ┌─────────────────────┼─────────────────────┐  │
│                        ▼                     ▼                     ▼  │
│                 /stream（SSE）         /trace（快照）       /step（按需）│
│                 120ms 合并推送          连接时发一次        展开时才取   │
└───────────────────────────────────────────────────────────────────────┘
                                 │
┌─ 客户端半  src/client/* → lib/client.js（ModuleLoader）──────────────┐
│  右侧栏标签页（真组件）；样式**全部**来自宿主 --dsw-* token，深浅自动跟随 │
└───────────────────────────────────────────────────────────────────────┘

几个刻意的取舍：

• 折在宿主，不在浏览器。事件是「流式增量 + 步边界 + 工具调用」三路混在一起， 在浏览器里折等于把同样的活干三遍，而且面板一刷新就得重来。
• 状态只有一个来源。stepStatus() 是纯函数，面板照抄宿主下发的状态，自己不推导 —— 早先两边各推一次，结果是"每一步跑完仍显示正在生成"。
• 中文标题按需生成。只有你点「生成标题」时才调用模型（或打开「实时」）， 一次调用覆盖整轮，结果按内容指纹落盘缓存：内容变了指纹才变，不会拿到旧标题。
• 正文可丢，骨架不丢。目录靠每轮几百字节的骨架（轮号/时间/用户消息/步数/Token）， 所以 133 轮的会话也能在面板里翻完，而正文只留你真正在看的那几轮。
• 样式只用宿主 token（--dsw-*），一个硬编码色值都没有 —— 所以深浅色自动跟随， 也不会在宿主换肤后和界面其余部分不是一套语言。

阶段块是怎么切的

同族（read/grep/glob 都算"读代码"，edit/write 算"改文件"…）且相邻、 间隔 < 90 秒的步骤合并成一个块。90 秒这个阈值是量出来的：夹在两次 grep 之间的 一个 npm test 用 20 秒阈值会把列表切成 9 个碎块，90 秒就不切。

命令行再按命令内容细分：只读命令（sed/grep/cat/ls）算「读代码」， 有副作用的（跑测试/构建/提交）算「跑命令」—— 实测一个会话 89 条命令里 70% 是前者， 28% 是后者，混在一起叫什么都不对。

Token 是怎么数的

面板上所有"多少"都是 Token（轮头的「思考 1.4k tok」、每行的容量条宽度、 收尾小结的条与图例比例），换算只有一处：src/trace.ts 的 tokenWeight()。

密度取 DeepSeek 官方给的经验值 —— 1 个英文字符 ≈ 0.3 Token、1 个中文字符 ≈ 0.6 Token。 （宿主自己的 dsh-token-meter 用的是"4 字符 = 1 Token"这套面向英文的固定密度， 对中文会低估一半以上；这个面板读的思考是英文 CoT、正文常常是中文，所以按字符宽度分档。）

为什么不用 provider 报的 usage.outputTokens：那是整个 step 的产出（思考 + 正文 + 工具参数）， 拿它当"这一步想了多少"会把工具参数一起算进去；而且它只在一个尝试结束时才到， 面板上那根会长的容量条就再也长不起来了。所以口径统一走密度估算 —— 实时与历史是同一把尺子，宿主算、客户端照抄（两端各取一次整必然漂）。

⚠️ 它是估算：真值只有 provider 的用量有。容量条是 log10 映射（10~1600 tok → 条宽的 8%~100%）， 所以 ±20% 的误差在图上几乎看不出来；要精确到 Token 的用量，看主会话自己的账单。 唯一还是"字符"的地方是内存预算（maxColdChars、maxReasoningCharsPerStep、 snapshotTailChars、titleStepChars 那几个配置）—— 那些管的是"留多少原文"， 不是面板上报的统计。

为什么本地规则做不出中文标题

试过用规则从工具参数起标题（现在仍是派生标题那条路，用来兜底），但它只能回答 "这一步机械地做了什么"，回答不了"这一步在解决什么问题"。实测拿它当主标题， 一轮 40 步里有 26 步长得一模一样（都是 跑测试）。所以主标题交给模型 （一次调用、整轮一起总结、按内容指纹缓存），规则退回去做次级标题。

工具失败是宿主说了算

判据全部来自宿主的会话事件，面板一个都不猜：

实测失败率 0.9%（8 个会话 11283 次调用里 104 次），所以红标是有效信号， 不至于把面板染红。⚠️ 但别拿它当"退出码非零"：bash 的非零退出不算失败 （退出码是结果数据，只在正文尾部标 [exit code: N]）。

数据与隐私

这个插件读你的会话，所以边界写清楚：

开发仓库里另有一层约定：真实会话渲染出来的开发资料不进公开仓库、也不进 npm 包 （.gitignore / .npmignore 里单列一段），公开的预览页与截图一律用 scripts/preview/demo-data.mjs 里合成的数据。

开发

npm ci                     # 按 package-lock.json 安装项目依赖；开发验证使用 Node 22.14 / 24

npm run build              # 项目内 tsc 编译宿主 + esbuild 打包客户端 → lib/
npm test                   # 自动构建当前源码，再跑模板检查、行为测试和构建回归检查
npm run preview            # 生成 docs/ui-preview.html（真组件 + 真主题 token，合成数据）
npm run shots              # 重新生成 assets/*.png（README 那几张图）
npm run align              # 布局对齐检查（需先 preview，并安装 Chrome 或设置 DSH_CHROME）

完整测试及下面的领域测试命令都会先构建当前源码，不会读取过期的 lib/。构建使用项目锁定的 TypeScript 与 esbuild；不再扫描全局编译器或本机 npx 缓存。主题预览默认使用项目依赖，也可显式设置 DSH_CHECKOUT 选择另一份宿主主题。

单独跑某一套：

npm run test:trace     # 纯函数折叠（含工具失败、截断、步边界）
npm run test:titles    # 提示词预算、响应解析容错、缓存指纹
npm run test:routes    # SSE 分帧、快照形状、按需取原文、LRU、节流、心跳、缓存
npm run test:client    # 注册、渲染、交互、历史、目录、对比度（解析真 token 算）
npm run test:translate # 译文缓存与持久化
npm run test:build     # 测试自动重建、类型错误中止、发布包边界

持续检查在普通 push / PR 时执行；发布流程使用同一份锁文件。npm pack / npm publish 会自动构建，发布包只包含运行时、类型、源码与必要元信息，开发工具与本地资料留在仓库。

怎么确认改动生效了：curl -s localhost:3080/think-flow/api/ping 看 build 号 —— 改宿主代码后 +1。host 半要重启 dsh web（热重载只重建 fiber，不重新 import 模块， ESM 缓存里还是旧代码）；client 半刷新页面即可。

边界与已知限制

• 正文窗口默认 20 轮：更早的走目录按需折回来（有缓存与上限），不是"看不到"。
• 历史回看最多折 maxHydrateEvents 条事件：上万事件的长会话，更早的轮次可能折不完整。
• 标题是模型的产物：偶尔会把某一步起得很泛（"处理文件"）；这时展开区的次级标题 （本地规则算的）仍在，机械事实不会丢。
• 面板一次只显示一轮：这是刻意的 —— 一轮 53 步，两轮并排就没法读了，所以用目录翻。
• "跳到某一轮"在两个页面里的能力不一样，因为宿主给的不一样：
  • 对话页有原生「轮次导航」（每轮一枚刻度）：面板只是替你点那一枚刻度 —— 没载入的轮次宿主自己会 loadThrough 翻到位、精确落位（离顶 24px）。窄窗口下刻度轨道 （容器查询）不渲染时，退回到"插件自己翻历史再滚"。
  • 轨迹页没有任何跳转 API，只能由插件驱动：先借 session.loadThrough(seq) 把历史翻到 这一轮，再在一个虚拟滚动的表格里滚动找那一行（屏幕外的行根本不在 DOM 里，行高也不齐， 算不出偏移，只能"读着渲染出来的轮次边界走"），最后点它一下把"选中"交给宿主 （选中态是宿主的：data-selected + 轮次标签高亮 + 检查器，都由它自己画）。 长会话里这一路可能翻不动或找不到 —— 那时按上限安静放弃（不做任何事，也不会把 表格搅乱）；重试一次或先把轨迹滚到顶通常就有了。压缩过的会话里记录顺序可能乱 （见"边界与已知限制"），那时二分走不动，会自动退回按位置从头扫一遍。
  • 主会话既不在对话页、也不在轨迹页（比如在看别的视图）时，点轮次号什么都不做 —— 不替用户切视图。
• 点步骤号只在轨迹页生效（这一条是刻意的）：步骤是"一次模型往返"，只有轨迹页把它当 一条记录摆出来、并且给了可寻址的身份。对话页那边每一步都躺在折叠住的过程块里， 没有能定位的锚点 —— 硬做只能在界面上凭空找位置，不如老实不做（对话页里点 #N 是空操作）。 轨迹页里长轮次也一样能到：先按轮定位（翻历史 + 滚），再按 (轮, 步) 路标一跳一屏地往里走。
• 轨迹页的记录顺序由宿主决定，压缩过的会话上可能乱：实测同一个会话里时间轴上的轮次 边界是 3,4,1,5,6（第 6 轮的行排在第 5、7 轮后面），有的轮次还会整段缺失 —— 那是宿主的记录模型（dsh-client-ui-trajectory），插件改不了。插件的对策是不假设顺序： 目标行按行身份（assistant\0轮\0步）认，二分走不动时兜底从头按位置扫一遍。 但模型里根本没有的行，谁也变不出来 —— 那种情况按上限安静放弃。
• 宿主的三个定时器（都挂在 ctx.effect 上，卸载即清）：标题节拍（autoTickMs）、 冷轮按时间收回（coldTtlMs/10，封顶 5 分钟）、过期自愈扫描（resyncSilenceMs，封顶 10 秒）。 内存有容量上限（LRU + 冷轮预算）；标题缓存文件坏掉会静默重置。
• 需要 web profile（右侧栏 + webserver）；TUI 下没有这个面板。

许可

MIT © 2026 yfwu2020