@mixin-ai/dsh-git-branch-switcher

Readme

# dsh-git-branch-switcher

[English](#english) | [简体中文](#简体中文)

<a id="english"></a>
## English

A DeepSeek Harness (DSH) Web plugin: a Git branch pill in the session header that shows the current branch of the session's workspace and lets you switch branches straight from the UI.

![license](https://img.shields.io/badge/license-MIT-blue)

### Features

- Shows the current git branch in the top-right session header (only for git-managed workspaces)
- Click the pill to open the branch panel: local branches, current one highlighted with ✓
- Click any branch to `git checkout` it; the pill updates immediately
- Detached HEAD support: shows the short commit hash with an explanation
- Auto-refresh every 30s (picks up terminal-side switches) plus a manual refresh button
- Checkout failures (e.g. conflicting local changes) surface git's own error message
- Theme-aware: all colors use the shell's `--dsw-*` tokens, light/dark ready
- Sandbox-aware: git runs under the same sandbox policy as the session's shell

### Install

```sh
dsh plugin --profile web add "github:mixin-ai/dsh-git-branch-switcher#main"
```

Then restart your Web profile:

```sh
dsh --profile web
```

The plugin is now listed under Settings → Plugins and the branch pill appears in the session header.

Alternative (source checkout):

```sh
git clone https://github.com/mixin-ai/dsh-git-branch-switcher
dsh web --patch ./dsh-git-branch-switcher/cordis.patch.yml
```

### Usage

1. Open a session whose workspace is a git repository.
2. The branch pill appears at the top-right of the conversation header.
3. Click it → branch list → click a branch to switch.
4. The ↻ button re-reads the branch list.

### Architecture

| Half | File | What it does |
| --- | --- | --- |
| Host | `lib/index.js` | `gitBranch` Typert Remote service (`status` / `branches` / `checkout`) running git through the `shell` service with the session's sandbox policy. Plain-JS Remote markers, no generated artifacts (SRC mode). |
| Client | `lib/client.js` | Prebuilt `__ModuleLoader__` bundle mounting the Remote contribution and rendering the header pill (session-scoped `conversation.session.header.utilities` slot). |
| Patch | `cordis.patch.yml` | Inserts the dual-face plugin row into the Web profile. |

- The workspace directory comes from the session's `cwd` (`useSessions` standard slot prop), so it always tracks the open session.
- Branch names are single-quote escaped for the shell and control characters are rejected — no command injection.
- All side effects (Remote mount, slot registration, timers, CSS) belong to the plugin fiber and are removed on unload.

### Dynamic plugin variant

`dynamic/` contains the same feature as an in-session dynamic Cordis Plugin (the form the DSH Web UI's plugin authoring flow runs). See `dynamic/README.md`.

### License

MIT

---

<a id="简体中文"></a>
## 简体中文

一个 DeepSeek Harness (DSH) Web 插件：在会话头部显示当前项目所在 git 分支的胶囊按钮，点击即可在界面里直接切换分支。

### 功能

- 在会话头部右上角显示当前 git 分支（仅当项目由 git 管理时出现）
- 点击胶囊弹出分支面板：本地分支列表，当前分支以 ✓ 高亮
- 点击任意分支即执行 `git checkout` 切换，胶囊立即更新
- 支持 detached HEAD：显示短提交哈希并给出说明
- 每 30 秒自动刷新（终端里切了分支也能同步）+ 面板内手动刷新按钮
- 切换失败（例如本地有冲突改动）时显示 git 原始报错
- 颜色全部使用主题 `--dsw-*` token，自动适配亮/暗主题
- 尊重沙箱策略：git 命令与会话 shell 使用同一套沙箱策略执行

### 安装

```sh
dsh plugin --profile web add "github:mixin-ai/dsh-git-branch-switcher#main"
```

然后重启 Web profile：

```sh
dsh --profile web
```

插件会出现在「设置 → 插件」中，分支胶囊显示在会话头部。

源码方式（patch 覆盖层）：

```sh
git clone https://github.com/mixin-ai/dsh-git-branch-switcher
dsh web --patch ./dsh-git-branch-switcher/cordis.patch.yml
```

### 使用

1. 打开一个工作区为 git 仓库的会话。
2. 会话头部右上角出现分支胶囊。
3. 点击胶囊 → 分支列表 → 点击分支即可切换。
4. ↻ 按钮重新读取分支列表。

### 架构

| 半边 | 文件 | 职责 |
| --- | --- | --- |
| Host | `lib/index.js` | `gitBranch` Typert Remote 服务（`status` / `branches` / `checkout`），通过 `shell` 服务执行 git，沿用会话沙箱策略。纯 JS Remote 标记，无生成产物（SRC 模式）。 |
| Client | `lib/client.js` | 预构建 `__ModuleLoader__` bundle：挂载 Remote 贡献并渲染头部胶囊（会话级 `conversation.session.header.utilities` 插槽）。 |
| Patch | `cordis.patch.yml` | 将双面插件行插入 Web profile。 |

- 项目目录取自会话的 `cwd`（`useSessions` 标准插槽属性），始终跟随当前打开的会话。
- 分支名经单引号 shell 转义并拒绝控制字符，不存在命令注入。
- 所有副作用（Remote 挂载、插槽注册、定时器、CSS）都归属插件 fiber，卸载时自动清理。

### 动态插件版本

`dynamic/` 目录提供同功能的内存态动态 Cordis 插件源码（DSH Web UI 插件创作流程所用的形态），见 `dynamic/README.md`。

### 许可证

MIT