# Gizwits Aliyun Protocol Merge

> Merges Gizwits (机智云) MCU protocol documents into the Aliyun IoT UART/WiFi protocol template and outputs .docx. Use when the user uploads a Gizwits platform protocol document, asks to integrate/merge 机智云协议 into 阿里云协议模版, or requests protocol document conversion for MCU-WiFi module communication.

- Skill: `lareina0011/gizwits-aliyun-protocol-merge` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add lareina0011/gizwits-aliyun-protocol-merge`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lareina0011/gizwits-aliyun-protocol-merge/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: lareina0011 (https://skillmd.com/u/lareina0011)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/lareina0011/gizwits-aliyun-protocol-merge

---


# 机智云协议 → 阿里云协议文档整合

将机智云开发者平台下载的 MCU 通讯协议，按整合规则填入阿里云协议模版，输出 `.docx`（优先）或 `.doc`。

**可在任意项目/目录使用。** 模版与机智云文档由用户上传或指定路径。

## 输入材料

| 材料 | 说明 | 获取方式 |
|------|------|----------|
| 机智云协议文档 | 「WiFi类设备接入协议文档-MCU方案」 | 用户上传或指定路径 |
| 阿里云协议模版 | 标红=需按机智云修改，绿色=固定不变 | 用户上传或指定路径 |
| 整合思路参考 | 逐步修改清单（可选） | `d:\work\数据点协议\协议整合思路.pdf` |

若用户未指定模版，在工作区查找 `协议模版.docx`；仍找不到则请用户上传。默认参考模版仓库：`d:\work\数据点协议\协议模版.docx`。

## 工作流程

```
整合进度：
- [ ] 1. 解析机智云协议文档（数据点表、类型、读写权限、PK/PS）
- [ ] 2. 修改 3.1 获取设备信息（Data 字段 PK/PS/IID 等）
- [ ] 3. 修改 3.2 WiFi模组向MCU发送业务指令
- [ ] 4. 修改 3.3 WiFi模组读取设备当前状态
- [ ] 5. 修改 3.4 MCU向WiFi模组上报业务指令
- [ ] 6. 校验长度与示例包一致性
- [ ] 7. 输出 .docx 到当前工作区并告知用户路径
```

## 核心原则

1. **只改标红/产品相关部分**；通讯模型、约定、扩展协议（第4章）等固定章节保持模版原文。
2. **数据点定义以机智云文档为准**；字段名、类型、取值范围、换算公式均来自机智云。
3. **attr_flags 固定 4 字节（32 bit）**；数据点超过 32 个时与用户确认处理方式。
4. **字节序为大端**；uint16 占 2 字节，uint8/bool/enum 按机智云位域定义。

## 分节修改（按协议整合思路）

### 2.1 修改 3.1 获取设备信息

更新 MCU 回复设备信息表 **Data** 字段：`PK`、`PS`、`IID`、`apName`、`resetDM` 等。

### 2.2 修改 3.2 WiFi模组向MCU发送业务指令

1. attr_flags 长度（通常 4B）
2. attr_vals 最大长度 `Max(NB)`
3. 「从右到左的标志位依次为」列表
4. 示例数据包（attr_vals 段）
5. attr_vals 数据格式表
6. MCU 回复段 attr_flags
7. MCU 回复段 dev_status 最大长度 `MAX（NB）`

### 2.3 修改 3.3 WiFi模组读取设备当前状态

1–2. attr_flags 长度；3. dev_status 长度；4. 示例包；5. dev_status 格式表

### 2.4 修改 3.4 MCU向WiFi模组上报业务指令

attr_flags 长度 + dev_status 长度（与 3.3 一致）

详细规则见 [reference.md](reference.md)。

## 生成输出文档

```bash
pip install python-docx
python "%USERPROFILE%\.cursor\skills\gizwits-aliyun-protocol-merge\scripts\merge_protocol_docx.py" \
  --template "<模版路径>" \
  --output "<当前工作区>/输出/[项目名]ESP32-C2接入阿里云平台之MCU与WIFI模组通讯.docx"
```

输出保存到**当前打开的工作区**，建议放在 `输出/` 目录。

## 完成前校验

- [ ] attr_vals / dev_status 字节长度正确
- [ ] attr_flags bit 列表与机智云可写点一一对应
- [ ] 3.2 / 3.3 / 3.4 中 dev_status 定义一致
- [ ] 未改动固定章节

## 补充资源

- [reference.md](reference.md) — 类型与位域计算细则
- 参考模版：`d:\work\数据点协议\协议模版.docx`