dsh-galgame

一句话定位

dsh-galgame 是面向 DSH Web 聊天界面的纯展示层插件，在「聊天」「轨迹」之外新增第三个标签「galgame 模式」，把真实 agent 会话渲染成 GalGame 演出：鲸鱼娘立绘 + 思考气泡 + 打字机对话框 + 分句翻页 + 提问选项 + 历史抽屉。它不写会话、不干预 agent 循环，任何时候都能切回常规聊天。

核心能力

• 在「聊天」「轨迹」标签栏右侧插入「galgame 模式」第三个会话视图（conversation.view keyed slot，id galgame，order 20，src/client/index.ts:122-156）
• 渲染鲸鱼娘立绘：透明底 WebP、说话每句弹跳一次（弹跳后保持居中）、跨差分 120ms crossfade（src/client/Stage.tsx:35-108、README.md:12）
• 流式输出时在立绘旁显示漫画风思考气泡，自动滚动到底，可拖拽，提问/审批/定稿后自动收起（src/client/Stage.tsx:54-91、README.md:13）
• 对话框只显示文本输出，工具调用/思维链/图片块全部隐藏在「幕后」（src/client/adapter.ts:19-28、README.md:14）
• 按换行分块、打字机逐字 + Markdown 渲染；点击 / 滚轮 / ◀▶ 翻页；模型运行中默认自动推进（约 0.95s/块），点击即接管（src/client/adapter.ts:61-110、src/client/GalgameView.tsx:43-46）
• 把 agent 的提问工具（pending question）与权限申请（pending approval）渲染成 GalGame 风格的浮层选项卡，支持多选、自定义答案（Shift+Enter 换行）、分多题逐题推进（src/client/ChoicePanel.tsx、src/client/ApprovalPanel.tsx）
• 任务执行中的用户输入默认走「steer 引导插话」直达运行中 agent 循环，而非排队发送（src/client/index.ts:135-145、src/client/GalgameInput.tsx:50-68）
• 右上角「历史」按钮展开完整台词回放抽屉（含流式中高亮追加），「⚙」按钮打开设置面板（自动翻句 / 打字机速度 / 说话弹跳 / 思考气泡 / 调试模式）（src/client/Backlog.tsx、src/client/SettingsPanel.tsx）

技术实现

• 语言: TypeScript + React 18（src/client/*.tsx、src/index.ts）
• 关键依赖: @deepseek-ai/dsh-client-ui-conversation（注入 conversation.view slot）、@deepseek-ai/dsh-client-ui-primitives（MarkdownText）、@deepseek-ai/dsh-client-runtime（session.prompt('steer')）、@deepseek-ai/dsh-client-locale（中英字典注册）—— 全部为 peerDependencies，不内联（package.json:58-67）
• 架构模式: 树外 npm 包双面架构。Host 半边在 src/index.ts 注册 /api/dsh-galgame/assets/* 静态路由前缀；Client 半边在 src/client/index.ts 用 ctx.slots.inject('conversation.view', ...) 注册标签入口；安装经 cordis.patch.yml 的 insert 段把 id: galgame 写入 web profile roster（cordis.patch.yml:6-8）
• 入口文件: Host 入口 src/index.ts、Client 入口 src/client/index.ts；构建产物 lib/index.js（Host）+ lib/client.js（Client，由 tsdown + lightningcss 编译 CSS Modules 打包，build/tsdown.client.ts:206-321）

适用场景

想让 DSH 的文字对话看着像视觉小说、而不是冷冰冰聊天窗口的用户；觉得「轨迹」面板信息密度高但缺乏角色陪伴感的用户；以及希望提问/审批弹窗更贴近游戏交互而不像普通表单的用户。前提是日常使用 DSH Web 端、能接受立绘素材 CC BY-NC-SA 4.0 的非商用条款。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:Lanxing6480/dsh-galgame

配置项

插件运行时配置以 localStorage（key=dsh.galgame.settings）持久化，无配置文件、无环境变量、无 DSH 配置 Schema（src/client/settings.ts:26-53）。

常见问题

Q: 装上后界面没看到「galgame 模式」标签怎么办？

A: 重启 dsh web 并刷新浏览器。安装动作不会自动注入视图；标签栏出现的前提是 web profile 已加载该插件的 cordis.patch.yml 条目（README.md:53-57）。

Q: galgame 模式会影响 agent 的实际回答内容吗？

A: 不会。插件只读 useSession 快照、只在用户回复提问/审批时调用 wait.respond、任务执行中的输入走 session.prompt(..., 'steer') 引导插话；不发送额外模型请求、不写入会话（src/client/index.ts:135-145、README.md:85）。

Q: 立绘只有一张会不会太单调？怎么加表情差分？

A: 当前内置仅 neutral.webp，表情自动分类未实现（DESIGN.md:36、README.md:81-83）。补差分：把 smile.webp 等放进 assets/characters/deepseek/portraits/，在 src/client/manifest.ts 的 portraits 表里加一条 { src, type: 'image' }，组件全链路已按 ID 解析（src/client/manifest.ts:24-31）。

Q: 提问/审批弹窗可以拖位置吗？

A: 默认位置已固化调好，平时不可拖。在设置面板开启「调试模式」后，思考气泡、提问框、审批框都可以拖（位置写入 localStorage）。非调试用户无需关注这一项（src/client/ChoicePanel.tsx:39-41、src/client/useHostDrag.ts:42-46）。

Q: 切换会话或暂时切到「聊天」再回来，会话演到一半的进度还有吗？

A: 播放位置（行 key + 句索引）会写入 localStorage.dsh.galgame.playback，重挂视图时尝试恢复到对应位置；演出状态本身只存组件局部，切换会话/视图后从快照重建（src/client/GalgameView.tsx:117-145、README.md:82-83）。

Q: 立绘/角色形象是哪里来的？能用在自己的项目里吗？

A: 立绘为衍生创作，三创署名链：上善（鲸鱼娘原作）→ ZipZipPipe（女仆鲸鱼娘二创）→ Small-tailqwq（dsh-deep-whale/maid-atelier 皮肤，本插件直接借用）。assets/ 以 CC BY-NC-SA 4.0 发布，禁止任何商业性使用，分发须保留完整署名链；代码本身是 MIT（README.md:88-98、NOTICE）。

Q: 怎么卸载？卸载后会留下残留吗？

A: 用 dsh plugin --profile web remove github:Lanxing6480/dsh-galgame 卸载，重启 dsh web 即可。cordis.patch.yml 的 insert 段只往 web profile roster 加一行 id，卸载时 DSH loader 会回收该条目，标签栏自动消失；localStorage 中的 settings / playback / 拖拽位置键为浏览器端孤立数据，不影响其他会话（cordis.patch.yml:6-8）。

上手难度

入门 — 安装重启后切到「galgame 模式」即可使用，无需命令、无需配置；调速/关弹跳等高级选项都在右上角「⚙」里点开即可。

已知问题与限制

• 自动情绪分类未实现：立绘差分 ID 固定 neutral，表情规则引擎规划中（README.md:81-83、DESIGN.md:36）；组件已按 portrait ID 解析，用户可手动放图后切换
• 当前仅内置一张 neutral.webp（透明底），原图（白底 JPG）仅作素材留档放在 assets/characters/deepseek/raw/（README.md:68、assets/characters/deepseek/portraits/neutral.webp）
• 演出状态（行号、句索引、自动模式）只存组件局部，切换会话/视图后从快照重建；仅播放位置 key+索引写入 localStorage（README.md:82-83）
• 选项框/审批框默认位置已固化，调试模式下才能拖拽；普通用户改不了（src/client/ChoicePanel.tsx:39-41、src/client/ApprovalPanel.tsx:34-35）
• 立绘素材 CC BY-NC-SA 4.0，禁止任何商业性使用，分发须保留三创署名链（README.md:88-98、NOTICE）
• 打字机逐字期间若 unit 文本被以非前缀方式替换（例如切到下一句），会从 0 重新打字；同一句流式续写则保持进度（src/client/DialogueBox.tsx:53-63）
• 不做：Live2D、BGM/SFX、镜头、多人站位、剧情分支编辑器、存读档、话题标签注入（DESIGN.md:104-106）

简介

在 DSH Web GUI 的聊天主界面新增一个与「聊天」「轨迹」并列的界面栏——「galgame 模式」。该模式下，DeepSeek 娘（鲸鱼娘）以 GalGame 女主角的形式与你对话：立绘 + 差分接口 + 思考气泡 + 打字机对话框 + 分块阅读 + 提问/审批选项 + 历史回顾 + 调试模式。纯视觉层：不写会话、不干预 agent 循环，随时可切回常规聊天。

能力清单（v1.0.0）

界面预览

配色主题化：跟随 DSH 当前主题/皮肤（默认浅色、默认深色、皮肤 mod 均自动适配）。

致谢：本插件的女仆鲸鱼娘立绘素材取自 dsh-deep-whale 皮肤（作者 Small-tailqwq），完整署名链见下方「素材来源与许可」。

形态与架构

• 形态：树外 npm 包（@lanxing/dsh-galgame，link 安装到 web profile）
• 平台：Host（立绘静态资源路由）+ Client（conversation.view 注册 + GalGame UI）
• 架构（详见 DESIGN.md）：

ConversationSnapshot (useSession 只读)
  → GalgameAdapter（纯函数：过滤工具/思维链、按换行分块）
  → 演出状态（分块/打字机/自动模式/翻页）
  → Stage（立绘+气泡+浮层插槽）/ DialogueBox / ChoicePanel / ApprovalPanel / Backlog

• 关键契约：conversation.view keyed slot（id/order/label/inject）、s.pending（question/approval 交互）、ctx.webServer prefix 路由、session.prompt(..., 'steer') 插话引导

使用方式

1. 构建：pnpm install && pnpm build（在 plugins/dsh-galgame/ 目录）。
2. 安装（本地 link）：dsh plugin --profile web add link:H:/Projects/DEEPSE~1/plugins/dsh-galgame；或从 npm：dsh plugin --profile web add @lanxing/dsh-galgame。
3. 重启 DSH Web（dsh web）后刷新浏览器。
4. 用户操作入口：聊天主界面顶部标签栏 →「galgame 模式」。

立绘资源约定

assets/characters/deepseek/
├── portraits/           # 差分图（同画布、同锚点、同基准线，避免切换跳位）
│   └── neutral.webp     # 当前唯一差分（透明底）
└── raw/                 # 原图/素材留档（不参与渲染）

• 补差分：把 smile.webp / thinking.webp / angry.webp 等放入 portraits/，并在 src/client/manifest.ts 的 portraits 表里增加条目（组件全链路已按 portrait ID 解析，接口已预留；表情规则引擎规划中，见 DESIGN.md）。
• 差分切换动画与「说话弹跳」在 src/client/galgame.module.css（ggPortraitFade / ggBounce），prefers-reduced-motion 下自动关闭。

源码与版本

• Client 入口：src/client/index.ts（locale + conversation.view 注册 + steer 发送）
• Host 入口：src/index.ts（/api/dsh-galgame/assets/* 静态路由）

限制与注意事项

• 差分自动情绪分类未做（规划中，见 DESIGN.md 表情方案）：台词当前固定 neutral，差分接口已预留。
• 播放状态只存组件局部：切换会话/视图后从快照重建，不持久化演出位置。
• 立绘为透明底 WebP；原图（白底 JPG）仅留档于 raw/。
• 纯前端渲染 + pending.respond，不发模型请求、不阻塞 agent 循环。
• 选项框/审批框位置已固化为默认值，仅调试模式可拖拽调整。

素材来源与许可

本插件代码（src/、build/）以 MIT 许可发布；立绘素材（assets/）为衍生创作，以 CC BY-NC-SA 4.0（署名-非商业性使用-相同方式共享）发布，禁止任何商业性使用。

立绘素材为衍生创作，署名链（详见 NOTICE）：

1. 一创 上善（Pixiv · Bilibili：上善无形）—— 鲸鱼娘角色形象原作者
2. 二创 zipzip（Pixiv · Bilibili：ZipZipPipe）—— 在其形象上加入 DeepSeek 元素的女仆鲸鱼娘二次设计（生成模型 GPT Image 2）
3. 三创 Small-tailqwq（dsh-deep-whale / maid-atelier）—— 本插件使用的女仆鲸鱼娘立绘素材即来自该皮肤（DeepSeek 元素再设计）

素材源文件在 assets/characters/deepseek/（portraits/neutral.webp 为透明底成品，raw/ 为原图留档）。完整许可文本见 LICENSE 与 NOTICE。

维护位置

• 本项目 plugins/dsh-galgame/

变更日志