作者：yumengjh

项目愿景：打造“动态、可扩展、可分片、可懒加载”的下一代文档系统。

基于 VitePress 的体验，但能力远超 VitePress。

---

项目愿景（Why）

传统 VitePress 有几个硬伤：

• ❌ 静态构建：文档更新必须构建 → 大文档构建时间长
• ❌ 超大文档卡顿：15k 字、30k 字的文档加载极慢
• ❌ 缺少后台系统：无法在线管理文档
• ❌ 无法动态获取内容（VitePress 本身是静态站点生成器）
• ❌ 无法跨端版本管理、多用户协作

而且你希望：

• 做一个 有挑战性的、长期迭代的、专业级文档系统框架
• 让自己技术提升，并做成产品级工程

于是，VitePress Pro 的核心目标是：

用 VitePress 的体验，做一个 Notion / GitBook / Vercel Docs 级别的 动态文档平台。

---

总体能力目标

VitePress Pro = 动态渲染器 + 文档数据库 + 分片系统 + 懒加载引擎 + 搜索引擎 + 版本系统

主要能力：

1. Markdown 动态渲染（无需构建）
2. 文档分片（标题 + 智能分片）
3. 全文搜索（倒排索引）
4. 语义搜索（向量搜索）
5. 懒加载渲染（按可视区域加载）
6. 文档版本控制（chunk diff）
7. 文档后台系统（编辑、发布、管理）
8. 前端渲染完全 VitePress 化（主题与布局可继承）
9. 后端文档 API（动态模式）
10. 多用户系统（可扩展）

---

核心思想总结（最重要部分）

⭐ 核心概念：Chunk（分片）

所有文档都被拆成可管理的小块。

每个 chunk 是：

{
  id: string,
  docId: string,
  type: "heading" | "paragraph" | "code" | "table",
  order: number,
  content: markdown_substring,
  html: optional_cache,
  tokens: [...],
  embedding: optional_vector
}

这意味着：

• ✔ diff 更快速
• ✔ 懒加载可做
• ✔ 搜索更精准
• ✔ 更新更轻量
• ✔ 可并发加载

⭐ 渲染器动态化

原本的：

createMarkdownRenderer(root)

是用于构建阶段，但你希望：

• 在 运行时 调用它
• 根据请求实时渲染 Markdown → HTML
• 甚至可缓存到 Redis/DB

⭐ 文档以 Markdown 原文保存，不保存 HTML

好处：

• 体积小
• 修改更快
• 可以版本控制
• 可以直接导入/导出
• 可重复渲染多主题

---

架构设计

架构图（文本式）

┌────────────────────────────┐
│        VitePress Pro       │
│      (前端渲染系统)        │
│   - 可视区域懒加载渲染       │
│   - 分片动态加载            │
│   - 主题：基于 VitePress    │
└──────────┬─────────────────┘
           ▼
┌────────────────────────────┐
│       Document API         │
│ - GET /doc/:id             │
│ - GET /doc/:id/chunks      │
│ - GET /chunk/:chunkId      │
│ - POST /doc                │
└──────────┬─────────────────┘
           ▼
┌────────────────────────────┐
│       文档管理后台           │
│ - 编辑器（在线 MD 编辑）     │
│ - 发布/预览/版本回退        │
│ - 搜索、分类                │
└──────────┬─────────────────┘
           ▼
┌────────────────────────────┐
│     文档存储数据库（DB）      │
│   Markdown 原文 + Chunk 表    │
│   索引表 + 版本表 + 用户表    │
└──────────┬─────────────────┘
           ▼
┌────────────────────────────┐
│   AI/搜索系统（可选）        │
│ - 向量搜索                  │
│ - 全文搜索                  │
└────────────────────────────┘

---

数据库设计（初版）

以 PostgreSQL 为例。

文档表

documents
---------
id (pk)
title
createdAt
updatedAt
authorId

分片表（最核心）

chunks
---------
id (pk)
docId (fk)
order (int)
type (enum)
markdown (text)
html (text, optional cache)
hash (text)
tokens (tsvector)      -- 用于全文搜索
embedding (vector)     -- 用于语义搜索（可选）

版本表

versions
---------
id
docId
createdAt
changes: jsonb   -- {chunkId: {oldHash, newHash}}

---

文档分片设计（Chunking）

支持两种策略：

① 标题分片（结构化）

根据：

# / ## / ###

切成层级结构。

用于：

• 目录
• 页面定位
• 层次化展示

② 智能分片（均匀）

按：

• tokens 数量（200~500）
• 段落边界
• 句子边界

切分。

用于：

• 搜索
• 懒加载
• diff/版本

⭐ 推荐混合模式：

一级结构：按标题分片
标题内部：按智能分片

---

懒加载渲染（可视区域渲染）

前端使用：

IntersectionObserver

在 chunk 可见时加载并渲染。

伪代码：

<div v-for="chunk in chunks" v-intersect="load(chunk)">
  <ChunkRenderer :chunk="chunk" />
</div>

渲染流程：

1. 请求 chunk markdown
2. 调用 createMarkdownRenderer.render()
3. 生成 html
4. 挂载 Vue 组件

缓存策略：

• 内存缓存（tab 内）
• IndexedDB 缓存
• 服务端缓存（Redis）

---

版本控制设计（Diff）

采用 chunk diff。

流程：

旧文档分片 → 对比 hash → 找到变化的 chunk → 对变化部分执行文本 diff → 保存增量版本。

细粒度 diff 使用：

• diff-match-patch
• 或 jsdiff

这样你可以：

• 高效版本回退
• 快速找出改动点
• 不保存整个文档

---

搜索体系设计

支持两种搜索：

---

全文搜索（倒排索引）

基于 PostgreSQL：

tsvector(chunk.markdown)

查询：

SELECT * FROM chunks WHERE tokens @@ plainto_tsquery('keyword')

优势：

• 高性能
• 支持高亮
• 原生

---

语义搜索（embedding）

embedding vector 存入：

pgvector

查询：

SELECT * FROM chunks ORDER BY embedding <-> $query LIMIT 10;

用途：

• 智能推荐
• 内容关联
• 文档问答

---

后台管理系统（CMS）

支持功能：

• 文档列表
• 在线 Markdown 编辑器
• 草稿与发布
• 文档版本查看（diff 视图）
• 文档导入/导出
• 用户权限

技术栈：

• Vue3 + Vite + Naive UI（轻量）
• 你的 Mist.js 也可以内嵌作为一个子组件（非常酷）

---

动态渲染器（Runtime Renderer）

核心思想：

不用构建，直接用 Node 版 VitePress 渲染器在运行时渲染 MD。

依赖：

import { createMarkdownRenderer } from 'vitepress'

你需要：

• 把这套插件链迁移到运行时
• 移除只依赖构建时的逻辑
• 删除 Rollup-only 的代码
• 保留 Markdown → HTML → Vue SFC 的过程

你可以把整个渲染器封装成一个：

@vitepress-pro/renderer

---

技术挑战与解决建议

大文档滚动性能

解决：

• chunk 级渲染
• 虚拟列表（Virtual Scroller）
• 预加载相邻 chunk

SSR？

可选：

• 动态渲染 SSR（像 Nuxt 内容模块）
• 或纯 SPA（更轻）

SEO

动态 HTML 可用：

• serverless SSR
• 或静态预渲染（只渲染第一页）

多主题切换

每个 chunk 的 HTML 可反复解析 → 支持主题动态切换

---

项目路线图（Roadmap）

阶段 1：最小可用版（MVP）

• 动态渲染器
• 文档 CRUD
• 文档分片（标题 + 智能）
• API 服务
• 前端渲染（无懒加载）

---

阶段 2：进阶功能

• 懒加载渲染
• 缓存
• 搜索（倒排）
• Markdown 编辑器
• 版本控制（chunk diff）

---

阶段 3：高级功能

• 语义搜索（向量）
• 多主题系统（多皮肤）
• 多用户权限
• 文档同步（Git-like）

---

阶段 4：产品化

• 网站托管服务
• 插件系统（像 VitePress plugin）
• 模板系统
• AI 文档分析
• 文档生成 API（AI → Markdown）

---

未来想法（可成为项目支线）

• 智能文档分片算法（可成为独立库）
• 文档 diff 引擎（类似 git diff，但更轻）
• Markdown 渲染器模块化（一个纯运行时的 VitePress Renderer）
• 文档搜索引擎（可开放 API）
• 动态知识库（像 Notion 或 Obsidian）

---

总结：VitePress Pro 是一项“大工程”

它不是一个简单的项目，而是：

• 一个框架
• 一个 CMS
• 一个搜索引擎
• 一个动态渲染器
• 一个版本控制系统
• 一个专业级知识库平台

而这些能力，对你未来技术成长也有巨大推动。

---

• 完整数据库 schema（SQL）
• 完整 API 文档
• 分片算法的伪代码
• 动态渲染器的代码框架
• 管理后台的 UI 图
• 项目 Monorepo 结构