1. 项目概述用AI重构你的龙与地下城战役管理如果你是一位《龙与地下城》DD地下城主DM或者正打算成为一位那么你一定对战役管理的繁琐深有体会。从整理玩家角色卡、设计平衡的遭遇战、到查阅海量规则书、再到为每个城镇和NPC填充细节——这些工作常常会消耗掉你本应用于构思精彩故事的宝贵时间。更别提当玩家突然问起“上次那个矮人铁匠叫什么来着”或者“我这个法术在这个环境下具体怎么生效”时你需要在成堆的笔记和PDF中手忙脚乱地翻找。5e-cursor这个项目正是为了解决这些痛点而生。它不是一个传统的桌面应用或网页工具而是一套深度集成在 Cursor 代码编辑器中的AI 优先战役管理解决方案。其核心思想是你不再需要学习复杂的软件操作也无需在不同的标签页和工具间反复切换。你只需要像和一位无所不知的助理对话一样用自然语言告诉 Cursor AI 你的需求它就能调用背后的工具链自动完成从数据整理到内容生成的一切工作。想象一下这样的场景你正在为下一场跑团做准备。你只需要在 Cursor 的聊天框里输入“为我的5级4人小队设计一场‘困难’难度的遭遇战敌人最好是亡灵生物。”几秒钟后AI 就会生成一份包含具体怪物组合、经验值计算、战术建议的完整遭遇战文档并自动保存到你的战役文件夹中。或者当玩家在游戏中想要施展“火球术”时你可以直接问 AI“火球术的详细规则是什么”它会立刻从本地索引好的规则库中找到精确的条文并附上引用来源呈现在你面前。这一切的基础是项目将 DD 5e2024版的核心规则书以及部分扩展内容从开源的 5etools 数据仓库中提取出来转换为一套结构清晰、便于 AI 理解和检索的 Markdown 文件和 JSON 索引。你的所有战役数据——角色、NPC、地点、会话记录——也都以 Markdown 格式存储。这意味着你的所有心血都是纯文本永远掌握在自己手中不依赖于任何可能关闭的在线服务。同时项目还提供了一个现代化的 Web 界面让你可以直观地浏览和搜索你的整个世界。2. 核心设计思路为何选择“AI优先”与本地化存储在深入实操之前理解5e-cursor的设计哲学至关重要。这决定了它与其他战役管理工具的根本不同也解释了其工作流的独特优势。2.1 “AI优先” vs “界面优先”大多数传统工具如 World Anvil, Campfire, 甚至 Roll20 的百科是“界面优先”的。它们提供一个图形界面你需要点击按钮、填写表单、在菜单中导航来完成操作。这种方式直观但步骤固定效率有上限。当你有一个复杂或跨模块的需求时例如“找出所有在‘被遗忘的国度’设定中出现的、挑战等级CR在3到5之间的、会对火焰伤害有抗性的怪物”你可能需要组合多次筛选和搜索。5e-cursor的“AI优先”模式则颠覆了这一流程。它将复杂的工具链数据提取、角色导入、遭遇战计算、规则引擎全部封装在后台只向你暴露一个统一的、最自然的接口自然语言。你不需要知道调用哪个脚本、传递什么参数你只需要“说出”你的意图。AI 扮演了翻译官和调度员的角色它理解你的自然语言请求将其转化为具体的函数调用和参数执行后再将结构化的结果用你能理解的方式呈现出来。这种模式的巨大优势在于灵活性和上下文感知。AI 可以理解模糊的、关联性的请求。例如“创建一个与‘黑荆棘’酒馆老板有债务纠纷的狡猾半身人盗贼 NPC”。AI 会先检查你的战役中是否已有“黑荆棘”酒馆然后生成一个不仅包含标准属性还自动建立了与现有地点关联的 NPC 档案。这是传统表单式工具难以实现的。2.2 本地化存储与数据主权另一个核心设计原则是数据本地化和开放格式。你的所有战役数据campaign/目录下和提取的规则参考books/目录下都存储在本地硬盘上格式是纯 Markdown 和 JSON。这带来了几个关键好处完全离线工作一旦完成初始设置和数据提取你可以完全断网进行战役准备和跑团。所有规则查询、遭遇战生成都在本地完成无延迟无隐私担忧。数据永存且可移植你的战役故事、自定义 NPC 和地点都是简单的文本文件。你可以用任何文本编辑器打开、修改也可以用 Git 进行版本管理记录你的世界是如何一步步演变的。你永远不会被“供应商锁定”。与现有工具链集成Markdown 是通用格式。你可以用 Typora、Obsidian、VS Code 等任何你喜欢的编辑器来查看和编辑这些文件。你也可以写自己的脚本去分析或处理这些数据。2.3 技术栈选型解析为什么是 Cursor Python FastAPI React项目的技术选型紧密服务于“AI优先”和“本地化”两大目标Cursor 编辑器它不仅仅是一个带 AI 的代码编辑器。其内置的“规则Rules”和“命令Commands”系统是关键。.cursor/rules/下的规则文件本质上是给 AI 的“工作说明书”指导它如何高效地查找数据、理解项目结构。.cursor/commands/下的命令文件则将复杂的自然语言指令映射到具体的 Python 脚本。这构成了 AI 代理的“大脑”和“技能库”。Python 作为后端逻辑核心Python 拥有极其丰富的生态库非常适合完成数据抓取requests,BeautifulSoup用于从 DD Beyond 导入角色、数据处理pandas用于计算遭遇战平衡、自然语言处理用于模糊规则查询等任务。scripts/目录下的所有工具脚本都用 Python 编写保证了强大的功能和灵活性。FastAPI 提供 Web API为了支持功能丰富的 Web UI需要一个高性能的本地 API 服务器。FastAPI 以其现代、快速和自动生成 API 文档的特性成为理想选择。它负责在后台提供战役数据和参考数据的查询接口。React Vite 构建现代 Web UI对于需要复杂交互的页面如遭遇战构建器、关系图谱、战斗追踪器一个响应式的单页应用SPA能提供最佳用户体验。React 的组件化特性非常适合构建这种数据驱动的仪表盘。Vite 则提供了极快的开发服务器和构建速度。这套组合拳确保了底层数据本地、可脚本化中间逻辑强大、灵活用户交互层面极度自然、智能。3. 从零开始完整部署与初始化指南现在让我们一步步将这个强大的工具部署到你的电脑上。整个过程大约需要15-30分钟具体取决于你的网络速度和电脑性能。3.1 前期准备与环境检查在开始之前请确保你的系统满足以下条件安装 Cursor 编辑器前往 Cursor 官网 下载并安装。它是免费软件本项目完全基于其免费功能构建。安装 Python需要 Python 3.8 或更高版本。建议使用 Python 3.10 以获得最佳兼容性。前往 Python 官网 下载安装。务必在安装时勾选“Add Python to PATH”这样才能在终端中直接使用python和pip命令。安装 Git用于克隆项目仓库和初始化子模块。前往 Git 官网 下载安装。安装 Node.js 和 npm用于运行 Web UI 的前端部分。需要 Node.js 16 和对应的 npm。前往 Node.js 官网 下载 LTS长期支持版本。安装完成后打开系统的终端Windows 可用 PowerShell 或 CMDmacOS/Linux 用 Terminal分别运行以下命令验证安装python --version git --version node --version npm --version如果都能正确显示版本号说明环境准备就绪。3.2 项目克隆与一键初始化这是最核心的步骤项目通过一个Makefile将复杂过程简化。打开 Cursor启动 Cursor 编辑器。克隆仓库在 Cursor 的欢迎界面或文件菜单中找到“Clone Repository”按钮。在弹出的对话框中粘贴项目仓库地址https://github.com/frobones/5e-cursor.git并选择一个你喜欢的本地文件夹作为项目根目录例如D:\MyDnD\5e-cursor。打开终端仓库克隆完成后在 Cursor 中打开项目。使用快捷键Ctrl反引号打开内置终端。终端的工作目录应该已经是项目根目录。执行一键初始化在终端中输入以下命令并回车make这个make命令是一个自动化脚本它依次执行了以下关键操作初始化 Git 子模块该项目依赖于5etools的数据仓库作为规则来源。make会将其作为子模块克隆到5etools-src/目录下。这是所有参考数据的源头。运行数据提取脚本调用scripts/extract_all.py等脚本读取5etools-src/中的原始 JSON 数据按照预设默认包含2024核心规则、星界冒险者指南等进行解析、转换生成我们之前提到的books/目录结构包括 Markdown 文件、JSON 索引和快速参考表。注意事项首次运行make时由于需要克隆较大的子模块并处理大量数据可能会花费几分钟时间。请保持网络连接稳定耐心等待终端输出完成。如果遇到网络问题导致子模块克隆失败可以尝试单独运行make submodule重试。3.3 验证与探索试运行演示战役初始化完成后强烈建议先运行演示战役直观感受工具的能力。加载演示战役在终端中运行make demo-campaign这个命令会将项目内置的一个示例战役数据解压到你的campaign/目录下。里面包含预设的玩家角色、NPC、地点和会话记录方便你立即体验。启动 Web UI在终端中运行make web-ui首次运行此命令时它会自动安装前端依赖npm packages然后同时启动后端 FastAPI 服务器和前端的 Vite 开发服务器。打开浏览器根据终端提示通常是http://localhost:5173在浏览器中打开该地址。你将看到一个完整的战役管理仪表盘。自由探索点击左侧导航栏的NPCs查看演示战役中预设的各类角色。进入Locations浏览地图上的各个地点。查看Sessions下的跑团记录。尝试使用Encounter Builder基于演示队伍生成一个遭遇战。在Reference中搜索你熟悉的法术或怪物。停止服务体验完毕后在终端中按CtrlC即可停止 Web UI 服务器。你也可以运行make web-ui-stop来确保所有服务进程被正确关闭。如果想清理演示战役数据运行make demo-campaign-clean。至此你的5e-cursor系统已经成功部署并可以运行了。接下来我们将深入核心功能学习如何让它为你自己的战役服务。4. 核心功能深度解析与实战应用系统搭建好了现在让我们把它变成你专属的地下城中枢。我们将逐一拆解核心功能并附上详细的实战操作指南和背后的原理。4.1 战役初始化与数据架构在你开始导入角色或创建 NPC 之前需要先为你的战役建立一个“家”。这通过初始化一个战役目录来实现。操作指南 你有两种方式初始化战役使用 AI 命令推荐在 Cursor 的 AI 聊天框中直接输入或使用斜杠命令/campaign.init。AI 会询问你战役的名称例如“幽暗地域之谜”。输入后AI 会自动在后台调用init_campaign.py脚本。使用命令行在终端中运行python scripts/campaign/init_campaign.py 你的战役名称底层原理与文件结构 无论用哪种方式脚本都会在campaign/目录下创建一套标准的 Markdown 文件结构。理解这个结构对你手动编辑或排查问题很有帮助campaign/ ├── campaign.md # 战役总览文件包含名称、设定简介、核心线索等。 ├── party/ │ ├── index.md # 队伍花名册列出所有队员及其基础信息链接。 │ └── characters/ # 每个玩家角色一个独立的 .md 文件包含详细数据。 ├── npcs/ │ ├── index.md # NPC 索引通常按角色盟友、敌人、中立者分类。 │ └── [npc-name].md # 每个 NPC 的独立档案。 ├── locations/ │ ├── index.md # 地点索引可按区域或类型分类。 │ └── [location-name].md # 每个地点的独立档案。 ├── sessions/ │ ├── index.md # 会话日志按时间顺序列出所有跑团记录。 │ └── session-001.md # 每次跑团的详细总结。 └── encounters/ ├── index.md # 预设遭遇战库。 └── [encounter-name].md # 单个遭遇战的配置包括怪物列表、地图提示等。实操心得在campaign.md中花些时间写好战役的“电梯演讲”一段简短的概要和核心主题。这能帮助 AI 在后续生成内容如 NPC、地点时更好地贴合你的战役基调。例如如果你在概要中强调“这是一个充满政治阴谋的低魔世界”那么 AI 生成的 tavern酒馆就更可能充满窃窃私语的间谍而不是喧闹的矮人战士。4.2 玩家角色管理从 DD Beyond 无缝导入手动填写 DD 5e 角色表是件苦差事。5e-cursor通过与 DD Beyond 的集成实现了角色数据的自动化导入和同步。操作指南让你的玩家在 DD Beyond 上创建并完善他们的角色。打开角色的“分享”页面复制浏览器地址栏的 URL。在 Cursor AI 聊天框中输入“导入我的角色这是链接[粘贴URL]”。或者使用命令/campaign.import-character [URL]。AI 会调用import_character.py脚本抓取数据并在campaign/party/characters/下生成一个格式优美的 Markdown 角色卡。技术细节与避坑数据抓取原理脚本并非通过官方 APIDD Beyond 的 API 限制较多而是通过解析角色分享页面的 HTML 结构来获取数据。这意味着如果 DD Beyond 的前端页面结构发生重大改版导入功能可能需要更新。目前社区维护的类似工具如 Avrae 的插件也采用类似方法相对稳定。字段映射脚本会尽可能多地将数据映射到本地 Markdown 文件中包括基础属性、技能、豁免、生命值、职业等级、法术列表已知/准备、装备、特性等。链接与引用导入的角色卡中法术、特性等名称会被自动链接到本地的books/reference/目录下的对应文件。这意味着在 Web UI 或通过 AI 查询时你可以直接点击角色卡中的“火球术”来查看完整规则。更新角色玩家升级或更换装备后你可以使用命令/campaign update-character [角色名]或python scripts/campaign/import_character.py update “角色名”来更新本地文件。使用--all参数可以批量更新所有角色。常见问题如果导入失败首先检查 URL 是否正确必须是公开分享链接。其次查看终端是否有 Python 报错可能是缺少requests或beautifulsoup4库运行pip install -r requirements.txt可以安装所有依赖。最后由于是网络抓取偶尔会因 DD Beyond 页面加载慢而超时可稍后重试。4.3 智能遭遇战构建告别 CR 计算器构建一个既具有挑战性又不会团灭队伍的遭遇战是 DM 的核心技能之一。5e-cursor的遭遇战构建器自动化了这个计算过程并提供了丰富的筛选条件。操作指南 最自然的方式就是直接告诉 AI 你的需求。例如“为我的队伍构建一场中等难度的遭遇战。”“我们需要一场在沼泽地里与蜥蜴人相关的遭遇难度要困难。”“构建一场适合5级4人小队的、与亡灵生物的战斗。”AI 会首先读取campaign/party/index.md来确定队伍的等级和人数然后调用encounter_builder.py脚本。脚本会根据队伍等级和人数计算各难度等级简单、中等、困难、致命的经验值XP阈值。从本地books/reference/creatures/索引中筛选符合条件的怪物。运用算法组合怪物使得总 XP 经过多人调整系数调整后落在目标难度区间内。生成一份遭遇战文档包含怪物列表、各自 XP、总 XP、调整后 XP、难度评估以及战术环境建议。高级用法与参数 你也可以直接使用命令行进行更精细的控制# 基于当前队伍自动构建 python scripts/campaign/encounter_builder.py --auto --difficulty hard # 指定队伍参数和怪物类型 python scripts/campaign/encounter_builder.py --level 5 --size 4 --type “undead” --environment “swamp” # 指定具体怪物和数量 python scripts/campaign/encounter_builder.py --monsters “goblin:3, ogre:1”背后的数学 工具严格遵循《地下城主指南》DMG中的遭遇战构建规则确定 XP 阈值根据队伍中每个角色的等级在 DMG 的表格中找到对应等级的“每场遭遇 XP”值将队伍所有成员的值相加得到四个难度等级的基础 XP 阈值。计算怪物 XP累加遭遇中所有怪物的 XP 值根据其挑战等级 CR 确定。应用多人调整系数根据怪物数量确定一个调整系数例如3-6个怪物系数为2。用怪物总 XP 乘以这个系数得到“调整后 XP”。评估难度将“调整后 XP”与队伍的 XP 阈值比较确定最终难度。注意事项DMG 的 XP 阈值和调整系数是一个很好的起点但并非金科玉律。实际战斗难度还受地形、玩家资源状态法术位、生命值、战术和运气影响。生成遭遇战后务必结合你的具体剧情和队伍构成进行微调。工具生成的“战术建议”部分通常能提供不错的灵感。4.4 规则仲裁与知识库查询你的随身 DM 手册忘记规则书在第几页不确定某个专长的具体效果AI 规则查询功能是你的救星。操作指南 在 Cursor AI 聊天框中直接用自然语言提问“‘倒地’状态的具体效果是什么”“给我看看‘火球术’的详细描述。”“有没有 CR 在2左右、居住在山区的怪物”“游侠的‘宿敌’特性怎么运作”AI 会利用books/reference-index.json和books/keyword-index.json这两个核心索引文件进行快速检索。它不仅返回找到的条目还会引用具体的来源例如[XPHB p.123]让你可以追溯到原始规则书。技术实现解析索引构建extract_all.py在提取数据时不仅生成可读的 Markdown还创建了结构化的 JSON 索引。reference-index.json是一个从名称包括别名到文件路径的映射表实现快速精确查找。keyword-index.json则对数据进行了语义化处理例如将所有怪物的“类型”、“居住环境”所有法术的“学派”、“伤害类型”等提取出来建立反向索引支持“查找所有塑能系法术”这类查询。模糊匹配与排序当你的查询不是精确名称时例如“那个让人睡觉的咒语”AI 会使用模糊字符串匹配算法如fuzzywuzzy或rapidfuzz来寻找最接近的条目并按匹配度排序返回结果。上下文关联AI 在回答时会尝试关联相关条目。例如当你查询“火球术”时它可能会顺便提及“抗火性”和“火焰免疫”这两个状态因为它们逻辑相关。实操心得这个功能在跑团现场极其有用。将 Cursor 窗口放在副屏上玩家有任何规则疑问你都可以快速输入并得到带引用的答案极大提升了游戏流畅度和权威性。建议在跑团前用几个关键规则如你战役中常用的法术、状态测试一下查询速度做到心中有数。4.5 会话记录与世界日志让战役历史活起来持续的记录是让战役世界富有生命力的关键。5e-cursor让记录和回顾变得简单。操作指南创建新会话跑团开始前或结束后对 AI 说“创建一场名为‘深入巨魔巢穴’的新会话记录”。或使用命令/campaign.new-session 深入巨魔巢穴。这会在campaign/sessions/下创建一个新的session-xxx.md文件并自动在index.md中登记。记录内容你可以在 Cursor 中直接打开这个 Markdown 文件进行编辑。推荐使用简单的模板如## 日期与地点 - **现实时间**2023-10-27 - **游戏时间**1492 DR 丰收之月 - **起始地点**无冬城“黑荆棘”酒馆 ## 出场人物 * **玩家角色**艾拉战士、贝尔法师、卡德加牧师 * **重要 NPC**酒馆老板布鲁诺线人“灰鼠” ## 发生了什么 ...你的叙述... ## 获得的线索与宝藏 - 从灰鼠处得知巨魔巢穴位于“哭泣溪谷”北侧山洞。 - 获得布鲁诺赠送的5瓶治疗药水。 - 一张画有奇怪符号的羊皮纸。 ## 下次预告 - 前往哭泣溪谷。 - 调查符号的含义。回顾历史你可以随时问 AI“我们在第三场会话里找到了什么”或者“我们上次遇到‘灰鼠’是什么时候”AI 会读取所有会话文件找出相关信息。进阶技巧 在记录会话时尽量使用项目中已有的NPC 名称和地点名称。AI 在后续分析时能更好地建立实体之间的关联。例如如果你在会话中提到了[[布鲁诺]]使用双中括号这是许多 Markdown 笔记软件的内部链接语法未来在生成关系图谱时这个链接就可能被识别出来。4.6 AI 辅助内容生成从灵感到完整设定这是最能体现“AI优先”理念的功能。你只需要提供一个种子想法AI 就能为你扩展出丰富、连贯的战役内容。NPC 生成 对 AI 说“创建一个名叫‘萨尔贡’的、愤世嫉俗的老兵 NPC他在码头区经营一家兵器铺失去了一条胳膊。” AI 会调用campaign_manager.py中的相关逻辑生成一个包含以下部分的完整 NPC 文件基础信息姓名、种族、职业、年龄、性别。外观描述详细的生理特征、穿着打扮、标志性物品如他的铁钩假肢。性格与声音口头禅、习惯动作、信仰、欲望、恐惧。背景故事如何失去手臂为何变得愤世嫉俗与码头区其他势力的关系。秘密一两个不为人知的秘密可能是未来的剧情钩子。游戏数据可选如果相关会附上简化的属性值或战斗数据。关联自动尝试将其与战役中已有的地点如码头区或其他 NPC 建立联系。地点生成 对 AI 说“在无冬城的墓园区创建一个被遗忘的、闹鬼的家族陵墓。” AI 会生成的地点档案可能包括感官细节阴冷潮湿的空气、苔藓的气味、远处滴水的声音、墙壁上剥落的家族纹章。关键区域前厅、主墓室、隐藏的祭坛间、坍塌的隧道。潜在遭遇幽灵、骷髅、食尸鬼或者一个被困的幽魂 NPC。可发现的物品锈蚀的家徽戒指、记载家族丑闻的日记、被封印的魔法物品。与世界的连接这个家族与无冬城历史上某件大事的关联。核心技巧AI 生成的内容是“初稿”。它基于你提供的种子和已有的战役数据结合从规则书中学习到的常见奇幻设定模式进行创作。你永远是最终的决定者。生成后务必仔细阅读调整细节使其完全符合你的战役风格和剧情需要。把它看作一个强大的灵感加速器和内容填充器而不是替代你创作的作者。5. Web UI 深度使用指南可视化你的世界虽然与 AI 对话是核心交互方式但一个直观的可视化界面对于浏览、搜索和宏观把握战役至关重要。5e-cursor的 Web UI 正是为此而生。5.1 仪表盘与全局概览启动 Web UI (make web-ui) 并打开浏览器后首先看到的是仪表盘。这里聚合了战役的关键信息战役概要显示campaign.md中的概述内容。近期会话列出最近几场跑团的标题和日期点击可快速跳转。队伍状态显示队员姓名、职业、等级和当前生命值如果从 DD Beyond 导入了最新数据。快速数据统计NPC 总数、地点总数、已记录会话数等。快速操作创建新 NPC、新地点、新会话或新遭遇战的按钮。使用建议将仪表盘页面设为浏览器书签作为你每次准备跑团时的起点页面。5.2 实体浏览与关系网络NPC 浏览器这里以卡片或列表形式展示所有 NPC。你可以按角色盟友、敌人、中立、种族、所在地点进行筛选。点击任意 NPC进入其详情页可以看到所有关联信息。更重要的是许多 NPC 卡片上会显示“关系”标签点击可以展开一个迷你关系图。地点浏览器类似地所有地点按区域或类型组织。地点详情页会列出已知的关联 NPC 和可能发生的遭遇。关系图谱这是 Web UI 的亮点功能之一。在导航栏找到“Relationship Graph”或类似链接点击后会生成一个基于 Mermaid 图表的交互式关系网络图。图中节点代表 NPC 和地点连线代表他们之间的关系如“属于”、“敌对”、“知晓”。这个图是自动通过分析 NPC 和地点文件中的内部链接[[...]]和特定关键词生成的。它能帮助你一眼看清势力分布和剧情脉络。5.3 遭遇战构建器与战斗追踪器Web UI 中的遭遇战构建器提供了比命令行更直观的交互方式。选择队伍通常自动加载当前战役队伍。设置参数通过滑块或输入框设定难度、环境偏好、怪物类型偏好。实时调整构建器会实时显示候选怪物列表。你可以手动添加/移除怪物界面会实时重新计算总 XP 和难度评级。保存与加载构建好的遭遇可以命名保存到campaign/encounters/目录方便下次直接调用。战斗追踪器当你开始一场遭遇战时可以点击“开始战斗”进入追踪器界面。你可以为每个玩家角色和怪物投掷先攻并自动排序。实时调整每个单位的生命值。标记状态如“倒地”、“中毒”。快速点击怪物名称查看其完整数据从本地参考库弹出。记录战斗轮次和重要动作。注意事项战斗追踪器是一个轻量化的辅助工具并非完整的虚拟桌面VTT。它最适合用于线下跑团或语音跑团时由 DM 在副屏上跟踪战斗状态。对于需要复杂地图和模型托管的在线团可能仍需依赖 Roll20、Foundry VTT 等专业工具。5.4 全局搜索与参考图书馆按下CmdK(Mac) 或CtrlK(Windows/Linux)会呼出全局搜索框。你可以在这里搜索任何内容NPC 的名字、地点的描述、会话记录中的关键词、法术的名称、怪物的特性。搜索是跨所有战役文件和参考数据的结果会按类别高亮显示。参考图书馆是一个独立的模块让你可以像翻阅电子书一样浏览所有从 5etools 提取的规则内容。你可以按法术等级、怪物 CR、物品稀有度等进行筛选和排序。这对于在准备阶段系统性地查阅规则非常方便。6. 高级配置与自定义技巧当你熟悉了基本功能后可以通过一些配置让工具更贴合你的需求。6.1 自定义规则数据源默认提取的是 2024 核心规则《星界冒险者指南》等。如果你主要跑《被遗忘的国度》或《艾伯伦》的战役可能需要其他扩展书的内容。查看可用源打开sources.yaml.example文件里面列出了所有预设preset和可用的源代码如PHB代表2014版玩家手册SCAG代表《剑湾冒险者指南》。创建配置文件复制sources.yaml.example并重命名为sources.yaml。编辑配置# 使用预设推荐 preset: 2014-core # 改为使用2014版核心三宝书 # 或者手动指定源列表 # sources: # - PHB # - DMG # - MM # - XGE # 添加《珊娜萨的万事指南》 # - TCE # 添加《塔莎的万事坩埚》重新提取数据在终端运行make clean清除旧的books/目录然后再次运行make extract根据新配置提取数据。重要提醒更改数据源后所有基于旧数据的 AI 查询和工具如遭遇战构建都将基于新数据运行。确保你的战役设定与所选规则版本一致。6.2 扩展 AI 命令与规则如果你有特定的、重复性的工作流可以创建自己的 Cursor 命令或增强现有规则。自定义命令在.cursor/commands/目录下复制一个现有的.md命令文件如campaign.create-npc.md修改其文件名和内部指令。命令文件本质上是给 AI 的“快捷指令模板”。例如你可以创建一个/campaign.quick-trap命令让 AI 快速生成一个符合队伍等级的陷阱。自定义规则在.cursor/rules/目录下的.mdc文件定义了 AI 在处理特定类型任务时应遵循的步骤和原则。如果你发现 AI 在某些方面如生成 NPC 的背景总是不符合你的口味你可以编辑相应的规则文件加入更具体的指导方针例如“生成的 NPC 背景应更注重个人悲剧而非宏大叙事”。6.3 与外部工具集成由于所有数据都是 Markdown你可以轻松与其他工具集成。Obsidian / Logseq将campaign/目录设置为这些双链笔记软件的一个库。你可以利用它们强大的图谱、反向链接和查询功能来发现战役中你自己都未曾注意到的联系。版本控制 (Git)用 Git 来管理你的战役目录。每次跑团后提交一次更改。这不仅能备份你的世界还能清晰看到剧情是如何一步步发展的。你甚至可以为不同的剧情分支创建不同的 Git 分支。导出与分享Markdown 可以轻松转换为 PDF、HTML 或 Word 文档。你可以将整理好的 NPC 卡或地点描述导出分享给你的玩家。7. 故障排除与常见问题实录即使设计再完善在实际使用中也可能遇到问题。这里记录了一些常见情况及其解决方法。问题一运行make命令时卡在克隆5etools-src子模块或下载很慢。原因5etools仓库较大且托管在 GitHub 上国内访问可能不稳定。解决方案检查网络连接尝试使用稳定的网络环境。可以尝试先手动配置 Git 的代理如果条件允许且合规。更通用的方法是如果多次失败可以尝试单独运行make submodule如果还是失败可以手动初始化git submodule init git submodule update。极端情况下可以到5etools的 GitHub 仓库页面下载 ZIP 包解压到项目根目录并重命名为5etools-src文件夹。问题二AI 在回答规则问题时找不到某些特定内容比如某个小众扩展里的法术。原因默认的数据提取配置可能没有包含你需要的扩展书。解决方案按照6.1节的步骤编辑sources.yaml文件添加对应的源代码如FTD代表《费资本的巨龙宝库》然后重新运行make clean make extract。问题三从 DD Beyond 导入角色失败提示“无法解析页面”或超时。原因DD Beyond 页面结构可能发生变动或者角色链接不是有效的公开分享链接或者网络问题。解决方案确认链接是直接从浏览器地址栏复制的角色“分享”链接并且该链接已设置为“公开”。在浏览器中打开该链接确认能正常看到角色表。暂时关闭可能干扰网络连接的插件。如果问题持续可能是脚本需要更新。关注项目 GitHub 仓库的 Issues 页面看是否有其他人报告类似问题。问题四Web UI 启动后前端页面能打开但数据显示“加载失败”或为空。原因后端 API 服务器可能未成功启动或者前端无法连接到后端通常是端口问题。解决方案检查终端窗口确保两个服务后端 FastAPI 和前端 Vite都在运行且没有报错。查看浏览器开发者工具F12的“网络Network”选项卡看对http://localhost:8000/api/...的请求是否失败。后端默认运行在 8000 端口。确认make web-ui命令启动了两个进程。你可以手动在两个独立的终端标签页中分别运行# 终端1后端 cd scripts python -m web.main # 终端2前端 cd frontend npm run dev这样能更清晰地看到各自的日志。问题五AI 生成的 NPC 或地点内容过于模板化缺乏新意。原因AI 的生成基于现有数据和通用模式。如果提示词过于简单输出就会比较通用。解决方案提供更丰富、更具体的种子描述。不要只说“创建一个精灵法师”尝试说“创建一个因为一次失败的实验而失去记忆、现在在酒馆打零工还债、性格有些偏执但心底善良的老年精灵法师他总是不自觉地摆弄一个坏掉的怀表”。给 AI 更多的“钩子”它就能编织出更独特的故事。问题六战役文件越来越多感觉有点乱。原因这是幸福的烦恼说明你的世界在成长。解决方案利用索引文件定期查看和整理npcs/index.md和locations/index.md确保分类清晰。建立子目录对于大型战役可以在npcs/或locations/下创建子文件夹如npcs/waterdeep/,npcs/baldurs-gate/。注意这可能需要你稍微修改一下 AI 规则或脚本中的文件查找逻辑或者你只需手动管理AI 的全局搜索依然能工作。定期“归档”将已经完结的故事线相关的 NPC 和地点移动到一个archive/文件夹保持当前活跃区域的整洁。这套工具的核心价值在于将你从重复性、查找性的劳动中解放出来让你能更专注于 DD 游戏最核心的部分讲故事、扮演角色和创造难忘的冒险。它就像一位不知疲倦的、知识渊博的副 DM负责处理所有的文书工作和数据查询而你则可以全情投入于与玩家共同编织的传奇之中。开始你的 AI 辅助城主之旅吧你会发现准备跑团从未如此轻松和充满乐趣。