yaml

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

@json-render/yaml

YAML wire format for

@json-render/core

. Progressive rendering and surgical edits via streaming YAML.

适用于

@json-render/core

的YAML有线格式。通过流式YAML实现渐进式渲染和精准编辑。

Key Concepts

核心概念

YAML wire format: Alternative to JSONL that uses code fences (
```
yaml-spec
```
,
```
yaml-edit
```
,
```
yaml-patch
```
,
```
diff
```
)
Streaming parser: Incrementally parses YAML, emits JSON Patch operations via diffing
Edit modes: Patch (RFC 6902), merge (RFC 7396), and unified diff
AI SDK transform:
```
TransformStream
```
that converts YAML fences into json-render patches

YAML有线格式：JSONL的替代方案，使用代码块（
```
yaml-spec
```
、
```
yaml-edit
```
、
```
yaml-patch
```
、
```
diff
```
）
流式解析器：增量解析YAML，通过对比差异生成JSON Patch操作
编辑模式：Patch（RFC 6902）、Merge（RFC 7396）和统一差异对比
AI SDK转换：将YAML代码块转换为json-render补丁的
```
TransformStream
```

Generating YAML Prompts

生成YAML提示词

typescript

import { yamlPrompt } from "@json-render/yaml";
import { catalog } from "./catalog";

// Standalone mode (LLM outputs only YAML)
const systemPrompt = yamlPrompt(catalog, {
  mode: "standalone",
  editModes: ["merge"],
  customRules: ["Always use dark theme"],
});

// Inline mode (LLM responds conversationally, wraps YAML in fences)
const chatPrompt = yamlPrompt(catalog, { mode: "inline" });

Options:

```
system
```
(string) — Custom system message intro
```
mode
```
("standalone" | "inline") — Output mode, default "standalone"
```
customRules
```
(string[]) — Additional rules appended to prompt
```
editModes
```
(EditMode[]) — Edit modes to document, default ["merge"]

typescript

import { yamlPrompt } from "@json-render/yaml";
import { catalog } from "./catalog";

// Standalone mode (LLM outputs only YAML)
const systemPrompt = yamlPrompt(catalog, {
  mode: "standalone",
  editModes: ["merge"],
  customRules: ["Always use dark theme"],
});

// Inline mode (LLM responds conversationally, wraps YAML in fences)
const chatPrompt = yamlPrompt(catalog, { mode: "inline" });

选项：

```
system
```
（字符串）——自定义系统消息引言
```
mode
```
（"standalone" | "inline"）——输出模式，默认值为"standalone"
```
customRules
```
（字符串数组）——附加到提示词的额外规则
```
editModes
```
（EditMode数组）——需要说明的编辑模式，默认值为["merge"]

AI SDK Transform

AI SDK转换

Use

pipeYamlRender

as a drop-in replacement for

pipeJsonRender

typescript

import { pipeYamlRender } from "@json-render/yaml";
import { createUIMessageStream, createUIMessageStreamResponse } from "ai";

const stream = createUIMessageStream({
  execute: async ({ writer }) => {
    writer.merge(pipeYamlRender(result.toUIMessageStream()));
  },
});
return createUIMessageStreamResponse({ stream });

For multi-turn edits, pass the previous spec:

typescript

pipeYamlRender(result.toUIMessageStream(), {
  previousSpec: currentSpec,
});

The transform recognizes four fence types:

```
yaml-spec
```
— Full spec, parsed progressively line-by-line
```
yaml-edit
```
— Partial YAML deep-merged with current spec (RFC 7396)
```
yaml-patch
```
— RFC 6902 JSON Patch lines
```
diff
```
— Unified diff applied to serialized spec

使用

pipeYamlRender

作为

pipeJsonRender

的直接替代方案：

typescript

import { pipeYamlRender } from "@json-render/yaml";
import { createUIMessageStream, createUIMessageStreamResponse } from "ai";

const stream = createUIMessageStream({
  execute: async ({ writer }) => {
    writer.merge(pipeYamlRender(result.toUIMessageStream()));
  },
});
return createUIMessageStreamResponse({ stream });

对于多轮编辑，传入之前的规范：

typescript

pipeYamlRender(result.toUIMessageStream(), {
  previousSpec: currentSpec,
});

该转换支持四种代码块类型：

```
yaml-spec
```
——完整规范，逐行渐进式解析
```
yaml-edit
```
——部分YAML与当前规范深度合并（RFC 7396）
```
yaml-patch
```
——RFC 6902 JSON Patch行
```
diff
```
——应用于序列化规范的统一差异对比

Streaming Parser (Low-Level)

流式解析器（底层）

typescript

import { createYamlStreamCompiler } from "@json-render/yaml";

const compiler = createYamlStreamCompiler<Spec>();

// Feed chunks as they arrive from any source
const { result, newPatches } = compiler.push("root: main\n");
compiler.push("elements:\n  main:\n    type: Card\n");

// Flush remaining data at end of stream
const { result: final } = compiler.flush();

// Reset for next stream (optionally with initial state)
compiler.reset({ root: "main", elements: {} });

Methods:

push(chunk)

flush()

getResult()

getPatches()

reset(initial?)

typescript

import { createYamlStreamCompiler } from "@json-render/yaml";

const compiler = createYamlStreamCompiler<Spec>();

// Feed chunks as they arrive from any source
const { result, newPatches } = compiler.push("root: main\n");
compiler.push("elements:\n  main:\n    type: Card\n");

// Flush remaining data at end of stream
const { result: final } = compiler.flush();

// Reset for next stream (optionally with initial state)
compiler.reset({ root: "main", elements: {} });

方法：

push(chunk)

、

flush()

、

getResult()

、

getPatches()

、

reset(initial?)

Edit Modes (from @json-render/core)

编辑模式（来自@json-render/core）

The YAML package uses the universal edit mode system from core:

typescript

import { buildEditInstructions, buildEditUserPrompt } from "@json-render/core";
import type { EditMode } from "@json-render/core";

// Generate edit instructions for YAML format
const instructions = buildEditInstructions({ modes: ["merge", "patch"] }, "yaml");

// Build user prompt with current spec context
const userPrompt = buildEditUserPrompt({
  prompt: "Change the title to Dashboard",
  currentSpec: spec,
  config: { modes: ["merge"] },
  format: "yaml",
  serializer: (s) => yamlStringify(s, { indent: 2 }).trimEnd(),
});

YAML包使用core中的通用编辑模式系统：

typescript

import { buildEditInstructions, buildEditUserPrompt } from "@json-render/core";
import type { EditMode } from "@json-render/core";

// Generate edit instructions for YAML format
const instructions = buildEditInstructions({ modes: ["merge", "patch"] }, "yaml");

// Build user prompt with current spec context
const userPrompt = buildEditUserPrompt({
  prompt: "Change the title to Dashboard",
  currentSpec: spec,
  config: { modes: ["merge"] },
  format: "yaml",
  serializer: (s) => yamlStringify(s, { indent: 2 }).trimEnd(),
});

Fence Constants

代码块常量

For custom parsing, use the exported constants:

typescript

import {
  YAML_SPEC_FENCE,   // "```yaml-spec"
  YAML_EDIT_FENCE,   // "```yaml-edit"
  YAML_PATCH_FENCE,  // "```yaml-patch"
  DIFF_FENCE,        // "```diff"
  FENCE_CLOSE,       // "```"
} from "@json-render/yaml";

对于自定义解析，使用导出的常量：

typescript

import {
  YAML_SPEC_FENCE,   // "```yaml-spec"
  YAML_EDIT_FENCE,   // "```yaml-edit"
  YAML_PATCH_FENCE,  // "```yaml-patch"
  DIFF_FENCE,        // "```diff"
  FENCE_CLOSE,       // "```"
} from "@json-render/yaml";

Key Exports

主要导出项

Export	Description
`yamlPrompt`	Generate YAML system prompt from catalog
`createYamlTransform`	AI SDK TransformStream for YAML fences
`pipeYamlRender`	Convenience pipe wrapper (replaces `pipeJsonRender` )
`createYamlStreamCompiler`	Streaming YAML parser with patch emission
`YAML_SPEC_FENCE`	Fence constant for yaml-spec
`YAML_EDIT_FENCE`	Fence constant for yaml-edit
`YAML_PATCH_FENCE`	Fence constant for yaml-patch
`DIFF_FENCE`	Fence constant for diff
`FENCE_CLOSE`	Fence close constant
`diffToPatches`	Re-export: object diff to JSON Patch
`deepMergeSpec`	Re-export: RFC 7396 deep merge

导出项	描述
`yamlPrompt`	从目录生成YAML系统提示词
`createYamlTransform`	用于YAML代码块的AI SDK TransformStream
`pipeYamlRender`	便捷的管道包装器（替代 `pipeJsonRender` ）
`createYamlStreamCompiler`	支持补丁生成的流式YAML解析器
`YAML_SPEC_FENCE`	yaml-spec对应的代码块常量
`YAML_EDIT_FENCE`	yaml-edit对应的代码块常量
`YAML_PATCH_FENCE`	yaml-patch对应的代码块常量
`DIFF_FENCE`	diff对应的代码块常量
`FENCE_CLOSE`	代码块结束标记常量
`diffToPatches`	重导出：对象差异转换为JSON Patch
`deepMergeSpec`	重导出：RFC 7396深度合并