longlongdragons / roleplay-plugin

沉浸式角色扮演插件（DeepSeek Harness 动态 Cordis 插件）

Immersive roleplay plugin for DeepSeek Harness, built as a dynamic Cordis plugin with a Host/Client split.

• Plugin ID：rplay-1（包名 roleplay-immersive-v2）
• 类型：DeepSeek Harness 动态 Cordis 插件（Host 端 + Client 端）
• 已自测：7 个 RPC 处理器注册、persona_guard_check 工具注册（schema 编译正确）、端到端执行通过
• 构建产物：host.js、client.js（均已通过 node --check）

功能总览

需求	实现
图形化控制面板	shell.overlay 右侧抽屉 + 右下角 🎭 悬浮按钮：预设分类卡片 / 自定义表单 / 角色库 / 设置 / 指令说明
官方预设角色	15 个：武侠4（侠客/魔教少主/掌门/说书人）、古人4（诗人/谋士/帝王/书生）、动漫3（热血少年/傲娇少女/高冷御姐）、科幻2（机甲指挥官/星际舰长）、现代2（温柔店长/治愈系博主）
主题联动	theme.overrideTokens('roleplay', …) 覆盖 13 个设计令牌（明暗双套）+ 氛围装饰层 + 主题字体：wuxia / ink / anime / scifi / modern / default
人设守卫	工具 persona_guard_check：评审官 LLM 强制纯 JSON → 检测 → 失败自动重写 1 次 → 兜底输出「角色思绪混乱，请重新提问或调整角色设定」，零死循环；严格/宽松双模式
人设注入	systemPrompt.section('roleplay:persona', order:10)，每次模型步骤动态读取当前状态，多轮不重置
斜杠指令	/reset、/role <描述>、/check、`/guard strict
双向同步	面板操作与指令共用 Host 单一状态源；客户端 1.2s 轮询 get_state（带 rev 增量）+ 操作即时回推
会话持久化	状态写 <workspace>/.dsh-roleplay.json（含 rev/current_role/current_theme/theme_enabled/guard_enabled/strict_mode/retry_count/custom_roles）
安全与扩展	自定义角色违规词过滤 + 字数上限；主题自动匹配（关键词加权评分，theme_desc 权重×2）；预设/主题为纯数据表可增删

文件结构

roleplay-plugin/
├── host.js        # Host 端插件：RPC / 斜杠指令 / 状态持久化 / 人设守卫评审
├── client.js      # Client 端插件：控制面板 UI / 主题渲染 / 轮询同步
├── manifest.json  # 插件元信息（id / 名称 / 服务依赖 / 入口）
├── README.md
└── LICENSE        # MIT

host.js 与 client.js 导出的是返回 Cordis 插件对象的工厂函数：

module.exports = function roleplayHost () {
  return {
    apply(ctx) { /* ... */ },
  }
}

DeepSeek Harness 的动态 Cordis 运行器会以 function () { …body… } 的形式装载插件体，因此这两个文件既是可直接阅读的源码，也是可直接交给插件管理器执行的产物。

架构（对应四节点工作流）

1. 角色&主题解析节点（Host）：面板 RPC（select_preset/select_role/create_role/delete_role/set_config/exec_command）与斜杠指令统一写入会话变量并持久化。
2. 界面主题渲染节点（Client）：applyTheme() 按状态叠加/移除令牌层；RoleplayRoot 渲染氛围层（pointer-events:none）。
3. 角色话术生成节点：personaText() 输出人设卡 + 扮演铁律 + 守卫协议，注入每次模型步骤。
4. 人设评审纠错节点（Host）：judge() 用 llm.stream 调用当前模型（评审官 system 提示 + temperature 0），extractJson 提取强制 JSON；verify →（fail）rewrite →（失败）固定兜底文本。

使用

1. 在 DeepSeek Harness 中把 host.js / client.js 分别作为动态 Cordis 插件的 Host 端与 Client 端装载（参考 harness 的插件管理器）。
2. 审批通过后，页面右下角出现 🎭 按钮 → 打开面板。
3. 预设页点任意角色卡：立即切换人设 + 整套界面主题（背景/配色/装饰/字体氛围）。
4. 自定义页填写人设表单保存（界面氛围留空则自动匹配最优主题），角色库可切换/删除。
5. 设置页可关闭主题联动或人设守卫、切换严格/宽松。
6. 聊天内等价指令：/role 一位豪迈的边关将军 → /check → 发一句带现代网络语的提问，观察守卫自动重写。

已知边界

• 守卫依赖当前会话可用的 LLM 路由（agentDefaultModel 或首个 provider）；路由不可用时返回兜底文本而非卡死。
• 主题令牌只改颜色令牌；聊天气泡颜色随 surface/label 令牌联动，产品 DOM 不直接改写。
• retry_count 为会话内计数（守卫活动不触发持久化写入，避免每轮落盘）。

License

MIT