dsh-git-workspace

dsh-git-workspace

面向 DeepSeek Harness（DSH）Web UI 的单 workspace 多 Git 仓库工作台。

一个 DSH workspace 下可以同时发现和维护多个彼此独立的 Git 仓库，并在同一界面完成状态查看、暂存、提交、历史查看、分支与 Remote 维护、Fetch、Pull、Push 和批量网络操作。Remote 可按实际目标主机选择代理、直连、继承 Host 环境或阻止访问。

支持 DSH >=0.2.0-rc.2 <0.3.0-0（插件源码版本 0.3.2）。升级前必须核对旧设置数据；详情见 0.2.1 迁移说明。

兼容性完整复查见 DSH 0.2.1 兼容性审计，包含已核对接口、已修复的测试和仍需运行的验收项目。

最新版本适配（0.3.2）

目标版本为 DSH 0.2.1-rc.2（官方标签 dsh-v0.2.1-rc.2，提交 687f282e）。

• 通信服务优先读取新版 browserPeer（浏览器连接主体），兼容旧版 operator（操作主体），避免请求携带空主体。
• 真实浏览器通信测试按包导出的 browser 条件选择入口，兼容新版服务器模块与浏览器模块分离的发布结构。
• 开发依赖固定为已发布的 0.2.1-rc.1，Cordis 为 4.0.5，Schemastery 为 3.18.5；附带重新生成的锁文件。核对时 rc.2 的依赖包尚未同步至包仓库；本插件使用的接口源码在 rc.1 与 rc.2 标签间没有差异。
• 保留宿主兼容范围 >=0.2.0-rc.2 <0.3.0-0，没有提高最低版本。
• 已通过新版依赖下的全部 87 项测试、类型检查、构建和构建产物冒烟检查；最低版本另执行关键接口验证，详见 本次适配说明。完整桌面端和网页宿主人工验收仍需在实际使用环境完成。

升级源码目录后执行：

pnpm install --frozen-lockfile
pnpm check
node scripts/smoke-built.mjs
dsh plugin --profile web add ./

安装或更新后，支持热重载的环境按 DSH 提示刷新或重新加载；若提示无法热重载则重启。已有安装目录必须先更新源码并重新安装依赖、构建，单纯停用再启用插件不会替代这些步骤。

当前兼容基线

• 最低宿主版本：DSH 0.2.0-rc.2；本次目标：0.2.1-rc.2。
• 网络设置入口：插件管理 → dsh-git-workspace 详情页，配置绑定 git-workspace 条目。
• 使用可动态编辑的配置引用和插件配置扩展点；不会调用已移除的 ctx.settings.register。
• 新版 DSH 优先按顶层 engines.dsh（宿主版本声明）判断兼容性；旧版还会校验 DSH 宿主依赖，两个声明范围保持一致。

能力

• 在当前 DSH workspace 内有限深度扫描多个独立 Git 仓库。
• 仓库总览：分支、ahead/behind、staged/unstaged、冲突和 Remote 数量。
• 文件级 Diff、Stage、Unstage、Stage All、Unstage All。
• Diff 使用带新旧行号、hunk 和增删颜色的可读视图；未跟踪新文件直接展示新增内容。
• Commit 只提交 staged 内容，绝不隐式执行 git add -A。
• 最近 100 条提交记录，并可查看完整消息、作者、时间、父提交、变更文件及每个文件在该提交中的 Diff。
• 本地与 Remote 分支分组展示；选择 Remote 分支时明确创建同名本地跟踪分支。支持分支创建和安全删除（git branch -d）。
• Remote 添加、删除和 Fetch URL 修改。
• Fetch、Pull、Push 独立操作；Pull 使用 --ff-only --no-rebase --no-autostash，允许不冲突的本地修改。
• 工作台、Diff、批量弹窗和网络设置跟随 DSH 亮色/深色主题及其颜色变量。
• 批量 Fetch/Pull 最多 4 个仓库并行，Push 顺序执行；弹窗内实时显示等待、执行中、成功、失败和阻止状态，并可仅重试失败项。
• 仓库批量范围支持全选、反选和逐项选择。
• 仓库栏、主操作区和 Diff/提交详情栏之间可拖拽调整宽度；详情栏未使用时不占空间。
• DSH 插件管理（旧版称 DSH Settings）内的简化代理配置：走代理、强制直连、禁止访问三组主机列表。
• Fetch URL 与 Push URL 分别决策；代理失败不会静默回退直连。
• Windows、macOS 和 Linux 的 Node.js 原生子进程调用，不经 shell 拼接用户输入。

环境要求

• DSH >=0.2.0-rc.2 <0.3.0-0；本次核对的官方源代码提交为 687f282e。
• Node.js ^22.19.0 或 >=24；pnpm 11.7.0。
• Git 命令行；建议 Git >=2.31（代理策略依赖 git --config-env）。
• @deepseek-ai/schemastery 精确版本 3.18.5，使用随包提供的新锁文件。

安装和本地验证

在本仓库目录中执行：

pnpm install --no-frozen-lockfile
pnpm check
node scripts/smoke-built.mjs
dsh plugin --profile web add ./

pnpm check 依次执行类型检查、单元与集成测试、打包；smoke-built.mjs 则直接导入构建后的宿主模块并验证前端模块注册格式。

构建后包含：

lib/index.js   # DSH Host 插件入口
lib/client.js  # DSH Web 客户端入口

安装到隔离测试配置（例如 test）时可将 web 替换为 test，具体以已创建的 profile 为准；直接运行 dsh plugin add ./ 在需要 --profile 的发行版中会被拒绝。

升级原源码目录时，先备份 profile 的配置文件。现有 Git 工作区不会被清空，但旧 settings.yaml 中的代理策略不能保证自动迁移。详细说明见 升级迁移。

使用

插件加载后，DSH 左侧原生全局面板列表中出现“Git 工作台”入口，折叠侧栏时显示图标。入口排序由 DSH 管理，不再依赖其他插件的 DOM 结构。

1. 点击“Git 工作台”。
2. 选择 DSH workspace；插件会扫描其中的 Git 仓库。
3. 在左栏选择仓库，在中栏查看修改、历史或 Remotes；批量范围可使用全选和反选。
4. 修改文件时，先明确 Stage，再填写提交信息并确认 Commit。
5. Fetch、Pull、Push 都有独立入口；批量操作在同一弹窗完成预检、实时进度和失败重试。
6. 点击“关闭并返回会话”返回 DSH 当前会话。导航由 DSH 原生 layout 管理，不改变当前 Session 身份；页面挂载与卸载遵循 DSH 原生 main slot 生命周期。

工作台每次打开都会重新读取 DSH 的 workspace 注册表，因此刚新增但尚未创建会话的 workspace 也会出现在选择器中；打开期间列表每 5 秒同步一次。

更完整的操作说明见 docs/USAGE.md。

Remote 代理设置

进入：

DSH 左侧 Plugins（插件管理）→ dsh-git-workspace → Git 工作台网络

配置项：

每行一个主机，也可用逗号分隔。支持 * 通配符：

github.com
*.githubusercontent.com
git.company.local

决策优先级固定为：

禁止访问 → 强制直连 → 走代理 → 默认动作

示例：

• github.com 放入“走代理的主机”。
• git.company.local 放入“强制直连的主机”。
• 默认动作选择“阻止访问”，使未知目标失败关闭。

代理只作用于当前一次 Git 子进程，不写 git config --global，也不修改仓库配置。当前版本只为 HTTP(S) Remote 注入 HTTP 代理；SSH Remote 可继承、直连或阻止，但不会把 HTTP 代理错误套到 SSH 上。

安全语义

• 浏览器 RPC 只传 workspaceId 和 repoId，不传可执行绝对 cwd。
• Host 通过 DSH workspaceRegistry 解析 workspace，并用 canonical path 验证仓库仍位于 workspace 内。
• 文件操作只接受当前 git status 中实际出现的路径。
• Git 通过 spawn('git', args, { shell: false }) 执行，分支、路径、URL 和提交信息不进入 shell 字符串。
• Commit 不会自动暂存。
• Pull 允许不妨碍快进的本地修改，使用 --ff-only --no-rebase --no-autostash；覆盖风险、已有冲突或分叉时停止。失败时 fetch 可能已更新远端跟踪引用，本地内容和 HEAD 由 Git 原生保护，不自动 stash、merge 或 rebase。
• 代理凭据使用 DSH settings secret 字段；浏览器读取不到保存值。
• 代理或认证失败不会自动尝试直连。
• 插件 RPC 使用 /api/git-workspace/<endpoint> 精确路由，不会与 DSH API Gateway 的共享 /api interceptor 冲突。

详细边界见 docs/SECURITY.md。

扫描规则

默认从 workspace 根目录扫描 4 层，识别 .git 目录和 worktree/submodule 使用的 .git 文件。以下目录默认跳过：

.git node_modules .pnpm-store .cache .next .nuxt .turbo
dist build coverage target vendor .venv venv __pycache__

Host 会对候选目录运行 git rev-parse --show-toplevel，canonical path 去重后再生成稳定 repoId。符号链接目录不会被递归跟随。

扫描深度和额外忽略目录属于插件 settings schema，默认安装无需配置。

批量操作

批量操作分为两段：

1. 客户端预检：无 Remote、存在未解决冲突的 Pull、Detached HEAD、未发布 Push 等会被标为“阻止”。
2. 客户端发起单仓库操作：Fetch/Pull 使用最多 4 个 worker 并行，Push 保持顺序执行；当前行显示“执行中”，完成后立即在列表右侧显示“成功”或“失败”，阻止项不会发送请求。

弹窗在执行期间保持打开且不能误关闭；完成后可关闭，失败项可单独重试。工作台不再提供独立“操作中心”。

Git 不提供跨多个独立仓库的原子事务，本插件不会在部分成功后尝试危险的自动回滚。

开发与验证

pnpm typecheck
pnpm test
pnpm build

一次执行全部门禁：

pnpm check

测试包含：

• Porcelain v2 状态解析。
• Remote URL 与代理策略匹配。
• 临时 Git 仓库集成测试：多仓库发现、staged-only commit、unborn branch unstage、过期路径拒绝、Remote 分支跟踪切换、非首条提交详情和提交文件 Diff。
• Host/Client 独立 RPC channel 契约，防止回退到共享 /api interceptor。
• Fetch/Pull 并发与批量实时进度、workspace 重新同步、可调整栏宽、本地/Remote 分支切换、工作区/历史提交文件 Diff 和可读 Diff 行号。

源码结构

src/
├── index.ts                  Host 插件入口、Settings 与 RPC
├── host/
│   ├── repository-service.ts 仓库注册表和 Git 业务语义
│   ├── git-process.ts        无 shell 的 Git 子进程封装
│   ├── proxy-policy.ts       Remote 主机决策和单进程代理注入
│   └── status-parser.ts      porcelain v2 -z 解析
├── client/
│   ├── index.tsx             Web 客户端入口
│   ├── Workbench.tsx         多仓库工作台
│   ├── DiffViewer.tsx        带行号和增删语义的 Diff 视图
│   ├── CommitDetailView.tsx  提交详情与变更文件
│   ├── NetworkSettingsCard.tsx DSH Settings 卡片
│   ├── native-panel.tsx      原生面板图标与 main slot 内容
│   └── panel-controller.ts   工作台显示生命周期
└── shared/protocol.ts        Host/Client 共享协议

完整架构和 UCD 见 docs/DESIGN.md。

已知边界

• 不提供交互式凭据输入；凭据由 Git credential helper、SSH agent 或系统凭据管理器处理。
• HTTP 代理不转换 SSH Remote；结构化 ProxyJump 不在当前版本范围内。
• 不自动执行 merge、rebase、force push、hard reset、clean 或冲突解决。
• Diff 主要面向文本差异；未跟踪普通文件会生成 new-file patch，二进制文件只展示 Git 可提供的元数据。
• 左侧主入口使用与 dsh-web“任务看板”相同的宿主适配方式；当 DSH 提供正式 workspace 级导航 slot 后，只需替换该适配层。

设计参考

• DeepSeek Harness
• mojiexuan/dsh-git
• luoyu-xingu/dsh-multi-root
• zhu1090093659/dsh-web
• Git status porcelain v2
• Git config

License

Apache-2.0。第三方实现模式的来源说明见 NOTICE。