Pre-alpha 文档

在本地验证 StateKnot。

这是一篇贡献者教程：安装项目锁定的工具链，并复现仓库的全部可执行质量门禁。

环境要求

Git。
rustup；仓库锁定 Rust 1.88.0、minimal profile、rustfmt 与 Clippy。
快速 Workspace 门禁不要求 PostgreSQL；Provider 集成测试必须连接 PostgreSQL。

运行类型化合约示例

下一篇教程会构造真实 Schema-pinned Agent 合约与两个 Provider Adapter，不执行外部 I/O，也不需要 Credential。Workspace 门禁通过后，继续阅读构建强类型 Agent 合约。

克隆并执行完整本地门禁

在干净的 Checkout 中执行以下命令。rustup 会自动读取 rust-toolchain.toml。

Shell · 仓库验证

git clone https://github.com/StateKnot/StateKnot.git
cd StateKnot
cargo fmt --all --check
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
cargo test --workspace --all-targets --all-features --locked
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --all-features --no-deps --locked

正确理解测试结果

本地门禁全部通过可以证明：

锁定的编译器能够编译所有 Workspace Target 与 Feature；
Core 合约、Canonical Wire、Property Test 与单元测试通过；
公开 Rust 文档没有 Warning。

它不会验证真实 PostgreSQL Server、真实 Model Provider 账号、MCP、A2A 或 Live Durable Agent Loop。CI 会分别在 PostgreSQL 16 与 17 上执行数据库支持的 Runtime 与 Store Provider 测试；Model Adapter Transport Test 使用真实本地 TCP Server。

执行 PostgreSQL 集成测试

请使用一次性数据库。测试角色必须能够创建和删除临时数据库，因为启动失败与迁移失败本身就是合约的一部分。

Shell · 仅限一次性 PostgreSQL

STATEKNOT_TEST_DATABASE_URL=postgres://USER:PASSWORD@HOST:PORT/DATABASE \
STATEKNOT_REQUIRE_POSTGRES_TESTS=1 \
cargo test -p stateknot-store-postgres --test postgres --locked -- --test-threads=1

不要把该命令指向生产或共享数据库。生产形态的连接与迁移边界请继续阅读 PostgreSQL Provider 指南。