仓库与工作区
本页讲群怎么绑定 git 仓库(主仓库与附加仓库)、每个 Bot 在哪些目录里干活、怎样更换工作区、同步模式,以及如何清理工作区。
先分清两个词:
- 仓库:群绑定的 git 仓库地址和分支。一个群有一个主仓库(带基准分支),还可以加多个附加仓库。
- 工作区:每个 Bot 在它所在机器上实际干活的目录。同一个群里每个 Bot 各有各的工作区,互不干扰。
仓库相关的设置都在「群设置 → 仓库与同步」里,只有群管理员能改,其他成员只读。
绑定仓库
新建群时在「发起会话」对话框最下方选,或事后由群管理员在「群设置 → 仓库与同步 → 代码仓库」点「绑定仓库…」。
选择仓库
- 点「仓库」一行,打开仓库选择面板。
- 从「最近」或已连接的 GitHub / GitLab 账号里选择,或在「搜索仓库,或粘贴地址」里直接粘贴地址,点「使用地址 …」。列表里标「本机已有」的仓库,说明你的机器上已经有它的克隆;「N 个群在用」表示团队里已有群绑定了它。
- 在「基准分支」里确认分支,默认
main。
不需要仓库时选「不绑定仓库」,各 Bot 使用本机目录,见 没有绑定仓库的群。
支持的地址格式:
| 格式 | 示例 |
|---|---|
| SSH | git@github.com:xinghe/todo-app.git |
| HTTPS / HTTP | https://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 单独建的目录,路径形如:
~/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 无法访问仓库」通知。
- Bot 主人点提示条上的「去配置」,在这台机器的「Git 访问」里配置 SSH 密钥或 HTTPS 令牌。
- Bot 主人或群管理员点「重新检查」,机器会重新克隆。
没有绑定仓库的群
没绑定仓库的群和私聊里,Bot 用主人在 Bot 设置里填的「默认工作区」;没有默认工作区,或默认工作区不可用时,改用托管目录,第一条 @ 就能执行。目录可以不是 git 仓库。
Bot 主人随时可以用「更换工作区…」换成别的目录。
Git 条
群头部的 Bot 条上,每个 Bot 显示工作区的分支、落后(↓N)/ 领先(↑N)和未提交改动;有未提交改动时,点增删行数可以直达代码审查。

每个 Bot 的工作区菜单里有「查看改动」「浏览文件」「更换工作区…」(仅 Bot 主人)「Git 面板」。提交、推送、切换分支等操作见 Git 管理,查看改动与文件见 代码变更与文件,上下文占用见 上下文占用与压缩。
用 /cd 绑定本机目录
除了在界面里「更换工作区…」,Bot 主人也可以在群里用 /cd:
/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 所在机器上:
gg workspaces每行显示「群 × Bot」、类型(托管 / 托管 · 无仓库 / 本机目录)、路径和状态:
| 状态 | 含义 |
|---|---|
| 运行中 | 正在使用 |
| 空闲 | 在用,当前没有运行 |
| 已移出 · 大小 | Bot 已移出、Bot 已删除或群已解散 |
| 未使用 · 大小 | 群和 Bot 还在,但 Bot 已改用别的目录 |
删除不再需要的托管工作区:
gg workspaces --delete <群>/<Bot><群>、<Bot>可以写 ID 或名字;只能删除「已移出」或「未使用」的托管工作区。- 本机目录永远不会被删除。
- 也可以在共工空间桌面端的「工作区」页操作,见 桌面端功能页面。
TIP
机器被吊销绑定时,daemon 会清理本机全部托管工作区;本机目录与备份保留。
命令完整参数见 命令参考。