dsh-git

组合后的配置中应出现 id/name 为 dsh-git 的根行

dsh --profile --dump-config

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

卸载：

```sh
dsh plugin --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. “更改”用于暂存；提交对话框只提交已暂存内容，不默认暂存全部文件。
7. 分支选择旁的 ＋ → 工作树 查看/管理 worktree。“打开”仅切换本插件的仓库查看目录，不会偷偷修改 DSH 会话的工作区或 cwd。
8. 在干净工作区中，选中普通提交后点击最右侧的 优选，确认提交哈希和当前分支再执行 cherry-pick。发生冲突时先关闭错误对话框，在编辑器解决冲突并于“更改”中暂存，再通过顶部提示条继续；也可以确认中止以恢复操作前状态。

键盘

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

安全与限制

• 执行者是 DSH 宿主机器上的 Git，不是模型工具沙箱中的 Git。现有 Git hooks、SSH、凭据助手和用户配置可能执行代码/访问网络。仅对可信工作区使用写操作。
• 不使用 shell，不允许客户端提供任意命令、可执行文件或 cwd；工作区路径只从宿主注册表解析。
• 选择的 linked worktree 必须与原工作区的规范化 Git common directory 一致；不允许陈旧登记把操作导向另一个仓库。
• 同一仓库的修改串行执行，并在锁内重新发现仓库，检查对话框打开时的 HEAD/分支预期值。
• 对解析出的真实短分支名再次校验；显式终止选项解析，防止异常引用名变为 --force 等选项。
• 远程操作依据 remote..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 服务：工作区授权、仓库发现、数据读取与安全修改。
• Git runner：无 shell 子进程、取消、超时与输出限额。
• 解析器：NUL 格式 status、refs、log、worktree 与文件列表。
• 客户端入口 / 状态模型：公开插槽接入、请求取消和界面状态。
• 面板 / 分支 / 样式：界面实现。
• 协议：允许的请求类型与边界校验。
• 构建脚本：宿主 ESM 与 DSH lazy-CJS 浏览器产物。
• 真实 Git 回归测试 / 模型与协议测试 / 浏览器测试。
• 验收与兼容性记录。
• 开发笔记与参考笔记。

许可

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

使用

1. 在 DSH 选择工作区/会话，点击右上角 Git。
2. 面板跟随主会话所属的注册工作区，也可以在面板右上角显式选择目录。
3. 非 Git 目录可选择 初始化 Git 仓库，确认后创建空的 main；已有 .git 元数据（包括损坏元数据）不会被覆盖。
4. 点击侧边栏分支筛选其历史；双击或右键“签出”进行切换。下拉列表点击其他分支同样需要确认。
5. 搜索提交，在提交图顶部直接按分支、用户、日期筛选；点击提交查看文件树，点击文件查看只读统一差异。
6. “更改”用于暂存；提交对话框只提交已暂存内容，不默认暂存全部文件。
7. 分支选择旁的 ＋ → 工作树 查看/管理 worktree。“打开”仅切换本插件的仓库查看目录，不会偷偷修改 DSH 会话的工作区或 cwd。
8. 在干净工作区中，选中普通提交后点击最右侧的 优选，确认提交哈希和当前分支再执行 cherry-pick。发生冲突时先关闭错误对话框，在编辑器解决冲突并于“更改”中暂存，再通过顶部提示条继续；也可以确认中止以恢复操作前状态。

键盘

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

配置

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

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