会话脑图 jianyuepei/dsh-session-mindmap

dsh-session-mindmap

English · 简体中文

把一个 DSH 会话变成一张自包含的 HTML 脑图。

一个阶段结束时执行 /mindmap，得到一个可以直接打开、发给别人、或存档的文件：这场会话聊了什么主题、得出了什么结论、做了哪些决策以及为什么、还剩什么待办和未决问题。文件不依赖网络、字体和 CDN，双击就能看。

演示

为什么做这个

长会话是很差的交付物：真正值钱的东西（决定了什么、否掉了什么以及为什么、还有什么没定）散落在几十轮对话里，回头重读一遍基本不划算。这个插件产出的是"一页版本"。

它刻意不是 GUI 面板、不是自动化、也不是知识库：你让它跑它才跑，产出一个文件，然后结束。

安装

从 npm 安装
dsh plugin add dsh-session-mindmap

从本地目录安装（开发用）
dsh plugin add /path/to/dsh-session-mindmap

从 git 安装（lib/ 已随仓库提交，不触发任何构建）
dsh plugin add github:jianyuepei/dsh-session-mindmap

要求 DSH 0.2.0-rc.2（dsh --version）。声明的 peer 版本与当前 DSH 不匹配时，插件管理器会直接拒绝安装；能升级就升级，别急着用 allow-version 绕过。

用法

让模型去调用：

把这个会话整理成脑图

或者直接给工具传参：

session_mindmap
sessionId? "last" 或某个会话 id；省略即当前会话 kinds? 逗号分隔：topic,conclusion,decision,todo,question,file focus? 只整理某一个主题 language? zh 或 en；省略用插件配置 force? 忽略缓存，重新调用模型

或者用命令——它不会为了"要不要生成"再花一轮模型：

/mindmap # 当前会话 /mindmap last # 最近一个会话 /mindmap session-abc --reveal # 指定会话，生成后在文件管理器里选中它 /mindmap --no-open # 只写文件，不打开任何窗口 /mindmap --focus=发布方案 # 只整理一个主题 /mindmap --kinds=topic,file # 把涉及的文件也带上 /mindmap --lang=en # 单次产出英文脑图，不用改配置 /mindmap list # 列出最近会话的 id 与标题

命令是推荐入口：不想为"请求本身"再花一轮模型时，它照样能跑。

产物

<会话工作目录>/.dsh/mindmap/ ├── <sessionId>-<yyyymmdd-HHMM>.html # 交付物 └── .cache/<hash>.json # 脑图数据 + 导出文本，按会话状态缓存

* 点击即达：结果里给的是同源链接（/session-mindmap/artifact?id=…），点一下直接在浏览器打开，不用复制路径；文件路径仍单独一行给出，方便终端、日志和 headless 场景。链接是进程级的——生成它的那个 DSH 实例还在运行就有效，和 App 自身 token URL 的生命周期一致。
* HTML 是自包含的：没有 CDN、没有网络字体、没有图片、没有任何上报，脑图用内联 SVG 画，离线可用，也能直接发给人或提交进仓库。
* 和上次比变了什么：对同一会话再次生成时，会给出差异——13 → 18 · 新增 6 · 消失 1，列出新增与消失的话题、在产物里把新增节点圈出来，结果里也给同一行摘要。这是两棵节点树的结构化 diff：不调模型、零成本，同样的输入永远得到同样的答案。上一次的节点措辞会回喂给模型并要求沿用——否则同一话题两次说法不同，对比就全是噪音。记录写在 .cache/index.json。
* 交互：点节点折叠/展开、拖拽平移、滚轮缩放、搜索高亮；悬停节点会告诉你它来自会话的哪一段（第 3 段 · seq 218-245）；工具栏可复制大纲、导出 PNG / Markdown / Mermaid。
* 缓存：key 由会话已捕获的事件序号、启用的维度、focus、语言和模型组成。会话没变时直接命中缓存，完全不调模型；force: true（或 --force）可强制重算。
* 重新生成会写一个新的带时间戳的文件，旧快照不会被覆盖。不想提交的话把 .dsh/ 加进 .gitignore。

配置

配置写在插件行上（profile 的 cordis.patch.yml）——补丁是整行替换而非深合并，所以要改几个键就得把需要的键都写全：

- id: session-mindmap
name: 'dsh-session-mindmap'
config:
language: zh
maxNodes: 120

| 键 | 默认值 | 说明 |
| provider / model | 空 | 留空即跟随 Agent 默认模型；生成频繁的话可以指定一个便宜模型。 |
| kinds | topic, conclusion, decision, todo, question | 抽取维度；加 file 会把会话涉及的文件也整理进去。 |
| language | zh | 节点语言：zh 或 en（工具参数 language 可单次覆盖）。 |
| maxInputTokens | 24000 | 单次模型调用的 transcript 预算。 |
| maxBlocks | 8 | 长会话最多分几段生成，另加一次合并调用。 |
| maxNodes / maxDepth | 80 / 4 | 对模型返回结果做的节点数与层数上限。 |
| maxOutputTokens / temperature | 8000 / 0.2 | 单次生成的采样参数。这个上限必须装得下整份回答——一个节点大约占 label + detail 那么多字，见「故障排查」。 |
| llmTimeoutMs | 180000 | 单次调用超时。 |
| outputDir | .dsh/mindmap | 相对会话工作目录；也接受绝对路径。 |
| cache | true | 会话没变时复用上次结果。 |
| openAfterBuild | true | 人手动执行 /mindmap 后自动打开产物；模型调用不受影响（它留一张交付物卡片）。 |

实现要点

sessionQuery.readSurface(id) 模型实际看到的上下文
↓ extract.js 事件流 → 逐轮区块（纯函数） ↓ budget.js token 估算 → 1 次调用，或 ≤maxBlocks + 1 次（纯函数） ↓ organize.js ctx.llm.stream → 严格 JSON，失败回喂重试一次（纯函数） ↓ schema.js 强制转换、裁剪、去重（纯函数） ↓ render-html.js 自包含 HTML + 内联 SVG 渲染器 <工作目录>/.dsh/mindmap/.html

有三个决定值得单独说明，因为它们通常是评审必问的：

不用 Mermaid 呈现。 DSH 的 Web GUI 里没有任何图形渲染器（没有 Mermaid、没有 markmap——这是扫描 app 包实测的），所以 * 会话只通过 ctx.sessionQuery 读。 落盘日志是多帧追加的 zstd（实测一个会话文件里有 136 帧），直接解压只能拿到第一帧。服务是唯一受支持的来源，而 readSurface 最接近"这场会话到底聊了什么"。
* 模型失败就是失败，不做兜底。 重试一次后仍拿不到可用 JSON，就直接报错，而不是写出一个看起来像脑图的目录树——那种产物会被当成真的脑图用。

隐私

* 插件通过宿主服务读取会话，并把 transcript 发给你已经配置好的模型，除此之外不发往任何地方。
* 产物写在会话自己的工作目录里。
* 测试用例里没有任何真实会话内容，全部是合成数据。这条请继续保持。

兼容性

| DSH | 0.2.0-rc.2（更低版本会被插件管理器拒绝） |
| Node | >= 20.18 |
| Profile | desktop / web 均可（纯 Host 插件，没有客户端 bundle） |
| 构建 | 无——lib/ 是直接提交进 git 的纯 ESM |

开发

sh
npm install # 只声明一个开发镜像包（schemastery），DSH 包作为 peer 自动装进来
npm test # node:test，77 个用例，不联网、不需要装 DSH
npm run demo # 重新生成 examples/demo.{html,md,mmd}

测试分三层，中间那层是关键：

1. 纯逻辑——extract、budget、schema、render-：不碰宿主、不做 IO。
2. 接线契约——tests/index.test.js 用真实的 @deepseek-ai/dsh-tools 跑一遍 apply，证明注册的工具能通过 schema 编译与参数校验。DSH 包取不到时会跳过而不是失败，离线环境照样能跑其余用例。
3. 全链路——tests/pipeline.test.js 用假宿主 + 预置模型输出 + 临时目录，把"读 → 组织 → 渲染 → 落盘"整条跑通。

lib/index.js Cordis 接线：Config、工具、命令 lib/config-schema.js Schemastery schema（用真实 peer 测过） lib/plugin.js 不含 DSH 依赖的宿主接缝：工具/命令契约、各类 helper lib/pipeline.js 读 → 规约 → 组织 → 渲染 → 落盘（不含 DSH 依赖） lib/extract.js 事件流 → 逐轮区块 lib/budget.js token 估算与分段 lib/organize.js prompt、流式收集、严格 JSON 解析、Map-Reduce lib/schema.js 脑图数据模型：解析、转换、裁剪 lib/render-md.js Markdown / Mermaid / 大纲 lib/render-html.js 自包含交付物 scripts/make-demo.mjs 重新生成 examples/

故障排查

报 模型两次都没有返回可用的脑图 JSON。 先看错误的第一行，它写了 finish 原因：

输出达到 maxOutputTokens，被截断——回答太长装不下。调大 maxOutputTokens，或者少要一点（--kinds=topic,conclusion、--focus=…、调小 maxNodes）。截断不代表全丢：截断点之前写出来的内容会被解析出来，脑图会短一点，日志里也会说明。
* 其它原因——模型回的是散文或结构不对。换一个模型（provider/model），或用 focus 把范围收窄。

prompt 里的节点预算（lib/organize.js 的 NODE_BUDGET）必须和 maxOutputTokens 匹配：要的节点数超过输出上限装得下的量，就会变成一整片"没有合法 JSON"的报错——这个坑踩过一次，现在有单测盯着两者不许失配。

参与贡献

欢迎提 issue 和 PR，三条底线：

* 保持纯 Host、零构建——不加客户端半侧、不引入打包器、不加运行时依赖；
* 测试和 issue 里不要出现真实会话内容；
* README.md 与本文件保持同步——两者是同一份文档的两个语言版本，不是两份文档。

提交 PR 前请跑 npm test 和 npm run demo；CI 会检查这两步，并且如果 examples/ 过期会直接失败。

DESIGN.md 说明这个插件为什么这么设计：实测到的约束、架构、契约，以及几条已经踩过的失败模式背后的规则。

许可

MIT

⬆ 回到顶部 · English