dsh-LorebookMD

一句话定位

dsh-LorebookMD 是 DeepSeek Harness（DSH）的本地化世界书插件：把酒馆（SillyTavern / TavernAI）格式的角色卡与独立世界书导入后落成本地 Markdown 设定文档，并提供「创作模式」让模型参考这套设定直接写出小说正文。

核心能力

• 导入酒馆角色卡 PNG（解析 PNG 的 tEXt chunk 中 chara 关键字）与 JSON（chara_card_v2/v3 与旧版字段置顶格式），同时提取内嵌世界书（extensions.world 或 character_book）与正则脚本
• 导入独立世界书 JSON（{ entries: [...] }）与独立正则脚本 JSON，每本世界书自动生成两份预设：「·世界书」（关键词触发用）与「·创作」（创作指令 + 设定全文）
• 把每本世界书的设定落地为本地 Markdown 文档 worldbooks/<名>.md（带编号、触发词、注释、分节），可手工编辑
• 在 Web 端设置页「世界书创作」分区集中管理：列表 / 进入创作 / 世界书模式 / 编辑本地文档 / 导入 / 删除；数据通过同源 JSON RPC /prompt-manager/api 与 host 半共享
• 关键词自动触发（agent/pre-step 钩子）：激活「·世界书」预设后，模型每轮读到用户消息时把命中触发词的条目以 user-role context 注入本轮，支持 constant（始终生效）、正则、大小写敏感、全词匹配等酒馆原版选项
• 提供对话工具 prompt_preset_list/use/off/save/delete 与 prompt_import_tavern/world/regex，随时切预设或重新导入文件

技术实现

• 语言: TypeScript（host 半 src/index.ts + browser 半 src/client/index.ts，构建产物 lib/index.js 与 lib/client.js）
• 关键依赖: @deepseek-ai/cordis（cordis 插件框架 + schemastery 配置 schema）、@deepseek-ai/dsh-tools（defineTool 工具注册）、@deepseek-ai/dsh-home-paths（数据目录路径解析）、@deepseek-ai/dsh-host-webserver（Web 路由注册）。所有 @deepseek-ai/* 由 DSH profile 运行时提供，发布包不打包
• 架构模式: 双面 cordis bundle。host 半注入 tools / systemPrompt / webServer，注册 systemPrompt.section 把当前激活预设注入系统提示词（text 是求值函数，切换/修改后下一轮即生效）；browser 半注入 slots，在 settings.section 注册「世界书创作」分区 React 组件，通过 /prompt-manager/api 与 host 半通信
• 入口文件: src/index.ts（host，导出 name='prompt-manager'、inject=['tools','systemPrompt','webServer']、apply）、src/client/index.ts（client，导出 name='prompt-manager-client'、inject=['slots']、apply）；构建走 .dsh-tools/tsdown/run.mjs

适用场景

手头有一批酒馆角色卡 / 世界书 JSON，想把它们从原来的在线服务里迁出来管理。当想做基于这套设定的长篇或短篇小说，但不想每次开新会话都重新贴一遍设定时，导入到本插件后激活「·创作」就能让模型始终参考同一份本地文档写作；想沉浸式扮演时切到「·世界书」，让设定按触发词自动出现而不用全文灌输。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:609476965/dsh-LorebookMD

配置项

这些字段在 cordis.patch.yml 的 config: 块里设置；schemastery 严格校验，填错或填入未知字段会导致加载失败。普通用户装好后无需调整。

常见问题

Q: 安装后在 DSH 的哪里使用？

A: Web 端打开设置 →「世界书创作」分区。客户端声明 dsh.client.platform=web，所以 CLI / TUI / 桌面客户端看不到这个分区，但能通过对话工具间接调用。

Q: 「进入创作」和「世界书模式」怎么选？

A: 想写小说就激活「·创作」预设，模型会用第三人称连贯叙述输出正文；想沉浸式扮演就激活「·世界书」预设，提到触发词时把对应条目临时注入本轮。两种模式随时可切换，停用回到正常对话。

Q: 导入酒馆角色卡 PNG 时会生成什么？

A: 一个角色卡预设（描述/性格/场景/示例对话/系统提示 拼成正文）、一个「·世界书」预设（关键词触发用）、一个「·创作」预设（创作指令 + 设定全文）、一份本地 Markdown 文档 worldbooks/<名>.md；卡内正则脚本会另存为「·正则」预设。

Q: 数据存在哪里？可以手工编辑吗？

A: 三处都在 ~/.dsh/dsh-LorebookMD/ 下：presets.json（预设正文）、worldbooks.json（条目原始数据，关键词匹配用）、worldbooks/<名>.md（可手工编辑的 Markdown 文档）。改 presets.json 时插件会自动热加载（200ms 防抖）。

Q: 数据文件写坏了怎么办？

A: 插件启动时如果 JSON 解析失败，会把损坏文件改名成 *.broken-<时间戳> 备份，并以空库启动，不会让后续保存覆盖你的原始数据。建议先看一眼备份文件再决定是否恢复。

Q: 正则脚本会真的执行吗？

A: 不会。DSH 没有聊天正则渲染管线，导入后的正则脚本只是「·正则」预设里的文字定义，供查看参考；如果需要做等价替换，需要自己按定义里的 pattern 手动处理。

Q: 「编辑文档」按钮打不开本地 .md 怎么办？

A: 插件会用系统默认程序打开文件（Windows: start / macOS: open / Linux: xdg-open）。如果系统没有关联 .md 程序或权限受限，spawn 会失败但 API 不报错——手动用任何编辑器打开 ~/.dsh/dsh-LorebookMD/worldbooks/<名>.md 即可。

Q: 需要额外的 API Key 或联网吗？

A: 不需要。预设、设定文档、世界书条目都存在本地磁盘，只有导入工具读取你指定的本地文件；模型生成小说靠 DSH 当前的会话模型。

上手难度

入门 — 装好后打开设置分区，导入一张角色卡或一个世界书 JSON，点「进入创作」就能用；要调细节（如触发词、条目顺序）时直接编辑 worldbooks/<名>.md 即可。

已知问题与限制

• 正则脚本导入后只在「·正则」预设里以文字呈现，不会在对话中自动执行；DSH 没有等价的聊天正则渲染管线（src/tavern.ts:178-181）
• 角色卡预设里的 {{user}} 占位符会被替换为「用户」，{{char}} 替换为当前激活预设名；DSH 已注册变量（provider / model / cwd）保留，其余未知变量会被丢弃以避免 DSH 渲染器报错（src/index.ts:834-844）
• 「编辑文档」按钮依赖系统关联程序：未关联 .md 时 spawn 会失败但 API 不报错，需要用户手动用编辑器打开（src/index.ts:617-627）
• 客户端仅在 web profile 下生效（package.json#dsh.client.platform=web），CLI / TUI / 桌面客户端看不到设置分区（package.json:36-46）
• 角色卡内嵌世界书条目时按 extensions.world 优先、character_book 拼接合并；只存名字字符串的空 world 会被忽略而不报错（src/tavern.ts:378-411）

一个面向 DeepSeek Harness（DSH）的插件：导入酒馆（SillyTavern/TavernAI）角色卡与世界书，落地为本地 Markdown 设定文档，激活创作模式后根据用户输入、参考世界书创作小说。

说明：本插件只管理你自己提供的设定文本；工程内不内置任何"破限/越狱"提示词内容。

功能

• 导入：角色卡（PNG 内嵌 / JSON）与独立世界书（{ entries: [...] }），兼容 extensions.world、SillyTavern character_book（角色书）与常见导出变体
• 落地本地：每本世界书生成三件产物——
  • 名·世界书 预设：设定全文 + 关键词自动触发（对话中按触发词注入对应条目）
  • 名·创作 预设：创作模式（创作指令 + 设定全文，激活后输入场景即生成小说正文）
  • worldbooks/<名>.md：本地 Markdown 设定文档，可手工编辑
• 设置页（设置 →「世界书创作」）：世界书列表 / 进入创作 / 世界书模式 / 编辑文档（系统默认程序打开本地 .md）/ 导入 / 删除
• 对话工具：prompt_import_tavern / prompt_import_world 等与设置页共享同一份数据

两种模式怎么用

想"写小说"用「进入创作」，想"扮演/对话"用「世界书模式」；两者可随时切换，停用后回到正常会话。

安装

跟 DSH 说

帮我安装这个插件https://github.com/609476965/dsh-LorebookMD

从 npm 安装（推荐）

dsh plugin --profile web add dsh-lorebookmd

发布包已内置构建产物（lib/）；dsh plugin 会自动把本包加入 dsh.profile.bundles 并应用 cordis.patch.yml，之后用 start-dsh.cmd 正常启动即可，无需 --patch。

本地试装（未发布时）：npm pack 生成 dsh-lorebookmd-1.0.0.tgz，然后 dsh plugin --profile web add ./dsh-lorebookmd-1.0.0.tgz。

手动安装

1. 一键安装：双击 install.cmd（或 powershell -ExecutionPolicy Bypass -File install.ps1）。脚本把插件复制到 DSH profile 的 node_modules（发布包已内置构建产物，无需本地构建环境）。

2. 挂载（二选一）：

   • 自动挂载（推荐）：把 dsh-lorebookmd 追加到 ~\.dsh\profiles\web\package.json 的 dsh.profile.bundles 数组，之后用 start-dsh.cmd 正常启动即可（DSH 会自动应用插件的 cordis.patch.yml，无需 --patch）
   • 临时挂载：双击 start-dsh-plugin.cmd（以 --patch 加载 cordis.yml）

以上挂载方式任选其一，勿同时使用（会重复挂载）。打开 http://127.0.0.1:3080：设置 →「世界书创作」即可使用；终端应打印 [prompt-manager] ready: …。

安装原理：正常安装 = 把插件包放进 DSH profile 的 node_modules。插件源码的 @deepseek-ai/* 依赖由 profile 运行时直接解析（DSH 自带完整运行时包），无需额外依赖链。更新插件：升级安装新版本后重启 DSH 即可。

数据位置

开发

node .dsh-tools/install-deps.mjs   # 首次开发前：重建 node_modules 依赖链（仅开发需要）
npm run bundle    # 构建 lib/client.js（改代码后需重新构建并随提交更新）
npm test          # 运行测试（Node >= 22.18 内置类型剥离）
npm run typecheck # tsc --noEmit 严格检查