Initial commit of akmon project

2026-01-20 08:04:15 +08:00
commit 77a2bab985
1309 changed files with 343305 additions and 0 deletions
--- a/doc_seo/README.md
+++ b/doc_seo/README.md
@@ -0,0 +1,185 @@
+# SPA SEO 与 AI 爬取可见性总纲（执行手册）
+
+面向现状：保持单页应用（SPA）架构，优先通过“主动提交 + 结构化数据 + 渲染策略 + 内链与性能”提升传统搜索与 AI 爬虫的可见性；仅在收益不足时，分阶段引入 SSR/SSG/ISR。
+
+## 1. 目标与原则
+
+- 兼顾传统搜索（Google/Bing/百度等）与新型 AI 爬虫（GPTBot/ClaudeBot/PerplexityBot 等）。
+- 新内容与更新“分钟级被发现”：IndexNow/百度主动推送 + 完整 sitemap。
+- 重要着陆页无需改架构即可可抓取：动态渲染/预渲染为爬虫提供 HTML 快照。
+- 结构化数据覆盖主要业务类型，获取富结果与高质量摘要。
+- 数据合规：robots.txt/ai.txt 明确抓取与使用边界。
+
+## 2. 两周内落地路线（优先级）
+
+第 1 周（发现能力与元数据）：
+- 接入站长平台：Google Search Console、Bing Webmaster、百度搜索资源平台。
+- 建立 sitemap 体系：主索引 + 分区 sitemap（栏目/详情/增量），含 `lastmod`、`hreflang`。
+- 接入 IndexNow 与百度“主动推送”API（发布/更新/删除即时推送）。
+- 为所有可索引路由补齐 `<title>`、`meta description`、`canonical`、OG/Twitter 卡片。
+- 添加 JSON-LD：Organization、WebSite+SearchAction、BreadcrumbList；内容页覆盖 Article/Product/FAQ。
+
+第 2 周（可抓取与体验）：
+- 路由与状态：存在的路由返回 200，不存在返回 404；history 模式避免哈希路由。
+- 动态渲染（过渡方案）：对爬虫 UA 提供 HTML 快照（Rendertron/Prerender/自建 Headless 中间层）。先覆盖前 20 个高价值入口。
+- 内链与面包屑：专题页 → 栏目 → 详情双向链路，清理孤页。
+- Core Web Vitals：首屏渲染/LCP、CLS、图片懒加载与尺寸、关键 CSS/JS 精简与分割。
+- 监控：GSC/Bing/百度的抓取/索引/体验报告 + 服务器日志（爬虫命中、耗时、状态码）。
+
+4–6 周评估后：
+- 若收录与流量提升有限，针对高价值路由切换 SSR/SSG/ISR（分批，成本可控）。
+
+## 3. 主动报告/推送策略
+
+- Sitemap：
+  - `sitemap_index.xml` 指向多份分区 sitemap（示例：`sitemap-pages.xml`、`sitemap-articles-0001.xml`…）。
+  - 详情页增量 sitemap（滚动窗口，仅近 7–14 天更新），全部挂在 index 上。
+  - 每条 URL 含 `lastmod`，多语言站点提供 `xhtml:link rel="alternate" hreflang`。
+- IndexNow（推荐）：发布/更新/删除 URL 即刻通知；Bing/百度/雅虎等共享。
+- 百度“主动推送”API：中文搜索重要渠道，显著提升时效性。
+- 说明：Google 通用内容不支持 Indexing API（仅 JobPosting/LiveStream）。
+
+## 4. SPA 可抓取与渲染策略
+
+- 服务端为每个可索引路由返回：
+  - 正确状态码（200/404/410 等）。
+  - 唯一 `<title>` 与 `meta description`、`canonical`、Open Graph/Twitter 卡片。
+- 动态渲染（UA 识别，仅爬虫）：
+  - 可选组件：Rendertron、Prerender.io、无头 Chrome 自建渲染服务。
+  - 缓存策略：热门路由 1–6 小时；刷新策略基于更新事件或 `lastmod`。
+  - 机器人 UA 白名单（示例）：`Googlebot`、`bingbot`、`Baiduspider`、`GPTBot`、`ClaudeBot`、`PerplexityBot`、`Applebot`、`Bytespider`。
+
+## 5. 结构化数据（JSON-LD 模板）
+
+嵌入到可索引页面 `<script type="application/ld+json">` 中：
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Organization",
+  "name": "Your Company",
+  "url": "https://example.com",
+  "logo": "https://example.com/logo.png",
+  "sameAs": ["https://twitter.com/your", "https://github.com/your"]
+}
+```
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "WebSite",
+  "url": "https://example.com",
+  "potentialAction": {
+    "@type": "SearchAction",
+    "target": "https://example.com/search?q={query}",
+    "query-input": "required name=query"
+  }
+}
+```
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "BreadcrumbList",
+  "itemListElement": [
+    {"@type": "ListItem", "position": 1, "name": "首页", "item": "https://example.com"},
+    {"@type": "ListItem", "position": 2, "name": "栏目", "item": "https://example.com/cat"},
+    {"@type": "ListItem", "position": 3, "name": "文章标题", "item": "https://example.com/a/123"}
+  ]
+}
+```
+
+内容页根据类型选用：`Article`（新闻/博客）、`Product`（商品）、`FAQPage`/`HowTo`（知识/指南）。
+
+## 6. AI 爬虫与抓取政策
+
+- robots.txt：明确允许/限制、抓取节奏（部分爬虫支持 `Crawl-delay`），指向 sitemap。
+- ai.txt（可选，逐步被采用）：说明数据使用许可范围与联系人信息。
+- 提供机器可读入口：sitemap + RSS/Atom/JSON Feed；知识性页面补 FAQ/HowTo JSON-LD，提升被摘要/引用概率。
+
+模板见：`doc_seo/templates/robots.txt`、`doc_seo/templates/ai.txt`。
+
+## 7. 站内链接与内容策略
+
+- 架构化内链：专题页 → 栏目 → 详情，相关内容组件；避免孤立页面。
+- 使用面包屑并输出到 JSON-LD。
+- Canonical 统一去重策略（分页/筛选/多入口）。
+- 多语言/区域站点：`hreflang` 覆盖。
+
+## 8. 性能与体验（Core Web Vitals）
+
+- LCP：关键资源预加载、服务端压缩、图片尺寸与格式（AVIF/WebP）。
+- CLS：预留尺寸、避免布局抖动、延迟加载非关键组件。
+- JS 体积：分包与按需加载，第三方脚本治理。
+
+## 9. 监控与校验
+
+- 平台：GSC/Bing/百度抓取统计、索引覆盖、富结果、页面体验。
+- 校验：Rich Results Test、Schema.org 校验器、PageSpeed Insights。
+- 日志：爬虫 UA 命中、状态码分布、渲染耗时、阻塞资源。
+
+## 10. SSR/SSG/ISR 回退与分批迁移
+
+- 触发条件：两轮（4–6 周）评估后收录/流量/展示低于阈值。
+- 范围优先：商业着陆页/栏目首页/高价值详情页。
+- 路径：保持 SPA，大路由增量改 SSR；低频内容用 SSG/ISR；未改部分继续用动态渲染。
+
+## 11. KPI 与验收标准
+
+- 发现/抓取：sitemap 提交成功率 99%+；IndexNow/百度推送成功率 95%+；爬虫 200 响应率 98%+。
+- 收录：重要路由 80%+ 在 7–14 天内被索引；长尾 60%+ 在 30 天内被索引。
+- 展示/点击：GSC 展示量/点击量环比提升；富结果覆盖增长。
+- 体验：核心页面 CWV 达标（Good）。
+
+## 12. 实施清单（可勾选）
+
+- [ ] 建立 sitemap 体系：index + 分区 + 增量，含 lastmod、hreflang。
+- [ ] 接入 IndexNow 与百度主动推送，绑定内容发布/更新事件。
+- [ ] 按路由注入 `<title>`、`meta description`、`canonical`、OG/Twitter。
+- [ ] JSON-LD：Organization、WebSite+SearchAction、BreadcrumbList；内容页 Article/Product/FAQ。
+- [ ] robots.txt/ai.txt 上线（模板在 `doc_seo/templates/`）。
+- [ ] 动态渲染中间层部署并仅对爬虫启用；覆盖前 20 个高价值路由。
+- [ ] 内链/面包屑/相关内容完善，清理孤页。
+- [ ] CWV 优化与监控面板上线。
+- [ ] 两周与六周评估，必要时切换高价值页到 SSR/SSG/ISR。
+
+---
+
+### 附录 A：sitemap 片段示例
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml">
+  <url>
+    <loc>https://example.com/a/123</loc>
+    <lastmod>2025-08-30</lastmod>
+    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/en/a/123"/>
+    <xhtml:link rel="alternate" hreflang="zh-CN" href="https://example.com/zh/a/123"/>
+  </url>
+  <!-- ... -->
+  </urlset>
+```
+
+### 附录 B：IndexNow 请求示例（HTTP）
+
+```
+POST https://api.indexnow.org/indexnow
+Content-Type: application/json
+
+{
+  "host": "example.com",
+  "key": "<your_key>",
+  "keyLocation": "https://example.com/<your_key>.txt",
+  "urlList": [
+    "https://example.com/a/123",
+    "https://example.com/a/456"
+  ]
+}
+```
+
+### 附录 C：更多 JSON-LD 类型参考
+
+- Article: https://schema.org/Article
+- Product: https://schema.org/Product
+- FAQPage: https://schema.org/FAQPage
+- HowTo: https://schema.org/HowTo