企业官网建设流程全解析

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 Compatible，Base URL 填https://taotoken.net/api，API Key 填你的 Key，Model 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.py

SKILL.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 的四类数据模型用表格固化最有效：

读保持寄存器（功能码 0x03）的参数定义：

调用示例给请求帧和返回帧，让 AI 能直接套用。读从站 0x11 的保持寄存器，起始地址 0，读 1 个：

请求帧：[11] [03] [0000] [0001] [CRC低] [CRC高] 返回帧：[11] [03] [02] [01 F4] [CRC低] [CRC高] 解读：字节数=2，值=0x01F4=500，若手册说 ÷10，则温度=50.0°C

注意事项里把坑写前面：地址偏移（手册 40001 → 协议发 0x0000）、CRC 低字节在前、异常响应功能码最高位为 1、优先用成熟库（pymodbus / libmodbus）别手写协议栈。

references/frame-formats.md 里写清 RTU 帧格式：

| 从站地址 1B | PDU | CRC16 2B | | 字段 | 字节 | 说明 | |------|------|------| | 从站地址 | 1 | 1–247（0 广播） | | 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 的温度，串口 COM3，9600 8N1，值除以 10，在页面上展示”。AI 会照着技能生成代码。以 Python 为例，它应该生成类似这样的采集脚本：

from pymodbus.client import ModbusSerialClient from modbus_codec import crc16_bytes client = ModbusSerialClient( port="COM3", baudrate=9600, bytesize=8, parity="N", stopbits=1, timeout=1 ) client.connect() # 手册 40001 → 协议地址 0x0000 result = client.read_holding_registers(address=0, count=1, slave=1) 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 Unauthorized：Key 填错或者没生效。检查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。写完上传，勾选技能，用自然语言描述需求，看生成的代码是否贴合规范，不对就回来补规范。这个循环跑顺了，设备接入的效率会有明显提升。