本文作者：茉卷，TRAE 开发者用户
背景
TurboPi 是一款由 Raspberry Pi 5 驱动的智能 AI 视觉机器人车套件， 配备 Mecanum 轮实现 360° 全向移动，2DOF 云台支持 360° 摄像头视角，具备面部检测、手势识别和二维码控制功能。
本文将介绍如何利用 TRAE + Spec-kit 实现一个控制小车方向的 前后端系统。
实现目标
前置条件：树莓派小车与 PC 需在同一局域网内
-
在 PC 上实现一个 React 前端页面，用来连接、控制小车移动。
-
在树莓派小车上，实现一个 FastAPI 后端，用来接收命令并执行。
Spec-kit 初始化
详细步骤，请大家查看 之前的公众号文章：TRAE × Spec Kit 实战：五步构建流式 AI 对话 Web 应用
示例我的项目路径 （turbopi_backend）：
bash
/Users/susirial/work_station/Turbopi/Turbopi_ios/spec_turbopi_backend/spec-kit-main/turbopi_backend
Spec-kit 关键 步骤执行
我们需要依次执行以下命令生成关键文档：
-
/speckit.constitution - 生成项目章程
-
/speckit.specify - 生成需求规格
-
/speckit.plan - 生成技术方案
-
/speckit.tasks - 生成任务拆分
-
/speckit.implement - 执行代码实现
3.1 /speckit.constitution
第一步，生成项目章程文档，大家根据需求设定即可。
模型： GPT-5
输入指令：
注意：#speckit.constitution.md 需要通过 # 号选中文档（后续步骤同理）
arduino
#speckit.constitution.md 制定以代码质量、测试标准、用户体验一致性及性能要求为核心的原则
输出： TRAE 生成项目宪章文档 constitution.md 并更新相关模板。
3.2 /speckit.specify
接下来是需求说明：
模型： GPT-5
输入指令：
arduino
#speckit.specify.md 我有一个树莓派小车 Turbopi, 它是UBUNTU系统 ，它支持ROS2 系统。 我想实现一个后端，这个后端可以控制小车的方向，摄像头，其上搭载的LLM模型服务、LED等等组件。
输出： TRAE 生成 SPEC 文档和需求文档。
markdown
# 规格质量检查清单 - Turbopi 控制后端（ROS2）
**Created** : 2025-10-28
**Spec Path** : `turbopi_backend/specs/001-ros2-control-backend/spec.md`
## 检查范围
- 覆盖用户故事、边界场景、功能性需求、关键实体与可度量成功指标。
- 面向技术无关的规范与交付质量门槛，不涉及具体技术栈实现。
## 一、代码质量（语义一致性、错误统一、可维护性）
- [PASS] 指令与状态语义统一（CarCommand/CarState 命名清晰且可追踪）。
- [PASS] 统一错误结构（message/code/details/request_id）在 FR-007 明确。
- [PASS] 安全急停与超时回退语义独立、互不依赖，便于隔离测试。
- [PASS] LLM 能力默认与行驶控制隔离，需安全评估后再联动（FR-005）。
- [NOTE] 授权方式未定（FR-008 标记 NEEDS CLARIFICATION）。
- [PASS] 运行时模式（macbook_sim / raspberry_pi_ros2）与统一 API 语义一致（FR-012/FR-016）。
- [PASS] ROS2 控制语义（`cmd_vel` 发布与停止时 `Twist()` 清零）明确（FR-014）。
- [NOTE] 远程代码执行的沙箱/资源限制策略待定（FR-015 标记 NEEDS CLARIFICATION）。
## 二、测试标准（独立可测、验收场景、结果可观测）
- [PASS] 每个用户故事声明独立测试路径，最小可测 MVP 明确。
- [PASS] 验收场景采用 Given/When/Then，结果有"状态/反馈"锚点。
- [PASS] 边界场景覆盖硬件不可用/服务离线/网络中断等重要异常。
- [NOTE] 建议在实现阶段补充"通信丢失超时值"的确定性测试门槛。
- [PASS] Zeroconf 服务发现验收场景覆盖 macbook 与树莓派两种模式，前端可读取服务基本信息。
- [PASS] 远程代码执行端点具备可观察输出（stdout/stderr/exit_code）与 `job_id` 跟踪。
## 三、用户体验一致性（反馈一致、跨子系统协同）
- [PASS] 行驶/摄像头/LED/LLM 的反馈结构一致，便于统一 UI 显示。
- [PASS] LED 可映射系统状态（录制/急停/LLM 处理中），降低认知负担。
- [PASS] 基础能力（行驶与急停）优先交付，其他能力独立递进。
- [NOTE] LLM 回复与控制权限边界需在实施期做明示提示与开关控制。
- [PASS] 统一 API 在两种模式下保持一致，避免前端分叉逻辑（FR-012/FR-016）。
- [PASS] 服务发现结果包含模式标签，前端可正确呈现运行环境。
## 四、性能与可度量目标（技术无关、面向体验）
- [PASS] 行驶指令反馈 ≤1s（95%），摄像头预览 ≤2s、快照 ≤1s（95%）。
- [PASS] LED 控制 ≤0.5s（95%）；LLM 文本回复 ≤5s（90%）。
- [PASS] 急停 100% 在安全时间窗内完成并返回停止状态。
- [NOTE] 安全时间窗及通信超时阈值需在实施时固化为配置常量。
- [PASS] Zeroconf 发现成功率 ≥95%，发现耗时 ≤3s（典型网络）。
- [PASS] 远程代码执行 trivial 片段 ≤1s 返回（90%），阻塞代码 100% 触发超时并返回错误。
## 结论
- 当前规格满足"代码质量、测试标准、体验一致性、性能指标"的四项宪法原则要求。
- 存在 3 处必要澄清：
1) 是否允许 LLM 触发行驶指令（需安全评估）。
2) 通信丢失/超时回退的阈值（需配置与测试门槛）。
3) 授权方式（令牌/账号/局域网白名单等）待明确。
新增澄清项：
4) Zeroconf 服务类型与 TXT 字段约定（与 iOS 发现兼容）。
5) 远程代码执行的沙箱策略（白名单库、资源限制、超时策略）。
这些澄清不影响当前规格作为实施输入的可用性，可在技术方案阶段冻结。3.3 /speckit.plan
接下来，我们描述一下技术实现细节要求。
模型： GPT-5
输入指令：
arduino
#speckit.plan.md 后端需要使用 python FastApi 实现。 需要 使用 zeroconf 来生成 turbopi_backend 服务可以让iOS前端NetServiceBrowser 的搜索到。需要做一个运行时开关，开发时是在macbook上，所以需要区分macbook 和树莓派ubuntu. 树莓派的控制是在ROS2上，通过 import rclpy 来控制，比如控制小车前进 
输出： TRAE 更新 SPEC 文档和需求文档。
3.4 /speckit.tasks
接下来，需要让 TRAE 拆分出任务。
模型： GPT-5
输入指令：
arduino
#speckit.tasks.md 详细拆分出完整的task
3.5 /speckit.implement
接下来，我们让 TRAE 开始编码。
输入指令：
arduino
#speckit.implement.md 开始实施 Phase 1，Phase 2，Phase 3
优化
4.1 修复代码问题
这里我 review 了一下代码，发现对于小车的方向控制部分，模型生成的代码有问题：Y 应该表示小车横向移动，而不是 Z （这个通过阅读厂商参考代码可以发现）。
于是我贴了一些参考代码给 TRAE，让它自己修复。
4.2 前端测试页面
我们需要一个前端页面来测试，于是我让 TRAE 写一个前端来测试（这里只是一个测试页面，没有用框架）。
输入指令：
参考 backend 后端代码，实现一个vite react 的前端页面，支持查询服务，然后给出一个测试树莓派小车前后左右控制的前端页面，页面的风格需要美观、符合国际一流最佳实践。给出需求说明文档，放到 web_react 目录下面
页面有些问题，将底部的错误输入到 TRAE 对话框，让它检查，修复。
4.3 启动后端服务
把后端代码拷贝到树莓派小车，然后根据项目 README.md （TRAE 写代码时生成） 安装、启动后端服务。
笔记本上成功找到后台服务。
进入方向控制页面测试，一次通过测试（之前把完整的 DEMO 代码给到 TRAE）。
效果演示
总结
本文展示了如何使用 TRAE + Spec-kit 工具链，从需求定义到代码实现，完整构建一个树莓派智能小车控制系统。整个流程遵循规范化开发流程，通过 AI 辅助大幅提升开发效率，同时保证代码质量和系统可维护性。