boltArtifact 协议详解

📚 学习目标

学完这篇文章后，你将能够：

• 理解为什么 bolt.new 选择 XML 标签而非 JSON 进行流式传输
• 掌握 boltArtifact 和 boltAction 的结构规范
• 学习如何编写 System Prompt 来让 LLM 稳定输出此协议

前置知识

在开始学习之前，建议先阅读：

• 01-streaming

1️⃣ 什么是 boltArtifact?

boltArtifact 是 bolt.new 项目设计的一套 XML 风格协议。它允许 AI 在生成文本的过程中，嵌入结构化的文件操作指令。

<boltArtifact id="my-project" title="My App">
  <boltAction type="file" filePath="package.json">
    { "name": "my-app" }
  </boltAction>
  <boltAction type="shell">
    npm install
  </boltAction>
</boltArtifact>

思考：为什么不用 JSON？ JSON 必须等待闭合 } 才能解析完整对象，或者需要复杂的流式 JSON 解析器。而 XML 标签（如 <boltAction>）天然适合流式处理——检测到开标签就开始，检测到闭标签就结束。

2️⃣ 协议规范

<boltArtifact>

容器标签，代表一个完整的项目或变更集。

• id: 唯一标识符 (kebab-case)。
• title: 人类可读标题。

<boltAction>

具体的原子操作。

type="file"

创建或覆盖文件。

• filePath: 相对路径。
• 内容: 标签内部的文本即为文件内容。

type="shell"

执行 Shell 命令。

• 内容: 要执行的命令脚本。

3️⃣ Prompt 工程

让 LLM 稳定输出 XML 需要精心设计的 Prompt。

关键约束

1. 禁止占位符：// ...rest of code 是严格禁止的，必须输出完整代码。
2. 顺序：先创建文件，再运行 npm install。
3. 格式：不要用 Markdown 代码块包裹 XML，直接输出 XML。

You are Bolt.
Use <boltArtifact> tags to define the project structure.
Inside artifacts, use <boltAction type="file" filePath="..."> to create files.
Use <boltAction type="shell"> to run commands.

4️⃣ 解析器实现原理

前端使用状态机解析流式文本：

1. Idle: 等待 <boltArtifact。
2. Inside Artifact: 等待 <boltAction。
3. Inside Action: 累积字符到 buffer。
4. Action Close: 当遇到 </boltAction>，触发回调（如写入文件）。

这种设计使得用户在 LLM 还在打字时，就能看到文件树在实时构建。

💡 练习题

1. 设计题：你要在 boltArtifact 协议里增加一个新动作 type="patch"（用于对文件做增量 patch，而不是整体覆盖）。你会怎么设计属性？为什么？
2. 实现题：写一个最小解析器（状态机即可），输入是一段流式字符串，输出是解析后的 action 列表：{ type, filePath?, content }[]。
3. Prompt 题：写 5 条“约束句”，用来降低 LLM 输出不完整文件或输出占位符的概率。

📚 参考资源

项目与协议

• stackblitz/bolt.new

✅ 总结

本章要点：

• 流式友好：XML 标签比 JSON 更适合流式传输。
• 容错性：LLM 偶尔会有格式错误，XML 解析器通常比 JSON 解析器更容易实现容错（只提取标签间的内容）。
• 用户体验：结合 WebContainer，实现了"边写代码边预览"的极致体验。

下一步：如何设计你自己的渲染协议？继续学习：自定义渲染协议。