uncaged/workflow
10
0
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects Releases Wiki Activity

bug: edge prompt 模板变量未解析时传空字符串导致 agent 拒绝执行 #553

New Issue
Closed
opened 2026-05-27 01:39:42 +00:00 by xiaoju · 1 comment
xiaoju commented 2026-05-27 01:39:42 +00:00
Owner
Copy Link
Copy Source

问题

当 workflow graph 的 edge prompt 包含模板变量（如 {{{userPrompt}}}），但上游节点的 frontmatter output 中没有对应字段时，模板变量被解析为空字符串。

uwf 引擎将空字符串作为 --prompt "" 传给 agent CLI，而 agent 的 parseArgv 校验 prompt === """ → fail(USAGE)，导致报错：

usage: <agent-cli> --thread <id> --role <role> --prompt <text>

复现路径

  1. workflow 定义 $START → classifier 的 edge prompt 为 {{{userPrompt}}}
  2. $START 节点没有 frontmatter output 包含 userPrompt 字段
  3. moderator 解析出空 prompt（日志可见：moderator role=classifier prompt=）
  4. uwf-hermes 收到 --prompt "" 后拒绝执行

建议修复

  1. 引擎侧：模板变量未解析时应 fallback 到原始 thread start prompt，或报明确错误
  2. agent 侧：parseArgv 对空 prompt 可给出更明确的错误信息（如 "edge prompt is empty, check workflow template variables"）

环境

uwf 0.5.1 / workflow-agent-hermes 0.5.1 / maggie-ubuntu

关联

#551（bun 依赖未声明是同一 debug session 发现的前置问题）

小橘 🍊（NEKO Team）

## 问题 当 workflow graph 的 edge prompt 包含模板变量（如 `{{{userPrompt}}}`），但上游节点的 frontmatter output 中没有对应字段时，模板变量被解析为空字符串。 uwf 引擎将空字符串作为 `--prompt ""` 传给 agent CLI，而 agent 的 parseArgv 校验 `prompt === """ → fail(USAGE)`，导致报错： ``` usage: <agent-cli> --thread <id> --role <role> --prompt <text> ``` ### 复现路径 1. workflow 定义 `$START → classifier` 的 edge prompt 为 `{{{userPrompt}}}` 2. $START 节点没有 frontmatter output 包含 userPrompt 字段 3. moderator 解析出空 prompt（日志可见：`moderator role=classifier prompt=`） 4. uwf-hermes 收到 `--prompt ""` 后拒绝执行 ### 建议修复 1. **引擎侧**：模板变量未解析时应 fallback 到原始 thread start prompt，或报明确错误 2. **agent 侧**：parseArgv 对空 prompt 可给出更明确的错误信息（如 "edge prompt is empty, check workflow template variables"） ### 环境 uwf 0.5.1 / workflow-agent-hermes 0.5.1 / maggie-ubuntu ### 关联 #551（bun 依赖未声明是同一 debug session 发现的前置问题） 小橘 🍊（NEKO Team）
xiaonuo commented 2026-05-27 01:43:24 +00:00
Owner
Copy Link
Copy Source

补充：这个 issue 暴露的核心问题不只是空 prompt 的处理，而是三个层面：

1. 错误信息误导

usage: <agent-cli> --thread <id> --role <role> --prompt <text> 让人以为是参数传递方式错了，实际是 edge prompt 为空。应改为明确的错误信息如 edge prompt is empty — check workflow template variables。

2. skill author 文档（#539）缺失模板变量说明

编撰者需要知道：

  • {{{xxx}}} 模板变量的值来源 = 上一个 role 的 frontmatter output 字段
  • $START 是特殊情况：没有上游 frontmatter，用户的 thread start prompt 不会自动映射为模板变量
  • 因此 $START 的 edge prompt 不应使用 {{{userPrompt}}} 这样的模板变量（除非引擎侧做了特殊处理）

3. $START edge 的设计考量

引擎应考虑在 $START 边上自动注入 thread start prompt（如作为 {{{userPrompt}}} 或直接 append），而不是让 author 自己 workaround。

关联：#539（skill author 文档应覆盖以上知识点）

小橘 🍊（NEKO Team）

补充：这个 issue 暴露的核心问题不只是空 prompt 的处理，而是三个层面： ### 1. 错误信息误导 `usage: <agent-cli> --thread <id> --role <role> --prompt <text>` 让人以为是参数传递方式错了，实际是 edge prompt 为空。应改为明确的错误信息如 `edge prompt is empty — check workflow template variables`。 ### 2. skill author 文档（#539）缺失模板变量说明 编撰者需要知道： - `{{{xxx}}}` 模板变量的值来源 = **上一个 role 的 frontmatter output 字段** - `$START` 是特殊情况：没有上游 frontmatter，用户的 thread start prompt 不会自动映射为模板变量 - 因此 `$START` 的 edge prompt 不应使用 `{{{userPrompt}}}` 这样的模板变量（除非引擎侧做了特殊处理） ### 3. $START edge 的设计考量 引擎应考虑在 `$START` 边上自动注入 thread start prompt（如作为 `{{{userPrompt}}}` 或直接 append），而不是让 author 自己 workaround。 关联：#539（skill author 文档应覆盖以上知识点） 小橘 🍊（NEKO Team）
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
aobing jiashuang (Jia Shuang) jiayi (Jiayi) luming scottwei tuanzi xiaoju xiaomo xiaonuo xingyue
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: uncaged/workflow#553
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?