蓝海AIoT一站式工作台 | 自定义技能开发实践

借助 AI 生成 IoT 代码效率显著提升但随意输出、协议参数 “凭空猜测”往往大幅增加后期联调成本。针对这一痛点萤石蓝海 AIoT 一站式工作台支持自定义专属 Skill。合理规划 Skill 规则与知识库能够约束 AI 严格遵循接口文档与设备协议产出规范、可落地的业务代码。技能Skill的介绍技能Skill是一双能替开发者落地执行的实操之手不是一段要运行的代码。在项目对话框的技能选择入口里勾选某个技能就能把它“喂”给 AI。技能里的调用规范会注入到 AI 的上下文之后再用自然语言描述需求AI就会照着这份说明书生成代码而不是凭空猜。1.1 最大的误区写技能 ≠ 开发软件这是新手最容易踩的坑。技能里通常不需要写一个可以独立运行、需要部署的程序。它的产物是结构化的文字说明Markdown 为主核心是讲清楚“要用这个能力接口怎么调、参数怎么填、返回长什么样” 输入的是“说明书”AI 才是根据说明书写代码的“人”。1.2 技能能解决什么问题用 AI 生成应用时最常见的问题不是AI不会写代码而是它不知道接口/协议的真实规范。比如端口是多少、字段顺序如何、地址要不要偏移、异常怎么判断。它只能猜猜错了就反复改都对不上。而技能就是把这些规范固化下来让AI一次性写对。1.3 什么时候该自己写技能平台已内置一批技能萤石设备控制、云存储、Web 视频播放、消息推送、视觉模型等。当内置技能覆盖不了业务需求时就需要自己写自有设备的私有通信协议内部系统的业务 API特定行业协议如 Modbus、BACnet、GB/T 等专有的数据格式、编解码规则技能的组成一个技能是一个目录核心是一份 SKILL.md可选带若干附属目录。your-skill/├── SKILL.md # 核心技能主入口和骨架必需├── references/ # 分主题的详细规范文档按需读取可选├── scripts/ # 可直接复用的编解码/工具脚本可选└── assets/ # 模板、配置样例、测试数据等资源可选2.1 核心文件技能的主入口AI 激活技能时首先读它。它给出全貌这个技能是什么、何时用、核心概念、调用规范、参数、示例、注意事项。2.2 附属目录2.3 一份合格 SKILL.md的五块内容无论技能多简单输入的“说明书”正文都应覆盖能力说明这个技能能做什么、边界在哪调用/协议规范怎么连、怎么调参数定义每个参数含义、必填/选填、取值范围调用示例请求样例 返回样例注意事项易错点、边界、经验写好 Frontmatter让 AI 知道“何时该用”SKILL.md顶部是一段 YAML frontmatter决定技能是否会被识别和触发。这是最关键、也最容易被写差的部分。官方规范只定义 6 个字段必填 name、description可选 license、compatibility、metadata、allowed-tools。没有所谓的“触发模式”开关—技能是靠 description被模型自动发现并加载的写好 description 就等于写好了触发条件。---name: modbus-protocoldescription: Modbus 工业通信协议对接。当用户提到 Modbus、RTU、TCP、读写寄存器、功能码、PLC 通信 时使用此 Skill。---3.1 name命名规范全小写单词间用连字符 -语义清晰见名知意modbus-protocol、ezviz-device-control不要用空格、中文、大写3.2 description 的黄金写法能力概述 触发词description 不是给人看的简介而是 AI 判断“这个场景该不该激活本技能”的依据。写法 一句能力概述 明确的触发词/触发场景。为什么触发词决定成败AI 靠 description 里的关键词匹配用户意图。触发词写的全面用户随口一说就能命中写的宽泛技能就难以建立识别路径。好的写法有具体触发词Modbus 工业通信协议对接。当用户提到 Modbus、RTU、TCP、读写寄存器、功能码、PLC 通信、RS-485 设备通信 时使用此 Skill。差的写法太泛AI 不知道何时用帮助进行设备通信。触发词怎么选想想用户会怎么说—协议名、同义词、场景词、典型操作词都列上。3.3 可选字段与“如何被触发”技能没有inclusion之类的模式开关。它的加载机制是模型读所有已安装技能的 description判断与当前任务是否相关相关就自动加载正文不相关时几乎不占 token。所以“何时触发”完全由 description 决定这也是 3.2 强调触发词的原因。几个可选字段按需使用不用则省略在蓝海 AIoT 一站式工作台里还可以在项目对话框的【技能选择入口】主动勾选某个技能把它拉进上下文。这是平台提供的“手动引用”入口和“模型自动发现”并不冲突—好的 description 两种方式下都更可靠。写好 SKILL.md 正文把“怎么接入”讲清楚正文按第 2.3 节的五块展开。核心原则信息密度 篇幅能用表格和示例说清的就不要长篇大论。4.1 能力说明先给全貌与边界开门见山说清能做什么、不做什么。边界写清楚能避免 AI 越界生成。本 Skill 帮助在应用中正确实现 Modbus 协议通信覆盖 RTU / ASCII / TCP三种传输模式提供功能码定义、帧格式、CRC/LRC 校验、异常处理及可复用编解码代码。本 Skill 只负责协议编解码不含具体串口/socket 收发实现。4.2 核心概念速览陌生协议先建心智模型接入一个陌生协议AI和读代码的人都需要先有心智模型。用表格把概念固化下来最有效。Modbus 是请求/响应协议采用主从模型。四类数据模型| 数据块 | 访问 | 单位 | 典型功能码 | 地址惯例 ||--------|------|------|-----------|---------|| Coils线圈 | 读写 | 1 bit | 01 读 / 05,15 写 | 0xxxx || Discrete Inputs | 只读 | 1 bit | 02 读 | 1xxxx || Input Registers | 只读 | 16 bit | 04 读 | 3xxxx || Holding Registers | 读写 | 16 bit | 03 读 / 06,16 写 | 4xxxx |4.3 调用/协议规范怎么连、怎么调写清协议分层、地址、端口、鉴权、请求-响应格式。协议类要精确到字节 / 位 / 字段顺序。ADU 地址/头 PDU 校验PDU 功能码(1B) 数据(NB)先构造 PDU再按传输模式包装成 ADURTU| 从站地址 1B | PDU | CRC16 2B低字节在前|TCP| MBAP 头 7B | PDU |默认端口 5024.4 参数定义用表格锁死每个参数读保持寄存器功能码 0x03参数| 参数 | 必填 | 类型 | 取值范围 | 说明 ||------|------|------|----------|------|| slave_addr | 是 | int | 1–247 | 从站地址0 为广播 || start_addr | 是 | int | 0–65535 | 协议地址从 0 开始 || quantity | 是 | int | 1–125 | 读取寄存器个数 |4.5 调用示例给可直接套用的样例示例是 AI 复用率最高的部分。给请求 返回 结果解读。读从站 0x11 的保持寄存器起始地址 0读 1 个请求帧[11] [03] [0000] [0001] [CRC低] [CRC高]返回帧[11] [03] [02] [01 F4] [CRC低] [CRC高]解读字节数2值0x01F4500若手册说 ÷10则温度50.0°C4.6 注意事项把坑写在前面把你踩过的坑、边界、经验固化下来。这是资深经验的沉淀价值极高。地址偏移手册写 40001 → 协议发 0x0000减掉基址字节序CRC 低字节在前与寄存器大端相反异常判断响应功能码最高位 1 表示出错后跟异常码优先用成熟库pymodbus / libmodbus别手写协议栈面向“代码接入特定协议”的实战写法这是把技能从“AI 能看懂”升级到“AI 能据此写出可用接入代码”的关键一步。5.1 为什么协议接入类技能必须拆附属文件协议规范往往很长功能码几十个、帧格式好几种、异常码一大表。如果全塞进 SKILL.md上下文一次性膨胀挤占了描述需求的空间反而降低生成质量AI 每次都要读全部效率低正确做法SKILL.md 给全貌 索引细节下沉到 references/AI 按需读取。5.2 references/ 怎么写按主题拆分一个主题一个文件职责单一references/├── frame-formats.md # 三种传输模式的帧格式、CRC/LRC 算法├── function-codes.md # 每个功能码的 PDU 结构、参数、示例└── troubleshooting.md # 异常码、常见故障与排查关键要求内容要“可被 AI 直接翻译成代码”。精确到字节、位、字段顺序不留模糊用表格 / 伪代码固化规则减少歧义每个字段标清长度、字节序、取值范围反面教材“CRC 放在帧尾”——AI 不知道 2 字节还是 1 字节、什么字节序。正面写法| 字段 | 字节 | 说明 ||------|------|------|| CRC | 2 | 低字节在前高字节在后little-endian |5.3 scripts/ 怎么写对于有固定算法的协议校验、编解码、帧构造给一份可运行的参考代码作为“算法范本”让 AI 据其逻辑生成而不是凭空重写——重写极易出错。写法要点因为新建项目的语言由平台固定脚本主要作为算法逻辑的权威参照AI 会把它翻译到目标语言未必原样照搬。所以要把算法步骤和字节级细节写清楚可翻译性比“能直接跑”更重要零依赖或最小依赖纯标准库优先逻辑清晰易读每个函数写清用途、参数、返回、字节序附带用法示例顶部注释说明适用场景如“受限环境或需逐字节掌控时用否则优先成熟库”例如 scripts/modbus_codec.py 里的 CRC 实现def crc16(data: bytes) - int:计算 Modbus RTU CRC16多项式 0xA001初值 0xFFFF。crc 0xFFFFfor byte in data:crc ^ bytefor _ in range(8):if crc 0x0001:crc (crc 1) ^ 0xA001else:crc 1return crc 0xFFFFdef crc16_bytes(data: bytes) - bytes:返回 RTU 帧尾 CRC 的 2 字节低字节在前。return struct.pack(H, crc16(data))有了这段脚本AI 生成接入代码时会直接调用它CRC 一次就对。5.4 assets/ 怎么写放静态、可复制的资源减少 AI 编造连接参数模板串口 8E1、TCP 端口 502 等默认值配置文件样例测试数据 / 样例帧5.5 主文件与附属文件的引用/索引方式在 SKILL.md 里明确列出“何时读哪个文件”这样 AI 才知道去哪找细节## 参考文件按需深入阅读- 需要具体功能码的 PDU 结构 → 读 references/function-codes.md- 需要封装成可传输的帧含 CRC/LRC→ 读 references/frame-formats.md- 遇到异常响应或通信故障 → 读 references/troubleshooting.md- 需要现成编解码代码 → 用 scripts/modbus_codec.py5.6 协议接入通用要点清单写任何协议接入技能这些点都建议覆盖字节序大端/小端多字节数值跨字段的顺序地址偏移文档地址 vs 协议地址的换算超时与重试无响应怎么办异常响应如何判断和解析错误码帧定界 / 粘包怎么切分一帧成熟库优先列出各语言推荐库避免不必要的手写完整范例写一个“协议接入”技能6.1 目录结构modbus-protocol/├── SKILL.md├── references/│ ├── frame-formats.md│ ├── function-codes.md│ └── troubleshooting.md└── scripts/└── modbus_codec.py6.2 SKILL.md骨架示意---name: modbus-protocoldescription: Modbus 工业通信协议实现指南。当用户需要与 PLC、RTU、传感器、电表、变频器通信或提到 Modbus、RTU、ASCII、TCP、线圈、保持寄存器、功能码、CRC16、读写寄存器 时使用此 Skill。---# Skill: Modbus 工业通信协议## 能力说明本 Skill 帮助在应用中正确实现 Modbus 通信覆盖 RTU / ASCII / TCP。只负责协议编解码不含实际串口/socket 收发。## 何时使用- 与工业设备PLC、仪表、传感器通信- 读写线圈、离散输入、保持寄存器、输入寄存器## 核心概念速览四类数据模型表格、PDU/ADU 分层、字节序说明## 实现工作流1. 确定角色主站/从站2. 确定传输模式RTU/ASCII/TCP3. 确定通信参数4. 优先用成熟库5. 构造 PDU → 包装 ADU → 收发 → 校验 → 解析## 优先使用成熟库Python: pymodbus / minimalmodbusC: libmodbus...## 参考文件按需深入阅读- 功能码细节 → references/function-codes.md- 帧格式与 CRC → references/frame-formats.md- 异常与排查 → references/troubleshooting.md- 现成编解码代码 → scripts/modbus_codec.py## 注意事项- 地址偏移40001 → 0x0000- CRC 低字节在前- 异常码响应功能码最高位16.3 references/frame-formats.md片段## Modbus RTU| 从站地址 1B | PDU | CRC16 2B || 字段 | 字节 | 说明 ||------|------|------|| 从站地址 | 1 | 1–2470 广播 || CRC | 2 | 低字节在前高字节在后 |帧定界靠静默间隔帧前后静默 ≥ 3.5 字符时间T3.5波特率 19200 时 T3.5 固定取 1.750ms。6.4 scripts/modbus_codec.py片段见第 5.3 节的 crc16 / crc16_bytes另含 lrc、pdu_read、RTU/ASCII/TCP 帧构造与解析零依赖纯标准库可直接复用。6.5 使用效果用户在项目里勾选 modbus-protocol 技能后描述需求读取 1 号从站保持寄存器 40001 的温度串口 COM39600 8N1值除以 10在页面上展示AI 就会照着技能用平台当前项目的语言/框架生成代码并把地址偏移到 0、正确处理字节序和缩放、按需选用对应语言的成熟库一次写对。注意新建项目时平台会固定应用的开发语言/框架不可随意指定如不能强行要求用 Python 写应用。因此技能应尽量写成语言中立的协议/接口规范——描述“协议规则”而非“某语言实现”AI 才能按平台实际栈落地。scripts/ 里的参考代码是“算法范本”AI 会据其逻辑翻译到目标语言未必原样照搬。创建、上传与验证新建技能按第六章的目录结构组织文件SKILL.md必需。上传在工作台的技能管理入口上传技能目录。引用在项目对话框点击选择技能选中你的技能其调用规范即注入上下文。验证给一个真实接入需求看 AI 生成的代码是否贴合你的协议规范端口、地址、字节序、异常处理是否都对。不对就回到技能里补充规范或示例再验证。检查清单 常见问题8.1 提交前自查清单frontmatter 的 name 规范≤64 字符、小写/数字/连字符、description 含明确触发词没有误写 inclusion 等非规范字段可选字段allowed-tools 等按需使用五块内容齐全能力说明 / 调用规范 / 参数 / 示例 / 注意事项协议细节精确到字节、位、字段顺序无歧义有可直接套用的调用示例请求 返回 解读长规范已拆到 references/主文件有“何时读哪个文件“的索引固定算法提供了 scripts/ 可复用代码注意事项写清了坑字节序、地址偏移、异常判断等8.2 FAQQ技能没被触发怎么办A多半是 description 触发词不够。把用户可能说的关键词、同义词、场景词补全。QAI 生成的代码不贴合规范怎么办A说明规范写得不够具体。把出错的那部分如字节序、地址偏移用表格/示例固化尤其补一个正确的调用示例。Q技能太长导致效果变差怎么办A按主题把细节拆到 references/SKILL.md 只留全貌和索引让 AI 按需读取。Q写技能要会编程吗A核心是“把规范讲清楚”主要写 Markdown。只有 scripts/ 才涉及代码且多为可复用的参考实现不是必需项。萤石致力于成为全球领先的智能视觉物联网服务商构建了全球领先的视觉物联网云平台打造了硬件产品软件云服务一体化的物联网服务体系。萤石云通过构建多数据中心就近服务点的方式服务于全球客户。截至2025 年底萤石物联网云平台在全球拥有超过120 个数据站点平台上的IoT 设备接入数超过3.6 亿其中视频类设备超过3 亿。在夯实自身平台能力的基础上萤石进一步开放技术能力将物联价值延伸至千行百业。萤石开放平台深度融合AI中台能力涵盖音视频多媒体、消息通知处理、智能算法调度、视频存储备份、ERTC、大数据、物联接入等已为智慧连锁、智慧养老、文教娱乐、畜牧养殖等42万余位行业客户提供数智化转型升级支撑萤石物联专有云支持专有化部署助力中大型企业和组织的数字化转型升级。