Skip to main content
代表项目：端侧语音 Agent 智控平台。 配置看起来像「运维细节」，实际是控制面和会话面能不能长期一起演进的关节。字段一旦两边各写各的，后面所有联调都在还债。

​
两种跑法

本地模式
默认配置 + 本机覆盖。适合单机把语音链路跑通，不依赖智控台。密钥和现场覆盖放在不进版本库的地方。 智控台模式
服务启动时若配置了控制面地址，就去拉基座配置；设备建连后再拉「这一台」的智能体、模型、插件等差异项。运营在网页改完，设备侧按新组合装配。 两种模式共享同一套字段含义。不是两套平行宇宙。

​
优先级怎么定

实践上大致是：
  1. 默认可提交结构（大家能对齐的骨架）
  2. 控制面下发的基座与按设备差异（运营真相）
  3. 少量本地白名单覆盖（排障/灰度逃生口）
  4. 密钥与环境相关项永远不进默认可提交文件
本地覆盖要克制。覆盖项越多，现场越难解释「到底谁说了算」。我们只对少数模块选型类字段开逃生口，并写清谁优先。

​
按设备差异，不必整进程重来

建连后拉到的私有配置，往往只影响部分模块（模型、插件、是否走端到端等）。理想情况是：变了的重建，没变的复用，而不是每次改音色都把整条连接初始化重跑一遍。 模块没就绪时，先别放行用户语音。半初始化状态答出的内容，排障极难。

​
两种身份，别混

  • 运营人员：登录智控台，走用户会话与权限
  • 设备侧服务：用服务身份拉配置，和用户 JWT 不是一路
混在一起会出现怪事：要么设备接口暴露在用户权限模型里难收口，要么运营接口被机机凭证误用。分开之后，缓存、审计、限流也能按角色设计。

​
契约就是接口

控制面改了一个字段名，设备侧没改，表现就是「配置了不生效」。这种 bug 不报错，只沉默，特别耗时间。 规矩可以很土，但有用：
  • 改契约当改 API：双边 PR / 变更说明
  • 默认可提交样例保持可跑
  • 能加最小契约校验就加（哪怕先手动 checklist）
还没做到完善的自动化契约测试——这是明确欠账。人肉纪律能顶一阵，规模上来会漏。

​
和前端的关系

智控台前端不负责「发明」配置语义，只是编辑和展示。真正的契约在后端下发结构与设备侧读取结构之间。前端要做的是：团队上下文带对、别用全局隐式头写错队、权限按钮和后端字符串对齐。

​
相关