前言¶
在 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 開演。
