前言¶
DeepSeek Harness (DSH) 的核心设计理念是“一切皆插件”。在智能体开发与调试过程中，频繁查看 Git 提交历史、定位具体变更以及安全切换分支是常见操作。dsh-git-chain 插件旨在解决这些问题，它将仓库历史以 SVG 泳道图的形式呈现，并提供在侧边栏工作流中直接查看详情、Diff 和受保护的分支切换能力。
插件定位¶
dsh-git-chain 是一款面向 DSH 的客户端插件，由 ShinonomeAya 维护。它不直接操作 Git 底层，而是作为 DSH Web GUI 和 DSH Host 之间的桥梁：前端负责渲染 SVG 可视化与交互，后端通过 ctx.subprocess 调用 Git CLI 来执行具体的图生成、Diff 和分支操作。
核心功能¶
历史视图与过滤¶
插件提供 SVG 泳道拓扑图，展示提交节点、Merge 汇入线和分支出线。
- First-parent 主线视图：专注于当前 HEAD 的第一父链，同时保留 Merge 元数据。
- 范围过滤：支持查看全部 refs、当前分支、指定本地分支。
- 即时过滤：在已加载的历史窗口内，可按主题、作者、引用或 Commit OID 进行筛选。
- 布局策略：采用最小泳道策略，配合固定行高和虚拟滚动，适合较长的提交列表。
提交详情与 Diff¶
- 点击提交节点可查看作者、提交者、时间、父提交及变更文件。
- 提供文件状态徽标和增删行数统计。
- 懒加载 unified Diff，单次输出上限为 1 MB，防止大变更占满界面。
分支切换与保护¶
- 受保护切换：切换分支前，系统会自动检查冲突、进行中的 Git 操作、其他 worktree 以及可能被覆盖的文件。
- 安全机制：使用
git switch --no-guess避免隐式创建或猜测远端分支；分支名和 commit OID 在命令执行前经过白名单校验，使用 argv 而非拼接 shell 字符串。 - Fallback 机制：优先显示在
dsh-better-sidebar中；若无该基座，则回退为输入栏芯片和浮动面板。
安装与启用¶
安装前请确保环境满足以下要求：
- DSH 版本 >= 0.1.1-rc.1
- Node.js 版本 >= 22.19.0
- Git 已加入系统 PATH
- 克隆仓库：
git clone https://github.com/ShinonomeAya/dsh-git-chain.git
cd dsh-git-chain
- 安装依赖并构建：
pnpm install
pnpm run build
- 添加插件到 DSH Desktop profile：
dsh plugin --profile desktop add link:/absolute/path/to/dsh-git-chain
- 重新启动 DSH，在侧边栏中找到 Git 链路图 标签页。
如需卸载：
dsh plugin --profile desktop remove dsh-git-chain
典型用法¶
- 查看提交详情：点击提交节点，侧边栏会展开显示作者信息、父提交记录以及变更文件列表。
- 浏览主线：在视图选择中启用 first-parent，聚焦当前分支的主线历史，便于梳理逻辑流。
- 安全切换：点击分支列表中的分支名，系统会进行安全检查（如是否有未提交的更改或冲突），确认无误后切换。
- 筛选历史：在已加载的历史窗口内，输入关键词即可快速过滤出特定作者或主题的提交。
适用场景与注意事项¶
该插件适合需要频繁在 DSH 中进行代码审查、历史回溯或分支管理的开发者。
需要注意以下已知限制：
- 过滤范围：文本过滤目前仅作用于已加载窗口；全历史的 subject、author 或文件级服务端搜索仍在路线图中。
- 布局限制：图布局采用最小泳道策略，少数复杂的菱形 merge 节点可能轻微重叠。
- 视觉截断：虚拟滚动窗口上下缘会对泳道进行截断，但通过 overscan 减少视觉跳变。
- Diff 大小：单次完整 Diff 输出上限为 1 MB。
此外，插件运行于 DSH 进程权限下，Git 路由只接受已注册的 workspace，默认只接受 loopback 请求，安全性由 Host 层把控。
结语¶
dsh-git-chain 通过可视化的方式重构了 Git 历史的查看体验，同时将分支切换的安全检查纳入工作流。对于使用 DSH 进行智能体开发或代码管理的用户，它是一个能够直接提升调试效率的工具。
