用Claude耗时两周、花费约800美元打造的《大唐长安》浏览器3D语音互动游戏教程 · AI HOT
Berryxia.AI@berryxia73
2026-06-01 11:35·31天前
AI 摘要本教程介绍了如何构建一个名为《大唐长安》的Web 3D互动项目。项目基于Three.js搭建低多边形风格的长安城沙盘，玩家可通过WASD模式在其中漫游探索。核心玩法包括与多种NPC进行语音对话、参与飞花令等诗词小游戏。项目集成了Agora实时语音能力，通过Agora Skills（技能）和Agora CLI工具完成Agent集成与环境配置，使玩家能通过麦克风与李白等角色实时语音交流。此外，项目还设计了将现代AI品牌融入游戏的唐风AI展馆。
Berryxia.AI@berryxia · X 2026-06-01 11:35·31天前
在 X 看原推· x.comAI 摘要本教程介绍了如何构建一个名为《大唐长安》的Web 3D互动项目。项目基于Three.js搭建低多边形风格的长安城沙盘，玩家可通过WASD模式在其中漫游探索。核心玩法包括与多种NPC进行语音对话、参与飞花令等诗词小游戏。项目集成了Agora实时语音能力，通过Agora Skills（技能）和Agora CLI工具完成Agent集成与环境配置，使玩家能通过麦克风与李白等角色实时语音交流。此外，项目还设计了将现代AI品牌融入游戏的唐风AI展馆。
每个角色有自己的头像、默认名字、初始钱包和物品。进入游戏后，玩家可以：
这一阶段真正完成了从"3D 页面"到"小游戏"的转变。
4. 第三阶段：让 NPC 不只是摆设
很多 3D 场景的问题是：建筑很漂亮，但里面没有生活。
所以我们给城市加了大量 NPC 和小游戏，让它变得有烟火气。
玩家靠近路人、文士、商贾、仕女、官员、僧人等 NPC，可以触发对话。不同 NPC 会有不同身份和口吻。
- 飞花令：给出一个关键字，玩家从诗句中选择含有该字的一句；
小游戏不是单纯为了"好玩"，而是让诗词和历史知识变成可参与的体验。
5. 第四阶段：做珍宝馆与诗画展厅
玩家可以进入不同展馆，欣赏诗画、珍宝和历史主题内容。例如：
展厅的作用是把"游戏"与"文化内容"连接起来：玩家既可以玩，也可以看展、听讲解、理解背后的历史语境。
6. 第五阶段：加入 AI 展馆
项目最特别的一部分，是我们把现代 AI 品牌做成了唐风展馆。
我们设计了一个"天枢府 / AI 展馆"概念：在盛唐长安里出现一个古今穿越的科技坊市。不同 AI 品牌不再只是 logo，而是变成一座座唐风殿宇，每个展馆都有自己的讲席和风格。
其中 Agora 馆作为核心语音互动展馆，承担了实时语音能力展示。
在游戏场景中，Agora 不只是一个外部服务名，而是被设计成一座可进入、可互动、可召唤智机使讲解的"Agora 馆"。这能帮助非技术用户理解：语音 AI 不只是后台 API，它可以成为一个场景化体验。
大唐长安出现了一座"智机府"，各路 AI 智机使在这里讲解不同的智能能力。
这样做的好处是：AI 展示不再像一个冷冰冰的产品页面，而是变成了玩家在游戏世界里能探索的一部分。
7. 第六阶段：接入实时语音 Agent
我们的目标不是让 NPC 弹出文字框，而是让玩家真的能用语音和角色交流。
7.0 开发前置：安装 Agora Skills / Agora CLI
在这个项目里，Agora 语音能力并不是直接把 App ID 写死在网页里，而是通过 Agora Skills + Agora CLI 完成项目登录、能力检查、环境变量写入和 ConvoAI 就绪检查。
Agora Skills 负责告诉 Agent 怎么集成 Agora；Agora CLI 负责登录账号、绑定项目、写入 .env.local。
层级作用谁来使用Agora Skills给 AI Coding Agent 的集成说明书，告诉 Agent 应该用官方 quickstart、怎么检查 ConvoAI、怎么处理 token 和环境变量Cursor / Claude / AgentAgora CLI真正执行登录、项目选择、能力检查、环境变量写入的命令行工具开发者和 Agent 都会用。
所以，"安装 Agora Skills"在实际复现时，通常会落到两件事：
- 确保你的 AI 开发环境已经有 Agora Skill / Agora 参考资料；
- 在本机安装并登录 agora CLI，让项目可以拿到有效的 Agora 项目配置。
第一步：确认是否已有 Agora Skill / Agora CLI
如果能输出路径和版本号，说明 CLI 已经进入你的 PATH。
如果终端能看到 Agora CLI install is healthy，说明 CLI 本身可用。
如果 agora 命令不存在，通常是 shell 没有加载新的 PATH。可以重开终端，或检查安装脚本输出里提示的 PATH 配置。
- 终端打印一个 https://sso2.agora.io/... 登录链接；
- 终端显示 Session stored 和 Status： authenticated。
如果这里显示未登录，重新执行 agora login。
如果登录成功但后面 agora project list 返回：
说明不是代码问题，而是 Agora 账号或控制台权限被限制。此时需要换一个可用账号，或先解除账号限制。
agora project use <project-id-or-name>
如果还没有项目，可以通过 Agora Console 创建，或用 CLI 初始化 quickstart 项目：
本项目是从 official quickstart 的思路继续改造的：先确保官方 demo 能跑，再把它嵌入到《大唐长安》的 3D 场景中。
实时语音 Agent 依赖 Agora 的 Conversational AI 能力。可以运行：
你希望看到的结果是 project doctor 没有 blocking issue。它不等于"语音一定已经通了"，但至少说明控制台项目配置层面准备好了。
注意：AGORA_APP_CERTIFICATE 是敏感信息，不要提交到 GitHub。项目的 .gitignore 已经忽略 .env.local。
写入后可以检查文件是否存在，但不要把证书贴到公开地方：
如果只是自查证书是否存在，可以看键名，不要打印完整值：
如果线上部署语音服务，可以通过 URL 参数指定：
？voiceOrigin=https://你的语音前端域名
如果返回 agent_id，说明后端成功请求 Agora 创建了一个语音 Agent。
最后打开游戏，进入 Agora 馆，点击右侧语音面板，观察三件事：
语音功能最终不是孤立存在的，它会和玩家身份、NPC、展馆、字幕、头像面板一起工作。玩家看见的是"角色在长安城里与智机使对话"，背后才是 RTC、ConvoAI 和 Agent 编排。
通常不是前端按钮坏了，而是 Agora 项目或凭据不可用。优先检查：
- agora project list 是否能正常列出项目；
- agora project doctor --feature convoai 是否通过；
- .env.local 里的 App ID / Certificate 是否来自同一个项目；
如果 CLI 登录正常，但 project list 返回 ACCOUNT_BLOCKED，说明账号侧被限制，代码无法绕过。需要换可用账号或解除 Agora 控制台限制。
- han-diorama 浏览器 3D 主场景 负责 Three.js、WASD、NPC、展馆、小游戏
- 负责 Agora ConvoAI、Persona、语音对话
主场景里点击 NPC 后，会打开右侧语音面板。这个面板本质上是一个嵌入的 iframe，它和主游戏通过 postMessage 通信。
玩家麦克风 ↓ 浏览器 RTC 上行 ↓ Agora 实时音频链路 ↓ ConvoAI：语音识别 → 大模型思考 → TTS 合成 ↓ AI 声音通过 RTC 回到浏览器 ↓ 游戏里 NPC 头像、字幕、状态同步变化
普通用户看到的是"我和李白说话了"。技术上背后是实时音频、语音识别、大模型、语音合成和游戏状态同步一起工作。
如果所有 NPC 都用同一个提示词，它们就会像同一个机器人。
- 智机使 · Agora 馆：讲解实时语音与 ConvoAI。
这让语音功能不只是"能说话"，而是和游戏世界绑定在一起。
8. 第七阶段：做角色头像、视频面板与 BGM
为了让语音互动更有"面对面"的感觉，我们做了左侧角色 portrait 面板。
- idle.jpg / idle.png 静态头像；
- 当玩家打开语音对话时，BGM 自动降低音量，避免盖住人声。
这一步看似是"包装"，但对用户体感影响很大。没有声音和头像时，AI 对话像工具；有了角色视频、字幕和背景音乐后，它更像游戏里的角色。
9. 第八阶段：解决视觉与尺度问题
开发中遇到过一个典型问题：AI 展馆一开始太大，放到城市里会出现"浮在地面上""镜头一转消失"的情况。
这个经验很重要：3D 项目里，美术好看不够，尺度一致才是可玩的前提。
10. 第九阶段：部署到 GitHub
项目完成后，我们把前端开源部署到了 GitHub。
前端 han-diorama 是静态 Web 项目，适合用 GitHub Pages 托管。
然后使用 GitHub Actions 自动发布 Pages。
https://andyhuo520.github.io/tang-changan/
- 实时语音后端 tang-voice-agent 需要单独部署；
- 本地开发时可以用 http://localhost:3000 作为语音 iframe；
- 线上如果要启用语音，需要给游戏传入可访问的语音前端地址。
11. 普通用户怎么体验
https://andyhuo520.github.io/tang-changan/
按键作用WASD移动鼠标调整视角E与 NPC 对话 / 触发小游戏F进入展馆 / 开店 / 触发场景Esc关闭语音面板
12. 开发者如何理解项目结构
han-diorama/ index.html 页面结构与 UI 容器 scene.js 主 3D 场景、游戏模式、NPC、语音面板 modelLoader.js 角色模型加载 assets/ logo、头像、BGM、预览图 portraits/ NPC 视频 / 头像素材 murals/ 画廊素材 lib/ content/brand-data.js AI 展馆品牌数据 world/brand-plaza.js AI 展馆 / 天枢府 world/gallery-hall.js 珍宝馆 / 展厅 world/diy-hall.js 丹青馆 DIY ui/voice-intent.js 语音意图路由 hero/ 大明宫、东西市、曲江等地标模块
tang-voice-agent/ web/ Next.js 语音前端 iframe server/ FastAPI 后端 server/src/personas/ 角色 Persona
3D 主项目负责"玩家在哪里、看见什么、能做什么"；语音子项目负责"玩家说什么、AI 怎么回答、声音怎么回来"。
13. 这次开发踩过的坑
浏览器会缓存 JS 和图片。我们在模块路径后面加版本参数：
scene.js？v=20260529-agora-only
实时语音不只是代码问题，还依赖 Agora 账号、项目状态、ConvoAI 开通状态和 token 鉴权。
CAN_NOT_GET_GATEWAY_SERVER： no active status 401 Invalid token
- App ID / Certificate 不匹配；
这是开发 AI 语音项目时最容易误判的地方：页面看起来是"麦克风开了"，但其实浏览器和 Agent 都没有真正加入频道。
展馆、城市、NPC、地面如果不在同一尺度体系里，就会出现漂浮、穿模、消失、点不到的问题。
解决办法不是不断调相机，而是回到世界坐标，统一单位、位置和可交互范围。
14. 如果你想复刻一个类似项目
- 确定主题 先选一个世界观，例如唐代长安、宋代汴梁、敦煌石窟、未来博物馆。
- 搭建一个能看的 3D 场景 不要一开始就做大地图。先做一个核心区域，保证 30 秒内能看懂。
- 加入一个可控角色 WASD + 简单碰撞 + 一个 NPC，就足够验证"游戏感"。
- 设计 3 个互动点 一个 NPC、一个展馆、一个小游戏。不要一开始做 20 个。
- 接入语音 Agent 先用一个默认 persona 跑通，再扩展多个角色。
- 把内容模块化 品牌数据、NPC 数据、展馆数据都写成配置，不要散落在代码里。
- 部署上线 前端用 GitHub Pages / Vercel，后端用可公网访问的服务器。
- 最后再做包装 BGM、头像、视频、封面图、教程、X 推文、GitHub README 都属于传播层。
15. 我们最终做成了什么
最终，这个项目不只是一个 3D 页面，也不只是一个语音 demo。
我们不是把 AI 放到一个按钮里，而是把 AI 放进了一座城。
1. 最初的设计目标
一开始，我们并不是想做一个普通的"3D 展示页"。我们的目标更像一个小型数字文旅实验：
- 它要像游戏一样能玩。 玩家可以进入场景，用 WASD 操控角色，而不是只能转动相机看模型。
- 它要像博物馆一样能逛。 场景里有宫殿、朱雀大街、珍宝馆、诗画展厅、AI 展馆。
- 它要像真实导览一样能说话。 玩家不是点几个固定按钮，而是能按住麦克风和 NPC 语音交流。
- 它要有盛唐气质。 色彩、建筑、人物、诗词、小游戏都围绕"长安""诗酒""万邦来朝"展开。
- 它要能开源。 最终要能部署到 GitHub Pages，让别人直接体验，也能阅读代码学习。
我们想把"盛唐长安"做成一个可漫游、可对话、可游戏、可展示 AI 能力的浏览器 3D 世界。
2. 第一阶段：先搭出一个能看的长安沙盘
任何复杂互动项目，第一步都不是做功能，而是先让"世界存在"。
我们先用 Web 3D 技术搭建了一个低多边形风格的长安微缩沙盘。核心技术是 Three.js：它可以在浏览器中渲染 3D 场景，不需要用户安装客户端。
- 搭建朱雀大街、宫殿、城门、市集、塔楼、河道等地标；
- 做出俯瞰视角，让它第一眼像一张"会动的唐代城市地图"。
这一阶段看起来像"美术搭建"，但其实它决定了后续所有玩法的边界：哪里能走、哪里能互动、哪些地标能承载剧情。
3. 第二阶段：把展示页变成可玩的游戏
只有沙盘还不够。我们希望玩家不是"看长安"，而是"走进长安"。
每个角色有自己的头像、默认名字、初始钱包和物品。进入游戏后，玩家可以：
这一阶段真正完成了从"3D 页面"到"小游戏"的转变。
4. 第三阶段：让 NPC 不只是摆设
很多 3D 场景的问题是：建筑很漂亮，但里面没有生活。
所以我们给城市加了大量 NPC 和小游戏，让它变得有烟火气。
玩家靠近路人、文士、商贾、仕女、官员、僧人等 NPC，可以触发对话。不同 NPC 会有不同身份和口吻。
- 飞花令：给出一个关键字，玩家从诗句中选择含有该字的一句；
小游戏不是单纯为了"好玩"，而是让诗词和历史知识变成可参与的体验。
5. 第四阶段：做珍宝馆与诗画展厅
玩家可以进入不同展馆，欣赏诗画、珍宝和历史主题内容。例如：
展厅的作用是把"游戏"与"文化内容"连接起来：玩家既可以玩，也可以看展、听讲解、理解背后的历史语境。
6. 第五阶段：加入 AI 展馆
项目最特别的一部分，是我们把现代 AI 品牌做成了唐风展馆。
我们设计了一个"天枢府 / AI 展馆"概念：在盛唐长安里出现一个古今穿越的科技坊市。不同 AI 品牌不再只是 logo，而是变成一座座唐风殿宇，每个展馆都有自己的讲席和风格。
其中 Agora 馆作为核心语音互动展馆，承担了实时语音能力展示。
在游戏场景中，Agora 不只是一个外部服务名，而是被设计成一座可进入、可互动、可召唤智机使讲解的"Agora 馆"。这能帮助非技术用户理解：语音 AI 不只是后台 API，它可以成为一个场景化体验。
大唐长安出现了一座"智机府"，各路 AI 智机使在这里讲解不同的智能能力。
这样做的好处是：AI 展示不再像一个冷冰冰的产品页面，而是变成了玩家在游戏世界里能探索的一部分。
7. 第六阶段：接入实时语音 Agent
我们的目标不是让 NPC 弹出文字框，而是让玩家真的能用语音和角色交流。
7.0 开发前置：安装 Agora Skills / Agora CLI
在这个项目里，Agora 语音能力并不是直接把 App ID 写死在网页里，而是通过 Agora Skills + Agora CLI 完成项目登录、能力检查、环境变量写入和 ConvoAI 就绪检查。
Agora Skills 负责告诉 Agent 怎么集成 Agora；Agora CLI 负责登录账号、绑定项目、写入 .env.local。
层级作用谁来使用Agora Skills给 AI Coding Agent 的集成说明书，告诉 Agent 应该用官方 quickstart、怎么检查 ConvoAI、怎么处理 token 和环境变量Cursor / Claude / AgentAgora CLI真正执行登录、项目选择、能力检查、环境变量写入的命令行工具开发者和 Agent 都会用。
所以，"安装 Agora Skills"在实际复现时，通常会落到两件事：
- 确保你的 AI 开发环境已经有 Agora Skill / Agora 参考资料；
- 在本机安装并登录 agora CLI，让项目可以拿到有效的 Agora 项目配置。
第一步：确认是否已有 Agora Skill / Agora CLI
如果能输出路径和版本号，说明 CLI 已经进入你的 PATH。
如果终端能看到 Agora CLI install is healthy，说明 CLI 本身可用。
如果 agora 命令不存在，通常是 shell 没有加载新的 PATH。可以重开终端，或检查安装脚本输出里提示的 PATH 配置。
- 终端打印一个 https://sso2.agora.io/... 登录链接；
- 终端显示 Session stored 和 Status： authenticated。
如果这里显示未登录，重新执行 agora login。
如果登录成功但后面 agora project list 返回：
说明不是代码问题，而是 Agora 账号或控制台权限被限制。此时需要换一个可用账号，或先解除账号限制。
agora project use <project-id-or-name>
如果还没有项目，可以通过 Agora Console 创建，或用 CLI 初始化 quickstart 项目：
本项目是从 official quickstart 的思路继续改造的：先确保官方 demo 能跑，再把它嵌入到《大唐长安》的 3D 场景中。
实时语音 Agent 依赖 Agora 的 Conversational AI 能力。可以运行：
你希望看到的结果是 project doctor 没有 blocking issue。它不等于"语音一定已经通了"，但至少说明控制台项目配置层面准备好了。
注意：AGORA_APP_CERTIFICATE 是敏感信息，不要提交到 GitHub。项目的 .gitignore 已经忽略 .env.local。
写入后可以检查文件是否存在，但不要把证书贴到公开地方：
如果只是自查证书是否存在，可以看键名，不要打印完整值：
如果线上部署语音服务，可以通过 URL 参数指定：
？voiceOrigin=https://你的语音前端域名
如果返回 agent_id，说明后端成功请求 Agora 创建了一个语音 Agent。
最后打开游戏，进入 Agora 馆，点击右侧语音面板，观察三件事：
语音功能最终不是孤立存在的，它会和玩家身份、NPC、展馆、字幕、头像面板一起工作。玩家看见的是"角色在长安城里与智机使对话"，背后才是 RTC、ConvoAI 和 Agent 编排。
通常不是前端按钮坏了，而是 Agora 项目或凭据不可用。优先检查：
- agora project list 是否能正常列出项目；
- agora project doctor --feature convoai 是否通过；
- .env.local 里的 App ID / Certificate 是否来自同一个项目；
如果 CLI 登录正常，但 project list 返回 ACCOUNT_BLOCKED，说明账号侧被限制，代码无法绕过。需要换可用账号或解除 Agora 控制台限制。
- han-diorama 浏览器 3D 主场景 负责 Three.js、WASD、NPC、展馆、小游戏
- 负责 Agora ConvoAI、Persona、语音对话
主场景里点击 NPC 后，会打开右侧语音面板。这个面板本质上是一个嵌入的 iframe，它和主游戏通过 postMessage 通信。
玩家麦克风 ↓ 浏览器 RTC 上行 ↓ Agora 实时音频链路 ↓ ConvoAI：语音识别 → 大模型思考 → TTS 合成 ↓ AI 声音通过 RTC 回到浏览器 ↓ 游戏里 NPC 头像、字幕、状态同步变化
普通用户看到的是"我和李白说话了"。技术上背后是实时音频、语音识别、大模型、语音合成和游戏状态同步一起工作。
如果所有 NPC 都用同一个提示词，它们就会像同一个机器人。
- 智机使 · Agora 馆：讲解实时语音与 ConvoAI。
这让语音功能不只是"能说话"，而是和游戏世界绑定在一起。
8. 第七阶段：做角色头像、视频面板与 BGM
为了让语音互动更有"面对面"的感觉，我们做了左侧角色 portrait 面板。
- idle.jpg / idle.png 静态头像；
- 当玩家打开语音对话时，BGM 自动降低音量，避免盖住人声。
这一步看似是"包装"，但对用户体感影响很大。没有声音和头像时，AI 对话像工具；有了角色视频、字幕和背景音乐后，它更像游戏里的角色。
9. 第八阶段：解决视觉与尺度问题
开发中遇到过一个典型问题：AI 展馆一开始太大，放到城市里会出现"浮在地面上""镜头一转消失"的情况。
这个经验很重要：3D 项目里，美术好看不够，尺度一致才是可玩的前提。
10. 第九阶段：部署到 GitHub
项目完成后，我们把前端开源部署到了 GitHub。
前端 han-diorama 是静态 Web 项目，适合用 GitHub Pages 托管。
然后使用 GitHub Actions 自动发布 Pages。
https://andyhuo520.github.io/tang-changan/
- 实时语音后端 tang-voice-agent 需要单独部署；
- 本地开发时可以用 http://localhost:3000 作为语音 iframe；
- 线上如果要启用语音，需要给游戏传入可访问的语音前端地址。
11. 普通用户怎么体验
https://andyhuo520.github.io/tang-changan/
按键作用WASD移动鼠标调整视角E与 NPC 对话 / 触发小游戏F进入展馆 / 开店 / 触发场景Esc关闭语音面板
12. 开发者如何理解项目结构
han-diorama/ index.html 页面结构与 UI 容器 scene.js 主 3D 场景、游戏模式、NPC、语音面板 modelLoader.js 角色模型加载 assets/ logo、头像、BGM、预览图 portraits/ NPC 视频 / 头像素材 murals/ 画廊素材 lib/ content/brand-data.js AI 展馆品牌数据 world/brand-plaza.js AI 展馆 / 天枢府 world/gallery-hall.js 珍宝馆 / 展厅 world/diy-hall.js 丹青馆 DIY ui/voice-intent.js 语音意图路由 hero/ 大明宫、东西市、曲江等地标模块
tang-voice-agent/ web/ Next.js 语音前端 iframe server/ FastAPI 后端 server/src/personas/ 角色 Persona
3D 主项目负责"玩家在哪里、看见什么、能做什么"；语音子项目负责"玩家说什么、AI 怎么回答、声音怎么回来"。
13. 这次开发踩过的坑
浏览器会缓存 JS 和图片。我们在模块路径后面加版本参数：
scene.js？v=20260529-agora-only
实时语音不只是代码问题，还依赖 Agora 账号、项目状态、ConvoAI 开通状态和 token 鉴权。
CAN_NOT_GET_GATEWAY_SERVER： no active status 401 Invalid token
- App ID / Certificate 不匹配；
这是开发 AI 语音项目时最容易误判的地方：页面看起来是"麦克风开了"，但其实浏览器和 Agent 都没有真正加入频道。
展馆、城市、NPC、地面如果不在同一尺度体系里，就会出现漂浮、穿模、消失、点不到的问题。
解决办法不是不断调相机，而是回到世界坐标，统一单位、位置和可交互范围。
14. 如果你想复刻一个类似项目
- 确定主题 先选一个世界观，例如唐代长安、宋代汴梁、敦煌石窟、未来博物馆。
- 搭建一个能看的 3D 场景 不要一开始就做大地图。先做一个核心区域，保证 30 秒内能看懂。
- 加入一个可控角色 WASD + 简单碰撞 + 一个 NPC，就足够验证"游戏感"。
- 设计 3 个互动点 一个 NPC、一个展馆、一个小游戏。不要一开始做 20 个。
- 接入语音 Agent 先用一个默认 persona 跑通，再扩展多个角色。
- 把内容模块化 品牌数据、NPC 数据、展馆数据都写成配置，不要散落在代码里。
- 部署上线 前端用 GitHub Pages / Vercel，后端用可公网访问的服务器。
- 最后再做包装 BGM、头像、视频、封面图、教程、X 推文、GitHub README 都属于传播层。
15. 我们最终做成了什么
最终，这个项目不只是一个 3D 页面，也不只是一个语音 demo。
我们不是把 AI 放到一个按钮里，而是把 AI 放进了一座城。