VitePress Docs Generator

根据 URL、本地目录或文字描述自动生成 VitePress 风格静态文档站点。

工作流路由

核心原则

• 🔒 忠实源内容：不编造、不臆造，基于源材料生成
• 🔒 用户可预览：生成后提供预览链接，用户可迭代修改
• 🔒 高级特性优先：默认包含 mermaid 图表、卡片布局、轮播图等
• 🔒 项目完整：输出可直接 npm install && npm run dev 运行的 VitePress 项目

工作流 W0: 模板选择

步骤：

1. 询问用户是否使用参考模板
2. 如果用户提供模板路径，读取模板配置
3. 如果没有提供模板，使用默认模板（vitepress-docs）
4. 根据模板生成 VitePress 项目

模板位置：
- 默认模板：templates/vitepress-docs/
- 用户模板：用户指定的路径

工作流 W1: URL → VitePress

步骤：

1. 抓取 URL 内容（使用 webfetch 或等效工具）
2. LLM 分析内容结构（标题层级、主题分类、关键信息）
3. 生成 VitePress 项目结构：
   - .vitepress/config.ts - 站点配置
   - docs/ - 文档页面（按主题分类）
   - package.json - 依赖配置
4. 智能布局：
   - 长文档 → 分页或折叠
   - 代码示例 → 语法高亮
   - 图片/图表 → 懒加载
   - 导航 → 侧边栏 + 顶部栏
5. 高级特性（根据内容类型自动添加）：
   - mermaid 流程图/架构图
   - 卡片布局（功能介绍、特性对比）
   - 轮播图（多页面展示）
   - 视频嵌入（如有）
   - 外部链接
6. 生成 README 和部署说明

输出约定：
- 输出目录：用户指定或当前工作目录 vitepress-docs/
- 文件命名：保持源文档逻辑结构
- 格式：Markdown (.md) + TypeScript 配置

工作流 W2: 文字描述 → VitePress

步骤：

1. LLM 理解用户描述意图
2. 询问补充信息（如有必要）：
   - 目标受众？
   - 文档主题？
   - 需要哪些板块？
3. 生成 VitePress 项目结构（同 W1）
4. 按描述填充内容

工作流 W3: 本地目录 → VitePress

步骤：

1. 扫描本地目录，识别文档结构：
   - Markdown 文件（.md）
   - 代码文件（.ts/.js/.py 等，提取注释和文档字符串）
   - 配置文件（package.json/README.md 等）
   - 其他文档（.txt/.rst/.adoc）
2. 解析文档层级关系（通过目录结构或文件命名）
3. 分析内容结构（标题层级、代码块、图表、链接等）
4. 生成 VitePress 项目结构：
   - 按源目录结构映射到 docs/ 页面
   - 自动生成分组和导航
5. 智能布局：
   - 目录树 → 侧边栏导航
   - 代码示例 → 语法高亮 + 可复制
   - 跨文件链接 → 自动转换
6. 高级特性：
   - 识别 mermaid 图表语法并保留
   - 识别图片引用并优化
   - 识别视频链接并嵌入
7. 生成 README 和部署说明

工作流 W4: Git 远程仓库 → VitePress

步骤：

1. 判断输入是否为 Git 远程仓库（GitHub/GitLab/Bitbucket URL）
2. Clone 仓库到临时目录
3. 调用 llm-wiki skill 分析仓库内容，生成 Wiki 文档
   - 使用 llm-wiki/scripts/analyze_source.py 分析源材料
   - 使用 llm-wiki/scripts/generate_wiki.py 生成 Wiki
4. 将 Wiki 文档作为源材料，运行 W3（本地目录 → VitePress）流程
5. 生成 VitePress 项目结构

输出约定：
- 临时 Clone 目录：/tmp/vitepress-clone-<timestamp>/
- Wiki 输出：{output_dir}/wiki/
- VitePress 项目：用户指定或 {output_dir}/vitepress-docs/

依赖：
- git 命令行工具
- llm-wiki skill（需预先安装）

加载策略

• 总是加载：references/vitepress-features.md（高级特性清单）
• 按需加载：references/layout-patterns.md（布局模式参考）

文件结构

vitepress-docs-generator/
├── SKILL.md                 # Skill 主文件（路由逻辑 + 核心指令）
├── README.md                # 使用说明
├── CHANGELOG.md             # 版本记录
├── _meta.json               # Skill 元数据
├── references/
│   ├── vitepress-features.md   # Mermaid/卡片/轮播等高级特性
│   └── layout-patterns.md      # 布局模式参考
├── scripts/
│   ├── generate_vitepress.py   # 核心生成脚本
│   └── fetch_url.py            # URL 抓取脚本
└── tests/
    └── test_generator.py       # 自动化测试

输出文件约定

• 输出目录：用户指定或当前工作目录 vitepress-docs/
• 文件命名：package.json、.vitepress/config.ts、docs/index.md 等标准 VitePress 命名
• 文件格式：Markdown (.md) + TypeScript/JavaScript 配置
• 错误输出：对话中报错 + 返回结构化错误 {"ok": false, "error": str}
• 路径示例：vitepress-docs/.vitepress/config.ts

Output

执行工作流后产出：

• VitePress 项目目录：包含 .vitepress/config.ts、docs/、package.json 等
• 扫描结果（本地目录输入）：scan_result.json 包含文件列表和结构分析
• README.md：项目说明和部署指南

输出格式：

{
  "ok": true,
  "output_dir": "/path/to/vitepress-docs",
  "input_type": "url|text|directory",
  "files_generated": ["package.json", ".vitepress/config.ts", ...],
  "scan_result": {...}
}

输出格式

首页 (layout: home)

首页使用 VitePress 官方 hero 布局，包含：

---
layout: home

hero:
  name: "项目名"
  text: "副标题"
  tagline: "描述"
  image:
    src: /logo.png
    alt: Logo
  actions:
    - theme: brand
      text: 快速开始
      link: /guide/getting-started
    - theme: alt
      text: GitHub
      link: https://github.com/...

features:
  - title: 特性1
    details: 描述
    icon: 📦
  - title: 特性2
    details: 描述
    icon: 📚
  - title: 特性3
    details: 描述
    icon: 🚀
  - title: 特性4
    details: 描述
    icon: 🌐
---

# 正文内容...

注意：
- actions 按钮会生成可点击的链接
- features 卡片包含标题、描述和图标
- 链接地址使用绝对路径（如 /guide/xxx）

内容页 (3栏布局)

• 顶部导航栏 (VPNav)：全局导航
• 左侧边栏 (VPSidebar)：文档分组导航
• 右侧目录 (VPDocAside)：当前页面大纲