m5stack-assistant

# M5Stack Assistant Skill 通过M5Stack官方MCP服务解决所有M5Stack相关问题。 ## 快速使用（优化后） ### 命令行工具直接调用 ```bash # 基础查询 node m5-search.mjs "M5Stack CoreS3 引脚定义" # 带参数查询 node m5-search.mjs "M5StickC Plus Arduino示例" --filter arduino --num 2 node m5-search.mjs "ESP32-S3 寄存器说明" --chip ``` **参数说明：** - `--num <1-3>`：返回结果数量，默认1 - `--filter <类型>`：过滤文档类型：`product`/`program`/`arduino`/`uiflow`/`esp-idf`/`esphome`，默认`product` - `--chip`：查询芯片相关数据手册 ### 代码中调用 ```javascript import { mcpSearch } from './scripts/mcp.mjs'; // 查询示例 const result = await mcpSearch('M5Stack CoreS3 基本参数', { num: 1, filter_type: 'product' }); ``` --- ## 核心流程 ### 1. 理解需求 - 明确用户要做什么 - 判断问题类型：产品咨询 / 规格查询 / 编程问题 / 技术支持 / 故障排除 - 确定涉及的M5Stack设备型号或产品系列 - 识别需要的功能模块 ### 2. 问题类型分类与查询策略 #### 产品咨询类 **当用户询问：** - 产品功能、特性、应用场景 - 产品对比、选型建议 - 包装内容、配件信息 **查询方式：** - 使用 `filter_type: "product"` 查询产品文档 - 查询数量 `num: 2-3` 获取完整信息 #### 规格参数类 **当用户询问：** - 技术规格、电气特性 - 尺寸、重量、SKU - 功耗、热设计、工作温度 - 芯片型号、内存配置、接口定义 **查询方式：** - 使用 `filter_type: "product"` 查询产品文档 - 如果涉及芯片，考虑设置 `is_chip: true` - 查询数量 `num: 1-2` #### 编程开发类 **当用户询问：** - Arduino / UIFlow / ESP-IDF 编程 - API使用、示例代码 - 库依赖、配置要求 - 引脚定义、硬件连接 **查询方式：** - 根据开发环境选择 `filter_type`： - Arduino → `"arduino"` - UIFlow → `"uiflow"` - ESP-IDF → `"esp-idf"` - 查询数量 `num: 2-3` #### 技术支持与故障排除 **当用户询问：** - 设备无法正常工作 - 连接问题、通信错误 - 常见问题解答 (FAQ) - 固件更新、恢复出厂设置 **查询方式：** - 使用 `filter_type: "product"` 或 `"program"` - 搜索相关故障排除文档 - 查询数量 `num: 2-3` ### 3. 查询MCP服务 使用M5Stack官方MCP服务检索： - 产品规格、技术参数 - 相关API文档 - 官方示例代码 - 设备特定的配置和限制 - 故障排除指南 使用提供的Node.js MCP客户端脚本进行查询，详见下方"工具脚本"部分。 ### 4. 迭代查询 - 当遇到不清楚的内容时，主动进行进一步查询 - 不要假设不确定的产品规格或API用法 - 查询相关的依赖、兼容性和配置要求 ### 5. 编程类任务额外步骤（如适用） #### 生成代码 - 基于官方示例和文档生成代码 - 保持代码风格与官方示例一致 - 添加必要的注释 #### 代码复查 生成代码后必须进行以下检查： - 语法正确性 - API调用是否正确 - 引脚配置是否合理 - 是否有遗漏的依赖 - 是否有常见的低级错误（如拼写错误、缺少分号等） - 代码逻辑是否完整 #### 提供说明 - 解释代码的主要功能 - 说明需要安装的库 - 提供上传和测试的建议 ### 6. 整理与回复 - 基于查询到的官方信息整理答案 - 提供准确的规格参数、产品特性 - 引用官方文档来源（如适用） - 提供清晰的操作步骤或使用建议 ## MCP服务使用 ### 服务器信息 - **端点**: `https://mcp.m5stack.com/sse` - **协议**: SSE (Server-Sent Events) + JSON-RPC over HTTPS ### 连接流程 1. **建立SSE连接**: GET `https://mcp.m5stack.com/sse` 2. **获取endpoint**: 接收 `event: endpoint` 事件，获取 `/messages?session_id=xxx` 3. **保持SSE连接**: 持续监听，JSON-RPC响应会通过SSE推送 4. **发送JSON-RPC请求**: POST 到返回的 `/messages?session_id=xxx` 端点 5. **接收响应**: 通过SSE连接接收 `event: message` 事件中的JSON-RPC响应 ### 可用工具 MCP 服务器当前提供以下工具： #### knowledge_search 从M5Stack产品知识库中检索相关信息。 **核心功能：** - 查询M5Stack产品的技术规格、参数、功能特性 - 检索产品兼容性、连接方式、引脚定义 - 获取编程API、代码示例、固件配置信息 - 查找芯片数据手册和技术细节 - 故障排除和常见问题解答 **必须触发此工具的场景：** 当用户询问涉及以下任何内容时，务必调用此工具： 1. M5Stack品牌及产品（Core、Atom、StickC、Paper、Dial、Capsule、加速卡等系列） 2. 硬件技术（模块、传感器、执行器、连接器、引脚、GPIO、接口、通讯协议如I2C/SPI/UART） 3. 编程开发（API、UIFlow、Arduino、MicroPython、ESP-IDF、固件、库函数、代码示例） 4. 技术参数（电气特性、尺寸、重量、SKU、兼容性、供电、功耗、热设计、性能指标） 5. 芯片相关（ESP32、芯片型号、数据手册、寄存器、技术规格） 6. 产品对比、选型建议、功能差异 7. 常见嵌入式问题解答（FAQ）、故障排除 **参数使用指南：** - `query`: 用清晰的关键词描述查询内容，必要时结合上下文重构查询语句 - `num`: 根据问题涉及的实体数量设置（默认1） * 询问单个产品/功能 → 1 * 对比2个产品 → 2 * 询问"有哪些"/"多少种"/"所有" → 3 * 多步骤操作或复杂问题 → 对应步骤数（最多5） - `is_chip`: 判断是否需要查询芯片数据手册 * 明确提到芯片型号、数据手册、寄存器 → true * 询问底层技术原理、电气特性 → true * 仅询问产品使用、编程API → false - `filter_type`: 指定查询的知识库类型 * "product": 查询所有产品文档（包括在售和EOL产品） * "product_no_eol": 查询在售产品文档 * "program": 查询全品类编程相关文档（包括Arduino、UIFlow、ESP-IDF） * "arduino": 专门查询Arduino开发相关文档 * "uiflow": 专门查询UIFlow开发相关文档 * "esp-idf": 专门查询ESP-IDF开发相关文档 * "esphome": 查询ESPHome官方文档 ### 工具脚本 skill提供以下Node.js脚本： 1. **scripts/mcp.mjs** - ES Module版本MCP客户端 - 提供 `mcpSearch(query, options)` 异步函数 - 支持ESM导入，兼容现代Node.js环境 2. **m5-search.mjs** - 命令行查询工具 - 无需编写代码，直接在终端快速查询文档 - 支持参数过滤，输出格式化结果 ## 关键注意事项 1. **始终基于官方资源** - 优先使用M5Stack官方文档和示例 2. **主动查询** - 不要猜测，有疑问就查 3. **严格复查** - 代码生成后必须复查 4. **准确理解问题** - 先明确用户需要什么类型的信息 5. **合理选择filter_type** - 根据问题类型选择合适的文档类型 6. **设备兼容性** - 注意不同M5Stack设备的差异 7. **库依赖** - 明确列出所需的开发库 8. **MCP服务状态** - 如果MCP服务不可用，降级使用官方文档站点: https://docs.m5stack.com