​
workspace upload

workspace upload 将 workflow 包上传到 Workflow Server。未传 --file 时，它会先执行本地打包；传入 --release-log 时，上传成功后会继续调用 publish。 从 issue #95 起，上传前会校验本地 workflow 顶层 package.json.id。该字段必须已经是 UUID，并且代表 server 端的项目主键；CLI 不再从目录名或 package name 推导远程项目 ID。 如果当前 workflow 源码通过相对路径引用了其它 workspace workflow，例如 ../openai-agents/index，CLI 会在本地打包阶段把这些兄弟 workflow 源码一起放进归档的 workspace/workflow/* 目录，保证 server 端构建时能解析这些本地依赖。

​
命令格式

pnpm -C workspace workspace upload <workflow> [--path <workflow-dir>] [--file <archive>] [--release-log <text>] [--create]

​
参数

参数说明
<workflow>本地 workflow 目录名、workflow 名称或直接传远程项目 UUID。
--path <workflow-dir>打包并上传指定本地目录。
--file <archive>直接上传已有 .tgz 包。
--release-log <text>上传成功后立即调用 publish。
--create先确保 server 上存在对应项目；本地已有 UUID 时按该 UUID 创建或复用，缺失 UUID 时由 server 分配并回写本地 package。

​
鉴权

配置说明
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。
--create先调用 POST /api/workflows 创建或复用远程项目；已有合法 UUID 时请求体会携带 workflowId，缺失时把 server 返回 UUID 写回顶层 package.json.id，再上传 draft 包。

​
API

步骤Endpoint
上传包POST /api/workflows/{workflow}/package
自动发布POST /api/workflows/{workflow}/publish

​
输出

情况输出
只上传输出 package API JSON。
上传并发布先输出 upload JSON，再输出 publish JSON。
server 返回非零 errCode输出 JSON，退出码为 1。

​
示例

pnpm -C workspace workspace upload hello --create
pnpm -C workspace workspace upload hello --path ./workspace/workflow/hello
pnpm -C workspace workspace upload hello --file ./workspace/.packs/hello.tgz
pnpm -C workspace workspace upload hello --create --release-log "初始发布"
Codex 示例也可以先手动打包，再上传已有归档： 
pnpm -C workspace workspace pack codex --output ./workspace/.packs/codex-manual.tgz
pnpm -C workspace workspace upload codex --file ./workspace/.packs/codex-manual.tgz
pnpm -C workspace 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 工具，随源码打包并使用 server/database backed PersistentValue 存储项目知识文档。 openai-agents 的自定义 test_tool 会随源码一起打包，用于发起小型 HTTP GET/POST 测试请求并返回响应摘要；可选本地 shellTool runner 也随源码一起 打包，通过 --local-shell 启用时仍受 --workdir 和 workflow 内部命令策略限制。

​
注意事项

场景说明
包内环境变量.env 和 .env.* 默认不进入归档，使用 server 环境变量管理运行配置。
自动发布失败upload 可能已成功，publish 失败时需要根据输出继续排查。
UUID 缺失或非法未使用 --create 时 CLI 会直接报错，要求先修正顶层 package.json.id；使用 --create 时，缺失 UUID 会由 server 创建并回写，已有 UUID 会作为 server 项目绑定值。
403 权限错误当前阶段优先提示“没有项目权限”或“已被禁止运行/上传”，不会统一引导重新登录。