# voice-agent

**Repository Path**: vvbtc/voice-agent

## Basic Information

- **Project Name**: voice-agent
- **Description**: 语音 Agent。沙盒项目，按 deploy.yaml 规范管理，Gitee 自动部署。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-16
- **Last Updated**: 2026-07-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 语音 Agent — CodeBuddy 语音模式

> 本仓库由 **WorkBuddy** 按 [sandbox-deploy](https://gitee.com/vvbtc/sandbox-deploy) 规范管理。服务器端由 WorkBuddy 负责，你只需按本仓库约定提交代码。

## 项目介绍

用语音和 AI 自由对话的 PWA 应用。打开浏览器 → 点麦克风 → 说话 → AI 流式回复 → 自动朗读。

- **类型**：PWA（React + Vite）+ Node 桥服务
- **状态**：MVP 核心链路已跑通，待服务器部署
- **标签**：AI、语音、PWA

## 快速体验

在线沙盒（Mock 演示模型，无需 Key）：  
👉 打开 `index.html` 中「在线体验」链接

## 仓库结构

```
voice-agent/
  index.html              # 项目门户（介绍 + 进度 + 下载入口）
  deploy.yaml             # 部署契约（sandbox-deploy 规范）
  README.md               # 本文件
  web/                    # PWA 构建产物（SPA 静态资源）
    index.html            # PWA 入口
    assets/               # JS/CSS
    manifest.webmanifest  # PWA 清单
    sw.js                 # Service Worker
  server/                 # Node 桥服务（零依赖）
    server.mjs            # 主桥：托管 web/ + 反向代理 /llm/* → LLM
    mock-llm.mjs          # 演示模型（无需 Key 即可跑通）
    gen-cert.sh           # 自签证书（本地 HTTPS 调试用）
    .env.example          # 环境变量模板
  systemd/                # systemd 单元
    voice-agent.service
  nginx/                  # nginx vhost 配置
    voice-agent.nnszwl.com.conf
```

## 你作为执行人要做的事

1. 填写 `server/.env` 的 `LLM_API_KEY`（火山方舟 / DeepSeek 等，桥自动注入）。
   - 部署目录：`/www/wwwroot/wl.nnszwl.com/public/voice-agent/`
   - 应用入口：`https://wl.nnszwl.com/voice-agent/`（PWA 以子目录 `/voice-agent/` 挂载，已配置 `base:/voice-agent/`）
2. 如需在公司首页展示介绍图：准备一张 PNG（1200×630），放到 `web/intro.png`，推到 `main` 后自动聚合。
3. 写代码、按规范提交、**推 `main`** 即触发自动部署（deployd 上线后）。
4. **禁止**提交：`.env`、密钥、密码、`node_modules`。

## 部署架构（子目录部署）

```
浏览器/手机
   │  https://wl.nnszwl.com/voice-agent/
nginx (wl.nnszwl.com)
   ├─ /voice-agent/        → 静态托管  web/  (PWA, SPA fallback)
   └─ /voice-agent/llm/*   → 反代 127.0.0.1:3000 (Node 桥)
                                │  去掉 /voice-agent 前缀
                          Node 桥 server/server.mjs
                                └─ /llm/* → 真实 LLM（密钥在 server/.env）
```

- `systemd/voice-agent.service`：`node server/server.mjs`，工作目录即上述部署目录
- `nginx/voice-agent.wl.nnszwl.com.conf`：子目录 vhost，`/voice-agent/llm/` 反代（SSE 已关缓冲）
- 完整手动部署步骤见 `DEPLOY-GUIDE.md`（服务器侧由管理员执行）

## 分支模型

- `main` = 沙盒自动部署分支。推 `main` 即上线沙盒。
- 开发请在自己分支，合并进 `main` 才部署。

## 开发进度

| 阶段 | 状态 |
|---|---|
| 需求分析与 PRD | ✅ 完成 |
| PWA 原型开发（React + Vite） | ✅ 完成 |
| 本地桥服务（Node SSE 透传） | ✅ 完成 |
| Mock 演示模式 | ✅ 完成 |
| Gitee 部署上线 | ✅ 完成 |
| Android APK 打包 | ⏳ 待开始 |
| iOS 原生 ASR 适配 | ⏳ 待开始 |
| 语音唤醒 & 连续对话 | ⏳ 待开始 |