bychv/dsh-stcardwriter

DSH SillyTavern 角色卡编写器

MIT License
Node.js

在 DeepSeek Harness 中创作、整理、预览和迁移 SillyTavern 角色卡、世界书与预设。当前插件版本：0.5.2-rc.1；npm 包名：dsh-stcardwriter，目前尚未发布到 npm。

已支持 DeepSeek Harness 0.1.2-rc.1，提供“酒馆创作模式”Agent 预设和三栏工作台：左侧连接 Harness 并管理项目，中间编辑资源，右侧整栏编辑世界书注入内容并可切换实时预览。内置本地 SillyTavern 连接器；提示词与伪装消息注入由直接依赖的 DSH Preset Plus 统一提供。

当前本机运行验证基线为 DSH 0.1.2-rc.1：格式检查/修复工具已通过该版本真实 ToolRuntime 的调用与 lossless JSON 校验；静态兼容检查同样针对官方 dsh-v0.1.2-rc.1 源码完成，并覆盖 Preset Plus 0.1.5 的相关接口。本次验证未安装或升级 DSH。插件不再直接声明 0.1.2 已删除的 @deepseek-ai/dsh-client-runtime，UI 使用新版仍保留的三个插槽；托管 Agent 组合 v4 同时覆盖 0.1.1 与 0.1.2 的标准工具行。可用 npm run check:dsh-compat --  复查。

快速安装

dsh plugin --profile web add github:bychv/dsh-stcardwriter
dsh --profile web --dump-config
dsh --profile web

安装或升级后重启 DSH Host。首次启动会创建 tavern-authoring 和 preset-plus 两个 Agent 模式。

开始使用

1. 在 DSH 设置的「预设增强」中创建、导入或激活 Preset Plus 预设。
2. 新建会话并选择「酒馆创作模式」。当前激活的 Preset Plus 预设会与完整 tavern_ 工具同时生效。
3. 从侧栏或会话输入栏打开「酒馆创作」，可以新建空项目，也可以批量导入 .json、.png、.charx、.zip。
4. 如需连接本机 SillyTavern，在左侧连接器填写安装根目录或 data/ 目录。
5. 在酒馆工作台顶部的「工具模式」下拉框切换当前对话的「标准模式／极简模式」。无需新建对话，也无需让 Agent 调用工具。

当前对话的标准／极简模式

默认使用标准模式，保留完整 DSH 通用工具与酒馆工具。极简模式只向当前对话保留 tavern_ 酒馆资源工具、ask_user_question 与 exit_plan_mode（若可用），隐藏 Shell、通用文件操作、Web、子 Agent 等工具，减少工具定义占用的上下文。已有的安全策略和其他插件限制仍然生效，切回标准不会解除它们。

这不是更换 DSH Agent 预设：同一个 tavern-authoring 对话、聊天记录、项目资源和 Preset Plus 注入保持不变，也不会清空系统提示词或上下文。模式仅由人类在酒馆界面选择，插件不注册 Agent 模式切换工具。运行中的回复不能中途切换；等待当前回复结束后操作，从下一次请求生效，已有后台任务不会被取消。

选择按会话 ID 保存到 $DSH_HOME/st-card-writer/session-modes/，重新打开对话或重启宿主后恢复；文件名为会话 ID 的 SHA-256，不直接使用 ID 作为路径。新对话默认标准模式，不会跟随其他对话变化。没有加载对话，或当前对话不是酒馆创作预设时，控件会提示原因。空项目也可以切换。

人类界面接口：GET /api/dsh-stcardwriter/sessions//mode 查询，PUT 同一路径并传入 { "mode": "standard" } 或 { "mode": "minimal" } 切换。这是工具目录精简功能，不是权限隔离或沙箱边界。

功能

- 创建完全空的项目；在项目里新建任意数量的角色卡、世界书和预设。
- 一次选择多个 .json、.png、.charx 文件，或导入包含这些文件的 .zip。
- Character Card V1/V2/V3 识别；以 V3 为主进行编辑，PNG 优先读取 ccv3、回退 chara。
- 导入角色卡时检查 character_book；内嵌世界书可逐条写作并测试触发，始终随角色卡保存。
- 保留 CHARX 中 card.json 以外的任意文件，以及 PNG chara-ext-asset_: 二进制资源；导出会原样带回未知附属文件。
- 在角色卡之间选择性迁移非世界书 data.assets 和未引用附属文件；同路径不同内容会自动安全改名，绝不覆盖目标内嵌世界书。
- Agent 可通过 tavern_character_resource_read 按 ID、路径或 data.assets 下标读取 UTF-8/UTF-16 文本附件；支持分块读取，不会把附件 Base64 或二进制内容塞进上下文。
- Agent 项目读取采用低 token 分层：tavern_project_get 默认只返回资源和字段大小摘要，tavern_asset_get 再按字段读取，只有显式 detail=full / fields=[""] 才返回完整 JSON。
- Agent 可用 tavern_character_patch 修改指定角色字段而不重传整卡；随卡世界书和独立世界书均支持分页、单条读取、增改、删除。
- tavern_worldbook_entries_copy 可在两张角色卡的内嵌世界书之间，或角色卡与独立世界书之间复制选定条目；ID 冲突可安全重编号、覆盖或跳过。
- tavern_preset_convert_to_preset_plus 只负责把 Chat Completion、System Prompt 或 Context 酒馆预设转换成项目内的 preset-plus-preset 草稿；可在中栏修改条目，并在右栏预览实际注入顺序。确认后再用 tavern_preset_plus_write 独立写入 Preset Plus，支持冲突改名/覆盖和写入后激活。动态 marker 会跳过并报告，不会伪造成静态提示词。
- 酒馆创作预设包含 DSH 0.1.2-rc.1 标准模式的文件、搜索、Shell、后台任务、技能、目标、计划、压缩、子 Agent、工作流、提问、Todo 与 Web 工具，并在其上追加 tavern_ 工具。
- 导出角色卡 PNG、V3 JSON、V2 JSON、V1 JSON 或 CHARX；保留导入 PNG 的原图并重写元数据。
- 酒馆连接器：填入本机酒馆安装根目录或用户数据目录，即可在工作台里浏览并勾选导入酒馆侧角色卡、世界书和五类预设；单张资源或整个项目可一键写回酒馆对应目录。
- Agent 可用 tavern_connect_ / tavern_remote_ 工具完成同样的连接、列举、导入与导出。
- 直接集成 @rain-kl/dsh-preset-plus：保留其 preset-plus 独立模式，并把 tavern-authoring 加入注入作用域；在酒馆创作模式中可同时使用完整 tavern_* 工具和 Preset Plus 当前激活预设。
- 编辑 SillyTavern 世界书原生条目；右栏整栏是当前条目的「注入内容」编辑窗（角色卡内嵌世界书同样适用，随条目选择联动），点击「资源实时预览」可切回原右栏预览。
- 编辑 Chat Completion 提示列表并按 prompt_order 预览；Context、Instruct、TextGen 预设可保真编辑原始 JSON。
- 项目整体导出 ZIP，按 characters/、worldbooks/、presets/ 分类。
- 原始 JSON 是持久化真源；结构化编辑不会主动删除未知字段或 extensions。
- 首次启动插件时，如目标不存在，自动安装 $DSH_HOME/.agent-presets/tavern-authoring；不会覆盖用户已修改的同名预设。

角色卡与世界书格式检查

酒馆独立世界书与随卡世界书表示同一种内容，但 JSON 结构不同，编辑和复制时会按目标转换（依据 CCv2、CCv3 和 SillyTavern 导入实现）。

| 项目 | 独立世界书 | 角色卡 data.character_book |
| --- | --- | --- |
| 条目容器 / ID | entries 对象 / uid | entries 数组 / id |
| 关键词 | key、keysecondary | keys、secondary_keys |
| 启用 / 顺序 | disable（反向）、order | enabled、insertion_order |
| 插入位置 | 数值 position | before_char / after_char，高级数值位置在 extensions.position |
| 深度、概率等 | depth、probability 等 | 条目的 extensions 内 |

- tavern_asset_validate(projectId, assetId)：只读检查角色卡或世界书。返回 JSON Pointer 问题路径、错误/警告数量及安全修复路径，不返回正文或附件 Base64；支持 offset / limit 分页，默认 50、最多 100 项。此工具不校验预设。
- tavern_asset_repair(projectId, assetId)：默认 dryRun=true，仅预览修复前后的报告。明确传入 dryRun=false 才保存；若仍有无法安全修复的问题，整次修复不保存。缺失默认值、明确类型转换、条目容器/字段映射和旧版卡面镜像可以自动修复；损坏正文、重复 ID、无效附件描述等必须先用编辑工具处理。
- Agent 新增/复制条目自动补齐目标结构；随卡世界书的中栏与右栏编辑均写回数组和 CC 字段，不再写成独立世界书对象。原有标题、未知扩展和附属文件保留。
- 所有角色卡/世界书导出入口（包括项目 ZIP 和酒馆连接器）先在副本上做安全规范化，遇到未解决的格式错误会阻止该资源导出并给出路径；不会为了生成文件而清空错误正文。导出规范化不会改写工作区源资源，需持久化时使用修复工具。
- valid 仅表示已检查的关键导入结构没有错误，不是完整 SillyTavern 运行保证。酒馆示例中省略的 V3 group_only_greetings 和书级 extensions 仅提示警告，导出时补齐；不执行卡内脚本、不测试所有第三方扩展或远程附件可用性。独立 JSON 不打包附件，保留嵌入文件请使用 PNG/CHARX。

推荐工作流：按需读取 → 编辑 → tavern_asset_validate → tavern_asset_repair 预览 → 确认保存 → 导出。

本地包安装与开发

从源码构建 tarball 后安装：

npm install
npm test
npm pack
dsh plugin --profile web add .\dsh-stcardwriter-0.5.2-rc.1.tgz

开发期也可以直接链接当前目录：

dsh plugin --profile web add .

启动后，侧栏底部以及会话输入工具栏会出现“酒馆创作”入口；新建会话时可选择“酒馆创作模式”预设。首次自动创建预设后如列表尚未刷新，重启一次 DSH Host。
每个 DSH 工作区的数据独立保存在 /.tavernres/projects。.json 只保存角色卡、世界书、预设及二进制引用；PNG 原图、CHARX/PNG 附件和二进制 Data URI 拆分到相邻的 .assets/ 目录，并用相对路径、字节数和 SHA-256 校验。移动工作区时将 .tavernres 整体迁移即可。

酒馆连接器

连接器通过本地文件直连与 SillyTavern 同步，不依赖酒馆的内部 HTTP 接口，也没有 CSRF/鉴权问题；酒馆无需处于运行状态，导出后在酒馆界面刷新即可看到新文件。

- 连接：在工作台左侧“酒馆连接器”面板填入酒馆安装根目录（如 F:\SillyTavern，自动探测 data/ 下的用户，多用户可选）或用户数据目录（如 F:\SillyTavern\data\default-user），点“探测”确认后保存。连接配置按工作区保存在 /.tavernres/connector.json。
- 从酒馆导入：按目录分组浏览 characters/、worlds/、OpenAI Settings/、TextGen Settings/、context/、instruct/、sysprompt/，勾选后导入当前项目。同一酒馆文件重复导入默认替换项目内既有资源（保留资源 ID 与创建时间），也可切换为新增副本。
- 导出到酒馆：角色卡以 PNG 写入 characters/（文件名取卡面名，与酒馆 avatar 规则一致）；世界书写入 worlds/；预设按格式写入对应目录，无法识别格式时默认 sysprompt/（可显式指定）。同名冲突支持覆盖、改名（追加  (2)）或跳过。
- Agent 工具：tavern_connect_status、tavern_connect_configure、tavern_remote_list（分页）、tavern_remote_import、tavern_remote_export。
- REST API：GET/PUT/DELETE /api/dsh-stcardwriter/connector、POST /connector/probe、GET /connector/remote、POST /connector/import、POST /connector/export。

Preset Plus 共存

本插件固定依赖并加载 @rain-kl/dsh-preset-plus@0.1.5。使用 npm 发布版是为了满足 DSH 的 blockExoticSubdeps 供应链策略；bundle 配置将其作用域设为 preset-plus 与 tavern-authoring：

- 选择 PresetPlus 模式时，行为与原插件一致。
- 选择 酒馆创作模式时，使用本插件的完整酒馆工具集，同时应用 Preset Plus 当前激活预设的 system/user/assistant 条目。
- 预设的创建、导入、导出、启用和激活统一在 DSH 设置页的「预设增强」中管理；本插件不再注册第二套 system prompt section，因此不存在双注入或两个 complete 段冲突。
- 不要在同一个 profile 中再次单独安装 @rain-kl/dsh-preset-plus；它已经由本插件作为直接依赖加载。

Preset Plus 0.1.5 的客户端清单仍带有旧 dsh-client-runtime 包边，但其浏览器插件实际只注入 slots 服务并通过 slots.inject("settings.section", ...) 注册界面；在 DSH 0.1.2-rc.1 中包边只用于信息展示，不决定激活顺序，因此该旧清单项不会阻塞加载。兼容检查脚本会同时验证这一点。

从旧版升级时，插件只会将内容与曾发布版本精确一致的 managed v2/v3 组合迁移为 v4；迁移补齐目标命令、子 Agent 模型选择设置和 Web fetch。只要旧预设有任何用户修改，插件就不会覆盖。

格式策略

- 角色卡：导入时保留原始对象；导出 V3 时补齐规范必需字段，额外字段继续保留。PNG 同时写入 V3 ccv3 和 V2 兼容 chara 文本块，并按规范读写 chara-ext-asset_:{path}。CHARX 保持根 card.json 与所有归档成员。
- 世界书：使用 SillyTavern 的 { "entries": { "uid": entry } } 结构；编辑器提供其常用激活、顺序、概率和递归字段，其他字段可从原始 JSON 编辑。
- 预设：Chat Completion 使用 prompts + prompt_order；原始 JSON 始终保真保存。转换到 Preset Plus 时仅提取可静态注入的提示词，动态 marker 会跳过并报告，纯参数型 Instruct/TextGen 预设不会被猜测性转换。

安全与限制

- API 只挂载在 DSH 自身 WebServer 的同源 /api/dsh-stcardwriter 路径，不另开端口。
- 项目文件名只来自插件生成的 ID，写入使用同目录临时文件后原子替换。
- 单次导入请求上限 80 MiB。
- 连接器对酒馆目录的写入严格限制在七类资源子目录内，文件名净化后仍做越界检查，写入采用原子替换；连接器不提供删除酒馆文件的能力。
- Preset Plus 由 bundle 统一加载一次，并只对 preset-plus、tavern-authoring 两个模式启用。
- 右栏默认是所选世界书条目的「注入内容」整栏编辑窗（含角色卡内嵌世界书）；点击「资源实时预览」切回原预览，触发预览覆盖关键词、AND/NOT 选择逻辑。最终 token 预算、递归、分组竞争和概率结果仍以 SillyTavern 运行时为准。

致谢与贡献说明
- Rain-kl/dsh-preset-plus 由 Rain-kl 及其贡献者开发，并以 MIT License 发布。它为本项目提供多预设数据模型与设置界面、system/user/assistant 条目注入、assistant 伪装输出预填充，以及独立的 preset-plus Agent 模式。本项目通过 npm 直接依赖使用这些能力，并负责 tavern-authoring 作用域组合、非目标模式隔离和酒馆工具兼容；相关上游成果与著作权归原作者和贡献者所有。
- SillyTavern 社区维护了角色卡、世界书和预设生态，本项目围绕这些格式提供编辑与保真往返能力。
- DeepSeek Harness 提供插件、Agent 预设、工具和 Web UI 基础设施。

本项目自身使用 MIT License。第三方依赖分别遵循其各自许可证。