酒馆世界书 libolunm/dsh-worldbook

dsh-worldbook

给 DeepSeek Harness（dsh） 用的酒馆式世界书。两类条目：

- 蓝灯（constant）：每次模型调用都作为常驻背景出现在系统提示里。
- 绿灯（关键词）：用户消息命中触发词时，在那一轮对话里插入一条背景资料消息。

附带一个装进 dsh web 设置面板的可视化编辑器，以及一个让 Agent 自己读写世界书的 worldbook 工具（说一句「记住…」就能存成条目）。

目录结构

| 目录 | 装到哪 | 作用 |
| worldbook/ | /plugins/worldbook/ | 引擎（agent 侧）：注册常驻提示段、worldbook 工具、agent/pre-step 关键词注入 |
| worldbook-editor/ | ~/.dsh/profiles//plugins/worldbook-editor/ | 编辑器（web 侧）：提供 /worldbook 页面与 /worldbook/api，并在设置面板挂一个分区 |
| examples/worldbook.example.json | 复制成你的 worldbook.json | 示例数据，含蓝灯／绿灯／停用三种形态 |

两个插件共用同一个 worldbook.json，彼此独立：只装引擎也能用（靠 Agent 工具维护），只装编辑器等于一个顺手的世界书文件编辑器。

安装

1. 引擎（agent 侧）

把 worldbook/ 整个目录拷进你的 preset，例如 ~/.dsh/.agent-presets/tavern/plugins/worldbook/，然后在 preset 的 agent.cordis.yml 里加一行：

- id: worldbook
name: './plugins/worldbook/index.js'
config:
path: './worldbook.json'
sectionOrder: 420

- name 以 ./ 开头 → 相对 preset 目录解析，插件跟着 preset 走，不用额外装 npm 包。
- config.path 同样相对 preset 目录；省略则默认 ./worldbook.json。
- sectionOrder 决定常驻段在系统提示里的排序，默认 420（数值越小越靠前）。
- 这条 row 不发布任何服务、不需要 isolate realm：它只消费宿主的 systemPrompt 与 tools 注册表，并监听 agent/pre-step 瀑布。

preset 里的内联插件在进程启动时加载，装完需要重启 dsh。

2. 编辑器（web 侧）

把 worldbook-editor/ 拷进 profile 的 plugins/ 目录，例如 ~/.dsh/profiles/web/plugins/worldbook-editor/，然后在同一个 profile 的 cordis.patch.yml 里加：

- insert:
- id: worldbook-editor
name: './plugins/worldbook-editor/index.mjs'

重启 dsh（或该 profile 配了 patchReload: live 时热载），打开 http://127.0.0.1:3080/worldbook，或在 设置 → 世界书 里看到它。

世界书文件的路径解析

引擎与编辑器顺序一致，取第一个命中的：

1. config.path（引擎在 preset row 里给，编辑器在 patch entry 里给）
2. 环境变量 DSH_WORLDBOOK_PATH
3. 默认 ~/.dsh/.agent-presets/tavern/worldbook.json

编辑器吃的是绝对路径最稳；相对路径按进程工作目录解析。

数据格式

worldbook.json 就是一个对象包一个 entries 数组：

{
"entries": [
{
"id": "entry-machine-setup",
"title": "本机环境", "content": "ComfyUI 在 E:\\woyao，端口 8188。", "constant": true, "enabled": true,
"keys": [],
"repeat": "once",
"caseSensitive": false
}
]
}

| 字段 | 类型 | 说明 |
| id | string | 必填，非空、全局唯一 |
| title | string | 必填，非空 |
| content | string | 必填，非空；注入时的正文 |
| constant | boolean | true = 蓝灯常驻；否则为绿灯 |
| keys | string[] | 绿灯的触发词；constant !== true 时至少一个非空 |
| caseSensitive | boolean | 默认 false |
| repeat | "once" \| "always" | 默认 once |
| enabled | boolean | 默认 true；false 表示停用 |

校验是严格的：非法结构直接抛错，不会静默修复或丢弃未知字段。手写文件时给 worldbook.json 配上编辑器里的 JSON 校验，比事后猜错在哪快得多。

Agent 工具：worldbook

引擎注册的工具，模型可直接调用：

| op | 必填参数 | 行为 |
| list | — | 列出全部条目（含 modes、关键词） |
| get | id | 读取单条全文与当前 revision |
| add | 视条目而定 | 追加条目；id 省略时自动生成 |
| update | id + expectedRevision | 按 id 改字段（省略的字段保持原样） |
| remove | id + expectedRevision | 删除条目 |
| reload | — | 立即重读文件并刷新内存快照 |

改／删之前先 get 拿 revision，再把它当 expectedRevision 传回；版本不一致会明确报「版本冲突」而不是覆盖别人的修改。

编辑器

- 左侧条目列表：搜索框过滤（标题／正文／关键词），四个筛选页签（全部／蓝灯／绿灯／停用）。
- 右侧表单：标题、激活方式（蓝灯·常驻／绿灯·关键词）、关键词、区分大小写、触发频率（每会话首次命中／每次新消息命中）、启用开关、删除。
- 顶部：重新读取（放弃本页草稿）与保存更改（Ctrl+S 同效）。有未保存修改时关闭页面会拦一下。
- 保存走乐观锁：文件被别人（或 Agent）改过就返回 409，页面上给提示并保留你的草稿，让你重新读取后再合并。
- 备注：修改在保存后才落盘；蓝灯段在下次模型调用时读到新内容，已经进入历史对话的背景资料不会从历史里抹掉。

并发与安全语义

- 修订号：文件内容的 SHA-256。引擎、编辑器、以及所有协作写入者共用同一个修订号做乐观锁。
- 写锁：每次写盘前用 open(path, 'wx') 抢一个 worldbook.json.lock。抢不到就明确失败，绝不偷锁、绝不静默覆盖。
- 原子替换：写临时文件 → fsync → rename 覆盖，读到的永远是完整文件。
- 二次校验：持锁后以及替换前各再读一次修订号，能抓到不守规矩的外部改动。
- 编辑器 HTTP 面：PUT /worldbook/api 要求同源（校验 Origin 与 sec-fetch-site）、Content-Type: application/json、请求体 ≤ 1 MiB；写盘前先备份 worldbook.json.bak；响应带 no-store 与 nosniff，编辑器页面带 CSP。
- 编辑器只监听本机 dsh web 服务器，不额外开端口。

触发语义细节

- 命中判定基于本轮进入的 user 消息文本；插件自己插入的合成消息不参与匹配（不会自我触发)。
- 关键词是纯子串包含，不做分词、不支持正则；caseSensitive: false 时两侧都转小写再比。
- repeat: once：同一个 agent 内，同一版本的条目只注入一次。「版本」是该条目对象的 JSON 哈希 —— 条目内容被改动后，哈希变了，可以再次注入。
- repeat: always：只要命中就注入。
- 合成消息紧跟触发它的那条用户消息之后插入，source.kind 为 plugin，视觉上与用户消息区分开。
- 蓝灯段与绿灯匹配都会在每次模型调用前重读文件，所以手改 worldbook.json 立即生效（除非你改的是插件配置里的路径）。

常见问题

编辑器 404 / 设置里没有「世界书」：确认 worldbook-editor/ 放进了 profile 的 plugins/、patch 里的相对路径对得上、profile 名没错（~/.dsh/profiles//），然后重启 dsh。

改了文件不生效：蓝灯与绿灯都会重读文件；只有改插件配置（config.path、sectionOrder）才需要重启。

保存报 409：文件被其他页面或 Agent 改过，点「重新读取」合并后重存。

提示世界书被锁定：有写入者没释放 worldbook.json.lock。确认没有正在写的进程后删掉这个残留文件即可。

条目明明命中却不注入：检查 enabled 是否为 false、keys 是否写成了别的分词、repeat: once 是否在本会话已经触发过；get 一下看看到底存的是什么。

License

MIT © 2026 libolunm

English summary

A tavern-style world book for DeepSeek Harness (dsh). Two halves:

- worldbook/ — the engine, mounted inside an agent preset via agent.cordis.yml. It renders constant entries as a standing system-prompt section, injects keyword-matched entries as a synthetic message on agent/pre-step, and registers a worldbook read/write tool.
- worldbook-editor/ — a same-origin web editor served by the dsh web server at /worldbook, mounted as a settings section through the profile's cordis.patch.yml.

Both halves share one worldbook.json (SHA-256 revision for optimistic locking, exclusive .lock file, atomic temp-write + rename). Path resolution: config.path → DSH_WORLDBOOK_PATH → ~/.dsh/.agent-presets/tavern/worldbook.json. MIT licensed.