autokeeper 0.0.6

AutoKeeper 是基于《克苏鲁的呼唤》第 7 版规则的中文跑团游戏，支持终端与浏览器。玩家扮演调查员，以自然语言描述行动、与人物交谈；AI 守秘人（KP）负责场景叙述、人物演出与剧情推进，并在需要时发起检定。

• 统一主持：KP 掌握模组设定，结合本局记录理解行动、安排 NPC 主动参与；裁定员、NPC 演出与导演按职责协作。
• 持久世界：保存人物位置、同行关系、重要物品、知情范围、承诺、日程与设定改写，区分人物的说法和实际发生的事实。
• 模组编译与即兴：内置三本模组，支持导入 PDF、Word、Markdown 与 ZIP，整理动机、线索条件、日程、规则和遭遇，保留原作图片与手稿，并支持临场扩展。
• 七版规则：3D 物理十面骰，以及幸运、孤注一掷、灵感、理智、疯狂、重伤与成长结算；可导入规则书与守秘人卡组。
• 战斗与追逐：支持自然语言和选单操作，按回合结算；战斗与追逐可相互转换，持续记录伤势、弹药、武器与障碍变化。
• 真彩字符画：照片、插图与 AI 配图转为字符画，结合天气、光照和战斗演出；信件、日记、剪报与电报采用独立版式。
• 角色与联机：AI 辅助建卡、多格式角色导入、角色库与 AI 队友；好友可通过浏览器加入，分组调查并行主持，断线时可启用 AI 临时代管。
• 规则插件：承载特殊机制、解谜交互与临时家规，支持 AI 生成代码，经沙箱测试后加载。
• 模型与记忆：支持 DeepSeek、Claude、Codex、Ollama 及 OpenAI 兼容接口，可按分工配置模型，提供会话压缩、按需检索与可配置的预算限制。
• 开发者模式：终端游玩与网页诊断分离，完整记录模型调用、后台任务和世界状态，支持按回合进行 AI 排查。

当前版本为 0.0.6。本版完善多人行动加入、调查发现公布、队友协作与阅读位置保持，统一 KP 对原始请求的理解和收尾，并优化上下文缓存结构与存档体积，详见更新记录。分组调查共享世界记录，分别保留见闻与叙述；普通输入向全桌公开，私信使用 /sc，同组发言突出显示，分头行动的消息使用灰色。

存档格式为 4。新存档采用共享正文编码，请同步更新房主与客户端；旧格式文件保留，但不能直接继续。

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

从早班火车进站开始

选定模组和调查员后，守秘人会结合角色背景安排开场。《追书人》的故事从早班火车驶入阿诺兹堡开始：委托人托马斯的家在小镇尽头的公墓旁，走过去还有一段路。你可以向站务员问路，在餐馆吃过早饭，或先去图书馆查阅旧报。交谈与探索均通过自然语言进行。调查延伸到原作未涉及的地方时，守秘人可补充人物、地点与支线，并保存在本局记录中；如需遵循原作，可切换严格模式。叙述篇幅、节奏与恐怖程度均可调整。

需要检定时，你会亲手投掷 3D 物理模拟的十面骰。失败后，可以选择花费幸运，或说明新的尝试方式，承担「孤注一掷」的风险；守秘人据此复核，结算实际耗时与后果。调查陷入僵局时，可按 Ctrl+L 请求灵感检定，获得关于遗漏线索的提示。理智损失、临时与不定性疯狂、重伤和幕间成长也有对应的结算。持有规则书与守秘人卡组时，还可导入游戏，供裁定查询原文，并在疯狂与惨事结算时抽卡。

调查所得通过叙述、人物对话与分发材料呈现，游戏不自动生成线索卡片或清单。玩家可按 F2 打开笔记，或输入 /记 内容 记录发现；已获得的剪报与信件保存在「资料」页，可查阅原文和原图。地图记录已到访或获知的地点，人物卡保存「本局经历」。游戏每回合自动存档，可在下次启动时继续。

_{《追书人》中的道格拉斯日记：独立纸张版式、红色页边与手写斜体，墨迹逐字显现。}

_{调查地图仅展示已到访或获知的地点，地表、道路与雾由程序生成。右侧列出当地见闻、人物与路程，按 G 前往所选地点。}

守秘人与世界记录

KP 掌握模组真相、人物秘密与当前世界状态，负责理解玩家意图、组织场面和把握节奏。NPC 的反应取决于自身动机与当前局势：托马斯可以主动带路、提供工具或协助调查，其他人物也可能拒绝合作、隐瞒事实、撒谎或抢先行动。

每轮的在场人物、同行关系与物品归属都有独立记录。程序核对相关操作，将冲突原因交回 KP 修正后，再展示相应叙述。例如，NPC 承诺“我陪您去”需要登记同行；声称“钥匙不在我这里”则可能是谎言，不会因此改变物品的实际归属。

场外人物按日程与触发条件活动，换场景、跳过时间或发生相关事件时，由同一 KP 统筹其动向。模组中结果明确的步骤由程序执行，人物资料与记忆持续保存。世界记录保留事实、知情范围、未完成约定及设定改写；会话摘要帮助模型接续故事，具体事实仍可回查。

导演可补充地点、线索、人物与规则，也可调整幕后设定，并记录改写依据。新增内容准备完成后才进入场面；若玩家提前抵达，界面显示“KP 正在构思…”，等待相关内容就绪。这些即兴与改写仅保存在本局，不覆盖导入的模组文件，也不影响其他存档。

Agent 架构

行动规划与最终主持共用 KP 会话，裁定员使用独立上下文，NPC 演出与导演备场按需调用。模型负责判断和提出方案，程序执行规则与世界操作，并将实际结果写入记录。下图展示各 Agent 的调用关系、上下文来源与执行回路。

放大查看 · 可编辑的 draw.io 源文件 · 图的设计与职责约定 · 实现说明

画面与手稿

模组中的老照片与插图会转成真彩字符画。天色随时间变化，雨雪、浓雾与摇曳的灯光叠加在场景中；按 Ctrl+A 可切换纯 ASCII 等画法。NPC 发言时，肖像出现在画面一侧，色调随情绪变化。信件、日记、剪报、电报与典籍各有纸色、墨色和版式，手写信与日记以斜体呈现，墨迹逐字显现。

配图优先采用模组原有素材。缺少图片的地点、人物与重要物件，会从公共图库和网页检索写实照片，由读图模型筛选、裁剪；素材不足且本机装有 Codex 时，可由 AI 补绘。怪物配图直接生成，用于战斗展示与追逐场景合成。所有配图统一调色并缓存在本机，可供同一模组的不同存档复用，也可通过 autokeeper art prepare 模组 提前准备。临时路人不生成头像；离线且没有 Codex 时，缺图内容以文字呈现。

开场、重大异状与结局可用整屏「大场景」插图呈现。本机装有 Codex 并开启「AI 画图」后，也能为即兴人物和地点生成配图。老宅失火、人物负伤，或伏笔在后续来访中发生变化时，场景与肖像可以依据原图重绘；这些变化图在剧情需要时才生成。

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

调查员与角色库

开局可选择模组预设调查员，也可新建或导入角色。角色库集中管理自建人物、存档中的调查员与模组预设，供后续游戏选用。

• AI 辅助建卡：可从角色设想开始，例如“落魄的禁酒令私家侦探”，也可输入历史人物或公众人物的姓名。以姓名建卡时，程序检索维基百科与历史图库，提供肖像候选，并结合人物经历和模组年代提出三个背景问题。完成问答后，按七版规则核算属性、职业点与兴趣点，后续仍可通过自然语言调整。
• 导入已有角色：支持骰娘 .st 属性串、Excel、PDF、Word 和纸质人物卡照片，识别录入后校正越界数值。酒馆角色卡（PNG / JSON）可保留人设与卡面图片，经背景问答转换为 CoC 调查员。

_{角色库统一管理自建角色、历次存档中的调查员与模组预设，支持跨局选用。}

模组导入、生成与规则插件

游戏自带《追书人》《冬雪之下》《有些人油盐不进》三本模组，分别呈现古典调查、暴风雪中的孤立小镇与多人冒险。初次游玩可以从适合单人入门的《追书人》开始。

_{模组选择界面展示故事背景、适用人数与场景预览。《追书人》适合单人入门。}

支持导入自备模组。将 PDF、Word、Markdown、纯文本或 ZIP 文件拖入标题页的「导入模组」，或运行：

autokeeper import 模组.pdf

编译模型读取原文，整理人物、地点、线索与事件，保留原有插图和手稿，并从公共图库补充符合年代的照片。通过编译与校验后，模组加入游戏列表。导入模型可单独配置。

编译期准备什么

编译阶段为 KP 准备人物知识、动机与关系，无人干预时的事件日程，以及场景背景、线索条件、伏笔变化、特殊规则、战斗数值和追逐路线。开场引入与初次见面的反应也会提前准备，游玩时再结合调查员背景与实际行动调整。

存在依赖的内容按顺序补全：先整理人物认知与动机，再生成关系和计划，最后对照原文复核。资料需明确区分“知道叔叔写日记”与“已经找到日记”，以及“买到酒”与“已将酒交给守墓人”。原作中的检定、前置条件和可能后果随资料提供给 KP，新增计划与规则一并导出至参考文件。

已有模组可用 autokeeper upgrade 模组 --dry-run 检查待补全的资料，该步骤不调用模型、不写文件；确认后运行 autokeeper upgrade 模组 补全。游玩时，KP 结合当前场景与本局记录使用这些材料，按需查询原文，并将临场安排写入本局记录。

生成原创模组

也可根据故事设定生成原创模组，由 AI 联网考据、编写剧情并准备插图：

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

规则插件与家规

传染病、机关、防线耐久、倒计时与资源消耗等特殊机制可由规则插件承载，例如《冬雪之下》的传染病与《追书人》的旧书架机关。插件可随模组提供，也可在游玩中生成：

• 模组专属机制：Python 插件在禁止文件、网络和子进程访问的沙箱中运行，可以显示边栏状态、播放字符演出、注册自定义 /命令，并提供选择、填空、排序与棋盘四类交互。
• 临时家规：开启开发者模式（F12），按 Ctrl+K 打开插件窗口，描述要添加的规则，例如“每次在暴风雪里赶路都要检定体质”。AI 生成插件并运行沙箱测试，通过后加载到本局。

_{规则插件面板（开发者模式下 Ctrl+K）：查看生效规则、触发状态与可用行动，支持以自然语言添加家规。}

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

战斗与追逐

战斗按第 7 版规则逐轮结算。对手在场景中呈现，血光与心跳配合交锋变化：扑击时逼近，受伤时呈现全屏溅血、爪痕与震动，命中时闪烁白光并显示血色伤害数值。怪物首次出现时，可通过全屏插图呈现，再进行理智检定。侧栏显示行动顺序与调查员生命值，对手仅显示伤势描述。

玩家可选择攻击、射击、推倒、缴械、制住、急救、装填、防守或逃跑，也可直接描述其他行动。闪避、反击与扑向掩体作为受攻击时的应对单独显示，按 Tab 切换，不占用行动。系统默认在首次被攻击、原应对不适用或危险升高时询问，并说明相应检定与代价；限时选择默认关闭，可在设置中开启。

引擎结算以多打少、射击修正、卡壳、贯穿、重伤、濒死与急救，伤势、弹药和掉落的武器保存在世界记录中。对手依据实际感知行动，不能攻击或追赶已失去踪迹的目标；护甲、自愈等特性在能够观察到时呈现。需要阅读长段叙述时，可按 Ctrl+N 收起画面。具体规则覆盖范围与简化见规则对照表。

_{《追书人》的书房战斗：对手仅显示可观察的伤势，每次交锋生成战斗记录；选单下方提供受攻击时的应对，按 Tab 切换。}

逃离与追赶沿地图路线展开。追逐开始时通过体质检定确定速度，每轮按速度差分配行动点；途中可翻越围墙、穿过灌木，或撬开、撞开锁门。场景采用冷色调与动态背景，并根据距离调整追兵的画面比例；侧栏显示路线、障碍和各参与者的位置。

脱离视线后，追兵可能失去目标，玩家也可尝试躲藏或转身迎战。被控制或倒在追兵面前时，追逐可转为战斗；对手逃离后，也可继续追赶。两者共用同一场遭遇，保留伤势、弹药、武器与实际位置。撞开的门和破坏的障碍会写入世界记录，后续经过时沿用改变后的状态。

_{《追书人》的墓园追逐：右侧显示通往出口的路线与障碍，各行动选项注明对应检定。}

单人游玩与好友联机

单人游玩可以独自调查，也可以选择 AI 调查员同行。「观战」模式则由 AI 小队进行游戏，供你观看故事发展。

房主在标题页选择「多人游戏 → 开房间」，配置真人与 AI 座位后分享房间网址。其他玩家通过浏览器加入，无需安装 Python 或配置模型密钥。每个座位可选择模组预设、导入已有角色，或使用房主的模型创建调查员。

调查与日常互动支持并行行动；战斗与追逐采用回合制，等待参战玩家提交行动或明确跳过后，按规则顺序结算。各玩家确认自己的骰点与应对，不因阅读或输入超时而失去行动机会。突发遭遇发生前尚未执行的声明，需由本人重新确认。

_{《冬雪之下》的房间准备界面：左侧配置真人与 AI 座位、选择调查员，右侧预览人物卡。}

分组调查可在不同地点同时推进，各玩家接收自己所在场景的叙述。同一建筑内的房间共用主持上下文，人物、物品与日程始终使用同一份世界记录。各场景独立主持，会合时由 KP 协调至共同时间；战斗、追逐与待答检定仍按回合处理。

调查阶段每人每轮提交一份行动。首段正文或 NPC 台词出现前，尚未行动的玩家仍可加入，KP 会结合新增声明继续处理，并保留已结算的动作与骰点。正文开始后，新行动留在输入框，不自动排入下一轮；也可按 Alt+J 先加入本轮，再填写行动。具体操作见一轮怎么进行。

检定者可决定是否向同场队友公布调查所得。涉及队友行动的请求需由对方确认后提交，保留各玩家的行动决定权。Alt+D 查看发现与协作，Alt+T 查看队伍状态、位置和连接情况。

房间默认开启「断线后由 AI 临时接管」。断线后保留一分钟重连宽限期，其间保留原声明与待答选择；超时后，AI 根据该角色的见闻继续行动。玩家重返原座位后恢复控制权，已完成的行动与骰点保留。关闭此选项后，系统等待玩家重连；全员离线时暂停游戏。AI 代管不额外消耗幸运，也不代为发起孤注一掷。

终端加入时，笔记只保存在自己的电脑上；浏览器笔记暂只保留在当前页面中，关闭或刷新后会清空。局域网及 Radmin、ZeroTier 等虚拟局域网的连接方法见联机说明。

队内交谈不占行动名额。以引号、“对某某说”或“对大家说”开头的发言会即时展示给同场人物并写入记录，无需 KP 单独回应；AI 同伴与在场 NPC 可在后续回应中承接。使用 /私聊 姓名 内容 可向同场队友私语，/私信kp 内容 可单独联系守秘人。场外聊天使用 // 或整句双括号；（压低声音）别进去。 等带动作的台词仍视为角色发言。单人模式下与 AI 队友的交流采用相同规则。

开始玩

Windows 用户可从发行页下载安装版或免安装版。 两者均内置 Python、Node.js、图片渲染组件和三本模组，保留终端字符界面。安装版运行安装程序；免安装版完整解压后运行 AutoKeeper.exe。模型凭据在首次启动时配置。

仅加入他人房间时，使用浏览器打开房间网址即可，无需安装客户端。

安装脚本会准备 uv、AutoKeeper 和图像渲染组件。掷骰需要 Node.js 18+，Windows 脚本会通过 winget 自动安装；其他系统的安装方法见游玩指南。

# 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，按首次配置引导选择模型并填写凭据。浏览器启动与模型配置也可通过以下命令完成：

autokeeper serve      # 在浏览器里玩
autokeeper login      # 换模型、补 API Key

再次运行一键安装命令即可更新至最新正式版。

# 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"

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

模型与上下文管理

AutoKeeper 的模型运行层（harness）负责调用、会话、工具执行与追踪，支持按分工组合 DeepSeek、Claude、Codex、Ollama 及 OpenAI 兼容接口。标题页「设置」与游戏内 F9 菜单均可切换模型；「各分工模型」可分别配置守秘人、NPC、裁定与读图模型，留空时使用方案默认值。「测试连接」逐一检查所用模型，预算设置与调用用量可在设置和开发者记录中查看。

会话独立于模型后端保存，随本局存档延续。近期对话保留原文，较早内容达到上下文窗口限制后由摘要模型压缩，重点保留人物态度、已作决定、谎言、约定与未完成事项。压缩失败时保留原记录，供后续重试；位置、物品、事件与当前设定由世界记录库维护。

KP 可按需查询人物、物品、历史事件与模组原文；模组建有 LightRAG 索引时，也可进行关联检索。规则书有独立的本地索引，裁定或提问时可查询相应原文。NPC 演出只接收自己的资料与所知，KP 则读取主持所需的幕后信息。

每轮按行动安排、裁定、人物回应与叙述等阶段执行，保存已完成的回应与结算结果，支持中断恢复。模组导入、原创生成等长任务通过工具循环读取材料、检索资料和写入文件，过程可追踪。Ollama 支持本地离线运行；模型配置、预算与花费说明见游玩指南。

_{模型设置（F9）支持按职责配置模型，并列出各分工用途；读图分工需要支持图像输入的模型。}

开发者模式与 AI 排查

按 F12、输入 /dev，或在「设置」中开启开发者模式后，终端显示本轮调用与场面概况，并打开本机私有网页供查阅完整后台资料。

诊断网页按存档保留玩家输入、模型实际收到的上下文、系统提示与摘要、回复、重试、用量、世界操作和图片任务。支持按回合回查人物位置、日程与导演进展，以及检索、下载记录；分页和会话压缩不会清除已保存的诊断历史。

针对剧情矛盾、知情范围或状态不一致，可指定回合、选择记录并提交问题，由独立 AI 对照证据分析。排查结果注明所用资料，排查过程不修改存档、世界或人物记忆；仅查看和下载记录不调用模型。旧版本未保存的请求无法补回。

当前源码中，从标题页创建房间的房主也可使用开发者面板、私有网页与规则插件。其他玩家和观战者没有开发者入口，不会收到隐藏资料。使用方法见开发者模式文档。

_{终端中的开发者面板：显示本轮模型调用、人物实际位置与日程；完整历史与 AI 排查在本机私有网页中查看。}

文档与开发

• 游玩指南：安装、模型配置、快捷键、战斗与追逐、规则书与卡组、联机排查。
• 模组格式 / 规则插件：手工编写剧本、配置大场景与开发自定义机制。
• 守秘人体验设计：开场引入、导演即兴、线索节奏与配图设计。
• 模型运行机制 / 评测记录 / 世界引擎设计：模型会话、工具循环、评测与世界记录的设计；历史设计与后续计划在相应章节说明。
• 战斗与追逐：规则分层、回合结算、追逐地图与联机公开状态投递。
• 规则对照表：战斗、伤害、追逐、检定与主持，逐条对照《守秘人规则书》的页码、实现和测试。
• 开发者模式：终端概况、本机完整记录网页、历史查询与独立 AI 排查。

反馈裁定或运行问题时，请提交 Issue，并附上模组名、当轮行动与相关日志。源码位于 src/autokeeper/，测试位于 tests/；提交 PR 前请运行 uv run ruff check src tests 与 uv run pytest -q。开发约定见 AGENTS.md。

README 截图由当前 Textual 界面与固定示例数据生成，保留实际字符网格和配色；画面中的叙述与骰点仅用于界面演示。生成方式见截图与架构图维护。

致谢与许可

终端界面基于 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 无关。