文章目录1. 项目概述1.1 项目背景1.2 核心功能1.3 技术栈选型1.4 应用场景2. 环境搭建2.1 系统要求硬件要求软件依赖2.2 安装步骤步骤一：安装基础工具步骤二：安装 Docker步骤三：安装 Node.js 和 npm步骤四：安装 Python 和 uv2.3 获取项目源码2.4 环境变量配置复制并编辑环境变量模板环境变量详解（`.env` 文件）WhatsApp 暴露模式详解2.5 创建工作区目录3. 项目结构解析3.1 目录结构总览3.2 关键文件详解📄 `AGENTS.md` — Agent 人格与指令定义📄 `docker-compose.yml` — 容器编排配置📄 `Dockerfile` — 镜像构建脚本📄 `.env.example` — 环境变量参考模板📄 `package.json` — WhatsApp Bridge 依赖📄 `pyproject.toml` — Talon Python 包配置4. 核心原理讲解4.1 架构设计概览4.2 核心组件原理4.2.1 WhatsApp Bridge 机制4.2.2 语音转录 (ASR) 管线4.2.3 Cron 定时任务机制4.2.4 Agent Harness 架构（LangGraph）5. 基础使用指南5.1 方式一：Docker 部署（推荐新手）完整操作流程启动后的日志输出示例扫码配对步骤（图文说明）发送第一条消息5.2 方式二：本地运行（无 Docker）完整操作流程本地运行的注意事项5.3 停止服务5.4 重新构建镜像6. 功能模块示例6.1 基础对话示例示例 1：简单问答6.2 文件操作示例6.3 语音消息处理示例6.4 Cron 定时任务示例6.5 自定义 AGENTS.md 示例6.6 LangSmith 追踪配置示例7. 最佳实践7.1 安全最佳实践✅ 推荐做法❌ 避免的做法7.2 性能优化建议ASR（语音转录）优化Docker 优化模型选择建议7.3 运维最佳实践数据备份日志管理健康检查7.4 开发调试技巧8. 常见问题解答Q1: QR 码扫描失败怎么办？Q2: 出现 "Session expired" 错误Q3: Agent 没有回复我的消息Q4: 语音消息没有被转录Q5: Docker 构建失败Q6: 如何更换 AI 模型？Q7: 如何查看 Agent 的思考过程？Q8: 如何让多人都能与 Agent 交互？Q9: 如何更新到最新版本？Q10: Token 用量过高怎么办？附录A. 快速命令参考卡B. 环境变量速查表1. 项目概述1.1 项目背景项目展示了如何将AI 智能体（Agent）与WhatsApp 即时通讯平台进行深度集成，实现一个可以自动接收、处理和回复 WhatsApp 消息的智能助手系统。⚠️ 实验性声明：Talon 是一个实验性运行时（Experimental Runtime），其 API 和功能可能随时发生变化或被移除。请关注官方更新。1.2 核心功能功能模块描述WhatsApp 桥接通过whatsapp-web.js库连接 WhatsApp Web，实现消息收发AI 对话引擎基于 Deep Agents 框架，支持多轮对话、工具调用、子代理委托语音转文字 (ASR)集成 NVIDIA Parakeet 模型，支持 WhatsApp 语音消息的本地转录