meter-protocol-serial

698/645 电表协议串口发帧与解析 Skill

触发时机

当用户需求涉及以下任一关键词时触发本 skill：

• 698、645、DL/T698、DL/T645
• OAD、DI
• 串口发帧、组帧、COM口
• 协议调试、回归测试
• 发帧验证、读电表数据、写电表参数

功能概述

本 skill 提供统一的 698/645 电表协议组帧、发送、接收和解析能力：

1. 只组帧模式（无 port 参数）：输出组好的请求帧十六进制
2. 串口闭环模式（有 port 参数）：发送请求、接收响应、解析结果

使用方法

快速调用

Linux / macOS / 原生Python

# 645读数据（只组帧）
python3 $SKILL_DIR/scripts/protocol_cli.py proto=645 op=read di=00010000

# 645读数据（串口发送）
python3 $SKILL_DIR/scripts/protocol_cli.py port=/dev/ttyUSB0 proto=645 op=read di=00010000

# 698读数据
python3 $SKILL_DIR/scripts/protocol_cli.py proto=698 op=read oad=40010200

# 698设置参数
python3 $SKILL_DIR/scripts/protocol_cli.py proto=698 op=set oad=43000300 value=bool:true

Windows / WSL (重要差异)

WSL中使用Windows串口时，推荐走 Python 包装脚本，它会自动转成 python.exe + Windows 路径：

# WSL中访问Windows COM口（推荐方式：使用 Python 包装脚本）
python3 $SKILL_DIR/meter-cmd.py port=COM10 proto=645 op=read di=04000401

# 或者手动转换路径
SKILL_PATH=$(wslpath -w /home/xx/.agents/skills/meter-protocol-serial/scripts/protocol_cli.py)
python.exe "$SKILL_PATH" port=COM10 proto=645 op=read di=04000401

常见错误：

# 错误方式1（WSL Python无法访问Windows串口）
python3 protocol_cli.py port=COM10 ...  # 会报错: No such file or directory

# 错误方式2（Windows Python无法直接访问WSL路径）
python.exe /home/xx/.../protocol_cli.py  # 会报错: can't open file

WSL串口映射关系：

Windows	WSL设备
COM1	/dev/ttyS1
COM10	/dev/ttyS10

Windows原生PowerShell/CMD：

# Windows直接运行（PowerShell）
python.exe C:\path\to\scripts\protocol_cli.py port=COM10 proto=645 op=read di=04000401

# Windows直接运行（CMD）
python C:\path\to\scripts\protocol_cli.py port=COM10 proto=645 op=read di=04000401

带断言的回归测试

# Linux/WSL通用（只组帧，无串口）
python3 $SKILL_DIR/scripts/protocol_cli.py proto=645 op=read di=00010000 expect=ack

# WSL+Windows串口（推荐直接走包装脚本）
python3 $SKILL_DIR/meter-cmd.py port=COM3 proto=645 op=read di=00010000 expect=ack

支持的协议

协议	操作	说明
DL/T645-2007	read	读数据
DL/T645-2007	write	写数据
DL/T698.45	read	GET.request.normal
DL/T698.45	set	SET.request.normal

输入参数

通用参数

参数	说明	示例
proto	协议类型	645 或 698
op	操作类型	read / write / set
port	串口（可选）	/dev/ttyUSB0 或 COM3
timeout_ms	超时时间	2000
baud	波特率	2400（645默认）、9600（698默认）
data_bits	数据位	8
parity	校验位	even / odd / none
stop_bits	停止位	1
expect	断言条件	ack / hex:0102 / bool:true / int:1
decode_hint	解码提示	hex / ascii / uint16_le / uint32_le / bcd
note	备注	任意文本

645专用参数

参数	说明	示例
di	数据标识（8位十六进制）	00010000
addr	表地址（12位BCD）	000000000001
value	写数据值	hex:010203 / ascii:abc
fe_count	前导FE个数	4
raw_prefix	前置数据	hex:041234
raw_suffix	后置数据	hex:0000

698专用参数

参数	说明	示例
oad	对象属性描述符（8位十六进制）	40010200
server_addr	服务器地址	000000000000
client_addr	客户机地址	00
ca	客户机地址（缩写）	00
value	写数据值	bool:true / int32:123 / string:abc

Value格式

645协议：

• hex:01020304 - 原始十六进制数据
• ascii:abc - ASCII字符串

698协议：

• bool:true|false - 布尔值
• int8:1, int16:1, int32:1 - 有符号整数
• uint8:1, uint16:1, uint32:1 - 无符号整数
• enum:1 - 枚举值
• octet:112233 - 八位串（带长度前缀）
• string:abc - 可见字符串（带长度前缀）
• hex:010203 - 原始十六进制（直接作为Data）

输出格式

MODE=frame_only|serial_roundtrip
PROTO=645|698
OP=read|write|set
TARGET=di:xxx|oad:xxx
REQUEST_HEX=68 AA AA ... CS 16
RESPONSE_HEX=68 BB BB ... CS 16  (串口模式)
FRAME_CHECK=ok|fail|partial
DECODE_STATUS=ok|partial|fail
RESULT=success|error|timeout
DATA_HEX=01020304
DATA_TYPED=typed_value  (如果有)
ASSERT_RESULT=pass|fail|skipped
ASSERT_REASON=...  (如果有)
SUMMARY=简短中文总结

645特有输出

645_ADDR=000000000001
645_CTRL=91
645_DI=00010000

698特有输出

698_SERVER_ADDR=45AAAAAAAAAAAA  (地址特征字节+6字节地址)
698_CLIENT_ADDR=00
698_CTRL=43  (控制域: DIR=0,PRM=1,分帧=0,扰码=0,功能码=3)
698_PIID=00
698_OAD=40010200
698_DAR=00  (数据访问结果，00=成功)

退出码

码值	含义
0	成功
2	输入参数错误
3	串口打开或发送失败
4	超时无响应
5	收到响应但解析失败
6	断言失败

AI 使用建议

回复顺序

当用户使用本 skill 时，AI 应按以下顺序回复：

1. 执行命令：给出实际执行的 CLI 命令
2. 关键输出：摘出 REQUEST_HEX、RESULT、ASSERT_RESULT 等关键字段
3. 简短解释：说明结果含义和下一步建议

示例场景

场景1：用户说"帮我组一个645读数据的帧"

执行命令：
python3 $SKILL_DIR/scripts/protocol_cli.py proto=645 op=read di=00010000

输出：
MODE=frame_only
PROTO=645
OP=read
TARGET=di:00010000
REQUEST_HEX=FEFEFEFE6800000000000068110433333333AD16
...
SUMMARY=组帧成功: FEFEFEFE6800000000000068110433...

场景2：用户说"验证COM3口能否读到数据"

执行命令：
python3 $SKILL_DIR/scripts/protocol_cli.py port=COM3 proto=645 op=read di=00010000 expect=ack

输出：
MODE=serial_roundtrip
PROTO=645
OP=read
...
ASSERT_RESULT=pass
SUMMARY=断言通过: 收到响应

注意事项

1. port 参数可选：无 port 时进入只组帧模式，不会打开串口
2. 地址默认值：
   • 645默认地址 AAAAAAAAAAAA（12位BCD通配地址）
   • 698默认服务器地址 AAAAAAAAAAAA（6字节通配地址，地址特征字节=0x45），客户机地址 00
3. 波特率默认：645默认9600bps，698默认9600bps
4. 超时处理：默认超时2000ms，可通过timeout_ms调整
5. 断言失败：assert_result=fail时进程返回非零退出码，可用于脚本自动化

模块结构

scripts/
├── protocol_cli.py      # CLI主入口
├── request_parser.py    # 请求解析
├── profiles.py          # 默认配置
├── serial_transport.py  # 串口收发
├── proto_645.py         # 645协议处理
├── proto_698.py         # 698协议处理
├── value_codec.py       # 值编解码
└── result_formatter.py  # 结果格式化

第一版限制

• 698：不支持登录、链路建立、安全认证、安全传输
• 698：不支持 ACTION 和 ROAD
• 645：不做各类业务DI的专用语义解析
• 两个协议：仅支持标准明文读写，不支持厂商私有扩展