DSH 契约

core 支持 DSH >=0.2.1-rc.2 <0.2.2；不再支持 0.2.0，因为 0.2.1 移除了本代码使用的子智能体启动选项和不变量软件包，并改变了接管已存储对话的方式。大部分集成使用公开 Cordis 服务和插槽；拥有专属工具的辅助智能体同样只用公开 API：由 bundle 提供预设的 DSH 子智能体激活。开发依赖与契约测试固定到一个经过测试的准确 DSH 版本；每次升级 DSH 都必须重新复核，之后才能扩大支持范围。

所有角色扮演聊天共享一个以数据根目录为工作目录的 DSH workspace。聊天 id 为 session-<角色扮演会话 UUID>，角色扮演数据库才是事实来源；聊天丢失时可重建。DSH 的 create 只在已存储的聊天还没有任何回合时才复用它，否则会用另一个 id 新建聊天，所以已存在的聊天绝不再次创建：已存储的聊天（带有开场白）会被接入项目，只有确实不存在的聊天才会创建，而 DSH 用了与请求不同的 id 时会直接拒绝。归档或删除会话时，先停止并隐藏 DSH 聊天，再处理会话目录。

开场消息必须在创建 live agent 前作为完整第一回合写入。存储头必须使用 workspace 规范路径和 roleplay preset。不要在已构造的循环上追加开场，否则会造成回合编号冲突。

浏览器在实际操作时解析 uiWorkspace，不要仅为了打开聊天就把它加入 client inject；在初始组合没有该服务的 profile 中，这会使角色扮演面板无法渲染。

通过 ctx 注册服务、监听、HTTP 路由、定时器和客户端插槽；返回手动 disposer 的 API 用 ctx.effect。热重载后不得留下重复项。密钥遵循 DSH 的凭据接口：配置里只放引用（apiKeyRef，类似 POSIX 的名称），值由 ctx.credentials 保存并在每次请求时解析；ctx.remote.credentials 不对外部插件开放，所以由宿主通过 set/unset 写入。该接口在本地声明类型，服务在使用时才查找，因此没有它的配置档仍可加载。runChild 通过 startActivation 在 roleplay-helper 预设下启动子智能体，并在其创建时限制其全局工具、把它自己的工具注册到其作用域；若 DSH 改动这一点，应迁移这一层，不能通过全局暴露工具来规避。

渲染器读取 narrate 工具结果里的 <roleplay-output>。协议标记、JSON 字段和事件顺序是兼容表面，不能本地化。世界创作默认使用审批，审批只授权当前提议的修改；拒绝后文件必须保持不变，对话仍能继续提出修订方案。明确启用自动模式只会跳过审批请求，不会跳过验证、原子替换或可恢复删除。

扩展 DSH 版本范围前，检查导出和组合 API、开场恢复、命名、workspace 关联、归档/停止、审批、客户端插槽、渲染、压缩、取消和热重载，并实测“开局 → 游玩 → 回退 → 分支 → 重开”。