跳到主要内容

提示词系统规范

本插件交给模型的每项指令都是文件，因此无需修改代码便可阅读、修改或替换。文件使用 Markdown，全部内容就是提示词。

文件位置​

<roleplay root>/prompts/<language>/<group>/<name>.md

软件包在 prompts/<language>/ 中附带英文和中文原件。启动时及第一次需要某条提示词时，软件包会把角色扮演根目录中尚不存在的文件复制过去。用户编辑过的文件按原样使用，永不覆盖。删除文件即可恢复原版，下次使用时会再次复制。空文件会被拒绝并报告路径；要恢复原版，应删除该文件。

分组内容
roleplay/游戏主持人指令（game-master、persona）、角色规则（character-rules、character-lookup、character-decide）、记录员、编年史作者及其三个任务、建议作者、图片作者、剧情作者、预分类卡片片段所用的决策问题（decide-instruction、decide-irrelevant），以及加入场景的短提示（rules、plot-hint、ooc-command、ooc-empty、input-refused）
world/世界创作助手（persona、procedure、welcome），以及创作和整合角色、地点、物品的世界作者（author、consolidate）
import/角色卡导入：分类器、名册、每类输出文档的提示词（character、place、faction、thing、lore）及共用的 common-rules、世界描述与标签，以及引导创作对话完成三个步骤或在截断后恢复的文本（cut-off）
preset/预设创作助手（persona、procedure、welcome）
lorebook/世界书创作助手（persona、procedure、welcome）
doctor/会话医生（persona、procedure、welcome）
translate/世界翻译（glossary、document、notice）

**创作助手和导入是全局的，所以它们的提示词只放在根目录。**世界、预设、世界书和会话医生助手，角色卡、预设和世界书的导入，以及翻译，每次使用都会读取 <root>/prompts/<language>/：改动那里的文件，下一次对话、导入或翻译就会使用，无需重启；删除文件即可恢复原件。文件只能使用其原件所提供的 ${name} 变量，使用其他变量会使运行失败并指出变量名。系统不附带用来编写这些提示词的助手，请手工编辑，或用普通对话编辑。留在代码里的是工具的名称、说明和参数结构，以及由数据生成的简报，因为程序依赖它们。

世界、预设和世界书创作对话使用插件的导入/创作模型、推理等级和请求上限。回复达到上限时，import/cut-off 会在同一回合中引导它完成待办动作或给出简短总结，而不是悄悄结束一段未完成的回答。

会话和世界的提示词​

<session folder>/prompts/<language>/<group>/<name>.md
<world folder>/prompts/<language>/<group>/<name>.md

会话可按同样的目录结构携带任意提示词，并以自己的文件覆盖根目录文件。会话未携带的提示词，以及其他语言的提示词，仍来自根目录。系统不会自动把提示词复制进会话，所以编辑根目录仍会影响没有覆盖该文件的会话。分支会保留来源会话的提示词。

世界也可携带同样结构的提示词。开始会话时，这些文件会复制到会话目录。遇到以下情况时，开始操作会返回 422 并列出每个问题文件：文件不是软件包已有的提示词，文件夹不是语言，文件为空，或使用了原版未提供的 ${name} 变量。

roleplay/persona、roleplay/style 和 roleplay/character-style 决定模型身份和故事写法。游戏主持人的 persona 包含 ${style}，每个角色的 persona 也携带自己的风格。其余提示词保存游戏规则或工具契约。

世界创作对话可通过 list_world_prompts、read_world_prompt、write_world_prompt 和 delete_world_prompt 编辑世界提示词。删除操作把文件移到 .trash/prompts/。写入和删除默认与其他世界文件修改一样需要用户批准；明确启用自动模式后会跳过询问。写入内容始终要通过会话开始时使用的验证。角色卡导入完成后的同一回合无需逐项批准，但只允许写入叙事类提示词，规则类提示词会被直接拒绝。

游戏主持人提示词可在独立一行包含 ${preview}。开启 preview.enabled 时，该变量替换为 roleplay/preview 的内容；关闭时替换为空，并删除只包含空变量的整行。关闭预览的对话也不会获得 preview_scene 工具。同样，${dice} 在主持人开启了骰子工具时是 roleplay/dice 的内容（何时掷骰、如何读取结果、结果不可更改，以及从故事中列出的世界的检定），没有骰子工具时为空。

预设​

预设是一组可复用的写作指令，保存在资料库 <角色扮演根目录>/presets/<名称>/ 中：

preset.json                                  { "title": "...", "description": "...", "sampling": { "master": 0.8, "characters": 0.9, "topP": 0.95 } }
prompts/<语言>/roleplay/style.md             与世界提示词相同的结构

预设带有故事的提示词（roleplay/…），检查方式与世界的提示词相同（必须是程序自带的提示词、不能为空、只能使用其自身的 ${name} 变量）。叙述类提示词是 roleplay/persona、roleplay/style 和 roleplay/character-style；其他 roleplay/ 提示词是规则类提示词，列在摘要的 rules 中。带有规则类提示词的预设会显示警告（卡片、编辑器、批准），因为这些提示词涉及程序读取的工具和字段。由世界书的指令生成的预设（createPresetFromGuidance）保留每个内置提示词，并把指引追加在后面。sampling 可以建议游戏主持人和角色的创作温度（0 到 2）；辅助智能体的低温度不由预设改变。预设只提供其拥有文件夹的语言的提示词：其他语言使用根目录的提示词，而不是英文。有问题的预设会连同问题一起列出，且不能使用。

预设在故事开始时被复制进故事，因此之后对资料库的修改不会影响进行中的故事，分支沿用所属故事的预设。文件按下面的顺序写入，后者覆盖前者：

  1. 根目录的提示词（不复制任何文件；这是默认）；
  2. 世界建议的预设（world.json 的 preset）；
  3. 世界自带的 prompts/；
  4. 开始对话框中选择的预设（请求的 preset；none 表示即使世界有建议也不使用预设）。

因此开始时的选择优先于世界自带的提示词，而世界的建议排在它们之下。选择了不可用的预设会拒绝开始。建议的预设不可用时（世界来自资料库不同的人），会在故事的第一张卡片上告知玩家，并以默认风格讲述。预设的温度只填补开始请求没有给出的设置。

故事会记录它来自哪个预设以及每个复制文件的内容（故事数据库旁的 preset.json）。聊天设置显示故事是否仍与资料库一致：一致、资料库中已更改、故事中已被编辑，或资料库中已不存在。可以切换到其他预设、重新应用资料库的版本，或移除预设。被替换的副本保存在故事的 .trash/prompts/ 中。只会改动来自预设的文件，世界自带但被预设替换的提示词不会恢复。切换不会改变故事的温度。

创建预设的方式：在预设页创建（以内置叙述类提示词的副本为起点来编辑）、导入 SillyTavern 预设，或使用世界编辑器“提示词”页的存为预设；也可以手工写文件夹，或保存世界的叙述类提示词（POST /roleplay-api/presets，带 name 和 fromWorld；不带 fromWorld 则以内置提示词为起点）。GET /roleplay-api/presets 列出预设；GET/PUT/DELETE /roleplay-api/presets/item?name= 读取、描述（title、description、sampling）和删除一个预设（删除会把它移到 <根目录>/.trash/presets/）；PUT/DELETE /roleplay-api/presets/prompt?name=&language=&id= 写入或移除一个提示词；GET /roleplay-api/sessions/preset?id= 是故事的状态，POST /roleplay-api/sessions/preset?id= 带 name 表示切换（不带则取消预设）。

创作聊天。POST /roleplay-api/presets/authoring?name= 会创建或重新打开专属聊天 preset-author-<编码后的名称>，位于 <根目录>/presets 的“Preset Authoring”项目下，使用 preset-authoring 智能体预设（@dsh-agentic-roleplay/core/preset-authoring，由捆绑包声明）。它的工具只能触及聊天所对应的那个预设：read_preset_info、list_preset_prompts、read_preset_prompt（预设未带有的提示词读到的是内置文本）、write_preset_prompt、delete_preset_prompt、write_preset_info 和 import_narration_preset。每次写入都先征求用户同意；导入只在预设已带有提示词时才询问。提示词的写入采用世界提示词的检查；写入或删除规则类提示词时，会带着明确的警告征求同意。

导入 SillyTavern 预设。POST /roleplay-api/presets/import?name=&language=（请求体为文件）会预留一个空的资料库条目，把文件保存在其 .import/preset.json，打开创作聊天并让它调用 import_narration_preset；该工具运行与角色卡导入相同的 import/style 任务，并把叙述类提示词写入预设的每个内置语言文件夹。在此之前，该条目会以“预设没有提示词”的问题列出。类型为 sillytavern/preset 的目录条目走同一条路径（POST /roleplay-api/catalogue/convert/preset），以条目标题命名；导入永远不会替换已有的预设。

变量​

提示词可以包含 ${name}。调用代码负责提供变量值，例如角色的 ${name}、限制值 ${max} 或共用规则块 ${rules}。缺少变量值时会报错，并指出提示词和变量，所以原版已有的变量必须保留。不要使用 {{...}}，DSH 自己的提示词装配会把它解释为 DSH 变量。

代码理解的工具名、字段和值在所有语言中都必须保持原样，例如 activate_characters、resolve_round、succeeded、character 和 [PLAYER]。只翻译它们周围的文字。

语言​

语言由文件夹 en 或 zh 表示，并在工作开始的位置确定：

  • 角色扮演会话使用对话设置中的指令语言（prompts.language）。开始会话时取界面语言，之后可修改。
  • 世界创作助手和角色卡导入使用用户打开助手或开始导入时的界面语言，并按世界保存在 worlds/.authoring/。
  • 软件包没有对应目录的语言回退到英文。

每个提示都可以使用 ${language}，它会被替换为该文件夹语言的名称（English、中文）。告诉模型写什么的提示（旁白、对白、摘要、信念、建议）都会点明它，所以即使世界文件使用另一种语言，故事也用对话的语言书写；世界中的名字和术语仍按文件中的写法。其他语言的世界可以翻译（见编辑器指南）。角色的话语、思考和叙述若使用了另一种文字也会被退回；在中文故事里，如果夹杂了普通的小写英文单词（人名和缩写首字母大写，不受影响）同样会被退回，并告知具体是哪些词，让模型重写。

插件启动时会检查被编辑过的文件。 根目录 <root>/prompts 里每个有对应出厂提示的文件，都不能为空，只能使用该提示被提供的 ${...} 变量，也不能含有 {{...}}（DSH 会把它当作自己的变量）。只要有一个不合格，启动时就会记录一条错误，逐个列出文件和原因；修改该文件，或删除它以恢复出厂文本。插件仍会加载，因为无法把某个出厂提示的旧副本和手工编辑区分开，但使用这样的文件时会以同样的原因失败。出厂提示里没有的文件不会被读取，会被忽略。

当角色卡和场景用的是另一种语言时，单靠提示并不能让模型一直用该语言书写。因此角色的回答、叙述、反思环节写下的信念，以及记录员写下的事件和感知，还会按所用文字检查：写成了另一种语言的会被拒绝并指明应使用的语言，模型会重写。过短而无法判断的文本，以及英文、中文以外的聊天语言，不检查。

增加语言时，需要新建包含相同文件的目录。测试会确保所有随附语言拥有相同的文件集合和变量。

不使用文件的文本​

每次请求都要根据故事数据动态构造的文字仍留在代码中，由消息目录提供：代码里写的英文文本就是它自己的键（tr('{name} is in {place}.', { name, place })），中文放在 dsh-roleplay-model 的 messages.ts 与 messages-zh.ts 中。目录涵盖主持人的场景提示（时间、日程、地点、谁在哪里、尚未了结的事、早先事件）和角色看到的内容（自身描述、场景、地点、物品、日程、关系、所属组织、带有把握程度的记忆、本幕此前的行动）、反思环节的简报与拒绝理由，以及故事中的日期、时间和时长（1912年9月21日 星期六 19:30、3小时12分钟；有历法时还包括当天的季节和节日）。某种语言缺少的文本以英文呈现，测试（tests/support/messages.spec.ts）确保每个 tr('...') 调用点都有译文且占位符一致，并且字典里没有无人使用的条目。场景提示还涵盖世界自行发生的事、谁去了哪里，以及交给不在玩家身边的角色的情形（到期的约定、已过期限的目标）。以下内容无论使用什么语言都有意保持英文：主持人的工具结果，记录员、组织策略师、判定者和作者的工作简报，状态工具的视图，以及工具及其参数的描述。它们是协议而不是故事：其中的工具、字段和 id 必须保持原样，而其中属于故事本身的文字（事件、名字、摘要）原样传递，并以对话的语言书写。