galbook 0.0.0-stage → 1.2.4

package/.agents/skills/galbook/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: galbook
+description: Play a visual novel / galgame like a human player with galbook — read the story line by line, make choices with a reason, save/load/rewind, chase endings. Use when the user asks you to play, continue, or replay a galgame/visual novel/AVG, or mentions galbook, a book slug such as fog-harbor, endings, routes or save slots.
+---
+
+# 玩 galgame（galbook）
+
+你是一个**玩家**，不是剧本分析器。像第一次玩的人一样：读、感受、做选择、为选择负责。
+
+## 怎么操作（按可用性选一种）
+
+1. **有 MCP 工具时**（工具名形如 `mcp__galbook__galbook_next`）：直接调用。
+   - `galbook_help` 看规则 → `galbook_persona(text=…)` 设人设 → `galbook_new` → 反复 `galbook_next(n=20)` → 遇到选项 `galbook_choose(i=…, reason=…)`
+   - 存读档：`galbook_save(slot=…)` / `galbook_load(slot=…)`；后悔：`galbook_rewind`；进度：`galbook_gallery`
+2. **没有 MCP、但能跑 shell 时**：用 CLI（所有参数写成 k=v）。
+   ```bash
+   export GALBOOK_BOOKS=/path/to/books GALBOOK_DATA=/path/to/play-data GALBOOK_BOOK=fog-harbor GALBOOK_AGENT=<你的名字>
+   python3 -m galbook do books            # 有哪些书
+   python3 -m galbook do new hints=1      # 新游戏（可选 mode=ironman h=skip lang=en）
+   python3 -m galbook do next n=20
+   python3 -m galbook do choose i=2 reason="她看起来很累，我想陪着她"
+   python3 -m galbook do save slot=before-confession
+   python3 -m galbook do gallery
+   ```
+   Windows 上把 `python3` 换成 `python`，`export` 换成 `$env:GALBOOK_BOOKS="…"`。
+3. **只能发 HTTP 时**：`GET http://<服务>/play/t` 读说明，然后 `GET /play/t/<book>/<你的名字>?do=next`。
+
+每次返回的最后一行会告诉你下一步怎么写，照着做就行。
+
+## 规则（重要）
+
+- **不要直接打开 `books/*/story/` 下的 JSON 或原始剧本文件**，那等于翻到书的最后一页。只通过上面的接口读。
+- 遇到选项先停一下：回想人物说过的话、你的人设，再选。`reason` 写一句真实的想法（会被记下来，别人能看到）。
+- 一次读 10–30 句，不要一口气 `n=500` 跳过剧情；除非用户要求，不用 `skip=1`。
+- 第一遍别开 `hints`；想看别的结局时再 `rewind`、读档或 `new`。
+- 铁人模式（`mode=ironman`）下不能存读档和回溯，选了就认。
+- H 场景默认折叠；用户没要求就不要改成 `h=full`。
+- 读到结局后，用两三句话告诉用户：你走了哪条路、为什么这么选、感受如何；问要不要再玩一遍。
+
+## 出错时
+
+- `没有这本书`：先 `do books` / `galbook_books` 看有哪些 slug。
+- `还没开始`：先 `new`，或 `load slot=auto`。
+- `现在没有选项可选`：先 `next`。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 galbook contributors
+
+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.

package/README.en.md

@@ -0,0 +1,114 @@
+# galbook
+
+**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.
+Hidden routes unlock across playthroughs, and many agents can play the same book at once with independent progress.
+
+[中文](README.md) · pure Python standard library, no dependencies · MIT
+
+## Four ways in
+
+| Way | Best for | Start |
+|---|---|---|
+| **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 |
+| **JSON API** | when you want structured fields | same server, `/play/?format=json` |
+| **MCP** | Claude Desktop, Codex-style clients, DeepSeek Harness | stdio: `python3 -m galbook mcp`; Streamable HTTP also supported |
+| **CLI** | agents with nothing but a shell | `python3 -m galbook do next n=20`; the last line tells the next command |
+
+Full protocol in [docs/AGENTS.md](docs/AGENTS.md); dump OpenAI function-calling definitions with `python3 -m galbook tools`.
+
+> **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/).
+
+> **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).
+
+- Pure Python standard library, zero dependencies
+- 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
+- Ready-made **DeepSeek Harness (dsh)** integration — MCP, skill and CLI all tested, see [integrations/deepseek-harness](integrations/deepseek-harness/)
+- 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)
+- 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
+
+![Three agents playing at once; watching one of them in the web UI](docs/img/watch.png)
+
+> ⚠️ **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.
+
+## Try it in 30 seconds
+
+```bash
+git clone <this repo> galbook && cd galbook
+python3 -m galbook demo --books books          # installs the demos: fog-harbor (Chinese), fog-harbor-en (English)
+python3 -m galbook serve --books books --lang en   # http://127.0.0.1:8765/play/
+```
+
+An agent only needs HTTP GET:
+
+```
+GET http://127.0.0.1:8765/play/t?lang=en                                 ← how to play (for the agent)
+GET http://127.0.0.1:8765/play/t/fog-harbor-en/alice?do=new&lang=en
+GET http://127.0.0.1:8765/play/t/fog-harbor-en/alice?do=next
+GET http://127.0.0.1:8765/play/t/fog-harbor-en/alice?do=choose&i=2&reason=she+looks+tired
+```
+
+A party of agents with different personalities (runs without any model; add `--decider llm` for any OpenAI-compatible API):
+
+```bash
+python3 examples/party.py --book fog-harbor-en
+```
+
+## Diversity options
+
+| Option | How | What |
+|---|---|---|
+| Adult scenes | `new&h=fold` (default) / `full` / `skip` | fold to a one-line note / show / skip entirely |
+| Ironman | `new&mode=ironman` | no save, load or rewind this run — live with your choices |
+| Hints | `new&hints=1` | mark options as [new] / [picked before]; off by default (feels like a first playthrough) |
+| Language | `new&lang=en`, or `&lang=en` on any request | English text interface |
+| Persona | `do=persona&text=timid, hates risks` | reminded to the agent at every choice |
+| Random | `choose&i=random` | roll a die (baselines, load tests) |
+| Gallery | `do=gallery` | endings / routes / CG / read ratio |
+| Human-likeness | `do=profile` | lines read before choices, reason rate, think time, always-first-option |
+| Skip read | `next&skip=1` | fast-forward to unread text |
+| Images | `next&img=1` | URLs of current background / sprites / CG for multimodal agents |
+
+## Connect your agent
+
+- **Any HTTP-capable agent**: the text API above. `/play/t?lang=en` can go straight into a system prompt.
+- **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)
+- **MCP (Streamable HTTP)**: `serve` exposes `POST /mcp?book=…&agent=…` — one server, many agents, works with tokens
+- **DeepSeek Harness**: [integrations/deepseek-harness](integrations/deepseek-harness/) (patch config, skill, a no-API-key self-test)
+- **Skill**: [.agents/skills/galbook/SKILL.md](.agents/skills/galbook/SKILL.md) — copy into `~/.agents/skills/` (dsh) or `.claude/skills/`
+- **OpenAI function calling**: `python3 -m galbook tools --format openai > tools.json`, execute with `galbook.tools.call_tool(...)`
+- **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)
+
+Details: [docs/AGENTS.md](docs/AGENTS.md) (Chinese with English examples).
+
+**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).
+
+## Import your own games
+
+```bash
+python3 -m galbook detect path/to/extracted
+python3 -m galbook build --src path/to/extracted --out books/mygame/story --assets-dir books/mygame
+```
+
+| Engine | Support |
+|---|---|
+| QLIE (`.s`) | branching ✅ |
+| Kirikiri KAG / TyranoScript (`.ks`) | branching ✅ |
+| Ren'Py (`.rpy`; decompile `.rpyc` with unrpyc first) | branching ✅ |
+| NScripter / ONScripter (`0.txt` / `nscript.dat`) | branching ✅ |
+| `.gal` (built-in hand-written format) | branching ✅ |
+| 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) |
+| anything else | write a plugin — see [docs/IMPORTERS.md](docs/IMPORTERS.md) |
+
+Archives (`.xp3`, `.pack`, `.rpa`, …) must be extracted first with tools such as GARbro.
+
+## Tests
+
+```bash
+python3 -m unittest discover -s tests -v
+```
+
+Tested on Python 3.9 / 3.12 / 3.13 (Linux) and Python 3.12 (mini PC) / 3.14 (Windows) with the same suite.
+
+## License
+
+Code: MIT ([LICENSE](LICENSE)). Demo stories and art in `galbook/demo/`: CC0.

package/README.md

@@ -1,3 +1,133 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# galbook
+
+**让 agent 像人一样玩 galgame / 视觉小说**：一句一句读剧情，遇到选项自己选并写理由，存档、读档、回到上个选项、多周目解锁隐藏线。很多 agent 可以同时玩同一本书，各自的进度互不干扰。
+
+[English](README.en.md) · 纯 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](docs/AGENTS.md)；OpenAI function-calling 的工具定义用 `python3 -m galbook tools` 导出。
+
+> **用 DeepSeek Harness（dsh）？** 插件面板 → 安装 → 来源填 `github:CHET-LI/DSH-galgame-galbook`，重启即可（包在根目录声明了组合包，多出 15 个 `galbook_*` 工具）。连不上 GitHub 就用本地目录或 `galbook-1.2.4.tgz`，见 [dsh-plugin](dsh-plugin/)。
+
+> **要离线包？** [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 包）。
+
+- 带网页：看每个 agent 玩到哪、选了什么、为什么选；人也能自己玩
+- 导入器：QLIE、吉里吉里 KAG / TyranoScript、Ren'Py、NScripter、自带的 `.gal` 手写格式；另外能吃 VNTextPatch 等工具导出的文本（20 多种引擎，只能线性读），还能写插件接新引擎
+- 另外附：Anthropic Skill 格式的技能文件、dsh 适配示例（[integrations/deepseek-harness](integrations/deepseek-harness/)）、`verify_claims.py` 逐条自检脚本
+
+![三个 agent 同时在玩，网页上看其中一个](docs/img/watch.png)
+
+> ⚠️ **版权**：本仓库只有代码和自己写的演示故事。游戏的剧本、图片、音乐归原作者/厂商所有。请只导入你自己合法拥有的游戏，导出的剧本和图片**不要上传或分发**。galbook 不带任何解包/解密工具，也不会运行游戏的 exe。
+
+## 30 秒试玩
+
+```bash
+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 兼容接口）：
+
+```bash
+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](examples/mcp_config.example.json)
+- **MCP（Streamable HTTP）**：`serve` 自带 `POST /mcp?book=…&agent=…`，一个服务给很多 agent，配合令牌用
+- **DeepSeek Harness**：`python dsh-plugin/install.py` 一条命令装好（自动找 profile、备份、填路径），细节和另外两种接法见 [dsh-plugin](dsh-plugin/) 与 [integrations/deepseek-harness](integrations/deepseek-harness/)
+- **技能**：[.agents/skills/galbook/SKILL.md](.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](docs/AGENTS.md)。
+
+**公开部署**：默认只听 127.0.0.1。要给别人用请开令牌：`--token 共享口令`，或 `--tokens tokens.json`（`{"口令": "alice", "管理员口令": "*"}`，每个口令只能用自己的名字玩）。
+
+## 导入你自己的游戏
+
+```bash
+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](https://github.com/arcusmaximus/VNTranslationTools) 抽成 JSON 再 `--engine textdump`（格式按 VNTextPatch 源码实现，还没拿真游戏的导出验证过） |
+| 其他 | 写插件（几十行），见 [docs/IMPORTERS.md](docs/IMPORTERS.md) |
+
+封包（`.xp3`、`.pack`、`.rpa`…）要先用 GARbro 等工具自己解开。各引擎的细节和已知限制见 [docs/ENGINES.md](docs/ENGINES.md)。
+
+## 文档
+
+- [docs/AGENTS.md](docs/AGENTS.md)：接入 agent（文本接口、JSON、MCP、OpenAI 工具、令牌）
+- [docs/ENGINES.md](docs/ENGINES.md)：各引擎能做到什么、怎么准备文件
+- [docs/IMPORTERS.md](docs/IMPORTERS.md)：`.gal` 格式说明、文本导出格式、写插件
+- [docs/SCHEMA.md](docs/SCHEMA.md)：中间格式（story.json / 指令 / 存档）
+- [dsh-plugin/README.md](dsh-plugin/README.md)：装进 DeepSeek Harness（一条命令、可卸载）
+- [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## 测试
+
+```bash
+python3 -m unittest discover -s tests -v
+```
+
+在 Python 3.9 / 3.12 / 3.13（Linux）和 Python 3.12（小主机）/ 3.14（Windows）上跑过同一套用例。
+
+## 许可
+
+代码 MIT（见 [LICENSE](LICENSE)）。`galbook/demo/` 里的演示故事和图是 CC0。

package/bin/galbook.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// npx galbook <命令> … → python -m galbook <命令> …（本体是 Python 标准库写的，这里只负责找 Python 和转发）
+// 选解释器：GALBOOK_PYTHON > Windows: py -3 / python / python3 > 其他: python3 / python；要求 3.9+。
+// 注意：stdin/stdout/stderr 原样继承——MCP 走 stdio 时 stdout 是协议通道，这里自己一个字都不往 stdout 写。
+import { spawn, spawnSync } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { delimiter } from "node:path";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const CHECK = "import sys; print('%d.%d' % sys.version_info[:2])";
+
+function candidates() {
+  if (process.env.GALBOOK_PYTHON) return [[process.env.GALBOOK_PYTHON]];
+  return process.platform === "win32" ? [["py", "-3"], ["python"], ["python3"]] : [["python3"], ["python"]];
+}
+
+function findPython() {
+  const tried = [];
+  for (const [cmd, ...pre] of candidates()) {
+    const r = spawnSync(cmd, [...pre, "-c", CHECK], { encoding: "utf8", windowsHide: true });
+    const v = (r.stdout || "").trim();
+    tried.push(cmd + (pre.length ? " " + pre.join(" ") : "") + (r.error ? "（没找到）" : v ? "（" + v + "）" : "（运行失败）"));
+    if (!r.error && r.status === 0 && /^\d+\.\d+$/.test(v)) {
+      const [maj, min] = v.split(".").map(Number);
+      if (maj > 3 || (maj === 3 && min >= 9)) return { cmd, pre, tried };
+    }
+  }
+  return { cmd: null, tried };
+}
+
+const py = findPython();
+if (!py.cmd) {
+  process.stderr.write(
+    "galbook 需要 Python 3.9 或更新版本，但这台机器上没找到能用的。\n" +
+      "  试过：" + py.tried.join("、") + "\n" +
+      "  解决：装 Python（https://www.python.org/downloads/ ，Windows 安装时勾选「Add python.exe to PATH」），\n" +
+      "        或者设环境变量 GALBOOK_PYTHON 指向 python 可执行文件，再重试。\n" +
+      "galbook needs Python 3.9+ and none was found on PATH. Install it from https://www.python.org/downloads/\n" +
+      "(on Windows tick \"Add python.exe to PATH\"), or set GALBOOK_PYTHON to the interpreter path.\n"
+  );
+  process.exit(127);
+}
+
+const env = { ...process.env, PYTHONIOENCODING: process.env.PYTHONIOENCODING || "utf-8" };
+env.PYTHONPATH = env.PYTHONPATH ? ROOT + delimiter + env.PYTHONPATH : ROOT;   // 用包里自带的 galbook/
+const child = spawn(py.cmd, [...py.pre, "-m", "galbook", ...process.argv.slice(2)], { stdio: "inherit", env, windowsHide: true });
+for (const sig of ["SIGINT", "SIGTERM"]) process.on(sig, () => child.kill(sig));
+child.on("error", (e) => {
+  process.stderr.write("galbook: 启动 Python 失败 / failed to start Python: " + e.message + "\n");
+  process.exit(127);
+});
+child.on("exit", (code, signal) => process.exit(signal ? 1 : code ?? 1));

package/cordis.patch.yml

@@ -0,0 +1,30 @@
+# dsh bundle: 把 galbook 的 MCP 服务挂进当前 profile。
+# 路径优先读环境变量 GALBOOK_HOME；没设就用安装后的包目录（<profile>/node_modules/galbook）。
+# python 想指定别的解释器：设 GALBOOK_PYTHON。
+- insert:
+    - id: mcp-galbook
+      name: '@deepseek-ai/dsh-mcp-client'
+      config:
+        serverName: galbook
+        transport: stdio
+        command: !!js "process.env.GALBOOK_PYTHON || (process.platform === 'win32' ? 'python' : 'python3')"
+        args:
+          - '-m'
+          - 'galbook'
+          - 'mcp'
+          - '--books'
+          - !!js "(process.env.GALBOOK_HOME || ((process.env.DSH_PROFILE_DIR || process.cwd()) + '/node_modules/galbook')) + '/books'"
+          - '--data'
+          - !!js "(process.env.GALBOOK_HOME || ((process.env.DSH_PROFILE_DIR || process.cwd()) + '/node_modules/galbook')) + '/play-data'"
+          - '--book'
+          - 'fog-harbor'
+          - '--agent'
+          - 'dsh-agent'
+          - '--lang'
+          - 'zh'
+        cwd: !!js "process.env.GALBOOK_HOME || ((process.env.DSH_PROFILE_DIR || process.cwd()) + '/node_modules/galbook')"
+        env:
+          PYTHONPATH: !!js "process.env.GALBOOK_HOME || ((process.env.DSH_PROFILE_DIR || process.cwd()) + '/node_modules/galbook')"
+          PYTHONIOENCODING: utf-8
+        failOnStartupError: false
+        toolCallTimeoutMs: 60000

package/dsh-plugin/README.md

@@ -0,0 +1,49 @@
+# DSH 插件包（给 DeepSeek Harness 用户）
+
+**三步装好，不需要 API key。**
+
+```bash
+# 1. 解开这个包，进到目录
+cd DSH-galgame-galbook
+
+# 2. 装演示书（中文 + 英文两本，几十 KB）
+python -m galbook demo --books books
+
+# 3. 挂进 dsh（自动找 profile、自动备份、自动填路径）
+python dsh-plugin/install.py
+```
+
+然后重启 DeepSeek Harness，新建会话问一句「galbook 有哪些工具？」，能看到 15 个就成了。
+
+## 它会做什么
+
+- 找到 `<dsh-home>/profiles/<profile>/cordis.patch.yml`（默认 profile `desktop`，`dsh-home` 默认 `~/.dsh`，可用 `DSH_HOME` 或 `--home` 指定）
+- 先备份成 `cordis.patch.yml.bak-时间戳`
+- 在文件末尾追加一段 `mcp-galbook`（stdio 方式，dsh 自己拉起 `python -m galbook mcp`），里面的路径按你这台机器填好
+- 不动 dsh 本体，不动别的配置条目；重复执行不会写两遍
+
+```bash
+python dsh-plugin/install.py --dry-run          # 只看要写什么
+python dsh-plugin/install.py --profile work     # 装到别的 profile
+python dsh-plugin/install.py --books D:/books --data D:/saves
+python dsh-plugin/install.py --remove           # 卸载
+```
+
+## 另外两种接法
+
+- **共享服务**：`python -m galbook serve --books books --port 8765`，多个 agent 共用一个进程，令牌绑定名字，URL 里冒名无效。配置见 `integrations/deepseek-harness/galbook-http.patch.yml`。
+- **命令行**：`python -m galbook do next n=20`，给只有 shell 的 agent 用，最后一行就是下一步该跑的命令。
+
+## 技能文件
+
+`.agents/skills/galbook/SKILL.md` 已经在包里。从仓库根启动 dsh 时会自动发现，里面写明了「不准偷看剧本文件」——agent 只能通过工具一步步读剧情。
+
+## 出问题怎么办
+
+- **Linux 上解压后目录名变乱码**（`уВ╣уВпуГкуГЧуГИ` 这种）：系统的 `unzip` 不认 UTF-8 文件名。用 `python3 -m zipfile -e galbook-1.2.3.zip .`，或直接下 `galbook-1.2.3.tar.gz`
+- **连 GitHub 超时 / 提示「请尝试其他安装来源」**：这台机器到 github.com 不通时，插件面板的链接安装会失败。两个办法：
+  - 用本地安装：把仓库解压到本地，插件面板里选**本地目录**；或下载 `galbook-1.2.4.tgz`（Release 里），来源填 `file:C:\路径\galbook-1.2.4.tgz`
+  - 给 dsh 走代理：启动 dsh 前设 `HTTPS_PROXY` / `HTTP_PROXY`（例如 `http://127.0.0.1:7897`），再重试链接安装
+- 看不到工具：确认改的是**当前在用的** profile；dsh 的配置只在启动时读，改完必须整组退出重开
+- `python` 找不到：`python dsh-plugin/install.py --python "C:\Path\python.exe"`
+- 想手动看写了什么：`--dry-run` 打印的就是最终 YAML

package/dsh-plugin/install.py

@@ -0,0 +1,190 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""把 galbook 挂进 DeepSeek Harness（dsh）——一条命令，不用手改 YAML。
+
+    python dsh-plugin/install.py                  # 装到默认 profile（desktop）
+    python dsh-plugin/install.py --dry-run        # 只打印要写进去的内容
+    python dsh-plugin/install.py --profile work   # 指定 profile
+    python dsh-plugin/install.py --remove         # 卸掉，不留痕
+
+它会：
+1. 找到 dsh 的配置文件 <dsh-home>/profiles/<profile>/cordis.patch.yml；
+2. 备份成 .bak-时间戳；
+3. 追加一段 MCP 配置（stdio 方式，dsh 会自己拉起 python -m galbook mcp），路径按你这台机器自动填；
+4. 打印重启和自测的方法。
+
+不改 dsh 本体，不动别的配置条目；重复执行不会写两遍。
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as _dt
+import os
+import sys
+import tempfile
+
+MARK = "mcp-galbook"
+HEAD_COMMENT = "# >>> galbook (installed by dsh-plugin/install.py) >>>"
+TAIL_COMMENT = "# <<< galbook <<<"
+
+BLOCK = """{head}
+- insert:
+    - id: {mark}
+      name: "@deepseek-ai/dsh-mcp-client"
+      config:
+        serverName: galbook
+        transport: stdio
+        command: {command}
+        args: {args}
+        cwd: {cwd}
+        env:
+          PYTHONPATH: {repo}
+          PYTHONIOENCODING: utf-8
+        toolCallTimeoutMs: 60000
+{tail}
+"""
+
+
+def repo_root() -> str:
+    return os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+
+def yaml_str(s: str) -> str:
+    return '"' + s.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def args_list(items):
+    return "[" + ", ".join(yaml_str(i) for i in items) + "]"
+
+
+def find_home(explicit: str | None) -> str:
+    if explicit:
+        return os.path.abspath(os.path.expanduser(explicit))
+    env = os.environ.get("DSH_HOME")
+    if env:
+        return os.path.abspath(os.path.expanduser(env))
+    return os.path.join(os.path.expanduser("~"), ".dsh")
+
+
+def profiles(home: str):
+    d = os.path.join(home, "profiles")
+    if not os.path.isdir(d):
+        return []
+    return sorted(p for p in os.listdir(d) if os.path.isdir(os.path.join(d, p)))
+
+
+def build_block(args, repo: str) -> str:
+    cmd = args.python or sys.executable
+    mars = ["-m", "galbook", "mcp",
+            "--books", os.path.abspath(args.books),
+            "--data", os.path.abspath(args.data),
+            "--book", args.book,
+            "--agent", args.agent,
+            "--lang", args.lang]
+    return BLOCK.format(head=HEAD_COMMENT, tail=TAIL_COMMENT, mark=MARK, command=yaml_str(cmd),
+                        args=args_list(mars), cwd=yaml_str(repo), repo=yaml_str(repo))
+
+
+def strip_block(text: str) -> tuple[str, bool]:
+    if HEAD_COMMENT not in text:
+        return text, False
+    start = text.index(HEAD_COMMENT)
+    end = text.index(TAIL_COMMENT, start) + len(TAIL_COMMENT)
+    rest = text[end:]
+    if rest.startswith("\n"):
+        rest = rest[1:]
+    return text[:start] + rest, True
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="Install galbook MCP into DeepSeek Harness")
+    ap.add_argument("--home", help="dsh home（默认 ~/.dsh，也可以用环境变量 DSH_HOME 指定）")
+    ap.add_argument("--profile", default="desktop", help="要写入的 profile（默认 desktop）")
+    ap.add_argument("--books", default=None, help="剧本目录（默认 <仓库>/books）")
+    ap.add_argument("--data", default=None, help="存档目录（默认 <仓库>/play-data）")
+    ap.add_argument("--book", default="fog-harbor", help="默认书目")
+    ap.add_argument("--agent", default="dsh-agent", help="默认玩家名")
+    ap.add_argument("--lang", default="zh", choices=["zh", "en"], help="界面语言")
+    ap.add_argument("--python", default=None, help="给 dsh 用的 python 解释器（默认当前这个）")
+    ap.add_argument("--dry-run", action="store_true", help="只打印，不写文件")
+    ap.add_argument("--remove", action="store_true", help="删掉之前写入的配置")
+    a = ap.parse_args()
+
+    repo = repo_root()
+    a.books = a.books or os.path.join(repo, "books")
+    a.data = a.data or os.path.join(repo, "play-data")
+    home = find_home(a.home)
+
+    print(f"仓库   : {repo}")
+    print(f"dsh home: {home}")
+
+    ps = profiles(home)
+    if not ps:
+        print("× 没找到任何 profile。确认 dsh 装过并且启动过一次，或用 --home 指定。")
+        print("  已有 profile:", ps or "（无）")
+        return 2
+    target = os.path.join(home, "profiles", a.profile, "cordis.patch.yml")
+    if not os.path.exists(target):
+        # 也允许写在 home 根下的 cordis.patch.yml
+        alt = os.path.join(home, "cordis.patch.yml")
+        if os.path.exists(alt) or a.profile == "desktop":
+            target = alt if not os.path.isdir(os.path.join(home, "profiles", a.profile)) else target
+    print(f"目标   : {target}")
+    print(f"profile: {a.profile}（可用: {', '.join(ps)}）")
+
+    block = build_block(a, repo)
+    if a.dry_run:
+        print("\n----- 将写入 -----")
+        print(block)
+        return 0
+
+    text = ""
+    if os.path.exists(target):
+        with open(target, encoding="utf-8") as f:
+            text = f.read()
+    text, existed = strip_block(text)
+
+    if a.remove:
+        if not existed:
+            print("没有找到 galbook 的配置块，什么都没改。")
+            return 0
+        _backup(target)
+        with open(target, "w", encoding="utf-8") as f:
+            f.write(text)
+        print("✓ 已移除。重启 dsh 生效。")
+        return 0
+
+    if MARK in text and not existed:
+        print("× 文件里已经有 mcp-galbook（可能是手动加的），为免冲突没有改动。")
+        return 3
+
+    if text and not text.endswith("\n"):
+        text += "\n"
+    new = text + ("\n" if text.strip() else "") + block
+    os.makedirs(os.path.dirname(target), exist_ok=True)
+    if os.path.exists(target):
+        _backup(target)
+    with open(target, "w", encoding="utf-8") as f:
+        f.write(new)
+
+    print("\n✓ 写入完成。")
+    if not os.path.isdir(a.books) or not os.listdir(a.books):
+        print("  ! 剧本目录还没有书，先装演示书（中文 + 英文两本）：")
+        print(f"    \"{a.python or sys.executable}\" -m galbook demo --books \"{a.books}\"")
+    print("  1) 重启 DeepSeek Harness（配置只在启动时读）")
+    print("  2) 新建会话，问它：galbook 有哪些工具？应能看到 15 个")
+    print("  3) 想先验证不重启：手动给 python -m galbook mcp 发一条 initialize")
+    print("  卸载：python dsh-plugin/install.py --remove")
+    return 0
+
+
+def _backup(path: str) -> None:
+    stamp = _dt.datetime.now().strftime("%Y%m%d-%H%M%S")
+    bak = f"{path}.bak-{stamp}"
+    with open(path, "rb") as s, open(bak, "wb") as d:
+        d.write(s.read())
+    print(f"备份   : {bak}")
+
+
+if __name__ == "__main__":
+    sys.exit(main())