Metadata-Version: 2.5
Name: autokeeper
Version: 0.0.6.3
Summary: 自动化 CoC 7 版中文跑团：自研 harness 上的多智能体守秘人，Claude / DeepSeek / 本地模型可换，模组导入与生成，彩色 ASCII 终端界面
Project-URL: Homepage, https://github.com/satoshinji2992/autokeeper
Project-URL: Source, https://github.com/satoshinji2992/autokeeper
Project-URL: Changelog, https://github.com/satoshinji2992/autokeeper/blob/main/CHANGELOG.md
Author-email: Sato shinji <wwwsatoshinji@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: call-of-cthulhu,coc7,llm,tabletop,textual,trpg
Classifier: Environment :: Console
Classifier: Natural Language :: Chinese (Simplified)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment :: Role-Playing
Requires-Python: >=3.12
Requires-Dist: aiohttp>=3.9
Requires-Dist: chafa-py>=1.2.0; (sys_platform == 'win32' and platform_machine == 'AMD64') or (sys_platform == 'linux' and platform_machine in 'x86_64 aarch64') or sys_platform == 'darwin'
Requires-Dist: ddgs>=9.16.0
Requires-Dist: filelock>=3.15
Requires-Dist: httpx>=0.27
Requires-Dist: ifaddr>=0.2
Requires-Dist: jieba>=0.42.1
Requires-Dist: jsonpatch>=1.33
Requires-Dist: jsonschema>=4.23
Requires-Dist: langchain-core>=1.6.12
Requires-Dist: langchain-deepseek>=1.1.1
Requires-Dist: langchain-google-genai>=4.4.2
Requires-Dist: langchain-ollama>=1.1.0
Requires-Dist: langchain-openai>=1.7.2
Requires-Dist: langchain>=1.4.6
Requires-Dist: langgraph-checkpoint-sqlite>=3.1.2
Requires-Dist: langgraph>=1.2.16
Requires-Dist: markitdown[docx,pdf,xlsx]>=0.1.8
Requires-Dist: networkx>=3.7
Requires-Dist: pillow>=10.4
Requires-Dist: platformdirs>=4.13.3
Requires-Dist: pydantic-settings>=2.16.0
Requires-Dist: pydantic>=2.7
Requires-Dist: pyfiglet>=1.0.4
Requires-Dist: pypdfium2>=5.14.0
Requires-Dist: pypinyin>=0.55.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: python-slugify>=9.1.3
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: rich>=15.0.0
Requires-Dist: skills-ref>=0.1.1
Requires-Dist: terminaltexteffects>=0.15.0
Requires-Dist: textual-canvas>=1.1.0
Requires-Dist: textual-serve>=1.1.3
Requires-Dist: textual>=6
Requires-Dist: typer>=0.27.3
Requires-Dist: wcwidth>=0.9.2
Provides-Extra: art
Requires-Dist: ascii-magic>=2.7.5; extra == 'art'
Requires-Dist: opencv-python-headless>=5.0.0.93; extra == 'art'
Provides-Extra: claude
Requires-Dist: claude-agent-sdk>=0.2.168; extra == 'claude'
Provides-Extra: graphrag
Requires-Dist: fastembed>=0.6; extra == 'graphrag'
Requires-Dist: lightrag-hku>=1.5.7; extra == 'graphrag'
Description-Content-Type: text/markdown

<div align="center">

<a href="docs/img/title.png"><img src="docs/img/title.png" width="760" alt="AutoKeeper 标题画面：克苏鲁与拉莱耶的彩色字符画"></a>

*Ph'nglui mglw'nafh Cthulhu R'lyeh wgah'nagl fhtagn.*

*我以为，世上最仁慈的事，莫过于人类的心智无法把它所知的一切关联起来。*<br>

<sub><i>H. P. 洛夫克拉夫特，《克苏鲁的呼唤》</i></sub>

<br>

**《克苏鲁的呼唤》第 7 版 · AI 守秘人**

真彩字符画 · 终端 / 浏览器

[![Release](https://img.shields.io/github/v/release/satoshinji2992/autokeeper?label=version&color=B8860B)](https://github.com/satoshinji2992/autokeeper/releases/latest)
[![CI](https://github.com/satoshinji2992/autokeeper/actions/workflows/ci.yml/badge.svg)](https://github.com/satoshinji2992/autokeeper/actions/workflows/ci.yml)
[![MIT](https://img.shields.io/badge/license-MIT-2EA44F)](LICENSE)

[项目网页](https://satoshinji2992.github.io/autokeeper/) · [游戏体验](#游戏体验) · [下载与游玩](#下载与游玩) · [技术设计](#技术设计) · [文档](#文档与开发)

</div>

AutoKeeper 是一款由 AI 担任守秘人（KP）的中文《克苏鲁的呼唤》第 7 版跑团游戏。你扮演调查员，以自然语言行动、交谈和探索；AI 负责备团、演出人物、安排遭遇与冲突，并根据调查进展把控节奏。可以独自调查、带上 AI 同伴，也可以邀请朋友，通过终端或浏览器进入同一场故事。

模组提供故事的起点，后续发展由玩家的选择与人物的动机共同影响。守秘人能够拓展原作未写到的地点、支线和规则，调整本局设定；世界引擎持续记录这些变化。多人分头行动时，各自获得不同的叙述、观察与材料，同时共享人物、物品和事件的实际状态。

<p align="center">
  <a href="docs/img/game.png"><img src="docs/img/game.png" width="100%" alt="追书人游戏界面：在图书馆查旧报，图书馆使用检定的物理十面骰，守秘人讲出旧报上的内容；右侧是人物状态、调查经过和玩家自己的笔记"></a>
  <br><sub>《追书人》游戏界面：在阿诺兹堡图书馆查阅旧报、投掷物理十面骰完成检定，右侧同步记录状态与调查经过。</sub>
</p>

## 游戏体验

### 从早班火车进站开始

选定模组和调查员后，守秘人会结合角色背景安排开场。《追书人》的故事从早班火车驶入阿诺兹堡开始：委托人托马斯的家在小镇尽头的公墓旁，走过去还有一段路。你可以向站务员问路，在餐馆吃过早饭，或先去图书馆查阅旧报。旅途、闲谈和人物关系也构成故事，调查不必每一步都直奔线索。

KP 根据当前局势决定何时留下交谈与休整的空间，何时让异状出现、人物介入或危险逼近。叙述篇幅、节奏与恐怖程度可以调整；希望严格遵循原作时，也可以关闭即兴扩展。

### 自动备团与临场拓展

导入自备的 PDF、Word、Markdown、纯文本或 ZIP 模组后，AI 会读取原文，整理人物动机、知情范围、线索条件、事件日程、场景与规则，保留原有图片和手稿，为正式开团准备资料。导入模型可单独配置；也可以给出一个故事设定，由 AI 联网考据、编写原创模组并准备插图。

游玩中，KP 会结合调查员的背景与行动继续改编。玩家走进原作未写到的街区、决定求助其他人物，或让事件偏离既定安排时，系统可按需准备新的地点、NPC、线索、遭遇和结局，并补齐配图与特殊规则。导演也能修改尚未被玩家确认的幕后设定，让新的安排与已经发生的事相衔接。

新增内容准备完成后才进入场面；玩家提前抵达时，会等待相关内容就绪。即兴与改写保存在本局记录中，原模组和其他存档保持独立。

传染病、机关、倒计时与资源消耗等机制可通过规则插件接入。插件既可随模组提供，也可由 AI 在编译或临场准备时生成，经沙箱测试后加载。

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

<p align="center">
  <a href="docs/img/module.png"><img src="docs/img/module.png" width="100%" alt="模组选择界面：追书人的故事介绍、调查人数与彩色字符画预览"></a>
  <br><sub>模组选择界面展示故事背景、适用人数与场景预览。《追书人》适合单人入门。</sub>
</p>

### 冲突、节奏与 NPC 的选择

NPC 各自保有动机、秘密、关系与未完成的打算。他们可以主动协助、隐瞒、撒谎、抢先行动，也会因调查员的说服、威胁或帮助而改变目标。托马斯可以主动带路、提供工具或参与调查；怀有戒心的人则可能敷衍问题、通知同伙，或在玩家返回前离开。

这些人物行动也是冲突的来源。KP 统一考虑现场反应与幕后动向，依据日程、约定和事件安排矛盾、悬念与后果，并决定何时让它们进入玩家视野。场外人物在换场景、时间跳过或相关条件成立时推进自己的计划；日常交流和暂时的平静同样可以保留，紧迫感随局势发展。

### 守秘人与世界记录

世界引擎持续维护人物位置、同行关系、重要物品归属、知情范围、约定、日程与设定变化。人物说过什么、打算做什么、实际上完成了什么，分别保存在记录中，后续场面可以继续使用这些事实。

例如，NPC 承诺“我陪您去”需要落实同行；声称“钥匙不在我这里”可能是谎言，钥匙的归属仍按实际交接记录。撞开的门、丢下的武器、已经发生的伤势和耗用的弹药，也会影响下一次遭遇。游戏每回合自动存档，继续游玩时沿用本局的世界状态与经历。

<p align="center">
  <a href="docs/img/map.png"><img src="docs/img/map.png" width="100%" alt="冬雪之下的彩绘地图：主街、诊所、教堂、邮局与农场之间的土路，右侧是主街的说明与去各处的路程"></a>
  <br><sub>调查地图仅展示已到访或获知的地点，地表、道路与雾由程序生成。右侧列出当地见闻、人物与路程，按 G 前往所选地点。</sub>
</p>

### 单人游玩与好友联机

单人游玩可以独自调查，也可以选择 AI 调查员同行；「观战」模式由 AI 小队进行游戏。多人游戏则支持各自行动、分组调查与个人见闻，朋友通过浏览器打开房间网址即可加入，无需安装客户端或配置模型密钥。

**分头调查时，各组可以同时推进，并看到不同的故事画面。** 例如，一组留在诊所询问医生，另一组前往农场查看车库，各自收到所在场景的叙述；个人观察、私信、图片和手稿按实际收件人投递。同一场遭遇也可以针对不同调查员呈现各自的观察，允许玩家之间保留信息差。

不同分支使用同一份世界记录，人物位置、物品流转与事件变化持续同步。同一个 NPC 不能同时出现在两处，一件物品的交接也会影响另一组后续的调查。会合时由 KP 协调时间与场面；同一建筑内换房间则继续共用主持上下文。

调查与日常互动支持并行行动，战斗与追逐按回合结算。每位玩家确认自己的骰点与应对，调查所得是否公布、是否接受队友提出的行动，都由本人决定。普通发言向全桌公开，分头行动的发言以灰色区分；与 KP 的私密交流使用 `/sc`。调查员数值仍照常共享。

<p align="center">
  <a href="docs/img/lobby.png"><img src="docs/img/lobby.png" width="100%" alt="冬雪之下开房间界面：左侧是座位与调查员选择，右侧是选中调查员的肖像与人物卡"></a>
  <br><sub>《冬雪之下》的房间准备界面：左侧配置真人与 AI 座位、选择调查员，右侧预览人物卡。</sub>
</p>

### 模组之外的临场发展

下面两段来自玩家实际游玩《冬雪之下》时的截图，保留了当时的对话与界面。

**一局麻将，成为认识 NPC 的契机。** 玩家在饭桌上提议打麻将，原模组没有这段安排。多琳询问玩法，门廊边的年轻人也接过话头。KP 顺着凑齐一桌的需要安排人物参与，把玩家临时提出的娱乐接成了结识 NPC 的机会。

<p align="center">
  <a href="docs/img/play-mahjong.png"><img src="docs/img/play-mahjong.png" width="100%" alt="冬雪之下实机：玩家提议打麻将，多琳回应，一名门廊边的年轻人加入谈话"></a>
  <br><sub>实机片段：模组之外的麻将邀约，让一名人物自然进入了饭桌上的交流。</sub>
</p>

**分头调查的经历，在会合后继续产生影响。** 玩家在诊所会合后，围绕贝尔的身份出现误认，医生在交谈中纠正：她是来调查病情的，并非诊所的当班护士。人物各自掌握的情况，通过对话进入共同场面。

<p align="center">
  <a href="docs/img/play-reunion.png"><img src="docs/img/play-reunion.png" width="100%" alt="冬雪之下联机实机：玩家在诊所会合，医生澄清贝尔是来查病的，与诊所当班护士不是同一人"></a>
  <br><sub>实机片段：会合后的身份误认与纠正，承接了分头行动时形成的人物关系。</sub>
</p>

### 画面与手稿

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

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

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

<p align="center">
  <a href="docs/img/showcase.png"><img src="docs/img/showcase.png" width="100%" alt="追书人开场的大场景：阿诺兹堡早班车，车站照片转成整屏彩色字符画"></a>
  <br><sub>关键时刻的整屏大场景：《追书人》开场，早班火车停靠阿诺兹堡车站。</sub>
</p>

<p align="center">
  <a href="docs/img/paper.png"><img src="docs/img/paper.png" width="100%" alt="道格拉斯·金博尔的日记：米色纸张、红色页边、斜体手写正文"></a>
  <br><sub>《追书人》中的道格拉斯日记：独立纸张版式、红色页边与手写斜体，墨迹逐字显现。</sub>
</p>

### 调查员与角色库

开局可选择模组预设调查员，也可新建或导入角色。角色库只管理自己创建或主动导入的人物卡，供后续游戏选用；存档中的调查员不自动加入角色库。

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

<p align="center">
  <a href="docs/img/cards.png"><img src="docs/img/cards.png" width="100%" alt="角色库：管理自己创建与导入的人物卡"></a>
  <br><sub>角色库管理自己创建与导入的人物卡，支持编辑、导出与跨局选用。</sub>
</p>

### 战斗与追逐

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

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

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

<p align="center">
  <a href="docs/img/fight.png"><img src="docs/img/fight.png" width="100%" alt="追书人书房里的战斗：犬脸的佝偻身影占满舞台，旁边是出手先后与伤势，下方是战斗卡片、行动选单和被攻击时的应对"></a>
  <br><sub>《追书人》的书房战斗：对手仅显示可观察的伤势，每次交锋生成战斗记录；选单下方提供受攻击时的应对，按 Tab 切换。</sub>
</p>

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

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

<p align="center">
  <a href="docs/img/chase.png"><img src="docs/img/chase.png" width="100%" alt="墓园里的追逐：调查员追着犬脸的佝偻身影，翻矮墙时摔了一跤；右侧是到出口的路，下方是灌木的几种过法"></a>
  <br><sub>《追书人》的墓园追逐：右侧显示通往出口的路线与障碍，各行动选项注明对应检定。</sub>
</p>

<a id="开始玩"></a>

## 下载与游玩

当前正式版为 **0.0.6.3**。本版恢复行动起笔、场面确定后的流式正文与后台备场，减少已完成问答的重复收尾；修复分队大图遗漏与会合等待提示，并完善调查信息投递和重要场景描写。更新前请先退出游戏，联机房主与玩家请统一升级。完整记录见 [CHANGELOG](CHANGELOG.md)。

```bash
uv tool install --force --refresh-package autokeeper "autokeeper==0.0.6.3"
```

使用 Claude 时将包名改为 `"autokeeper[claude]==0.0.6.3"`。本版不再提供 Windows 完整安装包；Windows 用户通过下方一键脚本安装或更新，运行 `autokeeper` 启动，沿用原有存档与设置。

### 下载安装

各平台通过下方一键脚本安装；首次启动时配置模型凭据。当前[发行页](https://github.com/satoshinji2992/autokeeper/releases/latest)提供 Python 包与源码包，历史 Windows 完整客户端保留在 [0.0.6.2 发行页](https://github.com/satoshinji2992/autokeeper/releases/tag/v0.0.6.2)。

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

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

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

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

安装完成后，在新终端运行 `autokeeper`，按首次配置引导选择模型并填写凭据。浏览器启动与模型配置也可通过以下命令完成：

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

退出 AutoKeeper 后，再次运行一键安装命令即可更新至最新正式版。Windows 用户需关闭所有 AutoKeeper 窗口，在新的 PowerShell 窗口执行更新；运行中的程序会占用安装文件，导致“拒绝访问”。更新保留存档与设置。游戏内的「检查更新」会提供对应命令，可在退出后复制执行。

<details>
<summary><b>手动安装：uv / pipx</b></summary>
<br>

手动安装使用 PyPI 上已发布的版本；若最新发行版尚未同步至 PyPI，请使用一键安装。pipx 用户可运行 `pipx install autokeeper`。如需安装 [uv](https://docs.astral.sh/uv/getting-started/installation/)，可运行官方脚本：

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

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

安装 uv 后打开新终端，运行：

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

首次运行会准备掷骰组件并检查图像渲染。常用平台随包安装 chafa 渲染库，无需另装 Scoop；存档位置与各系统的依赖说明见[安装说明](docs/playing.md#安装)。

</details>

网页端可在「设置 → 字体大小」调整字号，保存后立即生效，刷新后仍会保留，且只影响当前浏览器。原生客户端的字号由终端管理；Windows Terminal 可使用 Ctrl+滚轮调整。

### 选择模型与开始第一局

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

1. 启动游戏，在首次配置引导中选择模型并填写凭据；也可先在「设置」中测试连接。
2. 选择「新的调查」，挑选模组，再选择预设调查员、创建新角色或导入自己的卡。初次游玩可从《追书人》开始。
3. 开场结束后，在输入框描述行动或交谈。需要检定时按提示掷骰，下次启动可从标题页继续存档。

<p align="center">
  <a href="docs/img/models.png"><img src="docs/img/models.png" width="100%" alt="模型设置的各分工模型页：守秘人、守秘人安排、裁定、NPC、导演等分工与各自的模型"></a>
  <br><sub>模型设置（F9）支持按职责配置模型，并列出各分工用途；读图分工需要支持图像输入的模型。</sub>
</p>

### 行动、检定与调查记录

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

玩家的行动和发言靠右显示，KP 叙述与 NPC 对话靠左。每位调查员与 NPC 使用各自的颜色，公开内容直接显示，私信保留标记；长台词会完整换行。现场人物的圆形头像叠在场景左下角。

调查所得通过叙述、人物对话与分发材料呈现，游戏不自动生成线索卡片或清单。玩家可点击叙述或 NPC 台词右下角的圆形加号，为整段原文命名并加入笔记，也可按 F2 编辑笔记，或输入 `/记 内容` 记录发现；已获得的剪报与信件保存在「资料」页，可查阅原文和原图。地图记录已到访或获知的地点，人物卡保存「本局经历」。标题页的角色库只列出自己创建或主动导入的人物卡，模组预设仍可在开局选用。游戏每回合自动存档，可在下次启动时继续。

### 多人入房与交流

房主在标题页选择「多人游戏 → 开房间」，配置真人与 AI 座位后分享房间网址。其他玩家通过浏览器加入，无需安装 Python 或配置模型密钥。每个座位可选择模组预设、导入已有角色，或使用房主的模型创建调查员。所有玩家入座、选好角色并确认准备后，由房主点击“开始游戏”。全员准备不会自动开局。

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

检定者可决定是否向同场队友公布调查所得。涉及队友行动的请求需由对方确认后提交，保留各玩家的行动决定权。输入框上方会显示待回应和待公布的数量，点击即可处理，不会自动弹窗打断阅读。

右上角保留自己的详细人物面板，下方常驻队友的生命、理智、地点和连接状态；点击队友即可查看完整人物卡。分队与重连沿用各自收到的见闻，顶部用量显示全桌累计 token。窄窗口下也可点击「队伍」集中查看。

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

<details>
<summary><b>断线接管、笔记与连接方式</b></summary>

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

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

</details>

### 模组导入与原创生成

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

```bash
autokeeper import 模组.pdf
```

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

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

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

更多操作见[导入与生成说明](docs/playing.md#导入生成与观战)。

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

<details>
<summary><b>更多界面：电报、人物卡与存档管理（点击展开）</b></summary>
<br>

每张图均可点击查看高清原图。

#### 电报

<a href="docs/img/telegram.png"><img src="docs/img/telegram.png" width="100%" alt="冬雪之下的军队电报：黄色电报纸上贴着一条条打字纸条"></a>

#### 人物卡与本局经历

<a href="docs/img/sheet.png"><img src="docs/img/sheet.png" width="100%" alt="人物卡：调查员的背景、属性与完整技能列表"></a>

### 存档管理与进度预览

<a href="docs/img/saves.png"><img src="docs/img/saves.png" width="100%" alt="存档管理：模组、调查员、游戏时间和地点，以及存档预览"></a>

</details>

## 技术设计

### 世界操作与执行记录

KP 可以读取完整幕后资料，通过工具查询记录、预演与提交世界操作。程序核对位置、同行、物品归属及实际执行条件，将不成立的原因返回 KP 修正；模型提案、人物台词与已执行结果分别保存。

场外人物的主动行为由 KP 结合日程与触发条件统筹，NPC 演出按需调用，没有为每个人持续运行一个后台模型。模组中结果明确的日程由程序执行，需要新判断的事项交回 KP。各场景拥有自己的主持上下文和执行进度，提交变化时仍核对共享世界。

工具请求、实际回执、阶段进度与个人投递信息随存档保存。中断后沿已有记录恢复，已经结算的骰点、移动和交物不会因重新生成叙述而再次执行。导演的临场改写作为本局模组补丁保存，原模组可继续用于其他游戏。

### 编译期准备

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

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

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

### 模型与上下文管理

AutoKeeper 的模型运行层（harness）负责调用、会话、工具执行与追踪，支持按分工组合 DeepSeek、Claude、Codex、Ollama 及 OpenAI 兼容接口。

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

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

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

### 规则插件与家规

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

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

<p align="center">
  <a href="docs/img/plugins.png"><img src="docs/img/plugins.png" width="100%" alt="规则插件：查看本局特殊机制、可用行动，或者用一句话添加家规"></a>
  <br><sub>规则插件面板（开发者模式下 Ctrl+K）：查看生效规则、触发状态与可用行动，支持以自然语言添加家规。</sub>
</p>

更多细节见[导入与生成说明](docs/playing.md#导入生成与观战)、[模组格式文档](docs/module-format.md)与[规则插件文档](docs/plugins.md)。

### 开发者模式与 AI 排查

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

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

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

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

<p align="center">
  <a href="docs/img/developer.png"><img src="docs/img/developer.png" width="100%" alt="开发者模式：顶栏变色，叙述下方列出人物实际位置与接下来的日程"></a>
  <br><sub>终端中的开发者面板：显示本轮模型调用、人物实际位置与日程；完整历史与 AI 排查在本机私有网页中查看。</sub>
</p>

### Agent 架构

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

| 部分 | 当前职责 |
| --- | --- |
| 守秘人 | 理解玩家行动，统一安排现场与幕后人物，提交变化并叙述结果 |
| NPC 演出 | 根据自身知识、动机与关系回应，同时提交台词与当场动作 |
| 裁定员 | 根据行动与规则资料决定检定要求、耗时和后果 |
| 导演 | 按需准备完整的新遭遇、人物、地点、图片与特殊规则 |
| 世界记录与结算 | 保存事实与日程，执行确定的步骤，核对位置、同行和物品等操作 |

<p align="center">
  <a href="docs/img/architecture.svg"><img src="docs/img/architecture.svg" width="100%" alt="AutoKeeper Agent 架构：KP 主持循环、独立裁定、按需 NPC 与导演、上下文与记忆，以及工具执行回执"></a>
</p>

[放大查看](docs/img/architecture.svg) · [可编辑的 draw.io 源文件](docs/architecture.drawio) · [图的设计与职责约定](docs/agent-architecture-design.md) · [实现说明](docs/harness.md)

### 文档与开发

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

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

麻将与诊所会合两张图由玩家提供，保留实机原图。其余界面图在当前程序中加载固定展示场景后截取；战斗与追逐执行真实规则结算和物理掷骰，用于说明界面与操作，不作为 AI 临场表现的证据。截图方式见[截图与架构图维护](dev/README.md#截图与架构图)。

### 版本记录

<details>
<summary><b>0.0.5 更新亮点与升级须知</b></summary>
<br>

- **分组调查**：独立调查分支保留自己的主持上下文、游戏时间和待办选择；同一建筑内换房间继续由原守秘人统筹。KP 可判断跨场衔接时能否略过空白时间，共享人物与物品的争用交回守秘人裁定。
- **个人见闻**：私信、个人观察、图片和手稿按实际收件人投递，重连恢复当时收到的内容。调查员数值照常共享。
- **规则后果**：证词、材料与恐怖遭遇按实际接触者结算；已知内容与已结算后果分别记录，重复听闻和恢复不会重复扣除。
- **行动接续**：长等待保留原意图和期限；场面变化后可以重新声明。战斗与追逐继续逐轮处理。
- **断线接管**：默认保留一分钟重连宽限期，再由 AI 临时代管；玩家返回后交还控制权，已完成的结果保留。全员离线时暂停，也可在开房时关闭接管。
- **守秘人与世界**：现场人物、同行和物品交接直接写入记录，NPC 可以改变目标；同一段幕后日程共用调度，避免重复推进。
- **安装**：一键安装锁定正式发行版；PyPI 尚未同步时，使用同一版本的 GitHub 安装包。本版使用新存档格式，旧文件保留。

</details>

<details>
<summary><b>0.0.4 更新亮点与升级须知</b></summary>
<br>

- **战斗与追逐重写**：按第 7 版规则逐轮结算；选项位于输入框上方，受攻击时按 Tab 切换应对，危险升高时询问；追逐按地图路线推进，伤势、弹药与掉落武器写入世界记录。
- **灵感检定与孤注一掷**：调查陷入僵局时可按 Ctrl+L 请求灵感检定；孤注一掷需说明尝试方式，由裁定员复核，并计入实际耗时。
- **守秘人**：针对人物的检定依据对方技能确定难度；恐怖遭遇先呈现感官描述，避免直接揭示身份；伏笔随后续来访逐步变化，并更新场景图。
- **规则书与卡组**：`autokeeper rules index` 导入规则书，供裁定与 `/kp` 提问查询原文；`autokeeper cards import` 导入守秘人卡组，用于疯狂与惨事抽卡。
- **模组**：三本自带模组补充追逐路线、预设袭击与伏笔变化；《有些人油盐不进》新增小镇时钟。
- **联机**：各座位独立掷骰与应对攻击，倒计时精确至秒；客户端不再接收守秘人资料。
- **升级须知**：0.0.4 不兼容旧存档，旧文件保留并标记为不可读取；已移除通过 Claude Code MCP 主持的方式与 Claude Code 插件。
- 详见[完整更新记录](CHANGELOG.md)。

</details>

<details>
<summary><b>0.0.3 更新亮点</b></summary>
<br>

- **世界记录**：各局独立保存人物位置、知情范围、承诺与日程，区分人物意图、口头说法和已完成的行动。
- **守秘人统一主持**：KP 读取完整幕后资料，每轮安排玩家行动与在场人物的主动参与，将场面变化写入记录后呈现。
- **检定与现场互动**：检定失败不自动补发线索，孤注一掷前说明后果；支持当场取得或借用日常物件。
- **配图**：彩绘地图；手稿按信件、日记、报纸、电报、典籍排版。
- **模型按分工配置**：各分工可独立选择模型，Claude 方案使用 Sonnet 裁定；提高提示词缓存命中率，缩短等待。
- **命令行安装**：`uv tool install autokeeper`，支持在任意目录启动，并自动迁移源码目录中的存档。AutoKeeper 不绑定特定模型，Claude 为可选组件。

</details>

## 致谢与许可

终端界面基于 [Textual](https://github.com/Textualize/textual) 构建，照片转字符画使用 [chafa](https://hpjansson.org/chafa/)，掷骰与骰娘指令使用 [BCDice](https://github.com/bcdice/BCDice)，智能体编排与原文检索分别基于 [LangGraph](https://github.com/langchain-ai/langgraph)、[LangChain](https://github.com/langchain-ai/langchain) 与 [LightRAG](https://github.com/HKUDS/LightRAG)。

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