> ## Documentation Index
> Fetch the complete documentation index at: https://dingguoliang.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 构建生产级 AI 系统的经验总结

> 配置、打断、权限、工具等短复盘；链到深潜笔记。

从 [端侧语音 Agent 智控平台](/projects/voice-agent-platform) 里摘出的短复盘。细节分别在 [配置与控制面](/notes/config-control-plane)、[会话与打断](/notes/voice-session-interrupt)。

***

**配置字段两边不一致**<br />表现是「后台改了，设备没反应」，还不报错。后来把契约当接口改：双边同步，默认可提交样例保持可跑。自动化契约测试仍欠着。

**说完要干等整段才播**<br />体感就是卡死。先查有没有阻塞活堵在收发包循环上，再谈换模型。流式、可打断、预热不挡首轮，这几条比抠提示词更先。

**打断后旧声音还在冒**<br />只停麦不够。轮次标记作废过期输出；工具也要有结束态。没有会话维度日志时，这种偶现基本只能重启碰运气。

**能进后台却看到别的团队数据**<br />菜单权限和数据范围是两件事。写操作带明确团队上下文，列表/检索在查询侧过滤，前端别靠全局隐式头。

**工具失败后模型空转**<br />短超时、可理解错误、步数护栏；长任务开始/结束对用户可见。阈值没有一劳永逸的数字，按真实工具耗时调。

**经典路径和端到端一起抢音频**<br />同一连接只活一条主路径。切换简单，测试矩阵会变贵。

**任一环失败就踢连接**<br />未绑定、拉配置失败、TTS 挂了，更该进引导或回落，而不是直接断开。本地模式还得能独立开发。

***

如果重来：第一周冻契约；语音从第一天按可打断和可降级设计；权限模型先于功能清单；用少量真实会话看首包和打断，再优化模型。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.