yaml

@json-render/yaml

适用于 @json-render/core 的 YAML 线格式。通过流式 YAML 实现渐进式渲染和精准编辑。

核心概念

• YAML 线格式：JSONL 的替代格式，使用代码围栏（yaml-spec、yaml-edit、yaml-patch、diff）
• 流式解析器：增量解析 YAML，通过差异比较发出 JSON Patch 操作
• 编辑模式：Patch（RFC 6902）、merge（RFC 7396）和 unified diff
• AI SDK 转换器：将 YAML 围栏转换为 json-render patches 的 TransformStream

生成 YAML 提示词

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 转换器

使用 pipeYamlRender 替代 pipeJsonRender：

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 });

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

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

转换器可识别四种围栏类型：

• yaml-spec — 完整 spec，按行渐进式解析
• yaml-edit — 与当前 spec 进行深度合并的部分 YAML（RFC 7396）
• yaml-patch — RFC 6902 JSON Patch 行；应用于工作中的 spec，因此后续的 yaml-edit 围栏可以看到它们
• diff — 将统一差异应用于序列化后的 spec

流式解析器（底层）

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?)

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

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

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(),
});

围栏常量

自定义解析时，请使用导出的常量：

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";

主要导出项

导出项	描述
yamlPrompt	根据目录生成 YAML 系统提示词
createYamlTransform	用于 YAML 围栏的 AI SDK TransformStream
pipeYamlRender	便捷的 pipe 封装（替代 pipeJsonRender）
createYamlStreamCompiler	支持发出 patch 的流式 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 深度合并