核心概念

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

Cordy Desktop 建立在一套精简的对象模型之上。理解 Project(项目)、Workspace(工作区) 与 CodeTarget(代码目标) 这三个对象,就能解释应用的大部分行为:为什么视图会跟随你所在的工作区、智能体之间共享哪些文件,以及重启后哪些东西会留存。

模型速览

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

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

Project(项目)

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

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

Project 记录仓库在磁盘上的位置及其 Git 根目录。你所在的分支就是该检出目录当前检出的分支。

Workspace(工作区)

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

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

工作区生命周期

工作区的状态为 active(活跃)、closed(已关闭) 或 archived(已归档)。关闭工作区不等于删除它——关闭会保留记录,方便你日后回来继续。删除是一个独立的、需确认的操作,会从 Cordy 中移除该工作区的笔记与聊天历史。两者都不会改动仓库中的文件。

CodeTarget(代码目标)

CodeTarget 定义了一个工作区操作的是哪个目录。它只有一种形态:

  • project-root——工作区直接在项目自身的检出目录中工作。

所有"与代码相关"的东西都通过它解析:终端的 cwd、文件树、Git 状态,以及每个智能体的工作目录。

因此同一项目的所有工作区都操作同一组文件。同一项目两个工作区中的两个智能体编辑的是同一个检出目录;在一个工作区切换分支,会改变所有工作区看到的文件。

独立检出

Cordy 不再创建或管理 Git worktree(自 0.5.4 起)。如需独立检出:

  1. 自行运行 git worktree add <目录> <分支>。
  2. 用添加仓库把该目录作为单独项目添加到 Cordy。

早期版本的 worktree 工作区会在首次启动 0.5.4 或更高版本时被转换:它们改为使用项目自身的检出目录,磁盘上的 worktree 文件夹保持不动,旧的数据文件作为备份保留在新文件旁边。如需继续在该 worktree 中工作,请把它的目录添加为项目。

归属与视图范围

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

  • Files 与 Git 是项目级工具。 它们归属于 Project,而不属于任何单个工作区。
  • 它们的视图跟随当前工作区。 当你切换到另一个项目的工作区时,文件树和 Git 面板会重新指向那个项目的检出目录。

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

Cordy 把状态分为若干层。分清它们,就能明白重启后什么会保留:

层级举例持久性
持久真值项目、工作区、笔记、布局、自定义智能体预设、自定义主题存储在你的用户数据目录下的磁盘上;重启后依然保留
运行时资源实时 PTY、运行中的智能体、Git / 文件观察结果、指标运行时存活期间可重新挂接;完整退出会结束进程
终端历史快照不含备用屏幕模式的序列化终端屏幕 / 回滚历史保存在本地渲染器存储中,冷启动时恢复到新 Shell 上方
派生视图侧边栏树、状态徽章、当前 diff 视图由上述各层计算得出;永远不是真值来源

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

相关页面

  • 工作区——日常操作的外壳:侧栏、标题栏与窗格。
  • 笔记——工作区笔记。
  • 智能体——将 CLI 智能体启动进工作区。
  • 运行时——终端与智能体为何是持久的。