Codex 与 Docusaurus 协作记录
本文汇总截至 2026-08-04 的近期 Codex 问答与实际操作，保留可复用的技术结论、 仓库状态和后续注意事项，不记录终端审批、访问令牌、个人路径或无关调试输出。
问答摘要
| 问题 | 结论 |
|---|---|
| Docusaurus 如何工作？ | 它是以插件生命周期为核心的 React 静态站点编译器，把配置、Markdown/MDX 和 React 页面编译成预渲染 HTML 与可水合 SPA。 |
| 官方仓库提供 Skill 吗？ | 没有提供可安装的 SKILL.md；根目录只有面向 AI 编程代理的 AGENTS.md。 |
| 当前环境安装了哪些 Skill？ | 会话开始时可触发 29 个全局 Skill，主要分为 Codex 系统工具、Caveman 工具组和 Cheat-on-content 工作流；本项目随后新增 $docusaurus-site 与 $seo-audit。 |
| 是否为本项目创建专用 Skill？ | 已创建中文 $docusaurus-site，覆盖内容、配置、主题、构建、验证与部署准备。 |
| 项目是否有 SEO？ | Docusaurus 已提供静态渲染、canonical、Open Graph 和 sitemap；当前站点已禁用博客及其 Feed，并安装 $seo-audit 审查新文档。 |
| 仓库是否已初始化并推送？ | 已初始化 main 分支并建立远程跟踪；具体地址和提交标识不写入知识文档。 |
Docusaurus 工作原理
Docusaurus 不是单纯的 Markdown 转 HTML 工具。更准确的模型是：
docusaurus.config.ts
-> 展开 classic preset
-> docs、blog、pages 等插件读取内容
-> 插件生成路由、页面数据和全局数据
-> .docusaurus 保存自动生成的编译输入
-> Rspack/Webpack 分别构建客户端与服务端 bundle
-> 服务端 bundle 遍历路由并静态生成 HTML
-> 浏览器 hydrateRoot 接管页面并提供 SPA 导航
插件生命周期
核心插件大致按照以下顺序工作：
插件构造函数
-> loadContent()
-> translateContent()
-> contentLoaded()
-> allContentLoaded()
-> configureWebpack()
-> postBuild()
其中 contentLoaded() 可以创建数据、添加路由并公开插件级全局数据。docs 插件会读取
文档、front matter、版本和侧边栏，再把 MDX 注册为 React 页面模块。
开发与生产的区别
npm run start加载配置和插件内容，启动开发服务器，并监听配置与内容文件变化。npm run build同时构建浏览器 bundle 和构建期服务端 bundle，再为每条路由生成 静态 HTML。- 浏览器首先获得完整 HTML，随后 React 水合；之后的站内导航由客户端路由接管。
.docusaurus/是自动生成的路由和数据注册表，build/是最终部署产物；两者都不应 手工修改或提交。
上游仓库结构
上游 Docusaurus 仓库是 pnpm + Lerna monorepo，主要模块包括：
packages/docusaurus：@docusaurus/core，包含 CLI、配置加载、插件调度和 SSG。packages/create-docusaurus：项目脚手架。packages/docusaurus-preset-classic：组合 docs、blog、pages 和 classic theme。packages/docusaurus-plugin-content-*：文档、博客和页面内容插件。packages/docusaurus-theme-classic：默认 React UI。packages/docusaurus-mdx-loader：把 Markdown/MDX 编译成 React 组件。packages/docusaurus-bundler：Webpack/Rspack 抽象。packages/docusaurus-faster：Rspack、SWC、Lightning CSS 等加速能力。website：官方文档站，也用于框架自测。
当前项目如何映射
本仓库是官方 classic 模板生成的 Docusaurus 站点，不是框架 monorepo：
| 路径 | 作用 |
|---|---|
docusaurus.config.ts | 站点元数据、preset、导航、页脚、主题和国际化配置 |
sidebars.ts | 文档侧边栏；站点导览独立置顶，其余文档按 AI Agent 指南与部署运维两个类目组织 |
docs/ | 文档内容，路由前缀为 /docs |
src/pages/ | 基于文件的自定义页面；index.tsx 负责 / |
src/components/ | 可复用 React 组件 |
src/css/custom.css | 全局 Infima 变量和主题覆盖 |
static/ | 原样复制到部署根目录的静态资源 |
当前使用 Docusaurus 3.10.2、React 19、Node.js 20+ 和 npm。项目安装了
@docusaurus/faster，并设置 future.v4: true，因此采用面向 Docusaurus v4 的
兼容默认值和加速构建路径。
仓库操作记录
Git 与远程仓库
- 本地仓库默认分支：
main origin/main已与本地main建立跟踪关系
远程地址、仓库可见性和具体提交标识属于部署或运维元数据，不写入面向读者的知识文档。
初始提交前运行了 npm run typecheck 与 npm run build，两项均通过。
AGENTS.md
项目根目录已加入上游 Docusaurus 的 AGENTS.md。该文件描述的是框架 monorepo，
其中的 pnpm、Lerna、packages/ 和 website/ 工作流不适用于本 npm 站点。执行项目
任务时应以本仓库 package.json 中的 npm scripts 为准，并在采用其中的 Issue/PR
规则前先确认它们是否适用于当前仓库。
项目专用 Skill
仓库内已创建 .codex/skills/docusaurus-site/：
SKILL.md：中文触发描述、文件职责、SEO 门禁、实现约束和验证流程。references/project-map.md：仓库身份、npm 命令、目录职责和部署占位值。references/seo-content-gate.md：把通用 SEO 审查映射到 Docusaurus front matter 和构建后 HTML。agents/openai.yaml：中文显示名称、简介和默认提示词。
项目还安装了 .codex/skills/seo-audit/，用于技术
SEO、页面 SEO、内容质量、内链、国际化和博客审查。
调用方式：
$docusaurus-site
该 Skill 明确要求：
- 不编辑或提交
.docusaurus/与build/。 - 优先复用 classic preset、现有主题组件和 CSS 约定。
- 修改 TypeScript 或配置后运行
npm run typecheck。 - 修改路由、内容、主题、资源或部署设置后运行
npm run build。 - 每次生成新 docs/blog 时调用
$seo-audit，并检查构建后 HTML 的实际元数据。 - 不把上游 monorepo 的 pnpm/Lerna 命令误用于当前站点。
- 文档不得包含真实代码托管地址、访问凭据、密钥、认证日志或个人电脑绝对路径。
两个项目 Skill 已通过官方 quick_validate.py 校验，站点类型检查和生产构建也均通过。
当前待办与风险
站点部署前仍需确认生产域名、baseUrl、组织标识、项目标识和编辑链接。具体部署地址
应保存在部署配置或环境变量中，不应复制到面向读者的知识文档。