From c74700291bd52c4d25268120cb9ac0e04a1fc6a7 Mon Sep 17 00:00:00 2001 From: dajiaohuang Date: Sat, 29 Aug 2026 22:25:59 +0800 Subject: [PATCH] docs: overhaul Core runtime guides --- README-en.md | 44 +++++++++++++++++++++++++++++++++++++++++++- README.md | 35 ++++++++++++++++++++++++++++++++++- 2 files changed, 77 insertions(+), 2 deletions(-) diff --git a/README-en.md b/README-en.md index f7b3a70..d4b8dca 100644 --- a/README-en.md +++ b/README-en.md @@ -1,11 +1,24 @@ # SagaSmith Core -[中文](README.md) · [English](README-en.md) · [Website](https://sagasmithai.github.io) · [Platform overview](https://github.com/SagaSmithAI/.github/blob/main/profile/README.md) · [Hosted service](https://github.com/SagaSmithAI/SagaSmith-service) · [Content catalog](https://github.com/SagaSmithAI/SagaSmith-dnd-content-library) +[中文](README.md) · [English](README-en.md) · [Website](https://sagasmithai.github.io) · [Platform overview](https://github.com/SagaSmithAI/.github/blob/main/profile/README.md) · [SagaSmith Web](https://github.com/SagaSmithAI/SagaSmith-Web) · [Content catalog](https://github.com/SagaSmithAI/SagaSmith-dnd-content-library) **The system-neutral runtime for an AI-native TTRPG platform.** `sagasmith-core` gives rules systems, MCP servers, and clients persistent campaigns, actor knowledge, branching timelines, content ingestion, rule packs, and retrieval. It contains no D&D or Call of Cthulhu rules. > World state should be verifiable, timelines should branch, and every actor should know only what they actually know. +## Choose a path + +| Goal | Start here | +|---|---| +| Use Core from a system package | `pip install sagasmith-core`, then see the minimal service construction below | +| Integrate a current rules system | [D&D](https://github.com/SagaSmithAI/sagasmith-dnd) · [CoC](https://github.com/SagaSmithAI/sagasmith-coc) · [Narrative](https://github.com/SagaSmithAI/sagasmith-narrative) | +| Understand data and transaction boundaries | [Architecture](docs/ARCHITECTURE.md) · [Quickstart](docs/QUICKSTART.md) | +| Build or import content packages | [Content Packages](docs/CONTENT_PACKAGES.md) | +| Configure retrieval and caches | [Retrieval](docs/RETRIEVAL.md) | + +Python 3.11+ is required. Most end users should install a system MCP/Local Kit +instead of accessing Core's database directly. + ## What it provides - **Campaigns and characters** — system-neutral records, namespaced sheets, revisions, principals, and roles. @@ -32,6 +45,13 @@ flowchart TB Core does not decide GM style, MCP exposure, or system-specific rules. Skills own operating guidance, system runtimes own rules, MCP servers own the capability/storage boundary, and Core owns consistent data semantics. +SagaSmith Web never reads authoritative D&D, CoC, or Narrative tables directly. +After a domain MCP commits successfully, a rebuildable revisioned projection or +receipt boundary may feed Web read models; failed, rolled-back, and no-op writes +must not fabricate cache invalidation. Core vector, page, and embedding caches are +also rebuildable performance layers, never authorities for revisions, events, +facts, actor knowledge, or snapshots. + ## Current domain implementations | Domain | Current repository | Components versioned together | @@ -55,6 +75,13 @@ requester whose campaign role is evaluated. Neither identity may impersonate the other, and audit receipts retain the original fields. Explicit legacy v1 keeps its single caller/authorization-subject interpretation. +This does not make Core an MCP Host or server. Hosts mint delegation, domain MCPs +revalidate campaign role, authority, revision, and idempotency on every call, and +Core provides system-neutral parsing, persistence, and transactions. Stable tool +catalogs, bounded Host projection, stdio/HTTP adaptation, and tool-call policy +belong above Core; never store a connection-bound principal or campaign session +here. + ## Shareable content formats `sagasmith.content-package` v2 is the only public exchange format and uses the @@ -177,6 +204,21 @@ pytest --cov ruff check . ``` +## Upgrade and rollback + +Before deployment, stop writers and take a consistent backup after the SQLite +WAL settles, or use the external database's native consistent backup. Startup +should run `Database.upgrade_schema()`/Alembic to the current head. Snapshot +schema v8 full-document records have no in-place downgrade. A data rollback +restores the backup, Core, the matching Domain/MCP components, and the upstream +component lock as one compatible set. Rolling back only the MCP SDK or replacing +only the database is not a supported recovery. + +Tests and fixtures must not use production campaigns, real credentials, or paid +external services. Install document, OCR, vector, and embedding extras explicitly +for the capability exercised by CI or deployment; a missing optional dependency +is not data corruption. + Further reading: [Architecture](docs/ARCHITECTURE.md) · [Quickstart](docs/QUICKSTART.md) · [Retrieval](docs/RETRIEVAL.md) ## License diff --git a/README.md b/README.md index 394cc87..802d557 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,24 @@ # SagaSmith Core -[中文](README.md) · [English](README-en.md) · [官网](https://sagasmithai.github.io) · [平台总览](https://github.com/SagaSmithAI/.github/blob/main/profile/README.md) · [托管服务](https://github.com/SagaSmithAI/SagaSmith-service) · [内容目录](https://github.com/SagaSmithAI/SagaSmith-dnd-content-library) +[中文](README.md) · [English](README-en.md) · [官网](https://sagasmithai.github.io) · [平台总览](https://github.com/SagaSmithAI/.github/blob/main/profile/README.md) · [SagaSmith Web](https://github.com/SagaSmithAI/SagaSmith-Web) · [内容目录](https://github.com/SagaSmithAI/SagaSmith-dnd-content-library) **AI 原生 TTRPG 平台的系统无关运行时。** `sagasmith-core` 为规则系统、MCP 服务和 UI 提供持久化战役、角色知识、分支时间线、内容导入、规则包与检索能力；它本身不包含 D&D 或 CoC 规则。 > 世界状态应当可验证，时间线应当可分支，每个角色只应知道自己真正知道的事。 +## 从这里开始 + +| 目标 | 入口 | +|---|---| +| 在系统包中使用 Core | `pip install sagasmith-core`，再看下方最小服务构造 | +| 接入当前规则系统 | [D&D](https://github.com/SagaSmithAI/sagasmith-dnd) · [CoC](https://github.com/SagaSmithAI/sagasmith-coc) · [Narrative](https://github.com/SagaSmithAI/sagasmith-narrative) | +| 理解数据与事务边界 | [Architecture](docs/ARCHITECTURE.md) · [Quickstart](docs/QUICKSTART.md) | +| 创建或导入内容包 | [Content Packages](docs/CONTENT_PACKAGES.md) | +| 配置检索与 cache | [Retrieval](docs/RETRIEVAL.md) | + +需要 Python 3.11+。大多数最终用户应安装对应的系统 MCP/Local Kit，而不是直接操作 +Core 数据库。 + ## 它解决什么 普通聊天记忆无法充当长期战役数据库：它不知道哪条时间线有效，也无法可靠区分 GM、玩家、PC 和 NPC 的视角。SagaSmith Core 把这些问题建模为显式服务： @@ -34,6 +47,11 @@ flowchart TB 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 权威。 + ## 当前领域实现 | 领域 | 当前仓库 | 同仓版本化组件 | @@ -58,6 +76,10 @@ requester。两者不得互相冒充，审计 receipt 会保留原始身份字 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 是唯一公开交换格式，文件扩展名为 @@ -176,6 +198,17 @@ 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](docs/ARCHITECTURE.md) · [Quickstart](docs/QUICKSTART.md) · [Retrieval](docs/RETRIEVAL.md) ## License