跳到主要内容

在 Desktop 中编辑、预览、运行和发布

打开本地项目后，Desktop 工作区围绕当前目录工作，可以编辑、保存、预览、运行和发布。普通文件夹可使用文件、终端、浏览器、小助手和打开项目工具页签，但不会获得项目专属能力。打开云端项目后，工作区改用 Server adapter：文件与项目信息只读，结构、版本、运行数据或 Kanban 配置都来自 Workflow Server。

从首页打开本地工作区​

首页“本地”范围把 Workflow、Conversation、Kanban 和普通文件夹统一显示为工作区卡片，并一起按名称或路径搜索、按类型筛选及按名称或最近编辑时间排序。搜索右侧可切换列表或关联图；图视图按当前范围的项目关联连线，将关联组件从左到右排列，并把无关联工作区放在底部。搜索命中项目时会同时保留其完整关联链路。“普通文件夹”是 Desktop 本地工作区类型，不会加入 Workflow 项目类型，也不会出现在“云端”筛选中。文件夹卡片显示名称、真实路径和“普通文件夹”，不伪造项目版本、UUID 或 package 信息。

“打开文件夹”会让 Electron Main 选择、识别并注册目录；Renderer 只接收类型化 ID，不提交任意路径。首页也可以一次拖入多个项目或文件夹，Main 会按拖入顺序处理全部可用顶层目录，单个不可用项不会阻断其它目录。有效 Workflow Code 声明继续按原项目逻辑导入；没有 Workflow 声明的目录会注册为普通文件夹，即使其中存在普通 npm package.json。目录已声明 Workflow Code、但因旧版字段或结构问题无法通过当前校验时，同样会降级为普通文件夹，使文件、终端和小助手保持可用以便直接修复源码。目录按规范化真实路径去重，因此符号链接和 Windows 大小写差异会复用同一卡片；普通文件不会触发导入，文件系统根目录不能作为工作区打开。

普通文件夹只提供“文件”“终端”“浏览器”“小助手”和“打开项目”。文件树继续排除 .git、node_modules、缓存和敏感 .env 文件，并对二进制或超大文件应用既有预览限制。移除卡片只撤销 Desktop 注册和小助手授权，不删除磁盘内容；隐藏记录会保留稳定 ID，同一路径重新打开后可恢复原卡片及项目中的关联引用。Desktop 不会在普通文件夹内生成配置、修改目录结构或把它同步到 Server。

用户创建或导入的项目属于用户本地项目，可以编辑、发布和移除。从首页项目菜单打开“编辑项目信息”，或在项目详情 Dock 打开“信息”页签后，可以修改根 package.json.name 默认名称和手工“支持多语言/支持多平台”声明。确认“支持多语言”后才显示并启用简体中文与英文名称，确认“支持多平台”后才显示并启用“平台无关”或 macOS/Windows/Web 指定展示平台；取消声明只隐藏配置，不会清空已保存值或当前草稿。声明和展示平台只用于项目卡片与详情展示，不会自动改变版本发行目标或验证实际功能。首页仅在已声明支持多语言时按当前界面语言显示本地化名称并搜索本地化别名，否则使用和搜索默认名称；展示平台同样只在已声明支持多平台时显示。

“信息”页签在宽窗口中分为两列：左侧保留项目信息编辑器，右侧预览项目根目录的 Markdown README，窄窗口则按此顺序纵向排列。默认和中文界面读取 README.md；项目确认“支持多语言”后，英文界面优先读取 README.en.md，文件不存在时回退 README.md。仅新增 README.en.md 不会自动声明支持多语言。切换界面语言会立即切换预览，不会修改项目文件；README 中的相对 PNG、JPEG、WebP 和 GIF 图片从当前项目目录安全读取。

Desktop 管理的五个内置项目都已显式声明支持多语言，并同时提供中文 README.md 与英文 README.en.md。中文界面显示“对话助手”“智能体-Codex”“智能体-OpenCode”“桌面控制”“小助手”，英文界面分别显示 “Conversation”“Codex”“OpenCode”“Desktop Control”“Project Assistant”。Desktop Control 与小助手均为隐藏依赖，不出现在首页项目集合；这些名称和声明仍来自各项目自己的 package.json，不会由 Desktop 根据内置项目 ID 特判。

项目信息编辑器也管理首页卡片图标。Workflow/Conversation 类型从 executor 源码派生，Kanban 类型从 package.json.workflowCode.projectType 派生，三者都只读展示；中文界面分别显示“工作流”“对话”“看板”。图标编辑器可以选择本地图片并进行 1:1 预览、裁剪和缩放；保存时生成 512x512 WebP。未绑定项目直接写回本地 package.json；已绑定项目必须连接并登录原 Server，Desktop 会先通过项目图片与 PUT /api/workflows/{id}/project-info 同步云端，再写回本地。内置项目由 Desktop 管理：可以运行、只读刷新和创建副本，但不能编辑源码、项目信息、环境、远程源码或发布设置。

项目 TopBar 会保留底部/右侧 Dock 开关以及适用的环境、拉取、发布和项目操作；全局设置位于项目操作菜单。文件保存与刷新只出现在各“文件”页签自己的工具栏中。窗口变窄后，次要项目操作会按优先级收敛为带提示的图标按钮。

项目操作菜单中的“刷新项目状态”会重新读取已登记目录并执行完整项目识别。修复后的普通文件夹可原位恢复为 Workflow、Conversation 或 Kanban；如果清单仍含不支持字段、入口仍无效，或原项目后来失效，Desktop 会保留原项目注册表记录、把当前目录安全打开为普通文件夹，并在 Output 中显示本次识别的原始校验错误。刷新返回失败，不会把普通文件夹降级误报为项目刷新成功，也不会删除或改写项目源码。

使用 Kanban 项目​

新建项目时选择“Kanban”，可以从无参数或参数化示例开始。两个示例都会创建包含 .workflowignore、页面、状态模块、KV 存储模块、README 和纯逻辑测试的完整看板工程，并在页面内提供任务的新建、编辑、拖拽和删除。无参数项目不生成 kanban.json，打开后 HTML 画布占满预览区；参数化项目额外包含只配置标题和强调色的 kanban.json，预览区显示命名配置与参数表单。同一个 HTML 入口会随活动配置实时变化，但不会创建 workflow run。

使用 Vue、React、Vite 等工程时，在 package.json.workflowCode.kanban 中配置 artifactDir 与相对该目录的 entry。Desktop 宿主不安装依赖、不自动运行构建脚本，也不接入 dev server、端口或热刷新；开发者完成构建后，产物目录的变化会刷新预览，源码变化本身不会刷新。旧项目未配置时继续读取根目录 index.html。

本地用户 Kanban 项目可从任一 Dock 的 New Tab 目录打开小助手，默认落在右侧。它可以协助修改当前 Kanban 项目的 HTML、CSS、JavaScript 和其它项目文件；通过“信息”页签配置关联项目后，也可联动其它已授权的本地源码项目。对于配置了 artifactDir / entry 的框架项目，修改源码后会在依赖已安装时运行项目已有的一次性 build 并检查入口产物。小助手不会启动 dev/watch server、端口或 HMR，不会擅自安装依赖或编造构建脚本；构建失败时会明确说明预览仍是旧产物。它也不会为 Kanban 增加 Send、Run、项目 conversation、Logs 或 run history；云端 Kanban 和内置项目的 New Tab 目录不显示小助手。

第一次打开参数化 Kanban 时，Desktop 会创建“默认配置”。左侧参数设置区顶部用于切换或新建配置；重命名、复制和删除位于当前配置的操作菜单中，最后一个配置不能删除。参数使用纵向标签和全宽控件，短单选项会以紧凑分段形式展示。参数修改会自动保存，标题栏持续显示保存状态；保存失败时保留当前输入和重试入口。配置与活动配置保存在当前设备的 Desktop 数据中，不写回项目源码，也不会出现在其它本地项目中。file 参数只向页面提供受管理的文件引用，不暴露本地绝对路径。

Kanban 页面运行在隔离的离线 iframe 中，只能加载配置产物目录内的相对路径资源以及 data: / blob: 内容，不能访问源码目录、公网、Node、preload 或父页面 DOM。页面通过 window.workflowCodeKanban.getConfiguration() 读取当前配置并监听 workflow-code:kanban-configuration-change；通过 window.workflowCodeKanban.kv 和 .knowledge 访问当前项目固定作用域的数据。双方确认通用项目关系后，还可通过 window.workflowCodeKanban.relatedProjects.get(alias).kv.getValue/setValue/subscribe 按目标项目授予当前项目的权限访问关联 KV；页面只能提交 alias 和 key，不能覆盖目标 UUID、scope 或存储位置。完整接口、持久化示例和安全边界参见 Kanban 项目。

本地依赖​

Desktop 不会为本地项目安装、更新或删除依赖，也不会执行 pnpm install、npm install 等包管理器命令。导入项目前，请在项目目录中使用项目自己的包管理器完成依赖安装；Desktop 不要求项目必须使用 pnpm，也不要求必须存在 pnpm-lock.yaml。

Desktop 新建模板落盘时会由 Main 生成 UUID 并写入 package.json.id，把固定版本的 workflow-code 和 @workflow-code/cli 写入 devDependencies，并预置 dev、inspect、run:json、workspace:upload 和 workspace:publish 脚本。创建项目后仍需由用户在项目目录执行一次包管理器安装；Desktop 不自动执行安装。

开始本地运行、解析动态参数或恢复等待中的运行前，Desktop 会只读检查 package.json 中的运行时依赖和必需 peer dependency 是否能从项目的 node_modules 解析。开发依赖、optional dependency 和标记为 optional 的 peer dependency 不会阻止运行。

缺少依赖时，Desktop 会停止当前操作并显示项目目录和缺少的包名。请在该目录手动安装依赖后重试；项目仍可继续打开和编辑。建议提交所用包管理器的 lockfile 以保证团队和服务器构建可复现，但 lockfile 不代表依赖已经安装。

完成一次本地运行​

打开“文件”编辑源码

从右侧或底部 Dock 的 New Tab 目录选择“文件”，打开 workflow 源码文件。修改内容后，Desktop 会防抖重新分析当前内存文件并自动更新固定“运行”主区中的输入参数、conversation 模式和工具配置；点击页签工具栏中的“保存”后再写入本地目录并刷新环境变量数据。

填写运行参数

回到固定“运行”主区。Workflow 按声明顺序显示 Swagger 式入口列表；默认入口初始展开，每个入口有自己的参数，展开后才显示运行按钮。Conversation 仍显示单一会话列表和输入区。

点击 Run / Send

展开目标入口，在内容区点击 Run。Desktop 会先检查未保存改动，然后在本地 Electron 环境中直接运行该入口，不会先运行默认入口。Conversation 继续使用 Send。

查看输出和诊断

输出会直接显示在“运行”主视图中。需要查看节点链路时打开 Trace，需要排查 stdout、stderr 或 report 时打开 Logs。

主区与工具页签​

项目详情不再显示左侧视图导航。Workflow 和 Conversation 的主体区域固定显示“运行”，Kanban 固定显示“预览”；项目 TopBar 右上角的两个面板按钮分别打开底部 Dock 和右侧 Dock。新项目第一次进入时两个 Dock 均关闭，主体区域直接可用。

两个 Dock 使用同一套 New Tab 目录：

工具页签用途
运行 / 预览为同一目标打开额外的独立运行或 Kanban 预览会话。
定时为 Workflow 的指定入口配置后台定时运行；Conversation 和 Kanban 不提供。
信息编辑项目展示信息并预览根 README；可用宽度不足时按编辑区、README 顺序切换为上下布局；内置项目和云端项目只读。
知识库 / KV 数据管理当前项目和所选本地/服务器来源的数据。
文件编辑本地源码，或只读查看云端项目文件。保存与刷新位于该页签自己的工具栏。
MCP仅本地 Workflow 提供；显示 entrypoint/tool 目录，并生成可复制的精简 stdio 客户端配置。
终端在本地项目或普通文件夹中创建独立终端；云端项目不提供。
浏览器在受限浏览器中打开 http/https 页面，并使用地址栏、前进、后退、刷新和页面状态。
小助手维护普通用户本地项目或有效普通文件夹；云端项目和内置项目不提供。
日志 / 流程图查看绑定项目和 run 的诊断内容；Kanban 或没有运行记录的目标不提供。
打开项目在当前页签中选择另一个本地项目、云端项目或普通文件夹，不递归创建第二套 Dock。

普通文件夹只显示“终端 / 浏览器 / 文件 / 小助手 / 打开项目”。项目的其它可用项按 Workflow、Conversation、Kanban、本地或云端来源和运行记录自动过滤；旧项目尚未声明数据存储模式时，只能打开信息、浏览器、文件和另一个项目。知识库与 KV 数据仍跟随当前页签的明确项目来源，不会因为全局选中了另一个项目而切换 adapter。

MCP 页签从 Electron Main 的窄 IPC 读取连接配置，Renderer 不能提交 runtime 路径或任意项目目录。复制的配置只包含 Workflow Code 启动器和 Desktop 项目 ID；AI 客户端建立连接时会自动启动独立的无窗口进程，不需要预先手动执行命令，Desktop 主窗口也不需要保持打开。启动器会从 Desktop 注册表重新读取项目目录和已确认的关联项目，并在内部解析真实 runtime、本地数据目录与已保存认证，这些细节不会进入复制内容。

通过这份配置发起的每次 MCP tool call 都会保存到当前 Desktop 工作区的本地运行历史。原始 MCP input、CLI args、交互恢复值、完整 report、stdout 和 stderr 会随同一 runId 的状态更新一起保留，可从首页最近记录或项目历史打开 Output、Diagram 和 Logs。Desktop 主窗口已打开时会在外部调用写入后自动刷新；主窗口关闭不影响无窗口启动器持久化记录。

发行版配置形态如下；开发版会额外包含开发应用入口和一个短 profile 参数，但同样不会暴露 CLI、tsx loader、项目目录、数据目录或关联项目路径。

{
  "mcpServers": {
    "workflow-<PROJECT_UUID>": {
      "command": "<WORKFLOW_CODE_EXECUTABLE>",
      "args": ["--workflow-mcp", "<DESKTOP_PROJECT_ID>"]
    }
  }
}

项目必须继续保留在当前 Desktop 工作区，且本地目录可访问。修改源码、entrypoint、静态 params 或关联项目后，重新连接客户端以刷新固定的 tool 目录和启动上下文。

打开一个空 Dock 会先创建可关闭的 New Tab；选择工具后在原位打开，新建页签入口始终紧跟最后一个页签，同一种工具可以同时打开多个实例。标题栏最右侧用于隐藏当前 Dock；New Tab 不显示页签操作菜单，实际工具页签仍可通过菜单“移到右侧/底部”。拖动页签可以在同一 Dock 排序或移动到另一个 Dock，键盘可用 ArrowLeft / ArrowRight / Home / End 在当前 tablist 中移动焦点。终端和浏览器默认打开在底部，其它工具及从运行结果打开的日志、流程图、文件和小助手默认打开在右侧。

小助手可通过 workflow-desktop 的 open_dock_tool 打开本次运行所属工作区的工具页签。自动化入口默认使用右侧，也可明确指定底部；它不会沿用终端/浏览器的手动目录默认位置。宿主由 Main 固定为本次运行绑定的用户主目录、本地可编辑项目或普通文件夹，调用参数不能覆盖这个宿主。Renderer 在导航前继续使用上表的工具目录校验，因此首页只允许小助手、终端、浏览器和打开项目，不会出现文件；普通文件夹也不会获得信息、知识库或 KV。

当请求已经包含具体上下文时，小助手会在同一次调用中传入对应参数，让页签直接进入目标内容，而不是停在空地址栏、运行选择器或项目选择器：

参数生效范围与结果
url仅浏览器；接受 http/https，页签创建后立即导航。
filePath文件，或“打开项目”的文件视图；必须是所选工作区内的规范相对路径。
runId运行、日志、流程图，或“打开项目”的运行视图；直接选中对应 run。
conversationId运行、小助手，或“打开项目”的运行视图；直接恢复对应 conversation。
dataSource知识库/KV，或“打开项目”的知识库/KV 视图；明确选择 local / server。
openedProjectKind + openedProjectId仅“打开项目”；使用 list_projects 返回的本地项目/普通文件夹 ID，跳过选择器。
openedProjectTool直接进入侧边项目的运行、预览、计划、信息、OpenAI、知识库、KV 或文件；普通文件夹只允许文件。

“打开项目”的目标嵌入当前 Dock，不会改变小助手 run 的宿主；需要切换整个主工作区时使用 open_project。侧边目标不接受云端项目、任意绝对路径或未注册目录。Main 会校验参数组合、URL、相对路径、注册状态和服务器数据源，Renderer 会根据当前项目目录再次校验；失效上下文会明确报错，不会静默回退为空页签。

隐藏 Dock 只隐藏内容，不会关闭页签、终止终端或重新加载浏览器；返回当前页面后原实例仍在。只有页签上的关闭操作才释放实例，最后一个页签关闭后该 Dock 自动隐藏。未保存文件或知识库草稿会在关闭前显示 Desktop 确认。每个项目或普通文件夹分别保存两个 Dock 的尺寸、隐藏状态、页签顺序、活动项以及可恢复的 URL、文件、run 和 conversation 选择；返回项目或重启 Desktop 后继续恢复。浏览器恢复最后 URL 与登录会话，但不恢复前进/后退历史；终端会在同一目标创建新进程，不恢复重启前的进程。

拖动分隔条可以调整 Dock 尺寸，聚焦后可用方向键微调以及 Home / End 跳到最小或最大值。底部 Dock 最多占可用高度的 50%，右侧 Dock 最多占可用宽度的 75%；两者同时打开时，主体区域仍至少保留 320px 宽和 240px 高。全局“设置”位于 TopBar 的项目操作菜单中，离开设置后会返回当前项目。

Kanban 没有 executor。Desktop 打开、保存、刷新、发布或监听产物变化时，不会为 Kanban 启动 executor 结构分析、读取运行历史或加载本地执行环境变量；HTML 入口、静态资源和可选参数清单由独立的 Kanban 预览链路校验。开发者仍可按需运行 workflow-code structure <project-dir>，在命令行检查 projectType、artifactDir、entry 和 kanban.json，该命令只做静态校验，不会创建运行记录。

从运行结果或消息操作打开日志/流程图时，页签直接绑定当时的目标和 run；从 New Tab 目录打开时先选择运行记录。Logs 中 stdout、stderr、runner diagnostics 和 report.json 默认展开，仍可手动折叠；长文本和 JSON 保持在独立滚动区内，不会撑破 Dock。

保存本地修改​

“文件”工具页签展示本地项目文件，保存与刷新操作位于页签自己的工具栏。修改后，文件会显示“未保存”状态。点击“保存”后，Desktop 会执行：

保存 -> 写入本地文件 -> 重新读取结构 -> 更新环境变量视图

结构预览不需要等待保存：Desktop 内编辑内容或外部编辑器写入项目目录后，会在文件变化稳定后自动重新分析。连续修改会合并为一次刷新，旧分析结果不会覆盖较新的文件状态；刷新期间保留当前可用的运行预览，完成后原位更新。

保存只写入本地目录，不会上传服务器 draft，也不会发布版本。需要把修改同步到服务器时，请使用“发布”。Kanban 的产物目录在保存成功或外部构建写入后才刷新预览；独立产物目录之外的源码修改不会刷新。Monaco 中尚未保存的内容不会进入 iframe，package.json 的入口配置变化也会重新初始化预览。

文件树会区分目录展开状态、当前文件和未保存文件。本地普通文件是否显示不受扩展名白名单或 .workflowignore 影响，因此 .vue、.svelte 等有效 UTF-8 文本文件也可以直接查看和编辑；.workflowignore 仍只控制上传清单。二进制文件和超过 1 MB 的文件会保留在文件树中，选中后显示不可预览原因，不会作为文本打开或保存。为避免扫描依赖、版本控制数据和敏感环境配置，.git、node_modules、缓存目录及 .env 文件不进入文件树。

使用 ArrowUp / ArrowDown 移动到相邻项目，ArrowRight 展开目录或进入第一个子项，ArrowLeft 折叠目录或返回父目录，Home / End 跳到当前可见列表的首尾。文件仍在加载时会显示独立加载状态；搜索无结果不会被误显示为项目没有文件。

运行 workflow​

Workflow 运行区按 executor 的 entrypoints 声明顺序显示扁平折叠列表。紧凑标题栏左侧显示入口标题、ID 和默认标记，可选说明在最右侧单行显示，空间不足时省略；标题栏不提供 Run，默认入口初始展开，入口展开后才可从内容区运行。每个入口分别维护 Form/Raw 模式、参数、附件和工具策略草稿，作用域为项目 ID、精确解析目标和入口 ID；折叠或切换入口不会清空其它入口草稿，在其它入口填写参数、选择日期或完成参数联动也不会重新展开已折叠入口。结果只显示在实际运行入口下方。

窄窗口中，完整运行历史会收为主区顶部的单行选择入口，并保留独立的新建图标。展开后可以搜索和滚动当前已加载的运行记录，同时查看当前选择与运行中状态；关闭选择面板后仍停留在原输入或结果区域。composer 只显示真正可执行的 Send，不会再重复显示被动的 Input + 发送图标；存在结构化参数时仍可使用 Form/Raw、Advanced 和 Quick options。

workflow 可以用 panel: "quick" 把常用单选或多选放在 Advanced 右侧。多个快捷项保持单行排列，空间不足时可横向滚动；选择值会写入实际运行参数。conversation 中的快捷选择会按本地 workflow 与会话分别保存，返回项目首页后重新进入同一会话时会恢复。若 workflow 定义了 resolveParams，Desktop 会在初始化以及 main、Advanced、Quick 的任意 Form 参数变化后执行本地联动求值；动态隐藏会同时更新 Advanced 计数和 Quick 入口。主输入内容变化仅在参数声明 resolveOnInput: true 时触发。求值期间禁用 Send；失败时保留输入并显示错误，可直接点击“重试”重新执行当前求值，无需关闭项目。隐藏不会自动删除参数值，互斥场景需要 resolver 同时返回 visible: false 与 value: null。

type: "string" 参数可以使用 control: "date" | "time" | "datetime" | "date-range"。Desktop 直接复用 shared 日期控件：单日期、24 小时时间、本地日期时间和闭区间日期范围分别写成 YYYY-MM-DD、HH:mm:ss、YYYY-MM-DDTHH:mm:ss 和 YYYY-MM-DD/YYYY-MM-DD，不会做时区转换。日期控件可放在主表单或 Advanced，也会用于等待中的用户输入节点；Quick 仍只处理枚举。点击日历标题可使用年份、月份双列滚轮快速跳转，“完成”后切换，“取消”保持原月份。宽屏日期范围提供两个可独立切换年月的日历，重新打开时分别显示已选的开始月份和结束月份；起止同月时右侧显示下一个月。切换一侧不会移动另一侧，窄屏回退为单日历。Workflow 运行表单在入口展开时不显示必填或格式错误，首次点击 Run 后才显示并阻止无效提交；非空无效默认值或 resolver 返回值会原样保留，修正后 Run 恢复可用。

codex 示例与 conversation 一样从当前登录账户的系统 AI 配置读取 Provider 和 Model。Codex Quick 参数依次为 Provider、Model、Reasoning effort、Sandbox。它只显示 OpenAI Responses 配置，模型限定为 gpt-5.6-sol、gpt-5.6-terra、gpt-5.6-luna、gpt-5.5、gpt-5.4，没有有效选择时优先使用 gpt-5.6-terra，推理强度默认 high。配置或模型失效时会按相同规则回退，并在每次运行前重新校验，CLI 参数也不能绕过模型限制。它不使用本机 codex login 状态，未登录或没有兼容配置时会在参数区显示明确错误。运行时只向 Codex 子进程提供临时 loopback 地址和占位 Key，并为该子进程固定使用指向 loopback 的专用 model provider；用户全局 Codex 配置中的 provider 或 base URL 不会覆盖 Workflow Server 转发地址。真实上游 Key 不会进入项目进程。

该示例默认关闭 Advanced 中的 JSON structured output，assistant 正文会直接流式展示；需要结构化 title、branch、result 和 path 时，可显式打开 JSON。该示例支持在默认 composer 中粘贴、拖拽或上传图片，并把图片作为 Codex SDK local_image 输入。运行完成后，Logs 摘要会显示可用于恢复 SDK 会话的 Thread ID；Token badge 聚焦或悬浮后会展示 Input、Output、Reasoning、Cache read、Cache write 和 Calls 明细。SDK 内部重连耗尽后，示例会对上游断流、连接重置、超时、限流和临时 5xx 错误再自动重试一次，并在 Output 中显示重试状态；认证、参数、权限和用户取消不会触发重试。

opencode 内置项目会为每个 turn 启动仅绑定本机随机端口的 OpenCode server，并在 conversation state 中保存 Session ID 以继续后续消息。临时 server 会在成功、失败、取消或暂停后关闭，Desktop 等待它完整退出再结束当前 turn，避免最终回答已经显示但任务仍停留在执行中。Provider 和 Model 直接读取当前登录账户的系统 AI 配置，不使用项目 LLM_* / OPENCODE_PROVIDER_* 环境变量、用户全局 OpenCode 配置或 opencode auth login 状态。OpenAI Responses 与 Anthropic 配置均可使用；OpenAI 只显示 gpt-5.6-sol、gpt-5.6-terra、gpt-5.6-luna、gpt-5.5、gpt-5.4 并优先选择 gpt-5.6-terra，Anthropic 保留上游模型并优先选择 claude-sonnet-5。OpenAI Effort 默认提供 low / medium / high / xhigh，gpt-5.6-* 额外提供 max / ultra；切换到旧模型时，扩展档自动回退为 xhigh。默认选择 high，Anthropic 会禁用 Effort。

默认 composer 支持图片附件；OpenCode 为所选系统 AI 模型统一生成 text / image 输入和 text 输出的 modalities 配置，不在 Desktop 内预判具体模型是否具备视觉能力，不支持图片的模型会直接返回自身错误。Advanced 保留工作目录，快捷区提供 Provider、Model、Variant 和 Permission。OpenCode 的 Agent 固定为 build，不再提供 plan/build 选择。resolver 会原子更新 Provider 对应的兼容模型列表，保留仍有效的选择，并在配置或模型失效后优先回退到协议默认模型；失败时保留输入并提供重试。每个 turn 运行前还会重新请求系统 AI 目录并再次应用相同限制，避免使用已停用的配置或不受支持的模型。OpenCode 子进程只接收随机 loopback 地址和占位 Key，真实上游 Key 与 Workflow Server 短期代理凭据不会进入项目进程、OpenCode 配置或输出。

conversation 的模型选项会展示视觉、联网、推理和工具调用能力，联网搜索控制位于 Advanced 面板。只有当前模型的 modelDetails[].capabilities.webSearch 为 true 时该开关才可用并默认开启；未知或未声明能力的模型自动关闭并禁用。切换 Provider、Model 和发送消息前都会重新校验能力，不能通过旧参数绕过服务器设置。

OpenCode 没有与 Codex danger-full-access 同名的沙箱档位，它使用 allow / ask / deny 权限配置，默认选择 workspace：read-only 禁止写入和命令，workspace 自动批准工作区编辑与命令但禁止外部目录和循环升级，auto 对应 OpenCode --auto 并批准所有未显式拒绝的权限。普通原生 ask 不在 headless workflow 中启用；知识库和 KV MCP 的人工批准继续使用 workflow waiting-input 协议。

build Agent 提出问题时，OpenCode question 会转换为当前 run 的用户输入节点：单选显示 radio，多选显示 checkboxes，允许自定义答案的问题附带文本框。问题面板出现后，对应的 question 工具会立即显示为已完成；等待回答只由用户输入面板承担，不会让已结束的 assistant 消息继续转圈。授权问题正文会独占一行，选项在下一行按可用宽度排列；窄面板自动改单列，长中文和绝对路径会完整换行。关闭 Knowledge 或 KV 工具的自动批准后，工具调用会立即暂停当前 OpenCode turn，并在同一位置展示批准或拒绝操作，不依赖后续模型事件。run 会进入持久化 waiting_for_input，Desktop 与 server 共用界面提交后继续同一个 run。批准后，workflow 会通过同一审批 gate 确定性执行暂停前记录的工具与参数，把原工具状态更新为完成，再将真实结果作为 follow-up 发送到同一个 OpenCode Session；不会重复发送原始用户请求，也不会依赖模型自行猜测是否需要重试。由于 OpenCode 原生 pending question 不跨临时 server 进程保存，问题暂停时同样会结束当前 OpenCode turn；恢复时把选项作为 follow-up 发送到同一个 Session。

assistant 正文直接流式显示；reasoning、工具调用、任务列表、文件变更、Agent/子任务、附件、上下文整理、重试恢复和错误统一显示为带语义图标的紧凑活动行。assistant 文字与工具、相邻工具及其它活动行之间不再叠加额外的大块纵向间距，连续调用保持紧凑但仍保留完整触达高度。每类活动从首帧起就具有最终图标、自然语言摘要和结构化布局，后续只在原位更新内容与状态，不会先显示无图标占位或 raw JSON 再突然切换。读取、搜索、目录、命令、编辑、提问、Knowledge 和存储等工具继续使用各自图标；长摘要只在空间不足时省略，悬停可查看全文。展开后只展示 Input、Result、Error、Files、Tasks、Agent、Prompt、Reasoning 等有值的用户信息，不混入 callId、协议状态或整层 metadata。任务列表、重试和问题在恢复、失败、暂停或 turn 结束时会收敛到完成状态，不会遗留永久 spinner；空的 session.diff 和仅用于协议记账的 step/snapshot 不产生可见噪音。流式正文和工具结果会保持完整 Unicode 字符，不会因分段传输显示替换字符。Token badge 使用 OpenCode 返回的 Input、Output、Reasoning 和缓存统计。

OpenCode 遇到嵌套的上游断流、SDK 明确标记为可重试的 API 错误或输出长度中断时，会在同一个 Session 中最多自动续接 10 次。Output 使用同一条恢复详情显示当前 n/10 次数，并在恢复成功或耗尽后收敛为完成或失败。续接消息不会重发原始用户请求，而是要求先核对 Session、工具结果和工作区实际状态，避免重复已经完成的编辑或写操作。认证失败、用户取消、参数或权限错误、内容过滤、上下文溢出和工具业务错误不会自动重试。

使用小助手维护本地工作区​

Desktop 首页、普通用户本地项目（包括 Kanban）和有效普通文件夹可以从任一 Dock 的 New Tab 目录打开“小助手”，上下文入口与最近任务恢复默认落在右侧。它是普通工具页签，不会替换固定的运行/预览主区或其它页签；可以排序、拖到下方或从页签菜单移动。隐藏 Dock、切换项目页面或移动页签时，小助手会话和后台输出继续保留；显式关闭页签才释放该视图实例。Dock 的通用分隔条控制可用宽度或高度，小助手不再拥有独立固定宽度面板或单独宽度偏好。

小助手沿用页面当前的浅色或深色主题，不会改变页面颜色。同一工作区的小助手成功准备一次后，当前 Desktop 会话内再次显示已有页签不会重复显示“正在准备小助手”；内置助手重新安装或更新后仍会重新检查。窄 Dock 默认收起话题 rail，顶部当前话题入口会展开可搜索、可滚动并可继续加载更早记录的话题面板，适合管理大量对话；消息和新对话说明在上方区域滚动，输入框始终保留在底部。OpenCode、当前工作区根目录与已授权关联根目录的联动修改范围和稳定偏好/决策记忆能力的说明只在空白新对话中显示，发送并产生消息后不再占用对话区域。远程项目和内置项目的 New Tab 目录不显示小助手，也不能通过最近任务绕过这个限制。中文界面始终使用内置项目声明的“小助手”名称，不会回退显示 “Project Assistant”。

普通用户本地项目的“信息”视图会在“关联资源”字段中直接列出关联项目和小助手文件夹，并用警示样式保留失效引用的 ID；保存或拖入关联后列表会立即刷新。“管理关联资源”打开同名对话框。关联项目是所有项目类型共用的关系，写入 package.json.workflowCode.projectInfo.relatedProjects。目标项目也可编辑时，Desktop 事务式写入双方 package；目标不可编辑或不可用时只保留当前项目声明并显示“待确认”。新建双方关系默认显式授权 read: all、write: none，面板可分别设置双方允许对方读取或写入自己的 KV。待确认关系不授予 KV 权限，但仍可进入小助手代码工作区。

本地目录可以直接拖入对话框，Desktop 会复用首页“打开文件夹”的识别逻辑：Workflow Code 项目会导入并加入通用关联项目，普通文件夹会注册为只供小助手使用的本地关联文件夹，普通文件不会触发导入。文件夹 ID 只保存在 Desktop 本地项目记录中，不写入 package 或服务器；普通文件夹始终是叶子节点。搜索可同时筛选已导入项目和已注册文件夹，顶部显示直接关联数、递归可访问数（不含当前主工作区）和失效项。已失效引用可以保留或移除；使用相同 UUID 重新导入项目或重新打开同一路径后会恢复可用状态。

Desktop 只向 Electron Main 传递 { kind: "home" }、{ kind: "project", projectId } 或 { kind: "folder", folderId } 类型化目标，不接受 Renderer 提供目录。首页作为主目标时，Main 将规范化后的操作系统用户主目录作为唯一根目录，不从其中推断已导入项目、普通文件夹或关联资源。项目作为主目标时，Main 在每次新运行、等待输入恢复和最近任务恢复时沿各项目声明的通用关系逐级广度遍历，不扫描父目录或磁盘子目录，也不设置固定深度；双方确认和待确认关系都会进入代码工作区，到达每个项目时再加入其小助手关联文件夹。项目和文件夹 ID 用于处理循环和去重，规范化后的真实目录避免重复授权。只有已导入、来源为用户、允许编辑源码且目录仍有效的项目，以及已注册且目录有效的文件夹会进入工作区；缺失项目、失效目录、内置或不可编辑项目、失效文件夹及错误项目声明会终止对应分支并显示告警，其它有效分支继续运行。普通文件夹作为主目标时只授权自身，不扫描或推断其它目录。

如果普通文件夹中存在 Workflow Code 声明，小助手会结合当前 primaryTarget.kind: "folder" 把它视为可能的项目导入失败，而不是擅自把该目录升级为项目。它会先在当前根内修复旧 package 字段、源码、文档和可验证产物，并把源码迁移与 Desktop 项目识别分别报告；源码检查完成后会要求使用“项目操作 -> 刷新项目状态”，并根据 Output 中的原始校验错误继续处理。需要关联项目时，小助手不会扫描相邻目录或自行扩大权限，而是指导用户让 Desktop 重新识别当前目录，随后在“信息 -> 管理关联资源”中选择项目并配置双方授权；下一次从项目工作区发起的 run 才会获得新的关联根目录。关联项目进入代码工作区与 KV 权限确认是两件事：待确认关系可授权已导入源码目录，但 KV 仍要求双方 UUID 互指且目标项目的 grantToRelatedProject 允许当前项目访问。

当前目标根目录仍作为 OpenCode workdir。Desktop 为当前 run 写入临时 V2 工作区清单，以 roots[] 区分首页、项目和文件夹目标；小助手只接受 V2，不再转换旧 V1 清单。在 read-only 与 workspace 策略下，清单中的其它根目录、其后代以及运行时注入的 Skill 目录会进入精确 external_directory 白名单，使 Skill 引用文件可读，其它未列出路径继续拒绝；auto 不应用该目录白名单。Skill 路径只是调用方提供的指令来源，不会被系统提示词视为可写工作区根目录。清单会在正常结束、取消或失败后清理，conversation 参数不能提供或覆盖路径。Main 还会为每次小助手运行创建随机、短期、仅绑定 127.0.0.1 的宿主能力；参数化 Kanban 在同一能力中增加只绑定主项目的命名配置操作，run 结束后统一关闭。

小助手动态复用当前已安装的 OpenCode 入口，并使用同一套 Workflow Server 系统 AI Provider、Model 和 Variant 解析逻辑。首次使用会联动安装 OpenCode 与 Desktop Control；后续运行自动使用当前版本。小助手固定使用 build Agent，快捷参数中的 Permission 可选择 read-only、workspace 或 auto，默认 auto（Auto approve），批准所有未被明确拒绝的 OpenCode 权限。read-only 禁止编辑与命令；workspace 在没有关联项目时拒绝全部 external_directory，存在关联项目时也只允许 Desktop 清单中的目录子树，并始终拒绝循环升级权限。编辑、命令、Knowledge、KV、问题、全局记忆以及固定的 workflow-desktop MCP 属于全局能力；Kanban 宿主配置只在小助手打开本地 Kanban 时进入工具列表和当前 run。Workflow 或 Conversation 项目不会展示、加载或获得 Kanban capability。

workflow-desktop 由隐藏的 Desktop Control Workflow 通过标准 stdio MCP 固定注入。小助手可以读取 Desktop、更新、开机启动、内置项目、本地项目和普通文件夹状态，切换主题或语言，修改开机启动，导航或打开新建项目对话框，打开当前目标的右侧/底部 Dock 工具，创建最小 Workflow、导入已存在项目，读取或修改可编辑项目信息，单项或批量操作项目 KV 与知识库，以及检查、下载、安装更新或维护内置项目。KV 批量读写和知识库批量查询/修改最多接受 100 项；请求会先完整校验所有项，再按输入顺序执行并返回 succeeded、failed 和逐项 results。批量写不是事务，运行时失败不会回滚已经成功的项，也不会阻止后续合法项。OpenCode 只连接父 Workflow 提供的受控 MCP 代理：未注册或被禁用的工具不会暴露，更新管理、开机启动修改、项目创建或导入、项目信息修改、项目 KV 写入、项目知识库修改和内置项目管理默认等待用户批准，批准恢复后只执行原调用一次。调用只能使用 Desktop 返回的 ID 和已注册绝对路径；Main 会重新校验字段、项目能力、文件路径、JSON KV 值、KV scope、知识库边界与操作前置条件。安装更新还必须由当前请求明确授权重启。原始 stdio 环境和一次运行有效的宿主令牌不会进入 OpenCode 或 shell；MCP worker 不会获得 SQLite 路径、Electron 对象或账户密钥，复制出的普通 Workflow MCP 配置也不包含这次运行的临时宿主能力。工具不开放项目删除、任意数据库访问或任意 Electron 操作。

host_project_configuration 提供 Kanban 命名配置的创建、读取、更新和删除。小助手会先读取参数定义和各配置当前值；创建可指定名称和初始参数，更新可按配置 ID、名称或当前活动配置同时重命名并提交部分参数，删除必须明确指定 ID 或名称且不能移除最后一个配置。写操作继续通过 Main 的清单校验和 SQLite 数据路径，成功后右侧参数面板与预览实时更新，不需要修改源码或重新构建。工具不能指定其它项目、直接访问数据库、修改文件参数或把宿主配置写回 kanban.json。如果关闭该工具的自动批准，批准后会通过恢复 run 时创建的新桥确定性执行一次，再续接同一个 OpenCode Session。

每次会话都会注入完整可写根目录清单、非阻塞告警和项目级 workflow-code-generator skill。小助手进入每个根目录前必须读取本地约束；项目修复还必须完整读取 generator 指定的修复引用。必需 Skill 或引用缺失、被拒绝或只读取到部分内容时，本次修复会停止并报告未验证阶段，不能继续编辑、转向无关优化或用旧版 CLI 的成功结果宣称完成。仅当根目录确实是 Git 仓库时检查 Git 状态，仅当存在对应项目测试时执行测试。跨工作区修改后分别报告改动、验证与适用的 Git 状态。该 skill 是小助手指定的默认 skill，可在规划和实现 Workflow Code 时直接调用；普通文档文件夹不会因此被当成 Workflow 项目。OpenCode 发现的其它 skill 默认不调用，只有用户当前需求直接需要对应能力或说明时才选择最小相关集合。这个限制由小助手系统提示词约束，不是对 OpenCode skill discovery 的物理隔离。项目级 skill 随小助手提供，不安装到用户全局 skill 目录。新建项目默认使用简体中文，且不会自动生成翻译资源、语言切换或 locale 检测；只有用户明确要求国际化或多语言支持并说明目标语言时，小助手才会加入对应适配。

小助手会话按类型化目标隔离：首页使用固定的 Home context key，项目继续沿用已有项目 context key，普通文件夹使用 folder:<id>，因此在一个工作区打开的活动会话和快捷参数不会出现在另一个工作区。旧项目会话和最近任务仍可恢复。小助手自己的 KV、Knowledge、OpenCode Session 和全局记忆使用稳定内置命名空间，更新内置项目版本后仍可继续读取。global_memory 支持列出、读取、搜索、记录和忘记稳定的用户偏好或工作区决策；记忆只保存在当前设备的小助手 Knowledge 中，不同步到服务器或其它设备，并会拒绝看起来像密钥或凭据的内容。模型按需记录记忆，不会在每轮对话后强制生成摘要。

运行期间：

  • 运行按钮会进入 loading，避免重复触发同一次操作。
  • 当前 Workflow 工作区一次只聚焦一条 live run。任一入口启动后，其它入口的 Run 会一起禁用；只有活动入口显示 loading、Cancel 和本次结果。Server API 的项目级并发能力不受这个界面限制。
  • 运行中的记录可通过 Cancel 中止；流式输出和工具调用会立即收到中止信号，进入等待输入后会结束对应的输入请求，并标记为 aborted。
  • Output 会保留已经出现的输出；失败时错误追加在结果末尾，不覆盖已有内容。
  • Desktop 会把已经显示的运行中 Output 和 conversation 回复增量保存到本地 SQLite。强制刷新或正常退出后，最后已保存的可见内容会作为中断记录保留；重新进入原 workflow 时会自动打开这条中断记录，conversation 则恢复到原会话，不需要等待 workflow 完整结束。

远程运行云端项目​

从首页“云端”模式打开项目后，Run 主视图会通过服务器流式接口执行当前 draft 或已发布版本。Workflow 的入口 ID、参数联动、工具权限、取消信号和等待输入的提交或取消都会发送到同一个服务器项目；Conversation 只发送自己的参数和 conversationId。两者都不会调用本机 workflow runtime。

远程 Output 会在 Desktop 中实时显示，最终运行记录和 conversation 内容由服务器保存。Desktop 只保留当前工作区所需的临时内存状态，不会把云端运行、会话、知识库或 KV 正文写入 Desktop SQLite 或 localStorage。切换回同 UUID 的本地项目时，本地文件、名称、运行历史和数据仍按本地 adapter 独立读取。

需要编辑云端项目源码时，从首页云端项目菜单选择“下载到本地”或“复制为本地项目”。下载保留原 UUID 和服务器关联；复制生成新 UUID 并成为独立本地项目。只有保留原始源码的已发布版本能够执行这两项操作，本地落盘后仍需由用户在项目目录中手动安装依赖。

云端 Kanban 不进入远程运行流程。Desktop 从服务器读取固定 draft、latest 或指定版本的静态预览和当前用户的配置；预览只接受当前 Workflow Server 同源的短期 capability 地址，并继续运行在带离线 CSP 的 sandbox iframe 中。HTML 入口及其 JavaScript、CSS、图片和字体子资源以该 capability 作为临时凭据，不需要把 Desktop 的登录 Cookie 或 API Key 传入 iframe；capability 仍固定到当前项目、用户、目标版本和有效期，其它 Server API 继续要求登录。图片、字体等二进制资源会在下载或复制时按原始字节还原。对 Kanban 调用远程 Run、JSON report、Webhook 或 external run 会返回“不支持执行”错误。

定时运行 Workflow​

本地 Workflow 的“定时”工具页签可以为任一 entrypoint 创建独立计划。规则支持 IANA 时区下的“星期 + 多时间窗口 + 每 N 分钟”和五字段 Cron；保存前会校验当前 dev 源码中的入口和静态参数，并展示未来 5 次触发。项目声明 workflowCode.schedulePresets 时，预设会显示为可重复使用的建议项，只有点击确认并保存后才会创建计划。

Desktop 计划始终运行当前本地项目的 dev 源码，并在每次 fire 前重新读取 Structure；入口已经删除或参数失效时会记录跳过原因，不会换到默认入口。运行记录会显示计划名称、原触发时间和 fire ID；等待用户输入的定时 run 保持活动，后续同计划触发按重叠规则跳过。

关闭全部窗口后，Desktop 会继续驻留系统托盘并执行本地计划；明确选择“退出”、关机或设备休眠时调度停止。恢复后不会补跑停机或休眠期间的每个触发，只记录一条 skipped_missed 并推进到未来首个时间。系统偏好中的“开机后台启动”默认关闭，启用后 Desktop 会在登录系统时直接进入托盘，不自动打开窗口。完整规则参见 Workflow 定时运行。

本地运行记录​

Desktop 为每个 workflow 保留最近的本地运行记录。Workflow 摘要和完整记录会保存实际 entrypointId、入口标题快照和精确解析目标，历史列表与只读回放始终使用快照标题；旧记录缺少入口字段时显示“默认/旧版入口”。启动和历史列表先读取轻量摘要；选择某次运行时才还原完整报告。运行期间只增量更新当前 run 和当前 conversation 消息，避免按流式 token 重写全部会话；最终报告写入后，迟到的运行中快照不会覆盖它。当紧凑引用确实能减少 UTF-8 存储体积且报告处于本地运行预算内时，SQLite 会合并完全相同的 output JSON，并以显式路径记录它与报告原有位置的对应关系；在完整去重预算内，结构化输出中重复的对象和可见内容也会指向同一权威值，不同的节点 Trace 输出保持原样。超大或输出位置异常多的报告会保留原始报告结构，避免影响本地运行。已保存运行的 Logs 中，report.json 会显示实际保存的结构；运行中的 Logs 继续显示当前内存报告。Output、Diagram 和错误诊断继续使用完整的还原运行数据，行为不变。打开 Conversation Logs 时，当前已加载的每条 run 报告都会以展开状态按需读取；手动折叠只改变当前查看状态。本地运行报告不会随项目上传或发布发送到服务器。升级到新的本地报告存储格式时，旧版本地运行记录会被清理；释放的 SQLite 页会由后续新报告复用，不会在启动时执行全库压缩。被删除或裁剪的本地 run 独占附件会在后台回收；项目文件、仍被会话引用的附件和未发送的新上传附件不会受影响。

Desktop 生成的 stdio MCP 配置也写入同一套本地运行记录，并标记来源为 mcp。等待输入、连续恢复、失败、取消和完成状态始终更新同一 runId；外部 MCP 调用不会自动切换当前页面或抢占用户正在查看的其它 run。

使用 conversation​

开启 conversation 的 workflow 会显示会话列表和 composer：

Conversation 保持单入口 executor，不显示 entrypoint 列表，也不接受入口选择。它的会话 ID、队列、恢复和内部 workflow.runWorkflow() 语义不因 Workflow 多入口而改变。

  • 每个话题使用稳定的 conversation_id。
  • 标题可以由 workflow 设置，也可以由用户重命名。
  • 用户可以锁定标题；锁定后 workflow 推送的标题更新不会覆盖手动标题。
  • 左侧话题列表会在底部显示已加载范围；继续滚动或点击该续载区可以获取更早话题，加载失败时可直接重试。
  • 窄面板顶部使用紧凑的当前话题入口和图标化新建操作；展开话题入口后可搜索、滚动并继续加载更早记录，适合较长的话题列表。
  • 小助手窄页签与主区 conversation 共用顶部 44px 触达行、分隔线和 composer 垂直基线；窄版只收紧横向留白，顶部导航底边和底部输入区会保持对齐。
  • 图片和文件会先进入本地文件 store，再以 file reference 传给 workflow。
  • 消息完成后可从消息下方打开 Trace、Logs 或复制内容。
  • 流式正文和连续工具调用只会在消息区停留最底部时自动跟随；手动向上滚动后保持当前位置，重新滚到底部才恢复跟随。
  • 会话运行期间追加的等待输入会显示为紧凑单行摘要；图片、附件数量和其它详情不会占用输入区，完整文字可悬停查看，并可继续拖动排序、引导、编辑或删除。
  • 工具权限中的启用与自动批准状态按会话保存；切换会话时只恢复对应会话的覆盖值，新建或未配置会话使用 workflow 注册的工具默认值。
  • composer 右下角使用一个固定操作位：会话运行中且输入为空时显示取消图标，输入文字或添加附件后原位切换为 Send，清空输入后恢复取消，不会同时显示两个大按钮。
  • 会话运行期间可以使用取消图标中止流式输出、工具调用和恢复后的执行；如果 workflow 正在等待用户输入，取消会结束该等待的 run，不会保留可继续的任务。

会话附件只保存文件引用，不建议把 base64 原文写入 KV 或会话历史。

从首页最近任务进入 conversation run 时，Desktop 会先打开项目和对应会话，再选中该 run，方便回看输出、Trace 和 Logs。小助手任务还会携带目标项目身份，恢复前重新校验目标仍是可用的本地普通项目；仍在运行的小助手任务会直接在目标项目的右侧 Dock 打开或激活小助手页签，并定位到任务对应的对话，不需要等待运行记录写入本地历史。较早保存的运行记录如果缺少目标项目标记，Desktop 会从对应小助手会话的项目上下文恢复目标，不会退回 OpenCode 的普通项目界面。如果本地会话记录已经不存在，Desktop 仍会打开项目并尝试选中 run，同时显示非阻塞提示。

配置本地环境变量​

“环境”按钮管理本地运行使用的环境变量。它只影响 Desktop 本地运行，不会自动同步到服务器。

如果发布后的远程运行也需要同名变量，请在 Server Web 的项目详情页配置服务器环境变量。

环境变量对话框会分别显示加载、可编辑内容和错误状态。读取或保存期间会禁用重复提交；失败时保留已经填写的变量，并在对应区域提供错误信息。

管理项目知识库与 KV​

“知识库”和“KV 数据”都是项目级工具页签，并严格服从 workflowCode.projectInfo.dataStorage.mode。local 项目只显示本地数据，server 项目只显示服务器数据，both 项目在两个页签内分别提供“本地 / 服务器”分段切换并分别记忆选择。只有一个来源被允许时，Desktop 会在首次加载前直接选择该来源，不会先访问另一端再报错。同 UUID 的本地项目也能直接切到云端数据；从首页云端模式打开时则直接显示服务器数据。

  • 本地入口使用硬盘图标、青绿色和“本地”文字。知识库使用该项目独立的 PersistentValue 存储，本地 KV 使用另一套普通 KV；知识库内部命名空间按项目目录稳定生成，因此重新绑定服务器项目 ID 或修改 workflow 显示名称不会丢失本地内容。
  • 服务器入口使用云图标、信息蓝和“服务器”文字。服务器知识库、KV 与 PersistentValue 都使用同 UUID 项目的服务器数据库，不包含本地数据。
  • 本地项目首次选择服务器时，如果没有有效登录，Desktop 会先打开登录。成功后会创建或恢复同 UUID 云端绑定、同步完整声明并继续切换；失败时仍停留在原数据源，并清理本次服务器缓存。
  • Kanban iframe 的 kv 和 knowledge Bridge 与当前声明允许的后端一致；relatedProjects.get(alias).kv 只访问双方已确认的直接关联项目，并逐次校验目标对当前项目的读写授权。页面不能自行改用其它项目、scope 或存储位置。
  • 切换入口不会复制、合并或删除另一端数据。需要迁移时，应按业务需要显式导入或导出内容。

缺少 dataStorage.mode 的旧项目在执行任何用户模块或访问数据前被阻断，Desktop 只开放“信息”页。选择并保存声明后，Desktop 会把 Core 与 CLI 精确依赖更新为 0.2.0；原有 KV、知识库和 PersistentValue 不会自动迁移。

知识库列表按页加载摘要，选择文档后才加载完整 markdown；搜索结果同样按页返回。KV 列表按页展示 key、scope、类型、摘要、大小和更新时间，点击一行后才读取完整 value。这样可以在包含大文档或大型 JSON 值的项目中保持工作区响应。本地与服务器 KV 都只包含 project 和 conversation scope；KV 与 PersistentValue 使用彼此隔离的存储域。

发布到 Workflow Server​

确认登录和 server 连接

“发布”需要有效账号、可访问的 Workflow Server，以及已经绑定的项目 UUID。空 ID 项目会被阻止发布，并引导先从首页项目菜单或 Info 页创建云端应用。

保存本地文件

发布前 Desktop 会保存当前本地文件，避免把旧内容上传到服务器；开发者仍需先完成 Kanban 自己的前端构建。

选择版本发行目标

为本次不可变版本选择“Server 云端执行”和当前设备本地运行。macOS Desktop 只能选择 macOS，Windows Desktop 只能选择 Windows，异平台目标显示但不可选。Workflow/Conversation 至少启用一个目标；选择当前设备目标会锁定源码保留。Kanban 的 Server 开关固定关闭，但可以选择当前设备，也可以全部关闭并继续作为 Server 静态 Web 发布。

确认 Kanban 关联项目

Kanban 声明 workflowCode.projectInfo.relatedProjects 时，逐项确认已由双方声明的项目是随组上传还是作为 external 引用，并检查源码权限和 Server 数据初始化状态。待确认关系可以随项目保存和发布，但不能作为 included 依赖，也不获得 KV 权限。

上传并等待服务器准备

Desktop 会按 .workflowignore 上传，.gitignore 不参与。启用 Server 时，Workflow/Conversation 才安装依赖并构建 runtime；仅 Desktop 的版本只解包、校验并哈希源码。Kanban 只校验并保存静态产物。停止等待或暂时关闭 Desktop 不会取消服务器任务。

生成版本

服务器先发布 included 项目，最后激活 Kanban 根版本并固化精确 dependency lock。任一依赖失败时根版本不会上线。

“创建云端应用”与发布是两个独立动作。前者只发送项目名称、从 executor 源码派生的 projectType、workflowCode.projectCard 和 private 可见性，不发送 package.json 全文或任何源码；服务器返回 UUID 后，Desktop 才原子更新本地包身份、注册表、SQLite 会话/运行记录和当前路由。空项目首次上传时源码类型必须与创建值一致；已有 draft 或 version 后，后续上传会按 executor 的新声明更新服务器派生类型。绑定失败时本地项目与 pending UUID 都会保留，可在原服务器上重试。

Kanban 发布对话框直接读取当前编辑中的 workflowCode.projectInfo.relatedProjects，不依赖 executor Structure，也不会要求维护第二份依赖声明。每个关系会显示本地同 UUID 项目、Server 项目、双方确认状态、源码下载权限和 Server KV 初始化状态。本地存在但 Server 缺少的已确认项目默认勾选“一起上传”；选择 included 表示有权限的下载者可以取得该项目的精确源码，不能分发源码时应取消并保留为 external。KV 权限始终来自双方当前 projectInfo，发布流程不创建独立数据授权。待确认关系会明确标记，可以保存在 draft 或版本中，但不能选择 included。

项目已有已发布版本时，发布对话框会从 Server 重新确认 latest，并读取该精确版本的 Server/Desktop 发行目标、源码保留模式和 dependency lock。Server 目标、当前操作系统目标和源码偏好成为本次默认值；异平台 Desktop 目标不会继承，需要在对应系统发布。首次发布的 Workflow/Conversation 默认仅 Server，Kanban 默认只有静态 Web。关联 alias、项目 UUID 或确认状态变化时改用当前安全默认值，不继承旧绑定。发版日志始终留空。读取期间发布按钮不可用；读取失败会保留用户输入并阻止发布，避免在未知设置下改变交付方式。

项目组只传输源码文件。Desktop 会在打包和下载两端拒绝 .env*、KV、定时计划、运行历史、SQLite 和宿主用户配置；本地 KV 不上传到 Server，Server KV 也不会随下载进入本机。发布完成但 Server KV 尚未初始化时，界面会明确显示该状态，并提供打开来源 Workflow 运行页或定时任务页的入口，不会自动运行同步或启用计划。

发布对话框会展示保存、上传、服务器准备、生成版本四个阶段。服务器准备失败时会显示失败阶段和具体原因；重新打开项目后，Desktop 会查询并恢复最新的未完成或失败任务状态。

首次仅 Server 发布时“保留原始源码”默认关闭，版本只保留 Server runtime；开启后会同时保存原始源码快照。选择当前设备本地运行、发布 Kanban 或包含项目组依赖时，本次发布会锁定为保留源码，但不会改写用户原来的选择；取消强制条件后会恢复原值。源码模式与发行目标都随版本固化，发布后不能修改。

发布进行中会锁定重复发布和意外关闭，阶段状态会持续更新。发布失败后，版本和发版日志输入会保留，可根据错误详情修正后重新提交。

拉取远程代码​

“拉取”会从服务器下载 latest、draft 或指定版本，并完整替换本地可编辑源码。已发布版本会携带当前系统平台：macOS 只接受 macos 目标，Windows 只接受 windows 目标，latest 解析为该平台最新兼容在线版本；其它操作系统不会隐式兼容。执行前会要求保存或确认本地未保存改动。只有可编辑的用户本地项目存在远程版本且 Server 已连接时，顶部工具栏才显示“拉取”；内置项目不提供此操作。

下载已发布 Kanban 时，Desktop 严格读取根版本固化的 dependency lock，把有权限的 included 来源写入同一父目录下的独立同级目录，并保留各项目 UUID。Main 进程会在落盘前核对根版本、依赖的精确版本与 source hash，并按文件路径和原始字节重算每个源码包的 SHA-256；任一响应不一致时整组停止写入。父目录中已有相同 UUID 项目时视为已满足且不覆盖；目录被其它 UUID 占用时停止写入，避免混合项目。无源码权限的 included 依赖会列在完成弹窗中，可通过短期申请链接提交原因，审批后点击“补全依赖”继续。缺失来源时本地 Kanban 显示“来源项目未下载”，不会伪装成普通无数据。

“复制为本地项目”要求所有 included 依赖均可下载。复制会为整组生成新 UUID，并在同一原子写入中改写所有被复制项目之间的 workflowCode.projectInfo.relatedProjects[].projectId；只要仍有缺失依赖，该模式就保持禁用。external 关系不参与下载，其原 UUID 保持不变。

主题与布局​

工作区支持浅色、深色和跟随系统。每个宿主项目或普通文件夹的右侧/底部 Dock 尺寸、隐藏状态、页签顺序和活动项，以及部分输入布局，都是当前设备的本地 UI 偏好，不会写入项目源码或远程服务器。

参数初始化或发送前联动失败时，工作区会在对话内容区显示完整原因和对应恢复提示：Desktop 内置 Workflow Runtime 版本过旧时提示更新 Desktop，真正缺少项目依赖时提示安装缺少的包，服务器凭据返回 401 时提示重新登录，系统 AI 服务暂时不可用时提示检查连接，其他 resolver 错误保留原始摘要供排查。错误区提供“重试”按钮；重试期间会禁用重复点击，成功后恢复当前输入和 Send，无需关闭并重新打开项目。

窗口变窄时，顶部次要操作会收敛为带提示的图标，发布主操作和两个 Dock 开关仍保持可用。每个终端页签拥有独立会话，并同时显示连接状态文字和状态标记；拖动选择输出后，可以使用 header 复制按钮或 Ctrl+C / Cmd+C 复制。切换页签、隐藏 Dock、移动页签或离开项目页面不会中断终端任务，返回后可继续查看输出；只有关闭该终端页签才会结束其进程。重启 Desktop 后会在相同目标创建新终端，不恢复原进程。

下一步​

发布成功后，打开 Server Web 管理端，在项目详情中管理版本、环境变量、Embed、Webhook 和执行日志。