argentina-price-index

Paid Door — 阿根廷食品与饮料价格指数（Cloudflare 沙盒）

对视频核心机制的精简可运行测试：一次 Agent 请求在边缘变成一笔付费交易。 Cloudflare Worker 从 D1 实时计算价格指数，并通过 x402 风格的 402 → pay → retry → data 循环进行访问控制。支付经过模拟（使用共享密钥 HMAC），因此整个流程无需设置钱包即可运行；改用真正的 x402 只需局部调整。

数据为合成数据。 seed/observations.sql 是生成的占位数据，让演示能在真实抓取程序上线前运行。请勿将这些数字视为阿根廷的真实价格。

内容一览

paid-door-index/
├─ wrangler.jsonc         # Worker + D1 binding + sandbox vars
├─ schema.sql            # price_observations + methodology (+ future index_series cache)
├─ seed/
│  ├─ generate.mjs       # deterministic synthetic data generator (60 SKUs x 30 days)
│  └─ observations.sql   # generated seed (1,800 rows)
├─ src/index.ts          # Worker: routes + live index math + mock x402 gate
├─ agent/test-agent.mjs  # the paying "buyer": request → 402 → pay → retry → data
└─ README.md

端点

端点	层级	返回内容
GET /v1/headline?country=AR&category=food_beverages	免费	最新指数值 + 月度变化率（预览）
GET /v1/index?country=AR&category=food_beverages	付费（$0.02）	完整的每日序列
GET /v1/latest?country=AR&category=food_beverages	付费（$0.02）	最新读数 + 方法说明
POST /mcp	—	MCP JSON-RPC：initialize、tools/list、tools/call

MCP 接口（Agent 实际调用的内容）

Worker 还通过 /mcp 使用 HTTP 上的 MCP，并公开两个工具：

• get_ar_food_headline（免费）——最新值 + 30 天变化率
• get_ar_food_price_index（付费，$0.02 mock-x402）——完整的每日序列；先在不带 _payment 的情况下调用一次以接收挑战，然后使用 arguments._payment = {nonce, resource, amount, signature} 重试

在本地运行完整的 Agent 流程（运行 npm run dev）：

npm run agent:mcp     # initialize → tools/list → free call → paid call (challenge → pay → data)

**生产环境说明：**这里的 /mcp 是 Streamable HTTP 传输的精简 JSON 请求/响应子集（不含 SSE、会话或身份验证）。如需实际部署，请使用官方 MCP SDK 或 Cloudflare 的 agents McpAgent，并将模拟 HMAC 替换为真正的 x402 facilitator。

指数计算方式（methodology_version = v0-simple-avg）：对于有库存的 SKU，index = 100 × mean(price_t / price_base)，基期 = 窗口中的第一天。架构中已预留升级路径：类别内使用几何平均数，类别间使用 Laspeyres 指数。

在本地运行

前置条件：Node 18+ 和 Cloudflare 账户（npx wrangler login）。

cd paid-door-index
npm install

# 1. Create the D1 database, then paste the printed database_id into wrangler.jsonc
npm run db:create

# 2. Load schema + seed into LOCAL D1
npm run schema:local
npm run seed:gen        # (optional) regenerate observations.sql
npm run seed:local

# 3. Start the Worker
npm run dev             # serves http://127.0.0.1:8787

# 4. In a second terminal, run the paying agent
npm run agent

预期的 Agent 输出：先得到免费的预览，然后收到带价格挑战的 402，最后收到包含完整序列的 200 和 PAYMENT-RESPONSE 结算标头——一次请求变成一笔交易。

部署到你的账户

npm run schema:remote
npm run seed:remote
npm run deploy
# then point the agent at the deployed URL:
BASE=https://paid-door-index.<your-subdomain>.workers.dev npm run agent

使用 npx wrangler tail 查看实时日志。

从沙盒走向真实环境（后续工作）

1. **真实数据：**将 seed/generate.mjs 替换为定时运行的 Worker，每天抓取 1–2 家阿根廷在线杂货店的数据，并写入 price_observations。
2. **真实支付：**将 src/index.ts 中的 HMAC 模拟（verifyPayment / challenge）替换为真正的 x402 facilitator（POST /verify、POST /settle），并遵循 Cloudflare 的 Agents x402 文档。
3. **迁移密钥：**使用 npx wrangler secret put MOCK_PAYMENT_SECRET，而不是明文变量。
4. 公开为 MCP，让任何 AI Agent（包括此助手）都能直接调用 get_index。
5. 物化 index_series，在查询量增长后将其作为每晚更新的缓存。

说明 / 注意事项

• 模拟支付只能证明调用方知道共享密钥——它不是链上的密码学结算。它仅用于演示请求/响应格式。
• 沙盒中没有防重放保护（任何有效签名都可以重复使用）。真正的 x402 结算会处理这一问题。
• 合成月度变化率有意加入了较大噪声；单个网点的通胀读数会有波动，这本身就是一个很好的课堂讨论点。