SagaSmithAI开始使用Get started
想自己运行 Bot、桌面工具或 MCP 服务，选择 Local Agent Kit。想开发账户、多人房间、Forge 与浏览器产品，进入 SagaSmith Web。两条路径执行同一权威领域契约。Choose the Local Agent Kit to run bots, desktop tools, or MCP services yourself. Choose SagaSmith Web to develop accounts, multiplayer rooms, Forge, and the browser product. Both paths execute the same authoritative domain contract.
适合本地 AI GM、Discord/QQ/Telegram Bot、Workbench，以及需要直接控制数据、模型 provider 和更新节奏的团队。For local AI GMs, Discord/QQ/Telegram bots, Workbenches, and teams that need direct control over data, model providers, and update cadence.
Codex、Claude Code、OpenClaw 和其他 MCP Host 可以通过 auth bridge 连接选定领域 MCP；无凭证模板不包含 token、密钥、角色授权或 campaign authority。Codex, Claude Code, OpenClaw, and other MCP hosts can connect through the auth bridge. Credential-free templates contain no tokens, secrets, role grants, or campaign authority.
适合账户/session、协作房间、托管 worker、Forge、Module Studio 与运营基础设施。当前仓库是 proprietary Active Alpha；公开可见不构成生产服务承诺。For accounts and sessions, collaborative rooms, hosted workers, Forge, Module Studio, and operations infrastructure. The repository is a proprietary Active Alpha; public visibility is not a production-service promise.
进入对应 vertical repository；Domain、MCP、Skills、UI（如有）与创作流程在同一 commit 下版本化。不要从已归档的拆分仓库开始。Start in the matching vertical repository, where Domain, MCP, Skills, UI where present, and authoring flow are versioned at one commit. Do not start from archived split repositories.
Local Agent Kit
--source release 会使用 Agent 仓库内的不可变发行锁检出所选当前组件。锁同时记录经过验证的 MCP 现代/兼容组合；回滚恢复上一份完整锁，不会改用归档仓库。安装器不会导入商业书籍、生成私有 Pack、配置 provider secret 或自动激活内容。--source release uses the Agent repository's immutable release lock to fetch the selected current components. The lock records the validated modern/compatibility MCP combination; rollback restores the previous complete lock and never substitutes an archived repository. The installer does not import commercial books, create private Packs, configure provider secrets, or activate content.
Local Agent Kit 的安装器、发行锁、模板和 doctor 都在当前 SagaSmith-agent 仓库。The Local Agent Kit installer, release lock, templates, and doctor live in the current SagaSmith-agent repository.
git clone https://github.com/SagaSmithAI/SagaSmith-agent.git
cd SagaSmith-agent下面以 D&D-only 为例。可换成 CoC、Narrative 或 multi-system；已有同级源码工作区的开发者可按 Agent 指南选择 workspace source。The example uses D&D-only. Substitute CoC, Narrative, or multi-system; developers with current sibling source checkouts can follow the Agent guide for workspace source.
uv run nanobot sagasmith install --source release --profile dnd-only向导写入 repo-local 配置与 workspace。provider secret 只应通过环境变量或本机私密配置提供，不要提交填充后的配置。The wizard writes repo-local configuration and workspace state. Provide model-provider secrets through environment variables or private local configuration, and never commit filled configuration.
uv run nanobot onboard --wizard --config config/config.json --workspace workspacedoctor 分别报告 MCP/config、领域数据库、Skills、provider 与 transport。provider 未配置是 readiness 警告，不应被误报为安装损坏。Doctor reports MCP/config, domain databases, Skills, provider readiness, and transport separately. A missing provider is a readiness warning, not a broken installation.
uv run nanobot sagasmith doctor --json
uv run nanobot sagasmith start安装 profileInstall profiles
| Profile | 领域Domains | 当前仓库输入Current repository inputs |
|---|---|---|
| dnd-only | D&D 5e | Agent + Core + D&D 5e |
| coc-only | Call of Cthulhu 7e | Agent + Core + Call of Cthulhu 7e |
| narrative-only | Narrative | Agent + Core + Narrative |
| multi-system | D&D + CoC + Narrative | Agent + Core + D&D + CoC + Narrative |
MCP 2026-07-28，同一契约、三种本地 transportMCP 2026-07-28, one contract across three local transports
每种模式都必须执行同一 handlers、schema、错误、revision、idempotency 与 authority 语义。现代请求使用 server/discover，并在每次调用携带版本、能力与身份元数据；连接或 Mcp-Session-Id 不是权限边界。HTTP 仅监听 loopback。Every mode executes the same handlers, schemas, errors, revisions, idempotency, and authority semantics. Modern requests use server/discover and carry version, capability, and identity metadata on every call; neither a connection nor Mcp-Session-Id is an authority boundary. HTTP binds to loopback only.
stdio一个本地客户端独占每个 MCP 进程；不开放网络监听。One local client owns each MCP process; no network listener.
streamable-http多个本机客户端共享常驻领域进程；仅 loopback。Multiple local clients share long-lived domain processes on loopback only.
mixed默认：D&D/CoC 使用 loopback HTTP，Narrative 使用 stdio。Default: D&D and CoC use loopback HTTP; Narrative uses stdio.
SagaSmith Web
SagaSmith Web 独立拥有账户、Web session、配额、邀请、协作、Forge、Module Studio、durable RoomTurnJob 与云端投影；worker 只连接当前 campaign system，使用面向目标 MCP 的专用委托，并向模型投影最多 16 个任务工具。它不透传浏览器 token，也不直接读取或写入领域数据库。SagaSmith Web independently owns accounts, Web sessions, quota, invitations, collaboration, Forge, Module Studio, durable RoomTurnJob state, and cloud projections. A worker connects only the current campaign system, uses an audience-bound delegation, and projects at most 16 task tools to the model. It neither passes browser tokens through nor reads or writes domain databases directly.
SagaSmith Web 源码公开可见，但仓库使用 proprietary license。Local 的 Apache-2.0 组件不依赖 Web。SagaSmith Web source is publicly visible under a proprietary license. Apache-2.0 Local components do not depend on Web.
当前开发路径使用 Docker Compose 与同级当前源码 worktree；生产/release 形态使用仓库的不可变组件锁。不要把真实凭证、私有战役或商业来源材料放进测试数据。The current development path uses Docker Compose with current sibling source worktrees; production and release builds use the repository's immutable component lock. Keep real credentials, private campaigns, and commercial source material out of test data.
Copy-Item .env.example .env
docker compose -f compose.yaml -f compose.workspace.yaml up --build房间 turn 必须以持久状态、lease/heartbeat、幂等键、quota 续租和 base_revision 恢复；MCP 已提交但 Web 尚未发布时重用保存的标准 CallToolResult。text、image、audio、resource 与 embedded resource 由内部 HostMediaEnvelope 转为私有 artifact，不替换 MCP wire contract。RoomTurnJob 也不等同 MCP Task；只有协商能力且长工具返回 claim 后才 poll/cancel。Room turns recover through durable state, leases and heartbeats, one idempotency key, quota renewal, and base_revision. If MCP committed before Web publication, reuse the saved standard CallToolResult. Text, image, audio, resource, and embedded-resource content becomes private artifacts through the internal HostMediaEnvelope without replacing the MCP wire contract. A RoomTurnJob is not an MCP Task; poll and cancel begin only after capability negotiation and a long tool's Task claim.
生产部署只接受 sagasmith.release-lock/v3 中已验证的不可变 Web/Agent/Core/领域 commit 组合。先用锁定版本执行协议与数据 canary，再切换；回滚恢复上一份完整锁及其兼容 schema。不要把归档 split repo、未锁定 main 或 legacy session 状态作为回退输入。Production accepts only the validated immutable Web, Agent, Core, and domain commit set in sagasmith.release-lock/v3. Run protocol and data canaries against the lock before switching; rollback restores the previous complete lock and compatible schema. Never use an archived split repository, an unlocked main branch, or legacy session state as a fallback input.
仍然不确定？Still deciding?
它是最小、可逆且不依赖托管基础设施的入口；需要浏览器协作、Forge 或运营能力时，再评估 SagaSmith Web。It is the smallest reversible entry with no hosted-infrastructure dependency. Evaluate SagaSmith Web when you need browser collaboration, Forge, or operations.