DeepSeek Harness 插件：dsh-git-status（实时 Git 状态 + 分支切换）

前言¶

DeepSeek Harness (DSH) 的理念是“一切皆插件”。在会话开发过程中，频繁查看分支状态、ahead/behind 数值以及切换分支通常需要手动执行 Git 命令。dsh-git-status 插件通过官方 slot 将 Git 状态集成到会话视图中，在会话头徽标和输入区环境行展示实时状态，并提供分支切换功能，减少切换上下文的成本。

安装与启用¶

安装该插件需使用官方包管理命令，指定版本 v0.1.0。

dsh plugin --profile web add github:shenhuanageshei/dsh-git-status#v0.1.0

安装后，插件会自动挂载至会话视图的特定槽位。对于非 git 会话，两处展示会自动隐藏。

核心功能¶

该插件主要提供以下能力：

实时状态展示：在会话头徽标和输入区环境行展示当前工作目录的 git 状态，包括分支名称、ahead/behind 数值、脏区计数、worktree 状态、HEAD 提交信息以及相对时间。
分支切换与新建：点击会话头徽标弹出分支菜单，支持搜索、切换分支、新建分支。新建分支支持远程 DWIM（Do What I Mean）跟踪分支逻辑。
安全模型：写操作仅使用 git switch（绝无 --force），通过 ref 白名单、spawn 参数数组无 shell 模式以及 check-ref-format 校验新建名来保证安全。当工作区有未提交变更时，插件会拒绝可能导致数据丢失的切换操作。
智能交互：支持 per-cwd 互斥锁串行切换，agent 运行中切换需二次确认。读命令带有 --no-optional-locks 参数，避免与 agent 的 git 操作抢索引锁。

界面与交互¶

插件在界面设计上分为两个主要区域：

会话头徽标：格式为 ⎇ 分支名 ▾。
- 点击后弹出分支菜单，支持搜索和操作。
- 当工作区有未提交变更时，徽标显示琥珀色圆点提示。
- 当处于 detached HEAD 状态时，显示为 ⎇ @短sha。
- 当存在 linked worktree 时，显示 ⧉ 标记。
输入区环境行：位于输入卡下方，与官方统计行同槽位但为 ambient 读出行。
- 示例格式：⎇ main ↑2↓1 · +3 ~2 ?1 · ⧉ wt:feature-x · 0a1b2c3 10m前。
- 分段配色（⎇ 品牌蓝、分支名 primary、脏区琥珀、worktree 紫、HEAD 弱灰），字体大小 13px，段距 14px，具有呼吸感。
- 悬停可显示 cwd / 主仓 / HEAD / upstream / worktree 列表。

安全模型¶

插件的写操作遵循严格的安全约束：

拒绝 Force：仅使用 git switch，不使用 --force。脏区有丢失风险时，由 git 自身拒绝并回显错误原文。
Ref 校验：新建分支名需通过 check-ref-format 校验，切换目标为已枚举的 ref 白名单。
并发控制：使用 per-cwd 互斥锁串行切换，成功切换后失效缓存。
锁竞争：读命令带 --no-optional-locks，避免与 agent 的 git 操作争抢索引锁。

架构¶

插件采用“Node half + Client half”的零构建架构：

Node half（lib/index.mjs）：提供 HTTP API 路由，包括 GET /status（TTL 1.5s 轮询缓存）、GET /branches（TTL 5s）和 POST /switch。会话上下文通过 ctx.sessions.get(id).header.cwd 获取。
Client half（lib/client.js）：通过 ctx.slots.inject 挂载至官方槽位。客户端负责 UI 渲染，轮询策略为 2s 起步，慢仓自适应退避至 8s，页面隐藏时暂停轮询。
零构建：Client 端手写 CJS，使用 __ModuleLoader__ 包装，与 task-status 编译产物同构，改完即生效。

开发¶

若需本地调试或修改插件：

注入：运行时生效，无需重启。

    dev_inject_plugin <本仓库克隆目录>

重载：修改 Node half 后执行，Client half 需刷新页面。

    dev_reload_package dsh-git-status

卸载：

    dev_uninject_plugin dsh-git-status

注意事项¶

该插件以当前 DSH 进程的权限运行。安装前应检查源码与许可证（MIT）。该插件由社区开发者维护，与 DeepSeek 或官方应用商店无从属关系。

总结¶

dsh-git-status 通过将 Git 状态和操作直接嵌入 DSH 会话界面，实现了从“外部命令行”到“界面内集成”的转变。其零构建的架构和严格的安全模型使其适合在开发流程中直接使用。