dsh-plugin-tavern

Readme

# dsh-plugin-tavern · 酒馆

SillyTavern 精简版的两个 Agent Preset 插件：**角色卡解析管理员**（card-analyst）+ **角色扮演讲述者**（roleplay）。把任意 SillyTavern 角色卡（PNG/JSON，V1/V2/V3）解析成 `story.md + state.json`，然后用讲述者进行沉浸式连续角色扮演。

基于 SillyTavern 开源实现精读（[源码机制分析见 SPEC.md](assets/docs/SPEC.md)），按"单对话单角色"优化，核心机制（token 预算贪心填充、范例对话原文注入、增量摘要）复刻自 ST，另加 ST 没有的**结构化状态机**（好感度/心情/地点/剧情旗标）。

## 功能

| Agent | 做什么 |
|---|---|
| **酒馆-管理员** `card-analyst` | 解析角色卡：PNG tEXt chunk 提取（ccv3/chara）、V1/V2/V3 归一化、世界书扁平化；模型精修：归纳性格/说话风格、初始化状态机。产出 `story.md / state.json / analysis-log.md / meta.json` |
| **酒馆-讲述者** `roleplay` | 加载角色卡后连续扮演：第三人称叙述 + 引号对话，遵循卡内性格与说话风格，每轮自动更新 `state.json` 并追加历史，长对话增量摘要 |

## 安装

```bash
# 需要 DSH（DeepSeek Harness）与 pnpm
dsh plugin --profile web add git+https://github.com/Star-Guest/dsh-plugin-tavern.git
# 重启 DSH 后生效
```

插件安装后自动把两个 preset 与脚本物化到用户根：

```
~/.dsh/.agent-presets/card-analyst/   # 酒馆-管理员
~/.dsh/.agent-presets/roleplay/       # 酒馆-讲述者
~/.dsh/tavern/scripts/                # 解析/精修/扮演脚本
~/.dsh/tavern/SPEC.md                 # 规格书
```

## 使用

在 DSH GUI 新建会话，选择对应 preset：

**酒馆-管理员**
```
解析这张卡 /path/to/character.png
```
（支持 PNG 卡与 JSON 卡；纯图无元数据的卡会走视觉兜底）

**酒馆-讲述者**
```
加载 Blanche 开演
```
之后直接对话即剧情输入；指令：`换开场` / `查看状态` / `重置`。

## 模型要求

- 精修与扮演需要 DeepSeek 系 API 凭据（脚本从 `$DSH_HOME/.credentials.yaml` 或 `DEEPSEEK_API_KEY` 环境变量读取，与 Harness 共用）。
- 解析（`parse-card.js`）为纯确定性算法，无需 API。

## 工作原理

DSH 插件 = npm 包 + `cordis.patch.yml` 补丁。本插件的 patch 挂载一个 glue 插件（`src/index.js`），挂载时把 `assets/` 物化到用户根——因为 DSH 启动器会把 preset 根目录固定为 shipped 目录，插件无法通过配置注册新根，而用户根（`~/.dsh/.agent-presets`）天然被 roster 扫描。物化带版本标记：**用户自建的 preset 绝不覆盖**，插件升级自动刷新。

## 卸载

```bash
dsh plugin --profile web remove dsh-plugin-tavern
# 已物化的文件不会自动删除，手动移除即可：
rm -rf ~/.dsh/.agent-presets/card-analyst ~/.dsh/.agent-presets/roleplay ~/.dsh/tavern
```

## 安全说明

第三方插件代码，安装前建议审阅源码并固定 commit：

```bash
dsh plugin --profile web add git+https://github.com/Star-Guest/dsh-plugin-tavern.git#<commit-sha>
```

## License

MIT