DSH Git

一个面向 DeepSeek Harness 的原生 Git 插件。采用紧凑的 IDE 风格，并随宿主明暗主题自适应，在当前 DSH 工作区下提供分支、提交历史、提交图、文件差异和 Git worktree 管理。

已实现

• Git 初始化：在未使用 Git 的已注册工作区中，经确认执行 git init --initial-branch=main；已有 .git 元数据（包括损坏元数据）不会被覆盖。
• 顶部 Git 入口：Windows 桌面版在“应用 / 编辑”右侧追加 Git 按钮，点击打开/收起底部面板。普通浏览器及不兼容的宿主保留会话右上角入口；没有活动会话时提供右上角备用入口。
• 底部面板：支持拖动调整高度、键盘调整、最大化、收起，以及多个独立 Git 视图标签。
• 主题自适应界面：表面、边框与文字色全部取自 DSH 宿主令牌；强调色、语义色和提交图/差异配色随宿主明暗主题调整，浅色主题下不会出现低对比的荧光色。焦点环、悬停/禁用态、按钮按压反馈、弹层触发点缩放与 prefers-reduced-motion 一并处理。
• 三栏仓库视图：左侧分支/更改，中间提交历史及真实父子关系提交图，右侧变更文件树、提交正文、作者、时间与引用。
• 分支下拉：搜索本地和远程分支；更新、提交、推送、新建分支、抓取远程；签出前明确确认。
• 不同的右键菜单：当前分支与其他本地/远程分支分别提供适用操作，也有可通过键盘打开的“更多操作”按钮。
• 分支旁的加号：紧邻分支选择；两个选项严格为“GIT工作区”和“工作树”。前者新增仓库视图，后者显示真实的 git worktree list 结果。
• 统一选择框：历史分支/日期与工作区切换采用 shadcn/ui 风格的 Radix Select，统一圆角、分组、选中勾、焦点态与键盘导航；工作区选项附目录路径，长名称省略，弹层跟随宿主明暗主题并保持不透明。分支操作、右键菜单及子菜单同样使用实色背景。
• 平铺历史筛选：分支、用户、日期始终显示在提交图顶部，支持组合与一键清除；日期包括今天、最近 7/30/90 天与最近一年（按 Git 提交时间）。
• 优选（cherry-pick）：位于提交图顶部最右侧，将选中的普通提交应用到当前本地分支；要求工作区干净并明确确认，支持冲突后继续或中止，不猜测合并提交的主父提交。
• 工作树：创建、查看、打开为插件查看目录、复制路径、锁定/解锁、安全移除；保护主工作树、当前查看目录、已锁定或有改动的工作树。
• 日常 Git：逐文件/全部暂存与取消暂存、提交已暂存内容、分支创建/重命名/安全删除、合并、变基、仅快进更新、设置上游、非强制推送、抓取远程、远程分支删除。
• 批量提交选择：提交弹窗支持全选、反选、批量暂存/取消暂存；勾选与实际暂存分离，保留逐文件操作与已暂存/部分暂存状态，每批最多 1000 个文件。
• 底部操作提示：成功/失败消息显示在底栏路径、分支右侧，不再挤占顶部仓库内容；长消息省略并可悬停查看完整文本，错误不会自动消失。
• AI 提交预览：“更改”区顶部固定显示提交与 AI 入口；点击 AI 提交会自动暂存全部当前改动（含新文件、删除及部分暂存文件的剩余改动）、全选预览文件，再生成可编辑文本，最后由用户选择“提交”或“提交并推送”。可停止生成；失败或取消时保留已完成的暂存，无可用模型时仍支持手写提交。
• Git 设置：面板右上角收起按钮左侧的设置按钮，可选择 DSH 已登记模型、编辑提交文本规范和配置/录制提交、AI 生成、推送及获取快捷键。设置仅保存在当前浏览器，不读取或保存模型密钥。
• 冲突处理：保留冲突现场；在编辑器解决冲突后，可在“更改”中暂存并继续/中止合并、变基或优选。
• 友好的空状态：非 Git 目录不是异常；另行区分 Git 未安装、目录消失、权限/执行失败。

实现说明

插件按紧凑的深色 IDE 布局实现，对接依据为 DSH 0.2.0-rc.2、Cordis 4.0.4 的公开服务与注册契约。

该宿主没有公开的原生 bottom-panel 插槽，因此底部面板通过公开 shell.overlay 实现为固定、可缩放的底部覆盖层，不会伪造不存在的宿主 API。它不会把宿主聊天区域整体重新排版，增大面板会遮住其下方内容。

Windows 桌面标题栏目前也没有公开的插件菜单插槽。顶部入口采用针对 DSH 0.2.1-rc.2 的兼容适配：检测 [data-windows-menu] 的开放 Shadow DOM，在原生 menubar 后面追加独立按钮，而非注册第三个原生菜单；不修改“应用 / 编辑”、其快捷键或私有 IPC，不修改 DSH 安装文件。若标题栏尚未挂载或结构不匹配，则回退到原入口；结构恢复时自动迁回。宿主升级后仍需核对兼容性。

插件不会自行修改 DSH 的运行中配置，也不会自行重启宿主；安装后是否需要重启由宿主提示决定。

安装

插件以组合包（bundle）形式安装：包由 package.json 的 dsh.bundle.patch 声明一个配置层，安装进某个 profile 后，该层向组合中插入一行 dsh-git 插件。

• <你的-profile> 需替换为你实际使用的 profile 名；桌面应用所用 profile 可从 $DSH_HOME/profiles/ 下的目录名确认。
• 命令中的 dsh 指已安装的 DSH CLI。

方式一：从源码构建后安装（推荐）

需要 Node.js 22+、pnpm 与 Git。下述命令克隆源码、构建产物，再把 checkout 链接进 profile：

git clone https://github.com/cyrusgogogo/dsh-git.git
cd dsh-git
pnpm install --frozen-lockfile
pnpm run build

# 本目录已包含 dist/ 构建产物，链接进 profile
dsh plugin --profile <你的-profile> add .

也可以先打包，再安装 tarball；生成物可以拷给其他人直接安装：

pnpm pack
dsh plugin --profile <你的-profile> add ./dsh-git-0.1.2.tgz

方式二：直接从 GitHub 安装

dsh plugin --profile <你的-profile> add github:cyrusgogogo/dsh-git

git 安装拉到的是源码而非构建产物，因此 pnpm 会运行本包的 prepare 脚本（node scripts/build.mjs）在安装时构建发布入口。pnpm ≥10 默认拒绝执行依赖的构建脚本，第一次 add 可能因此失败并打印修法：把 pnpm 给出的确切包键写进该 profile 的 pnpm-workspace.yaml，然后重新执行 add。

allowBuilds:
  dsh-git: true

这等于允许该包的代码在安装时于你的机器上执行（不在 agent 沙箱内），请只对可信来源授权；需要可复现的安装时锁定 commit，例如 github:cyrusgogogo/dsh-git#<sha>。

安装后核对

# 组合后的配置中应出现 id/name 为 dsh-git 的根行
dsh --profile <你的-profile> --dump-config

保存成功不代表当前进程已激活。若宿主报告 restart-required，请重启 DSH 并刷新 Web 页面。

卸载：

dsh plugin --profile <你的-profile> remove dsh-git

安装/分层依据：官方插件发布与安装说明。插件只追加自己的配置行，不修改其他插件的完整配置对象。

从源码开发

要求 Node.js 22+、pnpm、Git 2.31+。

pnpm install --frozen-lockfile
pnpm run build
pnpm run test
pnpm run test:ui
pnpm run dev

浏览器测试优先使用 Playwright 对应的 Chromium，Windows 缺少时尝试本机 Edge。可通过 DSH_GIT_BROWSER 指定测试浏览器可执行文件；没有可用浏览器时，按需手工执行 pnpm exec playwright install chromium。测试不需要访问真实 DSH 页面、不需要模型密钥、不连接外部 Git 远程。

在 Windows DSH agent 沙箱中，捕获子进程输出和浏览器进程管道可能返回 spawn EPERM。这属于运行测试的沙箱边界，不是插件声称能够绕过的权限；需由操作者为相应测试命令授权。

pnpm run dev 只监听并重建本项目产物，不会自动把插件注入已安装的 profile；宿主端的客户端 HMR 取决于它实际加载的位置和对应的重建通知。

当前只在 Windows 上完成实机验证；macOS/Linux 的实现路径存在，但未做实机验收。

使用

1. 在 DSH 选择工作区/会话，点击顶部“编辑”后面的 Git（普通浏览器或不兼容宿主位于会话右上角）。
2. 面板跟随主会话所属的注册工作区，也可以在面板右上角显式选择目录。
3. 非 Git 目录可选择 初始化 Git 仓库，确认后创建空的 main；已有 .git 元数据（包括损坏元数据）不会被覆盖。
4. 点击侧边栏分支筛选其历史；双击或右键“签出”进行切换。下拉列表点击其他分支同样需要确认。
5. 搜索提交，在提交图顶部直接按分支、用户、日期筛选；点击提交查看文件树，点击文件查看只读统一差异。
6. “更改”区域顶部的 提交更改… 打开手动提交弹窗，支持全选、反选和批量暂存/取消暂存。勾选本身不会写入 Git；“暂存所选”会暂存所选文件的全部当前更改（包括原来只部分暂存的文件）。普通提交只包含已暂存内容，不默认暂存全部文件。
7. 点击 AI 提交（或 AI 快捷键）会先读取最新状态，自动暂存全部当前未暂存改动、全选文件，再生成可编辑说明。包括当前未跟踪的新文件、删除和部分暂存文件的剩余改动，不包含 Git 忽略文件。每次 RPC 最多暂存 1000 个文件，更多文件自动分批；暂存失败或期间出现新改动时停止，不会发送不完整范围给模型或自动提交。生成后检查并修改文本，明确点击 提交 或 提交并推送。取消/停止/模型失败不会回滚已完成的暂存；可手写说明或重试生成。预览里的“AI 生成 / 重新生成”只基于当前暂存内容，不重复暂存。API 密钥由已有 DSH 模型配置管理。
8. 右上角 设置 可选择 AI 模型、修改 Conventional Commits 默认规范并录制快捷键。未指定模型时使用宿主模型目录中的首个可用模型，实际模型会显示在生成结果旁；手动填写的 provider/model 也必须已登记。设置不写入仓库，不同步到其他浏览器。
9. 分支选择旁的 ＋ → 工作树 查看/管理 worktree。“打开”仅切换本插件的仓库查看目录，不会偷偷修改 DSH 会话的工作区或 cwd。
10. 在干净工作区中，选中普通提交后点击最右侧的 优选，确认提交哈希和当前分支再执行 cherry-pick。发生冲突时先关闭错误对话框，在编辑器解决冲突并于“更改”中暂存，再通过顶部进行中提示条继续；也可以确认中止以恢复操作前状态。

模型列表提示“Git 请求参数不合法”

此错误发生在插件请求协议校验阶段，并不表示模型名称或 API 密钥错误。若页面已显示 AI 设置，但运行中的宿主仍使用旧插件协议，新客户端的 aiModels 请求就会被旧宿主拒绝。单独刷新页面或运行 pnpm run build 不保证重载已运行的宿主模块。

1. 先保存当前输入，在方便时完全退出并重启 DSH（包括托盘驻留），再打开 Git 设置刷新模型列表；不要只刷新 Web 页面。
2. 确认当前 profile 安装/链接的是新构建。仓库中旧的 0.1.2 发布包尚未包含 AI 功能，不能把它当成本轮源码构建。
3. 若完全重启后仍失败，只需提供 /api/dsh-git 响应的 result.error.code 与 result.error.details.issues，不要提供 Cookie、Authorization、模型密钥或完整配置。

插件仅在新操作被宿主判定为未知操作时提示版本不一致；真实字段错误和未配置模型服务仍按原类别显示，不会自动安装、重启、放宽校验或改走其他模型接口。

键盘

以下操作快捷键可在 Git 设置中修改、录制或留空禁用：

操作	默认快捷键	行为
提交	Ctrl+Enter	打开提交预览，不直接提交
AI 提交	Ctrl+Shift+Enter	自动暂存全部当前改动、全选并生成预览；仍需确认提交
推送	Ctrl+Shift+P	打开推送确认
获取	Ctrl+Shift+F	打开获取远程更新确认

仅在 Git 面板获得焦点 时生效，不拦截宿主编辑器、输入框、其他弹窗或菜单。支持 Ctrl / Meta / Alt / Shift 与 Mod（macOS 对应 ⌘，其他平台对应 Ctrl）；检测快捷键冲突，忽略输入法组合事件与长按重复。部分组合键可能被浏览器/操作系统占用。

• 标签页：左右方向键、Home、End；当前标签为主要 Tab 停靠点。
• 提交列表：上下方向键、Home、End。
• 分支菜单、下拉、对话框：Radix 管理焦点与键盘行为；Esc 关闭，执行中的操作对话框不会被 Esc 意外关闭。
• 面板上边缘：聚焦后使用上下方向键调整高度，Home/End 调整到预设/最大高度；双击切换最大化。

安全与限制

• AI 数据边界：仅在明确触发 AI 生成时，将捕获的已暂存差异和提交规范发给 DSH 模型服务。AI 提交入口会先暂存全部当前未暂存/未跟踪改动，因此这些内容也会进入模型输入；不包含 Git 忽略文件、提交范围外文件正文、会话历史或模型工具。差异上限 64 KiB，提交规范上限 16000 字符，编码后的总输入上限 128 KiB，输出上限 1024 tokens / 16000 字节，90 秒超时；截断输入会提示，不接受不完整输出。触发前请检查没有密钥或其他不应发给模型的内容。
• AI 与提交确认：AI 提交的准备阶段会实际修改暂存区，取消预览不自动撤销。生成期间和最终提交前复核 HEAD、分支与暂存树；暂存变化会阻止使用旧预览。为计算暂存树标识，快照/生成还可能填充 Git tree objects 或 index 缓存；生成本身不创建提交或执行提交 hooks，不承诺 Git 元数据零写入。
• 提交并推送：先创建本地提交，再普通非强制推送，不自动重试或回滚。本地提交成功但推送未确认时，关闭旧提交确认并提示仅检查/重试推送；用户 Git hooks 仍会执行。若 hooks 改变已提交内容，停止后续推送并提示检查本地提交；超时/取消可能发生在提交落盘之后，应先确认结果，不可盲目重复提交。
• 执行者是 DSH 宿主机器上的 Git，不是模型工具沙箱中的 Git。现有 Git hooks、SSH、凭据助手和用户配置可能执行代码/访问网络。仅对可信工作区使用写操作。
• 不使用 shell，不允许客户端提供任意命令、可执行文件或 cwd；工作区路径只从宿主注册表解析。
• 选择的 linked worktree 必须与原工作区的规范化 Git common directory 一致；不允许陈旧登记把操作导向另一个仓库。
• 同一仓库的修改串行执行，并在锁内重新发现仓库，检查对话框打开时的 HEAD/分支预期值。
• 对解析出的真实短分支名再次校验；显式终止选项解析，防止异常引用名变为 --force 等选项。
• 远程操作依据 remote.<name>.fetch refspec 反向定位来源。映射歧义会拒绝操作，不会猜测远程名并删除错误仓库的分支。
• 不提供强制推送、reset --hard、branch -D、强制覆盖 checkout 或强制移除工作树。
• 远程删除需额外输入完整分支显示名；会真实影响远程和协作者，请谨慎操作。
• 取消/超时会终止拥有的 Git 进程树；已经完成的提交、推送等副作用不会因此自动回滚。
• 工作区外普通文件读取、Git 元数据路径、越界路径不接受；未跟踪文件读取校验真实路径并限量。
• 命令输出有上限；大差异会截断并明确提示。二进制差异不提供图像对比，未提供文件编辑器、stash、revert、合并提交的 cherry-pick 或复杂交互式 rebase。
• 工作树创建要求目标在当前仓库外、父目录已存在，且目标为空/不存在；不负责创建任意祖先目录。
• 视图打开且页面可见时每 10 秒刷新本地状态；不会自动 fetch/push。用户手动“获取”才执行网络抓取并清理过期远程跟踪引用。
• 当前仅识别 merge/rebase/cherry-pick 进行中的状态；不尝试代管其他外部工具的复杂 Git 流程。

这不是防御恶意本机进程的文件系统沙箱；外部编辑器/Git 命令仍可能并发修改仓库。插件的串行化与预期检查只覆盖其自身请求和可检测状态变化。

配置

组合包 patch使用稳定根行 ID。覆盖配置时应保留完整 config，宿主的 patch 不是对象深合并。

配置	默认值	范围	含义
maxCommits	300	20–1000	每次加载的提交数量，支持继续加载
commandTimeoutMs	30000	1000–120000	本地 Git 命令超时
networkTimeoutMs	120000	1000–600000	网络 Git 命令超时

项目导航

• 宿主入口：Standard Schema 配置、原生 Connection Fetch 路由、错误封装、生命周期。
• Git 服务：工作区授权、仓库发现、数据读取与安全修改。
• AI 提交服务：可选宿主模型目录、有界 staged diff、取消与安全输出处理。
• 提交预览 / 设置页面 / 设置与快捷键：批量暂存、人工确认与浏览器本地偏好。
• AI 单元测试 / AI 真实 Git 测试 / 提交状态模型测试 / 设置测试。
• Git runner：无 shell 子进程、取消、超时与输出限额。
• 解析器：NUL 格式 status、refs、log、worktree 与文件列表。
• 客户端入口 / 状态模型：公开插槽接入、请求取消和界面状态。
• 面板 / 分支 / 样式：界面实现。
• 协议：允许的请求类型与边界校验。
• 构建脚本：宿主 ESM 与 DSH lazy-CJS 浏览器产物。
• 真实 Git 回归测试 / 模型与协议测试 / 浏览器测试。
• 验收与兼容性记录。
• 开发笔记与参考笔记。

许可

MIT，见 LICENSE。第三方构建依赖的许可与版权声明见 THIRD_PARTY_NOTICES.md。