AI Agent 项目说明文档

July 22, 2026 · View on GitHub

前端（fronted）

1. 使用的技术

核心框架

技术	版本	用途
Vue 3	^3.5.31	前端核心框架，使用 Composition API
TypeScript	~6.0.0	类型安全的 JavaScript 超集
Vite	^8.0.3	构建工具与开发服务器
Vue Router	^5.0.4	前端路由管理
Pinia	^3.0.4	全局状态管理

UI样式与 AI 组件

技术	版本	用途
Tailwind CSS	^4.2.2	原子化 CSS 框架
shadcn-vue	-	基于 Reka UI 的组件库
Lucide Vue Next	^1.0.0	图标库
ai-elements-vue	^1.4.0	AI 交互 UI 组件库

样式特点：

深色主题设计，现代化的视觉体验
渐变色背景和半透明卡片效果
流畅的动画过渡和交互反馈

2. 如何启动前端项目

环境要求

Node.js：^20.19.0 或 >=22.12.0

安装依赖

cd fronted
npm install

启动开发服务器

npm run dev

启动后访问 http://localhost:3000

开发服务器已配置代理，/api、/resources、/storage 路径请求会自动转发到后端 http://localhost:8000。

其他常用命令

# 构建生产版本
npm run build

# 预览生产构建结果
npm run preview

# TypeScript 类型检查
npm run type-check

# 代码格式化（使用 Prettier）
npm run format

3. 项目文件结构与说明

fronted/
├── public/                     # 静态资源，直接复制到构建输出目录
├── src/                        # 源代码目录
│   ├── main.ts                 # 应用入口，初始化 Vue、Pinia、Router
│   ├── App.vue                 # 根组件，挂载路由视图
│   ├── style.css               # 全局样式（Tailwind 基础配置）
│   ├── api/                    # API 接口层
│   │   ├── index.ts            # API 统一导出入口
│   │   ├── http.ts             # HTTP 客户端封装（支持 REST 和 SSE 流式请求）
│   │   ├── chat.ts             # 聊天相关 API（AG-UI 事件解析、流式响应处理）
│   │   ├── resource.ts         # 音频资源相关 API（查询、删除）
│   │   ├── config.ts           # 配置管理 API（获取和更新配置）
│   │   └── mock-chat-response.json  # 本地 Mock 数据，用于开发调试
│   ├── assets/                 # 静态资源
│   │   ├── base.css            # 基础 CSS 变量与重置样式
│   │   ├── main.css            # 主样式入口
│   │   └── logo.svg            # 项目 Logo
│   ├── components/             # 公共组件
│   │   ├── AudioCard.vue       # 音频卡片组件（音频播放展示）
│   │   └── ai-elements/        # AI 交互 UI 组件集合
│   │       ├── agent/          # Agent 相关组件（展示 Agent 信息、工具调用等）
│   │       ├── artifact/       # Artifact 组件（展示 AI 生成的内容块）
│   │       ├── attachments/    # 附件上传与预览组件
│   │       ├── audio-player/   # 音频播放器组件
│   │       ├── canvas/         # 画布组件（Vue Flow 流程图封装）
│   │       ├── chain-of-thought/  # 思维链组件（展示 AI 推理步骤）
│   │       ├── checkpoint/     # 检查点组件（流程节点标记）
│   │       ├── code-block/     # 代码块组件（代码高亮、复制等）
│   │       ├── commit/         # Git Commit 展示组件
│   │       ├── confirmation/   # 确认对话组件（用户确认 AI 操作）
│   │       ├── connection/     # 连接状态组件
│   │       ├── context/        # 上下文信息组件（Token 用量展示）
│   │       ├── controls/       # 控制栏组件
│   │       ├── conversation/   # 对话容器组件（消息列表、滚动控制）
│   │       ├── edge/           # 边组件（Vue Flow 连线，支持动画）
│   │       ├── environment-variables/  # 环境变量展示组件
│   │       ├── file-tree/      # 文件树组件（目录结构展示）
│   │       ├── image/          # 图片展示组件
│   │       └── inline-citation/  # 内联引用组件（引用来源展示）
│   ├── lib/                    # 工具函数库
│   │   └── utils.ts            # 通用工具函数（CSS 类名合并等）
│   ├── router/                 # 路由配置
│   │   └── index.ts            # 路由定义（当前仅有首页路由）
│   ├── stores/                 # Pinia 状态管理
│   │   └── counter.ts          # 示例 Store（计数器）
│   └── views/                  # 页面视图组件
│       ├── ChatAgent.vue       # 聊天 Agent 页面（流式对话、工具调用展示）
│       ├── PodcastList.vue     # 播客成品列表页面（展示和管理播客作品）
│       ├── ResourceLibrary.vue # 资源库页面（音频资源管理）
│       └── VisualConfig.vue    # 可视化配置页面（API Key 和模型参数配置）
├── index.html                  # HTML 入口模板
├── vite.config.ts              # Vite 构建与代理配置
├── tsconfig.json               # TypeScript 配置（引用 app 和 node 子配置）
├── tsconfig.app.json           # 应用源码 TS 配置
├── tsconfig.node.json          # Node 环境 TS 配置（用于 Vite 配置文件）
├── package.json                # 依赖声明与脚本命令
├── .prettierrc.json            # Prettier 代码格式化配置
└── components.json             # shadcn/ui 组件配置

后端（backend）

1. 使用的技术

核心框架

技术	版本	用途
FastAPI	0.104.1	高性能 Python Web 框架，提供 REST API 与 SSE 流式接口
Uvicorn	0.24.0	ASGI 服务器，运行 FastAPI 应用
Pydantic	>=2.7.4	数据校验与序列化

AI / Agent

技术	版本	用途
LangChain	1.0.0	LLM 调用与 Agent 编排框架
LangGraph	1.0.3	基于图的 Agent 工作流管理，支持多轮对话与记忆
langchain-openai	1.0.0	OpenAI 兼容接口适配（支持 DeepSeek 等）
ag-ui-protocol	0.1.18	AG-UI 标准事件协议编码，用于前后端流式通信
sse-starlette	1.8.2	Server-Sent Events 流式响应支持

音频处理

技术	版本	用途
pydub	-	音频处理库（拼接、混音、音量调整等）

2. 如何创建虚拟环境

后端基于 Python，建议为项目创建独立的虚拟环境以隔离依赖。

方式一：使用 venv（Python 内置，推荐）

cd backend

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境（macOS / Linux）
source venv/bin/activate

# 激活虚拟环境（Windows）
venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

# 退出虚拟环境
deactivate

方式二：使用 conda

# 创建虚拟环境（指定 Python 版本）
conda create -n agent python=3.11

# 激活虚拟环境
conda activate agent

# 安装依赖
pip install -r backend/requirements.txt

# 退出虚拟环境
conda deactivate

3. 如何启动后端项目

环境要求

Python：3.11+
已创建并激活虚拟环境（参考第 2 节）

配置环境变量

复制 .env.example 为 .env 并填写相关配置：

cd backend
cp .env.example .env

编辑 .env 文件：

# OpenAI 兼容 API 配置（必需，支持 DeepSeek 等）
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_API_BASE=your_openai_api_base_here

# 阿里云 DashScope 配置（TTS 语音功能专用，必需）
DASHSCOPE_API_KEY=your_dashscope_api_key_here
DASHSCOPE_API_BASE_URL=https://dashscope.aliyuncs.com/api/v1

准备音频处理依赖

音频混音功能依赖 pydub 库，需要额外安装：

pip install pydub

注意：pydub 需要系统安装 FFmpeg。macOS 可使用 brew install ffmpeg，Ubuntu 可使用 sudo apt install ffmpeg。

准备背景音乐目录

播客混音功能需要准备背景音乐文件，放入 storage/bgm/ 目录：

mkdir -p storage/bgm
# 将您的背景音乐文件（.mp3 或 .wav）放入此目录

安装依赖

cd backend
pip install -r requirements.txt

启动服务

cd backend
python main.py

服务默认运行在 http://localhost:8000，支持热重载。

主要接口

方法	路径	说明
GET	`/`	服务健康确认
GET	`/api/health`	健康检查
POST	`/api/chat`	聊天接口（SSE 流式响应）
GET	`/api/config`	获取配置信息
PUT	`/api/config`	更新配置信息
GET	`/resources/audio`	查询音频资源列表
POST	`/resources/audio/upload`	上传音频文件（支持 .mp3 和 .wav）
DELETE	`/resources/audio/{id}`	删除指定音频文件
GET	`/storage/audios/{filename}`	静态音频文件访问

4. 后端文件结构与说明

backend/
├── main.py                         # 应用入口：初始化 FastAPI、注册路由、挂载静态文件
├── requirements.txt                # Python 依赖清单
├── .env                            # 环境变量配置（本地，不提交 git）
├── .env.example                    # 环境变量配置示例模板
├── app/                            # 应用核心模块
│   ├── __init__.py
│   ├── config/                     # 配置模块
│   │   └── paths.py                # 路径配置：定义存储目录路径常量
│   ├── llm/                        # LLM 工厂模块
│   │   ├── factory.py              # 创建 ChatOpenAI 实例（读取环境变量中的 API Key 和 Base URL）
│   │   └── README.md               # LLM 模块说明
│   ├── routers/                    # 路由层（接收 HTTP 请求，分发到 Service 层）
│   │   ├── chat.py                 # 聊天路由：POST /api/chat，支持 normal / text-to-voice 模式
│   │   └── resources.py            # 资源路由：音频文件的查询、上传与删除接口
│   ├── services/                   # 业务逻辑层
│   │   ├── __init__.py
│   │   ├── agent_service.py        # 创建 LangGraph Agent，处理流式对话，注册 TTS 工具
│   │   ├── prompt.py               # Agent 系统提示词（音频内容创作专家角色定义）
│   │   └── stream_processor.py     # 流式响应处理器：将 LangGraph 输出转换为 AG-UI 协议事件
│   ├── tools/                      # Agent 工具定义
│   │   ├── qwen_tts.py             # 阿里云 Qwen TTS 工具：语音设计（voice_design）和音色复刻（voice_cloning）
│   │   ├── qwen_asr.py            # 阿里云 Qwen ASR 工具：语音识别（语音→文字）
│   │   ├── qwen_multimodal.py      # 阿里云 Qwen 多模态工具：图片/视频/音频统一理解
│   │   ├── voice_save.py           # 音色保存工具：临时→永久的音色迁移与索引记录
│   │   ├── audio_index.py          # 音频索引公共模块：统一管理音频文件索引记录
│   │   └── audio_mixing.py         # 音频混音工具：拼接、BGM选择、音轨混音（播客后期制作）
│   └── utils/                      # 工具函数
│       ├── logger.py               # 日志配置：同时输出到控制台和文件，支持按大小轮转
│       ├── temp_cleanup.py         # 临时文件清理：定时清理 storage/temp/ 过期文件
│       └── config_manager.py       # 配置管理工具：配置可视化功能，支持配置文件 > 环境变量优先级
├── storage/                        # 持久化存储目录（静态文件服务挂载点）
│   ├── audios/                     # 永久音频文件存储目录（用户确认保存的定制音色）
│   ├── bgm/                        # 背景音乐存储目录
│   ├── podcasts/                   # 播客成品存储目录
│   ├── temp/                       # 临时文件目录（工具生成的中间产物，定期自动清理）
│   ├── voice_index.json            # 音频索引文件（记录所有音频的元数据信息）
│   └── images/                     # 图片文件存储目录
└── logs/                           # 运行日志目录（自动创建）

5. 核心功能模块

5.1 音频混音工具（播客后期制作）

backend/app/tools/audio_mixing.py 提供了三个核心音频处理工具：

1) 音频拼接工具（`concatenate_audio`）

将多个音频片段按顺序拼接成完整对话，支持：

交叉淡入淡出过渡（crossfade）
可配置的静音间隔
自动记录到音频索引

使用场景：将多个角色的语音片段拼接成播客对话。

2) 智能BGM选择工具（`select_background_music`）

根据场景描述智能匹配合适的背景音乐，支持：

基于文件名的语义匹配
自动循环或裁剪以匹配目标时长
指定特定BGM文件

使用场景：为播客对话选择合适的背景音乐。

3) 音频混音工具（`mix_audio_with_bgm`）

将人声对话与背景音乐混合，支持专业的BGM开场效果：

BGM开场时段（原音量）→ 过渡时段（渐变）→ 背景音量（约5%）
音量归一化处理
自动淡出效果

使用场景：生成最终的播客成品。

5.2 音频资源管理

backend/app/routers/resources.py 提供音频资源的RESTful API：

接口	功能
`GET /resources/audio`	查询所有音频资源列表
`POST /resources/audio/upload`	上传音频文件（支持 .mp3 和 .wav）
`DELETE /resources/audio/{id}`	删除指定音频资源（文件+索引记录）

特性：

自动生成唯一文件名避免冲突
统一的索引管理（voice_index.json）
支持查询、上传、删除完整生命周期

5.3 音频索引系统

backend/app/tools/audio_index.py 提供统一的音频索引管理：

存储格式：

[
  {
    "id": "uuid",
    "local_path": "/storage/audios/xxx.wav",
    "voice_id": "voice-xxx",
    "model_name": "cosyvoice-v2",
    "path": "audios",
    "createTime": "2026-07-10 14:30:00"
  }
]

path 字段说明：

audios：定制音色生成的音频
bgm：上传的背景音乐
podcasts：混音生成的播客成品


---

### 5.4 语音识别工具（ASR）

[`backend/app/tools/qwen_asr.py`](backend/app/tools/qwen_asr.py) 集成阿里云 DashScope `qwen3-asr-flash` 模型，提供高精度语音识别能力。

**核心调用链**：

```python
@tool("qwen_asr_tool", args_schema=ASRInput)
def qwen_asr_tool(audio: str, enable_itn: bool = False) -> str:
    # 1. 解析音频来源（URL / 本地路径 → data URI）
    audio_url = _resolve_audio_source(audio)

    # 2. 调用 ASR API
    response = _call_asr_api(audio_url, enable_itn)

    # 3. 提取识别文本
    text = _extract_text_from_response(response)
    return text

关键能力：

多格式支持：MP3、WAV、OGG、FLAC、M4A、AAC 等主流音频格式
ITN 逆文本标准化：自动将口语化表达转为书面形式（如"二零二五年" → "2025年"）
智能来源解析：支持本地路径和网络 URL，本地文件自动转为 base64 data URI

使用场景：将用户上传的音频内容转录为文字，作为播客脚本素材。

5.5 多模态识别工具

backend/app/tools/qwen_multimodal.py 集成阿里云 DashScope qwen3.5-omni-plus 模型，支持图片、视频、音频的统一多模态理解。

两大核心工具：

工具名	功能	适用场景
`qwen_multimodal_tool`	单媒体多模态识别	分析单张图片/单个视频/单段音频
`qwen_combined_multimodal_tool`	组合多模态识别	同时分析多个媒体（如图片+音频组合）

大视频智能分割：当视频文件超过 21MB 时，自动使用 moviepy 分割为多个片段分别处理：

def _split_and_encode_video(video_path: Path, suffix: str) -> List[dict]:
    video = VideoFileClip(str(video_path))
    target_size = 10 * 1024 * 1024  # 每段 10MB
    num_segments = max(1, int(file_size / target_size))
    segment_duration = duration / num_segments

    for i in range(num_segments):
        segment = video.subclipped(start_time, end_time)
        segments.append(_build_media_content(data_uri, suffix, is_url=False))
    return segments

额外能力：

支持流式输出（stream=True），实时获取识别结果
支持音频输出模态（enable_audio_output），可指定音色进行语音合成

使用场景：识别用户上传的视频/图片内容，提取关键信息用于播客制作。

5.6 音色保存工具

backend/app/tools/voice_save.py 将用户满意的定制音色从临时目录永久保存到 storage/audios/，并记录到索引文件。

核心逻辑：

@tool("save_voice", args_schema=VoiceSaveInput)
def save_voice_tool(audio_source: str, voice_id: str, text: str, model_name: str = "") -> str:
    if audio_source.startswith("storage/") or audio_source.startswith("/"):
        # 从临时目录复制到永久目录
        source_path = BASE_DIR / audio_source.lstrip("/")
        dest_path = AUDIOS_DIR / source_path.name
        shutil.copy2(source_path, dest_path)
        local_path = f"storage/audios/{source_path.name}"
    else:
        # base64 数据：解码并保存
        local_path = save_audio_from_base64(audio_source, text, "saved_voice")

    record_voice_index(local_path, voice_id, model_name, path="audios")
    return json.dumps({"audio_url": local_path, "voice_id": voice_id, ...})

设计亮点：

支持两种输入方式：临时文件路径（直接复制）和 base64 编码数据（解码保存）
自动生成唯一文件名，包含时间戳、UUID、音色ID和文本片段
使用文件锁（fcntl.flock）保证索引文件并发写入安全

使用场景：音色设计 → 临时保存 → 用户确认 → 永久保存，完整闭环。

5.7 临时文件清理任务

backend/app/utils/temp_cleanup.py 提供定时清理机制，自动清除 storage/temp/ 目录下超过指定时间的过期文件。

核心实现：

def cleanup_temp_files(max_age_minutes: int = 10) -> dict:
    """清理过期的临时文件"""
    cutoff_time = time.time() - (max_age_minutes * 60)

    for file_path in TEMP_DIR.rglob("*"):
        if file_path.is_file() and file_path.stat().st_mtime < cutoff_time:
            file_path.unlink()
            stats["deleted_files"] += 1
            stats["freed_bytes"] += file_size

    cleanup_empty_dirs(TEMP_DIR)
    return stats  # { total_files, deleted_files, freed_bytes, errors }

关键特性：

默认保留时间 10 分钟，可灵活配置
递归清理所有子目录，并自动移除空目录
返回详细统计信息（文件数、删除数、释放空间）
提供 schedule_cleanup_task() 函数，方便接入 APScheduler 等定时调度框架

使用场景：音色设计、语音克隆等工具会在 storage/temp/ 生成中间文件，此任务确保临时文件不会无限堆积。

5.8 配置可视化功能

backend/app/utils/config_manager.py 和 backend/app/routers/config.py 提供配置可视化和管理功能。

核心特性：

配置优先级：配置文件 > 环境变量 > 默认值
配置文件路径：backend/storage/config.json
前端可视化界面：fronted/src/views/VisualConfig.vue

配置结构：

class LLMConfig(BaseModel):
    """对话模型配置"""
    openai_api_key: str = ""
    openai_api_base: str = "https://dashscope.aliyuncs.com/compatible-mode/v1"
    model_name: str = "qwen3.6-plus"

class TTSConfig(BaseModel):
    """语音播客配置"""
    dashscope_api_key: str = ""
    dashscope_base_url: str = "https://dashscope.aliyuncs.com/api/v1"
    dashscope_model_name: str = "cosyvoice-v3.5-plus"
    dashscope_asr_model_name: str = "qwen3-asr-flash"
    multimodal_api_url: str = "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions"
    multimodal_model_name: str = "qwen3.5-omni-plus"

API 接口：

方法	路径	功能
GET	`/api/config`	获取当前配置
PUT	`/api/config`	更新配置

使用场景：用户无需手动修改 .env 文件，可通过前端界面直接配置 API Key 和模型参数，配置自动持久化到 config.json。

5.9 提示词系统

backend/app/services/prompt.py 定义了播客 Agent 的完整系统提示词，采用模块化结构：

模块组成：

模块	职责
核心能力定位	音视频内容理解、播客脚本转化、音色设计、音频质量把控
工作方式	自主拆解复杂需求、智能编排工具调用、避免重复调用
工具调用规则	按需调用、意图先行、上下文感知、失败重试
沟通规范	自然语言交流、隐藏技术细节、描述播客作品
执行流程	内容识别 → 需求解析 → 说明意图 → 调用工具 → 处理结果 → 立即结束

音视频识别工作流：

音视频转播客工作流：
1. 内容识别：调用 qwen_multimodal_tool 或 qwen_asr_tool
2. 脚本整理：基于识别内容整理为播客脚本
3. 播客制作：音色设计 → 音频合成 → 混音 → 交付

工具使用策略：

语音识别：qwen_asr_tool（音频→文字）
多模态理解：qwen_multimodal_tool / qwen_combined_multimodal_tool（音视频→理解）
音色设计：qwen_voice_design（文本描述生成音色，保存在临时目录）
音色保存：save_voice（永久保存用户满意的音色，仅在用户明确要求时调用）
音频拼接：concatenate_audio（按顺序拼接音频片段）
背景音乐：select_background_music（智能选择匹配BGM）
专业混音：mix_audio_with_bgm（人声与BGM完美融合）

6. 前端样式更新说明

6.1 整体设计风格

前端采用现代化的深色主题设计，提供沉浸式的用户体验：

视觉特点：

深色背景：主色调为 #0a0a0a，配合渐变效果营造科技感
渐变装饰：使用青色（cyan）和蓝色的渐变色，增强视觉层次
半透明效果：卡片和按钮使用 rgba 半透明背景，呈现玻璃态效果
光晕效果：关键元素添加 box-shadow 光晕，突出交互焦点

动画交互：

平滑的过渡动画（transition-all duration-300）
卡片悬停时的微动效（hover:-translate-y-0.5）
按钮和图标的状态反馈动画

6.2 页面样式细节

播客列表页（PodcastList.vue）

卡片网格布局，支持响应式多列展示
每个卡片包含封面区域和信息区域
封面区域使用渐变背景和中心播放图标
悬停时卡片边框变色并添加阴影效果

可视化配置页（VisualConfig.vue）

表单式布局，分为"对话模型配置"和"语音播客配置"两个区块
每个配置区块使用图标+标题的组合标识
输入框支持密码可见性切换
保存成功后显示滑入式提示框

聊天 Agent 页（ChatAgent.vue）

顶部导航栏使用渐变 Logo 图标
对话区域支持空状态展示和消息列表
消息气泡区分用户和 AI 角色
底部输入区支持语音输入和文件上传

样式代码示例：

/* 深色主题容器 */
.chat-container {
  background-color: #1c1c20;
  background-image: linear-gradient(180deg, rgba(44, 255, 248, 0.06) 14.42%, rgba(44, 104, 255, 0.06) 100%);
}

/* 渐变文字效果 */
.welcome-title {
  background: linear-gradient(90deg, #4ea8ff 0%, #5eead4 100%);
  -webkit-background-clip: text;
  -webkit-text-fill-color: transparent;
}