dsh-git-vcs

dsh plugin --profile web add dsh-git-vcs

dsh-git-vcs

DSH Web GUI 的 Git 版本管理插件：在右侧栏新增「版本管理」页，功能与界面参照 IntelliJ IDEA 的

Version Control 工具窗（Alt+9）与 Commit 工具窗（Alt+0）——本地变更与勾选提交、提交树与提交详情、

分支 / 远程 / 贮藏管理、git 命令流水。

版本与兼容性

项目 · 值

插件版本 · 0.2.0

仓库 / 分支 · <https://github.com/TiChuXiXi/dsh-git-vcs/tree/main>

npm 包名 / 插件行 id · dsh-git-vcs / git-vcs

兼容的 DeepSeek Harness · @deepseek-ai/dsh ≥ 0.2.1-alpha.2；验证基线为官方 master 提交 d743267388641bc76f17c45ce8b4c231aed1d32c

依赖的官方插件 · @deepseek-ai/dsh-client-ui-sidebar-right（随 web-app 分发，已验证 0.2.1-alpha.2）

依赖的 host 服务 · subprocess（跑 git）、connection（RPC 信任栅栏）、webServer（注册 /git-vcs 路由）

依赖的 client 能力 · sidebarRightTabs（注册 tab 类型）、slots（sidebar.right.pane.tab / .title）、标准 props sessionId + useSessions（取会话工作目录）

git · 2.x；argv 调用（不进 shell），从 PATH 解析或由配置 gitPath 指定

Node.js · ESM；要求 ≥ 22.12.0，本次 macOS 验证 v24.18.0

构建 · 零构建：无编译步骤、无运行时依赖（host 半区不 import 任何 @deepseek-ai/* 值）

2026-10-12 查询时，官方仓库最新版及 npm alpha 为 0.2.1-alpha.2，npm latest 仍为

0.2.0-rc.2。本次以官方仓库最新版为验证目标，旧宿主未列入本版支持范围。

session 作用域的 sessionId + useSessions、右侧栏槽位和 subprocess 接口仍适用。

完整验证记录和未覆盖范围见 兼容性测试报告。

快速开始

先准备 Node.js ≥ 22.12.0、Git 和兼容的 DSH：

npm install -g @deepseek-ai/dsh@0.2.1-alpha.2
dsh plugin --profile web add dsh-git-vcs@0.2.0 --registry=https://registry.npmjs.org
dsh web

在浏览器右侧栏的「+」或引导入口中选择「版本管理」，打开已有 Git 仓库所在的会话。

若 DSH 已经运行，安装或升级插件后必须重启进程，再刷新浏览器。

本插件安装到 DSH 的 web profile；单独执行 npm install -g dsh-git-vcs 不会注册插件。

升级注意： 0.2.0 提高了宿主和 Node.js 最低版本，不保证兼容 DSH 0.1.x。

仍使用 DSH 0.1.7 的用户请保留插件 0.1.2；不要只升级插件而保留旧宿主。

声明的最低版本不代表已验证所有未来版本；本次实际验证基线为上表所列固定版本。

[安装与升级](#安装) · [使用方法](#使用方法) · [配置](#配置) · [安全边界](#安全边界) · [自检与排障](#自检与排障)

更新记录

版本 · 主要变化

0.2.0 · 对齐 DSH 0.2.1-alpha.2；加固 RPC 请求校验及取消传播；修复首次提交前取消暂存、通配符文件误操作、仓库路径逃逸；贮藏支持包含未跟踪文件并准确报告空操作；补齐跨平台测试与完整宿主集成测试

0.1.2 · 适配 DSH 0.1.7：会话工作目录改从 session 作用域的标准 prop sessionId + useSessions 选择器取（0.1.7 的 SessionListState 移除了旧的 current 字段，旧写法导致面板永远停在「（未加载）」）；两个探针夹具同步成 0.1.7 的真机 props 形态，避免"夹具与真机漂移、自检全绿而真机红"

0.1.1 · 提交树覆盖所有分支并支持滚到底续拉（issue #1，--all + --skip，单页 50 / 上限 2000 行）；提交树从单轨画法改成多泳道图（对齐 git log --graph / IDEA，分叉与汇合画在真正的分叉提交上）；修掉两处真机几何错位（斜线层 SVG 高度按 viewBox 比例算成 100px、连线比圆点偏右 1px）；目录不是仓库时整页换成居中空态 + 一键 git init（issue #2，可选初始分支名）；新增真浏览器几何/空态自检 scripts/dom-probe.mjs（18 条断言）与「客户端调用的端点 host 侧都存在」的结构性断言

0.1.0 · 首个发布版：右侧栏「版本管理」页（Local Changes / Log / Console / Branches / Remotes / Stash）、按文件勾选提交、推送与凭据兜底、自挂 /git-vcs RPC 路由

插件说明

提供什么

• 一个右侧栏 tab 类型：版本管理（同时在右侧栏引导页注册一个胶囊入口，order: 20），

内容全部由本插件渲染；分栏、全屏、展开/收起由官方 @deepseek-ai/dsh-client-ui-sidebar-right

（右侧栏的停靠面与 header 展开控件）提供，本插件不碰布局。

• 一条 host RPC 通道 /git-vcs（端点见下表）：所有 git 调用都在 host 进程里以 argv 形式执行。
• 六页功能：Local Changes / Log / Console / Branches / Remotes / Stash。
• 目录不是仓库时：整页换成居中的空态 + 「在当前目录初始化 Git 仓库」按钮（repo/init）。

形态与文件

单包双半区、零构建（手写闭包工厂，无 tsdown、无运行时依赖）：

半区 · 文件 · 职责

host · index.js · 用 ctx.subprocess 执行 git；自己注册 webServer 前缀路由 /git-vcs 暴露端点；写操作门禁；repo/snapshot 一次刷新一次往返

浏览器 · lib/client.js · 注册右侧栏 tab 类型 + 正文（sidebar.right.pane.tab[.title]）；IDEA 风格 React UI（React.createElement，无 JSX）

组合层 · cordis.patch.yml · 插件行 git-vcs：inject: [subprocess, connection, webServer] + config

作用范围

当前会话的工作目录（session.cwd），语义等同 IDEA 的「项目根」——换会话即换仓库；

也可以在面板顶部手填绝对路径后点「打开仓库」。配置 repoRoot 可把它限定在某个仓库根之下。

RPC 端点

浏览器侧统一 ctx.connection.rpc.call('/git-vcs', endpoint, payload)；失败返回稳定错误码

（git-vcs/bad-request、git-vcs/not-a-repo、git-vcs/write-disabled、git-vcs/auth-required、

git-vcs/network、git-vcs/timeout、git-vcs/git-failed …）。

端点 · 作用 · 门禁

repo/info · 仓库根、分支、upstream、ahead/behind、git 版本、remote.origin.url、插件配置回显 · —

repo/snapshot · 一次刷新所需的全部数据（status + log + 本地/远程分支 + stash + 版本 + remote），host 侧并发探测；all: true 时提交列表覆盖所有分支 · —

repo/init · 把目录初始化为 git 仓库（初始分支名可传 branch）；已是仓库根返回 already: true，仓库内子目录直接拒绝 · write

status · git status --porcelain=v2 → 按「冲突 / 已暂存 / 已修改 / 未跟踪」分组 · —

diff · 单文件统一 diff；staged 取 index、untracked 走 --no-index、其余取工作区 · —

log · 提交列表（limit / skip 分页、all 覆盖所有分支、可按 branch / path 过滤） · —

show / show/file · 提交元数据 + 文件列表 / 单个文件的 diff（按需拉取） · —

branches · 本地 + 远程分支（hash、upstream、ahead/behind；过滤 origin/HEAD 符号引用） · —

remote/list · git remote -v · —

remote/add · 新增远程（可同时给出用户名/密码，加完即存凭据） · write

stash · action: list / push / pop / apply / drop · push/pop/apply/drop → write

console/list · git 命令流水（argv、退出码、耗时、stderr、是否截断） · —

stage / unstage · git add / git restore --staged · write

commit · git commit（可 amend）；带 paths 时先 git add -- <paths> 再按 pathspec 提交 · write

checkout / branch/create / merge · 切换或新建分支、合并 · write

branch/delete · 删除分支（-d / -D） · dangerous

fetch / pull · 抓取（--prune）/ pull --no-edit（Update Project） · write

push · 推送：直推 → SSL 后端兜底 → 认证兜底 · push

credential/approve · 把用户名/密码（Token）存进 git 凭据助手 · write

discard / revert / reset / cherry-pick / remote/remove · 丢弃改动、回滚提交、重置、拣选、删远程 · dangerous（remote/remove 为 write）

安装

1. 从 npm 安装（推荐）

在 macOS / Linux 终端或 Windows PowerShell 执行：

dsh plugin --profile web add dsh-git-vcs@0.2.0 --registry=https://registry.npmjs.org
dsh --profile web --dump-config

输出中应包含 dsh-git-vcs 的配置层。Windows 若找不到 dsh，请确认 npm 全局可执行目录在 PATH 中，

不要直接复制其他机器的用户目录。

更新到新版本

升级前先满足本页的 DSH / Node.js 要求，再执行上面的指定版本安装命令。

已有的精确版本或 ^0.1.x 依赖不会自然跨到 0.2.0，明确指定 @0.2.0 可避免停留在旧版本。

安装命令也可将原本的本地路径依赖替换为 registry 包。

升级后重启 dsh web 并刷新浏览器。使用镜像源时可能存在同步延迟，排障时显式使用 npm 官方源。

可通过以下命令查看官方源的实际版本：

npm view dsh-git-vcs version --registry=https://registry.npmjs.org
`

…(truncated)