This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
基于讯飞开放平台的智能聊天机器人。后端已实现三项核心能力：Spark LLM 多轮对话、语音识别（STT）、语音合成（TTS）。当前交互方式为 CLI 命令行菜单。
cd /path/to/py-chatbot
python main.py无需虚拟环境，系统级 Python 已安装依赖。
main.py # CLI 入口 + 菜单调度
├── spark_service.py # 讯飞星火 LLM v3.5，多轮对话
│ # chat(question) → 单轮
│ # chat_with_history(question, messages) → 多轮（有状态）
├── iat_service.py # 讯飞语音听写，麦克风实时采集 + 流式转写
│ # microphone_stream() → 返回识别文本
└── tts_service.py # 讯飞语音合成，流式文本转语音
# speech_synthesis(text) → 流式播放
所有服务通过 python-dotenv 从 .env 读取 API 凭证（APP_ID, API_KEY, API_SECRET）。各 Service 模块使用惰性单例模式（_service = None → get_service()）。
| 包 | 用途 |
|---|---|
spark-ai-python |
星火大模型 SDK（ChatSparkLLM） |
xfyunsdkspeech |
讯飞语音 SDK（IatClient, TtsClient） |
PyAudio |
麦克风采集 + 音频播放 |
websockets / websocket-client |
底层 WebSocket（SDK 依赖） |
python-dotenv |
读取 .env |
.env 包含真实的讯飞 API 凭证，绝对不能提交到版本控制。当前不在 .gitignore 中——添加 .env 到 .gitignore 是首要任务。
前端设计文档位于 docs/superpowers/specs/2026-07-16-chatbot-frontend-design.md。
已确定的技术方向（尚未实施）：
- 后端：FastAPI 封装现有 Service 为 REST + WebSocket API
- 前端：React + Vite + Zustand + Tailwind CSS（ChatGPT 风格 UI）
- 支持全模式：文字对话 + 语音输入（STT）+ 语音输出（TTS）
- v1 单用户，架构预留多用户扩展
# 后端
uvicorn server.main:app --reload --host 0.0.0.0 --port 8000
python -m pytest server/tests/ -v
# 前端
cd client && npm run dev
cd client && npm test