RabiPC 语音工作站

系统边界

浏览器麦克风 / 音频文件 / HTTP 客户端
  -> RabiPC 语音消息端
  -> RabiSpeech 本地 TTS / ASR，或用户显式启用的 API Provider
  -> 可选 RabiRoute Route / Agent
  -> RabiSpeech 主机级 FIFO 播放

RabiSpeech 的普通手动 TTS/ASR API 不接入 Agent。常驻麦克风完成非空转写后只向 POST /api/speech/messages 提交一次且不指定 Route；Manager 广播给所有已启用语音消息端的 Route。每个 Route 再独立执行 speechPushMode，因此同一段 ASR 可以同时进入多个人格，但主机只采集和识别一次。

本地 Provider 是默认安全基线。外部 API Provider 必须满足：配置显式启用；密钥或声线 ID 只来自点名环境变量；远端地址使用 HTTPS；不做失败后的隐式云端回退；local_only / relay_safe 如实反映启用状态。会议区分发言人应使用专门的 diarization 能力并返回 speaker turns，不得把普通短句 ASR 描述成已支持分人，也不得把说话人标签冒充已验证声纹身份。

活跃接口

底层本地服务：http://127.0.0.1:8781

• GET /health
• GET /v1/models
• GET /v1/models/<provider>/<model>
• GET /v1/capabilities
• GET /v1/events
• GET /v1/records
• GET /v1/speaker-profiles
• PUT /v1/speaker-identities
• PUT /v1/speaker-bindings
• POST /v1/audio/speech
• POST /v1/audio/transcriptions
• GET /v1/microphone/status
• POST /v1/microphone/start
• PUT /v1/microphone/settings
• POST /v1/microphone/stop
• GET /v1/playback/status
• PUT /v1/playback/settings
• POST /v1/playback/stop

RabiRoute Manager 同源代理：先调用已安装的 RabiRouteHost.exe --command status --json，使用当前应用代际返回的 managerBaseUrl；不得缓存或扫描端口。

• GET /api/speech/status
• GET /api/speech/events
• GET /api/speech/models
• GET /api/speech/personas
• GET /api/speech/records
• GET /api/speech/speakers
• PUT /api/speech/speaker-identities
• PUT /api/speech/speaker-bindings
• POST /api/speech/tts
• POST /api/speech/asr
• GET /api/speech/messages
• POST /api/speech/messages
• PUT /api/speech/microphone/settings
• POST /api/speech/microphone/reconcile
• PUT /api/speech/playback/volume

模型列表的每一项都要返回方法、endpoint、Content-Type、必填字段、可选参数和示例。调用方不得靠写死表格猜当前模型能力。

麦克风常驻转写

• 只在用户主动开启后获取浏览器麦克风权限。
• Route 的语音消息端总开关是该 Route 的主机 ASR 订阅真源；任意一个 Route 订阅时保持常驻监听，关闭一个只取消自身订阅，最后一个关闭才停止麦克风。
• 计算 PCM RMS，低于声音阈值时不触发新语段。
• 保留短前置缓冲，避免吞掉句首。
• 说话后按静音时长切段，同时设置最短与最长语段保护。
• ASR 请求顺序处理，避免多个 GPU 大模型争用显存。
• RabiSpeech 播放队列活跃时暂停麦克风触发，防止 TTS 回录形成反馈环。
• 常驻 ASR 每段只提交一次，由 Manager 广播给所有订阅 Route；语音服务页不得提供“投递 Route”或人工会话 ID，Route 页也不得重复主机 ASR/VAD 参数。
• 主机实时波形、五段链路、计数器、运行日志和最近转写只放在“语音服务 → ASR”；Route 的语音消息端只保留订阅开关、热投递/人格关键词、人格 TTS 摘要、职责说明、回复自动播放和单次广播说明。
• VAD/切句参数使用滑条加精确数值输入，当前统一覆盖录音阈值、转写阈值、自适应倍率、自适应余量、静音窗口、最短语段和最长语段。
• 手动 ASR 和直接人格 TTS 不要求 Route 或 Agent。

热投递与关键词唤醒

• speechPushMode 归 Route：hot 表示每个已完成、非空的 ASR 片段立即进入普通 start/steer 投递链；keyword 表示先记录，再决定是否唤醒。
• speechTriggerKeywords 归人格：放人格名、常用称呼和唤醒词，多条 Route 绑定同一人格时共用。
• keyword 模式下所有 ASR 仍写语音记录和人格会话账本；只有文本命中当前人格关键词才投递 Agent。
• 关键词为空时保持“只记录”，绝不暗中回退 hot。
• 公开 HTTP 终态必须区分 delivered、recorded、failed；recorded 是关键词未命中时的正常结果，不算投递失败。
• 普通消息端命中规则后默认直接投递。Heartbeat 的忙碌跳过和语音的热/关键词模式是两个独立、显式的例外。

人格与播放

人格资料属于 data/roles/<RoleId>。persona.md 是人格真相源；voice/voice-profile.json 是 TTS 模型、声线、语言、语速和表达指令的唯一配置真源；声音参考、台词索引、voice/cache/reference-audio/ 和 voice/cache/tts-audio/ 也归对应人格。只知道人格名时也能直接调用 TTS，Provider 声线 ID 必须通过该人格点名的环境变量解析，不能写进公开配置。没有解析到人格的直接 TTS 才使用 RabiSpeech 私有 fallback 缓存，不得伪装成人格资产。

RabiSpeech 是唯一播放所有者。所有 Route、会话、Agent、人格和模型的完成音频进入同一个 FIFO；不得让下游 worker 或浏览器另起并发播放器。

主机播放音量同样只归 RabiSpeech：范围 0–100，唯一运行时真源是 output/playback-settings.json，WebGUI 只能经 Manager 的滑条加精确输入更新。每条音频开始播放时冻结当时音量，因此修改从下一条开始播放的音频生效。Windows 使用 SoundFile / PortAudio 解码和播放，不能回退到会误读流式 WAV 头的 winsound。Windows 11 音量合成器按进程映像展示应用身份，因此安装/启动链必须使用带 RabiSpeech 版本资源的真实 runtime/RabiSpeech.exe。服务运行期间保持一个持续无声的共享输出会话：启动时把历史 Core Audio 倍率只归一一次到 100%，之后只保活、不回写，保证系统滑条一直可调。无声保活不得进入 FIFO，也不得触发麦克风防回流。

TTS 记录保留生成文本、Provider、模型、人格、会话、Route、播放状态、安全相对缓存引用和预计到期时间。音频缓存按每条记录自己的文件时间戳保留 24 小时，不按自然日整批删除；服务启动时扫描一次，之后只维护最早到期的一次性 cleanup deadline，新成品仅在更早到期时重排。预计到期仍不是硬实时承诺，因为进程停机和系统调度可能延后删除。Manager/WebGUI 只可暴露 POSIX 风格逻辑相对路径：人格记录使用 <RoleId>/voice/cache/tts-audio/<file>，fallback 使用 output/tts-audio/<file>，旧记录兼容单文件名；绝对路径、..、反斜杠越界必须省略。语音消息端触发的 Agent 回复必须走明确发送 API，由 Outbox 冻结当前 Route 的人格与语音参数后入队；Agent 不直接调用 worker。

双向上下文与说话人

• 所有消息端的统一人格会话真源是 data/roles/<RoleId>/conversation/current.jsonl，必须同时记录 inbound 与 outbound，并保存消息端、会话、发送方向和可用的说话人字段。
• current.jsonl 不设总条数上限。显式整理时，先检查是否存在超过 72 小时未活跃项；触发后把连续前缀中超过 24 小时可编辑窗口的完整输入集合归档到 archive/<n>~<m>.jsonl。
• 自动注入额度按人格、消息端和会话过滤，收发合计；每个消息端独立配置 0–200，默认 100。0 只关闭自动注入，不停止记录或删除历史。
• ASR 与成功 TTS 回传使用同一 speech 上下文额度，并尽量保留相同 sessionId，让 Agent 能理解前后问答。
• 说话人资料库是主机级共用真源。支持人工创建资料与把 sessionId + speaker label 绑定到某人；若没有经过验证的 matcher，必须明确显示自动声纹识别不可用。
• Agent 使用 PUT /api/speech/speaker-identities 原子查找/创建人物、合并别名并绑定当前会话标签；人工设置仍放在语音服务 ASR 页，两条入口共用同一资料库。
• 主机每个可提取分段的正式人格证据是稳定不透明的 voiceprintId（来自该主机 cluster）。speakerId 和 speakerSuggestionId 只供主机诊断，不能参与人格 isUser 分类或 AgentPacket 人格身份注入。
• validated=true 必须同时配置通过私有真实语料门禁生成的 validation_report_path；运行时必须核对目标模型 ID、模型 SHA-256、hard threshold、min margin 和目标引擎 policy 结果，不匹配时关闭正式自动认人。
• 人工标注区按未知/已知说话人折叠，并按分段标签或人物资料展示最近 10 句话；这只是辅助确认，不把聚类标签冒充生物声纹。
• 人格通过 GET /api/roles/:roleId/voice-transcripts 读取 conversation/current.jsonl 与自身 voice/voice-identities.jsonl 的派生联结。matchedCount 和 coverage summary 必须按完整筛选结果计算，不能被明细 limit 截断；统计不回写任何真源，也不作为主动智能轮询源。
• 自动声纹正式支持必须由真实同人/异人语料、显式校准 policy 和 --require-pass 报告证明。示例 policy 只是起点；未通过时保持 validated=false，不得把实验候选或未知聚类描述成已校准认人。

RabiLink 中转

Relay 只代理 allowlist 内的原始请求/响应，并使用通用应用 token。远端请求不能加载 Python 模块、修改模型 allowlist、下载模型或读取本机任意文件。只暴露规范化语音 API 和 OpenAPI，不暴露 worker 端口、模型路径或参考音频路径。

手机/眼镜 PCM 启动请求必须分开提交稳定 source_device_id 和临时 stream_id。前者进入 sourceDeviceId 并作为普通回复的唯一设备目标，后者只进入 sourceStreamId 用于诊断本次连接；不得把流 ID 写进 targetDeviceIds。

整个语音与主动智能链使用事件流：Android、PC worker 和 Manager 订阅 Relay SSE；RabiSpeech 通过 /v1/events 推送状态，Manager 通过 /api/speech/events 转发。cursor 只用于重连补漏，settle/重试/Heartbeat 只使用一次性 timer 事件；禁止固定间隔查询消息、重读账本、扫描配置或刷新状态。

动作安全

• 本地 TTS/ASR、模型查询和播放属于语音服务动作，不意味着 QQ/NapCat 外发。
• 常驻 ASR 的目标集合只由各 Route 的语音消息端订阅决定；显式 routeId 只保留给调试/兼容 API。外部消息发送仍经过 RabiRoute Action Gate。
• 不记录或公开 token、真实 Relay URL、私聊转写、录音、人格私有材料、模型权重和绝对路径。

验证

至少验证：

1. RabiSpeech /health 与模型列表。
2. 一个直接人格 TTS WAV。
3. 用该 WAV 完成一个真实 ASR 请求，并检查文字、speaker turns 和同会话记录。
4. Manager TTS/ASR 代理。
5. 播放状态和停止接口。
6. WebGUI 构建与语音消息端主要控件。
7. 两个 Route 同时订阅时，一段 ASR 只识别一次并返回两条 deliveries[]；关闭其中一个不停止麦克风，关闭最后一个才停止。
8. 没有订阅 Route 时返回 recorded + no_enabled_speech_routes；显式 routeId 调试调用继续兼容。
9. hot 返回 delivered；keyword 未命中返回 recorded；命中人格关键词返回 delivered；空关键词不回退热投递。
10. 人格双向账本能同时看到 ASR 与 TTS，TTS 写入对应人格的 voice/cache/tts-audio/，24 小时预计到期时间正确，WebGUI 不暴露绝对/越界路径，自动注入额度只影响注入不影响记录。