> ## 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.

# 配置与控制面：运营下发和本地调试怎么共存

> 双模式优先级、按设备配置、服务身份与用户登录分离、契约纪律。

代表项目：[端侧语音 Agent 智控平台](/projects/voice-agent-platform)。

配置看起来像「运维细节」，实际是控制面和会话面能不能长期一起演进的关节。字段一旦两边各写各的，后面所有联调都在还债。

***

## 两种跑法

**本地模式**<br />默认配置 + 本机覆盖。适合单机把语音链路跑通，不依赖智控台。密钥和现场覆盖放在不进版本库的地方。

**智控台模式**<br />服务启动时若配置了控制面地址，就去拉基座配置；设备建连后再拉「这一台」的智能体、模型、插件等差异项。运营在网页改完，设备侧按新组合装配。

两种模式共享同一套字段含义。不是两套平行宇宙。

***

## 优先级怎么定

实践上大致是：

1. 默认可提交结构（大家能对齐的骨架）
2. 控制面下发的基座与按设备差异（运营真相）
3. 少量本地白名单覆盖（排障/灰度逃生口）
4. 密钥与环境相关项永远不进默认可提交文件

本地覆盖要克制。覆盖项越多，现场越难解释「到底谁说了算」。我们只对少数模块选型类字段开逃生口，并写清谁优先。

***

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

建连后拉到的私有配置，往往只影响部分模块（模型、插件、是否走端到端等）。理想情况是：**变了的重建，没变的复用**，而不是每次改音色都把整条连接初始化重跑一遍。

模块没就绪时，先别放行用户语音。半初始化状态答出的内容，排障极难。

***

## 两种身份，别混

* **运营人员**：登录智控台，走用户会话与权限
* **设备侧服务**：用服务身份拉配置，和用户 JWT 不是一路

混在一起会出现怪事：要么设备接口暴露在用户权限模型里难收口，要么运营接口被机机凭证误用。分开之后，缓存、审计、限流也能按角色设计。

***

## 契约就是接口

控制面改了一个字段名，设备侧没改，表现就是「配置了不生效」。这种 bug 不报错，只沉默，特别耗时间。

规矩可以很土，但有用：

* 改契约当改 API：双边 PR / 变更说明
* 默认可提交样例保持可跑
* 能加最小契约校验就加（哪怕先手动 checklist）

还没做到完善的自动化契约测试——这是明确欠账。人肉纪律能顶一阵，规模上来会漏。

***

## 和前端的关系

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

***

## 相关

* [会话与打断](/notes/voice-session-interrupt)
* [经验总结](/notes/lessons-learned)


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