参考《暗流涌动》的非官方精简剧本,5–9 人在线联机。前端 Vite + React,后端 Node.js HTTP 服务,游戏规则、身份分配与胜负判定全部在服务端完成,客户端只拿到过滤后的视图。
**当前状态:**已在 WorkBuddy 以「网站应用」发布,线上地址与 sharecode 保持不变;存储仍为持久化文件驱动(DB_DRIVER=file),共享云数据库未开通,原因见「部署现状」。旧房间、旧邀请链接继续可用,正在进行中的对局不会被重新分配身份。
- 24 个候选角色,每局随机抽取:13 镇民(洗衣妇、调查员、图书管理员、厨师、共情者、占卜师、僧侣、士兵、送葬者、杀手、守鸦人、贞洁者、镇长)、4 外来者(管家、酒鬼、隐士、圣徒)、4 爪牙(投毒者、间谍、红唇女郎、男爵)、3 恶魔(小恶魔、方古、诺-达鲺)。
- 每局 1 恶魔(三选一随机)+ 1 爪牙;5/6/7/8/9 人局的外来者人数为 0/1/1/1/2(7 人局起保证至少 1 名外来者);男爵在场时外来者额外 +2(男爵仅 7 人局及以上出现)、方古在场再 +1;外来者总数最多 4 名且至少留 1 名镇民。
- 新角色裁定(已与用户确认):贞洁者按官方注册规则判定提名者(酒鬼算其伪装的镇民、间谍/隐士随机注册);镇长夜晚死亡 50% 概率由其他存活玩家代死,剩 3 人且当天无人被处决时善良获胜;守鸦人仅夜晚死亡触发,白天自选一人学习其真实角色(中毒时得到错误答案)。
- 首夜顺序:投毒者 → 间谍 → 洗衣妇 → 调查员 → 厨师 → 共情者 → 占卜师 → 管家。其他夜晚:投毒者 → 僧侣 → 间谍 → 红唇女郎接任提示 → 小恶魔 → 送葬者 → 共情者 → 占卜师 → 管家。未入场、已死亡或不需要目标的能力自动跳过;这是精简实现的顺序,不是完整官方夜序。
- 7–9 人局首夜:爪牙私下得知恶魔,恶魔私下得知爪牙以及 3 个不在场的善良角色(伪装候选,排除在场角色与酒鬼自认的身份)。5–6 人局不发送常规互认与伪装信息;间谍仍可凭自身能力查看魔典。
- 公开触发能力可伪装:任何存活玩家白天都能公开宣称使用杀手能力,说书人配合演出;只有清醒、未中毒、未用过的真杀手才会真的造成死亡,伪装与真失手都只播报「没有人因这次能力死亡」,伪装不消耗真杀手的次数。每人每天限宣称一次(防刷屏,对应官方可选规则)。
- 死者票:死者每局只有 1 次赞成票;投不赞成不消耗,且赞成票用完后仍可投不赞成。投票区的「已投 X/Y」只统计还能投出赞成票的玩家(存活者 + 尚有死者票者),因此死者的不赞成票不会误触发投票自动结束。
- 白天可多次提名:一个白天可以连续发起多轮提名,每轮独立投票。每人每天只能提名一次,同一名玩家每天最多被提名一次;达到存活人数一半的票数门槛不会立刻处决,白天结束时才按全场最高票(且不平票)处决。中栏「今日提名榜单」列出当天每一次提名的被提名者、提名者、票数与门槛,并标出当前最高票,方便对比后再决定是否继续提名;旧房间缺该字段时按空列表处理。榜单在白天结束时清空。
- 送葬者:在有人被处决之后的那个夜晚(非首夜)私下得知被处决者的真实角色(酒鬼显示「酒鬼」、间谍/隐士可能误报)。注意夜序中小恶魔在送葬者之前行动,若送葬者当晚被恶魔杀死就不会被唤醒,因此不会收到这条信息——这是官方夜序的正常结果,不是漏发;已用回归测试覆盖「存活收到 / 当夜被杀收不到」两种情况。
- 中毒 / 醉酒:能力仍然照常被唤醒、照常选择目标、照常收到信息,但信息有 80% 概率是错的(官方要求「可真可假、不可固定 50/50 或必定为假」,因此保留 20% 真信息;旧房间沿用旧规则)。每一条「假」信息都由服务端按当前局面构造并校验——例如洗衣妇的假线索绝不会出现两位玩家真实持有的身份,调查员可以给出「两人都不是显示的爪牙」——而不是把真答案换个名字。配置 Qwen 时模型只在服务端已校验的候选里挑选措辞,输出越界、超时或报错都会回退到规则选择,不参与裁定。
- 中毒来源互相独立:投毒者的毒与诺-达鲺的光环分开计算;投毒者死亡或自身中毒时其毒立刻结束,但不会清掉光环;一个来源失效不会误清另一个。中毒不会改变角色或阵营,中毒的恶魔仍被占卜师识别为恶魔。
- 胜负宣布只播一条:胜负在夜间判定(夜间死亡让场上只剩两人,或恶魔死亡)时,说书人只公布「某方获胜」,不再开启新的一天——不会再有「私聊时间开始」「进入自由讨论」的语音,也不会生成天亮旁白;当晚的死亡结果仍照常公布。
- 中毒时的一次性能力仍然消耗:中毒的杀手/贞洁者/守鸦人机会用掉后不会恢复;中毒的僧侣保护无效、士兵会死、圣徒被处决不触发败北、镇长不代死也不获胜、红唇女郎无法接任。间谍中毒时仍会看到魔典,只是其中部分身份不保证为真(不再提示「魔典模糊」)。
- 酒鬼只看到一名不在场镇民的假身份,且没有该能力;隐士可能被识别为邪恶/爪牙/恶魔;圣徒被处决且能力生效时邪恶获胜;红唇女郎在恶魔死亡且死亡前至少 5 人存活时接任。
**占卜师与红鲱鱼:**每局开局固定一名善良玩家(不含占卜师本人,不公开)作为红鲱鱼,被占卜时按恶魔登记;红鲱鱼整局不变,占到就答「是」。旧房间没有红鲱鱼,保持原规则。
**精简剧本的限制(已在游戏说明中写明):**未实现小恶魔自杀传位,只可提名存活玩家。
- 「游戏说明」弹窗按 镇民 / 外来者 / 爪牙 / 恶魔 四类分组展示全部 24 个角色,分类与角色数据由服务端
/api/config下发,与规则引擎同源,不会再出现两边不一致。 - 大厅与对局左栏、说明弹窗顶部都会显示本局默认配置:按当前人数给出基础的镇民 / 外来者 / 爪牙 / 恶魔人数,以及爪牙与恶魔是否首夜相认(7 人局起互认,恶魔另知三个不在场善良角色)。
- 默认配置只显示基础人数:男爵(+2 外来者)、方古(+1 外来者)改变的是实际发牌,说明里始终写基础值——例如 6 人局基础 1 名外来者,即使男爵让场上真有 3 名,卡片仍显示 1。
- 座位号:入座即分配 1–9 号固定座位(空出的座位会被新玩家优先复用),大厅、桌上与复盘里都能看到号码;发言顺序按座位进行。
- 大厅踢人(v0.6.6):开局前房主可以在「入座玩家」列表里把误入、重名或临时离开的人「请出」。被请出的玩家会立刻收到一条「你已被房主请出房间」的通知并被带回首页,他在大厅发的消息与所在讨论组也会一并清理;空出的座位由下一位加入者补上。服务端约束:只有房主能执行、只能在
lobby阶段、不能请自己;发牌之后座位锁定,既不能请人也不能退出。房主自己退出时房主身份自动转给下一位。实现要点:kickop +publish在某订阅者的 view 失效时下发一帧{removed:true,reason}并关闭该 SSE。 - 白天三段式(v0.6.9):
私聊 → 轮流发言 → 自由讨论,没有单独的结算阶段。私聊最先进行,默认 8 分钟,房主可随时「结束私聊,开始发言」提前进入下一环节;轮流发言每名存活玩家一轮,默认每人 2 分钟(房主可调 30–600 秒),发言者可以「结束发言」提前交棒,房主也可以跳过,发言超时自动换人时说书人会广播提醒(也会被语音朗读);自由讨论默认 10 分钟(房主可调 1–60 分钟),讨论期间即可提名,可以连续发起多轮。讨论计时结束(或房主提前「结束讨论」)时说书人宣布「自由讨论结束」,提名继续开放;之后房主点「结束白天」按最高票处决——没有人被提名时直接进入夜晚。「准备入夜」在自由讨论阶段即可使用。计时由服务端推进,/api/room的读取与后台时钟都会把过期阶段推到下一步,不依赖房主页面保持前台。 - 提名三段式(v0.6.11):提名后不再直接开票,而是走「提名者陈述 → 被提名者狡辩 → 15 秒限时投票」。前两步各有一个按钮,只有轮到的人(或房主代为)能按:提名者点「陈述完毕」后轮到被提名者,被提名者点「狡辩完毕」后才开始倒计时。倒计时由服务端计时,结束即自动结算,没投票的人视为不赞成(结算前会播报「N 人没有投票,视为不赞成」);所有人都在 15 秒内投完则立即结算。房主始终可以代按两步,也可以随时「跳过并结算」收尾,避免有人掉线卡住整桌。数据上只是给 ballot 加了
stage(accuse|defense|vote)与endsAt,旧房间没有这两个字段的投票按普通「进行中投票」处理,房主按钮照常可用。实现:nominate开在accuse、advance_ballot推进两段、tick在endsAt后调用closeBallot(g,true)。 - 私聊环节:白天第一个阶段,默认 8 分钟(房主可调 1–60 分钟)。环节结束后私聊与讨论组发送会被服务端拒绝(「私聊环节已结束」),公屏聊天不受影响。旧房间(v0.6.3 及更早开的局)保留旧时间线:私聊时钟与发言并行,到点关闭。
- 公开表决:投票区实时显示谁投了赞成、谁投了不赞成;每次提名关闭后,票数、门槛与赞成者名单会写进公开事件与「今日提名榜单」。
- 复盘页签:右侧「复盘」按天列出昨夜死亡、每一次提名(提名者、票数、门槛、赞成者)以及当天处决结果;数据只来自公开信息,不含任何身份或夜间秘密。
- 一对一私聊继续可用;可创建讨论组,创建时选 1 人或多人,组内成员均可继续邀请或退出。
- 大厅与白天可聊天;白天的私聊只在「私聊」环节开放(默认 8 分钟),环节结束后只能公开聊天;夜晚与游戏结束后不能发送消息,也不能修改组员。
- 所有人能在「私聊动态」看到谁与谁私聊、以及成员加入/退出;消息正文仅发送时的组内成员可见。每条群消息在服务端固定
audience:新加入者看不到加入前的记录,退出后看不到离开期间的消息,重新加入也看不到离开期间的内容。 - 每条群消息的
to写入群 ID(非 null),旧版过滤器不会把它当成公共消息。群消息与动态各保留最近 200 条,未实现端到端加密。 - 来信不会错过:收到悄悄话时,会话区顶部直接显示「某人 悄悄话给你:正文」的横幅,点一下进入会话;「聊天」页签、聊天对象下拉都带未读条数(按消息 id 记录已读,不受设备时钟影响)。公屏同样计数:聊天框默认贴底,向上翻看时新消息不打断阅读,底部出现「↓ N 条新消息」按钮。
- 仓库与代码不内置任何密钥:服务端从环境变量 /
.env读取 Key(见下文「AI 密钥配置」),房主也可以在「说书人设置」里粘贴自己的 Key(优先级最高)。没有任何 Key 时游戏照常进行,只是没有 AI 旁白与语音,可用「本机朗读」兜底。支持两种服务商:- 阿里云百炼(Qwen):文字默认
qwen-plus,语音使用qwen3-tts-flash(芊悦 Cherry / 苏瑶 Serena)。 - 火山方舟(豆包):OpenAI 兼容接口
https://ark.cn-beijing.volces.com/api/v3/chat/completions,模型名称必填,必须与控制台完全一致——带日期后缀的模型 ID(如doubao-seed-2-1-lite-260915)或推理接入点 ID(ep-…)。切到方舟时模型框预填doubao-seed-2-1-lite-260915。 - 模型名写错会返回 404(
InvalidEndpointOrModel.NotFound)。接口报错会带上游的错误码,并在 404 时提示正确的 ID 格式,不会只说一句「请检查密钥」。 - 设置弹窗里的「测试连接」用一次最小请求验证密钥 / 地域 / 模型是否可用(不写房间记录、不消耗对局),通过后再开局。
- 阿里云百炼(Qwen):文字默认
- 只能用「按量付费」的方舟 Key。 Agent Plan / Coding Plan 这类订阅套餐走的是另一套 Anthropic 风格地址(
/api/plan),官方明确写明月度套餐内的文字模型「不可用于 API 调用」,误用可能导致订阅停用或账号封禁,所以本应用不会去连那条路径;填订阅 Key 会得到鉴权失败。按量付费下一次旁白约几十 token,单局成本约 ¥0.02。 - 音色默认「玲玲姐姐」:
zh_female_lingling_uranus_bigtts(林志玲同款娃娃音,豆包语音合成 2.0,仅中文)。1.0 的zh_female_linzhiling_mars_bigtts与旧配置里的zh_female_zhiling_moon_bigtts已于 2026-06-30 随一批 1.0 音色下线,服务端做了别名映射,填旧 ID 会自动落到 2.0,不会再整局没声音。 - 语音是另一个产品:文字走方舟/百炼的模型接口,语音走火山引擎语音接口
https://openspeech.bytedance.com/api/v3/plan/tts/unidirectional(X-Api-Key+X-Api-Resource-Id: seed-tts-2.0,返回按行 JSON、音频为 base64 分片)。两把 Key 不通用:文字 Key 调不了语音,语音 Key 也调不了文字模型。选择方舟时设置里会多出「豆包语音 Key」与「音色 ID」两项。 - 豆包语音的
/plan/路由属于 Agent Plan 套餐,需要账号开启「语音抵扣」。未开启时接口返回45000030 / Forbidden.AgentPlanDeductNotEnabled,界面会直接提示去控制台开启;标准按量付费语音要用语音控制台的 AppID/AccessToken,不是方舟 Key。 - 三个开关,缺一个就听不到声音:①「开启本机朗读」只在这台设备发声;②房主点「为房间开启语音生成」才会为新出现的公开事件合成音频(开启后才产生的事件才会被朗读);③每个人还要各自点「开启收听」才会播放。收听已开但房间里没有音频时,语音弹窗会明确提示是哪一步没做。
- 听不到播报时的兜底:房间顶部会直接给出提示——没开收听显示「开启收听」,浏览器暂停播放显示「继续播放」,且在房间里任意点一下会自动续播;房主的合成任务偶发失败(限流、超时)会先自动重试同一条,不再整局静音;「本机朗读」改为逐条串行播报,避免同一刻的多条事件(宣称杀手 → 死亡 → 胜负)被浏览器丢弃。
- 「测试语音」按钮:语音弹窗里点一下,服务端用你的语音 Key 合成一句固定台词并直接在浏览器播放,成功会显示「语音正常:火山方舟 · 音色」,失败则原样给出上游原因(如 45000030)。不需要开局、不消耗对局事件。
- 不需要任何 Key 的「本机朗读」:用设备自带的
speechSynthesis念公开事件,人人可单独开关,只在本机发声、不联网、不消耗额度。Ark Key 或语音接口不可用时,这是最快能听到声音的方式。 - 语音只处理开启之后的公开事件与公开旁白;身份、私密线索、间谍魔典、聊天内容永不进入语音接口或公开日志。
POST /api/room的op=generate_voice校验房主令牌后合成一次;音频 URL 只存在服务端房间记录,GET /api/room?code=…&voice=…经令牌校验后代理返回audio/wav(Cache-Control: private, no-store)。数据库 CAS 冲突时重新加载并附加同一份合成结果,不会重复调用付费接口。- Key 只在房主页面内存与请求中使用,不写房间记录、不写日志;刷新后需重新填写。房主页需保持在线。手机端自动播放被拦截时提供「点击继续播放」。
- 房间状态走 SSE 长连接(
GET /api/room/stream,仍用X-Room-Token鉴权,token 不进 URL)。任何一次写入都会把该房间的新视图推给在场玩家,实测一次写入到另一名玩家收到推送约 70ms;轮询只作为连不上时的兜底(300ms,后台 2s)。 - 玩家自己的动作由服务端推进下一位:
night_action提交后,服务端在同一次请求里跳过无需操作的角色并停在下一个需要行动的人(auto标记由 HTTP 层加上),投票在最后一张有效票投出时自动结束。房主不再需要点「继续夜晚」,也不会因为房主切到后台而卡住整桌;房主按钮保留为兜底与主持控制。 - 模型调用加了 15 秒上限,超时按「本次旁白放弃」处理;天亮旁白生成失败也不会卡住对局,只是退回「规则主持」的纯文本。
- 豆包 seed-2.x 默认会先思考再回答,一句 60 字旁白实测要 17 秒;请求里关闭思考链(
thinking:{type:'disabled'})后降到 1.3–1.7 秒。不认这个参数的老模型会自动重试一次不带参数的请求。
rulesVersion: 2与night字段只在新开局时写入。旧房间没有这两个字段,继续使用原有的同时行动夜流程,身份、历史消息、进行中的投票都不变;start在已开局房间会被拒绝,因此不存在重新发身份的路径。chatGroups/chatActivity/chatActivityKeys是可选字段,旧房间缺失时按空处理。- 新增的旧房间兼容性由
tests/legacy-room.mjs与生产存储 e2e 覆盖。
需要 Node.js 22.12+。
npm install
npm run build
npm test
npm start # 端口读 PORT,默认 3000
npm start 会先执行 scripts/ensure-build.mjs:缺少 web-build/ 或 server-dist/ 时自动构建,并校验 web-build/index.html 引用的每个资源文件确实存在——只判断文件存在会漏掉「HTML 是新的、资源没上传」的陈旧前端。
前端产物目录是
web-build而不是dist:WorkBuddy 的部署上传会跳过名为dist的目录,导致后端已更新、前端仍是旧版本(本次合并时实际踩到过,已改用web-build)。
代码与仓库不包含任何密钥。server/index.mjs 启动时读取项目根目录的 .env(NODE_ENV=test 时不读,测试保持无密钥):
CLOCKTOWER_ARK_API_KEY/CLOCKTOWER_ARK_MODEL:文字模型的 Key 与模型 ID,页面里房主填的 Key 优先。CLOCKTOWER_VOICE_KEY:豆包语音 Key(X-Api-Key,与文字 Key 不通用)。CLOCKTOWER_SPEAKER:默认音色,缺省即zh_female_lingling_uranus_bigtts。
配置方式:复制 .env.example 为 .env 并填写,或直接设置同名环境变量。房主在设置弹窗里填的 Key 永远优先;不填 Key 也能开局,只是没有 AI 旁白与语音。
GET /api/config 只回答「用哪个服务商、有没有 Key、默认音色是什么」,不返回 Key 本身。.env 已在 .gitignore 中,不会被提交到仓库。
DB_DRIVER=file(默认,线上使用):一个房间一份 JSON 文档,临时文件 +rename原子替换,version条件更新(CAS),同一房间写入串行化。DB_DRIVER=cloudbase:CloudBase 文档数据库适配,clocktower_rooms集合,接口契约与 file 驱动一致。需要CLOUDBASE_ENV_ID/TCB_ENV_ID,或在支持SYMBOL_CURRENT_ENV的云环境中使用当前环境。切换前必须在目标环境验证鉴权、集合权限与 SDK 返回形状。DB_DRIVER=memory:仅NODE_ENV=test可用,生产会被拒绝。
- 大厅阶段最后一人退出:立即删除房间记录。
- 开局之后:规则不允许退出座位,房间不因玩家离开而消失。
- 闲置回收:启动时与每小时扫描,删除超过
CLOCKTOWER_ROOM_TTL_HOURS(默认 12 小时)无写入的房间,不可恢复。
WorkBuddy 共享云数据库的开通确认被关闭,平台返回 useLocalImplementation: true 并要求改用本地实现,因此线上使用 DB_DRIVER=file:
- 只保证单实例一致;若平台扩缩容出第二个实例,连到不同实例的玩家会看不到同一个房间。
- 重新部署会复用同一沙箱与磁盘(已实测旧房间在发布后仍在),但不要在有人对局时发布,重启会中断进行中的房间。
- 没有后台管理界面,也无法跨实例查看房间。
云数据库开通后把 DB_DRIVER 切到 cloudbase 即可,无需改动接口;现有房间不会自动迁移。
自动化(npm test,31 条用例,全部使用模拟 AI / 模拟存储):
smoke 构建产物与 sharecode 透传、建房入座、身份隔离、有序夜晚、私聊、提名投票、昼夜切换 · storage-smoke CloudBase 适配的 insert 唯一性与 CAS · file-storage-smoke 重启可读、陈旧写入被拒、闲置回收 · legacy-room 旧房间不重发身份、保持旧夜序 · roles-order 夜序、首夜信息、间谍魔典隔离、红唇女郎接任、夜间死亡不提前公开 · outsiders 外来者人数(含男爵 +2 的所有组合)、酒鬼假身份与无效能力、管家投票、圣徒、隐士与中毒 · new-roles 图书管理员二选一与「场上没有外来者」、贞洁者触发/不触发/中毒失效/仅首次、镇长三人生还获胜/处决取消/中毒失效/夜晚代死、守鸦人死亡选择与中毒错误答案 · demon-info 7–9 人首夜互认与三个伪装、5–6 人无互认、TTS 隔离 · group-chat / group-api 讨论组权限、冻结受众、加入退出后的历史隔离、公开动态不含正文 · public-claims 公开能力伪装、死者票不赞成不消耗、送葬者处决信息与夜序边界 · debate 提名三段式(陈述/狡辩/15 秒倒计时、未投视为不赞成、房主代按与跳过、旧投票兼容)· multiple-nominations 一天多次提名、每人/每目标每日一次上限、提名榜单票数与「后提名更高票胜过先达标」的白天结束结算、平票不处决、旧房间缺字段兼容 · volc-tts / volc-voice-api 豆包语音的 X-Api-Key 与 seed-tts-2.0、base64 分片拼接、mp3 代理与鉴权、45000030 提示、语音 Key 与音频不落库不下发 · ark-api / ark-http 方舟地址与请求头、模型 ID 与 ep- 接入点、401/404 可读报错、语音被拒、Key 不进房间记录与日志(HTTP 用例起真实服务,只拦截方舟域名)· qwen-tts / voice-api 请求结构、只读公开事件、房主权限、地址白名单与 SSRF、大小限制、CAS 重试不重复合成 · auto-advance 提交动作后服务端自动推进到下一位、最后一张票自动结束投票、玲玲姐姐 2.0 默认音色与旧 ID 映射 · restart 结束后房间保留:新人可直接入座、旧成员可退出、房主「再来一局」按当前配置直接开新一局(重新发牌)、人数不足被拒、进行中重开/退出被拒、房主离开后房主席位顺延 · realtime SSE 首帧快照、写入即推送、流式接口同样校验房间令牌、/api/config 不下发 Key。
本地生产配置 e2e(DB_DRIVER=file):旧房间文档加载后身份不变并走旧夜序、9 人有序夜晚、讨论组、双设备共享音频、执行恶魔后的胜负。
**已实测:**方舟文字 Key 走真实接口验证过——test_ai 返回「连接正常」,真实旁白 1.3–1.7 秒(关闭思考链后)。
**未验证:**真实语音合成(开发期使用的语音 Key 未开通语音抵扣,语音网关返回 45000030)。换成有语音合成额度(或已开启 Agent Plan 语音抵扣)的 Key 后无需改代码。真实多运营商网络下的可达性、以及真实手机的发声,仍需在目标环境实测。
web/App.tsx 界面与房间交互
web/useRoomStream.ts SSE 实时同步(断线后自动退化为轮询)
web/useNarration.ts Qwen 语音生成与收听队列
web/voiceEvents.ts 公开事件/就绪音频追踪(同时供服务端测试导入)
web/styles.css 样式
web-build/ 前端构建产物(由 vite 输出,服务端静态目录)
server/game.ts 规则引擎、视图过滤、Qwen 文本与语音调用
server/index.mjs HTTP 接口、SSE 推送、语音代理、静态资源、AI 密钥(仅环境变量)
server/storage.mjs 存储驱动(file / cloudbase / memory)
scripts/ 构建与 sharecode 注入
tests/ 自动化测试