使用说明

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（用于容器化部署）

本地开发

克隆存储库:
```
git clone <repository-url>
cd ai-docs
```

安装依赖项:

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

启动开发服务器:
```
pnpm start
```
维基将在http://localhost:3000

Docker部署

使用Docker Compose构建和运行:
```
docker compose up --build
```
访问维基:
- 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文件、提交和推送，网站就会自动重建。

基本工作流程

克隆存储库 （仅限第一次）：
```
git clone <repository-url>
cd ai-docs
```

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

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

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

添加所需的封面:

---
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...

承诺并推动你的改变:

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

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

验证您的更改:

# 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的说明。

文档

建筑

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

核心服务

Docusaurus维基 （端口3000）
- 基于React的静态站点生成器
- 提供人类可读的文档
MCP服务器 （端口3001）
- Node.js+TypeScript HTTP服务器
- 为GitHub Copilot提供AI友好型API
- 仅查询模式（无状态）
色度数据库 （端口8000）
- 用于语义搜索的矢量数据库
- 存储518个块嵌入（42篇文章）
嵌入服务 （端口8001）
- FastAPI+句子转换器
- 将文本转换为384维向量
- 型号： all-MiniLM-L6-v2
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章程：

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

贡献

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

许可证

麻省理工学院