workflow-code CLI
workflow-code 是 @workflow-code/cli 暴露的统一命令。本地命令加载 workflow 项目、安装全局 runtime API 并在当前设备执行；连接服务器的命令位于 workspace 分组。
调用方式
项目应同时安装 Core SDK 和 CLI。两个包独立版本化，建议固定到经过验证的精确版本：
pnpm add -D workflow-code@0.2.0 @workflow-code/cli@0.2.0
项目必须在 devDependencies.workflow-code 写精确 SemVer，不能使用 ^、~、0.2.x、workspace:* 或本地路径。精确声明用于记录开发基线；运行时只比较 Core 的 major.minor 兼容线，因此同线任意 patch 或日期 Alpha 可直接运行，major 或 minor 变化才要求升级 CLI 或其它宿主。@workflow-code/cli 也保持精确版本，但与 Core 独立发版。
CLI 自身精确绑定 Core，并把 peerDependencies.workflow-code 限制在同一 minor，例如绑定 0.2.7 时为 >=0.2.0 <0.3.0。run、json、structure、resolve-params 和 mcp 会在加载项目模块前校验实际安装的 Core、CLI 自身绑定和项目 Core 声明；structure 还会校验完整 workflowCode.projectInfo 合同。help 不加载项目，因此不执行这些检查。
| 场景 | 命令 |
|---|---|
| 项目脚本 | pnpm run dev |
| 已安装 bin | pnpm exec workflow-code <command> |
| CLI 源码仓库开发 | pnpm build && node dist/index.js <command> |
命令格式
workflow-code <command> [workflow-dir] [options] [--] [...args]
| 部分 | 说明 |
|---|---|
<command> | run、json、structure、resolve-params、mcp 或 help。不传命令时显示帮助。 |
[workflow-dir] | workflow 项目目录。不传时使用当前目录。 |
[--] [...args] | executor createInput 可读取的 CLI 风格参数。-- 用于停止解析 CLI 自身选项，后续参数会原样传给 workflow。 |
全局选项
| 选项 | 说明 |
|---|---|
--help / -h | 显示帮助。必须作为第一个参数使用。 |
--json | 在 run 命令中切换为 JSON 报告输出；json 命令默认开启。 |
--run-id <id> | 指定本次执行 ID。主要用于恢复 waiting_for_input run。 |
--entrypoint <id> | 为 Workflow 选择入口；省略时使用默认入口。适用于 run、json 和 resolve-params，Conversation 不接受非空值。 |
--conversation-id <id> | 指定会话 ID。run 和 json 都可使用。 |
--file-store-dir <dir> | 指定本地文件 store 目录。run 和 json 都可使用。 |
--related-project <alias>=<绝对项目目录> | 为 run 或 json 绑定一个双方已确认的关联项目；可重复指定。目录必须是绝对路径，且 alias、UUID、双方 package 声明都必须匹配。 |
--resolved-user-inputs-json <json> | 注入已提交的用户输入或工具审批答案数组。 |
--tool-permissions-json <json> | 宿主传入工具权限覆盖策略；普通手动 CLI 调试通常不需要传。 |
命令列表
| 命令 | 说明 |
|---|---|
workflow-code run | 本地执行 workflow，普通模式输出 output node 内容。 |
workflow-code json | 本地执行 workflow，并输出完整 JSON 执行报告。 |
workflow-code structure | 分析 workflow 结构并输出 JSON。 |
workflow-code resolve-params | 从 stdin 读取 composer 状态并执行 executor 参数联动回调。 |
workflow-code mcp | 将 Workflow entrypoint 作为标准 stdio MCP tools 提供给 AI 客户端。 |
workflow-code help | 输出帮助信息。 |
本地运行环境
| 环境变量 | 说明 |
|---|---|
WORKFLOW_KV_STORE_DIR | 本地 KV store 目录。 |
WORKFLOW_PERSISTENT_VALUE_STORE_DIR | 本地 PersistentValue store 目录，项目知识库也保存在这里。 |
WORKFLOW_FILE_STORE_DIR | 本地文件 store 目录。 |
WORKFLOW_DESKTOP_RUNTIME_EVENTS=1 | json 模式下额外输出 Desktop 可消费的 runtime event 前缀行。 |
WORKFLOW_KV_STORE_DIR 与 WORKFLOW_PERSISTENT_VALUE_STORE_DIR 互不复用：前者控制 context.storage.local.kv，后者控制 context.storage.local.persistentValue 和本地知识库。两者都按顶层 package.json.id 的 UUID 隔离当前项目。context.storage.server 始终使用同一项目 UUID 与已登录服务器连接，不受这两个本地目录影响。项目必须声明 dataStorage.mode；禁止或不可用的位置直接报错，本地数据不会自动同步到服务器。--related-project 只解析明确传入的目录，不扫描父目录或兄弟目录，也不会让关联访问递归穿过第二层关系。
退出码
| 情况 | 退出码 |
|---|---|
运行成功，且 payload errCode 为 0 | 0 |
| 运行失败 | 1 |
payload errCode 非 0 | 1 |
| structure 分析失败 | 1 |
输出
| 命令 | stdout/stderr |
|---|---|
run | 成功时将 output node 内容写到 stdout；失败时 JSON 报告写到 stderr。 |
json | 完整执行报告写到 stdout。 |
structure | workflow 结构 JSON 写到 stdout。 |
resolve-params | 参数状态补丁 JSON 写到 stdout。 |
mcp | stdout 只输出 stdio JSON-RPC；项目日志与 worker 诊断写到 stderr。 |
参数分隔
如果 workflow 参数本身以 -- 开头，建议显式写分隔符：
workflow-code run . -- --message "hello"
分隔符之后的参数会进入所选 entrypoint（Conversation 则为 executor）的 args 数组，即使参数名与 CLI 自身选项相同也不会再被 workflow-code 消费。例如 workflow-code run . --entrypoint validate -- --entrypoint workflow-owned 会选择 validate，并把第二个 --entrypoint workflow-owned 原样交给业务 workflow。