# dsh-character-studio

[![npm](https://img.shields.io/npm/v/dsh-character-studio.svg)](https://www.npmjs.com/package/dsh-character-studio)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

**DeepSeek Harness 原生沉浸式角色扮演（RP）与伴侣互动插件**。将「解耦角色卡机制（SOUL 框架 + Markdown/Tavern 外部卡库）」与「Hindsight 图谱实体记忆引擎」深度联通，让 DSH 成为轻量、优雅且具备生产级长期记忆的原生 RP 娱乐宿主。

[English](README.en.md) | 简体中文

---

## 🌟 核心优势与竞品区别

相比 DSH 生态已有的方案以及传统酒馆（SillyTavern），`dsh-character-studio` 具备以下关键优势：

| 对比维度 | 传统酒馆 (SillyTavern) | 社区已有 DSH RP 插件 | **dsh-character-studio (本插件)** |
|---|---|---|---|
| **系统架构** | 重前端单体，配置繁琐，多端同步重 | 侵入性修补 Host 或纯静态提示词 | **原生轻量 Cordis 插件**，标准非侵入，零多余依赖 |
| **长期记忆机制** | 简单滑动窗口/粗粒度向量搜索，易遗忘 | 本地单文件追加或无图谱记忆 | **对接 Hindsight 生产级实体图谱与时序推理** |
| **多角色记忆隔离**| 手动切换数据库/易发生设定与记忆串线 | 全局共用一份记忆，多角色易串戏 | **专属 Bank 隔离 (`rp_<角色名>`)**，换角色不串戏 |
| **思考沉浸度** | 需复杂正则拼接/依赖外部提示词注入 | 无深度思考链约束，偶发 AI 腔 | **DeepSeek 官方 `<think>` 第一人称内心独白注入** |
| **卡片与资产兼容**| 依赖专有前端格式与扩展插件 | 格式单一/需要手动修改代码 | **原生兼容 Markdown 三节卡与 SillyTavern V2 JSON** |

---

## 🌟 核心特性

- 🎭 **多格式角色卡原生加载**：
  - 标准 Markdown 角色卡（支持【角色】/【关系】/【对话】三节权威规范）；
  - 兼容 SillyTavern（酒馆）V2 JSON 角色卡；
  - 角色卡解耦外置，零代码热切换。
- 🧠 **Hindsight 专属 Bank 记忆隔离**：
  - 每个角色自动分配独立的 Memory Bank（如 `rp_alice`），杜绝跨角色记忆串线；
  - 跨会话沉淀剧情、羁绊与重要誓约，支持图谱实体与时间线关联分析；
  - 内置 60s 内存 TTL 召回缓存与写失效机制。
- 🎬 **DeepSeek `<think>` 内心独白沉浸推演**：
  - 官方级角色沉浸指令注入，在思考链内以第一人称进行心理分析与回复规划；
  - 严格规范酒馆级演出排版（台词 `""`、动作 `「」`、心理 `()`）与活人感法则。
- 🕹️ **斜杠命令与 OOC 导演交互**：
  - `/rp list`：一键列出所有角色卡与当前激活卡；
  - `/rp use <name>`：即时切换沉浸角色；
  - `/rp status`：查看角色状态、Bank 名与 Hindsight 连通状态；
  - `/ooc <directive>`：场外导演指令，用于调整剧情节奏或跳出戏份答疑。

---

## 📦 安装

### 从 npm 安装

```bash
dsh plugin --profile web add dsh-character-studio
# 或无头模式
dsh plugin --profile headless add dsh-character-studio
```

### 本地开发挂载

```bash
cd /path/to/dsh-character-studio
pnpm install && pnpm run build
dsh plugin --profile web add "link:$(pwd)"
```

---

## ⚙️ 配置说明

在 `$DSH_HOME/profiles/<profile>/settings.yaml` 或 Web 界面设置中配置：

| 配置项 | 默认值 | 说明 |
|---|---|---|
| `cardsPath` | `~/.dsh/cards` | 角色卡存放根目录（支持 `.md` 与 `.json`） |
| `defaultCard` | `""` | 默认激活的角色卡名称（留空则不默认激活） |
| `hindsightEndpoint` | `http://localhost:8888` | Hindsight 记忆服务 REST 端点 |
| `hindsightToken` | `""` | Hindsight 认证 Token（本地无需填写） |
| `bankPrefix` | `rp_` | 角色专属 Bank 的前缀 |
| `recallCacheTtlMs` | `60000` | 召回结果内存缓存时长（0 为禁用） |
| `enableDeepSeekImmersivePrompt` | `true` | 是否在 `<think>` 中注入第一人称内心独白规则 |
| `enableTavernFormatting` | `true` | 是否注入酒馆台词/动作排版规范 |

---

## 🛠️ 模型工具与命令

### 斜杠命令 (Slash Commands)
- `/rp list` — 查看角色卡库清单及当前状态。
- `/rp use <name>` — 切换当前扮演的角色。
- `/rp status` — 查看记忆库节点数与连通状态。
- `/ooc <message>` — 发送场外导演指示。

### 模型工具 (Agent Tools)
- `rp_recall(query, limit)` — 查询历史剧情、设定与共同经历。
- `rp_remember(content, context)` — 沉淀新的羁绊与重大事件。
- `rp_related(id, depth)` — 追踪记忆节点在关系图谱中的关联。
- `rp_status()` — 模型自检当前角色状态。

---

## 📄 开源许可

[MIT License](LICENSE)