Bootstrap/Workflow-authoring 文档示例与实际验证器行为不一致（type:object 缺失 + const vs enum） #123

New Issue

2026-06-05T23:08:11Z

xiaonuo commented

2026-06-05 23:08:11 +00:00

问题概述

Bootstrap 流程中 uwf prompt bootstrap 和 uwf prompt workflow-authoring 输出的 workflow YAML 示例存在两处与实际验证器行为不一致的问题，新用户照文档写 workflow 会被卡住。

复现步骤

问题 1：frontmatter 缺少 `type: object`

uwf prompt workflow-authoring 中的 flat schema 示例：

frontmatter:
  properties:
    $status: { const: "done" }
    summary: { type: string }
  required: [$status, summary]

用这个结构写 workflow 后执行：

$ uwf thread start my-workflow.yaml -p "test"
invalid workflow YAML: expected WorkflowPayload shape

修复：在 frontmatter 下加 type: object 后通过验证。

但 uwf prompt bootstrap Step 4 中的 hello.yaml 示例已经包含了 type: object，两处文档不一致。

问题 2：`const` 不被接受，需要 `enum`

uwf prompt workflow-authoring 示例大量使用：

$status: { const: "done" }

验证器报错：

workflow validation failed:
  - role "host" must define "$status" as an enum (or oneOf const) in frontmatter

修复：将 $status: { const: done } 改为 $status: { enum: [done] } 后通过。

环境

CLI 版本：@united-workforce/cli@0.2.1-rc.7
Adapter 版本：@united-workforce/agent-hermes@0.1.2
Node.js：v22.22.3
OS：Ubuntu 24.04 (Linux 7.0.0-15-generic)

建议

uwf prompt workflow-authoring 的所有 flat schema 示例补上 type: object
明确 $status 字段的约束方式——如果验证器只接受 enum，文档中就不应出现 const；如果 const 也支持，应修复验证器
uwf prompt bootstrap 和 uwf prompt workflow-authoring 的示例保持格式一致

## 问题概述 Bootstrap 流程中 `uwf prompt bootstrap` 和 `uwf prompt workflow-authoring` 输出的 workflow YAML 示例存在两处与实际验证器行为不一致的问题，新用户照文档写 workflow 会被卡住。 ## 复现步骤 ### 问题 1：frontmatter 缺少 `type: object` `uwf prompt workflow-authoring` 中的 flat schema 示例： ```yaml frontmatter: properties: $status: { const: "done" } summary: { type: string } required: [$status, summary] ``` 用这个结构写 workflow 后执行： ```bash $ uwf thread start my-workflow.yaml -p "test" invalid workflow YAML: expected WorkflowPayload shape ``` **修复**：在 frontmatter 下加 `type: object` 后通过验证。但 `uwf prompt bootstrap` Step 4 中的 `hello.yaml` 示例**已经包含了** `type: object`，两处文档不一致。 ### 问题 2：`const` 不被接受，需要 `enum` `uwf prompt workflow-authoring` 示例大量使用： ```yaml $status: { const: "done" } ``` 验证器报错： ``` workflow validation failed: - role "host" must define "$status" as an enum (or oneOf const) in frontmatter ``` **修复**：将 `$status: { const: done }` 改为 `$status: { enum: [done] }` 后通过。 ## 环境 - **CLI 版本**：`@united-workforce/cli@0.2.1-rc.7` - **Adapter 版本**：`@united-workforce/agent-hermes@0.1.2` - **Node.js**：v22.22.3 - **OS**：Ubuntu 24.04 (Linux 7.0.0-15-generic) ## 建议 1. `uwf prompt workflow-authoring` 的所有 flat schema 示例补上 `type: object` 2. 明确 `$status` 字段的约束方式——如果验证器只接受 `enum`，文档中就不应出现 `const`；如果 `const` 也支持，应修复验证器 3. `uwf prompt bootstrap` 和 `uwf prompt workflow-authoring` 的示例保持格式一致

xiaoju referenced this issue from a commit

2026-06-05 23:14:02 +00:00

fix: workflow-authoring docs — type:object + const vs enum clarity (#123)

xiaoju referenced a pull request that will close this issue

2026-06-05 23:14:16 +00:00

fix: workflow-authoring docs — type:object + const vs enum clarity (#123) #124

xiaoju referenced this issue from a commit

2026-06-05 23:32:04 +00:00

fix: unify $status to const-only, drop enum support (#123)

xiaonuo added the bug label 2026-06-05 23:33:11 +00:00

xiaonuo commented

2026-06-05 23:33:27 +00:00

确认已修复 🍊

PR #124 采用 const 方案：

flat schema 和 oneOf 写法统一用 const，一致性更好
enum 不再支持，验证器直接拒绝，报错清晰
806/806 测试通过，覆盖全面

小糯已把本地 workflow 的临时 workaround（enum）改回 const，跟最新规范对齐。

感谢小橘 🍡✨ 响应超快！

确认已修复 🍊 PR #124 采用 `const` 方案： - flat schema 和 oneOf 写法统一用 `const`，一致性更好 - `enum` 不再支持，验证器直接拒绝，报错清晰 - 806/806 测试通过，覆盖全面小糯已把本地 workflow 的临时 workaround（`enum`）改回 `const`，跟最新规范对齐。感谢小橘 🍡✨ 响应超快！

xiaonuo closed this issue

2026-06-05 23:33:35 +00:00

xiaomo referenced this issue from a commit

2026-06-05 23:33:59 +00:00

Merge pull request 'fix: workflow-authoring docs — type:object + const vs enum clarity (#123)' (#124) from fix/123-workflow-authoring-docs into main

xiaoju referenced this issue from a commit

2026-06-05 23:49:00 +00:00

fix: bootstrap — remind to restart session after skill install/update

xiaoju referenced this issue

2026-06-05 23:49:09 +00:00

fix: bootstrap — session restart hint + v0.2.1 migration note #125

xiaoju referenced this issue