@samecorner/dsh-git-graph

Readme

# dsh-git-graph

GitKraken / vscode-git-graph 风格的 **提交图插件**，跑在 DeepSeek Harness（dsh）web GUI 里：分支、合并、标签泳道直接渲染成会话中的交互卡片，点开还能看每提交的文件改动与着色 diff。

参考实现：`pi-web-git-graph`（pi-web 工作区面板插件）。

## 它能做什么

- **提交 DAG 图**：按 `git log --all --topo-order` 绘制（默认最近 500 条），自动分配泳道，首个父提交同列直连、合并父提交曲线连接；分支/标签用彩色 pill 标注在提交右侧；HEAD 用高亮环。
- **提交详情**：点任意行 → 展开作者、邮箱、时间、父提交、完整哈希（一键复制）。
- **diff 卡片**：让助手执行 `git_show` 工具，会话里直接渲染变更文件列表（A/M/D/R 状态徽章）+ 绿加红减的完整补丁（超长自动截断）。
- **只读安全**：两个工具都是只读的；检出/新建分支等写操作请在你的终端里做（卡片底部有提示）。

## 安装

```sh
dsh plugin --profile web add @samecorner/dsh-git-graph
```

`dsh plugin add` 会把包 reconcile 进 profile 的 bundle 层：服务端工具注册进 cordis 宿主，浏览器 half 由 `dsh.client` 声明自动编入 web 启动图。重启 web 即生效。

## 使用

在会话里用自然语言触发（助手会自动调用工具）：

- 「显示当前仓库的提交图」→ `git_graph`
- 「看看提交 aabbccd 改了什么」→ `git_show`

工具在 **会话工作目录**（`session.header.cwd`，与官方 tool-bash 同源）执行，也可传 `workdir` 指向任意仓库。模型得到的是一行文本摘要，浏览器端渲染的是完整 JSON（通过工具声明的 `output.presentationMeta` 投影到 `tool/result` 事件，再由 keyed tool view 读取——全程无二次请求）。

## 架构

```
┌─ npm 包 @samecorner/dsh-git-graph ──────────────────────────────┐
│  lib/index.js   server half（cordis 插件，bundle 层 insert）       │
│    ├─ git_graph  工具：git log --all --parents --topo-order        │
│    │              + for-each-ref（peel 标签）→ 规范 JSON            │
│    ├─ git_show   工具：diff-tree --name-status -r + git diff       │
│    └─ output.presentationMeta = value（投影给浏览器）              │
│  lib/client.js   browser half（dsh.client 声明编入启动图）         │
│    ├─ tool.call.toolview keyed 'git_graph' → GitGraphView（SVG）   │
│    └─ tool.call.toolview keyed 'git_show'  → GitShowView（diff）   │
└──────────────────────────────────────────────────────────────────┘
```

- 工具契约依据官方文档 `docs/user/develop/basic/tool.md` 与 `docs/cookbook/adding-a-tool.md`（`defineTool` / `output.schema` / `render` / `presentationMeta`）。
- toolview 槽位依据 `dsh-client-ui-tool` 的 `tool.call.toolview`（keyed，key 域开放，可接管任意工具名的渲染）。
- UI 主题跟随宿主：样式层全部映射 `--dsw-alias-*` 变量（亮/暗色自动适配），中英双语。

## 与 pi-web 参考版的差异（为什么 dsh 版更简单）

| | pi-web-git-graph | dsh-git-graph |
|---|---|---|
| 数据通道 | 终端命令写缓存文件 → `WorkspaceFiles` 读回（API 无 stdout） | `spawn('git')` 直接拿 stdout，无缓存文件 |
| 渲染位置 | workspace 面板（自定义元素） | 会话内 keyed toolview 卡片（React + 宿主主题） |
| 交互 | checkout / 新建分支 | 只读（写操作留给终端） |
| 泳道算法 | `assignLanes`（首个父同列、合并父新列、根释放） | 同算法移植（TS + 防御式类型） |

## 开发

```sh
npm install
npm run typecheck && npm run build && npm test
```

测试：`server-selftest.mjs`（真实 git 端到端，grep 本仓库历史）、`smoke-loader.mjs`（模块表物化）、`render-test.mjs`（SSR 渲染两个视图）。

已知限制：
- 默认取最近 500 提交（`maxCount` 可调至 2000）；窗口外的父提交画成开口箭头。
- 泳道分配为近似算法（线性历史单泳道、分支按 tip 封顶），拓扑正确但不保证与 vscode-git-graph 完全一致的紧凑度。
- `git_show` 对合并提交显示其相对首个父提交的差异。
- 依赖宿主 `tools` 服务与 `tool.call.toolview` 槽位（dsh ≥ 0.1.0-rc.6）。

## License

MIT