Skip to content

后端 v0.2 · 项目整体已入轨

TavernHeadless

为下一代 AI RP 平台构建基础设施

面向开发者的 AI RP 后端引擎 · Headless 架构 · SillyTavern 兼容 · TypeScript 全栈

引擎一览

0层消息结构Session → Floor → Page
0级变量系统全局 / 会话 / 分支 / 楼层 / 页
0+REST 资源会话、内容、变量、记忆、Tools、MCP 等
0官方接入包@tavern/sdk + @tavern/client-helpers

核心能力

兼容 SillyTavern 生态

导入 Preset、Regex、Worldbook、角色卡即可使用。已有的酒馆资产不需要重新配置。

三层消息结构

会话 → 楼层 → 消息页。分支、重试、回放和当前生效版本在这个结构里处理。

五级变量系统

全局 / 会话 / 分支 / 楼层 / 页级变量,优先级从低到高。页级沙箱保证重新生成不互相影响。

提示词编排

兼容模式沿用酒馆的拼接方式,原生模式走图编译。最终都输出同一份 Prompt IR。

记忆系统

自动提取摘要、结构化存储、按需注入上下文。后台异步维护,不阻塞对话。

开发者体验

TypeScript 全栈,接口有 OpenAPI 文档,接入有官方 SDK,调试有 dry-run。

一次回复背后的六步

用户发一条消息到 AI 回一条消息,中间经过六步。

会话层

绑定资产

角色卡、预设、世界书、正则和模型配置在创建会话时绑定。

过程

创建会话时把配置定好,后面的步骤都沿用同一份上下文。

结果

不需要每次生成都重新传入配置。

用 SDK 接入

不用自己拼 HTTP 请求和 SSE 解析。SDK 已经按资源分好了方法,直接调就行。

资源方法SSE 回调统一错误
  • createTavernClient() 把 baseUrl、headers 和底层请求收拢到一处
  • respondStream() 封装了 SSE 读取,你只要写回调
  • 入参、返回值和错误对象都有类型
quick-start.ts
1

让 Agent 帮你更快上手

已经知道要做什么了?不用翻一堆文档。 看一眼 /agent 里最新的变更摘要,再跟着对应的 Skill 走就行。

变更摘要Skill 引导验证清单
  • 第一次接入 TavernHeadless
  • 升级已有的接入代码
  • 参与开发、提交 PR
01

看一眼最新变更

打开 /agent/latest.json,几秒就能知道这次主干更新动了哪些接口、改了哪些包导出。

查看 Agent 总入口
02

挑一个 Skill 跟着走

做客户端接入就看「客户端接入与升级」,参与仓库开发就看「参与开发与协作」。不用自己拼流程。

查看 Skill 索引
03

跑一遍验证收工

Skill 里列好了验证步骤:typecheck、测试、文档构建,照着顺序来就行。

查看参与开发 Skill
一句话说

/agent 告诉你「改了什么」,Skill 告诉你「怎么做」。 对着看,省掉自己整理的时间。

技术选型

后端框架Fastify
语言TypeScript
数据库SQLite + Drizzle ORM
LLM 接入Vercel AI SDK
事件系统emittery
前端(管理台)Vue 3 + Pinia + TailwindCSS
包管理pnpm (monorepo)

仓库结构

@tavern/sdk 和 @tavern/client-helpers 对外提供接入,其他包按职责划分。

project structure
TavernHeadless/
├── apps/
├── api/# 后端服务(Fastify)
└── web/# 管理前端(Vue 3)
├── packages/
├── core/# 核心引擎逻辑
├── adapters-sillytavern/# 酒馆兼容层
├── shared/# 公共类型和内部共享工具
└── official-integration-kit/
├── sdk/# 官方接入基础层
└── client-helpers/# 官方接入语义层
├── docs/# 设计文档
└── vitepress/# 在线文档站
未来展望

RP Agentic 运行时

TavernHeadless 的 Agentic 不是把 RP 变成自动任务执行。 它是把 RP 运行时拆成一套可解释、可重放、可治理的舞台系统—— NodeGraph 管编排,Agent 出决策,Narrator 写正文,CommitGate 守正史。

NodeGraph 编排层

可解释、可调试、可重放的 Prompt / Agent / State 编排层。NodeGraph 是舞台机械,RP Agent 是导演组,两者的职责不混淆。

RP 分工模型

Narrator 是唯一写正文的实例。Director 出导演意图,Memory 做场记,Verifier 做连续性检查,Player Agency Guard 守住玩家主导权。

Floor / Page 重试

Floor 持有回合上下文,Page 是一次生成尝试。正文前节点可缓存到 Floor,正文后归属 Page。重试不重建 Floor,从指定 checkpoint 继续。

正史闸门

CommitGate。工具调用结果、记忆提案、状态写入默认落在 Page 暂存区,只有被接受的生效 Page 才能把暂存写入提升为正史。

状态双轨

Variables 负责 prompt 近场轻量事实;Session State 负责受治理的会话正史状态。两者定位不同,不互相替代。

三层模式兼容

compat_strict 保留酒馆行为;compat_plus 允许轻量辅助;naive_graph 启用完整 Agentic + NodeGraph。Agentic 不会侵入严格兼容模式。

以上六个维度不是路线图承诺,而是架构设计的长远意图。当前阶段已经有 Floor / Page 模型、Variables + Session State 双轨、工具调用权限分层和暂存写入语义,这些都是 Agentic 运行时的地基。