企业官网建设流程全解析

带过几期英语训练营之后，我越来越觉得传统口语陪练产品的路子有个死穴：剧本是写死的。学员在机场问路，系统只会弹出“Excuse me, where is the gate?”——真实对话里的插话、口误、换说法，它全都不接。所以我给自己定了个新目标：从零到一开发一个英语情景教学Agent，不是又一个聊天机器人，而是能自己设计场景、控制对话难度、事后给反馈的智能陪练。这篇博客就是整个开发过程的完整复盘，包括架构选型、Prompt设计、代码实现，以及我在测试阶段踩过的那些坑。不管你是想给学生做口语陪练的老师，还是在研究AI Agent落地的开发者，这篇都值得看完。

1. 为什么是Agent，而不是普通App

1.1 传统学英语的核心痛点

传统英语学习软件最大的问题不在内容，而在“交互模型”。一套课程做出来，对话分支是有限的，用户就算猜到最完美的答案，也只是在预置的树状结构里走了一遍。真实的英语交流是什么样？对方会打断你、换词、开新话题，甚至故意装听不懂让你换个说法。这种动态性，传统软件根本无法覆盖。

我最早试过用关键词匹配来做情景对话：用户说“book a room”，系统就触发下一步。结果学员一旦说得稍微不标准，比如“I want, um, to reserve a hotel room”，关键词匹配直接就挂了。后来换成意图识别模型，情况好一点，但依然无法处理对话中的上下文连贯性——上一句还在问价格，下一句突然问早餐时间，传统NLU就把对话上下文丢了。

1.2 Agent形态带来的本质变化

Agent和传统规则系统最大的区别在于：LLM具备理解复杂上下文、自主生成教学内容的能力。这个特性改变了三件事：

一是对话不再是“走剧本”，而是“同一场景可以无限变化”。同一个机场问路场景，Agent能根据用户英语水平动态调整语速、词汇难度和对话深度。初学者它多给提示词，进阶用户它就故意制造信息差的干扰，比如突然说“Sorry, the counter is temporarily closed”。

二是反馈从“对错判断”变成了“能力面诊断”。传统系统只会告诉用户“正确/不正确”，Agent可以把用户的口语输出拆解成流利度、语法准确性、词汇丰富度、交互策略四个维度，还能针对每次的卡壳位置给出替代表达。

三是教学策略可以实时演变。用户昨天的弱点是现在完成时，Agent今天会在情景里故意多安排几个需要现在完成时的语境，这是传统教学内容预设机制做不到的。

1.3 这个项目适合哪些人参考

如果你是教育类产品的产品经理，想弄清楚Agent和传统应用程序的区别；如果你是一个独立开发者，想低成本验证一个AI应用的想法；或者你是一个英语老师，想让AI帮你做课后的情景陪练——这个项目都能给你一套可以直接上手的方案。

我会把整个项目拆成五层：需求设计、架构选型、Agent核心逻辑、前后端实现、迭代方向。这里面我不会刻意用花哨的Agent框架，而是先带着大家用经典的大模型API写一套最小实现，理解原理之后，再看怎么往工程化方向演进。

2. 整体架构设计与技术选型

2.1 先画出数据闭环

动工之前，我给自己定了三个原则：对话数据可回放、用户画像可累积、反馈结果可量化。围绕这三个原则，整个系统的数据闭环是这样设计的：

用户语音 → 语音识别STT → 对话管理Agent → 情景策略调整 → 语音合成TTS → 用户 ↓ 对话记录持久化 → 能力评估模型 → 下一次情景定制

核心数据流并不复杂，复杂的是对话管理这一环。它不是简单地把用户的话丢给LLM拿回一个回复，而是要结合当前情景剧本、用户长期画像、最近几轮对话状态，决定：纵容这段对话继续、插入教学提示、还是切换对话场景。

2.2 LLM选型：API优先还是本地模型优先

这个选择题我纠结最久。市面上可选方案大致分三类：

我的最终决定是：MVP阶段直接用在线API，原因很朴素——教学Agent的核心能力是“对话质量”，对话质量取决于模型本身的理解能力。在模型效果无法保证的前提下，花大量精力做Prompt优化和系统设计，最终效果也不会好。

等架构跑通了，再考虑用蒸馏方案把高频场景压到本地小模型。这里有个小经验：英语情景对话对模型的多轮上下文能力要求很高，很多开源模型前三轮还行，到第五六轮就开始重复提问或丢失角色约束。选型时不要只看榜单分数，要做“十轮对话压力测试”。

2.3 语音链路：STT + TTS的取舍

英语口语教学Agent里，语音链路比文字消息更重要。我试过三条路线：

第一条路线是云端串联模式。用讯飞或阿里的语音识别做STT，识别结果给LLM处理，LLM回复文本再交给TTS合成语音。优点是用到各家最成熟的模块，每个环节都稳定。缺点是中间多了两跳网络延迟，对话节奏会慢半拍。

第二条路线是端到端实时语音模型。OpenAI的Realtime API把STT和LLM合成在一个模型里，延迟很低，但价格偏贵，且只能配合特定客户端SDK。我评估后认为当前阶段不划算。

第三条路线是第一轮识别用流式STT，但把“确认——纠错”环节交给Agent本身。简单说，不追求语音识别一次到位，而是允许用户在语音输入后看到识别文本，自己改一遍再发送。这个方案只有教育场景敢用，因为学习者在对话里本来就是需要“看到自己的话被改过来”的。

最终我的选择是：第一版本先用本地WebSocket接入ASR，准确率和速度平衡；TTS使用Edge系列或OpenTTS类服务，因为教学场景需要发音清晰、语速可调，而且音色不能太机械。

2.4 会话管理与双记忆体系

情景教学Agent最本质的问题，是要记住两件不同类型的事：

一件事是“当前这节情景课进行到哪了”。用户在A机场柜台问完航班，现在想找登机口，Agent必须知道这个问题属于当前情景的哪个阶段，才能决定是直接回答还是接着扮演地勤人员。

另一件事是“这个学习者往期的水平怎么样”。用户上次课里最容易犯的语法错误是什么，昨天刚练过餐厅点餐，今天就不该让他在咖啡厅场景里反复练同样的句型。

为了解决这个问题，我设计了双记忆体系：用短期记忆存储当前会话状态，用长期记忆持久化用户画像。短期记忆我直接塞在Prompt上下文里，长期记忆则用结构化字段记录在数据库里。在架构演进阶段，还可以把长期记忆升级成向量数据库检索，但对口述项目来说，结构化记录已经够用。

3. 核心模块落地：从Prompt工程到情景剧本

3.1 Prompt设计：让模型扮演角色而不出戏

写Prompt前必须想清楚一个事情：教学Agent不是“让模型回复正确答案”，而是“让模型同时理解三件事——练习目标、剧情推进、用户意图识别”。

我第一版Prompt写得一团糟，把角色、规则、例子全部混在一段里，结果是模型动不动就跳出角色，变成百科问答。后来我总结出一个相对稳定的结构：

# 角色设定 你叫Karen，是一名洛杉矶机场地勤人员。你在值机柜台工作了8年。 你会根据用户的英语水平调整语速和用词，但绝不主动脱离角色。 # 教学指令 1. 每次对话前，先判断用户的整句输出是否符合当前教学目标； 2. 如果用户卡顿超过2秒，给一个提示词（不是答案）； 3. 如果用户说出与当前情景无关的话题，礼貌地引导回情景； 4. 如果用户出现高频语法错误（如时态), 在对话中自然重复正确表达。 # 剧情进度控制（当前节点：3/5，用户已办理值机，下一节点：询问登机口） # 若上一节点任务完成度高，则在回答末尾给出半开放式追问； # 若任务完成度不足，则主动重复上一节点核心话题。 # 输出格式 使用对话文本 + 辅助标签，标签只给系统看，包括： <intent>, <skill_eval>, <should_end>, <difficulty_adjust>

关键奥秘在两处。第一，剧情进度控制不要靠“请记住剧情”这种软性要求，而是把状态直接结构化放在Prompt里，每次对话后由代码更新再塞回去。第二，<skill_eval>这种隐藏标签让模型输出的内容可以程序化解析，我可以知道模型自己判断的教学意图。

3.2 情景剧本的数据结构

一开始我把情景剧本设计成纯粹的文本：“场景是机场，目标是练习现在完成时”。后来发现完全没法用，因为没有节点控制，模型第一轮可能就把整个流程走完了。

我把它改成了基于节点的JSON结构：

{ "scenario_id": "airport_checkin_01", "title": "机场值机——超重行李处理", "target_skills": ["conditional_sentences", "polite_request"], "start_node": "at_counter", "nodes": [ { "id": "at_counter", "role": "agent", "script": "Good morning. May I see your passport and ticket?", "expected_user_actions": ["greeting", "present_passport"], "follow_up_nodes": { "direct": "baggage_check", "need_help": "help_explain" } }, { "id": "baggage_check", "role": "agent", "script": "Your suitcase is 24kg. The allowance is 23kg. A slight overweight.", "expected_user_actions": ["ask_solution", "pay_fee"], "follow_up_nodes": { "direct": "boarding_pass_issue", "ask_exemption": "explain_policy" } } ] }

这个结构的好处：Agent在该节点时，可以判断用户的response是否命中expected_user_actions，据此选择下一步，智能处理没有完全命中规则时的情况。

我自己编写了一套简单的规则匹配器，加上适合教学场景的意图识别。这套混合机制比纯规则灵活，比纯LLM可控，实际效果出乎意料地好。

3.3 教学反馈的生成逻辑

很多开发者会把“对话回复”和“学习反馈”混在一起，这是大忌。对话过程中你应该让学习者沉浸在情景里，误判用户的完整表达。一旦每个回合都插入“这里你该说过去式”，体验就会变得像审讯一样。

我把它们拆成两个通道：对话回应用户面对面内容，反馈在每个任务节点结束、或整段会话结束后输出。

对话中： Agent: If your suitcase is overweight, you can either pay the extra fee or repack. What would you like to do? 对话后（节点结束）： feedback: { "fluency": 72, "grammar_hits": ["I've already bought two souvenir" -> "I've already bought two souvenirs"], "vocabulary_richness": "medium", "interaction_strategy": "基本能保持对话推进，但主动提问偏少", "suggestions": [ "尝试用'What if...'提出假设性问题", "把'weight'相关的同义表达练习一遍：the scale, the limit, exceed" ] }

为了把流利度、覆盖率这些指标算出来，我在后端写了一个打分模块，综合参考用户自己的ASR识别结果、Agent记录的错误标志、用户整个会话中的字数占比，得到量化的四维反馈。这个模块不能全信LLM输出，一定要有自己的统计逻辑。

4. 实操：一个最小可运行的Agent

4.1 环境准备与依赖安装

我建议从头开始做一个小Demo，不要上来就引一堆Agent框架。项目目录结构如下：

english-agent/ ├── agent/ │ ├── core.py # 对话核心逻辑 │ ├── scenario.py # 情景剧本加载 │ ├── memory.py # 双记忆管理 │ ├── feedback.py # 反馈生成 │ ├── stt.py # 语音识别封装 │ └── tts.py # 语音合成封装 ├── data/ │ └── scenarios/ │ └── airport.json ├── web/ │ └── app.py # 简单Web界面 └── requirements.txt

运行环境我用的Python 3.10。依赖库尽量精简，核心就三个大的：openai（或其他兼容OpenAI协议的SDK），fastapi（提供Web服务），uvicorn（启动服务）。如果想做语音输入，再加一个websocket库。

创建虚拟环境并安装依赖：

python -m venv venv source venv/bin/activate pip install openai fastapi uvicorn pydantic python-multipart

整个过程在Mac和Windows上都验证过，Windows上如果遇到音频编码问题，建议装FFmpeg并配置环境变量，否则TTS合成的音频文件可能无法正常在浏览器里播放。

4.2 核心代码：对话状态机

这里我先写一个基础版本，用OpenAI兼容接口，并演示如何将LLM回复、情景剧本节点、短期记忆三者结合起来完成整个对话流程。

初始化部分：

from openai import OpenAI import json client = OpenAI( api_key="your_api_key", base_url="your_compatible_endpoint" ) class SceneAgent: def __init__(self, scenario_json): self.scenario = json.load(open(scenario_json, encoding="utf-8")) self.current_node_id = self.scenario["start_node"] self.short_memory = [] self.user_profile = {} self.finished = False def _get_current_node(self): for node in self.scenario["nodes"]: if node["id"] == self.current_node_id: return node return None

核心生成逻辑：

def build_messages(self, user_text): node = self._get_current_node() system_prompt = f""" 你是一个英语情景教学Agent，当前场景：{self.scenario['title']} 你的身份是场景中的角色，你正在与一个英语学习者对话。 当前情景节点ID：{node['id']} 当前节点目标技能：{self.scenario['target_skills']} 如果学习者表达困难，可以用<help>标签提示，但不要直接替他说完整句子。 如果学习者已达成节点目标，回复末尾加上<next>标签。 """ messages = [{"role": "system", "content": system_prompt}] for m in self.short_memory[-8:]: messages.append(m) messages.append({"role": "user", "content": user_text}) return messages def step(self, user_text): messages = self.build_messages(user_text) resp = client.chat.completions.create( model="your-model", messages=messages, temperature=0.7 ) agent_text = resp.choices[0].message.content self.short_memory.append({"role": "user", "content": user_text}) self.short_memory.append({"role": "assistant", "content": agent_text}) return agent_text

这里有个细节：short_memory只保留最近8轮，超过的压缩成摘要。原因后面第5节细说。

4.3 节点跳转与Completion逻辑

光靠LLM自由发挥不行，我用了一种轻量策略：让模型输出特殊标记，程序读取标记决定节点跳转。这不是把所有对话都交给状态机，而是把对话的“驾驶权”保留在程序里。

import re def step_with_control(self, user_text): node = self._get_current_node() agent_text = self.step(user_text) # 检测是否完成当前节点 if "<next>" in agent_text: follow_up = node["follow_up_nodes"]["direct"] self.current_node_id = follow_up self.short_memory.append({"role": "assistant", "content": "==== 节点切换 ===="}) return agent_text # 检测是否需要降级提示 if "<help>" in agent_text: return self._generate_help_hint() return agent_text

为了实现“是否达成节点目标”的判断，我在Prompt里要求模型在重新表达用户意图后给一次思考过程，并输出{"node_done": true/false}的JSON标签。程序解析标签，再决定是否跳转。

比如用户在前台说了一串很流利的请求，但漏掉了“出示护照”这个关键动作，模型会给node_done: false，Agent就会继续留在当前节点用不同的追问方式引导。这样一来，模型负责理解和表达，程序负责节奏掌控。

4.4 语音链路的接入

语音接入是整个Agent里最容易让人放弃的一环。我尝试了两种方式：

方式一：浏览器录音 → 上传到后端 → 后端的ASR识别 → 识别文本传给Agent → 回复文本发到前端 → 前端用TTS接口合成。这种链路最适合轻量Demo，延迟稍高但稳定。

方式二：浏览器里直接跑Whisper或其他模型的Web版本。这种方式省服务器资源，但浏览器的麦克风权限策略、模型加载时间和不同浏览器的兼容性都很麻烦，Mobile Safari上的表现更是灾难。

我最终选了方式一，因为教学场景对低延迟的容忍度其实比对准确率低很多。一个口语学习者，哪怕你返回速度慢一秒，他也不会太在意，但如果识别结果错得离谱，他会立刻对系统失去信任。

STT段我直接参考了云厂商的流式语音识别接口。这里给一个后端伪代码结构：

async def transcribe_audio(audio_base64): # 这里调用你选择的ASR服务 result = await asr_client.recognize( audio_data=audio_base64, language="en-US", enable_intermediate=True ) # 如果置信度低于0.7，标记uncertain，让Agent做提示 return { "text": result.text, "confidence": result.confidence }

TTS我会选择支持SSML的引擎，因为教学场景需要让系统输出更自然的停顿，例如“Could you say it again differently?pausemsMaybe try 'I would like to...'”。SSML里可控的pausems参数对学习者帮助非常大，比单纯调整语速更有效。

4.5 让Agent记住学习者

Student Profile模块我用了比较轻量的个性化：

class StudentProfile: def __init__(self, user_id): self.user_id = user_id # 重复错误：例如 {"past_tense_irregular": 3, "singular_plural": 2} self.error_frequency = {} self.common_level = "B1" self.interested_topics = [] def record_errors(self, feedback_segment): # 遍历反馈里的grammar_hits，统计错误类型 for e in feedback_segment["grammar_hits"]: tag = e["error_type"] self.error_frequency[tag] = self.error_frequency.get(tag, 0) + 1

有了档案，Prompt的组装方式就要相应调整。如果用户高频错误是“可数名词单复数”，在生成下一次对话时，我会刻意让Agent在回复里多说复数句子，让用户在听力输入里先建立感知。这个设计教学领域叫“input flood”。

4.6 前端与可观察性

前端我用的Streamlit，不是因为它是最好的选择，而是开发效率极高，适合这类型的重交互原型。整体界面分三块：

• 左侧是对话聊天窗口，像微信一样展示双方气泡。
• 右上角是当前情景节点指示器，显示“值机柜台/行李检查/登机牌打印”。
• 右下角是实时技能诊断面板，展示每个节点的评分情况。

实际操作中我发现，学习者最关注“我刚说的这句话，错误在哪”。所以我在聊天窗口里把每句话的ASR识别文本显示出来，让用户看到系统理解的内容是什么。这个设计虽然简单，但对口语教学特别关键——用户需要知道自己说得对不对，才有方向改进。

5. 常见问题与排查技巧实录

5.1 LLM角色越界：一不留神就开始科普

这几乎是所有Agent项目的通病。我第一版测试时，用户只说了句“I am tired”，我的Agent立刻跳出情景开始长篇大论科普睡眠的好处，看得我哭笑不得。

排查思路是这样的：先把Prompt的role设定从“普通描述”改为“硬性命令”。比如从“你是一个地勤人员”改成“你必须始终扮演地勤人员。除非用户明确说结束情景，否则任何新话题都由你用地勤人员的口吻重新引导到机场场景”。加了“必须”和“否则”之后，效果立刻改善了很多。

如果还是不听话，就在推理参数上动手：OpenAI客户端里temperature从0.8降到0.3，但这会导致对话变得无聊、重复。我更推荐的是在请求时加response_format之类的约束，让模型输出必须带情景标签，这样角色不贴合的几率就低很多。

5.2 剧情推进太快：用户一句话，模型把整个戏演完

脚本的下一个节点还没到，模型就已经把登机牌给用户打好了。这是我在情景Agent里遇到的第二个高发bug。

解决方案是把剧情的“进度变量”彻底从Prompt里抽离，改用程序变量。只要模型看到current_node_id是at_counter，它就只能围绕这个节点展开。即使它想推进剧情，我这边只要检测到它生成了过于超前的信息，就用一个过滤函数把回复拦截下来：

def guard_node_response(node, agent_response, next_node): # 如果回复中出现了下一个节点才应出现的实体词，则禁止触发<next> disallowed_terms = next_node["script_entities"] for term in disallowed_terms: if term in agent_response: return agent_response.replace("<next>", "") return agent_response

这个Guard策略很土，但真实项目里它比任何复杂方案都稳定。依托规则判断语义，比依赖大模型自律更可控。

5.3 记忆膨胀：对话越来越慢，钱越烧越快

跑了20轮的对话，如果每次请求把全部历史都塞进Prompt，Token消耗越来越高，回答延迟也肉眼可见变长。这是所有Agent的共性问题。

解决方法我试过两种：滑窗摘要和关键记忆抽取。

对话进行到第10轮时，做一次中间摘要： “用户已经完成值机，正在询问行李超重问题，他的回答偶尔出现助动词遗漏。” 摘要存在short_memory里，后续请求只带摘要 + 最近6轮原始对话。

长期记忆则单独存在StudentProfile里，按“错误频次+兴趣标签”存结构化字段，每次请求只带Top3相关记忆。这样即使在长对话中，Prompt也能保持稳定。

5.4 并发不高？先别背框架的锅

很多开发者会在一开始考虑“我的Agent能扛多少并发”，实际是典型的过度设计。我在测试阶段用FastAPI异步接口单机跑，实测300个并发请求时，LLM API的响应就成了瓶颈——但这不影响Agent本身，因为真正耗时的环节都在外部API调用上。

如果你真的要在生产环境扛并发，我的建议是给LLM调用加一层异步队列，而不是把整个对话逻辑写得花里胡哨。用一个简单的内存队列或Redis队列做削峰，配合超时重试机制，效果比调整Python代码快得多。

还有一个容易被忽略的点：语音识别和TTS的高并发需要大量的音频转码资源。我建议把音频统一转成PCM或WAV 16k单声道，可以省下不少转码时间。音频格式不对导致ASR接口报错的问题，我在测试阶段遇到过不下五次。

5.5 用户乱说无关话题怎么办

情景教学Agent永远会遇到学习者脱离剧本的情况。我一开始的应对是用规则拦截：“请回到机场场景”。结果学员体验感很差，那种感觉像被老师点名拉回座位上。

后来我把方案改成“先接住，再自然拉回”。比如用户在机场柜台问“Can I bring my dog with me?”，Agent会先以航空地勤的身份回答宠物运输政策，再反问一句“By the way, do you need to check your suitcase first?”，这样既保留了对话的开放性，又没有让情景崩塌。也就是说，模型输出的内容就是自然的对话延伸，即使超出原剧本范围也是合法的，只要角色没有脱离场景即可。

6. 效果评估：什么才算“有效教学”

6.1 主观体验必须量化

Agent上线后，我最先做的是找14位不同水平的用户测试。每位用户跑3个场景，每个场景约10分钟。测试后我会收集两层数据：主观满意度问卷和客观表现评分。

客观评分这个环节，我会记录用户在对话里的平均字数、每分钟有效输出字数、语法错误频率、主动提问次数。这里有个有意思的发现：Agent是否给出“跟随式追问”，直接决定用户的开口时长。当Agent回复末尾附带上一个半开放问题时，用户下一轮的字数平均会增加三分之一。

另一个经验是：不要让Agent太“爱纠正”。我本来设计在每个节点结束后都给一份详细反馈，但实际使用中，如果每个节点都大段反馈，用户根本读不进去。后来改成只对“错误频率最高”的1-2个点进行深度点评，反而更有效。

6.2 Agent教学能力的边界

做了这么多轮测试，我想说句实在话：Agent只能做口语陪练，不能替代真正的老师。原因在于LLM的结构性缺陷——它对真实语言学习的策略性把握还不够。比如一个初学者连最基本的“Where is the restroom”都说不利索，Agent可能会给他安排一个机场转机的情景，完全没有意识到这个场景对他来说过难。

要让Agent有“教学定级”的能力，还得靠外部条件。我的方案是加入一个规则引擎：根据用户历史成绩和本次节点的平均表现，自动控制节点的“难度挡位”。

难度挡位 = 词汇复杂度 + 语速 + 干扰项数量 如果用户最近3场均分 < 60，难度挡位 = 基础 如果用户最近3场均分 60-80，难度挡位 = 中等 如果用户最近3场均分 > 80，难度挡位 = 进阶，此时加入时间压力和口语中的不确定信息

6.3 这个项目以后还可以怎么改

目前这个版本的核心五脏俱全，但还有三个值得扩展的方向。

方向一是引入“意图不确定性”判断。现在ASR置信度低时，Agent会直接把识别文本发给LLM，而LLM会根据错误文本生成答非所问的回复。正确做法是当ASR置信度低时，走专门的“澄清对话流程”，让用户重说一遍或换个说法。

方向二是把反馈从“文本报告”推进到“点击交互”。用户看到自己说错的地方，可以直接点击录音重说一遍，系统对比新旧输出，测出用户目前发音的准确度。

方向三是在教学情景里引入多模态素材。比如用户学“预订机票”，Agent可以推送一个真实的航空邮件或登机牌截图，让用户在认读真实材料的过程中完成练习。

这次开发，我收获最大的一点不是Agent技术本身，而是它让我对“教学交互”有了新的理解：真正的学习反馈，不是用户哪里错了，而是用户离“能自主表达”还缺哪一步。Agent要做的不是代替老师回答，而是替老师观察每一次“卡住”的瞬间，然后用正确的追问，帮学习者自己跨过去。

如果你也打算做一个情景类Agent，我的建议很简单：先把一个场景做透，做到你愿意拿它面对真实用户，再谈框架和扩展。这个过程中你会踩的坑，基本跟我上面写的差不多。希望这篇能让你少走几步弯路。