@dsh-electron/dsh-plugin-git

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

---

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

kind: "package-bundle"

---

dsh-plugin-git

[English](README.md) | 中文

<a id="summary"></a>

概述

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

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

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

<a id="table-of-contents"></a>

目录

• [DSH 兼容性](#dsh-compatibility)
• [安装](#installation)
• [与上游右侧边栏配对](#pairing-with-sidebar-right)
• [用户体验](#user-experience)
• [组合](#composition)
• [配置](#configuration)
• [Git 操作](#git-operations)
• [npm 发布](#npm-publication)
• [开发](#development)
• [贡献](#contributing)
• [Model Experience](#model-experience)
• [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
• [开发备注](#dev-note)

<a id="dsh-compatibility"></a>

DSH 兼容性

已验证的精确版本、开发 pin、宿主 Node 要求和候选升级流程统一见[兼容契约](docs/reference/dsh-compatibility.md)。

<a id="installation"></a>

安装

本包已发布到 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 …。

<a id="pairing-with-sidebar-right"></a>

与上游右侧边栏配对

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。

<a id="user-experience"></a>

用户体验

在会话输入区左侧，Git 贡献 branch selector 与 changed-files indicator。点击任一控件会在右侧边栏打开 git.changes 标签页。创建分支会打开共享的 conversation Modal；在仅

…(truncated)