协议适配助手
一、功能介绍
协议适配助手用于辅助设备协议接入。用户在 AI 会话中上传协议文档、字段表、报文样例或抓包资料后，系统会自动识别为协议解析场景，并尝试提取协议结构、报文类型、字段定义、编解码规则、物模型映射和质量问题。
当前版本不需要用户手动创建协议适配任务。上传协议资料后，系统会在后台自动创建适配记录并推进解析流程，用户主要在 AI 会话中查看处理状态、解析结果和下一步建议。
协议适配助手可以降低协议理解和代码生成的工作量，但不能替代真实设备联调。协议上线前仍需要开发人员确认字段、校验算法、设备认证、上下行流程和样例报文。
二、操作路径
AI 赋能 > AI 会话进入 AI 对话后，可以选择“自动识别”，也可以切换到“协议解析”模式后再上传资料。不同版本菜单名称可能略有差异，以实际管理端为准。
三、使用前准备
使用协议适配前，建议先完成：
- 已配置并启用可用的对话模型。
- 如有协议领域资料，先维护并发布协议知识库。
- 准备原始协议文档、字段表、报文样例、抓包日志或设备手册。
- 明确协议编码方式、字节序、校验算法、设备标识、认证流程和上下行方向。
- 准备可用于验证的真实样例报文。
源协议资料支持常见文档和数据文件，例如 .pdf、.doc、.docx、.txt、.md、.xls、.xlsx、.csv、.json。
四、整体流程
用户不需要在协议适配页面手动新建任务。会话上传后，系统会自动保存资料、执行协议解析、进行质量门禁，并在条件满足时尝试生成代码包和验证结果。
五、如何上传协议资料
- 打开 AI 对话。
- 选择“自动识别”或“协议解析”模式。
- 上传协议文档、字段表、报文样例或抓包文件。
- 在问题中说明本次目标，例如“请解析该协议并生成适配代码包”。
- 等待 AI 会话返回处理进度和结果。
如果使用“自动识别”，建议问题中包含“协议解析”“协议适配”“报文”“编解码”“代码包”等关键词，便于系统准确路由到协议解析能力。
示例问题：
请根据上传的协议资料解析报文结构、字段定义、校验规则和物模型映射，并生成协议适配建议。请分析这个 Modbus 寄存器表，整理字段、倍率、单位和平台物模型映射。请根据上传的协议文档生成协议适配代码包，并列出需要人工确认的问题。六、AI 会话处理阶段
上传协议资料后，系统会按以下阶段处理：
| 阶段 | 说明 |
|---|---|
| 保存资料 | 保存用户上传的协议文档、字段表或样例报文 |
| 自动解析 | 从资料中抽取可分析文本，生成结构化协议 DSL |
| 质量门禁 | 检查协议总览、报文类型、字段、编解码规则和样例是否完整 |
| 代码生成 | 在资料满足条件时尝试生成协议适配代码包 |
| 静态验证 | 检查生成包结构、关键文件、样例报文和静态规则 |
| 返回结果 | 在 AI 会话中返回状态、摘要、下一步建议和相关编号 |
后台生成的适配记录主要用于保存资料、处理进度和生成结果。普通用户只需要关注 AI 会话返回的状态和建议。
七、会话结果怎么看
AI 会话通常会返回上传文件、处理状态、当前阶段、适配记录编号、生成记录编号和下一步建议。常见状态如下：
| 状态 | 含义 | 建议处理 |
|---|---|---|
| 已完成 | 解析、校验和生成流程基本完成 | 查看结果，进入人工复核和联调 |
| 已完成但有警告 | 已生成结果，但存在缺失或不确定项 | 按下一步建议补充资料或人工确认 |
| 需要复核 | 资料不足或质量门禁未完全通过 | 补充字段表、样例报文、校验规则后重新上传 |
| 失败 | 文件解析、模型调用或生成流程异常 | 查看失败原因，调整文件或稍后重试 |
如果会话结果中出现“下一步建议”，应优先按建议补齐缺失信息。常见建议包括补充样例报文、明确校验算法、确认字节序、完善物模型映射等。
八、AI 可能生成的内容
根据资料完整度不同，AI 可能输出以下内容：
| 内容 | 说明 |
|---|---|
| 协议结构摘要 | 协议名称、传输方式、编码方式、认证流程、上下行流程 |
| 报文类型 | 注册、心跳、属性上报、事件、控制下发、应答等消息类型 |
| 字段定义 | 字段名称、字节范围、类型、倍率、单位、枚举和说明 |
| 编解码规则 | 字节序、长度、校验、转义、拆包粘包等规则 |
| 物模型映射 | 协议字段到平台物模型属性、事件或功能的映射建议 |
| 质量问题 | AI 识别出的缺失项、风险项和人工确认项 |
| 生成结果 | 在条件满足时生成协议适配相关代码包、清单或测试报告 |
资料不完整时，AI 会优先给出分析结果和补充建议，不一定能直接完成代码包生成。
九、资料质量清单
上传资料前，建议重点确认：
- 报文方向是否明确，是设备上报、平台下发还是设备应答。
- 帧头、长度、命令字、流水号、设备标识、校验位是否完整。
- 字节序是大端还是小端。
- 字段类型是有符号还是无符号，是否存在 BCD、位图、字符串、JSON 等特殊编码。
- 倍率、单位、精度和取值范围是否明确。
- 枚举值是否完整，例如在线状态、告警类型、设备状态。
- 校验算法、转义规则、拆包粘包规则是否明确。
- 注册、认证、心跳、数据上报、控制下发和应答流程是否完整。
- 样例报文是否能对应到字段解释。
- 物模型标识符是否符合平台命名规范。
十、常见问题
1. 为什么没有“创建任务”入口
当前版本的协议适配由 AI 会话上传资料触发。系统会在后台自动创建适配记录，用户不需要手动创建任务。
2. 上传后没有进入协议解析
建议切换到“协议解析”模式后上传，或在问题中明确写出“协议解析”“协议适配”“报文”“编解码”“代码包”等关键词。
3. AI 解析结果字段缺失
通常是协议资料中字段表不完整，或报文样例没有标注方向和含义。建议补充字段表、样例报文和解析结果后重新上传。
4. 提示需要复核或资料不足
说明缺少生成所需的关键结构，例如协议基本信息、报文类型、字段定义、编解码规则或样例报文。按会话中的下一步建议补齐资料后重新上传。
5. 生成代码包失败
检查协议资料是否包含协议编码、字段定义、编解码规则、校验算法和样例报文。代码包生成依赖完整 DSL，资料缺失时可能只能输出分析建议。
6. 能否直接上线
不能。协议适配助手生成的是辅助产物，上线前必须完成代码审查、编译、单元测试、真实设备联调和业务验收。