聊天机器人 (作品集：赛博朋克)

上下文感知终端聊天机器人与 MCP 集成

LIVE DEMO • [GITHUB: Private Source]

概览

• 角色：全栈工程（从零开始创建了整个系统，包括架构、后端 API、状态管理、UI/UX 和音频集成）
• 技术栈：React, Next.js, TypeScript, Tailwind CSS, Framer Motion, next-intl, MCP
• 关键结果：一个沉浸式的、具有上下文感知能力的 V2 聊天机器人，作为赛博朋克作品集的中心交互节点
• 摘要：一个为“作品集：赛博朋克”深度集成的 V2 聊天机器人系统，它是建立在最初的 V1 聊天机器人（作品集：玻璃）之上的大规模演进。它模拟了一个名为“Oz”的 AI 构造终端，具有实时配音、通过 ToolBadge 指示器动态执行 MCP 工具、系统命令和主动的上下文限制管理功能。它作为代表 Franz 的完全自主的代理。

问题

• 挑战：赛博朋克作品集需要一个聊天机器人，它感觉像是内置终端或 AI 助手，而不是事后添加的小部件。与作为标准对话界面的 V1 玻璃聊天机器人不同，此 V2 迭代需要处理多个系统级命令，可视化呈现 LLM 工具调用（例如导航或播放音乐），在没有音频重叠的情况下播放同步的 AI 配音，并有效地处理上下文窗口。
• 受众：技术招聘人员、开发人员以及探索作品集的访客。
• 限制：涉及声音播放、UI 布局切换、用户输入、呈现异步工具调用和 API 限制（处理令牌限制）的复杂状态管理，需要在不影响 60fps 动画的情况下进行仔细的架构规划。

方法与决策

• 架构：将组件分离为模块化功能：ChatHeader、ChatInput、ChatMessage、ChatHistory、DubPopup 和 ToolBadge。利用 useChatbotAudio 安全地编排声音并避免垃圾信息。
• 关键决策：
  • 工具执行 (ToolBadge)：为了使 AI 的操作可见和透明，我构建了 ToolBadge 组件。当 AI 执行 MCP 工具（例如，切换音乐、下载简历、更改主题或翻译网站）时，聊天流中会出现一个时尚的动画终端徽章，详细说明操作。这从根本上将普通文本与系统操作分开。
  • 身份与自主行为：AI 在“Oz”的形象下运作，担任专业的 AI 助手。它动态处理复杂的工作流程，例如定价查询（显示隐藏的内部定价表）和联系表单路由（Oz 为用户起草电子邮件，但强制他们通过严格的检查和批准 UI 循环）。
  • LLM 引擎和回退架构：构建了具有弹性的后端回退链。它使用混合注意力架构原生处理多达 100 万个上下文令牌，以支持长上下文保留。如果遇到速率限制或临时中断，查询会优雅地从主要的快速模型级联到强大的辅助网络。
  • RAG 与上下文管理：当用户提出深度的技术问题时，它利用 RAG (query_portfolio_data) 获取完整的 MDX 案例研究。当达到上下文容量的 90-98% 时，自适应滑动窗口会丢弃最旧的消息。
  • 审核锁定：实施了自动化的 lockdown 系统，其中 Oz 可以因辱骂性语言或垃圾信息暂时封禁用户（短期、中期或长期超时），并完全与服务器端 cookie 同步。
• 权衡：与其使用 Redux 处理复杂状态，我依靠 React Context 和 useSyncExternalStore 进行本地化状态管理，这优化了包大小，但需要精确的钩子（hook）设计以防止不必要的重新渲染。

关键结果与影响

• 结果：一个引人注目、功能强大的助手，增强了赛博朋克叙事，同时提供了真正的实用性（例如回答问题、控制音乐和展示技能）。
• 影响：展示了高级的 Next.js 模式、通过 MCP 的系统集成、自定义钩子和精确的视听协调。

技术深度剖析

• 值得注意的细节：
  • 直接在 UI 中跟踪实时诊断信息（往返时间、活动模型、令牌）。
  • 关于工具调用：每当 AI 返回 action 对象而不是纯文本时，就会触发 ToolBadge.tsx 组件。它解析工具的参数（例如 { type: "toggle_theme", theme: "dark" }），并渲染一个充满未来感的发光徽章，总结在聊天流中执行的任务。
  • 自定义 TypewriterMarkdown，用于以类似黑客的打字机效果安全地渲染 markdown。
  • DubPopup 可视化工具根据 API 操作异步反映“AI 正在说话”的状态。
• 验证：构建了强大的限制（锁定状态，垃圾信息保护），以优雅地处理滥用行为或速率限制，将服务器配置直接反映在 UI 中。
• 代码质量：广泛使用 TypeScript 接口进行 ToolDetail、ChatSession，并对 ref 和视觉布局交互进行严格的空值检查。

经验与反思

• 可能的不同做法：我可能已经将音频播放器引擎解耦到一个通用 worker 中，以完全消除在移动设备上解码长音频文件时主线程的任何卡顿。
• 成功之处：将 useMusicPlayer 上下文与 AI 命令无缝连接，这样助手就可以真正地在网站内“行动”，跨越聊天和网站导航之间的界限。
• 经验教训：在“酷炫”的赛博朋克效果（打字机，出故障的工具）与可访问性之间取得平衡需要不断的测试。设计具有固定定位和滚动锁定的适合移动设备的浮动聊天窗口在很大程度上取决于浏览器的特性。

---

我的贡献

• 系统架构：设计了聊天状态引擎、用于实时诊断的轮询逻辑和会话存储历史记录。
• 音频工程：编写了基于序列的配音和音效钩子（useChatbotAudio）。
• UI/UX：使用 Tailwind 和 Framer Motion 为组件（ChatSettings、ChatInput）设置样式，以获得真实的类似终端的外观。
• 集成：将 AI 输出映射到影响更广泛应用程序的可执行工具（ToolBadge）（例如，更改语言，下载简历，切换主题）。

---

项目架构

components/chatbot/ 目录编排了助手逻辑：

• 核心引擎：Chatbot.tsx 充当主控制器。
• UI 组件：ChatMessage.tsx、ChatInput.tsx、ChatHistory.tsx。
• 特殊功能：用于视觉效果的 TypewriterMarkdown.tsx、用于音频存在的 DubPopup.tsx 和用于工具执行摘要的 ToolBadge.tsx。
• 集成：与全局提供程序（useMusicPlayer、useTheme、useLocale）集成。

---

实时预览

• 实时演示链接：在实时作品集网站 franzdomingo.dev 上直接体验聊天机器人。
• 尝试功能：输入 /help 查看命令，或让它“Play music”（播放音乐）以查看它触发全局音乐播放器。