工作台

项目与 Workspace

打开一个仓库，每件事单独一个目录，做完再清理。

树上的三样东西

Project 是你打开的一个目录。如果它是 git 仓库，Kumo 会把它归到主仓库根目录，所以打开一个已有仓库的 worktree 不会多出东西，只是把那个 worktree 勾上。普通文件夹也可以当 project，只是没有 worktree。

Workspace 是 agent 能在里面跑的目录。git project 的 Workspace 是主目录加上你添加的每个 worktree；普通文件夹就是它自己。主目录也是一个普通的 Workspace，要单独选中它；选中 project 不等于选中它。

Agent 是一场对话，绑在一个 Workspace 上。选中的是 project 行时不能开 agent，因为对话必须有一个目录可跑。

Workspace 还可以属于一条 Task，也就是它是为哪件事开的。属于的话，这一行会用小字带上任务的 #N，悬停能看到链接。

Kumo 从不扫描你的磁盘找仓库。冷启动是空的，这是有意的。

导入 project

点 PROJECTS 旁边的文件夹图标、空窗口中间的按钮，或者按 ⇧⌘O，选一个目录。如果它是 git 仓库，Kumo 还会列出 git worktree list 已经知道的那些 worktree，你可以勾选想放到树上的。

同一个路径打开两次，只会聚焦已有的那个 project，永远不会有第二份。

之后在终端里建的 worktree 不会自己出现。点 project 标题行上的分支图标（Join worktrees），在那里把它勾上。

托管 project

有时候还没有仓库。PROJECTS 旁边的 + 文件夹图标（New managed project）会问你一个名字，在 ~/KumoProjects/ 下建好文件夹，还可以顺手 git init 并提交一个空的首个 commit，这样 worktree 马上就能用。之后它就是一个普通 project。

唯一的区别在最后：关掉托管 project 时，Kumo 会提出把文件夹一起删掉，因为那是它建的。关掉其他 project 从不碰磁盘。

新建 Workspace

点 project 标题行上的 +，或右键 → New Workspace，或按 ⇧⌘N。只有一个对话框：

Branch。直接输入，或从列表里选。本地或 origin 上已有的分支会被 checkout 成新的 worktree；不存在的分支会从这个 project 的 base 分支新建，没在 project 设置里改过的话就是 origin/HEAD。
Label。这一行在侧栏里叫什么。和分支相互独立，之后改名也不碰 git。
First agent。默认勾上：选哪个 agent，名字留着或换一个。这时按钮写着 Create & Chat，建好直接落进新目录上的一场新对话，不用再按一次 +。

Branch 下面的列表最多分三组，顺序如下：

TASKS：这个 project 里没完成的 task，最近动过的在前。选一条，对话框的填法和 Task 页上 Start a Workspace… 一模一样，新 Workspace 也会挂到这条 task 下面。
ISSUES & PULL REQUESTS：project 的 origin 在 GitHub 上、且 gh 已登录时才有。选一个 issue，分支名替你定好（<编号>-<slug>）；选一个 PR，就是那个 PR 的 head 分支，从它所在的地方拉下来，包括 fork：Kumo 会把 fork 加成一个 remote，这样你 push 回去的还是它。fork 关掉了维护者编辑权限时，会有一条横幅提醒一次。
分支，本地的和远端的。

从 issue、PR 或 task 开始时，第一条 prompt 会预填好标题、正文和链接，外加一行告诉 agent 它在做哪条 task。你不按 Enter，它不会发出去。

目录落在 ~/worktrees/<仓库>/<分支>，分支名里的 / 换成 -。复用同一个分支会落回同一个目录，所以 agent 按目录存的会话历史可以接着用。根目录在 Settings → General 里改，也可以按仓库在 project 设置里改。

分支已经被别的 worktree 占着？Kumo 不会拒绝，而是把它拿回来：失效的记录直接清掉，真实存在的目录连同没提交的改动整个搬到新路径。唯一还会拒绝的情况，是主目录正 checkout 着这个分支，因为它搬不动。

侧栏

左栏上面是 PROJECTS，下面是 AGENTS，默认各占一半。拖动中间那条线可以改比例，双击恢复均分。

拖动行来排序。project 之间随便排；Workspace 只能在自己的 project 里移动。顺序会保存，重启后还在。
右键 project：New Workspace 和 Close Project。
右键 Workspace：Rename Workspace（只改 label；主目录那一行永远显示它当前的分支）和 Delete Workspace。
project 标题行上的齿轮打开它的设置，见下文。

AGENTS 列出所有 project 里的所有 agent，不只是当前 Workspace 的。每一行回答几件事：它是谁（名字）、在干什么（摘要）、在哪（project · workspace）、多久没说话了。状态既是一个点，也是一个词：


`running`	这一轮还在跑。蓝色，缓慢脉动
`idle`	可以接着发。绿色
`needs you`	在等一个权限、一个问题或一份计划。黄色
`error` / `lost`	这一轮失败了，或者目录没了。红色
`done`	你在看别处时跑完了。绿色，标为未读
`asleep`	现在没有进程，下一条消息会叫醒它。灰色

排序就是紧急程度：等你处理的在前，然后是未读，然后是其余的，每一组内最新的在前。在 running 和 idle 之间来回跳的行不会跟着上下乱跑。点一行就跳到那个 agent，不管它在哪；右键可以改名、重开或关闭。

删除 Workspace

右键 Workspace → Delete Workspace。它会先停掉这个目录上的所有 agent，再跑 git worktree remove。哪怕目录是干净的，也总要确认一次。

如果不干净（有未提交的改动、未跟踪的文件，或者没有别的 ref 指着的 commit），第一次会拒绝并告诉你是哪种情况，第二次确认才会强制删除。Kumo 不会悄悄丢掉你的工作。

主目录不能被删除。Close Project 会把 project 从树上拿掉并停掉它的 agent，仓库留在磁盘上。关掉普通文件夹 project 也从不删除文件夹。

如果目录在 Kumo 眼皮底下消失了（你在终端里删了它），这一行会标为 lost，上面的 agent 停止，把它从树上拿掉只改登记表。

Project 设置

project 标题行上的齿轮。两项设置，都跟着 project 存，而不是存在 app 里，所以重装也还在：

Base 分支：新分支从哪里分出来。留空就是 origin/HEAD。
Worktree 目录：这个仓库的 worktree 放在哪。留空就用全局默认。

两项都只影响之后新建的 Workspace。