Files

T

2026-07-14 15:43:18 +08:00

4.9 KiB

Raw Blame History

name, description

name	description
edge-mcp-tools	edge_collector 边缘侧本地模型与 MCP 工具接入规范。用于在鲁班猫/RK3566/RK3576/RK3588 等边缘设备部署本地模型后，设计或实现 MCP 工具服务，让模型安全调用网关状态、设备点位、历史数据、诊断、配置查询和运维只读能力。

edge_collector MCP 工具接入

目标

让边缘侧本地模型可以通过受控工具访问网关能力，而不是直接读取任意文件、执行任意命令或绕过现有服务。

典型链路：

本地模型
  -> MCP Client
  -> edge MCP tools
  -> configurator / collector / 本地数据库 / 只读诊断命令

适用场景

在 RK3566/RK3576/RK3588 鲁班猫上部署 Qwen 等本地模型。
给本地模型增加“查询设备状态”“分析点位趋势”“解释报警”“读取网关状态”等工具。
把边缘侧诊断能力封装成 AI 可调用工具。
设计 MCP 工具权限、输入输出和安全边界。

设计原则

默认只读。
工具服务独立运行，不耦合 edge 主服务。
本地模型不直接访问数据库文件、配置文件和 shell。
所有工具必须有明确输入 schema、输出 schema 和错误语义。
写配置、重启服务、删除数据等高风险动作第一版不开放。
工具返回用户可理解信息，不泄露密钥、路径、Token、内部模型配置。

工具命名

使用 edge_ 前缀。
动词清晰：get、list、query、analyze。
避免泛化工具名，例如 run_command、read_file。

输入输出

输入必须限制范围：

gateway_id
device_id 或 device_name
point_id 或 point_name
time_range
limit

输出建议结构：

{
  "ok": true,
  "data": {},
  "warnings": [],
  "source": "configurator",
  "timestamp": "2026-06-16T00:00:00+08:00"
}

错误要可行动：

{
  "ok": false,
  "error_code": "DEVICE_NOT_FOUND",
  "message": "未找到指定设备，请确认设备名称或 ID",
  "suggestion": "可先调用 edge_list_devices 查看可用设备"
}

与现有服务集成

优先通过现有 API 或受控本地接口访问：

configurator API。
collector 状态接口或已有数据接口。
本地只读数据库查询。
systemd 只读状态命令。

不要绕过业务逻辑直接修改配置文件。

本地模型注意

参考已有本地模型文档：

docs/本地模型/Qwen2.5-0.6B-Instruct在RK3566本地部署方案.md
docs/本地模型/Qwen2.5-VL-3B-Instruct在RK3576鲁班猫3边缘图文模型部署方案.md
docs/本地模型/Qwen2.5-14B-Instruct在16G_RK3588鲁班猫5部署方案.md

设计工具时必须考虑：

模型上下文有限，工具返回要摘要化。
RK3566/RK3576 资源有限，工具查询要分页、限流。
大历史数据先聚合摘要，再按需返回异常片段。
离线运行时不要依赖云端 AI Provider。

安全边界

结合 edge-security-secrets：

不返回 API Key、JWT、MQTT 密码、SSH 密码。
不暴露真实配置文件完整内容。
不开放任意命令执行。
日志中记录工具名、参数摘要、耗时、结果状态，不记录敏感值。
对外接口只监听本机或受控内网，默认不暴露公网。

部署方式

第一版建议使用 Python 独立 agent：

遵循 edge-python-agent。
使用 systemd 独立托管。
配置文件动态生成但不覆盖已有配置。
打包和同步遵循 edge-config-lifecycle。

服务名建议：

edge-mcp-tools

验证计划

至少验证：

工具列表可发现。
每个工具 schema 正确。
正常查询返回结构化数据。
设备不存在、点位不存在、时间范围过大时错误可理解。
返回内容脱敏。
大数据查询有 limit 或摘要。
服务重启后配置保留。
本地模型能完成一个端到端问题，例如“分析最近 1 小时某设备是否异常”。

文档输出

设计 MCP 工具时输出：

## 工具清单

## 权限边界

## 输入输出 schema

## 数据来源

## 部署方式

## 安全与脱敏

## 验证计划

4.9 KiB Raw Blame History Unescape Escape