# 页面第一方证据：让 AI 看到真实渲染后的页面


# 页面第一方证据：让 AI 看到真实渲染后的页面

## 这篇帮你解决什么

你是不是也遇到过：后台显示"已优化"，但 ChatGPT / Gemini 的回答里还是没你的商品？
原因通常是：**AI 看到的页面，和你以为的页面不是同一份**。

"页面第一方证据"就是让我们的系统**真的打开你的页面**，把 AI 会读到的东西（JSON-LD、FAQ、raw-md）抓回来，再在服务端重新算一遍，最后告诉你：

- AI 到底读到了什么；
- 哪些地方读错了 / 读不到；
- 下一步改哪里最值。

## 三步看到第一份证据

1. **安装主题扩展**：在 Shopify 后台启用 GEO-Sentry 的 App Embed（只需一次）。
2. **打开体检页**：进入「AI 就绪度体检」，选一个商品页，点「采集证据」。
3. **看结果**：等 10–30 秒，会出现「证据」卡片：状态、读到的 JSON-LD、FAQ 锚点、raw-md 长度。

> 如果显示"未测量"，不是失败，而是我们**不猜**：没抓到就如实说没抓到。

## 你需要知道的 3 个词

- **JSON-LD**：给 AI 看的"商品名片"。
- **FAQ 锚点**：问题和答案的对应关系，AI 引用时要用。
- **raw-md**：页面的纯文本版本，AI 读起来更省 token。

## 常见问题

**Q：为什么显示"未测量"？**
A：页面被密码保护、模板未部署 raw-md、或抓取超时。先看「证据详情」里的原因，再按提示处理。

**Q：会不会影响我店铺速度？**
A：扩展只做采集，不阻塞页面；采集失败也不影响店铺正常访问。

**想深入原理/排障？** 看高手版：[[page-evidence.expert]]


---


# 页面第一方证据（高手版）：原理、边界与排障

## 第一章：原理与边界

### 1.1 为什么是"第一方"证据

AI 爬虫不执行 JS，第三方探测也常被 WAF/CDN 干扰，所以不能靠"猜"或"截图"判断 AI 看到了什么。我们的做法：

1. 主题 App Embed 在**真实浏览器**里执行，读取渲染后的 JSON-LD / FAQ 锚点 / raw-md；
2. 通过 Shopify **App Proxy** 回传（HMAC 签名：`shop` + `path_prefix` + `timestamp` + `signature`）；
3. Worker 验签后**服务端重算**：不信任浏览器上报的 `passed/verdict`，只作原始证据；
4. 落库 `page_evidence`（`trust_level=APP_PROXY_HMAC`），带 hash 与时间戳。

### 1.2 模板感知

不同页面类型校验规则不同：

| 模板 | 必需 Schema 类型 |
|---|---|
| product | `Product` + `Offer` |
| page/collection/article | 页面类型 Schema（如 `FAQPage`、`CollectionPage`、`Article`、`Organization`） |

非商品页不再误报 `JSONLD_PRODUCT_REQUIRED`；raw-md 未部署时如实 `RAWMD_FETCH_UNAVAILABLE`，不伪造 PASS。

### 1.3 边界（必须知道）

- 证据只代表**采集时刻**的页面，不代表历史；
- 被 WAF/密码页挡住时是"未测量"，不是"通过"；
- raw-md 由主题模板决定，主题换版可能失效；
- 第一方证据不能替代平台官方数据（GSC/Shopify Analytics）。

## 第二章：排障与进阶

### 2.1 常见失败码

| 码 | 含义 | 处理 |
|---|---|---|
| `APP_PROXY_SIGNATURE_INVALID` | 验签失败 | 检查 App Proxy secret / 时间偏移（±5 分钟） |
| `RAWMD_FETCH_UNAVAILABLE` | raw-md 模板未部署/返回 HTML | 上传 `templates/*.raw-md.liquid`，确认 `Accept: text/html` |
| `JSONLD_PRODUCT_REQUIRED` | 商品页缺 Product/Offer | 补 JSON-LD 或检查主题是否去掉了 |
| `TENANT_UNRESOLVED` | 域名未绑租户 | 在租户里补 `primary_domain` |

### 2.2 API 与自动化

- 采集入口：`POST /api/v1/app-proxy/page-evidence`（HMAC，仅浏览器/签名请求）
- 查询：后台「证据」页或 `GET /api/v1/...`（按租户鉴权）
- 证据字段：`verdict / reasons / jsonld / faq_anchors / raw_md_json / hash / collected_at`

### 2.3 最佳实践

- 每次主题/商品大改后重新采集；
- 把证据时间戳写进客户报告，避免"上周的结论"；
- 对同一 URL 做 2–3 次采集取稳定结果（AI 读取有波动）。

**回新手版：** [[page-evidence.novice]]