ce

LLM 文档请求头：所有向 https://llm-docs.commercengine.io 发送的请求必须包含 Accept: text/markdown 请求头（或在 URL 路径末尾添加 .md）。如果没有此请求头，响应将返回 HTML，而非可解析的 Markdown。

Commerce Engine 技能路由器

这些技能适用于 B2C 店面。B2B 店面使用相同的 SDK 模式，并额外支持感知客户组的定价和请求头。

当前 SDK 心智模型

所有框架都安装 @commercengine/storefront——一个统一的软件包，按框架提供子路径导出：

• SPA（@commercengine/storefront）：createStorefront(...) → storefront.public() / storefront.session()
• Next.js（@commercengine/storefront/nextjs）：createNextjsStorefront(...) → storefront.publicStorefront() / storefront.clientStorefront() / await storefront.serverStorefront()
• TanStack Start（@commercengine/storefront/tanstack-start）：createTanStackStartStorefront(...) → storefront.publicStorefront() / storefront.clientStorefront()，并通过服务端入口使用 serverStorefront()

核心原则：公开读取使用公开访问器（基于 API 密钥，可安全用于构建阶段）。实时会话流程（身份验证、购物车、订单）使用会话/客户端/服务端访问器。

按任务分类

设置 SDK -> ce-setup

• 检测框架并安装 SDK
• 选择会话存储
• 环境变量和单一配置设置

身份验证与登录 -> ce-auth

• 匿名会话初始化
• OTP 登录、密码登录、密码注册、密码重置
• 账户/个人资料流程

商品与目录 -> ce-catalog

• 商品、类别、变体、搜索
• 评论和推荐

购物车与结账 -> ce-cart-checkout

• 托管式结账（推荐）
• 自定义结账（高级）
• 购物车 CRUD、优惠券、忠诚度积分、付款

订单与退货 -> ce-orders

• 创建订单、订单历史、配送、付款
• 取消订单和退货

Webhook 与事件 -> ce-webhooks

• 事件处理、签名验证、异步处理

Next.js / TanStack Start / Astro / SvelteKit 模式 -> ce-ssr-patterns

• publicStorefront() / clientStorefront() / serverStorefront()
• 初始化、Server Actions/函数、预渲染、令牌管理
• Next.js、TanStack Start、Astro 和 SvelteKit 的具体参考

SEO 与结构化数据 -> ce-seo

• Head 元数据、JSON-LD（Product/ProductGroup 及 variesBy）、规范 URL
• robots.txt、站点地图、llms.txt，以及供 AI 爬虫使用的 Markdown 镜像
• 根据部署模式选择服务器挂载或预构建

AI Agent 工具（WebMCP） -> ce-ai

• 通过 document.modelContext 提供目录、购物车、导航和会话工具
• 能力门控、购物车语义，以及 Agent 边界所在的位置

自定义 SSR 绑定 -> ce-ssr

• 对于没有官方封装的框架（Nuxt 等），使用 @commercengine/ssr-utils
• ServerTokenStorage 和 CookieAdapter
• 公开构建时读取与实时请求会话

店面页面

CE 店面的标准页面及各页面所需的技能／方法：

页面	示例路由	技能	关键 SDK 方法
首页	/	catalog	listProducts、listCategories、recommendations
商品列表	/products、/categories/[slug]	catalog	searchProducts、listProducts
商品详情	/products/[slug]	catalog	getProductDetail、listProductVariants、listProductReviews
购物车	Hosted Checkout 抽屉或 /cart	cart-checkout	useCheckout().openCart() 或 sdk.cart.*
结账	Hosted Checkout 抽屉或 /checkout	cart-checkout	useCheckout().openCheckout() 或自定义结账流程
登录	/login	auth	loginWithEmail、loginWithPhone、verifyOtp、loginWithPassword
账户	/account	auth	getUserDetails、updateUserDetails、changePassword
订单	/account/orders	orders	listOrders
订单详情	/account/orders/[id]	orders	getOrderDetails、listOrderShipments、listOrderPayments
SEO 资源	/robots.txt、/sitemap.xml、/llms.txt	seo	createCommerceSeo、挂载处理器或预构建
Markdown 镜像	/product/[slug].md	seo	productMarkdown、在标准 URL 上进行内容协商

转换现有项目

1. 安装 SDK - 按照 ce-setup 操作。安装 @commercengine/storefront。
2. 先替换公开目录数据读取 - 将列表／详情／分类页面改为使用 publicStorefront() / public()。
3. 添加会话感知流程 - 身份验证、购物车、结账、账户和订单应使用 clientStorefront() / serverStorefront() / session()。
4. 采用 Hosted Checkout 或自定义结账 - 按照 ce-cart-checkout 操作。
5. 根据需要添加框架特定的 SSR 行为 - 使用 ce-ssr-patterns（Next.js / TanStack Start / Astro / SvelteKit），或 ce-ssr（适用于 Nuxt 等的自定义绑定）。

一次替换一个数据源。尽可能保留现有 UI 组件，先替换数据层。

决策树

User Request
    │
    ├─ "Set up SDK" / "Add Commerce Engine"          → ce-setup
    ├─ "Login" / "Auth" / "OTP"                      → ce-auth
    ├─ "Products" / "Categories" / "Search"          → ce-catalog
    ├─ "Cart" / "Checkout" / "Payments"              → ce-cart-checkout
    ├─ "Orders" / "Returns" / "Shipments"            → ce-orders
    ├─ "Webhooks" / "Events" / "Sync"                → ce-webhooks
    ├─ "Next.js" / "Server Actions"                  → ce-ssr-patterns (references/nextjs.md)
    ├─ "TanStack Start" / "Server functions"         → ce-ssr-patterns (references/tanstack-start.md)
    ├─ "Astro" / "Astro SSR"                         → ce-ssr-patterns (references/astro.md)
    ├─ "SvelteKit" / "Svelte" / "Load functions"     → ce-ssr-patterns (references/sveltekit.md)
    ├─ "SSR" / "Cookies" / "Custom binding"          → ce-ssr
    ├─ "SEO" / "Sitemap" / "JSON-LD" / "llms.txt"    → ce-seo
    └─ "WebMCP" / "Agent tools" / "AI shopping"      → ce-ai

快速导航

• /ce-setup
• /ce-auth
• /ce-catalog
• /ce-cart-checkout
• /ce-orders
• /ce-webhooks
• /ce-ssr-patterns
• /ce-ssr
• /ce-seo
• /ce-ai