VAI TEAM 技术文档站

基于 VitePress 构建的 VAI TEAM 技术文档和教程站点。

特性

• 📚 完整文档 — 从快速开始到高级配置的全面文档
• 🎓 实操教程 — 7 章详细教程，手把手指导项目开发
• 🔍 中文搜索 — 内置全文搜索，支持中文分词
• 📱 响应式设计 — 完美适配桌面和移动设备
• ⚡ 快速加载 — 静态站点，CDN 友好
• 🎨 品牌一致 — 与 VAI TEAM 官网相同的视觉风格

快速开始

本地开发

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 访问 http://localhost:5173

构建部署

# 构建静态文件
npm run build

# 预览构建结果
npm run preview

使用部署脚本

我们提供了便捷的部署脚本：

# 开发模式
./deploy.sh dev

# 构建并预览
./deploy.sh preview

# 部署到服务器
./deploy.sh deploy user@server.com /var/www/docs

# 构建 Docker 镜像
./deploy.sh docker

# 部署到 GitHub Pages
./deploy.sh github

内容结构

techsite/
├── docs/                    # 技术文档
│   ├── quickstart.md       # 快速上手
│   ├── deployment.md       # 部署指南
│   ├── concepts/           # 核心概念
│   ├── config/             # 配置指南
│   └── api/                # API 参考
├── tutorial/               # 教程内容
│   ├── overview.md         # 教程概览
│   ├── env-and-model.md    # 环境准备
│   ├── first-project.md    # 第一个项目
│   ├── stage-0-to-4.md     # 阶段 0-4
│   ├── stage-5-to-7.md     # 阶段 5-7
│   ├── review-and-collab.md # 审核协作
│   ├── experience-reuse.md  # 经验复用
│   └── common-mistakes.md   # 常见错误
├── videos.md               # 视频教程
├── changelog.md            # 更新日志
└── index.md                # 首页

内容维护

添加新文档

1. 在相应目录创建 Markdown 文件
2. 在 .vitepress/config.ts 中添加导航配置
3. 使用标准的 Markdown 语法编写内容

更新现有文档

直接编辑对应的 Markdown 文件，VitePress 会自动重新构建。

添加图片

将图片放在 public/images/ 目录下，在文档中使用相对路径引用：

![描述文字](./images/screenshot.png)

代码高亮

支持多种语言的代码高亮：

\`\`\`python
def hello_world():
    print("Hello, VAI TEAM!")
\`\`\`

\`\`\`bash
docker compose up -d
\`\`\`

\`\`\`json
{
  "name": "vaiteam",
  "version": "1.0.0"
}
\`\`\`

提示框

使用 VitePress 内置的提示框：

::: tip 提示
这是一个有用的提示
:::

::: warning 注意
这是一个警告信息
:::

::: danger 危险
这是一个危险操作警告
:::

部署选项

1. 静态文件服务器

构建后将 .vitepress/dist/ 目录部署到任何静态文件服务器：

npm run build
cp -r .vitepress/dist/* /var/www/html/

2. Nginx 配置

server {
    listen 80;
    server_name ai-orchestration.cn;
    root /var/www/docs;
    index index.html;

    # SPA 路由支持
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 静态资源缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

3. Docker 部署

# 使用部署脚本构建镜像
./deploy.sh docker

# 运行容器
docker run -d -p 80:80 vaiteam-docs:latest

4. GitHub Pages

# 自动部署到 GitHub Pages
./deploy.sh github

5. Vercel 部署

1. 连接 GitHub 仓库到 Vercel
2. 设置构建配置：
   • Build Command: npm run build
   • Output Directory: .vitepress/dist
3. 自动部署

6. Netlify 部署

1. 连接 GitHub 仓库到 Netlify
2. 设置构建配置：
   • Build command: npm run build
   • Publish directory: .vitepress/dist
3. 配置重定向规则（public/_redirects）：

   /*    /index.html   200

自定义配置

修改主题色

编辑 .vitepress/theme/styles/custom.css：

:root {
  --vp-c-brand-1: #ff7a3d;  /* 主品牌色 */
  --vp-c-brand-2: #22b8a9;  /* 辅助品牌色 */
}

添加自定义组件

1. 在 .vitepress/theme/components/ 创建 Vue 组件
2. 在 .vitepress/theme/index.ts 中注册组件
3. 在 Markdown 中使用组件

修改导航菜单

编辑 .vitepress/config.ts 中的 themeConfig.nav 配置。

修改侧边栏

编辑 .vitepress/config.ts 中的 themeConfig.sidebar 配置。

性能优化

构建优化

• 自动代码分割
• 图片压缩和懒加载
• CSS 和 JS 压缩
• 预渲染和预加载

CDN 部署

推荐使用 CDN 加速静态资源：

# 构建时指定 CDN 基础路径
npm run build -- --base=/cdn/docs/

搜索优化

内置的本地搜索已针对中文优化，无需额外配置。

贡献指南

内容贡献

1. Fork 仓库
2. 创建特性分支：git checkout -b feature/new-tutorial
3. 编写或修改文档
4. 提交更改：git commit -m "docs: 添加新教程"
5. 推送分支：git push origin feature/new-tutorial
6. 创建 Pull Request

内容规范

• 使用中文编写，专业术语可保留英文
• 代码示例要完整可运行
• 截图使用统一的浏览器和主题
• 链接使用相对路径
• 文件名使用小写和连字符

审核流程

1. 内容准确性检查
2. 格式和样式检查
3. 链接有效性验证
4. 构建测试通过
5. 合并到主分支

技术栈

• VitePress — 静态站点生成器
• Vue 3 — 组件框架
• TypeScript — 类型安全
• Vite — 构建工具
• MiniSearch — 本地搜索

许可证

MIT License

支持

• 📖 完整文档
• 💬 GitHub Issues · Gitee Issues
• 📧 联系我们

---

VAI TEAM — 多 Agent 协作的 AI 开发团队