dsh-synapse 是给 DeepSeek Harness（DSH）用的「会话地图」插件：同一个工作区里的会话、追问和分支，会被摊成一张可拖拽、可缩放的画布，而 DSH 原生会话仍是唯一事实来源。它的信任档位是「已验证」（L4 真实安装，本站 7 天前在 dsh 0.2.0-rc.2 下装过），站点风险记录也是「暂无已知风险记录」。也就是说，下面这些坑不是踩出来的事故，而是从 README、中文指南和架构文档里挖出来的环境不对齐问题——提前看一眼，能省掉一次「装完没反应」的排查。
先认识一下它，再谈踩空
它的四个核心能力是：对话地图（连续追问、分支、不同会话放进同一张画布）、保留真实分支（按 DSH 原生 fork 关系连接卡片，不另造一套会话历史）、追问更顺手（选中回答中的文字可直接带入新追问）、双向同步（在地图与原生对话之间切换会话，上下文保持一致）。画布最高支持 4× 缩放，卡片位置会自动保存，工具调用与结果按callId折叠进对应的助手回答。
一句话记住它的边界：它只投影 DSH已提交的事件，不启动第二个 Web 服务，也不碰 prompt、工具 schema 或 KV-cache 前缀。当前 npm registry 上的 latest 是 0.4.2，星标 478（GitHub 上已 483），周下载量 330——这个下载数取自 npm 全网窗口，含 CI、镜像与爬虫流量，不代表装机人数。装之前想对照其它插件的中文清单与安装形态，可以先看 完整插件清单与汉化避坑指南。另外提一句，站点上的安全扫描显示「🔵 含敏感能力，16 处证据，尚无人工评估」——它能读写本地文件、发起外部网络请求，这是静态能力清单，不是安全结论。
五个容易踩空的地方
坑一 · 版本线是硬门槛，但没人会拦你
现象。在较老的 DSH 上装完，顶部「会话地图」入口根本不出现，或者进去了行为异常。原因。本版本含破坏性变更，只支持 DSH >= 0.1.7-rc.2，不再兼容更早版本；插件两半都直接调用 Host 会话与 Client 服务接口，Harness 接口一变，插件就必须同版本发布。更麻烦的是，package.json 里没有声明 dsh 版本约束，站点静态检查同样显示「未声明」——安装时不会有任何东西提醒你版本不对。解决。先把 DSH 升到 0.1.7-rc.2 以上再装；遇到入口不出现，先查版本，别急着重装。顺便说清一个容易误读的点：本站的 L4 验证是在 dsh 0.2.0-rc.2 上完成的，高于门槛——它能证明新版本装得上，但不能反推老版本可用。
坑二 · 内置 patch 只往 web profile 注册
现象。换个 profile 启动，插件像没装一样。原因。内置的cordis.patch.yml只把插件注册进 DSH 的webprofile，dsh web之外的 profile 不在内置支持范围。解决。用 web profile 运行；确实要在别的 profile 下用，得自己显式把插件加进去，那已经不属于「内置支持」的口径。
坑三 · pnpm 10+ 的 allowBuilds 会拦住 Git 依赖构建
现象。走 GitHub 渠道安装时构建被拦下，装完用不了。原因。pnpm 10 及之后版本默认可能阻止 Git 依赖执行构建脚本。解决。把 pnpm 输出的完整键复制进 profile 的pnpm-workspace.yaml，键里必须包含 tarball URL 与 commit，只填裸包名dsh-synapse是无效的；而且上游 commit 一变，键也会跟着变，要用 pnpm 新输出的值替换。
坑四 · 同一 profile 跑两个 dsh web 实例会互相覆盖画布
现象。两个窗口里的布局对不上，刚摆好的卡片位置莫名回退。原因。两个实例共享同一份workspaces.json（默认$DSH_HOME/synapse/workspaces.json）；即便有跨进程写锁和外部修改警告，仍可能出现最后写入覆盖。解决。官方要求每个共享 profile 只跑一个实例；真要并行，就给它们配不同的 profile。
坑五 · 局域网访问会被 Host 检查挡在门外
现象。从另一台机器访问，或走反向代理打开时进不去/synapse。原因。/synapse端点始终只接受localhost与127.0.0.1，其他主机名或主机:端口必须显式写进trustedHosts。解决。把实际访问用的主机名或主机:端口加进trustedHosts；同时记住这层校验只是 Web 面的一环，不能替代更上层的网络访问控制。
装之前顺手做的一件事
DSH 与插件目前都处于 developer-preview 阶段，站点给的建议很直白：装任何插件前先备份~/.dsh配置，出问题好回滚。这一步不解决上面五个坑里的任何一个，但它能让「踩空了要退回原状」变得便宜。
总结
五个坑其实指向同一件事：dsh-synapse 的边界很清楚，踩空多半是环境没对齐——DSH 版本、profile、构建授权、实例数量与允许的主机名。装之前对着插件详情页核一遍自己的环境，比装完再排查省事；更全的中文清单与各渠道安装形态，可以看 完整插件清单与汉化避坑指南。
适合与不适合
适合：DSH 已在 0.1.7-rc.2 以上、想用画布治理分支对话的开发者；愿意只跑一个 web 实例、并自己维护本地数据文件的人；需要局域网访问且懂得配trustedHosts的人。不适合：DSH 版本还停在 0.1.7-rc.2 以下的人；想同时跑多个共享同一 profile 的dsh web实例的人；期待跨设备同步或把它当会话备份工具的人。
标签：dsh-synapse、DeepSeek Harness、避坑、会话地图、插件安装
本文由 DeepSeek Harness Hub 自动整理，数据来源于插件详情页。
