Codex+魔珐星云：我快速上线了一个具身教育陪读Agent

乌龟哥哥呀

83人浏览 · 2026-06-30 14:28:28

乌龟哥哥呀 · 2026-06-30 14:28:28 发布

引言

Codex 正在改变这类教育应用的开发节奏。过去搭一个教育助手，需要自己拆页面、写交互、接模型接口、调试前后端链路；现在借助 Codex，我可以更快检查数字人组件、讲解页面、Pinia Store、模型调用和详情页渲染逻辑，把项目骨架和联调问题快速推进。

但 Codex 解决的是“如何更快把功能做出来”，还没有直接解决终端交互体验的问题。教育 Agent 如果只是生成知识点、题目和解析，最后仍然是一段段文字，学生面对的还是阅读压力，而不是一个会讲、会停顿、会强调、能被打断的陪读老师。

这正是魔珐星云适合接入的地方。Codex 负责加速应用开发和问题定位，魔珐星云负责把大模型输出转化为数字人的表情、语音、动作和实时反馈，让教育助手从网页功能变成可看、可听、可打断的具身交互智能终端成品。

换句话说，Codex + 魔珐星云可以把开发链路从“写一个 Demo”推进到“快速上线一个可交互的终端应用”。这对教育陪读、讲题答疑、课堂辅助等场景尤其关键。

在我的 AI 教育助手项目里，这个组合变得非常具体。项目基于 Vue 3，能够按照学科、主题和难度生成知识点，也能生成选择题、填空题和解答题。为了让生成结果不只停留在页面上，我进一步接入魔珐星云数字人 SDK，让大模型生成讲解内容，再由具身 Agent 实时表达。

魔珐星云官网地址：魔珐星云官网

这篇文章不打算泛泛介绍数字人行业，而是从这个项目的真实改造过程出发，讨论五个问题：
Codex 如何加速教育 Agent 的项目搭建；
为什么纯文字教育 Agent 仍然缺少真实教学交互；
星云如何把模型输出变成数字人的实时表达；
一次“二次函数讲解”如何从静态页面升级为具身交互智能应用。

一、现有方案的问题：内容生成出来了，教学交互却没有发生

当前项目已经具备一条比较完整的 AI 内容生产链路。

在知识点生成页，用户选择语文、数学、英语、物理、化学或生物，输入主题并选择难度。前端通过兼容 OpenAI SDK 的模型接口发送提示词，请模型输出 Markdown 内容。

在试题生成页，用户还可以指定选择题、填空题或解答题。系统要求模型只返回 JSON，再将题干、选项、答案、解析和分值归一化为内部数据结构。

Plain Text 用户输入 → 学科 / 主题 / 难度 / 题型 → 大模型生成 → Pinia 保存上下文 → Markdown、KaTeX 或结构化试题页面展示

从功能角度看，这条链路已经可以使用；从教学体验看，它仍然存在四个明显问题。

1. 页面展示代替不了教师讲解

知识点详情页可以正确渲染 Markdown 和数学公式，试题详情页也能展示答案与解析，但“内容展示正确”不等于“学生已经理解”。

例如，大模型生成一篇关于二次函数的知识点，页面里可能包含定义、图像、顶点公式和例题。学生仍然需要自己判断：

哪个概念最重要；
公式中的参数分别影响什么；
当前例题应该先看条件还是先画图；
哪一步最容易出错。

真实教师会通过语气、停顿和重复组织这些信息。纯文本只能把内容交给用户，却无法主动引导用户的注意力。

2. 普通“文字转语音”仍然像播放器

一个常见改造思路是把整篇回答交给 TTS，然后在页面中播放音频。它确实减少了阅读负担，但交互仍然是单向的：

生成完整文本 → 合成完整音频 → 点击播放

用户需要等待内容与音频全部准备完成。播放过程中，系统也很难表达“正在思考”“开始回答”“本轮结束”等会话状态。它更像给文章增加了朗读按钮，而不是构建一个能够持续响应的 AI 教师。

3.传统数字人的核心问题，是高延迟、高成本与低并发

传统数字人并非只能播放预制视频，很多方案同样支持问答和实时交互。但真正进入业务场景后，影响体验的往往不是“能不能交互”，而是交互速度、运行成本和并发能力。

在当前项目中，知识点、题型和讲解难度都由用户临时指定，每次生成的内容都不同。用户发起请求后，系统需要依次完成模型内容生成、TTS 语音合成、口型与动作驱动以及画面输出。如果等待模型生成完整讲稿后再启动后续流程，各环节的耗时就会不断叠加，学生很容易在等待中失去耐心。

因此，数字人交互真正需要优化的是整条端到端链路：

用户发起讲解 → 模型生成首段内容 → 语音与动作同步驱动 → 数字人开始表达

只有首段内容能够快速输出，后续内容再以流式方式持续生成、合成和播放，数字人才会让用户产生“正在与我交流”的感觉。同时，它还需要根据会话状态支持暂停、打断和结束，而不是必须等待整段内容播放完成。

除此之外，实时语音、动作和画面驱动还会带来较高的计算成本。当多个用户同时发起讲解时，如何降低单次交互成本、提升系统并发能力，同样是数字人真正进入业务必须解决的问题。

二、单点技术的局限：LLM、TTS、渲染都不能独立完成具身交互

在接入星云之前，我先拆解了项目中的三个核心技术环节。

1. LLM 擅长组织知识，但没有表达身体

项目使用 OpenAI JavaScript SDK 调用兼容接口的模型服务。知识点生成时，我通过系统提示词约束模型扮演中学、高中教研专家；试题生成时，则要求模型按照严格 JSON 输出。

LLM 解决的是“说什么”：

生成知识结构；
控制题目难度；
给出答案和解析；
把书面内容改写为教师口吻。

但模型返回的仍然是 Token 流。它不知道页面里数字人的初始化状态，也不知道一段文本何时完成口型驱动，更不能单独提供视觉上的拟人反馈。

2. TTS 能生成声音，但声音不等于交互

如果只接 TTS，需要自己处理文本断句、音频流缓冲、播放队列、中断恢复以及音画同步。长文本还要考虑首包等待和后续音频是否连续。

在教育场景里，TTS 的问题不只是“能不能读出来”，还包括：

公式应该如何口语化；
Markdown 标记不能直接朗读；
题目选项之间需要停顿；
答案与解析需要不同语气；
用户暂停后，模型流和音频队列是否同时停止。

这些都属于对话编排，而不是一个 TTS 接口能够单独解决的问题。

3. 传统云端视频渲染链路偏重

如果每次回答都走完整的视频生成或云端画面渲染，成本、等待时间和并发压力都会比较高。对当前项目这种由用户即时触发的讲解任务来说，几秒甚至更长的准备时间会明显破坏交互感。

魔珐星云既非传统视频流方案载体，也不是操作系统，而是具身智能数字人开放平台。它通过自研端侧渲染与参数流架构，把形象渲染放到用户终端完成，服务端传输驱动数字人的轻量参数，从而降低传输和云端渲染负担。

在实时交互方案中，端到端约 500ms 的毫秒级响应是一个关键能力目标。对教育项目而言，这意味着模型首段内容到达后，数字人能够尽快接住并开始表达，而不是等待整篇讲稿生成结束。

这套方案关注的不是单独生成一段音频或视频，而是低延时、高并发、低成本、全兼容的连续具身交互。

三、解决方案：用星云打通模型、会话和数字人

与其只停留在“看数字人展示”的阶段，不如亲自完成一次接入，让自己的 AI 从只会生成答案，真正升级为能够表达、互动和服务用户的具身智能体。

对具身数字人开发感兴趣的开发者，可以前往魔珐星云官网体验相关能力，也可以进一步查看具身驱动 SDK、视频生成 API 和语音合成 API，尝试将数字人接入自己的 Agent、应用或业务终端。

接入星云后，我把系统划分成四层。

业务交互层：学科、主题、难度、题型、开始/暂停
↓
Agent 编排层：上下文、提示词、状态机、分句、队列
↓
模型与知识层：LLM、教材知识、题库、Markdown/JSON
↓
星云具身表达层：SDK 会话、TTS、参数流、端侧渲染

1. 先把数字人封装成业务组件

项目在 DigitalHuman.vue 中创建 XmovAvatar 实例。数字人的挂载容器、应用信息和网关地址都集中在组件内部，页面只需要调用初始化、说话和断开三个方法。

在这里插入图片描述

组件再通过 defineExpose 向讲解页提供统一接口：

JavaScript defineExpose({ initDigitalHuman, disconnect, speak })

这样做之后，星云 SDK 不会散落在知识点、试题和详情页面中。未来即使增加英语口语教师、实验指导员或招生咨询角色，也可以复用同一套数字人基础组件。

2. 把书面知识改写为可说的内容

当前项目中的知识点可能包含 Markdown 标题、列表、代码块和 LaTeX 公式。这些内容适合页面阅读，却不能直接用于语音输出。

因此，点击“开始讲解”后，系统会再次调用大模型，并要求它以专业教师口吻改写内容，同时移除 Markdown 语法。

JavaScript const messages = [ { role: ‘system’, content: ‘你是一名熟悉中学和高中课程标准的资深教研专家。’ }, { role: ‘user’, content: 请以专业教师的口吻讲解以下内容，不要包含 Markdown 语法：${content} } ]

这一步很重要。页面稿和口播稿是两种不同内容产品。具身 Agent 不应该机械朗读页面，而应该对知识重新组织。

const avatar = new window.XmovAvatar({
  containerId: '#containerId',
  appId,
  appSecret,
  enableDebugger: false,
  gatewayServer
})

await avatar.init({
  onDownloadProgress: progress => {
    console.log(`初始化进度: ${progress}%`)
  },
  onMessage: message => {
    console.log('收到消息:', message)
  }
})

在这里插入图片描述

3. 让模型流直接进入数字人链路

项目已经使用 stream: true 获取模型增量输出，并将增量文本交给 speak()：

JavaScript const completion = await openai.chat.completions.create({  messages,  model,  stream: true }) let index = 0 for await (const part of completion) {  const delta = part.choices[0].delta.content  if (!delta) continue   await xmovHuman.value.speak(    delta,    index === 0,    false  )   index++ }

这让系统不必等待完整讲稿生成完成。模型产生内容后，数字人链路即可开始消费。

不过，当前实现仍然是原型：它直接按照模型增量调用 speak()。Token 可能只是单字或半句话，容易造成调用过碎。下一步应该增加语义缓冲层。

JavaScript let buffer = '' for await (const part of completion) {  buffer += part.choices[0].delta.content || ''   const sentences = splitCompletedSentences(buffer)  buffer = sentences.rest   for (const sentence of sentences.completed) {    speechQueue.enqueue(sentence)  } }

分句层可以在句号、问号、感叹号处切分，也可以设置最大字符阈值。数字人获得的是完整短句，声音和动作会比 Token 级输入更自然。

4. 用状态机管理“听、想、说、停”

当前页面只使用 isSpeaking 控制按钮，正式版本应该升级为完整状态机：

Plain Text idle → initializing → thinking → speaking → paused → completed → error

每次状态切换都要同时控制：

模型请求是否继续；
文本缓冲是否接收；
数字人播放队列是否消费；
开始和暂停按钮是否可用；
页面是否显示正在思考或正在讲解。

在这里插入图片描述

四、真实场景：一堂“二次函数”讲解如何升级为具身 Agent

为了验证这条链路，我选择了项目默认的数学场景：

Plain Text 学科：数学主题：二次函数难度：中等

第一步：生成可阅读的知识内容

用户提交表单后，模型生成包含二次函数定义、图像特征、顶点、对称轴和例题的 Markdown 内容。系统通过 Pinia 保存生成结果，再跳转到详情页。

详情页使用 Marked 渲染 Markdown，并在渲染前保护 $...$ 与 $...$ 公式，最后交给 KaTeX 显示。

此时，系统已经是一份合格的 AI 学习资料，但还不是 AI 教师。

在这里插入图片描述

第二步：从“文章”生成“讲稿”

学生点击数字人讲解后，系统读取同一条知识点上下文，让大模型把文章改写为口语化讲稿。

例如，页面上可能写着：

Plain Text 二次函数的一般形式为 y = ax² + bx + c，其中 a ≠ 0。

口播稿则可以改写为：

Plain Text 我们先抓住二次函数最基本的形式。大家注意，二次项系数 a 不能等于零；如果 a 等于零，它就会退化成一次函数。

模型负责把知识变成教学语言，数字人负责把教学语言变成可感知的表达。

在这里插入图片描述

第三步：数字人边接收边讲解

模型返回首段内容后，前端立即将文本送入星云数字人。星云通过参数流驱动端侧数字人渲染，学生在页面左侧看到 AI 讲师，右侧仍然保留完整知识点。

这种双通道设计是我认为当前项目最有价值的部分：

视觉通道保留公式和结构；
听觉通道负责解释和强调；
数字人形象提供持续的交互反馈；
用户可以暂停讲解，再回到原文核对。

与单纯播放 TTS 相比，数字人让“谁在讲”变得明确；与预制视频相比，本次讲解内容完全来自用户刚刚生成的知识点。

在这里插入图片描述

第四步：把同一套能力复用到试题解析

试题场景不需要重新搭建数字人系统，只需要更换讲解策略。

选择题可以按以下顺序组织：

题目背景 → 题干 → 逐项读出选项 → 公布正确答案 → 解释错误选项与关键依据

填空题重点解释答案来源；解答题则围绕审题、答题要点和推导过程展开。

当前项目已经为三类题型准备了不同文本结构，但还有一个需要修正的工程细节：generateExplanationText() 是异步函数，开始讲解时必须先 await 获取结果，否则试题分支的播放队列可能在内容准备完成前就被读取。


JavaScript const explanations = await generateExplanationText() if (!explanations.length) return

这类问题说明，具身 Agent 的难点不只在模型或数字人 SDK，也在多个异步系统之间的顺序控制。

在这里插入图片描述

五、SDK、API 与项目架构的实际落地方式

1. 当前项目技术栈

这次开发使用的主要技术包括：

层级	技术
前端框架	Vue 3 Composition API
构建工具	Vite 5
路由与状态	Vue Router、Pinia
模型调用	OpenAI JavaScript SDK 兼容接口、火山方舟推理端点
内容渲染	Marked、KaTeX
数字人	魔珐星云 XmovAvatar Web SDK
AI Coding	Codex，用于代码阅读、样式改造、问题定位与文档整理

在实际开发中，AI Coding 工具对这类跨模块项目很有帮助。我使用 Codex 同时检查了数字人组件、讲解页面、Pinia Store、模型调用和详情页渲染逻辑，并通过本地构建与浏览器检查验证修改结果。

但 AI Coding 只能加快阅读和实现，不能代替对异步链路与业务状态的判断。例如，模型流应该如何断句、暂停时应取消哪些任务、密钥应该放在哪里，仍然需要开发者明确系统边界。

2. SDK 接入应与业务解耦

我把星云 SDK 放在独立组件中，而不是直接写进讲解页面，原因有三点：

统一管理初始化和销毁；
避免重复创建数字人会话；
方便未来切换不同角色或讲解页面。

组件卸载时必须主动停止并销毁实例：

JavaScript const disconnect = () => {  const avatar = instance.value  if (!avatar) return   try { avatar.destroy?.() } catch {}   instance.value = null }