# App Spec Datapoints

> 根据 APP 产品规格书生成阿里云协议用数据点表（输出 .xlsx）。 Use when the user asks to 生成数据点、做数据点表、从规格书提取数据点, 或提供 APP 规格书要求输出阿里云/IoT 数据点 Excel；也可在用户说 「根据规格书生成对应的数据点（主要会出现在阿里云的协议上）」时使用。

- Skill: `lareina0011/app-spec-datapoints` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add lareina0011/app-spec-datapoints`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lareina0011/app-spec-datapoints/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: lareina0011 (https://skillmd.com/u/lareina0011)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/lareina0011/app-spec-datapoints

---


# APP 规格书 → 阿里云数据点表

请你帮我根据我的APP产品规格书，生成对应的数据点（主要会出现在阿里云的协议上），我会给你一份我已经写好的规格书和数据点，你根据我原来写的设计思路来做就行，最好输出给我一个excel表格就行了。

**最终交付：一律 `.xlsx`。** 不要用 Markdown/CSV 作为最终交付物。

## 输入

| 材料 | 必需 | 说明 |
|------|------|------|
| APP 产品规格书 | 是 | docx/pdf/截图文字均可 |
| 参考数据点表 | 强烈建议 | 同系列/已写好的 `.xlsx`，用于对齐命名、类型、备注写法 |
| 产品型号 | 否 | 用于输出文件名，如 `1271W数据点.xlsx` |

若用户只给了规格书、没有参考表：先按本 skill 的表头与规则生成；并询问是否有老品数据点可对齐。

可参考样例：[examples/1271W数据点.xlsx](examples/1271W数据点.xlsx)。列定义与设计细则见 [reference.md](reference.md)。

## 工作流程

```
进度：
- [ ] 1. 读规格书，列出需设备↔云端同步的功能点
- [ ] 2. 若有参考数据点表，对齐标识名/类型/备注风格
- [ ] 3. 按规则填：显示名称、标识名、备注、读写、数据类型及子字段
- [ ] 4. 排除纯 APP 侧能力（不进 MCU/协议）
- [ ] 5. 输出 .xlsx 到当前工作区并告知路径
```

## 核心设计思路（对齐已有表）

1. **只做协议需要的点**：规格里要和设备交互、上报状态、下发控制的功能 → 数据点；纯 UI（配网页文案、新手引导步骤、周报图表计算、家庭成员本地管理等）→ 不进表。
2. **跟参考表学**：有参考数据点时，优先沿用其 `标识名`、类型习惯、备注粒度；新品增量功能再新增行。
3. **四种数据类型**：
   - **布尔值**：开/关、启停类；数值四列与枚举/扩展留空
   - **数值**：填分辨率、增量、最小、最大（常见：分辨率=1，增量=0）
   - **枚举**：在「选项」填英文逗号分隔取值（如 `Heating,Keeping,Cooling`）
   - **扩展**：原始字节流，在「长度」填字节数
4. **读写类型**：APP 可下发 → `可写`；仅设备上报/状态 → `只读`
5. **标识名**：英文 `snake_case`，简洁稳定，供阿里云属性/协议位使用
6. **备注**：写清业务含义、特殊值（如故障码、254/255）、与其它点的联动；不必写 UI 文案

## 输出表头（必须一致）

两行表头 + 合并单元格，列顺序固定：

| 显示名称 | 标识名 | 备注 | 读写类型 | 数据类型 | 数值（分辨率/增量/最小/最大） | 枚举（选项） | 扩展（长度） |

生成时优先执行：

```bash
pip install openpyxl
python "%USERPROFILE%\.cursor\skills\app-spec-datapoints\scripts\generate_datapoints_xlsx.py" ^
  --input "<数据点JSON或由agent写入的中间JSON>" ^
  --output "<当前工作区>/数据点/<型号>数据点.xlsx"
```

也可用 openpyxl 按 [reference.md](reference.md) 的合并规则手写同等结构；**列名与合并方式必须与样例一致**。

## 自检

- [ ] 每个可控制 UI 动作（温度、水量、煮沸、静音等）有对应可写点或说明为何合并到已有点
- [ ] 每个需展示的设备状态（当前温度、工作状态、故障、出水记录等）有对应只读/可写点
- [ ] 标识名无中文、无空格；枚举选项为英文或数字约定
- [ ] 数值型四列完整；布尔/枚举/扩展未误填无关列
- [ ] 输出为 `.xlsx` 且可用 Excel 打开