rabiroute-voice-workstation

Files (1)

• SKILL.md

SKILL.md (first lines)

# RabiPC 语音工作站

## 系统边界

```text
浏览器麦克风 / 音频文件 / 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、私聊转写、录音、角色私有材料、模型权重和绝对路径。

From vb2250158/RabiRoute, MIT.

More from vb2250158/RabiRoute