# cubepi.ai SEO 审计报告

> 日期:2026-06-05 · 站点:Docusaurus 3.10.1(en + zh-Hans 双语)
> 方法:阅读 `website/` 源码 + 本地 `pnpm build` 后检查真实产物(HTML `<head>`、sitemap、robots.txt)
> 结论文中所有判断均以 build 产物为准,非仅凭配置推断。

---

## 0. 总评

**基础 SEO 8/10,已超过多数同类开源项目文档站。** 头部元数据、双语 hreflang、
canonical、版本去重、sitemap、结构化数据、分析埋点都已就位。剩余增量集中在
**首页 H1、样板页清理、sitemap lastmod、结构化数据丰富度,以及对比落地页内容**。

---

## 1. 已验证「做对了」的部分(无需改动)

| 项 | 验证结果 |
|----|----------|
| `url` / `baseUrl` / `organizationName` / `projectName` | 正确 |
| `onBrokenLinks` / `onBrokenAnchors` / `onBrokenMarkdownLinks` | 均为 `throw`,防死链 |
| canonical | 每页 `<link rel="canonical">` 正确生成 |
| hreflang | 每页含 `en` / `zh-Hans` / `x-default` 三条 alternate(中英互指) |
| Open Graph | `og:title/description/url/image/locale/locale:alternate` 齐全 |
| Twitter Card | `twitter:card=summary_large_image` + image + site/creator |
| description | **全部 42 篇文档**都有 frontmatter `description`;首页中英分别定制 |
| keywords | 中英混合关键词(`langgraph alternative`、`langgraph 替代品`、`异步 Agent` 等) |
| 版本去重 | 旧版本 0.3–0.6 与 `next` 均 `noIndex` + `sitemap.ignorePatterns`,只索引 0.7(根路径),避免重复内容 |
| sitemap(英文) | `https://cubepi.ai/sitemap.xml` — 53 条 URL |
| **sitemap(中文)** | `https://cubepi.ai/zh-Hans/sitemap.xml` — **存在,53 条 zh-Hans URL** |
| robots.txt | 两份 sitemap 都已声明,`Allow: /` |
| 双语翻译 | zh-Hans 完整翻译(154 个翻译文件,含各历史版本) |
| 分析 | Google gtag(`G-NE2PDN0M91`,anonymizeIP)+ PostHog |
| 性能基建 | 已启用 `@docusaurus/faster`;Hero 图带 `width/height`(无 CLS) |

> 说明:此前怀疑 `robots.txt` 引用的 `/zh-Hans/sitemap.xml` 是死链 —— **build 证明它真实存在**,
> Docusaurus 为每个 locale 各生成一份独立 sitemap。该项无需修改。

---

## 2. 待优化项(按优先级)

### P0 — 应尽快修(低风险 / 高确定性)

**2.1 首页 H1 关键词过弱**
- 位置:`website/src/components/Home/Hero.tsx:29`
- 现状:`<h1>CubePi</h1>` —— 只有品牌名一个词,价值主张全在 `<p>` 里。
- 影响:H1 是最强的页面级关键词信号,目前完全没承载 "agent framework / langgraph alternative"。
- 建议:H1 改为带描述的整句,视觉上可用 `<span>` 拆分让 "CubePi" 仍突出。例:
  ```tsx
  <h1>CubePi — a Pythonic, async-native agent framework</h1>
  ```
  中文页同理:`CubePi —— Pythonic 异步原生 Agent 框架`。

**2.2 脚手架样板页 `/markdown-page` 被收录**
- 位置:`website/src/pages/markdown-page.mdx`
- 现状:内容是 Docusaurus 默认占位文("Markdown page example / You don't need React…"),
  **已出现在 sitemap.xml 中**,会被索引,稀释站点质量信号。
- 建议:直接删除该文件(同时它不在任何导航里,删除无副作用)。

### P1 — 高价值

**2.3 sitemap 缺 `lastmod`**
- 现状:英文 sitemap 53 条 URL,`changefreq`/`priority` 有(默认 weekly/0.5),**`lastmod` 为 0 条**。
- 建议:`website/docusaurus.config.ts` 的 sitemap 配置加 `lastmod: 'date'`,让搜索引擎感知更新时间:
  ```ts
  sitemap: {
    lastmod: 'date',
    changefreq: 'weekly',
    priority: 0.5,
    ignorePatterns: [ /* 不变 */ ],
  },
  ```

**2.4 对比 / 替代品落地页(自然流量最大增量)**
- 现状:仅 `docs/migration/from-langgraph.md` 一篇。
- 机会:高购买意图查询 —— "langgraph alternative"、"pi-agent-core alternative"、
  "langgraph vs …"、"异步 agent 框架"、"langgraph 替代品" —— 缺少**专门的可索引落地页**。
  首页 `WhyTable` 内容很好,但独立页面排名效果远好于首页内的一个区块。
- 建议:新建 `/compare/langgraph`、`/compare/pi-agent-core`(及对应 zh-Hans),
  每页含对比表 + 迁移示例 + 内链回 quick-start。需要撰写中英双语内容,工作量最大。

### P2 — 结构化数据

**2.5 JSON-LD 过简且全站同一份**
- 位置:`website/docusaurus.config.ts:79-94`(`headTags`)
- 现状:`SoftwareApplication` schema 注入到**每一个页面**(包括文档页),且只有 6 个字段。
- 建议:
  - 拆分作用域:`SoftwareApplication` / `WebSite` / `Organization` 只放首页;文档页改用 `TechArticle`(或不注入)。
  - 字段补充:`softwareVersion`、`offers: { "@type": "Offer", price: 0, priceCurrency: "USD" }`
    (免费 → 有机会触发 rich result)、`author` / `publisher`(Organization)、`sameAs`(GitHub/X 链接)。
  - 首页可加 `WebSite` + `SearchAction`(站内搜索框 sitelinks)。

### P3 — 细节 / 锦上添花

**2.6 `og:title` 重复品牌名**
- 现状:首页 `og:title` = `CubePi — a Pythonic async-native agent framework | CubePi`(末尾多了 `| CubePi`)。
- 原因:标题模板自动追加 `| CubePi`,而首页标题本身已含 CubePi。
- 建议:首页可用更短/更干净的标题,或调整 `titleDelimiter`;影响很小,纯观感。

**2.7 Hero 大图为 LCP 元素**
- 位置:`website/src/components/Home/Hero.tsx:21`
- 建议:给该 `<img>` 加 `fetchpriority="high"`;把 PNG 社交预览图额外导出 WebP/AVIF 版本用于页面展示
  (分享卡片仍保留 PNG)。已有 `width/height`,CLS 无问题,仅优化 LCP。

---

## 3. 运营侧建议(非代码)

- **Google Search Console / Bing Webmaster**:验证站点并提交 `sitemap.xml` 与 `zh-Hans/sitemap.xml`。
- **百度站长平台(中文市场)**:单独提交 `https://cubepi.ai/zh-Hans/sitemap.xml`。
  百度不解析 hreflang,但能抓取 Docusaurus 的静态 HTML,且仍读 meta keywords/description ——
  现有中文关键词配置对百度有效,建议保留并持续扩充长尾中文词。
- **外链 / 品牌信号**:GitHub README、PyPI 页、X(@cubeplexai)互链,补充 `Organization.sameAs`。

---

## 4. 一句话行动清单

1. 改首页 H1(P0)
2. 删 `markdown-page.mdx`(P0)
3. sitemap 加 `lastmod: 'date'`(P1)
4. 写 `/compare/*` 对比落地页(P1,内容工作量最大,自然流量增量最大)
5. 丰富 + 拆分 JSON-LD(P2)
6. 修 `og:title` 重复、Hero 图 `fetchpriority`(P3)
