dsh-xiaoai-bridge

配置项说明

设置页在 DSH 里，分 8 个区，顺序就是下面表格的顺序。页面上的联动（比如关掉「连续对话」后「退出词」收起来）只影响显示，值本身保留。

保存怎么走：设置页保存时提交逐项操作（POST /plugin/xiaoai/config 的 ops，形如 {"op":"set"|"unset","path":[...]}，「重置为默认」就是 unset）。写入前会严格校验，不合法直接 400 并说明哪一项不对（dsh-xiaoai-bridge config: ），值不会写进去。

坏值怎么活：运行时读配置会逐条和默认值比，越界或类型不对就回退默认值，并按坏值集合去重只告警一次：dsh-xiaoai-bridge: unusable config repaired with defaults: = ()。插件不会因为一个坏值起不来，但设置页里仍然显示你填的那个值——日志里出现这一行，就说明它没生效。

配置怎么生效

配置有三条通道，改之前先看这一项走哪条：

通道	覆盖哪些设置	什么时候生效
渲染出的 /config.py	唤醒词、对话保持时长、连续对话、退出词、唤醒应答、退出应答、兜底播报文本、会话键、设备名、语音合成方式、豆包 App ID 与音色/音频格式/流式/语速、语音识别后端、行动准则与语音消息附加提示	写盘即热重载：桥接器每秒轮询它的 mtime，一般 1 秒内生效
桥接器子进程的环境变量	日志级别、静默启动、本地 API 服务的开关与监听地址/端口、音箱名称与音箱地址、音箱连接鉴权（开着时写 DSH_XIAOAI_TOKEN），以及两枚凭据	进程启动时快照：改完要重启桥接器（设置页只重渲染配置，不会替你重启）
只影响插件自己的会话	会话工作区、Agent 预设、任何会话都能让小爱说话、播报与回复器那一组	新会话按新值组建；已经在跑的会话保留它启动时的预设与路由

渲染出的 config.py 是覆盖层，不是模板：它把仓库里的 bridge/config.py 当模块加载，然后只覆盖上面那几个键。文本框留空表示这一项不写，桥接器继续用自己的默认值（而不是写一个空值进去）。插件还故意不碰这些键：dsh.rule_prompt（自动播放与连续对话用的那条约束）、openai.*、asr.doubao.*，以及 vad / kws / audio_input / xiaoai 这些段——要调就直接改仓库里的 bridge/config.py，改完同样会被热重载，见音箱侧的调参。

凭据怎么放：两枚秘密都存在 DSH 的凭据库里，插件启动桥接器时才解析出来放进子进程环境（XIAOAI_API_TOKEN、DOUBAO_ACCESS_KEY）。本地 API 服务的访问令牌在设置页里只填凭据名（字母或下划线开头的标识符，默认 XIAOAI_API_TOKEN），真值由插件在第一次启动时生成并写进凭据库；豆包访问令牌反过来——凭据名固定在 doubaoAccessKeyCredential 里（默认 DOUBAO_ACCESS_KEY），令牌本身直接粘在卡片的密码框里，由插件写进凭据库。同一枚访问令牌在「音箱连接鉴权」开着时还会以 DSH_XIAOAI_TOKEN 交给桥接器，用来校验拨上 4399 的设备。所以设置表和渲染出的 config.py 里都没有明文令牌。换凭据名或换令牌之后都要重启桥接器，新值才会被带上。

两种语音合成方式：

语音合成方式	写进配置	实际用谁	什么时候选
小爱原生（默认）	xiaoai	音箱自带的合成	不想配豆包凭据，音色由设备决定
豆包语音合成	doubao	火山引擎的豆包语音合成	想要固定音色、复刻音色或统一语速

选中的值一定会写进渲染出的 config.py，不存在「留空跟随模板」。以前的「朗读音色」（ttsSpeaker）已经删掉：它和这个开关本来是同一件事的两套入口——桥接器的旧规则就是看那个音色值是不是 xiaoai 来决定走哪条路。豆包音色现在只在选「豆包语音合成」时由「豆包音色」给，插件不再写 dsh.tts_speaker，桥接器模板里那个默认值原样留着。

注意：写一个桥接器不认识的值不会报错：它只记一条 Unknown tts_provider=...，然后按音色回退。「没报错」不等于「接上了」。

基本

配置项	类型	默认值	说明
启用插件 enabled	布尔	开	总开关。关掉后插件不再注册工具与技能，桥接器以 DSH_ENABLE=0 启动（xiaoai_speak 会直接回「插件已在设置中禁用」）。
音箱名称 deviceName	文本	小爱音箱	显示用的名字，会出现在会话标题里，同时作为 XIAOAI_DEVICE_NAME 传给桥接器。它不参与设备绑定：设备键只看音箱地址，改它不会换会话。
音箱地址 deviceHost	文本	192.168.1.191	音箱在局域网里的地址，作为 XIAOAI_DEVICE_HOST 传给桥接器，插件按它区分设备、决定这条语音进哪个会话。它不是插件去拨号的地址（是设备自己连 4399），填错的表现是语音落到别的设备键、会话归属错乱，而不是连不上音箱。
音箱连接鉴权 speakerAuth	开关	开	4399 是设备拨进来的音频通道，开着时要求客户端带上与「本地 API 服务」里「访问令牌凭据名」同一枚令牌，否则握手被拒（桥接器日志报 401）。多数音箱上跑的官方客户端不带请求头，把设备侧 /data/open-xiaoai/server.txt 写成 ws://:4399?token= 就行；coderzc 那个 fork 也可以在设备上加 OPEN_XIAOAI_TOKEN。改完要重启桥接器（它在子进程启动时快照）。关掉它等于允许同一局域网里任何主机往音箱注音、触发「已连接」并顶掉正在用的音箱槽位——只有设备实在带不了令牌时才关。
会话键 sessionKey	文本	agent:main:dsh-xiaoai-bridge	桥接器侧的会话标识（形如 agent::），只喂桥接器（日志前缀、按会话覆盖音色）。DSH 侧的会话由插件按音箱设备区分，所以改这里不会换掉音箱对话所在的会话。
会话工作区 sessionCwd	工作区选择	不指定（跟随默认工作区）	音箱会话归到哪个工作区分组，agent 的工作目录也是它。宿主只服务有绝对 cwd 的会话，所以这里是选择器而不是文本框。改完对新会话生效。
音箱会话的 Agent 预设 agentPreset	文本	xiaoai	音箱那个会话按哪个预设组建。留空用宿主默认预设；填了但没装不是错误：这次回落宿主默认，并留一条 agent-preset-missing 诊断。已经在跑的会话保留它创建时的预设。

唤醒与语音

配置项	类型	默认值	说明
唤醒词 wakeKeywords	多行文本	你好肥鱼	每行一个；逗号、顿号也算分隔符。命中即进入 DSH 对话。它同时写进桥接器的 wakeup.keywords（喂给唤醒词模型）与 dsh.wakeup_keywords（路由到 DSH 后端）。改完 1 秒内热生效。别把全角逗号写进词里：它会被当分隔符切掉，那个词就永远唤不醒。
对话保持时长（秒） wakeupTimeout	整数 1-600	20	一次唤醒之后，这次对话保持多久。
连续对话 continuousConversation	布尔	关	关：一句话一次唤醒。开：一次唤醒可以接着说下一句，直到静默超时或说出退出词。这一项即使关掉也会照写进配置，免得桥接器模板里的默认值反过来压过设置页。
语音识别后端 asrBackend	枚举	sense_voice	另两个选项是 paraformer 与 fire_red_asr。选完后按「后端 + 量化 + 模型目录」重建识别器；选了本机没装模型的后端不会把音箱弄哑：继续用已装好的识别器，只警告一次，并记一条 asr-model-unavailable。识别语言固定为中文（auto 会把短音频判成日文，插件不暴露这个开关）。
语音合成方式 ttsProvider	枚举	xiaoai（小爱原生）	两个选项：小爱原生 / 豆包语音合成，区别见上面那张表。

豆包语音合成

这一组只在「语音合成方式」选「豆包语音合成」时显示，选「小爱原生」时整组隐藏（值还留着，切回「豆包语音合成」就原样回来）。它不折叠，也没有自己的标题——上面那个选项已经写着「豆包语音合成」，再给一组标题只是重复。只有在想要豆包音色（固定音色、复刻音色、统一语速）时才要配。

去哪拿：在火山引擎控制台开通豆包语音合成、创建应用，拿到 App ID 与 Access Token（App ID 与 Access Token 的位置见控制台使用 FAQ https://www.volcengine.com/docs/6561/196768 ，可选音色见音色列表 https://www.volcengine.com/docs/6561/1257544 ）。App ID 是普通设置项；Access Token 直接粘在设置页的「豆包访问令牌」里，由插件写进 DSH 凭据仓，不进设置文件、不进日志。

配置项	类型	默认值	说明
豆包 App ID doubaoAppId	文本	空	控制台里这个应用的 App ID。留空表示沿用桥接器模板里的占位值（等于没配）。
豆包访问令牌	密码输入框（写进 DSH 凭据）	未设置	粘贴控制台里的 Access Token，点「保存令牌」由插件写进 DSH 凭据仓的 DOUBAO_ACCESS_KEY——凭据名固定在设置项 doubaoAccessKeyCredential 里（默认 DOUBAO_ACCESS_KEY），页面上不再让人填。令牌不进设置文件、不进草稿、不进日志，卡片上只显示「已配置 / 未配置」，旁边有「清除」。保存或清除后要重启桥接器：插件启动桥接器时把凭据解析成环境变量 DOUBAO_ACCESS_KEY，桥接器环境变量优先、取不到才回退渲染配置里的 tts.doubao.access_key。
豆包音色 doubaoSpeaker	文本	空	用豆包时朗读的音色 ID（例如 zh_female_vv_uranus_bigtts）；留空沿用桥接器配置里的默认音色。桥接器按音色前缀自动判定资源类型；复刻音色填控制台给的 S_xxxxxxxx。
豆包音频格式 doubaoAudioFormat	枚举	沿用配置（留空）	可选：沿用配置 / 自动 / PCM / MP3 / OGG Opus。留空表示不写，用桥接器模板里的 pcm；「自动」按文本长短在 PCM 与 MP3 之间挑。音箱本地播放用 PCM 首音最快。
边合成边播放 doubaoStream	布尔	开	开：边合成边播，首音更快；关：整段合成完再播。这一项即使关掉也会照写进配置。
豆包语速 ttsSpeed	数字 0.5-2	1	豆包朗读速度。只对豆包生效，小爱原生不看它。

注意：App ID 或缺访问令牌时，桥接器会明确报 Doubao TTS credentials are not configured，不会静默换回小爱原生。

应答与兜底

配置项	类型	默认值	说明
唤醒应答 wakeupReplyText	文本	肥鱼来了	唤醒词命中时先念的一句。留空表示不写，用桥接器模板默认（同样是「肥鱼来了」）。
退出应答 exitReplyText	文本	肥鱼走了	连续对话结束时念的一句。
退出词 exitKeywords	多行文本	退出、停止、再见	每行一个，说出任意一个就结束这次对话。只在「连续对话」打开时出现在页面上，值仍然保留。
兜底播报文本 fallbackText	文本	连不上电脑，请稍后再试	桥接器还在跑、但联系不上插件时念的话：DSH 没在运行，或者插件路由不可达。

播报与回复器

音箱念出来的话不是模型的原始回复，而是先经过一次「回复器」调用做口语化润色（关掉「自动念出回复」之后，这一组里只有「任何会话都能让小爱说话」与「审批等待提示语」还有意义）。回复器是一次独立的模型调用，默认跟随该会话的模型路由。

配置项	类型	默认值	说明
自动念出回复 autoSpeak	布尔	开	模型这一轮没调 xiaoai_speak 时，把回复正文交给回复器润色后念出来。关掉后只有模型主动调工具才出声，回复器那一组选项会收起来（值保留）。审批等待提示语不受这个开关影响：审批是工具卡在屏幕上等人处理，这一句照念（见下一行）。
任何会话都能让小爱说话 speakFromAnySession	布尔	关	关：xiaoai_speak 只在音箱发起的会话里可用，工具与技能也只注册在那一层。开：桌面与网页会话也能调它。
播报字数上限 spokenMaxChars	整数 40-2000	300	一条播报最多多少字；超了先让回复器精简一次，仍然超就截断。
审批等待提示语 approvalText	文本	需要你到电脑上确认一下	工具卡在宿主审批流上时念的固定一句，关掉「自动念出回复」也照念（审批意味着有工具正等你到电脑上点一下）。审批请求的正文永远不会被念出来。
回复器模型 replyerProvider / replyerModel	下拉（DSH 模型目录）	跟随会话默认模型	从这台 DSH 已配置的模型里挑一个给回复器用；选项按 provider 分组，选中后写成「provider/model」两个键。选「跟随会话默认模型」等于把两项留空、不指定路由。选项直接读 DSH 的模型目录（读不到、目录为空、当前值已不在目录里，卡片都会写明并给「重试」）。切换只对回复器即时生效——语音会话的 agent 路由在会话创建时就定了，要重启 DSH 才换。
回复器参考轮数 replyerHistoryTurns	整数 0-50	6	回复器能看到最近多少轮对话（只用于润色，不影响主会话的上下文）。
回复器失败提示语 replyerFailureText	文本	回复器调用失败	回复器连续失败时改念这一句，免得把没润色的原文念出去。

人格与提示词

这一组都是文本提示词，改完立刻影响下一次播报。「人格设定」「说话风格」与「输出限制」只进回复器请求（只管念出来的话）；「行动准则」与「语音消息附加提示」由桥接器追加在每条语音输入后面（影响音箱会话里模型怎么答）。

配置项	类型	默认值	说明
人格设定 personality	多行文本	内置身份句	回复器的身份设定，默认是「你是一个通过小爱音箱和用户说话的语音助手，你的回答会被直接念出来。」改成别的内容后，回复器请求里会多出一行「关于你自己：…」。
说话风格 replyStyle	多行文本	内置风格句	回复器怎么措辞，默认是「用日常、口语化的说法讲出来，就像对着用户说话一样。」
行动准则 behaviorStyle	多行文本	内置准则	渲染成配置里的「行动准则：…」一段，由桥接器追加在每条语音输入后面：约束回答的写法——别用 Markdown、代码、emoji、颜文字、括号动作与 URL，一般 50 字以内、最多不超过 300 字，只有确实要逐字念出的内容才调 xiaoai_speak。提醒「回复会被念出来」的是下面那条「语音消息附加提示」。
输出限制 outputLimits	多行文本	内置限制	写进回复器请求的硬性约束：只输出要念的话，不要 emoji、颜文字、Markdown 标记、括号里的动作或心理描写、URL、@ 提及，不要换行；长度是两档要求——一般 50 字以内、一两句话讲完，只有确实需要长回复时才展开，最多不超过 300 字。
语音消息附加提示 voiceRuleText	多行文本	内置提示	桥接器把它追加在每条语音输入后面，告诉模型这条消息来自音箱、回复正文会被念出来。留空表示不写，用桥接器模板默认。

桥接器进程

配置项	类型	默认值	说明
随插件启动桥接器 autoStart	布尔	开	DSH 启动时顺手把桥接器进程拉起来。关掉后需要桥接器的调用会失败（xiaoai_speak 不会替你拉起进程）。
静默启动 silentStart	布尔	关	开：桥接器连上音箱时不再出声（不发连接提示、不播启动提示音）。只在「随插件启动」打开时出现。
日志级别 logLevel	枚举	INFO	桥接器进程的日志级别：DEBUG / INFO / WARNING / ERROR。走环境变量，改完要重启桥接器。
桥接器目录 bridgeDir	文本（高级）	空	桥接器源码目录；留空用插件包内的 bridge/。指到自己的 checkout 时，虚拟环境与模型都在那边。
Python 解释器 pythonPath	文本（高级）	空	跑桥接器的解释器；留空用 /.venv/Scripts/python.exe（Windows）。桥接器要求 Python 3.12 以上。

本地 API 服务

这一组管桥接器进程里那个 HTTP API Server，插件用它播报与探活（xiaoai_speak 走的就是它）。默认只监听本机。

配置项	类型	默认值	说明
启用本地 API 服务 apiServerEnabled	布尔	开	关掉后桥接器不提供 API，xiaoai_speak 会直接回「桥接器 API Server 已在设置中关闭」。
监听地址 apiServerHost	文本	127.0.0.1	API Server 的监听地址。保持 loopback 最安全：改成 0.0.0.0 等于把音箱的播放与唤醒交给整个局域网。
监听端口 apiServerPort	整数 1-65535	9092	API Server 的端口。
访问令牌凭据名 apiServerTokenCredential	文本（标识符）	XIAOAI_API_TOKEN	存放访问令牌的 DSH 凭据名，不是令牌本身。插件用它给 /asr 做 bearer 门禁，并把它交给桥接器。改完要重启桥接器，环境变量在进程启动时快照。

安全边界

能触达 POST /plugin/xiaoai/asr 的调用方，等于拿到了这个 agent 的输入通道：请求正文会被当成一句用户消息。这条路径上插件不做任何语义拦截，也没有给语音轮次单独收窄工具集——一句话得到的权限，等于它落进去的那个会话的权限。

机械保障只有两条：/asr 的 bearer 门禁（fail closed：没配置令牌一律 503，bearer 对不上回 401，且不看来源地址），以及宿主既有的审批流（审批前音箱先念固定的一句提示，审批请求的正文永不念出，决定由宿主做）。其余插件路由（/config、/bridge/*、/data/wipe）按设计不做鉴权：它们和 DSH 在同一台机器、同一个信任边界里。要更强的约束只能靠会话与 agent 层（预设、审批策略、沙箱）。

最小可用配置

{
  "enabled": true,
  "deviceName": "小爱音箱",
  "deviceHost": "192.168.1.191",
  "wakeKeywords": "你好肥鱼",
  "wakeupTimeout": 20,
  "continuousConversation": false,
  "agentPreset": "xiaoai",
  "asrBackend": "sense_voice",
  "ttsProvider": "xiaoai",
  "autoSpeak": true,
  "fallbackText": "连不上电脑，请稍后再试",
  "autoStart": true,
  "silentStart": false,
  "logLevel": "INFO",
  "apiServerEnabled": true,
  "apiServerHost": "127.0.0.1",
  "apiServerPort": 9092,
  "apiServerTokenCredential": "XIAOAI_API_TOKEN"
}

这是设置页里最常改的一组键。页面保存时提交的是逐项 ops，这份 JSON 是同一组键的可读写法；要用 POST /plugin/xiaoai/config 提交就放进 patch 字段（patch 与 ops 不能同时给）。

配置怎么生效

配置有三条通道，改之前先看这一项走哪条：

通道	覆盖哪些设置	什么时候生效
渲染出的 /config.py	唤醒词、对话保持时长、连续对话、退出词、唤醒应答、退出应答、兜底播报文本、会话键、设备名、语音合成方式、豆包 App ID 与音色/音频格式/流式/语速、语音识别后端、行动准则与语音消息附加提示	写盘即热重载：桥接器每秒轮询它的 mtime，一般 1 秒内生效
桥接器子进程的环境变量	日志级别、静默启动、本地 API 服务的开关与监听地址/端口、音箱名称与音箱地址、音箱连接鉴权（开着时写 DSH_XIAOAI_TOKEN），以及两枚凭据	进程启动时快照：改完要重启桥接器（设置页只重渲染配置，不会替你重启）
只影响插件自己的会话	会话工作区、Agent 预设、任何会话都能让小爱说话、播报与回复器那一组	新会话按新值组建；已经在跑的会话保留它启动时的预设与路由

渲染出的 config.py 是覆盖层，不是模板：它把仓库里的 bridge/config.py 当模块加载，然后只覆盖上面那几个键。文本框留空表示这一项不写，桥接器继续用自己的默认值（而不是写一个空值进去）。插件还故意不碰这些键：dsh.rule_prompt（自动播放与连续对话用的那条约束）、openai.*、asr.doubao.*，以及 vad / kws / audio_input / xiaoai 这些段——要调就直接改仓库里的 bridge/config.py，改完同样会被热重载，见音箱侧的调参。

凭据怎么放：两枚秘密都存在 DSH 的凭据库里，插件启动桥接器时才解析出来放进子进程环境（XIAOAI_API_TOKEN、DOUBAO_ACCESS_KEY）。本地 API 服务的访问令牌在设置页里只填凭据名（字母或下划线开头的标识符，默认 XIAOAI_API_TOKEN），真值由插件在第一次启动时生成并写进凭据库；豆包访问令牌反过来——凭据名固定在 doubaoAccessKeyCredential 里（默认 DOUBAO_ACCESS_KEY），令牌本身直接粘在卡片的密码框里，由插件写进凭据库。同一枚访问令牌在「音箱连接鉴权」开着时还会以 DSH_XIAOAI_TOKEN 交给桥接器，用来校验拨上 4399 的设备。所以设置表和渲染出的 config.py 里都没有明文令牌。换凭据名或换令牌之后都要重启桥接器，新值才会被带上。

两种语音合成方式：

语音合成方式	写进配置	实际用谁	什么时候选
小爱原生（默认）	xiaoai	音箱自带的合成	不想配豆包凭据，音色由设备决定
豆包语音合成	doubao	火山引擎的豆包语音合成	想要固定音色、复刻音色或统一语速

选中的值一定会写进渲染出的 config.py，不存在「留空跟随模板」。以前的「朗读音色」（ttsSpeaker）已经删掉：它和这个开关本来是同一件事的两套入口——桥接器的旧规则就是看那个音色值是不是 xiaoai 来决定走哪条路。豆包音色现在只在选「豆包语音合成」时由「豆包音色」给，插件不再写 dsh.tts_speaker，桥接器模板里那个默认值原样留着。

注意：写一个桥接器不认识的值不会报错：它只记一条 Unknown tts_provider=...，然后按音色回退。「没报错」不等于「接上了」。

最小可用配置

{
  "enabled": true,
  "deviceName": "小爱音箱",
  "deviceHost": "192.168.1.191",
  "wakeKeywords": "你好肥鱼",
  "wakeupTimeout": 20,
  "continuousConversation": false,
  "agentPreset": "xiaoai",
  "asrBackend": "sense_voice",
  "ttsProvider": "xiaoai",
  "autoSpeak": true,
  "fallbackText": "连不上电脑，请稍后再试",
  "autoStart": true,
  "silentStart": false,
  "logLevel": "INFO",
  "apiServerEnabled": true,
  "apiServerHost": "127.0.0.1",
  "apiServerPort": 9092,
  "apiServerTokenCredential": "XIAOAI_API_TOKEN"
}

这是设置页里最常改的一组键。页面保存时提交的是逐项 ops，这份 JSON 是同一组键的可读写法；要用 POST /plugin/xiaoai/config 提交就放进 patch 字段（patch 与 ops 不能同时给）。