零手写代码开发机械臂遥控器：Agent+WebSocket+ESP32实战全记录

我从一个完全没写过机械臂控制的“小白视角”，分享最近这次有点特别的开发经历：我做了一个机械臂遥控器，过程里没有手工敲过业务代码，所有代码都由 Agent 自动完成。这里面的关键不是“偷懒”，而是把注意力从“怎么实现某段逻辑”转移到了“怎么把需求描述清楚，怎么判断 Agent 给出的结果对不对，怎么处理它看不到的硬件问题”。这篇文章是把整个开发实录拆开，讲清楚技术链路、每一步做了什么、踩了哪些坑，以及我对 Agent 开发方式的一些真实感受。

适合谁看？两类人：一是想做硬件小项目但编程基础一般，想用 Agent 快速跑通流程；二是已经在用 Agent 写代码，想把它用于真实硬件项目、但不确定边界在哪里的人。

1. 这个项目是怎么“零手写”立起来的

1.1 先别急着开聊，需求本身要足够清晰

很多人用 Agent 写代码，上来第一句话就是“帮我做一个机械臂遥控器”，然后期待它返还一个能跑的项目。实际效果往往很差。不是 Agent 不行，而是这个需求本身太模糊：机械臂是什么型号？几个自由度？通信走什么协议？界面是网页还是桌面程序？这些信息如果不提前想清楚，Agent 就只能按照它自己的默认理解生成一套方案，最后大概率和你手头的硬件对不上。

我这次动手前，先花了半小时把自己的需求写成了几条明确的约束：

• 机械臂是六个舵机驱动的六轴结构，每个关节角度范围按 0 到 180 度处理；
• 遥控器的形态做成 Web 页面，这样手机、平板、电脑都能直接操控，不用装额外软件；
• 通信方式选用 WebSocket，局域网内实时性比 REST 好，操作滑块时指令能高频推送；
• 界面需要包含每个关节的独立滑块、实时角度显示、预设姿态按钮，以及一个急停按钮。

把这几条整理清楚之后，我才把需求贴给 Agent。一轮对话就拿到了初版程序，整件事的起点就在这里：不是 Agent 没有能力，而是我有没有先把自己的需求抽象成它能执行的边界条件。这一步谁也替代不了。

1.2 为什么选 Web 界面，不选桌面应用

机械臂遥控器的控制端有很多种做法。传统一点的是 Qt 桌面程序，或者用 Python 写一个带图形界面的工具，用上位机通过串口和机械臂通信。这些方案很稳，但开发周期较长，而且对“零手写代码”的目标来说，桌面的跨平台打包、依赖管理、界面布局都是额外负担。

我最后选了纯 Web 方案：一个 HTML 页面，配合 JavaScript 与 WebSocket 服务端通信。理由主要有三个：

• 浏览器天然跨平台，手机和电脑是同一个页面，不需要考虑操作系统差异；
• Agent 对 Web 前端代码的生成能力非常成熟，JavaScript、HTML、CSS 这些都是它的强项，出错概率低，改起来也快；
• 调试链路短，后端起一个 WebSocket 服务，前端页面直接连，中间少了很多环境变量干扰。

实测下来，这个选型非常顺。Web 页面里做滑块、按钮、摇杆这些交互控件，Agent 一次就能生成像模像样的布局。唯一需要注意的是局域网通信延迟，但在同一个无线网络环境下，WebSocket 的推送延迟体感基本可以忽略，遥控一个桌面大小的机械臂完全够用。

1.3 Agent 在流程里的真实角色：不是“代码生成器”，是“多功能协作者”

“一行代码没写”很容易被误解成“我啥也没干，全靠 Agent 自动搞定”。真实情况完全不是这样。Agent 更像一个能力很强的协作者，它能处理编码、读报错、写调试脚本，但它不会替你接舵机线，不会知道你的电源功率够不够，也不会替你判断“机械臂转到这个角度会不会撞到自己”。

在这次开发里，我实际的角色是：

• 需求拆解人：把整个项目拆成硬件通信、网页控制端、协议设计、调试验证几个模块；
• 硬件接线员：舵机、开发板、电源的物理连接必须亲自完成；
• 测试与验收者：Agent 生成每个版本后，都要由我来编译烧录、运行、观察实际动作，把问题反馈给它；
• 迭代决策者：当 Agent 给出多个方案时，我需要根据实际场景选一个，比如通信协议用简单 JSON 还是自定义二进制帧。

想清楚这个分工，后面就不会对 Agent 抱有不切实际的期待。它不是魔法，而是一台“会说人话的机器”，机器能干的越多，对操作者的判断力要求反而越高。

2. 核心链路拆解：机械臂遥控器的技术难点

2.1 硬件侧：下位机怎么接收指令并驱动舵机

机械臂遥控器，通俗说就是“上位机发指令、下位机转动作”。上位机是浏览器页面，下位机是开发板加六个舵机。开发板收到遥控指令后，要把它变成舵机转动的 PWM 脉冲信号。

舵机这个东西，控制原理并不复杂：给它一个周期 20ms 的脉冲，脉冲宽度在 0.5ms 到 2.5ms 之间变化，对应舵机臂从 0 度转到 180 度。不同品牌的舵机对脉宽和角度的映射会略有差异，但基本逻辑是一样的。下位机的职责，就是根据收到的目标角度，计算出对应的脉宽，持续输出稳定的 PWM 波。

这部分 Agent 写得非常快，它用的是现成的舵机控制库：

#include <ESP32Servo.h> Servo servo[6]; int servoPins[6] = {13, 12, 14, 27, 26, 25}; void setup() { for (int i = 0; i < 6; i++) { servo[i].attach(servoPins[i]); } }

这里有个关键细节：六个舵机同时运动时，对供电的要求会瞬间变高。如果直接用开发板上的 5V 引脚给六个舵机供电，电流一上来电压就被拉低，舵机轻则抖动，重则直接复位。这一课我是后来踩坑踩出来的，Agent 完全不会提醒你——它只负责生成代码，不负责物理世界的电流定律。

2.2 通信协议：WebSocket 消息的“边界优势”

遥控器要和下位机交换数据，必须定义一套双方都理解的协议格式。Agent 默认选了 JSON，理由很充分：可读性好、调试方便、前端 JavaScript 解析几乎零成本。

我让它生成的第一版通信协议大概是这样：

{ "type": "servo", "id": 2, "angle": 135 }

意思是：把 2 号舵机转到 135 度。

如果只控制单个舵机，这个消息格式够用。但实际遥控器场景里，用户往往希望让机械臂做一个“组合动作”，也就是六个舵机同时按不同角度运动。这种消息就需要改成数组形式：

{ "type": "pose", "servos": [90, 45, 120, 60, 30, 150] }

数组元素的顺序对应舵机编号，这样一条消息就能让六个舵机同时转向目标角度。Agent 生成这部分逻辑的时候，我额外要求它加入“消息完整性校验”，否则如果网络传输中出现半截数据，下位机解析就会错乱。

这里顺便说一个很多人忽略的点：WebSocket 底层是面向消息的，每个消息自带边界，应用层不需要自己拆包。但如果你的机械臂遥控器改成走串口，那就完全不同，串口是字节流，必须自己定义帧头、帧尾、长度、校验，这些都是 Agent 能生成，但需要你判断该不该用的细节。

2.3 控制端：把网页做成“游戏手柄”手感

遥控器的前端界面，是这次项目里 Agent 贡献最明显的部分。我只需要描述“六个滑块分别控制六个关节，要有角度显示，要有预设姿态按钮，最好滑块加了阻尼效果”，它就生成了一整个单页应用。

初始版本大概是这样：

<div class="controller"> <label>关节1</label> <input type="range" min="0" max="180" value="90" id="joint0"> <span id="angle0">90</span> </div>

滑块拖动时，JavaScript 捕获数值变化，实时通过 WebSocket 发送给下位机。这里我特意要求 Agent 做了“拖动松开发送”和“拖动过程中连续发送”两种模式。从实际体验来说，连续发送模式操作手感更跟手，机械臂会随着你拖动滑块实时转动，但前提是下位机能消化高频率的 WebSocket 消息。如果出现掉帧，就得在发送端做节流控制，这也是 Agent 能生成的常见优化。

整个界面从朴素版到顺手版，基本上就是我和 Agent 一段一段对话改出来的。

2.4 联调阶段：让 Agent 直接看日志修 Bug

这个项目里效率最高的一步，不是让 Agent“写代码”，而是让 Agent“看日志”替我排查问题。

第一次把整套系统跑起来时，网页端能连上 WebSocket，但舵机完全不动。我把串口监视器的输出粘贴给 Agent：

WebSocket connected received message: {"type":"pose","servos":[90,45,120,60,30,150]}

它立刻判断出问题不在通信，而在舵机初始化：ESP32 在启动时，舵机库可能没有正确为每个舵机分配通道，或者引脚定义和实际接线不一致。按它的建议重新检查引脚定义，发现我把 4 号舵机接在了 26 号引脚，但代码里写的是 25。这种问题如果靠人肉看代码，可能要看很久，但 Agent 结合日志和代码一对比，几秒钟就定位了。

我很快养成一个习惯：所有烧录、运行、操控动作，我都会把串口日志完整保留。遇到问题不自己瞎猜，直接连日志带代码喂给 Agent，让它给修改建议。有日志的调试过程，Agent 的分析质量比只贴代码高一个量级。

3. 从自然语言到能跑的 Demo：完整实操节点记录

3.1 第一轮对话：让机械臂先动起来

我的第一条需求是这么写的：

“用 ESP32 做一个机械臂控制器，通过 WebSocket 接收 JSON 指令，控制 6 个舵机转动，角度范围 0 到 180。WiFi 名和密码先写成占位符，收到指令后串口打印出来。舵机引脚先用 13、12、14、27、26、25。”

Agent 返回了一个完整的烧录工程。我做的第一件事不是立刻烧录，而是先让它解释每段代码的作用，尤其是 WebSocket 服务初始化和舵机控制部分。这一步非常重要——尽管不写代码，但你必须能读懂代码逻辑，才能判断它是否符合你的硬件接线。

第一次烧录后，机械臂确实动了。但动作非常生硬，舵机从一个角度“跳”到另一个角度，完全没有平滑过渡。机械臂不是数字开关，这种急转不仅看起来不专业，长期还会损伤舵机齿轮。我让 Agent 加了一个“缓启动”的逻辑，也就是每个舵机的目标角度不是一步到位，而是按固定步长逐步逼近，形成类似自然运动的曲线效果。

3.2 第二轮对话：把“遥控器”长出来

机械臂能动了，接下来是遥控器界面。我把需求拆成了几条细节：

• 一个面板对应一个关节，面板里有一个从 0 到 180 的滑块，外加一个实时角度数；
• 页面底部放六个预设姿态按钮，点击后机械臂整体移动到某个固定姿势；
• 加一个急停按钮，点击后所有舵机立即回到 90 度中立位置；
• 界面要适配手机屏幕，按钮要大，方便手指点击。

Agent 生成的页面比我预想的好看很多，滑块、数字、按钮都带着现代的圆角风格和配色。最让我惊喜的是，它连滑块拖动时的数值防抖都处理了，不会因为快速拖动把中间值全部塞进 WebSocket 通道。这一步之后，遥控器已经有了可用的完整形态。

3.3 第三轮对话：硬件世界的恶意，Agent 看不见

如果说代码部分是 Agent 的主场，那硬件调试就完全反过来。我遇到的第一个大坑是舵机集体抖动。起初我以为是代码问题，让 Agent 反复检查 PWM 初始化、脉冲频率、通道分配，它给了好几个优化版本，全都没用。最后我把开发板换成外接电源给舵机供电，抖动立刻消失。

原因不复杂：开发板自带的稳压模块承受不了六个舵机同时启动的瞬时电流，电压跌落导致 PWM 信号异常。这种问题靠看代码永远排查不出来，必须对硬件有常识。第二个坑是“共地”——控制板和外接电源如果不共地，信号电平参考不一致，舵机就会不规律乱转。解决方案很简单，把两者的地线接到一起。

这两个坑让我彻底明白了一个边界：Agent 能帮你写出逻辑完美的代码，但物理世界的接线、供电、干扰这些问题，它看不见也猜不到，必须由人来处理。

3.4 第四轮对话：把遥控器打磨顺手

基础版本跑通后，我又花了不少时间在“手感”上。比如滑块步长：机械臂每转 1 度，实际末端会移动一段距离，如果想让细微调整更精准，就要把滑块步长调小；如果想让操作更快，步长就得大。Agent 改起来很快，我在对话里提一句“滑块步长改成每格 1 度，长按可以连续变化”，几秒钟它就完成了调整。

我还让它加了一个“随机动作”按钮，用来演示机械臂的灵活性。点击之后，程序会自动生成一组随机角度组合，让机械臂做一小段即兴动作。这个小功能对非技术朋友来参观时特别有展示效果。

4. 典型问题速查与排查技巧实录

我把实际操作中踩过坑的问题整理成了一张速查表，未必和你的项目一模一样，但排查思路是通用的。

还有一个特别实用的排查方法：让 Agent 在下位机代码里加上“指令回显”。也就是每收到一条有效指令，就在串口打印一条解析结果，包含指令类型、目标舵机编号和目标角度。这个回显让所有问题都变得可见——网页发没发出去、下位机收没收到、解析对不对，一眼就能分辨。遥控器系统越复杂，越需要这种“可观测性”。

5. 我复盘下来的几条判断标准

5.1 什么样的项目最适合用 Agent 做

这次机械臂遥控器的经历，让我对 Agent 的实际能力边界有了新的判断。它最适合做的项目，往往具备几个特征：技术栈主流、功能边界清晰、输出结果可以快速验证。Web 页面、通信协议、单片机控制逻辑，这些在它的训练数据里都有大量范例，生成质量自然高。

反过来，如果项目高度依赖隐性知识，比如复杂的机械结构设计、模拟电路调试、一个人说不清楚的业务规则，Agent 就无能为力。它能帮你把想法变成代码，但没法替你“知道”那些只有经验才能积累的内容。这时候强行用 Agent，反而会陷入“代码看起来对，但实际跑不通”的怪圈。

5.2 “一行代码没写”到底意味着什么

有人觉得“一行代码没写”等于“不需要技术能力”。实际上，它只是把技术能力的重心转移了。以前要会写代码，现在要会写需求、会做代码评审、会做硬件验证。后端返回一个 JSON，你能看懂什么意思；前端滑块没反应，你能从网络面板里判断 WebSocket 是否建立——这些能力没有一项是不需要学习的。

但不可否认，它对入门门槛的降低是实实在在的。以前需要花几周啃语法、看框架文档，现在只要你清楚自己要什么，Agent 能很快帮你拼出一个能跑的雏形。从“会写代码”到“会用代码解决问题”，这中间的过渡被 Agent 拉短了。

5.3 下一步我打算怎么扩展

这个遥控器项目目前只是一个起点。我接下来想做三件事：一是给机械臂加一个摄像头，通过图像识别自动定位目标物体；二是让 Agent 生成一份完整的标定脚本，用来微调每个舵机的角度映射，解决舵机个体差异带来的精度问题；三是把遥控器界面从单机版改成可多人连接的版本，让几个朋友在同一局域网里同时观察和操作。

这三件事的代码量远大于现在的遥控器，但按这次的经验，Agent 完全可以帮我完成很大一部分。关键仍然在我这边：有没有把每一步的需求拆到位，能不能准确判断硬件的物理限制。

这次项目给我最深的感受是：Agent 不是替你思考，而是替你执行。你把“想”的质量提上去，它的“执行”才有意义。机械臂遥控器只是一个小例子，但它把人和工具各自的位置摆得非常清楚。