Git 提交图谱 songgms/dsh-git-graph

DeepSeek Git Graph

面向 DeepSeek Harness 的 Git Graph 面板 —— 在对话所在的同一个窗口里查看提交拓扑、引用、提交详情与逐文件差异。

License: MIT
Node

English · 中文

Git Graph 面板

功能

侧边栏面板，就在对话旁边，画出你当前所在仓库的提交图谱。

- 图谱 —— 用 SVG 绘制分支车道，按「新提交在上」排列；颜色跟着线走，所以一条分支从它的顶点一直保持同一颜色，直到并入某个引用。
- 引用 —— 本地分支、远程分支、标签以 chip 形式出现在对应的提交行上，当前 HEAD 有标记。
- 筛选 —— 可只看某个引用的历史，也可以边输入边搜索提交信息、作者和哈希。
- 提交详情 —— 完整哈希、父提交、作者与提交者及时间、提交正文，以及每个变更文件的 +/− 计数。
- 差异 —— 点开文件查看 unified diff，增删行与 hunk 头都用 Harness 自己的设计 token 着色。
- 复制与导出 —— 复制完整哈希、短哈希、提交标题或整条提交信息；把提交另存为 .patch 文件。
- 创建引用 —— 在选中的提交上新建分支或标签。

面板完全跟随 Harness 主题，因此明暗两种模式下都能和内置页面并列而不突兀。

界面结构

侧边栏图标 ──▶ 主面板 ├── 仓库选择 · 拉取 · 推送 · 储藏 · 刷新 ├── 工具栏：引用筛选 · 文本搜索 · 行高切换 ├── 提交列表 → 车道图 (SVG) · 引用 · 标题 · 作者 · 日期 └── 详情面板 → 哈希、父提交、作者/提交者、正文、变更文件、unified diff、复制 + 补丁 + 新建引用

安装

本包是 DeepSeek Harness 的 bundle：Host 半负责注册 HTTP 路由，浏览器半负责渲染面板。装它分两步：先取得包，再把它装进某个 profile。

第一步：取得包

从 npm —— 包发布到 registry 之后：

npm install dsh-git-graph

目前还没有发布到 npm；发布之前可以直接从 GitHub 安装：

npm install github:songgms/dsh-git-graph
或
npm install git+https://github.com/songgms/dsh-git-graph.git

第二步：安装进 DeepSeek Harness

在 Harness 会话里，把 bundle 安装器指向包所在的目录：

plugin_manager action=install_bundle target=

target 就是包目录：用 npm 安装的话是 node_modules/dsh-git-graph；本地开发时就是这个仓库的目录本身。

install_bundle 会完成包安装与 bundle 选择，并且改动能跨重启保留。不要手改 profile 的 package.json 或 cordis.patch.yml —— 那两个文件归安装器管。

装完之后：

1. 刷新页面。 浏览器半是一个 client module，页面不重启 shell 就不会把它纳入 boot graph。
2. 如果这个包此前已经装过，还要重启 profile。 loader 按 URL 缓存插件模块，所以以 link: 方式安装的 bundle 会一直执行进程首次 import 的那份 JavaScript。

用 cordis_inspect_query 确认它已生效：Slots.listSubTree 查 sidebar.panellist 应看到 id: git-graph，查 main 应看到 key: git-graph。Host 行是 include:git-graph。

配置

全部可选；不加 patch 层也能用默认值。

- id: git-graph
name: dsh-git-graph
config:
extraRoots: [] # 额外仓库，始终出现在选择器里
probeRoots: [] # 额外探测路径，用于查找「包含它的仓库」
discoverMaxDepth: 6 # 向上查找仓库时走过的父目录层数 scanChildren: true # 同时探测候选目录的直接子目录 maxChildren: 24 # 每个候选目录最多探测多少个子目录 discoverCacheMs: 5000 # 探测结果缓存时长 timeoutMs: 30000 # 单次 git 调用的上限 maxCommits: 5000 # 单页最多请求多少提交

取值非法时会连同字段路径一起报错并回退到默认值，所以 patch 层里写错一个字段也不会让面板打不开。

面板如何找到仓库

两个互相独立的来源，合并后展示：

1. 当前工作区 —— 页面的 session 快照带有工作目录，Host 先探测它，再逐级探测其父目录（discoverMaxDepth），最后探测它的直接子目录（scanChildren）。工作区本身就是仓库时由第一步找到；会话开在一个装着多个 checkout 的父目录上时由最后一步找到。
2. Harness 进程目录 —— 再加上配置里的 extraRoots 与 probeRoots。

仓库以 git rev-parse --show-toplevel 认定，所以选择器显示的是仓库根目录，而不是碰巧匹配上的某个子目录。什么都没找到时，空状态接受粘贴一个绝对路径。

它会写什么

面板的一切都是只读，除了一小组刻意的仓库操作——它们都在右上角，且只能由用户触发，agent 碰不到。

| 操作 | 实际执行的命令 | 为什么放在这里是安全的 |
| 新建分支 / 新建标签 | git branch / git tag | 只添加一个引用，其他什么都不动。重名拒绝，名字先本地校验再交给 git check-ref-format --branch。 |
| 拉取 | git pull（merge / rebase / ff-only） | 唯一可能留下冲突的操作。面板通过 git 自己的标记和未合并路径检测到冲突后显示横幅，并提供中止——当初只读设计暂缺的那套机制如今已经就位。 |
| 推送 | 把当前分支推到它的上游 | 永远不碰工作区；被拒绝的推送不会改变仓库的任何状态。 |
| 储藏 | git stash push -u、list、pop、drop | 完全可逆：保存（默认包含未跟踪文件，可写备注）后，菜单可恢复或删除；恢复遇冲突时储藏本身完好保留。 |

另存为补丁是只读操作：git format-patch -1 --stdout 把提交渲染成 mbox 补丁文本，浏览器负责把它变成下载，所以插件依然不在磁盘上创建任何文件。

所有改变状态的路由都只接受 POST 并要求 x-dsh-plugin CSRF 头，跨站页面无法驱动其中任何一个。

cherry-pick、revert、手动 rebase、fixup/squash 和 reset 仍然不开放。它们需要本插件没有的机制 —— 能把「破坏性动作」和「复制到剪贴板」区分开的确认流程、rebase 的 todo 编辑器、以及针对未提交改动的前置检查。没有这些就把它们放进来，会让一个「按构造安全」的插件变成一个「靠运气安全」的插件。

架构

| 部分 | 路径 | 职责 |
| Host 半 | index.js | 只负责挂载：Config schema、向 webServer 注册路由。 |
| git 层 | lib/git.js | 所有 git 调用：参数数组、不经 shell、非交互环境、硬超时。解析 log --numstat 与 show --numstat。 |
| HTTP 面 | lib/routes.js | /api/dsh-git/ 的各个 handler。 |
| 实时加载 | lib/live.js | 上面两个模块文件内容变化时重新 import。 |
| 布局 | lib/graph.js | 纯函数式的提交 DAG 车道分配。无 DOM、无 React。 |
| Client 半 | client.js | 侧边栏图标、面板、图形渲染、详情与差异视图。构建产物。 |
| 样式 | client.css | 只用主题 token（--dsw-alias-），明暗通用。 |

设计注记

- 一页一次请求。 git log -z --topo-order --numstat 一次带回拓扑和每个提交的变更规模。-z 不是可选项：少了它，git 会把整段 numstat 输出放在最后一个格式化提交之后，于是每个提交的文件列表都会落到错误的提交上。
- 用车道，而不是合并专用几何。 一条车道只交给一个父提交，所以合并就是一条进入节点的水平边，而不是需要特殊处理的情况。
- 窗口化渲染。 只有视口内的行存在于 DOM 中；图形是一整块绝对定位的 SVG 并随窗口平移，所以一条越过视口的长线依然能正确画进来。
- 截断的历史是可见的。 父提交落在已加载窗口之外的边，会以虚线画到图形底部。
- 面板自己安装样式表。 客户端 runner 的 styles 内建符号属于动态包的闭包；已安装的 client module 的 factory 根本收不到它。所以面板先向组合请求 styles 服务，拿不到就自己往文档里插一个 元素。

为什么 index.js 几乎是空的

loader 按 URL 缓存插件模块，所以以 link: 方式安装的 bundle 会一直执行 profile 首次 import 的那份 JavaScript —— set_plugin 循环只是把 fiber 重新挂载一遍，复用的还是缓存里的模块。于是 index.js 除了挂载什么也不做，所有承载行为的部分都经 lib/live.js 按内容戳（content stamp）导入：

| 改动的文件 | 生效时机 |
| lib/git.js、lib/routes.js | 下一次 HTTP 请求 —— 无需重启 |
| index.js、cordis.patch.yml | profile 重启之后 |
| client.js、client.css | 页面刷新之后（bundle URL 带内容修订号） |

开发

npm run build # 把 lib/graph.js 与 client.css 内联进 client.js
npm run check # 对 client.js 做语法检查，并确认它与源文件同步
npm run verify # 跑全部离线套件（需要 pwsh）

client.js 是提交进仓库的构建产物：它是一个手写的 window.__ModuleLoader__ 包外壳，tools/build-client.mjs 把 lib/graph.js 和 client.css 内联进它内部的标记之间。请改那两个源文件，不要改内联出来的副本，然后跑 npm run build。

验证

pwsh tools/verify-offline.ps1 [仓库路径] # 232 项检查，无需服务

node tools/serve-routes.mjs 19417 # 真实路由表，不启动 app
pwsh tools/verify-live.ps1 -Base http://127.0.0.1:19417/api/dsh-git # 42
pwsh tools/verify-routes.ps1 -Base http://127.0.0.1:19417/api/dsh-git # 30

| 套件 | 覆盖范围 |
| tools/verify.mjs | parseLog 的分帧、车道分配及其不变量、edgePath、浏览器半的模块外壳与两个 slot 注册、渲染出的元素树，以及复制菜单和引用操作控件跑过它们真实的状态机。 |
| tools/verify-host.mjs | 整个 Host 半对真实仓库跑端到端：发现、status、refs、log、提交详情、diff、补丁渲染，以及每一条拒绝路径 —— 13 个非法引用名、重名、未知 kind、不存在的提交。写路径跑在它自己创建并清理的临时仓库上。 |
| tools/verify-reload.mjs | lib/live.js 确实会重新 import 变化过的字节 —— 整个热加载故事都依赖这一点。 |
| tools/verify-live.ps1 | 对正在运行的 profile 或本地 harness 逐个打全部路由。 |
| tools/verify-routes.ps1 | 通过真实 HTTP 验证 /ref 与 /patch：方法与 CSRF 拒绝、创建成功、重名拒绝，以及工作区和 HEAD 未被改动。 |

tools/make-demo-repo.ps1 会生成前两个套件所用的测试仓库 —— 一个刻意构造的合并拓扑：两条 feature 分支、一次嵌套合并、一个附注标签和一条 hotfix 分支。

为什么要一个 harness。 新加到 lib/routes.js 里的路由，在已经跑起来的 profile 中要等重启才存在，所以 tools/serve-routes.mjs 把同一张路由表挂在一个一次性端口上。它只增加了精确路径分发；它回答的一切都出自插件自己的 handler、guard 和 CSRF 检查。

为什么没有套件去捕获子进程的 stdout。 开发沙箱不允许 execFile 和 spawnSync 需要的管道，所以每个套件都让 git 的输出经文件绕行。被测代码本身没有变化。

这些套件不能证明的：像素。渲染、主题解析和滚动都需要真实页面。

参与贡献

欢迎提 issue 和 PR。两条底线：

- client.js 是生成出来的。 请改 lib/graph.js 或 client.css 然后跑 npm run build；直接编辑内联区域的 PR 会被要求重新生成。
- 新增写操作需要先给出安全方案。 如果你想要 cherry-pick 或 reset，请先开一个 issue 描述确认流程、冲突处理和前置检查怎么做 —— 原因见上文「它会写什么」一节。

许可证

MIT © 2026 songgms

DeepSeek Harness 是 DeepSeek 开发的独立项目；dsh-git-graph 是对其插件生态的独立贡献。

本插件是 DeepSeek Harness 的插件。