xiaozhi-esp32-server/docs/unified-fastapi-platform/decisions.md

# 架构与交付决策

本文件记录跨 PR 的稳定决策。普通实现 PR 不得顺手改变已接受决策；需要变更时，先提交新的
决策记录并说明替代关系。

## D001：统一代码库，按职责运行

- 状态：Accepted
- 决策：gateway、API、realtime 和 jobs 使用同一发布版本，但生产环境独立运行。
- 原因：REST、长连接、模型内存和定时任务的扩缩容及故障边界不同。
- 后果：允许 Lite 单 worker `all` 模式；生产容量不得由 Lite 推断。
- 重新评估：有证据证明单进程能够满足模型内存、多 worker 配置一致性和故障隔离。

## D002：只冻结外部行为

- 状态：Accepted
- 决策：设备、调用方、数据和已启用 Provider 的可观察行为保持；内部类、库、线程模型、目录和
  自调用方式可以重构。
- 原因：目标是保留现有功能，不保留实现偶然性。
- 后果：manager-web 与后端可以协同调整内部接口，但设备固件契约必须保持。
- 重新评估：产品所有者批准公开行为变更并提供迁移方案。

## D003：特征测试先于 realtime 重构

- 状态：Accepted
- 决策：M1 的黄金报文、虚拟设备和 Fake Provider 是 ASGI 会话重构的前置条件。
- 原因：xiaozhi-server 当前没有正式协议回归套件。
- 后果：不能以“代码更整洁”为由跳过旧行为记录。
- 重新评估：无。

## D004：应用服务替代内部 HTTP 自调用

- 状态：Accepted
- 决策：完整模式下 API 与 realtime 共享应用服务端口，不通过环回 HTTP 调用自己。
- 原因：减少密钥复制、网络重试和同进程/多进程语义差异。
- 后果：HTTP router 只负责协议适配，长连接不持有数据库 Session。
- 重新评估：跨语言或跨安全域部署成为明确需求。

## D005：Redis 承担配置版本事件，不承担事实来源

- 状态：Accepted
- 决策：数据库是完整配置事实来源；Redis 缓存有版本的快照并广播失效/控制事件。
- 原因：支持多 realtime worker 一致更新和 Java 回滚期兼容。
- 后果：配置事件必须可观测，worker 必须暴露当前版本。
- 重新评估：引入独立且受运维支持的消息系统。

## D006：Provider 按能力族迁移

- 状态：Accepted
- 决策：按 VAD/ASR、LLM/VLLM/Memory/Intent、TTS、Tools/MCP/IoT 四组迁移。
- 原因：限制 Agent 数量、统一契约并避免每个供应商重复搭建测试框架。
- 后果：只有出现供应商特有阻塞时才拆分单独工作包。
- 重新评估：某 Provider 需要独立进程或不可兼容的系统依赖。

## D007：集成分支承载全部开发 PR

- 状态：Accepted
- 决策：纯 Agent 阶段所有 PR 目标为 `refactor/unified-fastapi-platform`。
- 原因：项目所有者要求开发 PR 不进入主分支，并需要统一的长期集成点。
- 后果：PM 负责持续同步上游并在每个里程碑重跑消费者与协议清单。
- 重新评估：仅由项目所有者明确批准。

## D008：真实环境是独立验收门

- 状态：Accepted
- 决策：ESP32、真实 Provider、MQTT/RAGFlow 和目标网络只能在 M8 判定。
- 原因：Mock 和模拟不能证明硬件、供应商及生产网络事实。
- 后果：M7 可以形成 RC，但不能发布正式版本或描述为生产通过。
- 重新评估：所需真实资产已经安全接入自动化环境。

## 新决策模板

```text
ID / 日期 / 状态
背景：
决策：
备选方案：
后果：
验证方式：
重新评估触发条件：
Owner / 关联 PR：
```