dsh-git-chain

Readme

# dsh-git-chain

**[English](README.en.md) · 中文**

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

> 当前版本：`0.1.1` · Stable · [GitHub Release](https://github.com/ShinonomeAya/dsh-git-chain/releases/tag/v0.1.1) · 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` 的第一父链。

<p align="center">
  <img src="smoke/01-tab-graph.png" alt="完整 Git 链路图" width="420">
  <img src="smoke/08-tab-first-parent.png" alt="仅主线 Git 链路图" width="420">
</p>

## 功能

### 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`

```sh
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 链路图**。

卸载：

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

Windows PowerShell 示例：

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

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

## 开发与验证

```sh
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/`。

公开协作：[贡献指南](CONTRIBUTING.md) · [安全策略](SECURITY.md) · [变更记录](CHANGELOG.md) · [兼容性矩阵](docs/COMPATIBILITY.md) · [社区收录准备计划](docs/COMMUNITY-SUBMISSION.md) · [固定包生命周期计划](docs/RELEASE-LIFECYCLE-PLAN.md)

## 技术架构

```text
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](docs/ROADMAP.md)。

欢迎通过 [GitHub Issues](https://github.com/ShinonomeAya/dsh-git-chain/issues) 反馈问题或提交改进建议。涉及安全问题，请不要在公开 Issue 中发布敏感信息。

## License

[MIT](LICENSE)