TavernHeadless

主题

Worldbooks（世界书管理） ​

世界书是一组由关键词触发的背景条目。聊天时，如果消息里出现了某个关键词，对应的世界书条目就会被自动注入到提示词里。

每个世界书可以包含很多条条目。世界书数据通常从 SillyTavern 导入。

什么时候需要看这页 ​

  • 你要查看导入进来的世界书列表
  • 你要查看世界书的原始内容
  • 你要管理世界书里的条目
  • 你要导出世界书

一个简单例子 ​

bash
# 列出所有世界书
curl http://localhost:3000/worldbooks

# 查看某个世界书里的条目
curl "http://localhost:3000/worldbooks/wb_001/entries"

先理解几个词 ​

词这里的意思
条目世界书里的一条记录，包含触发关键词和要注入的文本
触发当聊天消息里出现条目设置的关键词时，这条条目就会被激活
注入位置条目内容被插入到提示词的哪个位置（开头、结尾等）

世界书包含一组关键词触发的条目（entries），用于在对话中注入背景设定。

GET /worldbooks/:id 和 PUT /worldbooks/:id 面向原始 SillyTavern 世界书 payload。如果只需要对条目做结构化 CRUD，请使用后半部分的 Worldbook Entries 子资源接口。

列出 Worldbooks ​

http
GET /worldbooks

响应 200 ​

json
{
  "data": [
    {
      "id": "wb_kingdom",
      "name": "Kingdom Lore",
      "source": "sillytavern",
      "created_at": 1735689600000,
      "updated_at": 1735689660000,
      "version": 2
    }
  ]
}

获取 Worldbook 详情 ​

http
GET /worldbooks/:id

返回完整的世界书数据。

响应 200 ​

json
{
  "data": {
    "id": "wb_kingdom",
    "name": "Kingdom Lore",
    "source": "sillytavern",
    "data": {
      "name": "Kingdom Lore",
      "entries": [
        {
          "uid": 0,
          "key": ["kingdom", "realm"],
          "keysecondary": ["history"],
          "selective": true,
          "selectiveLogic": 0,
          "constant": false,
          "content": "The kingdom is recovering from a long war.",
          "comment": "Kingdom basics",
          "position": 0,
          "order": 100,
          "depth": 4,
          "role": 0,
          "disable": false,
          "scanDepth": null,
          "caseSensitive": null,
          "matchWholeWords": null
        }
      ],
      "scanDepth": 2,
      "caseSensitive": false,
      "matchWholeWords": false,
      "recursive": false,
      "maxRecursionSteps": 0
    },
    "created_at": 1735689600000,
    "updated_at": 1735689660000,
    "version": 2
  }
}

这里的 data.entries[] 使用的是原始 SillyTavern 字段名，例如 key、keysecondary、selectiveLogic、scanDepth、caseSensitive、matchWholeWords。它不同于下方 Worldbook Entries 子资源接口里的规范化字段 keys、keys_secondary、selective_logic、scan_depth 等。

错误 ​

状态码code说明
404not_found世界书不存在

更新 Worldbook ​

http
PUT /worldbooks/:id

此接口要求提供并发控制字段：

  • 新接入应优先传 expected_version
  • 现有主资源 PUT 路由仍兼容 expected_updated_at
  • 如果两者都不传，会返回 400

请求体 ​

字段类型必填说明
namestring是名称（至少 1 字符）
dataobject是原始 SillyTavern 世界书 JSON 数据
expected_versioninteger否推荐的乐观锁字段；期望的 version 值
expected_updated_atinteger否兼容字段；仅用于已有主资源 PUT 调用方

请求示例 ​

json
{
  "name": "Kingdom Lore v2",
  "expected_version": 2,
  "data": {
    "name": "Kingdom Lore v2",
    "entries": [
      {
        "uid": 0,
        "key": ["kingdom", "realm"],
        "keysecondary": ["history"],
        "selective": true,
        "selectiveLogic": 0,
        "constant": false,
        "content": "The kingdom has entered a new era of peace.",
        "comment": "Kingdom basics",
        "position": 0,
        "order": 100,
        "depth": 4,
        "role": 0,
        "disable": false,
        "scanDepth": null,
        "caseSensitive": null,
        "matchWholeWords": null
      }
    ]
  }
}

响应 200 ​

json
{
  "data": {
    "id": "wb_kingdom",
    "name": "Kingdom Lore v2",
    "source": "sillytavern",
    "created_at": 1735689600000,
    "updated_at": 1735690000000,
    "version": 3
  }
}

错误 ​

状态码code说明
400validation_error / worldbook_validation_error请求体校验失败、未提供 expected_version / expected_updated_at，或原始世界书 payload 无法通过校验
404worldbook_not_found世界书不存在
409worldbook_conflict版本基线过期，或兼容字段 expected_updated_at 不匹配
503resource_busy资源写入暂时繁忙，请稍后重试

删除 Worldbook ​

http
DELETE /worldbooks/:id

删除世界书时，其下所有条目会被级联删除。

删除时推荐通过 query string 传入 expected_version。此接口不使用 DELETE 请求体。

查询参数 ​

参数类型必填说明
expected_versioninteger否推荐的版本前置条件；不传时保留无前置条件删除行为

请求示例 ​

http
DELETE /worldbooks/wb_kingdom?expected_version=3

响应 204 ​

无响应体。

错误 ​

状态码code说明
400validation_error查询参数校验失败
404worldbook_not_found仅当传入 expected_version 且目标世界书不存在时返回
409worldbook_conflictexpected_version 与服务端当前版本不一致
503resource_busy资源写入暂时繁忙，请稍后重试

未传 expected_version 时，删除走无前置条件的幂等 204 路径。即使目标世界书已经不存在，接口仍返回 204。

Worldbook Entries（条目管理） ​

对单个世界书条目进行增删改查和批量操作，无需操作整个世界书 JSON。

所有条目端点都挂载在 /worldbooks/:worldbook_id/entries 下。

写入并发控制 ​

以下写入端点都支持 expected_version：

  • POST /worldbooks/:worldbook_id/entries
  • PATCH /worldbooks/:worldbook_id/entries/:id
  • PATCH /worldbooks/:worldbook_id/entries/batch/update
  • POST /worldbooks/:worldbook_id/entries/batch/delete
  • PUT /worldbooks/:worldbook_id/entries/batch/reorder

其中 DELETE /worldbooks/:worldbook_id/entries/:id 使用 query string expected_version，其他写入端点通过 JSON body 传递 expected_version。当版本基线过期时返回 409 worldbook_conflict；当 SQLite 写入暂时繁忙时返回 503 resource_busy。

条目字段说明 ​

字段类型说明
idstring条目 ID（系统生成）
worldbook_idstring所属世界书 ID
uidinteger数值 UID（ST 兼容，自动分配）
keysstring[]主关键词
keys_secondarystring[]辅助关键词
contentstring注入的文本内容
commentstring标题/备注
selectiveboolean是否启用辅助关键词
selective_logicinteger辅助关键词逻辑（0=AND_ANY, 1=NOT_ALL, 2=NOT_ANY, 3=AND_ALL）
constantboolean常驻条目（无需触发）
positioninteger插入位置（0–7）
orderinteger插入优先级
depthinteger@depth 模式的深度
roleinteger消息角色（0=system, 1=user, 2=assistant）
disableboolean是否禁用
scan_depthinteger | null独立扫描深度（null=使用全局）
case_sensitiveboolean | null独立大小写设置（null=使用全局）
match_whole_wordsboolean | null独立全词匹配（null=使用全局）
exclude_recursionboolean递归轮是否跳过该条目
prevent_recursionboolean该条目内容是否阻止继续进入递归缓冲区
delay_until_recursioninteger | null至少递归到指定层级后才允许命中
outlet_namestringposition=7 时使用的 outlet 名称
created_atinteger创建时间戳
updated_atinteger更新时间戳

列出条目 ​

http
GET /worldbooks/:worldbook_id/entries

查询参数 ​

参数类型默认值说明
limitinteger50每页数量（1–200）
offsetinteger0偏移量
sort_bystringorder排序字段：order / updated_at / uid
sort_orderstringascasc / desc
disableboolean—按禁用状态过滤
constantboolean—按常驻状态过滤
positioninteger—按插入位置过滤
qstring—搜索关键词/备注/内容

响应 200 ​

json
{
  "data": [
    {
      "id": "ent_abc123",
      "worldbook_id": "wb_kingdom",
      "uid": 0,
      "comment": "Kingdom basics",
      "content": "The kingdom is vast and ancient.",
      "keys": ["kingdom", "realm"],
      "keys_secondary": ["history"],
      "selective": true,
      "selective_logic": 0,
      "constant": false,
      "position": 0,
      "order": 100,
      "depth": 4,
      "role": 0,
      "disable": false,
      "scan_depth": null,
      "case_sensitive": null,
      "match_whole_words": null,
      "exclude_recursion": false,
      "prevent_recursion": false,
      "delay_until_recursion": null,
      "outlet_name": "",
      "created_at": 1735689600000,
      "updated_at": 1735689660000
    }
  ],
  "meta": {
    "total": 1,
    "limit": 50,
    "offset": 0,
    "has_more": false,
    "sort_by": "order",
    "sort_order": "asc"
  }
}

创建条目 ​

http
POST /worldbooks/:worldbook_id/entries

请求体 ​

字段类型必填说明
expected_versioninteger否期望的父世界书 version 值
keysstring[]是主关键词
contentstring是注入内容
commentstring否标题/备注
keys_secondarystring[]否辅助关键词
selectiveboolean否默认 true
selective_logicinteger否默认 0
constantboolean否默认 false
positioninteger否默认 0；7 表示 outlet
orderinteger否默认 100
depthinteger否默认 4
roleinteger否默认 0
disableboolean否默认 false
scan_depthinteger | null否默认 null
case_sensitiveboolean | null否默认 null
match_whole_wordsboolean | null否默认 null
exclude_recursionboolean否默认 false
prevent_recursionboolean否默认 false
delay_until_recursioninteger | null否默认 null
outlet_namestring否默认空字符串，仅 position=7 时有意义

运行时说明：

  • position=7 的条目现在会进入真实 prompt 组装。
  • 如果预设里存在同名 outlet marker，会按该 marker 的位置注入；如果没有匹配 marker，当前实现会回退为显式 section，而不是静默丢弃。

请求示例 ​

json
{
  "expected_version": 3,
  "keys": ["kingdom", "realm"],
  "content": "The kingdom is vast and ancient.",
  "comment": "Kingdom basics"
}

响应 201 ​

返回创建的完整条目对象（格式同列表中的单个条目）。

错误 ​

状态码code说明
400validation_error请求体校验失败
404not_found世界书不存在
409worldbook_conflictexpected_version 过期
503resource_busy资源写入暂时繁忙，请稍后重试

获取条目 ​

http
GET /worldbooks/:worldbook_id/entries/:id

响应 200 ​

json
{
  "data": {
    "id": "ent_abc123",
    "worldbook_id": "wb_kingdom",
    "uid": 0,
    "comment": "Kingdom basics",
    "content": "The kingdom is vast and ancient.",
    "keys": ["kingdom", "realm"],
    "keys_secondary": ["history"],
    "selective": true,
    "selective_logic": 0,
    "constant": false,
    "position": 0,
    "order": 100,
    "depth": 4,
    "role": 0,
    "disable": false,
    "scan_depth": null,
    "case_sensitive": null,
    "match_whole_words": null,
    "exclude_recursion": false,
    "prevent_recursion": false,
    "delay_until_recursion": null,
    "outlet_name": "",
    "created_at": 1735689600000,
    "updated_at": 1735689660000
  }
}

错误 ​

状态码说明
404世界书或条目不存在

更新条目 ​

http
PATCH /worldbooks/:worldbook_id/entries/:id

部分更新，只传需要修改的字段。至少传一个字段。

请求体可选传入 expected_version，用于校验父世界书版本。

请求示例 ​

json
{
  "expected_version": 3,
  "content": "The kingdom has entered a new golden age.",
  "disable": false
}

响应 200 ​

返回更新后的完整条目对象。

错误 ​

状态码code说明
400validation_error请求体校验失败或未传任何更新字段
404not_found世界书或条目不存在
409worldbook_conflictexpected_version 过期
503resource_busy资源写入暂时繁忙，请稍后重试

删除条目 ​

http
DELETE /worldbooks/:worldbook_id/entries/:id

查询参数 ​

参数类型必填说明
expected_versioninteger否期望的父世界书 version 值

响应 200 ​

json
{
  "data": {
    "id": "ent_abc123",
    "deleted": true
  }
}

错误 ​

状态码code说明
404not_found世界书或条目不存在
409worldbook_conflictexpected_version 过期
503resource_busy资源写入暂时繁忙，请稍后重试

批量更新条目 ​

http
PATCH /worldbooks/:worldbook_id/entries/batch/update

对多个条目应用相同的字段更新。

请求体 ​

字段类型必填说明
expected_versioninteger否期望的父世界书 version 值
idsstring[]是条目 ID 数组（1–100，不可重复）
fieldsobject是要更新的字段（同更新条目的请求体）

请求示例 ​

json
{
  "expected_version": 3,
  "ids": ["ent_abc123", "ent_def456"],
  "fields": {
    "disable": true
  }
}

响应 200 ​

json
{
  "data": {
    "results": [
      {
        "index": 0,
        "id": "ent_abc123",
        "action": "updated",
        "data": { "...完整条目对象..." }
      },
      {
        "index": 1,
        "id": "ent_def456",
        "action": "not_found"
      }
    ],
    "meta": {
      "total": 2,
      "updated": 1,
      "not_found": 1
    }
  }
}

批量删除条目 ​

http
POST /worldbooks/:worldbook_id/entries/batch/delete

请求体 ​

字段类型必填说明
expected_versioninteger否期望的父世界书 version 值
idsstring[]是条目 ID 数组（1–100，不可重复）

请求示例 ​

json
{
  "expected_version": 3,
  "ids": ["ent_abc123", "ent_def456"]
}

响应 200 ​

json
{
  "data": {
    "results": [
      { "index": 0, "id": "ent_abc123", "action": "deleted" },
      { "index": 1, "id": "ent_def456", "action": "not_found" }
    ],
    "meta": {
      "total": 2,
      "deleted": 1,
      "not_found": 1
    }
  }
}

批量重排序条目 ​

http
PUT /worldbooks/:worldbook_id/entries/batch/reorder

批量更新条目的 order 字段。

请求体 ​

字段类型必填说明
expected_versioninteger否期望的父世界书 version 值
itemsobject[]是排序项数组（1–100，id 不可重复）
items[].idstring是条目 ID
items[].orderinteger是新的排序值

请求示例 ​

json
{
  "expected_version": 3,
  "items": [
    { "id": "ent_abc123", "order": 10 },
    { "id": "ent_def456", "order": 20 }
  ]
}

响应 200 ​

json
{
  "data": {
    "results": [
      {
        "index": 0,
        "id": "ent_abc123",
        "action": "updated",
        "data": { "...完整条目对象..." }
      },
      {
        "index": 1,
        "id": "ent_def456",
        "action": "updated",
        "data": { "...完整条目对象..." }
      }
    ],
    "meta": {
      "total": 2,
      "updated": 2,
      "not_found": 0
    }
  }
}

错误（所有批量端点通用） ​

状态码code说明
400validation_error请求体校验失败或 ID 数组有重复
404not_found世界书不存在
409worldbook_conflictexpected_version 过期
503resource_busy资源写入暂时繁忙，请稍后重试