autokeeper 0.0.4

AutoKeeper 把《克苏鲁的呼唤》第 7 版的跑团桌面搬进了终端。你扮演调查员，用中文说出想做的事；AI 担任守秘人，铺陈场景、扮演镇上的各色人物，并在需要检定时请你掷骰。

• 会自己运转的小镇：守秘人看得到模组的全部底牌，每局有一份世界记录，记着谁在哪、知道什么、答应过谁；NPC 照自己的打算行事，你不去找他们，他们也在走自己的日程。
• 七版规则与物理十面骰：检定时亲手投掷 3D 物理十面骰；失败就是失败，花幸运、孤注一掷、灵感检定、理智与不定性疯狂、重伤和幕间成长都按规则结算。手上有规则书和守秘人卡组时可以读进游戏，裁定时查原文，疯狂与惨事照卡抽取。
• 战斗与追逐：按第 7 版一轮一轮结算。行动从列出的选项里选，也可以自己写打法；被攻击时的应对按 Tab 切换，危险升高时才停下来询问。对手占满舞台，受伤时全屏溅血；追逐沿地图上的路线跑，追兵在场景里越逼越近。伤势、弹药和掉落的武器都记进世界记录。
• 字符画演出：老照片与插图转成真彩字符画，随时间和叙事飘起雨雪浓雾、摇曳灯影；模组没有图的地点、人物、物件和怪物，先找写实照片，找不到再由 AI 画；地图是一张彩绘的羊皮纸。
• 按纸张排版的手稿：信件、日记、剪报、电报、典籍各有纸色、墨色与版式，手写的信和日记用斜体，墨迹逐字渐显。
• AI 辅助车卡与多格式导卡：一句人设或一个人名即可按七版规则建卡；也能导入骰娘 .st、表格、PDF、纸质卡照片与酒馆卡。
• 模组编译与沙箱规则插件：内置三本模组，支持拖入 PDF、Word、ZIP 自动拆解编译；专属机制与解谜小游戏用规则插件实现，开局后也能一句话加家规。
• 独行、带 AI 队友，或叫朋友上桌：一个人随时开局；想凑一桌时开好房间，朋友用浏览器打开链接就能入座，不用装环境或配密钥。
• 不绑定模型：DeepSeek、Claude、Codex、Ollama 与任意 OpenAI 兼容接口都能用，守秘人、NPC、裁定、读图等分工可以各配一个模型，并设预算上限。

_{《追书人》实机画面：在阿诺兹堡图书馆查阅旧报、投掷物理十面骰完成检定，右侧同步记录状态与调查经过。}

从早班火车进站开始

挑好模组和调查员，守秘人会顺着你的角色背景拉开序幕。以入门模组《追书人》为例，故事从早班火车驶入阿诺兹堡讲起：委托人托马斯的家在小镇尽头的公墓旁，走过去还有一段路。你可以先向站务员打听方向、找家餐馆吃早饭，或是拐进镇图书馆查查旧报纸。想和谁搭话、翻看什么东西，直接打字就行。如果顺着好奇心走到了原作没写的地方，守秘人会即兴补出人物、地点和支线，并写进本局存档；偏爱原汁原味的话，也能在设置里切回严格模式，或按喜好调整篇幅、节奏与恐怖浓度。

行动撞上悬念时，桌面会弹出检定提示，请你亲手掷出物理模拟的十面骰。失败了要不要花幸运、要不要冒着大祸临头的风险「孤注一掷」，都由你当场拍板；孤注一掷要说明调查员打算怎么做，守秘人据此复核，时间照常流逝。调查陷入僵局时，可以按 Ctrl+L 做一次灵感检定，想起遗漏的线索里最要紧的一条。一路上收集的剪报与信件可以随时展开阅读原文、查看原图；去过的地方、打过照面的人和查出的线索，会分别归档进地图、线索本与人物卡的「本局经历」里。每回合自动存档，随时合上终端，下次都能接着往下查。

_{手稿按纸张排版：《追书人》里道格拉斯的日记，红色页边、手写斜体，墨迹逐字渐显。}

_{彩绘调查地图：只画走过和听说过的地方，地面、土路和雾都由程序生成；右侧是地点的所见、遇到的人、找到的线索和到各处的路程，按 G 即可动身。}

照片画字符，没有照片就找、就画

模组自带的老照片与插图会转成彩色字符画，窗外的天色和天气跟着叙事流转：细雨、大雪、浓雾，夜里的台灯会摇曳（也可按 Ctrl+A 切换纯 ASCII 等画法）。NPC 开口时，人物立绘站到画面一侧，色调随台词里的情绪变化。

模组没有配图的地点、人物、重要物件和怪物，以及守秘人即兴加出来的，先上网找写实照片，由读图模型挑选、裁剪；找不到合适的，本机有 Codex 时由 AI 按写实照片的样子画一张。两者都统一轻度调色，放在一起不突兀。图存在本机，每个模组只找、只画一次，以后每局都用；autokeeper art prepare 模组 可以在开局前全部准备好。路人不配头像；离线又没有 Codex 时不配图，只用文字。

到了开场、撞见异状或步入结局的关头，画面会展开成整屏「大场景」插图。本机装有 Codex 时，开启「AI 画图」还能让即兴人物与地点改由图像模型配图；若是剧情里老宅失火、NPC 负伤，场景和头像也会按原图重新绘制。伏笔在之后几次来访中逐步变化，场景图也随之变样，这些图在故事走到那里时才画。

_{关键时刻的整屏大场景：《追书人》开场，早班火车停靠阿诺兹堡车站。}

AI 辅助车卡，或者把你的老角色带进来

开局前可以直接选用模组预设调查员，也能在「角色卡」里亲手建一张属于自己的卡：

• AI 辅助车卡：输入一句角色设想（如“落魄的禁酒令私家侦探”），或直接填一位历史、公众人物的名字。写名字时，程序会检索维基百科与历史图库，由你挑选满意的照片转成字符画肖像；接着结合人物经历与模组年代向你提出三个背景问题。答完后，程序按七版规则自动核算属性分配、职业点公式与兴趣点，生成合规的人物卡，不满意的地方还能用一句话继续微调。
• 多格式导入老卡：手头已有的调查员不用重填。骰娘的 .st 属性串由代码直接解析；Excel 表格、PDF、Word 乃至拍下来的纸质人物卡照片，会照原样识别录入并自动修正越界数值；酒馆角色卡（PNG / JSON）也能直接读取人设与卡面图片，走完背景问答后转成 CoC 调查员。

_{角色库：集中管理自己建的角色、存档里的历任调查员与模组预设，随时带进新的一局。}

自带三本模组，也能导入剧本与规则插件

游戏自带三本风格各异的模组：适合单人上手的古典调查《追书人》、暴风雪孤立小镇中的《冬雪之下》，以及适合多人热闹开局的《有些人油盐不进》。装好后不用额外找剧本，直接就能开第一局。

_{模组选择界面：自带《追书人》《冬雪之下》《有些人油盐不进》，第一次玩推荐从《追书人》开始。}

想跑自己攒下的模组，把 PDF、Word、Markdown、纯文本或 ZIP 压缩包拖进标题页的「导入模组」，或者用一行命令导入：

autokeeper import 模组.pdf

导入时，AI 会通读原文，把零散的人物、地点、线索和事件整理成结构化数据，保留原书的插图与手稿，并按年代去公共图库搜寻合适的历史老照片转成字符画，校验通过后直接出现在游戏列表中。手上没有现成剧本时，也能给一句设定，让它联网考据、编写剧情并配好插图，生成一部原创模组：

autokeeper generate "1931 年上海，一张没有标签的唱片" --id changpian

规则插件与一句话家规

CoC 模组常有标准规则之外的特殊机制——比如《冬雪之下》的传染病蔓延、《追书人》书房里的旧书架机关，或是防线耐久、倒计时与资源消耗。AutoKeeper 用一套隔离沙箱中的规则插件来承载这些设计：

• 模组专属机制与小游戏：导入或编写模组时可附带 Python 规则插件。插件在屏蔽了文件、网络与子进程的沙箱中运行，能在右侧边栏挂载实时状态面板、播放字符演出、注册自定义 /命令，或是向玩家弹出选择、填空、排序、棋盘四类交互式解谜小游戏。
• 游戏中一句话加家规：跑团途中临时起意，在开发者模式（F12）下按 Ctrl+K 打开插件窗口，用自然语言输入一条家规（例如“每次在暴风雪里赶路都要检定体质”）。AI 会在后台生成插件并在沙箱中跑通自动化测试，测试通过后立即装进本局生效。

_{规则插件与家规面板（开发者模式下 Ctrl+K）：查看本局生效的特殊规则、触发状态与可用行动，或用一句话现场添加家规。}

更多细节见导入与生成说明、模组格式文档与规则插件文档。

打起来，或者拼命跑

撞上怪物或者谈崩了，守秘人判定打起来以后，游戏进入按第 7 版规则一轮一轮结算的战斗。面对的对手占满舞台，背后透着血光，血顺着画面往下流，心跳一样明暗起伏；它扑过来时贴近画面，被它抓中时爪痕划过画面、整个屏幕溅红摇晃；被你打中时它白光一闪，伤害数字用血写在它身上。第一次看见怪物时，它先占满整个屏幕，再过理智检定。旁边是出手先后、对手的伤势（只写字样，不给数字）和你们的生命值。

每一轮从输入框上方列出的行动里选：攻击（写明武器和伤害）、射击、推倒、缴械、制住、急救、装填、防守、逃跑；也可以自己写，守秘人把它读成规则里的一项行动。被攻击时怎么应对（闪避、反击、扑向掩体）是选单下方的一行，按 Tab 切换，不占用行动；第一次被攻击、这样应对不合适或者危险升高时，才会停下来问你，窗口里写明每种应对掷什么、代价是什么。闪避与反击、以多打少、射击的修正、卡壳、贯穿、重伤、濒死和急救都按规则来。对手只按它察觉得到的行动：躲好了、跑出了视线，它就找不到你；它身上的护甲、自愈这类特性，你看得见时会写进叙述。按 Ctrl+N 收起画面，留出读故事的地方。每轮的选择可以限时，默认关闭，在设置里打开。

_{《追书人》书房里的战斗：对手只写伤势，每次交锋一张战斗卡；选单下方是被攻击时的应对，按 Tab 切换。}

逃跑或追赶时进入追逐，路线就是地图上的路：先过体质定速度，每轮按速度差得到行动点，翻墙、钻灌木要过检定，锁着的门可以撬开或撞开。场景变冷变暗、向后掠过，追兵离得越近画得越大；旁边是到出口的一条路，每一处的名字、要跳要爬要撞开的东西和谁在哪里。随时可以躲起来，逃出视线后追兵可能跟丢；有人回身迎战、被制住或倒在追兵面前，就转为战斗。对手逃跑时，你也可以追上去。打完以后，伤势、弹药和掉落的武器都还记着。

_{《追书人》墓园里的追逐：右侧是到出口的一条路和路上的障碍，选项写明每种过法用什么检定。}

一个人随时开，或者叫朋友凑一桌

一个人玩时，可以独自调查，也可以挑几位性格各异的 AI 调查员当队友；单纯想看故事的话，还有「观战」模式能让 AI 小队自己跑完整局。

想约朋友一起跑，由房主在标题页选择「多人游戏 → 开房间」，排好真人与 AI 的座位，把生成的网址发给朋友就行。朋友用浏览器打开链接就能入座，不需要安装 Python、也不用配置任何模型密钥。座位只定是玩家还是 AI、谁来坐；调查员在座位下方另选，可以用模组预设、导入自己的老角色，或者当场调用房主的模型车一张新卡。

_{《冬雪之下》开房间：左上排座位（玩家或 AI），左下为座位选调查员，右侧预览人物卡。}

开局后，同一轮里大家各自提交行动，先后不限，视为同时发生：守秘人逐个裁定检定，再把这一轮合成一段讲出来；守秘人讲述时也能提前打字排进下一轮。战斗中每个人自己掷骰、自己选被攻击时的应对，等你回答的窗口按秒倒数；没发现的线索和守秘人的资料不会发到朋友的电脑上。中途掉线重连即可坐回原位，局域网与虚拟局域网（如 Radmin、ZeroTier）下的连接排查见联机说明。

开始玩

先装 uv（Python 工具管理器，已经有了就跳过）：

# Linux、macOS、WSL
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

装好后开一个新终端，一条命令装好 AutoKeeper（用 pipx 的话是 pipx install autokeeper）：

uv tool install autokeeper            # 用 Claude 的话：uv tool install "autokeeper[claude]"

然后在任意目录输入 autokeeper 开始。第一次运行会装好掷骰组件，再问你用哪家模型、填 API Key。

也可以用一键脚本，它会先装 uv、chafa，再做上面的事：

# Linux、macOS、WSL
curl -fsSL https://raw.githubusercontent.com/satoshinji2992/autokeeper/main/install.sh | bash

# Windows PowerShell
irm https://raw.githubusercontent.com/satoshinji2992/autokeeper/main/install.ps1 | iex

autokeeper serve      # 在浏览器里玩
autokeeper login      # 换模型、补 API Key
uv tool upgrade autokeeper   # 更新

掷骰要用 Node.js 18+，推荐再装 chafa 显示照片字符画（各系统的装法、存档放在哪、以前从源码玩的存档怎么带过来，见安装）。

除了 Claude 和 DeepSeek，游戏还支持 Codex、Ollama 本地离线模型以及任意 OpenAI 兼容接口，可以在标题页「设置」或游戏中按 F9 随时切换。「各分工模型」页可以给守秘人、NPC、裁定、读图等分工各填一个模型，留空就用方案默认；「测试连接」会把用到的每个模型都测一遍。详细配法与花费说明见游玩指南。

_{模型设置（F9）的「各分工模型」页：每个分工一行，写明它做什么；只有「读图」需要能看图的模型。}

文档与开发

• 游玩指南：安装、模型配置、快捷键、战斗与追逐、规则书与卡组、联机排查。
• 模组格式 / 规则插件：手工编写剧本、配置大场景与开发自定义机制。
• 守秘人体验设计：开场引入、导演即兴、线索节奏与配图设计。
• 模型运行机制 / 评测记录 / 世界引擎设计：多智能体架构、修辞防注入评测与后续计划。
• 战斗与追逐：规则怎么分层、一轮怎么结算、追逐的地图、联机只发公开的局面。
• 规则对照表：战斗、伤害、追逐、检定与主持，逐条对照《守秘人规则书》的页码、实现和测试。
• 开发者模式：游戏中按 F12，查看本轮每次调用的分工、模型、用时与缓存命中，所有人物的实际位置和接下来的日程。

遇到不合理的裁定或报错，欢迎提交 Issue 并附上模组名、当轮行动与日志。源码位于 src/autokeeper/，测试位于 tests/；提交 PR 前请运行 uv run ruff check src tests 与 uv run pytest -q。开发约定详见 AGENTS.md。README 的截图由 dev/screenshots.py 生成。

_{开发者模式（F12）：顶栏变色，叙述下方显示本轮的模型调用、所有人物的实际位置和接下来的日程。}

致谢与许可

终端界面基于 Textual 构建，照片转字符画使用 chafa，掷骰与骰娘指令使用 BCDice，智能体编排与原文检索分别基于 LangGraph、LangChain 与 LightRAG。

本项目代码以 MIT 协议发布，src/autokeeper/module/example/ 为 CC0 格式样例。自带模组《追书人》（改编自 Chaosium 出版、Bret Kramer 著 Paper Chase）、《冬雪之下》与《有些人油盐不进》均为同人改编，原作版权归各自原作者与出版方所有，仓库不含原模组文本与原版插图；模组选用的历史照片均来自 Wikimedia Commons，署名与授权见各模组的 art/credits.yaml（追书人、冬雪之下、有些人油盐不进）。标题画面背景取自 Dominique Signoret 的画作 Cthulhu and R'lyeh（CC BY-SA 3.0，Wikimedia Commons）。Call of Cthulhu 是 Chaosium Inc. 的注册商标，本项目与 Chaosium 无关。