AI 原生 TTRPG 平台 · An AI-native TTRPG platform
Agent 负责理解与主持，规则引擎负责确定性结算，领域 MCP 负责权威状态。
Agents interpret and host; engines settle deterministic rules; domain MCPs own authoritative state.

开始使用 · 官网 · 架构 · Local Agent Kit · SagaSmith Web · 全部仓库

当前阶段：Active Alpha。 适合本地开发、集成验证与实团测试；公开源码、参考战役通过或仓库可见，都不等于生产服务承诺或内容再分发授权。

Current stage: Active Alpha. Ready for local development, integration validation, and real-table testing—not a production-service or content-licensing promise.

flowchart LR
    subgraph Local[Local Agent Kit]
      LC[Bot · SagaSmith Agent · Generic Agent]
      LT[stdio · localhost HTTP]
      LD[(SQLite · local files)]
      LC --> LT
    end

    subgraph Hosted[SagaSmith Web]
      B[Browser · PWA]
      API[API/BFF · collaboration · Forge]
      W[Principal-scoped Agent worker]
      DB[(PostgreSQL · Redis · object storage)]
      B --> API --> W
      API --> DB
    end

    LT --> MCP[Authoritative Domain MCP contract]
    W --> MCP
    MCP --> R[D&D · CoC · Narrative runtime]
    R --> C[Sagasmith Core]
    C -. local persistence .-> LD

本地与 Hosted 只允许在 transport、authentication、storage、deployment 上不同。两条路径必须保持相同的 MCP handlers、tool schemas、错误、权限、revision、idempotency 与规则写入语义。

Local and hosted deployments may differ in transport, authentication, storage, and deployment only. MCP handlers, tool schemas, errors, authority, revisions, idempotency, and rule-write semantics stay identical.

现代链路不再依赖 initialize、Mcp-Session-Id 或连接内隐藏状态。每个请求携带协议版本、客户端能力与面向目标 MCP 的短期委托；跨调用状态使用服务器签发、绑定 owner 与 TTL 的显式 handle，且每次使用都会重新授权。handle 只是状态名称，不是权限凭证。

同一授权范围内的 tools/list 保持确定排序并通过 ttlMs / cacheScope 安全缓存。Agent Host 再按 system × phase × role × task 只向当前模型回合投影少量 facade 与相关工具，默认硬上限为 16 项，避免把完整目录塞入上下文；16 是 SagaSmith 的模型命中率策略，不是 MCP 协议限制。领域 MCP 仍对每次调用独立校验角色、阶段、revision 与具体 tool ID。迁移期保留的 handshake-era 路径仅用于明确兼容，并通过独立的 stdio / HTTP / Hosted contract matrix 验证。

MCP 2026-07-28: stable catalogs, task-scoped projection. The modern path does not depend on initialize, Mcp-Session-Id, or hidden connection state. Every request carries its protocol version, client capabilities, and a short-lived delegation for the target MCP. Cross-call state uses explicit server-issued handles bound to an owner and TTL; a handle names state and never grants authority by itself. Within one authorization scope, tools/list is deterministically ordered and safely cacheable through ttlMs / cacheScope. The Agent host then projects only a small system × phase × role × task facade subset into each model turn, with a default hard cap of 16. That cap is a SagaSmith model-accuracy policy, not an MCP protocol limit. The domain MCP independently validates role, phase, revision, and the concrete tool ID on every call. Retained handshake-era behavior is compatibility-only and has a separate stdio / HTTP / Hosted contract matrix.

• Agent ≠ 领域数据库：Agent 管理模型、身份、会话与渠道，不直接拥有规则或战役账本。
• Skills ≠ 引擎：Skills 描述主持与创作流程；可结算状态变化必须经过 MCP / runtime。
• 检索 ≠ 真相：检索寻找候选证据；持久状态、分支祖先、规则锁与来源决定有效事实。
• 客户端 ≠ 权威：浏览器和 Bot 只接收服务端按 principal、actor、campaign 与 phase 过滤的投影。
• 内容包 ≠ 存档：Pack 不携带权限、ActorKnowledge、进度、随机流、分支或 Snapshot。
• Web job ≠ MCP Task：RoomTurnJob 负责队列、lease、heartbeat、重试、取消与恢复；MCP Task 只用于单个经过能力协商的真正长耗时工具。
• Web cache ≠ 领域数据库：Web 只消费 MCP 成功提交后的 revisioned receipt/outbox projection；failed、rolled-back 与 no-op 写入不触发伪失效。

默认安装需要 Python 3.11+、uv 与 Node.js 22.12+（含 npm）；纯后端安装可显式添加 --skip-ui。

git clone https://github.com/SagaSmithAI/SagaSmith-agent.git
cd SagaSmith-agent
uv run nanobot sagasmith install --source release --profile dnd-only
uv run nanobot onboard --wizard --config config/config.json --workspace workspace
uv run nanobot sagasmith doctor --json
uv run nanobot sagasmith start

--source release 会按 Agent 的发行锁克隆并固定所选组件；可将 dnd-only 换成 coc-only、narrative-only 或 multi-system。安装器不导入商业书籍、不自动激活 Pack，也不会替用户配置 provider secret。已有 sibling 源码工作区的开发者可按 Agent 文档改用 workspace source。完整步骤与 transport 选择见 开始使用页面。

原独立 MCP、Skills、UI 与通用 Module Generator 仓库是 archived read-only history：不接收新 Issue，不参与发布，也不是 compatibility fallback。

长回归现会从当前 Agent 与领域依赖重建托管栈，以签名身份并发运行 D&D 和 CoC 参考战役，并保存逐战役机器可读证据。

Current runtime completes parallel D&D and CoC reference regressions — The long regression now rebuilds the hosted stack from the current Agent and domain dependencies, runs D&D and CoC reference campaigns concurrently with signed identity, and preserves machine-readable evidence per campaign.

三条领域链路现在分别在一个仓库内共同版本化 Domain、MCP、Skills、UI（如有）与创作流程；旧拆分仓库已归档为只读历史。

D&D, CoC, and Narrative complete vertical repository convergence — Each domain path now versions Domain, MCP, Skills, UI where present, and authoring workflows in one repository; the former split repositories are archived read-only history.

SagaSmith Web、D&D/CoC 多系统房间与当前 46 个 Content Pack 的校验和目录现已公开可见，同时继续保留明确的状态与内容权利边界。

SagaSmith Web and the current content catalog enter public development — SagaSmith Web, hosted D&D/CoC rooms, and the checksum catalog for 46 current Content Packs are now publicly visible with explicit state and content-rights boundaries.

• 先从拥有行为的仓库开始；跨仓库或公共契约变更请先开 Issue。
• 报告问题时附带仓库、commit/release、操作系统、Python/Node 版本、命令与脱敏错误。
• 漏洞、私有战役数据、凭证或受限制来源内容不要放进公开 Issue；按相关仓库的 SECURITY.md 使用可用的私密渠道。
• 多数 SagaSmith 原创 runtime、Skills、UI 与网站代码使用 Apache-2.0；SagaSmith-Web 以其仓库内许可证为准；每个 Content Pack 仍需单独核对许可与来源授权。

Build worlds that remember.
Get started · Contributing · Security