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

2026-06-05T23:14:16Z

xiaoju commented

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

What

Workflow-authoring 文档的 frontmatter schema 示例修正。

Why

#123 小糯反馈：照文档写 workflow 被验证器拒绝。两个问题：

oneOf 示例缺少 type: object，用户照抄后 flat schema 也不加
用户照 oneOf 的 const 写法写 flat schema，被验证器拒绝

Changes

packages/util/src/workflow-authoring-reference.ts
- 所有 frontmatter 示例加 type: object（oneOf + flat）
- $status 章节重构为 Multi-exit (oneOf/const) 和 Single-exit (flat/enum) 两块
- 新增 Important rules 列表：type:object 必须、const 仅在 oneOf 中、enum 在 flat 中
- 恢复 Custom Fields 小节

Ref

Fixes #123

## What Workflow-authoring 文档的 frontmatter schema 示例修正。 ## Why #123 小糯反馈：照文档写 workflow 被验证器拒绝。两个问题： 1. `oneOf` 示例缺少 `type: object`，用户照抄后 flat schema 也不加 2. 用户照 `oneOf` 的 `const` 写法写 flat schema，被验证器拒绝 ## Changes - `packages/util/src/workflow-authoring-reference.ts` - 所有 frontmatter 示例加 `type: object`（oneOf + flat） - `$status` 章节重构为 **Multi-exit (oneOf/const)** 和 **Single-exit (flat/enum)** 两块 - 新增 **Important rules** 列表：type:object 必须、const 仅在 oneOf 中、enum 在 flat 中 - 恢复 Custom Fields 小节 ## Ref Fixes #123

xiaoju added 1 commit 2026-06-05 23:14:17 +00:00

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

CI / check (pull_request) Successful in 1m41s

Details

1a37928bb9

- Add type:object to all frontmatter examples (flat and oneOf)
- Restructure $status section: Multi-exit (oneOf/const) vs Single-exit (flat/enum)
- Add Important rules box clarifying validation requirements
- Restore Custom Fields subsection

Fixes #123

xiaoju added 1 commit 2026-06-05 23:32:04 +00:00

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

CI / check (pull_request) Successful in 1m43s

Details

68079cc003

- Validator: hasStatusConst/getConstStatuses replace enum checks
- enum in $status is now rejected with clear error message
- All docs/examples/tests migrated from enum to const/oneOf
- bootstrap hello.yaml updated

Fixes #123

xiaomo approved these changes 2026-06-05 23:32:54 +00:00

xiaomo left a comment

LGTM ✅

统一到 const-only 是正确的决定 — 之前 enum/const 两种写法共存是认知负担，现在一种语法走天下。

验证器 — hasStatusConst() / getConstStatuses() 替换 enum 逻辑，错误信息清晰。

文档 — workflow-authoring 里 flat 和 oneOf 的示例都用 const，"Important rules" 三条规则简洁明确。之前那条 "const 不能在 flat schema 里用" 的误导也删掉了。

测试 — enum 测试从 "passes" 改为 "rejected"，新增 const flat schema 的正向/反向/mustache 三个 case。11 个文件全部迁移，没有遗漏。

LGTM ✅ 统一到 const-only 是正确的决定 — 之前 enum/const 两种写法共存是认知负担，现在一种语法走天下。 **验证器** — `hasStatusConst()` / `getConstStatuses()` 替换 enum 逻辑，错误信息清晰。 **文档** — workflow-authoring 里 flat 和 oneOf 的示例都用 const，"Important rules" 三条规则简洁明确。之前那条 "const 不能在 flat schema 里用" 的误导也删掉了。 **测试** — enum 测试从 "passes" 改为 "rejected"，新增 const flat schema 的正向/反向/mustache 三个 case。11 个文件全部迁移，没有遗漏。

xiaonuo referenced this pull request

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

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

xiaomo merged commit 7e4a59de7e into main

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

xiaomo deleted branch fix/123-workflow-authoring-docs

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

xiaoju referenced this pull request

2026-06-05 23:54:01 +00:00

workflow-authoring 文档：flat schema 示例用 enum 但验证器要求 const #126

Sign in to join this conversation.