Loreweaver

一句话定位：自托管「世界/故事优先」AI GM/Keeper——确定性引擎（骰子/CoC 理智/技能成长/属性全部真代码）+ LLM 只做叙事；M17 文档投影模型实现结构化反剧透信息隔离；内置 D&D 5e SRD + CoC 7e + WoD 三套规则包。类型：自托管 AI GM/Keeper · 开源 · 许可：MIT · 仓库：1A7432/loreweaver · 协议版本随包版本联动（v2.1）

1. 项目概述

本轮调研中工程完成度最高的开源 AI DM 引擎（35★ 但架构成熟度远超星数）。作者明确与「人设聊天前端」划清界限：Loreweaver 是「世界与故事优先」的引擎——结构化世界（模组 + 规则 + 持久状态）是地基，AI 只负责叙事/NPC/氛围。两大设计支柱：

确定性 vs 生成性严格分层（铁律 #1）：骰子、成功等级、角色数学、随机表、权限、审查全部是真实代码；任何 AI 都不许碰。
反剧透信息隔离（铁律 #3）：所有内容（模组、NPC 秘密、守秘人笔记、变量）都是「文档」，每个出站视图都经 project(doc, viewer) 投影——玩家视角、NPC 视角结构化地看不到守秘人信息；守秘人则永远持有全部真相（以便埋伏笔）。

2. 核心功能

规则包驱动（数据即代码）：rulepacks/*.yaml 定义检定阶梯、角色卡形态、子系统——内置 CoC 7e（理智检定、技能成长、消耗幸运、对抗检定、随机疯狂）、D&D 5e、WoD，新系统无需改代码。
KP 技能系统（Claude Code 形态 SKILL.md）：内置 module-forge（模组生成）、rule-forge（规则生成）、skill-forge、svg-mapmaker、image-gen、romance-relationships、mature-mode。
编年史折叠记忆：回合用量表达到上下文 60% 触发折叠 → 旧编年史批量并入滚动战役摘要（0.40 下限 / 0.85 紧急 / 4 回合滞后窗口），长期战役不丢关键剧情。
多模态演出：Director（演出导演）在剧情节拍时生成演出卡/信件/剪报/音效/配乐（bgm/ambience/sfx 分层）。
SillyTavern 角色卡导入（拆卡：世界机关与玩家可见内容结构化分离）+ EJS 模板沙箱。
内容包生态：.lwpack zip 打包技能+规则+卡片+世界书，Git Releases 即注册表。
双传输：Iroh p2p（默认，ticket 分享免域名/端口转发）+ WebSocket（本地/回环）；协议版本化（docs/protocol.md），TypeScript 客户端 npm 包 loreweaver-protocol。

3. 技术架构（分层，每层一个职责）

core/——确定性引擎：骰子、resolution（检定阶梯）、sheets（角色卡派生 DAG，派生值永不持久化）、character_rules（每次写属性都过规则校验）、clock、rulepacks、skills、关系轨迹、modvars、worldbook、charcard、chronicle、documents（M17：一切内容皆文档）。
infra/——SQLite（documents/room_state/kv）、pydantic-settings 配置、i18n（en/zh 全量双语言，lint 门禁）、llm/embeddings（各带 Fake* 离线替身）、多厂商 provider 工厂。
agent/——AI-KP 大脑：AgentCtx、@tool 工具（模式生成+门控）、forge（技能/规则/模组自扩展生成）、prompt_builder（唯一提示词组装点）、function-calling 循环、Scribe（书记官）/Director/companion 子演员。
gateway/——平台无关：会话/事件/回合/成员/房间、双方言命令（. 前缀 + / 斜杠）、限流/审查/权限、RoomHub。
net/——SessionCore（传输无关）、iroh_server（p2p QUIC）、tui_server（WebSocket）、keystore（邀请 key 管理）、房间备份。
clients/——TypeScript：protocol（共享类型+WsClient）、tui（OpenTUI 终端，主客户端）。
每回合模型调用预算：1 个玩家回合 ≤21 次调用（≤3 编年史折叠 + 12 工具轮 + 5 收尾检查 + 1 溢出重试），Scribe/Director 各 1 次；架构测试钉死该预算。

4. 本机实测记录（✅ 完整运行）

uv sync 被 lark-parser（纯 sdist）挡住 → 自建 wheel（可信 python 跑 setup.py bdist_wheel）后全量装齐（含 iroh）。
python -m app --doctor 全绿：30+30 语言文件；规则包 coc7（resolution DSL + 6 变体；子系统 sanity_check/skill_growth/spend_luck/opposed_check/random_madness）、dnd5e、wod；7 个 KP 技能。
CLI 实测：r 3d6+2 → [4,4,1]+2 = 11；/roll 4d6kh3 → 13；.ra 侦查（中文 CoC 技能检定）→ 目标 25 / 掷 39 / Failure；.setcoc 2、.roll 1d100 全通过。
WebSocket 协议真实 KP 回合（端到端）：join（守秘人 key 认证）→ input（玩家行动）→ TURN busy → 守秘人 function-calling 回合 → 流式 narrative_delta → 关闭 narrative 帧 → usage 统计（context 2559 / output 1536 tokens）→ TURN idle。全链路指向本地 KoboldCpp（Qwen2.5-3B）。
发现：--serve 只跑 Iroh p2p，WebSocket 需按仓库惯例直接实例化 TuiServer（20 行 wrapper，见实测报告）。
结论：3B 模型复读退化（as/as/as…），仓库明示「预算模型会跑偏、不掷骰」——引擎满分，模型是唯一瓶颈（换 7B 显著改善）。

5. 如何运行（复现）

git clone https://github.com/1A7432/loreweaver && cd loreweaver
uv sync --extra anthropic --extra gemini --extra ejs   # 或 pip -e ".[dev,anthropic,gemini,ejs]"
uv run python -m app --cli        # 骰子/检定 REPL（离线 demo 模式）
uv run python -m app --doctor     # 环境自检
# 真实 KP：.env 配 TRPG_LLM__PROVIDER/API_KEY/BASE_URL/CHAT_MODEL（OpenAI 兼容即可）
uv run pytest -q                  # 离线测试（FakeLLM，无需网络/密钥）

客户端：clients/tui（bun install && bun test）；或按 docs/protocol.md 自写客户端（join→input→narrative/dice/state 帧）。

6. 优劣势分析

优势	劣势
确定性/生成性分层 + 文档投影反剧透，架构教科书级	生态年轻（35★）、终端优先（无现成 Web UI）
CoC/D&D/WoD 规则包数据驱动，扩展不改代码	对模型要求高（小模型跑偏，官方明示）
编年史折叠记忆解决长期战役上下文	p2p 客户端需 bun/Tauri 栈
每回合调用预算 + 架构测试把成本钉死	内容包（模组）需要社区供给

7. 参考链接

仓库与文档：https://github.com/1A7432/loreweaver · https://1a7432.site
协议：docs/protocol.md；扩展契约：docs/plugins.md；防御性模式：docs/defensive-patterns.md
同类：diceframe（中文跑团引擎）、SumanasJ/coc-kp-host（中文 CoC KP 技能）、open-tabletop-gm