AI Docs

AI文档

一个基于游乐场标记的wiki平台，集成了MCP服务器，通过VS Code中的GitHub Copilot实现无缝文档访问。

特性

• 📝 Markdown维基：使用Docusaurus 3.x生成静态站点
• 🔍 智能搜索：在所有文档中进行全文搜索
• 🏷️ 组织：内容组织的类别和标签
• 🔄 基于Git的工作流：通过git推送markdown文件来编辑内容
• 🤖 MCP集成：通过GitHub Copilot直接在VS Code中访问wiki文章
• 🐳 Docker就绪：使用Docker Compose进行一次命令部署

快速开始

先决条件

• Node.js 20 LTS或更高版本
• pnpm 8.x或更高
• Docker和Docker Compose（用于容器化部署）

本地开发

1. 克隆存储库:

   git clone 
   cd ai-docs

1. 安装依赖项:

   corepack enable
   corepack prepare pnpm@latest --activate
   pnpm install

1. 启动开发服务器:

   pnpm start

维基将在http://localhost:3000

Docker部署

1. 使用Docker Compose构建和运行:

   docker compose up --build

1. 访问维基:

- Wiki网站：http://localhost:3000 - MCP服务器：在配置的端口上运行

项目结构

ai-docs/
├── wiki/                     # Docusaurus wiki application
│   ├── docs/                # Markdown content (wiki pages)
│   ├── src/                 # Custom Docusaurus components
│   ├── static/              # Static assets (images, files)
│   ├── docusaurus.config.ts # Docusaurus configuration
│   ├── sidebars.ts          # Auto-generated sidebar (do not edit manually)
│   ├── generate-sidebars.js # Dynamic sidebar generator
│   ├── standardize-metadata.js # Metadata standardization tool
│   ├── fix-links.js         # Link fixing utility
│   └── package.json         # Wiki dependencies
├── mcp-server/              # MCP server for VS Code integration
│   ├── src/                 # TypeScript source code
│   └── package.json         # MCP server dependencies
├── indexer/                 # Document indexing service
│   ├── indexer.py           # Main indexer script
│   └── requirements.txt     # Python dependencies
├── embedding-service/       # Text embedding service
│   ├── server.py            # FastAPI server
│   └── requirements.txt     # Python dependencies
├── docker-compose.yml       # Multi-service orchestration
├── pnpm-workspace.yaml      # pnpm workspace configuration
└── package.json             # Root workspace scripts

基于Git的内容工作流

AI Docs对所有内容更改都使用基于git的工作流。只需编辑markdown文件、提交和推送，网站就会自动重建。

基本工作流程

1. 克隆存储库 （仅限第一次）：

   git clone 
   cd ai-docs

1. 创建或编辑标记 在 wiki/docs/ 目录：

   # Create a new guide
   touch wiki/docs/guides/my-guide.md

   # Or edit existing content
   vim wiki/docs/guides/existing-guide.md

1. 添加所需的封面:

   ---
   title: My New Guide
   description: A step-by-step guide for beginners
   category: Guides
   tags: [tutorial, beginner, example]
   date: 2025-11-14
   ---

   # My New Guide

   Your content here...

1. 承诺并推动你的改变:

   git add wiki/docs/guides/my-guide.md
   git commit -m "Add guide for new feature"
   git push origin main

1. 自动重建 （仅限Docker部署）：

- Git post receive钩子检测wiki/docs/更改 - Docker容器自动重启 - 侧边栏自动再生 - 网站重新生成新内容 - 时间线：30秒内完成

1. 验证您的更改:

   # Local dev: http://localhost:3000
   # Production: your-wiki-domain.com
   open http://localhost:3000

设置Git钩子（用于生产部署）

在git push上启用自动重建：

# Copy post-receive hook to your git repository
cp scripts/post-receive .git/hooks/post-receive

# Make it executable
chmod +x .git/hooks/post-receive

只要按下任何按钮，钩子就会触发 wiki/docs/ 目录。

内容组织

分类 （顶级部分）：

• Wiki Docs -关于使用此wiki的文档（安装、编写、工作流程）
• Guides -如何使用教程和分步说明
• Reference -API文档、体系结构、配置
• Examples -代码示例和模板
• Blogs -技术博客文章
• CI/CD -管道、GitOps和部署工作流
• Cloud -云架构和AWS模式
• Docker -容器最佳实践和优化
• Engineering -Java指南、SDLC流程
• Kubernetes -K8s部署模式和最佳实践
• Observability -监控、记录和跟踪
• Onboarding -工程师入职材料
• Security -安全最佳实践和指南
• Tech Radar -技术采用和建议

文件结构:

wiki/docs/
├── wiki-docs/            # Documentation about this wiki
│   ├── intro.md
│   ├── installation.md
│   ├── quickstart.md
│   ├── writing-markdown.md
│   ├── git-workflow.md
│   └── frontmatter-guide.md
├── guides/               # How-to guides
│   ├── mcp-setup.md
│   └── docker-deploy.md
├── reference/            # Technical reference
│   ├── architecture.md
│   └── mcp-tools.md
├── examples/             # Examples
│   ├── basic-page.md
│   └── advanced.md
├── blogs/                # Blog posts
│   ├── index.md
│   └── docker-best-practices.md
├── cicd/                 # CI/CD documentation
├── cloud/                # Cloud architecture
├── docker/               # Docker guides
├── engineering/          # Engineering practices
├── kubernetes/           # Kubernetes guides
├── observability/        # Observability guides
├── onboarding/           # Onboarding materials
├── security/             # Security documentation
└── tech-radar/           # Tech Radar

页面模板

使用提供的模板实现一致的结构：

# Copy template for new page
cp wiki/docs/_templates/page-template.md wiki/docs/guides/my-new-page.md

# Edit with your content
code wiki/docs/guides/my-new-page.md

该模板包括所有必需的frontmatter字段和常用内容部分。

维护脚本

维基包括有用的维护脚本：

# Standardize metadata across all files
cd wiki && node standardize-metadata.js

# Fix internal links after reorganization
cd wiki && node fix-links.js

# Check for broken links
cd wiki && node check-broken-links.js

最佳实践

• 描述性标题：使标题可搜索且清晰
• 一句话描述：总结页面目的
• 每页3-5个标签：始终如一地使用常用标签
• 更新日期：进行重大编辑时更改日期
• 本地测试：运行 pnpm start 在推送之前预览
• 原子提交：每次提交一次逻辑更改
• 清除提交消息：描述什么以及为什么

有关详细说明，请参阅 Git工作流指南 和 前台指南

MCP服务器集成

看 MCP设置指南 有关将MCP服务器连接到VS Code和GitHub Copilot的说明。

文档

• 安装指南
• 快速入门指南
• 编写Markdown
• Git工作流
• 前台指南
• MCP设置指南
• MCP工具参考
• 架构概述

建筑

AI Docs是一个具有多种服务的分布式系统：

核心服务

1. Docusaurus维基 （端口3000）

- 基于React的静态站点生成器 - 提供人类可读的文档

1. MCP服务器 （端口3001）

- Node.js+TypeScript HTTP服务器 - 为GitHub Copilot提供AI友好型API - 仅查询模式（无状态）

1. 色度数据库 （端口8000）

- 用于语义搜索的矢量数据库 - 存储518个块嵌入（42篇文章）

1. 嵌入服务 （端口8001）

- FastAPI+句子转换器 - 将文本转换为384维向量 - 型号： all-MiniLM-L6-v2

1. Python索引器 （一次性工作）

- 读取markdown文件 - 生成嵌入 - 填充ChromaDB

数据流

索引 （一次）：

Markdown Files → Indexer → Embedding Service → ChromaDB

询问 （运行时）：

GitHub Copilot → MCP Server → Embedding Service → ChromaDB → Results

有关详细的体系结构图和服务交互，请参阅 架构概述.

技术栈

• 静态站点生成器: Docusaurus 3.x
• 运行时：Node.js 20 LTS
• 程序包管理器：pnpm 8.x
• 语言：TypeScript+Python
• MCP协议: 模型上下文协议
• 向量数据库: 色度数据库
• ML模型: 句子变换器
• 容器化：具有多阶段构建的Docker
• Web服务器：NGINX（生产）

宪法原则

该项目遵循AI Docs章程：

1. 快速启动优先级：使用Docker在5分钟内运行
2. 简单文档：示例驱动的工作演示
3. 最小依赖性：每个依赖关系都提供了巨大的价值

贡献

1. 为您的功能创建新分支
2. 在中添加或编辑markdown文件 docs/
3. 本地测试 pnpm start
4. 承诺并推动你的改变
5. 网站将自动重新生成

许可证

麻省理工学院