AI Agent 课程文档

切换日光/暗黑模式

041. AI 流式更新表单与点表示法 ​

学习目标 ​

这一节解释 AI 流式更新表单的底层原理。

学完后，你应该能理解：

  • 为什么后续很多功能都会用到流式更新表单；
  • 什么是点表示法；
  • AI 为什么要按固定格式返回字段路径和值；
  • 流式响应为什么需要 buffer；
  • 为什么要增量处理已经返回的行；
  • useBufferStreamHandler 负责什么；
  • setValueByPath 如何按路径写入表单数据。

先理解目标 ​

AI 流式更新表单的目标是：AI 一边生成，页面一边把结果填到表单里。

它不是等 AI 完整返回一个大 JSON，再一次性设置表单。

这种能力后面会用于：

  • AI 修改简历文案；
  • AI 填写表单；
  • AI 配置字段；
  • AI 生成结构化数据。

所以这里先讲通用原理。

让 AI 返回结构化文本 ​

AI 返回的数据要遵守固定格式。

格式里最重要的是字段路径。

例如：

txt
name=张三
basicInfo.0.label=电话
basicInfo.0.value=13800000000
workExperiences.1.company=某科技公司

这种写法叫点表示法。

它用字符串表达对象里的深层路径。

点表示法 ​

点表示法可以表示对象属性，也可以表示数组下标。

例如：

txt
person.title

表示：

ts
person.title

再例如：

txt
person.responsibilities.0

表示：

ts
person.responsibilities[0]

如果根节点本身是数组，也可以用 0.xxx 开头。

为什么提示词里要说“点表示法” ​

提示词里要明确告诉 AI：使用点表示法返回数据。

这个名字很重要。

如果只说“返回字段路径”，模型可能会输出各种格式。

明确说点表示法后，模型更容易按 a.b.0.c 这种规则生成。

前端也更容易解析。

流式响应是一段一段来的 ​

模型不是一次返回全部文本。

它会一段一段返回。

例如第一次返回：

txt
name=张

第二次返回：

txt
三
basic

第三次返回：

txt
Info.0.label=电话

单个片段可能是不完整的。

所以不能拿到一个 chunk 就立即按完整行解析。

buffer 的作用 ​

前端要维护一个 buffer。

每次收到新的文本片段，就追加进去：

ts
buffer += chunk;

然后从 buffer 里找完整行。

只有完整行才拿去解析。

还没完整的最后一段，要继续留在 buffer 里，等下一个 chunk 补齐。

为什么要删除已处理内容 ​

如果每次都从头解析整个 buffer，数据越多性能越差。

更好的方式是：

  1. 找出已经完整的行；
  2. 处理这些行；
  3. 从 buffer 里移除已处理部分；
  4. 保留未完成的尾巴。

这样每次只处理新增内容。

表单更新也只更新少量字段，性能更好。

增量更新表单 ​

每解析出一行，就得到一个路径和值。

例如：

txt
workExperiences.0.company=某公司

前端就可以把这个值写入表单对象对应路径。

这样用户能看到表单一点点被填充。

相比等整个 JSON 完整返回，流式体验会更好。

useBufferStreamHandler ​

项目会封装 useBufferStreamHandler。

它负责：

  • 接收流式 chunk；
  • 维护 buffer；
  • 找出完整行；
  • 解析路径和值；
  • 调用设置函数；
  • 保留未完成文本。

这样后续不同 AI 功能都能复用同一套流式解析逻辑。

parse ​

解析函数负责把一行文本拆成路径和值。

例如：

txt
basicInfo.0.value=13800000000

解析后得到：

  • path: basicInfo.0.value
  • value: 13800000000

如果格式不符合规则，就可以跳过或做容错。

setValueByPath ​

setValueByPath 负责根据点表示法路径写入对象。

例如路径是：

txt
person.responsibilities.0

它就要找到：

ts
data.person.responsibilities[0]

并把值写进去。

如果中间对象或数组不存在，还需要按路径创建。

为什么不直接 JSON.parse ​

如果等 AI 返回完整 JSON，再 JSON.parse，实现会简单一些。

但它有几个问题：

  • 必须等完整返回；
  • 中途无法更新 UI；
  • JSON 一旦格式错，整个解析失败；
  • 每次更新整个对象，性能可能更差。

点表示法配合流式解析，可以更早显示结果，也更容易做增量更新。

这一节的重点 ​

AI 流式更新表单的核心是：

  • 提示 AI 输出点表示法；
  • 前端用 buffer 接收流式文本；
  • 只处理完整行；
  • 已处理内容及时移除；
  • 按路径更新表单字段。

理解这套机制后，后面 AI 填表、AI 修改简历、AI 配置字段都会容易很多。

AI Agent 课程学习文档。

Copyright © 2026