mirror of
https://github.com/xinnan-tech/xiaozhi-esp32-server.git
synced 2026-07-25 00:23:53 +08:00
83 lines
3.6 KiB
Markdown
83 lines
3.6 KiB
Markdown
# 架构与交付决策
|
||
|
||
本文件记录跨 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：
|
||
```
|