Home

Clarion

AI 外呼语音引擎，基于 Sonata 核心库构建。Sonata 提供与产品无关的实时语音对话能力（流式 ASR→LLM→TTS 管线、媒体状态机、WebRTC VAD、打断检测），Clarion 在此之上实现完整的电话外呼产品：FreeSWITCH ESL 呼叫控制、规则驱动的对话引擎、任务调度与通话后处理。

三个进程通过 Redis 解耦，各自独立部署和扩缩：

进程	入口	职责
API Server	cmd/clarion/	HTTP REST API，任务管理，通话状态和结果查询
Call Worker	cmd/worker/	消费任务队列，经 ESL 控制 FreeSWITCH 发起呼叫，运行实时对话
Post-Processing Worker	cmd/postprocessor/	消费通话完成事件，持久化记录，LLM 摘要，商机提取，通知

快速开始

前置要求：Go 1.25+、PostgreSQL 15+、Redis 7+、FreeSWITCH 1.10+（含 mod_audio_fork）、Task。

task local-up                              # 启动 PG + Redis + FreeSWITCH
task migrate-up                            # 数据库迁移
cp deploy/local/clarion-local.toml clarion.toml   # 填入 ASR / LLM / TTS 的 API Key

go run ./cmd/clarion -c clarion.toml       # API Server
go run ./cmd/worker -c clarion.toml        # Call Worker
go run ./cmd/postprocessor -c clarion.toml # Post-Processor

构建与测试：task build、task test、task lint、task bench；不依赖 FreeSWITCH 的端到端语音测试用 task gen-test-audio 和 task pipeline-test。完整说明见 README。

文档导航

设计文档按关注点拆分，建议按顺序阅读；源文件在仓库 design/ 目录，本 Wiki 与之同步。

页面	内容
架构设计总纲	为什么选 Go、工程原则、技术栈选型、配置统一、测试策略
目标与约束	项目目标、当前阶段定义、约束条件、设计原则
总体架构	六层架构、模块边界、Go interface、领域适配设计
实时会话运行时	流式管道、媒体状态机、VAD / 打断 / 超时、goroutine + channel
通信与媒体层	FreeSWITCH 集成、音频流路径、Call Worker 架构
对话引擎与规则	业务状态机、规则引擎、LLM 职责边界、线索分级
数据模型与存储	核心表设计、Redis 用途、对象存储、事件日志
部署与运维	进程部署、技术选型、成本度量、合规与风险
租户体系与认证	多租户模型、认证授权、数据隔离

技术栈速览

组件	选型
语言	Go
HTTP	net/http（标准库路由）
数据库	PostgreSQL（pgx/v5 + sqlx），golang-migrate 迁移
Redis	go-redis/v9
WebSocket	coder/websocket
配置	TOML（knadh/koanf/v2）
日志	slog（标准库）
AI Provider	通义听悟 ASR、DeepSeek LLM、DashScope TTS、Qwen3-Omni Realtime
测试	testing + testify，golangci-lint

名字来源

Clarion 是中世纪的一种高音小号，音色清亮，用于传令与号召。借用这一意象，为外呼场景取名：主动发声、清晰传达。