# 工作台使用指南

适用范围：0.3.6-rc.1，面向 DSH 0.2.1 全系列。正文分包、正则编辑、分享配置恢复与紧凑 Raw 已发布；后续源码改动以对应版本和验证记录为准。

预设模式的能力、适用场景和任务示例见[模式说明与如何使用](PRESET_MODE.md)。

## 安装与上手

### 已发布候选版

安装 next 候选通道：

```powershell
dsh plugin --profile web add dsh-preset-enhance@next
```

安装后重新启动 `dsh web`，侧边栏会出现“预设工作台”，新建对话的模式列表中会出现“预设模式”。

1. 打开工作台，导入 SillyTavern JSON 或 `.dsh-preset.json` 分享文件。导入的预设会保存到全局库，并成为当前默认。
2. 新建“预设模式”对话，自动启用当前默认预设。已有会话可用 `/preset on` 开启注入。
3. 检查提示词顺序与消息预览。如果最后一条消息是 assistant，请使用支持预填充的对话补全接口，并按需开启“预填充自动兼容”。
4. 在工具面板选择“模式默认”或“当前会话覆盖”，调整工具开关并保存。新策略从下一次请求生效。

### 分包安装与本地开发

主包仍使用 `dsh-preset-enhance` 名称，运行依赖携带正文包；升级无需换装 `dsh-preset-enhance-bundle`，也不迁移预设数据。在同一插件详情页可以分别启停主包与正文包。正文替换默认关闭，正文包停用时规则及开关偏好仍保留。

子包尚未发布时，直接安装根目录会尝试获取不存在的 registry 依赖。请先构建两个包，再在独立测试 profile 用本地 tarball 满足正文依赖，步骤见[开发验证](../DEVELOPMENT.md#未发布分包的本地安装)。不要在同一 profile 同时选择主包和旧组合入口；此前单独安装过正文包的开发环境应取消重复的独立入口。

### DSH 0.1.5

继续使用 DSH 0.1.5 时，固定安装原有 RC 版本：

```powershell
dsh plugin --profile web add dsh-preset-enhance@0.3.2-rc.2
```

当前组合版本的兼容声明为 `>=0.2.1-0 <0.2.2`，覆盖 0.2.1 的 alpha、rc 和正式版，不覆盖 0.2.2。旧宿主应使用对应的旧插件版本。历史适配及实际验证范围见[兼容记录](../compatibility/DSH_0.2.1_COMPATIBILITY.md)。

## 连接协议与能力范围

DSH 0.1.6 的官方连接默认使用 Messages，0.1.7 更移除了官方的对话补全协议。工作台顶部现在选择**会话被路由到哪个连接**：插件自带的 DeepSeek-预设增强走对话补全接口，预填充续写、工具调用转换与正文提取都在这条路径上生效；宿主的官方连接走 Messages，这些能力不适用。切换在宿主的 provider/model 配置层完成，立即生效、无需重启，也不会改写官方连接的配置字段。有当前会话时仅更新该会话的模型选择；无会话时更新宿主默认选择。

| 能力 | 对话补全接口（Chat Completions） | Messages 接口 |
| --- | --- | --- |
| 预设消息注入 | 支持顺序表和深度注入 | 有限兼容，宿主可能重排或覆盖历史中段、末尾的 system 消息 |
| Assistant 预填充 | 接口支持时可用，可开启自动兼容 | 不支持，预填充设置面板禁用 |
| DSML 转换与正文提取 | 匹配预填充请求时可用 | 不应用 |
| 工具开关、分组与会话覆盖 | 支持 | 支持 |

插件会合并预设开头连续的 system 消息，避免 Messages 序列化只保留最后一条。需要准确保留预设消息顺序、使用预填充或正文提取时，请选择对话补全接口。无法识别当前连接时，工作台不会代选其他连接来修改。

## 预设工作台

### 预设库与会话

预设库支持导入、编辑、预览、导出和删除。最后选择的预设全局保存，重启后继续作为默认预设使用。 在会话中切换、导入、保存预设或设为默认时，也会同步该会话使用的预设，从下一次请求生效；会话原有的注入开关和角色变量会保留。重新打开工作台时优先显示当前会话绑定的预设。

“新会话自动启用预设注入”可以选择任意可用的 DSH 模式，保存后只影响之后新建的会话。“预设模式”始终自动启用；已有会话通过以下本地命令控制，命令不会发给模型：

| 命令 | 行为 |
| --- | --- |
| `/preset` | 切换当前会话的注入状态 |
| `/preset on` / `/preset off` | 开启 / 关闭注入 |
| `/preset status` | 查看当前状态 |

“预设模式”从宿主的 `standard` 模式生成，继承标准工具集，并移除 DSH 身份提示与运行环境快照。其他模式叠加预设时，由置顶的“DSH 系统提示词”条目控制是否保留模式原有提示；旧预设默认保留。关闭后，请求和预览也会过滤历史中已有的 DSH 系统提示与运行环境快照，不改写原始会话记录。

删除被默认设置或会话引用的预设时，插件会切换到另一个已保存预设；删除最后一个预设会关闭相关会话的注入。

### 提示词编辑

提示词分区按是否加入顺序表区分，和启用状态无关：

| 区域或条目 | 含义 |
| --- | --- |
| 顺序表内 | 已加入当前顺序表；关闭复选框只停用该条目，不会将其移出 |
| 闲置条目 | 尚未加入顺序表，不参与注入 |
| DSH 系统提示词 · 模式名 | 可编辑的模式模板，支持动态宏、注入开关和恢复默认 |
| `chatHistory` | 从真实聊天记录读取内容的占位标记，正文不可编辑 |

支持 `chatHistory` 前后的 system、user、assistant/model 消息，以及按聊天深度注入。常用宏包括 `setvar`、`getvar`、全局变量、数值修改、随机选择与骰子。预设中的未知 `extensions` 原样保留；已支持的正则与插件配置按本文执行，不运行任意酒馆脚本。

### 模式系统模板与请求参数

DSH 系统正文按「当前预设 + DSH 模式」分别保存：编辑过的模式使用自己的修改，未编辑的模式读取宿主默认内容。「恢复默认」只还原当前模式。模型、适配器、工作目录及动态段落通过宏在发送和预览时重新读取，可在「动态宏与段落」查看或展开。

工作台跟随输入框当前模式，包括输入文字后已创建但尚未发送消息的空白会话；模板名称显示对应模式。首条消息发送时重新读取真实会话变量。

「请求参数」提供同步的 `max_tokens` 滑块与数字输入，范围 `0–1000000`，`0` 沿用原请求或适配器默认；参数仅在启用预设注入时生效。流式默认开启，关闭后 Chat / Messages 接口请求完整 JSON 响应，Chat 的工具调用与预填充兼容继续生效；Messages 仍不支持预填充。参数跟随预设保存、自动保存和导出。

字段、宏、源码分析与运行行为见 [DSH 系统模板与请求参数](../api/DSH_SYSTEM_TEMPLATE.md)。

### 消息预览与 Raw

消息预览与 Raw 读取同一个请求快照。发送后可查看实际请求及工具续轮；「解析当前草稿」用于发送前调试动态模板。草稿可能随会话状态变化，最终出站以「实际请求」为准。

聊天记录默认只展开最近两条，早期记录可完整展开。Raw 使用紧凑 JSON 树，默认展开消息与工具的浅层结构；支持长文本就地展开、展开一层、收起全部和分页。工具摘要来自当前快照，复制按钮始终复制完整原始请求字符串。切换视图或展开条目不会重新执行动态解析。

操作步骤、三种预览来源及协议边界见 [请求预览使用说明](REQUEST_PREVIEW.md)。

工作台固定配置区域（如正则、试运行、接口设置）的展开/折叠偏好保存在当前浏览器，离开返回和刷新后恢复。页面及独立列表的滚动位置在同一浏览器标签页内按会话与预设保留，切出再返回时恢复；滚动偏好不会写入分享文件或触发预设自动保存。预设页隐藏会话正文宽度手柄，切回对话恢复正常调整。

同一会话切换宿主页面或标签后返回，工作台及 SPreset 编辑器保持原页面实例、滚动位置和临时界面状态。完整导航和浏览器刷新时，工作台在当前标签页内通过滚动快照恢复位置。最多保留四个闲置页面，超出后重新加载较早离开的页面。

### 正则配置

工作台的可折叠「正则配置」面板同时管理提示词和正文规则，两套通道共用预设中的规则列表，默认总开关均关闭。

- 「启用提示词正则」控制发送给模型的请求副本；「同时处理预填充」只作用于这个通道。
- 「启用正文正则」控制助手正文的显示副本，需要正文显示包启用并就绪，停用时开关自动禁用且保留保存的偏好；不要求启用预设注入，不写回历史。
- 每条规则可分别选中「发送提示词」「正文显示」，可同时开启。作用对象、表达式、替换、深度及启停共用。正文通道只执行模型输出位置；其他酒馆位置原样保留。
- 工具栏的「通道」切换适用性和试运行；正文试运行固定为助手。总开关关闭时仍可测试规则自身效果，结果注明开关状态。
- 保存预设或使用全局自动保存后，两套开关和规则一并保存，SPreset 编辑器读取同一份配置。试运行使用受超时保护的 Worker，不提交宏变量变更。

### SPreset 编辑器

工作台顶部工具栏的「SPreset 编辑器」按钮会在原工作台范围内打开编辑器（`/preset-enhance/editor`），保留宿主导航，可返回工作台并保留会话关联。三栏布局：**资源库 / 提示词链 / INSPECTOR**。

- **资源库**：分「未使用」与「模板」两组计数，可按标题、正文或 ID 搜索并按角色筛选。模板是**一条普通提示词条目**（名称、角色、正文），保存在插件状态文件里、与任何预设无关；可以加入当前预设的提示词链，也可以把链上条目存成模板。
- **提示词链**：条目上可直接切换系统、用户、助手角色；电源按钮控制当前顺序组的启停，停用条目仍属于已使用。点击条目在右侧编辑名称、正文和注入配置；占位符（marker）与酒馆内置条目会显示徽章。拖动时条目保持不透明，其他条目实时让位；列表边缘自动滚动，Esc 取消本次拖动。改动随「保存预设」写入该预设。
- **条目更多菜单**：提供上移、下移、移到未使用、复制为模板、创建副本和删除。移到未使用只移除当前顺序组的引用；删除经确认后移除提示词本体及所有顺序组中的引用。复制为模板写入独立资源库；创建副本将独立条目插入原条目之后，继承配置及当前启停状态。角色修改作用于提示词本体，引用它的其他顺序组也使用新角色。
- **特殊条目**：marker 的角色只读，可停用或移到未使用，不能复制或删除；外部关联条目的角色只读，先通过插件模板面板解除关联再复制。正文锁定时需先解锁才能复制或删除，角色与启停仍可调整。菜单支持方向键、Tab、Esc，布局跟随系统明暗主题。
- **INSPECTOR**：选中条目的完整字段；正则绑定（`extensions.SPreset.RegexBinding`）的适用性由插件既有正则引擎判定并显示原因。酒馆/SPreset 侧设置可以查看、编辑并原样保存，但本插件不执行它们，界面上会逐项标注。
- 界面布局与控件命名参考 soliumbra 的 SPreset 编辑器；本仓库的实现、数据读写与正则判定均为本项目自有代码，未复制对方源码。

### 保存

全局自动保存默认开启，预设正文、接口设置、自动启用模式、会话设置、工具开关和分组配置都会自动保存。用户关闭后会记住关闭状态，此时使用各区域的保存按钮。

工具面板还提供独立的“自动保存工具开关”：仅自动保存逐工具及批量开关，分组名称、排序和成员编辑仍需手动保存，除非已开启全局自动保存。未确认的工具自动保存草稿会暂存在浏览器中，刷新或重新打开相同范围后可继续保存。

## 预填充与工具调用兼容

当最终注入消息是 assistant 时，包括顶层 `assistant_prefill` 或顺序表中的末尾 assistant/model 条目，工作台会显示预填充提醒，预览中标记为 `Assistant Prefix`。

在对话补全接口下开启“预填充自动兼容”，插件会为匹配到的末条 assistant 消息添加 `prefix: true`，处理 `<think>` / `<thinking>` 前缀及兼容接口的思考字段，并保留工具调用历史中的真实 `reasoning_content`。接口要求见 [DeepSeek 对话前缀续写文档](https://api-docs.deepseek.com/zh-cn/guides/chat_prefix_completion)。

预设编辑区的“Assistant 预填充”内提供“预填充到思考”开关，默认开启，随当前预设保存和分享。开启时末条前缀写入 `reasoning_content`；关闭时原样写入 `content`。该选择也适用于顺序表末尾的 assistant 条目及工具调用后的自定义前缀，不改变历史消息的通道。思考模式已关闭时按正文发送；Messages 协议仍不启用预填充桥接。

思考目标支持普通文本，以及开头的 `<think>` / `<thinking>` 包装，兼容未闭合标记、大小写和标签内空白；包装会移除。选择正文时保留原始文本和标记。原有预设没有 `dsh_prefill_target` 字段时默认使用思考目标。

### 地址与工具字段

| 请求目标与设置 | 处理方式 |
| --- | --- |
| DeepSeek 官方地址 | 匹配的预填充请求自动切换到 `https://api.deepseek.com/beta` |
| 非官方适配器地址 | 使用适配器实际请求地址，不改写地址，无需在工作台重复填写 |
| 开启“处理工具调用” | 官方与非官方地址均转换工具定义、调用历史和响应，并移除原生工具字段 |
| 关闭处理，使用官方 Beta | 移除 `tools`、`tool_choice` 和 `parallel_tool_calls` |
| 关闭处理，使用非官方地址 | 由“非官方接口移除原生工具字段”开关决定移除或原样发送 |

工具调用处理会将可用工具定义加入 system 提示，将历史调用与结果转换为 DSML。模型返回的 DSML 再恢复为标准 `tool_calls`，交给 DSH 执行，支持流式和非流式响应；工具结果中的常见 base64 图片也会转换为兼容的图片内容块。

### 正文提取与后续预填充

“正文/工具调用提取”是默认关闭的实验功能，使用结束思考标记、10 token 窗口和输出区标签兜底区分思考与正文，移除输出区控制标记，并恢复 DSML 工具调用。策略说明见 [预设稳定性实验](../../scripts/PRESET_STABILITY.md)。

开启时，格式提示词自动加入当前预设的 `chatHistory` 后方、assistant 预填充前，可在提示词列表中编辑。重复开启保留已有编辑；保存接口设置时会一并保存当前预设。

“工具调用后继续请求的预填充”默认继承原预设，也可填写独立提示词，支持变量宏和 `<think>` / `<thinking>` 前缀。开启自动兼容后，它只替换同一轮工具执行后继续请求的末条预填充；新一轮用户消息仍使用原预设。留空或展开为空时继续继承。

上述接口设置全局保存，从下一次请求生效。预填充转换只作用于匹配当前会话末条 assistant 前缀的请求。

## 工具预设与分组

### 生效范围

| 范围 | 生效规则 |
| --- | --- |
| 模式默认 | 为每个 DSH 模式选择自定义开关或工具预设，没有会话覆盖时采用此策略 |
| 当前会话覆盖 | 完整替换模式默认策略，可在同一会话内随时变更 |
| 恢复继承 | 移除会话覆盖，重新使用模式默认 |

工具目录从宿主模式注册表、模式作用域和当前会话实时获取，兼容其他插件引入的模式与工具。保存后从下一次请求生效；暂时缺失的工具引用会保留，待对应插件恢复后重新匹配。

工具预设支持新建、复制、重命名和删除，可以被多个模式或会话引用。修改预设会影响所有引用者的后续请求。删除仍被引用的预设时，模式回到自定义、会话回到继承，并保留原有逐工具策略数据。直接保存工具开关会将当前范围切换为自定义策略。

### 用户分组与 MCP

- 按 MCP 服务自动生成“服务名 · MCP”分组，也可将 MCP 工具加入用户分组。点击“刷新工具列表”重新读取动态工具目录。
- 用户分组支持名称、排序和成员编辑；同一工具最多属于一个用户分组。固定标签提供“全部”和“未分组”。
- 分组支持三态开关，以及全开、全关、仅启用此组和恢复预设值。顶部全选 / 全不选作用于当前模式全部工具，不受标签筛选影响。
- 标签栏保持单行横向滚动，也可折叠为下拉框；窄屏自动使用下拉框。MCP 服务名过长时从中间省略，保留首尾，完整名称可在悬浮提示或下拉框中查看。

关闭工具后，插件过滤请求中的工具定义，并通过执行守卫拒绝调用。在 DSH 0.1.6 中，可限制的继承工具还会通过宿主作用域限制从 PTC（程序式工具调用）的 SDK 提示中移除。宿主保留的 `run_code` 入口不会被关闭；宿主不允许限制的会话本地工具仍由执行守卫约束。

## 单文件分享与数据保存

工作台可导入、导出 `.dsh-preset.json`，也可导出普通 ST JSON。

| 内容 | 分享文件中的行为 |
| --- | --- |
| ST 预设 | 包含完整提示词与顺序表 |
| 预填充接口配置 | 有效 `prefill` 在导入时恢复到全局，对其他会话也生效；缺失或 null 保持本机设置 |
| 工具预设与分组 | 默认导出当前关联的工具预设及分组，导入后需手动应用工具配置 |
| 会话 ID、模式和会话选择、目录缓存、引用计数 | 不导出 |
| 浏览器折叠状态、最后工具模式、自动保存开关及待保存草稿 | 不导出 |

导入、再次应用包内配置和保存接口设置时，正文提取开启且模板缺失会补入格式条目；已有内容保留，关闭不会删除条目。Messages 下仍保存配置，切回 Chat 后使用。

未知工具格式子版本仍可导入、编辑和再次导出，但不能应用工具配置。字段定义见 [单文件格式说明](../../PRESET_FORMAT.md)。

预设库、默认选择、会话绑定、接口设置和工具策略默认保存在 `DSH_HOME/preset-enhance/state.json`；未设置 `DSH_HOME` 时使用用户目录下的 `.dsh`。浏览器只保存界面偏好、自动保存开关和待确认的工具草稿。

插件 Chat 请求会为缺少思维链的助手消息（包括预设自定义回复和工具调用历史）补充空的 `reasoning_content`，避免思考模式因字段缺失拒绝请求；已有思维链原样保留。官方 Messages 转 Chat 的兼容路径采用相同规则，原生 Messages 请求不添加此字段。

## Chat 适配器模型

工作台切换连接时会同步当前会话的模型选择器，优先保留同名模型；目标目录没有该模型时选择其默认或首个模型。已在执行的请求继续使用原连接，下一次请求使用新选择。

插件 Chat 适配器默认同步官方适配器的模型列表。DSH 设置的预设增强插件页面可直接修改或新增 Chat 模型，配置模型 ID、名称、上下文长度、最大输出及输入类型。未手动配置时跟随官方列表；重置该字段或清空列表恢复同步。模型配置由宿主管理，不随预设分享。


## SPreset 正则编辑

在 SPreset Editor 顶部切换“附加功能”，进入正则列表。左侧筛选全部、提示词或正文规则，支持新建、复制、删除、启停与排序；右侧编辑表达式、替换内容、执行位置、通道、宏展开和深度。窄屏通过规则详情及“返回规则”切换。

顶部“提示词正则”和“正文正则”分别启用两个通道。“包含预填充”仅作用于提示词通道。编辑后使用“保存预设”，也可开启顶部自动保存；规则随预设导入导出，未知兼容字段继续保留。

“试运行”折叠区支持单条或全部规则、输入/输出角色及深度；只有点击运行才执行，并使用可终止 Worker。正文显示需要启用主包携带的可选显示包；安装、字段与限制见[正文正则](../api/DISPLAY_REGEX.md)。