dsh-liketavern
dsh web 的 Tavern 模式 — 在 dsh agent runtime 上支持 SillyTavern 角色卡、提示词预设、世界书、角色设定和正则表达式。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:Amakurai/dsh-liketavern#530f32005f555fb89be355d1ac2a511bbfa3e8a0Liketavern 以 dsh-liketavern 发布，当前版本为 0.3.1。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
在 DeepSeek Harness 的 dsh web 中使用角色卡、世界书与长期记忆，开始 Tavern 式角色扮演。
v0.3.1 · 适配 dsh 0.1.5-rc.2 · Node.js ≥ 24
中文 | English
dsh-liketavern 是 DeepSeek Harness 的角色扮演插件。你可以导入 SillyTavern（下文简称 ST）角色卡和提示词预设，在 dsh 中管理设定、推进剧情、重新生成和切换分支。模型连接、聊天历史和 agent 运行时由 dsh 提供，插件负责角色资产、提示词组装和剧情状态；界面默认跟随宿主语言。
内置 EJS 提示词模板、酒馆助手部分接口和可选原生 MVU。第三方卡片能否直接使用，取决于其依赖的接口；具体范围见下方兼容说明。
第一次使用可从安装和第一段对话开始；迁移已有 ST 资产时，先核对基本概念和兼容范围；开发与适配入口在文档。
| 功能 | 当前能力 |
|---|---|
| 角色卡 | 导入 V1 / V2 / V3 的 PNG、JSON 角色卡，导出 PNG / JSON；支持可恢复的收纳箱与引用保护永久删除；多开场白、内嵌世界书、卡内正则与 HTML 交互卡 |
| 预设与人设 | 导入、编辑和导出 ST 提示词预设；人设提供 {{user}} 名称和描述；预设与人设在读写入口校验数据 |
| 世界书与世界状态 | 全局、角色、会话级世界书；关键词触发、常驻条目；剧情变化层记录新增、变更和失效的事实 |
| 长期记忆 | BM25 检索与时间衰减，模型按需读写；超过容量时在空闲阶段自动摘要，保留可检索的归档来源 |
| 剧情分支 | 重新生成、编辑和回退创建独立子会话，撤销受影响的记忆、变量等剧情状态，保留原会话 |
| EJS 模板 | 条件、循环、异步表达式、剧情及消息变量、JSON / YAML 初值、JSON Patch、Zod、Lodash、Faker 与世界书装饰器 |
| 交互卡与脚本 | 沙箱卡面、三类脚本库、剧情变量持久化、同页面同剧情事件、世界书读写、消息编辑 / 删除 / swipe 与显示刷新 |
| 原生 MVU | 可选自动初始化与正常回复后的变量更新，失败任务保留重试；受限适配角色展示正则声明的状态栏占位符 |
| 代答与续写 | AI 代答生成用户台词并复制到剪贴板；续写沿当前会话继续生成 |
模型可按需调用 7 个工具：记忆检索 / 写入 / 更新、世界书按条读取、世界状态更新、资产列表 / 读取。普通扮演直接回复，缺少设定或需要记录已确定事实时再使用工具。
编辑器支持未保存提示和草稿恢复；设置页、表单和弹窗适配窄屏。第三方交互卡内部是否适配手机，仍由卡片自身排版决定。
角色管理页、收纳箱和新会话角色选择器支持按角色名、标签、作者或内嵌世界书名搜索。
| 名称 | 用途与区别 |
|---|---|
| Tavern 模式 | dsh 的会话预设，负责启用插件的角色扮演运行时；新建会话时选择 |
| 提示词预设 | 在 Tavern「预设」页管理的 ST 提示词配置；绑定到角色会话后使用，可先用内建默认值 |
| 角色卡 / 人设 | 角色卡描述 AI 扮演的角色；人设描述你在故事中的身份，并提供 {{user}} 的名字 |
| 世界书 / 记忆 / 世界状态 | 世界书提供背景设定；记忆记录剧情事实；世界状态记录设定在剧情中的新增、变更与失效 |
| 会话 / 剧情 / 分支 | 会话保存聊天记录，绑定的剧情保存插件状态；重新生成等操作会创建子会话及独立剧情 |
| MVU | 卡片常用的变量更新框架；本插件提供可选原生执行器，供依赖变量更新的卡使用 |
| 项目 | 要求 |
|---|---|
| Node.js | 24 或更新版本；当前开发与 Windows / Ubuntu CI 使用 Node 24 |
| dsh CLI / 宿主 | 0.1.5-rc.2，本插件的宿主依赖锁定此版本 |
| pnpm | 已安装且可在终端运行，供 dsh plugin 管理插件依赖 |
| 模型 | 在 dsh 中完成模型配置，能够正常对话 |
首次使用 dsh 可先参考官方文档，运行一次 dsh web 完成配置。web profile 会在首次启动或安装插件时自动初始化。
在终端执行，固定到发布标签：
dsh plugin --profile web add github:Amakurai/dsh-liketavern#v0.3.1
dsh plugin --profile web list --depth 0
确认列表中出现 dsh-liketavern 后，停止已运行的 dsh，再启动：
dsh web
本仓库包含编译好的 lib/，普通安装无需自行构建。插件会作为组合包自动加入 web profile；安装机制见官方打包与安装插件。
从 v0.3.1 Release 下载 dsh-liketavern-0.3.1.tgz，在文件所在目录执行：
dsh plugin --profile web add ./dsh-liketavern-0.3.1.tgz
安装后同样重启 dsh web。Release 附有 SHA256SUMS.txt，可用于核对下载文件。
在「设置 → Tavern → 关于」可查看插件和宿主版本、打开 GitHub 项目，并点击「检查更新」查询最新正式发布。页面会核对宿主版本；发现兼容的新版本后可复制固定发布标签的更新命令。当前宿主通过终端安装更新，检查按钮不会自动安装。源码开发版会提示在源码目录更新并构建。自定义 profile 需将命令中的 web 改为对应名称。
先核对更新日志中的宿主版本，停止 dsh 并备份数据，再执行目标版本的安装命令。升级插件沿用现有数据目录；完整备份范围见数据与备份。
未带 #版本标签 的 GitHub 地址跟随仓库默认分支。希望固定运行内容时，使用正式标签或具体 commit。升级 dsh 宿主前，也需要确认有对应的插件版本。
先完成 dsh 的模型配置，再用一张角色卡跑通普通对话。提示词预设可使用内建默认值，人设、附加世界书、脚本和 MVU 按卡片需要再配置。
‹ n/m › 切换。收到第一条正常回复后，可从会话顶部角色入口打开「提示词预览 → 最近请求」，查看本轮实际捕获的请求。脚本卡的后续配置见脚本与原生 MVU。
下表中的「Tavern」指 dsh 设置里的 Tavern 管理页。
| 想做什么 | 入口 | 生效范围 |
|---|---|---|
| 管理角色卡、提示词预设、世界书和人设 | Tavern → 角色 / 预设 / 世界书 / 用户 | 共享资产；用于这些资产的后续提示词组装 |
| 设置以后选卡时的默认组合 | Tavern → 设置 → 默认配置 | 之后在新会话中点选角色时套用，已绑定会话单独调整 |
| 调整当前会话的预设、人设、世界书与作者注释 | 会话顶部角色入口 | 当前会话，保存后用于后续轮次 |
| 编写只属于这条剧情的世界书 | 会话顶部角色入口 → 编辑本会话世界书 | 当前剧情，随分支继承和回滚 |
| 查看或修订记忆、世界状态、角色笔记 | 会话顶部角色入口 → 记忆；或 Tavern → 记忆 | 当前 / 所选剧情；选择「初始状态」则只影响未来新剧情 |
| 管理正则、脚本与变量备份 | Tavern → 正则；Tavern → 设置 → 脚本 / 卡片与数据 | 正则和脚本按所选来源管理，变量备份按角色与剧情选择 |
| 检查提示词与世界书触发情况 | 会话顶部角色入口 → 提示词预览 | 当前会话，只读查看 |
提示词在每轮首次成功组装后固定；生成中编辑资产或设置，会在下一轮使用。界面语言默认跟随宿主（中文宿主显示中文，其余显示英文），也可在「Tavern → 设置 → 界面 → 界面语言」固定为中文或 English；语言选择立即保存，仅影响插件界面。
例如，原会话中已经记录「角色取得钥匙」，你回到取得钥匙之前重新生成：插件会创建独立子会话，在子剧情中撤销未继承楼层的记忆、变量等状态，原会话仍保留原来的发展。两条剧情此后独立演进，共享的角色卡和预设仍可复用。
编辑 AI 正文也会创建分支，并撤销该层及后续派生事实；保存编辑后，由你接话或手动修订状态。续写则沿当前会话继续生成。更详细的边界见提示词、采样和楼层操作。
generate / generateRaw、消息插入与旋转、历史分页和跨页面事件等仍待适配。完整接口和示例见酒馆助手兼容说明。BEFORE_MESSAGE_UPDATE 正文更新钩子仍待适配。当前界面没有独立的变量 schema 编辑器入口。parent.TavernHelper、parent.$ 或 Node 访问。网络请求及外部脚本默认受限，可在「设置 → 卡片与数据」配置可信域名；图片和字体按现有策略加载。| 项目 | 实际行为 |
|---|---|
| 采样参数 | 导入预设保留受支持的采样字段，并按字段覆盖插件设置，未提供的沿用插件设置；旧预设需重新导入以补回以前未保存的参数。temperature、maxTokens、stop 及插件设置中模型公布的思考档位可以生效；top_p、惩罚系数仅记录并提示。宿主锁定关闭思考时，插件不能强制开启 |
| 提示词预览 | 「最近请求」在官方 DeepSeek 通道显示布局与系统能力处理后的消息及兼容说明；其它通道显示宿主请求。其他页签是重新计算的 ST 模拟，不能代表实际入模消息 |
| 预设语义 | 卡级主提示词与后置指令替换原槽位，遵守开关、触发场景及禁止覆盖设置；「设置 → 提示词」可分别关闭这两种角色覆盖。仅通过 {{original}} 保留原文。动态宏变量的后续读取进入本轮上下文，静态变量仍可使用稳定前缀 |
| 预设格式与宏 | 保留 wi_format、scenario_format、personality_format；空格式发送原字段，旧预设需重新导入原 JSON 补回格式。lastmessage 读取最后一条真实用户或角色消息，charPrompt / charInstruction 读取卡片提示字段。导出内建标记 system_prompt 与消息角色独立，自定义 system 条目可往返 |
| 预设消息位置 | DeepSeek 官方通道自动使用 Tavern 适配器按角色、顺序与深度插入预设。支持途中更新 system 的模型使用完整系统快照；只读首条 system 的模型将系统条目合并到首条，user/assistant 保留位置。继续使用原宿主聊天、工具、凭证及流式回复；每轮冻结布局，不替换历史正文。其他供应商暂沿用 standing/turn 两段映射 |
| 正则与助手预填 | 实时展示使用 output/render；历史正则改写用于模拟与代答。末尾 assistant 条目按普通 assistant 消息发送，尚未实现供应商专用 prefill/prefix 协议；不能据此保证模型从该文本继续生成 |
| 改写与删除 | 楼层编辑、回退、重新生成及脚本消息删除通过分支实现，原会话保留。编辑 AI 正文会撤销该层及后续派生事实，不自动重新提取或发起回复 |
| 回滚范围 | 回滚覆盖插件剧情状态；剧情工作区之外的工具副作用不会随楼层操作撤销 |
Tavern 使用 dsh 原生 PTC（程序化工具调用）。需要查证或记事时，模型可用一次 run_code 合并操作，独立查询可并行，只回传必要结果。写入仍经当前剧情的楼层事务。更新后重启 dsh，以加载插件托管的 Tavern 预设；自建宿主需提供 codeRuntime，与原装 PTC 模式要求相同。
插件数据位于 $DSH_HOME/dsh-tavern/。未设置 DSH_HOME 时，默认是 ~/.dsh/dsh-tavern/（Windows 为 %USERPROFILE%\.dsh\dsh-tavern\）。宿主聊天记录与配置还保存在 dsh 的其他目录；完整迁移或升级备份应在停止 dsh 后复制整个 DSH_HOME。
角色资产共享，剧情状态隔离。 同一角色的卡片、预设和脚本资产可复用；每个剧情及分支独立保存记忆、世界变化、笔记、聊天世界书、变量和回滚日志。新剧情复制角色初始状态，修改「初始状态」只影响之后创建的剧情。同一数据目录不支持多个宿主进程同时写入。
| 保存方式 | 包含什么 | 如何恢复 / 注意事项 |
|---|---|---|
| 交互卡变量备份 | 已保存的当前剧情变量，变量数据最多 1 MiB | 「设置 → 卡片与数据」选择角色与剧情，导出或粘贴备份恢复；不包含消息正文、角色卡、脚本资产或尚未写入变量的表单输入 |
| 编辑草稿暂存 | 角色、预设、世界书、用户、正则、记忆和设置的未保存编辑 | 出现「草稿已暂存」后，在同一浏览器标签页刷新或重开编辑器可恢复；仍需点保存才能应用。单份上限 2 MiB |
| 可校验目录备份 | DSH_HOME 内插件数据、宿主会话与配置；含版本、文件大小及 SHA-256 清单 | 用下方命令创建、校验、恢复到新目录；排除可重装的 profile 依赖，变量导出不能替代此备份 |
编辑草稿保存在插件数据目录的 editor-drafts/，浏览器只保存随机标签页标识。关闭标签页或禁用浏览器存储后不保证恢复；暂存失败会保留页面内容并提供重试，明确放弃会清除对应草稿。角色预览中的交互数据是临时的，不会写入真实剧情。
在插件源码或安装目录中使用以下命令，把示例路径替换为实际路径。备份和恢复的目标必须不存在，其父目录必须已存在。
node lib/backup.js create --home "C:/data/dsh-home" --backup "D:/backups/dsh-2026-09-19" --offline
node lib/backup.js verify --backup "D:/backups/dsh-2026-09-19"
node lib/backup.js restore --backup "D:/backups/dsh-2026-09-19" --target "C:/data/dsh-restored" --offline
安装环境已暴露命令时，也可将 node lib/backup.js 换成 dsh-tavern-backup。加 --json 可读取结构化结果。校验会拒绝缺失、篡改和额外文件，并检查插件数据结构、绑定引用和 WAL；恢复先验证并在临时目录复制，成功后才发布新目录，不覆盖现有数据。宿主压缩历史按字节校验，不做完整语义解析，恢复后仍需实际打开会话检查。
--offline 是操作者的停机声明；工具可拒绝仍活跃的 PID 锁，但无法证明所有写入进程均已停止。DSH_HOME 指向恢复目录；保留原备份。清单记录执行备份工具时的版本，不能证明数据最后由哪个历史版本写入。备份保留 profile 配置和锁文件，精确排除 profiles/node_modules、profiles/<名称>/node_modules 与 profiles/<名称>/.dsh-module-fallback/node_modules；恢复后需按原 profile 重装依赖。其余位置的符号链接、junction、硬链接与异常文件会被拒绝，不跟随到目录外。自定义放在 DSH_HOME 外的插件数据、外部工作区及外部凭据需另行备份。目录备份没有加密，可能包含本地凭据和私有对话，应按原数据同等保护。
旧版共享状态会在首次打开旧绑定时复制到独立剧情，原目录保留。此前混合的多分支事实无法自动可靠拆分，需要核对迁移结果。自动摘要可能遗漏信息，原文来源会保留；异常、截断或超时回复不会触发归档。分支与归档会占用磁盘，当前不自动清理旧剧情。
| 问题 | 排查方式 |
|---|---|
| 安装后没有 Tavern 模式或设置入口 | 用 dsh --version 确认宿主为 0.1.5-rc.2，再用 dsh plugin --profile web list --depth 0 检查安装目标；重启 dsh web 后新建会话，仍未出现时查看终端的插件加载错误 |
| 改了默认预设，当前对话没有变化 | 默认配置只在新会话点选角色时套用；当前对话在会话顶部角色入口修改并保存 |
| 卡片显示正常，但按钮、脚本或 MVU 不工作 | 检查交互卡是否启用，再到「设置 → 脚本」确认脚本及文件夹已启用并保存，查看运行诊断；自动 MVU 还需开启会话选项并保持页面打开，按兼容范围核对所需接口 |
| 记忆页为空，或修改没有作用于当前剧情 | 检查所选角色、剧情及是否选中了「初始状态」；长期记忆由模型工具或手动写入，对话正文不会逐条自动复制到记忆中 |
| 提示词预览与模型表现不一致 | 先查看「最近请求」及兼容说明；其他页签是 ST 模拟。新会话尚未发出请求、宿主重启或缓存淘汰后，最近请求可能为空 |
| pnpm 提示构建脚本被拦截 | 先核对报错涉及的依赖；插件源码构建问题可尝试 Release 安装包，宿主依赖按 dsh 提示检查对应 profile 的 pnpm-workspace.yaml 中的 allowBuilds |
安装环境可运行：
dsh plugin --profile web exec dsh-tavern-doctor
dsh plugin --profile web exec dsh-tavern-doctor --json
源码仓库中对应 npm run doctor 和 npm run doctor -- --json。报告只给出版本、目录状态、角色/剧情/WAL（回滚日志）数量和固定问题码，不输出真实路径、资产名称、ID、正文或令牌，也不提供修复参数。
仍无法定位时，可按问题反馈提供最小复现。
| 你要了解什么 | 文档 |
|---|---|
| 版本变化、升级时的宿主要求 | 更新日志 |
| 卡面、脚本、变量、世界书、消息和 MVU 接口 | 酒馆助手兼容说明 |
| EJS、宏、装饰器与模板示例 | 提示词模板说明 |
| 第三方接口的适配进度与验收条件 | 酒馆助手适配进度、ST 模板兼容核对 |
| 剧情隔离、分支回滚、记忆和提示词通道 | 架构说明 |
| 已核对的宿主行为、UI 冒烟范围及升级检查 | 宿主兼容记录 |
| 依赖安全更新、剩余告警与隔离边界 | 依赖安全记录 |
| 代码边界、测试、发布包与交付要求 | 开发约定、发布包审核 |
开发栈为 TypeScript ESM（NodeNext）、React 和 Vitest。先克隆本仓库并进入目录；当前宿主包版本以 package.json 为准。
在 Node 24 下，从仓库根目录执行：
npm ci
npm run build
npm test
npm pack --dry-run
lib/ 是提交到 Git 的交付物，修改 src/ 后必须重新构建并同步提交。npm pack 会先构建；发布包仅包含编译产物、插件配置、预设及发布说明文件。测试使用手写工厂数据，不提交真实卡片、会话或记忆。
| 命令 | 用途 |
|---|---|
npm run dev | 通过仓库的 cordis.patch.yml 启动本地 dsh web，需先完成下方挂载 |
npm run doctor | 只读检查当前 DSH_HOME，不修复数据 |
npm run doctor:check | 在临时环境验证编译后的诊断入口、安装链接和 JSON 输出 |
npm run package:check | 检查打包白名单、必要产物与发布文档的相对链接；需先构建 |
CI 在 Ubuntu 与 Windows 上执行构建、测试、诊断入口和打包检查，并在 Ubuntu 检查 lib/ 与提交一致。宿主升级还需完成安装环境的启动与 UI 冒烟，核对步骤见宿主兼容记录。
先运行一次 dsh web 初始化 profile，再把仓库挂载到 $DSH_HOME/profiles/node_modules/dsh-liketavern。以下示例使用默认的 ~/.dsh；自定义 DSH_HOME 时请替换路径。使用专用开发数据目录，避免已安装的发行包遮蔽本地挂载。
# Windows（PowerShell，在仓库根目录执行）
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.dsh\profiles\node_modules" | Out-Null
New-Item -ItemType Junction -Path "$env:USERPROFILE\.dsh\profiles\node_modules\dsh-liketavern" -Target (Get-Location).Path
# macOS / Linux（在仓库根目录执行）
mkdir -p ~/.dsh/profiles/node_modules
ln -s "$(pwd)" ~/.dsh/profiles/node_modules/dsh-liketavern
挂载完成后执行 npm run dev，会以 dsh web --patch ./cordis.patch.yml 启动。代码变更后先运行 npm run build，再重启开发实例验证。
src/
├── core/ 纯函数：提示词、世界书、正则、宏、BM25、兼容数据处理
├── state/ 文件存储：角色资产、剧情工作区、记忆与回滚日志
├── node/ 宿主编排：配置、服务、管线、楼层、工具与维护
├── client/ React 界面：管理页、会话操作、交互卡与脚本运行器
├── index.ts 宿主入口
├── agent.ts agent 入口
└── remote.ts 前后端业务契约
test/ 保存行为与集成测试，scripts/ 保存构建和交付检查，presets/ 保存 Tavern 宿主预设，docs/ 保存专题说明，lib/ 保存发布产物。
在 GitHub Issues 提交问题时，请包含：
涉及提示词问题时，请说明依据的是「最近请求」还是 ST 模拟；提交截图或日志前移除密钥、私人剧情与个人信息。
修正文案、补充翻译、提供最小复现和接口适配都欢迎提交 PR。较大的功能或兼容性调整，建议先在 Issue 中说明使用场景与预期行为。
开始前阅读开发约定。修改 core/state 时补行为测试，涉及宿主事件、分支、请求或故障时补集成测试；修改源码后同步构建产物。README 的使用说明保持中英文同步，PR 中写明改动原因和实际完成的验证。