Git 面板 relaxyabc/dsh-GitPanel

GitPanel

DSH Web 客户端的 Git 管理插件 —— 在左侧面板栏打开一个全页三栏 Git 工具(分支 / 历史 / 提交详情),右侧边栏的 Git 胶囊只负责把面板打开。类似 IntelliJ 的 Git 工具窗口,以 DSH 插件 bundle 形式挂载。

1. 这是什么、跑在哪、怎么用

是什么

| 项 | 值 |
| 包名 / 版本 | GitPanel / 0.2.0(private,仓库根即包根) |
| 挂载方式 | DSH 插件 bundle(dsh.manifestVersion: 1,client 平台 web) |
| 运行要求 | DSH ≥ 0.1.7-rc.1;使用 Web 客户端的 profile;Host 机器的 PATH 里有 git |
| 依赖 | 无运行时依赖、无构建步骤:Host 半一个文件 + 浏览器半若干分片,交付什么运行什么 |

安装

1. 装进 profile —— dsh plugin 把参数原样转给 pnpm:

dsh plugin --profile add github:relaxyabc/dsh-GitPanel # 从 GitHub(公开仓库,默认分支 main)

GitHub 形式装的是拷贝,升级用 dsh plugin --profile update GitPanel 重新解析(要固定版本就写 github:relaxyabc/dsh-GitPanel#v0.2.0 或 #);本地路径形式装的是指向仓库的链接,改完代码重启即生效,适合边改边用。

2. 在 profile 的 cordis.patch.yml(或以 --patch 叠加层)里插入下面的块 —— 包内 cordis.patch.yml 即此内容:

- insert:
- id: GitPanel
name: 'GitPanel'

3. 重启 profile(启用 dsh-hmr 时自动重载)。

使用

- 左侧面板栏的 Git 图标 → 全页三栏面板:左(分支 + 改动 + 提交框)、中(历史)、右(上:提交信息,下:该提交的文件改动)。
- 右侧边栏的 guide 胶囊里也有 Git:点击即打开全页面板并关掉那张标签页(布局按会话持久化,留下的标签页会跨刷新复活)。若控制器拒绝关闭,标签页里只显示一张不读仓库数据的兜底卡片。
- 顶栏常显工作区目录与仓库字段(下拉可切换,悬停见完整路径),当前分支以芯片展示并带 ahead/behind 计数;面板打开时自动选中当前会话所在的工作区,切换会话后面板跟随。
- 提交信息框里 Ctrl/Cmd+Enter 直接提交。危险操作(hard reset、删除分支)有确认对话框;成功提示 4 秒后自动消失。

配置

配置在插件页面「已安装」分组里的 GitPanel 上(本包自己的配置位,不占官方分组),分「仓库发现」「差异显示」「文件预览」三组;输入后按「保存」写入 profile,三个字段都即时生效、无需重启。

| 配置项 | 类型 | 默认 | 说明 |
| discoveryDepth | number(1–8) | 3 | 仓库发现向下递归的目录层数;运行时始终夹取在该区间内 |
| wholeFileDiff | boolean | false | 开启后 diff 左右两栏显示整个文件而不只是改动片段 |
| filePreviewFix | boolean | true | 修复 Chromium 上「文件资源服务不可用」的文件预览,见下 |

filePreviewFix 补偿的是 DSH 上游的一个缺陷(discussion #6437):dsh-client-resources 用 new URL(address).hostname 取协议键,而 Chromium 不把非特殊 scheme 的 authority 当作主机(new URL('dsh-resource://file/x').hostname 在 Node 上是 file、在 Chromium 上是 ''),于是每个资源地址都解析不出提供方,右侧边栏的文件预览只剩那句报错。本插件的修复只改 dsh-resource:// 这一类地址(其余地址、相对地址解析、非法地址抛错全部交回浏览器),代价是这类地址不是 instanceof URL、就地改写部件不回写整条地址(面板只读不改)。上游修好后可以关闭本项。

2. 功能清单

仓库与工作区
- 递归发现工作区下的全部仓库与子模块工作树(含位于父仓库树之外的子模块),自动跳过 node_modules、.git、dist、vendor 等目录。
- 多工作区浏览;打开面板自动选中当前会话所在的工作区,顶栏下拉显示与左侧列表一致的名称与完整路径。
- 深度可配置,切换仓库不重新扫描。

分支
- 本地 / 远程分组、可折叠、可按名称过滤;当前分支带 HEAD 标记,显示上游与最新提交说明。
- 右键或双击:Checkout 分支、从远程分支建本地分支、删除分支(默认安全删除)、从任意提交 New branch from here。
- 分支右键菜单的 Merge into 把该分支并入当前分支(合并提交的信息在对话框里预填,可直接编辑),Rebase onto this branch 把当前分支重放到该分支上。二者都先弹确认框(说明工作区必须干净、rebase 会重写提交),冲突时 Git 停下来,面板显示黄色横幅,并给出分支里实际执行的命令按钮:Commit merge / Merge --abort,或 Rebase --continue / Rebase --abort;冲突文件与普通改动一样列在工作区里,解决后 stage 即可。

提交历史与 diff
- 每页最多 200 条(作者、相对时间、ref 装饰);每提交的文件统计在选中该提交时才单独读取,历史列表始终是一次轻量调用。
- 选中提交后右栏显示完整信息(哈希、作者、日期、父提交、正文;可改写最新提交的信息)与该提交的文件列表。
- 双击文件弹出左右双栏 diff（两侧行号、替换行同排对照；二进制与无差异分别提示）；未跟踪文件也能给出内容 diff。
- diff 弹窗自带两条改动导航：左侧改动列表（逐条 + 上一处/下一处），右侧概览条（按位置比例高亮、显示可见范围、点击跳转）；开启 wholeFileDiff 后两栏改为整文件对照。
- 提交右键菜单：Copy hash、Amend message（仅最新提交）、Checkout、Cherry-pick、New branch from here、Reset (soft/mixed/hard)、Revert commit。

工作区改动与提交
- 基于 git status --porcelain=v2 -z 的改动列表：状态字母 + 每文件 +/− 行数，二进制标注。
- 复选框只表示选中（纯本地、不触发 Host 调用）：表头全选（部分选中显示半选态）+「暂存选中 / 取消暂存选中」按钮；右键仍可单文件 stage/unstage、看 diff、复制路径。
- Commit / Commit all（先暂存全部）/ Commit & push 三个按钮，Ctrl/Cmd+Enter 快捷提交；提交信息框的高度随窗口自适应（约 clamp(150px, 26vh, 380px)，即 8–16 行），也可拖拽下边缘自行调整。
- 提交框顶部是占满整行的 Amend 开关；勾选即进入改写模式：信息框自动填入最新提交的信息，该行高亮，按钮变为 Amend / Amend all，git commit --amend 会把已暂存（或全部）内容并入最新提交、并替换其信息；取消勾选会把改写前的草稿还给信息框。改写期间 Commit & push 被禁用 —— 改写后的提交需要强制推送才能发布，面板不提供。
- 提交右键菜单 / 提交信息右键菜单里的「修改提交信息」弹出的改写对话框，其多行输入框同样自适应高度（clamp(150px, 26vh, 360px)），不再是单行小框。这两处既有菜单的文案保持不变 —— 只有提交框里的 amend 控件在中文界面下也用英文 Amend。
- Push（必要时自动 --set-upstream）、Fetch（只下载对象与远程跟踪引用）、Pull（仅当前分支有上游时可用）。
- 暂存、提交、推送只重载相关数据：暂存不会重新扫描工作区或重读历史，因此不会出现整面板「载入中」。

子模块
- 列出全部子模块与状态（initialized / uninitialized / out-of-date / conflicted），一键 init / update / sync（递归）。

界面与语言
- 中英双语：面板内全部文案（含 guide 条目、菜单、对话框、提示）经 DSH locale 服务输出，跟随客户端语言设置实时切换；插件卡片上的包名与描述来自 locale/{en,zh}.json。
- git 命令名不翻译：菜单里的 Checkout / Cherry-pick / Reset (soft|mixed|hard) / Revert commit / Merge / Rebase 在中英文界面下都是这几个词（横幅按钮另按实际调用写作 Merge --abort / Rebase --continue），Amend 也一直保持英文。中文只用在它们的方位与解释上，例如中文界面下的分支菜单是「Merge into main」「Rebase main onto this branch」。
- 全部样式为内联设计令牌（--dsw-alias- + 字面回退值），自动适配明暗主题。

3. 架构与目录结构

两半对等，通过一条认证 Fetch 路由通信：

┌─ 浏览器半 src/client.js + src/client..js ─┐ ┌─ Host 半 index.js ─────────────────┐ │ client.js:注册入口 + 接线 + apply │ fetch│ ctx.connection.fetch.register │ │ client.*.js:包内分片(词典 / 样式 / │ ────▶│ POST /api/local-git │ │ 面板 / 三栏 / diff / 设置卡 / 修复) │ │ (继承 Host/Origin 围栏 + 会话认证) │ │ React,createElement,无 JSX、无构建 │ ◀────│ resolveInside 路径围栏 → execFile(git)│ │ inject: slots/sidebarRightTabs/layout │ └──────────────────────────────────────┘ └─────────────────────────────────────────────┘ JSON

Host 半在仓库根（index.js），浏览器半在 src/（相当于上游包的 lib/）。两半的定位互不相干：Host 半由 exports["."] 决定，浏览器入口由 exports["./client"] 决定 —— 只有分片必须与浏览器入口同级。

通信与操作

// 一个请求一个操作;错误一律 200 + ok:false,400 只用于非 JSON 请求体,413 只用于超过 1 MiB POST /api/local-git { "op": "state", "args": { "workspaceRoot": "E:/ws", "path": "alpha" } }
→ { "ok": true, "data": { … } }
→ { "ok": false, "error": "the path is outside the workspace root" }

| op | 类型 | 作用 |
| repos | 读 | 发现工作区下的全部仓库(含子模块),并回报生效的扫描深度 |
| state | 读 | 当前分支、本地/远程分支、ahead/behind、子模块、全部改动文件 |
| log | 读 | 提交历史(可按分支 / 文件过滤,1–200 条;不含每提交文件统计) |
| commitFiles | 读 | 某一个提交改动的文件与行数 |
| diff | 读 | 单文件 unified diff(可指定 commit、wholeFile;未跟踪文件也能给出) |
| stage / unstage | 写 | 暂存 / 取消暂存指定路径或全部 |
| commit | 写 | 创建提交(--all / --amend) |
| push / fetch / pull | 写 | 推送 / 只下载对象与远程跟踪引用 / 把上游整合进工作区 |
| checkout | 写 | checkout 分支或提交,可顺带新建分支 |
| deleteBranch | 写 | 删除本地分支(默认安全删除) |
| reset / cherryPick / revert | 写 | reset --soft/--mixed/--hard / cherry-pick 一个提交 / 用新提交 revert |
| amend | 写 | 改写最新提交的信息 |
| merge | 写 | 把指定分支并入当前分支(--no-ff / --ff-only / --squash / --no-commit;会提交时必须带信息) |
| rebase | 写 | 把当前分支重放到指定分支上(可 --interactive / --autostash) |
| mergeAbort / rebaseAbort / rebaseContinue | 写 | 解冲突期间的收尾:merge --abort / rebase --abort / rebase --continue |
| submodule | 写 | 子模块 init / update / sync |

参数与语义以 index.js 的 READ_OPERATIONS / WRITE_OPERATIONS 为准(两者合起来就是上表)。

安全与限额

- 路径围栏:所有带 path 的操作都经 resolveInside 解析(Windows 下大小写折叠),越界一律拒绝。
- 认证路由:经 ctx.connection.fetch.register 注册,继承 API 桥的 Host/Origin 围栏与会话认证,不是裸 webserver 路由。
- 无 shell:git 一律 execFile + argv 数组,路径前保留 --。
- 限额:请求体 ≤ 1 MiB;单次 git 60 s 超时、32 MiB 输出上限;发现扫描 ≤ 8 层 / 64 个仓库 / 20 000 个目录项;diff 弹窗最多渲染 3000 行两栏对照(超出给出截断提示)。
- 不做昂贵的投机调用:git submodule status(无子模块的仓库上约 1 s)只在仓库声明了子模块时才执行;每提交的文件统计改为选中时才读。
- 不挂起:GIT_TERMINAL_PROMPT=0、GIT_OPTIONAL_LOCKS=0,失败以数据形式返回;合并与变基的提交信息一律由参数或 Git 已保存的 MERGE_MSG 提供(rebase / rebaseContinue 另带一次性 GIT_EDITOR=:),面板没有编辑器可回答 Git 的提示。
- 不猜测状态:state 顺带报告仓库是否停在某个操作中(inProgress:merge / rebase / cherry-pick / revert / bisect),标记经 git rev-parse --git-path 解析,链接工作树同样正确;合并与变基的冲突路径由 git status --porcelain 读出并写进错误信息。

浏览器半为什么分片

浏览器半没有打包器:DSH 把它当普通脚本加载,client.js 自己调 window.__ModuleLoader__.load({ id, factory }) 注册工厂 —— import 不被允许,DSH 的 require 也只认平台种子与清单里 inject 的包。官方给零构建包留的通道是包内分片:与浏览器入口同级、名字匹配 client..js,自己注册成 { id: 'GitPanel', chunk: 'client.panel.js', factory },再由入口 await require.async('./client.panel.js') 取回。

- 因此 apply 是 async 的,且必须在注册任何席位之前把分片取回来。
- 分片之间不互相依赖,依赖全部由 client.js 的 shared 接线表单向接出去。
- 只改分片时要硬刷新:分片 URL 只带包级版本(DSH 按浏览器入口的 mtime/ctime/size 算),只改分片不会换 URL,浏览器会拿住那份 immutable 缓存。改入口文件本身则会换掉全部版本。

目录结构

dsh-GitPanel/ # 插件包 GitPanel(仓库根即包根) ├─ package.json # 清单:导出映射 / client.inject / files 白名单 ├─ cordis.patch.yml # Host 半的插入补丁 ├─ index.js # Host 半:发现 / git 子进程 / 解析器 / 路由 / 配置图 ├─ icon.svg # 面板图标 ├─ src/ # 浏览器半(分片必须与 client.js 同级) │ ├─ client.js # 入口:词汇表 / shared 接线 / Host 传输 / apply │ ├─ client.panel.js # 整页面板:状态、Host 调用、工具栏、三栏组装 │ ├─ client.branches.js # 左栏:分支、远程、子模块、工作树与提交框 │ ├─ client.history.js # 中栏(历史)与右栏(提交信息与文件) │ ├─ client.rows.js # 变更 / 分支 / 提交行,右键菜单,对话框 │ ├─ client.diff.js # unified diff 解析、改动导航、并排视图与弹层 │ ├─ client.settings.js # 插件页面上的配置卡片 │ ├─ client.preview-fix.js # 资源地址修复及其地址读取 │ ├─ client.sidebar.js # 右侧边栏的门与标题 │ ├─ client.i18n.js # 中英词典 │ └─ client.style.js # 设计令牌样式表与 Git 图标路径 ├─ locale/{en,zh}.json # 插件卡片(插件列表与清单)的包名与描述 ├─ test/ # 四个无框架 Node 测试 + 分片契约替身 └─ README.md / LICENSE / AGENTS.md

开发与测试

无需安装依赖,Node(≥ 18)与 git 即可;四个测试互相独立,全部通过时退出码 0:

node test/host.e2e.mjs # Host 半端到端:临时工作区 + 真实 git + 裸仓库远程,覆盖全部操作与安全拒绝
node test/client.smoke.mjs # 浏览器半冒烟:真实 ModuleLoader 契约 + React 替身 + 假 fetch,驱动面板全部状态
node test/preview-fix.mjs # 文件预览修复:Node 契约 + 真实无头 Chromium 复现(无浏览器时该半 skip)
node test/preview.mjs # 视觉稿:输出 preview/git-panel.html(明暗双主题共 6 幅)

浏览器半在每次页面加载时重新取用,Host 半只在 DSH 进程启动时导入一次:长跑的 dsh web 上刷新页面只更新面板 UI,Host 侧的新操作要重启进程(或让 dsh-hmr 监听本包目录)才生效;面板会识别出旧 Host 并显示橙色横幅。改动前请读 AGENTS.md(架构不变量、代码风格、测试要求与红线)。

License

MIT © 2026 relaxyabc