前言¶

DSH 的理念是「一切皆插件」，但日常用 DSH 做开发时，看仓库状态还是得切到终端敲 git status、git log、git diff。状态散落在终端和 GUI 之间，分支切错、漏看变更的情况并不少见。dsh-git-control（插件名 wx-98/dsh-git）把这个流程搬进了 DSH 右侧栏：一个类 VSCode「源代码管理」面板，带提交图、分支切换、hunk 级暂存和逐文件 diff。

这个插件由 wx-98 维护，是 Cordis 插件 bundle（Host 半边 + Web Client 半边），不是皮肤、不是 TUI，也不是独立桌面客户端。它解决的是「在 DSH 界面内完成大部分常见 Git 操作」这件事。

插件定位¶

插件名：dsh-git-control（目录页与 GitHub 仓库名写作 DSH-GIT，维护者 wx-98）。

一句话职责：在 DSH Web/Desktop 的右侧栏与会话头部提供类 VSCode/IDEA 的 Git 源码管理。

• 分类：客户端插件（Cordis bundle，浏览器半边注册右侧栏标签）
• 前置：DSH Web/Desktop 0.2.1-rc.5，依赖右侧栏标签扩展点 sidebarRightTabs + sidebar.right.pane.tab 槽位
• 依赖：本机 git CLI（需在 PATH 中，或安装在 Windows 默认路径）
• 许可证：MIT
• 无构建步骤、无运行时依赖

安装前请自行检查源码与许可证——插件以当前 DSH 进程的权限运行，Host 半边会调用本机 git。

Host 与 Client 的共同工作方式¶

插件是一个双面 bundle：

1. Host 半边（index.js）在 DSH 进程内注册 /git/* HTTP 路由，只通过 git CLI 操作仓库，不直接读写 .git 内部文件。
2. 浏览器半边（client.js）在右侧栏注册 git 标签类型，提供 Git 面板、提交图、diff 视图与头部分支芯片。
3. 请求先过 DSH 的连接信任栅栏（ctx.connection.requestRejection，Host/Origin 校验 + 登录 cookie），未认证返回 401/403。
4. 路径参数必须是仓库相对路径，.. 上跳、绝对路径、NUL 一律拒绝；discard 需要显式 confirm: true。
5. 写操作（stage/unstage/discard/commit/checkout）串行执行，避免并发互相踩；插件不产生任何模型可见事件。

核心功能¶

下面按 README 能力清单逐条列出，均已核实。

会话头部分支芯片。 会话标题栏直接显示 ● main 3（分支 + 变更数 + ahead/behind），点开是工作区变更摘要，不必打开面板就知道在哪个分支。

当前分支状态。 分支名、当前 commit、上游分支、ahead/behind 计数；detached HEAD 与空仓库都能正确显示。

VSCode 风格配色。 状态字母按语义着色（M 琥珀、A/未跟踪 绿、D 红、R/C 蓝、冲突 橙），文件名跟随状态着色，深浅主题各有一套，HEAD -> main 与远端引用各有颜色。

提交图（GRAPH）。 历史列表左侧绘制彩色泳道（圆点 + 竖线 + 合并/分叉曲线）；普通分支用 8 色调色板，HEAD 所在分支线用强调色并加大圆点加描边环，列号跨行稳定、分支线不跳色。

分支面板。 点芯片即开：当前分支段（upstream / ahead / behind / 变更摘要）+ 切换分支（本地分组、当前打勾，点击即 checkout）+ 分支操作（创建 / 重命名 / 删除，删除有二次确认且禁止删当前分支，未合并需强制删除）。

IDEA 风格变更树。 按目录折叠/展开，每个文件带 +N/-N 行数，四分组（已暂存/变更/未跟踪/冲突）不变。

hunk 级暂存。 diff 内每块可「暂存此块 / 取消暂存此块」，只把该块应用到索引。

提交增强。 amend 上一个提交 + 最近 10 条提交信息复用（本地保存）。

stash。 列表 / 创建 / 应用 / 弹出 / 删除，弹层内操作，删除需确认。

历史过滤与导航。 按提交信息 / 作者 / 路径过滤，条件可见且可清除，另支持日期范围过滤与 ↑/↓/Enter 键盘导航；「日志范围」与「切换到此分支」是两个独立动作。

逐文件 diff。 结构化 unified diff（hunk + 行号 + 增删着色），支持工作区 / 已暂存 / 未跟踪（合成）/ 指定提交四种视角；二进制文件有明确提示；大 diff 超过 4000 行会被截断并提示。

写操作。 暂存、取消暂存、放弃变更（二次确认）、填写提交信息并提交（Ctrl/Cmd+Enter）。

提交历史（IDEA 风格）。 左侧分支树（HEAD / 本地 / 远端，点击只改日志范围不改 HEAD）+ 右侧列式列表（图 / 主题+refs / 作者 / 日期 / 短哈希）；合并提交斜体弱化、HEAD 行强调；提交详情含完整 sha、正文、变更文件与增删行数。

自动刷新。 面板可见时变更列表每 4s 轮询；所有写操作成功后立即重新拉取。

多语言与主题。 中文 / 英文文案，跟随宿主主题（深色 / 浅色）。

说明：README 末尾的「已知限制」一节仍写着「暂不支持分支创建/删除、stash、hunk 级暂存」，与上文能力清单及 package.json 描述直接冲突，判断是过期文字。清单里未出现的仍是真限制：pull/push/fetch、三方冲突解决界面、文件历史（blame）、子模块视图。

安装与启用¶

从 npm 安装（推荐）¶

当前 npm latest 为 dsh-git-control@0.4.6（README 发布状态一节仍写 0.4.0）。

dsh plugin --profile desktop add dsh-git-control

从 GitHub 安装¶

dsh plugin --profile desktop add github:wx-98/DSH-GIT

本地目录安装（开发用）¶

GUI 操作：Plugins → Add plugin → 本地绝对路径，填本仓库目录，安装后在 Plugins 页启用 dsh-git-control 这个 bundle row，刷新页面。

本地目录以 link 方式安装：改动 client.js 刷新页面即生效；Host 半边改动需重启应用后生效。

desktop profile 由 Electron 应用独占管理，CLI 会拒绝操作。此时用 GUI 安装，或运行仓库内的一键脚本：

pwsh -File .\tools\install-desktop.ps1              # 安装，重启 DSH 后生效
pwsh -File .\tools\install-desktop.ps1 -LivePatch  # 额外写 live patch，让运行中的实例立刻热加载 Host 半边
pwsh -File .\tools\install-desktop.ps1 -RemoveLivePatch

典型用法¶

Git 面板以会话 cwd 为仓库根，所以先确认打开的会话工作目录是目标仓库：

1. 打开任意会话；
2. 打开右侧边栏 → 点 + → 在标签向导里选 源代码管理（标签标题显示为 Git + 当前分支）；
3. 变更标签：填写提交信息 → 暂存/放弃文件 → 提交；
4. 历史标签：浏览提交、点开看详情与逐文件 diff；
5. 顶部摘要行的刷新按钮可手动刷新，分支下拉可切换分支（git checkout <branch>）。

开发与验收命令：

node --test test/                                        # Host + Client 测试
node tools/verify-installed.mjs "http://127.0.0.1:PORT/?token=XXXX"   # 对真实运行中的 DSH 实例做端到端自检

自检脚本会用启动 token 换 cookie，断言插件已进入客户端入口图，拉取被 /plugins 服务的浏览器半边，造临时仓库并逐条驱动 /git/* 路由，最后断言连接栅栏。

适用场景与注意¶

适合：

• 在 DSH Web/Desktop 界面内完成日常提交、暂存、查历史、切分支的人；
• 需要 commit graph 和 hunk 级暂存、又不想离开 DSH 的人；
• 想给 DSH 右侧栏加一个 Git 面板的插件开发者，可以拿 docs/contract.md（Host ⇄ Client 接口契约）当参考。

注意：

• 目标版本是 DSH 0.2.1-rc.5，插件依赖其公开扩展点（sidebarRightTabs、slots、webServer、connection、locale），DSH 升级后建议重新回归。
• 需要本机 git 在 PATH 中（或装在 Windows 默认路径）。
• 不支持 pull/push/fetch、三方冲突解决界面、文件历史（blame）、子模块视图。
• 大 diff 超过 4000 行会被截断。
• 插件以当前 DSH 进程权限运行，安装前应检查源码与许可证（MIT）。
• 社区目录（SkillHub）是独立站点，与 DeepSeek / 幻方无官方从属关系，不属官方应用商店。

结尾¶

dsh-git-control 的价值在于把 VSCode/IDEA 里那种 Git 面板完整搬进 DSH 右侧栏，并额外提供了会话头部分支芯片与提交图泳道，减少在终端和 GUI 之间来回切换的次数。发布状态方面，npm dsh-git-control@0.4.6、MIT 许可证、awesome-dsh-plugin 已收录（PR 已合并）。

目录页：https://www.skillhub.cn/plugins/wx-98/DSH-GIT
GitHub：https://github.com/wx-98/DSH-GIT