🔄 三种编程范式对比

📋 规格驱动开发 (Spec-Driven)

AI 原生开发的核心是规格驱动——你写清楚"要什么"，AI 负责"怎么做"。

# 规格示例: 网球检测节点
名称: tennis_detector
输入: camera_frame (RGB, 640x480)
输出: detections [{x, y, confidence, class}]
要求:
  - 检测黄色球形物体 (HSV 范围: H=20-35, S=100-255, V=100-255)
  - 最小面积阈值: 500px
  - 返回置信度 > 0.7 的检测结果
  - 处理延迟 < 33ms (30fps)
异常:
  - 无检测结果 → 返回空列表
  - 帧读取失败 → 报错并跳过

✅ 你的角色变化

🔗 端到端数据流

📦 各层职责速览

📊 三者对比

🔊 三阶段流水线

🛠️ 搭建步骤

# 1. 克隆 OminiX-API
git clone https://github.com/OminiX-Team/OminiX-API.git
cd OminiX-API

# 2. 安装依赖
pip install -r requirements.txt

# 3. 配置 ASR
export ASR_MODEL=whisper-large-v3

# 4. 配置 LLM
export LLM_API_KEY=your_key
export LLM_BASE_URL=https://api.openai.com/v1

# 5. 启动服务
python app.py --port 8080

# 6. 测试
curl -X POST http://localhost:8080/asr -F "audio=@test.wav"
curl -X POST http://localhost:8080/tts -d '{"text":"收到"}' -o out.wav

💡 关键接口

🎯 检测流程

HSV 范围: H=20-35 (黄色), S=100-255, V=100-255。形态学: 膨胀→腐蚀 去除噪点。

📝 核心代码

import cv2, numpy as np

def detect_tennis_ball(frame):
    """检测网球，返回 (x, y, radius, confidence) 或 None"""
    hsv = cv2.cvtColor(frame, cv2.COLOR_BGR2HSV)
    lower = np.array([20, 100, 100])
    upper = np.array([35, 255, 255])
    mask = cv2.inRange(hsv, lower, upper)
    kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (5,5))
    mask = cv2.morphologyEx(mask, cv2.MORPH_CLOSE, kernel)
    mask = cv2.morphologyEx(mask, cv2.MORPH_OPEN, kernel)
    contours, _ = cv2.findContours(mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
    if not contours: return None
    c = max(contours, key=cv2.contourArea)
    if cv2.contourArea(c) < 500: return None
    (x, y), r = cv2.minEnclosingCircle(c)
    return (int(x), int(y), int(r), 0.9)

🔄 ReAct 循环

🛠️ 工具定义示例

tools = [
    {"name": "move_base", "desc": "移动底盘到指定位置",
     "params": {"x": float, "y": float, "theta": float}},
    {"name": "scan_area", "desc": "扫描区域寻找目标",
     "params": {"direction": ["left","right","full"]}},
    {"name": "pick_object", "desc": "抓取指定位置的物体",
     "params": {"x": float, "y": float, "z": float}},
]

📊 数据模型

{
  "objects": [{
    "id": "tennis_ball_1",
    "position": { "x": 1.2, "y": 0.5, "z": 0.05 },
    "confidence": 0.92,
    "last_seen": "2026-07-06T13:45:00Z",
    "status": "visible"
  }],
  "robot": {
    "position": { "x": 0, "y": 0, "theta": 0 },
    "arm_state": "home",
    "gripper": "open"
  },
  "task": {
    "goal": "pick and place tennis ball",
    "current_step": "scanning",
    "retries": 0
  }
}

🧠 设计原则

📊 数据流图

🦀 自定义 Rust 节点

use dora_node_api::{DoraEvent, DoraOutputSender};

fn main() -> eyre::Result<()> {
    let (_node, mut events) = dora_node_api::DoraNode::init_from_env()?;
    let sender = DoraOutputSender::new()?;
    while let Some(event) = events.recv() {
        if let DoraEvent::Input { id, data, .. } = event {
            if id == "camera_frame" {
                let detections = detect_tennis_ball(&data.try_into()?);
                sender.send_output("detections", detections)?;
            }
        }
    }
    Ok(())
}

🏗️ 三层架构

🔑 各层特点

🎯 技能分解

🔧 关键命令

🔗 端到端流程

1. 用户说: "帮我把网球捡起来放到盒子里"
2. ASR → 文本: "帮我把网球捡起来放到盒子里"
3. LLM 理解意图 → 结构化任务:
   {"action": "pick_and_place",
    "object": "tennis_ball",
    "destination": "box"}
4. Octos Agent 生成计划:
   Step 1: scan_area(direction="full")
   Step 2: move_to(target=ball.position)
   Step 3: pick_object(ball.position)
   Step 4: move_to(target=box.position)
   Step 5: place_object(box.position)
5. dora-rs 逐步执行每个技能
6. World Model 实时更新状态
7. TTS 反馈: "已将网球放入盒中"

⚠️ 常见失败场景

🔄 恢复策略

def execute_with_recovery(plan, max_retries=3):
    for step in plan:
        for attempt in range(max_retries):
            result = execute_step(step)
            if result.success:
                world_model.update(result)
                break
            elif attempt < max_retries - 1:
                tts.speak("正在重试...")
            else:
                # 重新感知 → 重新规划
                new_state = scan_and_update()
                plan = replan(goal, new_state)

📋 四步工作流

📝 你的职责

• 写规格：用自然语言 + 结构化格式描述"要什么"
• 审计划：检查 AI 的实现计划是否合理
• 评代码：审查 AI 生成的代码，发现 bug 和改进点
• 验结果：运行测试，确认行为符合规格

📦 交付物清单

📅 最后3天安排