前言¶
在 DSH 里做多角色剧情或分角色对话时，常见做法是在同一会话里切换 persona，或手动开多个窗口来回粘贴。前者容易串戏、工具权限混在一起；后者难等「一手演完」再取下一句台词，也不方便给每个角色绑独立音色。
dsh-theater 是社区插件 KarBurKi/dsh-theater（分类：工作流），定位是「多角色剧场的执行器（Host 半）」：只负责给角色建独立会话、投 cue、绑音色。打分、裁决、场记、弹窗等剧本逻辑留在导演会话（场景剧情）里，插件内没有剧本引擎。
这是什么¶
维护者 KarBurKi。当前 README 对应版本 0.1.5（见仓库 package.json）。简介与目录一致：为每个角色创建或唤醒独立会话，投递 cue 并取回该角色输出原文；零依赖，运行时 不 import DSH 核心包。
演员表落盘为 actors.json（角色名 → sessionId / 预设 / 音色）。
核心功能¶
插件 README 写明「只做三件事」：独立会话、cue 投递、音色绑定；另提供演员表查询。对外暴露四个工具：
| 工具 | 用途 |
|---|---|
theater_open |
为角色创建独立会话（工作区 + 预设 theater-actor），可顺带绑音色 |
theater_say |
投一条 cue，等这一手演完，返回该角色输出原文（台词/行为/内心）；默认后台送达、不切窗 |
theater_bind |
给已存在会话绑 GPT-SoVITS 音色（写 dsh-tts 的 sessionVoices） |
theater_cast |
演员表 + 存活状态 |
预设 theater-actor 由 profile 的 cordis.patch.yml 注入（只挂 persona + compaction，不挂任何工具）。
零依赖实现方式¶
插件以 link: 装进 profile 后，运行时解析不到 @deepseek-ai/* 核心包。因此：
- 消息对象按
dsh-llm的createUserMessage形状手工构造（{role, content, source, id}）； - 工具按
dsh-tools的register(definition)契约手写（parameters直接给 JSON Schema）。
改这两处之前，应先确认当前环境能否 import 核心包。
投递与切窗¶
theater_say 默认 后台送达：宿主不推 now，主人正在看的窗口不动，对方照常收消息、照常回话。要看戏时传 focus: true——宿主把 now 推到目标会话，客户端轮询到就切过去。
{ "sessionId": "session-...", "text": "...", "focus": true } // 切窗
{ "sessionId": "session-...", "text": "..." } // 后台（默认）
focus: false 时也不会因「导演回合结束」自动把视图切回场景；切回同样由 focus: true 才登记导演会话。client 半未改，只跟随宿主推的 now。
正文一律用代码块包住：把 text 用三重反引号包住（```正文```）。语音播报（dsh-tts）会跳过代码块，不把投递内容念出来。该约定写在工具 description 里，不要指望会话指令长期记住——AGENTS 只在会话启动时读一次。
并发与唤醒¶
- 一个会话同时只允许一手 cue；
theater_say撞上未完成的手会直接报错。 - 会话未 live 时按演员表里的预设自动
resume。 - 回合边界靠
session/event的turn/start→assistant/message→turn/end判定；只有自己开过的回合才算数，避免被上一手的收尾提前唤醒。
日志与排错（0.1.5）¶
宿主侧错误和警告走 console.error / console.warn，落在 stdout/stderr，由重启脚本写入 tmp_all\host-out-*.log 与 host-err-*.log。不要用 ctx.logger：产品 profile 未给 ctx.logger 挂 console exporter，宿主侧没有 exporter 写 stdout。0.1.4 及更早在 session/event 异常处用 ctx.logger?.warn?.(...)，出错时可能没有任何输出；0.1.5 改为 console.error("[theater] session/event 处理失败：", error) 并带上 error 本体。仓库无自动化测试脚本，该改动以读源码与 node --check 为主，运行时确认需等实际异常场景。
安装与启用¶
安装方式以 README 为准：在 profile 的 package.json 里声明 link 依赖并加入 bundle，再用目录联接（Windows 示例）指向本地插件目录。
// ~/.dsh/profiles/<profile>/package.json
"dependencies": { "dsh-theater": "link:<home>/.dsh/plugins/dsh-theater" },
"dsh": { "profile": { "bundles": ["...", "dsh-theater"] } }
New-Item -ItemType Junction -Path "$env:USERPROFILE\.dsh\profiles\<profile>\node_modules\dsh-theater" `
-Target "$env:USERPROFILE\.dsh\plugins\dsh-theater"
将 <profile>、<home> 换成你的 profile 名与本机 home 路径。插件需先放到 ~/.dsh/plugins/dsh-theater（或联接目标路径）。DSH 社区目录页：https://www.skillhub.cn/plugins/KarBurKi/dsh-theater ；源码：https://github.com/KarBurKi/dsh-theater 。
典型用法（流程）¶
下面是从工具职责归纳的可复现流程，剧本与 cue 文案由导演会话自行维护。
- 用
theater_open为每个角色建会话，必要时一并绑音色。 - 用
theater_cast查看演员表与存活状态。 - 导演会话按剧情调用
theater_say，text内正文用代码块包裹；需要切到角色窗口时加focus: true。 - 已有会话需补绑音色时，调用
theater_bind。
适用场景与注意¶
适合：已在 DSH 里用独立会话扮演多角色、并由「导演」会话编排 cue 的工作流；需要与 dsh-tts 按会话绑 GPT-SoVITS 音色的场景。
注意：
- 插件以当前 DSH 宿主进程权限运行；安装前请阅读仓库源码与许可证，自行评估信任边界。
- 社区目录 skillhub.cn 为独立站点，与 DeepSeek / 幻方无官方从属关系；DSH 生态理念是「一切皆插件」，本文介绍的是社区贡献插件，非官方应用商店条目。
- GitHub 星标数为 0（目录页与公开仓库一致时以你查阅时点为准）。
结尾¶
dsh-theater 把多角色剧场的 Host 侧收束为四个工具：开演、说 cue、绑音、查 cast；剧本留在导演侧。若你的场景是「多窗口、等一手、可选不切窗、可选 TTS」，可按 README 的 link 安装方式接入 profile。
- 目录页：https://www.skillhub.cn/plugins/KarBurKi/dsh-theater
- GitHub：https://github.com/KarBurKi/dsh-theater
