Stateset iCommerce

StateSet iCommerce Engine

商务领域的 SQLite。 完整的商务运行时——订单、库存、结账、支付、退货、订阅、仓库运营、财务——在进程内通过一个数据库文件运行。无需托管控制平面、服务账户或速率限制。

为实现自主执行，它还提供 AI Agent 在花钱之前所需的能力：委托身份、默认拒绝的权限、精确预算、幂等命令，以及可通过密码学验证的收据。

---

从这里开始

搭建一个可运行的店面：

npm create stateset-app@latest my-store

然后运行：

cd my-store
cp .env.example .env.local
npm run seed          # 10 products, stock, a demo catalog in ./store.db
npm run dev           # http://localhost:3000

这是一个背后运行着真正商务引擎的 Next.js 店面——生成器和种子数据步骤均由 Storefront Golden Path CI 任务端到端覆盖。

为 AI Agent 提供商务沙盒

适用于 Claude Desktop、Cursor、Windsurf 或任何 MCP 客户端：

{
  "mcpServers": {
    "stateset-commerce": {
      "command": "npx",
      "args": ["-y", "-p", "@stateset/cli", "stateset-mcp", "--db", "./store.db", "--profile", "core"]
    }
  }
}

默认情况下，写入操作仅供预览。 core 配置文件（默认值）仅开放通过冒烟测试的核心层级（196 个工具）；finance、operations、agents 和 all 可开放更多工具，--domains a2a,x402 则可添加单独的领域。每个工具的层级（core、extended、experimental）都列在 cli/docs/TOOLS.md 中。只通过由运营人员管理的文件赋予 Agent 应用权限，切勿通过工具参数赋予：

{
  "args": [
    "-y", "-p", "@stateset/cli", "stateset-mcp", "--db", "./store.db", "--apply",
    "--kernel-policy", "./kernel-policy.json",
    "--kernel-principal", "./kernel-principal.json",
    "--kernel-store-id", "store:production"
  ]
}

对于托管部署，stateset-mcp-http 通过 MCP Streamable HTTP（协议修订版 2026-07-28）提供相同的工具，且其设计本身就是无状态的——没有会话 ID，每个请求都会创建一个新的服务，因此可以跨副本扩展：

npx -y -p @stateset/cli stateset-mcp-http --db ./store.db --port 8090

添加 --host 0.0.0.0 以对外开放，添加 --read-only 以在传输层边界禁用写入，或添加 --strict-protocol 以拒绝使用 2026-07-28 之前协议版本的客户端。

---

安装

渠道	命令
crates.io	cargo add stateset-sdk --features full
npm	npm install @stateset/[email protected]
PyPI	pip install stateset-embedded==1.40.0
CLI + MCP 服务	npm install -g @stateset/[email protected]

Ruby 和 WASM 绑定已发布软件包，但未持续更新：RubyGems 上的 stateset_embedded 版本为 0.1.9，npm 上的 @stateset/embedded-wasm 版本为 0.7.22，均远落后于 1.40.0。PHP、Java、Kotlin、Swift、.NET 和 Go 均没有已发布的软件包——请从源代码构建，并参阅 docs/src/api/，了解各绑定的 API 和安装示例。

使用

import { Commerce } from '@stateset/embedded';

const commerce = new Commerce('./store.db');
const customer = await commerce.customers.create({
  email: '[email protected]',
  firstName: 'Ada',
  lastName: 'Lovelace',
});

use stateset_sdk::prelude::*;

let commerce = Commerce::new("store.db")?;
let customer = commerce.customers().create(CreateCustomer {
    email: "[email protected]".into(),
    first_name: "Ada".into(),
    last_name: "Lovelace".into(),
    ..Default::default()
})?;

金额从头到尾均为精确的十进制值。每次变更都可审计。

Rust 快速入门 → · CLI 快速入门 → · 开始使用（所有语言）→

提供 REST API

stateset-http 是一个可嵌入层，由 Rust 应用启动。它默认绑定到 127.0.0.1:3000，并在 /api/v1/openapi.json 提供 OpenAPI 3.1 规范， 在 /api/v1/docs 提供交互式参考文档。默认启用身份验证：服务器会生成令牌， 可在调用 serve() 前通过 bearer_auth_token() 读取；日志只显示经过脱敏的预览。 绑定到非回环地址时，必须提供由运营方管理的 bearer 令牌、 授权和速率限制（或明确受信任的网关）。请参阅 Rust 快速入门的第 4 步。

---

为什么选择 iCommerce

大多数商务 API 回答的是“模型可以调用哪个端点？”StateSet 回答的是 更难的问题：“这个参与方如何安全地提交资源、从故障中恢复，并证明发生了什么？”

• 状态，而非聊天记录。 订单、库存、余额、审批和工作流能够经受进程重启， 并通过受约束的状态机演进。
• 权限，而非模型置信度。 Agent 提出意图；由运营方管理、默认拒绝的策略决定 是否可以执行。
• 事务，而非对工具调用的乐观假设。 领域状态、预算、事件和幂等性记录要么 一同原子提交，要么一同回滚。
• 凭证，而非无法验证的叙述。 重要操作会返回一份密封记录，其中包含参与方、 主体、意图、策略决策、观察到的结果、审计锚点和结算证据。
• 以精简的公共词汇覆盖复杂的底层机制。 Agent 使用 quote、 buy、sell、pay、fulfill、return_order、refund 和 subscribe 进行推理，同时引擎保留完整的领域 API 和生成的 MCP 目录。
• 默认嵌入式。 SQLite 是零基础设施方案；需要多个工作进程共享后端时， 可使用 PostgreSQL。

由内核执行的商务操作

内核是模型提出操作与软件获准执行操作之间的边界：

objective → typed intent → authenticated agent → delegated authority
          → policy + budget → atomic domain command → economic receipt

原语	保证内容
EconomicAgent	明确指定参与方、委派主体、角色、租户/商店范围、凭证、能力和公钥。
EconomicAuthority	将精确的自主执行、需要审批和拒绝范围编译为默认拒绝的内核策略。
EconomicIntent	八种稳定的商务动词承载精确承诺和幂等性，且独立于任何模型框架。
持久化预算	SQLite 和 PostgreSQL 会随经济变更原子扣减范围限定的资金预算。预览和重放不会重复扣款。
EconomicReceipt	参与方、意图、决策、结果、审计锚点和结算证据共用一个规范摘要，受信任方可共同签署。

身份和策略是受信任的运行时输入，绝不接受模型编写的工具调用中的内容。 货币限额使用十进制字符串；非法币资产使用独立的资产标识符；库存命令会将授权数量 与执行器观察到的数量绑定。

详情：内核执行 · 信任基础（安全模型及其 明确列出的缺口） · 内核路线图

---

Agent 框架

如果你的 Agent 运行时位于应用进程内部，并且需要 JSON Schema 工具而不是 stdio MCP，请使用嵌入式工具包：

入口点	适用对象
@stateset/embedded/openai	OpenAI 工具调用 / Agents SDK
@stateset/embedded/vercel-ai	Vercel AI SDK
@stateset/embedded/langchain	LangChain / LangGraph JS
@stateset/embedded/generic	任意运行时（纯 { name, description, schema, execute } 描述符）
stateset_embedded.openai / .langchain / .crewai / .autogen	Python 对应实现

使用 pip install "stateset-embedded[agents]==1.40.0" 一步安装 Python 框架扩展。

该工具包还提供支付感知助手函数（getPayableToolCatalog()、executePaidTool()、discoverRemotePaymentService()）以及合约/重放助手函数（getRuntimeContract()、simulatePlan()、executePlan()、replayMutation()）。启用写入操作前，请先调用 simulateMutation() 或 executePlan({ dryRun: true })，然后仅对应该修改商务状态的 Agent 设置 allowApply。

实用示例：嵌入式 Agent 工具包 · AI Agent

Agent 间商务

Agent 间直接支付、报价与协商、支持条件释放的托管、分账、订阅、发现与信誉，以及签名事件流都是一等功能。参见 智能商务协议、 A2A 协议概览 和 x402。

确定性多 Agent 市场演示将一个买家、三家商户和一个支付 Agent 放在同一个由 Ed25519 签名、全序排列的消息板上，获胜的授标会跨越两个独立的内核边界：

(cd bindings/node && npm run build)
node examples/sequencer-marketplace/demo.mjs --self-test --kernel

---

架构

分层 Rust 内核，包含两个外部产品界面：语言绑定和基于 Node 的运维运行时。

stateset-primitives | stateset-crypto | stateset-pricing | stateset-observability
stateset-policy | stateset-authz | stateset-a2a | stateset-jobs
stateset-migrations | stateset-macros
        ->
stateset-core | stateset-sync
        ->
stateset-db
        ->
stateset-embedded
        ->
stateset-http | stateset-sdk | bindings/*
        ->
admin | cli

请按以下顺序阅读：stateset-core、stateset-db、stateset-embedded，然后是 stateset-sync/stateset-policy/stateset-authz/stateset-pricing，接着是 stateset-http，最后是 bindings/node 和 admin/ 或 cli/。

完整导览：架构 · 依赖方向 · 工作区清单（生成）

---

开发

nvm use                      # .nvmrc / .node-version (20.20.0)
rustup show active-toolchain # pinned by rust-toolchain.toml (1.90.0)

npm run check                # developer gate across the core workspace surfaces
npm run check:release        # release preflight; run before cutting a tag

各界面的开发循环：

cargo test -p stateset-core -p stateset-db -p stateset-embedded
npm --prefix cli test
npm --prefix admin test
npm --prefix bindings/node run check

权威的远程门禁是 master 上的 CI。CI 还会在 Rust 1.85 上验证工作区 MSRV，并使用相同的固定版本 Node 20.20.0 运行绑定和管理界面。

参与贡献：CONTRIBUTING.md · 发布：RELEASING.md · 安全：SECURITY.md

---

文档

• 本书 — 概念、所有商务领域、A2A、支付、安全、策略、适配器、运维和 API 参考。 使用 mdbook serve docs 在本地构建。
• 工具目录 — MCP/CLI 工具界面的权威生成列表（目前涵盖 87 个领域中的 923 个工具）。
• 各绑定的 API 参考 — Rust、Node、Python、Go、 Java、Kotlin、Swift、.NET、Ruby、PHP、WASM。
• 示例 — 可运行的端到端程序。
• docs.rs 上的 Rust API 文档。
• CHANGELOG.md — 发布历史。
• llms.txt — 面向 Agent 的机器可读索引；AGENTS.md 是 Agent 在此代码仓库中工作的简要指南。

---

许可证

采用 MIT 或 Apache-2.0 双重许可，由你选择。