gal-view

一句话定位

为 DSH Web GUI 的会话页追加一个「GAL 视窗」标签，把对话区变成可拖拽布局、可换图的 Galgame 舞台，内置可视化场景编辑器可即时改图、改台词、改图层。

核心能力

在会话标签栏的「对话」与「轨迹」之间插入「GAL 视窗」标签页（标签顺序由 order: 5 决定）
以 16:9 舞台形式渲染对话：背景、立绘、大对话框、打字机台词、玩家输入与历史/自动/快进/设置四个预设功能按钮
内置可视化编辑器：拖拽移动、改尺寸/对齐/颜色/字体/图层顺序，支持撤销/重做（最多 100 步历史）
导入图片与字体素材库，图片单文件最大 8 MB、字体单文件最大 24 MB，超限或类型不符自动跳过
通过 Ctrl+S 把当前场景连同被引用素材/字体一并导出为 JSON，可在编辑模式导入或一键重置回默认预设
每会话独立保存阅读进度（当前行、页码、打字进度），切换标签或刷新后能恢复继续阅读

技术实现

语言: JavaScript（Node half ESM）+ JSX（client half，经典 React.createElement 转换）
关键依赖: 仅 esbuild（devDependency，用于把 client/ 源码打包为 client.js）；运行时不依赖任何 npm 包，react 走 external、由宿主渲染器共享同一实例
架构模式: 官方 bundle 插件——cordis.patch.yml 在 web 组合层挂一层 gal-view（Node half 极简，无宿主行为），package.json#dsh.client 声明由 client 内核组合进页面；视图层通过 slots.inject('conversation.view') 注册到对话视图槽位，order 5 落在「对话」(0) 与「轨迹」(10) 之间
入口文件: .dsh-plugin/index.mjs（Node half，无副作用）+ .dsh-plugin/client/index.mjs（浏览器 half 实际逻辑）+ 构建产物 .dsh-plugin/client.js

适用场景

想在 DSH 的会话页里把 AI 对话以 Galgame 视觉小说形式呈现的玩家和创作者。适合给会话定制专属立绘/背景/字体，或者把对话作为互动剧情素材来截图、演示、直播——本地化素材完全跑在浏览器里，不需要后端配合。

前置依赖与兼容性

依赖	最低版本	说明
DSH	未声明	插件未在 `package.json` 中声明 `dsh` 版本约束，安装后需执行「重启 web」让 bundle 层重新合成
Node	未声明	`package.json` 无 `engines` 字段；构建脚本 `esbuild --target=es2020`，需支持 ESM 的现代 Node 版本
平台	跨平台	完全运行在浏览器 half（Web GUI），与操作系统无关
原生模块	无	不依赖 `node-pty` / `node:sqlite` 等原生扩展

安装方式

dsh plugin --profile web add github:Ayase34/gal-view

配置项

本插件没有面向用户的传统「配置表单」，唯一可控的是开关本身。

配置	类型	说明	默认值
GAL 视窗标签显隐	开关	在 Web GUI「设置 → 插件 → GAL 视窗」中可关闭/开启；关闭后「GAL视窗」标签会从会话标签栏消失，场景数据仍保留	启用

常见问题

Q: 装了插件但会话页没看到「GAL 视窗」标签怎么办？

A: bundle 层在 web 启动时合成，必须执行重启 web 才会加载插件；可以再跑 dsh --profile web --dump-config，输出中应能看到 # == gal-view 这一层。

Q: 场景布局、导入的图片和阅读进度存在哪里？

A: 全部存在浏览器本地——场景 JSON 走 localStorage，图片/字体二进制走 IndexedDB；重装或卸载插件不会丢数据，清除浏览器站点数据才会重置。

Q: 编辑模式能拖拽吗？支持撤销/重做吗？

A: 编辑模式支持拖动、改属性、换图层（上下/置顶/置底）；撤销/重做基于栈实现，最多保留 100 步历史；可通过 Ctrl+S 把当前场景连同被引用素材/字体导出为 JSON。

Q: 重新安装插件会清空我的场景吗？

A: 不会。场景数据存在浏览器本地，与插件生命周期解耦；卸载或重装都不会丢失，需要清除浏览器站点数据才会重置。

Q: 导入图片或字体有大小限制吗？

A: 图片单文件上限 8 MB，超过会跳过；字体单文件上限 24 MB，超限或非字体类型也会被跳过。被跳过的文件不会中断整批导入。

Q: 默认带什么场景？首次打开看到的内容是哪里来的？

A: 仓库根目录的 gal-scene.json 是随插件分发的默认预设场景，内嵌了被引用的图片与字体；首次打开且本地无存档时会自动加载该预设，编辑模式的「重置」也回到该预设。

Q: 怎么彻底卸载并恢复原状？

A: 执行 dsh plugin --profile web remove gal-view 后重启 web；场景数据会留在浏览器本地（不影响卸载本身），如要彻底清空再清除浏览器站点数据。

上手难度

入门 — 安装一条命令、重启即生效；编辑模式所见即所得，不需要写代码；想自定义预设可导出 JSON 后替换仓库根 gal-scene.json 重新打包。

已知问题与限制

单张图片素材上限 8 MB（assets.mjs 中的 MAX_ASSET_BYTES），单份字体上限 24 MB（fonts.mjs 中的 MAX_FONT_BYTES），超出或非对应 MIME 类型会被静默跳过，不弹错误对话框
编辑模式撤销/重做栈最多保留 100 步（index.mjs 中的 HISTORY_LIMIT），超出后更早的历史会被丢弃
浏览器的 localStorage / IndexedDB 配额上限会随浏览器与设备而异，导入大量高清素材可能触发持久化失败（代码里以 try/catch 静默忽略，未做配额预警 UI）
浏览器隐私模式下 localStorage 读写会被吞掉异常，刷新后阅读进度会回到初始状态
编辑器历史菜单与「矩形/圆形/装饰」等旧元素类型仅做兼容显示，新建菜单已移除，仅保留 background/character/dialogue/dialogue-text/speaker-name/text/image/button/action-button 九种当前类型

gal-view

安装

一句话定位

核心能力

技术实现

适用场景

前置依赖与兼容性

安装方式

配置项

常见问题

上手难度

已知问题与限制

默认预设

安装

前置条件

从 GitHub 安装（一行命令）

完成安装

更新到新版本

卸载

开发

结构