站内 AI 问答助手

这是嵌在 Willa空叙 里的站内助手：右下角圆形入口展开弹窗，围绕站主、文章与作品作答，并支持语音输入与朗读。

设计目标

• 单入口、轻打扰：圆形 FAB → 独立弹窗，不打断阅读流
• 只服务本站：系统提示词绑定站点人设与已发布内容目录；站外闲聊（行情、天气等）短拒
• 流式可读：SSE + Markdown 增量渲染，附带朗读
• 可部署：与现有 Astro SSR / Docker Compose 同栈，Redis 内网共存

从设计到实现

1. 交互与界面

• Astro 布局挂载 React island（@astrojs/react）
• 弹窗：消息流、输入框、语音、发送、新会话
• Markdown：react-markdown + remark-gfm
• 样式贴合 atelier 纸感与暗色变量

2. 协议与前端编排

• AG-UI：服务端 @ag-ui/encoder 输出 RUN_* / TEXT_MESSAGE_* SSE 事件
• 浏览器 @ag-ui/client 的 HttpAgent 消费流；先 addMessage 再 runAgent
• 随请求带上当前页 pathname / title，写入空间系统提示词

3. 模型与编排

• Vercel AI SDK：ai + @ai-sdk/openai，streamText 对接通义 DashScope 兼容接口
• 环境变量：dotenv 加载；OPENAI_BASE_URL / OPENAI_MODEL_NAME
• 短期记忆：Redis（ioredis）按 threadId 存最近多轮，TTL 过期；无 Redis 时内存兜底

4. 语音

• ASR：浏览器采集 WAV → /api/assistant/asr → 腾讯云一句话识别
• TTS：助手消息「朗读」→ /api/assistant/tts → 腾讯云语音合成（密钥仅服务端）

5. 安全与部署

• /api/assistant/* 公开放行 + 简易限流；管理 API 仍需登录
• Compose 增加内网 Redis；Caddy 对助手路径 flush_interval -1 保证 SSE
• 可观测：可选 LangSmith 环境变量

技术栈一览

层	技术
站点壳	Astro 7 SSR、Tailwind 4、atelier 样式
助手 UI	React 19 island、react-markdown
协议	AG-UI（SSE 事件流）
模型调用	Vercel AI SDK、DashScope OpenAI 兼容
记忆	Redis / ioredis
语音	腾讯云 ASR + TTS
配置	dotenv
部署	Docker Compose、Caddy、阿里云 ECS

相关路径

• 接口：/api/assistant/run、/asr、/tts
• 核心代码：src/lib/assistant/、src/components/assistant/