核心概念

Cordy Desktop 背后的 Project、Workspace 与 CodeTarget 模型。

Cordy Desktop 建立在一套精简而有意为之的对象模型之上。理解 Project（项目）、Workspace（工作区） 与 CodeTarget（代码目标） 这三个对象，几乎就能解释应用的全部行为：为什么视图会跟随你所在的工作区、多个智能体如何同时工作而互不冲突，以及重启后哪些东西会留存。

模型速览

对象是什么拥有什么
Project一个被导入的本地 Git 仓库仓库身份、Files 工具、Git 工具
Workspace项目内一个持久的、个人的工作上下文自己的 CodeTarget、终端标签页、笔记本、智能体运行、布局
CodeTarget工作区实际操作的那一份代码副本指向项目根目录，或指向某个 Git worktree 的指针

三者关系严格分层：一个 Project 包含多个 Workspace，而每个 Workspace 恰好绑定一个 CodeTarget。

Project（项目）

Project 是仓库级别的根对象。你通过导入一个已有的本地 Git 仓库来创建它（导入流程见 工作区）。一个 Project：

  • 表示一个被导入的本地代码库，
  • 定义 Git 仓库边界，
  • 拥有多个工作区，并且
  • 拥有项目级别的工具——Files 面板与 Git 面板。

Project 记录仓库在磁盘上的位置及其 Git 根目录。它本身并不决定你在哪个分支或 worktree 上工作——那是当前工作区的 CodeTarget 的职责。

Workspace（工作区）

Workspace 是项目之下的核心执行上下文——也就是你日常真正工作的地方。每个工作区：

  • 是一个由用户掌控的、个人的工作上下文，
  • 恰好绑定一个 CodeTarget（见下文），
  • 组织自己的终端标签页、笔记本与 CLI 智能体运行，
  • 记住自己的布局（打开的面板、分屏、当前的中央界面），并且
  • 跨会话长期保留，直到你主动关闭它。

工作区生命周期

工作区的状态为 active（活跃）、closed（已关闭） 或 archived（已归档）。关闭工作区不等于删除它——关闭会保留本地连续性，方便你日后回来继续。删除是一个独立的、需明确确认的操作。对于基于 worktree 的工作区，存在三个不同层级：

  • 关闭工作区——保留记录及其 worktree，仅停止展示。
  • 删除工作区——移除工作区记录，但把 Git worktree 留在磁盘上。
  • 删除工作区及其 worktree——两者一并移除。

工作区不等于 Git worktree。worktree 只是工作区绑定代码的一种方式，而不是工作区本身。

CodeTarget（代码目标）

CodeTarget 定义了一个工作区实际操作的是哪一份物理代码副本。它有两种形态：

  • project-root——工作区直接在仓库根目录中工作。
  • worktree——工作区在一个专属的 Git worktree 中工作：它自己检出的分支，位于自己的目录里。

CodeTarget 的存在是为了解耦两个容易被混为一谈的概念：

  • 工作区——你持久的、个人的工作上下文，以及
  • 代码路径——真正用作工作树的目录，供终端、Files 与 Git 视图，以及每个智能体的工作目录（cwd）使用。

因为 CodeTarget 携带了路径，所有"与代码相关"的东西都通过它解析：终端的 cwd、文件树、Git 状态，以及每个智能体的工作目录。

并行的、基于 worktree 的工作区

这正是该模型的价值所在。Git worktree 让一个仓库可以同时检出多份工作树，各自位于自己的分支上。Cordy 把这一能力直接映射到工作区上。你可以在以下位置创建工作区：

  • 项目根目录，用于快速的就地工作；
  • 已有的 worktree，用于恢复一个已在别处检出的分支；或
  • 新分支的 worktree，用于从零开始一个隔离的任务。

由于每个基于 worktree 的工作区都拥有自己的目录和分支，多个任务——以及多个 CLI 智能体——可以同时推进而互不干扰，也不会在你的主分支上冲突。一个智能体可以在某个 worktree 里重构，另一个在第二个 worktree 里跑测试，两者互不触碰彼此的文件。将智能体启动进这些工作区的方式，见 智能体。

归属与视图范围

两条规则解释了界面为何这样呈现：

  • Files 与 Git 是项目级工具。 它们归属于 Project，而不属于任何单个工作区。
  • 它们的当前视图跟随当前工作区的 CodeTarget。 当你切换工作区时，文件树和 Git 面板会重新指向那个工作区的代码路径——项目根目录，或某个具体的 worktree。

因此右侧的 Project Tools（项目工具） 在产品语义上是项目工具；但你在其中实际看到的内容，取决于当前工作区绑定的是项目根目录还是某个 worktree。这样既维持了正确的仓库心智，又展示了你真正所处的工作上下文。

什么会留存，什么是运行时的

Cordy 把状态分为三层。分清它们，就能明白重启后什么会保留：

层级举例持久性
持久真值项目、工作区、笔记本、布局、自定义智能体预设、自定义主题存储在你的用户数据目录下的磁盘上；重启后依然保留
运行时资源终端会话（PTY）、运行中的智能体、Git 与文件快照、实时指标由持久运行时拥有；会被重新挂接或重建，绝不写入快照
派生视图侧边栏树、状态徽章、当前 diff 视图由上述两层计算得出；永远不是真值来源

一个重要结论是：你的终端与运行中的智能体是由后台 Rust 运行时拥有的运行时资源，因此它们能在窗口重载、以及（在 Windows 上）收起到托盘后存活——而你的项目、工作区与笔记则是磁盘上的持久真值。持久性的工作原理见 运行时，而具体哪些数据存在哪里，见 隐私。

相关页面

  • 工作区——日常操作的外壳：Files、Git 与笔记本。
  • 智能体——将 CLI 智能体启动进工作区。
  • 运行时——终端与智能体为何是持久的。