更新日志

开发版 · 协议 2.32026-08-19

撑得住事故的引擎 · 旗舰模组第一次跑完 · 命令层拆包 · 每个调用模型的地方都得报上车道

先把 8 月 7 日之后欠的账补上。协议走到了 2.3：工具调用的公开后果现在是在发生的那一刻广播出去——以前是回合结束后从记录里读出来再发，在流式 provider 上会把叙述排在它讲的那一骰上面；入房回放也把骰子帧和 NPC 台词按当时的顺序一起回放，而不只是正文；character.attributes 只下发规则包声明的特征值，不再把整张卡的键都倒出来；装好的内容包自带的卡可以直接从客户端挑着导入（list_pack_cards）。.st 名字=数值 是一次显式赋值，不会再被拆成两个词。

撑得住事故的引擎（M23）。长团涨出模型窗口时，不再是玩家这一回合直接报废：以 provider 自己的拒绝为准，引擎折叠一次、重发一次，而且只在折叠确实腾出了空间时才重发，所以不会和 provider 来回打乒乓；模型在窗口边缘说到一半断掉的回复，不再算作一个完成的回合。进过模型的内容都能从存档重建——撤回、中途加入的人补看、事后复盘，看到的都是模型当时看到的。每一种房间状态还得自己声明重置、删除、导入、导出该拿它怎么办，谁都不认领就构建失败——一个月里连修三次「重置漏了点东西」，要的就是这个。

旗舰模组第一次完整跑完。真模型、两个真人玩家、五十个玩家回合打通全部五幕。模组本身撑住了，NPC 的边界是最强的一项；引擎和守秘人这一侧有两处没撑住：守秘人看不见非行动玩家的卡，把那名玩家登记成了 AI 伙伴、替他行动了一整场；模组自造历法上的时钟推进被整条丢掉，日计数器从来没走过。两处都修在结构层——玩家的名字从任何入口都不可能再被写成 NPC 或伙伴，删伙伴连卡一起退，自造历法的推进照样送到房间钩子。这次实测还留下三个给主持人的把手：.npc / .companion（守秘人对名录的那只手：看、查、删）、.panel <id>（把模组面板渲成文字，给画不出来的客户端）和 TRPG_DEBUG__TOOL_TRACE（模型发出的每一次工具调用，连参数带结果，默认关——五条根因全靠它）。顺手的小件：世界卡房间不再被塞进五个只会失败的知识池工具；provider 说了要等多久，重试就照着等。

命令层拆了包，回合管道不再认识任何命令的名字。四千行的命令路由器拆成按域分的包——检定、卡表、规则、房间、名录、世界、面板、媒体、模型控制台各自一个模块，装进同一个路由器；新命令落在自己的域里加一行声明，永远不必去改回合流程。agent/loop.py 没拆，但顶部多了一张地图：一个回合的十一步、必须守住的不变量、看着像小改进其实是坑的清单。

每个调用模型的地方都得报上车道。规则本来写的是「任何模块不得往模型上下文塞文本」，比实际架构还宽——代码里一直有六个调模型的地方，其中四个（NPC、伙伴、导演、书记官）各自只能从自己的记录拼自己的提示词，这正是信息隔离本身。现在钉住的是锐的那条：守秘人的上下文只有一个装配器和一个调用者；其它每一处调用点都要在一张表里声明自己是哪一类，新加一处不声明就过不了构建；core/ 一次模型都不调——三个原本住在那里的模块（模组全文分析、文档检索问答、人设出卡）搬去了 agent/。聊天平台适配器不回来这条，也从一篇笔记变成了一条构建就红的测试。

还没做的：模组面板在服务端渲成的文字和客户端画出来的，目前靠手工对齐，两端共钉的向量文件在做；守秘人每轮能叫多少次 NPC 发言没有上限；.bind/.unbind 仍在。

开发版 · 协议 2.12026-08-07

规则变成数据 · 一个文档模型 · 长团记忆 · 演出层 · 版本号跟着协议走

规则系统现在就是一个文件。检定档位、卡表形状、子系统、点命令写法、给守秘人的说明，都归规则包自己所有，引擎不知道 CoC 是什么。验收方式很直接：把 rulepacks/coc7.yaml 删掉，CoC 就没了，引擎里不留残渣。检定结算是骰子引擎之上一小段声明式 DSL；骰池、命运骰、爆炸骰是引擎原语，所以「数成功数」这类系统也只是数据。DSL 写不出来的落到 QuickJS 沙箱纯函数，随机性和状态不出引擎。.setcoc 没有了，换成通用的 .rule——档位由规则包声明，不同系统能选的不一样。

房间里的一切都是同一种文档。设定、NPC、卡表、预设角色、追踪器、笔记、知识池，都收进一张表；每种类型注册一个 project(文档, 观看者)，所有对外的出口都走它。以前是五套并行的保密机制各管一段，现在只有一条路——这也是我们对它比较有底的原因。顺带把每一份按存储分列的备份白名单也一起去掉了，那是漂移 bug 的常见来源。

战役能比上下文窗口活得久。跑团过程记成编年史文档。提示占到模型窗口 60%，最老的记录成批折叠进滚动摘要，直到降回 40% 以下；最近四回合不折，正在进行的这场戏还不算历史。折叠过的记录进向量索引，所以第三场的细节到第十二场还找得回来。玩家那一面是 .recap，守秘人的剧透批注由投影过滤掉；守秘人那一面是 .chronicle，能看未收的线、手动折叠、直接改摘要。

模组可以自己布置牌桌。内容包能声明自己的面板，绑活的追踪器、按数值开关，放进侧栏／托盘／弹窗，谁能看见由服务端说了算；还有手作物、信笺、剪报、地图钉、幕卡这些演出模板。富客户端渲染得好看，终端把同样的字段打成几行，作者只写一份。之上是演出导演：一个玩家侧的演员，在剧情节拍上决定这桌人看见和听见什么。它的输入只有投影过的玩家可见流，加上模组自带的演出资料包，所以它拿不到守秘人材料。出图要有定妆参考图才做，作者也可以用 pack_only 一票否决；房间里的模组不带资料包，它就不会被唤醒，也不花钱。

发布版本号改成跟着协议走。之前三个数字在描述同一个东西，只有一个有人维护：协议说 2.1,npm 包说 2.1.0，而每个 wheel 和 Release 都说 1.0.1.dev*——因为版本基准是上一个 v* tag 自动加一位补丁，跟别的没有关系。现在基准直接从协议常量推导，改协议版本，下一次构建自己跟过去。第一个新形状的产物是 release-2.1.dev88+g21427a4。

文档站重做了一遍。玩家上手、开服带团、做一个模组、扩展契约、酒馆卡、hooks.js、部署、协议、路线图，九份文档中英各一版，都有了站点页面，并且是从仓库里的 markdown 生成的，不是另抄一遍。上一次两边各写一份的后果这里的读者可能已经碰到过：指令手册教了一个月早就删掉的 .setcoc。

还没做的：.bind/.unbind 在引擎里还留着，但它们服务的聊天平台适配器七月就删了，对用户是死命令；--doctor 只报随包发的目录，装进数据目录的内容包要在房间里用 .panels / .skill 看。

开发版 · 协议 1.92026-08-06

制卡工作室开源 · 预设导入 · 原生卡格式 · 兼容层三轮实测加固

Loreweaver Studio 开源了。和引擎配套的桌面工作室（macOS / Windows / Linux），三个工作台：拆卡台把任何一张酒馆卡拆开，让你看到引擎会怎么理解它——角色半与世界半、MVU 变量树提升成类型化状态量；制卡机是分阶段共创向导（世界观→性格→世界书→变量→开场白），AI 只做引导和整理，性格衍生这类关键创作位强制作者手写，还带一个「AI 八股」检查器；双输出：做一次卡，同时导出标准酒馆卡（PNG，酒馆里直接用）和 Loreweaver 原生格式。制卡机刚开门，想找愿意踩坑的作者。仓库：loreweaver-studio。

原生卡格式全链路打通。.lorecard.json 是无损的原生卡：类型化变量、守秘条目、条件注入都是一等字段，不用塞进酒馆卡的缝里。.import 自动识别，打包（--pack）、安装（--install）同样直通——自己的格式从制卡到分发到进房全程一等公民。顺带修掉一个真隐患：非守秘人导入带 secret 标记的条目，此前会把标记洗掉当公开内容落地，现在在导入关口结构性丢弃。

酒馆预设（preset）能导入了。.preset import 读一份酒馆 completion 预设——双层启用矩阵、8 个 marker 占位，语义都按酒馆实义解析——.preset enable 把它作为房间的「风格层」折进守秘人提示词：只塑造文风与框架，压不过骰子与守秘纪律。采样参数现在只报告、不应用。

兼容层被三轮真实对局打过了。拿社区流行的重型前端卡，用真实模型连跑三轮完整对局，每轮发现的问题当天修、当天复测：世界书按模组状态精准注入（路线/难度这类互斥条目组跟随变量树，不再看文件里的面板残留）；硬事件按卡内日程准点触发；[InitVar] 的 YAML 形态（近来新卡的主流写法）两端都认；「D1 上午 09:30」这类模组钟面可以直接推进；防泄密纪律块补进了卡导入的房间（此前只有 .module 知识池的房间有）。三轮红线全程零违例——不泄密、不先叙后掷、不伪造骰值。

协议走到 1.9。state.pregens 把模组自带的可认领角色池推给客户端（玩家 .pc claim 认领）；守秘人视角未暴露变量的 hidden 标记进了类型定义。npm 包 loreweaver-protocol@1.9.0 已发布，Studio 的协议依赖也切到了 npm——克隆它不再需要并排检出引擎仓库。

Windows 安装器修复（issue #17）。感谢第一位报告问题的用户。根因是安装脚本先在临时目录装依赖再整体改名，而 Windows 的 NTFS junction 只存绝对路径，改名后依赖链接全部悬空，启动即报找不到模块。现在先把客户端落到最终目录再装依赖，装完校验依赖真的可解析，失败自动回滚旧版本——重跑一行安装命令即可。

终端客户端小修。面板模板碰上没公开的变量一律不显示（卡自带的面板永远看不到你没 .var expose 的内部量）；选项列表不再只显示一半；叙事里的插图链接渲染成「[图] 说明」占位，不再是一段裸文本。已知未修：变量很多时侧栏还不能键盘滚动，在排期上。

v1.0.0 · 协议 1.72026-07-29

v1.0.0 正式版：酒馆卡真的能跑 · 事件钩子 · 内容包

第一个正式版。Release 页从此既有 v1.0.0 这样的正式版，也有随主干滚动的开发版；想装哪个，安装时用 TRPG_RELEASE_TAG 钉住对应 tag 就行，客户端和一键开服的服务器程序会来自同一个 Release。协议版本走到 1.7，协议 SDK 也发上了 npm（loreweaver-protocol，带类型的帧定义 + 自动重连的 WebSocket 客户端），想自己写客户端或机器人的可以直接用。

酒馆卡从「能导入」变成「真的能跑」。MVU 变量树导入（[InitVar]，重复导入不清进度）、<UpdateVariable> 五命令文本协议由引擎代码解析记账、完整 EJS 模板在 QuickJS 沙箱里跑（装 ejs extra 默认开启，循环/函数/lodash 都行）、世界书触发语义整套落地——副键四种逻辑、probability 真掷、sticky/cooldown/delay 挂游戏回合、分组抽选。{{user}}/{{char}}/{{roll:XdY}} 这些宏也认，其中 {{roll}} 走真骰子引擎。哪些地方和酒馆不一样，写在新的卡作者指南里。

模组有了自己的计分板。守秘人（或模组）可以声明类型化状态量——数值/布尔/文本/枚举，可设边界，可标「仅守秘人可见」——每次变动由引擎校验、钳位，不是模型拍脑袋。玩家可见的部分实时显示在 TUI 侧栏的状态量面板里，仅守秘人可见的在引擎内部就被过滤，永远不出服务器。

模组能带行为了。技能旁边放个 hooks.js，或者卡带上 extensions.loreweaver_hooks，就能在回合生命周期上挂沙箱 JavaScript：回合开始、回复就绪、掷骰、变量变更四个事件。钩子能记变量、往守秘人提示词里塞段落、追加或改写叙事，还能用 emitUI 画声明式 UI——进度条、徽章、选项按钮，走协议 1.7 的 ui 帧由客户端渲染。钩子只提请求，引擎校验后才落实；脚本写坏了顶多钩子失效，坏不了回合。写法见 hooks.js 作者参考。

.lwpack 内容包。技能、规则包、角色卡、世界书、媒体素材打成一个 zip:python -m app --pack 一行打包，--install 一行安装，装的来源可以是本地文件、直链或 gh:owner/repo@tag（直接从 GitHub Release 拉，没有中心商店）。装之前先看信任卡片——包里有多少技能/卡、带不带沙箱脚本、素材多大——确认了才落盘，每个文件都过完整性校验，打包结果字节级可复现。

Windows 安装器修复。此前安装脚本在系统自带的 Windows PowerShell 5.1 上会失败（issue #8），现已修复——不用先装 PowerShell 7 了。

协议 1.42026-07-06

终端多媒体整套落地：图片 · 音频 · AI 生成图 · SVG 地图

发图。图片像 Claude Code 一样直接粘贴或者拖进输入框回车就发给全桌，聊天流里有内联预览。推荐使用 Ghostty、WezTerm 一类的现代终端工具，走 kitty graphics 协议真像素原生渲染图片。Win11 自带的 Windows Terminal 1.22+ 虽然也做了自动检测走 sixel，但图片排版不确定能不能像其他支持 kitty graphics 协议的一样好和稳定。啥都不支持的（比如 mac 自带终端）会回落成半块字符画的形式输出，体验明显会差些。

音频。守秘人可以建房间音乐库，分 .bgm / .ambience / .sfx 三种。音频文件会传输到各家客户端本地播放，其中背景音乐循环放，环境音铺底，音效一次性。暂时只能由守秘人手动使用以上指令播放，以后打算做个 skill 由多模态模型 KP 自动选择播放。

AI 生成图。这个倒是已经可以通过 skill 让 AI 自动干了。配一个画图模型的 key，开 skill 开关，KP 就会在换场景、重要 NPC 登场这种时刻生成场景图/立绘发全桌。也能生成头像挂在队伍面板上。酒馆卡导进来的角色自动用卡面当头像。

画地图/房间结构。顺带还加了画地图功能，不是用的 AI 生成图片——那个生成地图随机性太大了完全不可控，文字标注信息也不可读。我是通过一套 skill 里的提示词和工具包让它写 SVG 矢量图生成的。为了安全考虑只放行了 SVG 静态安全子集，不过够用了。

首发2026-07-05

开源发布

Loreweaver 在 GitHub 公开，MIT 协议。真骰子引擎 + AI 叙事的切分、Iroh p2p 联机（发个 ticket 朋友就能连）、一键本地开服；955 个确定性离线测试全绿。首发于 LINUX DO 社区。