Server Workspace CLI
workspace 命令与本地命令都由 @workflow-code/cli 提供。它可以打包、上传、发布和下载 Workflow、Conversation 与 Kanban 项目；只有 Workflow/Conversation 支持远程运行和节点调试。安装后使用统一的 workflow-code workspace 前缀；仓库源码开发也可以通过 workspace 脚本调用：
pnpm exec workflow-code workspace <command> [args]
它用于连接 Workflow Server，管理远程 workflow 包和版本。
参数规则
workspace CLI 会在显式 -- 之前识别全局选项，未识别的参数保留为命令位置参数或 workflow args。-- 本身会被剥离，其后的参数全部原样传给 workflow。
| 规则 | 说明 |
|---|---|
| 全局选项 | --server、--token、--target、--entrypoint、--release-log、--source-mode、--path、--file、--output、--no-wait、--create 会在分隔符前被 CLI 解析。 |
| workflow args | run 的 <workflow> 之后，未被识别为全局选项的参数会发送到 server run API。 |
| debug args | debug-node 的 <workflow> 和 <node> 之后，未被识别为全局选项的参数会发送到 debug node API。 |
| 参数分隔 | 业务参数与 CLI 选项同名时，在 CLI 选项后写 --；其后内容不再解析。 |
--version | 已废弃。版本号由 server 发布流程生成。 |
全局选项
| 选项 | 说明 |
|---|---|
--server <url> | Workflow Server 地址。默认读取 WORKFLOW_SERVER_URL，再读保存的 CLI 登录态，最后回退到开发常用的 http://localhost:7125。部署环境建议显式传正式域名或你的 server 地址。 |
--token <token> | 可选的显式 Bearer 覆盖值。默认读取 WORKFLOW_SERVER_ADMIN_KEY，再读保存的 CLI 登录态 API Key。 |
--target <target> | 远程运行、调试或下载目标。常用值为 draft、latest 或具体版本号。 |
--entrypoint <id> | 为远程 run 或 debug-node 选择 Workflow 入口；省略时使用目标版本默认入口。Conversation 不接受非空值。 |
--release-log <text> | 发布日志。用于 upload 后自动 publish，或用于 publish。 |
--source-mode <bundled|source> | 版本源码模式。默认 bundled；设为 source 时保留原始源码快照。 |
--server-runtime / --no-server-runtime | upload / publish 显式启用或关闭本次版本的 Server runtime；两者互斥。 |
--desktop-platform <macos|windows> | upload / publish 增加 Desktop 下载目标；可重复，且会强制 source 模式。 |
--path <path> | 本地 workflow 目录或下载目标目录。 |
--file <archive> | 已存在的 .tgz workflow 包。 |
--output <file.tgz> | pack 生成的压缩包路径。 |
--no-wait | upload 创建服务器准备任务后立即返回任务信息，不轮询完成状态。 |
--create | upload 时按本地 package.json.id UUID 创建或复用远程项目，并提交当前 projectInfo；不会由 Server 分配或回写 UUID。 |
配置和登录态
| 来源 | 说明 |
|---|---|
当前项目 .env | 从执行命令的工作目录读取。 |
Monorepo 根目录 .env | 仅在源码仓库内运行时额外读取。 |
| CLI 登录态文件 | login 会写入 workflow-auth.json，后续命令可复用。 |
| 环境变量 | 显式环境变量优先级高于 .env。 |
.env 示例：
WORKFLOW_SERVER_URL=http://localhost:7125
WORKFLOW_SERVER_ADMIN_KEY=replace-with-admin-key
WORKFLOW_REPO_ROOT=/absolute/path/to/workflow-code
WORKFLOW_WORKSPACE_PACKS_DIR=/absolute/path/to/writable/workflow-packs
配置优先级
| 配置项 | 优先级 |
|---|---|
| server URL | --server > WORKFLOW_SERVER_URL > CLI 登录态 > http://localhost:7125 |
| token | --token > WORKFLOW_SERVER_ADMIN_KEY > CLI 登录态 |
| repo root | WORKFLOW_REPO_ROOT > 从当前目录或 CLI 文件位置向上查找包含 pnpm-workspace.yaml 的项目根目录 |
| pack 暂存目录 | WORKFLOW_WORKSPACE_PACKS_DIR > <repo root>/workspace/.packs |
| CLI 登录态目录 | WORKFLOW_CLI_AUTH_DIR > 系统默认应用配置目录 |
CLI 登录态文件名为 workflow-auth.json。macOS 默认目录是 ~/Library/Application Support/workflow-code，Windows 默认使用 %APPDATA%/workflow-code，Linux 默认使用 $XDG_CONFIG_HOME/workflow-code 或 ~/.config/workflow-code。
从Desktop 发行包触发 Publish 时，Desktop 会为 workspace CLI 设置 WORKFLOW_WORKSPACE_PACKS_DIR 到 Desktop 用户数据目录下的可写位置；同时 upload --path <workflow-dir> 会按 <workflow-dir> 的父目录查找 ../sibling-workflow 这类本地 workflow 依赖，避免发行包误把 app.asar 当成项目根目录。
命令列表
| 命令 | 说明 |
|---|---|
login | 通过 browser device flow 登录，并保存 CLI 专用连接配置。 |
logout | 清空保存的连接配置。 |
status | 查看当前是否已登录。 |
health | 请求 server /health。 |
pack | 将本地项目打成 .tgz。 |
upload | 上传项目包；可选择自动发布。 |
publish | 将远程 draft 发布为新版本。 |
versions | 查看 workflow 版本列表。 |
run | 远程运行 Workflow/Conversation；Kanban 会被明确拒绝。 |
debug-node | 远程运行 Workflow/Conversation registry 中的单个调试节点。 |
download | 下载远程文件到本地项目目录，Kanban 二进制资源会恢复原始字节。 |
help | 输出帮助信息。 |
输出和退出码
| 情况 | 行为 |
|---|---|
server 返回 errCode: 0 | 输出 JSON，退出码保持成功。 |
server 返回非零 errCode | 输出 JSON，并设置退出码为 1。 |
| 参数缺失或本地命令失败 | 输出错误信息，退出码为 1。 |
完整发布示例
pnpm exec workflow-code workspace health --server http://localhost:7125
pnpm exec workflow-code workspace login --server http://localhost:7125
pnpm exec workflow-code workspace pack hello
pnpm exec workflow-code workspace upload hello --create --release-log "初始发布" --server-runtime --source-mode bundled
pnpm exec workflow-code workspace versions hello
pnpm exec workflow-code workspace run hello --target latest --entrypoint main -- --message "hello"
从源码运行可以继续使用本地开发地址；部署环境请替换为你的 server 地址。例如：
workflow-code workspace health --server http://localhost:7130
workflow-code workspace login --server http://localhost:7130
workspace CLI 的上传、发布、运行和下载都以顶层 package.json.id UUID 作为远程项目标识。<workflow> 位置参数可以写本地目录名或 workflow 名称，CLI 会优先读取该目录内 package.json.id；如果直接传入 UUID，则跳过本地 package 读取。本地 package 缺失 UUID 或 UUID 非法时必须先修正源码；UUID 合法但 server 端项目尚不存在时，使用 workspace upload <workflow> --create 按该 UUID 创建项目。
发行目标属于不可变版本，不属于项目展示平台。未传任何目标参数时，首次 Workflow/Conversation 上传默认仅 Server，后续上传由 Server 继承上一精确版本；Kanban 固定关闭 Server。只传 --desktop-platform 的直接 publish 会先读取远端项目类型，因此 Kanban 不会被误设为 Server 可运行。自动上传并发布会在 package 与 publish 两阶段复用同一个目标对象。
当 Workflow/Conversation 源码通过 ../<sibling-workflow>/... 引用其它 workspace workflow 时，pack 和 upload 也会把这些兄弟 workflow 源码一起打进归档里的 workspace/workflow/* 结构，确保 server 端构建 draft/runtime 包时能解析本地依赖，不需要手工拼包。Kanban 以配置的 artifactDir 和 HTML entry 为静态站点边界，不需要 README 或 executor；服务器不运行前端构建。
所有本地打包只读取每个项目根目录的 .workflowignore，不读取 .gitignore。缺少有效规则时会提示全部普通文件的数量和总大小；.workflowignore 自身、项目入口和必要元数据不能被排除。Kanban 的 dist 等产物目录不会被宿主自动保留或排除，必须由项目规则显式选择。
Codex 手动上传示例
本地 Codex 项目可先打包为 .tgz，再通过 upload --file 上传已有包，适合需要人工确认归档内容或复用包文件的场景：
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"