iot

iot 技能概览

iot 技能可以帮你用 PlantUML 创建 IoT 架构图，配合设备、传感器、网关和云服务的 stencil 图标使用。它最适合那种需要说明“物理世界的东西如何连接到边缘和云系统”的图：智能家居、工业 IoT、车队遥测、传感网络、数字孪生和机器人场景。

这个 iot 技能不是通用的画图捷径。它面向的是需要正确 IoT 术语和图标体系的读者，而不只是几个方框和箭头。如果你的目标是把数据流、站点边界、协议跳转或设备生命周期讲清楚，而且还要让工程师能快速扫读，这个技能就很合适；如果你只是想画通用云基础设施图或软件 UML，应该换别的技能。

iot 的用途

当图里需要展示设备、网关和服务在真实世界中的关系时，用 iot 来做 Diagramming：哪些部署在现场，哪些运行在边缘，哪些上云，以及哪些按站点或区域分组。它的核心价值在于把 IoT 特有的组件和模式讲清楚，而不是单纯做装饰。

什么时候这个技能最合适

如果你需要为以下场景出图，选择 iot 技能会更合适：

• 智能家居 hub 和设备分组
• 工厂产线、PLC、传感器和边缘 PC
• 车辆车队和遥测管道
• LoRaWAN 或由网关汇聚的传感网络
• 数字孪生和资产模型数据流
• 机器人或边缘 ML 部署

它和其他画图方式有什么不同

它最主要的区别在于：输出的是基于 stencil 的 PlantUML，并使用类似 AWS 风格的 IoT 图标，例如传感器、网关、Greengrass、IoT Core、SiteWise、FleetWise 以及设备管理组件。相比普通矩形框，这种方式更适合做架构评审时的 iot guide，尤其是当受众本来就期待看到具体服务符号时。

如何使用 iot 技能

安装并加载技能

按标准的 repo 安装流程来安装 iot：
npx skills add markdown-viewer/skills --skill iot

然后按这个顺序打开技能文件：

1. SKILL.md，看规则和语法
2. examples/*.md，看可复用的模式
3. 技能正文里提到的任何 stencil 参考链接

从图的任务开始，不要从图标清单开始

一个好的 iot 提示词，应该描述的是实际架构结果，而不是只说“画一个 IoT 图”。建议包含：

• 领域：智能家居、工厂、车队等
• 设备类型
• 边缘层（如果有）
• 涉及的云服务
• 协议或数据路径
• 受众，如果它会影响细节层级

一个强提示的例子：
“为智能工厂产线创建一张 iot 架构图，包含温度和振动传感器、PLC、边缘侧 Greengrass、IoT Core、SiteWise 和基于事件的告警。展示从传感器到边缘再到云的数据路径，并按生产线和云平台分组。”

写自己的提示词前先看示例

示例文件是最快掌握这个技能偏好模式的方式：

• examples/smart-home.md
• examples/smart-factory.md
• examples/edge-computing.md
• examples/fleet-telemetry.md
• examples/digital-twin.md
• examples/sensor-network.md
• examples/device-management.md
• examples/robotics.md

这些示例会告诉你哪些 stencil 适合搭配使用，以及图通常是怎么分组的。这比死记每个图标名称更重要。

使用会影响输出质量的技能规则

有几条规则会明显改变最终结果：

• 输出要包在 ```plantuml 或 ```puml
• 以 @startuml 开头，以 @enduml 结束
• 典型的设备到云流转图建议使用 left to right direction
• 用 rectangle 或 package 分组系统
• 流程关系优先用实线箭头，异步更新优先用虚线箭头
• 不要无端要求通用配色调整，除非你确实需要

如果你已经知道目标环境，一定要说出来。比如，“传感器到网关使用 MQTT”或者“展示 PLC 到边缘的 OPC-UA”。这些细节会提升 iot 的使用效果，因为它们会迫使图反映真实集成，而不是只停留在视觉结构。

iot 技能常见问题

iot 只适合 AWS 图吗？

不是。这个技能使用的是 AWS 风格的 mxgraph.aws4.* stencils，但图本身仍然适用于更广泛的 IoT 架构。关键是 IoT 的视觉语言和 PlantUML 工作流，而不是厂商锁定。

它能替代普通提示词吗？

可以，前提是你希望图里持续保持 IoT 特有的符号和结构。普通提示词也能描述图，但 iot 技能能给你更稳定、可复用的设备、边缘和云组合模式。

iot 技能适合初学者吗？

适合，只要你能用自然语言把系统描述清楚。你不需要提前掌握 PlantUML 语法，但你需要知道想展示哪些设备、流向和主要服务。

什么时候不该用 iot？

不要把它用在通用应用架构、CRUD 后端或纯云端标准图上。iot 技能最适合物理设备或边缘处理是故事核心的场景。

如何改进 iot 技能

把真实部署形态讲清楚

最好的 iot guide 输入一定要具体：有多少区域，边缘层放在哪里，哪些是本地处理，哪些是云端处理。说“工厂里有传感器”太弱；“两个产线，每条产线有温度和振动传感器，每条产线一个 Greengrass 网关，统一汇总到 SiteWise 做分析”要好得多。

明确协议和数据路径

当你直接点出路径时，输出质量会更高：

• sensor → gateway → core
• PLC → industrial PC → cloud
• vehicle edge agent → telemetry service → analytics

这样可以帮助 iot 技能选择更合适的箭头、标签和分组方式，也能避免画出一张看起来合理、但把真实集成关系藏起来的泛化图。

注意常见失败模式

最常见的问题是范围太模糊、服务太多、边界缺失。如果你不说清楚哪些内容属于边缘层，图可能会把所有东西压成一层；如果你一次要求太多服务，结果会变得拥挤，甚至比更简单的 iot for Diagramming 输出还难读。

通过逐层收紧来迭代

如果第一版图太宽泛，可以按层收紧：

1. 先确认物理设备
2. 再确认边缘组件
3. 再确认云服务
4. 最后确认按站点、车队或产线的分组方式

这种迭代方式在 iot install 工作流里特别有效，因为这个技能最强的使用方式，本来就是在架构已经明确的前提下，把它清晰、懂服务关系地视觉化。