feat(workflow-util-agent): two-layer frontmatter safeguard — RFC #351 Phase 2 #353

2026-05-19T05:46:52Z

xiaoju commented

2026-05-19 05:46:52 +00:00

What

Adapter now tries frontmatter markdown first before falling back to LLM extract.

Why

RFC #351 Phase 2 — zero LLM cost when agent outputs valid frontmatter; safety net when it doesn't.

Changes

workflow-util-agent/src/create-agent-adapter.ts — tryFrontmatterMeta() + two-path logic
workflow-util-agent/__tests__/create-agent-adapter.test.ts — 5 tests (happy path + 3 fallback scenarios)
workflow-util/src/frontmatter-markdown/frontmatter-markdown.ts — JSDoc nit fix from #352 review

Flow

Agent returns raw string
tryFrontmatterMeta(raw, schema): parse → validate → safeParse
✅ Success → CAS stores body, return meta directly
❌ Fail → CAS stores full raw, runtime.extract() via LLM

Ref

Refs #351

## What Adapter now tries frontmatter markdown first before falling back to LLM extract. ## Why RFC #351 Phase 2 — zero LLM cost when agent outputs valid frontmatter; safety net when it doesn't. ## Changes - `workflow-util-agent/src/create-agent-adapter.ts` — `tryFrontmatterMeta()` + two-path logic - `workflow-util-agent/__tests__/create-agent-adapter.test.ts` — 5 tests (happy path + 3 fallback scenarios) - `workflow-util/src/frontmatter-markdown/frontmatter-markdown.ts` — JSDoc nit fix from #352 review ## Flow 1. Agent returns raw string 2. `tryFrontmatterMeta(raw, schema)`: parse → validate → safeParse 3. ✅ Success → CAS stores body, return meta directly 4. ❌ Fail → CAS stores full raw, `runtime.extract()` via LLM ## Ref Refs #351

xiaoju added 2 commits 2026-05-19 05:46:52 +00:00

docs: fix parseMinimalYaml JSDoc (nit from #352 review) 37c35560e9

Refs #351

feat(workflow-util-agent): two-layer frontmatter safeguard in adapter d5f47d1a18

Phase 2 of RFC #351 — adapter tries frontmatter first (zero LLM cost),
falls back to runtime.extract() when frontmatter is missing/invalid.

- tryFrontmatterMeta(): parse → validate → schema.safeParse
- Happy path stores body (no frontmatter) in CAS
- Fallback stores full raw in CAS + LLM extract
- 5 tests covering both paths

Refs #351

xiaomo approved these changes 2026-05-19 05:47:42 +00:00

xiaomo left a comment

LGTM ✅

亮点：

tryFrontmatterMeta 三步链路清晰：parse → validate → safeParse，任一步失败即回退
Happy path 零 LLM 开销，fallback 走原有 extract，向后兼容
测试覆盖了关键路径：happy path 不调 extract、无 frontmatter 调 extract、validation 失败回退、schema 不匹配回退
CAS 存 body 不存 frontmatter block，干净
顺手修了 Phase 1 的 JSDoc nit

细节确认：

putContentNodeWithRefs(runtime.cas, frontmatterResult.body, []) — happy path refs 传空数组，后续 Phase 如果 artifacts 需要映射到 refs 可以在这里扩展，当前设计合理

可以合并 🚀

LGTM ✅ **亮点：** - `tryFrontmatterMeta` 三步链路清晰：parse → validate → safeParse，任一步失败即回退 - Happy path 零 LLM 开销，fallback 走原有 extract，向后兼容 - 测试覆盖了关键路径：happy path 不调 extract、无 frontmatter 调 extract、validation 失败回退、schema 不匹配回退 - CAS 存 body 不存 frontmatter block，干净 - 顺手修了 Phase 1 的 JSDoc nit **细节确认：** - `putContentNodeWithRefs(runtime.cas, frontmatterResult.body, [])` — happy path refs 传空数组，后续 Phase 如果 artifacts 需要映射到 refs 可以在这里扩展，当前设计合理可以合并 🚀

xiaomo merged commit 4a4ddba9f6 into main

2026-05-19 05:47:47 +00:00

xiaomo referenced this issue from a commit

2026-05-19 05:47:47 +00:00

Merge pull request 'feat(workflow-util-agent): two-layer frontmatter safeguard — RFC #351 Phase 2' (#353) from feat/351-phase2-adapter-frontmatter into main

xiaoju referenced this pull request

2026-05-19 06:08:30 +00:00

feat: 将 RFC #351 frontmatter markdown 移植到 uwf-* 路径 #355

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: uncaged/workflow#353