app-template/packages/seo-geo/AGENTS.md

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 文本。

命令

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