# AGENTS.md — @app/seo-geo

## 职责

**SEO / GEO 纯函数库**：生成 meta 标签、sitemap、robots.txt、JSON-LD、llms.txt。不依赖 Astro/React/DB，调用方自行注入到页面。

## 依赖库（重构后）

| 库 | 用途 |
|----|------|
| `zod` | 入参 schema + 派生 TS 类型（`types.ts`） |
| `schema-dts` | JSON-LD 节点的 schema.org 强类型 |
| `escape-html` | head 标签属性转义 |
| `sitemap` | sitemap.xml 流式序列化 |
| `serialize-javascript` | JSON-LD `<script>` 安全序列化（XSS） |
| `mdast-util-to-markdown` | llms.txt / FAQ Markdown 生成 |

## 结构

```
src/
  types.ts    # Zod schema + SiteSeoConfig / PageSeoInput / SitemapEntry / LlmsSiteConfig ...
  url.ts      # absoluteUrl / normalizeSiteUrl / normalizePath ...
  meta.ts     # buildTitle / buildHeadTags / renderHeadTagsHtml / buildRobotsContent
  sitemap.ts  # buildSitemapXml / pathsToEntries
  robots.ts   # buildRobotsTxt / buildDefaultRobotsInput / paginationRobots / DRAFT_ROBOTS
  jsonld.ts   # webSite/webPage/faq/howTo/... + toJsonLdScript
  llms.ts     # buildLlmsTxt / buildLlmsFullTxt / faqToJsonLdAndMarkdown
  index.ts    # 全量导出（类型、Zod schema、函数）
```

## 核心类型

- `SiteSeoConfig`：站点级一次配置（`siteUrl`、`name`、`description`、`llms`…）。
- `PageSeoInput`：页面级（title、path、robots、jsonLd、pagination…）。
- `HeadTag`：结构化 meta/link，由 `renderHeadTagsHtml` 转 HTML（已转义）。
- `JsonLdNode`：`Thing | JsonLdObject | Record<string, unknown>`，builder 返回 `schema-dts` 的 Leaf 类型。

## 修改指南

- 保持**纯函数**：无 IO、无全局状态、不读 `import.meta.env`。站点 URL 由调用方传入。
- 加新标签/JSON-LD 类型：扩展 `types.ts` Zod schema + 对应 build 函数，并从 `index.ts` 导出。
- `toJsonLdScript` 走 `serialize-javascript`（已转义 `</script>` 与 U+2028/2029）——**序列化 JSON-LD 一律走它**，不要手拼 `<script>`。
- 生成 HTML/XML 必须走库转义（`escape-html` / `sitemap` 包自带序列化）。
- JSON-LD 构造用 `schema-dts` Leaf 类型（`WebSiteLeaf` 等），自定义节点放 `page.jsonLd`。
- GEO：`llms.txt` 约定参考 llmstxt.org；FAQ 同步产出 JSON-LD 与 Markdown 用 `faqToJsonLdAndMarkdown`。

## 消费方

主要在 `@app/web`：`lib/seo.ts` 维护 `siteSeo`，`AppLayout.astro` 调 `buildHeadTags` + `buildDefaultJsonLd`，`pages/*.ts` 产出 sitemap/robots/llms 文本。

## 命令

```bash
yarn workspace @app/seo-geo typecheck
yarn workspace @app/seo-geo lint
yarn workspace @app/seo-geo build
```