steamharness run
steamharness run 在本地设备加载一个 workflow 目录，安装全局 workflow runtime API，执行所选入口（Conversation 则为 executor）的 createInput 和 workflow run，并按普通 CLI 模式输出结果。
该命令只支持 Workflow 和 Conversation。Kanban 是静态 HTML 项目，调用时会返回“不支持 workflow 执行”的明确错误；请使用 steamharness structure 检查项目，并通过 steamharness web、Studio 或 Server Web 静态预览。
命令格式
steamharness run [workflow-dir] [--entrypoint <id>] [--json] [--run-id <id>] [--conversation-id <id>] [--file-store-dir <dir>] [--related-project <alias>=<absolute-project-dir>] [--resolved-user-inputs-json <json>] [--tool-permissions-json <json>] [--] [...args]
参数
| 参数 | 说明 |
|---|---|
workflow-dir | workflow 项目目录。不传时使用当前目录。 |
args | 所选入口（Conversation 则为 executor）的 createInput({ args }) 可读取的原始参数数组。 |
选项
| 选项 | 说明 |
|---|---|
--json | 切换为 JSON 报告输出。行为接近 steamharness json。 |
--entrypoint <id> | 运行指定 Workflow 入口；省略时使用 defaultEntrypoint。Conversation 传入非空值会失败。 |
--run-id <id> | 指定本次执行 ID。用于恢复 waiting_for_input run 时保持同一个 runId。 |
--conversation-id <id> | 指定会话 ID。仅对声明 executor.projectType: "conversation" 的项目有状态读写意义。 |
--file-store-dir <dir> | 指定本地文件 store 目录。未传时读取 STEAMHARNESS_FILE_STORE_DIR。 |
--related-project <alias>=<绝对项目目录> | 显式提供一个关联项目目录；可重复指定。只接受双方 package 已确认、UUID 和 alias 匹配的关系。 |
--resolved-user-inputs-json <json> | 注入已提交的用户输入或工具审批答案数组。 |
--tool-permissions-json <json> | 宿主传入工具权限覆盖策略；普通手动 CLI 调试通常不需要传。 |
file 参数接收本地路径或 JSON file reference。声明 control: "audio" 的参数仍只接收一个音频文件；CLI 不使用麦克风，直接传 WAV、AIFF、FLAC、M4A、MP3、AAC、Opus 或 Ogg 路径。
执行流程
| 阶段 | 说明 |
|---|---|
| 解析目录 | workflow-dir 缺省时使用当前目录。 |
| 加载环境 | 执行前加载 workflow 目录下 .env。 |
| 选择入口 | Workflow 按 --entrypoint 或 defaultEntrypoint 选择执行配置；Conversation 使用 executor 本身。 |
| 创建输入 | 调用所选入口或 Conversation executor 的 createInput(context)。 |
| 执行 workflow | 只调用所选配置的 steamharness.run(input, context)，普通节点会触发 CLI 输出 hooks。 |
| 设置退出码 | workflow 失败、暂停等待输入或 payload errCode 非 0 时退出码为 1。 |
输出
| 情况 | 输出 |
|---|---|
成功且未传 --json | output node 的内容写到 stdout。 |
失败且未传 --json | 完整 JSON 执行报告写到 stderr。 |
waiting_for_input 且未传 --json | 不会交互式读取 stdin；建议改用 steamharness json 查看 pendingUserInput 并恢复。 |
传入 --json | 完整 JSON 执行报告写到 stdout。 |
示例
steamharness run .
steamharness run . --entrypoint validate -- --message "只校验"
steamharness run workspace/workflow/hello -- --message "hello"
steamharness run workspace/workflow/runtime-timer -- --title "Fixture Timer" --milliseconds 2000
steamharness run . --conversation-id demo -- --message "继续"
steamharness run . --related-project inventory=/srv/workflows/inventory -- --message "读取库存"
STEAMHARNESS_KV_STORE_DIR="$PWD/.workflow-kv" \
STEAMHARNESS_PERSISTENT_VALUE_STORE_DIR="$PWD/.workflow-persistent-values" \
steamharness run workspace/workflow/conversation-knowledge --conversation-id demo -- --message "记录今天的结论"
steamharness run . --json -- --message "debug"
注意事项
| 场景 | 建议 |
|---|---|
workflow 参数以 -- 开头 | 使用分隔符 --，分隔符后的参数会原样传给 workflow。 |
workflow 也定义了 --entrypoint 参数 | CLI 的入口选择放在分隔符前；分隔符后的同名参数原样进入业务 args。 |
| 需要检查节点报告 | 使用 --json 或改用 steamharness json。 |
| 需要恢复用户输入或工具审批 | 使用相同 --run-id 与 --resolved-user-inputs-json；调试时优先使用 steamharness json。 |
| 需要稳定会话 | 显式传 --conversation-id，否则会话 ID 可能由 runtime 根据输入生成。 |
| workflow 调用 PersistentValue 或知识库 helper | 必须传入 context.storage.local 或 .server。本地位置使用 STEAMHARNESS_PERSISTENT_VALUE_STORE_DIR；服务器位置使用项目 UUID 与 STEAMHARNESS_SERVER_URL / STEAMHARNESS_SERVER_ADMIN_KEY 或 workspace 登录态。禁止或不可用的位置直接报错，不会回退或同步。 |
| workflow 调用关联项目的 KV / 知识库 / 入口 | 为每个直接关系重复传入 --related-project。CLI 校验目录、UUID、alias 和双方当前声明；单边待确认关系不可用，也不会递归解析目标项目的其它关系。关联 KV 用 STEAMHARNESS_KV_STORE_DIR（缺省为共享临时目录）；关联知识库需要显式配置 STEAMHARNESS_PERSISTENT_VALUE_STORE_DIR，未配置时知识库不可达并明确报错，不会回退或新建临时目录；目标入口的子运行与关系共用同一份目录，入口失败时抛出的是该入口自己的错误信息。 |
workflow 调用 context.files.createFile(...) | 本地运行会读取同一 server 连接并上传到 server 文件 API；未连接 server 时调用会报错，不会写入本地文件 store。 |
项目配置
三种项目类型均支持字段、命名配置及完整导入导出。Studio 与本地 CLI 共用本地存储，Server 按项目和账号隔离。面板关闭时 Studio Control 仍能查询和管理配置。JSON 操作、版本检查和运行快照规则见项目配置。