aigou-storefront — 一条命令把你的店接入 AI购开放商务网络

把你的商品目录发布为 aigou/catalog@1 快照，推送到 AI购目录服务（或自托管），所有接入网络的购物 agent 都能发现你的商品。零佣金、零平台抽成，商家保持 merchant-of-record。

快速开始（WooCommerce）

1. 安装 Node.js ≥ 18，然后在你的商店目录：

npm install -g aigou-storefront   # 或直接 npx aigou-storefront

2. 写配置 aigou-storefront.config.json：

{
  "store": { "store_id": "acme", "name": "Acme 旗舰店" },
  "source": {
    "type": "woocommerce",
    "base_url": "https://shop.example.com",
    "consumer_key": "ck_你的key",
    "consumer_secret": "cs_你的secret"
  },
  "publish": {
    "mode": "push",
    "catalog_base_url": "http://127.0.0.1:8000",
    "shop_domain": "shop.example.com"
  }
}

（WooCommerce key 在 后台 → 设置 → 高级 → REST API 创建，只读权限即可。）

3. 先干跑看一眼，再正式注册并推送：

aigou-storefront sync --dry-run
aigou-storefront sync --register --reg-token <目录运营方签发的注册令牌>

注册令牌由目录运营方按店签发（找 AI购 运营索取）；只门控首次注册/注册信息变更，日常快照推送不需要。也可写进 config 的 publish.reg_token 或环境变量 AIGOU_REG_TOKEN。

4. 建议用 cron / 计划任务每天同步一次。改价、上新、下架，下次同步即生效。

无 WooCommerce？用 JSON 源

手工（或用你的进销存导出脚本）维护一份快照文件，字段见目录服务的 GET /catalog/schema：

{
  "store": { "store_id": "acme", "name": "Acme 旗舰店" },
  "source": { "type": "json", "path": "./products.aigou.json" },
  "publish": { "mode": "file", "path": "./public/aigou-catalog.json" }
}

mode: "file" 生成可自托管的 aigou-catalog.json，上传到你网站的任意公开路径后，在目录服务注册并触发拉取：

curl -X POST http://127.0.0.1:8000/stores \
  -H "Content-Type: application/json" \
  --data-binary @register.json
# register.json: {"store_id":"acme","name":"Acme 旗舰店",
#   "shop_domain":"shop.example.com","endpoint_type":"catalog_url",
#   "catalog_url":"https://shop.example.com/aigou-catalog.json"}
curl -X POST http://127.0.0.1:8000/stores/acme/refresh

注意：目录服务只在收到 refresh 调用时拉取（不会自动轮询，可用 cron 定期调用）；且快照内的 store.store_id 必须与注册的 store_id 一致，否则拉取被拒绝。

配置参考

| 字段 | 说明 | |---|---| | store.store_id | 全网唯一店 ID（注册后绑定你的域名） | | store.name / store.currency | 店名（展示用）/ 币种，默认 CNY | | source.type | woocommerce、shopify 或 json | | source.base_url / consumer_key / consumer_secret | WooCommerce REST v3 凭据 | | source.storefront_access_token | Shopify Storefront API 访问令牌（shopify 源） | | source.path | json 源的快照文件路径 | | publish.mode | push（推目录服务）或 file（写文件自托管） | | publish.catalog_base_url / shop_domain | 目录服务地址 / 你的店域名（push 用） | | publish.path | 输出文件路径（file 用） |

开放 MCP 店面端点（让 agent 可代下单）

目录快照只让 agent「搜得到」；要让 agent 真正下单，再跑一个 MCP 端点：

1. WooCommerce 的 REST key 需要读写权限（后台 → 设置 → 高级 → REST API 新建，权限勾 Read/Write；只读 key 会在下单时报 403）。Shopify 店用 Storefront API token（shopify 源）：购物车/结账走 Shopify 收银台，订单在买家支付完成后才进商家后台。
2. 配置里加 mcp 段：

{
  "store": { "store_id": "acme", "name": "Acme 旗舰店" },
  "source": { "type": "woocommerce", "...": "..." },
  "publish": { "mode": "push", "...": "..." },
  "mcp": {
    "port": 8080,
    "token": "换成你生成的长随机串",
    "public_base_url": "https://shop.example.com"
  }
}

3. 启动端点（建议用 systemd / pm2 常驻，反代 /mcp 到该端口）：

aigou-storefront mcp

4. 注册端点信息到目录（下次 sync 一并完成）：

aigou-storefront sync --register --reg-token <目录运营方签发的注册令牌>

之后任何接入 AI购 的 agent 都能通过标准 MCP 工具调用你的店：search_products、get_product、create_cart、checkout。订单以 pending 状态落到你的 WooCommerce 后台，收款与发货由你按平时流程处理——你始终是 merchant-of-record。

安全说明：mcp.token 会随注册提交给目录服务，用于买方服务调用你的端点；请只通过 https 暴露 public_base_url，并定期轮换 token（改配置后重新 sync --register 并重启 mcp）。

信任层（trust-layer ①）

v0.3 起商家拥有自己的去中心化身份（DID，did:key:z…，Ed25519），并可为履约订单签发签名回执。

密钥文件 --key-file

• 默认 <当前目录>/aigou-storefront-key.json，sync 与 mcp 都可用 --key-file <path> 改。
• 首跑自动生成 Ed25519 密钥对并落盘（格式 aigou/storefront-key@1）；文件丢失 = 换了新身份，请像保管密码一样备份它。
• 注意：push 模式下即使 --dry-run 也会创建缺失的密钥文件（干跑要打印你的商家 DID）；file 模式不涉及密钥，不会创建任何文件。

注册自动携带 DID

push 模式 sync --register 的注册体会自动带上你的 did（公钥），目录服务用它核验你后续签发的履约回执——无需任何额外配置。

履约回执工具 get_fulfillment_receipt

MCP 端点新增工具（需已装配密钥文件）：买方 agent 在订单履约后按订单号取得商家 DID 签名的回执（aigou/receipt@1），验签回签后提交到中心声誉账本，沉淀你的店铺声誉。

• WooCommerce 店：直接支持——订单状态为完成履约（completed / shipped / delivered）即签发；订单未履约则返回 { "receipt": null, "reason": "order_status_<status>" }，绝不预签。
• Shopify 店：诚实降级，返回 { "receipt": null, "reason": "unsupported_backend" }，不做任何伪造。

安全说明

• consumer key/secret 只用于读取商品（只读权限即可），且只在你自己的机器与你的商店之间传输；请勿在 http 明文环境使用。
• 工具不会上传任何订单、客户数据；快照只含公开商品信息。

路线图

v0.2：WooCommerce + JSON + Shopify 源 → 快照推送/自托管 + 开放 MCP 店面端点（search/get_product/cart/checkout，可代下单）+ 下单幂等键（idempotency_key，重试绝不重复下单）+ 购物车状态跨重启持久化（mcp 命令默认写 ./aigou-storefront-state.json，--state-file 可改）。 v0.3（本版）：信任层①——商家 DID 身份（--key-file 密钥文件，首跑自动生成）、sync 注册自动携带 DID、履约回执工具 get_fulfillment_receipt（双签回执入中心声誉账本；详见「信任层」一节）。 下一步：微店适配、ACP checkout；信任层后续增量（评价签名入账、声誉哈希链与时间戳锚定）。

品牌资产

assets/ 下提供可复用的品牌物料（GitHub、npm、社交分享卡片均可直接引用）：

• assets/banners/minimal-hex-1500x500.png — README banner（本文顶部）
• assets/banners/minimal-hex-1200x630.png — og-image / 社交分享卡片
• assets/logo.svg / assets/logo.png — logo（矢量 / 512px 透明底）
• assets/banners/src/ — 各物料的 HTML 源文件，可自行改文案后用 Chrome headless 重导出