开发者地图Developer map

一份契约，多条清晰边界。One contract. Clear ownership.

SagaSmith 不是一个把所有功能装进同一后端的仓库。Agent、Hosted Web、Core 与三个领域 vertical 各自拥有明确职责，通过同一 authoritative MCP contract 组合。SagaSmith is not a monolith that puts every feature into one backend. Agent, Hosted Web, Core, and three domain verticals own distinct responsibilities and compose through one authoritative MCP contract.

双发行物Two distributions

部署可以不同，领域真相不能分叉。Deployment may differ. Domain truth may not fork.

Local 与 Hosted 可以采用不同 transport、authentication、storage 和 deployment。它们必须保持相同 handlers、tool schemas、capability discovery、错误、权限、revision、idempotency 与规则写入语义。现代 MCP 每次请求都携带版本、能力与身份元数据，不执行 initialize，也不以连接或 Mcp-Session-Id 建立权威。Local and Hosted may use different transport, authentication, storage, and deployment. They must preserve the same handlers, tool schemas, capability discovery, errors, authority, revisions, idempotency, and rule-write semantics. Modern MCP carries version, capability, and identity metadata on every request; it does not initialize or derive authority from a connection or Mcp-Session-Id.

LOCAL AGENT KITHost → Domain MCP → Runtime → CoreHost：SagaSmith Agent、Bot 或通用 MCP AgentHost: SagaSmith Agent, a bot, or a generic MCP agent
Transport：stdio 或仅 loopback 的 Streamable HTTPTransport: stdio or loopback-only Streamable HTTP
同一 request-scoped handlers；legacy initialize 仅是锁定的兼容 adapterThe same request-scoped handlers; legacy initialize is only a pinned compatibility adapter
Storage：SQLite 与本地文件Storage: SQLite and local files
不依赖 Web、PostgreSQL、Redis、对象存储、账户或 ForgeNo dependency on Web, PostgreSQL, Redis, object storage, accounts, or Forge

SAGASMITH WEB

Browser → API/BFF → Agent worker → Domain MCP

Web 拥有账户、session、配额、邀请、协作、Forge 与云端投影Web owns accounts, sessions, quota, invitations, collaboration, Forge, and cloud projections
每个 turn 只连接当前 campaign system，并向模型投影最多 16 个相关工具Each turn connects only the current campaign system and projects at most 16 relevant tools to the model
worker 使用面向目标 MCP audience 的短期专用委托Workers use short-lived delegations issued for the exact target MCP audience
共享 HTTP pool 不携带隐式 principal/session，也不透传浏览器 tokenShared HTTP pools carry no implicit principal or session and never pass browser tokens through
领域服务在每次调用边界重新验证权限与 revision；Web 不直接读取或写入领域数据库Domain services revalidate authority and revision at every call boundary; Web never reads or writes domain databases directly

托管运行契约Hosted operating contract

可恢复的 Host 工作流，不复制领域权威。A recoverable Host workflow without duplicating domain authority.

DURABLE TURN

RoomTurnJob 跨崩溃恢复RoomTurnJob survives crashes

每个房间动作持久化 queued / running / waiting / succeeded / failed / cancelled 状态、lease、heartbeat、重试与结果引用。浏览器、Web、Agent 和 MCP 复用同一业务幂等键；base_revision 冲突返回可恢复结果，LLM turn 期间不持有房间或数据库锁。Every room action persists queued / running / waiting / succeeded / failed / cancelled state, lease, heartbeat, retries, and a result reference. Browser, Web, Agent, and MCP reuse one business idempotency key; base_revision conflicts are recoverable, and no room or database lock is held for the LLM turn.

STANDARD MCP MEDIA

保留 CallToolResultPreserve CallToolResult

Hosted worker 保留标准 MCP text、image、audio、resource 与 embedded-resource 内容。Web 保存原始结果，再通过内部 HostMediaEnvelope 投影为受 audience 约束的私有 artifact/object ID；房间图片与战斗 grid 不需要私有 MCP wire protocol。Hosted workers preserve standard MCP text, image, audio, resource, and embedded-resource content. Web stores the original result, then projects it through an internal HostMediaEnvelope into audience-bound private artifact/object IDs; room images and combat grids need no private MCP wire protocol.

RECEIPT PROJECTION

成功 receipt 驱动可重建投影Successful receipts drive rebuildable projections

Web 不直接读取或写入领域权威数据库。成功 MCP receipt 驱动 durable outbox 与带 authority revision、audience 的云端投影；failed、rolled-back 与 no-op 不失效缓存，工具目录也不会因每次战斗写入全量刷新。Web never reads or writes a domain's authoritative database directly. Successful MCP receipts drive a durable outbox and cloud projections carrying authority revision and audience; failed, rolled-back, and no-op work does not invalidate caches, and combat writes do not refresh the entire tool catalog.

TASK NEGOTIATION

Host job 不等于 MCP TaskA Host job is not an MCP Task

RoomTurnJob 覆盖整个 LLM turn。MCP Tasks 仅在协商 io.modelcontextprotocol/tasks 且真正长耗时工具返回 claim 后进入 authenticated poll、cancel 与恢复；普通工具保持同步。RoomTurnJob spans an entire LLM turn. MCP Tasks switch to authenticated poll, cancel, and recovery only after io.modelcontextprotocol/tasks negotiation and a claim from a genuinely long tool; ordinary tools stay synchronous.

WORKSPACE LIFECYCLE

只清理由 Host 登记的工作区Clean only Host-registered workspaces

稳定 opaque --workspace-id、TTL、LRU、数量与容量上限约束 managed root；启动时恢复崩溃标记，terminal success 清理登记状态。未知、外部、legacy、symlink 或 active 目录保留给 operator 审核。A stable opaque --workspace-id, TTL, LRU, count, and byte limits bound the managed root; startup recovers crash markers and terminal success cleans registered state. Unknown, external, legacy, symlinked, or active directories remain for operator review.

TRACE + METRICS

可追踪，不用高基数标签Traceable without high-cardinality labels

traceparent、tracestate 与 baggage 穿过 Web、Agent 与 MCP。service、MCP phase、projection、durable job、quota 与 outbox 指标保持低基数，不使用 user、campaign、room、run 或 tool args 作为标签。traceparent, tracestate, and baggage cross Web, Agent, and MCP. Service, MCP phase, projection, durable-job, quota, and outbox metrics stay low-cardinality and never label by user, campaign, room, run, or tool arguments.

权威所有权Authority ownership

每一次写入，都能回答“谁负责”。Every write has an accountable owner.

Client / UI输入与服务端授权投影Input and server-authorized projection

Agent / Skills意图、主持、工具选择与提案Intent, facilitation, tool selection, and proposals

Domain MCP权限、phase、revision、幂等与原子结算Authority, phase, revision, idempotency, and atomic settlement

Domain runtime系统规则、随机流与领域状态System rules, random streams, and domain state

SagaSmith Core持久化、事务、知识、分支、内容与检索Persistence, transactions, knowledge, branches, content, and retrieval

Agent ≠ Domain

Agent workspace memory 与主持人格不能替代战役 Snapshot、ActorKnowledge、权限或规则 receipt。Agent workspace memory and facilitation identity cannot replace campaign snapshots, ActorKnowledge, permissions, or rule receipts.

NO DIRECT DB WRITE

Skills ≠ Engine

Skills 描述主持、审核和创作步骤；会改变权威状态的机械结果必须由 runtime/MCP 验证。Skills describe facilitation, review, and authoring procedures; mechanical outcomes that change authoritative state must be validated by runtime and MCP.

PROPOSAL ONLY

Retrieval ≠ Truth

检索返回候选证据；来源、规则锁、分支祖先与持久状态决定什么当前有效。Retrieval returns candidate evidence; sources, rule locks, branch ancestry, and persistent state decide what is currently valid.

SOURCE-BOUND

当前仓库拓扑Current repository topology

这些是唯一当前入口。These are the only current entry points.

原独立 MCP、Skills、UI 与通用 Module Generator 仓库仅保留为 archived read-only history：不接收新 Issue、不参与发布，也不是 compatibility fallback。Former standalone MCP, Skills, UI, and generic Module Generator repositories are archived read-only history. They accept no new issues, supply no releases, and provide no compatibility fallback.

agentSagaSmith-agent

Agent host、Channels、MCP consumer、Local Agent Kit 与 Hosted worker 基础Agent host, channels, MCP consumer, Local Agent Kit, and the shared Hosted worker base

CURRENT

webSagaSmith-Web

浏览器/PWA、API/BFF、托管控制面、协作、Forge、Module Studio 与运维Browser/PWA, API/BFF, hosted control plane, collaboration, Forge, Module Studio, and operations

CURRENT

coreSagasmith-core

系统无关持久化、文档导入、检索、分支、知识与事务语义System-neutral persistence, document ingestion, retrieval, branches, knowledge, and transactions

CURRENT

dndSagasmith-dnd

D&D 5e Domain、权威 MCP、Skills、Workbench 与模组生成D&D 5e Domain, authoritative MCP, Skills, Workbench, and module authoring

CURRENT

cocSagasmith-coc

CoC 7e Domain、权威 MCP、Skills、Workbench 与模组生成CoC 7e Domain, authoritative MCP, Skills, Workbench, and module authoring

CURRENT

narrativesagasmith-narrative

系统无关 Narrative Domain、权威 MCP、Skills 与项目生成System-neutral Narrative Domain, authoritative MCP, Skills, and project authoring

CURRENT

librarySagaSmith-dnd-content-library

逐包许可约束的 Pack、来源/资产 blob 与 checksum 索引Rights-aware Packs, source/asset blobs, and checksum index

CURRENT

profile.github

组织 Profile、贡献指南、行为准则与公共安全入口Organization profile, contribution guide, code of conduct, and public security entry point

CURRENT

公共契约Public contract

现代协议、权威语义与发布锁必须跨发行形态一致。Modern protocol, authority semantics, and release locks stay consistent across distributions.

DISCOVERY + PROJECTION

稳定目录，最多 16 个任务工具Stable catalogs, at most 16 task tools

现代 Host 使用 server/discover 与确定排序、按 authorization 隔离且可私有缓存的 tools/list。SagaSmith Host 只连接当前 system，并按 system、phase、role 与任务把最多 16 个排序且去重的 facade 工具交给模型；这是 Host 命中率策略，不是 MCP 协议上限。MCP 仍在每次调用重新校验权限与 revision，目录不会被同一连接的副作用改写。Modern Hosts use server/discover and a deterministically ordered tools/list that is authorization-isolated and privately cacheable. A SagaSmith Host connects only the current system and projects at most 16 sorted, unique facade tools for the system, phase, role, and task. This is a Host selection policy, not an MCP protocol limit. MCP still revalidates authority and revision on every call, and connection side effects never mutate the catalog.

ERROR + REVISION

失败可解释，写入可并发验证Failures explain themselves; writes remain concurrency-safe

客户端收到一致的错误结构与 revision 语义；旧 revision 不能通过 UI、Agent 文本或 transport 差异绕过。Clients receive consistent error structures and revision semantics; stale revisions cannot bypass checks through UI, Agent text, or transport differences.

IDEMPOTENCY + AUTHORITY

重试不会复制结算，身份不能由请求自选Retries do not duplicate settlement; requests do not choose identity

幂等键与 caller/workload、requester/resource owner、acting character、audience、room turn、base revision、expiry 均由可信 Host 结构化注入并由 MCP 每次重新验证。模型不能选择权威身份，HTTP 也不接受 token passthrough。Idempotency keys and caller/workload, requester/resource owner, acting character, audience, room turn, base revision, and expiry are injected structurally by the trusted Host and revalidated by MCP on every call. Models cannot choose authoritative identity, and HTTP does not accept token passthrough.

HANDLE + CROSS-CALL STATE

显式状态，不依赖隐藏 sessionExplicit state, never a hidden session

跨调用的 exposure、import、render 等状态使用服务端签发的 opaque handle，或显式 campaign/revision 参数。Handle 绑定 owner 与 TTL，过期返回可恢复错误；它只是名称，不是 bearer capability。Cross-call exposure, import, render, and similar state uses a server-issued opaque handle or explicit campaign and revision parameters. Handles bind an owner and TTL, return a recoverable expiry error, and are names rather than bearer capabilities.

COMPONENT LOCK + ROLLBACK

整组升级，整组回滚Upgrade and roll back as one set

Local release profile 与 Hosted production 固定经过验证的 Agent、Core、三个领域和 Web commit 组合。切换前执行 modern/legacy、stdio/HTTP 与数据 canary；回滚恢复上一份完整锁及兼容 schema，不把 archived repo、未锁定 main 或旧 session 状态当作输入。Local release profiles and Hosted production pin a validated Agent, Core, domain, and Web commit set. Before switching, run modern/legacy, stdio/HTTP, and data canaries; rollback restores the previous complete lock and compatible schema, never an archived repository, unlocked main branch, or old session state.

PACK CONTRACT

统一内容包，独立权利与激活Unified content packages, separate rights and activation

sagasmith.content-package v2 是当前公开交换格式；每个 Pack 的许可、来源、导入权限与 campaign activation 都独立判断。sagasmith.content-package v2 is the current public exchange format; each Pack's license, provenance, import authority, and campaign activation are evaluated separately.

贡献入口Contribution entry

从拥有行为的仓库开始。Start in the repository that owns the behavior.

跨仓库或公共 contract 变更请先开 Issue。提交报告时附 commit/release、环境、复现命令与脱敏错误；漏洞、凭证、私有战役和受限制来源请走私密安全入口。Open an issue before cross-repository or public-contract changes. Include commit or release, environment, reproduction commands, and redacted errors. Route vulnerabilities, credentials, private campaigns, and restricted source material through private security reporting.

贡献指南Contributing guide ↗安全入口Security