中文 · English · 官网 · 平台总览 · SagaSmith Web · 内容目录
AI 原生 TTRPG 平台的系统无关运行时。 sagasmith-core 为规则系统、MCP 服务和 UI 提供持久化战役、角色知识、分支时间线、内容导入、规则包与检索能力；它本身不包含 D&D 或 CoC 规则。
世界状态应当可验证，时间线应当可分支，每个角色只应知道自己真正知道的事。
| 目标 | 入口 |
|---|---|
| 在系统包中使用 Core | pip install sagasmith-core，再看下方最小服务构造 |
| 接入当前规则系统 | D&D · CoC · Narrative |
| 理解数据与事务边界 | Architecture · Quickstart |
| 创建或导入内容包 | Content Packages |
| 配置检索与 cache | Retrieval |
需要 Python 3.11+。大多数最终用户应安装对应的系统 MCP/Local Kit，而不是直接操作 Core 数据库。
普通聊天记忆无法充当长期战役数据库：它不知道哪条时间线有效，也无法可靠区分 GM、玩家、PC 和 NPC 的视角。SagaSmith Core 把这些问题建模为显式服务：
- 战役与角色 — system-neutral campaign/character 模型、namespaced sheet、revision 和访问控制。
- 分支与 Snapshot — 不可变 Snapshot DAG、checkout、lineage、分支连续性和完整性校验。
- Actor Knowledge — 按 actor、主体、分支和可见范围维护所知事实，不把角色知识混入全局摘要。
- 事件与长期记忆 — 事件日志、事实身份、分支修订、continuity context 与 recap 数据面。
- 规则包 — core/extension 包、profile 锁定、版本与来源、规则 receipt 和机械 IR。
- 内容导入 — 可恢复 import job、内容寻址的标准化/页面缓存、PDFium 文本提取、选择性 OCR 质量门禁与页码索引。
- 统一内容包 — core rules、addon、module、preset 共用 v2 归档骨架，携带 v3 PC/NPC/怪物卡、标准化来源、内容寻址资产、严格校验及模块 Agent 定稿记录。
- 检索 — 精确与词法检索、SQLite FTS5，以及可选的 ChromaDB + sentence-transformers。
- 插件系统 — 通过
sagasmith.systemsentry point 注册 D&D、CoC 或新的系统实现。
flowchart TB
A[Agent / MCP Host] --> M[System MCP Server]
M --> R[System Runtime<br/>D&D · CoC · custom]
R --> C[SagaSmith Core]
C --> D[(SQLite / PostgreSQL)]
C --> F[FTS5]
C -. optional .-> V[ChromaDB / embeddings]
Core 不负责主持风格、MCP 工具暴露或具体规则裁决。Agent Skills 负责工作流，系统运行时负责规则，MCP 服务负责能力与存储边界，Core 负责一致的数据语义。
SagaSmith Web 不直接读取 D&D、CoC 或 Narrative 的权威表。领域 MCP 成功提交后可以通过 可重建的 revisioned projection/receipt 边界为 Web 提供读取模型；failed、rolled-back 或 no-op 写入不得伪造 cache 失效。Core 的向量、页面与 embedding cache 同样只是可重建性能层， 不能替代 revision、事件、事实、角色知识或 Snapshot 权威。
| 领域 | 当前仓库 | 同仓版本化组件 |
|---|---|---|
| D&D 5e | sagasmith-dnd |
Domain、MCP、Skills、UI、模组生成流程 |
| Call of Cthulhu 7e | sagasmith-coc |
Domain、MCP、Skills、UI、模组生成流程 |
| Narrative | sagasmith-narrative |
Domain、MCP、Skills、项目生成流程 |
以上三个垂直仓库是当前唯一源码入口。原独立 MCP、Skills、UI 与通用 Module Generator 仓库已归档，只保留只读历史；新集成不得依赖其分支、发布或文档。
权威历史读取在服务边界保持有界。EventService.list*、MemoryService.search、
ActorKnowledgeService.search、ContinuityService.context 与 RevisionService.history
接受有界分页和经过校验的 offset，让领域 MCP
可以用 opaque continuation cursor 翻过前 100 条记录，而不必把完整战役历史加载到公开工具响应。
Continuity 会同步推进事实、事件和角色认知的候选窗口，并在
retrieval.pagination 中返回逐流前瞻状态与 next_offset。
EventService.list_for_actor_event_ids 可按同一分支、参与者、认知来源与 audience
规则精确解析最多 128 个旧事件引用，避免持久 scene/actor ref 被近期历史窗口遮蔽。
现代 Host 使用 sagasmith.auth-context/v2 逐请求委托，不依赖隐藏 transport session。
Core 会分别保留 requester、resource owner、acting Host/character、audience、具体操作、
room turn 与 base revision。v2 的 actor_principal/authority_principal 明确表示实际执行
权威操作的 acting Host；authorization_principal 则表示接受 campaign role 校验的
requester。两者不得互相冒充，审计 receipt 会保留原始身份字段。v1 只留在显式 legacy
兼容路径，其 actor_principal 继续同时表示调用者与授权主体。
这条边界不改变 Core 的职责：Host 负责签发委托，领域 MCP 负责每次调用重新校验 campaign、requester role、authority、revision 与幂等性；Core 只提供系统无关的身份 解析、持久化与事务保证。
Core 不是 MCP Host、MCP server，也不管理 tools/list。稳定目录、Host 端小型工具投影、
stdio/HTTP 协议适配与每次工具调用授权都属于各领域 MCP/Agent；不要在 Core 中引入连接级
principal 或 campaign session。
sagasmith.content-package v2 是唯一公开交换格式，文件扩展名为
.sagasmith-pack。addon、module、preset、core_rules 共用同一归档骨架：
校验和锁定的 manifest、结构化内容、actor cards、来源索引，以及
blobs/sha256/ 中的原始文档、标准化全文和图片。
完整的 archive、证据、角色图与 kind 语义见
docs/CONTENT_PACKAGES.md。
actor card 使用 sagasmith.actor-card.v3，统一表示 PC、NPC 与怪物。每张卡可引用
一张带媒体类型、许可、署名及来源证据的角色图；图片留在卡和内容包中，不复制到
运行时角色或 Snapshot。导入角色始终产生新的本地 identity，且绝不携带 campaign、
revision、权限、ActorKnowledge、随机流或进度。
Core 校验统一归档并通过公开服务重建来源、角色与模组结构；系统插件继续校验
sheet、edition、规则依赖和具体语义，应用/MCP 负责权限与导入根目录。规则包由
RulePackService 完成 draft、不可变存储和 campaign activation 生命周期。旧 portable、
release manifest 与 .sagasmith-module 不是公开兼容协议。
| 领域 | 主要服务 | 关键保证 |
|---|---|---|
| Campaign | CampaignService, AccessService |
system_id 分区、principal/role 访问边界 |
| Character | CharacterService, StateMutationService |
revisioned sheet、受控状态写入、actor-card 导入/导出 |
| Knowledge | ActorKnowledgeService |
actor 视角隔离、分支有效性 |
| Timeline | SnapshotService, BranchService, ContinuityService |
DAG 祖先链、checkout、连续性上下文 |
| Content | ImportJobService, ModuleService, PdfDocumentConverter |
可恢复导入、来源、结构、统一 content package |
| Rules | RuleService, RulePackService, RuleProfileService, RuleReceiptService |
内容包来源、规则包版本、精确依赖、激活上下文和结算证据 |
| Retrieval | RuleService, VectorStore |
检索可降级，权威状态不交给向量库 |
Python 3.11+：
pip install sagasmith-core系统插件通常会自动安装 Core。按需启用 extras：
pip install "sagasmith-core[documents]" # PDF
pip install "sagasmith-core[documents,ocr]" # 扫描版或乱码 PDF 恢复
pip install "sagasmith-core[vector]" # ChromaDB
pip install "sagasmith-core[embedding]" # sentence-transformers
pip install "sagasmith-core[all]"本地常驻运行时可为每个领域前缀配置持久 embedding cache。例如 D&D 使用：
export DND5E_EMBEDDING_CACHE_DIR="/absolute/private/user-cache/sagasmith/dnd5e"请选择源码 checkout 之外、仅当前用户可读写的 OS 应用缓存目录。BgeEmbedder 会先查进程内
LRU，再查其中的 SQLite cache；cache identity 绑定固定模型 revision、profile、维度、推理
epoch 与原始文本 digest，向量按 float32 保存且带完整性校验。内置 BGE profile 已固定到
Hugging Face commit；所有自定义 profile 也必须提供 40 位 commit SHA 形式的不可变
model_revision，避免 SQL、Chroma 或 cache 在移动 ref 后复用旧向量。损坏记录会被当作
miss 并在下一次推理后替换；锁竞争经过一次有界 cache 尝试后降级为普通推理，默认等待
50 ms。POSIX 上新建 cache 目录和数据库会自动收紧为仅当前用户可访问。
默认硬上限为 50,000 项和 256 MiB 逻辑数据，写入时按最早写入顺序淘汰。可使用
<PREFIX>_EMBEDDING_CACHE_MAX_ENTRIES、<PREFIX>_EMBEDDING_CACHE_MAX_BYTES、
<PREFIX>_EMBEDDING_CACHE_BUSY_TIMEOUT_MS 与 <PREFIX>_EMBEDDING_CACHE_EPOCH 调整，
并通过 embedder.persistent_cache_stats() 查看当前用量。CoC 等运行时使用自己的 prefix，
不得让不同用户或 tenant 共用同一目录。
最小服务构造：
from sagasmith_core import CampaignService, Database, SystemRegistry
db = Database("sqlite:///sagasmith.db")
db.upgrade_schema()
systems = SystemRegistry.discover()
campaigns = CampaignService(db)系统包通过 entry point 注册：
[project.entry-points."sagasmith.systems"]
my_system = "my_package.system:get_system"系统实现提供 profile、角色 schema、模块解析与规则引擎；Core 表保持系统无关。需要新的系统字段时，优先使用 namespaced JSON 或系统包自己的明确扩展表，不向通用表塞入某一规则专属列。
- Snapshot、branch 和 revision 是权威连续性；向量命中不是。
- 客观事实使用稳定
fact_key，在分支内通过 revision head 演进；修订应携带expected_revision_id。角色的主观知识继续使用独立的 ActorKnowledge ledger。 - 事实的 recency 与
updated_at来自所选分支的 revision head；修改旁支不会重排或重标当前分支。直接调用 ActorKnowledge 修订会保留未提供的认知状态、置信度、来源、成因与披露范围；只有显式传值（包括source_event_id=None）才修改对应字段。通过ContinuityCommitService修订时，新提交的场景事件会成为来源，其余未提供字段仍保留。 - 场景收尾优先使用
ContinuityCommitService，在同一事务中写入事件、事实、 角色认知和可选 Snapshot，避免产生半保存状态。 - Snapshot 在语义上是可独立恢复的全量 checkpoint；
recap才是相对父节点的差量摘要。完整性校验同时覆盖 payload、DAG 祖先链以及 fact/event/actor-knowledge bindings。 - checkout 不会静默丢弃工作区：当前分支有未保存变化时，必须先创建 Snapshot。
- 写操作应携带 expected revision 与幂等键，避免 Agent 重试造成重复副作用。
- 玩家读取只允许当前可见分支、场景作用域和角色知识；GM 权限需要显式 principal/role。
- 最终统一 Pack 从不充当存档或权限载体；导入 actor 必须使用新身份，主观知识必须在目标战役中重新获得或合理传递；导入规则 Pack 也不能自动启用。
- 文档解析结果保留来源、页码、质量警告和 parser profile；调用方必须处理缺失的富元数据。
- 持久 embedding cache 只是可重建的性能层，不是权威检索或 campaign 状态；默认不启用， 配置目录后也不保存原始文本，只保存 model/text digest 和校验过的 float32 向量。但 digest 可能被低熵文本字典猜测，embedding 本身也是敏感派生数据；目录必须采用私有权限，不得提交到 Git、备份到公共位置或跨 tenant 共享。
- 这是 Alpha 项目；主线迁移会保留当前已发布 schema 的数据，但不承诺任意旧实验版本或 downgrade 路径。
pip install -e ".[all,dev]"
pytest --cov
ruff check .部署前先停止写入，并在 SQLite WAL 收敛后创建一致性数据库备份；外部数据库使用其原生
一致性备份。应用启动应通过 Database.upgrade_schema()/Alembic 升级到当前 head。
Snapshot schema v8 的完整文档记录没有原地 downgrade；需要数据回滚时，必须把备份、Core、
领域 Domain/MCP 与上游 component lock 恢复为匹配的一组。只回滚 MCP SDK 或只替换数据库
都不是受支持的恢复方式。
测试与 fixture 不应使用生产战役、真实凭据或付费外部服务。文档、OCR、向量与 embedding extras 在 CI/部署中应按实际能力显式安装，不能把缺少可选依赖误报成数据损坏。
更多资料：Architecture · Quickstart · Retrieval
Apache-2.0