aivos-xie 知识库 + MCP Server 架构
核心概念
知识库不是原始文档堆砌，而是AI专用的结构化知识：
- patterns — 架构模式、设计模式、代码模式
- decisions — 技术选型、架构决策、方案对比
- strategies — 重构策略、测试策略、部署策略
- references — API参考、命令速查、配置指南
项目结构
project/
├── index.html # 首页（搜索+分类+Agent接入）
├── search.html # 搜索页（fuse.js前端搜索）
├── doc.html # 文档查看器（客户端渲染markdown）
├── download.html # 下载Skill页
├── mcp.html # Agent接入指南
├── about.html # 关于/贡献指南
├── docs/ # Markdown文档（按分类目录）
│ ├── {分类名}/
│ │ └── *.md
├── assets/
│ ├── app.js # 共享JS（header/footer/搜索）
│ ├── style.css # 样式
│ ├── search-index.json # 搜索索引（fuse.js用）
│ ├── categories.json # 分类统计
│ ├── all-docs.json # 全部文档元数据
│ ├── knowledge-index.json # AI专用结构化索引
│ └── modules.json # Skill模块列表
└── mcp-server/
├── index.js # MCP Server（4个Tool）
└── package.json
关键设计决策
文档用Markdown，不用HTML
- 原始README → 清洗 → 保留.md格式
- 客户端用
marked.js渲染 - 体积小（38MB vs 150MB+ HTML）
- 更新方便，git diff清晰
搜索用fuse.js前端搜索
- 零服务器成本
- 搜索索引是JSON文件
- 支持模糊匹配
Agent接入用MCP协议
- 任何MCP兼容Agent都能调用
- 4个Tool: search_knowledge / get_document / list_categories / list_skills
- 本地运行或通过npx
MCP Server 实现要点
// 核心Tool定义
server.tool("search_knowledge", "搜索知识库", {
query: z.string(),
category: z.string().optional(),
limit: z.number().optional().default(5),
}, async ({ query, category, limit }) => {
// 从search-index.json搜索
// 返回{title, category, summary, url}
});
server.tool("get_document", "获取文档详情", {
path: z.string(), // 如 docs/python/README.md_xxx.md
}, async ({ path }) => {
// 读取本地markdown文件
// 返回截断内容（前8000字符）
});
数据清洗Pipeline
处理GitHub README的关键步骤：
- 去掉
# https://raw.githubusercontent.com/...头 - 去掉
Collected:/Source:/Size:元数据行 - 去掉 shields.io badge图片链接
- 去掉居中的
<p align="center">badge块 - 去掉base64编码的长行（>500字符）
- 去掉HTML注释
<!-- ... --> - 合并多余空行
SSH批量数据传输
不要逐个文件SSH读取，太慢！
# 错误：每个文件一次SSH调用（234个文件 = 234次连接）
ssh server "cat file1" > local1
ssh server "cat file2" > local2
# 正确：批量scp
scp server:/path/docs/*/*.md ./local/docs/
# 更好：rsync（增量同步）
rsync -avz server:/path/docs/ ./local/docs/
Pitfalls
- Node.js MCP Server需要ESM — package.json必须有
"type": "module" - marked.js CDN — 用
https://cdn.jsdelivr.net/npm/marked/marked.min.js - 搜索索引更新 — 每次数据更新后必须重新生成search-index.json
- 文档路径 — doc.html用
?file=docs/xxx/yyy.md参数加载 - GitHub Pages 1GB限制 — 纯markdown够用，加图片会超