gitcompass

dsh-git-manager

English | 中文

DeepSeek Harness 的 GitHub 可视化 Git 管理插件——引导式 GitHub Flow 流程、GitLens 风格提交图谱（带 PR/CI 徽章）、一键 GitHub 登录，以及为 Agent 提供的结构化 Git 操作工具。

面板的呈现方式与 dsh-better-sidebar 同源：每一个颜色、字号角色与动效值都走 DSH 主题令牌；界面是平面的（发丝边框 + 悬停底色，流内没有阴影）；纯图标按钮是圆形、透明底、悬停才浮出。明暗主题与任何 dsh-web-ui 皮肤都能直接重绘这个面板——面板内部没有自己的调色板，也没有主题选择器。详见 DESIGN.md。

2.0.0 起由 gitcompass 改名而来：包名、插件行 id（dsh-git-manager）、HTTP 路由（/gitm/*）与 CSS 前缀（--gm-*）一并迁移。模型侧的工具名（git_status、git_commit、github_pr_* 等）刻意保持不变——它们命名的是操作，不是产品。

功能特性

• 引导流程条（顶部）：可视化展示 GitHub-Flow 六个阶段：分支 → 提交 → 推送 → PR → 评审 → 合并。
• 分支管理：查看本地/远程分支、切换、新建、删除、重命名、合并、拉取、检出远程分支。
• 变更视图：文件状态（已暂存/未暂存/未跟踪）、暂存/取消暂存、提交、Diff 查看（点击文件查看变更）、贮藏/弹出、推送、拉取、抓取。
• 提交图谱（GitLens 风格 Lane 布局）：三栏（列 / SHA / 主题），PR 徽章，cherry-pick 到当前分支，撤销提交。
• PR 管理：列出 PR、查看详情（检查、评审、评论）、创建 PR、Squash 合并、评审（通过 / 请求修改 / 评论）、添加评论。
• 议题（Issues）：列出议题、查看详情、创建新议题、添加评论。
• GitHub 集成：设备流 OAuth 登录、PAT 输入、复用 gh CLI、加密 Token 存储（Windows DPAPI）。
• 结构化 Git 工具（Agent 侧）：git_status、git_diff、git_branches、git_commit、git_push、github_pr_list/read/create/merge/comment/review、github_issue_list/read/create/comment。
• Agent 活动监视器：实时 SSE 事件流展示 Agent 正在执行的每次工具调用（开始/完成/失败），仓库观察器轮询捕获面板外的 bash git 操作（新提交 / 切换分支 / 工作区变更）。
• 面板内审批（面板权威）：Agent 的写操作在面板中弹出审批卡片，可直接批准或拒绝；与 DSH 原生弹窗并行竞速，先到者生效。原生通道的自动拒绝（包括 approval policy 为 never 时的 ghost deny，例如 danger-full-access 预设自带 never）不能否决面板卡——任何审批策略下写操作都能走面板审批。面板决定一次性有效且不落盘；无面板在线时快速失败并提示打开面板（或先在面板中预批准），不再静默挂死。
• 多语言：自动跟随 DSH Web 界面语言（中文 / 英文）。
• 主题：面板不带自研调色板，颜色全部来自宿主主题令牌，因此明暗与第三方皮肤都能生效。
• 两种宿主形态：装了 dsh-better-sidebar 时，面板把自己注册成它的一个页签并把右栏让给它；没装时保留自己的右栏卡片，且可折叠。详见下文。

安装

dsh plugin --profile web add dsh-git-manager

本地开发：

dsh plugin --profile web add link:/path/to/dsh-git-manager

重启 dsh web，打开一个绑定 git 仓库的会话，右侧面板即显示「Git 管理」。

架构

src/
  index.ts           # Cordis 插件入口：注册路由 + 工具 + 系统提示词
  tools.ts           # Agent 侧结构化 git/GitHub 工具（写操作审批竞速）
  core/types.ts      # 共享类型定义
  host/
    git-service.ts   # 以工作区为边界的 git 操作服务
    routes.ts        # /gitm/* HTTP 路由（含 SSE 事件流 /gitm/events、审批端点）
    event-bus.ts     # 内存事件总线 + 预批准表 + 面板审批 Broker + 仓库观察器
    github-service.ts # GitHub REST 封装（Token 不离开宿主进程）
    github-auth.ts   # 设备流、DPAPI Token 加密存储、gh CLI 同步
  client/
    index.ts         # 浏览器端入口：选择宿主（better-sidebar 页签 / 独立卡片）
    embed.tsx        # better-sidebar 页签注册（结构化类型，可选 peer）
    shell.tsx        # 独立宿主：可折叠的右栏卡片
    Panel.tsx        # 主面板：分支 / 变更 / 图谱 / PR / 议题 / GitHub / Agent
    styles.ts        # 全部样式，建立在宿主主题令牌之上（见 DESIGN.md）
    api.ts           # /gitm/* 路由的类型化 Fetch 封装
    events.ts        # SSE 订阅 + 页签角标共用的共享事件存储
    i18n.ts          # 中英文双语词典
    icons.tsx        # 图标唯一来源（16px 网格、1.5 笔重内联 SVG）
    graph.ts         # 提交 DAG Lane 布局算法

宿主形态

面板不抢占宿主已经拥有的表面：

• 装了 dsh-better-sidebar —— 面板注册成它的一个侧栏页签（dsh-git-manager:panel，标题「Git 管理」，单实例幂等），不再自己挂右栏。从侧栏的「新建页签」列表里打开，之后随会话持久化。页签上带实时角标：当前有多少个写操作在等你批准。
• 没装 dsh-better-sidebar —— 面板保留自己的右栏卡片，头部多一个收起把手。收起后只剩头部条，并停止全部轮询（不会在后台继续打 git），状态落 localStorage。

探测是运行时的（ctx.get('betterSidebar')），所以 better-sidebar 始终只是可选 peer：没有硬依赖、构建期不 import 它的类型；注册失败也只降级成独立卡片，不会把面板弄丢。也可以用 localStorage['gm.host'] = 'dock' | 'tab' 手动覆盖（默认自动）。

面板还会跟随所属会话的工作区：先取宿主给的 scope.cwd，没有就用"当前选中的会话"；你切换会话时它自动切到对应仓库——没见过的仓库会先自动收录（宿主会向上找到最内层的仓库根，所以会话停在一个嵌套仓库里时，选的是那个仓库而不是包着它的工作区）。绝不覆盖你手动选的仓库。

什么算"我正在改的文件夹"

会话的工作区往往只是个容器——D:\Harness 里套着十几个独立仓库——只看会话 cwd 永远不知道你此刻在动哪一个。所以宿主还盯着 tools/execute：取文件类工具（read / write / edit / grep / glob 等）的路径参数，向上找到所属仓库根，把它自动收进下拉框。还不存在的文件也算——观测发生在工具执行之前，write 新建文件恰恰是最该被看见的那一类活动。

• 自动收进来的条目标了 auto，下拉框里显示成 名字 · 自动：货架自己长了要看得见，才不会变成一件玄学。
• 自动条目上限 20 条，超了淘汰最旧的自动条目；手动收录的一条都不会动。
• 每收一条就往活动流里发一条 repo:auto-added。
• 想关掉：在插件那一行加 config.autoRegisterRepos: false——下面的悬挂条仍会显示正在动什么。

下拉框下面常驻一条两行悬挂提示，两个问题一眼可答：

会话文件夹   D:\Harness
正在修改     D:\Harness\dsh-learn-wiki

第一行是面板跟随的会话文件夹，第二行是 agent 此刻在动的文件夹（写类工具显示「正在修改」，只读类显示「正在读取」）。当第二行是个已收录、但不是当前选中的仓库时，旁边会出现一个切过去按钮。

开发

pnpm install
pnpm run build

构建产物：lib/（宿主端）和 client/（浏览器端 bundle）。

node scripts/test-activity.mjs   # 文件活动自动收录（在临时 home 下跑，不碰真实货架）

许可证

MIT