---

简介

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 服务。

常用命令：

# 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. 你有权提交该内容，并同意保留现有版权与专有许可声明。

---