Skip to content

dsh-plugin-git

Verified

@dsh-electron/dsh-plugin-git · v0.2.9 · MIT · Web UI

Portable Git repository service and DSH client experience

Install

dsh plugin add @dsh-electron/dsh-plugin-git

Confirm the layer applied with dsh --profile default --dump-config — see the install guide.

Source

Creators

Readme


description: "面向 DeepSeek Harness Desktop 与标准 DSH Web profile 的 portable Git repository 操作及 Client UI。" kind: "package-bundle"

dsh-plugin-git

English | 中文

概述

标准 DSH/Cordis Git 插件,包含一项 portable Host service、一份 Client bundle 与 optional Desktop enhancement。同一 package 可在 DeepSeek Harness Desktop 与标准 DSH Web host 中原样运行;npm scope @dsh-electron/ 标识发布者,不是运行时要求。

依赖上游右侧边栏。 支持的 DSH 精确版本以兼容契约为准;这些版本的 Client UI 均自带右侧边栏 @deepseek-ai/dsh-client-ui-sidebar-right。Git 以标准两阶段方式注册三个 sidebar tab type,并通过 ctx.sidebarRight 导航;宿主没有右侧边栏时 Client 半无法加载。旧的第三方 Details Host 插件已废弃,不再被依赖。已验证版本见 DSH 兼容契约。

DeepSeek Harness Desktop 预装本插件,并通过 git subtree 镜像本仓库。用户可在设置 → 插件中禁用 Git;右侧边栏是上游内置项。

目录

DSH 兼容性

已验证的精确版本、开发 pin、宿主 Node 要求和候选升级流程统一见兼容契约。

安装

本包已发布到 npm:@dsh-electron/dsh-plugin-git(当前 0.2.9,MIT,带构建 provenance)。仍处于试验开发阶段:API 与版本保持 pre-1.0,minor 版本之间可能变化。

DeepSeek Harness Desktop — Git 默认预装并启用。不需要仓库 UI 时,可在设置 → 插件中禁用。

DSH Web — 全部已支持版本都提供右侧边栏,因此只装 Git 即可。最短路径是两条命令:

dsh plugin --profile web add @dsh-electron/dsh-plugin-git
dsh --profile web

dsh plugin 在 profile 目录内转发给 pnpm:安装 package,并激活包内 cordis.patch.yml 层,把插件挂进组合。它支持四种安装来源,下表以 web profile 为例:

来源 命令 说明
npm 注册表(推荐) dsh plugin --profile web add @dsh-electron/dsh-plugin-git 预构建产物;无需构建授权
tarball dsh plugin --profile web add ./dsh-electron-dsh-plugin-git-<version>.tgz 预构建离线包;无需构建授权
本地路径 dsh plugin --profile web add /path/to/dsh-plugin-git pnpm 链接该 checkout;适合开发
GitHub / git dsh plugin --profile web add github:cherrchen/dsh-plugin-git 拉取源码并在安装时经 prepare 现场构建;需 allowBuilds,建议锁定 tag

无论用哪种来源,Git client 加载时都要求宿主已提供 ctx.sidebarRight 与 ctx.sidebarRightTabs 两个 service;全部已支持的 DeepSeek Harness 版本都提供它们。

从 npm 注册表安装(推荐)

dsh plugin --profile web add @dsh-electron/dsh-plugin-git

注册表里是预构建产物,安装时不会有任何 package 代码在你的机器上执行。

从 tarball 安装

pnpm pack --pack-destination dist
dsh plugin --profile web add ./dist/dsh-electron-dsh-plugin-git-0.2.9.tgz

pnpm pack 产出上述单一 tarball,每个 tag 的 GitHub Release 都附同一个文件 —— 0.2.9 对应 https://github.com/cherrchen/dsh-plugin-git/releases/download/v0.2.9/dsh-electron-dsh-plugin-git-0.2.9.tgz。它同样是预构建产物,因此适合内网或离线 profile。

从 GitHub 安装

dsh plugin --profile web add github:cherrchen/dsh-plugin-git

git 安装拉取的是源码而非构建产物,因此由本包自带的 prepare 脚本在安装方机器上构建发布入口:pnpm run build 先用 tsc 产出声明,再用 tsdown 打包两个面,只使用本包自带的 standalone tsconfig —— 不假设任何 sibling checkout。pnpm ≥ 10 会先拦下该脚本,首次 add 以 ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED 失败。把 pnpm 打印出的原样包键写入该 profile 的 pnpm-workspace.yaml —— 对 git 依赖而言,该键是包名加上解析后的 git spec 与 commit,裸包名并不匹配:

allowBuilds:
  # 此处填 pnpm 打印出的键
  '@dsh-electron/dsh-plugin-git@git+<host>/<path>#<commit>': true

然后重新执行 add 即可;换 pin 会换 commit,键也随之变化。请把该授权视为允许该 package 在安装时于你的机器上执行代码(且不在 agent 运行的任何沙箱之内)。建议锁定 tag,让后续推送无法悄悄改变实际运行的内容:

dsh plugin --profile web add github:cherrchen/dsh-plugin-git#v0.2.9

从本地 checkout 安装(开发调试)

git clone https://github.com/cherrchen/dsh-plugin-git.git
cd dsh-plugin-git
pnpm install
pnpm build        # 生成 lib/;它未纳入 Git,但安装读的就是它
dsh plugin --profile web add "$PWD"

pnpm 以链接方式接入该 checkout,之后的 pnpm build 无需重装即被采用。

提示:如果你的 DSH 是 clone 源码方式使用(而非全局安装),dsh 不在 PATH 里,请把上述命令中的 dsh 换成 pnpm dsh,例如 pnpm dsh plugin --profile web add …。

与上游右侧边栏配对

Git 通过上游右侧边栏的标准两阶段注册接入 tab-type 体系。Client manifest 只声明 service 依赖:

{
  "dsh": {
    "client": {
      "inject": [
        "@deepseek-ai/dsh-client-ui-sidebar-right"
      ]
    }
  }
}

动态 client plugin 不允许 import 其他 plugin 包的运行时值,只允许 import type;因此类型引用在 bundle 中被完全擦除,external 不再需要。

阶段一——ctx.sidebarRightTabs.register(definition) 注册三个 tab type:git.changes 与 git.graph 是 page type(按 kind 打开,每个 pane 单例),并各贡献一个 guide 条目(Changes order: 11、Graph order: 12),在 guide 页替代旧 Details Launcher 卡片;git.diff 是 resource type,pattern dsh-resource://git/diff/**,canOpen 校验地址可解码,tab 标题取解码出的文件名。可选 Worktrees 与 Remote 条目分别使用顺序 13、14,使所有 Git 入口统一排在“工作区文件”(10)与“新建终端”(20)之间。Graph 使用提交轨道图标;Remote 使用云端与上传/下载箭头图标。

阶段二——每个 tab type 的 body 组件注入 sidebar.right.pane.tab 座(key 即 definition 的 id),body 通过 useTabInfo().tab.navigation 读取 { address, params, revision }。

统一导航收敛到 ctx.sidebarRight:

ctx.sidebarRight.openTab('git.changes')
ctx.sidebarRight.openResource('dsh-resource://git/diff/<encodeURIComponent(path)>/<staged|worktree>', { params: { path, staged } })
ctx.sidebarRight.openTab('git.graph')

diff 标签页以精确地址为身份:同一文件同一比较侧重复打开会 reveal 既有标签页并递增 revision(body 据此重新拉取),而同一文件的 staged 与 working-tree diff 是两个不同地址,可并排共存。changes 与 graph 由侧栏按 kind 在每个 pane 去重。changed-files indicator、分支芯片与 guide 条目打开 git.changes;点击文件行打开该路径的 git.diff。

参数类型通过 augmentation 挂到右侧边栏:

declare module '@deepseek-ai/dsh-client-ui-sidebar-right/client' {
  interface SidebarRightResourceParamsMap {
    git: GitDiffPayload
  }
}

仓库操作按钮(refresh / reveal)由本包以本地组件渲染在各 Git 面板内部。标签栏、guide 页、停靠几何与面板宽度由右侧边栏(基于 ui-dockkit)拥有,不属于本 package。

用户体验

在会话输入区左侧,Git 贡献 branch selector 与 changed-files indicator。点击任一控件会在右侧边栏打开 git.changes 标签页。创建分支会打开共享的 conversation Modal;在仅有 git init、尚无提交(unborn HEAD)时,菜单以禁用态展示符号默认分支,说明需要先完成首次提交,并在 HEAD 存在前禁用创建。

分支选择器跟随该会话的有效目录。宿主若发布 workingDirectory 会话投影,Git 使用它;否则仍使用会话头里的目录。每个会话有自己的仓库状态。链接的检出显示工作树标记。Changes 面列出同一仓库的其他检出。只有宿主能够改变该会话目录时才出现 在此会话中使用,它请求宿主的工作目录服务进入所选检出;Worktrees tab 启用时另有 管理工作树 入口打开该 tab。本包不删除或修剪工作树。

Changes surface 顶部展示当前 branch 与 refresh,其下是默认一行、随内容增高的 commit message 输入框,带魔法棒 Generate 控件,以及分裂式 Commit 按钮(Commit、Amend、Commit & Push、Commit & Sync)。Staged、unstaged 与 untracked 路径以图标操作分区列出:plus/minus 切换 index,undo 在两步确认后 discard,porcelain 字母标记行状态。点击路径打开对应 diff。Diff 适配层在右上角展示 refresh,将单文件的 working-tree 或 staged 比较交给官方 DSH DiffBlock;复制、折叠以及支持版本上的换行由官方组件负责。Git patch 转换与非文本状态见架构总览,原有资源地址仍可恢复。Graph surface 顶部在同一行展示自动/全部/首父链与 refresh,其下以 canvas 绘制的 lane graph 展示提交历史——整页共享一个连续坐标系,rail 与 merge 边不会在行边界断裂——每个 commit 单行呈现 subject、author 与按类型着色的 HEAD/branch/remote/tag ref chips,悬停卡片承载完整 subject、hash、author、date 与 refs,滚动到底自动分页。当 host 暴露 LLM runtime 时,staged diff 会发送到会话模型——或发送到插件配置里的自定义 provider/model——流式生成的建议写入可编辑输入框。Worktrees 面——仅当宿主报告了创建模式时才注册 tab type——列出仓库的全部检出并标记当前检出,提供每个检出的 在此会话中使用,以及一个可填可选分支名与起始提交的创建对话框。宿主挂载上游实验性 worktrees 运行时(upstream 模式)时创建委托给它;否则 git-worktrees 的 enabled 设置开启本插件的本地 git worktree add 实现(local 模式),其检出池默认位于仓库根下的 .agents/worktrees,可在设置中修改。宿主能改变会话目录时,创建成功会直接进入新检出。同一张配置页也可以编辑生成所用的 system message。0.1.6-alpha.1 及更早在 设置 → 插件 → 插件配置;自 0.1.6-alpha.2 起在插件管理页该组合包的详情页。生成绝不 stage、commit 或 push 任何内容。在 Electron 上,optional Desktop enhancement 在 Desktop provider 存在时提供 reveal-in-folder 与 open-path 操作。

组合

Host plugin 要求 ctx.subprocess,提供 ctx.git,并使用 executable 与独立 argv values 启动 Git。它绝不调用 shell。DSH Web Host 存在时,optional Connection child 注册 loopback /git RPC channel。

Client plugin 要求 Connection、locale、renderer、conversation UI、primitives、session UI 与上游右侧边栏(ctx.sidebarRight / ctx.sidebarRightTabs,仅类型级 import)。Business components 通过 slot injection 接收该会话自己的 controller 与 openDetails(),不访问 Cordis context。两个会话不共享同一份仓库快照。

当 ctx.settingsScope 或 ctx.configForms 存在时,Client 通过 src/compat/dsh-client-settings.ts 注册提交信息与 worktrees 两个配置节。0.1.5-rc.2 与 0.1.6-alpha.1 消费 settings.plugin.item,命名空间为 git-commit-message 与 git-worktrees,出现在 设置 → 插件 → 插件配置。自 0.1.6-alpha.2 起,宿主改消费 plugins.bundle.config,两个节合并为一张以包名 @dsh-electron/dsh-plugin-git 为键的卡,出现在插件管理页该组合包详情的描述与组件列表之间。0.1.7 起表单数据来自补丁行 id dsh-plugin-git,不是包名。宿主未声明对应 slot、或未提供该命名空间时,配置不会出现。

Client main fiber 不要求 desktop。Child ctx.inject(['desktop'], ...) fiber 只接受 shell.showItemInFolder、shell.openPath 与 notification.show;缺少这些能力时,repository、status、diff、stage、commit 与 branch operations 仍可用,native actions 不显示。

本 package 不发布 runtime invariant companion,因为 Cordis 负责它所使用的 service、RPC registration 与 child-fiber lifetimes。

配置

字段 默认值 含义
executable git 由 ctx.subprocess 解析的 Git executable name 或 absolute path。
maxOutputBytes 8 MiB 单条 Git command 每个 stream 的 collection cap。
graceMs 3000 Managed subprocess termination grace period。
commitMessage.provider — 注册到 DSH LLM runtime 的 provider route。commitMessage.mode 为 custom 时必填。
commitMessage.model — 由 provider route 解析的 model id。commitMessage.mode 为 custom 时必填。
commitMessage.mode inherit inherit 使用宿主会话模型;custom 固定 provider/model。
commitMessage.systemPrompt 内置 提交信息生成的 system prompt。空或缺省使用 package 默认值。
commitMessage.maxDiffBytes 48 KiB 生成 prompt 构建前对 staged diff 施加的字节上限(validated 最小值 1024)。
worktrees.enabled — 默认跟随宿主上游 worktrees 运行时;设为 true 则在未挂载时启用本地实现。
worktrees.directory .agents/worktrees 本地创建 worktree 的检出池:相对仓库根目录,或为绝对路径。

整个 commitMessage 节是 optional,同时也是 git-commit-message 设置命名空间;同理 worktrees 即 git-worktrees 设置命名空间。两者均可在上面的插件配置入口编辑,或作为 composition entry。Host 未暴露 LLM runtime,或既没有会话模型也没有可解析的自定义路由时,commit message 生成不可用,Client 报告 git/generation-unavailable。

Git 操作

首个版本支持 repository discovery、Git version、current branch 与 HEAD、staged/unstaged/untracked status、local branches、working 与 staged diffs、stage/unstage、commit、amend、向 origin push、rebase-then-push sync、branch creation 与 branch switching。Status 使用带 NUL path separators 的 porcelain v2;branches 使用 for-each-ref;每个 caller-supplied path、branch 与 message 始终作为一个 argv value。Status 同时记录当前检出是主工作树、链接工作树还是裸仓库,并用 git worktree list --porcelain 列出检出。进入另一个检出只通过宿主工作目录服务改变该会话的目录,且只接受这份列表中的路径。创建检出在宿主挂载上游实验性 worktrees 运行时委托给它(上游同时进入新检出),否则在 git-worktrees 的 enabled 开启时走本插件自己的 git worktree add -b;删除和修剪工作树不属于本 package。

Discard 通过明确的 index、working tree 与 clean 操作还原一条 staged、unstaged 或 untracked 变更,包括暂存后再次编辑的新增和重命名,属于破坏性操作:Client 在发送 RPC 前总是要求第二次显式确认,确认正文会点名该路径。

提交历史以分页 git log 读取(GIT_LOG_FORMAT,每行一条 commit、固定字段数),Graph surface 通过滚动哨兵增量追加更早的提交,而不是一次性物化整个历史。

Commit message 生成在宿主侧按需启用:需要 LLM runtime 与可解析的模型(会话默认,或自定义 provider/model)。staged diff(受 commitMessage.maxDiffBytes 上限约束)会发送到该路由,流式生成的建议写入可编辑的 commit message 输入框。System prompt 默认为 Conventional Commit 说明,可在插件配置中覆盖。生成只提供建议 —— 它绝不 stage、commit 或 push 任何内容。

宿主提供完整可选 credentials seam 时,Remote 提供认证、PR/Issue 浏览、比较、PR 评论/review、核验 checkout、Issue 分支及受保护 create/close/merge。配置、限制、凭据处理与未知结果恢复以远程 RPC 契约为准,验收证据及尚未验证的外部场景见进行中计划。Git fetch/push 独立使用现有 Git 传输凭据。Stash、cherry-pick 与 merge-conflict 编辑仍不在本包范围。

npm 发布

本包已发布到 npm:@dsh-electron/dsh-plugin-git(MIT;最新 0.2.9)。发布方式为推送 vX.Y.Z tag:工作流跑测试与构建、打包 tarball、带构建 provenance 发布到 npm,并把同一个 tarball 附到 GitHub Release。API 与版本保持 pre-1.0。UI 宿主是上游内置的右侧边栏,无需独立安装的第三方配对包。发布步骤与凭据见 docs/development/README.md。

开发

使用 Node.js ^22.19 或 >=24 与 pnpm 11。

pnpm install --frozen-lockfile
pnpm test
pnpm build
pnpm pack

Model Experience

无,因为本 package 不注册 model tools、prompt sections 或 request context。

KV Cache effect

无。Commit message 生成是独立的 Host LLM 请求,不增加、替换或保留会话 token。

Known Limitations and Deferred Work

  • 独立 Git 传输——Remote 平台登录不配置 Git fetch/push 凭据;Git 认证仍由现有 helper 或 SSH 负责。
  • Command output 有界 — 大于 maxOutputBytes 的 diff 只保留 subprocess collector tail;处理超大 diff 的 deployment 必须提高这一 validated setting。
  • 生成依赖 host 与模型 — commit message 生成需要 host LLM runtime 与可解析的模型(会话默认或插件配置中的自定义路由);两者缺其一时,Generate 动作保持禁用或报告 git/generation-unavailable。
  • 进入工作树需要活的目录服务 — 没有宿主工作目录服务,或该会话没有活的 agent 时,检出列表只读。写操作此时仍沿用原先由调用方提供仓库路径的契约。目录消失后的恢复不属于本包,由宿主工作目录服务负责。
  • 创建工作树需要已报告的模式 — Worktrees tab 只在宿主报告 upstream(挂载实验性 worktrees 服务)或 local(git-worktrees 的 enabled 开启)时出现;否则 create-worktree 拒绝。local 模式下没有会话也能创建——检出创建但不进入。

开发备注

无。

贡献

环境搭建、质量门禁与文档义务见 CONTRIBUTING.md。每个已发布版本的用户可见变更见 CHANGELOG.md。本包以 MIT 许可发布,见 LICENSE。