callflow-esl

callflow-esl 是 FreeSWITCH outbound ESL 通话业务编排服务，也是系统一的语音 runtime 与 系统二流程脚本的执行端。它接收 FreeSWITCH 回连，调用流式 ASR、TTS、NLU / Chat，向业务层 提供播报、识别、DTMF、外呼、桥接、会议和录音能力。

模块不负责系统二的名单、调度、权限和经营数据；这些职责属于 callout-server。

文档

• 配置参考
• HTTP 与运行时接口
• 深入文档导航
• 业务开发
• 组件 API
• 全双工语音通信
• 内置业务
• TTS 对接
• 场景示例
• 全仓服务目录

当前结构

apps/callflow-esl/
├── index.ts                  # 进程入口
├── config.toml              # 外置运行配置
├── src/
│   ├── business/            # 业务实现与注册
│   ├── llm/                 # OpenAI 兼容大模型客户端与语音流式调度器
│   ├── runtime/             # 通话 runtime、组件与会话生命周期
│   ├── http/                # 健康检查、外呼与控制面接口
│   ├── esl/                 # outbound ESL 协议层
│   ├── freeswitch/          # FreeSWITCH 控制与事件处理
│   ├── speech/              # ASR / TTS 适配
│   ├── db/                  # Bun 原生 SQL 数据访问
│   ├── config/              # 配置加载与校验
│   └── types/               # 全局类型定义
├── package.json
└── tsconfig.json

识别链路为 FreeSWITCH mod_audio_fork → WebSocket ASR → callflow-esl；播报链路为 callflow-esl → HTTP TTS → FreeSWITCH playback。

运行

在仓库根目录：

bun run dev:callflow-esl

或进入本目录：

bun run dev
bun run start
bun run typecheck
bun test

默认监听、健康检查和依赖服务以服务目录为准。远端 FreeSWITCH 联调时，freeswitch.callbackHost 必须是 FreeSWITCH 能访问到的本机地址。

构建

bun run build
bun run build:all

build 在类型检查后构建 Windows x64 独立可执行文件；build:all 在类型检查后构建 Windows、Linux x64 独立可执行文件和 Bun bundle 三种产物，并复制外置 config.toml 到 dist/。可执行文件默认读取同目录配置，也可通过 CALLFLOW_ESL_CONFIG_PATH 指定。

配置

最小联调需校准以下分组：

• eslServer：FreeSWITCH outbound 回连监听。
• httpServer：健康检查、外呼控制面接口及 token。
• freeswitch：ESL 地址、密码、回连地址和 originate 模板。
• audioFork：ASR WebSocket 地址与音频约定。
• tts.defaults / tts.use / tts.profiles：WAV 与流式播放策略（推荐 stream 搭配 audio_fork:// 原生 PCM 流，无阻塞且首包延迟极低；若使用 shout:// 则 use.conference 必须为 wav）。
• llm：全局大模型服务基础设施连接配置（endpoint、apiKey、model、requestTimeoutMs、maxRetries）。
• businessConfig：业务级下游依赖（支持自动继承全局 [llm] 或回退 [callout]）。
• db / redis：持久化与运行时状态。

字段、默认值、路径解析和完整示例只在配置参考维护。

快速验证

服务启动后先验证 HTTP 健康状态，再确认 FreeSWITCH originate 后能回连 outbound ESL。完整 命令、依赖顺序与收尾方式见开发测试手册。涉及识别或播报时， 同时检查对应 ASR / TTS 服务健康状态。

最低代码检查：

bun run typecheck
bun test

外呼 API

外呼请求、鉴权、响应与错误约定见 HTTP 与运行时接口。

业务路由

号码到业务的解析、业务注册方式和内置业务清单见 业务开发与内置业务。

注意事项

• src/runtime/ 是通用通话能力，具体业务优先放入 src/business/。
• 新增业务需在 src/business/index.ts 的 coreBusinesses / demo/index.ts 的 demoBusinesses 中显式导出；只新增文件不会自动生效（src/runtime/business-registry.ts 只消费汇总后的 allBusinesses，不需要手改）。
• config.toml 中不要写入机器专属绝对路径或真实生产凭据。
• 修改识别、播报、会议、桥接或清理逻辑后，至少执行类型检查和相关 bun test。
• 任务中启动的服务必须在结束前停止。
• 运维问题从故障排查进入。