快速开始
小云直播助手是一套多平台直播自动运营系统:一个后端服务带动 电脑客户端 + 6 个浏览器端(中控台 / 云控台 / 大屏 / 后台 / 官网用户中心 / 本帮助中心),支持抖音、视频号、快手等 9 个直播平台的直播间管理、自动发评/回评/弹窗、素材编排与多直播间大屏。
1. 启动服务
cd m2/server
set DB_MODE=demo && node src/index.js # Windows 演示模式(内存存储)
# 生产模式:set DB_MODE=mssql 后启动,连接 SQL Server(见「数据库与备份」)
2. 登录
演示内置账号:demo / demo123456(演示模式重启后数据复位)。
3. 三步跑通第一场自动直播
- 绑定直播平台账号(v0.32.0 起登录成功自动检测:客户端内嵌登录后自动向平台确认,确认通过即自动写入账号并同步真实直播间,无需手动点「已完成登录」;同步也可以手动触发);
- 在「素材中心」准备语音组、关键词组、商品,组建直播场景;
- 点「开始运营」——语音口播、评论回复、商品弹窗即按场景循环执行。
2.2 注册与登录
小云直播助手的账号体系分两处:用户中心(/user/,浏览器,负责注册与账号自助管理)与电脑客户端(桌面端,负责日常直播运营登录)。当前版本支持用户名注册与账号密码登录;手机号注册、微信扫码登录标注为规划中,详见下方能力对照。
2.2.1 如何注册?
| 注册方式 | 具体操作 | 操作示意 |
|---|---|---|
| 用户名注册 已上线 |
【第一步】打开电脑客户端登录弹窗点「立即注册」,或在用户中心 /user/ 登录卡片切到「注册」页签;【第二步】填写账号(字母开头 3~20 位,可用字母 / 数字 / _ . @ -)、昵称与手机号(选填)、密码(8~32 位、含字母和数字)、图形验证码并勾选协议后提交。注册成功后自动登录默认开通试用版 |
用户中心 · 账号登录
登录注册
用户名(≥3 位)
密码(≥8 位)
昵称(选填)
注册并登录
|
| 手机号注册 规划中 |
规划形态:【第一步】点击「立即注册」;【第二步】填写手机号、短信验证码与登录密码后提交。 当前版本未接入短信通道,请先使用用户名注册。需同步新增:验证码下发与校验、手机号唯一性校验、短信服务商接入与费用核算。 |
立即注册(规划中)
手机号
短信验证码 获取验证码
登录密码
立即注册
|
| 微信扫码注册 规划中 |
规划形态:【第一步】点击右上角「扫码登录」;【第二步】使用微信扫码并关注公众号完成注册。 当前未接入微信开放平台,无扫码能力。需先完成公众号认证、开放平台应用创建与 UnionID 打通。 |
扫码登录(规划中)
二维码区域
微信扫码并关注公众号
|
/user/。客户端注册需填图形验证码,成功后直接进入工作台。不想登录时,点登录弹窗右上角「✕」或底部「暂不登录,退出客户端」即可退出客户端(按 Esc 同效,v0.22.1 起)。2.2.2 如何登录?
| 登录方式 | 具体操作 | 操作示意 |
|---|---|---|
| 账号密码登录 已上线 |
在电脑客户端登录页(或用户中心 /user/ 的「登录」页签)输入用户名与密码,点击「立即登录」。演示环境内置账号: demo / demo123456;运营后台账号:admin / admin123456。连续失败 5 次锁定 10 分钟接口限流 10 次/分钟 不想登录时:点登录弹窗右上角「✕」或底部「暂不登录,退出客户端」,按 Esc 同效(v0.22.1 起)。
|
小云直播助手
用户名
密码
立即登录
还没有账号?去注册 →
|
| 微信扫码登录 规划中 |
规划形态:在登录页右上角切换为「扫码登录」,使用微信扫码即可登录;可再切回账号密码登录。 与「微信扫码注册」共用同一套开放平台能力,需一并评估。 |
扫码登录(规划中)
二维码区域
扫码后自动登录
|
2.2.3 账号安全规则(当前实现)
| 规则 | 说明 |
|---|---|
| 账号规则 | 字母开头、3~20 位,仅限字母、数字与 _ . @ -;查重不区分大小写,保留名(如 admin)不可注册 |
| 密码强度 | 8~32 位,须同时含字母与数字、不含空格、不得与账号相同;注册接口限流 5 次/分钟/IP |
| 注册防刷 | 图形验证码必填:答案只存服务端内存、不随响应下发,5 分钟有效、一次性消费、同图错 3 次作废 |
| 登录失败锁定 | 同一账号连续失败 5 次后锁定 10 分钟(可通过环境变量 LOGIN_LOCK_THRESHOLD / LOGIN_LOCK_MINUTES 调整),剩余 1–2 次时提示还剩几次 |
| 账号状态 | 被禁用的账号(status ≠ 1)登录返回「账号已被禁用」,需运营后台恢复 |
| 登录态 | JWT 令牌,客户端存于本地;注册成功即建立会话(等同登录);令牌无效或过期时自动退出并回到登录页 |
| 演示模式复位 | DB_MODE=demo 重启后账号数据回到初始态(demo 恢复),新注册账号会消失——重跑案例脚本可恢复演示数据 |
2.2.4 能力对照(对标智播魔方)
下表用于明确当前版本与对标产品的差距,便于排期决策:
| 能力 | 小云直播助手 | 缺口与依赖 |
|---|---|---|
| 用户名注册 | 已上线 | 入口:用户中心 /user/ 与电脑客户端登录弹窗 |
| 手机号 + 验证码注册 | 未实现 | 需短信服务商(阿里云/腾讯云短信)、验证码存储与防刷、手机号唯一索引 |
| 微信扫码注册 | 未实现 | 需公众号认证 + 微信开放平台应用(网站应用)、UnionID 打通 |
| 账号密码登录 | 已上线 | 含失败锁定与接口限流,已优于对标基本要求 |
| 微信扫码登录 | 未实现 | 同上,与扫码注册共用能力,建议一并开发 |
| 忘记密码 / 重置 | 未实现 | 依赖短信或邮箱通道;当前只能由运营后台重置 |
| 客户端内注册入口 | 已上线 | v0.22.0 起:客户端登录弹窗内置注册表单(含图形验证码) |
| 登录页可关闭 / 退出 | 已上线 | v0.22.1 起:右上角「✕」、底部「暂不登录,退出客户端」、Esc 三种方式退出客户端 |
访问入口一览
服务启动后(默认 http://localhost:3000),所有端通过单域名路径访问:
| 路径 | 端 | 用途 |
|---|---|---|
/desktop | 电脑客户端(Electron 加载,也可浏览器打开) | 日常运营主入口:看板、直播间、素材中心、场景、大屏 |
/console | 中控台 | 总览全部直播间运行状态与各模块四宫格面板 |
/cloud | 云控台 | 语音预生成任务、多机云控下发 |
/wall | 多直播间大屏 | 投屏监控所有直播间的实时数据流 |
/admin | 运营后台 | 用户、套餐订单、平台管理、数据看板 |
/user | 官网 / 用户中心 | 产品介绍与账号自服务 |
/help | 帮助中心 | 本页 |
/dl/tts/*.wav | 语音文件 | 语音库合成结果(供播放器/推流取用) |
常查路径:服务端代码 m2/server/src/;各浏览器端源码 m2/<端名>/index.html;客户端工程 m2/desktop/(界面在 m2/desktop/app/index.html,改界面无需重新打包);案例脚本 m2/server/scripts/;实测断言 m2/server/tests/*-realtest-report.json;案例报告 reports/。
直播间管理
- 绑定平台账号:「平台账号」页选择平台(抖音/视频号/快手/小红书/拼多多/美团/京东/支付宝,淘宝暂 pending)。v0.31.0 起绑定只保存凭据,不再生成任何直播间——直播间只来自平台真实会话同步(v0.32.0 起登录成功自动检测并同步),没有真实数据就显示空列表。
- 添加直播间(v0.23.0 起,电脑客户端):点「+ 添加直播间」→ 在宫格里选平台 → 客户端内嵌打开该平台登录页 → 登录完成后点「已完成登录」,系统自动写入平台账号记录并同步直播间到列表;同平台已有账号会先确认再新增。浏览器环境(未装客户端)会引导用系统浏览器打开登录页,登录后回来点「已完成登录」同样生效。
- 直播间状态:直播中 / 已下播 / 异常,可手动开播、下播、刷新状态。
- 评论流:进入直播间详情可查看实时评论(含系统 bot 的自动回复)与运行报表。
src/adapters/ 实现对应平台的授权、房间拉取、评论通道与经营指标接口,路由层零改动。自动运营(发评 / 回评 / 弹窗)
- 自动发评:配置话术组按频控间隔发送公屏评论(同直播间最小间隔 800ms,自动打散防风控)。
- 自动回评:命中关键词组的评论自动回复;AI 开启后走大模型生成回复,关闭或超时降级为模板话术。
- 商品弹窗:场景 popConfig 按间隔轮换弹出商品。只能弹出已挂小黄车(商品与直播间存在映射)的商品;每 600 秒(可配)轮换一次。
- 报表:每个直播间实时统计 评论接收 / 组回复 / 自动互动 / 语音播放 / 弹窗 / 循环轮次。
素材与编排中心(M10 / M11)
桌面端「素材中心」分组包含四个模块,核心设计是 「改一处处处生效」:场景只引用素材的组 ID,运行时引擎展开成员——修改组内容后所有引用它的场景自动更新。
语音库与语音组
语音库
- 输入文字一键合成语音(演示为 mock TTS 按估时生成 WAV;真实环境在
config.tts配置阿里云/火山/azure/GPT-SoVITS)。 - 也支持直接上传录音文件。
- 时长要求:单条语音 5 秒 ~ 3 分钟——这是编排系统的调度边界,案例脚本内置校验(估时 + 落库真实时长双重校验),越界即构建失败。
- 时长估算口径:约 4.5 字 / 秒,也就是 5 秒 ≈ 23 字、3 分钟 ≈ 810 字。切条时按自然句边界合并:短钩子 5–12s,讲解段 15–30s。
- 删除语音会自动从引用它的语音组中摘除。
- 试听:列表里每条语音可「▶ 试听」,编辑弹窗内也有同一个「▶ 试听」(再点一次变成「⏹ 收起试听」)。试听前会先探测音频能否访问,把 服务不可达 / 音频文件缺失 / 解码失败 分开提示——不会把「服务没启动」误报成「音频坏了,要重新生成」。
- 换音频(重新生成 / 录音 / 上传)时若正在试听,会先停掉旧音频,完成后 自动切到新音频继续播放,改完立刻能听到效果。
- 每条语音可「编辑」:改名称/标签/文案与音色,并提供 🔄 重新生成 / 🎙 录音替换 / 📤 上传替换 三种换音频方式。
- 编辑弹窗底部显示该条语音的 服务端磁盘路径、相对项目路径、在线访问地址,均可一键复制——方便备份音频、核对文件是否落盘、排查「音频加载失败」时确认文件到底在不在。
- 音频文件名按「文本 + 音色」的内容哈希生成:重新生成后文件名与路径会变化,弹窗内会自动刷新;相同「文本 + 音色」再次提交会复用已有文件,不重复占磁盘。
语音组
- 多条语音打包成组,支持 顺序(sequence)/ 随机(random) 两种播放模式与组内间隔。
- 场景步骤
say只引用voiceGroupId,引擎运行时逐条播报。 - 改组成员/顺序后,所有引用场景下一轮生效;复用脚本会自动 PUT 同步成员。
关键词组
- 触发词 + 回复 抽成组:3 种匹配方式(包含/完全/正则)× 3 种回复类型(文字/语音库/文字+语音)。
- 冷却秒数:同一关键词组两次回复的最小间隔,避免刷屏。
- 上线前可「试打」:输入模拟评论文本验证是否命中及回复内容。
- 场景的
keywordRules只存组 ID;停用的组禁止绑定,重复绑定自动去重。
直播商品库
- 从直播间同步:一键拉取各直播间小黄车商品(幂等,重复点只更新)。
- 手工录入:自建商品(标题/价格/原价/分类/标签/平台)。
- 批量操作:按分类/标签/平台筛选后批量启停、批量调价(比例 / 增减额 / 设为)。
- 映射视图:查看商品与各直播间小黄车的对应关系(roomProductId)。
v0.31.0 起服务端不再预设任何小黄车商品:直播间商品只来自平台真实数据或运营手动上架(
POST /live-rooms/:roomId/goods/add)。没有挂车商品时,自动讲解与弹窗会如实跳过并记录原因,不会编造商品。直播场景
场景 = 一场直播的完整编排脚本,勾选素材一键组装,循环闭环执行。
步骤类型
| 类型 | 作用 | 关键参数 |
|---|---|---|
say | 播报一个语音组 | voiceGroupId(组引用,热更新) |
interact | 发一条引导评论 | text(如"扣【想要】上福利") |
explain | 讲解商品并弹窗 | productRef(自动映射当前直播间平台商品,映射不到跳过) |
wait | 停顿 | seconds(1–3600) |
运行规则
- 步骤按序执行,走完一轮自动回到第一步循环(一轮语音实播通常 20–30 分钟)。
- 每轮循环重新读取场景定义——运行中改脚本即生效。
- 悬空引用(如组已删除)给出提示但不阻断保存。
- 一个直播间同一时间只能运行一个自动化会话;重新开播前会自动停止旧会话。
云控与大屏
- 云控台 /cloud:批量语音预生成任务(提前把话术合成好,开播即播)、云控指令下发。
- 多直播间大屏 /wall:投屏监控所有直播间实时数据(评论流、运行指标、弹窗),适合团队值守。
- OBS 联动:支持 OBS 28+ 内置 WebSocket(默认 4455),未配置时走演示模拟执行。
AI 设置
AI 网关统一封装外部大模型(不自建),用于智能回评与话术生成:
| 配置 | 环境变量 | 说明 |
|---|---|---|
| 厂商 | AI_PROVIDER | 通义千问 / DeepSeek / 豆包(OpenAI 兼容接口),mock 为演示 |
| 密钥 | AI_API_KEY | 只在服务端配置,客户端永不接触 |
| 模型 | AI_MODEL | 按厂商填写 |
- 内置敏感词过滤(命中直接拦截);
- 按用户套餐每日限额,超量或 API 超时自动降级为关键词模板回复,直播不中断。
案例脚本一览(3 个平台)
每个案例都是一条命令:按话术文案构建全部素材(语音库切条 → 语音组 → 关键词组 → 商品 → 场景)并自动开播。脚本幂等可重跑,改文案后重跑即同步,不需要在界面手工准备素材。
| 案例 / 平台 | 建场开播命令 | 语音库切条 | 实测脚本(用例数) |
|---|---|---|---|
| 抖音 · AI 电商干货场 | node scripts/douyin-ai-case.js --verify 60 |
20 段(DG· 前缀) | node scripts/douyin-case-realtest.js(8) |
| 视频号 · 容县沙田柚产地直发场 | node scripts/shipinhao-pomelo-case.js --verify 60 |
27 条(SP· 前缀) | 用 --verify 60 观察运行数据 |
| 快手 · 广西芭乐产地直发场 | node scripts/kuaishou-guava-case.js --verify 90 |
33 条(KS· 前缀) | node scripts/kuaishou-guava-realtest.js(9) |
命令均在 m2/server 目录下执行;--verify N 表示开播后额外观察 N 秒运行数据(循环 / 组播 / 语音 / 组回 / 互动 / 弹窗)。实测脚本按真实节奏运行、不加速不造数据,结果落 m2/server/tests/*-realtest-report.json。
reports/ 目录。实战案例:抖音 · AI 电商干货场(无限画布)
对标《直播案例(1).txt》60–90 分钟纯干货涨粉场,一键构建:20 段话术按时间轴转语音库 → 8 个语音组 → 5 个关键词组 → 贴牌算力商品 → 22 步循环闭环场景,并自动开播。
cd m2/server
node scripts/douyin-ai-case.js --verify 60 # 构建 + 开播 + 观察 60 秒
- 幂等可重跑:素材按名复用,变更自动同步,旧话术自动清理;
- 开播前自动停止目标直播间旧会话;
- 改话术直接改
scripts/douyin-ai-case.js中 SEGMENTS 后重跑。
详见 docs/小云直播助手-抖音自动直播案例-无限画布AI电商干货场.md。
实战案例:视频号 · 容县沙田柚产地直发场
对标《容县沙田柚直播案例(1).txt》六大环节,按直播需求把话术切成 27 条 5 秒 ~ 3 分钟的语音库切条(估时 + 实测双重校验,越界构建失败),按开场/卖点/试吃/逼单/答疑(随机穿插)/收尾组成 6 个语音组,配套 5 个关键词组、整箱+礼盒两商品、19 步循环场景。
cd m2/server
node scripts/shipinhao-pomelo-case.js --verify 60 # 构建 + 开播 + 观察 60 秒
详见 docs/小云直播助手-视频号案例-容县沙田柚产地直发场.md。
实战案例:快手 · 广西芭乐产地直发场
对标《广西芭乐直播带货完整文案.md》,按直播需求把话术切成 33 条 5 秒 ~ 3 分钟的语音库切条(估时 + 落库真实时长双重校验,越界即构建失败),组成 6 个语音组、6 个关键词组、2 个商品、19 步循环场景,并自动开播到快手直播间。
| 语音组 | 时间轴定位 | 条数 / 合计 | 单条区间 |
|---|---|---|---|
| KS·01开场留人 | 0-3 分钟·热情抓眼球 | 4 / 46s | 7–14s |
| KS·02卖点讲解 | 3-10 分钟·讲透优势建立信任 | 9 / 130s | 7–18s |
| KS·03试吃互动 | 10-15 分钟·感官种草 | 6 / 85s | 9–22s |
| KS·04价格逼单 | 15-25 分钟·快速成交 | 6 / 87s | 8–19s |
| KS·05答疑稳单 | 循环穿插(随机播放) | 5 / 65s | 11–14s |
| KS·06收尾催单 | 下播前 5 分钟·复盘催单 | 3 / 44s | 12–18s |
cd m2/server
node scripts/kuaishou-guava-case.js --verify 90 # 建场 + 开播 + 观察 90 秒
node scripts/kuaishou-guava-realtest.js # 实测用例 T1~T7
实测结果 9/9 通过:场景真实运行、循环口播推进、关键词组试打 6/6 命中、观众弹幕命中并真实回复、运行中改话术下一命中即生效、语音可播(RIFF 校验)、语音库 33/33、切条时长全部落在 5s~180s。
关键词组覆盖:问价福利 / 已拍承接 / 问库存发货 / 问口感吃法 / 问售后正宗 / 互动留人。
详见 reports/快手芭乐直播案例-实测报告.md。
部署与 Windows 服务
环境要求
- Windows Server 2019/2022(全 Windows 体系,不用 Docker/K8s);
- Node.js 22 LTS;生产另需 SQL Server 2019/2022。
用 NSSM 注册为 Windows 服务
nssm install XiaoyunLive "C:\Program Files\nodejs\node.exe" "D:\xiaoyun\m2\server\src\index.js"
nssm set XiaoyunLive AppDirectory D:\xiaoyun\m2\server
nssm set XiaoyunLive AppEnvironmentExtra DB_MODE=mssql NODE_ENV=production
nssm start XiaoyunLive
单机 All-in-One(一期推荐)
应用 + SQL Server 同机部署,用户量增长后按「应用机 + 数据库机」两台拆分,架构无需重写。健康检查:GET /health(含版本号,可接 UptimeRobot 外部探测)。
数据库与备份
- 建表:
m2/server/sql/init.sql(幂等,可重复执行);连接配置在src/config.js(MSSQL_*环境变量)。 - 演示与生产共用同一套 store 接口,
DB_MODE=demo|mssql一键切换。 - 备份策略:每日全量 + 事务日志备份,备份文件归档到腾讯云 COS。
常见问题
Q:演示模式重启后数据没了?
正常。DB_MODE=demo 使用内存存储,重启复位;生产用 mssql 模式持久化。
Q:自动弹窗一直不触发?
按顺序排查:① 弹窗配置里的商品是否已挂小黄车(商品库有 roomProductId 映射);② 场景 popConfig 是否 enabled;③ 弹窗定时器在开播时读取配置——运行中改弹窗配置需重启会话(语音组/关键词组不受影响,仍即时生效)。
Q:改了话术为什么没生效?
语音组/关键词组/场景话术为运行中热更新,下一轮循环生效(一轮 20–30 分钟属正常等待);若通过案例脚本改,需重跑脚本(幂等)。
Q:语音合成失败或时长不对?
单条语音要求 5 秒 ~ 3 分钟;检查文本长度(约 4.5 字/秒,5 秒 ≈ 23 字、3 分钟 ≈ 810 字)或 TTS 配置。合成结果在 /dl/tts/。文本含 [失败]/[fail] 时会模拟合成异常,用于验证失败重试。
Q:脚本跑完提示的 PASS 是真的吗?怎么自己验证?
案例脚本的 --verify N 只是「观察 N 秒运行数据」,属于自报。要独立验证请跑实测脚本(如 node scripts/kuaishou-guava-realtest.js),它不加速、不造数据,通过接口交叉核对真实直播间:会话是否在跑、口播计数是否推进、关键词组试打是否命中、真实弹幕命中后评论区是否出现 bot 回复、语音音频能否下载并通过 WAV 头校验、切条时长是否都在区间内。结果同时写进 tests/*-realtest-report.json。
Q:案例商品明明建了,为什么讲解被跳过、弹窗弹的是别的商品?
因为自动讲解/弹窗只认可「当前直播间已挂车」的商品。v0.31.0 起服务端不再预设任何小黄车商品,所以必须先真实挂车:接入真实平台后在平台后台把商品挂上小黄车(或调用上架接口),讲解与弹窗即指向该商品。没有挂车商品时步骤会如实记录「该直播间没有这个商品」并跳过。
Q:为什么客户端/大屏里的商品、在线人数、GMV 都是空的?
因为 v0.31.0 起不再使用任何演示/模拟数据:没有真实平台数据时,列表、商品、评论流与大屏经营指标都如实显示空态(大屏标注「待接入」)。请在电脑客户端内嵌登录平台并点「同步」,真实数据才会出现在界面与大屏上。
Q:添加了平台账号,但直播间列表是空的?
账号绑定成功 ≠ 同步到直播间。登录成功后客户端会立刻用本机会话向平台拉取真实直播间;若平台判定当前会话不是真实登录态(例如只完成了登录页加载、尚未扫码确认),同步会如实拒绝并保持列表为空——这是 v0.31.0 起的诚实原则(不造数据)。v0.34.2 起「已完成登录」兜底按钮也会先向平台确认登录状态,确认未登录就拒绝创建账号并给出原因。解决办法:在添加弹窗里完成真实扫码登录,等自动检测提示「登录成功」即可;已误建的空账号可在「账号管理」里删除。
Q:改了案例文案,重跑脚本会不会建重复素材?
不会。案例脚本按名称幂等复用(语音、语音组、关键词组、商品、场景),并会自动同步组成员/关键词/场景步骤,清理不再被引用的旧切条(按案例前缀如 KS·)。开播前先 stop-all,避免「该直播间已有自动化任务运行」。
Q:一个直播间能同时跑两个场景吗?
不能。同一直播间同一时间只允许一个自动化会话;案例脚本开播前会自动 stop-all。
Q:同平台想登录两个账号(比如两个视频号),会互相顶号吗?
不会。v0.29.0 起每个平台账号一个独立会话分区,v0.33.0 进一步加固:同步只读该账号自己分区的 Cookie(绝不回退公共会话),打开账号后台也不再从公共会话迁移 Cookie。操作:点「+ 添加」选同一平台,确认「新增一个账号」后,在弹窗里登录第二个账号即可;两个账号各自打开各自的后台,登录态互不影响。若某个账号显示未登录,用地址栏「重新登录」只清它自己的会话。
Q:真实平台(抖音/视频号)怎么接入?
在 src/adapters/ 实现对应平台的授权(OAuth/Cookie)、房间拉取、评论收发与推流接口,把 PLATFORMS 中对应项的适配器替换为真实实现即可,路由层零改动。接入前请确认平台对自动化播报的风控政策,建议保留真人出镜。
Q:接口报「该直播间已有自动化任务运行」?
先调用 POST /api/v1/automation/stop-all(或对单房间 stop)再重新启动场景。