仓库与工作区

本页讲群如何绑定 git 仓库、每个 Bot 在哪个目录里干活、Git 条怎么看、用 /cd 让 Bot 在本机目录工作，以及如何清理工作区。

先分清两个词：

• 仓库：群绑定的 git 仓库地址和基准分支，整个群共用一个。
• 工作区：每个 Bot 在它所在机器上实际干活的目录。同一个群里每个 Bot 各有各的工作区，互不干扰。

群的模式

群目前只有分区模式：每个 Bot 在自己的机器、自己的工作区里独立干活，改动留在各自的工作区，不会自动同步给其他 Bot。需要合并时，让 Bot 按你们的 git 流程提交分支、推送或提 PR 即可。

绑定仓库

新建群时在对话框里填，或事后由群管理员在「群设置 → 仓库与工作区」里「绑定仓库…」。

选择仓库

1. 点「仓库」一行，打开仓库选择面板。
2. 从「最近」或已连接的 GitHub / GitLab 账号里选择，或在「搜索仓库，或粘贴地址」里直接粘贴地址，点「使用地址 …」。
3. 在「基准分支」里确认分支，默认 main。

支持的地址格式：

格式	示例
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 在它自己的机器上用机器已有的 git 凭据检查能否访问：

结果	含义
可访问 · HTTPS / 可访问 · SSH	可以克隆
无权限 · 进群后暂停	这台机器没有访问权限，或仓库不存在
网络或证书 · 进群后暂停	网络不通或证书问题
超时 · 进群后暂停	连接超时
离线 · 上线后验证	机器不在线，上线后再检查
分支不存在	基准分支不存在，不能绑定

• 只有「分支不存在」会阻止绑定。其他失败的 Bot 照样进群，只是先暂停，见下文 Bot 暂停。
• 你没改过分支、而 main 不存在时，会自动换成仓库的默认分支。
• 群里还没有 Bot 时，显示「没有可检查的 Bot · 进群后由各 Bot 的机器验证」。

凭据与协议

• 克隆用的是每个 Bot 所在机器上的 git 凭据（SSH 密钥或凭据管理器），服务器不保存克隆凭据。请 Bot 主人先在自己机器上确认能 git clone 这个仓库。
• 在头像菜单 →「设置…」→「Git 与仓库」→「协议偏好」里，可选「按仓库地址」「优先 SSH」「优先 HTTPS」，决定你的 Bot 克隆或检查时先尝试哪种协议；失败时自动换另一种再试。
• 「已连接的账号」里「添加账号…」可接入 GitHub / GitLab 的 Token。Token 只用于在选择面板里列出仓库和分支，加密保存在服务器，不用于 clone。

更换仓库

群管理员在「群设置 → 仓库与工作区」里点「更换…」。

WARNING

更换仓库后，各 Bot 的托管工作区会重建，/cd 绑定和会话也会清空。仓库一旦绑定，只能更换，不能解绑。

每个 Bot 的工作区

「群设置 → 仓库与工作区」的「各 Bot 的工作区」列出每个 Bot 的状态：

状态	含义
托管克隆 · 就绪	已克隆好，可以干活
克隆中…	正在克隆
等待上线	机器离线，上线后克隆
已暂停 · 无权限 / 网络或证书 / 超时	机器无法访问仓库
未选择工作区	主人还没给它选工作区
本机目录路径	用 /cd 或手动选择了本机目录

Bot 主人可以点「更改…」重新选择工作区（机器离线时不可用）。

托管工作区

绑定了仓库的群里，Bot 进群后默认使用托管工作区：它的机器自动把仓库克隆到一个独立目录，路径形如：

~/.gonggong/workspaces/<群 ID>/<Bot ID>/<仓库 ID>/

• 每个群、每个 Bot 一个目录，彼此隔离。
• 群里依次出现「某某 加入 · 使用托管工作区，等待本机克隆…」「某某 · daemon 已 clone 到托管工作区」。
• 工作区没准备好之前，@ 这个 Bot 不会执行。

选择其他目录

Bot 主人点「更改…」或提示条上的「绑定工作区」，打开「为 某某 选择工作区」：

• 「托管克隆群仓库」（推荐）：在机器上自动克隆到独立目录，互不干扰。
• 「使用本机已有的仓库目录」：直接用机器上已有的克隆，免 clone。
• 「使用默认工作区」：Bot 设置里填的默认目录。
• 或浏览机器上的目录，进入具体项目后点「选择此目录」。

选择的目录不是群仓库时会提示「该目录不是群仓库」，确认「仍然使用」后，这个 Bot 不再使用群仓库和基准分支，只影响它自己。

以下目录不能用：不存在的目录、根目录或用户主目录（「目录范围过大，请选择具体的项目目录」）、系统目录（「不能使用系统目录」）。

两个 Bot 用同一个目录

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

Bot 暂停

机器无法访问仓库时，群里出现提示条，如「某某 已暂停：所在机器无法访问仓库（无权限或仓库不存在）」。

1. Bot 主人在这台机器上配置好 git 凭据。
2. Bot 主人或群管理员点提示条上的「重新检查」，机器会重新克隆。

没有绑定仓库的群

没绑定仓库的群和私聊里，Bot 使用主人在 Bot 设置里填的「默认工作区」；没填时群里提示「等待 某某 绑定工作区」，由 Bot 主人为它选一个目录。目录可以不是 git 仓库。

这种群的 Git 条不显示分支等 git 信息。

Git 条

绑定了仓库的群，群头部下方有一条 Git 条，每个 Bot 一段：

显示	含义
分支名	工作区当前分支
↓N	落后远端 N 个提交
↑N	领先远端 N 个提交
未提交	工作区有未提交的改动
托管 / 本机目录	工作区类型
待绑定 / 待创建 / clone 中… / 工作区创建失败	工作区还没就绪

• 「改动」：打开这个 Bot 的改动。有未提交改动时显示未提交内容，否则对比基准分支。
• 「文件」：浏览这个 Bot 工作区的文件。
• 状态在每轮运行结束后刷新。Git 条只用于查看，没有提交、推送按钮。

改动与文件的查看方式见 代码变更与文件。Git 条上还有每个 Bot 的上下文占用，见 上下文占用与压缩。

用 /cd 在本机目录干活

Bot 主人可以用 /cd 让 Bot 直接在它所在机器上的某个目录里干活，例如你本地正在开发的项目：

/cd @后端助手 /Users/wanglei/code/todo-app

恢复托管工作区：

/cd @后端助手 --reset

• 只有 Bot 主人能用，路径必须是 Bot 所在机器上的绝对路径，Bot 需要在线。
• 目录校验与上文「选择其他目录」相同，校验失败时保持原工作区不变。
• 群里依次出现「已请求 某某 绑定到 …，等待本机校验…」和「✓ 某某 已绑定到 …（本机目录）」。
• 之后目录被删除，运行会失败并提示「/cd 目录不存在」。

恢复托管的三种方式：群里发 /cd @Bot --reset；在机器上执行 gg workspaces --reset-cd <群/Bot>；在共工空间桌面端「工作区」页点「改回托管」。

完整语法见 指令参考。

工作区清理

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

在 Bot 所在机器上查看：

gg workspaces

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

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

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

gg workspaces --delete <群>/<Bot>

<群>、<Bot> 可以写 ID 或名字。

• 只能删除「已移出」或「未使用」的托管工作区。
• /cd 绑定的本机目录永远不会被删除。
• 也可以在共工空间桌面端「工作区」页点「删除…」，见 桌面端功能页面。

TIP

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

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

相关页面

• 群与私聊
• 指令参考
• 代码变更与文件
• Bot 设置与权限