工作区
工作区是你在 Codeg 中真正完成工作的地方。它把四样东西放在同一个屏幕上——智能体的对话、你项目的文件、它的 git 变更，以及一个终端——让提示、审阅、提交的整个闭环在同一处完成，无需在编辑器、diff 工具和 shell 之间来回切换标签页。
本页讲的是窗口本身——它的布局、侧边栏、标签页与分屏、终端。中间的对话有自己的一页，对话；右边的面板也是，右侧面板。
布局
桌面工作区是并排的四列，每一列都有自己的头部条，列与列之间由可拖动的细线分隔，细线从顶边一直贯穿到底部：
- 对话（最左）。 你打开过的每个文件夹中的每个会话——既是你的历史记录，也是你开启新会话的地方。它们按项目分组，每个都带有一个实时状态圆点：进行中、待复查、已完成。顶部的条上有定位当前会话、全部展开/折叠以及显示选项——标签筛选就在后者里——其下是新建会话和各导航行：自动化、待办任务、仓库面板和无限画布。自动化和待办任务各自带有自己的徽标——前者是失败的运行，后者是等你处理的任务数量——因此无论你身在哪个界面，需要照看的队列都会主动说话。
- 对话（中间偏左）。 智能体的对话记录，composer 停靠在底部。它的标签页在顶部，下方一条纤细的详情头部显示文件夹面包屑和该对话的标题，标题后面是它的标签。→ 对话
- 文件（中间偏右）。 你打开的文件的编辑器、diff 和实时预览——就在对话旁边，因此你可以在智能体做出更改时实时看到它们落地。它有自己的标签页条和一个文件路径详情头部。
- 右侧面板（最右）。 沿着它右边缘一条图标标签栏上的八个标签页——会话详情、文件、变更和提交，然后是项目的自动化、待办任务、议题和拉取请求——装着会话的详情、计划与消息导航，项目树，你工作树里的变更和历史，以及项目自己的工作。→ 右侧面板
终端在两个中间列的下方展开，底部的状态栏显示你的对话数量、更新提示、命令启动器、codeg-mcp 伴生服务的状态，以及最右端的告警——你的会话发出过的警告和错误，留在那里供你回头查找。打开电脑操作之后，那里也会多出它的图标。当连接到远程工作区时，它的名称也会显示在那里。点击那个对话数量会打开 Token 用量——按天、文件夹、智能体和模型拆开看你的智能体到底花了多少。
状态栏的最左端——也就是窗口的左下角——是快捷操作，一个把所有「只能经由某个会消失的东西才能到达」的入口都收拢起来的菜单。三个分组：
在 0.30.0 之前还有一个会话分组。它那两行作用于某一个文件夹，而这恰恰是状态栏里的启动器所没有的东西——并且两者本来就都在文件夹自己的右键菜单和「文件夹」标题栏上，所以这个分组被移除了，而不是留在那儿对着一个猜出来的文件夹动手。
重点不在于新增能力——每一个入口在别处都有自己的家。重点在于状态栏从不卸载，所以在侧边栏收起时，这里仍是一条进得去的路。远程工作区和宠物仅限桌面端。搜索被刻意排除在外，因为它自己的家同样不会消失——见下文。
当有更新的 Codeg 发布时，状态栏会主动告诉你，而不是等你到设置里去发现：一个 New v… 徽章会出现，点击后弹出一个浮层，其中包含版本号、完整的更新内容说明，以及可执行的按钮——与设置面板相同的下载 → 安装 → 重启流程，另加一个稍后用于暂时略过。忽略某个版本会在每个打开的窗口中一并静默它，并留下一个灰色图标让你随时还能回来；下一个版本会重新点亮徽章。→ 设置 → 系统
这里没有横贯整个宽度的标题栏——取而代之的是两个角落簇，它们在面板开合时保持原位：左上角切换侧边栏并打开搜索，右上角是终端、辅助面板和设置。搜索在 0.27 搬到这里，理由和快捷操作存在的理由完全一样：它原本是侧边栏里的一行，而侧边栏一收起就被卸载，于是 ⌘K 成了唯一入口。角落簇从不卸载，按钮上的提示还会显示你当前生效的 ⌘K 绑定。从 0.32.3 起，⌘K 打开搜索时光标已经停在搜索框里，而且无论你在对话和文件之间切换，还是选择某个智能体筛选，光标都会留在那里。（移动端在它的标题栏里得到同一个按钮，那里本来就没有快捷键。）被它挤走的远程工作区选择器移到了侧边栏列表的右键菜单中，单独成组——它上面的每一行都作用于本机，只有这一行是去往另一台主机的。每个面板都可以通过拖动调整大小，当你需要空间时，侧边面板和终端可以折叠收起——⌘B（对话）、⌘E（右侧面板；点一下它已选中的标签页也能把它关上）、⌘J（终端）。从 0.35.0 起，聊天区域本身也能拖动调整：拖动它左右任意一侧的边缘，它就会在两侧同时变宽或变窄，双击边缘则恢复默认（其余细节见聊天区域宽度）。在手机或狭窄的浏览器窗口中，侧边面板会变成滑入式抽屉。
待办任务、自动化、仓库面板、Token 用量和画布会接管整片区域，因此其中之一打开时，右上角那一簇会藏起此刻无从作用的终端与面板开关，右侧面板也会收起来，直到你回来。出路在页面标题的开头，它读起来像一条面包屑：一个会话按钮，提示为返回会话，然后是 › 和页面的名字。即便侧边栏已收起、屏幕上又没有对话可点，它也在那里；而它不改变别的任何东西：你原先所在的标签页会原样回来。有自己控件的页面会把它们放进那两个开关腾出来的位置：待办任务把视图切换和设置按钮停在那里，仓库面板停的则是刷新和设置。
面板从你工作的旁边滑入
从 0.28 起，每一个滑入式面板——移动端侧边栏、辅助面板、终端、设置导航、技能详情、任务详情、仓库工作项详情——都是一个内嵌抽屉，而不再是对话框：它离窗口边缘略有内缩、自带一道边线，而且背后的一切既不变暗也不冻结。下面那一层保持活着，这正是重点——这些面板是你一边工作一边查看的，而不是要先关掉才能回到手头事情的模态框。Esc、关闭按钮和滑动手势依然能关掉它；移动端那四个导航抽屉还额外保留了「点一下它们留出的那条页面」就收起的行为，因为在手机上人们就是这么收起面板的——而从 0.35.2 起，手机的返回手势也一样能把面板收起来。从 0.37.0 起，点一下已经选中的那个标签页，右侧面板的抽屉也会关上。
会话查看器可以层叠。 被委派的子智能体的对话记录、待办任务的会话、Grok 的子运行——这三者都会互相嵌套，因为一份子智能体的记录里本身就带着它自己的委派卡片，每张卡片又各有一个「查看会话」。它们从前是居中的模态对话框，彼此之间没有层叠关系，于是第二个直接把第一个埋了。现在每一个都在开启它的那一个内部打开，宽度全部相同，所以下层不会有一侧支棱出来。
随之消失的还有两个你本会当成 bug 的现象：查看器不再因为开启它的那张卡片滚出视野而关闭，而一个留在整页路由或后台标签页背后的查看器，也不会再画到取代它的东西上面——它是被隐藏后再恢复的，所以切回来时它还在你离开时的位置。
文件夹与侧边栏
左侧边栏是你的大本营：你打开过的每个文件夹（即一个项目目录），其对话都分组显示在其下方。打开一个项目文件夹即可添加（⌘O）。从 0.35.0 起，打开文件夹的对话框里有一个新建文件夹按钮，它会在你正在浏览的位置新建一个文件夹并进入其中，于是一个项目可以从一个空目录起步——桌面端和浏览器里都一样。右键点击文件夹的标题栏（或点击其 ⋯），即可看到你能对它执行的所有操作：
- 设置默认智能体。 选择某个文件夹应使用的智能体，之后你在该文件夹中开启的每个新对话都会预选它。选择不设置（使用全局默认）可回退到你的全局选择。它只设定智能体——一旦该智能体连接，模型和模式仍由它提供。
- 修改颜色。 为文件夹指定一种强调色，让它的分区在你同时处理多个项目时更醒目。该颜色会为侧边栏中的文件夹及其对话着色；但不会延续到标签页中。
- 设置别名。 给文件夹起一个更友好的显示名称，而不改动磁盘上的任何东西——它会在侧边栏和对话头部显示为 别名 [ 文件夹 ]。把输入框留空即可清除它，回到原始名称。
- 导入本地会话。 打开导入窗口，并预先选中本项目的过往会话，从而把你各个智能体自己的历史拉入工作区——这正是 Codeg 对话聚合的实际运作。→ 对话聚合 介绍了它扫描哪些内容以及如何匹配。
- 会话管理。 批量选择对话来更改其状态或删除它们。它是从某个文件夹打开的，但并不锁定在那个文件夹上：一个搜索框占满整行，下方是四个由粗到细的筛选器——文件夹、分支、智能体、状态——因此无论你从哪里打开它，都能横扫整个工作区。分支按共同前缀折叠，
task/49和task/50会收进同一个task/下并带上计数，而每一行都会显示对话当初是在哪条分支上开始的。 - 关联的文件夹。 把其他目录以子目录的形式带进这个工作区，让一个智能体能跨它们一起工作。→ 跨多个文件夹工作
- 管理标签… 新建、编辑、排序和删除这个文件夹提供给自己会话的标签，全局标签也在这里。→ 给会话打标签
- 在外部打开。 在 Finder / Explorer / 你的文件管理器中显示该文件夹、在该处进入终端，或者——从 0.29.0 起——用 VS Code 打开它（仅桌面版）。VS Code 这一项在目录和单个文件上也有，不只在文件夹标题上。
- 从工作区移除。 将文件夹移出 Codeg——它的标签页和终端会关闭，但磁盘上的任何内容都不会被改动。
文件夹的真实名称始终是它在磁盘上的目录名——这一点永远不变——但设置别名可以给它一个更友好的标签，而颜色和分组能帮你一眼区分各个项目。
导入本地会话并不只在文件夹菜单里。右键点击列表周围的空白处也能找到同一项；而在一个还什么都没有的工作区上，这个按钮就直接摆在空状态里——挨着打开文件夹和项目引导——因为把你已有的东西导进来，通常是让一个全新的 Codeg 迅速充实起来的最快方式。那个空白处菜单也正是远程工作区选择器所在的地方，位于本机相关的那几项之下，单独成组。
右键点击一行对话会给出添加到会话，把它作为一枚提及徽章放进 composer——和 @ 面板、文件树产出的是同一种徽章。它落在你的光标处，点两次也不会加两遍。想说「看看那个会话里发生了什么」时，这是最短的一条路，不必再走 @ 然后敲名字。同一个菜单里还有一个标签子菜单，用来给这个会话打标签。
文件夹旁边的数字统计的是此刻正在其中运行的东西——正在工作的会话，worktree 也算在内——没有时它会消失。它是一个实时的负载指示，而不是总数，因此顺着侧边栏扫一眼，就知道你的智能体究竟都在哪儿。展开/折叠的箭头只在悬停时出现；文件夹图标本身已经说明了它是开是合。
把指针停在一个对话行上，旁边会浮出一张卡片，装着这一行本身放不下的东西：更多的标题（最多三行 —— 目的是让你看清它，而不是摊开一篇文章）、智能体、有记录时的模型、所属文件夹（认别名，是 worktree 时还会打上标记）、它的绝对路径、分支，以及它带着的每一个标签。如果这个会话是从一个后来被移除的 worktree 里重新挂过来的，它还会在源 worktree 已删除一栏点出原来的路径——自 0.37.0 起这是唯一会提到这件事的地方，因为那一行本身不再带标记。上面刻意没有状态：你指着的那一行本来就已经标出了值得提示的那两种状态。这不花任何请求，上面的一切本来就在内存里。在 0.29.0 之前，想知道这些只能开「会话详情」对话框，而那里连文件夹和它的路径都没有——并且当同一个仓库开着好几个 worktree 时，两行读起来是真的一模一样。
给文件夹分组
装着十几个仓库的工作区就是一条长长的平铺列表。文件夹分组是有名字、可以上色的带子，用来收纳文件夹 —— 而且它们和你那些零散的文件夹共用同一个顺序，于是两者可以交错排列，而不是把分组统统赶到某一端去。
用「文件夹」标题悬停时出现的新建分组按钮，或者在文件夹的右键菜单里选移动到分组 → 新建分组…，就能建一个分组。把文件夹拖到某个分组的标题上就放进去；拖到尾部的区域就拿出来；拖动分组本身则搬动整条带子。你拖着文件夹的时候，每个分组都会展开，折叠着的也不例外，于是没有哪里是够不到的。文件夹右键菜单里的移动到分组是同一件事的无指针版本。
分组也可以直接把文件夹收进来。自 0.37.0 起，鼠标悬停或用键盘聚焦分组标题时，它的 ⋯ 旁边会出现克隆仓库和打开文件夹——在触屏上则一直显示。它们打开的是和「文件夹」标题上同样的对话框，只是你打开或克隆的文件夹会直接落进这个分组，分组也会展开把它露出来。如果那是一个 worktree、而它的仓库已经打开，它会留在仓库旁边；克隆还没完成时你又从别处重新打开了对话框，克隆好的文件夹仍会进入你最初发起它的那个分组。
分组标题上带着一个把里面一切加总起来的运行中会话徽标，于是一个折叠着的分组也能告诉你：它下面某个项目是不是有智能体在干活。成员的缩进方式与 worktree 子项完全一致，导轨和对话一起位移，因为底下就是同一套机制。
三个分区，顺序由你定
侧边栏有三个顶层分区：
- 文件夹——你的项目，对话嵌套在各自之下。
- 聊天——不属于任何文件夹的对话，也就是你在聊天模式下开始的那些。
- 最近——把你此刻能够到的对话排成一张扁平列表，属于文件夹的和聊天的一并在内，从 0.39.0 起始终按最近活动时间排序，不受排序方式影响。不嵌套、不分组；它回答的是「我刚才在干什么？」，而不需要展开任何东西。它遵循与侧边栏其余部分相同的显示选项——已收起文件夹里的对话、在显示已完成会话关闭时的已完成对话，以及已经在置顶里的对话，都不会出现在这里。它一次显示 10 行，底部的显示更多每点一次多显示一页，而分区自己的计数徽标报告的仍是全部总数。从 0.28.2 起，那一行也能把列表收回去：一旦你展开到第一页之外，同一行上就会出现一个复位入口——于是一个你为找某样东西才展开的列表，不会在接下来的整个会话里一直占着屏幕，把它下面的分区挤出可视区域。只有当确实多显示了不止一页时才会提供它。它的标题栏上带着新建对话按钮，和「聊天」一样；从 0.32.3 起还多了一个 ⋯，可以把列表收窄为全部、聊天或文件夹——也就是只看无文件夹的聊天，或只看属于某个文件夹的对话。从 0.38.0 起，命令行可只显示由
codeg-cli发起的对话，这些对话还带有终端图标。这个选择会在本设备上记住，而且列表处于收窄状态时这个按钮会一直显示，所以一张筛选过的列表绝不会被误当成一张本来就短的列表。
这三个分区都可以在显示选项菜单里调整顺序——每个分区一行，带上移和下移（或在聚焦行上按 Alt+方向键）——而「最近」也可以整个关掉，如果你不想要它的话。
整理列表——显示选项
侧边栏顶部的三个按钮能让长长的历史保持可管理。定位当前会话会跳转到你所在的会话，并展开它被折叠在其后的任何层级。全部展开/折叠如今是它旁边一个独立的按钮，因为它作用于列表本身，而不是保存某个显示偏好——而且它折叠的是所有东西，包括扁平的聊天、最近和已置顶这几个分区标题，而不只是它们里面的文件夹分组。全部折叠后剩下四行标题、下面空无一物；再展开时，下面的文件夹会原样恢复，因为分区折叠和单个文件夹的折叠是分开记住的。
最后一个是一只眼睛，它打开显示选项：
- 按标签筛选（子菜单）——把列表收窄到带有你所选标签的会话。自 0.37.0 起它是这个菜单的第一项，取代了原先排在顶部那条最前面的漏斗按钮。→ 给会话打标签
- 会话列表（子菜单）——显示已完成会话，默认关闭，因此已完成的工作不会挡道，列表中呈现的就是仍在进行的内容；显示工作树分支，默认开启；以及显示「最近」分组，默认开启。
- 菜单导航项（子菜单）——见下文。
- 标签页跟随文件夹——分别保留各文件夹的会话标签页、文件标签页和分屏布局，默认关闭。→ 标签页跟随文件夹
- 排序方式——文件夹和聊天列表可选按创建时间排序（默认）或按更新时间排序；最近始终按最近活动排序。最近和聊天行显示最近活动时间，嵌套子会话仍显示创建时间。
- 区域顺序——上文所述的那个可排序列表。
筛选和那两组清单被放进了悬停展开的子菜单里，好让「排序方式」和「区域顺序」——人们真正会反复回来改的那两项——不必被埋在一个长菜单的最底部。另外两项则留在外层：一对单选按钮和一个可排序列表，藏在多一层跳转之后读起来不对，而顺序那几行也需要菜单的完整宽度。拨动一个开关或勾选一个标签，既不会关掉子菜单，也不会关掉菜单本身，因此改两项设置只需进去一次。
关于显示工作树分支：开启时，每个 worktree 都作为独立分组置于其仓库之下，带有自己的计数和颜色。它的标题栏也用项目标题栏那种别名 [ 名称 ] 的写法——task/49 [ codeg-task-49 ]，前面是检出在那里的分支，后面是它所在的目录——因此同一个仓库的好几个 worktree 一眼就能分清。从 0.30.0 起，仓库自己那一行也用同样的写法标注 —— main [ root ]，与它的 worktree 兄弟们对齐 —— 而不再是一个对分支只字不提的光秃秃的「root」。已有的 worktree 会在启动时被打上标签，而你自己起过的名字绝不会被覆盖。把它关闭即可把它们合并进父文件夹，成为单一列表。
选择你要看到哪些导航行
菜单导航项子菜单可以逐个开关侧边栏那四行整页入口：自动化、待办任务、仓库面板和无限画布。如果你不用 forge 集成，那一行不必一直杵在那里。
隐藏一行不会让你永久失去什么——每一条路由都仍可从状态栏的快捷操作到达，正因如此隐藏它们才是安全的。这个设置按设备保存，而一行你从未动过的入口是显示的，所以将来版本新增的路由到来时是可见的，而不会悄悄处于关闭状态。
给会话打标签
从 0.34.0 起，一个会话可以带上标签——每个标签有一个名称和一种颜色——紧跟在标题后面显示，侧边栏也可以筛选出带有这些标签的会话。标签分两种：
- 全局标签——所有会话都能用，聊天模式也包括在内。
- 文件夹自己的标签——只出现在那个文件夹的会话上，它的工作树中的会话也算在内。聊天模式的会话不属于任何文件夹，所以只能用全局标签。
名称在每一组里唯一——全局那一组，或某个文件夹那一组——且不区分大小写：全局的 bug 和某个文件夹自己的 bug 可以并存，但同一组里不能 Bug 与 bug 并列。
给会话打标签，有两个地方可以用：
- 会话头部。 标签就排在标题后面——没有标签时是一个标签图标，即添加标签——点一下就会打开选择器。可以搜索，点一个标签就给会话加上或取下；选择器不会关闭，所以一口气打三个标签也只要打开一次。输入一个还不存在的名称，它就会提出新建：新建全局标签“…”，以及用来建文件夹自有标签的在 文件夹 中新建“…”——聊天模式下没有后者。新建的标签会直接加到这个会话上，颜色取九个深色预设里第一个还没被旁边的标签——全局标签，或这个文件夹自己的标签——用掉的；九个都用掉之后，就会重复使用。
- 侧边栏。 右键一个会话，有一个标签子菜单。在那里勾选标签同样不会关掉菜单；新建标签…会打开完整的表单，其中可用范围可以选所有会话，或者仅 该文件夹。
会话身上还带着的、属于另一个文件夹的标签，会单独列在其他文件夹下面。它在那里只是为了让你取下；一旦取下，就加不回去了。子智能体会话——由委派派生出来的那些——不能打标签。
管理标签…——选择器底部、标签子菜单里、文件夹的右键菜单上，以及标签筛选的底部都有它——会打开一个统管这一切的对话框，并从你打开它时所在的文件夹开始：
- 最上面是分支标签——见下文。
- 然后是全局标签，再往下是文件夹标签，标题旁边有一个文件夹选择器。
- 每个标签都可以拖动到新位置、编辑和删除。你拖出来的顺序，就是标签在各处出现的顺序——先全局标签，再文件夹自己的。编辑只改名称和颜色，从不改变它属于哪一种。删除前会先确认，因为这个标签会从所有带着它的会话上取下，而且无法撤销。
- 新标签需要一个最多 64 个字符的名称和一种颜色——十八个预设色，分深浅两行，或者用自定义颜色选任意别的颜色。在对话框里添加的标签，属于哪一种由你添加时所在的分区决定。
标签显示在哪里。 侧边栏的一行在标题后面放得下两个标签，再往后是一个 +N，它的提示会列出其余的；标题太长时会先让出位置，但总会保留几个字。会话头部最多显示三个——窄屏上只有一个——而把指针停在一行上时浮出的那张卡片会把它们全部列出。存下来的一种颜色同时服务两种主题：浅色模式下是实心的标签，深色模式下是带提亮文字的淡色底。打标签不算活动，所以列表按更新时间排序时，会话不会因此挪位置。搜索、画布、标签页标题和会话详情里都不会出现标签。
按标签筛选。 显示选项 → 按标签筛选会打开一个面板，列出可供筛选的标签——先是全局标签，再是各个文件夹自己的——每个标签旁边都标着带有它的会话数，上方还有一个搜索框。匹配决定多个标签怎么组合——默认的任一显示至少带有其中一个的会话，全部则只显示每个都带的会话。筛选生效时，列表上方有一条会列出选中的标签，每个都能单独移除，旁边就是清除筛选；菜单里的按标签筛选那一行则会标出你选了几个标签。眼睛按钮本身不会高亮，所以那条横条就是提示。它会收窄每一个分区——已置顶、文件夹、聊天和最近——并拿掉筛完后空无一物的文件夹、工作树分组或文件夹分组；在文件夹、聊天和最近里，显示已完成会话仍会照常隐藏已完成的会话——已置顶一向不受它影响——文件夹的运行计数也不受影响。筛选条件按设备记住，而标签本身存放在 Codeg 的数据库里。
分支标签会把会话开始时所在的 git 分支——和会话管理里列出的是同一个，而不是现在检出的那个——作为一个标签放在它其余标签的前面，颜色由你选。它默认关闭：在对话框的分支标签下勾选显示即可。它计入各处的标签数量上限，也从不被折进 +N。不在 git 里的会话、聊天模式的会话、在分离 HEAD 上开始的会话都没有分支可显示，子智能体会话也不显示。
标签和分支标签的设置都存放在 Codeg 的数据库里，而不是窗口里，所以每个窗口看到的都一样、变化也会同步过来，浏览器会话能用上完整的功能，备份也会把它们带上。分叉出来的会话保留原会话的标签；导入的会话进来时不带标签。
跨多个文件夹工作
一个工作区不必只有一个目录。从 0.23.1 起，你可以把其他文件夹以子目录的形式关联进来——隔壁的服务、共用的库、旁边的文档仓库——智能体便能在同一段对话里跨它们读写。文件树会显示它们，工作区搜索会覆盖它们，@ 提及也能伸进去。
只需要一个动作：在侧边栏里右键该文件夹 → 关联的文件夹，然后添加文件夹，想选几个就选几个。（新打开一个文件夹时，在你选好主文件夹之后也会紧接着提供同一步，因此可以边创建边把工作区拼起来。）
它适合用来做什么
重点其实不在于"目录变多了"，而在于：主文件夹不必再是那个项目本身，而成了你组装项目的地方——需要多久就摆多久，不需要了就拆掉。
- 分处两个仓库的前端与后端。 把
api关联到web旁边，一个回合就能同时改动接口和调用它的代码——契约的两侧都摆在智能体眼前，而不是一侧加上一次猜测。 - 本周的改动实际涉及的那几个微服务。 把牵涉到的两三个关联进来，做完，解除关联，下周换一组。工作区于是成了一个看待你那些服务的视角，而不是一份需要你维护的检出。
- 一个自己不装任何代码的空目录。 专门建一个用来组装的目录——比如
~/work/current-task——需要什么就关联什么进去。事后没有任何东西要清理，因为那里本来就什么都没有。 - 代码与它的文档。 把文档仓库关联到代码仓库里，一次改动和描述它的那一页就能落在同一个会话、同一次评审里。（这份文档正是这样与 Codeg 本体保持同步的。）
- 想从源头修好的那个库。 把共用的包关联进依赖它的应用，智能体就能在缺陷真正所在的地方修它，而不是在调用方绕过去。
- 你无意改动的参考资料。 一个设计系统仓库、一份接口规范、另一个团队的服务。智能体照着真实的接口工作，而不是靠推测。
- 旧仓库与它的替代品并排摆着，用于把代码搬过去的那段时间——这种场景下，同时打开两棵树本身就是全部工作。
- 有意不放进仓库的样本数据。 把一个装着测试夹具或真实输入文件的目录关联进来，智能体就能拿它们跑，而这些东西一份也不会被提交。
底层是怎么回事
这些关联在磁盘上是真正的文件系统链接，这是有意为之：智能体 CLI 是以工作区主文件夹为工作目录运行的，因此一个只存在于 Codeg 界面中的合并，对它们而言根本不可见。既然它是一个真实的目录项，其余的一切也就顺理成章——ls 找得到它，智能体自己的文件工具找得到它，你的终端也找得到它。
在 macOS 和 Linux 上，它是一个符号链接。在 Windows 上，只要系统允许，它同样是符号链接；但创建符号链接需要一项权限，普通进程只有在开启开发者模式时才具备——因此 Codeg 会退而使用目录联接（junction），它不需要任何权限，对 Codeg 所关联的本地绝对路径而言行为完全一致。若两者都失败，界面会提示你开启开发者模式，或以管理员身份运行 Codeg。
每个被关联的文件夹以它自己目录的名字出现，并在文件树中标记为关联的文件夹。如果该名字在主文件夹中已被占用，Codeg 会消歧为 api-2，而不是覆盖任何东西——而且是不区分大小写的，因为 macOS 和 Windows 把 API 和 api 视为同一个条目。
之后如何管理
在同一个菜单里重新打开关联的文件夹，每个关联都会显示它当前的状态：
| 状态 | 发生了什么 | 该怎么做 |
|---|---|---|
| 已关联 | 一切正常 | — |
| 链接已从该文件夹中消失 | 有东西删掉了这个符号链接 | 重建链接 |
| 该名称已被其它条目占用 | 一个真实的文件或文件夹占了这个名字 | 重命名，然后重建 |
| 被关联的文件夹已不存在 | 目标被移动或删除了 | 按它的新路径重新关联 |
重命名只改变它在工作区里显示的名字——它所指向的那个目录仍然叫它自己的名字。解除关联只删除符号链接，别的什么都不动；被关联的文件夹本身永远不会被触碰。
那个界面上还有一个默认开启的开关，不让关联目录污染 git 状态：它会把关联的名字写进仓库的 .git/info/exclude。那个文件只属于你这份克隆，从不会被提交，所以别人的检出不会知道你的关联习惯。
它在工作区文件夹是一个 git 仓库时生效，并且是尽力而为的：即便规则写不进去，代价也只是 git status 更吵一点，绝不会导致关联失败。有两处值得知道的空缺——工作区若不是仓库，这条规则就无处可放；而重命名一个关联并不会把它的规则一并带过去，因此在你自己补上排除项之前，新名字会以未跟踪文件的形式出现。
有些选择它会直接拒绝，并告诉你是哪一类：工作区文件夹自身、包含工作区的文件夹、已经在它内部的东西（不需要关联——它本来就够得着），以及已经关联过的东西。
只有你自己建立的关联才会被跟随
Codeg 把每一次文件操作都限制在工作区主文件夹之内，而这道防线并不会对符号链接一路放行——它会比对你所创建的那份关联清单。所以你克隆下来的某个仓库即便自带一条 secrets -> ~/.ssh，它在你关联任何东西之后，依然和之前一样读不到。→ 隐私与安全
关联并不会延伸的两件事
有两样东西仍然只跟随工作区主文件夹。一是文件实时监听——智能体在被关联文件夹内做出的修改不会自动刷新文件树，需要你重新打开或刷新它。二是变更与提交面板跟踪的是主文件夹的仓库，因此被关联仓库自身的工作树改动与历史不会显示在那里。当你想审阅并提交那个仓库的改动时，请把它作为独立的文件夹打开。
对话，以及它旁边的面板
窗口中间属于对话——智能体的对话记录，下方停靠着 composer——它有自己的一页，对话：开启会话并设置智能体的模型、模式和各项选项，跟着一条回复流式出现，从一条已完成的回复分叉，在智能体还在工作时插话，以及一个回合失败或连接断开时会发生什么。
沿着窗口右边缘的那块面板——会话的详情、计划与消息导航，项目的文件和 diff，你的 git 变更，以及项目的自动化、待办任务、议题和拉取请求——见右侧面板。
运行已保存的命令
状态栏带有一个启动器，用于你反复运行的那些命令——开发服务器、测试监听。Codeg 会从你项目的 package.json 脚本中为该列表播种，因此你第一次查看时通常就已经有内容了；在那之前它显示为添加命令。从菜单中选一个，▶ 按钮就会在终端中运行它，并变成 ■ 用于停止——而从 0.35.0 起，停止时会保留那个终端以及它打印过的内容，而不是把它关掉。管理命令...可以添加、编辑、重新排序和删除它们，而你的选择会按文件夹被记住。
从 0.39.0 起，命令编辑器还提供两个开关：
- 在本机运行——即使当前文件夹在远程服务器上，也在运行桌面应用的电脑上执行。它不会打开集成终端，适合启动本机工具，例如用自己的编辑器打开远程项目。浏览器中不提供此开关。
- 在所有文件夹中显示——让命令在不同文件夹、worktree 和远程连接中都可使用，并保存在本机；关闭时，命令只属于当前文件夹。
本机命令会收到 CODEG_FOLDER_PATH（当前文件夹在其所属主机上的绝对路径）和 CODEG_REMOTE_HOST（远程服务器主机名，本地工作区时为空）。例如，配置好 Zed 和 SSH 后，在 macOS/Linux 上可以这样打开远程文件夹：
zed "ssh://user@$CODEG_REMOTE_HOST$CODEG_FOLDER_PATH"请把 user 换成你的 SSH 用户名。Windows 默认使用 cmd.exe，变量写法为 %CODEG_REMOTE_HOST% 和 %CODEG_FOLDER_PATH%。如果通过 SHELL 或 COMSPEC 指定了其他 shell，请使用该 shell 的环境变量语法，例如 PowerShell 中的 $env:CODEG_FOLDER_PATH。替换后的值应放在双引号内。要为远程文件夹自己的命令保存在本机运行开关，服务器也必须为 0.39.0 或更新版本；旧服务器可改为开启在所有文件夹中显示，将命令保存在本机。
终端
按 ⌘J 可在你的工作文件夹中打开一个集成终端——一个真实的 shell，而非沙箱。你可以在标签页中打开任意多个。它专为那些你更愿意自己运行的命令而存在：启动开发服务器、检查输出、在智能体旁边运行一次性脚本。
Ctrl+Shift+C 复制选区，Windows 上的 Git Bash 也包括在内，并且复制后焦点仍留在终端里 —— 而单纯的 Ctrl+C 保持它一直以来的含义：中断。
重新加载不会让你丢掉终端。 从 0.35.0 起，重新加载页面或重新连接之后，终端面板会原样回来：同样的标签页、其中的命令仍在运行，最近 128K 个字符的输出也会按终端自己的尺寸重放出来。已经结束的命令会一直保留它的输出，直到你关闭它的标签页——从前它会在十分钟后被丢弃。回不来的是 Codeg 本身的重启——那会结束这些 shell，之后恢复出来的标签页会显示终端会话不可用。新开或复制出来的浏览器标签页会有它自己的终端，而不会接管另一个标签页的。
在窄窗口下 —— 手机，或者任何小于 768 px 的宽度 —— 软键盘上方会浮着一条虚拟按键条，因为触屏键盘上一个 shell 需要的键都没有：ESC、TAB、/、-、四个方向键、HOME、END、PGUP 和 PGDN。CTRL 与 ALT 是闩锁而不是按住不放的键，而且两者互斥 —— 点一下它会高亮，接着你输入的下一个字符会被它包装，然后闩锁自动弹起，于是 Ctrl+C 是两下，而且对软键盘打出的字母和按键条自己的键都有效。无论如何这个闩锁都会被消耗掉：如果你按下它之后输入的那个字符它没有对应的编码，那个字符会原样送出去。这条按键条可以从终端的标签栏收起，收起状态会为那个浏览器或应用记住。
标签页与多任务处理
中间区域采用标签页形式，因此可以同时打开多个会话：
- 对话标签页可通过拖动重新排序，双击可固定。⌘T 打开新对话，⌘W 关闭标签页，⌘Tab 在它们之间循环切换。
- 文件标签页追踪你在文件窗格中打开的文件、diff 和预览。标签条末尾的 + 可以开一个空白浏览器标签页，并列出此刻正在运行的本机服务，于是智能体刚起的开发服务器只隔着一次点击。
- 最大化对话。 从 0.35.0 起，旁边开着文件时，对话标签页条右端的最大化按钮会把整个中间区域都交给对话，还原则把文件按你离开时的样子带回来。打开或切换到某个文件，也会让它们回来。拆分成分组时，只有右上角那个分组的标签页条上有这个按钮；手机上则没有。
- 未发送的草稿能在重启后保留。 你开启却从未发送的对话会回到原处——连你在 composer 里敲过的文字也一并回来。每个草稿都保留各自的文本，因此并排的两个草稿不会再互相覆盖。
标签页跟随文件夹
从 0.41.1 起，侧栏的显示选项 → 标签页跟随文件夹让每个文件夹分别保留自己的会话与文件标签页、当前选中项和分屏布局。开启后，点击文件夹即可切换到该项目的工作。无所属文件夹的聊天使用另一组共享标签页。
切换文件夹会保留未发送的草稿、未保存的文件编辑和正在运行的对话。回到文件夹即可继续使用原来的标签页与分屏。同一文件在多个文件夹中打开时共用编辑缓冲区，未保存的修改也会保持一致。没有打开标签页的文件夹会显示空白，不会因切换而自动创建对话。
关闭此选项即可重新查看各文件夹的标签页。设置保存在当前设备，本地与远程工作区分别记忆。
把对话视图拆分为分组
一条标签页条并不总是够用。右键点击任意对话标签页，你就可以把对话区域拆分成标签分组——与编辑器的分屏是同一个思路，而且数量没有固定上限：
- 向右拆分 / 向下拆分——把当前分组一分为二。新分组会打开一个空白草稿，因为同一段对话不能同时出现在两个分组里。
- 拆分并向右移动 / 拆分并向下移动——同样的拆分，只是这个标签页会移入新分组。
每个分组都是一套完整的工作区：自己的标签页条、下方自己的对话头部，以及自己的新建会话按钮（沿用该分组的文件夹）。同一时刻只有一段对话是活动的——即 composer 和快捷键作用的那个——因此拆分之后你也不会搞不清按键落在了哪里。
拆分之后，同一个右键菜单还负责管理布局：
- 移动到对面分组，或在分组较多时使用移动到分组 n（每一项都会标注它正显示的对话）。
- 更改分隔方向——把左右并排的一对翻转成上下堆叠，或反过来。
- 取消拆分会把当前分组并入相邻分组；全部取消拆分则把一切收回成一个。
你也可以直接把标签页拖过去——拖到另一个分组的标签条上，或它窗格中的任意位置——一个浮动小片会跟随光标，同时会有落点指示告诉你它将落在哪里。拖动两个分组之间的分隔条可以改变空间的分配。拆分可以自由组合：先向右拆，再把其中一半向下拆，你就得到了一个网格。
你的布局会按工作区记住，草稿也包含在内——重新打开 Codeg，拆分会回来，同样的对话仍在同样的分组里。开启标签页跟随文件夹时，每个文件夹会分别保留自己的分屏布局。
有两条小规则让这一切保持可预期。草稿会留在生成它的分组里（它在服务端还没有可移动的东西），因此它的移动菜单项和跨分组拖动会被撤下——在自己分组内重新排序仍然可用。而在分组之间移动标签页不会打断它：会话会保持连接、继续流式输出，只是换了个家。
将多个会话并排平铺
拆分是每个分组显示一段对话，平铺显示则正相反——它把一个分组所有的标签页同时显示出来。右键点击一个对话标签页并选择它，即可把该分组的对话并排铺开：不是固定的两栏分屏，而是每个打开的标签页对应一个窗格，并排排列，当它们放不下时可横向滚动。这就是你同时运行一支智能体舰队的方式：在一个里开启一项任务，在另一个里开启另一项任务，无需切换标签页就能看到每份对话记录并行流动。
- 窗格就是你的标签页。 打开另一个对话（⌘T 或侧边栏）可添加一个窗格；关闭一个标签页可移除一个。平铺至少需要该分组中有两个对话才能生效。
- 自由混合项目。 平铺的窗格不局限于单个文件夹——可以把来自不同项目的会话并排放在一起。
- 只有一个窗格是活动的。 活动窗格——即 composer 和快捷键作用的那个——会以流动的渐变边框勾勒出来。点击任意其他窗格即可聚焦它。
- 它是按分组生效的。 平铺与拆分可以组合：把一个分组平铺成一整面对话记录墙，同时让旁边的分组只显示一段对话。
- 随时退出。 右键 → 退出平铺会把该分组带回单标签页视图。
平铺是多智能体协作的绝佳搭档：将主导会话与它启动的子智能体会话并排平铺，观看整个团队协同工作。
桌面版与浏览器版
无论你运行桌面应用还是在浏览器中打开 codeg-server，工作区都是一样的。有几处不同：
- 文件。 桌面应用使用原生文件对话框，并且可以在 Finder / Explorer / 终端中打开；在浏览器中，你则改为上传文件或在服务器上选择文件。
- 窗口与附加功能。 自定义窗口控件和桌面宠物仅限桌面版；浏览器则增加了登录（你的访问令牌），以及连接断开时的重新连接提示。
- 远程工作区。 桌面应用可以连接到远程服务器，此时它的文件操作会表现得像浏览器一样——而从 0.32.2 起，它的内置浏览器打开的是远程主机自己的地址。
- 远程工作区能熬过断线。 从 0.35.0 起，连接到远程服务器的窗口会一直重连，需要多久就连多久，期间底部会显示一条连接已断开提示，而不再是试三次就放弃、把连接判为已失效。已失效如今只有一个含义——服务器拒绝了令牌——而在它连接失败期间你改过的地址、令牌或请求头，会在下一次尝试时用上。从 0.35.2 起，Windows 上连接到运行在 WSL 里的
codeg-server的窗口也能连上了：IPv6 一直没有应答时，它会改试 IPv4。 - 回到本地工作区。 从 0.35.0 起，远程工作区窗口提供打开本地工作区——在状态栏的快捷操作里、在 macOS 的 Window 菜单里，以及连接失败或已失效时显示的那个页面上。
- 你的窗口会回来。 从 0.33.0 起，桌面应用会重新打开你退出时开着的那些工作区窗口——本地的那个和每一个远程工作区，而你当时正在用的那个会回到最前面。从 0.35.0 起，即使服务器离线，远程工作区窗口也会重新打开，并在服务器恢复后就地接着工作；只有根本无法重建的窗口才会在本地窗口里报告。在 macOS 上点击 Dock 图标——或在 Windows 和 Linux 上再次启动 Codeg——带到前面的是你最后用过的那个工作区，最小化了的远程工作区也算在内，而不再总是本地窗口。
- 退出会停掉 Codeg 启动的东西。 从 0.33.0 起，无论你以哪种方式退出——⌘Q、程序坞、登出，或在 Windows 上注销——智能体、终端和 Web 服务都会被关闭，和一直以来从托盘的「退出 Codeg」退出时一样。从 0.36.0 起，Windows 上的应用内更新在交给安装程序之前也会这样做，并记住你当时开着的那些窗口，供它重新打开时恢复。
- 浏览器会留一份应用的副本。 从 0.35.2 起，网页版会缓存它自己的文件——通过 HTTPS 访问或在
localhost上时——于是被浏览器休眠的标签页重新打开时不必再下载一遍 Codeg，而在服务器宕机时重新加载，显示的是 Codeg 自己的连接界面，而不是浏览器的错误页。→ 把它安装为应用 - 触屏。 在手机或平板上，切换到另一个对话时，屏幕键盘不会再弹出来盖住它；想打字时点一下 composer 即可。使用鼠标或触控板时一切照旧。而在手机上，从 0.35.2 起，返回手势会一层一层地关掉你打开的东西——一个文件、一个抽屉、一个查看器——而不是直接离开 Codeg。
键盘快捷键
以上是默认设置；其中一些可以在设置 → 快捷键里更改。Tab 和 Alt ↑/↓ 是固定的。