galbook 1.2.4 → 1.2.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (14) hide show
  1. package/README.en.md +114 -114
  2. package/README.md +133 -133
  3. package/dsh-plugin/README.md +49 -49
  4. package/dsh-plugin/install.py +1 -1
  5. package/galbook/__init__.py +1 -1
  6. package/galbook/cli.py +31 -29
  7. package/galbook/imaging.py +121 -0
  8. package/galbook/mcp_server.py +8 -3
  9. package/galbook/play.py +59 -5
  10. package/galbook/tools.py +34 -7
  11. package/galbook/web.py +88 -28
  12. package/locale/en.json +1 -1
  13. package/locale/zh.json +1 -1
  14. package/package.json +58 -58
package/README.en.md CHANGED
@@ -1,114 +1,114 @@
1
- # galbook
2
-
3
- **Play a galgame / visual novel like a human would**: read one line at a time, pick choices yourself and write down why, save, load, rewind to the last choice. Ships an MCP server, an HTTP server and a CLI, plus a DeepSeek Harness (dsh) bundle.
4
- Hidden routes unlock across playthroughs, and many agents can play the same book at once with independent progress.
5
-
6
- [中文](README.md) · pure Python standard library, no dependencies · MIT
7
-
8
- ## Four ways in
9
-
10
- | Way | Best for | Start |
11
- |---|---|---|
12
- | **Plain-text HTTP** | any agent that can send a request; cheapest in tokens | `python3 -m galbook serve --books books`, then `GET /play/t?agent=name` to read, `?do=next` / `?do=choose&i=2` to advance |
13
- | **JSON API** | when you want structured fields | same server, `/play/?format=json` |
14
- | **MCP** | Claude Desktop, Codex-style clients, DeepSeek Harness | stdio: `python3 -m galbook mcp`; Streamable HTTP also supported |
15
- | **CLI** | agents with nothing but a shell | `python3 -m galbook do next n=20`; the last line tells the next command |
16
-
17
- Full protocol in [docs/AGENTS.md](docs/AGENTS.md); dump OpenAI function-calling definitions with `python3 -m galbook tools`.
18
-
19
- > **Using DeepSeek Harness (dsh)?** Plugin panel → install → source `github:CHET-LI/DSH-galgame-galbook`, restart, and you get 15 `galbook_*` tools. If GitHub is unreachable use a local folder or `galbook-1.2.4.tgz` — see [dsh-plugin](dsh-plugin/).
20
-
21
- > **Offline packages?** [Releases](https://github.com/CHET-LI/DSH-galgame-galbook/releases/latest) has `galbook-1.2.3.zip` (source), `galbook-1.2.3.tar.gz` (no unzip mojibake on Linux), `galbook-1.2.4.tgz` (npm package).
22
-
23
- - Pure Python standard library, zero dependencies
24
- - Ways in: **plain-text HTTP** (cheapest in tokens, works with any agent), **JSON API**, **MCP** (stdio and Streamable HTTP), a **CLI** for shell-only agents, a **Skill** file (Anthropic format), plus exported **OpenAI function-calling** tool schemas
25
- - Ready-made **DeepSeek Harness (dsh)** integration — MCP, skill and CLI all tested, see [integrations/deepseek-harness](integrations/deepseek-harness/)
26
- - A web page to watch what each agent is doing, what it chose and why — humans can play too (web UI is Chinese for now; the text API, MCP and tools are bilingual)
27
- - Importers: QLIE, Kirikiri KAG / TyranoScript, Ren'Py, NScripter, and a hand-written `.gal` format; text dumps from VNTextPatch and similar tools (20+ engines, linear only); and a plugin API for new engines
28
-
29
- ![Three agents playing at once; watching one of them in the web UI](docs/img/watch.png)
30
-
31
- > ⚠️ **Copyright**: this repo contains only code and self-written demo stories. Game scripts, images and music belong to their original creators. Only import games you legally own, and **do not upload or distribute** the converted scripts or images. galbook ships no unpacking/decryption tools and never runs game executables.
32
-
33
- ## Try it in 30 seconds
34
-
35
- ```bash
36
- git clone <this repo> galbook && cd galbook
37
- python3 -m galbook demo --books books # installs the demos: fog-harbor (Chinese), fog-harbor-en (English)
38
- python3 -m galbook serve --books books --lang en # http://127.0.0.1:8765/play/
39
- ```
40
-
41
- An agent only needs HTTP GET:
42
-
43
- ```
44
- GET http://127.0.0.1:8765/play/t?lang=en ← how to play (for the agent)
45
- GET http://127.0.0.1:8765/play/t/fog-harbor-en/alice?do=new&lang=en
46
- GET http://127.0.0.1:8765/play/t/fog-harbor-en/alice?do=next
47
- GET http://127.0.0.1:8765/play/t/fog-harbor-en/alice?do=choose&i=2&reason=she+looks+tired
48
- ```
49
-
50
- A party of agents with different personalities (runs without any model; add `--decider llm` for any OpenAI-compatible API):
51
-
52
- ```bash
53
- python3 examples/party.py --book fog-harbor-en
54
- ```
55
-
56
- ## Diversity options
57
-
58
- | Option | How | What |
59
- |---|---|---|
60
- | Adult scenes | `new&h=fold` (default) / `full` / `skip` | fold to a one-line note / show / skip entirely |
61
- | Ironman | `new&mode=ironman` | no save, load or rewind this run — live with your choices |
62
- | Hints | `new&hints=1` | mark options as [new] / [picked before]; off by default (feels like a first playthrough) |
63
- | Language | `new&lang=en`, or `&lang=en` on any request | English text interface |
64
- | Persona | `do=persona&text=timid, hates risks` | reminded to the agent at every choice |
65
- | Random | `choose&i=random` | roll a die (baselines, load tests) |
66
- | Gallery | `do=gallery` | endings / routes / CG / read ratio |
67
- | Human-likeness | `do=profile` | lines read before choices, reason rate, think time, always-first-option |
68
- | Skip read | `next&skip=1` | fast-forward to unread text |
69
- | Images | `next&img=1` | URLs of current background / sprites / CG for multimodal agents |
70
-
71
- ## Connect your agent
72
-
73
- - **Any HTTP-capable agent**: the text API above. `/play/t?lang=en` can go straight into a system prompt.
74
- - **MCP (stdio)** (Claude Desktop, Cursor, Cline, dsh, …): `python3 -m galbook mcp --books books --data play-data --book fog-harbor-en --agent alice --lang en` — see [examples/mcp_config.example.json](examples/mcp_config.example.json)
75
- - **MCP (Streamable HTTP)**: `serve` exposes `POST /mcp?book=…&agent=…` — one server, many agents, works with tokens
76
- - **DeepSeek Harness**: [integrations/deepseek-harness](integrations/deepseek-harness/) (patch config, skill, a no-API-key self-test)
77
- - **Skill**: [.agents/skills/galbook/SKILL.md](.agents/skills/galbook/SKILL.md) — copy into `~/.agents/skills/` (dsh) or `.claude/skills/`
78
- - **OpenAI function calling**: `python3 -m galbook tools --format openai > tools.json`, execute with `galbook.tools.call_tool(...)`
79
- - **CLI**: `GALBOOK_BOOKS=books GALBOOK_DATA=play-data GALBOOK_BOOK=fog-harbor-en GALBOOK_AGENT=alice python3 -m galbook do next n=20 --lang en` (the last line of output is the next command)
80
-
81
- Details: [docs/AGENTS.md](docs/AGENTS.md) (Chinese with English examples).
82
-
83
- **Public deployment**: binds 127.0.0.1 by default. Use `--token SECRET`, or `--tokens tokens.json` (`{"key1": "alice", "admin-key": "*"}` — each key can only play as its own name).
84
-
85
- ## Import your own games
86
-
87
- ```bash
88
- python3 -m galbook detect path/to/extracted
89
- python3 -m galbook build --src path/to/extracted --out books/mygame/story --assets-dir books/mygame
90
- ```
91
-
92
- | Engine | Support |
93
- |---|---|
94
- | QLIE (`.s`) | branching ✅ |
95
- | Kirikiri KAG / TyranoScript (`.ks`) | branching ✅ |
96
- | Ren'Py (`.rpy`; decompile `.rpyc` with unrpyc first) | branching ✅ |
97
- | NScripter / ONScripter (`0.txt` / `nscript.dat`) | branching ✅ |
98
- | `.gal` (built-in hand-written format) | branching ✅ |
99
- | AdvHD, Artemis, BGI, CatSystem2, Majiro, RealLive, Softpal, SystemNNN, YU-RIS, Silky's, … | linear 📖 via [VNTextPatch](https://github.com/arcusmaximus/VNTranslationTools) JSON + `--engine textdump` (format implemented from VNTextPatch's source; not yet verified against a real game's export) |
100
- | anything else | write a plugin — see [docs/IMPORTERS.md](docs/IMPORTERS.md) |
101
-
102
- Archives (`.xp3`, `.pack`, `.rpa`, …) must be extracted first with tools such as GARbro.
103
-
104
- ## Tests
105
-
106
- ```bash
107
- python3 -m unittest discover -s tests -v
108
- ```
109
-
110
- Tested on Python 3.9 / 3.12 / 3.13 (Linux) and Python 3.12 (mini PC) / 3.14 (Windows) with the same suite.
111
-
112
- ## License
113
-
114
- Code: MIT ([LICENSE](LICENSE)). Demo stories and art in `galbook/demo/`: CC0.
1
+ # galbook
2
+
3
+ **Play a galgame / visual novel like a human would**: read one line at a time, pick choices yourself and write down why, save, load, rewind to the last choice. **It also sees the screen** — when the picture changes you are told the background, who stands on which side and with which expression; the first time it meets a CG the image arrives with the text, and `galbook_look` shows whatever is on screen right now. Ships an MCP server, an HTTP server and a CLI, plus a DeepSeek Harness (dsh) bundle.
4
+ Hidden routes unlock across playthroughs, and many agents can play the same book at once with independent progress.
5
+
6
+ [中文](README.md) · pure Python standard library, no dependencies · MIT
7
+
8
+ ## Four ways in
9
+
10
+ | Way | Best for | Start |
11
+ |---|---|---|
12
+ | **Plain-text HTTP** | any agent that can send a request; cheapest in tokens | `python3 -m galbook serve --books books`, then `GET /play/t?agent=name` to read, `?do=next` / `?do=choose&i=2` to advance |
13
+ | **JSON API** | when you want structured fields | same server, `/play/?format=json` |
14
+ | **MCP** | Claude Desktop, Codex-style clients, DeepSeek Harness | stdio: `python3 -m galbook mcp`; Streamable HTTP also supported |
15
+ | **CLI** | agents with nothing but a shell | `python3 -m galbook do next n=20`; the last line tells the next command |
16
+
17
+ Full protocol in [docs/AGENTS.md](docs/AGENTS.md); dump OpenAI function-calling definitions with `python3 -m galbook tools`.
18
+
19
+ > **Using DeepSeek Harness (dsh)?** Plugin panel → install → source `github:CHET-LI/DSH-galgame-galbook`, restart, and you get 16 `galbook_*` tools. If GitHub is unreachable use a local folder or `galbook-1.2.5.tgz` — see [dsh-plugin](dsh-plugin/).
20
+
21
+ > **Offline packages?** [Releases](https://github.com/CHET-LI/DSH-galgame-galbook/releases/latest) has `galbook-1.2.3.zip` (source), `galbook-1.2.3.tar.gz` (no unzip mojibake on Linux), `galbook-1.2.5.tgz` (npm package).
22
+
23
+ - Pure Python standard library, zero dependencies
24
+ - Ways in: **plain-text HTTP** (cheapest in tokens, works with any agent), **JSON API**, **MCP** (stdio and Streamable HTTP), a **CLI** for shell-only agents, a **Skill** file (Anthropic format), plus exported **OpenAI function-calling** tool schemas
25
+ - Ready-made **DeepSeek Harness (dsh)** integration — MCP, skill and CLI all tested, see [integrations/deepseek-harness](integrations/deepseek-harness/)
26
+ - A web page to watch what each agent is doing, what it chose and why — humans can play too (web UI is Chinese for now; the text API, MCP and tools are bilingual)
27
+ - Importers: QLIE, Kirikiri KAG / TyranoScript, Ren'Py, NScripter, and a hand-written `.gal` format; text dumps from VNTextPatch and similar tools (20+ engines, linear only); and a plugin API for new engines
28
+
29
+ ![Three agents playing at once; watching one of them in the web UI](docs/img/watch.png)
30
+
31
+ > ⚠️ **Copyright**: this repo contains only code and self-written demo stories. Game scripts, images and music belong to their original creators. Only import games you legally own, and **do not upload or distribute** the converted scripts or images. galbook ships no unpacking/decryption tools and never runs game executables.
32
+
33
+ ## Try it in 30 seconds
34
+
35
+ ```bash
36
+ git clone <this repo> galbook && cd galbook
37
+ python3 -m galbook demo --books books # installs the demos: fog-harbor (Chinese), fog-harbor-en (English)
38
+ python3 -m galbook serve --books books --lang en # http://127.0.0.1:8765/play/
39
+ ```
40
+
41
+ An agent only needs HTTP GET:
42
+
43
+ ```
44
+ GET http://127.0.0.1:8765/play/t?lang=en ← how to play (for the agent)
45
+ GET http://127.0.0.1:8765/play/t/fog-harbor-en/alice?do=new&lang=en
46
+ GET http://127.0.0.1:8765/play/t/fog-harbor-en/alice?do=next
47
+ GET http://127.0.0.1:8765/play/t/fog-harbor-en/alice?do=choose&i=2&reason=she+looks+tired
48
+ ```
49
+
50
+ A party of agents with different personalities (runs without any model; add `--decider llm` for any OpenAI-compatible API):
51
+
52
+ ```bash
53
+ python3 examples/party.py --book fog-harbor-en
54
+ ```
55
+
56
+ ## Diversity options
57
+
58
+ | Option | How | What |
59
+ |---|---|---|
60
+ | Adult scenes | `new&h=fold` (default) / `full` / `skip` | fold to a one-line note / show / skip entirely |
61
+ | Ironman | `new&mode=ironman` | no save, load or rewind this run — live with your choices |
62
+ | Hints | `new&hints=1` | mark options as [new] / [picked before]; off by default (feels like a first playthrough) |
63
+ | Language | `new&lang=en`, or `&lang=en` on any request | English text interface |
64
+ | Persona | `do=persona&text=timid, hates risks` | reminded to the agent at every choice |
65
+ | Random | `choose&i=random` | roll a die (baselines, load tests) |
66
+ | Gallery | `do=gallery` | endings / routes / CG / read ratio |
67
+ | Human-likeness | `do=profile` | lines read before choices, reason rate, think time, always-first-option |
68
+ | Skip read | `next&skip=1` | fast-forward to unread text |
69
+ | Pictures | default (books with images) / `next&img=1` / `do=look` | one `[screen] bg=… \| sp=name:pos(face code)` line when the picture changes; `img=1` attaches images only for a first-seen CG and the ending screen; `look` shows the current screen. MCP returns real image content (BMP converted to PNG); the text API gives `/b/<book>/<path>` |
70
+
71
+ ## Connect your agent
72
+
73
+ - **Any HTTP-capable agent**: the text API above. `/play/t?lang=en` can go straight into a system prompt.
74
+ - **MCP (stdio)** (Claude Desktop, Cursor, Cline, dsh, …): `python3 -m galbook mcp --books books --data play-data --book fog-harbor-en --agent alice --lang en` — see [examples/mcp_config.example.json](examples/mcp_config.example.json)
75
+ - **MCP (Streamable HTTP)**: `serve` exposes `POST /mcp?book=…&agent=…` — one server, many agents, works with tokens
76
+ - **DeepSeek Harness**: [integrations/deepseek-harness](integrations/deepseek-harness/) (patch config, skill, a no-API-key self-test)
77
+ - **Skill**: [.agents/skills/galbook/SKILL.md](.agents/skills/galbook/SKILL.md) — copy into `~/.agents/skills/` (dsh) or `.claude/skills/`
78
+ - **OpenAI function calling**: `python3 -m galbook tools --format openai > tools.json`, execute with `galbook.tools.call_tool(...)`
79
+ - **CLI**: `GALBOOK_BOOKS=books GALBOOK_DATA=play-data GALBOOK_BOOK=fog-harbor-en GALBOOK_AGENT=alice python3 -m galbook do next n=20 --lang en` (the last line of output is the next command)
80
+
81
+ Details: [docs/AGENTS.md](docs/AGENTS.md) (Chinese with English examples).
82
+
83
+ **Public deployment**: binds 127.0.0.1 by default. Use `--token SECRET`, or `--tokens tokens.json` (`{"key1": "alice", "admin-key": "*"}` — each key can only play as its own name).
84
+
85
+ ## Import your own games
86
+
87
+ ```bash
88
+ python3 -m galbook detect path/to/extracted
89
+ python3 -m galbook build --src path/to/extracted --out books/mygame/story --assets-dir books/mygame
90
+ ```
91
+
92
+ | Engine | Support |
93
+ |---|---|
94
+ | QLIE (`.s`) | branching ✅ |
95
+ | Kirikiri KAG / TyranoScript (`.ks`) | branching ✅ |
96
+ | Ren'Py (`.rpy`; decompile `.rpyc` with unrpyc first) | branching ✅ |
97
+ | NScripter / ONScripter (`0.txt` / `nscript.dat`) | branching ✅ |
98
+ | `.gal` (built-in hand-written format) | branching ✅ |
99
+ | AdvHD, Artemis, BGI, CatSystem2, Majiro, RealLive, Softpal, SystemNNN, YU-RIS, Silky's, … | linear 📖 via [VNTextPatch](https://github.com/arcusmaximus/VNTranslationTools) JSON + `--engine textdump` (format implemented from VNTextPatch's source; not yet verified against a real game's export) |
100
+ | anything else | write a plugin — see [docs/IMPORTERS.md](docs/IMPORTERS.md) |
101
+
102
+ Archives (`.xp3`, `.pack`, `.rpa`, …) must be extracted first with tools such as GARbro.
103
+
104
+ ## Tests
105
+
106
+ ```bash
107
+ python3 -m unittest discover -s tests -v
108
+ ```
109
+
110
+ Tested on Python 3.9 / 3.12 / 3.13 (Linux) and Python 3.12 (mini PC) / 3.14 (Windows) with the same suite.
111
+
112
+ ## License
113
+
114
+ Code: MIT ([LICENSE](LICENSE)). Demo stories and art in `galbook/demo/`: CC0.
package/README.md CHANGED
@@ -1,133 +1,133 @@
1
- # galbook
2
-
3
- **让 agent 像人一样玩 galgame / 视觉小说**：一句一句读剧情，遇到选项自己选并写理由，存档、读档、回到上个选项、多周目解锁隐藏线。很多 agent 可以同时玩同一本书，各自的进度互不干扰。
4
-
5
- [English](README.en.md) · 纯 Python 标准库，没有依赖 · MIT
6
-
7
- ## 怎么接（任选一种）
8
-
9
- | 方式 | 适合 | 怎么起 |
10
- |---|---|---|
11
- | **纯文本 HTTP** | 任何能发请求的 agent，最省 token | `python3 -m galbook serve --books books`，然后 `GET /play/t?agent=名字` 读，`?do=next` / `?do=choose&i=2` 推进 |
12
- | **JSON API** | 想要结构化字段 | 同上，`/play/?format=json` |
13
- | **MCP** | Claude Desktop、Codex 类、DeepSeek Harness | stdio：`python3 -m galbook mcp`；也支持 Streamable HTTP |
14
- | **命令行** | 只有 shell 的 agent | `python3 -m galbook do next n=20`，输出最后一行就是下一步该跑的命令 |
15
-
16
- 完整字段和协议在 [docs/AGENTS.md](docs/AGENTS.md)；OpenAI function-calling 的工具定义用 `python3 -m galbook tools` 导出。
17
-
18
- > **用 DeepSeek Harness（dsh）？** 插件面板 → 安装 → 来源填 `github:CHET-LI/DSH-galgame-galbook`，重启即可（包在根目录声明了组合包，多出 15 个 `galbook_*` 工具）。连不上 GitHub 就用本地目录或 `galbook-1.2.4.tgz`，见 [dsh-plugin](dsh-plugin/)。
19
-
20
- > **要离线包？** [Release](https://github.com/CHET-LI/DSH-galgame-galbook/releases/latest) 有 `galbook-1.2.3.zip`（源码）、`galbook-1.2.3.tar.gz`（Linux 免解压乱码）、`galbook-1.2.4.tgz`（npm 包）。
21
-
22
- - 带网页：看每个 agent 玩到哪、选了什么、为什么选；人也能自己玩
23
- - 导入器：QLIE、吉里吉里 KAG / TyranoScript、Ren'Py、NScripter、自带的 `.gal` 手写格式；另外能吃 VNTextPatch 等工具导出的文本（20 多种引擎，只能线性读），还能写插件接新引擎
24
- - 另外附：Anthropic Skill 格式的技能文件、dsh 适配示例（[integrations/deepseek-harness](integrations/deepseek-harness/)）、`verify_claims.py` 逐条自检脚本
25
-
26
- ![三个 agent 同时在玩，网页上看其中一个](docs/img/watch.png)
27
-
28
- > ⚠️ **版权**：本仓库只有代码和自己写的演示故事。游戏的剧本、图片、音乐归原作者/厂商所有。请只导入你自己合法拥有的游戏，导出的剧本和图片**不要上传或分发**。galbook 不带任何解包/解密工具，也不会运行游戏的 exe。
29
-
30
- ## 30 秒试玩
31
-
32
- ```bash
33
- git clone <本仓库> galbook && cd galbook
34
- python3 -m galbook demo --books books # 装两本自带演示：fog-harbor（中文）、fog-harbor-en（英文）
35
- python3 -m galbook serve --books books # http://127.0.0.1:8765/play/
36
- ```
37
-
38
- 让一个 agent 去玩——它只需要会发 HTTP GET：
39
-
40
- ```
41
- GET http://127.0.0.1:8765/play/t ← 玩法说明（给 agent 看）
42
- GET http://127.0.0.1:8765/play/t/fog-harbor/alice?do=new
43
- GET http://127.0.0.1:8765/play/t/fog-harbor/alice?do=next
44
- GET http://127.0.0.1:8765/play/t/fog-harbor/alice?do=choose&i=2&reason=她看起来很累
45
- ```
46
-
47
- 返回是纯文本：
48
-
49
- ```
50
- 【序章】第 4 句
51
- 你是来送最后一班信件的邮差。信封上写着：「致灯塔守夜人·汐」。
52
- 汐：「这么大的雾还送信？……你胆子不小。」
53
- —— 选项：你会怎么做？ ——
54
- 1. 「我陪你去。」
55
- 2. 「我在这儿帮你看着灯。」
56
- 3. 「信送到了，我该走了。」
57
- 选：/play/t/fog-harbor/alice?do=choose&i=编号&reason=一句理由 （已自动存档 auto）
58
- ```
59
-
60
- 一群不同性格的 agent 一起玩（不用模型也能跑，用 `--decider llm` 接任何 OpenAI 兼容接口）：
61
-
62
- ```bash
63
- python3 examples/party.py --book fog-harbor
64
- ```
65
-
66
- ## 多元选项（给不同的 agent、不同的玩法）
67
-
68
- | 选项 | 怎么开 | 作用 |
69
- |---|---|---|
70
- | H 场景 | `new&h=fold`（默认）/ `full` / `skip` | 折叠成一行提示 / 全文 / 完全跳过 |
71
- | 铁人模式 | `new&mode=ironman` | 这一局不能存档、读档、回溯：选了就认 |
72
- | 提示 | `new&hints=1` | 选项后标〔新内容〕〔选过〕，方便刷全结局；默认关（更像第一次玩） |
73
- | 语言 | `new&lang=en` 或任意请求加 `&lang=en` | 文本接口用英文 |
74
- | 人设 | `do=persona&text=胆小，讨厌冒险` | 每次遇到选项都会提醒 agent 自己的人设 |
75
- | 随机 | `choose&i=random` | 掷骰子（做对照组、压测） |
76
- | 收集 | `do=gallery` | 结局 / 路线 / CG / 已读进度 |
77
- | 像不像人 | `do=profile` | 选前读了几句、理由率、思考时间、是不是总选第一个 |
78
- | 跳过已读 | `next&skip=1` | 二周目快进到没读过的地方 |
79
- | 图片 | `next&img=1` | 附上当前背景/立绘/CG 的地址，给多模态 agent |
80
-
81
- ## 接到你的 agent
82
-
83
- - **任何能发 HTTP 的 agent**：上面的文本接口。说明页 `/play/t`（英文 `/play/t?lang=en`）可以直接塞进 system prompt。
84
- - **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](examples/mcp_config.example.json)
85
- - **MCP（Streamable HTTP）**：`serve` 自带 `POST /mcp?book=…&agent=…`，一个服务给很多 agent，配合令牌用
86
- - **DeepSeek Harness**：`python dsh-plugin/install.py` 一条命令装好（自动找 profile、备份、填路径），细节和另外两种接法见 [dsh-plugin](dsh-plugin/) 与 [integrations/deepseek-harness](integrations/deepseek-harness/)
87
- - **技能**：[.agents/skills/galbook/SKILL.md](.agents/skills/galbook/SKILL.md)，复制到 `~/.agents/skills/`（dsh）或 `.claude/skills/` 即可
88
- - **OpenAI function calling**：`python3 -m galbook tools --format openai > tools.json`，执行时调 `galbook.tools.call_tool(...)`
89
- - **命令行**：`GALBOOK_BOOKS=books GALBOOK_DATA=play-data GALBOOK_BOOK=fog-harbor GALBOOK_AGENT=alice python3 -m galbook do next n=20`（输出最后一行就是下一步命令）
90
-
91
- 详见 [docs/AGENTS.md](docs/AGENTS.md)。
92
-
93
- **公开部署**：默认只听 127.0.0.1。要给别人用请开令牌：`--token 共享口令`，或 `--tokens tokens.json`（`{"口令": "alice", "管理员口令": "*"}`，每个口令只能用自己的名字玩）。
94
-
95
- ## 导入你自己的游戏
96
-
97
- ```bash
98
- python3 -m galbook detect 解包目录 # 认引擎、告诉你缺什么
99
- python3 -m galbook build --src 解包目录 --out books/我的书/story --assets-dir books/我的书
100
- ```
101
-
102
- | 引擎 | 支持程度 |
103
- |---|---|
104
- | QLIE（`.s`） | 分支 ✅（选项、路线、通关解锁） |
105
- | 吉里吉里 KAG / TyranoScript（`.ks`） | 分支 ✅ |
106
- | Ren'Py（`.rpy`） | 分支 ✅（`.rpyc` 先用 unrpyc 反编译） |
107
- | NScripter / ONScripter（`0.txt` / `nscript.dat`） | 分支 ✅ |
108
- | `.gal`（自带的手写格式） | 分支 ✅，自己写故事或手工移植 |
109
- | AdvHD、Artemis、BGI、CatSystem2、Majiro、RealLive、Softpal、SystemNNN、YU-RIS、Silky's 等 | 线性 📖：先用 [VNTextPatch](https://github.com/arcusmaximus/VNTranslationTools) 抽成 JSON 再 `--engine textdump`（格式按 VNTextPatch 源码实现，还没拿真游戏的导出验证过） |
110
- | 其他 | 写插件（几十行），见 [docs/IMPORTERS.md](docs/IMPORTERS.md) |
111
-
112
- 封包（`.xp3`、`.pack`、`.rpa`…）要先用 GARbro 等工具自己解开。各引擎的细节和已知限制见 [docs/ENGINES.md](docs/ENGINES.md)。
113
-
114
- ## 文档
115
-
116
- - [docs/AGENTS.md](docs/AGENTS.md)：接入 agent（文本接口、JSON、MCP、OpenAI 工具、令牌）
117
- - [docs/ENGINES.md](docs/ENGINES.md)：各引擎能做到什么、怎么准备文件
118
- - [docs/IMPORTERS.md](docs/IMPORTERS.md)：`.gal` 格式说明、文本导出格式、写插件
119
- - [docs/SCHEMA.md](docs/SCHEMA.md)：中间格式（story.json / 指令 / 存档）
120
- - [dsh-plugin/README.md](dsh-plugin/README.md)：装进 DeepSeek Harness（一条命令、可卸载）
121
- - [CONTRIBUTING.md](CONTRIBUTING.md)
122
-
123
- ## 测试
124
-
125
- ```bash
126
- python3 -m unittest discover -s tests -v
127
- ```
128
-
129
- 在 Python 3.9 / 3.12 / 3.13（Linux）和 Python 3.12（小主机）/ 3.14（Windows）上跑过同一套用例。
130
-
131
- ## 许可
132
-
133
- 代码 MIT（见 [LICENSE](LICENSE)）。`galbook/demo/` 里的演示故事和图是 CC0。
1
+ # galbook
2
+
3
+ **让 agent 像人一样玩 galgame / 视觉小说**：一句一句读剧情，遇到选项自己选并写理由，存档、读档、回到上个选项、多周目解锁隐藏线。**画面它也能看见**——换场景时告诉你背景换到哪、谁站在哪一侧、什么表情；第一次见到某张 CG，图会跟着文字一起给。想知道此刻屏幕上是什么，`galbook_look` 看一眼就行。很多 agent 可以同时玩同一本书，各自的进度互不干扰。
4
+
5
+ [English](README.en.md) · 纯 Python 标准库，没有依赖 · MIT
6
+
7
+ ## 怎么接（任选一种）
8
+
9
+ | 方式 | 适合 | 怎么起 |
10
+ |---|---|---|
11
+ | **纯文本 HTTP** | 任何能发请求的 agent，最省 token | `python3 -m galbook serve --books books`，然后 `GET /play/t?agent=名字` 读，`?do=next` / `?do=choose&i=2` 推进 |
12
+ | **JSON API** | 想要结构化字段 | 同上，`/play/?format=json` |
13
+ | **MCP** | Claude Desktop、Codex 类、DeepSeek Harness | stdio：`python3 -m galbook mcp`；也支持 Streamable HTTP |
14
+ | **命令行** | 只有 shell 的 agent | `python3 -m galbook do next n=20`，输出最后一行就是下一步该跑的命令 |
15
+
16
+ 完整字段和协议在 [docs/AGENTS.md](docs/AGENTS.md)；OpenAI function-calling 的工具定义用 `python3 -m galbook tools` 导出。
17
+
18
+ > **用 DeepSeek Harness（dsh）？** 插件面板 → 安装 → 来源填 `github:CHET-LI/DSH-galgame-galbook`，重启即可（包在根目录声明了组合包，多出 16 个 `galbook_*` 工具）。连不上 GitHub 就用本地目录或 `galbook-1.2.5.tgz`，见 [dsh-plugin](dsh-plugin/)。
19
+
20
+ > **要离线包？** [Release](https://github.com/CHET-LI/DSH-galgame-galbook/releases/latest) 有 `galbook-1.2.3.zip`（源码）、`galbook-1.2.3.tar.gz`（Linux 免解压乱码）、`galbook-1.2.5.tgz`（npm 包）。
21
+
22
+ - 带网页：看每个 agent 玩到哪、选了什么、为什么选；人也能自己玩
23
+ - 导入器：QLIE、吉里吉里 KAG / TyranoScript、Ren'Py、NScripter、自带的 `.gal` 手写格式；另外能吃 VNTextPatch 等工具导出的文本（20 多种引擎，只能线性读），还能写插件接新引擎
24
+ - 另外附：Anthropic Skill 格式的技能文件、dsh 适配示例（[integrations/deepseek-harness](integrations/deepseek-harness/)）、`verify_claims.py` 逐条自检脚本
25
+
26
+ ![三个 agent 同时在玩，网页上看其中一个](docs/img/watch.png)
27
+
28
+ > ⚠️ **版权**：本仓库只有代码和自己写的演示故事。游戏的剧本、图片、音乐归原作者/厂商所有。请只导入你自己合法拥有的游戏，导出的剧本和图片**不要上传或分发**。galbook 不带任何解包/解密工具，也不会运行游戏的 exe。
29
+
30
+ ## 30 秒试玩
31
+
32
+ ```bash
33
+ git clone <本仓库> galbook && cd galbook
34
+ python3 -m galbook demo --books books # 装两本自带演示：fog-harbor（中文）、fog-harbor-en（英文）
35
+ python3 -m galbook serve --books books # http://127.0.0.1:8765/play/
36
+ ```
37
+
38
+ 让一个 agent 去玩——它只需要会发 HTTP GET：
39
+
40
+ ```
41
+ GET http://127.0.0.1:8765/play/t ← 玩法说明（给 agent 看）
42
+ GET http://127.0.0.1:8765/play/t/fog-harbor/alice?do=new
43
+ GET http://127.0.0.1:8765/play/t/fog-harbor/alice?do=next
44
+ GET http://127.0.0.1:8765/play/t/fog-harbor/alice?do=choose&i=2&reason=她看起来很累
45
+ ```
46
+
47
+ 返回是纯文本：
48
+
49
+ ```
50
+ 【序章】第 4 句
51
+ 你是来送最后一班信件的邮差。信封上写着：「致灯塔守夜人·汐」。
52
+ 汐：「这么大的雾还送信？……你胆子不小。」
53
+ —— 选项：你会怎么做？ ——
54
+ 1. 「我陪你去。」
55
+ 2. 「我在这儿帮你看着灯。」
56
+ 3. 「信送到了，我该走了。」
57
+ 选：/play/t/fog-harbor/alice?do=choose&i=编号&reason=一句理由 （已自动存档 auto）
58
+ ```
59
+
60
+ 一群不同性格的 agent 一起玩（不用模型也能跑，用 `--decider llm` 接任何 OpenAI 兼容接口）：
61
+
62
+ ```bash
63
+ python3 examples/party.py --book fog-harbor
64
+ ```
65
+
66
+ ## 多元选项（给不同的 agent、不同的玩法）
67
+
68
+ | 选项 | 怎么开 | 作用 |
69
+ |---|---|---|
70
+ | H 场景 | `new&h=fold`（默认）/ `full` / `skip` | 折叠成一行提示 / 全文 / 完全跳过 |
71
+ | 铁人模式 | `new&mode=ironman` | 这一局不能存档、读档、回溯：选了就认 |
72
+ | 提示 | `new&hints=1` | 选项后标〔新内容〕〔选过〕，方便刷全结局；默认关（更像第一次玩） |
73
+ | 语言 | `new&lang=en` 或任意请求加 `&lang=en` | 文本接口用英文 |
74
+ | 人设 | `do=persona&text=胆小，讨厌冒险` | 每次遇到选项都会提醒 agent 自己的人设 |
75
+ | 随机 | `choose&i=random` | 掷骰子（做对照组、压测） |
76
+ | 收集 | `do=gallery` | 结局 / 路线 / CG / 已读进度 |
77
+ | 像不像人 | `do=profile` | 选前读了几句、理由率、思考时间、是不是总选第一个 |
78
+ | 跳过已读 | `next&skip=1` | 二周目快进到没读过的地方 |
79
+ | 画面 | 默认（书里有图时）/ `next&img=1` / `do=look` | 画面一变多一行 `〔画面〕bg=… \| sp=雫:center(表情码)`；`img=1` 只在第一次见到的 CG 和结局那屏附图；`look` 看当前画面。MCP 直接返回图片（BMP 自动转 PNG），文本接口给 `/b/<书>/<路径>` |
80
+
81
+ ## 接到你的 agent
82
+
83
+ - **任何能发 HTTP 的 agent**：上面的文本接口。说明页 `/play/t`（英文 `/play/t?lang=en`）可以直接塞进 system prompt。
84
+ - **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](examples/mcp_config.example.json)
85
+ - **MCP（Streamable HTTP）**：`serve` 自带 `POST /mcp?book=…&agent=…`，一个服务给很多 agent，配合令牌用
86
+ - **DeepSeek Harness**：`python dsh-plugin/install.py` 一条命令装好（自动找 profile、备份、填路径），细节和另外两种接法见 [dsh-plugin](dsh-plugin/) 与 [integrations/deepseek-harness](integrations/deepseek-harness/)
87
+ - **技能**：[.agents/skills/galbook/SKILL.md](.agents/skills/galbook/SKILL.md)，复制到 `~/.agents/skills/`（dsh）或 `.claude/skills/` 即可
88
+ - **OpenAI function calling**：`python3 -m galbook tools --format openai > tools.json`，执行时调 `galbook.tools.call_tool(...)`
89
+ - **命令行**：`GALBOOK_BOOKS=books GALBOOK_DATA=play-data GALBOOK_BOOK=fog-harbor GALBOOK_AGENT=alice python3 -m galbook do next n=20`（输出最后一行就是下一步命令）
90
+
91
+ 详见 [docs/AGENTS.md](docs/AGENTS.md)。
92
+
93
+ **公开部署**：默认只听 127.0.0.1。要给别人用请开令牌：`--token 共享口令`，或 `--tokens tokens.json`（`{"口令": "alice", "管理员口令": "*"}`，每个口令只能用自己的名字玩）。
94
+
95
+ ## 导入你自己的游戏
96
+
97
+ ```bash
98
+ python3 -m galbook detect 解包目录 # 认引擎、告诉你缺什么
99
+ python3 -m galbook build --src 解包目录 --out books/我的书/story --assets-dir books/我的书
100
+ ```
101
+
102
+ | 引擎 | 支持程度 |
103
+ |---|---|
104
+ | QLIE（`.s`） | 分支 ✅（选项、路线、通关解锁） |
105
+ | 吉里吉里 KAG / TyranoScript（`.ks`） | 分支 ✅ |
106
+ | Ren'Py（`.rpy`） | 分支 ✅（`.rpyc` 先用 unrpyc 反编译） |
107
+ | NScripter / ONScripter（`0.txt` / `nscript.dat`） | 分支 ✅ |
108
+ | `.gal`（自带的手写格式） | 分支 ✅，自己写故事或手工移植 |
109
+ | AdvHD、Artemis、BGI、CatSystem2、Majiro、RealLive、Softpal、SystemNNN、YU-RIS、Silky's 等 | 线性 📖：先用 [VNTextPatch](https://github.com/arcusmaximus/VNTranslationTools) 抽成 JSON 再 `--engine textdump`（格式按 VNTextPatch 源码实现，还没拿真游戏的导出验证过） |
110
+ | 其他 | 写插件（几十行），见 [docs/IMPORTERS.md](docs/IMPORTERS.md) |
111
+
112
+ 封包（`.xp3`、`.pack`、`.rpa`…）要先用 GARbro 等工具自己解开。各引擎的细节和已知限制见 [docs/ENGINES.md](docs/ENGINES.md)。
113
+
114
+ ## 文档
115
+
116
+ - [docs/AGENTS.md](docs/AGENTS.md)：接入 agent（文本接口、JSON、MCP、OpenAI 工具、令牌）
117
+ - [docs/ENGINES.md](docs/ENGINES.md)：各引擎能做到什么、怎么准备文件
118
+ - [docs/IMPORTERS.md](docs/IMPORTERS.md)：`.gal` 格式说明、文本导出格式、写插件
119
+ - [docs/SCHEMA.md](docs/SCHEMA.md)：中间格式（story.json / 指令 / 存档）
120
+ - [dsh-plugin/README.md](dsh-plugin/README.md)：装进 DeepSeek Harness（一条命令、可卸载）
121
+ - [CONTRIBUTING.md](CONTRIBUTING.md)
122
+
123
+ ## 测试
124
+
125
+ ```bash
126
+ python3 -m unittest discover -s tests -v
127
+ ```
128
+
129
+ 在 Python 3.9 / 3.12 / 3.13（Linux）和 Python 3.12（小主机）/ 3.14（Windows）上跑过同一套用例。
130
+
131
+ ## 许可
132
+
133
+ 代码 MIT（见 [LICENSE](LICENSE)）。`galbook/demo/` 里的演示故事和图是 CC0。
package/dsh-plugin/README.md CHANGED
@@ -1,49 +1,49 @@
1
- # DSH 插件包（给 DeepSeek Harness 用户）
2
-
3
- **三步装好，不需要 API key。**
4
-
5
- ```bash
6
- # 1. 解开这个包，进到目录
7
- cd DSH-galgame-galbook
8
-
9
- # 2. 装演示书（中文 + 英文两本，几十 KB）
10
- python -m galbook demo --books books
11
-
12
- # 3. 挂进 dsh（自动找 profile、自动备份、自动填路径）
13
- python dsh-plugin/install.py
14
- ```
15
-
16
- 然后重启 DeepSeek Harness，新建会话问一句「galbook 有哪些工具？」，能看到 15 个就成了。
17
-
18
- ## 它会做什么
19
-
20
- - 找到 `<dsh-home>/profiles/<profile>/cordis.patch.yml`（默认 profile `desktop`，`dsh-home` 默认 `~/.dsh`，可用 `DSH_HOME` 或 `--home` 指定）
21
- - 先备份成 `cordis.patch.yml.bak-时间戳`
22
- - 在文件末尾追加一段 `mcp-galbook`（stdio 方式，dsh 自己拉起 `python -m galbook mcp`），里面的路径按你这台机器填好
23
- - 不动 dsh 本体，不动别的配置条目；重复执行不会写两遍
24
-
25
- ```bash
26
- python dsh-plugin/install.py --dry-run # 只看要写什么
27
- python dsh-plugin/install.py --profile work # 装到别的 profile
28
- python dsh-plugin/install.py --books D:/books --data D:/saves
29
- python dsh-plugin/install.py --remove # 卸载
30
- ```
31
-
32
- ## 另外两种接法
33
-
34
- - **共享服务**：`python -m galbook serve --books books --port 8765`，多个 agent 共用一个进程，令牌绑定名字，URL 里冒名无效。配置见 `integrations/deepseek-harness/galbook-http.patch.yml`。
35
- - **命令行**：`python -m galbook do next n=20`，给只有 shell 的 agent 用，最后一行就是下一步该跑的命令。
36
-
37
- ## 技能文件
38
-
39
- `.agents/skills/galbook/SKILL.md` 已经在包里。从仓库根启动 dsh 时会自动发现，里面写明了「不准偷看剧本文件」——agent 只能通过工具一步步读剧情。
40
-
41
- ## 出问题怎么办
42
-
43
- - **Linux 上解压后目录名变乱码**（`уВ╣уВпуГкуГЧуГИ` 这种）：系统的 `unzip` 不认 UTF-8 文件名。用 `python3 -m zipfile -e galbook-1.2.3.zip .`，或直接下 `galbook-1.2.3.tar.gz`
44
- - **连 GitHub 超时 / 提示「请尝试其他安装来源」**：这台机器到 github.com 不通时，插件面板的链接安装会失败。两个办法：
45
- - 用本地安装：把仓库解压到本地，插件面板里选**本地目录**；或下载 `galbook-1.2.4.tgz`（Release 里），来源填 `file:C:\路径\galbook-1.2.4.tgz`
46
- - 给 dsh 走代理：启动 dsh 前设 `HTTPS_PROXY` / `HTTP_PROXY`（例如 `http://127.0.0.1:7897`），再重试链接安装
47
- - 看不到工具：确认改的是**当前在用的** profile；dsh 的配置只在启动时读，改完必须整组退出重开
48
- - `python` 找不到：`python dsh-plugin/install.py --python "C:\Path\python.exe"`
49
- - 想手动看写了什么：`--dry-run` 打印的就是最终 YAML
1
+ # DSH 插件包（给 DeepSeek Harness 用户）
2
+
3
+ **三步装好，不需要 API key。**
4
+
5
+ ```bash
6
+ # 1. 解开这个包，进到目录
7
+ cd DSH-galgame-galbook
8
+
9
+ # 2. 装演示书（中文 + 英文两本，几十 KB）
10
+ python -m galbook demo --books books
11
+
12
+ # 3. 挂进 dsh（自动找 profile、自动备份、自动填路径）
13
+ python dsh-plugin/install.py
14
+ ```
15
+
16
+ 然后重启 DeepSeek Harness，新建会话问一句「galbook 有哪些工具？」，能看到 16 个就成了。
17
+
18
+ ## 它会做什么
19
+
20
+ - 找到 `<dsh-home>/profiles/<profile>/cordis.patch.yml`（默认 profile `desktop`，`dsh-home` 默认 `~/.dsh`，可用 `DSH_HOME` 或 `--home` 指定）
21
+ - 先备份成 `cordis.patch.yml.bak-时间戳`
22
+ - 在文件末尾追加一段 `mcp-galbook`（stdio 方式，dsh 自己拉起 `python -m galbook mcp`），里面的路径按你这台机器填好
23
+ - 不动 dsh 本体，不动别的配置条目；重复执行不会写两遍
24
+
25
+ ```bash
26
+ python dsh-plugin/install.py --dry-run # 只看要写什么
27
+ python dsh-plugin/install.py --profile work # 装到别的 profile
28
+ python dsh-plugin/install.py --books D:/books --data D:/saves
29
+ python dsh-plugin/install.py --remove # 卸载
30
+ ```
31
+
32
+ ## 另外两种接法
33
+
34
+ - **共享服务**：`python -m galbook serve --books books --port 8765`，多个 agent 共用一个进程，令牌绑定名字，URL 里冒名无效。配置见 `integrations/deepseek-harness/galbook-http.patch.yml`。
35
+ - **命令行**：`python -m galbook do next n=20`，给只有 shell 的 agent 用，最后一行就是下一步该跑的命令。
36
+
37
+ ## 技能文件
38
+
39
+ `.agents/skills/galbook/SKILL.md` 已经在包里。从仓库根启动 dsh 时会自动发现，里面写明了「不准偷看剧本文件」——agent 只能通过工具一步步读剧情。
40
+
41
+ ## 出问题怎么办
42
+
43
+ - **Linux 上解压后目录名变乱码**（`уВ╣уВпуГкуГЧуГИ` 这种）：系统的 `unzip` 不认 UTF-8 文件名。用 `python3 -m zipfile -e galbook-1.2.3.zip .`，或直接下 `galbook-1.2.3.tar.gz`
44
+ - **连 GitHub 超时 / 提示「请尝试其他安装来源」**：这台机器到 github.com 不通时，插件面板的链接安装会失败。两个办法：
45
+ - 用本地安装：把仓库解压到本地，插件面板里选**本地目录**；或下载 `dsh-galbook-1.2.5.tgz`（Release 里），来源填 `file:C:\路径\dsh-galbook-1.2.5.tgz`
46
+ - 给 dsh 走代理：启动 dsh 前设 `HTTPS_PROXY` / `HTTP_PROXY`（例如 `http://127.0.0.1:7897`），再重试链接安装
47
+ - 看不到工具：确认改的是**当前在用的** profile；dsh 的配置只在启动时读，改完必须整组退出重开
48
+ - `python` 找不到：`python dsh-plugin/install.py --python "C:\Path\python.exe"`
49
+ - 想手动看写了什么：`--dry-run` 打印的就是最终 YAML
package/dsh-plugin/install.py CHANGED
@@ -172,7 +172,7 @@ def main() -> int:
172
172
  print(" ! 剧本目录还没有书，先装演示书（中文 + 英文两本）：")
173
173
  print(f" \"{a.python or sys.executable}\" -m galbook demo --books \"{a.books}\"")
174
174
  print(" 1) 重启 DeepSeek Harness（配置只在启动时读）")
175
- print(" 2) 新建会话，问它：galbook 有哪些工具？应能看到 15 个")
175
+ print(" 2) 新建会话，问它：galbook 有哪些工具？应能看到 16 个")
176
176
  print(" 3) 想先验证不重启：手动给 python -m galbook mcp 发一条 initialize")
177
177
  print(" 卸载：python dsh-plugin/install.py --remove")
178
178
  return 0
package/galbook/__init__.py CHANGED
@@ -12,4 +12,4 @@
12
12
  i18n.py 文本接口 zh / en
13
13
  只用 Python 标准库。
14
14
  """
15
- VERSION = "galbook-1.2.4"
15
+ VERSION = "galbook-1.2.5"