扩展管理

扩展（Extension）是 NeoMind 的可插拔能力模块——视觉 AI、OCR、天气预报、自定义数据源等，都以扩展形式接入。扩展运行在独立进程中，通过 FFI 通信，单个扩展崩溃不会影响主服务，实现了真正的故障隔离。

只想装扩展？

直接跳到安装扩展，一键从扩展市场安装；完整扩展目录见下方表格。

什么是扩展？

扩展为 NeoMind 提供三类能力：

能力	说明	数据形态	典型示例
指标（Metric）	扩展产出的时序数据，写入 `telemetry.redb`，可在仪表板展示	按时间序列存储	天气扩展的 `temperature` 指标
命令（Command）	可被 AI Agent / API / 规则调用的操作，支持参数与返回值	输入参数 → 执行 → 返回 JSON	YOLO 扩展的 `detect` 命令
组件（Component）	仪表板自定义可视化组件（由扩展附带的前端 bundle 提供）	在仪表板编辑器中拖入	视频流扩展的实时画面组件

一个扩展可以同时声明多种能力。例如 yolo-video 同时提供指标（检测统计）、命令（单帧检测）和组件（实时画框画面）。

官方扩展

NeoMind-Extensions 仓库提供官方扩展，通过内置扩展市场一键安装（市场当前版本 2.14.0，共 26 个扩展，随扩展仓库发版更新；以下列表随市场持续更新）：

扩展 ID	类别	说明
`yolo-video`	视觉 AI	YOLOv11 实时视频流目标检测（RTSP/摄像头），ROI 统计与越线计数
`yolo-device-inference`	视觉 AI	绑定 NE101/NE301 设备图像流的自动 YOLOv8 检测（ROI 监控、越线检测）
`image-analyzer`	视觉 AI	图像理解与分析（ML 模型懒加载）
`face-recognition`	视觉 AI	人脸检测与识别
`locate-anything`	视觉 AI	LocateAnything 视觉定位：目标检测、短语定位、视觉 grounding
`video-vlm`	视觉 AI	实时视频流 VLM 语义理解（RTSP/文件，板载 LFM2.5-VL）
`ocr-device-inference`	OCR	绑定设备图像流的自动 OCR（SVTR 模型，输出带框结果）
`paddle-ocr-v6`	OCR	PP-OCRv6 原生 ONNX 推理（tiny/small/medium 多档模型）
`paddle-ocr-vl`	OCR	PaddleOCR-VL 高精度多语言 OCR、表格识别与关键信息抽取
`voice-assistant`	语音	实时语音助手编排：麦克风 → VAD → ASR → LLM → TTS → 扬声器
`sensevoice-asr`	语音	SenseVoice-Small 语音识别（中/英/日/韩/粤）
`cosyvoice-3`	语音	CosyVoice 3 流式 TTS（本机播放 + 合成 wav）
`moss-tts-nano`	语音	MOSS-TTS-Nano 音色克隆 TTS
`voice-edge-tts`	语音	Edge TTS（sherpa-onnx ZipVoice，CPU 流式合成）
`stream-player`	流媒体	通用视频播放：RTSP / RTMP / HLS / 本地文件（FFmpeg 转码）
`deepstream`	流媒体	NVIDIA DeepStream 桥接：远程视频管线与事件路由（NG4500）
`homeassistant-bridge`	桥接	Home Assistant 桥接：实体同步与控制
`lorawan-bridge`	桥接	LoRaWAN 桥接：连接 ChirpStack/TTN 传感器，自动发现设备
`modbus-bridge`	桥接	Modbus TCP/RTU：PLC、电表、工业传感器
`opcua-bridge`	桥接	OPC-UA：连接工业服务器，浏览节点、订阅数据
`bacnet-bridge`	桥接	BACnet/IP：楼宇自控设备发现与控制
`onvif-bridge`	桥接	ONVIF 摄像头：发现 IP 摄像头、RTSP 取流、PTZ 控制
`uink-rms-bridge`	桥接	Uink-RMS 墨水屏：设备注册、遥测采集、显示内容下发
`weather-forecast`	数据源	实时天气预报（多城市，OpenWeatherMap）
`gym-tracker`	行业	健身房运营套件：运动轨迹/热力/成员分析（扩展 + 仪表板组件）
`laya-decision`	工具	LAYA 决策层：托管 `/v1/systemone` sidecar 协议背后的 ONNX 决策运行时，附产物/审计监控与仪表板状态卡

市场索引随扩展仓库发版刷新。若你在市场里看到的扩展少于上表，说明平台加载的是上一版发布的索引，等下一次发布即可。

详细的端到端示例见应用案例。

界面总览

进入左侧导航的 Extensions 页签，可以看到当前已安装的全部扩展：

页面顶部工具栏提供三个操作：

按钮	图标	作用
刷新	RefreshCw（旋转箭头）	重新拉取扩展列表，查看最新状态
上传安装	Upload	打开本地 `.nep` 包安装对话框
扩展市场	Globe（地球）	打开官方扩展市场，一键下载安装

扩展卡片本身展示：扩展名称、版本号、当前状态（Running / Stopped / Error / Crashed）、提供的能力图标（指标 / 命令 / 组件）。点击卡片任意区域即可进入扩展详情页。

安装扩展

NeoMind 提供四种安装方式，按推荐度排序：

方式一：扩展市场（推荐）

点击工具栏的 地球图标 打开扩展市场对话框，NeoMind 会从官方仓库拉取可用的扩展列表：

在市场对话框中：

浏览可用的官方扩展（含名称、版本、简介、大小）
点击 Install 一键下载并安装
安装完成后扩展自动出现在列表中并启动

市场安装会自动选择与当前主服务 ABI 版本匹配的扩展包，无需手动选平台。

方式二：Web UI 上传

如果你已有 .nep 包（自己开发或从 Releases 下载），可以使用上传安装：

点击工具栏的 Upload 按钮
在弹出的对话框中拖入或选择 .nep 文件
NeoMind 自动校验包完整性（manifest / 格式 / 平台二进制）与 ABI 版本
校验通过后解包、加载、启动

提示

官方 .nep 包按平台分发（如 weather-forecast-2.14.0-linux_amd64.nep）。市场安装会自动选择与当前平台和主服务 ABI 版本匹配的扩展包，无需手动挑选；从 Releases 手动下载时请选择对应平台目录下的包。市场源可在系统设置 → Preferences 中切换镜像。

方式三：CLI

# 安装本地 .nep 包
neomind extension install /path/to/weather-forecast.nep

# 从 URL 安装（适合自动化部署，注意选择对应平台的包）
neomind extension install https://github.com/camthink-ai/NeoMind-Extensions/releases/download/v2.14.0/weather-forecast-2.14.0-linux_amd64.nep

# 列出已安装扩展
neomind extension list

install / info / uninstall 等全部子命令见下文 CLI 参考。

方式四：AI Chat

直接对 AI Chat 说：

「帮我安装天气扩展」

LLM 会引导你上传 .nep 包或提供下载链接，并自动调用 extension install 命令完成安装。

扩展详情与配置

点击任意扩展卡片进入详情页。详情页采用左右布局：左侧是五个功能区的导航，右侧是对应内容。下面分别介绍每个标签页。

1. Overview（总览）

总览页展示扩展的基本信息：

扩展 ID：唯一标识（如 yolo-device-inference），用于 API 调用、数据源绑定
名称与版本：人类可读名称 + SemVer 版本号
状态：当前运行状态（Running / Stopped / Error / Warning / Crashed）
能力声明：扩展提供的能力类型（指标数 / 命令数 / 组件数）
描述：扩展的功能说明
ABI 版本：扩展编译时对应的 ABI 版本（必须与主服务匹配）

2. Configuration（配置）

部分扩展需要配置参数才能运行（如天气扩展需要 API Key）。切换到 Configuration 标签页进行配置：

配置参数按类型自动渲染为合适的输入控件：

参数类型	控件	校验规则
`string`	文本输入框	必填校验、最大长度
`string`（名称含 `password`）	密码输入框（掩码）	必填校验
`string` + `enum`	下拉选择	只能选预定义值
`integer` / `number`	数字输入框	最小值 / 最大值范围
`boolean`	开关（Switch）	true / false

填写完成后点击 Save，配置会先按 schema 校验（越界数字、必填留空会在保存时报错，不会写入），随后热更新到运行中的扩展进程——多数参数无需重启即可生效。

提示

保存后会尝试把新配置推送给运行中的扩展（热更新）。若热更新失败（或扩展只在启动时读取配置），配置已保存，执行 neomind extension reload <id> 或在详情页操作菜单重启后生效。

3. Commands（命令）

命令是扩展暴露的可调用操作。切换到 Commands 标签页查看所有命令：

每个命令卡片展示：

命令名称：如 detect、ocr_recognize
描述：命令功能说明
参数表单：点击 展开按钮 后显示该命令的参数输入表单
Execute 按钮：填写参数后点击执行，结果以 JSON 形式返回并显示在下方

提示

命令执行支持手动测试，也支持被 AI Agent / REST API / 自动化规则调用。手动测试是验证扩展是否正常工作的最快方式。

4. Metrics（指标）

指标是扩展产出的时序数据。切换到 Metrics 标签页查看历史数据：

指标页提供：

时间范围选择：1 小时 / 24 小时 / 7 天 / 30 天
指标列表：扩展产出的所有指标（如 detection_count、avg_confidence）
趋势图：选中指标后展示历史曲线
最新值：当前指标的实时数值

指标数据源格式：extension:<extension_id>:<metric_name>，可在仪表板中作为组件数据源使用。

5. Logs（日志）

日志页实时展示扩展进程的标准输出与错误输出：

特点：

自动刷新：每 3 秒拉取一次新日志
滚动到底部：新日志自动滚动到视图底部
错误高亮：ERROR / WARN 级别日志会用红色 / 黄色高亮显示
保留行数：默认保留最近 2000 行

排查扩展问题时，日志页是第一现场。如果扩展状态为 Error 或 Crashed，日志通常能直接看到 panic 堆栈或初始化失败原因。

扩展状态与生命周期

状态	图标	说明	触发条件
Running	绿色圆点	扩展正常运行中	安装完成 / 手动启动 / 自动恢复
Stopped	灰色圆点	扩展已停止	手动停止 / 配置变更重启中
Error	红色圆点	扩展崩溃或加载失败	进程异常退出 / 初始化失败
Warning	黄色圆点	扩展健康检查有告警	运行异常但未崩溃
Crashed	红色标签	因崩溃停止自动重启的已停止扩展（悬停显示崩溃原因与连续崩溃次数）	连续崩溃触发崩溃循环保护后进入

重启 / 重载扩展

# 重载（重启）扩展进程
neomind extension reload <extension_id>

# 查看扩展状态
neomind extension status <extension_id>

启动 / 停止目前通过 REST API 提供（POST /api/extensions/:id/start / stop，见下文），CLI 侧用 extension reload 即可完成重启。

也可以在扩展详情页通过 操作菜单 进行启动 / 停止 / 重启 / 卸载。

崩溃保护

扩展运行在独立进程中，NeoMind 通过多层机制保障主服务稳定性：

进程隔离 — 扩展崩溃不影响 API、MQTT、仪表板、其他扩展
自动重启 — 扩展进程异常退出后自动重启，最多重试 3 次，每次间隔 5 秒
挂起检测 — 每个扩展进程有 liveness 探测（Ping），无响应的挂起进程会被判定为崩溃并进入重启流程
崩溃循环检测 — 连续崩溃 ≥ 3 次且最后一次崩溃发生在 50 秒冷却窗口内时，判定为崩溃循环，停止自动重启（扩展显示为 Crashed 状态），防止资源耗尽
应用内通知 — 扩展停止自动重启时，系统会发送一条应用内消息，运维人员会收到告警

因崩溃循环停止自启的扩展需要人工介入排查：

# 查看扩展崩溃原因与状态（推荐）
neomind extension info <extension_id>

# 或直接在扩展详情页的 Logs 标签页查看 panic 堆栈
# 修复后手动重启
neomind extension reload <extension_id>

常见崩溃原因：模型文件缺失、API Key 无效、端口被占用、ABI 版本不匹配。

扩展卡死（进程存活但不响应）同样有防护：宿主每 30 秒发送一次存活探测，连续失败会终止进程并自动重启——与崩溃走同一套恢复机制。扩展列表中状态为 Crashed 表示该扩展是崩溃停止（而非手动停止），悬停可见崩溃原因与连续次数。

使用扩展数据

在仪表板中

扩展指标和设备指标使用方式完全一致。在仪表板编辑器中添加组件时，数据源选择扩展指标：

DataSourceId 格式：extension:<extension_id>:<metric_name>
示例：extension:weather-forecast:temperature
组件型扩展会出现在组件库的 Extension Components 分类下，直接拖入即可

在 AI Chat 中

直接对 AI Chat 说：

「调用天气扩展，查一下上海明天会下雨吗？」

LLM 会自动识别扩展命令、填充参数、调用并解读返回结果。

在 AI Agent 中

Agent Focused 模式可绑定：

扩展指标 作为数据源（用于周期性分析）
扩展命令 作为工具（用于 LLM tool calling）

Agent 在执行时会自动调用扩展命令完成推理-执行闭环。

在自动化规则中

自动化规则可用扩展指标做条件，或调用扩展命令做动作：

{
  "name": "高温预警",
  "trigger": { "trigger_type": "schedule", "cron": "0 0 18 * * *" },
  "condition": {
    "condition_type": "comparison",
    "source": "extension:weather-forecast:tomorrow_temp",
    "operator": "greater_than",
    "threshold": 35
  },
  "actions": [
    { "type": "notify", "message": "明日高温预警，请做好防暑准备" }
  ]
}

安全校验

市场安装会校验包的 SHA256（来源为发布产物附带的 checksums.txt）；校验失败会拒绝安装。对完整性要求更高的部署可设置环境变量 NEOMIND_STRICT_PACKAGE_SHA256=1——元数据中无校验和的包将一律拒装。本地安装的 .nep 会经过路径穿越与压缩炸弹防护，符号链接条目一律拒绝。

扩展包格式（.nep）

.nep 是 NeoMind 扩展的标准打包格式，本质是一个 ZIP 包：

weather-forecast.nep
├── manifest.json          # 扩展元数据（format/abi_version/id/版本/能力声明 + binaries 平台映射）
├── binaries/
│   └── linux_amd64/       # 平台目录（.nep 按平台分发，通常只含当前平台）
│       └── extension.so
├── frontend/              # 可选：仪表板组件 bundle + frontend.json
└── models/                # 可选：ML 模型文件

备注

扩展需匹配主服务的 ABI 版本（当前 v3）。不匹配的扩展会被拒绝加载，安装 / 加载时报 "Incompatible version"（ABI 版本不兼容）错误。

详细的 .nep 结构与开发流程见开发指南 - 扩展开发。

CLI 参考

# 列表
neomind extension list                              # 列出所有已安装扩展
neomind extension list -v                           # 详细输出（指标 / 命令信息）

# 安装 / 卸载
neomind extension install <path-or-url>             # 安装（本地路径或 URL）
neomind extension uninstall <extension_id>          # 卸载

# 详情与状态
neomind extension info <extension_id>               # 查看元数据、指标、命令、配置参数
neomind extension status <extension_id>             # 查看运行状态（进程、uptime、最近错误、资源占用）

# 生命周期控制
neomind extension reload <extension_id>             # 重载（重启进程；启动/停止走 REST API）

# 配置
neomind extension config <extension_id>             # 查看当前配置
neomind extension config <extension_id> --set '{"city":"Beijing"}'  # 修改配置项（JSON 对象）

开发扩展还会用到 extension validate（安装前校验 .nep 包）、extension create（脚手架）、extension build（编译打包）、extension logs（进程日志）与 extension market-list / market-install（市场安装）。CLI 通过 NEOMIND_API_KEY 环境变量或 --api-key 参数认证。

REST API

扩展管理也提供 REST API，方便集成到外部系统：

# 列出所有扩展
curl -H "X-API-Key: $NEOMIND_API_KEY" http://localhost:9375/api/extensions

# 查询单个扩展详情
curl -H "X-API-Key: $NEOMIND_API_KEY" http://localhost:9375/api/extensions/<extension_id>

# 启动 / 停止 / 重启
curl -X POST -H "X-API-Key: $NEOMIND_API_KEY" \
     http://localhost:9375/api/extensions/<extension_id>/start

curl -X POST -H "X-API-Key: $NEOMIND_API_KEY" \
     http://localhost:9375/api/extensions/<extension_id>/stop

curl -X POST -H "X-API-Key: $NEOMIND_API_KEY" \
     http://localhost:9375/api/extensions/<extension_id>/reload

# 调用扩展命令
curl -X POST -H "X-API-Key: $NEOMIND_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"command":"detect","args":{"image_url":"https://example.com/test.jpg"}}' \
     http://localhost:9375/api/extensions/<extension_id>/command

扩展相关接口的权威清单见开发指南 — REST API 参考。

故障排查

快速诊断

遇到扩展问题时，先运行以下命令收集信息：

# 查看所有扩展状态
neomind extension list

# 查看具体扩展的元数据和最近错误
neomind extension info <extension_id>

# 查看扩展进程日志文件
neomind extension info <extension_id>   # 含最近错误；实时日志用详情页 Logs 标签页

# 查看主服务日志中的扩展相关条目
journalctl -u neomind.service | grep -i extension

也可以直接打开扩展详情页的 Logs 标签页实时查看进程输出。

常见问题

问题	可能原因	解决方案
安装后扩展显示 Error	ABI 版本不匹配 / 二进制加载失败	升级扩展或主服务到匹配的 ABI 版本（当前 v3）；查看详情页 Logs 确认具体错误
安装报 `Unsupported platform`	`.nep` 包不含当前平台的二进制	确认包内含对应平台二进制目录（如 macOS arm64 需 `binaries/darwin_aarch64/`）；从官方源重新下载完整包
安装报 `Extension already registered`	扩展 ID 已存在	先 `neomind extension uninstall <id>` 卸载旧版，再安装新版
扩展启动超时（120s 后 Error）	模型文件过大 / 初始化逻辑阻塞	查看详情页 Logs 确认卡在哪一步；如果是模型加载慢，耐心等待或减小模型
扩展因崩溃循环停止自启（显示 Crashed）	初始化失败 / 模型缺失 / 端口冲突	连续崩溃 3 次触发保护。查看 Logs 找根因，修复后 `neomind extension reload <id>`
扩展指标在仪表板不显示	扩展未配置 / DataSourceId 拼写错误	确认格式为 `extension:<id>:<metric>`；打开详情页 → Metrics 查看实际指标名
AI 无法调用扩展命令	扩展已停止	在 Extensions 页签启动扩展，确认状态为 Running
命令执行超时	推理耗时过长 / 输入过大	默认超时 300 秒；压缩输入图片、减小 batch size，或检查网络连接
扩展安装后无可视化组件	该扩展未提供 Component 能力	只有声明了 frontend bundle 的扩展才有仪表板组件；在详情页 Overview 查看能力声明
配置保存后未生效	扩展不支持热更新 / 仅启动时读取配置	保存后 `neomind extension reload <id>` 重启扩展进程再验证
市场安装失败 / `Checksum failed`	网络中断 / 包损坏	重新点击 Install；检查网络代理设置；或改用 CLI 从 GitHub Releases 下载安装

更多通用排查技巧见故障排查。

自己开发扩展？

扩展开发完整教程见开发指南 - 扩展开发，包含：

从零创建 Rust 扩展项目
ExtensionMetadata::new() 构建器用法
neomind_export!() 宏导出 FFI 入口
三种能力（指标 / 命令 / 组件）的实现模式
跨平台打包（5 个平台目标）
ML 模型生命周期管理（懒加载、会话内保活）

下一步

应用案例 — 看扩展在实际场景中怎么用（目标检测 / OCR / 人脸识别）
仪表板 — 扩展提供的可视化组件怎么在仪表板上展示
AI Agent — 让 Agent 调用扩展命令，实现自动化巡检
自动化规则 — 用扩展指标做条件触发告警与动作

最后更新: 2026-10-21

什么是扩展？​

官方扩展​

界面总览​

安装扩展​

方式一：扩展市场（推荐）​

方式二：Web UI 上传​

方式三：CLI​

方式四：AI Chat​

扩展详情与配置​

1. Overview（总览）​

2. Configuration（配置）​

3. Commands（命令）​

4. Metrics（指标）​

5. Logs（日志）​

扩展状态与生命周期​

重启 / 重载扩展​

崩溃保护​

使用扩展数据​

在仪表板中​

在 AI Chat 中​

在 AI Agent 中​

在自动化规则中​

安全校验​

扩展包格式（.nep）​

CLI 参考​

REST API​

故障排查​

快速诊断​

常见问题​

自己开发扩展？​

下一步​