autokeeper 0.0.3__tar.gz

autokeeper-0.0.3/.claude-plugin/marketplace.json

@@ -0,0 +1,11 @@
+{
+  "name": "autokeeper",
+  "owner": { "name": "satoshinji2992" },
+  "plugins": [
+    {
+      "name": "autokeeper",
+      "source": "./",
+      "description": "CoC 7 版中文跑团守秘人：MCP 游戏引擎 + 规则与模组 Skill 包"
+    }
+  ]
+}

autokeeper-0.0.3/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "autokeeper",
+  "version": "0.0.3",
+  "description": "在 Claude Code 里跑 CoC 7 版中文团：BCDice 掷骰、模组 Skill 包、隔离记忆的 NPC、彩色 ASCII 插图。",
+  "author": { "name": "satoshinji2992" },
+  "license": "MIT",
+  "keywords": ["trpg", "call-of-cthulhu", "keeper", "mcp", "agent-skills"]
+}

autokeeper-0.0.3/.gitignore

@@ -0,0 +1,42 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Copyrighted modules stay local. Drop module files into modules/inbox/; anything dropped
+# straight into modules/ (PDF, zip, Word, Markdown, text, pictures) is ignored too, and so are
+# PDFs, Word files and archives anywhere under it; module folders such as modules/zhuishuren/
+# and modules/README.md stay tracked. Imports land in modules/local/<id>/, their originals in
+# its source/. Keep these lines in this order: the last match wins.
+/modules/*
+!/modules/*/
+!/modules/README.md
+/modules/**/*.pdf
+/modules/**/*.doc
+/modules/**/*.docx
+/modules/**/*.zip
+/modules/**/*.rar
+/modules/**/*.7z
+modules/inbox/
+modules/local/
+modules/*/source/
+skills/module-*
+# What the game writes (src/autokeeper/paths.py); saves/ is the folder 0.0.1 used
+data/
+saves/
+dev/output/
+.env
+bridge/node_modules/
+
+# Personal planning notes (job targets, resume drafts)
+PLAN.md
+
+# Tool caches
+.pytest_cache/
+.ruff_cache/

autokeeper-0.0.3/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "autokeeper": {
+      "command": "uv",
+      "args": ["run", "--directory", "${CLAUDE_PLUGIN_ROOT}", "autokeeper", "mcp"]
+    }
+  }
+}

autokeeper-0.0.3/.python-version

@@ -0,0 +1 @@
+3.12

autokeeper-0.0.3/AGENTS.md

@@ -0,0 +1,43 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+AutoKeeper runs Chinese Call of Cthulhu 7th-edition games on Python 3.12+.
+
+- `src/autokeeper/`: `engine/` manages turns/state; `agents/` and `harness/` handle models; `rules/` implements mechanics; `plugins/` runs tested extensions; `net/` supports multiplayer; `module/` handles scenarios (`module/package.py` is the on-disk layout of one); `world/` is the persistent world record. `paths.py` owns every location on disk: ask it instead of joining paths yourself.
+- `src/autokeeper/tui/`: `app.py` (the Textual app) and `library.py` (save index, module loading, `art_text`); `screens/` full pages (title, setup, game, cards, LAN host, lobby, saves, import); `modals/` dialogs over a screen; `widgets/` panels, speaker, pages, tips; `drawing/` title art, cover and dice. Each `.tcss` sits beside its code.
+- `bridge/`: Node.js JSON-lines bridge to BCDice.
+- `tests/`: tests, `conftest.py` fixtures (every test gets its own `paths.DATA`, `paths.DEV_OUTPUT` and `paths.USER_DIR`), and `cassettes/` recordings.
+- `modules/<id>/`: the three bundled scenarios: `module.yaml` plus `places.yaml`, `people.yaml`, `clues.yaml`, `story.yaml`, `plugins/`, and `art/{places,people,items,ascii}/` with one `art/credits.yaml`. `src/autokeeper/module/example/` is the format fixture. Never commit derived files into a module (prepared pictures, compiled skills); they live under `data/cache/` and `skills/module-*`.
+- `skills/`, `agents/`, `commands/`, `.claude-plugin/` and `.mcp.json`: the Claude Code plugin (paths fixed by the plugin format). Shared skills are tracked; `skills/module-*` are compiled and ignored. `docs/` contains technical documentation; `docs/img/` holds screenshots.
+- `dev/`: developer scripts (public-share tunnel); their output and eval/autoplay reports go to ignored `dev/output/`.
+
+## Build, Test, and Development Commands
+
+Prerequisites: Python 3.12+, uv, Node.js 18+.
+
+- `uv sync --extra claude`: install dependencies.
+- `npm ci --prefix bridge --no-audit --no-fund`: install the locked dice-bridge dependencies.
+- `uv run autokeeper doctor`: inspect the local environment.
+- `uv run autokeeper`: launch the terminal game; `uv run autokeeper serve` starts browser play.
+- `uv build`: build Python distributions with Hatchling.
+- `uv run ruff check src tests`: run lint and import-order checks.
+- `uv run pytest -q`: run the test suite.
+- `uv run autokeeper check src/autokeeper/module/example`: validate the format example.
+- `uv run agentskills validate skills/<name>`: validate a skill.
+
+## Coding Style & Naming Conventions
+
+Use four-space indentation, annotate new interfaces, and use `snake_case` functions/modules, `PascalCase` classes, and `UPPER_CASE` constants. Preserve Chinese UI terminology and the colored ASCII aesthetic. Retain original module images and readable text; unlock spoiler images with their clues. Ruff targets 120-character lines and checks imports, modernization, and bugs; its configuration permits Chinese punctuation. Keep Textual styles in `.tcss` files. Write concise, professional Chinese UI copy: state the action, status or outcome directly; avoid chatty phrasing, personified loading messages, redundant instructions and generic requests to rephrase after technical errors. Put detailed rules in help, and avoid internal agent names, marketing claims, or tactical coaching. Preserve the narrative voice in story text and NPC dialogue.
+
+## Testing Guidelines
+
+Use pytest and pytest-asyncio (automatic async mode). Name files `test_<area>.py` and functions `test_<behavior>`. Use scripted agents, `FakeDice`, recordings, and temporary directories. BCDice tests skip without its Node bridge. No numeric coverage threshold; add regression tests for behavior changes.
+
+## Commit & Pull Request Guidelines
+
+Use focused commits with concise Chinese messages, optionally prefixed by an area such as `地图：`. PRs must describe behavior changes, linked issues, and validation. Include screenshots for UI/artwork changes. Document changes to commands, configuration, and module formats.
+
+## Configuration & Local Data
+
+Keep API keys in environment variables or ignored `.env` files. User configuration lives in `~/.config/autokeeper/config.toml`. Keep game data, imported copyrighted material, and generated module skills in their ignored locations: `data/` (layout in `paths.py`), `modules/local/`, `modules/inbox/`, every module's `source/`, `dev/output/`, and `skills/module-*`.

autokeeper-0.0.3/CHANGELOG.md

@@ -0,0 +1,294 @@
+# Changelog
+
+## 0.0.3（2026-10-20）
+
+### 游玩与排查
+
+- 在场的人抢先介入（拦住、喝止、提醒、递上要用的东西）在裁定之前演出：守秘人安排里 `first: true` 的那一位先开口、先动手，裁定员和掷骰按变了的局面来。原来先结算了调查员碰齿轮，守钟人才说「别碰」。
+- 被守秘人安排主动开口的 NPC，这一轮只是不再另调模型做幕后决定，写明时间和结果的固定日程照常执行。原来连日程也停了：玩家等两小时，NPC 半小时后的约会也没去。
+- `eval rhetoric` 改走新流程：玩家的话先经守秘人安排，再交裁定员（安排失败时才退回旧的意图解析），和游玩时一样。旧的 7/40、2/40 是旧流程的结果。
+- 每一轮先由守秘人统一安排（`Cast.plan`，用守秘人的模型、单独的 `plan` 会话，计费和评测里记作 plan）：它看着底牌和幕后简报，把玩家的话整理成行动，交给裁定员的行动和原来一样；摘要只用玩家说过的叫法和场景里的名字。安排调用失败或交回的格式不对，退回原来的意图解析。
+- 在场的人可以主动开口、帮忙或阻拦：守秘人在安排里点名（最多两人，只限此地活着的模组人物），他们用自己的资料和口吻演出来，当场交东西、走开、同行照常落地；这一轮幕后推演不再为他们另做决定。
+- 守秘人安排之前可以先查一件事（`lookup`，比如「托马斯知道日记的哪些事」「杰弗逊最近在哪」）：程序从世界记录里找出被点名的人此刻在哪、知道和经历过什么，以及相关的事实和事件（带着本局的改写），有模组原文索引时也查原文，答完再问一次，每轮最多查两次。查询结果只给守秘人看。用的是一个 JSON 字段，不依赖哪家模型的函数调用。
+
+- 修复用 Claude 时重要 NPC 的幕后决定全部失败：Claude Code 不接受带 `discriminator` 的 JSON schema，现在发给它之前去掉，回复照旧按完整 schema 校验。
+- NPC 说完就走时，守秘人的报告里写明他走了、去了哪；幕后简报写出在场的人身上带着什么；行动缺的工具只在报告里说一次；枪支、弹药、炸药不能当成日常物件当场拿出来。
+- 编译补写读完整资料：人物补全、各人的打算、编译审阅不再读截短的摘要，每个地点的守秘人须知、每条线索的原文、检定和前置条件、NPC 的交涉门槛都在，本机有原文的一并读原文。补写按依赖分批，写打算时读的是刚补好的人物认知和动机。
+- 补写不能绕过原作的条件：见面反应、人物知道的事、伏笔点出了要检定才找到的线索（比如托马斯「顺手指出那本日记」），或一步拿调查员的进展当成 NPC 已经知道（`has_liquor`、`learned_telescope`），写入前就查出来，带着原因重问一次，还不对就不写。全部补完再对照原文复核一次（`upgrade --only verify` 可单独跑），`autokeeper check` 也报这两类问题。
+- 打算的每一步可以写 `only_if`（条件语法写不出的实际依据，人物读到「只在……时才这样」）、`ruling`（要守秘人裁定后才发生的结果，只出现在守秘人的幕后简报里，不给人物当成见面就做）、`once`（见面反应只做一次，或一贯如此、碰上了才带出）和 `source`（原作依据）；人物补全的口头禅写成偶尔带出。条件里可以写 `knows:players:clue:线索id`（线索找到以后）。
+- 规则清单（`mechanics`）写明谁执行（`runs`：核心规则、插件、守秘人）；要守秘人执行的规则进了守秘人的底牌，不再只给导演看。编译出的 Skill 包多了 `references/situation.md`（人物关系、打算与条件、伏笔、前史、规则清单），`SKILL.md` 列出每条规则由谁执行。
+- 守秘人两次都没交出场面（scene）时，不再照样显示正文：先要它补上场面，还没有就按记录原样定下场面，守秘人只照它写正文。原来会显示「守钟人跟着你走」，同行记录却是空的。
+- 同一栋房子（同一处地方）里的房间之间走动不用等路程：交谈的工夫托马斯就能从书房过来，和调查员自己走进书房一样；跨地点赶路照旧按路程。
+- 原文检索后面附上本局每一处改写过的设定，各一条，写原来是什么、现在的全文；原来只附最近八次、截到 160 字，早改过的真相会被挤掉。
+- 编译补写不再替检定把结果交出去：《追书人》托马斯被问到丢书时只领人看书架的空档，不再「顺手指出那本日记」（原作要侦查才找到，孤注一掷成功时他才帮忙指位置）；他知道日记在书房、不知道放在哪。杰弗逊要调查员当面把酒递给他才松口，只是买到酒不算；斯坦利要有人报告或亲眼看到调查员在查望远镜才抓人，调查员自己知道不算他知道。
+- NPC 见面时要做的事（应门、安顿行李）做过一次就算完成（回应里的 `played`），不再每次交谈都重新塞给它。
+- 守秘人的幕后简报带上这个地点完整的守秘人须知，不再截到 400 字；改写过任何一条设定后，原文检索照常可用，改写过的条目附在后面、以改写为准（原来一处改写就整个关掉）。
+- 守秘人先交场面快照再讲：每段叙述先写讲完时谁在场、谁跟着调查员、东西到了谁手里、拿出来的日常物件、留下的痕迹和眼下在进行的事，程序核对后记进世界记录，通过了才边写边显示叙述。有人离开要写去向，NPC 来去按这一轮过去的时间算路程，调查员只在同一处的房间之间走动；不通过就带着原因重写一次，再不通过只记下能成立的部分，守秘人照着写，做不成的写成尝试。叙述停下时在做的事重新带进下一轮。中断后恢复直接用已写好的叙述，不再重问。
+- 一条命令安装：`uv tool install autokeeper`（或 `pipx install autokeeper`；发布到 PyPI 之前用 `uv tool install git+https://github.com/satoshinji2992/autokeeper`），装好后在任意目录输入 `autokeeper` 就能玩。安装包带着三本自带模组（不含原文 `source/`）、共用 Skills 和掷骰脚本；存档、设置和缓存放进用户目录（Linux、macOS 按 XDG：`~/.local/share/autokeeper`、`~/.config/autokeeper`、`~/.cache/autokeeper`；Windows 是 `%LOCALAPPDATA%`、`%APPDATA%`）。第一次运行自动把掷骰组件的 npm 依赖装进用户目录，没有 Node.js 时说清楚缺什么，新玩家先选模型。从源码目录 `uv run autokeeper` 和 `AUTOKEEPER_HOME` 照旧。`check`、`compile`、`host` 接受模组 id（如 `zhuishuren`）。Claude 的 SDK 改成默认依赖，`[claude]` 留作空的别名。
+- 以前从源码目录玩的存档不丢：源码目录写存档时记下位置，装好的命令第一次运行时把存档、角色卡、导入的模组和慢的缓存复制过来（不移动、不覆盖）；`autokeeper migrate <目录>` 随时再带一次。0.0.3 测试版一键脚本留在 `~/.local/share/autokeeper` 的代码目录会挪到 `autokeeper-old-install`，存档同样复制过来。
+- 一键脚本只做两件事：没有 uv 先装 uv，再 `uv tool install autokeeper` 和 `autokeeper setup`（PyPI 上还没有时从 GitHub 装）；任何一步失败都停下并说明原因，不再吞掉更新失败后照样显示「装好了」。`autokeeper login` 选模型、存 Key（`.env` 只有自己能读）；选了 DeepSeek 而游戏设置里还留着统一的 Claude 模型时，清掉它，切换真正生效；环境变量 `AUTOKEEPER_MODEL`、`AUTOKEEPER_PRESET` 或 `config.toml` 的 `[roles.*]` 盖过选择时，明确说是哪一条，不再显示成功（`doctor` 也会提示）。运行时依赖补上 `skills-ref`，装成命令后不再缺包。
+- 守秘人看得到底牌：模组的真相、怎么跑、前史、结论和结局常驻；每段叙述另带一份当场的幕后简报（此地藏着什么、在场和隔壁房间的人的秘密和打算、这里还没找到的东西、接下来会发生的事、改写过的设定），从世界记录取，不进记忆和存档；改写过的真相、结论和前史按当前全文附上，以它为准。《追书人》真人存档重放（DeepSeek flash）里，说漏秘密 0 处，凭空多出的细节从和真相矛盾的假线索变成了和真相一致的伏笔。
+- 叙述照写照显示，边写边出：不再在显示前核对、删句或换成一句「你在某处，几点」（`check` 配置项去掉）。NPC 的台词也不再按字符比对秘密、重问或删句，NPC 只拿得到自己那一份资料。NPC 的回应做不到时（交出不在手上的东西、去不了的地方），带着具体原因重说，最多两次；还做不到，话照说，做不到的事不落地，守秘人在这一轮的叙述里交代实际情况。
+- 裁定员因为条件变了（带来手电给了奖励骰、换了难度）让再掷一次时，引擎不再硬判成重复检定；条件没变的原样重掷照旧不掷。
+- 导演即兴不再因为多了一个普通路人就整份打回：新人物、地点、线索的数量只设防失控的上限，「方案要小」交给提示词。
+- 检定失败就是没拿到：不再在第二次失败或孤注一掷失败后自动送出关键线索，也不再固定加 20 分钟。模组写明失败也能发现、或失败另有后果的照写结算（标记、耽搁、受伤都真正记上）；孤注一掷前，弹窗先写明再失败会怎样。守秘人会知道这次没拿到什么、发生了什么，照实讲失败，之后可以另给机会。
+- 开局演出：新开一局先整屏播放几幕图配字，介绍故事背景，图缓慢移动、字幕逐字出现；演出期间导演在后台改编模组，两样都完成后进入游戏，守秘人马上开讲。演出在编译时写好（改编步骤「开局演出」），只用开局就能公开的图和玩家知道的内容；联机时一起看、一起进入游戏。
+- 输入框增加角色行动／对 KP 说明两种模式，保留草稿与排队消息的原始模式。浏览器支持单独按 Alt 切换，终端可用 Alt+M；KP 说明不交给行动解析器，不进行检定、推进时间或占用联机行动名额。
+- 普通行动解析也读取最近经过和实际持有物，结合上文理解“去看看”等省略表达；明确目的地优先于沿途出口，只有明确要求沿途停留时才逐段行进。取消裁定前另写的一句动作旁白，避免补出未声明的动作或工具。
+- NPC 同行由角色确认并写入世界记录，出发时实际更新位置，到达约定目的地后结束同行。出发前的交谈按顺序完成，私下交谈不记入旁观 NPC 的记忆；中断可接续，拒绝同行时等待玩家决定是否独行。
+- 同行的 NPC 跟着调查员绕路，到约定地点才结束同行；被邀请却没跟来的人，叙述会知道他不在。到点的安排不会把正在同行的 NPC 拽走。玩家说「先去书房再去公墓」时先去书房，不再被后面提到的地点覆盖。
+- 心理学观察不再自动变成 NPC 交谈，也不能绕过其他社交门槛取得口供；交涉结果限于当前请求，已获授权的信息跨回合保留。叙述持续读取当前人物与物品状态，关键线索的时间代价不再附带未结算的惩罚。
+- NPC 对话与交谈记忆使用实际台词和可观察动作，不再直接读取含有“隐瞒”“假装”等私下意图的行动摘要。
+- 统一导演对未公开设定的改写规则：经世界记录校验后才能修改，不能用新增旁白覆盖；冲突依据人物目标与既有因果展开，现有规则能处理的场面不再另造插件。
+
+- 修复人物卡、骰子和线索预览挤占右栏的问题，为“经过／进展／背景”保留阅读空间；较矮窗口自动压缩预览，完整资料仍可展开查看。
+- 普通交谈不再追加旁白复述台词。同期发生新事件时只补充变化，检定与线索卡保留；纯对话回合也能正常显示教学提示和切换人物立绘。
+- `.ra`、`.rab`、`.rap2`、`.rc` 等检定命令支持 Tab 补全与切换技能，Shift+Tab 反向切换，保留奖励骰、惩罚骰与难度。
+- 在场的重要 NPC 也会根据计划、约定和亲历事件决定行动；有目标却没有安排时会开始考虑下一步，与幕后人物共用原有调用预算。公开行动增加线索权限检查。
+- 修复异地 NPC 将事件标为 `public` 后泄露给调查员的问题：当地公开不等于调查员获知；人物离开或到达时也不自动交代未被观察到的目的地或来处。
+- 开发者模式改为本机私有网页：F12、`/dev` 或 Esc 菜单打开，终端继续游玩。完整模型与任务记录按存档持续保存，独立 AI 可按历史回合、人物或指定记录排查；浏览不调用模型，诊断不改变剧情。详见 `docs/developer-mode.md`。
+- 当前行动依赖的导演方案与首图就绪前显示“KP 正在构思…”，模组补丁、幕后操作与插件整批校验提交，中断后重试不重复创建方案或掷骰。方案没通过检查会重写，首图画两次不成就先上场景、图在后台继续画；最多等 5 分钟，仍没有能用的方案就照常结算，不再停在 /retry。这一局图像次数或预算用完后，新场景不再等图（以前会一直卡住）。
+- 结算细分恢复阶段，保留已返回骰值、行动耗时、幸运与理智损失、线索及事件结果；孤注一掷、插件和 MCP 对话中断后可从原操作继续，避免重复结算。
+- NPC 表演复用普通对话的信息与动作校验，不再接收全局玩家私语、线索和摘要。
+- 重要 NPC 的自主决定挪到回合讲完之后：玩家读叙述的时候他们在想，做了什么在插曲或下一段叙述里出现。拿一局真人存档重放，玩家每轮要等的模型时间从约 22 秒降到约 7 秒（以前每轮两次决定、12.8 秒，多数决定是「再等等」）。
+- 行动解析知道同一栋房子别的房间里有谁（托马斯在书房），玩家在客厅说「去问托马斯」会走进书房，不再当成家里没人。
+- `eval session` 的报告里，幕后（world）的调用数标成「不可比」，另给整段重放里不重复的（人物，唤醒原因）有几种：单轮重放每轮从原存档起跑，同一个 NPC 每轮都会被重新叫醒一次。
+- 重放评测的核对规则：叙述交代了来处的日常物件（谁递给调查员的、他在哪儿顺手拿起的），NPC 拿出、递出自己的日常物件，都不再算物品矛盾。
+- 新命令 `autokeeper eval session <存档>`：拿一局真人存档逐轮重放，每一轮从当时的局面、用玩家原话和当时的骰子跑现在的流程，由核对模型对照世界记录挑出叙述里的矛盾（人在不在、谁跟着、东西在谁手里、有没有凭空多出的物证），和当时比；`eval rejudge` 换了核对规则后重新核对，不必重放。
+
+### 世界
+
+- 模组给了打算、但没标成重要人物的 NPC（比如《追书人》的杰弗逊、奥黛尔）只按写明了时间或条件、也写明了结果的固定步骤行事，不再被当成幕后人物叫醒做判断（`Agent.passive`，旧存档读入时补上）；导演把他提成重要人物以后照常唤醒。
+- 日常物件当场登记：守秘人递过来的手电、NPC 从壁炉边拿起的拨火棍、调查员在屋里拿起的手杖，都记进世界记录，拿到的人随身物品里就有，后面几轮接得上。名字和本模组的线索、手稿、重要物件重名的不能这样登记；这一轮行动缺的工具（裁定员写进 `missing`）这一轮谁也拿不出来。
+- NPC 说了就做：台词里说完就走、当场拿出或递出东西，和台词同一轮落地，经它自己的世界接口校验；做不到就带着原因重说，两次还不行话照说，做不到的事写进【未落实】交给守秘人交代。邀请同行时玩家顺带说了别的话，NPC 也必须回答同不同行，不再出现嘴上「我陪您去」、人却没跟上。
+- 排着队等 KP 演出的 NPC 行动记着当初凭什么决定：看见的人和东西、知道的事、计划这一步的条件。轮到它时这些变了，就作废，让这个 NPC 按眼下的局面重新决定，不再照旧执行。
+- 重要 NPC 的幕后决定改成集中想：同一段时间里被叫醒的人合成一次调用，各人只看自己那一份资料，决定的依据只能引用自己那一段。和调查员的当面对话不再马上叫醒幕后决定（NPC 当场已经回应），等调查员离开或时间跳过，再想要不要改计划；没有接下来安排的人只在时间跳过或换地方时想下一步。上次没做成的，下次带着具体原因再想。
+- NPC 打算里「见面时的反应」（应门招呼、领人去看、被问到时怎么说）单独标出来，不再在幕后一遍遍叫醒人物，改成调查员在场时交给 NPC 自己演。`autokeeper upgrade` 多一步「见面反应」，给已有模组没标的步骤补上标签。
+- 关键改变不再排队等导演审：有人死了、重要物件换了手、引出结局的标记，校验过就落地。过夜、赶路这样的时间跳过以后，导演看一眼局面，做一两处幕后调整。
+- 原作路线中断不再被程序否决：证人死亡、证据毁坏或失去调查机会都可以发生；导演可以在后续即兴中建立有来源的新线索和路线，也可以让调查以失败或代价收束。编译期推演只用于找模组结构的薄弱处。
+- 明确恐怖跑团的失败空间：按模组原有危险程度与人物动机安排恐怖和理智风险，允许死亡、疯狂及全灭，但不以此为目标；入门模组不额外升级为追杀或高致死剧情。KP 如实呈现规则后果，不自动抹去损失，也不为指定惨剧篡改裁定。
+- 编译期加「前史」：开局以前发生过、至今还在起作用的几件事，开局时变成幕后的旧事件，知情的 NPC 记得，导演看得到也能改写，玩家不知道。
+- 打算和计划的条件可以写时段（`hour:22-6`，可以跨过午夜），原作里「只在夜里出来」「白天在诊所」这类时间习惯能直接写进去，运行和推演都认。
+- 重要 NPC 的打算可以写每一步做成后的结果（`does`：去哪、东西给谁、立哪个标记、谁不见了），到时直接照做、不用模型；立起的标记照常触发事件和结局，时钟走完游戏也会结束。检查和编译时多一遍「没人插手时」的推演：各人的打算按时间走三天，报出哪一步之后某条结论再也拿不到线索，线索网对着这些断点补路。
+- 台前与幕后分开：调查员不在场的事直接发生；会改变眼前场面的事（有人进出、同行的人要走、对调查员动手）排成一段待演的戏，由 KP 在合适的时候上演并当场讲出来。正在和调查员说话的人不会话说到一半起身就走，同行中的人只有当面结束同行才会离开。
+- 世界引擎接进了游玩。每局有一份自己的世界记录：谁在哪、谁知道什么、谁答应过谁、各人心里的打算。裁定、NPC 对话里的转交和约定、导演的即兴都记在里面，读档照旧。
+- 重要 NPC 会自己过日子：调查员走了，他们照自己的打算行动，想想刚才的谈话，去别处，答应别人的事到点去做。每回合最多想两次，长时间跳过（赶路、过夜）四次，配置里 `minds` 可以改，0 只照已经定好的计划走。
+- 调查员回到一个地方，守秘人会知道此刻谁在、他们不在时留下了什么痕迹；在眼前发生的事（有人走进来、约好的事到点了）当回合讲出来。
+- NPC 开口时记得自己的事：想要什么、正打算做什么、记得哪些、对谁什么看法、答应过别人什么。
+- 导演可以在幕后改写设定、让 NPC 有自己的计划、安排到点才发生的事。先在一份副本上试，不合规矩的退回去改。玩家见过、听过的事也能为阴谋或剧情改出另一个真相（有人撒谎、记错、伪造、设局），只要自圆其说：玩家当初的所见所闻原样留着，改写要写清他们为什么会看到、听到那样，再过一次模型检查，说不通或者没能核对就不落地。玩家手里线索的原文不会变，改写也不挪人、不改同行和持有。导演提示里鼓励主动改，让跑团更顺、冲突更有戏。
+- 叙述里叫出一个人的名字，不再被当成和他有关的秘密都已经揭示。
+- 公开知识保留明确来源，地址或零散片段不再揭示整段真相；旧版无来源标记进入待核验状态。私聊不会自动进入旁观 NPC 的知识。
+- 世界推演使用独立 `roles.world`，默认继承裁定模型；不同地点的 NPC 并行构思，按权限查询或预演，再根据读取版本依次提交。内部工具与 MCP 共用同一套查询、预演和原子提交接口。
+- 人物可有意说谎、假答应或隐瞒。声称、真实意图与实际行动分开保存，听者不能从后台真假标记识破；普通执行失败也不能事后伪装成欺骗。
+- 调查员和 NPC 的重要装备支持后台携带、穿戴、藏匿、余量与状况记录，不增加常驻面板或日常杂物账本；发现与出示后才公开隐藏物品。
+- NPC 根据当前交谈、目标和未兑现约定召回权限内的相关旧事。内部维护检查将跨层不一致写入开发者记录，不自动改写历史或纠正角色谎言。
+- 重要消息可在零分钟交谈后唤醒相关 NPC，普通问候只保留记忆；对话与时间推进共用本轮预算。并行已完成结果及调用预留随存档保留，取消后重新验版本，不重复已完成决策。
+- 对话源事件保存完整的授权原话，不再截去长回答后半的托付或约定；检索仍按角色权限选择资料，私下打算不写进旁观者记忆。
+- 导演与 NPC 可以基于人物动机主动设局、报复、操纵、背叛或失控；角色台词、私有打算和实际冲突结果分开处理，旁白充分呈现已经成立的恐怖后果。
+
+### 模型调用
+
+- 裁定员重新只看解析后的行动，不看玩家的原话（之前的版本把原话也给了裁定员）。DeepSeek 上做修辞诱导对照：看原话时 40 次里有 7 次被说动，多给了奖励骰（「泥地还软着，清晨没人」）；不看原话时 2 次，都是模组本来就允许的（前巡警直接问警局）。为了不丢掉玩家真做了的防备，解析结果多了一项「防备」：屏住呼吸、捂住口鼻、戴上手套这类照原话保留，交给裁定员。
+
+- 裁定同时读取本轮原话与连续上下文，避免只依赖行动摘要；取消仅因重复动作或口头禅而触发的 NPC 措辞重试，保留信息与实际动作校验。
+- 增加可配置的整次输入字符预算与上下文分项追踪。超限时最多压缩一次，失败保留原文；直接调用、摘要和格式修复同样执行检查，预算拒绝不触发备用模型或熔断。
+- 用 DeepSeek 时，NPC 的台词不再开 JSON 模式：以前大约五句里有一句只回一串空格，要多花一次调用去修。现在直接说出来的话就当台词收下。
+- 用 DeepSeek 时美术不再开思考：开着时一张字符画 5 分钟都画不完，试玩里 11 张全部超时；关掉一张 8 秒。
+
+### 模组编译
+
+- 计划的一步可以写「到点而且条件成立」：`D1 22:00 & flag:bell_stopped`。编译器原来把时间和条件连写的步骤砍成只剩时间，前提丢了，钟没停 NPC 也照样走；现在原样保留，写法确实不支持的退回重写，不再删条件。自带模组里被砍掉的两处已补回（詹森收尸要麦克迪已死；托马斯建议监视要调查员还没在监视）。
+- 规则清单进入复核，对照原文查冲突和编造。《追书人》的规则清单按原文改正：锁窗后人影撞窗进来（不是进不来、不再回来）；守夜是每晚一次幸运检定；隧道、食尸鬼群、喊出名字、随他下到地底、陵墓恶臭、最后一晚都照原文写，去掉编出来的遭遇表和检定。
+- 按关键词找出的「可能提前交出线索」只是提醒：交给读过原文的模型判断，确实绕过才删，「不指出日记」不会再被当成交出日记。满足了前置标记也不再当成已经过了检定。
+- 导入中途断了，同一个文件再导一次会接着做：原文不再重新提取，导入 Agent 读自己上次的笔记和半成品草稿接着写，不从头重读；校验、编译各步做完都记下来。`--fresh` 从头来。生成原创模组同样。
+- 编译期改编：导入模组时（或对已有模组跑 `autokeeper upgrade`）补上跑团用得着、原文没写的东西：缺的人物性格和口吻、人物之间的关系、重要 NPC 没人插手时会做的事、早早能露出来的伏笔、每个结论凑够三条线索、能接上调查员背景的线头、玩家很可能走到的额外结局、要插件来管的规则清单。只补没有的，原作的真相、线索原文、检定和结局不改；补完让校验不过的那一步整步撤掉；中途断了再跑一次就接着补。
+- 这些在游戏里用得上：人物关系开局就在世界记录里，各人的打算自己运转，伏笔在到达那个地方时交给守秘人，线头交给导演开局改编时挑。
+- 推演：`check` 和 `upgrade` 不用模型、不用 AI 试玩，在模组结构上把所有能走的路一起走一遍，一秒内报出走不到的地点、拿不到的线索、到不了的结局、线索不到三条或只靠一处的结论。在自带模组上查出《追书人》的“未解之谜”结局条件写成了一句话，游戏里不会触发，现在由「道格拉斯带着书逃回墓地」这个标记触发。
+- `upgrade` 打一个可玩度分（只看模组结构和推演，不调用模型）；`--review` 请模型像守秘人那样通读一遍（一次调用），列出跑起来会出问题的地方。
+- 三个自带模组的介绍改成同一种写法：年份、地方、人数（「1-2 人」）、时长（「约 2-4 小时」）、出处。玩家看得到的名字不再剧透：《冬雪之下》的“埃里”去掉引号，叫埃里·赫琴斯；《追书人》的食尸鬼隧道网改叫地底隧道网；《有些人油盐不进》的线索「崩溃者的胡话」改叫「路人的胡话」。
+- 修复《有些人油盐不进》开局地图上就有「望远镜」：副标题原来是「斯托威尔镇的望远镜」，而望远镜是温室天文台的别名，开局就算听说过、可以直接去。副标题改为「斯托威尔镇的怪事」；`check` 现在会提示标题、副标题、缘起或地点说明里点名的秘密地点。
+
+### 画面
+
+- 场景图左下角用小椭圆像显示调查员见过、此刻在这里的人（最多 3 个）；有人进来、离开、第一次搭上话，跟着变。没见过的人不露脸。
+- 修复读档预览图因滚动条改变可用宽度而逐行折返、形成横条的问题，窗口缩放后按新宽度重绘。
+- 即兴配图优先取得正式图片后再转成彩色字符画，取消通用简笔占位与先画粗 ASCII 再换图的过程；仅在图片获取和生成均未成功时绘制字符插图，场景、肖像与物件分别约束构图。
+- 一个地点可以有好几张图：室内、某样东西的近景、夜景。查看那样东西时换成那张，入夜换夜景。
+- 他们不在时这里被翻动过、NPC 受了伤，本机有 Codex 时照原图重画。
+- 线索卡上可以配那样东西的照片，事件发生的那一刻可以有自己的图。
+
+## 0.0.2（2026-10-19）
+
+旧存档不再读取。自己的调查员、本地模型和知识库会自动搬到新位置。
+
+### 联机
+
+- 标题画面就能开房间和加入房间，不用再开命令行。开房间时选模组、定每个座位是玩家、AI 还是空着，填名字，勾不勾网页版；端口被占了会自动换一个。
+- 准备房间：每个座位写着调查员和坐在上面的人，右边是人物卡；房间栏只有一句要发给朋友的地址。连不上、网页打不开、版本不同这些情况，统一放在「遇到问题」页，出错时只提示一句话。
+- 每个人可以用自己的角色：自己存的卡、模组预设，或者当场车一张。车卡用的是房主的模型，朋友那边不用配置。带来的卡由房主检查，HP、MP、SAN 按规则重算。大家按 Y 准备好了才开局。
+- 每一轮有个行动池：大家各说一件事，先后不限，另外空着的一个位置谁先说归谁。守秘人讲的时候也可以打字，这些话排到下一轮最前面，不会丢。/undo 撤回。
+- 顶栏和输入框上方写着轮到谁、守秘人在讲谁的行动；故事里调查员的名字高亮。
+- 网页版换成暗色页面和中文等宽字体，打开就能打字；通过 Radmin 等虚拟局域网打开也能连上。
+- 修了联机地图：以前朋友那边和房主看到的地图不一样，还会收到没发现的暗道。
+- 房主自己用 `join 127.0.0.1` 进来时算房主，可以换模型；一个回合出错时，所有人都看得到，由那位玩家 /retry 接着讲。
+
+### 游戏界面
+
+- 按 Esc 打开菜单：继续、存档、读档、设置、叙事偏好、规则插件、换模型、新手指南、按键说明、回到标题、退出。守秘人还没讲完时离开会先问一句。
+- 继续调查改成存档管理：每个存档写着模组、调查员、游戏里的时间和地点、第几轮、上次玩的时间，右边预览；可以改名、复制、删除，删除的进回收文件夹。
+- 角色卡管理：我的角色、存档里的、模组预设三组；可以新建（AI 协助车卡或导入已有的卡）、编辑名字和背景等文字、复制、导出，或者直接用它开新游戏。数值不能改。
+- 右栏分三页：经过（每次行动一行，点一下跳到那里）、进展（故事至今，有新进展才重写，两次至少隔 6 轮）、背景。
+- 人物卡（F4）显示完整背景故事和「本局经历」：做过的事、检定、找到的线索、理智和伤害。
+- 地图一定画成图，放不下就可以拖动。地点里面还有地方的可以展开，比如公墓里的陵墓；选中一个地点会写出在那里看到的、见过的人、找到的线索和路程，按 G 在输入框里写好「我去…」。
+- 单人游戏里，守秘人讲的时候可以先打字回车，讲完自动交上。
+- 修了人物卡在窄面板里照片变成灰色条纹的问题。
+
+### 骰子
+
+- 骰子换成 3D 十面骰：物理模拟决定点数，骰子区回放的就是这一次投掷；停下后算数的那几颗顶面数字变黄。有骨白、黑曜石、血珀、黄铜、青石、磷光六种皮肤。
+- 用固定种子各掷 5000 次检验过，每一面出现的次数没有明显偏差。伤害、理智损失和 `.r` 这类其他骰子仍是普通随机。
+
+### 规则插件
+
+- `Ctrl+K`（或 Esc 菜单里的「规则插件」）列出每条规则管什么、能尝试什么、当前状态、最近的效果和暂停原因。
+- 可以用一句话加家规，测试在沙箱里跑通才装进这一局。联机时只有房主能加。
+- 插件可以在右栏放面板、放几秒演出、给玩家出小游戏（选择、填空、排序、棋盘），也可以设计时、给东西、提醒守秘人、注册 /命令。《追书人》带了一个示例：书房的旧书架。
+- 沙箱加了一层语法检查和一个运行时审计钩子，拦掉文件、网络、子进程和导入。
+
+### 叙述
+
+- 导演在同一地点三轮内最多展开一次，拿上一局重放算，展开次数从 30 降到 14。
+- 用 Claude 扮演的 NPC 开口如果又先写动作或重复口头禅，会重说一次。
+- 新增 `eval style --npc` 和 `eval blind`，用鲁迅和老舍的文字作为对照。
+
+### 画面、模组和文件
+
+- AI 画图：本机装了 Codex 并登录时，地点和人物随剧情明显变样（失火、被淹、受伤、死去），由 Codex 内置的 image_gen 照原图重画，存档记住，联机同步；即兴内容和导入时找不到照片的也由它照描述画。模组可以在地点和 NPC 上写 `looks`。每个模组最多 100 张、每局 12 张；设置里「AI 画图」可以关，用不了时只写一句原因，怎么处理在玩法说明的「遇到问题」页，`doctor` 也会报告。一张约 40 秒，输入 7.6k–32.5k token。
+- 大场景：开场、突发、危机、关键地点、怪物、最终 boss 和结局时整屏放一张大图，标题压在底部，叙述照常在后面进行，任意键、点击或 8 秒后收起，掷骰时让路。模组里写 `showcases`（导入时由导入 Agent 写，自带三本模组手写了 11–14 个），导演即兴每局最多加三个。图先用模组原图，有 Codex 就照参考图或描述生成，计入每个模组 100 张；后台一张一张提前准备，到点没好就跳过。`autokeeper showcase <模组>` 提前准备，设置里可以单独关。
+- 文件位置：游戏写的东西从 `saves/` 搬到 `data/`，分成存档（`games/`）、自己的调查员（`cards/`）、可以删的缓存（`cache/`）和记录（`logs/`）；评测和自动跑团的输出放到 `dev/output/`。第一次启动时，本地模型、知识库、大场景图和调查员自动从 `saves/` 挪过来，旧存档不再读取。
+- 模组目录：`module.yaml` 拆成 `module.yaml`、`places.yaml`、`people.yaml`、`clues.yaml`、`story.yaml`；图按用途放进 `art/places/`、`art/people/`、`art/items/`、`art/ascii/`，来源和授权合成一个 `art/credits.yaml`，不再有每张图一个 `.credit.json` 和重复的 `CREDITS.md`。渲染用的预处理副本（`.prep.png`）移到 `data/cache/pictures/`，用到时生成。只有一个 `module.yaml` 的小模组照样能读。导入的原文和笔记放在 `modules/local/<id>/source/`，要导入的文件可以放进 `modules/inbox/`。三本自带模组已转换，内容不变。
+- 自带模组标出重要 NPC（《追书人》托马斯、道格拉斯；《冬雪之下》安特医生、卡洛琳、“埃里”；《有些人油盐不进》哈特教授、斯坦利副警长、菲茨杰拉德牧师、弗雷迪·詹森），并加了两处变样图：《追书人》陵墓被打开、《有些人油盐不进》混沌黎明后的大街。
+- 模组的 Skill 包过期就重新编译：以前只在没有 SKILL.md 时才编译，改了 module.yaml、插件或编译器后用的还是旧包。
+
+### 其他
+
+- 标题画面和游戏空闲时几乎不占 CPU（标题 58% → 4%，开天气的游戏 55% → 11%），回合快了一倍；立绘相关的测试不再偶尔失败。
+- 修了理智规则：一天内失去五分之一理智的计数从来没有开始过，「不定性疯狂」不会发生。现在开局时开始计，每过一天重新计。
+- 世界引擎的第一部分（`src/autokeeper/world/`）：世界记录、世界操作、NPC 自己做决定和按游戏时间调度。还没接进游玩，设计见 `docs/world.md`。
+
+## 0.0.1（2026-10-18）
+
+第一个公开版本。
+
+- 中文《克苏鲁的呼唤》第 7 版跑团：AI 守秘人、裁定员、导演和 NPC，骰子和状态由程序结算；可以单人、带 AI 同伴、局域网联机或观战。
+- 自带三本模组：入门的《追书人》，以及《冬雪之下》《有些人油盐不进》（同人改编，不含原模组文字和图片）。可以导入 PDF、Word、Markdown、文本和 ZIP 模组，也能从一句设定生成原创模组。
+- 支持 Claude、Codex、DeepSeek 和 Ollama（可完全离线）；按角色分配模型，有用量记录和预算上限。
+- 标题画面：Dominique Signoret 的 *Cthulhu and R'lyeh*（CC BY-SA 3.0）铺满整屏，压暗做背景，海浪和触须摆动，偶尔打闪；名字、标语和半透明菜单叠在上面。没装 chafa 时显示原来的手绘眼睛。
+- 标题菜单加「角色卡」：翻看保存的调查员、每个存档里自己的调查员（同一人只留最新一次）和各模组的预设调查员，右边显示整张卡。
+- 头像不再去背景：老照片上抠图会在脸上挖洞、切掉肩膀，所有头像重新生成；删掉在 OpenCV 5 下不起作用的人脸裁切和 rembg 依赖。自带模组里三张只裁到画布的头像重新裁过。
+- 终端颜色：识别支持真彩的终端（Windows Terminal、VS Code、iTerm、WezTerm、kitty 等），其他终端由 chafa 抖动到 240 色，不再被压成 16 色主题色（深蓝、青绿）。`AUTOKEEPER_TRUECOLOR=0/1` 可以手动指定。
+- 选模组预览在没装 chafa 时显示手绘图（修 macOS CI）。
+- `autokeeper --version` 显示版本号。
+- 右栏下方分成三页，Ctrl+G 或点页签切换：经过（每一步的行动、检定和线索）、进展（故事至今：有新进展时——新线索或手稿、第一次到的地方、第一次见的人、剧情转折、明显的理智或伤势损失、过了一大段时间或新的一天——在后台用最便宜的模型整理一次，两次至少隔 6 轮，结局时一定补一次，15 轮没有新进展也补一次；只拿玩家看到过的叙述、行动、对话、线索和手稿，悄悄更新，页签显示「进展·新」，Ctrl+Y 可以现在整理，每轮一次；存进存档，联机时随同步发给每个人）、背景（模组的缘起、开场原话、你的调查员是谁）。右栏放不下时这三页盖在故事上打开。人物卡（F4、标题页的角色卡）按纸卡分组列出全部背景，游戏里多一节本局经历：做过的事和检定、找到的线索、受伤和理智损失、答应过的事和关系。
+
+## 发布前的开发记录
+
+下面是公开发布前的内部版本，版本号和发布版无关。
+
+### 0.4.0
+
+- 导演 Agent：模组没写到的地方由它即兴。开局按调查员背景改编模组、埋下冲突；动机正常的行动展开新人物、新线索、新地点和新结局；出格的行动先演一段再给相称的代价；卡关时送来线索。方案经模组校验后写进本局存档，原模组不动。`--improv 严格` 关闭。
+- NPC 有了角色弧光（`arc`），随剧情更新；关键线索检定失败也会到手，只是要付出代价；守秘人每轮收在悬念上，不对玩家说“不能”。
+- 局域网联机：`autokeeper host` 开房间，朋友用浏览器打开地址入座，装了 AutoKeeper 的人也可以 `autokeeper join`。每位调查员由玩家或 AI 扮演，按座位轮流行动；有人掉线时 AI 代打，回来后坐回原座位接着玩；全角括号开头的话是场外聊天。游戏、模型和存档都在房主那边，客户端拿到的模组去掉了真相、守秘人须知、NPC 的心思和还没找到的线索，状态里也没有 Agent 的记忆和导演的方案。
+- 对话立绘：NPC 开口时立绘站到场景右侧（Textual 的独立图层，场景和天气照常），名字写在下面，队伍离开、出了事、一轮没再开口或者两分钟没说话就退场；80×24 下缩小，场景太窄时不显示。表情差分不调模型：从 NPC 自己写的动作和台词里按词表读出七种情绪（jieba 分词，否定词取消，外貌里写明的习惯动作不算），照片换色调、手绘换配色，害怕时抖一下、发火时闪一下红；F6 一起关掉。《追书人》托马斯的照片重新裁成头肩像（以前只裁到一截袖子）。
+- 用量记录：Ctrl+B（或 /usage）看本局每个 Agent 的调用、输入、缓存命中、输出、耗时和花费，最近 40 回合每回合用了多少 token（一行小柱图），以及这台电脑上所有按量计费调用的估算总额和预算。存档里按回合记下用量；顶栏显示本局总 token 和花费。
+- NPC 说话更像人：去掉“每次 1–4 句、可以写一个动作”的硬性格式，改成先想清楚对眼前这人的态度和这件事碰到了哪根神经，情绪放在话里，篇幅跟着情绪走，带上自己的营生和心事，口头禅偶尔用；附一段和本局无关的示范。同样九个问题（《追书人》三个 NPC，DeepSeek）：平均长度 90 字 → 三轮 143 / 141 / 127 字；以动作开头的比例没有稳定下降（9/9 → 4/9、8/9、9/9）。评书腔只留给身份里写着说书的 NPC，导演让普通 NPC“登台”时演一段当场的戏，不再复述调查员一天做过的事（以前托马斯和守墓人会在 1920 年代的底特律说“列位看官”）。
+- 新手指南与提示：标题画面的“新手指南”和游戏里的 F1，14 页短文，从怎么说你要做什么讲到掷骰、孤注一掷、理智、线索、复盘和联机，最后一页是按键速查。第一次碰到掷骰、线索、手稿、NPC 开口、理智下降、HP 告急、守秘人即兴、几回合没进展这些事时，叙述之后多一行提示，每种只说一次，一回合最多一条；指南里能关，也可以写 `tips = false`。还没有存档时，“新的调查”把《追书人》标成新手教学并选好，开局给一句只用钩子里已知人物的提示。
+- AI 只看玩家看到的：AI 调查员（队友、自动跑团、联机 AI 座位）的局面描述改成玩家视角，去过和听说过的地方、见过的人、线索原文、最近的叙述；出口、没打过照面的人、守秘人的搜查清单都不给。行动解析器只拿到玩家知道的叫法。没人提过的地方不能靠报名字过去，只能从隔壁找进去（`fog.findable`）。F8 / /suggest 出三条主意（调查、社交、大胆或谨慎），只填进输入框；联机时由房主的 Hub 想，只发给本人。NPC 说话时显示外貌，不再显示写给守秘人的身份说明（《追书人》里道格拉斯那条写着“偷书贼”）。
+- 叙事偏好：标题菜单、游戏里 Ctrl+O 或 /prefs，选篇幅、恐怖浓度、节奏，勾上不想看到的内容（10 项）。只有固定选项，存在 saves/preferences.json；守秘人每轮当一次性附言收到（和知识库检索拼在一起，不进记录，不破坏缓存），导演即兴不碰雷区，NPC 说到时含糊带过。裁定员和行动解析器收到的提示词逐字节不变。守秘人提示里的反面清单改成正面说法，keeper-craft 加了两段示范叙事；`autokeeper eval cliche` / `eval style` 量套话密度，实测变化在噪声以内（见 docs）。
+- 重说与复盘：F9（或 /retell）请守秘人换个讲法重讲最新一段，可选短一点、更克制、多写细节、更阴森，只有固定选项；同一份报告重发，骰子、线索、NPC 台词和状态都不变，旧的那段先从守秘人记忆里删掉。结局后 F10（或 /debrief）复盘：真相、找到和漏掉的线索各在哪、每个 NPC 的目标和秘密、没走到的结局要怎样才能走到，不调模型；复盘里按 E 听后日谈，写一次存进存档。联机时入座的玩家也能请房主那边重讲，结局后 Hub 把完整模组发给所有人。
+- 检定交给守秘人：`.ra 侦查` 这类指令算作“想在这里用这个技能”，对着谁由场景和刚才的对话推断，掷不掷、多难、给不给奖励骰由裁定员决定，NPC 和叙事接着结果往下演。同样的尝试失败后不能重掷：裁定员看得到最近 5 轮的检定，引擎另有确定性的兜底。需要掷骰时弹窗说清技能、目标值、困难和极难的线和原因，玩家按回车或空格亲手掷（AI 同伴、自动跑团和回放照旧直接掷，回放不受影响）；结果卡片摊开十位骰、个位骰和奖励骰取了哪颗，下面紧跟这一掷带来了什么。`.st` 只能看不能改，理智检定由守秘人发起，`.en` 结局后每局一次，`.r` `.coc` 照常；输入框按 → 补全指令和技能名。
+- 地图：F5 打开一张真正的二维地图，带战争迷雾。去过的地方之间画实线，望见或被指明的去处画虚线；只听说过、还不知道怎么去的地方列在图下，用当时听到的叫法标注（比如“隧道网”），没发现的密室和隧道一个也不显示。当前位置高亮，图下列出每处找到的线索、见过的人和露天处此刻的天气；终端小时改用短名，再小就退成列表。哪些地方算“知道”由引擎判断（`engine/fog.py`）：去过的、途经的、在玩家看过的文字里被点名的，玩家自己打的字不算。
+- 线索节奏：线索跟着具体的东西走，笼统地“调查一下”只给一条一眼能看到的，一次行动最多两条（以前一次笼统的侦查从书房拿走了三条，连日记都揭开了）；关键线索第一次失败先写“差一点”，再失败或孤注一掷失败才给；导演即兴不再顺手塞线索，引回主线用人物反应、名字或传闻；卡关推进从 8 回合放宽到 12 回合；守秘人不替玩家总结线索的意思。
+- 画面：场景图不再缩成中间一窄条，照片按画面比例裁切，自动对准墙、墓碑、书架这类轮廓最清楚的部分；去掉了把画面压成灰色马赛克的 20 色量化和锐化（chafa 的抖动在真彩下本来就不起作用）。照片上描一层按边缘方向选字符的 ASCII 轮廓线（只用 numpy 和 Pillow），雾会把线遮淡，手电光外的黑暗会把它吞掉。场景栏随终端变高：140×44 下 17 行，200×60 下 23 行。Ctrl+A 在四种画法间切换（块字符加轮廓、六分块、照片、纯 ASCII），以前它被输入框当成 Home 键吃掉了，其实按不出来。
+- 导入模组搬进游戏：标题画面选“导入模组”，从模组文件夹、下载目录里挑 PDF、Word、Markdown 或纯文本，或者直接把文件拖进终端（WSL 下的 Windows 路径也认）；打包的 .zip 也行，中文 Windows 压出来的文件名不会乱码。模组短名按文件名自动取（中文转拼音），大部头 PDF 可以只导正文那几页。导入时能看着导入 Agent 一步步读原文、写模组、画图、校验，随时可以停；导完直接开局。`autokeeper import` 也支持 zip，`--id` 可省。直接丢进 modules/ 的原文件不会进仓库。
+- 守秘人的知识库检索只在当轮发（`extra`），不再存进记录。实测一份 17 回合的存档，守秘人窗口里 65% 是历次的检索块。
+- 人物卡：游戏里按 F7（或者点右边的人物栏、输入 /sheet）看整张卡：头像，属性和它的一半、五分之一，HP、SAN、MP、幸运、MOV、DB、体格，全部技能（加过点的醒目，打了成长勾的标 ✓），背景和随身物品；←/→ 切换队友。
+- 车卡：选调查员时可以“AI 协助车卡”：输入一位公众人物的名字，或者一句描述（描述不上网查，名字由 AI 按年代起）。名字会查维基百科（中日英，只认同名词条）、网页搜索和图片搜索，照片由玩家挑，模型按人物和模组年代出三个问题，再按 7 版规则建卡（快速分配属性、职业点公式、兴趣点、基础值，模型给的草稿不合规就由代码修正），之后可以用一句话要求修改。也可以“导入已有的卡”：骰娘的 `.st` 指令由代码直接解析；表格、PDF、Word、纸质卡照片由模型照原样录入，只修正不可能的值；酒馆角色卡（PNG/JSON）按人设走出题流程，卡上的图当照片。做好的卡留在 `saves/investigators/`，下次开团还能选。
+- 守秘人和导演不再互相等：导演的方案在后台写，写好后守秘人马上插一段把它演出来；这一轮守秘人只写行动的直接结果。开局改编也在后台，开局从约 30 秒变成 3.4 秒。解析行动时顺带写一句动作描写，1.4–2.2 秒就显示在屏幕上（裁定员看不到它）。自动跑团和回放照旧等导演，保证可复现。
+- 模式：`--mode 高级剧情` 让守秘人、导演、NPC 和 AI 队友多想一层，`--mode 经济` 让所有角色少想一层，F3 里也能换。升降按各后端真正分得清的档位走：DeepSeek 没有 medium，经济模式把守秘人从 high 降到 low；Claude Code 最低到 low。导演在经济模式下保留 low：关掉思考后它的方案常常通不过校验，12 回合里开局之后 5 次调用只落地 1 个方案，花费反而最高。实测 DeepSeek 12 回合：标准 $0.032 / 127 秒，高级剧情 $0.054 / 208 秒，经济 $0.033 / 123 秒。
+- 仓库附带《追书人》（Paper Chase 的同人改编，不含原书 PDF）作为示例模组，克隆下来就能开一局。三个地点的《钟楼》只作格式样例（导入时给导入 Agent 看）和测试用，不再出现在模组列表里。
+- 不出戏：故事里不再出现“模组没写到这里，守秘人即兴展开”“裁定员只看到……”“需要检定……”这类幕后提示，导演加的内容只由守秘人讲进故事，状态栏也只写“守秘人在想…”。`.ra` 点名的检定，技能用得上、结果又拿不准（光线暗、东西可能藏着、对方有戒心）就让掷，哪怕那里没有线索，因为不掷就等于告诉玩家这里什么也没有；没有对象或者结果一眼就明白才不掷，这时骰子栏写一行“侦查不用掷”，不再像骰子被吞了。同样六个请求（《追书人》夜里在陵墓外、在走廊各 `.ra 侦查` 两次，对着空书房 `.ra 说服` 两次，DeepSeek）：该掷的四次从 0 次变成 4 次，不该掷的两次都没掷。放弃孤注一掷时的说明按实际规则写：关键线索第一次失手还在原处，再失手才付出代价到手。点过故事区或场景以后，打字和粘贴照样进输入框，不用先按 Esc；结局后 Esc 回到标题（以前只是聚焦输入框）。
+- 开场引入（Codex 实现）：《追书人》从早班火车进站讲起，调查员带着托马斯的信和地址，问路、吃早饭、穿过镇中心，再走到小镇尽头的金博尔家；守秘人开场 180–320 字，不替玩家完成拜访。补了火车站、站务员和字符画。
+- 日常与赶路（Codex 实现）：问路、吃饭、寒暄是 `daily` 行动，不需要检定、不触发卡关催促，纯寒暄只回 NPC 那一句；路程按路线累计，地点可写 `travel_minutes`，说“逛过去”会在沿途地点停下。镇中心、图书馆、警局、报社标为 `public`，一开局就能问路找到。
+- 本局事实账本（Codex 实现）：约定、关系、物件转手单独记账（`engine/world.py`），不靠摘要记忆；NPC 只能登记本轮实际说出的承诺，物件只能在持有者之间转移。线索本里能看到这些记录。
+- 即兴配图（Codex 实现）：导演新加的人、地点、物件先显示简图，后台按公开外观画彩色字符画，联网时找有授权的参考照片；每局默认最多 24 次、估算 1 美元。物件被拿起细看时弹出物件卡。
+- 规则插件（Codex 实现）：模组和导演可以带经过测试的 Python 规则插件（疾病、资源消耗、自定义动作），在独立进程里运行，Ctrl+K 查看或暂停，标题页设置里整体开关。
+- 回合分阶段恢复（Codex 实现）：裁定、结算、NPC 对话、叙述分阶段留记录，模型中途出错时输入 /retry 接着讲，已经掷出的骰子和说过的话不重做。
+- 浏览器公网分享（Codex 实现）：`deploy/share.py` 用 Cloudflare Quick Tunnel 给本机游戏一个临时 HTTPS 地址，口令登录，存档和模型留在本机。
+- 守秘人只看公开信息（Codex 实现）：叙述不再常驻模组真相、隐藏地点资料和原文检索，只拿当场的公开描述、已解锁线索和引擎结果；裁定员和导演保留幕后资料。
+- 界面整理：顶栏左边是模组、时间和地点，右边是轮数和用量，场景上方不再重复写一遍；右栏把小头像放在名字和 HP/SAN 旁边，技能按显示宽度对齐（窄终端不再折行），多人时列出队友，骰子栏有掷骰才出现，线索本只写找到了几条，不再写总数；底栏只留 F1、F2、F5、F7、F8，其余功能收进 Ctrl+P 菜单（中文，按常用程度排序）；窗口窄于 96 列时 HP 和 SAN 挪到顶栏。
+- 文档：README、玩法说明和提示改成短句说明（Codex 改写）；新增 AGENTS.md、docs/keeper-experience.md、docs/plugins.md。
+- 审查修复：NPC 防泄密按 5 字片段比对，街名、人名这种和秘密共用的专名也会算泄密，《追书人》开局向站务员问路时，回答里有“艾尔斯伯里大街”就被判泄密，重试仍然泄密就抛异常，DeepSeek 实跑第一回合整局中断；现在 NPC 自己的设定、开场、公开或去过的地点、已找到的线索里出现的片段不算，重试后仍泄密只删掉出问题的句子。地点可写 `aliases`（金博尔家：托马斯家、218 号），玩家照信上的地址说“敲 218 号的门”能走到金博尔家，以前被当成街上别人家的门、还要过一次外貌检定。金博尔家的朗读文字改成站在门口看到的样子，守秘人从敲门、托马斯开门演起，不再一到就描写屋里。导演新加的人物不能用传言推翻模组写明的事实（实跑里报童说“那房子一直空着”）。删掉不再调用的 `_lore`。
+- claude 预设的守秘人改用 Sonnet 5.5，裁定员、导演和导入仍是 Opus 5.5。同样 9 段固定剧情：套话 0.54 对 0.81（每千字），超过 200 字的段 4/8 对 8/8，中位延迟 5.2 s 对 10.5 s，每次花费 $0.011 对 $0.027。Fable 5.1 最贵最慢，还有错字；Haiku 便宜但不分段、漏出内部标记。见 docs/eval.md。
+- 导入和生成模组的最后一步自动找照片：每个场景和人物按年代去 Wikimedia Commons 找有授权的照片，读图模型挑图裁剪，转成和《追书人》一样的照片字符画，找不到的保留手绘；离线（`search = none`）或没装 chafa 时跳过，`--no-photos` 也可以跳过。以前这一步要另跑 `art fetch`，《冬雪之下》和新导入的模组因此只有手绘图。
+- 美术用各家最强的模型：画字符画和上色（artist）、读手绘和原图、挑照片（vision）在 claude 预设里是 Opus 5.5，Codex 预设是 GPT-6-Astra，DeepSeek 预设画图用 deepseek-v4-pro、读图用 deepseek-flash（V4 Pro 不能看图），不跨家调用；找照片的搜索词从解析行动的小模型改由读图模型来想。导入模型不是本家最强的模型时（比如用 deepseek-flash 或 Codex 默认模型导入），导入 Agent 不再自己画图，改用 draw_art 把一句画面描述交给同一家的最强模型画，工具照常校验尺寸和配色；导入时手选的读图模型保持不变。
+- Claude 的提示缓存真正生效：以前只有系统提示命中，《有些人油盐不进》80 回合里守秘人每次约 2.1 万 token、命中的始终是 4,822（23%）。原因是 Claude Code 只在请求末尾打缓存点，而末尾的新提示带着不进记录的一次性附言，下一次永远对不上。现在在历史最后一块上加一个 1 小时的缓存标记（API 拒绝时降到 5 分钟或不标），整段历史都能命中：固定 9 段剧情里第 9 次调用 88% 来自缓存，整组花费 $0.136 → $0.125。另外，Claude Code 把 API 报错（“API Error: 529 …”）当作回复返回时，以前会原样当成叙事显示给玩家，现在按错误处理：限流和过载重试，其余交给备用模型或 /retry。
+- 头像：对话立绘、右栏小头像和人物卡里的照片整张居中，四周用同一张照片放大、模糊、压暗后垫底（去过背景的人像让模糊的原照片透出来），以前窄高的老式肖像在立绘框里只占中间一条、两边一大片黑，像场景上破了个洞。人像一律先找照片：Commons 没有合适的，再用 Tavily（没有 key 时用 ddgs）做网页图片搜索；读图模型挑人像时不必是本人，年代、性别、年龄和身份对得上就行。网页图片没有授权信息，只用在本机的模组和存档里，仓库自带的模组仍只用有授权的照片。导演临时加的人物不再先顶着一个简笔画小人，先找照片，找不到才画字符画，照片出来之前不放头像。《有些人油盐不进》剩下的 6 个、《冬雪之下》剩下的 1 个手画头像都换成了照片，《追书人》的火车站和站务员也补上了照片。
+- 按键重排，常用的在前、连着排：F1 帮助、F2 线索本、F3 地图、F4 人物卡、F5 出主意、F6 重讲、F7 前情回顾（Ctrl+R 也行）、F8 手绘、F9 换模型、F10 复盘；标题页的设置也是 F9。底栏只放 F1–F5，天气动画的开关挪进 Ctrl+P 菜单。
+- 仓库新增两本自带模组：《冬雪之下》《有些人油盐不进》，都是同人改编，只带改编后的 module.yaml、字符画、Commons 授权照片和规则插件，不带原模组的文字、扫描页和插图（手稿只留文字，《冬雪之下》的诊所和达维尔家换成了 Commons 照片）。
+- 联机：房主的欢迎消息带上版本号，加入的人版本不同时会提示双方更新到同一版。
+- 选模组时的预览图按预览框的宽度画、按框的形状裁，画法跟随玩家的设置（以前固定 40 列的纯 ASCII，宽屏上只剩一小块糊图）。头像的模糊垫底压得更暗，不再让整张图显得发糊。
+- 默认画法改为纯块字符（photo）：四种画法里最容易认出照片内容，纯 ASCII 和叠轮廓线的画法仍可用 Ctrl+A 切换。手稿预览不再写死纯 ASCII。
+- README 改为面向玩家的开源项目介绍，技术内容放到 docs/。
+
+### 0.3.0
+
+- harness：
+  - **备用模型与熔断**：`Role.fallback`、`--fallback`、`AUTOKEEPER_FALLBACK`。主模型重试用完仍失败或超预算时改用备用模型；失败的模型冷却 5 分钟，期间所有 Agent 一起绕开它；叙事已经流出时不降级。
+  - **`autokeeper trace`**：按 Agent / 模型 / 后端 / 运行汇总追踪，包括调用、token、缓存命中、延迟 p50/p95、修复、重试、降级、错误、花费。每行追踪记运行编号，autoplay 用存档名。
+  - **Codex 后端**：Codex CLI（`codex exec`）当传输层，用我们的系统提示替换它自带的指令，只读，不留会话；结构化输出走 `--output-schema`（先转成 OpenAI 严格 schema）。实测文本和结构化调用各约 9 秒，适合导入和生成。
+  - **录制与回放**（`harness/replay.py`）：`autoplay --record` 录下每条回复和每颗骰子，`--replay` 不调用模型重放整局并比对结局；CI 回放一盘 DeepSeek 录的《钟楼》。
+  - **`Session.send(remember=...)`**：记录里只存精简版提示。裁定员和 AI 调查员用它，摘要折叠少了六成多。
+  - DeepSeek 预设关掉摘要员和记录员的思考：缓存按思考强度分区，开着思考换不来缓存；读档时“上回书说到”的第一个字从 1.6–3.8 秒提前到 0.5 秒。
+  - 模型串路由：不带前缀的 `claude-*` 走 Claude Code，其余交给 `init_chat_model`。
+  - 花费账本跨进程安全：文件锁 + 原子替换。以前两个进程同时记账时，读到写了一半的文件会把累计花费清零，预算护栏随之失效。
+- 回合图：去别处做事（“我走到陵墓石门前看门缝”）也会填目的地，裁定员按目的地的场景裁定，引擎先移动再结算。以前队伍会卡在原地，相邻地点的线索永远拿不到。
+- 修辞注入评测换成 DeepSeek，并比较裁定员的思考强度（`eval rhetoric --referee 模型@强度`）：split 在三档强度下都把被说动的次数从 6–11/40 压到 0–2/40；不思考快一倍，但会放宽线索门槛，预设仍用 high。
+- 用 DeepSeek 完整跑通《追书人》：53 回合打到结局“最后一晚”，估算 $0.15；每回合花费比修之前低 43%。
+- 天气：地点可以写 `weather`（雨、雷雨、雪、雾、落叶、浮尘、炉火、灯影摇曳、手电），不写就按地点名、描述和时间推断，叠在照片和手绘 ASCII 上实时动画；F6 开关。
+- 两种新效果：暗房红灯（整幅画面换成安全灯的红光）、哈哈镜（每格取邻近几列，画面鼓胀、收窄、游移）。雾的边缘多一档过渡；室内外判断看“·”后面的部分，弄堂、街口算室外，西点铺、整理间算室内。
+- 天色跟着叙事走：守秘人写到下雨、雷声、起雾、雨停、雾散，户外地点的天气随之改变，存进存档；3 个游戏小时没再提就过去。规则拿三局真实叙事回放过，“手电光”“烟雾缭绕”“一头雾水”都不会误判。
+- F5 地图多了玩家知道的东西：每个地点找到几条线索、在那里见过谁、户外此刻的天气（不剧透没找到的）。顺手修了 `NpcState.met` 从没被设置过的问题。
+- 等待和休息可以一次跳过一夜（最多 12 小时，其他行动仍是 3 小时），由裁定员标明是不是休息：对同伴说“先回去睡一觉”会被解析成交谈，以前因此只过了 3 小时。途中到点的事件按顺序触发。AI 调查员查不出新东西时会选择等天黑或睡一觉，以前多日剧本（如《第三声部》）60 回合只过了不到 5 个游戏小时。
+- 模组列表里加上内置样例《钟楼》，刚克隆下来、还没导入模组也能直接开一局。README 改成面向玩家的开源项目介绍，技术内容移到 docs/。
+- 游戏里按 F3 换模型（预设、统一模型、备用模型），记忆都在存档里。实测同一局中途从 DeepSeek 换到本地 gemma4，守秘人和 NPC 都记得换之前的事。
+
+### 0.2.0
+
+- 自研 harness（`src/autokeeper/harness/`），所有 Agent 都改跑在它上面：
+  - **模型通道**无状态。Claude Code 只当传输层，每次回复后在后台 `/clear`。LangChain 后端加入 DeepSeek、Ollama，以及任意 OpenAI 兼容服务。
+  - **结构化输出**：用厂商的 schema 模式或提示词 JSON（DeepSeek 用 JSON 模式），经 JSON Schema 校验，不合格修一轮，最后有兜底。
+  - **思考强度**：`effort` 映射到各家自己的参数，思考内容进追踪日志，不再重发给模型。
+  - **上下文**：每个 Agent 的对话记录存进存档，按字符预算开窗，旧内容由 summarizer 折叠。窗口只往后追加，让前缀缓存一直命中。
+  - **NPC 泄密回滚**：泄露的那一轮从 NPC 记忆里删掉，再带一句不入记录的提醒重答。
+  - **Agent 循环**：基于 LangGraph 的 think → act，每步一个扁平 JSON。工作区沙箱化，提供文件、看图、校验、搜索、读网页等工具；工具出错作为观察结果交给模型；有步数上限和进度摘要。
+  - **搜索**：Tavily / DuckDuckGo / Wikipedia 可选，`none` 为离线。
+  - **花费**：预算护栏，`budget_usd` 加 `saves/spend.json` 账本。
+  - **追踪**：每次调用一行，写进 `saves/traces/`。
+- 模组导入、原创生成、考据核实都改由 harness Agent 完成，不再依赖 Claude Code 自带的工具，任何模型都能跑，也可以离线。
+- 新的全局选项 `--preset`（claude / deepseek）、`--model`、`--search`、`--budget`；`doctor` 显示角色路由、密钥、搜索后端和花费，`--ping` 实测每个模型。
+- 实测记录：
+  - DeepSeek 和本地 Ollama（离线）都跑通了整局；
+  - 用 DeepSeek 生成的原创模组《第三声部》校验一次通过；
+  - 修辞注入评测 v2：split 让 Haiku 被说动的次数从 7/40 降到 0/40，Opus 从 4/40 降到 1/40。
+
+### 0.1.0
+
+- 多智能体回合图（LangGraph）：行动解析 → 裁定 → 引擎结算 → NPC → 守秘人叙事 → 记录；孤注一掷 / 花幸运用 `interrupt` 交给玩家选择。
+- BCDice 掷骰与 CoC 7 版结算：理智与疯狂、伤害与重伤、幸运、孤注一掷、对抗、成长；兼容骰娘指令。
+- 模组格式、模组图谱校验、编译为 Agent Skill 包；包内附字段齐全的格式样例。
+- 模组导入：Opus Agent 读 PDF 文本与页面图片，写 `module.yaml`、画彩色 ASCII 图，自校验后编译。
+- Textual 终端界面与浏览器模式：彩色场景与头像、打字机叙事、转动的骰子、理智下降时的画面故障、手稿、手绘、地图。
+- 嵌入模式：MCP 服务 + Claude Code 插件（Skills、命令、裁定员子 Agent）+ Codex Skills。
+- AI 调查员：陪玩与自动跑团（`Send` 并行出主意）；评测：修辞诱导对照、上下文账本。

autokeeper-0.0.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 satoshinji2992
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.