---
name: site-geo-optimizer
description: Use when 给 kael-site 做 GEO（AI 搜索可见性）优化. 覆盖新文章 geoAnswer+FAQ 写作规范、存量批量注入、五语翻译携带与 QA、站点级实体 GEO、上线验证全流程.
---

# kael-site GEO 优化全栈

面向 Perplexity / ChatGPT / AI Overviews / Google AI Mode 的引用优化。目标：让 AI 引擎能直接引用站点的「一句话答案」和 FAQ，并把作者钉成跨平台单一实体。

三层结构：**内容数据层**（frontmatter 字段）→ **模板渲染层**（已上线，勿重建）→ **验证层**；外加**站点级实体 GEO**。

## 一、文章级 GEO（geoAnswer + FAQ，核心）

### 流程 A：新文章（2026-09-19 起标准流程，零额外 API 调用）

1. **zh mdx 定稿时手写进 frontmatter**（成稿阶段顺手产出，别等翻译后再补）：
   - `geoAnswer`：40-80 字定义式一句话答案。口径与正文严格一致——估算数字带「据媒体报道」类 hedge、实体名/数字与正文完全相同，AI 引擎引用的是这句。
   - `faq`：3 条问答。`q` 用自然问句（就是用户在 AI 引擎会问的原话），`a` 用完整句作答，可带正文锚点链接。
2. **整文件翻译一次带走**：geoAnswer/faq 随 frontmatter 被译走，`column`/`tags` 等枚举值保持英文原值不译。
3. 落盘后跑 QA（见第三节）。

### 流程 B：存量/补漏（老文章批量补）

```bash
python3 <skill目录>/scripts/geo-batch.py            # 全量扫，幂等跳过已注入
python3 <skill目录>/scripts/geo-batch.py zh/xxx.mdx # 只处理指定文件（相对 src/content/blog/）
```

8 线程并行，glm-4-flash 主力、解析失败自动降级 glm-4.6。全站 334 篇实测约 15 分钟。

### 注入格式（block scalar，勿手写裸引号）

追加在 frontmatter 末尾，天然免疫冒号/引号/中文标点，不动文件其余字节：

```yaml
geoAnswer: >-
  一句话定义式答案
faq:
  - q: >-
      问题
    a: >-
      回答
```

schema（`src/content.config.ts` blog collection）：

```ts
geoAnswer: z.string().optional(),
faq: z.array(z.object({ q: z.string(), a: z.string() })).optional(),
```

## 二、渲染层（2026-09-11 上线 commit 3bd9b04，勿重复建）

`src/layouts/BaseLayout.astro` 三个挂载点：

1. **答案卡片**（`<main>` 内、slot 之前）：`article.geoAnswer` 存在时渲染「AI 速览 · 一句话答案」卡片（sky/violet 蓝紫体系）；五语言标签在 `geoLabels` 常量（zh/en/ja/de/fr）。
2. **FAQ 折叠区**（slot 之后）：`<details>/<summary>` 原生折叠，无 JS。
3. **FAQPage JSON-LD**（`<head>`）：`article.faq` 存在时注入。

5 个语言文章页（`src/pages/{,zh,ja,de,fr}/blog/[...slug].astro`）已传 `geoAnswer: post.data.geoAnswer, faq: post.data.faq`——**新增语言页或改 article prop 结构时别丢这两个字段**。

## 三、翻译携带 QA（每篇译稿落盘后，顺序执行）

1. `python3 <astro-blog-sync skill>/scripts/fix-fm-quotes.py <文件>`——GLM 给 frontmatter 值套单引号且内嵌单引号，js-yaml 会静默拼出多余空格；跑完 pyyaml 回验 title/faq/geoAnswer。
2. `python3 <astro-blog-sync skill>/scripts/qa-normalize.py <slug>...`——补 `---` 围栏、pyyaml 回验、column 枚举漂移自动校正回 dialogue/teardown/hot。
3. `python3 <astro-blog-sync skill>/scripts/check-fences.py <slug>`——围栏数与 zh 基准对比，防翻译丢开围栏。
4. `python3 <astro-blog-sync skill>/scripts/check-structure.py <slug>`——H2 数 vs zh + 尾句收尾启发式 + 长度下限 60%，防「plausible-length 截断」（译文长度够但中段被切断缺节）。

参数都是 slug 不是文件路径（传路径会拼进 BLOG 前缀报 MISSING）。

### 语言补丁（每批译稿必查）

- **fr**：全文 `\'` → `'`（GLM 法语转义残留）
- **en**：title 类 `Can''t` 双撇号修回单撇号
- **ja**：frontmatter 禁 `slug:` / `heroImage:` 行（存在即静默跳过不产 dist，sed 删行）

## 四、站点级实体 GEO（2026-09-16 上线）

区别于文章级，把 Kael Zhang/永亮 钉成跨平台单一实体：全站每页注入 Person JSON-LD（`@id: https://kaelzhang.com/#person`，sameAs 挂 X/YouTube/GitHub/Substack/WhatsApp，knowsAbout 挂领域词）。机制细节见 [references/entity-geo.md](references/entity-geo.md)。

## 五、上线验证

1. 全量核验：`grep -rl '^faq:' src/content/blog --include='*.mdx' | wc -l` 应等于总 mdx 数
2. `npm run build` → push → Vercel 约 90 秒 → 线上 `curl <文章页> | grep -E "FAQPage|AI 速览|Quick Answer"` 应命中（en 站无前缀 `https://kaelzhang.com/blog/<slug>/`，其余语言带 `/zh/` `/ja/` `/de/` `/fr/` 前缀）
3. 也可用 Rich Results Test 验 FAQPage 结构化数据

## 坑清单（全部实测踩过）

| 症状 | 处置 |
|---|---|
| js-yaml safeParseFrontmatter 报错 | title/description 里有未转义英文双引号，换中文引号或单引号包裹 |
| frontmatter 值莫名多个空格 | GLM 单引号嵌套单引号，跑 fix-fm-quotes.py |
| tags 含 `l'IA` 类撇号项炸 YAML | 该项用双引号包裹 |
| GLM 429 "Weekly/Monthly Limit Exhausted" | coding plan 端点（api.z.ai）周限额，换官方端点 `https://open.bigmodel.cn/api/paas/v4`（同 key） |
| glm-4.6 并发 429 | 重试改串行 |
| glm-4-flash 输出 JSON 引号未转义 | 脚本已内建指令约束 + glm-4.6 兜底 |
| 单篇顽固 400 | 手动简化 prompt 调一次再 inject |
| Astro 模板表达式不支持内联 `as` 强转 | 多语言映射放 frontmatter 常量 |
| check-structure 尾句 FAIL | 先对读 zh/en 尾段——列表结尾/括号结尾/单引号句尾属正常（09-21 已修启发式） |
| ja 文章不产 dist 无报错 | frontmatter 有 `slug:`/`heroImage:` 行，sed 删之 |
