@json-render/yaml 是 @json-render/core 的 YAML 线格式(wire format)包,目标是用流式 YAML 实现渐进式渲染与精确编辑。它是 JSONL 之外的一种替代方案。
【主要能力】
- YAML 线格式:相比 JSONL,使用代码围栏来承载规范,围栏类型包括 yaml-spec、yaml-edit、yaml-patch、diff。
- 流式解析器:以增量方式解析 YAML,并通过 diff 计算生成 JSON Patch 操作。
- 编辑模式:支持 patch(RFC 6902)、merge(RFC 7396)以及 unified diff。
- AI SDK Transform:提供 TransformStream,可将 YAML 围栏转换为 json-render 的补丁。
【生成 YAML 提示词】 通过 yamlPrompt 从 catalog 生成系统提示词,支持 standalone 模式(LLM 只输出 YAML)与 inline 模式(LLM 在对话中输出并以围栏包裹 YAML)。可配置项包括:system(自定义系统消息开头)、mode(输出模式,默认 standalone)、customRules(追加的额外规则)、editModes(需要记录的编辑模式,默认 ["merge"])。
【AI SDK Transform】 pipeYamlRender 可作为 pipeJsonRender 的直接替代。在多轮编辑时,可传入 previousSpec(前一份规范)。该 transform 识别四种围栏:yaml-spec(完整规范,逐行渐进解析)、yaml-edit(部分 YAML,与当前规范做 RFC 7396 深合并)、yaml-patch(RFC 6902 JSON Patch 行)、diff(作用于序列化规范的统一 diff)。
【流式解析器(低层)】 可通过 createYamlStreamCompiler 创建编译器,使用 push(chunk) 逐块输入、flush() 结束刷新、getResult()、getPatches() 获取结果与补丁,reset(initial?) 重置以用于下一轮流。
【编辑模式与提示词构建】 YAML 包使用 core 的通用编辑模式系统,可调用 buildEditInstructions 与 buildEditUserPrompt 生成编辑指令与用户提示词,format 传入 "yaml",并可传入序列化函数。
【围栏常量与主要导出】
导出的围栏常量包括 YAML_SPEC_FENCE("yaml-spec")、YAML_EDIT_FENCE("yaml-edit")、YAML_PATCH_FENCE("yaml-patch")、DIFF_FENCE("diff")、FENCE_CLOSE("```")。主要导出有:yamlPrompt(从 catalog 生成 YAML 系统提示词)、createYamlTransform(AI SDK TransformStream)、pipeYamlRender(便捷 pipe 包装,替代 pipeJsonRender)、createYamlStreamCompiler(带补丁输出的流式解析器)、上述围栏常量,以及重导出的 diffToPatches(对象 diff 转 JSON Patch)和 deepMergeSpec(RFC 7396 深合并)。
【适用场景】 适合需要在 AI 应用中边生成边渲染、并以 YAML 围栏承载规范或增量编辑指令的场景,也适合需要将流式输出转换为 json-render 补丁的集成开发。
【限制】 关于运行环境要求、版本兼容范围、性能指标等,资料暂未提供。