1. 从一次 Modbus 采集翻车说起为什么需要自定义技能如果你做过工业设备接入大概率遇到过这种场景手头有一台支持 Modbus RTU 的温湿度变送器手册上写着“保持寄存器 40001温度值除以 10”你让 AI 帮忙写一段采集代码它给你生成了read_holding_registers(40001, 1)跑起来直接超时或者返回一堆乱码。问题不在 AI 不会写代码而在于它不知道你手里这台设备的真实协议规范——地址要不要偏移、CRC 字节序是低字节在前还是高字节在前、串口参数是 8N1 还是 8E1这些细节 AI 只能猜。蓝海 AIoT 一站式工作台里的自定义技能Skill就是来解决这个问题的。简单说技能是一份写给 AI 看的“设备接入说明书”用 Markdown 写成核心文件叫 SKILL.md。你把 Modbus 的帧格式、功能码、地址换算规则、异常判断逻辑固化进去AI 在生成代码时就会照着这份说明书来而不是凭空编造。它适合三类人一是手里有私有协议设备、平台内置技能覆盖不到的开发者二是做工业网关、边缘采集盒需要批量接入 Modbus 设备的团队三是想用自然语言快速生成设备接入代码、又不想反复联调的物联网应用开发者。我试过用一份写好的 modbus-protocol 技能让 AI 生成读取从站 1 号保持寄存器温度值的代码从地址偏移到 CRC 校验一次通过省掉了至少两轮联调。下面把从 SKILL.md 编写到 Modbus 采集回读的完整链路拆开讲。2. TaoToken 前置准备把模型调用链路先跑通在写技能之前得先确保你的 AI 代码生成链路是通的。蓝海 AIoT 工作台本身集成了模型对话能力但如果你想像我一样在本地用 Claude Code 或者 Cline 这类编码工具来辅助调试技能文件、生成采集脚本就需要一个稳定的模型 API 入口。TaoToken 提供的就是这个入口它把多家模型的调用统一成一套 OpenAI 兼容接口你不需要分别去申请各家 Key。先拿到 API Key。访问 https://taotoken.net/api-keys 创建一个密钥复制出来存好。注意这个 Key 只在创建时显示一次丢了就得重新建。然后确认你要用的模型 ID比如claude-sonnet-4-20250514或者gpt-4o具体以控制台模型列表为准。Base URL 填https://taotoken.net/api不要加多余的路径后缀。如果你用的是 Claude Code配置方式是在项目根目录建.claude/settings.json写入{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }如果你用的是 Cline 或者 Roo Code 这类 VS Code 插件在设置里选 OpenAI CompatibleBase URL 填https://taotoken.net/apiAPI Key 填你的 KeyModel ID 填上面那个模型名。Codex 的话在~/.codex/auth.json里配置{ openai_api_key: sk-你的Key, base_url: https://taotoken.net/api }这三件套——Base URL、Key、Model ID——缺一不可。配好之后你可以先用模型对话页面 https://taotoken.net/model-chat 发一句“你好”验证链路是否通。如果返回正常说明模型调用没问题接下来写技能、生成采集代码就都有保障了。长期做编码和 Agent 调试的话Coding Plan 会更划算具体在 https://taotoken.net/coding-plan 看。3. 可复制配置SKILL.md 模板与 Modbus 点位定义技能目录结构建议这样组织SKILL.md 是必需的主入口references 放分主题的详细规范scripts 放可复用的编解码脚本modbus-protocol/ ├── SKILL.md ├── references/ │ ├── frame-formats.md │ ├── function-codes.md │ └── troubleshooting.md └── scripts/ └── modbus_codec.pySKILL.md 顶部的 YAML frontmatter 决定技能能否被 AI 识别和触发这是最关键的部分。官方只定义 6 个字段必填name和description可选license、compatibility、metadata、allowed-tools。没有所谓的“触发模式”开关技能靠 description 里的关键词被模型自动发现。写法是“一句能力概述 明确触发词”--- name: modbus-protocol description: Modbus 工业通信协议对接。当用户提到 Modbus、RTU、TCP、读写寄存器、功能码、PLC 通信、RS-485 设备通信、线圈、保持寄存器、CRC16 时使用此 Skill。 ---name 必须全小写、单词间用连字符不要用空格或中文。description 里的触发词要覆盖用户可能说的各种说法协议名、同义词、场景词、典型操作词都列上。正文部分按五块展开能力说明、核心概念、调用规范、参数定义、调用示例、注意事项。Modbus 的四类数据模型用表格固化最有效数据块访问单位典型功能码地址惯例Coils线圈读写1bit01读 / 05,15写0xxxxDiscrete Inputs只读1bit02读1xxxxInput Registers只读16bit04读3xxxxHolding Registers读写16bit03读 / 06,16写4xxxx读保持寄存器功能码 0x03的参数定义参数必填类型取值范围说明slave_addr是int1–247从站地址0 为广播start_addr是int0–65535协议地址从 0 开始quantity是int1–125读取寄存器个数调用示例给请求帧和返回帧让 AI 能直接套用。读从站 0x11 的保持寄存器起始地址 0读 1 个请求帧[11] [03] [0000] [0001] [CRC低] [CRC高] 返回帧[11] [03] [02] [01 F4] [CRC低] [CRC高] 解读字节数2值0x01F4500若手册说 ÷10则温度50.0°C注意事项里把坑写前面地址偏移手册 40001 → 协议发 0x0000、CRC 低字节在前、异常响应功能码最高位为 1、优先用成熟库pymodbus / libmodbus别手写协议栈。references/frame-formats.md 里写清 RTU 帧格式| 从站地址 1B | PDU | CRC16 2B | | 字段 | 字节 | 说明 | |------|------|------| | 从站地址 | 1 | 1–2470 广播 | | CRC | 2 | 低字节在前高字节在后 |帧定界靠静默间隔帧前后静默 ≥ 3.5 字符时间T3.5波特率 19200 时 T3.5 固定取 1.750ms。scripts/modbus_codec.py 里放 CRC 实现零依赖纯标准库import struct def crc16(data: bytes) - int: 计算 Modbus RTU CRC16多项式 0xA001初值 0xFFFF。 crc 0xFFFF for byte in data: crc ^ byte for _ in range(8): if crc 0x0001: crc (crc 1) ^ 0xA001 else: crc 1 return crc 0xFFFF def crc16_bytes(data: bytes) - bytes: 返回 RTU 帧尾 CRC 的 2 字节低字节在前。 return struct.pack(H, crc16(data))有了这段脚本AI 生成接入代码时会直接调用它CRC 一次就对。SKILL.md 里要明确列出“何时读哪个文件”的索引比如“需要具体功能码的 PDU 结构 → 读 references/function-codes.md”这样 AI 才知道去哪找细节。4. 验证请求与成功结果技能加载与采集回读技能文件准备好后在工作台的技能管理入口上传整个目录。上传成功后在项目对话框的技能选择入口勾选modbus-protocol它的调用规范就注入到 AI 上下文了。接下来用自然语言描述采集需求“读取 1 号从站保持寄存器 40001 的温度串口 COM39600 8N1值除以 10在页面上展示”。AI 会照着技能生成代码。以 Python 为例它应该生成类似这样的采集脚本from pymodbus.client import ModbusSerialClient from modbus_codec import crc16_bytes client ModbusSerialClient( portCOM3, baudrate9600, bytesize8, parityN, stopbits1, timeout1 ) client.connect() # 手册 40001 → 协议地址 0x0000 result client.read_holding_registers(address0, count1, slave1) if not result.isError(): raw result.registers[0] temperature raw / 10.0 print(f温度: {temperature}°C) else: print(f采集异常: {result}) client.close()验证时重点看几个点地址是否从 40001 偏移到了 0、串口参数是否匹配 8N1、返回值是否做了除以 10 的缩放、异常分支是否处理了isError()。如果这些都对说明技能规范被正确执行了。实测下来一份写清楚的 SKILL.md 能让 AI 生成的采集代码一次跑通省掉反复改地址和字节序的时间。如果采集结果不对比如返回Exception Response先检查从站地址和功能码是否匹配设备手册如果返回空值检查串口是否被占用、波特率是否一致。技能里的 troubleshooting.md 应该把这些常见故障和排查步骤写进去AI 遇到报错时会参考它给出排查建议。5. 本篇常见错排查401、local proxy failed 与 OAuth 报错配置过程中最容易卡住的是模型调用链路。下面几个报错我实际遇到过对照排查能省不少时间。401 UnauthorizedKey 填错或者没生效。检查ANTHROPIC_API_KEY或openai_api_key是否完整复制有没有多余空格。如果用的是 Claude Code确认.claude/settings.json里的ANTHROPIC_BASE_URL是https://taotoken.net/api不要写成带/v1的路径。Key 创建后只在控制台显示一次如果丢了就重新建一个。local proxy failed / connection refused本地代理配置冲突。如果你之前配过其他工具的代理环境变量里可能有HTTP_PROXY或HTTPS_PROXY指向了不存在的端口。在终端执行echo $HTTP_PROXY检查有的话临时 unset 掉再试。Cline 插件里如果开了“使用系统代理”选项关掉它直接用 Base URL 直连。reading choices 报错 / 返回格式异常模型 ID 写错了或者接口返回的不是 OpenAI 兼容格式。确认 Model ID 和控制台模型列表一致比如claude-sonnet-4-20250514不要写成claude-sonnet-4。如果用的是 Codex检查auth.json里base_url字段名是否正确有些版本要求写api_base。OAuth 相关报错Claude Code 首次启动会尝试 OAuth 登录如果你已经配了 API Key在 settings.json 里加ANTHROPIC_AUTH_MODE: api_key跳过 OAuth 流程。或者直接在终端执行claude --api-key sk-你的Key启动。排查完这些模型调用链路就稳了。技能加载和采集验证过程中如果遇到 AI 生成的代码不贴合规范多半是 SKILL.md 里规范写得不够具体把出错的那部分用表格或示例固化尤其补一个正确的调用示例再重新验证。6. 语义一致 CTA从技能开发到长期编码技能写好后日常调试和迭代会频繁用到模型对话来验证 SKILL.md 的表述是否清晰、生成的采集代码是否符合预期。你可以直接在模型对话页面 https://taotoken.net/model-chat 里粘贴技能片段让模型模拟生成代码快速检验规范有没有歧义。如果你需要频繁生成和调试设备接入代码或者在做多设备批量接入的 Agent 工作流Coding Plan 的额度更充足适合长期编码场景详情在 https://taotoken.net/coding-plan 看。接入文档和更多配置示例在 https://taotoken.net/doc 可以查到API Key 管理入口在 https://taotoken.net/api-keys。技能开发的核心不是写代码而是把设备协议规范讲清楚。一份好的 SKILL.md 能让 AI 从“猜着写”变成“照着写”Modbus 采集只是其中一个场景换成 BACnet、GB/T 或者你自家的私有协议思路是一样的能力说明、调用规范、参数定义、调用示例、注意事项五块写全细节下沉到 references固定算法放 scripts。写完上传勾选技能用自然语言描述需求看生成的代码是否贴合规范不对就回来补规范。这个循环跑顺了设备接入的效率会有明显提升。