基于大模型与原生交互的高情商社交辅助工具
嘴替侠是一款面向社交场景的 AI 回复生成器。输入对方原话，选择场景，即可一键生成五种风格的嘴替文案——温柔一刀、阴阳怪气、直球暴击、幽默化解、以退为进。通过物理级卡片滑动交互，左滑扔掉、右滑采纳，让社交对线变得优雅而高效。
本项目 100% 由 Prompt Engineering 驱动，是与 AI 工具 (Trae) 结对编程的产物。代码骨架与交互逻辑由 AI 辅助生成，开发者主导了产品架构设计、技术选型（FastAPI + interact.js）与全流程 Debug。拥抱 AI，才能更好地驾驭未来。
| 特性 | 说明 |
|---|---|
| FastAPI 高性能架构 | 基于 Starlette 的异步 ASGI 框架，支持高并发请求，自带 OpenAPI 文档 |
| Pydantic 数据安全校验 | 请求/响应全链路类型校验，双模型保障数据完整性 |
| AI 容错重试机制 | 大模型返回 JSON 解析失败时自动重试最多 2 次，正则兜底提取，最终 Mock 数据回退 |
| interact.js 物理级卡片交互 | 基于物理引擎的拖拽手势，支持丝滑回弹、方向指示器、飞出动画 |
| 零 Node.js 依赖 | 纯 Python 后端 + 原生 HTML/CSS/JS 前端，CDN 引入 Tailwind / interact.js / SweetAlert2 / html2canvas |
| 本地弹药库 | 基于 localStorage 的历史收藏系统，支持复制、海报生成、删除管理 |
| 社交裂变海报 | html2canvas 将文案渲染为赛博朋克风海报图片，一键下载分享 |
| 项目 | 要求 |
|---|---|
| Python | 3.8+ |
| 操作系统 | Windows / macOS / Linux |
| 浏览器 | Chrome 90+ / Edge 90+ / Safari 14+（推荐移动端 Chrome） |
| 网络 | 需要访问 CDN 资源（首次加载）；接入大模型需能访问对应 API 服务 |
# Windows 用户：双击或命令行运行
run.bat
# Linux / macOS 用户
chmod +x run.sh && ./run.sh脚本会自动安装依赖并启动服务，打开 http://localhost:8000 即可使用。
pip install -r requirements.txt依赖清单：
| 包名 | 用途 |
|---|---|
fastapi |
Web 框架 |
uvicorn |
ASGI 服务器 |
requests |
HTTP 客户端（调用大模型 API） |
pydantic |
数据校验 |
uvicorn main:app --reload --host 0.0.0.0 --port 8000浏览器打开 http://localhost:8000 即可使用。
⚠️ 注意：未配置 API Key 时，系统会返回预设的 Mock 数据，仅能体验交互功能。要获得真正的 AI 智能回复，必须配置 API Key，详见下方教程。
嘴替侠的核心能力来自大语言模型。没有 API Key，你只能看到固定的示例回复；配置 API Key 后，AI 会根据对方原话和所选场景，实时生成真正可用的高情商回复。
- 打开项目根目录下的
config.json文件 - 填入你的 API Key 和对应的服务地址
{
"api_key": "sk-你的API密钥",
"api_base": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"model": "qwen-turbo"
}- 保存文件，重启服务即可生效
以下是国内主流大模型服务的获取方式，均提供免费额度：
| 服务商 | 注册地址 | 免费额度 | api_base | model 示例 |
|---|---|---|---|---|
| 阿里云通义千问 | dashscope.console.aliyun.com | ✅ 新用户送 100 万 Token | https://dashscope.aliyuncs.com/compatible-mode/v1 |
qwen-turbo |
| 字节豆包 | console.volcengine.com/ark | ✅ 新用户送 5 元体验金 | https://ark.cn-beijing.volces.com/api/v3 |
doubao-pro-32k |
| 智谱 GLM | open.bigmodel.cn | ✅ 新用户送 25 元体验金 | https://open.bigmodel.cn/api/paas/v4 |
glm-4-flash |
| Moonshot | platform.moonshot.cn | ✅ 新用户送 15 元体验金 | https://api.moonshot.cn/v1 |
moonshot-v1-8k |
| DeepSeek | platform.deepseek.com | ✅ 新用户送 500 万 Token | https://api.deepseek.com/v1 |
deepseek-chat |
| OpenAI | platform.openai.com | ❌ 需付费 | https://api.openai.com/v1 |
gpt-3.5-turbo |
首选：阿里云通义千问（免费额度最多，注册最简单）
- 访问 dashscope.console.aliyun.com，用支付宝扫码登录
- 开通 DashScope 服务（免费）
- 在「API-KEY 管理」页面创建一个新的 API Key
- 将 API Key 填入
config.json：
{
"api_key": "sk-你从阿里云获取的Key",
"api_base": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"model": "qwen-turbo"
}- 保存后重启服务，即可体验完整功能
项目支持两种配置方式，config.json 优先级高于环境变量：
| 配置方式 | 字段/变量名 | 说明 | 默认值 |
|---|---|---|---|
| config.json | api_key |
大模型 API 密钥 | "" (空则使用 Mock) |
| config.json | api_base |
API 基础地址 | https://dashscope.aliyuncs.com/compatible-mode/v1 |
| config.json | model |
模型名称 | qwen-turbo |
| 环境变量 | AI_API_KEY |
大模型 API 密钥 | "" |
| 环境变量 | AI_API_BASE |
API 基础地址 | 同上 |
| 环境变量 | AI_MODEL |
模型名称 | 同上 |
本项目完全兼容支持 OpenAI API 规范的本地推理工具，实现纯离线、隐私安全的"赛博嘴替"。你的嘴替文案，不出本机半步。
适合拥有高性能显卡的工作站，图形化界面一键加载模型：
- 下载并安装 LM Studio
- 在 LM Studio 中搜索并下载你喜欢的模型（推荐 Qwen2.5-7B-Instruct）
- 点击「Start Server」开启本地推理服务（默认端口 1234）
- 修改
config.json：
{
"api_key": "lm-studio",
"api_base": "http://localhost:1234/v1",
"model": "qwen2.5-7b-instruct"
}适合在掌机或轻量设备上运行小参数模型，开箱即用：
- 安装 Ollama
- 一行命令拉取并运行模型：
ollama run qwen2.5:0.5b- Ollama 会自动开启本地 API 服务（默认端口 11434）
- 修改
config.json：
{
"api_key": "ollama",
"api_base": "http://localhost:11434/v1",
"model": "qwen2.5:0.5b"
}💡 提示：本地模型的回复质量取决于模型参数量。0.5B 模型适合体验交互流程，7B+ 模型才能获得接近云端 API 的回复质量。显存不足时，LM Studio 支持 GGUF 量化格式，4-bit 量化后 7B 模型仅需约 4GB 显存。
- 在「对方原话」文本框中输入或粘贴对方说的话
- 在「场景选择」下拉框中选择对应场景（共 10 个场景）
- 点击「请求嘴替」按钮，等待 AI 生成五种风格的回复
| 风格 | 策略 | 适用场景 |
|---|---|---|
| 🩵 温柔一刀 | 先肯定再反转，暗藏锋芒 | 职场、长辈、需维持关系 |
| 💗 阴阳怪气 | 反讽夸张，让对方自感荒谬 | 怼人、反击、让对方无话可说 |
| 🔴 直球暴击 | 不绕弯子，直接亮明底线 | 维权、拒绝、划清界限 |
| 🟡 幽默化解 | 玩笑自嘲，笑着反击 | 朋友、社交、缓和气氛 |
| 🟢 以退为进 | 先示弱认同，再提诉求 | 谈判、协商、需对方配合 |
| 场景 | 覆盖痛点 |
|---|---|
| 🏢 职场对线 | 老板 PUA、同事甩锅 |
| 💔 手撕海王 | 渣男/渣女套路 |
| 💰 闲鱼砍价 | 二手交易砍价 |
| 🎎 亲戚催婚 | 过年灵魂拷问 |
| 🏠 房东 battle | 押金/维修纠纷 |
| 💸 朋友借钱 | 借钱不还/拒绝借钱 |
| 🛡️ 客服维权 | 售后推诿/维权 |
| 💑 情侣吵架 | 感情沟通 |
| 🎓 导师沟通 | 学术圈生存 |
| 🍽️ 饭局应酬 | 社交脱身 |
- 右滑（→ 采纳）：拖拽卡片向右超过阈值，文案自动复制到剪贴板，并存入「我的弹药库」
- 左滑（← 扔掉）：拖拽卡片向左超过阈值，卡片飞出丢弃
- 回弹：拖拽未达阈值时，卡片弹性回弹到中心位置
- 拖拽过程中会显示方向指示器（✓ / ✗），透明度随拖拽距离动态变化
- 点击右上角「🗂️」按钮打开侧边栏
- 所有右滑采纳的文案自动保存在本地（localStorage）
- 每条记录显示：风格标签、保存时间、文案内容
- 支持操作：复制文案 / 生成海报 / 删除记录
- 角标数字实时显示已收藏数量
- 在弹药库中点击某条记录的「生成海报」按钮
- 系统自动将文案渲染为赛博朋克风格的精美海报
- 海报包含 VocalHero 品牌标识、风格标签、文案内容
- 自动触发浏览器下载 PNG 图片，可直接分享到社交平台
VocalHero/
├── main.py # FastAPI 后端（AI 调用 + Pydantic 校验 + 重试机制）
├── config.json # API 配置文件（api_key / api_base / model）
├── requirements.txt # Python 依赖清单
├── run.bat # Windows 一键启动脚本
├── run.sh # Linux/macOS 一键启动脚本
├── README.md # 项目文档
└── static/
├── index.html # 前端页面（赛博朋克 UI + CDN 引入）
├── style.css # 自定义样式（毛玻璃 + 动态渐变 + 卡片动画）
└── app.js # 前端逻辑（interact.js 滑动 + 弹药库 + 海报生成）
用户请求 → Pydantic 校验 → API Key 检查
├─ 无 Key → 返回 Mock 数据
└─ 有 Key → 调用大模型 API
├─ 成功 → JSON 解析
│ ├─ 解析成功 → 返回结果
│ └─ 解析失败 → 重试（最多2次）
└─ 失败 → 重试（最多2次）
└─ 全部失败 → Mock 数据回退
pip install gunicorn
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]docker build -t vocalhero .
docker run -p 8000:8000 -v $(pwd)/config.json:/app/config.json vocalhero# /etc/systemd/system/vocalhero.service
[Unit]
Description=VocalHero Web App
After=network.target
[Service]
WorkingDirectory=/opt/VocalHero
ExecStart=/usr/bin/uvicorn main:app --host 0.0.0.0 --port 8000
Restart=always
[Install]
WantedBy=multi-user.targetsudo systemctl enable vocalhero
sudo systemctl start vocalheroMIT License — 自由使用、修改和分发。