让 AI 坐上 KP 的位置，把故事跑下去。
面向 COC7 的开源、自托管 AI 跑团平台：AI 守秘人推进剧情，规则书知识库回答规则问题，剧本编辑器把 Word / PDF 模组变成可玩模组，角色卡与内置编辑器管住每一点技能——剧本、账号与聊天记录全部落在你自己的机器上。
引擎在后台，剧本、角色卡与知识库在你自己手里。
它不是一个只会续写剧情的聊天框。叙事与检定交给引擎，内容交给内置的剧本编辑器、世界书、角色卡编辑器与规则书知识库——两边分开，跑团才推得下去。
AI KP，不抢走规则
自然语言叙事与结构化状态分开处理。模型负责讲故事，引擎让检定结果、技能值与角色卡真正落地。
一张实时多人桌
房间码邀请、成员列表、角色变更实时同步、正在输入提示。页面和实时聊天共用同一个端口，网络环境受限时也能保持同步。
世界书会记得
命中触发词直接激活，未命中回退 BM25 + 向量检索；支持常驻条目、分层、概率、粘滞与冷却轮数，AI 只读到它此刻该读的部分。
剧本：文档丢进来就能玩
Word / PDF / Markdown 模组按标题分节语义切块并建索引，导入完成即可开团；也可以先让 AI 转成结构化剧本，你审阅修改后再发布。「直接导入」与「审核导入」两条路径都在。
内置剧本编辑器
场景卡、结局、时间线、NPC、怪物与道具在同一个界面里编排，可配封面与简介。只有改动剧本内容才会生成新版本；改标题、作者、封面这类基础信息既不升版本、也不重算索引。
COC7 角色卡与检定
属性、技能、武器、专精与本地化技能名一应俱全；检定名会对照 character_skills.json（含专精与中文变体）校验，未知名直接拒绝并提示。聊天里的 1D100 结果直接写回卡上，失败 / 成功 / 困难 / 极难都有反馈。
内置角色卡编辑器
不用手写 JSON：在页面里直接建卡、改卡、分配技能点。改动技能上限会按最终值裁剪所有点数；带专精的技能在右侧选好专精再切换基础值；技能基础值支持「房规 > 管理员默认 > 规则书默认」三级覆盖。
规则书知识库
管理员上传 COC7 规则文本（.txt / .md / .doc / .docx）建成立即生效的检索库。玩家问「这个法术怎么算」时，AI 从你的规则书里找依据再回答，而不是凭记忆编。
单进程运行，不需要 Docker 也能跑。预置 DeepSeek / OpenAI / 阿里云百炼 / SiliconFlow / OpenRouter / LM Studio 六家平台，也支持任意 OpenAI 兼容接口。
六项能力，六张真实界面。
房间聊天、剧本编辑器、世界书、COC7 角色卡、角色卡编辑器与规则书知识库，全部照程序的实际界面绘制。
一张聊天，跑完一局
AI 守秘人推进叙事，玩家掷骰、检定，结果直接写回角色卡——全在同一张聊天里，右侧还能看到谁在线、绑定了哪张卡。
- @KP 呼叫 AI
- 1D100 检定
- 结果写回角色卡
创建剧本
✕场景1 · 仓库调查
公开 · 发送给 AI
Word / PDF 模组，直接变成可玩剧本
场景卡、结局、时间线、NPC、怪物与道具在同一个编辑器里编排，封面与简介跟着剧本走；写完存草稿或直接发布。
- 九类模块
- 文档直接导入
- 草稿 / 发布
知识块（世界书）
✕
决定 AI 此刻能读到什么
每条知识块都能调触发词、副键、常驻、概率与粘滞 / 冷却轮数：命中即注入，冷却即剔除，剧本再大也不会串味。
- 触发词激活
- 粘滞 / 冷却
- 概率与分组竞争
属性、技能、武器与专精，一页看全
9 项属性、三档成功率（普通 / 困难 / 噩梦）、技能上限与武器清单一并呈现，技能名按角色卡自己的本地化名称显示。
- 9 项属性
- 困难 / 噩梦值
- 武器与装备
创建角色卡
✕
建卡改卡，都在页面里完成
职业点数与兴趣点数实时汇总剩余，分类筛选快速定位技能；带专精的技能选好专精，基础值随之切换。
- 点数实时剩余
- 分类筛选
- 专精选择
规则问题，用你的规则书回答
上传 COC7 规则文本后立即可检索，AI 回答规则问题时以它为依据；剧本知识库删除只清向量与索引，不动剧本本身。
- 上传并索引
- BM25 + 向量
- 独立规则集索引
叙事可以自由，状态必须可信。
玩家看到的是干净的叙事，背后每一次检定、技能变动与存档都由引擎处理。
- 检定先掷骰，结果再被叙述。KP 不会先写好结局再补一个骰点。
- 技能上限改动后按最终值裁剪所有技能点数，不会留下越界的分配。
- 剧情不会丢。聊天记录持久保存，可打回档节点，也可按周期自动存档。
- 中途换剧本也不乱。换成同一剧本的最新版本可继承剧情进度，换别的剧本则重置。
「世界书」装的是这个剧本的线索、NPC 与触发器；「规则书知识库」装的是 COC7 规则本身。两者分开检索——剧情线索不会被规则条文挤掉，规则问题也不用你现场翻书。
规则文本支持 .txt / .md / .doc / .docx，上传后立即生效；换一份规则书不用重跑剧本。
四步，开始第一场 AI 跑团。
部署
克隆仓库或解压 release 包，装好依赖，python server.py 即起。
配置
打开首页会弹出 5 步向导：选平台、填 Key、测试连接、创建 Owner，全程不用手改配置文件。
准备剧本与角色卡
手写模组，或把文档导进来；再在剧本编辑器里调场景卡、在世界书里逐条设触发词，顺手建几张 COC7 角色卡，上传规则书建起知识库。
开团
建房、发房间码、朋友加入。AI 开场并推进剧情，玩家掷骰、检定、行动。
跑起来只需要一个终端。
需要 Python 3.11+；Node.js 18+ 只在你自己构建前端时才会用到。
git clone https://github.com/Nobook1121/AIBasedTRPG cd "AIbased TRPG" python -m venv .venv .\.venv\Scripts\Activate.ps1 pip install -r requirements.txt npm install npm run build:frontend python server.py
启动日志（示例）
如果用的是 release 压缩包，里面已经带构建好的前端：解压后 pip install -r requirements.txt 再 python server.py 就行。
这套东西是给谁的。
凑不齐 KP 的玩家
想随时开一局，但没人愿意、或者没空来当守秘人。
手里压着剧本的 KP
想把那些 Word / PDF 模组变成可对话、可检索、能反复开的线上团。
只想给朋友开服的人
在自家电脑或一台小服务器上搭个不对外开放的跑团服务，账号自己管。
不用云服务器，也能让朋友连上。
程序可以配合内网穿透等方式使用：在一台普通电脑上跑起来，把地址分享出去，朋友就能加入。零成本、无需云服务器，也不用先准备域名和证书。
- 同一台电脑：运行
python server.py，浏览器打开127.0.0.1:8086，先自己开一局。 - 同一个 Wi-Fi：朋友打开启动日志里的局域网地址就能加入，记得放行防火墙端口。
- 异地联机：用内网穿透把本机地址映射出去，把得到的外网地址发给朋友即可，不必购买云服务器。
- 长期使用前，先设置自己的密钥：
$env:AI_TRPG_SECRET_KEY，不要沿用默认开发密钥。
- 01跑起来在本机运行
python server.py，先自己开一局试试。 - 02开穿透用任意内网穿透工具把本机地址映射出去，无需云服务器。
- 03发地址把得到的外网地址发给朋友，他们打开就能一起玩。
上手前可能想知道。
打开页面是空白的？
前端没有构建。执行 npm install && npm run build:frontend，或者改用已经带构建产物的 release 压缩包。
朋友连不上？
依次检查三件事：主机防火墙有没有放行端口、IP 对不对（异地组网要用虚拟网卡 IP）、启动日志里有没有对方能访问到的 listening 地址。
AI 不回复，或者只回复一半？
多数是模型接口超时。可以在设置页调大「AI 请求超时」和「最大工具调用轮数」，再确认 API Key 与模型 ID 没写错。
扫描版 PDF 导进来没有内容？
默认只处理文本型 PDF。扫描件需要额外装 OCR 依赖（PaddleOCR），见开发文档里的进阶可选项。
改了剧本标题或封面，版本号为什么没变？
这是刻意的。标题、作者、推荐人数、简介、封面都属于基础信息，改它们不会升版本、也不会重算索引；只有改动剧本内容才会生成新版本。
- ▸ docs / api.md
- ▸ docs / development.md
- ▸ docs / scenario-format.md
- ▸ docs / scenario-import.md
- ▸ docs / console-commands.md
- ▸ docs / vector-store.md
- ▸ README.md
- ▸ LICENSE (Apache-2.0)