团队：手势魔法
成员：Hallo, Celine
手势魔法工坊 是一个基于计算机视觉（Computer Vision）和生成式 AI 代理（Generative AI Agents）的无接触创意工作室。用户无需键盘或鼠标，仅通过手势和语音即可完成从灵感搜索到艺术创作的全过程。
本项目采用了 “前端视觉 + 云端智能体” 的混合架构，确保交互的实时性和生成的灵活性。
-
视觉交互层 (Visual Core)
- MediaPipe Hands: 在浏览器端本地运行（60fps），实时捕捉 21 个手部关键点，无需上传视频流，保障隐私。
- Gesture Logic: 自研手势识别算法，支持防抖动（Anti-jitter）和长按触发（Hold-to-trigger）机制。
-
智能体调度层 (Agent Protocol)
- Qveris Agent System: 核心逻辑基于 Search & Execute 协议。系统不依赖单一模型，而是根据意图动态调度工具。
- Fallback 机制: 当智能体网络繁忙时，自动降级切换至 Google Gemini API 保障基础服务。
-
服务集成 (Integrated Services)
- 语音转录: Deepgram Nova-2 模型（毫秒级 STT）。
- 图像生成: 智谱 CogView-3 / Stable Diffusion (通过 Agent 调用)。
- 灵感搜索: Brave Search API。
- 语义提炼: Google Gemini 2.5/3.0 Flash。
本项目依赖多个云端 API。在运行前，请确保配置以下密钥。
在项目根目录创建或检查环境变量（通常在构建平台配置）：
API_KEY: Google Gemini API Key (可选/备选)。主要作为 Qveris 智能体服务的备选方案。若未配置，将无法使用 Gemini Fallback 模式及部分高级语义润色功能。
为了方便演示，部分 Keys 可能硬编码在 services/geminiService.ts 中。生产环境部署时，请务必替换为你自己的 Key。
需要关注的文件位置：src/services/geminiService.ts
| 变量名 | 描述 | 获取方式 |
|---|---|---|
API_CONFIG.qverisKey |
Qveris Agent 鉴权密钥 | 联系 Qveris 管理员或部署自有 Agent 网关 |
TOOLS_CONFIG.deepgram.apiKey |
Deepgram 语音识别密钥 | Deepgram Console |
TOOLS_CONFIG.stability.key |
(可选) Stability AI 绘图密钥 | Stability AI Platform |
注意: 如果
process.env.API_KEY未生效，代码会自动尝试使用 Qveris 代理模式。建议确保 Google API Key 可用以获得最佳体验。
本项目基于 React (TypeScript) 构建，使用常见的构建工具（如 Vite 或 Webpack）。
-
安装依赖
npm install # 或者 yarn install -
启动开发服务器
npm start # 或者 npm run dev打开浏览器访问
http://localhost:3000(或控制台提示的端口)。 -
授权许可 首次运行时，浏览器会请求 摄像头 和 麦克风 权限，请点击“允许”以启用视觉和语音功能。
npm run build构建产物将位于 dist/ 或 build/ 目录，可直接部署至 Vercel, Netlify 或任何静态网站托管服务。
系统包含 核心指令 和 风格修饰 两类手势。操作时请确保手部位于摄像头视野中央。
| 手势图标 | 动作名称 | 操作方法 | 功能描述 |
|---|---|---|---|
| ✊ | 语音录入 | 握紧拳头 (保持) | 激活麦克风开始录音。松开拳头时自动停止录音并开始转录。 |
| 🖐️ | 灵感探索 | 张开手掌 (保持 1秒) | 调用智能体搜索网络热门视觉趋势，并将其转化为艺术提示词。 |
| 👌 | 确认生成 | OK 手势 (保持 1秒) | 提交当前的提示词和风格设置，调用绘图模型生成图片。 |
在生成图片前，使用以下手势为提示词注入特定的艺术风格：
| 手势图标 | 风格名称 | 操作方法 | 风格效果 |
|---|---|---|---|
| ✌️ | 赛博朋克 | V字手势 (剪刀手) | 注入霓虹灯、高科技、未来城市、机械感元素。 |
| 🤘 | 重金属风 | 摇滚手势 (收起中指无名指) | 注入火焰、暗黑、哥特、硬核、高对比度元素。 |
| 🤟 | 二次元风 | 爱的手势 (伸出拇指) | 注入日系动漫、柔光、粉彩、可爱、梦幻元素。 |
Q: 摄像头画面是黑色的？ A: 请检查浏览器地址栏是否允许了摄像头权限。另外，确保没有其他应用（如 Zoom/Teams）占用了摄像头。
Q: 手势反应迟钝或识别不准？ A:
- 确保环境光线充足。
- 手部距离摄像头约 0.5 - 1 米。
- 背景尽量简洁，避免杂乱背景干扰识别。
Q: 提示 "API Key 缺失"？ A: 请参照“配置指南”章节，检查代码中的 Key 是否已正确填入或环境变量是否生效。
Q: 生成图片一直转圈（Loading）？ A: 图像生成模型冷启动可能需要 10-20 秒。如果长时间无响应，请尝试点击控制面板右下角的 “自检工具” (扳手图标) 查看服务连接状态。
Made with ❤️ by Hallo & Celine