dsh-synapse 是什么？DeepSeek Harness 的可视化会话地图工作台

dsh-synapse 是 DeepSeek Harness（DSH）的可视化对话工作台插件，为「线性对话难以回溯、分支多了管不过来」提供了画布式的解决方案：它把同一工作区中的会话、追问和分支组织成一张可浏览、可拖拽、可缩放的地图。 本文介绍 dsh-synapse 是什么、核心功能、完整的安装更新卸载命令、典型用法与常见排错，帮你把长会话和分支真正「摊开」来看。

dsh-synapse 是什么？

dsh-synapse 解决的是「线性对话回溯难、分支管理乱」的问题：把会话、追问与分支放进一张可视化画布，让操作会话像操作地图一样直观。 以下定位与事实均来自官方 README 与中文指南（来源）：

dsh-synapse 由 liangmianya 维护，MIT 协议开源，属于 DSH Plugin 生态里的会话可视化类插件。它不替代 DSH 的模型、工具、会话、权限或 Web 服务，所有对话操作仍由 DSH 完成；Synapse 只做一件事——把已经提交的会话事件投影成画布上的卡片。这意味着画布怎么调整都不影响真实会话：DSH session log 保存真实内容、是唯一事实来源，画布布局数据单独存放在 $DSH_HOME/synapse/，删掉它也不会丢失会话。插件还承诺不修改模型请求、系统提示词、工具 schema、provider 路由或可复用 KV-cache 前缀，因此安装与否都不改变模型行为。

dsh-synapse 的核心功能有哪些？

核心能力围绕「对话地图、真实分支、顺手追问、双向同步」展开：把连续追问、分支和不同会话放进同一张画布，并按 DSH 原生 fork 关系连接卡片。 以下能力来自官方 README 与中文指南（来源）：

• 对话地图：把同一工作区的会话、连续追问和分支放到同一张可操作画布上，支持拖动画布、最高 4× 缩放、一键定位当前会话。
• 保留真实分支：按 DSH 原生 fork 关系连接卡片，可从已完成的回答创建替代路径，不制造另一套会话历史。
• 追问更顺手：选中回答中的文字可直接带入新的追问，常用补充词可编辑，省去手动复制粘贴。
• 双向同步：在地图或 DSH 原生对话中切换会话，当前上下文保持一致，不会被第二套历史搞乱。
• 卡片与详情：卡片内部支持平滑滚动与 Markdown 表格渲染，点击卡片底部「详情」可查看完整会话记录。
• 工具调用折叠：将工具调用和结果按 callId 折叠到对应助手回答中，画布上只展示结论，不刷屏过程。

怎么安装与启用 dsh-synapse？

安装 dsh-synapse 需要支持 profile 插件机制的 DeepSeek Harness（2026-08 或之后版本）、Node.js ≥ 22.19.0，并只支持 web profile；npm 分发的是预构建产物，装完启动 dsh web 即可使用。 前提与命令来自官方中文指南（来源）：

1. 从 npm 安装：npm 包分发的是预构建产物、无需任何构建授权，是最简单的安装方式：

corepack pnpm dsh plugin --profile web add dsh-synapse

2. 从 GitHub 安装（审计源码用）：GitHub 安装会运行本包的 prepare 脚本，通过 node --check 验证 JavaScript 语法：

corepack pnpm dsh plugin --profile web add github:liangmianya/dsh-synapse

3. 启动 Web UI 并进入会话地图：启动 DSH Web 服务后，在浏览器打开默认地址，点击顶部「会话地图」进入 Synapse：

corepack pnpm dsh web

默认地址是 http://127.0.0.1:3080/。

4. 端口被占用时自动选择端口：3080 被占用时可让 DSH 自动选择空闲端口：

corepack pnpm dsh web --port 0

注意不要同时运行两个共享同一 profile 的 dsh web 实例。

5. 更新（update）插件：更新 dsh-synapse 时重新执行安装命令，跟随 npm registry 的最新版本：

corepack pnpm dsh plugin --profile web add dsh-synapse

6. 卸载插件：remove 只移除插件依赖和 profile 激活层，不会删除画布数据；需要彻底清理时再手动删除 $DSH_HOME/synapse/ 目录：

corepack pnpm dsh plugin --profile web remove dsh-synapse

卸载后 pnpm-workspace.yaml 里遗留的 allowBuilds 键没有副作用，可一并移除。

dsh-synapse 典型用法

dsh-synapse 装完即用：先发消息让会话进入工作区历史，再切到「会话地图」，点卡片就能在地图与原生对话之间来回操作。 使用步骤来自官方中文指南（来源）：

1. 打开工作区并产生历史：在 DSH 中选择一个工作目录，或打开已有会话，发送至少一条消息，让会话进入工作区历史——这是画布生成的前提。

2. 进入会话地图：点击 DSH 顶部「会话地图」，已提交的会话事件会自动投影成画布卡片（默认 autoProjection 为 true，投影进标题为「DSH 任务」的自动投影工作区）。

3. 浏览与同步会话：点击画布卡片或侧边栏的会话，可在会话地图与 DSH 原生对话之间同步当前会话，两边看到的上下文保持一致。

4. 创建分支并查看详情：在某个已完成的回答上使用「分支」创建替代路径；点击卡片底部「详情」查看完整会话记录；需要返回原生界面时点击「打开 DSH」或顶部「对话」，仍是同一个 DSH 会话。

5. 按需调整配置：插件通过 profile 的 cordis.patch.yml 注入，可在自己的 patch 中用行 id synapse 覆盖 dataFile、autoProjection、projectionWorkspaceTitle、trustedHosts 等键；由于 DSH patch 会整体替换该行的 config，覆盖时需要重述所有要保留的键。

dsh-synapse 常见问题与排错

dsh-synapse 的高频问题集中在 pnpm 安装被拦截、地图看不到卡片、局域网打不开三处，分别用 allowBuilds 完整键、先发消息入历史、trustedHosts 白名单解决。 依据来自官方中文指南（来源）：

1. pnpm 10 及以上安装被拦截：症状是 Git 依赖执行构建脚本被阻止，提示 allowBuilds 相关错误。原因：pnpm 10 起默认阻止 Git 依赖执行构建脚本。解决：把 pnpm 输出的完整键复制到 DSH Web profile 的 pnpm-workspace.yaml 的 allowBuilds 下，示例：

allowBuilds:
  "dsh-synapse@https://codeload.github.com/liangmianya/dsh-synapse/tar.gz/<commit>": true

键必须包含 codeload tarball URL 和 commit，不能只填裸包名 dsh-synapse；上游 commit 变化后键也随之变化，届时使用 pnpm 新输出的值。

2. 地图上看不到会话卡片：症状是进入「会话地图」后画布为空、没有卡片。原因：Synapse 只投影已提交的会话事件，没发过消息的会话不会生成卡片。解决：先发送至少一条消息再进入地图，或检查 autoProjection 是否被覆盖为 false，并到「DSH 任务」自动投影工作区查看结果。

3. 局域网打不开 /synapse 页面：症状是通过局域网内其他主机访问会话地图时被拒绝。原因：/synapse 有 Host 检查，默认只放行 localhost 与 127.0.0.1。解决：把实际访问的主机名或「主机:端口」加入 trustedHosts 数组（默认空数组）后重启生效。

4. 画布布局时好时坏、疑似被覆盖：症状是两个窗口同时打开会话地图，布局互相打架。原因：共享同一 profile 的两个 DSH Web 实例写同一个 workspaces.json，虽有跨进程写锁仍可能出现最后写入覆盖。解决：始终只运行一个共享该 profile 的 dsh web 实例。

适用场景与注意

dsh-synapse 适合会话长、追问多、经常需要回看或分叉的 DSH 重度用户，但使用前需要分清「画布」与「真实会话」、并注意 web profile 与局域网配置这两个边界。 适用性与限制来自官方中文指南（来源）：

典型场景包括：长会话回溯——把几十轮追问摊开在画布上快速定位；分支探索——对同一回答创建多条替代路径并行比较；会话总览——把多个会话放在同一张地图横向浏览、快速切换。需要留意的限制有：内置 patch 仅支持 web profile，其他 profile 暂不支持；单条消息投影上限为 8000 字符，超出部分在卡片中截断并标注「—…（详情查看全文）」，完整内容仍可在会话详情中查看；插件复用现有 DSH Web Server，不启动第二个 Web 服务、不创建第二套 Agent，也不修改 prompt 与模型请求；局域网使用前务必先配置 trustedHosts，否则其他设备无法打开地图页。

项目链接

dsh-synapse 是 liangmianya 维护的 MIT 开源项目，作为 DeepSeek Harness 的可视化会话地图工作台持续迭代。 想查看完整功能、截图与插件信息，欢迎访问本站的 dsh-synapse 插件详情页：dsh-synapse。

本页是基于该插件官方 README 独立重写的导读——权威文档和最新变更请以源头为准：liangmianya/dsh-synapse。插件是安装时就在你机器上运行的第三方代码；收录不代表背书——安装前请自行审阅源码。