workspace run

workspace run 调用 Workflow Server 的 run API，在远程 draft、latest 或指定在线版本上执行 workflow。

该命令只支持 Workflow 和 Conversation。Kanban 不产生运行记录，服务器会返回静态项目不支持执行的明确错误。

CLI 运行会使用 API key owner 作为 actor 写入 server run record。项目必须已绑定顶层 package.json.id UUID，并且当前账号同时满足“项目可见 + 有运行权限 + 未被 run block 禁止”。

命令格式

pnpm exec workflow-code workspace run <workflow> [--target draft|latest|version] [--entrypoint <id>] [--] [...args]

参数

参数	说明
`<workflow>`	本地 workflow 目录名、workflow 名称或直接传远程项目 UUID。
`args`	发送到 server run API 的 `args` 数组。
`--target <target>`	运行目标。默认 `latest`。
`--entrypoint <id>`	Workflow 入口。省略时使用目标版本的默认入口；Conversation 传入非空值会返回 `400`。

Target

值	说明
`latest`	默认值。运行当前 latest 版本。
`draft`	运行远程 draft。适合发布前验证。
具体版本号	运行指定在线版本。`preparing` 或 `offline` 版本会被 server 拒绝。

参数解析规则

workspace CLI 会在显式 -- 之前识别自己的全局选项。未识别的参数会保留到 args 数组；-- 本身被剥离，其后参数全部原样透传。

场景	写法
普通业务参数	`run hello -- --message "hello"`
指定 target 和入口	`run hello --target draft --entrypoint validate -- --message "hello"`
业务参数也叫 `--entrypoint`	`run hello --entrypoint validate -- --entrypoint workflow-owned`；前者选择入口，后者进入业务 args。

API

步骤	Endpoint
远程运行	`POST /api/workflows/{workflow}/run`

请求体包含 target、可选 entrypointId 和 args，也兼容 entrypoint_id。直接调用 HTTP API 时，可以用 version 作为具体版本号别名；未提供 target 时 server 会把 version 作为运行目标。Server 会在入队前按精确目标校验入口，未知入口返回 400 并附允许入口与默认入口。

输出

情况	输出
运行成功	server run API JSON。
workflow payload `errCode` 非 `0`	server 返回错误语义，CLI 退出码为 `1`。
未登录	输出错误信息，退出码为 `1`。
403	CLI 会区分“没有项目权限”和“当前账号已被该项目禁止运行”，而不是统一提示重新登录。

示例

pnpm exec workflow-code workspace run hello -- --message "hello"
pnpm exec workflow-code workspace run hello --target latest --entrypoint main -- --message "hello"
pnpm exec workflow-code workspace run hello --target draft --entrypoint validate -- --message "draft test"
pnpm exec workflow-code workspace run conversation-knowledge --target draft -- --message "记录今天的结论" --title "Demo conversation"

如果需要为 conversation workflow 指定稳定 conversation_id，直接调用 server run API；workspace run 当前只发送 target 和 args：

curl -X POST "$WORKFLOW_SERVER_URL/api/workflows/conversation-knowledge/run" \
  -H "Authorization: Bearer $WORKFLOW_SERVER_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "draft",
    "conversation_id": "demo-thread",
    "args": ["--message", "记录今天的结论", "--title", "Demo conversation"]
  }'

目标	命令
单节点调试	`debug-node`
查看可运行版本	`versions`

命令格式​

参数​

Target​

参数解析规则​

API​

输出​

示例​

相关命令​

命令格式

参数

Target

参数解析规则

API

输出

示例

相关命令