线下讨论，线上发牌。
面向阿瓦隆聚会的微信小程序，提供私密身份与视野、投票、任务及技能结算辅助。
使用微信扫描上方小程序码，即可创建或加入牌桌。
快速上手 · 功能亮点 · 支持的玩法 · 本地开发 · 部署与发布 · 项目文档
- 创建或加入：房主选择人数和板子，朋友通过邀请或 6 位房间码加入。
- 入座与发牌：选择座位并准备，满座且全员准备后由房主发牌；每人在自己的手机上查看身份和初始视野。
- 讨论与操作：面对面讨论，房主按现场进度发起投票、任务或技能操作，提交收齐后自动结算。
- 结束与再开：线下完成最终结算，由房主登记胜方或选择“不计战绩”后结束本局；同一牌桌可重新准备、再开一局。
支持 5–12 人，具体人数和可用能力随板子变化，见下方玩法表。准备阶段可以换座或站起围观，满座时加入会先围观。
- 私密身份与视野：身份默认遮盖，主动查看；小程序切到后台会清除私密展示内容。
- 按现场节奏推进：投票、任务和技能按需发起；任务可选择队员及一张／两张失败票门槛。
- 秘密提交、自动结算：房主可查看提交进度，不能查看秘密票型或目标；最近公开结果可持续回看。
- 多种扩展玩法：涵盖经典基础、逆仆、影中执刃、混沌契约和十二骑士。
- 多桌切换与恢复：支持个人备注、房间恢复和同房重开，切换牌桌不会退出当前对局。
- 我的战绩与对局记录：小程序个人页展示有效局数、胜场和胜率；战绩页按阵营、角色逐层展开。独立的对局记录页按时间列出每场的板子、本人身份、同桌成员与胜负；结算时的最终阵营决定个人胜负。
- 积分与积分榜：经典基础 5–8、10、12 人新对局支持按结束原因计分；“我的”显示总积分和本月积分，对局记录可展开每项得分，战绩页展示场均与连胜，排行榜增加积分榜。分值及奖励说明由服务端配置，规则调整只需部署服务端；详情见 积分系统。
- 可选头像：编辑资料时可按风格选择 160 款内置头像，经典线稿、彩色蜡笔、黑白简笔、极简几何、像素风各 32 款。除奇幻角色外，还可选择月亮、药水、盾牌、王冠、动物等头像；选择后点击“保存资料”生效。服务端启用自定义头像后，小程序可上传自己的图片，审核通过并保存后同步展示到牌桌、排行榜与网页版。
- 玩家昵称：尚未设置个人昵称的用户在首次创建或加入牌桌时确认昵称，同时用于个人资料和排行榜；支持快捷填写微信昵称或自由输入。已有个人昵称会默认带入，临时修改本桌昵称只影响当前牌桌。历史默认“新朋友”会在下次进桌时确认，已有主动设置的昵称保留。
- 排行榜：在“我的 → 排行榜”查看有效局数、总胜率、好人胜率和坏人胜率，支持全部／本月切换、并列排名及本人上榜进度。未上榜但已有成绩可分享，图片显示未上榜及所差样本；暂无本人成绩时点击会提示原因，无有效机会可切换次数榜。微信和开发账号默认公开展示，可在排行榜底栏关闭，游客仍可查看榜单。
- 成绩图片分享：战绩、单项趣味成绩、完整趣味记录和排名可生成图片，预览后直接发给微信好友或保存到相册。趣味记录页顶部分享完整记录，单项入口保留；刀客刀法展示出刀与三种结果。战绩展示阵营表现和四个常玩角色；排名展示本人附近最多五位公开玩家，突出本人和同周期样本。图片高度随内容调整，标明统计时间和范围，接收者无需进入小程序即可阅读。已发送的图片无法随公开设置撤回。
- 开发与自部署：原生微信小程序 + Node.js + SQLite，附网页版玩家入口、陪测面板和可选管理平台。
牌桌管理与等待处理
- 我的牌桌：显示房主、公共状态、人数、座位和最近活动，支持仅自己可见的 30 字备注。进行中的牌桌优先，同状态按最近进入排序；达到 6 桌时显示状态筛选。
- 移除记录：仅隐藏自己的列表条目，8 秒内可撤销，重新进入后恢复；隐藏状态和备注保存在服务端。
- 离开与解散：离开房间按游戏规则退出并释放座位；解散房间仅房主可执行，需二次确认，会影响所有成员并删除房间内的过程记录；已归档的个人战绩仍保留。
- 房主管理：可转交管理权，在准备阶段或对局结束后移出玩家；失效房间的列表条目可自行清理。
- 结束等待：房主确认后可结束等待。投票未提交记弃权，技能按本次不使用处理，任务或必选目标操作作废。
胜率仅统计有明确胜负的有效参赛局。测试房间及有陪测参与的有效对局中，真实玩家和开发账号正常计入；陪测账号（test:）不保存个人战绩、积分及趣味记录，纯陪测对局不归档；终止局、未登记胜负和身份不完整的局不计入；旁观者没有参赛战绩。人工登记与系统判定会标记来源；管理员可更正有完整依据的结算结果。战绩从功能启用后的结算开始归档；已有归档中仅因测试标记被排除、且依据完整的胜负与趣味记录，会在服务启动时恢复。小程序沿用微信身份；网页版默认游客，启用扫码登录后可在“我的”使用小程序账号，共用资料、战绩、积分与座位。游客历史不自动合并，原游客凭证失效后无法自动找回。
| 玩法 | 人数 | 当前支持范围 |
|---|---|---|
| 经典基础 | 5、6、7、8、10、12 | 按人数配置身份与初始视野，支持投票、任务；12 人含双奥伯伦 |
| 逆仆 | 9、11 | 经典操作及刀逆仆，阵营变化私密呈现；匪队在线下决策 |
| 影中执刃 | 12 | 身份与初始互认视野、投票、任务；特殊盘刀和最终胜负在线下完成 |
| 混沌契约 | 12 | 身份与初始互认视野、魔法票与盗贼失败票结算；首夜绑定、特殊盘刀与排名在线下完成 |
| 十二骑士 | 10、11、12 | 秘密技能提交与同时生效、守护／换号／替死、猎人预选开枪、圣骑士反伤、石像鬼查验、B 牌复活、身份转换、仙女与先知视野 |
所有板子共用湖中仙女设置：5、6 人不支持，7 人默认关闭，8 人及以上默认开启；房主可在房间设置中切换。公共座位显示「湖仙」，查验结果仅本人可见。
所有板子均以按需工具、操作收齐自动结算、房主手动结束整局为主：不会因为三次任务成功／失败、连续否决或单次操作结果自动结束整局。当前小程序不提供刀梅林入口，最终刀梅林在线下进行。影中执刃的完全自动胜负模式未开放。
十二骑士换牌后会向本人提示新身份，主动技能在下一技能周期启用，先知视野自动更新。房主可在「房间设置」开启已结算技能过程的公开展示，默认隐藏；最终出局与复活座位仍会公示，新牌身份仅本人可见。
详细角色、技能和操作约定见 规则说明。该文档保留了规则演进记录，同一事项以靠后的最新补充为准。
使用原生微信小程序、单体 Node.js HTTP 服务和 SQLite。图片上传使用 busboy 解析与 sharp 重编码，无需 Redis 或消息队列。
需要 Node.js ≥ 22.13.0（使用内置 node:sqlite；生产镜像使用 Node 24）及 npm。
npm ci
npm run dev默认服务地址为 http://127.0.0.1:8787，数据库位于 data/shadowtable.sqlite。开发命令同时启用匿名开发登录、本地陪测和网页版入口：
| 入口 | 地址 | 用途 |
|---|---|---|
| 网页版 | http://127.0.0.1:8787/ |
浏览器玩家入口 |
| 本地陪测 | http://127.0.0.1:8787/dev |
添加独立测试玩家、准备、投票与技能操作 |
| 健康检查 | http://127.0.0.1:8787/health |
检查服务状态 |
开发登录每次新登录生成独立身份；清除会话后无法恢复原开发身份。测试多名玩家时使用独立设备、独立存储环境或陪测面板。
- 在微信开发者工具中导入项目根目录，工具会读取
project.config.json。 - 使用自己的小程序 AppID；仓库已配置项目 AppID，自行部署时需要替换。
- 本地联调使用
miniprogram/config.js中的baseUrl: "http://127.0.0.1:8787"和devAuth: true，与npm run dev配套。 - 在开发者工具的本地设置中关闭 request 合法域名校验，然后编译运行。
- 创建牌桌后，可在
/dev输入房间码、补齐测试玩家并全部准备，再回到小程序开局。
真机访问本地服务时，不能使用手机上的 127.0.0.1。同网调试需将 baseUrl 改为电脑的局域网地址，并以 HOST=0.0.0.0 npm run dev 启动服务；正式环境使用 HTTPS 和微信 request 合法域名。
在 /dev 中添加独立测试玩家，可快速验证发牌、投票、任务和技能流程。面板仅允许本机访问，必须同时启用 DEV_AUTH=1、DEV_PANEL=1，生产环境不可用。
陪测账号与房间管理
- 陪测面板仅操作独立测试账号，不代替真人提交；测试玩家身份默认隐藏，可手动展开。
- 清空陪测玩家会保留真人和牌桌。陪测担任房主时，可发起投票、任务、技能、查验、结算及转交房主。
- 管理房间列表提供带房间号的陪测入口；面板按房间保存当前标签页的账号和未确认请求，切换无需先清空旧房间。
- 房间或凭据失效时可移除本地记录，但不会删除服务器座位；残留座位由管理平台在准备阶段清理。
npm test
npm run checknpm test 运行 Node.js 测试，npm run check 检查主要服务端和客户端脚本语法。真机与人工验收范围见 验证记录。
miniprogram/ 原生微信小程序页面与接口调用
server/ HTTP API、规则引擎与 SQLite 存储
web/ 网页版玩家入口
dev-panel/ 本地陪测面板
admin/ 正式管理平台
tests/ 自动化测试
deploy/cloud/ 容器部署、预检与回退脚本
docs/ 规则、架构、部署说明与 README 图片
服务端采用单实例 Node.js + SQLite，使用 Docker Compose 部署；独立 Caddy 网关提供 HTTPS。仓库已提供 GitHub Actions 流程：推送 main 后执行验证并构建镜像，再手动选择已验证的镜像通过 SSH 发布，健康检查失败时回退应用镜像。
完整的服务器初始化、镜像仓库、Secrets、网关和备份配置见 部署文档。环境变量示例见 .env.example 和 容器部署配置。Node 不会自动加载 .env，需由运行环境或 Compose 注入。
| 配置 | 用途 |
|---|---|
WECHAT_APP_ID / WECHAT_APP_SECRET |
小程序服务端微信登录凭据 |
HOST / PORT |
监听地址与端口，默认 127.0.0.1:8787 |
DB_PATH |
SQLite 文件路径，默认 data/shadowtable.sqlite |
WEB_ORIGIN |
启用网页版与访客登录，生产环境使用完整 HTTPS 源地址 |
WECHAT_WEB_LOGIN |
默认关闭；小程序确认页发布后设 1 开启网页扫码登录，还需配置小程序微信凭据 |
ADMIN_ORIGIN / ADMIN_KEY |
两项同时配置后启用 /admin，详见部署文档 |
DEV_AUTH / DEV_PANEL |
开发登录与本地陪测开关，生产环境设为 0 |
生产服务启动示例（其余配置由环境注入）：
NODE_ENV=production DEV_AUTH=0 DEV_PANEL=0 PORT=8787 npm start小程序需单独上传发布：配置自己的 AppID、HTTPS baseUrl 和 request 合法域名，将客户端 devAuth 改为 false。AppSecret 仅放在服务端。
资料编辑页及 160 张内置头像位于 pages/profile 普通分包，页面路由仍为 /pages/profile/profile；一级导航和其他页面留在主包。npm test 包含主包与各分包的源码体积检查，最终包体积需在微信开发者工具的代码包分析中确认。头像文件路径与服务端镜像共用，发布时先更新服务端镜像，再上传小程序；仅移动资源不改变头像编号、内容哈希或已有用户头像，无需数据库迁移。
正式管理平台支持房间概览、为准备阶段房间开启陪测、清理测试座位、终止／删除房间及操作审计。生产陪测不依赖开发登录开关。
SQLite 仅由一个服务实例写入；备份使用 SQLite 在线备份或停服备份完整数据目录，不要在运行时仅复制主文件而遗漏 WAL。发布失败时的自动回退只恢复应用镜像，不恢复数据库。main 只运行 CI 并构建镜像；通过 GitHub Actions 的 Deploy tested image 手动选择目标和构建编号发布。
服务已内置每日本机在线备份及日／周／月保留。准备牌桌默认 7 天无活动后进入 3 天宽限，结束牌桌保留 30 天，失效列表条目和操作回执保留 90 天；历史战绩、积分和进行中牌局保留。自动清理要求最近 48 小时内存在已校验备份。双端支持公共详情条件请求和空闲降频，网页补齐自动重连、未确认操作核对及恢复提示。配置、恢复与版本兼容要求见 维护说明。
底部“对局 / 我的”分别管理牌桌和个人资料；进入牌桌后隐藏底部导航，返回大厅保留座位。“我的”支持头像、昵称、胜负积分及趣味记录。点趣味次数可回查本人对应对局；排行榜提供积分、局数、胜率与趣味四类，趣味榜支持玩法、角色、次数／成功率及全部／本月筛选。资料沿用当前登录账号保存；网页版可通过小程序扫码确认登录同一账号，游客历史暂不合并。发布顺序、会话恢复与退出规则见 扫码登录说明。
- 房主也是玩家，不拥有全员身份或秘密行动查询权限；完成进度不包含具体提交内容。
- 小程序不持久化身份；私密接口按当前玩家返回角色、视野与合法动作。组队票在结算后公开，任务牌只展示汇总。
- 十二骑士的技能过程公开属于房间设置，开启前需要确认；新抽取的身份牌面始终仅本人可见。
- 切换未结算操作前需确认作废，已发身份和已结算记录保留；结束本局不会额外公开全员身份。
- 网络结果不确定时使用原请求编号重试，避免重复操作；切到后台后不会自动重新揭示身份。
| 文档 | 内容 |
|---|---|
| 规则说明 | 角色配置、线上操作与扩展板规则 |
| 规则待确认项 | 规则歧义与历史讨论，结合最新规则说明阅读 |
| 规则原文快照 | 自定义板子的参考原文 |
| 架构与接口 | 服务结构、数据模型与 API |
| 部署指南 | 容器、CI/CD、网关、备份及运维 |
| 维护说明 | 数据保留、本机备份、恢复与连接稳定性 |
| 验证记录 | 测试记录与真机验收 |
| 趣味记录 | 指标口径、个人展示与荣誉榜 |
本项目原创代码采用 MIT License，允许商业使用、修改和分发，使用时须保留版权及许可声明。第三方依赖、引用的规则文档、图片及其他第三方素材的权利归各自权利人所有，不因本项目的 MIT 许可而重新授权。