@json-render/yaml

@json-render/core 用の YAML ワイヤフォーマット。ストリーミング YAML を経由した段階的なレンダリングと外科的な編集。

重要な概念

• YAML ワイヤフォーマット: JSONL の代替として、コードフェンス (yaml-spec、yaml-edit、yaml-patch、diff) を使用
• ストリーミングパーサー: YAML を段階的に解析し、diffing 経由で 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";

// スタンドアロンモード (LLM は YAML のみを出力)
const systemPrompt = yamlPrompt(catalog, {
  mode: "standalone",
  editModes: ["merge"],
  customRules: ["Always use dark theme"],
});

// インラインモード (LLM が会話的に応答し、YAML をフェンスで囲む)
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 });

複数ターンの編集の場合、前のスペックを渡します:

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

トランスフォームは 4 つのフェンスタイプを認識します:

• yaml-spec — 完全なスペック、行ごとに段階的に解析
• yaml-edit — 部分的な YAML を現在のスペックと深くマージ (RFC 7396)
• yaml-patch — RFC 6902 JSON Patch 行
• diff — シリアル化されたスペックに適用される unified diff

ストリーミングパーサー (低レベル)

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

const compiler = createYamlStreamCompiler<Spec>();

// 任意のソースから到着するチャンクをフィード
const { result, newPatches } = compiler.push("root: main\n");
compiler.push("elements:\n  main:\n    type: Card\n");

// ストリーム終了時に残りのデータをフラッシュ
const { result: final } = compiler.flush();

// 次のストリーム用にリセット (オプションで初期状態付き)
compiler.reset({ root: "main", elements: {} });

メソッド: push(chunk)、flush()、getResult()、getPatches()、reset(initial?)

編集モード (@json-render/core から)

YAML パッケージはコアからの汎用編集モードシステムを使用します:

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

// YAML フォーマット用の編集命令を生成
const instructions = buildEditInstructions({ modes: ["merge", "patch"] }, "yaml");

// 現在のスペックコンテキスト付きユーザープロンプトを構築
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	便利なパイプラッパー (pipeJsonRender を置き換え)
createYamlStreamCompiler	パッチ発行を伴うストリーミング YAML パーサー
YAML_SPEC_FENCE	yaml-spec 用フェンス定数
YAML_EDIT_FENCE	yaml-edit 用フェンス定数
YAML_PATCH_FENCE	yaml-patch 用フェンス定数
DIFF_FENCE	diff 用フェンス定数
FENCE_CLOSE	フェンスクローズ定数
diffToPatches	再エクスポート: オブジェクト diff を JSON Patch へ
deepMergeSpec	再エクスポート: RFC 7396 深いマージ