​
App 项目列表

桌面 App 的首页只围绕本地 dev 项目工作。代码实现中，selectWorkflow 会拒绝没有本地副本的项目，并提示“当前 app 只打开本地项目，请先创建或导入本地项目”。服务器上的同 ID 项目只会作为“线上存在”的状态出现，不能直接在 App 中远程编辑。 issue #97 的阶段 0 起，App 增加了发布前置打包配置：仓库内开发仍通过 app/.env 默认连本地 http://localhost:7125 这套 712x 环境，但已打包发行 App 在没有用户自定义绑定时会内置 https://wfapi.yuhe.space 作为 release API 默认地址，用于 /health 探活、登录和后续远程发布/拉取能力。未登录账号但 /health 可达时，首页底部状态栏显示 server connected，账号入口显示未登录；没有任何 server URL 时才显示未绑定状态，不会把本地项目模式误报为 server disconnected。桌面端已经补齐 electron-builder / electron-updater 依赖、build:mac 脚本和发布 feed 基础配置。build:mac 会先构建 core 与 server/cli，再把 dist/core/cli.js、server/cli/dist/index.js 和 tsx / esbuild / @esbuild/darwin-* / AI SDK / zod 等运行时依赖一起打进 App；发行包运行本地 workflow、结构分析和 Publish 时不再依赖源码 checkout 里的 node_modules/tsx。macOS 打包会先从 app/build/workflow-code-icon.png 生成 icon.icns，避免发布 Electron 默认图标；release:finalize-app 还会在 stable 切换前挂载 DMG，检查图标、Apple Developer ID 签名、notarize/Gatekeeper 状态。阶段 D 起，已打包 macOS App 会在启动后自动检查 https://wfupdates.yuhe.space/app/stable/，并在设置页的系统偏好中展示当前 app.getVersion()、手动检查、下载进度和“重启并安装”确认流程。 首页采用极简黑白工作台风格：左侧是一条与 macOS traffic lights 融合的一体化竖向侧栏，搜索、项目入口、目录树和工具按钮都在同一区域内；侧栏支持拖拽或键盘调整宽度，也可以通过顶部按钮隐藏，隐藏后不保留左侧窄列或竖排标签，只在右侧项目标题栏左侧显示一个展开按钮，macOS 下该按钮会避开左上角三颗窗口按钮。设置入口固定在侧栏底部单独一行，不混在目录工具图标中。右侧顶部是轻量标题栏并与左侧 chrome 对齐，整条顶部可拖动窗口，右侧主体是当前目录下的项目网格。浅色主题使用 #F8FAFC、#FFFFFF、#F1F5F9 和 #E2E8F0 组成亮灰层级，蓝色只作为焦点与连接点缀，绿色、黄色和红色只表达成功、警告和错误。项目列表按本地项目最近编辑时间倒序展示。每张卡片会显示“编辑于 …”时间，方便优先打开刚修改过的 workflow。（issue #80、issue #89） 首页不再在主体内容区放置独立的大号账号状态卡。账号入口被收敛到左下角，与“设置”按钮保持同尺寸的紧凑卡片：
  • 未登录 / 授权失效：展示“登录账号”入口，点击直接打开全局登录弹窗。
  • 已连接：展示当前用户头像、显示名和邮箱，点击直接进入设置页里的个人信息。
首页上的 401 横幅 CTA 也统一为“登录账号”，点击后直接打开同一套全局登录弹窗。设置页只保留个人信息、外观和系统偏好，不再承担服务器连接配置入口。 目录管理是 App 首页的本机持久化 UI 偏好，保存到 renderer localStorage 的 workflow-code.app.project-directories:v1，重启 App 后仍会保留目录树、展开状态、当前选择和项目归类。App 只会在本地项目列表完成加载后清理不存在项目的归类，避免启动初始空列表把已有目录归类误清掉。它不会写入 workflow 源码、不会修改 .env、不会进入 Electron main 进程的 local-projects.json 注册表，也不会进入本地 SQLite。目录最多支持 3 层；删除目录只会解除项目归类，让项目回到“未归类”，不会删除本地项目文件或项目注册。项目可以通过卡片左下角拖拽手柄拖到目录，也可以用项目菜单里的“移动到目录 / 移出目录”完成同样操作，便于键盘操作和自动化测试。 App 左侧导航侧栏的宽度和隐藏状态属于 renderer 本地布局偏好，统一保存到 localStorage 的 workflow-code.app.sidebar-layouts:v1 中的 app-navigation 项；首页和设置页会复用这份状态，因此在首页调窄、隐藏或恢复侧栏后，进入设置页会保持一致的导航宽度与显隐表现。它只影响 App 导航布局，不影响目录树内容、项目归类、项目源码、项目注册表或 SQLite。 左侧目录树不展示项目数量统计，自定义目录的“新建子目录 / 重命名 / 删除”三个操作只在 hover 或键盘 focus 时出现在目录行右侧；操作区域本身保持透明，只有 hover 到具体图标按钮时才显示按钮背景。选中自定义目录后，右侧项目区会显示“添加未归类项目”按钮；点击后可以从当前未归类项目中搜索、多选并加入当前目录。这个批量加入操作与拖拽和项目菜单移动使用同一份目录归类状态，仍然只更新首页 localStorage 偏好。 项目卡片会在底部第一枚标签明确区分 Workflow 与 Conversation；没有显式配置时，App 会从 index.ts 的 executor.conversation.enabled 或项目 id/name 中做轻量推断。默认 workflow 项目图标会直接显示内置 Workflow 图标，旧版 sparkles 元数据也会兼容映射到同一枚图标；Electron window / Dock 图标和系统状态栏 / tray 图标仍然使用 Workflow Code 的品牌资源；自定义 iconUrl 仍然优先。卡片展示元数据保存在项目自己的 package.json 的 workflowCode.projectCard 下，并会随项目上传后在 server/web 项目列表中继续展示。旧版 workflowCode.appCard 仍会被兼容读取，但新保存只写 projectCard，例如： 
{
  "workflowCode": {
    "projectCard": {
      "kind": "conversation",
      "icon": "message-circle",
      "iconUrl": "https://example.com/icon.png",
      "iconBackgroundColor": "#0f766e"
    }
  }
}
kind 只支持 workflow / conversation，icon 使用 App 内置 token（workflow 会显示 Workflow 图标），iconUrl 只允许 http:// 或 https:// 图片地址，iconBackgroundColor 必须是 #RRGGBB。在项目菜单的“编辑应用信息”里可以修改显示名、类型标签、图标、图片 URL 和背景色；保存只写回本地 package.json，不会改变项目 ID、目录归类、SQLite 会话或运行历史。
当前 App 截图已在 issue #80 UI 重设计后临时下线，避免继续展示旧版界面；重新截取首页、工作区、设置页和主要弹窗后再恢复图片。

​
项目来源

  • New project 会在本地项目目录中创建一个新 workflow，并写入初始文件。
  • Import folder 通过 Electron 选择已有文件夹，注册为本地项目。
  • 开发模式会自动发现仓库 workspace/workflow 下的示例项目，并在项目卡片左下角显示“示例”标签；空目录或只包含 node_modules、dist、.git、.cache、本地 .env*、*.tmp 等忽略内容的占位目录会被跳过，不会当作缺失 package.json 的无效项目报错。
  • 当本地注册表里仍保留其它 checkout 的同 ID workspace/workflow 示例时，App 会优先使用当前 dev checkout 中自动发现的示例；首页展示、打开、文件监听、保存、运行和环境变量读写都会指向同一个当前 checkout 目录，避免把后续写入落到旧 checkout。（issue #80）
  • 已发布过的同 ID server 项目会在卡片上显示“线上存在”，用于发布、版本拉取和状态对照。
  • 无项目时会显示单独的空状态，不复用加载态。
  • 首页目录树包含“全部项目”“未归类”和用户自定义目录；搜索会跨全部本地项目与目录归属过滤，而不是只搜索当前选中的目录。

​
打开项目

点击本地项目卡片后，App 会：
  1. 切换到本地工作区。
  2. 读取本地项目文件并启动文件监听。
  3. 加载本地 dev 结构预览和本地环境变量。
  4. 如果 server 上有同 ID 项目，同时读取版本和远程运行历史。
如果当前项目有未保存改动，切换项目、切换文件、运行和 Pull Code 前都会弹出确认，并优先要求保存。 运行 workflow 或发送 conversation 消息时，App 会停留在项目详情的 Run 主视图，持续展示输入、输出或 conversation transcript；不会再自动切到 Diagram。Trace 内容通过对应运行或消息下方的按钮手动打开右侧诊断抽屉，并在 Diagram 节点详情层中展示，所有节点都有统一关闭入口，正在运行节点会用执行中占位等待详情回填，input、output、executionInfo 会纵向折叠展示，详情层可以拖拽调整高度。Provider 和 LLM 节点即使未运行也会展示结构分析可见的 provider/env/prompt 配置，secret 字段、provider 表达式源码、函数源码和 runtime binding call 参数源码中的 secret 语义内容都会先脱敏；无法确定归属到当前节点的 getLLMProvider 调用不会展示，避免把后续节点的 provider 详情错挂到当前节点。Logs 也在同一个右侧诊断抽屉中打开；conversation 模式下 Logs 按当前 active conversation 汇总多次 workflow run，每条日志保留 stdout、stderr、runner diagnostics 和单次 report.json，并提供 Diagram 按钮跳转到该 run 的执行流程。report.json 和 Diagram 长 JSON 详情都支持搜索定位和上一个/下一个跳转。（issue #80、issue #83、issue #89）

​
新建与导入

新建项目会调用 Electron 主进程创建本地文件。目录名称只决定本地文件夹名称，顶层 package.json.id 会保存项目 UUID：已登录时先向 server 申请 UUID，再创建本地项目；未登录时先生成本地 UUID，首次 Publish 时再绑定 server UUID。导入项目不会复制线上代码，只注册本地目录。项目卡片上的右键菜单可以克隆本地项目、修改显示名或移除本地注册；当前实现不再支持从 App 克隆到服务器，发布必须走 Publish。（issue #95）

​
状态说明

  • 示例：开发模式自动发现的仓库 workspace/workflow 项目。
  • 本地：项目存在本地注册。
  • 线上存在：server 返回了同 ID 项目。
  • Workflow / Conversation：来自 package.json 的 workflowCode.projectCard.kind，用于区分普通 workflow 与对话型 workflow；旧 workflowCode.appCard.kind 只作为读取兼容。
  • dev：本地文件相对已保存内容存在未保存变更。
  • 无效：server 项目摘要返回了 invalid 信息，通常需要查看构建或上传结果。
首页项目区保留当前连接状态与本地/线上项目统计，项目卡片 hover 或右键都能打开“移动到目录 / 移出目录 / 克隆项目 / 编辑应用信息 / 删除项目”菜单。所有按钮在加载期间会禁用重复触发并保留局部 loading 标识。

​
追踪

本文档首版由 issue #32 记录。App 本地优先行为来自 app/src/renderer/src/store/index.ts 中的 selectWorkflow、loadFiles、saveDraft、publish 和 pullServerVersionToLocal。