角色扮演引擎 LiranHuang/dsh-roleplay-engine

DSH Roleplay Engine

将 SillyTavern 角色卡与世界书，原生接入 DeepSeek Harness 会话。

确定性上下文编译 · 世界书激活 · 预设人格绑定 · Prompt 诊断 · 中英双语设置界面

简介

DSH Roleplay Engine 是 DeepSeek Harness 的原生角色扮演插件。它能读取 SillyTavern 兼容的角色卡，把角色设定、世界书条目和回复协议编译成模型实际可见的系统提示词，并自动绑定到指定的 Agent Preset。

插件不会替换 Harness 原生会话历史，也不会额外维护一套聊天状态。它只在请求进入模型前生成当前回合所需的角色上下文，因此新建、恢复和分叉会话都能得到一致、可诊断的结果。

[!IMPORTANT]
本项目目前处于早期开发阶段，package.json 中仍标记为 private。公开仓库用于源码审阅、协作评估与本地非商业试用，不代表已经发布到 npm，也不代表作者放弃版权或授予开源许可。

功能亮点

| 能力 | 说明 |
| 🎭 角色卡兼容 | 支持 PNG 与 JSON 角色卡，包括 Character Card V3 元数据。 |
| 📚 世界书编译 | 合并角色卡内嵌 Lorebook 与多个外部 JSON 世界书。 |
| 🔎 确定性激活 | 支持主关键词、次关键词、大小写、整词、常驻条目与概率规则；相同输入产生相同决策。 |
| 🧩 预设人格绑定 | 按 presetId 自动绑定角色，可作用于全部会话或仅指定的活跃会话。 |
| ♻️ 会话生命周期 | 自动处理创建、恢复、分叉、人格切换、配置热更新和插件重载。 |
| 🧠 预算控制 | 通过上下文预算、输出预留和扫描深度控制注入内容。 |
| 🎚️ 回复丰富度 | 内置多轮场景、单轮场景和一句对白三种输出模式。 |
| 🛠️ 可观测性 | 可查看实际注入文本、编译 IR、世界书命中情况、预算与稳定哈希。 |
| 🌐 原生设置页 | 在 Harness 设置界面中管理绑定、扫描素材目录，并提供中英文界面。 |

工作方式

graph LR
A[角色卡 PNG / JSON] --> D[角色扮演编译器]
B[内嵌 / 外部世界书] --> D
C[原生会话历史与当前输入] --> D
D --> E[关键词匹配与预算裁剪]
E --> F[确定性 Prompt IR]
F --> G[Harness System Prompt Section]
G --> H[模型请求]

每个模型回合大致经过以下流程：

1. 根据当前 Session 的组合人格解析 presetId；
2. 加载对应角色卡，并合并内嵌和外部世界书；
3. 从原生会话历史中截取指定扫描深度的文本；
4. 确定性计算世界书条目的接受与拒绝结果；
5. 在上下文预算内按原子段落编译 Prompt IR；
6. 将渲染文本注入 Harness 的 System Prompt，而不改写原生聊天历史；
7. 保存诊断信息，供命令或 Agent Tool 检查。

支持格式

角色卡

- .png：带 SillyTavern 角色卡元数据的 PNG；
- .json：SillyTavern 兼容角色卡 JSON；
- 优先识别 Character Card V3（ccv3）元数据。

世界书

- .json 外部世界书；
- 角色卡中内嵌的 Lorebook；
- 可同时配置多个外部世界书，插件会统一规范化并合并条目。

安装

1. 克隆仓库

git clone https://github.com/LiranHuang/dsh-roleplay-engine.git
cd dsh-roleplay-engine

2. 安装依赖并验证

npm install
npm run check
npm test

3. 作为 Harness Bundle 安装

本仓库根目录本身就是一个 DSH Bundle，其中：

- package.json 声明 Host、Client 和 Bundle 元数据；
- cordis.patch.yml 挂载插件实例；
- index.js 提供 Host 端编译与运行时；
- client.js 注册 Harness 设置页。

在 DeepSeek Harness 的插件管理界面或管理工具中，选择 Install Bundle / 安装 Bundle，并将目标指向本仓库的绝对路径。安装后，进入 Harness 的 设置 → 角色扮演引擎 完成绑定。

安装权限与信任边界

安装 Bundle 会让插件代码在 Harness Host 与 Web Client 环境中运行。安装前请审阅源码，并确认你信任本仓库及所安装的具体提交。

插件运行时需要以下能力：

| 能力 | 用途 |
| 读取本地文件 | 加载你明确配置的角色卡和世界书。 |
| 枚举所选目录 | 在设置页中列出当前目录层级的 PNG / JSON 候选文件。 |
| 注册本地 HTTP 路由 | 向设置页提供候选文件和活跃会话列表。 |
| 读取原生会话历史 | 根据最近消息确定世界书激活结果，不改写历史。 |
| 注入 System Prompt Section | 将编译后的角色上下文交给模型。 |
| 调整模型请求参数 | 应用配置的 Temperature；仅在非零时覆盖最大输出 Token。 |
| 读写插件设置 | 保存人格绑定、路径、预算、作用域和回复模式。 |

插件本身不需要 GitHub Token，不主动上传角色素材，也不执行支付或系统管理操作。实际可用权限仍由 DeepSeek Harness 的运行环境和用户配置决定。

[!WARNING]
仓库中的 cordis.patch.yml 带有开发机示例路径。首次安装前请将角色卡和世界书路径改为你自己的绝对路径，或在安装后通过设置页重新配置。不要提交包含隐私信息的角色卡、世界书或本机凭据。

快速配置

在 设置 → 角色扮演引擎 中添加绑定：

1. 填写需要绑定的 Agent Preset ID；
2. 选择 PNG 或 JSON 角色卡；
3. 按需选择一个或多个 JSON 世界书；
4. 选择作用范围：
- 全局：该人格的所有会话生效；
- 自定义：仅对勾选的活跃会话生效；
5. 设置上下文预算、扫描深度、Temperature 和回复模式；
6. 开启 启用注入，然后保存全部配置。

配置示例

- insert:
- id: roleplay-engine
name: '@alyx/dsh-roleplay-engine'
config:
bindings:
- presetId: my-agent
enabled: true
characterPath: 'D:\Roleplay\characters\MyCharacter.png'
worldbookPaths:
- 'D:\Roleplay\worldbooks\MyWorld.json'
scopeMode: global
sessionIds: []
contextBudget: 12288
outputReserve: 2048
scanDepth: 8
temperature: 1
maxOutputTokens: 0
responseRichness: full-scene-dialogue

配置字段

| 字段 | 类型 | 默认值 | 说明 |
| presetId | string | — | 要绑定的 Agent Preset ID，必须唯一。 |
| enabled | boolean | true | 是否为该绑定启用角色 Prompt 与请求参数覆盖。 |
| characterPath | string | — | PNG 或 JSON 角色卡的绝对路径。 |
| worldbookPaths | string[] | [] | 外部 JSON 世界书绝对路径列表。 |
| scopeMode | global \| custom | global | 对该人格全部会话生效，或仅对指定会话生效。 |
| sessionIds | string[] | [] | custom 模式下允许启用的活跃 Session ID。 |
| contextBudget | number | 12288 | 角色上下文编译可使用的总 Token 预算。 |
| outputReserve | number | 2048 | 为模型输出保留的 Token 数。 |
| scanDepth | number | 8 | 用于触发世界书的最近历史消息数量。 |
| temperature | number | 1 | 覆盖绑定会话的模型 Temperature，范围 0–2。 |
| maxOutputTokens | number | 0 | 最大输出 Token；0 表示保留模型或 Provider 默认值。 |
| responseRichness | string | full-scene-dialogue | 回复丰富度策略，见下表。 |

回复模式

| 值 | 行为 |
| full-scene-dialogue | 多个连续轮次，包含场景、动作、情绪变化和人物对白。 |
| scene-dialogue | 只演出一个完整轮次，可包含多个自然段。 |
| single-dialogue | 只输出一句不带引号的角色对白。 |

命令与 Agent Tool

Harness 命令

| 命令 | 用途 |
| /roleplay | 查看当前会话实际注入模型的角色扮演文本。 |
| /roleplay-inspect [输入] | 查看最后一次 Prompt IR；提供输入时执行一次确定性预览。 |
| /roleplay-richness [模式] | 读取或临时更改当前会话的回复丰富度。 |

示例：

/roleplay-richness scene-dialogue
/roleplay-inspect 月光照亮了古老遗迹 /roleplay

插件还注册了 roleplay_session_command Tool，允许 Agent 按精确 Session ID 执行以下只读或运行时操作：

- prompt：读取实际加载的角色文本；
- inspect：读取编译诊断；
- richness：读取或修改当前会话的回复模式。

项目结构

dsh-roleplay-engine/
├─ index.js # Host 插件入口、配置、命令、Tool 与生命周期 ├─ client.js # Harness Web 设置页 ├─ agent.js # Agent 注入与请求参数覆盖 ├─ lib/ │ ├─ card.js # PNG / JSON 角色卡解析 │ ├─ compiler.js # Prompt IR 与预算编译 │ ├─ lore.js # 世界书规范化、匹配与激活 │ ├─ response.js # 回复丰富度协议 │ └─ stable.js # 稳定序列化与哈希 ├─ locale/ # 插件展示元数据 ├─ test/ # Node.js 测试与示例素材 ├─ cordis.patch.yml # Harness Bundle 挂载配置 └─ package.json

开发与测试

要求：

- Node.js 支持 ESM 与内置 node:test；
- DeepSeek Harness 提供插件运行所需的 Host / Client 服务。

常用命令： powershell

JavaScript 语法检查

npm run check

运行全部测试

npm test

测试覆盖的关键行为包括：

- PNG / JSON 角色卡解析与损坏文件拒绝；
- Character Card V3 元数据；
- 世界书关键词、概率、常驻条目和扫描深度；
- 确定性编译、稳定哈希与预算原子性；
- Agent 创建、恢复、人格切换、热更新和销毁；
- 全局与自定义 Session 作用域；
- 回复丰富度与模型参数覆盖；
- Prompt Inspector 与实际运行时结果一致性。

安全与隐私

- 角色卡和世界书可能包含个人设定、私密文本或未公开作品，请谨慎提交；
- 配置使用本机绝对路径，公开日志或截图前请先脱敏；
- 目录扫描接口只列出所选目录当前层级中受支持的文件；
- 插件只编译并注入角色上下文，不会主动上传角色素材；
- maxOutputTokens: 0 会保留模型提供方的默认值，避免意外截断长回复。

兼容性

| 项目 | 状态 |
| DeepSeek Harness | 面向支持 Bundle、Host Plugin、Client Slot、Settings、Agent Preset 与 System Prompt Section 的当前桌面版架构。 |
| 已验证 Profile | desktop |
| 已验证平台 | Windows 11（本地绝对路径与目录选择器流程） |
| Node.js | 已在 Node.js v24.22.1 完成语法检查与测试；源码使用 ESM 与内置 node:test。 |
| 角色卡 | SillyTavern 兼容 PNG / JSON，包含 Character Card V3 测试覆盖。 |
| 世界书 | JSON；支持项目测试中记录的关键词、概率、常驻条目等基础规则。 |

由于仓库没有绑定一个可验证的 Harness 发行版本号，兼容性以当前 API 能力和实际测试结果为准。升级 Harness 前建议保留配置备份，并重新运行测试及安装验证。

当前限制

- 设置页面面向 DeepSeek Harness，不能作为独立 Web 应用运行；
- 角色素材使用本地绝对路径，不会自动同步到其他设备；
- 当前回复协议默认要求模型使用简体中文；
- 尚未发布 npm 包或稳定版本；
- 部分高级 SillyTavern 世界书特性只保留并报告警告，尚未参与求值。

版权与许可

Copyright © 2026 LeonYellow（GitHub：@LiranHuang）。保留所有权利。

本项目采用专有许可证，不是开源软件。公开可见仅用于源码审阅、协作评估和许可证明确允许的个人非商业试用。未经版权所有者事先书面许可，不得复制、修改、制作衍生作品、重新发布、再许可、出售、提供托管服务或用于商业及生产用途。

作者身份、规范仓库地址和第三方标识说明见 NOTICE。如需商业授权、再分发授权或其他超出许可证范围的许可，请通过仓库 Issues 联系版权所有者。

Git 提交记录、LICENSE、NOTICE 和源码版权头用于明确权利归属与许可边界，但不替代特定司法辖区的软件著作权登记或专业法律意见。

贡献

欢迎通过 Issues 提交问题与改进建议。由于本项目采用专有许可证，提交 Pull Request 前请先联系作者确认贡献与授权条款。未经作者书面接受，提交内容不会自动取得合并或使用许可。

提交代码前请确保：

1. 改动聚焦且不会破坏原生会话历史；
2. 新增行为有对应测试；
3. npm run check 与 npm test 均通过；
4. 不提交真实角色素材、个人路径、Token 或其他凭据；
5. 你有权提交该内容，并同意保留现有版权与专有许可声明。

让角色设定成为 Harness 的原生上下文，而不是旁路状态。