Loreweaver 路线图

Loreweaver 还很年轻，基本是一个人带着 AI 写出来的。这份是老实的前进计划：现在在忙什么，往后想做成什么样，以及一个曾经真的犹豫过、现在已经定下来的设计问题。分层契约和铁律在 AGENTS.md。

想做成什么

目标不是“拿 AI 顶替一个主持人”，而是做 AI RPG 的引擎与开放标准。会写代码的 agent 到处都是，能把一场团跑好的却几乎没有；而一个世界要想被带走、被续写、被别人的程序读懂，需要的格式压根还不存在。这里每一层——真骰子和硬规则、靠工具调用做事的守秘人、只知道自己该知道那部分的子角色、照着 SKILL.md 和酒馆惯例长出来的扩展生态——都朝同一个方向：让“把一个世界跑好”成为 agent 的一等能力，而且跑在谁都不用申请许可的格式上。

现在到哪了

确定性引擎——骰子、检定档位、角色数值、规则校验、游戏内时钟——是最扎实的部分，有一整套离线测试盯着。终端客户端（OpenTUI）仍然是主力，走 Iroh p2p 连接。五个聊天平台适配器（Discord/QQ/Telegram/飞书/OneBot）在 2026-07-30 主动删掉了：项目的界面方向是声明式 ui 帧、实时追踪面板、可深度定制的客户端扩展层，纯文本聊天平台根本画不出来，所以客户端一律改走开放协议。

v1.0.0 是第一个稳定版，之后在 1.0.1.dev* 这条线上继续开发。这期间落了七个结构性的里程碑：

• 规则变成了数据（M16）。 一个规则系统就是一个文件，检定怎么判、卡表长什么样、有哪些子系统、认哪些点命令、要跟守秘人交代什么，全在这个文件里。引擎不再知道 CoC 是什么：有架构测试盯着 agent/ 里一个规则系统的词都不许出现，把 rulepacks/coc7.yaml 删掉，CoC 就干净消失、不留残渣。DSL 表达不了的系统，走沙箱里的纯函数通道。
• 一个文档模型（M17）。 房间里的所有内容——设定、NPC、卡表、预设角色、追踪器、笔记、知识池——都是同一个 Document 类型，每种类型的 project(document, viewer) 是所有内容出门的唯一一道口子。原来五套各管一摊的保密机制合成了一套，每个存储各自维护的备份白名单（一个稳定的 bug 来源）也跟着没了。
• 能撑过上下文窗口的长团记忆（M18）。 跑团过程记成编年史文档，按一套固定策略折叠进滚动摘要，于是一场战役可以比它的上下文窗口活得更久。.recap 就是同一批文档给玩家看的那一面。
• 演出层（M19）。 演出导演是一个站在玩家这边、知识受限的演员，在剧情节拍上用声明式演出模板、音频提示和有定妆约束的生成图布置舞台，剧本是模组作者随包发的一份创作简报。协议 2.1。
• 回合有了纪律（M20）。 提示词保持一段字节不变的头部，模型缓存才真的省钱；工具分成备团和跑团两个阶段，内容包塞不胖正式回合；这一桌自己的玩法习惯沉淀成程序性记忆；回合还能撤销——.undo 倒回的是整个房间，不只是聊天记录。
• 记忆自己会写（M21–M22）。 抄写员本来就每回合都在看，现在编年史由它顺手写下，一次额外的模型调用都不花，战役记录从此不指望守秘人记得动笔。底下那套折叠依赖的上下文窗口算术，也在一张过期表格把某个窗口放大了十六倍之后，拿各家厂商自己的文档逐个重新核对过。
• 撑得住事故的引擎（M23，spec 已公开，英文）。 长团涨出模型窗口时，不再是玩家这一回合直接报废：以模型自己的拒绝为准，引擎折叠一次再重发一次，而且只在折叠确实腾出了空间时才重发；模型在窗口边缘说到一半断掉的回复，也不再算作一个完成的回合。进过模型的内容现在都能从存档重建——撤回、中途加入的人补看、事后复盘，看到的都是模型当时看到的。每一种房间状态还得自己声明重置、删除、导入、导出该拿它怎么办，谁都不认领就构建失败——一个月里连修三次“重置漏了点东西”，要的就是这个。定下的和否掉的设计决策也进了仓库（docs/notes/，英文）。
• 旗舰模组的第一次完整实测，以及它买来的结构（2026-08-18/19）。 真模型、两个真人玩家、五十个玩家回合打通全部五幕。模组本身撑住了；引擎和守秘人这一侧有两处没撑住：守秘人看不见非行动玩家的卡，把那名玩家登记成了 AI 伙伴、替他行动；模组自造历法上的时钟推进被整条丢掉，日计数器从来没走过。两处都在结构层修掉——玩家的名字从任何入口都不可能再被写成 NPC 或伙伴，删伙伴连卡一起退，自造历法的推进照样送到房间钩子——这次实测还留下三个给主持人的把手：.npc / .companion（守秘人对名录的那只手）、.panel <id>（把模组面板渲成文字，给画不出来的客户端）和 TRPG_DEBUG__TOOL_TRACE（模型发出的每一次工具调用，连参数带结果，默认关）。次日一次整仓评审发现债是集中的、不是散的，要紧的两半当天落地：四千行的命令路由器拆成按域分的包（新命令落在自己的域里，永远不进回合管道）；每一处调用模型的地方都要声明自己的车道——守秘人的上下文只有一个装配器和一个调用者，core/ 一次模型都不调，新加的调用点不起名就过不了构建。

在这些之外还有：确定性的模组变量和实时追踪面板；对导入的酒馆卡的完整兼容（MVU 变量树、<UpdateVariable> 文本协议、QuickJS 沙箱里的完整 EJS、酒馆世界书的触发语义）；能画声明式界面的沙箱事件钩子；走 Git Release 分发的 .lwpack 内容包；以及发在 npm 上的协议 SDK（loreweaver-protocol，它的 major.minor 跟着协议版本走）。再往上是拆卡：导入会把一张酒馆卡拆成人物那一半（玩家可以自己带，机制被结构性剥掉）和世界那一半（只能由守秘人 .import … world）；内容包给卡标 world / character，这个标签由真实检测说了算；导入的变量树默认不上玩家面板，得守秘人一条条公开；模组还可以用规则包补丁（extends: coc7 加增量）的形式带自己的房规。细节见 plugins.zh.md、authoring.zh.md、cards.zh.md、hooks.zh.md。

地基——已经打完的

在往宽了做之前，有些不好看但必须先做对的事情刚刚做完。现在这个项目能干净地装上、行为正确，给一小群人用也更放心：

• 能装。 wheel 里带齐了所有包和运行时数据（本地化、规则包），所以 pip install 在一个干净环境里就能用，不必非得从源码目录跑。
• 权限。 玩家和守秘人的区分现在在每一个命令入口上都生效了——以前只有管理帧那一层守着，一个玩家密钥可以从终端直接跑守秘人专用命令。会带出秘密的回复，比如遮掉一半的 API key、守秘人专属设定，只发给发问的人，不往房间里广播。
• 角色数值。 改一项技能或属性不会再顺手把受伤的调查员治好；建卡时衍生值算对了（生命和魔法满值，SAN = min(POW, SANMAX)）；每一条写属性的路径都被规则包钳在合法范围里。
• 老实的内容过滤。 过滤器默认关闭，也不随包带词表（要用自己配），文档就这么写，不去暗示“内置审核”。
• 每晚拿真模型跑红线。 一个定时任务让真模型走一遍完整回合，测两件事：守秘人的秘密有没有被原样说出来或者换个说法说出来，以及该掷骰的地方有没有真掷。超过阈值就算失败。它只是某个模型、某一次运行的回归信号，不是长期保票。（为什么必须和离线测试分开，见下面这节。）
• 传输和发布的杂活。 Iroh 的 join 超时、守秘人密钥只能管自己房间、支持的系统上敏感文件收紧到仅本人可读、发布包带摘要校验、稳定版和预发布分流、CI 同时跑 Python 3.11 和 3.12，以及清理死代码。
• 聊天适配器：做出来了，又退役了。 五个平台适配器（Discord、QQ 官方、Telegram、飞书、OneBot 11）做到了相当能用的程度，有 mock 测试覆盖，然后被主动删掉：界面方向定成声明式帧加模组自绘面板之后，纯文本渲染就是一条死路，与其一直端着一个二等体验，不如老实下线。它们验证过的跨传输 RoomHub 留了下来，现在撑着 CLI 和协议客户端。

近期

• 联机再打磨一遍。 权限这一层已经守住了，接下来收拾联机剩下的毛刺——真正的机器人循环防护、中途加入的人能看到更完整的状态——让一桌熟人玩起来是真的舒服。
• 桌面客户端是推荐的游玩方式。 loreweaver-studio 从制卡工作台起步，现在是完整的图形客户端：Markdown 叙事流配带颜色的骰子、实时的角色 / 队伍 / 变量面板、模组自带的面板——一层模板和沙箱里的二层页面，也就是终端结构上画不出来的那部分——守秘人的那几屏（房间与邀请、模型、模组、规则、技能、建卡），以及同一个一键「本地托管并游玩」；另一个模式是工作室（锻造、拆卡、.lwpack 构建、AI 起草——和手敲内容过同一套校验）。它跟着协议 2.3 走，有一道跨仓库的往返门：它的输出和引擎的解析器一漂移就红。它还缺的是安装包：今天从源码构建（macOS 已验证；Windows / Linux 在 CI 里能编译），发行包是下一步。终端客户端不退场——一行命令装好、有终端就能跑，服务端自己的 --cli 和实测 harness 驱动的也是它。
• 一个旗舰模组。 格式值多少钱，取决于第一个认真用它做出来的东西。旗舰模组正在做，而且是和面板、演出层一起设计的——让这一层有个真的使用者，而不是一个假想的。

再往后——世界引擎

真正拉开差距的是冒险底下那个世界，而不只是“带骰子的聊天”。长期方向：

• 可深度定制的界面扩展层。 这也是砍掉聊天适配器的原因：模组和钩子应该能画出自己的界面。今天是声明式 ui 帧（进度条、徽章、选项按钮），接下来是更丰富的模组自定义面板和客户端扩展点——让一个世界不只带规则和设定，还带自己那套桌面陈设。渲染目标是协议客户端（终端客户端和配套桌面客户端）。
• 更深的世界书： 会生长的世界（不只是靠关键词和向量把设定捞出来）、有因果的时间线（一件事的后果会往下传）、设定一致性（守秘人没法和已经定死的事实自相矛盾）。
• 中途加入的人自动补课： 半路进来的玩家，会被补上他的角色本来就该知道的那些事，同时不漏出他不该知道的。
• 导入 D&D Beyond 角色卡，和现有的酒馆卡通道并行。
• 预编译覆盖更多平台，现在是 Windows x64、macOS arm64、Linux x64/arm64。

一个已经关掉的问题

守秘人的秘密该放在哪？ 这件事一度是真的岔路。守秘人的系统提示里几乎完整地带着模组的守秘人材料，守秘人专用工具也把秘密原样交回给模型——所以在守秘人这一侧，防剧透靠的是纪律（一条“这些别引给玩家”的指令），不是结构上的保证。另一条路是把秘密从基础提示里拿出去，让守秘人用工具现取，模型任何时刻只握着它刚推理过的那一条。

我们决定不走那条路。 一个不掌握全部真相的守秘人主持不了谜案：它埋不了伏笔，把握不住揭示的节奏，两场之后就开始自相矛盾。给守秘人自己的知识分级，等于拿产品的立身之本去换一点泄漏面，而泄漏面本来就该由行为评测来管。所以这条界线是永久的，也是故意的：

• 对其他所有人，是结构上的保证。 玩家、NPC、同伴、演出导演拿到的只有投影，别的什么都没有。这由代码结构保证，另有一组专测泄漏的测试盯着。
• 对守秘人本人，是行为上的要求。 它看得见模组，它被要求不许引用。这条要求是每晚拿真模型实测的，而不是当成保证来宣称的。

老实的说法就是 README 和 deploy.zh.md 里的那一句，而且会一直留在那儿：CI 绿说明的是引擎正确，不是守秘人嘴严。

离线测试和真模型质量

这件事值得直说，因为“CI 绿了”太容易被过度解读。离线测试套件是确定性的，用的是一个脚本化的守秘人。它严格地证明确定性的那部分机制：守秘人材料和玩家材料的过滤、子角色的提示隔离、固定种子的真骰子、命令入口——这些里面任何一处退化都会被它抓住。它证明不了一个活的模型不会把看过的秘密说出去，也证明不了它一定先掷骰再叙述；那些是模型的行为，正是每晚那道真模型红线要测的东西。所以“CI 绿”要读成引擎是对的，不是守秘人是好的。

想搭把手

上面任何一条都可以，或者 README 里标了 🧪 的任何一条。提 PR 之前，uv run ruff check …、uv run python scripts/i18n_lint.py 和 uv run pytest -q（还有相关的 bun test）都得过，AGENTS.md 里的铁律也得守住：用户能看到的字符串一律不许硬编码，该由代码算的绝不交给模型，信息隔离一次都不能破。