CLI 与引擎设计

Clarify CLI 位于 packages/cli，它把内部构建引擎封装成 clarify dev、clarify build 和 clarify init。用户只需要关心 Clarify 命令，不需要创建或维护 Vite 配置文件。

职责分层

CLI 内部仍复用 Vite 的开发服务器和构建管线，但这是实现细节。公共 API 以 @clarify-labs/cli 和 clarify 命令为中心。

内容摄取流水线

引擎读取两种类型的源材料：

流程概览：

source → Frontmatter → MDX/OpenAPI 编译 → 路由清单 → Renderer → 静态 HTML

1. Frontmatter 提取：读取 title、description、keywords / keyword / tags 等页面元数据。
2. OpenAPI 资源加载：解析 OpenAPI 3.0/3.1 规范，并注入运行时 registry。
3. MDX 编译：将 .md / .mdx 编译为 React 组件，并注入 Clarify MDX 组件映射。
4. 路由注册：将文件路径映射为 URL 路径，同时生成侧边栏导航和 H2/H3 章节。
5. 内容制品：为 Markdown/OpenAPI 路由附加 contentArtifactUrl，用于 raw copy/link 和 llms.txt。
6. 静态生成：构建阶段为每个路由输出独立 index.html。

CLI 命令如何工作

clarify dev

1. 根据 CLI 参数解析项目根目录和内容目录。
2. 自动创建临时 HTML 入口（如果项目没有 index.html）。
3. 启动内部开发服务器。
4. 监听内容文件变化并触发路由清单重建与页面刷新。

clarify build

1. 使用相同的内容发现逻辑生成路由和虚拟模块。
2. 打包客户端资源。
3. 调用服务端渲染入口为所有路由生成 HTML。
4. 写出 raw Markdown/OpenAPI 文件和 llms.txt。

clarify init

生成最小项目骨架：

clarify.ts 或 clarify.json
source/index.mdx
package.json scripts

clarify.ts 是推荐形式，因为它可以使用 defineConfig 获得类型提示，并承载插件。

路由系统

Clarify 使用从文件系统派生的约定式路由：

source/
├── index.mdx           → /
├── getting-started.mdx → /getting-started
├── guides/
│   ├── index.mdx       → /guides
│   └── theming.mdx     → /guides/theming
└── api.openapi.yaml    → /api

多语言站点使用 locale 目录。默认语言不带前缀，非默认语言带 locale 前缀：

source/
├── zh-CN/index.md      → /
└── en-US/index.md      → /en-US

当 i18n.missing 为 fallback 时，缺失翻译会复用默认语言页面，并在路由上标记 isFallback。每个本地化路由还会携带 basePath 和 alternates 供语言切换使用。

配置加载

配置查找顺序为：

1. clarify.ts
2. clarify.js
3. clarify.json

clarify.ts 推荐用于类型安全配置：

import { defineConfig } from '@clarify-labs/cli'

export default defineConfig({
  title: 'My Docs',
  description: 'Product documentation',
  routePrefix: '/',
})

JSON 配置会被校验并应用默认值，但不能表达可执行插件。

虚拟模块

内部引擎通过虚拟模块把构建时数据传递给运行时：

• virtual:clarify-config — 解析后的站点配置和构建选项
• virtual:clarify-routes — 客户端路由清单、lazy 页面导入和导航树
• virtual:clarify-routes/server — SSR 使用的服务端路由清单，页面为 eager import
• virtual:clarify-openapi-registry — 已解析的 OpenAPI 规范集合
• virtual:clarify-entry-client — CLI 注入的客户端入口
• virtual:clarify-page/* — 每个 MDX/OpenAPI 页面对应的虚拟模块

这些模块由 CLI 内部装配，普通用户无需直接导入。

Hook 生命周期

内置插件先运行，用户插件后运行。当前生命周期为：

routes:discover
  → routes:discovered
  → 构建默认 navigation
  → routes:resolved
  → buildVirtualModules
  → modules:before
  → html:transform
  → dev:configureServer / build closeBundle
  → build:done

新增插件能力时应优先修改结构化数据（routes、navigation、modules），避免直接重写生成产物。Hook 抛错时会带上插件名和 hook 名，便于定位。

设计原则

• 隐藏构建工具细节：用户面向 clarify 命令，而不是 Vite 配置。
• 内容优先：默认约定为 source，新增文件即新增页面。
• 静态优先：构建产物是纯静态文件，可部署到任意静态托管平台。
• 可扩展：内部 hook 和插件机制为搜索、AI 翻译等后续能力预留扩展点。