Skip to content

仓库与工作区 ​

本页讲群怎么绑定 git 仓库(主仓库与附加仓库)、每个 Bot 在哪些目录里干活、怎样更换工作区、同步模式,以及如何清理工作区。

先分清两个词:

  • 仓库:群绑定的 git 仓库地址和分支。一个群有一个主仓库(带基准分支),还可以加多个附加仓库。
  • 工作区:每个 Bot 在它所在机器上实际干活的目录。同一个群里每个 Bot 各有各的工作区,互不干扰。

仓库相关的设置都在「群设置 → 仓库与同步」里,只有群管理员能改,其他成员只读。

绑定仓库 ​

新建群时在「发起会话」对话框最下方选,或事后由群管理员在「群设置 → 仓库与同步 → 代码仓库」点「绑定仓库…」。

选择仓库 ​

  1. 点「仓库」一行,打开仓库选择面板。
  2. 从「最近」或已连接的 GitHub / GitLab 账号里选择,或在「搜索仓库,或粘贴地址」里直接粘贴地址,点「使用地址 …」。列表里标「本机已有」的仓库,说明你的机器上已经有它的克隆;「N 个群在用」表示团队里已有群绑定了它。
  3. 在「基准分支」里确认分支,默认 main。

不需要仓库时选「不绑定仓库」,各 Bot 使用本机目录,见 没有绑定仓库的群。

支持的地址格式:

格式示例
SSHgit@github.com:xinghe/todo-app.git
HTTPS / HTTPhttps://github.com/xinghe/todo-app.git
ssh://ssh://git@git.example.com:2222/xinghe/todo-app.git

地址格式不对时提示「地址格式不正确,支持 git@ / https:// / http:// / ssh://」。

访问检查 ​

填好地址后,系统让群里每个 Bot 在它自己的机器上检查能否访问:

仓库选择与访问检查

结果含义
可访问可以克隆,并标出用的是 HTTPS 还是 SSH
无权限 · 进群后暂停这台机器没有访问权限,或仓库不存在
网络或证书 · 进群后暂停网络不通或证书问题
超时 · 进群后暂停连接超时
离线 · 上线后验证机器不在线,上线后再检查
分支不存在基准分支不存在,不能绑定
  • 只有「分支不存在」会阻止绑定。其他失败的 Bot 照样进群,只是先暂停,见 Bot 暂停。
  • 群里还没有 Bot 时,显示「没有可检查的 Bot · 进群后由各 Bot 的机器验证」。

凭据 ​

  • 克隆用的是每个 Bot 所在机器上的 git 凭据。机器主人可以在网页上为机器配置 SSH 密钥和 HTTPS 令牌(机器的「Git 访问」),也可以沿用机器上已有的 SSH 密钥或凭据管理器,见 我的机器与 Bot。
  • 头像菜单 →「设置…」→「Git 与仓库」→「协议偏好」:「按仓库地址」「优先 SSH」「优先 HTTPS」,决定你的 Bot 克隆或检查仓库时优先尝试哪种协议。
  • 同一页的「已连接的账号」→「添加账号…」可接入 GitHub / GitLab 的 Token。Token 只用于在选择面板里列出仓库和分支,加密保存在服务器,不用于 clone。

主仓库与附加仓库 ​

「群设置 → 仓库与同步」的「代码仓库」列出群的全部仓库:主仓库标「主」并显示基准分支,附加仓库显示各自的分支。

操作按钮说明
添加附加仓库「添加仓库…」绑定主仓库后才有。每个附加仓库单独指定分支
更换主仓库主仓库的「更换…」各 Bot 的自动克隆将重建
更改附加仓库附加仓库的「更改…」换地址或分支
移除附加仓库「移除…」各 Bot 从下一轮起不再使用它并开始新会话;已有克隆保留在各自机器上,不会删除
解绑主仓库「解绑…」要先移除其他仓库并切回分区模式
  • 各 Bot 默认自动克隆每个仓库,附加仓库克隆在主仓库旁边。Bot 主人可以把某个附加仓库改用本机已有的克隆(remote 须一致),见下文。
  • 附加仓库按各自的分支提交和推送,不参与强制同步。Git 状态、提交、推送和基准分支保护都按仓库分别处理,见 Git 管理。

解绑主仓库后:自动克隆的 Bot 改用默认工作区,没有默认工作区的需要主人重新选择;已使用本机目录的 Bot 不变;自动克隆保留在各自机器上,不会删除。

推送规则 ​

绑定仓库后,「推送规则」里有「禁止直推基准分支」:打开后,Bot 在功能分支上提交,推送到基准分支需要 Bot 主人审批。

每个 Bot 的工作区 ​

在「群设置 → Bot」里,每个 Bot 下方显示它主工作区的状态:

状态含义
自动克隆 · 就绪已克隆好,可以干活
克隆中…正在克隆
等待上线机器离线,上线后克隆
待主人确认等 Bot 主人选择工作区,见下文
已暂停 · 无权限 / 网络或证书 / 超时机器无法访问仓库,见 Bot 暂停
本机目录路径用的是机器上已有的目录

点「工作区…」打开「某某 的工作区」,列出这个 Bot 在本群用到的全部目录:主仓库(或主目录)、每个附加仓库、自带的附加目录。只有 Bot 主人能修改,改动从下一轮起生效并开始新会话。

进群时用哪个目录 ​

情况Bot 用的工作区
绑定了仓库,Bot 主人的机器在线先「待主人确认」:群里提示「等待 某某 确认工作区:自动克隆或使用本机已有目录」,主人选好后才开始干活
绑定了仓库,机器离线托管工作区,上线后自动克隆
没绑定仓库,Bot 设置了默认工作区默认工作区,群里提示「使用默认工作区 …(主人可改绑)」
没绑定仓库,也没有默认工作区托管目录,第一条 @ 就能执行
别人和共享给他的 Bot 私聊独立的托管工作区,不碰主人的目录

待确认期间 @ 这个 Bot,群里提示「某某 等待 某某 确认工作区,本次未执行;确认后重新发起即可」。Bot 主人点群里提示条上的「确认工作区」,或在 Bot 页点「选择工作区…」即可。

托管工作区 ​

托管工作区是共工在机器上为这个群、这个 Bot 单独建的目录,路径形如:

text
~/gonggong/workspaces/<群名>/<Bot 名>/<仓库名>/
  • 名字在创建时确定,之后群或 Bot 改名不会搬目录;重名的自动加 -2。没绑定仓库时最后一级是 _empty。
  • Docker 里运行的机器在 /home/gg/gonggong/workspaces/ 下。
  • 旧版本放在 ~/.gonggong/workspaces/ 里的克隆,会在这个 Bot 下次运行或绑定、且没有任务在用时自动搬过来,未提交的改动、分支与 stash 都保留。搬迁后的第一次运行会开新会话。

更换工作区 ​

Bot 主人有三个入口:群头部 Bot 条上这个 Bot 的工作区菜单「更换工作区…」、「工作区…」对话框里主仓库的「更改…」、群里提示条上的按钮。都会打开「为 某某 选择工作区」:

选择工作区

  • 「使用本机已有的仓库目录」(免 clone):机器上已有这个仓库的克隆时列出。
  • 「自动克隆群仓库」(推荐):在机器上自动克隆到独立目录,互不干扰。
  • 「使用默认工作区」:Bot 设置里填的默认目录。
  • 「使用托管目录」:没绑定仓库时出现,共工在机器上为这个会话单独建的目录,不碰你已有的文件。
  • 或在下方浏览机器上的目录,进入具体项目后点「选择此目录」。

选的目录不是群仓库时,会提示「该目录不是群仓库」,并说明群的基准分支与自动克隆对这个 Bot 不再生效、只影响它自己;确认「仍然使用」后生效。

机器离线时不能更换(「机器离线,上线后可更改」)。

附加仓库与附加目录 ​

在「某某 的工作区」对话框里,Bot 主人还可以:

  • 附加仓库:点「改用本机目录…」,选这个仓库在本机的克隆;点「改回自动克隆」恢复。每个附加仓库都显示分支、领先 / 落后和未提交状态。
  • 「添加目录…」:让 Bot 额外使用机器上的其他目录,最多 10 个。点「−」移除。
  • 没绑定仓库的分区模式群里,附加目录可以「设为主工作区」。

目录选择器 ​

选目录时打开的是机器上的目录浏览器:

  • 左侧有「位置」(桌面、文稿、下载等)、「隐藏文件夹」快捷入口和「最近使用」,可勾选「显示隐藏文件夹」。
  • 可以搜索、按名称或修改时间排序,或「新建文件夹」。Windows 机器可以切换磁盘。
  • git 仓库会显示当前分支和 remote。

以下目录不能选:

  • 共工托管的工作区:提示「这是共工按群托管的工作区,原群删除 Bot 或清理空间时会被删掉。请把仓库克隆到其他目录(如 ~/code)再选择。」
  • 根目录或用户主目录:「目录范围过大,请选择具体的项目目录」。
  • 系统目录:「不能使用系统目录」。

两个 Bot 用同一个目录

两个 Bot 的工作区指向同一个真实目录、又同时要运行时,群里会出现提问卡片,让你选择「并行开始」或「排队等待」。改动范围不重叠时可以并行;改到同一文件会互相覆盖。

Bot 暂停 ​

机器无法访问仓库时,群里出现提示条,如「某某 已暂停:所在机器无法访问仓库(无权限或仓库不存在),在这台机器的「Git 访问」里配置后重新检查」。这时 @ 它不会执行,群里提示「…本次未执行;某某 配置后点「重新检查」」,主人还会收到「Bot 无法访问仓库」通知。

  1. Bot 主人点提示条上的「去配置」,在这台机器的「Git 访问」里配置 SSH 密钥或 HTTPS 令牌。
  2. Bot 主人或群管理员点「重新检查」,机器会重新克隆。

没有绑定仓库的群 ​

没绑定仓库的群和私聊里,Bot 用主人在 Bot 设置里填的「默认工作区」;没有默认工作区,或默认工作区不可用时,改用托管目录,第一条 @ 就能执行。目录可以不是 git 仓库。

Bot 主人随时可以用「更换工作区…」换成别的目录。

Git 条 ​

群头部的 Bot 条上,每个 Bot 显示工作区的分支、落后(↓N)/ 领先(↑N)和未提交改动;有未提交改动时,点增删行数可以直达代码审查。

群头部 Git 条

每个 Bot 的工作区菜单里有「查看改动」「浏览文件」「更换工作区…」(仅 Bot 主人)「Git 面板」。提交、推送、切换分支等操作见 Git 管理,查看改动与文件见 代码变更与文件,上下文占用见 上下文占用与压缩。

用 /cd 绑定本机目录 ​

除了在界面里「更换工作区…」,Bot 主人也可以在群里用 /cd:

text
/cd @后端助手 /Users/wanglei/code/todo-app
/cd @后端助手 --reset
  • 只有 Bot 主人能用,只在分区模式可用;路径必须是 Bot 所在机器上的绝对路径,Bot 需要在线。
  • 路径是某个附加仓库的克隆时,用作这个附加仓库的本机目录;否则替换主工作区。
  • --reset 回到托管工作区。
  • 群里依次出现「已请求 某某 绑定到 …,等待本机校验…」和「✓ 某某 已绑定到 …(本机目录)」。

完整说明见 指令参考。在机器上也可以用 gg workspaces --reset-cd <群>/<Bot> 改回托管。

同步模式 ​

「群设置 → 仓库与同步 → 同步模式」:

模式说明
分区模式(默认)各 Bot 在自己的工作区独立工作,互不同步。需要合并时,让 Bot 按你们的 git 流程提交分支、推送或提 PR
强制同步参与的 Bot 工作区保持一致:每轮结束后改动自动分发给其他 Bot(不同步 .git)
  • 只有群管理员能切换,且绑定仓库后才能切换为强制同步。
  • 「切换为强制同步」时要选一个「基准 Bot」:它当前的工作区文件(含未提交改动)生成第一个版本,其他 Bot 的工作区对齐到它。对话框会列出每个 Bot 的处理方式,例如用本机目录或有未提交改动的 Bot「不参与」。对齐会覆盖工作区,被覆盖的文件先备份到本机。
  • 强制同步群里,群设置侧栏多一行「同步状态」,显示当前版本和一致的 Bot 数。附加仓库和附加目录不参与同步。
  • 「切回分区模式」:停止同步,各 Bot 保留当前文件各自发展;服务器存档保留 30 天。

工作区清理 ​

Bot 被移出群、群被解散、Bot 被删除时,工作区不会自动删除,由 Bot 主人决定。

网页上:在「机器与 Bot」里打开这台机器的「工作区」页,可以查看工作区占用并清理,见 我的机器与 Bot。

在 Bot 所在机器上:

bash
gg workspaces

每行显示「群 × Bot」、类型(托管 / 托管 · 无仓库 / 本机目录)、路径和状态:

状态含义
运行中正在使用
空闲在用,当前没有运行
已移出 · 大小Bot 已移出、Bot 已删除或群已解散
未使用 · 大小群和 Bot 还在,但 Bot 已改用别的目录

删除不再需要的托管工作区:

bash
gg workspaces --delete <群>/<Bot>
  • <群>、<Bot> 可以写 ID 或名字;只能删除「已移出」或「未使用」的托管工作区。
  • 本机目录永远不会被删除。
  • 也可以在共工空间桌面端的「工作区」页操作,见 桌面端功能页面。

TIP

机器被吊销绑定时,daemon 会清理本机全部托管工作区;本机目录与备份保留。

命令完整参数见 命令参考。

相关页面 ​

基于 Apache License 2.0 开源