@nateec/dsh-gitkraken

Readme

<div align="center">

# dsh-gitKraken

### DeepSeek Harness 里的可视化 Git Graph、Agent 工作区与安全 Git Workbench

[![GitHub stars](https://img.shields.io/github/stars/nateEc/dsh-gitKraken?style=flat-square&logo=github&label=Stars)](https://github.com/nateEc/dsh-gitKraken/stargazers)
[![Version](https://img.shields.io/badge/version-0.4.0-2dd4bf?style=flat-square)](https://github.com/nateEc/dsh-gitKraken)
[![DSH](https://img.shields.io/badge/DeepSeek%20Harness-%3E%3D%200.1.1--rc.2-f59e0b?style=flat-square)](https://github.com/deepseek-ai/DeepSeek-Harness)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D%2022.19-43853d?style=flat-square&logo=nodedotjs&logoColor=white)](package.json)
[![License](https://img.shields.io/github/license/nateEc/dsh-gitKraken?style=flat-square)](LICENSE)

无需离开当前 DSH 会话，就能读懂仓库历史、审阅改动、管理 WIP，并在多个 Worktree 与 Agent 会话之间快速切换。

[功能概览](#功能概览) · [界面导览](#界面导览) · [安装](#安装) · [使用](#使用) · [安全边界](#安全边界) · [Roadmap](docs/ROADMAP.md)

</div>

![dsh-gitKraken Git Graph overview](docs/images/graph-overview.png)

## 为什么做这个项目

DSH 很适合让多个 Agent 在不同 Worktree 中并行工作，但终端里的 `git log` 很难同时回答这些问题：

- 当前分支是从哪里分出来的，哪些提交已经合并？
- 这次 WIP、某个分支和某个历史提交之间到底差了什么？
- 哪个 Worktree 还有未提交改动，对应的 DSH 会话和 AgentTeams 任务在哪里？
- Rebase、Undo Commit 或解决冲突前，能否先看清影响，并留下一条恢复路径？

`dsh-gitKraken` 把这些信息放进 DSH 原生的 **Git Graph** 标签页：历史图谱负责理解仓库，Agents 页面负责理解并行工作，Workbench 负责执行有护栏的 Git 操作。

## 功能概览

| 区域 | 能力 |
| --- | --- |
| **Graph** | 多分支 DAG、分支/标签/远端引用、作者与变更统计、服务器端分页、Repository Sonar Minimap、缩放与跳转 |
| **Search & Filter** | `message:`、`author:`、`file:`、`change:`、`commit:`、`@me`，支持大小写、正则、全词匹配和跨分页结果导航 |
| **Inspect & Compare** | 提交详情、历史文件 Diff、完整 Patch、Multi-diff，以及 Commit / Branch / WIP 任意两点 Compare |
| **WIP & Commit** | 逐文件暂存/取消暂存、Stage All、Unstage All、Copy Patch、Commit Composer、创建与切换分支 |
| **Agent Workspaces** | 多 Worktree WIP、AgentTeams Kanban、Agent Activity、普通与子代理 DSH 会话状态及直达链接 |
| **Safe Workbench** | Stash、Undo Commit、Rebase 预览、恢复引用、冲突的 ours/theirs 选择、Continue / Abort |
| **DSH Model Tools** | 使用当前 DSH 会话 Provider 生成 Review、Explain 与 Changelog，不读取或复制模型 API Key |
| **Remote** | Fetch、仅快进 Pull、普通 Push；可选的 GitHub/GitLab Pull Request Provider 默认关闭 |

### 图谱不是一张静态图片

- 每页加载历史，搜索最多扫描 5,000 条提交并返回前 200 个匹配结果。
- Minimap 显示 HEAD、引用与搜索 markers，可点击跳转并调整图谱密度。
- 分支与引用可以 Focus、Pin、Hide；提交列表可切换当前分支、本地分支、引用节点或淡化合并。
- Changes 支持 Bar、Numbers、Squares、Bipolar 四种显示，并可隐藏列或启用 Compact 模式。

## 界面导览

### Compare 与 Multi-diff

选择任意 Commit、Branch 或当前 WIP 作为起点和终点，直接查看 ahead/behind、文件清单、单文件 Diff 与完整 Multi-diff。

![Compare a commit with the working tree](docs/images/compare-multidiff.png)

### 多 Worktree 与 Agent 会话

每个 Worktree 独立显示 WIP；AgentTeams 任务按 Blocked、Ready、In progress、Done 映射到 Kanban，并持续同步 DSH 会话状态。

![Worktree WIP, AgentTeams board and DSH sessions](docs/images/agent-workspaces.png)

### Safe Git Workbench

高风险操作先预览、再精确确认。Rebase 会在 `refs/dsh-gitkraken/recovery/*` 下创建恢复引用；恢复操作只创建新的本地分支，不执行 hard reset。

![Safe Git Workbench](docs/images/safe-workbench.png)

### 可调的图谱密度

按仓库规模和审阅习惯切换列、Compact 模式与 Changes 视觉编码；界面自动跟随 DSH 的暗色/亮色主题变量。

![Graph layout and change visualization settings](docs/images/graph-customization.png)

## 安装

### 要求

- Node.js `22.19.0` 或更高版本
- DeepSeek Harness `0.1.1-rc.2` 或兼容版本
- 一个由 DSH 注册、且包含 `.git` 的本地工作区

### 加入 DSH Web profile

建议固定到已验证的 Git commit，而不是跟随浮动分支：

```json
{
  "dependencies": {
    "@nateec/dsh-gitkraken": "github:nateEc/dsh-gitKraken#1b7cda88f3bba07e859a653d15d46b9db2238e14"
  }
}
```

或者在目标 profile 中执行：

```bash
pnpm add '@nateec/dsh-gitkraken@github:nateEc/dsh-gitKraken#1b7cda88f3bba07e859a653d15d46b9db2238e14'
```

包内已经声明 DSH bundle metadata 和 `cordis.patch.yml`，不需要手写 Cordis patch。安装完成后，用你的 profile 固定版本启动器重启 DSH；例如 `my-dsh` 使用：

```bash
./scripts/dsh.sh web
```

打开任意 Git 工作区的会话，顶部就会出现 **Git Graph** 标签页。

> 本 README 使用 Git commit pin，确保安装结果可复现。

## 使用

1. 在 DSH 中打开一个真实 Git 仓库的会话。
2. 切换到 **Git Graph**。
3. 在 **Graph** 中搜索、筛选、选择提交或 WIP；右侧 Inspector 会显示文件和 Diff。
4. 切到 **Agents** 查看所有 Worktree、AgentTeams 任务与 DSH 会话。
5. 切到 **Workbench** 执行批量暂存、Stash、模型审阅或带恢复点的历史操作。

### Rich Search

| 查询 | 含义 |
| --- | --- |
| `message:fix timeout` | 提交信息包含指定文本 |
| `@me` | 当前 Git 用户提交的内容 |
| `file:src/client` | 改动过匹配路径的提交 |
| `change:token budget` | Patch 中包含指定内容的提交 |
| `commit:db6c94a` | SHA 前缀或完整 SHA |

搜索栏旁可以启用 **Aa**（区分大小写）、**.\***（正则表达式）和 **All**（匹配全部词）。

### 快捷键

| 快捷键 | 操作 |
| --- | --- |
| `⌘/Ctrl + F` | 聚焦搜索框 |
| `⌘/Ctrl + G` | 跳到下一个搜索结果；加 `Shift` 跳到上一个 |
| `↑` / `↓` | 在 WIP 与提交之间移动选择 |
| `R` | 刷新仓库状态 |

## 安全边界

这个插件会执行真实 Git 操作，因此安全约束属于产品功能，而不是附注：

- 后端只接受 DSH 已注册工作区的真实路径，HTTP 接口只允许本机回环访问。
- Git 命令始终使用参数数组执行，不经过 shell 拼接。
- Pull 只允许 fast-forward；Push 不提供 force 模式。
- Undo Commit 仅在干净工作区执行 soft reset，文件变化会保留在暂存区。
- Rebase 要求工作区干净、当前分支非 detached，并在改写前创建恢复引用和精确确认。
- Stash 使用保留式 Apply，不自动 Pop；恢复操作不会执行 hard reset。
- 当前不提供 Discard、删除本地/远端分支、force push 或跳过 hooks。
- 没有遥测或自动更新逻辑。

### 可选 PR Provider

GitHub/GitLab Provider 默认关闭。开启后只访问从 `github.com` 或 `gitlab.com` remote 识别出的仓库：

- 公开仓库无需凭据。
- 私有仓库只读取插件专用的 `DSH_GITKRAKEN_GITHUB_TOKEN` 或 `DSH_GITKRAKEN_GITLAB_TOKEN`。
- Token 不会返回浏览器，也不会复用 DSH 模型凭据。

## 开发

```bash
git clone https://github.com/nateEc/dsh-gitKraken.git
cd dsh-gitKraken
pnpm install
pnpm check
```

`pnpm check` 会依次执行 Host/Client TypeScript 检查、构建和 Vitest 测试。

项目结构：

```text
src/client/   React 界面、图谱布局和 Workbench
src/host/     本机 HTTP 边界、Git runner 与服务层
src/core/     Host/Client 共用类型和 Git 输出解析
tests/        布局、解析、渲染、Bundle 与真实 Git 集成测试
docs/         Roadmap 与 README 截图
```

## Roadmap

当前版本聚焦 Graph 审阅、多 Worktree/Agent 可见性和可恢复的安全操作。Inline/Split/Hunk Diff、文件历史与 Blame、Interactive Rebase、Hunk 级冲突处理等后续计划见 [`docs/ROADMAP.md`](docs/ROADMAP.md)。

欢迎通过 [Issues](https://github.com/nateEc/dsh-gitKraken/issues) 提交 Bug、兼容性报告和功能建议。涉及破坏性 Git 操作的功能，需要同时给出预览、确认、恢复路径与集成测试方案。

## 致谢与商标

信息架构参考 [GitLens Commit Graph](https://help.gitkraken.com/gitlens/commit-graph/) 的高密度审阅工作流，但界面、图标与实现均为本项目原创，不包含 GitLens/GitKraken 商标或专有素材。

GitLens 与 GitKraken 是 GitKraken 公司的产品与商标。本项目与 GitKraken 公司无关联，也未获得其背书。

## License

[MIT](LICENSE)