59 lines
2.6 KiB
Markdown
59 lines
2.6 KiB
Markdown
# 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
|
||
```
|