yaml

@json-render/yaml

@json-render/core 用の YAML ワイヤ形式です。YAML ストリーミングによる段階的なレンダリングと外科的な編集を実現します。

主な概念

• YAML ワイヤ形式：コードフェンス（yaml-spec、yaml-edit、yaml-patch、diff）を使用する、JSONL の代替形式です
• ストリーミングパーサー：YAML を段階的に解析し、差分計算によって JSON Patch 操作を出力します
• 編集モード：Patch（RFC 6902）、merge（RFC 7396）、unified diff です
• AI SDK 変換：YAML フェンスを json-render パッチに変換する 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（string）— カスタムのシステムメッセージの導入文
• mode（"standalone" | "inline"）— 出力モード。デフォルトは "standalone" です
• customRules（string[]）— プロンプトに追加するルール
• editModes（EditMode[]）— 説明する編集モード。デフォルトは ["merge"] です

AI SDK 変換

pipeJsonRender の代わりに、pipeYamlRender をそのまま使用できます。

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

変換処理は、次の 4 種類のフェンスを認識します。

• yaml-spec — spec 全体を行ごとに段階的に解析します
• yaml-edit — 部分的な YAML を現在の spec にディープマージします（RFC 7396）
• yaml-patch — RFC 6902 の JSON Patch 行です。作業中の spec に適用されるため、後続の yaml-edit フェンスからも反映済みの内容を参照できます
• diff — シリアライズされた spec に統合 diff を適用します

ストリーミングパーサー（低レベル）

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	パッチ出力に対応したストリーミング 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 のディープマージです