核心架构与设计理念
dnd-dm 采用创新的三层分离架构，从根本上解决了传统AI城主系统"幻觉计算"与"规则漂移"的顽疾。底层 dnd-engine（Python包，90项测试覆盖）封装纯函数式规则引擎，涵盖骰子、战斗、存档、SRD搜索等核心机制；中层 dnd-api（FastAPI :8081）提供22个标准化HTTP端点，支持Discord、Foundry等任意平台接入；顶层LLM层专注叙事生成与NPC对话，通过prompt调用下层API完成所有计算。这种"LLM不计算、引擎不叙事"的严格边界，确保了2024版规则的精确执行。
核心功能亮点
战斗自动化：命中/伤害/豁免检定完全由 dnd_engine.combat.checks 结构化处理，LLM仅渲染 detail_lines 数组；战斗状态持久化至JSON，支持中断续战。
渐进式探索：幕前通过自然语言暗示引导玩家，幕后以 _scene_cache_*.json 精确追踪房间状态与回声映射，实现"模糊叙事+精确状态"的平衡。
对话式角色创建：7阶段流程，属性roll由引擎层 roll_stat() 执行，杜绝LLM虚报数值。
模组化运行：通过 MODULE_ARC.md 剧情框架与 ECHO_ARC.md 回声系统，支持复杂模组的节奏控制与信息层管理。
显著优点
- 规则权威性：锁定2024版三宝书，15条行为红线（如"自然1不重投""禁止混用世界观"）从系统层面消除规则漂移。
- 可扩展性：API层设计使任何IM软件均可驱动，无需专用客户端。
- 可审计性：所有检定公式、状态变更均有代码级可追溯路径。
潜在局限
- 部署复杂度：需同时配置Python环境（dnd-engine）、API服务（可选）与LLM层文件，技术门槛高于纯prompt方案。
- SRD依赖：规则引用基于SRD 5.2.1，部分2024版专有内容需用户自行准备。
- 实时性限制：HTTP调用引入延迟，不适合对毫秒级响应有极端要求的场景。
适合人群
TRPG主持人寻求AI辅助以减轻 cognitive load；跑团平台开发者需要标准化D&D 5e规则后端；规则严谨派玩家厌倦了AI"口胡"DC与伤害数值。
常规风险
- 版本锁定风险：2024版规则仍在迭代，引擎层需跟进官方勘误。
- 存档兼容性：
live_party.json与_scene_cache_*.json格式变更可能导致旧存档失效。 - API依赖：若选择本地部署dnd-api，需自行保障服务可用性与并发安全。