Genarrative/.codex/skills/genarrative-spacetimedb/SKILL.md

name, description

name	description
genarrative-spacetimedb	Genarrative 的 SpacetimeDB 项目适配规范。用于涉及 SpacetimeDB 架构、Rust module、schema、migration、reducer、procedure、view、绑定生成、CLI、MCP、发布、调试或运行时核验的任务。

Genarrative SpacetimeDB 项目指导

本 skill 只保存 Genarrative 的项目约束和操作边界；SpacetimeDB 的通用 API、语言 SDK 和 CLI 手册由已安装的官方插件提供。项目规则覆盖插件示例中的默认值或与本仓库冲突的建议。

官方插件依赖

开始 SpacetimeDB 任务时，按任务范围读取官方插件 skill：

• spacetimedb:concepts：核心语义、表、reducer、procedure、view、订阅和身份。
• spacetimedb:rust-server：Rust module、表属性、访问器、迁移兼容性和 SDK API。
• spacetimedb:cli：初始化、构建、发布、生成绑定、SQL、调用、日志和 server 管理。
• spacetimedb:typescript-client：前端生成绑定、订阅和 TypeScript 客户端 SDK；其它语言客户端按需读取插件对应 skill。
• spacetimedb:mcp：通过已连接的 MCP 操作运行中的数据库；没有 MCP 工具时使用 CLI 等价命令。

如果当前环境尚未安装插件，使用：

codex plugin marketplace add clockworklabs/SpacetimeDB --sparse .agents --sparse codex-plugin
codex plugin add spacetimedb\@spacetimedb-plugins

插件不可用时，以当前源码、docs/、生成绑定和仓库脚本为准，不凭记忆发明 SpacetimeDB API。

架构边界

Genarrative 的唯一有效后端路线是：

server-rs + Axum + SpacetimeDB

• module-*：领域模型、命令、应用规则、领域事件和领域错误；不得直接依赖 Axum、SpacetimeDB table/reducer/procedure、spacetime-client、外部平台或文件系统。
• spacetime-module：SpacetimeDB 表、reducer、procedure、view、migration、事务 adapter 和 row mapper。
• spacetime-client：后端访问 SpacetimeDB 的 typed facade；其它后端 crate 不直接创建第二套访问路径。
• api-server：HTTP、SSE、BFF 和外部副作用编排。
• platform-*：OSS、LLM、认证、语音等外部平台能力。
• shared-contracts / packages/shared：前后端 DTO、公开契约和无业务真相的共享 TypeScript 代码。
• 前端只负责表现、交互、临时 UI 状态和后端结果渲染，不绕过 BFF/投影直接读取私有表或推导正式业务状态。

SpacetimeDB 是数据和事务层，不替代 api-server BFF、spacetime-client facade 或公开 read model。插件提供的“SpacetimeDB 可替代传统服务端”通用描述不能改变本项目边界。

语义与安全不变量

• Reducer 是原子事务写路径，不向调用者返回业务数据；读取通过订阅、read model、view 或 BFF。
• Reducer 必须确定性执行：不得访问文件系统、网络、系统时钟或外部随机源；使用 ctx.timestamp、ctx.rng() / ctx.random() 等 SpacetimeDB 能力。
• 授权使用上下文中的 ctx.sender()（或当前语言对应 API），不信任调用参数传入的身份。
• Auto-increment ID 不是排序依据；需要顺序时使用时间戳或显式序列字段。
• Private table 是后端事实；用户可见状态通过 BFF、投影或明确的 public table/view 暴露。公共表仍只能由 reducer/procedure 写入。
• Procedure 在 2.8 已稳定，可使用显式事务和 ctx.http；Genarrative 默认仍把外部 provider 协议放在 platform-*，把编排放在 api-server，除非当前架构明确要求 module procedure。
• Event table 必须显式订阅，按插入事件消费；不要依赖其持久化行或 OnUpdate。需要更新回调时使用持久表或带主键的 procedural view。
• Standalone MCP 是 operator/developer 集成面，不是 BFF、facade 或公开 read model 的替代品。MCP/SQL/CLI 的写入都必须有明确授权；日常 smoke 优先只读。

Schema 与迁移

修改现有 SpacetimeDB persistent table 时：

1. 新字段只能追加到 Rust 表结构体末尾，并设置明确的 #[default(...)]。

2. 删除、改名、重排、改类型或破坏性约束变更前，必须先询问用户并确认迁移计划。

3. 同步更新 server-rs/crates/spacetime-module/src/migration.rs、后端架构文档中的表目录、生成绑定和相关契约/测试。

4. 运行：

   npm run spacetime:generate
   npm run check:spacetime-schema
   

Event table 的较宽松自动迁移规则不适用于 persistent table，不能借此绕过上述门禁。以当前源码和 docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md 为 schema 真相。

CLI、目标 server 与本地开发

• 优先使用仓库 wrapper：npm run dev:spacetime、npm run dev:api-server、npm run spacetime:generate。
• 直接使用 CLI 时始终显式传 --server 或 --server-url；不要依赖默认云端目标或个人 CLI 默认 server。
• 不新增 maincloud / MAINCLOUD 命令、环境变量、脚本或文档；历史残留只按历史处理。
• 人工命令、本地联调、排障步骤和文档示例禁止使用 spacetime --root-dir；本地数据隔离使用项目脚本或 --data-dir。
• spacetime publish 的 --delete-data=always 只在明确授权的破坏性操作中使用；schema 冲突优先按项目脚本和受控迁移流程处理。
• 项目 SpacetimeDB crate、SDK、CLI/standalone 和生成 bindings 按 2.8.3 对齐；官方发行资产、Rust crates 和容器镜像使用 v2.8.3 版本标签，仓库额外固定 CLI commit 8e410d2842147bd8e5a32a9589cc00c19f7478e2。升级时核对 Cargo 精确 pin、实际 CLI 和运行中服务二进制，不把本地 CLI 重装当作仓库升级。

本地开发默认由项目启动器管理端口；实际监听地址以 .app/dev-stack.json 和启动日志为准，不能从文档默认端口推断当前目标。发布后确认 api-server 使用的是同一 database、server 和 token。

MCP 与运行时核验

如果当前会话暴露 SpacetimeDB MCP 工具，读取运行中的数据库优先使用 typed MCP：先 list_databases / get_schema，再做只读 SQL 或 ping；调用 reducer 或 SQL 写入前确认目标、身份和授权。没有 MCP 工具时使用显式目标的 CLI。2.8 standalone 的 MCP HTTP endpoint 是 POST /v1/database/{name_or_identity}/mcp，提供 ping、get_schema、sql、call；升级 smoke 在隔离数据库中只做 initialize、tools/list、ping、get_schema，除非写入明确属于任务范围。

排查“服务健康但业务不可用”时按顺序核对：

1. SpacetimeDB standalone 是否运行（本地优先 npm run dev:spacetime，主机侧核对 systemd）。
2. module 是否发布到 api-server 实际使用的同一个 server/database。
3. 生成绑定是否来自当前 module。
4. api-server 的 database、server URL 和 token 是否一致。
5. reducer/procedure 是否真正被调用；区分超时、权限、schema 不存在和业务错误。
6. /healthz / /readyz 通过但业务仍失败时，继续检查 API 日志和公开路由，不把健康检查当作业务成功证明。

主机升级需核对运行中进程而非只看 PATH：

type -a spacetime
spacetime --version
pid="$(systemctl show spacetimedb.service -p MainPID --value)"
readlink -f "/proc/${pid}/exe"
"/proc/${pid}/exe" --version
curl -fsS http://127.0.0.1:3101/v1/ping

修改后的最小验证

按范围执行定向测试/类型检查，并至少运行：

npm run check:encoding
git diff --check

涉及 schema 时追加 npm run spacetime:generate 和 npm run check:spacetime-schema；涉及 API 时按当前后端文档启动 npm run dev:api-server 并检查 /healthz。无法运行的验证要在交付说明中标记为未验证并说明原因。

参考入口

• docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
• docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
• server-rs/README.md
• scripts/check-spacetime-schema-guard.mjs
• scripts/check-server-rs-ddd-boundaries.mjs