平台使用说明
这本手册讲怎么用：后台每个按钮干什么、字段怎么填、出了问题看哪里。原理和部署见 README.md 与 deploy/README.md。
1. 三分钟理解这个系统
- 每个「主播」是一个独立进程，有自己的房间、人设、声音、知识库、节目单和背景音乐。
- 主播会不间断地讲（按节目单一句句播），中间有空档就用兜底内容（笑话/控场/话题）补上。
- 观众发的弹幕先进「判定器」：判断这条值不值得回、要不要查知识库；值得才插进去说一句，说完回到原来那句继续讲。
- 第三方可以用 API 让主播说话、把他们的弹幕灌进来、把 AI 的回复取回去（见 api.md、ingest.md）。
三种角色：
| 角色 | 用什么 | 需要 Key 吗 |
|---|---|---|
| 观众 | 观众端首页 /、直播间 /stage?anchor=<id> | 不需要 |
| 运营（你） | 运营后台 /admin | 配了 ADMIN_TOKEN 时要口令 |
| 第三方 | /v1/* 接口 | 每个主播一把专用 Key（推荐）或租户级 Key |
2. 打开后台
浏览器访问 http://<服务器IP>:8010/admin。
- 左边是主播列表，点一个开始配置；右上角有「使用文档」（就是这里）、「设置口令」、「观众端首页」。
- 如果提示"需要运营口令"：说明
.env里配了ADMIN_TOKEN，点右上角「设置口令」输入一次即可（浏览器会记住）。 - 顶部状态灯：绿色=服务正常；红色点开看
/api/health的诊断信息。
3. 页签一：主播参数
改完点最下方「保存」，需要重启才生效的项会有提示（涉及音色/人设的改动建议点「重启主播」）。
换音色怎么试：在「音色」下拉里选一个（清单里没有的复刻音色点「手动输入」填 ID）→ 点「试听」→ 浏览器直接播放一句样例（首次约 2~5 秒，之后同一句走缓存几乎立刻出声）→ 满意了点「保存并重启」。 试听用的是主播同一套豆包 TTS，听到的就是观众将听到的。
| 字段 | 说明 | 建议 |
|---|---|---|
| 主播昵称 | 观众端顶栏显示的名字 | 短、好记，别带符号 |
| 是否启用 | 关掉后不能开播 | 临时下线用「停播」就行，不用改这个 |
| 人设 system | 主播的性格与说话方式，{name} 会被昵称替换 | 写"你是谁 + 怎么说话 + 不许做什么"，200~600 字最稳 |
轮次档位 runtime.profile | 决定空闲节奏与内容比例（kb 偏知识、chat 偏聊天） | 讲干货选 kb，纯聊天选 chat |
音色 voice_type | 下拉选择（显示名称/场景）；旁边「试听」用当前音色合成一句样例 | 换音色要重启（点「保存并重启」最省事） |
| 语速/音高 | 0.9~1.1 之间微调即可 | 语速 >1.15 会显得赶；当前 bidir 模式下这两项不生效，只有 http 模式才发给供应商 |
| 空闲档位（秒） | 讲完内容后，隔多少秒插一段兜底内容 | 默认 8,20,45：越久内容越"轻" |
| 同条内容冷却（分钟） | 同一个笑话/话题多久内不重复 | 60 分钟比较合适 |
| 单条最长（秒） | 一句话最长播多久，超了会截断 | 30 秒 |
4. 页签二：知识库范围
这里决定「这个主播能查到哪些资料」。两种通道：
| provider | 走什么 | 什么时候用 |
|---|---|---|
none | 不接知识库，纯聊天 | 场控/陪聊型主播 |
fastgpt_app | 调 FastGPT 的只检索工作流应用（流程开始 → 知识库搜索 → 指定回复） | 想复用 FastGPT 里配好的检索参数、或对方已有应用 |
fastgpt_bridge | 直连 FastGPT 的向量库（只读） | 追求低延迟（热态 120~150ms），不经过应用层 |
字段：
| 字段 | 说明 |
|---|---|
provider | 上面三选一 |
相似度 similarity | 0.4~0.55。调低召回更多但更杂，调高更准但可能查不到 |
召回条数 limit | 3~8，进 prompt 的片段数；太多会稀释重点 |
检索模式 search_mode | embedding（语义）或 fullText（关键词） |
app_id | 只有 fastgpt_app 需要，填 FastGPT 应用的 id |
| 超时 ms | 检索超过这个时间就放弃（会退化成"我不确定"） |
三个按钮：
- 连通校验：立刻看链路通不通（向量库连上没、应用能不能调、返回几段）。
- 检索预览：输入一句观众可能问的话，看实际命中的片段和分数。调相似度就靠它，不用开播试。
- 文档列表：看这个知识库到底有哪些段落，确认资料有没有上传成功。
5. 页签三：本场直播
主播讲的内容来自「节目单」。
- 填本场主题（例如"新人最常问的十个问题"）、时长、小节数（0=自动）。
- 点「生成节目单」→ 后台会：按主题查知识库 → 列大纲 → 逐节检索 → 逐句写稿。有进度条，通常 1~3 分钟。
- 生成完逐段看：可以改标题、改脚本、删段；确认没问题点「审核通过」。
- 「让主播用这份」→ 热加载，不需要重启；如果正在播，会从当前段接着往下讲。
要点：
- 不生成节目单也能播：没有节目单时主播会走兜底内容（笑话/话题/控场）。
- 脚本里一句一行，太长的句子会被 TTS 切开，反而更自然。
- 审核这一步别省：
draft状态的段落不会被播出。
6. 页签四：运行态
实时看这个主播现在在干什么，也是手动干预的地方。
| 区块 | 能干什么 |
|---|---|
| 当前播出 | 阶段（开场/讲解/控场/讲笑话/回应弹幕）、在讲哪一段、第几句、循环了几轮、插播队列长度、判据统计 |
| 按钮 | 跳过本段 / 暂停 / 继续 / 重载节目单 |
| 插播一句话 | 输入文字，主播会立刻打断当前内容说这句，说完回到被打断的那句继续 |
| 背景音乐 | 开关、曲目下拉、两个音量滑块（不说话时 / 说话时）、实时实际增益 |
| API | 一句话看到开关状态与有效 Key 数（详细在第五个页签） |
判据统计怎么看：
- 看到：判定器收到了多少条弹幕；
- 回应：决定回应的条数；
- 查库：其中触发了知识库检索的条数。
"看到 20 条只回 3 条"是正常的——否则主播会变成复读机。
7. 页签五：API 接入（第三方用）
每个主播都有一把自己的钥匙和一个总开关。这把钥匙只能操作这一个主播，泄露也只影响这一个。
| 区块 | 说明 |
|---|---|
| API 开关 | 关掉后该主播所有 /v1/* 返回 403 api_disabled。只影响第三方接口，观众页和直播完全不受影响 |
| 接入信息 | anchor_id、API 地址、LiveKit 地址、OpenAPI 链接 |
| 专用 Key | 名称、前缀、权限范围、创建时间、最后使用时间、吊销按钮；「生成新 Key」后明文只显示一次，关掉就再也看不到，丢了只能吊销重建 |
| 接入示例 | 四条可直接复制的命令：查状态、让主播说话、换观众 token、发弹幕 |
| 弹幕源 | 该主播的平台直推源（ingest_url + secret），给"对方平台回调"用 |
安全底线：Key 不要放在网页前端。嵌直播间要么用这里的「换观众 token」流程（你的后端拿 Key 换 token，前端只拿 token），要么让对方后端调。
8. 为什么有些弹幕主播不回
判定器每条弹幕看三件事：需不需要回（need_reply）、要不要查库（need_kb）、急不急（urgency）。
| 情况 | 结果 |
|---|---|
| 纯表情、哈哈哈、太长 | 不回（继续讲自己的） |
| 正常提问 | 查库后插播，说完回到原句 |
| 礼物 / 关注 | 最高优先级，直接答谢 |
| 1 秒内进来几十条 | 转成"现在弹幕在刷：…（共 N 条）"的聚合摘要，主播回应整体气氛 |
| 队列满了 | 丢优先级最低的（普通闲聊），礼物和提问不丢 |
如果发现"该回的不回"：去运行态看判据统计，再调 config/agent_profile.yaml 里的判定阈值；或者用 ingest.md 里的联调清单逐条验证。
9. 背景音乐
- 曲库：三首内置合成曲（燃 / 舒缓 / 安静），也可以把自己的 mp3 放进
assets/bgm/。 - 压音：主播说话时自动压低（默认 0.22~0.30），不说话时抬起（0.85~0.90），渐变 350ms。
- 调音量：运行态页签的两个滑块，拖动即时生效，不用重启；想长期保存就点「应用并保存到配置」。
10. 常见故障排查
| 现象 | 最可能的原因 | 怎么处理 |
|---|---|---|
| 页面打不开 | 端口不对 | 平台是 8010，不是 8000 |
| 保存失败：需要运营口令 | .env 配了 ADMIN_TOKEN | 右上角「设置口令」输入一次 |
| 主播不说话 | 未开播 / 进程没起来 / 派单失败 | 运行态看阶段；不行点「重启主播」；再看服务 Get-Service LiveKitAnchor-* |
| 说话了但没声音 | 浏览器自动播放限制 | 直播间点一下「🔊 点击开始收听」 |
| 知识问答答非所问 | 相似度太低命中杂段落 | 用「检索预览」调 similarity |
| 第三方报 401 | Key 错/被吊销 | 后台 API 页签看 Key 状态，重建一把 |
第三方报 403 api_disabled | 该主播 API 开关被关了 | API 页签打开开关 |
| 第三方报 404 | 用了别的主播 id，或 Key 绑的是别的主播 | 核对 anchor_id 与 Key 的绑定关系 |
第三方报 409 anchor_not_live | 主播没在播 | 先「开播」再调 |
| 弹幕进去了但没回应 | 被判定为"不值得回" | 属正常；用礼物/提问测试，或看判据统计 |
| 公网能连上但没声音 | 媒体端口没转发（信令走 443，音频走 UDP/TCP） | 路由器转发 50000-50100/UDP + 7881/TCP 到本机；改完跑 scripts\enable-public-media.ps1 |
| 公网打不开 / 502 | 域名没解析、边缘没转发、平台没起 | 本机先测 http://127.0.0.1:8010/api/health；再看边缘那台 nginx |
| 公网页面还是旧的 | HTML 被边缘/CDN 缓存 | 平台已发 Cache-Control: no-store；若仍是旧的，去边缘/CDN 控制台刷新缓存 |
| 更新版本后要重新输口令 | 后台口令换了 | 右上角「设置口令」输入新口令（见 .env 的 ADMIN_TOKEN） |
11. 术语表
| 词 | 意思 |
|---|---|
| 主播 / anchor | 一个 AI 主播实例，有独立房间、人设、音色、知识库 |
| 值守号 / keeper | 平台用来"钉住房间"的内部参与者，观众看不到 |
| 派单 / dispatch | 通知某个主播进程进入某个房间开始工作 |
| 节目单 / show | 一场直播的段落与逐句脚本 |
| 判定器 / judge | 决定一条弹幕要不要回、要不要查库的那次 LLM 判断 |
| 门控 / gate | 判定器 + 队列 + 插播策略的合称 |
| 兜底内容 | 没有节目单或空闲时用的笑话/话题/控场话术 |
| 租户 / tenant | 一个第三方客户；有自己的主播、Key、用量 |
| 每主播 Key | 绑定单个主播的 API Key，只能操作那一个主播 |
| ingest 源 | 给第三方平台回调用的弹幕入口，有自己的 secret |