Eventer 操作手册
1. 当前电脑怎样使用
打开终端：
cd /home/zhou/share/eventer
./start.sh等待终端显示「Eventer 已启动」，在浏览器打开 http://localhost:8765。优先使用 Chrome、Edge 或 Chromium。第一次加载约 17 GB GGUF 需要等待，状态和错误写在 .runtime/logs/model.log、.runtime/logs/app.log。
启动命令会同时运行本地语言模型和应用，并尝试打开浏览器。无桌面时使用 ./start.sh --no-browser。在当前终端按 Ctrl+C 安全停止两个服务。关闭浏览器不会停止演化；要暂停世界，请先在页面点「暂停世界」。重启应用后，所有世界从已保存状态恢复，保持暂停。
如果提示已启动，直接打开上述地址；不要启动第二份。端口冲突可运行 ./start.sh --port 8766 --model-port 8082。
当前机器运行于 Linux。若在 Windows 使用，推荐 WSL2 的 Ubuntu 24.04，安装可供 WSL 使用的 NVIDIA 驱动，在 WSL 内执行这些命令，然后用 Windows 浏览器打开 localhost。Windows 原生、macOS 和无 NVIDIA 的完整模型模式本版未实测。
2. 在其他电脑安装
从项目网站下载源码包并解压。需要 Linux x86_64、Python 3.12 或更新版本、python3-venv、curl、可用的 NVIDIA 驱动；RTX 3090 的 24 GB 显存适合这里的 27B Q4 模型。建议系统内存至少 16 GB，模型之外预留约 5 GB 磁盘。
cd eventer
./setup.sh
./start.sh --model /你的模型目录/模型.gguf安装会创建 .venv，安装锁定的 Python 依赖，下载约 1.0 GiB 的官方运行库和语音模型压缩包，再校验、解压。网络中断后重新执行 ./setup.sh，完整分片会保留。首次安装需要联网，完成后推理不访问云模型。
默认自动查找项目上一级 model/ 中唯一的 .gguf；有多个模型时必须指定 --model，也可设置 EVENTER_MODEL。当前实测文件为 Qwen3.6-27B-Uncensored-HauhauCS-Aggressive-Q4_K_P.gguf。本项目不分发该语言模型。3090 默认全部层上 GPU、16,384 上下文、单推理槽、Q8 KV、关闭思考输出。其他架构 GGUF 的支持取决于 llama.cpp。
只查看界面与代码规则时，用 ./start.sh --demo，再点击「探索规则演示」。这不会加载语言模型，不能用来判断真实模型质量。
3. 创建世界
点击「创建一个世界」。输入世界观、故事背景、地点、人物关系、当前局面、你关心的限制。可以点击示例填入「雾港」。例如：
灯塔熄灭的小镇里，修理工在修理铺找电池，船长在码头调查船只，守塔人在塔内等待。每个人有自己的目标。没有魔法，物品不能凭空出现，修理需要工具和本人在场。
点击「建立这个世界」，等待模型输出并通过结构和引用校验。页面会显示真正的错误，不会在失败时偷偷替换成示例故事。世界初始化后自动存档，先检查「世界规则」与存在状态，再开始演化。
在「世界规则」中可编辑、新增或移除自定义规则，每次修改都暂停世界并写入历史。代码约束里的「禁止」是全世界所有人物禁止该类动作；「执行者标签」检查人物本身，不能用它表示目标物品的标签。复杂的「带某物到某地才能修理」应选择模型裁决、作用于自定义互动。固定设施不能拿取等内置规则始终有效。
本版上限为 12 个地点、12 个人物、40 个存在、30 条规则；初始化默认创建较小场景，以控制 3090 的响应时间。全文设定最多 12,000 字符。复杂设定建议从一个小区域开始。
4. 观看世界自行演化
「推进一轮」收集所有自动人物和用户人物的意图，完成统一裁决，时间前进默认 5 分钟。所有自动人物均基于这一轮开始前的快照作出计划，镜头切到谁不会影响其他人物是否行动。
「持续演化」会循环推进，每轮完成后等待 4 秒。推理需要真实计算时间，页面的「规划」「裁决」状态会显示当前阶段。只允许一个世界持续运行，切换另一个世界到持续模式会暂停前一个。
「暂停世界」会取消尚未提交的后台轮次，保留上一份完整快照。推理故障也会暂停并显示错误；恢复模型后可继续。页面关闭但服务仍运行时，世界会继续演化。
世界图中的数字是当前位置的人物数，点击地点筛选右侧存在。事件流显示成功或拒绝的行动及原因。被拒绝的行动不会扣体力或留下半完成的状态。
5. 进入世界，参与交互
点击某个人物，然后「接管这个人物」，世界会暂停；这个人物以后只执行你提交的行动。也可点击「构建存在」新增自己控制的人物，填写名称、人设、目标和初始地点。添加物品属于建世界操作，会留下创建记录。
在人物行动面板选择：
| 行动 | 如何使用 |
| 观察等待 | 该人物本轮不改变位置或物品 |
| 休息 | 恢复 12 点体力，上限 100；仍受世界约束 |
| 移动 | 只能选择相邻、有道路连接的地点 |
| 拿取 | 同地点无主的可移动物品；固定设施不能拾取 |
| 交给 | 选择持有物品与同地点接收人物 |
| 使用 | 消耗自己持有、带 consumable 标签的物品，恢复 25 点体力 |
| 交谈 | 选择同地点人物，输入要说的话，形成客观事件 |
| 自定义互动 | 写具体行动，模型按规则裁决，可改变本人或目标的描述状态 |
点「提交到下一轮」，再点推进或持续演化。每个人只保留一个待执行意图，重新提交会替换原意图。尚未执行的意图可撤销；它只保存在运行内存中，重启后需要重新提交。
同时争用同一人物或物品时，按每轮轮换的确定顺序分配机会，其他冲突行动拒绝。同一轮不能先拿物品再交给别人，不能先移动再用终点处的资源。
自定义互动可以把灯塔设备的描述状态从「熄灭」改为「运行」，但不能绕过代码修改位置、所有权、体力、健康、数量或时间。生命损伤、物品生产等更复杂数值系统尚未实现。需要这类规则时应扩展代码动作，不能依赖一段模型叙述冒充实际数值变化。
6. 文字与实时语音
右下对话窗口可选择「世界观察员」或某个人物。文字按 Enter 发送、Shift+Enter 换行；输出逐字显示。观察员看全局，人物对话提供该人物与同地点存在的状态。对话只做交流，不自动修改世界；真正说给其他人物听并写入时间线，使用行动面板的「交谈」。
接管人物后，对话对象中会出现「替某人行动」。在这里输入或说出「走到广场」「拿起电池」等指令，模型转成行动并排入下一轮。提交只代表意图，是否成功以事件流为准。可以先打开持续演化再用语音参与；对话期间后台规划暂时让出模型，随后重新从完整快照规划。
点击圆形麦克风开始录音，再点结束。声音在本机转成文字后自动发送。勾选「语音朗读」会分句合成并按顺序播放；勾选「连续对话」会自动检测说话及约 0.7 秒停顿，持续进行识别和回应。为减少扬声器回声，连续模式在识别、回复和播放时暂不收音。要立即插话，可以点麦克风重新录音，或点「停止」中断回复与播放。连续模式不是同时收听和播放的全双工通话。
单次录音最长 20 秒；上传音频最长 30 秒，需要 16 位 PCM WAV。没有麦克风也可正常使用文字、朗读和上传 WAV 测试。
点击「音频设备与状态」可查看模型、ASR、TTS 是否就绪、最近耗时，并试听中文合成。网页不会调用浏览器的在线 SpeechRecognition 或云端 TTS。
7. 以后连接蓝牙耳机
先在系统设置配对蓝牙耳机，确认操作系统能录音和播放。打开「音频设备与状态」，点「授权并刷新设备」，允许浏览器使用麦克风，然后选择输入与输出设备。切换输入会关闭旧录音，重新点击麦克风或勾选连续对话即可。
某些浏览器不支持网页选择输出设备，此时在系统声音设置中切换扬声器。蓝牙耳机进入通话模式后音质和延迟可能变化，需要接上实际硬件后试听调整；本次没有用真实蓝牙耳机验收。为了避免扬声器回录，建议语音对话时佩戴耳机。
麦克风权限仅能在本机 localhost/127.0.0.1 或 HTTPS 页面申请。如果浏览器在另一台电脑，而程序运行在这台 Linux 电脑上，可使用 SSH 本地转发：
ssh -L 8765:127.0.0.1:8765 用户名@运行Eventer的电脑然后在浏览器所在电脑打开 http://localhost:8765；不要直接把本地 API 暴露到公网。
8. 保存、导出、恢复、分支
每次世界修改连同完整快照、事件和哈希链在一个 SQLite 事务中提交，文件为 data/worlds.sqlite3。聊天保存在同一数据库。原始音频不存档。
点击世界标题旁的下载图标导出 JSON，含全部世界历史与对话；从侧栏「导入世界存档」恢复。导入会校验每一版本和当前状态，生成独立世界，不覆盖原世界。网页导入限制 8 MB；较大世界请停止程序后整体备份/恢复 data/ 目录。不要只复制正在写入的 SQLite 主文件而遗漏 WAL。
「历史与分支」可查看任意版本快照、从该版本建立新的世界，或校验历史完整性。分支继承所选时刻的状态，原世界不变；分支的历史从分叉记录开始，原历史仍在原世界。版本号对应每次提交，轮次只对应时间推进，两者不同。
9. 常见情况
- 未检测到 CUDA：先运行
nvidia-smi，确认驱动和显卡可见；重新执行./setup.sh检查运行库。安装脚本不改变系统驱动。 - 显存不足：关闭其他 GPU 程序；尝试
./start.sh --ctx 8192并缩小世界设定。语言模型过大时需另选合适量化文件。 - 模型输出格式错误：缩短初始设定、减少人物，查看日志重试。未通过校验的初始化不会建立世界；未提交的轮次不会污染存档。
- 声音没有播放：先点击「试听本地语音」，允许浏览器播放；检查系统静音与输出设备。语音模型加载未完成时先用文字。
- 识别同音字错误：使用较安静环境并清晰说出名称；涉及精确人物/物品选择时用行动面板。生成语音回测也可能出现同音误差。
- 卡在某一轮：查看
.runtime/logs/model.log与页面错误。暂停后可单步重试，已提交历史仍保留。 - 下载中断：直接重跑安装脚本。资源来自官方 GitHub Release，若当前网络限制 GitHub，需要先让终端能够访问这些下载域名。
10. 网站与本地应用的关系
https://eventer.codeloop.cn 发布项目介绍、源码下载、操作手册和验收说明。真正的世界计算在你的本地 GPU 上完成。公网服务器没有语言模型、私人世界数据库、录音或本地控制接口。公网部署沿用 wild 的独立 Nginx 站点、独立证书、版本目录和 current 链接方式。