帮助内容如何同步

1. 插件命令与帮助由 PicMenu 配置及插件公开帮助提供，网站从同一份快照生成文档和插件详情。
2. 菜单的外部配置源位于 config/nonebot_plugin_picmenu_next/external_infos/；Mai2Help 的公开帮助源在 src/plugins/nonebot_plugin_mai2help/menu.py。编辑前确认对应插件和命令实现。
3. Bot 启动时尝试导出公开帮助到 data/web/plugin_help.json。修改帮助后，通过现有管理方式重启 Bot，并检查导出日志。
4. 打开使用文档，核对帮助快照时间、分类、命令及插件详情。未更新时先排查快照导出，不要直接修改生成的 JSON 当作长期维护方式。

隐藏帮助不应通过手写补充内容重新公开。涉及权限、群聊范围或参数语法的说明，只在核对实现后填写；快照更新不等于功能已完成实测。

配置与外部服务

环境变量与密钥放在本地配置中，不写入网页模板、截图或公开文档。项目启动需以根目录为工作目录，使 LocalStore 的配置、运行数据和缓存落在项目内对应目录。

• 查分器：水鱼上传 Token、OAuth 与落雪授权各有用途。外部服务不可用时，先查看本站错误和对应平台状态，不通过重复授权或重试掩盖问题。
• 机厅：资料与出勤使用 Nearcade。人数上报需要配置具有相应权限的 API key；未配置时，查看与上报的可用范围不同。营业状态及上游权限也可能拒绝上报。
• 定位与地图：公网浏览器定位需要安全上下文，通常为 HTTPS；localhost 可用于本地调试。地图瓦片、机厅资料与定位分别检查，外部导航还依赖对应地图服务。

详细机厅集成和部署说明保留在仓库的 docs/arcade-web.md；项目目录、配置位置和依赖限制见 README.md。这些是维护说明，不是公开下载配置或密钥的入口。

卡片背景素材

背景名称来自仓库中的公开落雪素材名称快照。需要更新时运行 .venv\Scripts\python.exe scripts\update_frame_names.py，检查差异后提交。新增名称不会自动下载背景图片，列表只展示本地已有素材。

可运行 .venv\Scripts\python.exe scripts\warm_frame_thumbnails.py 预先生成缩略图，减少首次浏览时的等待。图片缓存可以重新生成；用户选用的背景和收藏保存在身份数据库中。

版本与备份

Git 用于记录源码和已纳入版本控制的文档。提交前查看差异，将一个可独立回退的改动保存为一次提交；回退网页代码不会自动恢复账号、数据库或运行配置。

另行备份本地环境配置、config/ 和 data/。全站用户、登录会话、昵称、偏好及背景收藏默认保存在 data/web/identity.sqlite3，机厅数据使用独立数据库。SQLite 备份需使用数据库备份工具或停服后复制，避免只复制正在写入的主文件。备份应存放在私有位置。

当前依赖快照不能完整记录虚拟环境内的本地修改。重建环境前核对依赖、定制修改与数据恢复步骤，不要把 .venv/ 或 data/ 当作普通缓存清理。

检查与排障

1. 先区分页面打不开、Bot 未连接、某个功能失败或外部服务失败，查看对应进程及错误日志。
2. 网页改动后检查首页、舞萌、机厅、插件目录和文档，并检查未登录状态与手机布局。
3. 功能变更优先用测试与模拟服务验证，不把真实导分、人数上报或群通知当作普通页面检查。
4. 记录问题页面、操作步骤、错误文字和发生时间；分享日志前去除验证码、Token、二维码、Cookie 与个人信息。