🔥 一个面向实时语音与多模态智能体落地的 Pipecat 工程化发行版。
🚀 在保留 upstream 核心能力的同时，补齐了私有化改造常用的配置治理、命名规范、健康检查、发布安全门禁与迁移文档。
⭐ 目标是把“示例可跑”升级为“仓库可持续维护”。
非官方声明（Non-Affiliation）
however-yir/pipecat-engine是基于pipecat-ai/pipecat的社区维护衍生发行版，与上游项目及其权利主体不存在官方关联、授权背书或从属关系。
商标声明（Trademark Notice）
Pipecat及相关项目名称、Logo 与商标归其各自权利人所有；本仓库仅用于说明上游来源与兼容关系。
命名说明（Naming）
仓库名是pipecat-engine，用于承载 fork 的工程化治理、Issue、CI 与发布记录。Python 包发布名是howeverpipecat-ai，用于在包索引中与 upstream 的pipecat-ai区分；安装后 import 路径仍保持pipecat.*，降低迁移成本。
- 1. 项目定位
- 2. 适用人群
- 3. 与 Upstream 的关系与边界
- 4. 本仓核心改动概览
- 5. 项目文档导航
- 6. 快速开始（5 分钟路径）
- 7. 配置说明（含 DB / Redis / Ollama）
- 8. 本地健康检查
- 9. 依赖与发布策略
- 10. 命名规范与兼容策略
- 11. 质量门禁与 CI
- 12. 测试与检测命令
- 13. 与原版差异清单
- 14. 迁移指南（Upstream -> however）
- 15. 常见故障排查清单
- 16. 90 天路线图
- 17. 贡献方式
- 18. 许可证与分发说明
pipecat-engine 不是对 upstream 的“简单镜像”，而是发布 howeverpipecat-ai 的工程化发行分支：
- 保留 Pipecat 在实时语音与多模态 pipeline 方面的核心能力。
- 增强本地化部署与私有化改造的高频薄弱环节。
- 为二次开发提供可复制、可审查、可持续维护的目录与规范。
- 想基于 Pipecat 做长期迭代项目的个人开发者。
- 需要将语音 Agent 接入内部服务（DB / Redis / Ollama / Telemetry）的团队。
- 希望沉淀“可部署 + 可回归 + 可交接”技术资产的课程或实验项目。
- 希望保留 upstream 能力同时建立自有发布标识与治理规则的维护者。
| 项 | 说明 |
|---|---|
| 上游仓库 | pipecat-ai/pipecat |
| 当前 fork | however-yir/pipecat-engine，面向工程化落地的 Pipecat 发行版 |
| 包发布名 | howeverpipecat-ai，与仓库名不同是为了在包索引中表达 fork 发行身份 |
| 当前定位 | 保留 upstream 实时语音与多模态 pipeline 能力，补齐私有化部署常用的配置、健康检查、安全扫描、质量门禁与迁移文档 |
| 同步策略 | 以 upstream main/正式发布为同步来源，按月度窗口或安全修复需要合并；每次同步后运行新增回归、健康检查、命名 lint、secrets scan 与依赖安全扫描 |
| 兼容边界 | 保持 pipecat.* import、核心 pipeline API 与许可证信息；fork 增量优先放在 env.however.example、scripts/however_*、docs/however_* 等独立文件中 |
- 不删除 upstream 许可信息。
- fork 增量优先放在独立文件（
env.however.example、scripts/however_*、docs/however_*）。 - 尽量避免对 upstream 主流程做破坏性重写。
- 对兼容性影响提供迁移路径与过渡期。
- 包发布名改为
howeverpipecat-ai。 - 仓库首页、源码、Issue 与 Changelog 统一指向
however-yir/pipecat-engine。 - 文档中保留
howeverpipecat-ai作为 Python 包名，不再把它当作仓库名使用。 - 新增仓库元信息脚本：
scripts/however_set_repo_metadata.sh。
- 新增标准命名
OllamaLLMService。 - 旧名
OLLamaLLMService保留兼容，并给出DeprecationWarning。 - 新增命名检查脚本：
scripts/however_naming_lint.py。
- 新增
env.however.example。 - 新增
configs/services.example.yaml。 - 新增运行时配置模块：
src/pipecat/utils/however_runtime_config.py。 - 新增健康检查模块与脚本：
src/pipecat/utils/however_health.pyscripts/however_service_health.py
- 新增敏感信息扫描：
scripts/however_secrets_scan.sh。 - 新增依赖安全扫描：
scripts/however_dependency_security_scan.sh。 - 新增 CI 工作流：
.github/workflows/however-quality.yaml.github/workflows/however-dependency-security.yaml
- 发布工作流增加依赖安全检查前置门禁。
| 文档 | 目的 |
|---|---|
docs/however_series_map.zh-CN.md |
系列仓库关系与定位 |
docs/however_versioning.zh-CN.md |
版本命名与发布策略 |
docs/however_naming_conventions.zh-CN.md |
类名/脚本/环境变量命名规范 |
docs/however_dependency_strategy.zh-CN.md |
核心与扩展依赖边界、升级策略 |
docs/however_python_compatibility.zh-CN.md |
Python 3.11/3.12 兼容说明 |
docs/however_dependency_conflicts_faq.zh-CN.md |
依赖冲突 FAQ |
docs/however_config_change_audit_checklist.zh-CN.md |
配置变更审计清单 |
docs/however_migration_from_upstream.zh-CN.md |
上游迁移指南 |
docs/however_troubleshooting_checklist.zh-CN.md |
故障排查 checklist |
docs/however_roadmap_90days.zh-CN.md |
90 天演进路线图 |
docs/however_projectization_suggestions.zh-CN.md |
60 条改造建议清单 |
- Python
3.11+（建议3.12） uv包管理工具
# 1) 克隆
git clone https://github.com/however-yir/pipecat-engine.git
cd pipecat-engine
# 2) 安装基础开发依赖（不要求全量 extras）
uv sync --group dev
# 3) 复制本地模板
cp env.however.example .env.however.local
# 4) 离线健康检查（不依赖真实外部服务）
uv run python scripts/however_service_health.py --skip-network --json
# 5) 跑 fork 新增回归
uv run pytest tests/test_however_runtime_config.py tests/test_however_health.py这条路径先验证 fork 发行版的本地配置与健康检查，再启动 upstream 兼容的最小语音 Agent 示例。
# 安装基础开发依赖
uv sync --group dev
# 复制 fork 运行时配置模板；health check 默认读取 .env.however.local
cp env.however.example .env.however.local
# examples 仍沿用 upstream 的 .env 约定；填入 OPENAI_API_KEY / DEEPGRAM_API_KEY / CARTESIA_API_KEY
cp env.however.example .env
# 离线健康检查，不访问真实 DB / Redis / Ollama / Telemetry
uv run python scripts/however_service_health.py --skip-network --json
# 最小 fork 回归测试
uv run pytest tests/test_however_runtime_config.py tests/test_however_health.py
# 启动最小语音 Agent 示例前安装所需 transport / STT / TTS extras
uv sync --group dev --extra runner --extra webrtc --extra deepgram --extra cartesia
uv run python examples/getting-started/06-voice-agent.py -t webrtc启动后打开 http://localhost:7860/client/，点击 Connect 进行本地语音对话。
本仓将 fork 运行时配置统一为 HOWEVER_ 前缀，避免与 upstream 服务 API Key 变量混淆。
| 变量名 | 说明 | 示例 |
|---|---|---|
HOWEVER_DB_URL |
业务数据库连接 | postgresql://hc_user:***@postgres.internal.example:5432/howeverpipecat |
HOWEVER_REDIS_URL |
缓存或会话存储连接 | redis://redis.internal.example:6379/0 |
HOWEVER_OLLAMA_BASE_URL |
Ollama 网关地址 | http://ollama.internal.example:11434/v1 |
HOWEVER_TELEMETRY_ENDPOINT |
可观测性上报地址 | https://telemetry.internal.example/pipecat/events |
HOWEVER_STARTUP_CHECK_TIMEOUT_MS |
启动检查超时（毫秒） | 1500 |
HOWEVER_STRICT_STARTUP_CHECKS |
检查失败是否阻断 | true |
- 进程环境变量
.env.however.local- 代码默认占位值
- URL 会校验 scheme + host。
- timeout 会校验范围。
- 非法值会抛出明确错误，归类为
config_error。
# 离线模式
uv run python scripts/however_service_health.py --skip-network --json
# 联网模式
uv run python scripts/however_service_health.py --json输出字段统一包含：env、region、status、latency_ms、fault_type。
fault_type 分类：
config_errornetwork_errorauth_errorunknown_error
- Core：最小可运行依赖。
- Extras：按服务能力拆分按需启用。
详细策略见 docs/however_dependency_strategy.zh-CN.md。
- 统一规则：
vX.Y.Z-however.N - 详细见
docs/however_versioning.zh-CN.md
- 每月固定窗口执行依赖升级、回归对比与发布决策。
- 使用
OllamaLLMService。 - 环境变量前缀使用
HOWEVER_。 - fork 脚本统一
however_*前缀。
OLLamaLLMService保留兼容，迁移期内可继续使用。- 建议在 1-2 个版本周期内迁移到
OllamaLLMService。
python scripts/however_naming_lint.py- 命名检查：
scripts/however_naming_lint.py - 敏感信息扫描：
scripts/however_secrets_scan.sh - 依赖安全扫描：
scripts/however_dependency_security_scan.sh - fork 运行时测试与离线健康检查
.github/workflows/however-quality.yaml.github/workflows/however-dependency-security.yaml- 发布流程增加 dependency security scan 前置步骤。
# fork 新增测试
uv run pytest tests/test_however_runtime_config.py tests/test_however_health.py
# 健康检查（离线）
uv run python scripts/however_service_health.py --skip-network --json
# 命名 lint
python scripts/however_naming_lint.py
# 敏感信息扫描
bash scripts/however_secrets_scan.sh
# 依赖安全扫描（发布前）
bash scripts/however_dependency_security_scan.sh| 差异项 | 文件 / 能力 | 作用 | 兼容说明 |
|---|---|---|---|
| 包发布名 | howeverpipecat-ai |
与 upstream pipecat-ai 做包索引层面的发行区分 |
import 仍保持 pipecat.* |
| 配置模板 | env.however.example、configs/services.example.yaml |
收敛 DB / Redis / Ollama / Telemetry 等本地化部署变量 | 不替换 upstream env.example |
| fork 脚本 | scripts/however_* |
承载命名检查、仓库元信息、健康检查、依赖安全扫描、secrets scan 等治理动作 | 独立脚本，避免改写 upstream 主流程 |
| fork 文档 | docs/however_* |
记录版本策略、命名规范、依赖策略、迁移指南、排障 checklist 与路线图 | 作为补充文档，不覆盖 upstream 文档结构 |
| Health check | src/pipecat/utils/however_health.py、scripts/however_service_health.py |
输出统一的 env、region、status、latency_ms、fault_type，支持离线检查 |
默认可 --skip-network，适合作为 CI smoke test |
| Secrets scan | scripts/however_secrets_scan.sh |
发布前扫描常见密钥、token 与本地配置泄漏风险 | 与 .gitignore / 示例 env 配合使用 |
| Ollama 命名 | OllamaLLMService |
修正类名大小写，并保留 OLLamaLLMService 兼容别名 |
旧名会给出迁移提示 |
| 依赖安全门禁 | scripts/however_dependency_security_scan.sh、.github/workflows/however-dependency-security.yaml |
发布前检查依赖风险 | 作为 fork 门禁补充 |
| 协议补充 | LICENSE.HOWEVER |
说明 fork 补充分发边界 | 保留 upstream LICENSE |
| 运维模板 | .github/ISSUE_TEMPLATE/however_runtime_bug.yml、.github/RELEASE_NOTES_TEMPLATE.md |
标准化运行时问题和发布说明 | 与原有模板并存 |
快速迁移：
- 将依赖从
pipecat-ai替换为howeverpipecat-ai。 - 保持 import 为
pipecat.*（无需大规模改代码）。 - Ollama 类名逐步迁移到
OllamaLLMService。 - 复制并填写
env.however.example。 - 执行健康检查与新增测试。
详细见 docs/however_migration_from_upstream.zh-CN.md。
请按 checklist 执行，不建议跳步：
- 配置检查（变量完整性与格式）
- 依赖检查（是否完整安装）
- 运行时检查（离线 -> 联网）
- 回归检查（测试 + lint + scan）
详细清单见 docs/however_troubleshooting_checklist.zh-CN.md。
- 第 1-30 天：稳定性治理
- 第 31-60 天：性能与回归基线
- 第 61-90 天：生态兼容与发布流程固化
详细路线图见 docs/however_roadmap_90days.zh-CN.md。
- 先阅读
CONTRIBUTING.md与本 README 差异清单。 - 涉及 fork 增量能力时，优先放在独立目录并补测试。
- 提交 PR 时建议写清：变更模块、影响范围、回归命令、回滚方案。
- 运行时问题模板：
.github/ISSUE_TEMPLATE/however_runtime_bug.yml - 发布说明模板：
.github/RELEASE_NOTES_TEMPLATE.md
- Upstream 许可证：
LICENSE（BSD-2-Clause） - Fork 补充说明：
LICENSE.HOWEVER
本仓用于工程开发、测试和部署实践。生产使用前，请自行完成安全、合规与稳定性评估。