workspace upload

workspace upload 将项目包上传到 Workflow Server。未传 --file 时，它会先按 .workflowignore 执行本地打包；服务器收到归档后返回准备任务 ID。启用 Server runtime 的 Workflow/Conversation 会安装依赖并 bundle/minify；Server 关闭时只解包、校验并哈希源码，不安装依赖或创建 runtime。Kanban 固定关闭 Server，只校验配置的产物目录和 HTML 入口并保留静态资源。CLI 默认轮询任务直到成功或失败；传入 --release-log 时，准备成功后会继续调用 publish，并复用同一发行策略。

CLI 在打包和上传过程中不会安装或修改本地项目依赖，也不要求本地存在 node_modules。未传 --file 时只收集源码并生成归档，依赖安装由服务器构建阶段负责。服务器不会把仅用于平台 API 与开发命令的 workflow-code、@workflow-code/cli 写入版本 runtime；其它业务依赖会被整理为不含符号链接的可移植归档。

上传文件只受项目根目录 .workflowignore 控制；.gitignore 不参与。缺少有效规则时，CLI 会在上传前提示将上传全部普通文件的数量和总大小。Kanban 的实际 artifactDir 必须保留；前端源码、测试、依赖和 secret 是否上传由项目规则显式决定。

上传前会校验本地 workflow 顶层 package.json.id。该字段必须是 UUID，并且代表 server 端的项目主键；CLI 不再从目录名或 package name 推导远程项目 ID。

如果当前 workflow 源码通过相对路径引用了其它 workspace workflow，例如 ../openai-agents/index，CLI 会在本地打包阶段把这些兄弟 workflow 源码一起放进归档的 workspace/workflow/* 目录，保证 server 端构建时能解析这些本地依赖。

命令格式

pnpm exec workflow-code workspace upload <workflow> [--path <workflow-dir>] [--file <archive>] [--release-log <text>] [--source-mode bundled|source] [--server-runtime|--no-server-runtime] [--desktop-platform macos|windows] [--no-wait] [--create] [--project-group] [--publish-group] [--dependency <alias>=<path>]

参数

参数	说明
<workflow>	本地 workflow 目录名、workflow 名称或直接传远程项目 UUID。
--path <workflow-dir>	打包并上传指定本地目录。
--file <archive>	直接上传已有 .tgz 包。
--release-log <text>	上传成功后立即调用 publish。
--source-mode <bundled|source>	自动发布的源码模式。默认 bundled；source 会保留原始源码快照。
--server-runtime	为本次版本准备 Server runtime。
--no-server-runtime	关闭本次版本的 Server runtime；Workflow/Conversation 仍需至少一个 Desktop 目标。
--desktop-platform <macos|windows>	允许对应 Desktop 下载；可重复，自动要求 source，不能与 --source-mode bundled 组合。
--no-wait	单项目上传时创建服务器准备任务后立即返回 jobId，不轮询任务完成状态。不能与项目组或本次命令内的自动发布组合使用。
--create	按本地 package 已声明的 UUID 和 projectInfo 创建或复用 Server 项目；缺失 UUID 或存储声明时直接失败。
--project-group	按根 Kanban 中双方已确认的关联项目创建 project-group v1，而不是普通单项目上传。
--dependency <alias>=<path>	将 alias 对应的本地关联项目作为 included 依赖打包；可重复。未指定的已确认关系保持 external，待确认关系不进入依赖组。
--publish-group	项目组准备完成后立即发布；未填写 --release-log 时也生效。

鉴权

配置	说明
server URL	来自 --server、WORKFLOW_SERVER_URL 或 CLI 登录态。
token	来自 --token、WORKFLOW_SERVER_ADMIN_KEY 或 CLI 登录态 API Key。
未登录	命令失败，并提示先执行 workspace login。

上传模式

模式	行为
默认	上传包为远程 draft。
--file	跳过本地打包，直接读取指定归档。
--release-log	上传成功后调用 /api/workflows/{workflow}/publish。
发行目标	package 请求使用 `serverRuntime=true
--no-wait	仅用于单项目上传，只返回服务器准备任务；稍后通过 preparation API 查询状态。项目组必须等待整组完成权限校验、版本预留和准备。
--create	先调用 POST /api/workflows，携带 package 中的 workflowId、projectType 与完整 projectInfo 创建或复用远程项目，再上传 draft 包；不会修改本地项目 ID。
项目组	只要使用 --project-group、--dependency 或 --publish-group 就进入项目组模式；CLI 校验根项目是 Kanban，并按 projectInfo.relatedProjects 中双方已确认的 alias 解析 included/external。

--create 创建的空项目会保存当前源码派生的 projectType 和 package 当前 projectInfo，首次上传必须与该值一致。Workflow/Conversation 类型来自 executor，Kanban 类型来自 package.json.workflowCode.projectType。远程项目已经有 draft 或 version 后，后续上传会用新的明确声明更新派生值；任何上传都不会从目录名或包名猜测类型。

项目组上传

项目组模式先为根 Kanban 和全部 included 关联项目创建或复用 Server 项目，再分别按各自 .workflowignore 打包，生成包含 project-group.json 和项目归档的 tar.gz。Server 一次性校验所有项目权限、双方关系并预留版本；依赖先发布，Kanban 根版本最后激活并保存精确 dependency lock。included 项目强制以 source 模式发布，表示有权限的下载者可以取得源码；不能分发源码时不要传对应 --dependency。数据读写权限只来自双方当前 projectInfo，CLI 不创建独立授权。

CLI 在每个项目归档和外层项目组中都拒绝 .env*、KV、PersistentValue、定时计划、运行历史、SQLite、workflow-auth.json 与其它宿主用户配置。本地 KV 不进入 Server；发布后必须通过来源 Workflow entrypoint、Server Run API 或业务接口在 Server 端初始化数据。

API

步骤	Endpoint
上传包	POST /api/workflows/{workflow}/package?serverRuntime=<boolean>&desktopPlatform=<platform>
查询准备任务	GET /api/workflows/{workflow}/preparations/{jobId}
自动发布	POST /api/workflows/{workflow}/publish
创建项目组计划	POST /api/deployments
上传项目组	POST /api/deployments/{deploymentId}/package
发布项目组	POST /api/deployments/{deploymentId}/publish

也可以使用 workflow-code workspace preparation <workflow-id> <job-id> 查询已返回的准备任务；该命令不会取消或重启服务器任务。

输出

情况	输出
只上传	准备成功后输出 draft 构建结果 JSON。
上传并发布	准备成功后输出构建结果，再输出 publish JSON。
项目组	输出部署记录，其中包含每个项目的预留版本、准备阶段、精确发布版本和失败原因。
server 返回非零 errCode	输出 JSON，退出码为 1。

示例

pnpm exec workflow-code workspace upload hello --create
pnpm exec workflow-code workspace upload hello --path ./workspace/workflow/hello
pnpm exec workflow-code workspace upload hello --file ./workspace/.packs/hello.tgz
pnpm exec workflow-code workspace upload hello --create --release-log "初始发布" --server-runtime
pnpm exec workflow-code workspace upload hello --release-log "macOS 本地发行" --no-server-runtime --desktop-platform macos
pnpm exec workflow-code workspace upload hello --release-log "云端与双桌面发行" --server-runtime --desktop-platform macos --desktop-platform windows
pnpm exec workflow-code workspace upload stock-kanban \
  --path ./stock-kanban \
  --dependency stocks=./stock-workflow \
  --publish-group \
  --release-log "发布股票看板项目组"

Codex 示例也可以先手动打包，再上传已有归档：

pnpm exec workflow-code workspace pack codex --path ./codex-project --output ./workspace/.packs/codex-manual.tgz
pnpm exec workflow-code workspace upload codex --file ./workspace/.packs/codex-manual.tgz
pnpm exec workflow-code workspace publish codex --release-log "manual codex upload"

带第三方 SDK 的示例也按 workflow 目录自己的 package.json 声明依赖。 例如 workspace/workflow/openai-agents 声明 @openai/agents、openai 和 zod，workspace/workflow/claude-agent 声明 @anthropic-ai/claude-agent-sdk，workspace/workflow/gpt-image 声明 openai，workspace/workflow/pi-agent 声明 @earendil-works/pi-coding-agent；server runtime 会在构建 runtime 包时安装这些业务依赖。 OpenAI 示例的 OPENAI_API_KEY / OPENAI_BASE_URL、Claude Agent 示例的 ANTHROPIC_API_KEY、Pi Agent 示例的 ANTHROPIC_* / OPENAI_* provider 配置 都通过 server 环境变量页面配置。OpenAI、Claude Agent 和 Pi Agent 示例都包含 knowledge_documents 工具；这些 workflow 在 server runtime 中会使用 server/database-backed PersistentValue 存储项目知识文档。本地 CLI/Desktop 运行 同一 workflow 时，可以通过 WORKFLOW_PERSISTENT_VALUE_STORE_DIR 使用独立的 本地知识库，且不会自动与服务器项目同步。 openai-agents 的自定义 test_tool 会随源码一起打包，用于发起小型 HTTP GET/POST 测试请求并返回响应摘要；可选本地 shellTool runner 也随源码一起 打包，通过 --local-shell 启用时仍受 --workdir 和 workflow 命令策略限制。

注意事项

场景	说明
包内敏感文件	宿主不会暗中排除 .env、node_modules 或 Git 元数据；必须在 .workflowignore 中显式配置。
Git 与上传	.gitignore 不参与上传；同一 dist 可以不提交 Git 但仍由 .workflowignore 保留并上传。
Kanban 静态资源	artifactDir 内 HTML、CSS、JavaScript、图片和字体按原始字节保留；页面必须遵守产物目录内相对路径和离线 sandbox。
项目组数据	项目组只交付源码，不上传本地 KV、计划、运行历史、环境变量或用户配置；Desktop 与 Server 数据仍相互隔离。
中断等待	CLI 退出或网络中断不会取消服务器准备任务，之后可使用 preparation 查询 API 恢复状态。
自动发布失败	upload 可能已成功，publish 失败时需要根据输出继续排查。
大型 SDK 首次安装	server 会保留包内 lockfile，并按 lockfile 安装确定版本。包含平台二进制的 SDK 首次上传可能耗时较长；下载超时时应检查 server 的 npm registry 网络、磁盘空间和依赖安装超时配置。
UUID 缺失或非法	CLI 直接报错并要求先修正顶层 package.json.id；--create 不会分配、转换或回写 UUID。
403 权限错误	CLI 会优先提示“没有项目权限”或“已被禁止运行/上传”，不会统一引导重新登录。