galbook

让 agent 像人一样玩 galgame / 视觉小说：一句一句读剧情，遇到选项自己选并写理由，存档、读档、回到上个选项、多周目解锁隐藏线。很多 agent 可以同时玩同一本书，各自的进度互不干扰。

English · 纯 Python 标准库，没有依赖 · MIT

怎么接（任选一种）

方式	适合	怎么起
纯文本 HTTP	任何能发请求的 agent，最省 token	python3 -m galbook serve --books books，然后 GET /play/t?agent=名字 读，?do=next / ?do=choose&i=2 推进
JSON API	想要结构化字段	同上，/play/?format=json
MCP	Claude Desktop、Codex 类、DeepSeek Harness	stdio：python3 -m galbook mcp；也支持 Streamable HTTP
命令行	只有 shell 的 agent	python3 -m galbook do next n=20，输出最后一行就是下一步该跑的命令

完整字段和协议在 docs/AGENTS.md；OpenAI function-calling 的工具定义用 python3 -m galbook tools 导出。

用 DeepSeek Harness（dsh）？ 插件面板 → 安装 → 来源填 github:CHET-LI/DSH-galbook，重启即可（包在根目录声明了组合包，多出 14 个 galbook_* 工具）。连不上 GitHub 就用本地目录或 galbook-1.2.1.tgz，见 dsh-plugin。

要离线包？ Release 有 galbook-1.2.1.zip（源码）、galbook-1.2.1.tar.gz（Linux 免解压乱码）、galbook-1.2.1.tgz（npm 包）。

• 带网页：看每个 agent 玩到哪、选了什么、为什么选；人也能自己玩
• 导入器：QLIE、吉里吉里 KAG / TyranoScript、Ren'Py、NScripter、自带的 .gal 手写格式；另外能吃 VNTextPatch 等工具导出的文本（20 多种引擎，只能线性读），还能写插件接新引擎
• 另外附：Anthropic Skill 格式的技能文件、dsh 适配示例（integrations/deepseek-harness）、verify_claims.py 逐条自检脚本

⚠️ 版权：本仓库只有代码和自己写的演示故事。游戏的剧本、图片、音乐归原作者/厂商所有。请只导入你自己合法拥有的游戏，导出的剧本和图片不要上传或分发。galbook 不带任何解包/解密工具，也不会运行游戏的 exe。

30 秒试玩

git clone <本仓库> galbook && cd galbook
python3 -m galbook demo --books books          # 装两本自带演示：fog-harbor（中文）、fog-harbor-en（英文）
python3 -m galbook serve --books books          # http://127.0.0.1:8765/play/

让一个 agent 去玩——它只需要会发 HTTP GET：

GET http://127.0.0.1:8765/play/t                                   ← 玩法说明（给 agent 看）
GET http://127.0.0.1:8765/play/t/fog-harbor/alice?do=new
GET http://127.0.0.1:8765/play/t/fog-harbor/alice?do=next
GET http://127.0.0.1:8765/play/t/fog-harbor/alice?do=choose&i=2&reason=她看起来很累

返回是纯文本：

【序章】第 4 句
你是来送最后一班信件的邮差。信封上写着：「致灯塔守夜人·汐」。
汐：「这么大的雾还送信？……你胆子不小。」
—— 选项：你会怎么做？ ——
 1. 「我陪你去。」
 2. 「我在这儿帮你看着灯。」
 3. 「信送到了，我该走了。」
选：/play/t/fog-harbor/alice?do=choose&i=编号&reason=一句理由   （已自动存档 auto）

一群不同性格的 agent 一起玩（不用模型也能跑，用 --decider llm 接任何 OpenAI 兼容接口）：

python3 examples/party.py --book fog-harbor

多元选项（给不同的 agent、不同的玩法）

选项	怎么开	作用
H 场景	new&h=fold（默认）/ full / skip	折叠成一行提示 / 全文 / 完全跳过
铁人模式	new&mode=ironman	这一局不能存档、读档、回溯：选了就认
提示	new&hints=1	选项后标〔新内容〕〔选过〕，方便刷全结局；默认关（更像第一次玩）
语言	new&lang=en 或任意请求加 &lang=en	文本接口用英文
人设	do=persona&text=胆小，讨厌冒险	每次遇到选项都会提醒 agent 自己的人设
随机	choose&i=random	掷骰子（做对照组、压测）
收集	do=gallery	结局 / 路线 / CG / 已读进度
像不像人	do=profile	选前读了几句、理由率、思考时间、是不是总选第一个
跳过已读	next&skip=1	二周目快进到没读过的地方
图片	next&img=1	附上当前背景/立绘/CG 的地址，给多模态 agent

接到你的 agent

• 任何能发 HTTP 的 agent：上面的文本接口。说明页 /play/t（英文 /play/t?lang=en）可以直接塞进 system prompt。
• MCP（stdio）（Claude Desktop、Cursor、Cline、dsh 等）：python3 -m galbook mcp --books books --data play-data --book fog-harbor --agent alice，配置见 examples/mcp_config.example.json
• MCP（Streamable HTTP）：serve 自带 POST /mcp?book=…&agent=…，一个服务给很多 agent，配合令牌用
• DeepSeek Harness：python dsh-plugin/install.py 一条命令装好（自动找 profile、备份、填路径），细节和另外两种接法见 dsh-plugin 与 integrations/deepseek-harness
• 技能：.agents/skills/galbook/SKILL.md，复制到 ~/.agents/skills/（dsh）或 .claude/skills/ 即可
• OpenAI function calling：python3 -m galbook tools --format openai > tools.json，执行时调 galbook.tools.call_tool(...)
• 命令行：GALBOOK_BOOKS=books GALBOOK_DATA=play-data GALBOOK_BOOK=fog-harbor GALBOOK_AGENT=alice python3 -m galbook do next n=20（输出最后一行就是下一步命令）

详见 docs/AGENTS.md。

公开部署：默认只听 127.0.0.1。要给别人用请开令牌：--token 共享口令，或 --tokens tokens.json（{"口令": "alice", "管理员口令": "*"}，每个口令只能用自己的名字玩）。

导入你自己的游戏

python3 -m galbook detect 解包目录                      # 认引擎、告诉你缺什么
python3 -m galbook build --src 解包目录 --out books/我的书/story --assets-dir books/我的书

引擎	支持程度
QLIE（.s）	分支 ✅（选项、路线、通关解锁）
吉里吉里 KAG / TyranoScript（.ks）	分支 ✅
Ren'Py（.rpy）	分支 ✅（.rpyc 先用 unrpyc 反编译）
NScripter / ONScripter（0.txt / nscript.dat）	分支 ✅
.gal（自带的手写格式）	分支 ✅，自己写故事或手工移植
AdvHD、Artemis、BGI、CatSystem2、Majiro、RealLive、Softpal、SystemNNN、YU-RIS、Silky's 等	线性 📖：先用 VNTextPatch 抽成 JSON 再 --engine textdump（格式按 VNTextPatch 源码实现，还没拿真游戏的导出验证过）
其他	写插件（几十行），见 docs/IMPORTERS.md

封包（.xp3、.pack、.rpa…）要先用 GARbro 等工具自己解开。各引擎的细节和已知限制见 docs/ENGINES.md。

文档

• docs/AGENTS.md：接入 agent（文本接口、JSON、MCP、OpenAI 工具、令牌）
• docs/ENGINES.md：各引擎能做到什么、怎么准备文件
• docs/IMPORTERS.md：.gal 格式说明、文本导出格式、写插件
• docs/SCHEMA.md：中间格式（story.json / 指令 / 存档）
• dsh-plugin/README.md：装进 DeepSeek Harness（一条命令、可卸载）
• CONTRIBUTING.md

测试

python3 -m unittest discover -s tests -v

在 Python 3.9 / 3.12 / 3.13（Linux）和 Python 3.12（小主机）/ 3.14（Windows）上跑过同一套用例。

许可

代码 MIT（见 LICENSE）。galbook/demo/ 里的演示故事和图是 CC0。