文章目录一、JSON我们熟悉的完整对象二、JSONL行级独立的流式格式JSON vs JSONL 核心对比为什么 JSONL 特别适合流三、Agent 场景中的 JSONL 实战3.1 Streaming API一个请求多条返回3.2 工具调用追踪Agent 的黑匣子3.3 微调数据集Fine-tuning Data3.4 多 Agent 通信与消息队列3.5 日志聚合与可观测性四、设计取舍什么时候该用什么选 JSON 当选 JSONL 当一条实用原则五、一个小技巧在项目中同时使用两种格式一、JSON我们熟悉的完整对象JSONJavaScript Object Notation是过去二十年里最成功的数据交换格式。一个典型的 JSON 文档长这样{messages:[{role:user,content:你好},{role:assistant,content:你好有什么可以帮你的},{role:user,content:今天天气怎么样}],model:claude-fable-5,temperature:0.7}JSON 的核心特征完整、闭合、一次性解析。整个文件是一个合法的 JSON 值对象、数组、字符串等解析器必须读取全部内容才能得到完整的数据结构在内存中它就是一棵完整的树这对配置和请求-响应场景是天作之合——配置文件、API 请求体、一次性的结构化数据传递JSON 都是不二之选。但当一个 Agent 系统开始 “边跑边想、边说边做” 时JSON 的完整性约束反而成了瓶颈。二、JSONL行级独立的流式格式JSONLJSON Lines的规则简单得惊人一行一个合法的 JSON 对象行与行之间互不依赖。{type: tool_use, id: toolu_01, name: read_file, input: {path: config.yaml}} {type: tool_result, id: toolu_01, content: server: {port: 8080}} {type: thinking, content: 配置文件读取成功现在我需要解析端口号……} {type: text, content: 你的应用监听在 8080 端口。}JSON vs JSONL 核心对比维度JSONJSONL结构单个完整的 JSON 值每行一个独立 JSON 对象解析方式一次性全文解析逐行解析可流式处理追加写入需要重写整个文件append即可无需改写已有内容部分读取不行——不完整则非法可以随时截断不破坏前面的行内存占用与文件大小成正比只需当前行的内存合法性验证整体合法才算合法逐行合法坏行不影响好行典型场景API 请求/响应、配置文件流式输出、日志、数据集、Agent 消息流为什么 JSONL 特别适合流想象你在看直播弹幕——你不会等主播下播后才一次性收到所有弹幕而是来一条看一条。Agent 的思考过程和工具调用也是如此用户不应该等 Agent 完全跑完才看到结果而应该实时看到每一步推理和行动。JSONL 就是为这种来一条消费一条的模式而生的。三、Agent 场景中的 JSONL 实战目前主流 AI Agent 系统对 JSONL 的使用已经渗透到几乎每一个环节。3.1 Streaming API一个请求多条返回当你调用 LLM 的 streaming API 时服务端返回的不是一个完整的 JSON 响应而是一系列Server-Sent Events每个 event 内部的数据就是一行事实上的 JSONL通常是data: {choices: [...]}的形式。OpenAI / Anthropic 的流式响应本质上就是 JSONLdata: {type: text, content: 我来} data: {type: text, content: 帮你} data: {type: text, content: 查一下。} data: {type: tool_use, name: search, input: {query: ...}} data: [DONE]没有 JSONL 会怎样那你只能等模型完整生成完毕后才能看到第一个字——用户体验回到拨号上网时代。3.2 工具调用追踪Agent 的黑匣子一个多步 Agent 的执行过程会产生大量事件type: thinking → 模型在思考 type: tool_use → 模型决定调用工具 type: tool_result → 工具返回结果 type: thinking → 模型分析工具结果 type: tool_use → 再次调用工具 type: text → 最终回复这些事件天然就是 JSONL——时间有序、独立可读、增量产生。每个事件带上timestamp和id整个 Agent 执行过程就有了完整的审计日志{ts: 2026-07-18T10:23:01.001Z, type: start, agent: research-agent, task: 调研竞品定价} {ts: 2026-07-18T10:23:01.500Z, type: tool_use, tool: web_search, input: {q: SaaS 定价策略 2026}} {ts: 2026-07-18T10:23:03.200Z, type: tool_result, tool: web_search, output: 3 条结果, tokens: 450} {ts: 2026-07-18T10:23:05.100Z, type: tool_use, tool: deep_read, input: {url: https://...}} {ts: 2026-07-18T10:23:08.300Z, type: tool_result, tool: deep_read, output: ...}有了这样的 JSONL 日志你可以重放从任意步骤重新执行 Agent审计快速 grep 所有tool_use事件看 Agent 调用了哪些外部服务统计流水线式分析延迟、Token 消耗、工具成功率——不需要加载整个日志到内存3.3 微调数据集Fine-tuning Data几乎所有主流 LLM 的微调数据格式都是 JSONL。以 OpenAI 的 fine-tuning 格式为例{messages: [{role: system, content: 你是客服助手}, {role: user, content: 如何退款}, {role: assistant, content: 您可以在订单页面点击...}]} {messages: [{role: system, content: 你是客服助手}, {role: user, content: 物流多久到}, {role: assistant, content: 顺丰发货通常 2-3 天}]}为什么是 JSONL 而不是一个巨大的 JSON 数组数据量大——一个 fine-tuning 数据集可能有几十万到几百万条单个 JSON 数组会撑爆内存和 IDE流式上传和验证——逐行校验一行格式错误不影响其他行Shuffle 和分片——可以用shuf file.jsonl | head -10000一行命令取子集增量追加——新数据直接追加不需要反序列化→合并→重新序列化3.4 多 Agent 通信与消息队列在复杂的多 Agent 系统中比如 Claude Code 的 workflow 模式不同 Agent 之间需要传递结构化消息。JSONL 文件作为轻量级消息队列非常实用# Agent A 写入任务 {event: task_dispatched, task_id: abc, handler: code-reviewer, payload: {...}} # Agent B 边处理边写结果 {event: review_started, task_id: abc} {event: finding, task_id: abc, severity: high, description: ...} {event: review_complete, task_id: abc, score: 0.85}为什么不用数据库对于开发调试阶段和轻量级编排JSONL 零依赖、零配置tail -f就是天然的消费者。生产环境当然要上 RabbitMQ / Kafka但 JSONL 在原型阶段不引入新基础设施的价值不可忽视。3.5 日志聚合与可观测性AI Agent 系统天然是异步、多步、长时运行的。JSONL 日志让其可视化变得简单# 统计今天各 Agent 的工具调用次数greptype:tool_useagent-2026-07-18.jsonl|jq-r.tool|sort|uniq-c|sort-rn# 找出所有报错的工具调用greptype:tool_erroragent.jsonl|jq{tool, error: .error, ts}# 统计 token 总消耗greptype:token_countagent.jsonl|jq.tokens|paste-sd|bcUnix 管线和jq的生态系统就是 JSONL 最好的处理工具——几千行、几万行、甚至百万行都可以用这套组合拳流式处理。四、设计取舍什么时候该用什么选 JSON 当API 的请求体和响应体一次性传递完整信息配置文件package.json、tsconfig.json、claude_settings.json需要在对象内部进行复杂嵌套和交叉引用的数据一次性导出/导入的场景数据量可控需要 schema 校验时——整体校验比逐行校验更符合预期“要么全对要么全错”选 JSONL 当流式输出——LLM 的 token-by-token 生成、Agent 的事件流大规模数据集——训练数据、评测数据、爬虫结果日志和审计追踪——Agent 执行过程、用户行为日志增量写入——需要频繁追加的时序数据管道处理——需要grep | jq | awk组合加工的文本流多进程协作——多个进程同时写同一个文件每行写入是原子的一条实用原则如果你的数据是一张快照——写完就不再变了——用 JSON。如果你的数据是一条河流——持续产生、增量消费、可能需要随时截断——用 JSONL。五、一个小技巧在项目中同时使用两种格式很多成熟项目是这样玩的project/ ├── config.json # 配置用 JSON一次性加载 ├── prompts/ │ └── system.jsonl # 提示词模板用 JSONL逐条复用 ├── data/ │ ├── train.jsonl # 训练数据50万条JSONL │ └── test.jsonl # 测试数据1万条JSONL ├── logs/ │ └── agent-2026-07-18.jsonl # 运行时日志JSONL └── results/ └── eval_report.json # 评估报告用 JSON方便阅读规则就是输出的消费者是谁就选适合它的格式。人类阅读的报告 → JSON或直接 Markdown机器逐行消费 → JSONL一次性加载的元数据 → JSON
