dsh-liketavern

在 DeepSeek Harness 桌面端或 dsh web 中使用角色卡、世界书与长期记忆，开启 Tavern 式角色扮演。

中文 | English

功能特性 · 核心概念 · 安装与升级 · 快速上手 · 日常使用

兼容范围 · 数据与备份 · 常见问题与诊断 · 文档指南 · 开发与调试 · 参与贡献

dsh-liketavern 是为 DeepSeek Harness（简称 dsh）打造的角色扮演插件。你可以直接导入 SillyTavern（简称 ST）规范的角色卡和提示词预设，在 dsh 原生环境中管理设定、推进剧情、分支出行和无损回滚。

• 宿主负责：模型接入、长上下文聊天历史、工具调度与 Agent 运行时。
• 插件负责：角色资产管理、ST 预设与提示词组装、剧情状态隔离（记忆/世界状态/变量）、交互卡与脚本沙箱。
• 开箱即用：内置 EJS 模板引擎、酒馆助手接口子集、原生 MVU 支持；界面默认跟随宿主语言。

💡 第一次使用？ 建议先阅读环境要求与安装并跟随快速上手 5 步走体验第一场对话；若需迁移现有 ST 资产，请先核对核心概念与兼容范围。

功能特性

🧩 智能工具调用：角色扮演默认直接流畅回复；仅在缺失关键设定或需要固化重要剧情事实时，模型才会精准调用工具，兼顾沉浸感与长期一致性。

核心概念

在开始使用前，了解以下核心概念有助于更好地理解插件的运作机制：

flowchart LR
    subgraph Shared["共享资产 (复用)"]
        Card["角色卡 (Character)"]
        Preset["提示词预设 (Preset)"]
        Persona["用户人设 (Persona)"]
    end

    subgraph Runtime["运行时 (隔离)"]
        Session["宿主会话 (Session)"] --> Story["独立剧情状态 (Story)"]
        Story --> Mem["长期记忆 / 变化层"]
        Story --> Vars["卡片变量 / 局部世界书"]
        Story --> WAL["事务回滚日志 (WAL)"]
    end

    Shared -.->|"绑定到"| Runtime

安装与升级

环境要求

📌 首次接触 dsh？建议先查阅 DeepSeek Harness 官方文档，运行一次 dsh web 完成基础配置。

桌面端：从 GitHub 安装与升级

打开 「插件 → 添加插件」，在输入框填写以下 GitHub 地址并安装：

https://github.com/Amakurai/dsh-liketavern.git#v0.5.1

升级时先在「插件」页面卸载旧 Tavern，再用新版本标签重新添加，最后完全退出并重启桌面端。「设置 → Tavern → 关于」中的「检查更新」只查询正式发布与宿主兼容性；安装由桌面端插件管理页面完成。仓库已包含预编译的 lib/，无需本地构建。

Web / CLI：通过 dsh plugin 安装

在终端中执行以下命令，固定安装到最新稳定标签：

# 1. 添加插件到 web profile
dsh plugin --profile web add github:Amakurai/dsh-liketavern#v0.5.1

# 2. 检查安装状态
dsh plugin --profile web list --depth 0

# 3. 启动 dsh web（若已在运行，请先停止再启动）
dsh web

本仓库已包含预编译的 lib/ 产物，无需本地配置 TypeScript 构建环境。

方式二：通过 Release 安装包（离线环境）

1. 从 v0.5.1 Release 下载 dsh-liketavern-0.5.1.tgz（发布页附带 SHA256SUMS.txt 校验和）。
2. 在压缩包所在目录执行：

dsh plugin --profile web add ./dsh-liketavern-0.5.1.tgz
dsh web

检查与升级

• 图形界面检查：在 dsh 内打开 「设置 → Tavern → 关于」，可查看当前版本并一键检测 GitHub 最新发布。
• 桌面端升级：核对 更新日志 中的兼容说明，备份数据后卸载旧插件，再通过「添加插件」填写新版 GitHub 标签地址，安装后完整重启桌面端。
• Web / CLI 升级：在终端运行新版本的 dsh plugin add 命令并重启 dsh web。
• 升级过程会自动沿用现有数据目录（详见数据与备份）。

快速上手

只需要 5 步，即可体验完整的 Tavern 角色扮演：

  1. 导入角色卡    ➔    2. 新建会话    ➔    3. 配置设定    ➔    4. 开始对话    ➔    5. 探索分支
(PNG / JSON 导入)   (选择 Tavern 模式)   (绑定预设/世界书)     (切换开场白)     (重试/回退/代答)

1. 准备角色卡 进入「设置 → Tavern → 角色」，点击「导入角色」选择 PNG 或 JSON 文件。系统会展示静态兼容性检查报告，确认后即可保存。
2. 新建剧情会话 点击新建会话，选择 「Tavern 模式」，在弹出的列表中点选刚刚导入的角色卡。
3. 确认会话设定 点击会话顶部的角色入口，可为当前会话单独微调提示词预设、人设或附加世界书（初次体验保持默认即可）。
4. 选择开场白并开局 若角色卡包含多条开场白，使用左右箭头 ‹ › 挑选心仪的开局，点击「开始对话」并发送第一句台词。
5. 自由调整与分支探索 对 AI 的回答不满意？使用消息右侧的操作栏：
   • 🔄 重新生成 / ✏️ 编辑：自动创建独立时间线分支，随时通过 ‹ n/m › 在多条分支间无缝切换。
   • ⏩ 继续生成：让 AI 顺着当前文本继续扩写。
   • 🎭 AI 代答：让 AI 替你构思下一句回应（自动复制到剪贴板）。

🔍 调试提示词：第一轮对话完成后，可点击会话顶部角色入口的 「提示词预览 → 最近请求」，查看实际发送给模型的完整请求结构与上下文。

日常使用

配置入口与生效范围

🌐 多语言界面：插件界面语言默认跟随 dsh 宿主；你也可以在「Tavern → 设置 → 界面 → 界面语言」中手动固定为中文或 English。

剧情分支与回滚机制

不同于传统单线对话，dsh-liketavern 具备细粒度的状态快照与回滚隔离能力：

[主线剧情] ─── 第 1 轮 ─── 第 2 轮（获得钥匙） ─── 第 3 轮（开启大门）
                                  │
                                  └── [重新生成第 2 轮] ─── 分支 2（钥匙断裂，记忆自动回滚）

• 分支安全：在第 2 轮重新生成时，插件会自动建立独立子会话，并撤销第 2 轮之后产生的所有派生记忆与世界状态。
• 互不干扰：主线依然保留「获得钥匙」的事实，分支 2 则拥有全新的剧情状态，两者独立演进。
• 编辑 AI 回复：同样会安全切入新分支，撤销该楼层后的派生事实，等待你继续交互或手动调整。

兼容范围

第三方卡片、模板与脚本

• 酒馆助手（Tavern Helper）：已支持变量存储、脚本库加载、世界书读写及主要消息操作接口。部分高级功能（如 generateRaw、跨页面事件广播）正在逐步适配中。详情请查阅 酒馆助手兼容说明。
• EJS 提示词模板：原生内置，兼容常见的 ST 模板表达式，无需额外安装扩展插件。详见 提示词模板说明。
• 渲染安全与 Markdown：全面采用 markdown-it 替代存在安全风险的历史解析器。HTML 交互卡面运行在严格的 sandbox iframe 中，阻止主页面 DOM 与敏感接口逃逸。
• 原生 MVU 支持：支持纯官方规范的 MVU 导入与原生执行；自定义框架保留原代码运行。

提示词与采样机制

数据与备份

数据存储架构

所有插件数据均存放在 $DSH_HOME/dsh-tavern/（默认路径为 ~/.dsh/dsh-tavern/，Windows 下为 %USERPROFILE%\.dsh\dsh-tavern\）：

$DSH_HOME/dsh-tavern/
├── characters/         # 角色卡元数据与私有资产
├── presets/            # 提示词预设
├── lorebooks/          # 全局与角色世界书
├── personas/           # 用户人设
├── stories/            # 独立剧情数据（记忆、变量、WAL 日志）
└── editor-drafts/      # 未保存编辑草稿暂存

🛡️ 核心原则：角色资产共享，剧情状态隔离。 每个故事和分支都拥有专属的状态存储与写前日志（WAL），多分支间绝不相互污染。

备份方式对比

命令行备份与恢复

在插件目录或安装环境中，提供了可靠的备份与恢复 CLI 工具：

# 1. 创建完整备份（--offline 声明停止写入）
node lib/backup.js create --home "C:/data/dsh-home" --backup "D:/backups/dsh-2026-09-19" --offline

# 2. 校验备份文件完整性与结构合法性
node lib/backup.js verify --backup "D:/backups/dsh-2026-09-19"

# 3. 恢复到指定的新目录
node lib/backup.js restore --backup "D:/backups/dsh-2026-09-19" --target "C:/data/dsh-restored" --offline

若全局安装了工具，可直接使用 dsh-tavern-backup 命令代替 node lib/backup.js。

常见问题与诊断

常见问题排查

一键只读诊断

当遇到难以排查的异常时，可在终端运行只读诊断工具，快速获取环境状态与问题码（绝不输出任何隐私数据、路径或正文）：

# 线上安装环境运行
dsh plugin --profile web exec dsh-tavern-doctor

# 输出结构化 JSON
dsh plugin --profile web exec dsh-tavern-doctor --json

文档指南

更多进阶指南与底层架构设计文档（推荐卡片作者与开发者查阅）：

开发与调试

本地构建与验证

项目采用 TypeScript ESM（NodeNext）、React 18 与 Vitest：

# 1. 安装依赖
npm ci

# 2. 编译产物
npm run build

# 3. 运行完整测试套件 (150+ 测试套件)
npm test

# 4. 发布包完整性预检
npm run package:check

本地开发环境挂载

# 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

目录结构概览

src/
├── core/     # 纯函数层：提示词组装、世界书逻辑、正则引擎、BM25 检索与兼容解析
├── state/    # 文件存储层：角色资产、剧情隔离工作区、记忆持久化与 WAL 事务日志
├── node/     # 宿主编排层：生命周期配置、服务注册、请求投影管线与后台维护
├── client/   # 界面层：React 管理页面、会话操作栏、沙箱卡面与脚本宿主
├── index.ts  # 插件主入口 (Host Plugin Entry)
├── agent.ts  # Agent 运行时与工具装配入口
└── remote.ts # 前后端强类型 RPC 契约

参与贡献

问题反馈

若遇到问题，欢迎前往 GitHub Issues 提交反馈。为便于快速定位，请在描述中附带：

1. 运行环境：插件版本、dsh 版本、Node.js 版本、操作系统与安装方式。
2. 复现步骤：涉及的页面、操作顺序、预期表现与实际异常现象（可附带只读诊断输出）。
3. 最小复现样本：脱敏后的角色卡或手写测试卡（若涉及第三方卡片特殊脚本）。
4. 提示：截图与日志请务必剔除 API Key、私人对话与个人敏感信息。

代码与文档贡献

• 欢迎提交第三方卡片接口适配、Bug 修复、复现测试用例与文档纠错（如失效链接/勘误）PR。
• 涉及新特性或底层架构调整，请先在 Issue 中讨论设计方案与使用场景。
• 开始开发前请查阅 开发约定。
• 提交 PR 前请确保 npm test 与 npm run package:check 全项通过，并保持中英文文档同步。

开源协议

本项目采用 MIT License 开源。