如何准确描述你要的设备

整个平台就是一个输入框。你输入的那句话，是它唯一知道你想要什么的来源——所以这一篇大概是这十篇里最值得读的。

一览

它能从你的话里读出你要做什么设备、你想怎么跟它交互、你已经有什么硬件、什么算成功、要什么精度
它读不出你的接线实况、你板子的具体版本、你家 WiFi 信号强弱、你的预算（除非你说）
单条消息上限项目对话 8000 字；首页对话 4000 字
能传的文件输入框收图片和文本类文件（png jpg webp gif log txt csv json md，以及源码和配置文件），单个 10MB、一条消息最多 5 个且合计不超过 20MB。pdf 和 zip 输入框不收，要传到「资料」面板（单个 25MB）；rar、7z、tar 两个通道都不收
回复的语言跟着你这句话走，不看界面语言。能分辨中文、英文、日语、韩语

先看两句话的差别

同一个想法，两种说法，得到的结果完全不同。

含糊：

做一个测距的东西

它只能自己猜：猜你用红外还是超声波、猜你要不要屏幕、猜你要不要联网、猜你要什么精度。猜错了你得反复修改多轮。

清楚：

做一台超声波测距仪。 用 ESP32-S3-DevKitC-1，模块用 HC-SR04。 TRIG 接 GPIO2，ECHO 接 GPIO1，模块按它自己的供电要求接（假设是 3.3V 版本），GND 共地。 每秒测一次，通过串口打印当前距离。 测量范围 2 cm 到 2 m，误差 1 cm 以内就够。 USB 供电，不需要电池，也不需要屏幕。

这句为什么管用：点名了板子和模块，它就不用在几十个可选型号里替你推测；给了两个引脚和供电方式，省掉一轮往返；说了「不需要屏幕」，它就不会额外添加一块屏，也就不会多占掉几个引脚。

把这五件事说进去

不用一次说全，但说得越多，反复修改的轮数越少。

1 · 做什么设备承担什么功能。「测前面的障碍物有多远」「按一下就拍张照」「屏幕上显示时间」。
2 · 如何交互要不要显示屏，还是网页交互，还是串口。
3 · 你已经有什么最重要的一条。手上有什么板子、什么模块，型号直接报出来。
4 · 什么算成功「串口能打出距离即可」和「手机上要能看到实时曲线」是两个工程量。
5 · 精度和范围精度是多少，范围是多少。

第 3 条尤其有价值。你不说手上有什么，它只能按最常见的情况给方案，然后你会发现方案里的板子你没有、你有的板子方案里没用上。开头就说清楚，可以减少一整轮往返。

例句库

下面每一条都是完整的、可以整段复制粘贴的。挑一条改成你自己的情况。

点灯与输出

用 ESP32-C3 让板载 LED 每秒闪一次。 先做最小的，能编译能烧就行，我要先确认整条链路是通的。

这句为什么管用：「先确认整条链路是通的」是这一行里的惯例——第一次用一块新板子，先烧一个闪灯，把「板子、线、驱动、浏览器、烧录」这五个环节一次性验掉。等到真正做复杂项目时出了问题，你就知道不是这五个环节的问题。

用 ESP32 控制一个继电器，接在 GPIO5。 串口收到 on 就吸合，收到 off 就断开。 继电器模块是低电平触发的。

这句为什么管用：「低电平触发」这一句新手常常不知道要说。不说，代码会写成高电平吸合，接上去的表现是「反的」，而且从代码上完全看不出错在哪。

读传感器

用 ESP32-S3-DevKitC-1 读 HC-SR04 的距离。 TRIG 接 GPIO2，ECHO 接 GPIO1，模块按它自己的供电要求接（假设是 3.3V 版本），GND 共地。 每秒测一次，通过串口打印，格式写成 Distance: xxx cm。 测不到或者超时的时候也打印一行，不要静默跳过。

这句为什么管用：「测不到也打印一行」——超声波模块对着空旷处或者软织物时收不到回波是常态。静默跳过，你会看到串口莫名其妙断断续续，而完全不知道是没测到还是程序死了。

用 ESP32 读 BMP280 气压传感器，走 I2C。 我不确定它的地址是 0x76 还是 0x77，启动时扫一遍 I2C 总线，把扫到的地址打印出来。

这句为什么管用：同一个型号在不同模块上地址可能不同。让它启动时扫一遍，比你翻资料快，而且这个扫描结果以后排查问题还能用。

按键与输入

用 ESP32 做一个按键，接 GPIO0，按下去切换板载 LED 的亮灭。 按键要做消抖，我用的是普通轻触开关，没有外接电阻。

这句为什么管用：「没有外接电阻」告诉它要启用芯片内部的上拉。不说，代码可能假设你外面接了电阻，实际表现是按键乱触发。

做一个网页

在上面的基础上，让板子连上 WiFi，在局域网里开一个网页。 网页上实时显示当前距离，每秒刷新一次。 先做最朴素的，能看到数字就行，样式后面再说。

这句为什么管用：「先做最朴素的」把这一轮的范围压到最小——先让网页能打开、数字会动，样式和图表是下一轮的事。一次要太多，出问题时你分不清是网络的锅还是页面的锅。

连上网络

WiFi 名 MyHome，密码 12345678。 连上之后把拿到的 IP 打到串口上，我要用它来开网页。 连不上的时候在串口里说清楚是没找到网络还是密码错了。

这句为什么管用：两句都在给自己省事。「把 IP 打到串口上」——不然你根本不知道该在浏览器里输什么地址。「说清楚是哪种失败」成本极低回报极高：WiFi 连不上是最常见的问题，而默认代码往往只打印「连接失败」，那句话对排查毫无帮助。

组合起来

把测距和网页合起来： 距离每秒测一次，串口照常打印，网页上也实时更新。 网页上加一个最近 8 秒的趋势曲线，距离小于 30 cm 的时候变红告警。 断网的时候串口照常输出，不要卡住。

这句为什么管用：「断网的时候串口照常输出」——网络相关的代码很容易写成阻塞的，一断网整个设备就像死机。提前说明这一点，可以避免一次很难自行定位的问题。走到这里，你要的就是本文档一直在用的那个示例项目。

把它猜不到的约束直接写进去

下面这些是新手不可能知道、但会实实在在影响结果的。看到符合你情况的，就把那一句加进你的描述里。

加这句为什么
我的模块是 3.3V 的，不要按 5V 设计电平不对轻则读不到、重则烧掉模块
不要用 GPIO6 到 GPIO11经典 ESP32 上这几个脚接着 flash 芯片，用了会直接起不来
主循环里不要用超过 50 毫秒的 delay长 delay 会让按键没反应、网络掉线，而现象看起来像「卡住了」
串口波特率用 115200不指定就得靠猜，猜错了日志全是乱码
启动时打印一遍芯片型号、flash 大小和当前引脚配置以后任何问题，第一句都是「把你的启动日志贴上来」。让它自带这段，等于给自己装了个仪表盘

传原理图和 datasheet

光靠打字说不清的时候，把文件给它。有两条通道，作用完全不同，别混淆。

Workspace 资料对话框里的临时附件
怎么传切到「资料」面板上传直接往输入框粘贴或拖进去
活多久一直在，是这个项目的工程资料只在这一轮对话里有效，用完即不再保留
能不能再引用能。输入框里打 @ 会弹出资料列表，文件名和标签都能搜；最终认的是文件名不能
会不会跟着项目走会（备份、发布、被人复刻时都在）不会
适合放什么原理图、datasheet、模块说明文档；单个 25MB 以内，整套 SDK 压缩包通常放不下一次性的报错截图、一段日志

一个常见的失望：把原理图当临时附件粘进去，聊了两轮之后它「忘了」。那不是它记性差——临时附件原本就是一轮有效的。原理图和 datasheet 请传到「资料」面板。

上传文件后需要补充一句说明

只拖一个文件进去、什么都不说，它不知道你想让它做什么。界面上也会提示你补一句。

@HC-SR04-datasheet.pdf 是我手上这个超声波模块的规格书。 请照着它整理出硬件方案，尤其是它的供电要求和 Echo 输出电平。

日志太长贴不进去？项目对话单条上限 8000 字，但你不必自己先存成文件——把日志直接粘进输入框，超过上限的粘贴内容会整段转成一个 pasted-…….log 附件。转完再写一句「这是烧录后的串口输出，帮我看看为什么一直重启」。

用什么语言说都行

你用中文说，它用中文回；你用英文问，它用英文答；日语、韩语也一样。它跟的是你这句话的语言，不是界面语言。所以界面开着英文、你用中文提问，回复仍然是中文。

目前能分辨的是中文、英文、日语、韩语四种。其他用拉丁字母书写的语言（西班牙语、法语等）会被当成英文。

如果你熟悉软件开发

可以把这个输入框理解成一个「意图 → 工程变更」的编译器，而不是聊天机器人。它每一轮都会：读你的话 → 读当前项目的硬件事实 → 决定要不要改代码 → 真的去改、去编译。

所以描述的精确度直接决定产出质量，和写 issue 是一回事：期望行为、实际约束、验收标准 三件事说全，往返轮数就少。区别在于它没法 git diff 你的桌子——你的接线、你的板子版本，它一概看不见，只能靠你说。

常见问题

它给的方案不是我想要的，怎么办？

直接说哪里不对即可，不用重新描述一遍。「这个方案里的屏幕我不需要，去掉」「换成我手上的 ESP32-C3」——它会在原方案上改。

我可以要求它用某个具体的库吗？

可以，直接点名。HTTP 服务用 esp_http_server，不要引第三方框架。不点名它就自己选一个常见的。

一次说太多会不会更好？

不会。先实现最小的那一版，验证通过后再增加。一次描述十个功能，出问题时你分不清是哪一块出的问题，而且改一次要等一次编译。这行的惯例是先闪灯、再读传感器、再联网。