# dsh-git-branch

[English](README.md) | 中文

在 DeepSeek Harness（DSH）Web 界面的输入框工具行中，紧跟在「模式」控件（访问模式 / Plan 模式）之后，
展示**当前工作区**的 git 分支。存在 git 仓库时才展示；切换分支后按事件驱动规则自动刷新。

## 效果位置

输入框工具行布局为：`[+ 命令] [访问模式] [Plan] ← 分支 chip`。本插件注册到 `conversation.input.left`
这个「位于常驻模式 chrome 之后」的插槽，因此分支 chip 恰好落在模式控件右侧。

- 分支：`⎇ main`
- detached HEAD：`⎇ detached @ a1b2c3d`
- 无 git：不渲染
- 点击 chip：立即刷新（`title` 有提示）

## 安装

插件是一个 DSH **bundle**（自带 `cordis.patch.yml`），因此 `dsh plugin add` 会同时完成两件事：
安装依赖 + 把它加入 profile 的 `bundles` 列表，**无需手动改任何配置**。一条命令 + 重启即可：

```bash
# 从 npm 安装（推荐）
dsh plugin --profile web add dsh-git-branch

# 或本地目录（开发）
dsh plugin --profile web add ./dsh-git-branch
```

然后重启（或重新进入）该 profile，刷新浏览器页面即可：

```bash
# 重启正在运行的 dsh web 后，刷新浏览器页面
```

> 原理：本包在 `package.json` 里声明了 `dsh.bundle.patch = ./cordis.patch.yml`，其中 `- insert` 一行
> `git-branch` 插件行；`dsh plugin add` 检测到 `dsh.bundle` 后会自动把它加入 `dsh.profile.bundles`，
> 下次启动时该 patch 层生效，宿主加载 host 半并自动把 client 半下发到浏览器。

### 可选配置（host）

如需改命令名，在你的 profile 自己的 `cordis.patch.yml` 里做一次 id 覆盖（id 与 bundle 插入行一致）：

```yaml
- id: git-branch
  name: dsh-git-branch
  config:
    commandName: git-branch   # 可选，默认即 git-branch
```

未知配置键会在加载时报错。

### 客户端刷新常量

见 `src/client/index.tsx`（或 `lib/client.js`）顶部：

- `POLL_INTERVAL_MS = 60000`：慢速兜底轮询；`<= 0` 关闭。

## 工作原理

- **host**：`lib/index.js` 注册 `/git-branch` 命令；handler 从 `session.header.cwd` 向上查找最近的
  `.git`（支持 worktree / submodule），解析 `HEAD`，把结果以 JSON 放进命令 `text` 返回。
- **client**：`lib/client.js` 注册 `conversation.input.left` chip，通过 `ctx.remote.commands.execute`
  拉取分支；并注册 `conversation.chat.commandview` 的 `git-branch` 键位为 `null`，隐藏传输命令在对话流中的行。

刷新时机（详见 [DESIGN.md](./DESIGN.md)）：挂载 / 会话或工作区切换 → 立即；窗口 `focus` → 立即；
标签页 `visibilitychange→visible` → 立即；点击 chip → 立即；60s 轮询 → 兜底。

## 目录结构

```
dsh-git-branch/
├── package.json          # dsh.bundle + dsh.client 装配 + peerDependencies
├── cordis.patch.yml      # bundle patch：插入 git-branch 插件行
├── LICENSE
├── src/
│   ├── index.ts          # host 半（TS 源）
│   └── client/index.tsx  # client 半（TS 源）
├── lib/
│   ├── index.js          # host 半（预构建）
│   ├── index.d.ts
│   ├── client.js         # client 半（预构建，window.__ModuleLoader__ 格式）
│   └── client.d.ts
├── DESIGN.md             # git 分支刷新规则设计
├── README.md             # English（默认）
└── README.zh.md          # 中文（本文件）
```

## License

MIT