前言¶
在 DeepSeek Harness（DSH）里做智能体或终端协作时，会话往往绑定一个工作目录。分支名通常要切到终端里 git branch 或看 IDE 状态栏，和 Composer 里正在写的提示词不在同一视线里。Agent 或本地 shell 改了分支，Web 界面也不会自动跟上，容易在错误分支上继续对话。
下面介绍的 dsh-git-branch 是 MYiYang 维护的 DSH Web 客户端插件（npm 包名 dsh-git-branch-plugin，插件内 id 为 dsh-git-branch）。它把当前 Git 分支放进消息输入区左侧的紧凑控件行（模型选择器左边），点开可浏览本地与远程分支、切换本地分支，并打开只读的提交图。仅当会话工作目录位于 Git 仓库内时显示该控件；非仓库时 chip 隐藏。
这是什么¶
一句话：在 Harness 对话 Composer 上展示会话目录的当前分支，提供四列分支表与只读 commit graph，本地分支可 checkout。
- 维护者：MYiYang
- 分类：客户端（Web profile）
- 源码与说明：GitHub MYiYang/dsh-git-branch
- 社区目录页：skillhub.cn/plugins/MYiYang/dsh-git-branch（独立社区站点，与 DeepSeek / 幻方无官方从属关系）
- 许可证：MIT（见仓库 LICENSE）
- 当前 npm 版本（资料来源 package.json）：0.2.1；Node 引擎要求
>=22.16.0
浏览器侧不能执行 git，插件由 Host 半挂载受信围栏的 POST /git-branch/api/{status,checkout,graph}，工作目录来自会话的 workingDirectory（回退到会话头里的 cwd），不接受请求体里的任意路径；checkout 前会校验分支名是否在仓库 refs/heads 列表中。
核心功能¶
Composer 上的分支 chip¶
- 显示当前分支名；若处于 detached HEAD，显示
HEAD@<short commit>。 - 位置：
conversation.input.left，即输入区左侧控件行。
分支表（点击 chip 打开）¶
四列表格，本地行在前、远程行在后：
| 列 | 本地分支 | 远程分支 |
|---|---|---|
| Branch | 名称（当前检出带勾） | 名称（地球图标） |
| Upstream | 跟踪 ref，如 origin/main |
空 |
| Ahead·Behind | 相对上游 ↑2 ↓1，同步时为 = |
空 |
| Last commit | 短 hash（tooltip 含 subject/日期） | 短 hash |
分支超过 8 个时出现搜索框，同时过滤本地与远程两组。仅本地分支提供切换（等价于在该目录执行 git checkout <branch>）；点远程行不会 detach HEAD，也不会自动建本地分支。脏树冲突等失败信息在菜单内展示。
只读提交图¶
菜单头部的按钮打开只读图表面板（空间足够时在 chip 上方，否则在下方）。绘制各 ref 可达历史（最多 200 条 commit）的 lane 与节点，含分支、remote、tag 标记，以及 subject、短 hash、作者、日期。按 Esc、关闭按钮或点击外部可关闭；打开时读取，可在面板头部刷新。
刷新策略¶
页面可见时每 15 秒重读状态；窗口获焦、页面变为可见、以及切换分支后立即刷新，以便 Agent 或终端改分支后界面跟上。提交图在打开面板时读取。
实现要点（便于排查）¶
| 文件 | 作用 |
|---|---|
index.js |
Host：挂载 API 路由，解析会话工作目录 |
git.js |
argv 方式调用 git，分支列表、切换、图数据、detached/非仓库检测 |
graph.js |
纯解析与 lane 布局（无 DOM），单测覆盖 |
client.js |
chip、分支表、提交图、轮询与 locale |
cordis.patch.yml |
注入 Host 行 git-branch |
路由经 ctx.webServer 注册，并用 ctx.connection.requestRejection 围栏，仅已认证的 Harness 页面可 POST 调用。
安装与启用¶
插件是 DSH bundle（自带 cordis.patch.yml），添加后会安装依赖并激活 Host 行。还需在 Web profile 的 dsh.profile.bundles 中列出该包（~/.dsh/profiles/web/package.json）；仅有安装条目而未写入 bundles 时，bundle 不会 layered。
官方安装命令（来自 README）：
# 从 npm 安装
dsh plugin --profile web add dsh-git-branch-plugin
本地开发目录可用 dsh plugin --profile web add ./dsh-git-branch（需自行持有源码目录，本文不展开 clone 步骤）。
安装或修改包后：重启 DSH 以加载 Host 路由；刷新 Harness 页面 以加载最新 client.js（已打开的标签页可能仍缓存旧客户端模块）。
典型用法¶
- 确认会话工作目录在某个 Git 仓库内；输入区左侧应出现当前分支 chip。
- 点击 chip，在表中查看 upstream、ahead/behind、最近提交；需要时在本地行上执行切换。
- 在菜单头打开提交图，浏览合并历史；只读，不替代
git log的全部分支策略。 - 若 Agent 在终端改了分支，等待轮询或切回窗口焦点即可更新；也可切换一次分支触发立即刷新。
Host API 形状（Client 调用，供对接理解）：
status→{ isRepo, root?, branch?, detached?, commit?, branches }，分支项含name, kind, current?, upstream?, ahead?, behind?, lastCommit?等。checkout→ 本地分支名，成功后返回与status相同结构。graph→{ root, rows }，每行含 hash、lane 几何、refs、links 等。
适用场景与注意¶
适合谁： 经常在 DSH Web 里写提示、又让 Agent 或终端动 Git 的开发者；希望在 Composer 旁一眼确认分支、偶尔切换本地分支、快速看近期提交拓扑，而不必每步开终端。
限制（README Notes）：
- 只切换本地分支；远程仅展示。
- 提交图只读，且最多 200 条 commit（跨所有 ref 的可达历史）；不对请求传入 path 或 revision 做
git log。 - 使用
git checkout而非git switch，以兼容部分 Windows 主机自带的 Git 2.18。 - 启动时会探测可执行的
git（先subprocess执行环境，再 PATH）；找不到可执行 git 时 chip 保持隐藏。 - 每次请求重新解析工作目录，会话进入 linked worktree 时会显示该 worktree 的分支。
安全与权限： 插件以当前 DSH 进程权限在会话工作目录执行 git。安装前请阅读 源码 与 MIT 许可证，确认行为符合你的环境策略；社区目录页仅作索引，不替代源码审查。
结尾¶
dsh-git-branch 把「当前在哪个分支、本地/远程差多少、最近提交长什么样」收进 Harness 输入区，并限制在会话自己的仓库目录内操作，适合 Web 侧协作开发时的轻量 Git 上下文。更多信息见 社区目录页 与 GitHub 仓库。
