前言¶
在 DeepSeek Harness（DSH）里做带剧情、选项和立绘的交互，常见做法是自己在会话外维护脚本，或另开一套独立应用。AIVN 本身是一套舞台引擎：剧作家输出 Stage DSL，客户端实时渲染背景、立绘、台词与停止点选项。同名独立项目 stage-ai 提供完整桌面或 Web 体验（路线树、周目存档、工坊等）；若你已经在用 DSH，希望工作区即剧目、会话里直接看到舞台，而不多开一个应用，可以用插件 dsh-aivn（维护者 john-walks-slow，社区目录分类为「趣味换装」）。
下面介绍它是什么、能做什么，以及如何安装与上手。
这是什么¶
dsh-aivn 把 AIVN 的舞台引擎装进 DSH：一个工作区对应一部剧目，在会话里选择「剧作家」预设后，对话页会出现 AIVN tab（仅剧作家会话；搭台助手会话没有该 tab）。剧作家写的 Stage DSL 在 tab 内实时演出——背景、立绘、台词条、停止点选项；玩家点选项后，该句回到剧作家继续写。可选能力包括逐句 TTS、联网检索、生图、配乐等，由插件配置决定是否注册对应工具。
插件与独立版共用 @aivn/core、@aivn/stage 引擎与领域模型，差别在宿主：DSH 版用原生会话、文件侧栏与技能机制，不做 AIVN 自有的谱系分支；分岔与回退依赖 DSH 原生能力（如 dsh-rewind、在新对话中分支）。
核心功能¶
舞台与会话角色¶
- 剧作家：在 Stage DSL 中推进剧情；会话头部第三个 tab 为 Chat / Trajectory / AIVN。
- 搭台助手：备料（立 play.json、素材等）；生图、抠图等工具在该预设侧使用，不在舞台右上角导演栏里出图。
预设会在会话开始时固定，中途不能换 seat；要换角色需新建会话。
实时渲染与交互¶
- 背景、立绘、对话框、停止点选项在 AIVN tab 中同步更新。
- 舞台左上角可全屏（iPhone Safari 退化为铺满视口）；玩家 HIDE 时全屏键随台词条隐藏。
- 右下角提供语音开关与「重听这句」（需配置 TTS Key）。
导演工具栏¶
舞台右上角面向「导演」：提示（引导 / 打断）、改写、重写。改写 / 重写通过会话追加替换标记（与 dsh-rewind 同类手法），让剧作家重写对应拍子，保证上下文与画面一致；与 AIVN 独立版里改脚本行的语义不同。
可选能力（配置后才注册工具）¶
| 能力 | 配置要点 | 不配时的行为 |
|---|---|---|
| 语音 | ttsKeys 等（默认 Fish Audio） |
无语音相关工具与提示 |
| 联网检索 | searchKeys（Exa） |
搭台助手无 web_search |
| 生图 / 素材 | imageFormat、imageBaseUrl、imageModel 等需给齐 |
无 generate_image / generate_asset |
| 配乐 | musicBaseUrl、musicModel 等需给齐 |
无 generate_bgm |
| 命令行 | shell: true |
默认关闭 bash；仅对新开会话生效 |
| 限制级通道 | nsfwModel、nsfwPrompt（可按剧目 play.json 覆盖） |
进通道不换模型时留空 |
配置共 21 个顶层字段；改插件配置或 cordis.patch.yml 后多数能力下一轮对话即生效，shell 例外。
剧目与 DSH 原生能力¶
- 工作目录根需有
play.json（唯一必填）；另有memory/、角色卡等骨架，详见 README「一部剧目长什么样」。 - 回退：
dsh-rewind回退后，插件重投影舞台到该点。 - 分支：用 DSH「在新对话中分支」；插件从会话重铺，停在分叉时刻。
- NSFW：剧作家调
enter_nsfw/exit_nsfw；退出后主模型只见摘要，日志与舞台仍保留原文。
客户端 AIVN tab 依赖 dsh-web-app，在 package.json 的 dsh.client（platform: web）中声明。
安装与启用¶
包为 DSH bundle（package.json 中 dsh.bundle.patch）。web profile 下推荐：
dsh plugin --profile web add dsh-aivn
从 GitHub 直装（仓库内 lib/ 为跟踪的构建产物，无需本地 build）：
dsh plugin --profile web add github:john-walks-slow/dsh-aivn
手工挂载：在 profile 的 cordis.patch.yml 增加：
- insert:
- id: dsh-aivn
name: dsh-aivn
config: {}
配置方式二选一，保存后就地生效（一般无需重启 dsh）：
- 侧边栏 Plugins → dsh-aivn 配置卡（P0 能力开关与 Key，P1 默认口味项）。
- 同一 profile 的
cordis.patch.yml里config块（与界面写入同一份配置）。
示例片段（完整字段与默认值见 GitHub README）：
- id: dsh-aivn
name: dsh-aivn
config:
ttsKeys: ["<your-fish-audio-key>"]
searchKeys: ["<your-exa-key>"]
shell: false
imageFormat: gemini
imageBaseUrl: http://127.0.0.1:38000
imageModel: gemini-3.0-pro-image
部分 Key 可用环境变量兜底，例如 DSH_AIVN_TTS_KEYS、DSH_AIVN_EXA_KEYS。
安装前请自行查看仓库源码与 LICENSE，并理解插件以当前 dsh 进程权限运行；开启 shell 或外连 API 前评估风险。
典型用法¶
1. 进入舞台¶
- 新建会话，在座位 chip 上选 剧作家（备料选 搭台助手）。
- 确认工作目录根存在
play.json；若无，舞台会提示「还不是一座剧目」。 - 在输入框说一句话开演（例如「开始吧」）——该句会与剧目
opening一并交给剧作家，不必照念开场白。
若已选剧作家且目录里有 play.json，输入框上方会出现 「开始游戏」：一次完成投递 opening 并自动切到 AIVN tab（仅首次自动切换，之后由 DSH 记住 tab 选择）。也可手动发话后点 AIVN tab。
2. 新建剧目¶
工作区尚无 play.json 时，可在输入框执行（只写尚不存在的文件；已有 play.json 会报错）：
/new-play 雨中的旧校舍
不写剧目名则取工作目录名。该命令写骨架，不消耗 LLM 往返。校验结构可让搭台助手调用 validate_play。
3. 玩家推进¶
在停止点选择选项；选项作为玩家台词回到剧作家，后续 DSL 继续在 AIVN tab 演出。导演栏的提示不会出现在玩家时间线上（来源标记为 dsh-aivn-director）。
适用场景与注意¶
适合：已在 DSH web 环境做 agent / 技能开发，希望用同一工作区管理剧目文件、会话轨迹与可视化舞台；需要可选 TTS、检索、生图、配乐，且接受按 Key 逐项开启。
不太适合：需要 AIVN 独立版的路线树、周目存档与完整工坊——应使用 stage-ai。
注意：
- 两个预设、
/new-play、/aivn路由固定，不可通过配置改掉。 - 社区目录 skillhub.cn 与 DeepSeek / 幻方无官方从属关系；安装命令以 README 为准。
- 当前 package 版本为 0.2.0（以仓库
package.json为准）。
结尾¶
dsh-aivn 把「工作区 = 剧目、剧作家写 DSL、会话内舞台 tab 实时演」接到 DSH 上：回退与分支跟会话走，扩展能力靠扁平配置按需打开。若要完整 AIVN 产品体验用独立版；若已扎根 DSH，可按上文命令安装并在 web profile 下从 /new-play 或现有 play.json 开演。
