🚀 Pybricks项目启动指南
本项目为基于MCP的RAG助手提供了一个简洁而可靠的蓝图，专为Python和Pybricks初学者（如FLL儿童和教练）设计。它通过整合Pybricks的官方文档和示例，为用户提供基于实际情况、版本感知的答案。
🚀 快速开始
本项目包含两个核心文件，助您快速搭建起工作环境：
ingest_pybricks.py：该脚本会爬取官方的Pybricks文档、教程以及关键的GitHub页面，对内容进行合理分块，并构建一个ChromaDB集合。mcp_server.py：这是一个轻量级的MCP风格工具服务器，它基于Chroma集合，提供了docs.search、code.search、snippet.suggest和compare.versions等功能。
初始爬取范围已限制在对初学者最有用、最稳定的页面，如API参考、参数/常量、机器人技术/DriveBase、入门指南、教程和更新日志等。您可以在后续添加更多内容。
✨ 主要特性
- 数据爬取：从官方文档和教程中提取关键信息，构建ChromaDB集合。
- 工具服务：提供多种搜索和建议功能，方便用户查找文档、代码示例和版本信息。
- 版本感知：支持根据版本过滤搜索结果，确保答案与用户使用的版本一致。
- 初学者友好：使用官方API调用和示例，避免复杂的技巧，易于理解和使用。
📦 安装指南
依赖安装
运行脚本前，请确保已安装以下依赖：
pip install requests beautifulsoup4 lxml markdownify tiktoken chromadb sentence-transformers fastapi uvicorn
数据摄入
首次运行或定期更新数据时，执行以下命令：
python ingest_pybricks.py
启动服务
启动工具服务器：
uvicorn mcp_server:app --reload --port 8765
💻 使用示例
基础用法
以下是使用ingest_pybricks.py脚本的示例：
#!/usr/bin/env python3
"""
Build a beginner-friendly Pybricks RAG corpus into ChromaDB.
- Crawls/loads selected Pybricks docs/tutorials + key GitHub changelogs.
- Normalizes & chunks (HTML/Markdown-aware; preserves code blocks).
- Creates multi-view docs (full text + headings/signatures + identifiers).
- Indexes into ChromaDB collections: pybricks_docs and pybricks_snippets.
Requires: requests, beautifulsoup4, lxml, markdownify, tiktoken, chromadb, sentence-transformers
pip install requests beautifulsoup4 lxml markdownify tiktoken chromadb sentence-transformers
"""
# 后续代码保持不变...
高级用法
以下是使用mcp_server.py提供的工具的示例：
# 发送文档搜索请求
import requests
data = {
"query": "DriveBase的使用方法",
"filters": {"version": "latest"}
}
response = requests.post("http://localhost:8765/tools/docs.search", json=data)
print(response.json())
📚 详细文档
摄入数据范围
初始允许列表包含以下内容：
- API文档（稳定版和最新版）：
docs.pybricks.com，包括机器人技术/DriveBase和参数/常量。(Pybricks Documentation) - 入门指南和IDE基础：
pybricks.com/learn/getting-started/*，code.pybricks.com主页。(Pybricks, Pybricks Code) - 初学者友好的教程和示例：如集线器到PC和集线器到集线器的通信、按钮基础、快速参考等。(Pybricks)
- 更新日志（用于版本检查）：
pybricks-code和pybricks-micropython的更新日志。(GitHub) - pybricksdev文档（可选辅助工具）：(Pybricks Documentation, GitHub)
工具服务器接口
docs.search(query, filters)：混合密集搜索，可根据版本和来源进行过滤。code.search(symbol)：优先查找标识符匹配的结果。snippet.suggest(goal, hardware)：返回预定义的代码模板。compare.versions(feature)：检查更新日志，查找特定功能的版本信息。
未来升级方向
- 添加对Python示例的AST感知分块：对于本地保存的Python示例，进行更精细的分块处理。
- 重排序：在密集搜索后，根据精确匹配的符号（如
DriveBase.turn、Port.A等）提升结果排名。 - 版本提示：在答案中显示版本信息，如“在v3.5中添加”。
🔧 技术细节
数据爬取与处理
ingest_pybricks.py脚本通过以下步骤完成数据的爬取和处理：
- 配置种子URL和允许的域名：定义初始爬取的URL列表和允许的域名范围。
- 爬取页面：使用
requests库发送HTTP请求，获取页面内容，并使用BeautifulSoup解析HTML。 - 转换为Markdown：将HTML内容转换为Markdown格式，同时保留代码块和标题。
- 分块处理：根据标题（H1 - H3）将Markdown内容分割成多个部分，并进行窗口化处理，确保每个块的长度在指定的令牌范围内。
- 提取标识符：从文本中提取可能的标识符，如符号、常量、错误名称等。
- 构建记录：为每个分块生成唯一的ID，并添加元数据，如URL、标题、版本等。
- ChromaDB插入：将记录插入到ChromaDB集合中，并创建一个轻量级的标识符集合，用于重排序。
工具服务器实现
mcp_server.py使用FastAPI框架实现了一个简单的工具服务器，提供了以下接口：
/tools/docs.search：处理文档搜索请求，支持根据版本和来源进行过滤。/tools/code.search：处理代码搜索请求，优先查找标识符匹配的结果。/tools/snippet.suggest：根据目标和硬件信息，返回预定义的代码模板。/tools/compare.versions：检查更新日志，查找特定功能的版本信息。
索引与检索策略
- 混合搜索：结合密集嵌入和BM25/正则表达式，提高符号匹配的准确性。
- 父子关系：嵌入小的分块，并保留“父”部分或文件，以便在需要时扩展。
- 多向量表示：每个分块使用多个向量表示，包括全文、标题/签名视图和仅标识符视图。
- 版本过滤：为每个分块标记版本信息，支持根据版本过滤搜索结果。
- 重排序：根据精确符号匹配、版本接近度和文档类型对前K个结果进行重排序。
📄 许可证
文档中未提及相关许可证信息。
💡 使用建议
- 定期运行
ingest_pybricks.py脚本，以更新ChromaDB集合中的数据。 - 在使用工具服务器时，根据需要调整搜索参数，如
k值和过滤条件，以获得更准确的结果。 - 对于初学者，建议参考官方文档和示例，以确保使用正确的API调用和方法。
⚠️ 重要提示
确保在运行脚本前已安装所有依赖项，否则可能会导致脚本运行失败。同时，注意数据爬取可能会受到网站的反爬机制限制，请遵守相关网站的使用条款。