dsh-git-chain

English · 中文

面向 DeepSeek Harness（DSH） 的 Git 提交图插件。它把仓库历史呈现为可读的 SVG 泳道图，并在同一个侧边栏工作流中提供提交详情、完整 Diff、范围过滤和受保护的本地分支切换。

当前版本：0.1.1 · Stable · GitHub Release · MIT License

为什么使用 dsh-git-chain

• 看清提交拓扑：用连续泳道、节点、merge 汇入线和分支出线表达真实的 Git DAG。
• 保持工作流连贯：优先显示在 dsh-better-sidebar 中；没有该基座时回退为输入栏芯片和浮动面板。
• 从查看到定位：点击提交即可查看作者、父提交、变更文件和懒加载的 unified Diff。
• 安全地切换分支：切换前检查冲突、进行中的 Git 操作、其他 worktree 和可能被覆盖的文件。
• 适配不同阅读方式：支持全部 refs、当前分支、指定本地分支和 first-parent 主线；支持中文/英文界面。

当前版本是 0.1.1 Stable；已在 Windows 11 + DSH Desktop 2.0.2.0 的固定 profile 完成安装、升级、卸载、重装和 fallback 验收。其他 DSH/OS 组合请先参考兼容性矩阵。

界面预览

完整链路展示分支泳道、merge 节点、当前分支和 refs；“仅主线”聚焦当前 HEAD 的第一父链。

功能

Git 历史与过滤

• 使用 Git CLI 获取带父关系和 decorations 的拓扑排序历史。
• 查看全部 refs、当前分支或指定本地分支的服务端范围。
• 使用 first-parent 查看当前 HEAD 的主线视图，同时保留 merge 元数据。
• 在已加载的历史窗口内按主题、作者、引用或 commit OID 即时过滤。
• 固定行高、虚拟滚动和可识别的 lane identity，适合较长的提交列表。

提交详情与 Diff

• 展示作者、提交者、时间、父提交和变更文件。
• 用文件状态徽标和增删行数快速定位变化。
• 按需加载 unified Diff；Host 对单次输出设置 1 MB 上限，避免大变更占满界面。

分支切换与刷新

• 列出当前工作区的本地分支，并同步当前分支勾选状态。
• 使用 git switch --no-guess，不会隐式创建或猜测远端分支。
• Host 通过 SSE 推送外部 Git 变化，窗口重新聚焦时也会节流刷新。

安装

从源码安装到 DSH

环境要求：

• 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 plugin --profile desktop add link:/absolute/path/to/dsh-git-chain

重新启动 DSH，使 Host 侧插件和 bundle patch 生效，然后打开侧边栏中的 Git 链路图。

卸载：

dsh plugin --profile desktop remove dsh-git-chain

Windows PowerShell 示例：

dsh plugin --profile desktop add link:F:\path\to\dsh-git-chain

将上面的路径替换为你的本地 checkout 路径。

开发与验证

pnpm install
pnpm run typecheck
pnpm test
pnpm run build
node scripts/browser-smoke.mjs

当前仓库的发布前验证包括：双工程类型检查、55 个单元/集成测试、Host/Client 构建，以及真实 Chromium 中的完整链路、first-parent、详情、Diff、过滤、分支菜单、fallback 和响应式检查。smoke 截图输出到 smoke/。

公开协作：贡献指南 · 安全策略 · 变更记录 · 兼容性矩阵 · 社区收录准备计划 · 固定包生命周期计划

技术架构

DSH Web GUI                         DSH Host
┌──────────────────────────┐       ┌─────────────────────────────┐
│ better-sidebar tab       │ HTTP  │ workspace-gated Git service │
│ 或 fallback 浮动面板      │ ────► │ /git-chain/* JSON + SSE      │
│ React + SVG graph        │       │ Node + ctx.subprocess + Git  │
└──────────────────────────┘       └─────────────────────────────┘

• Host：通过 ctx.subprocess 调用 Git CLI，提供 workspace、status、branches、graph、show、diff 和受守卫的 switch 能力。
• Client：React 面板负责 SVG 泳道、节点交互、虚拟滚动、过滤和详情联动。
• 布局：纯函数布局快照携带 lane identity、节点类型、merge edge、窗口边界和节点入边语义，避免线路断开或因列变化错色。
• 构建：tsdown 分别输出 Host bundle 和浏览器 Client bundle，符合 DSH 的双面 Cordis 插件装配方式。

安全边界

• Git 路由只接受 DSH 已注册 workspace，并进行真实路径校验。
• 默认只接受 loopback 请求；配对设备放行仍需额外信任凭据。
• 变更接口要求 application/json。
• 分支名和 commit OID 在进入 Git 命令前经过白名单校验；命令使用 argv，不拼接 shell 字符串。
• 分支切换遇到冲突、进行中的操作、其他 worktree 或文件覆盖风险时会拒绝执行。

已知限制

• 文本过滤目前只作用于已加载窗口；subject、author、文件级的全历史服务端搜索仍在路线图中。
• 图布局采用最小泳道策略，少数复杂菱形 merge 可能出现轻微曲线重叠。
• 虚拟滚动窗口上下缘会对泳道进行截断，并通过 overscan 减少视觉跳变。
• 单次完整 Diff 输出上限为 1 MB。

路线图与反馈

后续计划包括父链 hover 高亮、键盘导航、提交比较、服务端全文查询、分页和增量更新。详细的同类项目调研、架构取舍和分阶段计划见 docs/ROADMAP.md。

欢迎通过 GitHub Issues 反馈问题或提交改进建议。涉及安全问题，请不要在公开 Issue 中发布敏感信息。

License

MIT