前言¶
在 DeepSeek Harness（DSH）的智能体开发或工具链构建过程中，开发者经常需要在本地查看仓库的提交历史与工作树状态。传统的命令行工具虽然精确，但在可视化和上下文切换上存在成本。
dsh-sidebar-git-graph 旨在解决这个问题。它作为一个客户端插件，为 DSH 的 Web 端提供右侧栏页面，直接将当前会话的仓库渲染为可视化的 Git 提交图谱。该插件支持 VS Code 风格的分支/合并泳道与贝塞尔曲线，并可与 dsh-better-sidebar 共存。
插件简介¶
这是 AFunDog 维护的一个 DSH 插件，主要解决多仓库、多工作树场景下的 Git 历史查看与变更追踪需求。它通过只读模式，利用六条 Git 命令在本地构建视图，不执行任何写入操作。
核心功能¶
1. 可视化提交图谱
页面展示只读的 Git 提交图谱，采用 VS Code 风格的泳道设计。每条历史线占据一个泳道，分支分叉与汇入处使用贝塞尔曲线连接。合并提交的圆点较大，当前 HEAD 所在泳道会使用主题色高亮。每个提交节点显示 Ref 芯片（本地分支、远程分支、标签），当前分支的文字颜色与主题配色对齐。
2. 工作树改动区
在图谱上方提供工作树改动区，展示暂存区、未暂存区和合并中的更改。每行显示文件状态字母（M/A/D/R/C/U）及增删行数。用户点击行即可就地展开 Diff，改动区支持折叠且会记住状态。
3. 多仓库与多工作树支持
当工作区包含多个仓库时，顶部会出现下拉框供用户选择。支持切换不同仓库，并记住用户的选择。对于使用 git worktree 管理的场景，插件支持列出并切换不同工作树，每个工作树展示各自的分支与未提交改动。
4. 搜索与详情查看
提供提交信息搜索功能，高亮命中项并逐个跳转（不过滤列表）。点击提交行可查看详情，包括完整 SHA、作者、时间、父提交及参与 refs。下方列出该提交改动的文件清单，点击文件可展开 Patch 视图。
5. 性能与限制
使用虚拟列表技术，窗口内仅渲染可见行，优化了大量提交时的性能。页面在非激活状态时不发送请求。但虚拟列表限制窗口内最多 2000 条，单次最多 3000 行改动。
安装与启用¶
在安装前，请确保宿主环境满足要求：@deepseek-ai/dsh >= 0.1.7-rc.1。
执行以下命令安装插件：
dsh plugin --profile web add github:AFunDog/dsh-sidebar-git-graph
安装完成后，需要重启 dsh web 宿主进程以加载新路由。
启用步骤如下：
1. 打开 DSH Web 客户端。
2. 在右侧栏选择「Git 图谱」（若安装了 dsh-better-sidebar，可在 + 菜单中找到；裸 DSH 则在引导页）。
3. 使用顶部下拉框切换仓库或工作树。
4. 点击图谱中的行或文件列表中的项查看详情。
适用场景与注意¶
该插件适用于需要频繁在本地查看 Git 历史和变更的开发者。它特别适合管理包含嵌套仓库或多个 git worktree 的工作区。
注意事项：
* 只读设计：插件不执行 checkout、commit、reset、rebase、fetch/push、add、restore 等写入命令，只使用 rev-parse、status、for-each-ref、log、diff、worktree list。
* 本地依赖：图谱仅基于本地仓库，不进行网络请求，因此远端更新需先执行 git fetch。
* 版本区分：NPM 上的 dsh-git-graph 是另一个作者的插件，本插件为 @zeng/dsh-sidebar-git-graph。
总结¶
dsh-sidebar-git-graph 通过可视化的方式，将 Git 历史与工作树状态集成到 DSH 的侧边栏中。它克制地只读数据，通过虚拟列表和精细化渲染，提供了流畅的查看体验。对于构建基于 DSH 的开发工具链，这是一个辅助查看状态的高效组件。
