管理 Desktop 项目

Desktop 的首页用于管理本地和云端 workflow 项目，并快速返回最近的运行任务。先选择项目模式，再创建、导入或安装项目。

首次打开且尚未创建、导入或安装任何项目时，首页会显示空状态。Desktop 不会自动把仓库中的 workspace 示例加载到项目列表。

认识首页

首页分为左侧最近任务区和右侧项目区：

左侧顶部显示 Workflow Code 品牌标识，中部按当前“本地 / 云端”模式展示对应最近任务，底部是账号和设置入口。
项目区顶部提供“本地 / 云端”模式切换和当前可见项目数量。本地模式提供“新建项目”和“导入本地”；Desktop 云端模式还提供“加入项目”和登录操作。
项目工具栏在搜索右侧提供“列表 / 图”切换，随后是项目类型筛选和排序；中文界面的类型筛选统一显示“工作流”“对话”“看板”，不会混入英文类型名。存在搜索、筛选或非默认排序时才会显示“重置”；这些条件只影响右侧项目集合，不会改变最近任务。

“新建项目”是本地模式的页面主操作；“导入本地”用于注册已有目录。首页不提供手动刷新项目列表按钮；创建、导入或云端状态变化完成后会更新对应项目集合，加载期间相关操作会显示进度并暂时禁止重复触发。

本地模式与云端模式

本地模式只显示当前设备中已经创建、导入或安装的项目。云端模式只显示当前登录账号可以访问的服务器项目；切换到云端模式不会下载项目源码。

同一个项目 UUID 可以同时存在本地副本和服务器项目。本地模式使用本地项目名称、卡片信息和本地操作，并可显示服务器关联状态；云端模式使用服务器上的项目名称和卡片信息。Desktop 的云端项目菜单只提供受权限控制的“下载到本地”和“复制为本地项目”，不会混入本地编辑、删除或发布操作。

Desktop 会保存最后选择的首页模式、列表或图视图以及搜索、筛选、排序和滚动位置。这些界面偏好不包含云端项目源码、知识库、KV 或运行记录正文。

点击云端项目卡片会直接打开云端工作区，不会创建本地副本或下载源码。文件、结构、版本、运行历史、知识库和 KV 都从 Workflow Server 读取；云端文件与项目信息在 Desktop 中只读。

云端工作区可以直接发起远程流式运行，并支持取消运行和提交或取消 workflow 的等待输入。云端会话与运行正文以服务器为权威来源，Desktop 不会把它们复制到本地 SQLite 或浏览器 localStorage。

下载或复制云端项目

云端项目的 latest 版本必须以 source 模式发布，并且当前账号具备源码下载权限，菜单中的本地化操作才可用。以 bundled 模式发布的版本没有原始 TypeScript/JavaScript，不能还原为可编辑本地项目；尚未发布版本或权限不足时，菜单会显示对应不可用原因。

“下载到本地”保留服务器项目 UUID，并在本地注册服务器地址和项目 ID 关联；如果本机已经存在同 UUID 项目，Desktop 会拒绝覆盖。“复制为本地项目”由 Desktop 生成新 UUID，清除服务器项目身份，得到独立的普通用户项目。两种操作都会先选择或确认本地目录，再下载源码、原子写入和注册；失败时不会留下半成品，也不会自动安装依赖。

切换服务器账号、API Key 或服务器地址时，Desktop 会立即关闭当前云端项目并清除仅属于上一身份的项目列表、运行状态和会话内存。尚未进入本地写入阶段的云端项目下载也会取消；本地项目、运行记录和本地会话不受影响。

通过邀请加入云端项目

在Desktop 的云端模式点击“加入项目”，粘贴项目管理员分享的邀请链接。Desktop 会先显示项目名称、邀请角色和有效期；邀请已经使用、撤销或过期时不会提供接受操作。

接受邀请需要登录 Workflow Server 账号。登录后确认接受，项目会加入当前账号的云端列表；随后可以直接打开云端工作区。邀请链接只在本次对话框中使用，不会写入本地项目、SQLite 或 localStorage。

搜索、筛选和排序

在项目工具栏中输入名称可以缩小当前模式的项目范围。类型筛选支持全部、Workflow 和 Conversation；项目默认按最近编辑排序，也可以切换为名称。只有存在搜索词、类型筛选或名称排序时才显示“重置”；点击后会清除搜索条件、恢复全部类型和最近编辑排序。升级时，旧版保存的默认名称排序会一次迁移为最近编辑；迁移后手动选择的名称排序仍会被记住。

切换到图视图后，Desktop 会按当前“本地 / 云端”范围读取每个项目的 workflowCode.projectInfo.relatedProjects，用线连接当前可见的关联项目。关联组件从左到右排列；双向关系使用 parent / child / grandchild 等 alias 时，会按父级、子级、孙级保持层级。空间不足时向下继续，没有关联的项目和普通文件夹排列在图的底部。点击卡片可直接打开项目或文件夹，右键卡片可打开与“更多”按钮相同的操作菜单；画布支持平移、缩放和适应画布。输入搜索词时，除了真正命中的项目，还会展示它们所在的完整关联链路，并用强调边框区分命中节点；另一范围、隐藏或当前账号不可访问的项目不会因此出现。

打开项目后返回首页时，Desktop 会保留此前的搜索条件、排序方式和列表位置。没有匹配项目时，页面会显示当前筛选条件并提供重置入口；这与尚未创建任何项目的首次使用状态分开显示。

识别项目卡片

项目卡片以项目名称为主要信息，并按当前界面语言解析后的结果原样展示；不会把 @workflow-code/gitlab-webhook 这类名称拆成组织名和短名。内置项目会明确标识，且仍可独立关联服务器状态。

首页默认不显示项目 UUID。仅保存在当前设备的项目不会重复显示“本地副本”说明或“本地”标签。Desktop 会检查本地项目的运行源码；调用 workflow.getServerLLMCredentials() 的项目会显示“需登录”，表示运行时需要当前 Workflow Server 用户账号。卡片还会在有区分意义时显示服务器关联、本地修改或异常状态，并为异常提供相应的恢复入口。每张卡片的更多菜单始终可见，可用于访问项目级操作。

Server Web 管理端

Server Web 是独立于Desktop 的服务器管理界面。它只连接 Server，用于查看服务器项目、版本、运行记录、环境变量、计划任务、Webhook 和公开 Embed，不承载 Desktop renderer，也不读取本地项目目录。

需要把本地项目发布到 Server 时，在Desktop 中绑定服务器项目并上传，或使用 CLI 的 workspace upload / workspace publish。Desktop 与 CLI 按项目根目录 .workflowignore 选择文本和二进制文件；.gitignore 不参与上传判断。

创建新项目

点击新建项目

在首页点击 新建项目，依次选择 Workflow 或 Conversation 类型、示例项目并填写项目名称。Workflow 当前提供只输出 Hello 的最小示例；Conversation 当前提供不调用 LLM、按轮次输出 第 i 轮输出 的示例。Desktop Main 会为每个新项目生成 UUID 并立即写入 package.json.id，同时显式写入 workflowCode.projectInfo.dataStorage.mode: "both"，并生成一组高对比度的图标颜色和背景颜色；同一次创建的本地项目与云端应用使用相同 UUID、配色和完整 projectInfo。类型和示例列表均可继续扩展。

按需选择项目存放位置

项目存放位置可以不选，此时 Desktop 会使用统一维护的默认项目目录。需要自定义位置时，通过系统目录选择器选择一个父目录，该目录不需要为空。Desktop 会在父目录下创建以项目名称命名的子目录；如果同名目录已经存在，会停止创建并提示修改项目名称或存放位置，不会覆盖现有内容或自动追加时间后缀。

按登录状态创建云端应用

无论是否登录，完成本地文件创建时 package.json.id 都已经是有效 UUID，因此项目可以立即本地运行并访问声明允许的本地数据。未登录时不会创建云端应用；已登录时，Desktop 会在本地文件创建成功后使用同一个 UUID 原子创建 private 云端应用，一次提交名称、类型、卡片信息和完整 projectInfo，但不上传源码。云端失败不会删除本地文件，可稍后从项目菜单或 Info 页重试。

打开项目

项目创建和云端绑定完成后，Desktop 会直接打开新项目工作区并读取文件树、结构信息和本地环境变量。云端应用创建失败时，可以在提示中重试，或直接打开已经创建完成的本地项目。

克隆本地项目

从本地项目卡片的更多菜单选择 克隆项目。克隆流程保留来源项目的源码、项目类型和卡片信息，只需填写副本的项目名称，并按需选择项目存放位置；不需要再次选择项目类型或示例项目。

项目名称同时用于副本的 package.json.name 和文件夹名称。未选择存放位置时，Desktop 使用默认项目目录；选择自定义位置时，Desktop 在所选父目录下创建同名子目录。目标目录已存在时会停止克隆，不会覆盖内容或自动追加后缀。

副本在本地复制时会立即获得与来源不同的新 UUID，并写入 package.json.id，无论是否登录都不会清空。已登录时，Desktop 在本地复制完成后使用这个新 UUID 自动创建只包含项目元数据的 private 云端应用，不上传源码。云端创建失败不会删除本地副本，可以重试或直接打开本地项目；流程完成后 Desktop 会直接进入副本工作区。

从旧版本导入或克隆的项目如果缺少 workflowCode.projectInfo.dataStorage.mode，Desktop 的 New Tab 目录只开放“信息”“浏览器”“文件”和“打开项目”。在“信息”页签选择“仅本地”“仅服务器”或“本地和服务器”并保存后，Desktop 会同时把项目的 Core 与 CLI 精确依赖更新到 0.2.0，再按声明开放其它工具；不会自动迁移既有 KV、知识库或 PersistentValue 数据。

导入已有目录

点击导入本地

选择已有 Workflow、Conversation、Kanban 或其它本地文件夹。也可以把一个或多个项目、文件夹同时拖到首页；Desktop 会依次注册全部可用顶层目录。每次导入（包括再次导入同一路径）都会把项目或普通文件夹的最近编辑时间刷新为当前时间，因此会在默认排序下移到最前。导入不会复制目录，也不会从服务器下载源码。

确认导入分类

Workflow/Conversation 使用根 package.json 和 index.ts，Kanban 使用 workflowCode.projectType: "kanban" 和配置后的 HTML 入口；Kanban 未配置 workflowCode.kanban 时默认读取根 index.html。新项目应使用 UUID 格式的 package.json.id，空 ID 旧项目会获得稳定注册 ID 以便迁移。旧版字段、损坏结构或其它项目校验错误不会阻断首次打开：Desktop 会把该目录降级注册为普通文件夹，保留文件、终端和小助手入口供直接修复。普通文件、不可访问路径和文件系统根目录不会注册；取消目录选择不会显示错误。

检查项目卡片

项目卡片会展示名称、类型和最近更新时间；存在服务器关联、本地修改或异常时，会补充相应状态。

进入工作区

点击卡片打开项目。导入过程不会自动安装依赖；运行前需要在项目目录中手动完成依赖安装。之后可以继续编辑文件、运行 workflow，或在登录后发布到 Workflow Server。

远程关联

本地项目与服务器项目通过 package.json.id 中的 UUID 关联。Desktop 新建或克隆的项目从落盘起就使用该 UUID；只有手工导入的旧项目可能暂时为空。执行“创建云端应用”时，Desktop 使用现有 package UUID；旧空 ID 项目则使用其稳定注册 UUID，并在绑定时写回 package.json.id，Server 不会另行分配。绑定中断时 Desktop 会保留 pending UUID；在同一服务器上重试只恢复同 UUID 绑定，不会创建第二个应用，也不会因无关本地项目的迁移错误而失败。

创建云端应用只同步名称、类型、卡片和完整项目声明。真正点击发布时，Desktop 才会把本地源码上传到 Workflow Server 并生成新版本；导入项目不会自动下载或覆盖服务器代码。

首页“云端”模式只展示至少已经发布过一个版本的服务器项目。创建云端应用只代表完成注册；首次发布之前，该项目仍可在“本地”模式继续编辑和发布，但不会进入云端项目集合、搜索结果、关联图或数量统计。发布成功后，它会自动出现在云端模式。

使用首页工具 Dock

首页 Topbar 最右侧提供“底部面板”和“右侧面板”两个图标开关，两个面板默认隐藏。本地与云端首页模式共用这一套页签和尺寸状态，但它与任何项目工作区的 Dock 状态相互独立。左侧最近任务栏始终保持原宽度；进入项目或设置页后，首页中的小助手、终端和浏览器实例会继续保留，返回首页即可接着使用。

首页 New Tab 只提供“小助手、终端、浏览器、打开项目”，不提供“文件”、运行、信息、知识库、KV、日志或流程图。首页终端和小助手固定使用当前操作系统用户的主目录，不提供路径选择器；小助手不能访问该主目录之外的目录。选择“打开项目”后，可以在页签内选择本地项目、云端项目或有效普通文件夹；本地与云端项目行最右侧分别显示“本地”和“云端”，只有明确选中目标后才展示该项目或文件夹允许的功能。

查看最近任务

首页左侧的最近任务跟随“本地 / 云端”模式切换：

本地模式读取当前设备 SQLite 中的本地运行历史，并合并尚未持久化的运行中任务。同一项目的同一定时计划在分页前合并为一条计划记录，普通手动运行仍逐条展示。
云端模式读取当前服务器上由Desktop 发起的运行日志，不显示本地 SQLite 记录，也不会展示 CLI、Webhook、Embed 或其他客户端发起的 run。

切换模式时，列表会重置分页、加载和错误状态，不会短暂保留上一模式的任务。云端模式需要登录；未登录、没有对应记录或读取失败时，最近任务区会显示独立提示和恢复入口。

最近任务标题固定在列表顶部，任务采用紧凑的单行列表，不使用独立卡片。普通任务和定时计划都按各自最新运行时间倒序排列，不按运行结果调整优先级；分页数量按合并后的展示记录计算，底层运行历史不会被删除。列表标题吸附时会紧贴最近任务标题下沿，账号入口固定在侧栏底部。

定时计划记录在计划名称前显示“定时”标识，并显示所属项目、最近运行时间、本地保留记录中的运行次数和失败次数。点击后直接打开该计划最新一次 run；每次触发的完整结果仍可在项目 Dock 的“定时”页签查看。

每条任务都会保留状态标识：

running 显示为运行中。刚开始且尚未写入本地历史的任务也会立即显示。
waiting_for_input 显示为请求用户批准。
failed、timed_out、success、aborted 和其它已结束状态显示对应的运行结果。

普通 Workflow 任务显示 workflow 名称和实际入口标题/ID；旧记录缺少入口快照时显示“默认/旧版入口”。本地 Conversation 任务显示会话标题和所属 workflow。点击本地任务会打开本地项目并选中该 run；点击云端任务会打开服务器项目和对应服务器 run，不会回落到同 UUID 的本地日志。带 conversation ID 的任务会同时携带会话定位。

显示与窗口状态

首页同时支持浅色和深色主题。项目状态除颜色外还会使用图标或文字表达，键盘操作时搜索、筛选、项目卡片、任务和菜单都会显示清晰的焦点指示。

窗口变窄时，项目卡片会由多列调整为双列或单列，项目工具栏可以换行但不会产生横向滚动。最近任务区可以折叠，并通过侧栏恢复入口重新打开。

关闭最后一个窗口不会退出 Desktop：主进程继续驻留系统托盘，以便执行本地 Workflow 定时任务。从托盘可以恢复主窗口；只有选择“退出 Workflow Code”才会停止调度、取消仍由 Desktop 持有的运行并释放本地资源。未配置本地计划时也保持相同关闭语义。

项目列表与最近任务会分别显示加载、空状态和错误状态。某一区域加载或失败不会阻止另一区域继续使用；失败时 Desktop 会尽量保留上一次成功加载的内容，并在对应操作附近提供恢复反馈。

内置项目

发行版首次打开时不会自动导入示例项目。内置项目在“设置 > 内置项目”中单独管理：Conversation 等轻量项目可直接安装，Codex 和 OpenCode 等包含较大运行时的项目会按当前系统和 CPU 架构下载对应资源包。

“小助手”与它依赖的 Desktop Control 都是隐藏内置项目，不会出现在首页项目集合、搜索结果或项目计数中。小助手仅支持用户主目录、普通用户的本地可编辑项目和有效普通文件夹；云端项目、内置项目和只读本地项目都不提供该入口。首次打开时，Desktop 会先确保 OpenCode 与 Desktop Control 已安装，再安装并注册小助手；准备期间会显示下载或安装进度，失败后可以从页签内重试。小助手默认打开在右侧 Dock，也可排序或移动到下方；隐藏 Dock 或切换页面会保留页签和会话，显式关闭页签才释放该视图实例。用户主目录中的小助手任务会在首页最近记录中标记为“用户主目录”，点击后返回首页并恢复对应页签和会话。

安装过程会显示下载和安装状态。Desktop 会校验资源大小与 SHA-256，再以原子方式切换到新版本；下载、校验或解压失败时，已有可用版本会继续保留。安装或更新内置项目不需要本机安装 Node、pnpm 或其它包管理器。

内置项目安装或移除完成后，首页项目列表会自动更新。

Codex、Conversation、OpenCode 和小助手都使用当前登录账户的系统 AI 配置，不读取本机 agent 登录态，也不要求在项目环境中保存上游 Key。Codex 只支持 OpenAI Responses，并把可选模型限制为内置兼容列表，默认使用 gpt-5.6-terra 和 high 推理强度；OpenCode 支持 OpenAI Responses 与 Anthropic，分别优先使用 gpt-5.6-terra 与 claude-sonnet-5，OpenAI 模型同样应用兼容列表。Conversation 按协议使用这两个首选模型，但仍保留 Provider 当前开放的其它模型；模型选项展示 Server 能力目录中的视觉、联网、推理和工具调用信息，并仅在当前模型声明联网能力时启用搜索。四个项目都会在每次 turn 前重新校验所选配置和模型。composer 将模型与 Effort 合并到一个快捷摘要入口，打开后可继续配置 Provider、权限、沙箱等全部快捷参数，并可一次恢复默认值。直接打开 OpenCode 时仍可在 conversation 快捷选项中选择只读、工作区自动批准或 OpenCode --auto；小助手固定使用工作区自动批准，并拒绝访问当前用户主目录、目标本地可编辑项目或普通文件夹所授权范围之外的目录。

在 Desktop 仓库根目录通过 pnpm dev 启动时，Desktop 会自动加载同级的 build-in-conversation、build-in-codex、build-in-opencode、build-in-desktop-control 和 build-in-developer-assistant 仓库，直接从源码目录运行并监听文件变化，不需要安装或复制版本目录；也可以用 WORKFLOW_BUILTIN_PROJECTS_SOURCE_ROOT 指向包含这些仓库的其它父目录。保存源码后，后续读取和运行会使用最新内容，也不会访问下载服务。pnpm dev 与复用现有 Electron 二进制的 pnpm dev:shared-electron 分别使用 workflow-code-dev 和 workflow-code-dev-shared-electron 开发数据目录，二者互不读写，也不会使用已安装发行版的数据；需要临时指定其它目录时可设置 WORKFLOW_CODE_ELECTRON_USER_DATA_DIR。打包后的 Desktop 才启用内置项目安装维护逻辑，默认从 https://wfupdates.yuhe.space/builtin-projects 检查并下载资源。每个内置项目独立发布并维护 index.json；每个发布必须原子声明 minDesktopVersion 以及精确的 Core/CLI components。Desktop 只选择最低 Desktop 版本已满足且两个组件分别处于宿主相同 major.minor 兼容线的最高项目版本，并在下载后要求项目 package 的精确依赖与索引逐字一致；同线 patch 与日期 Alpha 顺序不影响选择。Desktop 每次检查都会重新验证可变索引，带版本且经过哈希校验的资源包可以长期缓存。下载没有固定的应用层总时限，平台资源使用可移植依赖布局并流式写入临时目录，再按索引校验响应大小与 SHA-256；校验、解压或注册失败时保留原有可用版本，索引暂时不可访问时已安装版本会显示为离线可用。私有部署可以通过 WORKFLOW_BUILTIN_PROJECTS_URL 指定完整的资源根地址；该地址需要为每个内置项目提供 index.json 及其引用的平台资源包。manifest.json 仅为旧版 Desktop 保留兼容，不用于新版本选择。

内置项目可以运行和创建副本，但不能直接编辑、重命名、发布或删除其内置源码。创建副本会生成新的项目 UUID，副本成为普通用户本地项目，可按自己的依赖和发布流程维护。

Codex、Conversation、OpenCode 和小助手已迁移到 Core/CLI 0.2.0，并显式声明 dataStorage.mode: "both"。它们要求 Desktop 0.1.22 或更高版本：在 Desktop/CLI 中明确使用本地数据，在 Server Web 中明确使用同 UUID 项目的服务器数据，两端不会自动回退、复制或同步。

修改项目卡片

项目菜单中的“编辑应用信息”会更新本地 package.json 的 workflowCode.projectCard：

{
  "workflowCode": {
    "projectCard": {
      "icon": "message-circle",
      "iconColor": "#f8fafc",
      "iconBackgroundColor": "#0f766e"
    }
  }
}

项目类型不属于卡片元数据。Desktop 从源码中 workflow.defineExecutor({ projectType }) 派生并只读展示 workflow 或 conversation。
icon 使用 Desktop 内置图标 token。
iconUrl 由 Desktop 在上传自定义图片后写入服务器生成的 WebP 地址。旧项目中已有的 http:// 或 https:// 地址仍可显示，但 Desktop 不提供手动填写入口。
iconColor 使用 #RRGGBB，控制内置图标颜色；旧项目未配置时使用白色。
iconBackgroundColor 使用 #RRGGBB。

在项目信息中点击“编辑图标”可以集中调整自定义图片、内置图标、图标颜色和背景颜色。自定义图片支持 PNG、JPEG 和 WebP，选择后可以按 1:1 比例预览、裁剪和缩放；Desktop 会生成 512x512 WebP，并在保存项目信息时上传到当前项目绑定的 Workflow Server。项目尚未创建云端应用，或当前连接不是绑定服务器时，仍可使用内置图标，但不能上传自定义图片。上传或同步失败时，裁剪草稿会保留，可直接重试。

预置配色会同时应用图标色与背景色；“随机配色”只会生成亮暗方向相反且对比度至少为 4.5:1 的颜色组合。

保存应用信息不会改变项目类型、项目 ID 或运行历史。旧项目若仍包含 workflowCode.projectCard.kind，需要删除该字段并在 executor 上补齐 projectType 后才能重新导入或运行。

登录状态

首页左下角显示当前账号状态：

状态	你可以做什么
未登录	创建、导入和编辑项目；声明为 `local` 或 `both` 的项目可离线使用本地数据并本地运行。
登录失效	重新登录后继续发布、拉取和读取服务器历史。
已登录	访问声明允许的服务器数据，并在同 UUID 绑定完成后发布、拉取、远程运行和读取服务器历史。

本地编辑不要求登录。只有 local 或 both 声明允许使用本地存储；server 声明要求登录和同 UUID 云端绑定，both 只在实际访问服务器数据、发布、拉取、远程运行或读取服务器历史时要求有效账号。

下一步

进入 Desktop 工作区，编辑、运行和发布 workflow。
进入 Desktop 设置，管理账号、主题和自动更新。

认识首页​

本地模式与云端模式​

下载或复制云端项目​

通过邀请加入云端项目​

搜索、筛选和排序​

识别项目卡片​

Server Web 管理端​

创建新项目​