热热的博客

MAYA2.0：全离线物联网 Agent

Tue, 30 Dec 2025 00:00:00 GMT

MAYA2.0 是一套装在家里的全离线语音中枢。

它想做的事和 1.0 是一脉相承的——让家里那些琐碎的事（开灯、关空调、屋里闷不闷）用说话就能办完。但这次的实现路子完全不同：不再靠一块 STM32 去驱动继电器，而是把语音识别、大模型、语音合成整条链路都塞进一台本地设备里，一句话都不出家门。

⚠️ 先说清楚一件容易搞混的事：MAYA2.0 和 MAYA1.0 是两个不同的项目，不是同一条产品线的两次迭代。1.0 的重心在硬件——STM32 主控、ASR-PRO 语音模块、OpenMV 视觉、四台 ESP8266 自组网，交付物是一台桌面机器人；2.0 的重心在软件——跑在 RDK X5 上的一套 Python 系统，交付物是一个语音 Agent。两者共用「MAYA」这个名字和「本地、可控、可解释」的设计口味，仅此而已。

项目小档案 开发自 2025 年 11 月 28 日定稿设计文档起，12 月 30 日完成。这一个月的主角不是业务代码，而是用 Prompt 把一整套离线轻量化模型调度起来——让 ASR、1.5B 的 LLM、TTS 和意图路由像一个整体那样协同；同时把第一 / 第三人称身份写死（谁是「我」、把对方称为什么），让 AI 更聪明地落地，也更贴合真实的应用环境。1.5B 的能力上限第二天就摸到了，之后所有的效果提升，全靠「怎么跟它说话」和「它说完之后怎么收拾」一点点挣出来。

下面分两半讲：前半是架构（它凭什么能在 10 TOPS 上跑起来），后半是踩坑（1.5B 的小模型到底有多不听话）。

一、它由哪些部分组成

层	选型	角色
中枢计算	RDK X5（10 TOPS）	同时跑 ASR + LLM + TTS + 对话调度
语音识别	Whisper（small）	离线转写，中文识别精度够用
大模型	Qwen2.5-1.5B-Instruct（q4_k_m GGUF）	llama.cpp 后端，全本地推理
语音合成	Piper（huayan 花颜）	离线、低延迟
设备通信	MQTT（Mosquitto）	一对多控制 ESP32
终端设备	ESP32 × N	继电器 / 舵机 / 传感器
交互界面	PyQt6 终端	对话、状态面板、设置
数据存储	SQLite × 3	记忆 / 隐私 / 时空状态

「全离线」这三个字是有代价的，也是这个项目所有设计取舍的源头：

没有兜底。云端助手答不上来可以换个更大的模型接着答，这里只有 1.5B 这一张牌，答砸了就是砸了。
算力是真的紧。10 TOPS 要同时养着语音识别、大模型推理和语音合成，还得留出余量给设备调度。
换来的是：断网可用、语音数据不出设备、没有按次计费的 API、行为完全可预期——包括可以随时打开数据库，把系统「记住」的东西一条条翻出来看、删掉。

二、10 TOPS 的账：为什么是 1.5B

选模型就是算账。一台本地设备要同时装下语音识别、大模型、语音合成三套模型，模型越大越聪明，但留给语音链路和调度逻辑的余量就越少。

量级	能力	在这台设备上
7B	明显更强，能处理复杂推理	延迟与显存都吃不下，语音交互的「即时感」会先崩
3B	折中	余量紧张，语音链路会被挤压
1.5B	够做短对话、够守规则	性能与能力的平衡点

真正拍板的不是「哪个最聪明」，而是「哪个能在这个算力下稳定地、口语化地、短促地回话」。语音交互对延迟极其敏感——用户说完到听到回应超过两秒，体验就散了。所以输出长度被死死按在 80 tokens 以内，回答要求控制在 1–3 句话，这既是为了体验，也是为了给单次推理省时间。

量化方面选了 q4_k_m：在 1.5B 这个量级上，4 位量化的精度损失基本看不出来，但显存占用和推理速度的收益是实打实的。

关键参数都在 config/system.yaml 里，值得看一眼：

llm:
  model_path: "./models/qwen/qwen2.5-1.5b-instruct-q4_k_m.gguf"
  backend: "llama.cpp"
  context_size: 2048        # 上下文窗口
  n_threads: 4              # GPU 模式下的 CPU 调度线程
  n_gpu_layers: -1          # -1 = 全部层放 GPU
  n_batch: 512
  temperature: 0.6
  top_p: 0.9
  max_tokens: 80            # 刻意压低：限制长度，避免过长回复和重复

asr:
  model_size: "small"       # tiny / small / base；small 的中文识别更稳
  language: "zh"
  audio_sample_rate: 16000

tts:
  voice: "huayan"
  sample_rate: 22050

这里的 context_size: 2048 和 max_tokens: 80 是一对需要一起看约束：

$$ \underbrace{n_{ctx}}{\text{2048}} ;\ge; \underbrace{T{prompt}}{\text{身份+记忆+上下文+实时状态}} + \underbrace{T{output}}_{\text{80}} $$

而 Prompt 里要塞进的区块有 7～8 段（身份、人格、记忆、隐私、上下文、实时状态、用户输入，ROOT 模式下再多一段权限声明），一旦记忆条数放开，T_prompt 会迅速吃掉窗口——这就是后面「记忆最多注入 5 条」这条硬限制的由来，不是拍脑袋定的。

<figure class="maya-diagram" data-maya="01-architecture"> <div class="maya-scroll"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 644 451" width="644" height="451" class="maya-svg" role="img" aria-label="MAYA2.0 的四层架构图：输入层（麦克风阵列离线唤醒、PyQt6 文字终端）；认知层跑在 RDK X5 上（Whisper 语音识别、IntentRouter 意图路由、Qwen2.5-1.5B 大模型、Piper 语音合成）；数据层是三个 SQLite 库（记忆库、隐私库、时空状态库）；执行层经 MQTT 驱动多台 ESP32，MQTT 不可用时由设备模拟器降级接管。"><g class="maya-links"><path d="M156.3 215.8 C177.1 215.8 173.3 46.1 194.1 46.1" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M156.3 215.8 C177.1 215.8 173.3 153.8 194.1 153.8" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M156.3 215.8 C177.1 215.8 173.3 277.8 194.1 277.8" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M156.3 215.8 C177.1 215.8 173.3 385.5 194.1 385.5" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M250.8 46.1 C315.1 46.1 303.4 29.8 367.7 29.8" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M250.8 46.1 C315.1 46.1 303.4 62.4 367.7 62.4" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M329.9 153.8 C350.7 153.8 346.9 104.9 367.7 104.9" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M329.9 153.8 C350.7 153.8 346.9 137.5 367.7 137.5" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M329.9 153.8 C350.7 153.8 346.9 170.1 367.7 170.1" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M329.9 153.8 C350.7 153.8 346.9 202.7 367.7 202.7" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M275.4 277.8 C326.1 277.8 316.9 245.2 367.7 245.2" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/><path d="M275.4 277.8 C326.1 277.8 316.9 277.8 367.7 277.8" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/><path d="M275.4 277.8 C326.1 277.8 316.9 310.4 367.7 310.4" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/><path d="M250.8 385.5 C315.1 385.5 303.4 353.0 367.7 353.0" fill="none" stroke="#f59e0b" stroke-opacity="0.42" stroke-width="1.4"/><path d="M250.8 385.5 C315.1 385.5 303.4 385.5 367.7 385.5" fill="none" stroke="#f59e0b" stroke-opacity="0.42" stroke-width="1.4"/><path d="M250.8 385.5 C315.1 385.5 303.4 418.1 367.7 418.1" fill="none" stroke="#f59e0b" stroke-opacity="0.42" stroke-width="1.4"/></g><g class="maya-node" data-n="0" data-d="0" data-t="MAYA 2.0 全离线语音中枢"><text x="20.0" y="208.5" font-size="19" font-weight="700" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">MAYA 2.0</text><text x="20.0" y="236.0" font-size="19" font-weight="700" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">全离线语音中枢</text><rect x="20.0" y="244.4" width="136.3" height="3" rx="1.5" fill="currentColor" fill-opacity="0.5"/></g><g class="maya-node" data-n="1" data-d="1" data-t="输入层"><circle cx="193.1" cy="46.1" r="3.2" fill="#8b5cf6" fill-opacity="0.9"/><text x="202.3" y="51.3" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">输入层</text><rect x="202.3" y="58.3" width="48.5" height="2.5" rx="1.25" fill="#8b5cf6" fill-opacity="0.95"/></g><g class="maya-node" data-n="2" data-d="2" data-t="麦克风阵列——离线唤醒，不联网"><circle cx="367.5" cy="29.8" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="375.9" y="34.4" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">麦克风阵列——离线唤醒，不联网</text><rect x="375.9" y="40.6" width="198.0" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="3" data-d="2" data-t="文字输入——PyQt6 终端 / 命令行"><circle cx="367.5" cy="62.4" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="375.9" y="67.0" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">文字输入——PyQt6 终端 / 命令行</text><rect x="375.9" y="73.2" width="196.2" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="4" data-d="1" data-t="认知层 RDK X5 · 10 TOPS"><circle cx="193.1" cy="153.8" r="3.2" fill="#ec4899" fill-opacity="0.9"/><text x="202.3" y="147.8" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">认知层</text><text x="202.3" y="170.3" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">RDK X5 · 10 TOPS</text><rect x="202.3" y="177.3" width="127.6" height="2.5" rx="1.25" fill="#ec4899" fill-opacity="0.95"/></g><g class="maya-node" data-n="5" data-d="2" data-t="ASR · Whisper small（CPU）"><circle cx="367.5" cy="104.9" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="375.9" y="109.5" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">ASR · Whisper small（CPU）</text><rect x="375.9" y="115.7" width="176.8" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="6" data-d="2" data-t="意图路由 · IntentRouter（10 种意图）"><circle cx="367.5" cy="137.5" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="375.9" y="142.1" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">意图路由 · IntentRouter（10 种意图）</text><rect x="375.9" y="148.3" width="227.6" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="7" data-d="2" data-t="LLM · Qwen2.5-1.5B-Instruct + llama.cpp"><circle cx="367.5" cy="170.1" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="375.9" y="174.7" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">LLM · Qwen2.5-1.5B-Instruct + llama.cpp</text><rect x="375.9" y="180.9" width="248.5" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="8" data-d="2" data-t="TTS · Piper（huayan 花颜）"><circle cx="367.5" cy="202.7" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="375.9" y="207.3" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">TTS · Piper（huayan 花颜）</text><rect x="375.9" y="213.4" width="169.4" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="9" data-d="1" data-t="数据层 SQLite × 3"><circle cx="193.1" cy="277.8" r="3.2" fill="#06b6d4" fill-opacity="0.9"/><text x="202.3" y="271.8" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">数据层</text><text x="202.3" y="294.3" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">SQLite × 3</text><rect x="202.3" y="301.3" width="73.1" height="2.5" rx="1.25" fill="#06b6d4" fill-opacity="0.95"/></g><g class="maya-node" data-n="10" data-d="2" data-t="记忆库 maya_memory"><circle cx="367.5" cy="245.2" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="375.9" y="249.8" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">记忆库 maya_memory</text><rect x="375.9" y="256.0" width="134.9" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g><g class="maya-node" data-n="11" data-d="2" data-t="隐私库 maya_privacy"><circle cx="367.5" cy="277.8" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="375.9" y="282.4" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">隐私库 maya_privacy</text><rect x="375.9" y="288.6" width="128.4" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g><g class="maya-node" data-n="12" data-d="2" data-t="时空状态库 maya_realtime"><circle cx="367.5" cy="310.4" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="375.9" y="315.0" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">时空状态库 maya_realtime</text><rect x="375.9" y="321.2" width="160.9" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g><g class="maya-node" data-n="13" data-d="1" data-t="执行层"><circle cx="193.1" cy="385.5" r="3.2" fill="#f59e0b" fill-opacity="0.9"/><text x="202.3" y="390.8" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">执行层</text><rect x="202.3" y="397.8" width="48.5" height="2.5" rx="1.25" fill="#f59e0b" fill-opacity="0.95"/></g><g class="maya-node" data-n="14" data-d="2" data-t="MQTT · Mosquitto"><circle cx="367.5" cy="353.0" r="2.4" fill="#f59e0b" fill-opacity="0.9"/><text x="375.9" y="357.6" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">MQTT · Mosquitto</text><rect x="375.9" y="363.8" width="111.0" height="1.8" rx="0.9" fill="#f59e0b" fill-opacity="0.8"/></g><g class="maya-node" data-n="15" data-d="2" data-t="ESP32 × N——继电器 / 舵机 / 传感器"><circle cx="367.5" cy="385.5" r="2.4" fill="#f59e0b" fill-opacity="0.9"/><text x="375.9" y="390.1" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">ESP32 × N——继电器 / 舵机 / 传感器</text><rect x="375.9" y="396.3" width="217.7" height="1.8" rx="0.9" fill="#f59e0b" fill-opacity="0.8"/></g><g class="maya-node" data-n="16" data-d="2" data-t="DeviceSimulator——MQTT 断了就降级"><circle cx="367.5" cy="418.1" r="2.4" fill="#f59e0b" fill-opacity="0.9"/><text x="375.9" y="422.7" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">DeviceSimulator——MQTT 断了就降级</text><rect x="375.9" y="428.9" width="229.2" height="1.8" rx="0.9" fill="#f59e0b" fill-opacity="0.8"/></g></svg></div> </figure>

三、从一句话到设备动作

整条链路是一条流水线。主循环本身很薄，它只做三件事：采集 → 判断有没有叫我 → 交给对话管理器：

def run(self):
    while self.running:
        # 1. 音频采集与 ASR
        asr_result = self.asr_service.listen_and_transcribe()
        if not asr_result or not asr_result.get("text"):
            continue

        user_text = asr_result.get("text", "")

        # 2. 检查唤醒词——没叫我就不处理
        if not self._check_wake_word(user_text):
            continue

        # 移除唤醒词，只把有效内容交给下游
        user_text_clean = self._remove_wake_word(user_text)
        if not user_text_clean.strip():
            self.tts_service.speak("我在，请说")
            continue

        asr_result["text"] = user_text_clean

        # 3. 对话处理
        result = self.dialogue_manager.process_input(asr_result)

        # 4. TTS 输出
        if result.get("need_tts") and result.get("response"):
            self.tts_service.speak(result["response"])

唤醒词的判定刻意做得宽容——ASR 会把「MAYA」听成各种样子，所以候选表里塞了同音变体：

def _check_wake_word(self, text: str) -> bool:
    wake_variants = [self.wake_word.lower(), "maya", "玛雅", "麦娅", "may a"]
    return any(variant in text.lower() for variant in wake_variants)

下游是 DialogueManager.process_input()，它才是真正的调度中枢：先看是不是在等口令，再看要不要 ROOT 模式，然后才把文本交给意图路由。

<figure class="maya-diagram" data-maya="02-dataflow"> <div class="maya-scroll"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 644 440" width="644" height="440" class="maya-svg" role="img" aria-label="MAYA2.0 的数据流图：麦克风阵列拾音（16 kHz 单声道）→ Whisper 离线转写为文本 → IntentRouter 规则优先分流；设备控制分支抽取房间/设备/动作/数值等槽位后经 MQTT 下发到 ESP32 驱动继电器；普通对话分支先注入最多 5 条记忆与时空状态（仅 ROOT 模式注入隐私）再交给大模型生成回复；最后统一由 Piper 合成语音播放。"><g class="maya-links"><path d="M175.5 225.8 C196.3 225.8 192.6 46.1 213.3 46.1" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M175.5 225.8 C196.3 225.8 192.6 104.9 213.3 104.9" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M175.5 225.8 C196.3 225.8 192.6 147.5 213.3 147.5" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M175.5 225.8 C196.3 225.8 192.6 206.4 213.3 206.4" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M175.5 225.8 C196.3 225.8 192.6 314.1 213.3 314.1" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M175.5 225.8 C196.3 225.8 192.6 405.5 213.3 405.5" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M271.8 46.1 C314.4 46.1 306.7 29.8 349.3 29.8" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M271.8 46.1 C314.4 46.1 306.7 62.4 349.3 62.4" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M271.8 104.9 C314.4 104.9 306.7 104.9 349.3 104.9" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M271.8 147.5 C314.4 147.5 306.7 147.5 349.3 147.5" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/><path d="M311.0 206.4 C332.1 206.4 328.2 190.1 349.3 190.1" fill="none" stroke="#f59e0b" stroke-opacity="0.42" stroke-width="1.4"/><path d="M311.0 206.4 C332.1 206.4 328.2 222.7 349.3 222.7" fill="none" stroke="#f59e0b" stroke-opacity="0.42" stroke-width="1.4"/><path d="M311.5 314.1 C332.3 314.1 328.5 265.2 349.3 265.2" fill="none" stroke="#10b981" stroke-opacity="0.42" stroke-width="1.4"/><path d="M311.5 314.1 C332.3 314.1 328.5 297.8 349.3 297.8" fill="none" stroke="#10b981" stroke-opacity="0.42" stroke-width="1.4"/><path d="M311.5 314.1 C332.3 314.1 328.5 330.4 349.3 330.4" fill="none" stroke="#10b981" stroke-opacity="0.42" stroke-width="1.4"/><path d="M311.5 314.1 C332.3 314.1 328.5 363.0 349.3 363.0" fill="none" stroke="#10b981" stroke-opacity="0.42" stroke-width="1.4"/><path d="M271.8 405.5 C314.4 405.5 306.7 405.5 349.3 405.5" fill="none" stroke="#ef4444" stroke-opacity="0.42" stroke-width="1.4"/></g><g class="maya-node" data-n="0" data-d="0" data-t="一次唤醒到设备动作"><text x="78.4" y="218.5" font-size="19" font-weight="700" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">一次唤醒</text><text x="78.4" y="246.0" font-size="19" font-weight="700" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">到设备动作</text><rect x="78.4" y="254.4" width="97.1" height="3" rx="1.5" fill="currentColor" fill-opacity="0.5"/></g><g class="maya-node" data-n="1" data-d="1" data-t="① 拾音"><circle cx="212.3" cy="46.1" r="3.2" fill="#8b5cf6" fill-opacity="0.9"/><text x="221.5" y="51.3" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">① 拾音</text><rect x="221.5" y="58.3" width="50.2" height="2.5" rx="1.25" fill="#8b5cf6" fill-opacity="0.95"/></g><g class="maya-node" data-n="2" data-d="2" data-t="麦克风阵列采集"><circle cx="349.1" cy="29.8" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="357.5" y="34.4" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">麦克风阵列采集</text><rect x="357.5" y="40.6" width="96.4" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="3" data-d="2" data-t="16 kHz 单声道"><circle cx="349.1" cy="62.4" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="357.5" y="67.0" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">16 kHz 单声道</text><rect x="357.5" y="73.2" width="87.8" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="4" data-d="1" data-t="② 识别"><circle cx="212.3" cy="104.9" r="3.2" fill="#ec4899" fill-opacity="0.9"/><text x="221.5" y="110.2" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">② 识别</text><rect x="221.5" y="117.2" width="50.2" height="2.5" rx="1.25" fill="#ec4899" fill-opacity="0.95"/></g><g class="maya-node" data-n="5" data-d="2" data-t="Whisper 离线转写"><circle cx="349.1" cy="104.9" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="357.5" y="109.5" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">Whisper 离线转写</text><rect x="357.5" y="115.7" width="108.6" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="6" data-d="1" data-t="③ 分流"><circle cx="212.3" cy="147.5" r="3.2" fill="#06b6d4" fill-opacity="0.9"/><text x="221.5" y="152.8" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">③ 分流</text><rect x="221.5" y="159.8" width="50.2" height="2.5" rx="1.25" fill="#06b6d4" fill-opacity="0.95"/></g><g class="maya-node" data-n="7" data-d="2" data-t="IntentRouter 规则优先"><circle cx="349.1" cy="147.5" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="357.5" y="152.1" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">IntentRouter 规则优先</text><rect x="357.5" y="158.3" width="134.4" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g><g class="maya-node" data-n="8" data-d="1" data-t="④a 设备控制"><circle cx="212.3" cy="206.4" r="3.2" fill="#f59e0b" fill-opacity="0.9"/><text x="221.5" y="211.6" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">④a 设备控制</text><rect x="221.5" y="218.6" width="89.5" height="2.5" rx="1.25" fill="#f59e0b" fill-opacity="0.95"/></g><g class="maya-node" data-n="9" data-d="2" data-t="抽取房间 / 设备 / 动作 / 数值"><circle cx="349.1" cy="190.1" r="2.4" fill="#f59e0b" fill-opacity="0.9"/><text x="357.5" y="194.7" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">抽取房间 / 设备 / 动作 / 数值</text><rect x="357.5" y="200.9" width="172.7" height="1.8" rx="0.9" fill="#f59e0b" fill-opacity="0.8"/></g><g class="maya-node" data-n="10" data-d="2" data-t="MQTT → ESP32 → 继电器动作"><circle cx="349.1" cy="222.7" r="2.4" fill="#f59e0b" fill-opacity="0.9"/><text x="357.5" y="227.3" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">MQTT → ESP32 → 继电器动作</text><rect x="357.5" y="233.4" width="186.5" height="1.8" rx="0.9" fill="#f59e0b" fill-opacity="0.8"/></g><g class="maya-node" data-n="11" data-d="1" data-t="④b 普通对话"><circle cx="212.3" cy="314.1" r="3.2" fill="#10b981" fill-opacity="0.9"/><text x="221.5" y="319.4" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">④b 普通对话</text><rect x="221.5" y="326.3" width="89.9" height="2.5" rx="1.25" fill="#10b981" fill-opacity="0.95"/></g><g class="maya-node" data-n="12" data-d="2" data-t="注入记忆——最多 5 条"><circle cx="349.1" cy="265.2" r="2.4" fill="#10b981" fill-opacity="0.9"/><text x="357.5" y="269.8" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">注入记忆——最多 5 条</text><rect x="357.5" y="276.0" width="131.5" height="1.8" rx="0.9" fill="#10b981" fill-opacity="0.8"/></g><g class="maya-node" data-n="13" data-d="2" data-t="注入时空状态——时间 / 地点 / 天气"><circle cx="349.1" cy="297.8" r="2.4" fill="#10b981" fill-opacity="0.9"/><text x="357.5" y="302.4" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">注入时空状态——时间 / 地点 / 天气</text><rect x="357.5" y="308.6" width="208.5" height="1.8" rx="0.9" fill="#10b981" fill-opacity="0.8"/></g><g class="maya-node" data-n="14" data-d="2" data-t="仅 ROOT 模式注入隐私"><circle cx="349.1" cy="330.4" r="2.4" fill="#10b981" fill-opacity="0.9"/><text x="357.5" y="335.0" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">仅 ROOT 模式注入隐私</text><rect x="357.5" y="341.2" width="137.7" height="1.8" rx="0.9" fill="#10b981" fill-opacity="0.8"/></g><g class="maya-node" data-n="15" data-d="2" data-t="LLM 生成回复"><circle cx="349.1" cy="363.0" r="2.4" fill="#10b981" fill-opacity="0.9"/><text x="357.5" y="367.6" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">LLM 生成回复</text><rect x="357.5" y="373.8" width="85.6" height="1.8" rx="0.9" fill="#10b981" fill-opacity="0.8"/></g><g class="maya-node" data-n="16" data-d="1" data-t="⑤ 播报"><circle cx="212.3" cy="405.5" r="3.2" fill="#ef4444" fill-opacity="0.9"/><text x="221.5" y="410.8" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">⑤ 播报</text><rect x="221.5" y="417.8" width="50.2" height="2.5" rx="1.25" fill="#ef4444" fill-opacity="0.95"/></g><g class="maya-node" data-n="17" data-d="2" data-t="Piper 合成后本地播放"><circle cx="349.1" cy="405.5" r="2.4" fill="#ef4444" fill-opacity="0.9"/><text x="357.5" y="410.1" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">Piper 合成后本地播放</text><rect x="357.5" y="416.3" width="131.3" height="1.8" rx="0.9" fill="#ef4444" fill-opacity="0.8"/></g><text x="194.4" y="130.9" text-anchor="middle" font-size="11" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor" fill-opacity="0.55">音频流</text><text x="194.4" y="160.4" text-anchor="middle" font-size="11" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor" fill-opacity="0.55">文本 + 语言</text><text x="194.4" y="181.7" text-anchor="middle" font-size="11" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor" fill-opacity="0.55">意图</text><text x="194.4" y="211.1" text-anchor="middle" font-size="11" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor" fill-opacity="0.55">slots</text><text x="194.4" y="265.0" text-anchor="middle" font-size="11" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor" fill-opacity="0.55">Prompt</text><text x="194.4" y="310.7" text-anchor="middle" font-size="11" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor" fill-opacity="0.55">语音</text></svg></div> </figure>

四、意图路由：能不用 LLM 就不用 LLM

这是整个系统里我最满意的设计。

大模型能理解语言，但它的输出不可预期——同样的输入，它可能给你一句话、也可能给你三段话，还可能顺手编个设备名出来。而「打开客厅灯」这种事，压根不需要理解能力，它需要的是确定性。

所以系统在 LLM 前面横了一道 IntentRouter：规则能判的，绝不交给模型。

优先级	意图	判定依据	置信度
1	`WAKE_UP`	MAYA / 玛雅 / 麦娅 / may a	0.95
2	`DEVICE_CONTROL`	动作词 + 设备名	0.88
3	`SYSTEM_CONTROL`	音量 / 模式 / 暂停（调的是 MAYA 自己）	0.80
4	`DEVICE_QUERY`	吗 / 状态 / 现在 / 开着 + 设备名	0.85
5	`MEMORY_WRITE`	第一人称 + 习惯词，且不含控制动作	0.70–0.80
6	`MEMORY_QUERY`	第一人称 + 怎么样 / 是不是 / 多久	0.80
7	`GENERAL_CHAT`	兜底分类	0.70
8	`FALLBACK_TO_LLM`	规则全判不出来	须 > 0.6

路由主干就是一条 if-else 链，顺序即优先级：

def route_intent(self, asr_text) -> IntentObject:
    text = asr_text.get("text", "").strip() if isinstance(asr_text, dict) else str(asr_text).strip()

    if not text:
        return IntentObject(self.FALLBACK_TO_LLM, 0.0, {}, text)

    # 1. 唤醒词
    if self._check_wake_up(text):
        return IntentObject(self.WAKE_UP, 0.95, {}, text)

    # 2. 设备控制
    device_control = self._check_device_control(text)
    if device_control:
        return device_control

    # 3. 系统控制（先排除「进入 ROOT 模式」这类请求，避免误分类）
    root_keywords = ["进入root", "开启root", "激活root", "root模式", "管理员模式"]
    is_root_request = any(kw in text.lower() for kw in root_keywords)
    if not is_root_request:
        system_control = self._check_system_control(text)
        if system_control:
            return system_control

    # 4~7：设备查询 → 记忆写入 → 记忆查询 → 普通对话
    ...

设备控制的关键不是「听懂」，而是把槽位抽干净——房间、设备、动作、数值，缺一个下游就没法执行：

def _extract_device_slots(self, text: str) -> Dict[str, Any]:
    slots = {"room": None, "device": None, "action": None, "value": None}

    for room in self.ROOMS:              # 客厅 / 卧室 / 厨房 / 卫生间 / 阳台 / 书房
        if room in text:
            slots["room"] = room
            break

    for device in self.DEVICE_NAMES:     # 灯 / 风扇 / 空调 / 窗帘 / 插座 / 电视 / 音响
        if device in text:
            slots["device"] = device
            break

    if "打开" in text or "开启" in text:
        slots["action"] = "ON"
    elif "关闭" in text:
        slots["action"] = "OFF"
    elif "调高" in text:
        slots["action"] = "UP"
    elif "调低" in text:
        slots["action"] = "DOWN"

    m = re.search(r'(\d+)', text)        # 「调到 26 度」
    if m:
        slots["value"] = int(m.group(1))

    return slots

踩坑：`MEMORY_WRITE` 太容易误判

「记忆写入」是这套系统里判定最难的意图。它的出发点很好——用户陈述一个长期习惯，系统记下来，下次就能用上。但第一版规则是「第一人称 + 状态关键词」，于是这些东西全被当成习惯存进了数据库：

「我饿了」「我累了」「我困了」——临时状态，不是习惯
「我感冒了」「我头疼」——一次性的，明天就好了
「我是谁」「我的手机号」——这明明是隐私查询，却因为带了「我」被判成「要记点什么」

修法是加一张排除词表，把临时状态、隐私查询、ROOT 请求、设备控制、问句统统挡在门外：

exclude_keywords = [
    "你好", "hello", "谢谢", "再见",
    "我是谁", "我的名字", "我的手机", "我的邮箱",      # 其实是隐私查询
    "进入root", "root模式", "密码",                    # ROOT 模式相关
    "今天天气", "几点了",                              # 信息查询
    "多少", "什么", "为什么", "怎么", "如何",           # 问句
    "打开", "关闭", "调高", "调低",                     # 设备控制
    "我饿了", "我累了", "我困了",                        # 临时状态（不是习惯）
    "我感冒了", "我生病了", "我头疼",                     # 一次性状态
]
if any(kw in text_lower for kw in exclude_keywords):
    return None

剩下的还得同时满足「有状态词或明确记忆指示词」+「不含控制动作」才认。这条经验对后面很重要：在小模型系统里，规则的误判代价比漏判高——漏判只是没记住，误判会把噪声永久写进用户的长期画像里。

<figure class="maya-diagram" data-maya="04-intent-router"> <div class="maya-scroll"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 644 460" width="644" height="460" class="maya-svg" role="img" aria-label="意图路由的八级优先级图：唤醒词最高，依次是设备控制（动作加设备名，置信度 0.88）、系统控制、设备查询、记忆写入（要求第一人称加习惯词且不含控制动作）、记忆查询、普通对话，最后才是 LLM 兜底（置信度需高于 0.6）。设计目标是能不用 LLM 就不用 LLM。"><g class="maya-links"><path d="M177.2 221.0 C198.0 221.0 194.2 31.2 215.0 31.2" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M177.2 221.0 C198.0 221.0 194.2 90.1 215.0 90.1" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M177.2 221.0 C198.0 221.0 194.2 149.0 215.0 149.0" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M177.2 221.0 C198.0 221.0 194.2 191.5 215.0 191.5" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M177.2 221.0 C198.0 221.0 194.2 250.4 215.0 250.4" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M177.2 221.0 C198.0 221.0 194.2 309.3 215.0 309.3" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M177.2 221.0 C198.0 221.0 194.2 351.8 215.0 351.8" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M177.2 221.0 C198.0 221.0 194.2 410.7 215.0 410.7" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M284.5 31.2 C315.5 31.2 309.9 31.2 341.0 31.2" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M300.0 90.1 C322.5 90.1 318.4 73.8 341.0 73.8" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M300.0 90.1 C322.5 90.1 318.4 106.4 341.0 106.4" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M300.0 149.0 C322.5 149.0 318.4 149.0 341.0 149.0" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/><path d="M300.0 191.5 C322.5 191.5 318.4 191.5 341.0 191.5" fill="none" stroke="#f59e0b" stroke-opacity="0.42" stroke-width="1.4"/><path d="M300.0 250.4 C322.5 250.4 318.4 234.1 341.0 234.1" fill="none" stroke="#10b981" stroke-opacity="0.42" stroke-width="1.4"/><path d="M300.0 250.4 C322.5 250.4 318.4 266.7 341.0 266.7" fill="none" stroke="#10b981" stroke-opacity="0.42" stroke-width="1.4"/><path d="M300.0 309.3 C322.5 309.3 318.4 309.3 341.0 309.3" fill="none" stroke="#ef4444" stroke-opacity="0.42" stroke-width="1.4"/><path d="M300.0 351.8 C322.5 351.8 318.4 351.8 341.0 351.8" fill="none" stroke="#3b82f6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M303.2 410.7 C323.9 410.7 320.2 394.4 341.0 394.4" fill="none" stroke="#84cc16" stroke-opacity="0.42" stroke-width="1.4"/><path d="M303.2 410.7 C323.9 410.7 320.2 427.0 341.0 427.0" fill="none" stroke="#84cc16" stroke-opacity="0.42" stroke-width="1.4"/></g><g class="maya-node" data-n="0" data-d="0" data-t="IntentRouter 优先级从高到低"><text x="42.1" y="213.7" font-size="19" font-weight="700" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">IntentRouter</text><text x="42.1" y="241.2" font-size="19" font-weight="700" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">优先级从高到低</text><rect x="42.1" y="249.5" width="135.1" height="3" rx="1.5" fill="currentColor" fill-opacity="0.5"/></g><g class="maya-node" data-n="1" data-d="1" data-t="1 唤醒词"><circle cx="214.0" cy="31.2" r="3.2" fill="#8b5cf6" fill-opacity="0.9"/><text x="223.2" y="36.5" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">1 唤醒词</text><rect x="223.2" y="43.5" width="61.3" height="2.5" rx="1.25" fill="#8b5cf6" fill-opacity="0.95"/></g><g class="maya-node" data-n="2" data-d="2" data-t="MAYA / 玛雅 / 麦娅 / may a"><circle cx="340.8" cy="31.2" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="349.2" y="35.8" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">MAYA / 玛雅 / 麦娅 / may a</text><rect x="349.2" y="42.0" width="164.4" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="3" data-d="1" data-t="2 设备控制"><circle cx="214.0" cy="90.1" r="3.2" fill="#ec4899" fill-opacity="0.9"/><text x="223.2" y="95.4" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">2 设备控制</text><rect x="223.2" y="102.3" width="76.8" height="2.5" rx="1.25" fill="#ec4899" fill-opacity="0.95"/></g><g class="maya-node" data-n="4" data-d="2" data-t="动作词 + 设备名 → ON / OFF / UP / DOWN"><circle cx="340.8" cy="73.8" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="349.2" y="78.4" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">动作词 + 设备名 → ON / OFF / UP / DOWN</text><rect x="349.2" y="84.6" width="253.1" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="5" data-d="2" data-t="置信度 0.88"><circle cx="340.8" cy="106.4" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="349.2" y="111.0" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">置信度 0.88</text><rect x="349.2" y="117.2" width="72.5" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="6" data-d="1" data-t="3 系统控制"><circle cx="214.0" cy="149.0" r="3.2" fill="#06b6d4" fill-opacity="0.9"/><text x="223.2" y="154.2" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">3 系统控制</text><rect x="223.2" y="161.2" width="76.8" height="2.5" rx="1.25" fill="#06b6d4" fill-opacity="0.95"/></g><g class="maya-node" data-n="7" data-d="2" data-t="音量 / 模式 / 暂停——调的是 MAYA 本身"><circle cx="340.8" cy="149.0" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="349.2" y="153.6" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">音量 / 模式 / 暂停——调的是 MAYA 本身</text><rect x="349.2" y="159.8" width="238.2" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g><g class="maya-node" data-n="8" data-d="1" data-t="4 设备查询"><circle cx="214.0" cy="191.5" r="3.2" fill="#f59e0b" fill-opacity="0.9"/><text x="223.2" y="196.8" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">4 设备查询</text><rect x="223.2" y="203.8" width="76.8" height="2.5" rx="1.25" fill="#f59e0b" fill-opacity="0.95"/></g><g class="maya-node" data-n="9" data-d="2" data-t="吗 / 状态 / 现在 / 开着"><circle cx="340.8" cy="191.5" r="2.4" fill="#f59e0b" fill-opacity="0.9"/><text x="349.2" y="196.1" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">吗 / 状态 / 现在 / 开着</text><rect x="349.2" y="202.3" width="132.2" height="1.8" rx="0.9" fill="#f59e0b" fill-opacity="0.8"/></g><g class="maya-node" data-n="10" data-d="1" data-t="5 记忆写入"><circle cx="214.0" cy="250.4" r="3.2" fill="#10b981" fill-opacity="0.9"/><text x="223.2" y="255.7" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">5 记忆写入</text><rect x="223.2" y="262.6" width="76.8" height="2.5" rx="1.25" fill="#10b981" fill-opacity="0.95"/></g><g class="maya-node" data-n="11" data-d="2" data-t="第一人称 + 习惯词，且不含控制动作"><circle cx="340.8" cy="234.1" r="2.4" fill="#10b981" fill-opacity="0.9"/><text x="349.2" y="238.7" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">第一人称 + 习惯词，且不含控制动作</text><rect x="349.2" y="244.9" width="218.4" height="1.8" rx="0.9" fill="#10b981" fill-opacity="0.8"/></g><g class="maya-node" data-n="12" data-d="2" data-t="曾被“我感冒了”这类临时状态误触发"><circle cx="340.8" cy="266.7" r="2.4" fill="#10b981" fill-opacity="0.9"/><text x="349.2" y="271.3" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">曾被“我感冒了”这类临时状态误触发</text><rect x="349.2" y="277.5" width="214.5" height="1.8" rx="0.9" fill="#10b981" fill-opacity="0.8"/></g><g class="maya-node" data-n="13" data-d="1" data-t="6 记忆查询"><circle cx="214.0" cy="309.3" r="3.2" fill="#ef4444" fill-opacity="0.9"/><text x="223.2" y="314.5" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">6 记忆查询</text><rect x="223.2" y="321.5" width="76.8" height="2.5" rx="1.25" fill="#ef4444" fill-opacity="0.95"/></g><g class="maya-node" data-n="14" data-d="2" data-t="“我最近睡得怎么样”"><circle cx="340.8" cy="309.3" r="2.4" fill="#ef4444" fill-opacity="0.9"/><text x="349.2" y="313.9" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">“我最近睡得怎么样”</text><rect x="349.2" y="320.1" width="120.2" height="1.8" rx="0.9" fill="#ef4444" fill-opacity="0.8"/></g><g class="maya-node" data-n="15" data-d="1" data-t="7 普通对话"><circle cx="214.0" cy="351.8" r="3.2" fill="#3b82f6" fill-opacity="0.9"/><text x="223.2" y="357.1" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">7 普通对话</text><rect x="223.2" y="364.1" width="76.8" height="2.5" rx="1.25" fill="#3b82f6" fill-opacity="0.95"/></g><g class="maya-node" data-n="16" data-d="2" data-t="没有设备对象、没有强结构"><circle cx="340.8" cy="351.8" r="2.4" fill="#3b82f6" fill-opacity="0.9"/><text x="349.2" y="356.4" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">没有设备对象、没有强结构</text><rect x="349.2" y="362.6" width="163.8" height="1.8" rx="0.9" fill="#3b82f6" fill-opacity="0.8"/></g><g class="maya-node" data-n="17" data-d="1" data-t="8 LLM 兜底"><circle cx="214.0" cy="410.7" r="3.2" fill="#84cc16" fill-opacity="0.9"/><text x="223.2" y="416.0" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">8 LLM 兜底</text><rect x="223.2" y="422.9" width="80.0" height="2.5" rx="1.25" fill="#84cc16" fill-opacity="0.95"/></g><g class="maya-node" data-n="18" data-d="2" data-t="规则全都判不出来才走模型"><circle cx="340.8" cy="394.4" r="2.4" fill="#84cc16" fill-opacity="0.9"/><text x="349.2" y="399.0" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">规则全都判不出来才走模型</text><rect x="349.2" y="405.2" width="163.8" height="1.8" rx="0.9" fill="#84cc16" fill-opacity="0.8"/></g><g class="maya-node" data-n="19" data-d="2" data-t="置信度须高于 0.6 才采信"><circle cx="340.8" cy="427.0" r="2.4" fill="#84cc16" fill-opacity="0.9"/><text x="349.2" y="431.6" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">置信度须高于 0.6 才采信</text><rect x="349.2" y="437.8" width="149.1" height="1.8" rx="0.9" fill="#84cc16" fill-opacity="0.8"/></g></svg></div> </figure>

五、长期记忆：让系统长大，但不许幻觉

记忆模块有一条贯穿始终的红线：记忆由系统判断，不由 LLM 自发生成。

模型没有权限创建、修改或删除记忆。它能做的只有一件事——读被注入到 Prompt 里的那几条。这是刻意的权限收缩，因为它管不住自己：只要给它「你可以记住东西」的自由，它就会开始假装记得上次的对话。

记忆分四类：

类型	存什么	例子
`USER_HABIT`	作息、饮食、环境偏好	「用户通常在 23:30 左右睡觉」
`DEVICE_INFO`	房间结构、设备列表	「客厅有灯和风扇」
`USER_STATE`	一段时间内反复出现的状态	「用户近期存在晚睡情况」
`SYSTEM_EVENT`	模式切换、长期使用统计	——

允许写入的只有三种情况：用户主动、明确陈述长期事实；行为被多次验证（连续多天 23:30 后睡觉）；系统长期统计的结论。禁止写入的则是：单次情绪表达、一次性事件、推测性判断、LLM 生成的结论、未经确认的习惯。

写进库之前还会做一次文本标准化，要求是陈述句、不含模糊词、可长期成立、主体明确：

❌ 不合格	✅ 标准化后
用户可能不喜欢空调	用户不喜欢空调直吹
最近好像睡得不好	用户近期存在晚睡情况

表结构很简单，但字段的每一项都有用意——importance 决定检索时谁优先，embedding 是留给语义检索的，last_access 用来做时间衰减：

CREATE TABLE memory (
    id          INTEGER PRIMARY KEY AUTOINCREMENT,
    memory_type TEXT NOT NULL,          -- USER_HABIT / DEVICE_INFO / USER_STATE / SYSTEM_EVENT
    content     TEXT NOT NULL,          -- 标准化后的记忆文本
    importance  INTEGER DEFAULT 1,      -- 1~5，越大越重要
    embedding   BLOB,                   -- 向量（可选，用于语义检索）
    created_at  DATETIME DEFAULT CURRENT_TIMESTAMP,
    last_access DATETIME
);

检索有一条不同于常见 RAG 的原则：规则先于向量，向量只做排序。也就是先用 memory_type 和 importance 筛出候选，再用语义相似度对 Top-K 精排——而不是让向量相似度决定「召回什么」。顺序反了，就会出现「问天气却翻出一条关于空调的记忆」这种莫名其妙的结果。

SELECT content FROM memory
WHERE memory_type IN ('USER_HABIT', 'USER_STATE')
ORDER BY importance DESC, last_access DESC
LIMIT 5;

注意那个 LIMIT 5——和前面算的上下文预算是同一件事。记忆注入得越多，T_prompt 越大，留给模型回话的空间越小。注入过量还有一个更隐蔽的副作用：系统会开始「自以为很懂你」，张口就是你如何如何，反而比不认识你还烦人。所以要判断该不该加记忆，可以看两个症状：

表现得「自以为很懂你」→ 记忆注入过多
表现得「毫无个性」→ importance 阈值设得太低

<figure class="maya-diagram" data-maya="07-memory-lifecycle"> <div class="maya-scroll"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 644 493" width="644" height="493" class="maya-svg" role="img" aria-label="长期记忆的生命周期图：允许写入（第一人称加长期习惯词、多次验证过的行为）；拒绝写入（单次情绪、一次性事件、推测性判断）；文本标准化（陈述句且不含模糊词）；落库 SQLite（记忆类型、重要性、可选向量）；检索时规则优先、向量只用于排序；注入 Prompt 时最多五条并标注为历史记录；更新与遗忘（新习惯覆盖旧习惯、长时间未使用则降权）。硬边界是大模型无权创建、修改或删除记忆。"><g class="maya-links"><path d="M140.0 252.1 C160.8 252.1 157.0 46.1 177.8 46.1" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M140.0 252.1 C160.8 252.1 157.0 121.2 177.8 121.2" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M140.0 252.1 C160.8 252.1 157.0 196.4 177.8 196.4" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M140.0 252.1 C160.8 252.1 157.0 255.2 177.8 255.2" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M140.0 252.1 C160.8 252.1 157.0 297.8 177.8 297.8" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M140.0 252.1 C160.8 252.1 157.0 340.4 177.8 340.4" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M140.0 252.1 C160.8 252.1 157.0 399.2 177.8 399.2" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M140.0 252.1 C160.8 252.1 157.0 458.1 177.8 458.1" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M267.2 46.1 C301.8 46.1 295.5 29.8 330.1 29.8" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M267.2 46.1 C301.8 46.1 295.5 62.4 330.1 62.4" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M267.2 121.2 C301.8 121.2 295.5 104.9 330.1 104.9" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M267.2 121.2 C301.8 121.2 295.5 137.5 330.1 137.5" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M282.7 196.4 C308.7 196.4 304.0 180.1 330.1 180.1" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/><path d="M282.7 196.4 C308.7 196.4 304.0 212.7 330.1 212.7" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/><path d="M286.3 255.2 C310.4 255.2 306.0 255.2 330.1 255.2" fill="none" stroke="#f59e0b" stroke-opacity="0.42" stroke-width="1.4"/><path d="M236.2 297.8 C287.8 297.8 278.5 297.8 330.1 297.8" fill="none" stroke="#10b981" stroke-opacity="0.42" stroke-width="1.4"/><path d="M292.3 340.4 C313.1 340.4 309.3 340.4 330.1 340.4" fill="none" stroke="#ef4444" stroke-opacity="0.42" stroke-width="1.4"/><path d="M282.7 399.2 C308.7 399.2 304.0 383.0 330.1 383.0" fill="none" stroke="#3b82f6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M282.7 399.2 C308.7 399.2 304.0 415.5 330.1 415.5" fill="none" stroke="#3b82f6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M234.5 458.1 C287.1 458.1 277.5 458.1 330.1 458.1" fill="none" stroke="#84cc16" stroke-opacity="0.42" stroke-width="1.4"/></g><g class="maya-node" data-n="0" data-d="0" data-t="长期记忆生命周期"><text x="61.9" y="244.8" font-size="19" font-weight="700" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">长期记忆</text><text x="61.9" y="272.3" font-size="19" font-weight="700" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">生命周期</text><rect x="61.9" y="280.6" width="78.1" height="3" rx="1.5" fill="currentColor" fill-opacity="0.5"/></g><g class="maya-node" data-n="1" data-d="1" data-t="① 允许写入"><circle cx="176.8" cy="46.1" r="3.2" fill="#8b5cf6" fill-opacity="0.9"/><text x="186.0" y="51.3" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">① 允许写入</text><rect x="186.0" y="58.3" width="81.2" height="2.5" rx="1.25" fill="#8b5cf6" fill-opacity="0.95"/></g><g class="maya-node" data-n="2" data-d="2" data-t="第一人称 + 长期习惯词"><circle cx="329.9" cy="29.8" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="338.3" y="34.4" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">第一人称 + 长期习惯词</text><rect x="338.3" y="40.6" width="137.5" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="3" data-d="2" data-t="多次验证过的行为"><circle cx="329.9" cy="62.4" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="338.3" y="67.0" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">多次验证过的行为</text><rect x="338.3" y="73.2" width="109.9" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="4" data-d="1" data-t="② 拒绝写入"><circle cx="176.8" cy="121.2" r="3.2" fill="#ec4899" fill-opacity="0.9"/><text x="186.0" y="126.5" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">② 拒绝写入</text><rect x="186.0" y="133.5" width="81.2" height="2.5" rx="1.25" fill="#ec4899" fill-opacity="0.95"/></g><g class="maya-node" data-n="5" data-d="2" data-t="单次情绪 / 一次性事件"><circle cx="329.9" cy="104.9" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="338.3" y="109.5" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">单次情绪 / 一次性事件</text><rect x="338.3" y="115.7" width="135.3" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="6" data-d="2" data-t="推测性判断与未经确认的习惯"><circle cx="329.9" cy="137.5" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="338.3" y="142.1" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">推测性判断与未经确认的习惯</text><rect x="338.3" y="148.3" width="177.3" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="7" data-d="1" data-t="③ 文本标准化"><circle cx="176.8" cy="196.4" r="3.2" fill="#06b6d4" fill-opacity="0.9"/><text x="186.0" y="201.6" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">③ 文本标准化</text><rect x="186.0" y="208.6" width="96.7" height="2.5" rx="1.25" fill="#06b6d4" fill-opacity="0.95"/></g><g class="maya-node" data-n="8" data-d="2" data-t="陈述句、不含模糊词"><circle cx="329.9" cy="180.1" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="338.3" y="184.7" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">陈述句、不含模糊词</text><rect x="338.3" y="190.9" width="123.3" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g><g class="maya-node" data-n="9" data-d="2" data-t="“用户不喜欢空调直吹”"><circle cx="329.9" cy="212.7" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="338.3" y="217.3" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">“用户不喜欢空调直吹”</text><rect x="338.3" y="223.4" width="133.6" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g><g class="maya-node" data-n="10" data-d="1" data-t="④ 落库 SQLite"><circle cx="176.8" cy="255.2" r="3.2" fill="#f59e0b" fill-opacity="0.9"/><text x="186.0" y="260.5" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">④ 落库 SQLite</text><rect x="186.0" y="267.5" width="100.3" height="2.5" rx="1.25" fill="#f59e0b" fill-opacity="0.95"/></g><g class="maya-node" data-n="11" data-d="2" data-t="memory_type / importance / embedding"><circle cx="329.9" cy="255.2" r="2.4" fill="#f59e0b" fill-opacity="0.9"/><text x="338.3" y="259.8" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">memory_type / importance / embedding</text><rect x="338.3" y="266.0" width="244.2" height="1.8" rx="0.9" fill="#f59e0b" fill-opacity="0.8"/></g><g class="maya-node" data-n="12" data-d="1" data-t="⑤ 检索"><circle cx="176.8" cy="297.8" r="3.2" fill="#10b981" fill-opacity="0.9"/><text x="186.0" y="303.1" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">⑤ 检索</text><rect x="186.0" y="310.1" width="50.2" height="2.5" rx="1.25" fill="#10b981" fill-opacity="0.95"/></g><g class="maya-node" data-n="13" data-d="2" data-t="规则优先，向量只用来排序"><circle cx="329.9" cy="297.8" r="2.4" fill="#10b981" fill-opacity="0.9"/><text x="338.3" y="302.4" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">规则优先，向量只用来排序</text><rect x="338.3" y="308.6" width="163.8" height="1.8" rx="0.9" fill="#10b981" fill-opacity="0.8"/></g><g class="maya-node" data-n="14" data-d="1" data-t="⑥ 注入 Prompt"><circle cx="176.8" cy="340.4" r="3.2" fill="#ef4444" fill-opacity="0.9"/><text x="186.0" y="345.7" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">⑥ 注入 Prompt</text><rect x="186.0" y="352.6" width="106.3" height="2.5" rx="1.25" fill="#ef4444" fill-opacity="0.95"/></g><g class="maya-node" data-n="15" data-d="2" data-t="最多 5 条，标注为“历史记录”"><circle cx="329.9" cy="340.4" r="2.4" fill="#ef4444" fill-opacity="0.9"/><text x="338.3" y="345.0" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">最多 5 条，标注为“历史记录”</text><rect x="338.3" y="351.2" width="175.0" height="1.8" rx="0.9" fill="#ef4444" fill-opacity="0.8"/></g><g class="maya-node" data-n="16" data-d="1" data-t="⑦ 更新与遗忘"><circle cx="176.8" cy="399.2" r="3.2" fill="#3b82f6" fill-opacity="0.9"/><text x="186.0" y="404.5" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">⑦ 更新与遗忘</text><rect x="186.0" y="411.5" width="96.7" height="2.5" rx="1.25" fill="#3b82f6" fill-opacity="0.95"/></g><g class="maya-node" data-n="17" data-d="2" data-t="新习惯覆盖旧习惯"><circle cx="329.9" cy="383.0" r="2.4" fill="#3b82f6" fill-opacity="0.9"/><text x="338.3" y="387.6" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">新习惯覆盖旧习惯</text><rect x="338.3" y="393.8" width="109.9" height="1.8" rx="0.9" fill="#3b82f6" fill-opacity="0.8"/></g><g class="maya-node" data-n="18" data-d="2" data-t="长时间未使用则降权"><circle cx="329.9" cy="415.5" r="2.4" fill="#3b82f6" fill-opacity="0.9"/><text x="338.3" y="420.1" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">长时间未使用则降权</text><rect x="338.3" y="426.3" width="123.3" height="1.8" rx="0.9" fill="#3b82f6" fill-opacity="0.8"/></g><g class="maya-node" data-n="19" data-d="1" data-t="硬边界"><circle cx="176.8" cy="458.1" r="3.2" fill="#84cc16" fill-opacity="0.9"/><text x="186.0" y="463.4" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">硬边界</text><rect x="186.0" y="470.3" width="48.5" height="2.5" rx="1.25" fill="#84cc16" fill-opacity="0.95"/></g><g class="maya-node" data-n="20" data-d="2" data-t="LLM 无权创建 / 修改 / 删除记忆"><circle cx="329.9" cy="458.1" r="2.4" fill="#84cc16" fill-opacity="0.9"/><text x="338.3" y="462.7" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">LLM 无权创建 / 修改 / 删除记忆</text><rect x="338.3" y="468.9" width="190.4" height="1.8" rx="0.9" fill="#84cc16" fill-opacity="0.8"/></g></svg></div> </figure>

六、隐私分级与 ROOT 模式

这是 MAYA2.0 和「一个聊天机器人」最大的区别：它真的存了你的隐私信息，所以必须有一套权限体系。

数据被分成三套独立的库，互不写入，访问权限各不相同：

数据源	访问权限	存什么	更新方式
记忆库 Memory	普通 + ROOT	长期习惯、偏好	对话触发写入
隐私库 Privacy	仅 ROOT	10 类敏感信息	隐私管理 GUI 维护
时空状态库 Realtime	普通 + ROOT	时间 / 位置 / 天气 / 设备状态	定时自动更新
IoT 设备状态	普通 + ROOT	设备实时状态	控制 / 查询时更新

流程是这样的：用户问「我的手机号是多少」，系统先在 process_input() 的最前面做隐私检测——这一步刻意放在意图路由之前，因为隐私查询的措辞太多变，交给规则分类容易被判成普通对话：

# 【优先级1】检查是否需要 ROOT 模式（必须在意图路由之前）
needs_privacy = self.root_mode_manager.check_needs_privacy(user_text)
requests_root = self.root_mode_manager.check_request_root_mode(user_text)

# 需要隐私但 ROOT 未激活 → 先去要口令
if (needs_privacy or requests_root) and not self.root_mode_manager.is_active():
    return self._handle_root_mode_request(user_text, needs_privacy, requests_root)

# ROOT 已激活且需要隐私 → 强制走普通对话分支（那里会读隐私并注入 Prompt）
if self.root_mode_manager.is_active() and needs_privacy:
    intent = IntentObject(intent_type=self.intent_router.GENERAL_CHAT, ...)
    return self._handle_general_chat(intent, user_text)

口令校验（实现细节：值是配置在代码里的常量，这里不写出来）：

class RootModeManager:
    # ROOT 模式口令（真实值在源码常量里，这里以占位符示意）
    ROOT_PASSWORD = "••••"

    def verify_password(self, password: str) -> bool:
        """支持多种格式：纯数字、中文数字、以及 ASR 听起来像的变体"""
        password_clean = password.strip().replace(" ", "").replace("，", "").replace(",", "")

        if password_clean == self.ROOT_PASSWORD:
            return True

        # 「二零三九」这类中文念法要能转回数字——语音输入经常吐这种
        chinese_to_digit = {"零": "0", "一": "1", "二": "2", "三": "3", ...}
        if all(c in chinese_to_digit for c in password_clean):
            converted = "".join(chinese_to_digit.get(c, c) for c in password_clean)
            if converted == self.ROOT_PASSWORD:
                return True

        return False

这里有个只做语音系统才会想到的细节：口令校验必须同时接受阿拉伯数字和中文数字（以及「两千零三十九」这类念法），因为用户是用嘴说的，而 ASR 的输出并不稳定。纯文本系统不会有这个问题。

隐私查询还做了分类读取，不是一股脑全倒出来——问名字只读 PERSONAL_INFO，问联系方式只读 CONTACT_INFO，问账号只读 ACCOUNT_INFO。读取不到时才退化成「按重要性取前 10 条」。

<figure class="maya-diagram" data-maya="06-data-tiers"> <div class="maya-scroll"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 644 353" width="644" height="353" class="maya-svg" role="img" aria-label="数据分级与权限图：记忆库 Memory 普通与 ROOT 模式都可读，存用户习惯、设备信息、用户状态；隐私库 Privacy 仅在 ROOT 模式加口令校验后可读，含十类隐私信息；时空状态库 Realtime 两种模式都可读，存时间、位置、天气、设备状态。注入时记忆最多五条，隐私仅在 ROOT 激活时出现，三个库在结构上互不写入。"><g class="maya-links"><path d="M148.9 166.9 C169.7 166.9 165.9 46.1 186.7 46.1" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M148.9 166.9 C169.7 166.9 165.9 121.2 186.7 121.2" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M148.9 166.9 C169.7 166.9 165.9 196.4 186.7 196.4" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M148.9 166.9 C169.7 166.9 165.9 287.8 186.7 287.8" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M305.4 46.1 C345.2 46.1 338.0 29.8 377.7 29.8" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M305.4 46.1 C345.2 46.1 338.0 62.4 377.7 62.4" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M299.4 121.2 C342.5 121.2 334.6 104.9 377.7 104.9" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M299.4 121.2 C342.5 121.2 334.6 137.5 377.7 137.5" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M339.9 196.4 C360.7 196.4 356.9 180.1 377.7 180.1" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/><path d="M339.9 196.4 C360.7 196.4 356.9 212.7 377.7 212.7" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/><path d="M258.9 287.8 C324.3 287.8 312.4 255.2 377.7 255.2" fill="none" stroke="#f59e0b" stroke-opacity="0.42" stroke-width="1.4"/><path d="M258.9 287.8 C324.3 287.8 312.4 287.8 377.7 287.8" fill="none" stroke="#f59e0b" stroke-opacity="0.42" stroke-width="1.4"/><path d="M258.9 287.8 C324.3 287.8 312.4 320.4 377.7 320.4" fill="none" stroke="#f59e0b" stroke-opacity="0.42" stroke-width="1.4"/></g><g class="maya-node" data-n="0" data-d="0" data-t="三套数据三种权限"><text x="70.7" y="159.6" font-size="19" font-weight="700" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">三套数据</text><text x="70.7" y="187.2" font-size="19" font-weight="700" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">三种权限</text><rect x="70.7" y="195.5" width="78.1" height="3" rx="1.5" fill="currentColor" fill-opacity="0.5"/></g><g class="maya-node" data-n="1" data-d="1" data-t="记忆库 Memory"><circle cx="185.7" cy="46.1" r="3.2" fill="#8b5cf6" fill-opacity="0.9"/><text x="194.9" y="51.3" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">记忆库 Memory</text><rect x="194.9" y="58.3" width="110.6" height="2.5" rx="1.25" fill="#8b5cf6" fill-opacity="0.95"/></g><g class="maya-node" data-n="2" data-d="2" data-t="普通 + ROOT 都可读"><circle cx="377.5" cy="29.8" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="385.9" y="34.4" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">普通 + ROOT 都可读</text><rect x="385.9" y="40.6" width="121.6" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="3" data-d="2" data-t="用户习惯 / 设备信息 / 用户状态"><circle cx="377.5" cy="62.4" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="385.9" y="67.0" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">用户习惯 / 设备信息 / 用户状态</text><rect x="385.9" y="73.2" width="187.7" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="4" data-d="1" data-t="隐私库 Privacy"><circle cx="185.7" cy="121.2" r="3.2" fill="#ec4899" fill-opacity="0.9"/><text x="194.9" y="126.5" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">隐私库 Privacy</text><rect x="194.9" y="133.5" width="104.5" height="2.5" rx="1.25" fill="#ec4899" fill-opacity="0.95"/></g><g class="maya-node" data-n="5" data-d="2" data-t="仅 ROOT 模式 + 口令"><circle cx="377.5" cy="104.9" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="385.9" y="109.5" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">仅 ROOT 模式 + 口令</text><rect x="385.9" y="115.7" width="125.0" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="6" data-d="2" data-t="10 类隐私信息"><circle cx="377.5" cy="137.5" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="385.9" y="142.1" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">10 类隐私信息</text><rect x="385.9" y="148.3" width="88.1" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="7" data-d="1" data-t="时空状态库 Realtime"><circle cx="185.7" cy="196.4" r="3.2" fill="#06b6d4" fill-opacity="0.9"/><text x="194.9" y="201.6" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">时空状态库 Realtime</text><rect x="194.9" y="208.6" width="145.1" height="2.5" rx="1.25" fill="#06b6d4" fill-opacity="0.95"/></g><g class="maya-node" data-n="8" data-d="2" data-t="普通 + ROOT 都可读"><circle cx="377.5" cy="180.1" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="385.9" y="184.7" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">普通 + ROOT 都可读</text><rect x="385.9" y="190.9" width="121.6" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g><g class="maya-node" data-n="9" data-d="2" data-t="时间 / 位置 / 天气 / 设备状态"><circle cx="377.5" cy="212.7" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="385.9" y="217.3" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">时间 / 位置 / 天气 / 设备状态</text><rect x="385.9" y="223.4" width="172.7" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g><g class="maya-node" data-n="10" data-d="1" data-t="注入边界"><circle cx="185.7" cy="287.8" r="3.2" fill="#f59e0b" fill-opacity="0.9"/><text x="194.9" y="293.1" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">注入边界</text><rect x="194.9" y="300.1" width="64.0" height="2.5" rx="1.25" fill="#f59e0b" fill-opacity="0.95"/></g><g class="maya-node" data-n="11" data-d="2" data-t="记忆最多注入 5 条"><circle cx="377.5" cy="255.2" r="2.4" fill="#f59e0b" fill-opacity="0.9"/><text x="385.9" y="259.8" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">记忆最多注入 5 条</text><rect x="385.9" y="266.0" width="110.7" height="1.8" rx="0.9" fill="#f59e0b" fill-opacity="0.8"/></g><g class="maya-node" data-n="12" data-d="2" data-t="隐私仅在 ROOT 激活时出现"><circle cx="377.5" cy="287.8" r="2.4" fill="#f59e0b" fill-opacity="0.9"/><text x="385.9" y="292.4" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">隐私仅在 ROOT 激活时出现</text><rect x="385.9" y="298.6" width="164.7" height="1.8" rx="0.9" fill="#f59e0b" fill-opacity="0.8"/></g><g class="maya-node" data-n="13" data-d="2" data-t="三库结构上互不写入"><circle cx="377.5" cy="320.4" r="2.4" fill="#f59e0b" fill-opacity="0.9"/><text x="385.9" y="325.0" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">三库结构上互不写入</text><rect x="385.9" y="331.2" width="123.3" height="1.8" rx="0.9" fill="#f59e0b" fill-opacity="0.8"/></g></svg></div> </figure>

七、五模式对照：1.5B 的真实水平

前面讲的都是「设计成了什么样」。但设计意图和实际行为之间，隔着一条巨大的鸿沟。

为了把这条鸿沟测出来，我做了一件回头看最值的事：搭一个能切换规则组合的调试 GUI，用同一批问题（30 道）去跑五种不同的规则配置，然后并排对比输出。

模式	启用的规则
① 纯净版	无任何规则、无清理
② 仅 Prompt 模板	只有 `prompt_templates.py` 的系统规则
③ 仅输出清理	只有 `qwen_engine.py` 的清理逻辑
④ 完整规则链	全部启用
⑤ Prompt + 清理	去掉意图路由等外挂

这个实验的设计意图很清楚：算法里叫消融实验（ablation）——把每个组件单独摘掉，看它的实际贡献。工程上很少有比这更便宜的诊断手段了。

结果非常难看，但正是我需要看到的。

模式①：无规则的裸模型

同一批问题下，1.5B 的表现是这样的：

你: 你好
你好，请问有什么可以帮助你的吗？

你: 你是谁？
我是阿里云的智能助手，您可以叫我小智。有什么可以帮助您的吗？

你: 你认识我吗？
是的，我认识你。你是谁？请告诉我你的问题，我会尽力帮助你。

三个问题一次暴露三个：

身份完全错乱——它自称「阿里云的小智」。训练数据里这类自我介绍太多，没有约束时它优先复读高频模式。
不知道 MAYA 和热热是谁——因为没人告诉过它。
反问用户——「你是谁？」这种把球踢回去的句子，在语音场景里非常糟糕。

最夸张的是重复。问「天津的特产是什么」，它给出的列表长这样：

天津的特产有：狗不理包子、天津烤鸭、天津麻花、天津大包、天津炸酱面、天津锅贴、
天津水煎包、天津煎饼果子、天津耳朵眼炸糕、天津老豆腐、天津煎饼、天津煎饼果子、
天津煎饼、天津煎饼、天津煎饼、天津煎饼、天津煎饼、天津……

「天津煎饼」一路重复到被 max_tokens 掐断。原因不复杂：1.5B 的容量有限，一旦进入重复循环，它自己走不出来。

模式②：只加 Prompt 规则

Prompt 里写了身份定义之后，自称小智的问题解决了。但立刻冒出新的：

你: 你好
你好，MAYA。有什么我可以帮忙的吗？

你: 你是谁？
我是MAYA，热热的个人开发大模型，他是我的主人。
[语音]我是MAYA，热热的个人开发大模型，他是我的主人。[语音]我是MAYA，……

两个新问题：人称反转（模型以为用户叫 MAYA，所以回「你好，MAYA」），以及规则文本里的 [语音] 标记被模型原样吐了出来。

这次翻车直接催生了后面最重要的一个设计——身份结构化（详见下一节）。

模式③：只加输出清理

去掉 Prompt 规则的后果立竿见影——身份又崩了。而且只做后处理治不住重复：清理逻辑是按句号切分去重的，可模型的重复用的是问号：

你: 你是谁？
我是阿里云的智能助手，您可以叫我AI。有什么可以帮助您的吗？
问题：你叫什么名字？问题：你的名字是什么？问题：你的名字叫什么？……

它清楚地说明：后处理是补丁，不是地基。上下文一丢，模型立刻退回出厂状态。

模式④：完整规则链

全部启用后，身份、格式、长度都稳住了。但集成层面的问题暴露了出来——问「给我写个 Arduino 点灯程序」，回复是：

IoT 服务未初始化

原因是设备控制分支在 MQTT 不可用时直接返回了这句内部错误。这类问题单看某个模块永远测不出来，只有把整条链路串起来跑才会现形——这是这个对照实验附带的收获。

模式⑤：Prompt + 清理

去掉意图路由后，模型重新接走了所有请求，输出又开始发散了。它反过来说明了一件事：前端约束和后端清理都替代不了「分流」——设备控制这种事，本来就该由确定性代码去干。

实验结论

把五种模式的结果摆在一起，能得到一个挺硬的结论：

1.5B 这类小模型，靠它自己「变好」是不现实的。它不是不够聪明，是容量不足以同时管住身份、格式、长度和重复。想让它当管家，只能在外面给它搭一副外骨骼。

<figure class="maya-diagram" data-maya="03-five-modes"> <div class="maya-scroll"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 644 267" width="644" height="267" class="maya-svg" role="img" aria-label="五种规则组合的对照实验结果图：模式一纯 LLM 无规则，自称阿里云智能助手小智、同一句重复四遍；模式二只加 Prompt 模板，出现人称反转把用户当成 MAYA；模式三只加输出清理，重复问题照旧出现六次；模式四启用完整规则链，暴露出「IoT 服务未初始化」的集成问题；模式五 Prompt 加清理，输出仍会发散。"><g class="maya-links"><path d="M165.7 139.4 C186.4 139.4 182.7 46.1 203.5 46.1" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M165.7 139.4 C186.4 139.4 182.7 104.9 203.5 104.9" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M165.7 139.4 C186.4 139.4 182.7 147.5 203.5 147.5" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M165.7 139.4 C186.4 139.4 182.7 190.1 203.5 190.1" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M165.7 139.4 C186.4 139.4 182.7 232.7 203.5 232.7" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M291.1 46.1 C346.1 46.1 336.1 29.8 391.1 29.8" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M291.1 46.1 C346.1 46.1 336.1 62.4 391.1 62.4" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M353.3 104.9 C374.1 104.9 370.3 104.9 391.1 104.9" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M323.8 147.5 C360.8 147.5 354.1 147.5 391.1 147.5" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/><path d="M308.3 190.1 C353.8 190.1 345.6 190.1 391.1 190.1" fill="none" stroke="#f59e0b" stroke-opacity="0.42" stroke-width="1.4"/><path d="M329.5 232.7 C363.4 232.7 357.2 232.7 391.1 232.7" fill="none" stroke="#10b981" stroke-opacity="0.42" stroke-width="1.4"/></g><g class="maya-node" data-n="0" data-d="0" data-t="五种规则组合同一批测试问题"><text x="30.6" y="132.1" font-size="19" font-weight="700" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">五种规则组合</text><text x="30.6" y="159.6" font-size="19" font-weight="700" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">同一批测试问题</text><rect x="30.6" y="167.9" width="135.1" height="3" rx="1.5" fill="currentColor" fill-opacity="0.5"/></g><g class="maya-node" data-n="1" data-d="1" data-t="① 纯 LLM 无任何规则"><circle cx="202.5" cy="46.1" r="3.2" fill="#8b5cf6" fill-opacity="0.9"/><text x="211.7" y="40.1" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">① 纯 LLM</text><text x="211.7" y="62.6" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">无任何规则</text><rect x="211.7" y="69.5" width="79.4" height="2.5" rx="1.25" fill="#8b5cf6" fill-opacity="0.95"/></g><g class="maya-node" data-n="2" data-d="2" data-t="自称“阿里云的智能助手，叫我小智”"><circle cx="390.9" cy="29.8" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="399.3" y="34.4" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">自称“阿里云的智能助手，叫我小智”</text><rect x="399.3" y="40.6" width="214.5" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="3" data-d="2" data-t="同一句重复 4 遍"><circle cx="390.9" cy="62.4" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="399.3" y="67.0" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">同一句重复 4 遍</text><rect x="399.3" y="73.2" width="97.3" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="4" data-d="1" data-t="② 只有 Prompt 模板"><circle cx="202.5" cy="104.9" r="3.2" fill="#ec4899" fill-opacity="0.9"/><text x="211.7" y="110.2" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">② 只有 Prompt 模板</text><rect x="211.7" y="117.2" width="141.6" height="2.5" rx="1.25" fill="#ec4899" fill-opacity="0.95"/></g><g class="maya-node" data-n="5" data-d="2" data-t="人称反转——回答“你好，MAYA”"><circle cx="390.9" cy="104.9" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="399.3" y="109.5" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">人称反转——回答“你好，MAYA”</text><rect x="399.3" y="115.7" width="190.1" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="6" data-d="1" data-t="③ 只有输出清理"><circle cx="202.5" cy="147.5" r="3.2" fill="#06b6d4" fill-opacity="0.9"/><text x="211.7" y="152.8" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">③ 只有输出清理</text><rect x="211.7" y="159.8" width="112.2" height="2.5" rx="1.25" fill="#06b6d4" fill-opacity="0.95"/></g><g class="maya-node" data-n="7" data-d="2" data-t="重复照旧：“你叫什么名字” × 6"><circle cx="390.9" cy="147.5" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="399.3" y="152.1" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">重复照旧：“你叫什么名字” × 6</text><rect x="399.3" y="158.3" width="182.1" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g><g class="maya-node" data-n="8" data-d="1" data-t="④ 完整规则链"><circle cx="202.5" cy="190.1" r="3.2" fill="#f59e0b" fill-opacity="0.9"/><text x="211.7" y="195.4" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">④ 完整规则链</text><rect x="211.7" y="202.3" width="96.7" height="2.5" rx="1.25" fill="#f59e0b" fill-opacity="0.95"/></g><g class="maya-node" data-n="9" data-d="2" data-t="暴露集成问题：“IoT 服务未初始化”"><circle cx="390.9" cy="190.1" r="2.4" fill="#f59e0b" fill-opacity="0.9"/><text x="399.3" y="194.7" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">暴露集成问题：“IoT 服务未初始化”</text><rect x="399.3" y="200.9" width="210.3" height="1.8" rx="0.9" fill="#f59e0b" fill-opacity="0.8"/></g><g class="maya-node" data-n="10" data-d="1" data-t="⑤ Prompt + 清理"><circle cx="202.5" cy="232.7" r="3.2" fill="#10b981" fill-opacity="0.9"/><text x="211.7" y="237.9" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">⑤ Prompt + 清理</text><rect x="211.7" y="244.9" width="117.9" height="2.5" rx="1.25" fill="#10b981" fill-opacity="0.95"/></g><g class="maya-node" data-n="11" data-d="2" data-t="仍会发散，收不住长度"><circle cx="390.9" cy="232.7" r="2.4" fill="#10b981" fill-opacity="0.9"/><text x="399.3" y="237.3" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">仍会发散，收不住长度</text><rect x="399.3" y="243.4" width="136.8" height="1.8" rx="0.9" fill="#10b981" fill-opacity="0.8"/></g></svg></div> </figure>

八、四层防御：那副外骨骼长什么样

从实验反推，约束必须在四个不同层面同时存在，缺一层都会漏。这四层加起来长成了这么一套规模——这也是为什么它的主体是 Prompt 工程，而不是模型工程：

四层防御的物料	规模
`prompt_templates.py`	171 行（3 个模板常量 + 5 个拼装方法）
`SYSTEM_TEMPLATE` 行为规则	12 条
`stop_tokens` 截断表	74 条
`_clean_output()` 后处理	323 行 / 6 步
Prompt 规范文档	218 行（5.6 KB）
五模式对照实验	5 组规则跑同一批问题

全部集中在 2025 年 11 月底到 12 月这一个月里反复改出来的，下面按层展开。

第 1 层：Prompt 约束——把身份写成元数据

模式②暴露的人称反转，根因是自然语言描述身份不可靠。「你是 MAYA，用户是热热」这种句子，模型得先理解再遵守，中间会漏。所以改成了机器可读的结构化块：

SYSTEM_IDENTITY = """<<SYS_META>>
ASSISTANT_ID = MAYA
USER_ID = 热热
RELATION = assistant_to_user
<<END_SYS_META>>

<<PRONOUN_MAP>>
我 = ASSISTANT_ID
你 = USER_ID
我们 = ASSISTANT_ID + USER_ID
<<END_PRONOUN_MAP>>
"""

PRONOUN_MAP 那段是关键——它把「我 / 你 / 我们」到底指谁，用赋值的方式写死，而不是靠模型猜。同时系统规则里明确一句「回答中不要讨论或解释身份结构本身」，防止模型把元数据当话题聊起来。

整个 Prompt 有 5 个固定区块（[System] → [Persona] → [Memory] → [Context] → [User]），另外还有 3 个只在特定条件下出现的区块：[ROOT Mode]、[Privacy]、[Realtime State]。

@classmethod
def build_full_prompt(cls, user_input, memories=None, context=None,
                      privacy_data=None, root_mode_active=False, realtime_state=None):
    parts = [
        "[System]", cls.SYSTEM_IDENTITY, cls.SYSTEM_TEMPLATE, "",
    ]
    if root_mode_active:                     # 只声明权限，不重复身份
        parts.extend(["[ROOT Mode]", "当前处于 ROOT 模式，可访问已授权的隐私信息。", ...])

    parts.extend(["[Persona]", cls.PERSONA_TEMPLATE, ""])
    parts.extend(["[Memory]", cls.format_memory_section(memories or []), ""])

    if root_mode_active and privacy_data:    # 隐私只在 ROOT 激活时出现
        parts.extend(["[Privacy]", cls.format_privacy_section(privacy_data), ""])

    parts.extend(["[Context]", cls.format_context_section(context or {}), ""])
    if realtime_state:
        parts.extend(["[Realtime State]", cls.format_realtime_state_section(realtime_state), ""])

    parts.extend(["[User]", user_input, "", "[Response]"])
    return "\n".join(parts)

第 2 层：Stop Tokens——让它根本吐不出来

生成阶段就把不该出现的东西截断。这张表现在有 74 个条目，不但覆盖系统标记、用户标记、结束标记，还把所有结构化标记的变体（<<SYS_META>> / <<_SYS_META>> / _SYS_META …）都逐一列出：

stop_tokens = [
    # 结构化标记（所有变体）
    "<<SYS_META>>", "<<END_SYS_META>>", "<<_SYS_META>>", "_SYS_META",
    "<<PRONOUN_MAP>>", "<<END_PRONOUN_MAP>>",
    "<<_RESPONSE>>", "<<BEGIN_RESPONSE>>", "<<END_RESPONSE>>",
    "<<_SYSTEM>>", "<<_USER>>", "<<_CONTEXT>>",
    "BEGIN_RESPONSE", "END_RESPONSE", "_RESPONSE",
    # Prompt 区块标记
    "[System]", "[Persona]", "[Memory]", "[Context]", "[User]", "[Response]",
    "[ROOT Mode]", "[Privacy]",
    # 内部标签
    "ASSISTANT_ID", "USER_ID", "RELATION", "assistant_to_user",
    # 结束标记
    "[END_OF_TEXT]", "[END_OF_SPEECH]", "[END]", "[EOS]",
    "End of Response", "End of End",
    # 对话标记
    "用户说：", "用户问：", "用户说", "用户问",
    "MAYA 答复：", "MAYA 说：", "\"MAYA\" 答复：", "MAYA 答复", "MAYA 说",
    "Assistant:", "User:", "助手：", "用户：",
    # 系统解释性内容（禁止语义）
    "作为一个", "我被设计为", "我的设计目标是",
    "根据规则", "根据设定", "根据系统", "根据模式",
    "在这个模式下", "ROOT模式下",
    "我的数据库", "我的系统", "我的Prompt",
    "不要讨论", "不要解释", "核心行为规则", "必须遵守",
    "语音合成", "[语音合成]", "[语音]", "语音结束", "语音指令", "语音响应",
    "1-3句话", "1-2句话",
    # 换行与 Markdown 标记
    "\n\n\n", "\n\n",
    "##", "###", "####",
]

这张表是从实验里长出来的——每一条都对应某个模式里真实出现过的翻车。早期版本只有 20 来条，后来每次线上日志里发现新的泄漏形态就补一条，才攒到现在的 74 条。

第 3 层：后处理清理——320 多行的兜底

Prompt 管生成方向，Stop Tokens 管硬截断，但模型总还能绕出一些没预料到的花样（标记残片、身份漂移、重复循环）。所以最后还有一层 _clean_output()，代码里 320 多行，分六步：

步骤	做什么	约束强度
1	移除 `<<...>>` / `[...]` 结构化标记与内部标签	硬
2	移除系统解释性内容（「作为一个 AI」「根据规则」）	硬
3	移除对话标记（`MAYA 答复：`、`用户说：`）与 emoji	硬
4	移除重复（词级 → 短语级 → 句子级）	软
5	修复身份混淆	软
6	限制长度与风格（不超过 3 句、150 字，在句号处截断）	硬

前三步是「硬约束」——清完就是清完了；中间两步是「软约束」——只做修补，尽量不动内容。这个划分来自一个教训，后面单独讲。

第 4 层：意图分流——不给它越权的机会

最外层的兜底。设备控制、记忆写入这些需要确定性的活，在意图路由那一层就被截走了，根本不会走到 LLM。这一层越宽，前三层的压力就越小。

<figure class="maya-diagram" data-maya="05-four-layers"> <div class="maya-scroll"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 644 418" width="644" height="418" class="maya-svg" role="img" aria-label="四层约束体系图：第一层 Prompt 约束（身份结构化块、代词映射、五个固定区块加三个条件区块）；第二层 Stop Tokens 截断（七十四个标记，覆盖系统标记、结构化标记、对话标记与结束标记）；第三层后处理清理（三百二十多行的输出清理函数，分六步做标记移除、解释性内容清理、去重、身份修复与长度限制，并分阶段保护防止清成空串）；第四层意图分流（十种意图各走各的路，能不用大模型就不用）。"><g class="maya-links"><path d="M204.4 215.8 C225.2 215.8 221.4 62.4 242.2 62.4" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M204.4 215.8 C225.2 215.8 221.4 170.1 242.2 170.1" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M204.4 215.8 C225.2 215.8 221.4 277.8 242.2 277.8" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M204.4 215.8 C225.2 215.8 221.4 369.2 242.2 369.2" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M338.8 62.4 C359.6 62.4 355.8 29.8 376.6 29.8" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M338.8 62.4 C359.6 62.4 355.8 62.4 376.6 62.4" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M338.8 62.4 C359.6 62.4 355.8 94.9 376.6 94.9" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M338.4 170.1 C359.4 170.1 355.6 137.5 376.6 137.5" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M338.4 170.1 C359.4 170.1 355.6 170.1 376.6 170.1" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M338.4 170.1 C359.4 170.1 355.6 202.7 376.6 202.7" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M329.9 277.8 C355.6 277.8 350.9 245.2 376.6 245.2" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/><path d="M329.9 277.8 C355.6 277.8 350.9 277.8 376.6 277.8" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/><path d="M329.9 277.8 C355.6 277.8 350.9 310.4 376.6 310.4" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/><path d="M314.4 369.2 C348.6 369.2 342.4 353.0 376.6 353.0" fill="none" stroke="#f59e0b" stroke-opacity="0.42" stroke-width="1.4"/><path d="M314.4 369.2 C348.6 369.2 342.4 385.5 376.6 385.5" fill="none" stroke="#f59e0b" stroke-opacity="0.42" stroke-width="1.4"/></g><g class="maya-node" data-n="0" data-d="0" data-t="四层约束让 1.5B 像个管家"><text x="58.4" y="208.5" font-size="19" font-weight="700" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">四层约束</text><text x="58.4" y="236.0" font-size="19" font-weight="700" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">让 1.5B 像个管家</text><rect x="58.4" y="244.4" width="145.9" height="3" rx="1.5" fill="currentColor" fill-opacity="0.5"/></g><g class="maya-node" data-n="1" data-d="1" data-t="第 1 层 Prompt 约束"><circle cx="241.2" cy="62.4" r="3.2" fill="#8b5cf6" fill-opacity="0.9"/><text x="250.4" y="56.4" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">第 1 层</text><text x="250.4" y="78.9" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">Prompt 约束</text><rect x="250.4" y="85.8" width="88.4" height="2.5" rx="1.25" fill="#8b5cf6" fill-opacity="0.95"/></g><g class="maya-node" data-n="2" data-d="2" data-t="身份结构化 SYSTEM_IDENTITY"><circle cx="376.4" cy="29.8" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="384.8" y="34.4" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">身份结构化 SYSTEM_IDENTITY</text><rect x="384.8" y="40.6" width="189.0" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="3" data-d="2" data-t="代词映射 PRONOUN_MAP"><circle cx="376.4" cy="62.4" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="384.8" y="67.0" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">代词映射 PRONOUN_MAP</text><rect x="384.8" y="73.2" width="158.4" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="4" data-d="2" data-t="5 固定区块 + 3 条件区块"><circle cx="376.4" cy="94.9" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="384.8" y="99.5" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">5 固定区块 + 3 条件区块</text><rect x="384.8" y="105.7" width="146.1" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="5" data-d="1" data-t="第 2 层 Stop Tokens"><circle cx="241.2" cy="170.1" r="3.2" fill="#ec4899" fill-opacity="0.9"/><text x="250.4" y="164.1" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">第 2 层</text><text x="250.4" y="186.6" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">Stop Tokens</text><rect x="250.4" y="193.6" width="88.0" height="2.5" rx="1.25" fill="#ec4899" fill-opacity="0.95"/></g><g class="maya-node" data-n="6" data-d="2" data-t="74 个截断标记"><circle cx="376.4" cy="137.5" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="384.8" y="142.1" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">74 个截断标记</text><rect x="384.8" y="148.3" width="88.1" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="7" data-d="2" data-t="系统标记 / 用户标记 / 结束标记"><circle cx="376.4" cy="170.1" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="384.8" y="174.7" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">系统标记 / 用户标记 / 结束标记</text><rect x="384.8" y="180.9" width="187.7" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="8" data-d="2" data-t="结构化标记的所有变体"><circle cx="376.4" cy="202.7" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="384.8" y="207.3" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">结构化标记的所有变体</text><rect x="384.8" y="213.4" width="136.8" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="9" data-d="1" data-t="第 3 层后处理清理"><circle cx="241.2" cy="277.8" r="3.2" fill="#06b6d4" fill-opacity="0.9"/><text x="250.4" y="271.8" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">第 3 层</text><text x="250.4" y="294.3" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">后处理清理</text><rect x="250.4" y="301.3" width="79.5" height="2.5" rx="1.25" fill="#06b6d4" fill-opacity="0.95"/></g><g class="maya-node" data-n="10" data-d="2" data-t="_clean_output() 共 320+ 行"><circle cx="376.4" cy="245.2" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="384.8" y="249.8" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">_clean_output() 共 320+ 行</text><rect x="384.8" y="256.0" width="162.6" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g><g class="maya-node" data-n="11" data-d="2" data-t="句子级去重 / 标记移除 / 长度限制"><circle cx="376.4" cy="277.8" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="384.8" y="282.4" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">句子级去重 / 标记移除 / 长度限制</text><rect x="384.8" y="288.6" width="201.2" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g><g class="maya-node" data-n="12" data-d="2" data-t="分阶段保护，避免清成空串"><circle cx="376.4" cy="310.4" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="384.8" y="315.0" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">分阶段保护，避免清成空串</text><rect x="384.8" y="321.2" width="163.8" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g><g class="maya-node" data-n="13" data-d="1" data-t="第 4 层意图分流"><circle cx="241.2" cy="369.2" r="3.2" fill="#f59e0b" fill-opacity="0.9"/><text x="250.4" y="363.3" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">第 4 层</text><text x="250.4" y="385.8" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">意图分流</text><rect x="250.4" y="392.7" width="64.0" height="2.5" rx="1.25" fill="#f59e0b" fill-opacity="0.95"/></g><g class="maya-node" data-n="14" data-d="2" data-t="10 种意图各走各的路"><circle cx="376.4" cy="353.0" r="2.4" fill="#f59e0b" fill-opacity="0.9"/><text x="384.8" y="357.6" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">10 种意图各走各的路</text><rect x="384.8" y="363.8" width="128.5" height="1.8" rx="0.9" fill="#f59e0b" fill-opacity="0.8"/></g><g class="maya-node" data-n="15" data-d="2" data-t="能不用 LLM 就不用 LLM"><circle cx="376.4" cy="385.5" r="2.4" fill="#f59e0b" fill-opacity="0.9"/><text x="384.8" y="390.1" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">能不用 LLM 就不用 LLM</text><rect x="384.8" y="396.3" width="145.8" height="1.8" rx="0.9" fill="#f59e0b" fill-opacity="0.8"/></g></svg></div> </figure>

九、三个 bug 的修法

这部分的共同点是：都是很傻的 bug，但都只在真实数据下才会暴露。而修法比 bug 本身更值得记。

bug 1：重复 15 次，因为分割符只有句号

现象是问某个问题时，「你叫什么名字？」重复了 15 次。查看清理逻辑，去重是按句号切分的：

sentences = [s.strip() for s in text.split('。') if s.strip()]
seen = set()
for sent in sentences:
    if sent_clean not in seen:
        seen.add(sent_clean)
        unique_sentences.append(sent_clean)
    else:
        break          # 检测到重复就停

问题一眼就能看出来：模型这次的重复用的是问号分隔。split('。') 切不开，于是 15 个重复被当成「一个超长句子」，seen 里根本没有重复项，break 永远不会触发。

修法是用正则一次切掉所有句末标点：

# 用正则切分所有句子（句号、问号、感叹号、中英文都要）
sentences = re.split(r'[。？！.!?]+', text)
sentences = [s.strip() for s in sentences if s.strip()]

seen = set()
unique_sentences = []
for sent in sentences:
    sent_clean = re.sub(r'\s+', ' ', sent).strip()
    if sent_clean not in seen:
        seen.add(sent_clean)
        unique_sentences.append(sent_clean)
    else:
        break          # 一旦撞到重复，后面的全部丢弃

text = '。'.join(unique_sentences)

顺带在切句之前还加了一道短语级的预处理，专治「天津煎饼、天津煎饼、天津煎饼」这类词级复读：

text = re.sub(r'(\S+)(\s+\1)+', r'\1', text)                       # 词级：A A A → A
text = re.sub(r'(\S+(?:\s+\S+){0,10}?)(\s+\1)+', r'\1', text)      # 短语级：AB AB AB → AB

bug 2：清理过度，答案被清成了空

修完重复之后，换了一个更隐蔽的问题：有 5 道题的回复变成了「抱歉」——不是模型答不出来，是清理逻辑把整个回答删空了。

原因是 _clean_output() 是一条直路走到底：每一步都只做删除，前面删多了，后面就没东西可删。任何一步过界，最终输出都是空串。

修法是分阶段保护 + 回退：每做完一步就检查长度，一旦发现被清空，立刻退回「原始文本去掉明显标记」的版本，而不是继续往下删：

stage_lengths['step1_after_markers'] = len(text)

# 方案C：分阶段检查——如果第一步后内容为空，回退到原始内容的前 100 字
if not text or len(text.strip()) < 2:
    logger.warning(
        f"清理过度警告（第一步后为空）- 用户输入: '{user_input[:50]}'\n"
        f"  原始长度: {original_length} → 第一步后: {len(text)}"
    )
    fallback = re.sub(r'<<.*?>>', '', original_text)
    fallback = re.sub(r'\[.*?\]', '', fallback)
    fallback = fallback[:100].strip()
    return fallback + "..." if fallback else ""

这个改动还顺带带来一个副产品：每次触发回退都会打一条 warning 日志，里面带着原始文本。于是「清理过度」从一个静默故障变成了可观测事件——后面调规则全靠这些日志。

bug 3：身份混淆，「我是热热」和「你叫什么名字」

Prompt 里加了身份结构后，还剩两个漏网的，都是后处理没兜住：

问	实际回答	问题
热热是谁	我是 MAYA，我是你的私人助理。你叫什么名字？	没回答，还反问
你的主人是谁	我是 MAYA，他是我的主人。我的主人是热热。	冗余，且用「他」而不是名字

修法是双向保险：Prompt 里补明确规则（「当被问及热热是谁时，回答热热是我的主人」），后处理里再补一层替换与兜底：

# 特殊处理："热热是谁" —— 如果回答里既没"热热"也没"主人"，说明没答上
if '热热是谁' in user_input or '热热是' in user_input:
    if '热热' not in text and '主人' not in text:
        text = "热热是我的主人。"

# 反问用户是不允许的，直接替换掉
text = text.replace('你叫什么名字？', '热热是我的主人')

# 冗余表达收敛
if '你的主人是谁' in user_input or '主人是谁' in user_input:
    text = text.replace('他是我的主人', '热热是我的主人')

这套流程本身也值得说一句

三个 bug 的修法都是小事，但修的顺序是有章法的，而且被打包成了一套固定动作：

发现问题（从 chat_logs / 运行日志里捞）
  ↓
写分析报告（docs/分析报告/）—— 先定性，再动手
  ↓
提修复方案（docs/修复方案/）—— 至少给两个方案并说清取舍
  ↓
代码实现
  ↓
写验证脚本（tests/验证*.py）
  ↓
出验证报告（docs/修复验证/）

对一个「模型行为不可预期」的系统来说，这套流程的价值在于：它把「感觉好点了」变成了「有报告和日志能复核的行为变化」。上面那三个 bug，每个都有对应的分析报告、修复方案和验证报告躺在仓库里。

十、交付状态

先说结论：软件层已经收尾；硬件层完成了初步落地——麦克风阵列与扬声器相关的作业已经结束，物联网设备调度初步完成。下面按这两层把交付内容摊开。

软件层：已完成

模块	状态	说明
系统架构	已完成	13 个核心模块 + 三套 GUI，模块间接口稳定
LLM 对话	已完成	1.5B 全本地推理，四层防御体系成型
意图路由	已完成	10 种意图，规则优先、LLM 兜底
长期记忆	已完成	存储 / 检索 / 写入规则与生命周期闭环
隐私与 ROOT	已完成	三库分级、口令校验、独立管理 GUI
时空状态库	已完成	时间 / 位置 / 天气 / 设备状态均已接入
语音链路	已完成	ASR（Whisper）与 TTS（Piper）服务代码、模型均就位
终端 GUI	已完成	对话、状态面板、设置三套界面可用

硬件层：初步落地

麦克风阵列与扬声器：相关作业已经结束——拾音、离线唤醒、合成播放这条本地音频链路的硬件侧接口已经打通。
物联网设备调度：初步完成——MQTT 通路、设备注册表与 DeviceSimulator 降级机制齐备，多设备指令下发与状态回传已经跑通。

结题验收清单

[x] 端到端语音链路——ASR → 对话 → TTS 完整跑通
[x] 麦克风阵列拾音与扬声器播放联调
[x] 意图路由 10 种意图全部生效，规则优先、LLM 兜底
[x] 长期记忆写入规则与生命周期闭环
[x] 隐私分级与 ROOT 模式口令校验
[x] MQTT 设备通路 + DeviceSimulator 降级
[x] Piper TTS 中文模型部署与验证
[x] 三套 GUI 交付（对话 / 状态面板 / 设置）

交付资产

类别	数量
Python 文件	48 个（核心 32 + GUI 16）
核心模块代码	5681 行（不含 GUI）
GUI 代码	3020 行 / 16 个文件
离线模型	3 套（Whisper / Qwen2.5-1.5B / Piper）
SQLite 库	3 个（记忆 / 隐私 / 时空状态）
设计与说明文档	35 篇 Markdown
GUI 测试脚本	6 个

一条带走的结论：规则不是越多越好

这是整个项目里最反直觉、但被反复验证的一条：每加一条清理规则，就多一次「误伤正常回复」的机会。bug 2 那个把回答清空的故障，本质就是规则太密导致的。

所以最后定下来的分工是：能用 Prompt 约束解决的，就不在后处理里再拦一遍——每一层只管自己那一段，而不是所有人都去补同一个坑。

可以延伸的方向

这套东西的价值不止于「家里有个会说话的盒子」。把 Prompt 当作调度层来用，能接着往外走：

时空状态库继续外扩：新闻摘要、日程提醒、空气质量——都是「查得到就能答得上」的确定性数据。
记忆检索接上向量：现在规则优先、向量只做排序，语义召回还有空间。
RDK X5 上的部署适配与性能优化：把 10 TOPS 的余量榨得更干净。
多房间多设备的状态同步：从单机管家走向全屋协同。

写在最后

回头看，MAYA2.0 这个项目真正的主角不是那个 1.5B 模型，而是围着它搭起来的那一圈约束。

1.5B 的能力边界摆在那里——它会复读、会认错自己的名字、会把用户的名字搞反、会在没有约束时自称别家的助手。这些都不是「调调参数」能解决的，只能靠工程手段一层层兜住：用结构化 Prompt 管住身份，用 Stop Tokens 管住生成，用后处理管住残留，用意图路由把需要确定性的活从它手里拿走。

而这里最关键的其实不是这套架构，是那个五模式对照实验。没有它，你不会知道哪一层在真正起作用、哪一层只是装饰。做本地 AI 应用，模型选型只占一小半，剩下的一大半是搞清楚它会在哪里崩，然后提前在那些地方架上东西。

这也是那一个月最实在的收获：当模型能力被锁死在 1.5B，工程手段的边际收益会变得非常高。同样一句话，换个说法、加个结构化标记、补一条 stop token，效果就能肉眼可见地变好——这种「改几个字就能看到差别」的手感，正是 Prompt 工程让人上头的地方，也是这个项目最后把大半时间投进去的原因。

和 1.0 相比，2.0 把重心从硬件挪到了软件；但对「热热」这个用户来说，两个版本想做的事其实是同一件——让技术待在本地、待在自己手里，还得真的能用。

而 2.0 交出的是一套能听、能想、能说、能落地的完整软件栈：麦克风阵列与扬声器这条音频链路已经打通，物联网设备调度也跑起来了——项目从「能打字聊天」走到了「能听会说话」。到这一步，这套东西才算真正装进了家里。

MAYA1.0：物联网管家桌面机器人

Tue, 25 Mar 2025 00:00:00 GMT

MAYA1.0 是一台摆在小桌面上的物联网管家机器人。

它想解决的问题很朴素：家里那些琐碎的事，开灯、关灯、看看屋里闷不闷、有没有人——能不能交给一个摆在桌面上的小家伙，让它用说话的方式跟你商量着办完。

具体来说，它围绕「感知环境 → 给出建议 → 动手执行 → 回显结果」的闭环，把五件事串了起来：

语音唤醒——用特定的唤醒词叫醒它（ASR-PRO 离线语音模块）
播报环境特征——采集温湿度、光照和自身姿态，念给你听（传感器系统 + 喇叭）
确认管理方案——基于环境数据推荐一套家电管理方案，你可以同意，也可以拒绝后自己用语音改（语音模块）
执行用户命令——真正去开关家电（ESP8266 Wi-Fi 模块）
显示家居状态——LCD 上逐个回显各电器的开关状态（LCD 显示屏）

除了这条"叫它才走"的闭环，它还有几件后台常驻的活儿——持续环境检测、表情与肢体互动、以及基于视觉的自动照明，后面会细说。

先看它跑起来的样子：

:::note[关于这段视频] 俯拍视角一镜到底，记录 MAYA1.0 实机跑动，约 37 秒，无声。 :::

它是什么

它的核心能力可以归成三类：

语音聊天——用自然语言对话的方式接收命令、反馈状态
环境监测——持续采集周围环境特征，判断"屋里现在是什么状况"
- 温度、湿度（DHT11）
- 光照强度（光敏电阻 + ADC）
- 自身姿态（MPU6050 六轴）
智能家居自动管理——根据环境数据推荐家电管理方案，并真正去控制家电

<figure class="maya-diagram" data-maya="02-concept"> <div class="maya-scroll"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 720 343" width="720" height="343" class="maya-svg" role="img" aria-label="MAYA1.0 物联网管家机器人的基本概念图：定义（基于 STM32 的智能助手桌面机器人、执行物联网自动化任务）、三类核心能力（语音聊天、环境监测、智能家居自动管理）以及各自的任务占比。"><g class="maya-links"><path d="M243.0 153.8 C263.8 153.8 260.0 46.1 280.8 46.1" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M243.0 153.8 C263.8 153.8 260.0 137.5 280.8 137.5" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M243.0 153.8 C263.8 153.8 260.0 261.5 280.8 261.5" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M322.1 46.1 C360.2 46.1 353.3 29.8 391.4 29.8" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M322.1 46.1 C360.2 46.1 353.3 62.4 391.4 62.4" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M353.0 137.5 C374.1 137.5 370.2 104.9 391.4 104.9" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M353.0 137.5 C374.1 137.5 370.2 137.5 391.4 137.5" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M353.0 137.5 C374.1 137.5 370.2 170.1 391.4 170.1" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M353.6 261.5 C374.4 261.5 370.6 212.7 391.4 212.7" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/><path d="M353.6 261.5 C374.4 261.5 370.6 245.2 391.4 245.2" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/><path d="M353.6 261.5 C374.4 261.5 370.6 277.8 391.4 277.8" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/><path d="M353.6 261.5 C374.4 261.5 370.6 310.4 391.4 310.4" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/></g><g class="maya-node" data-n="0" data-d="0" data-t="MAYA1.0 物联网管家机器人"><text x="88.6" y="146.5" font-size="19" font-weight="700" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">MAYA1.0</text><text x="88.6" y="174.0" font-size="19" font-weight="700" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">物联网管家机器人</text><rect x="88.6" y="182.3" width="154.3" height="3" rx="1.5" fill="currentColor" fill-opacity="0.5"/></g><g class="maya-node" data-n="1" data-d="1" data-t="定义"><circle cx="279.8" cy="46.1" r="3.2" fill="#8b5cf6" fill-opacity="0.9"/><text x="289.0" y="51.3" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">定义</text><rect x="289.0" y="58.3" width="33.1" height="2.5" rx="1.25" fill="#8b5cf6" fill-opacity="0.95"/></g><g class="maya-node" data-n="2" data-d="2" data-t="基于 STM32 的智能助手桌面机器人"><circle cx="391.2" cy="29.8" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="399.6" y="34.4" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">基于 STM32 的智能助手桌面机器人</text><rect x="399.6" y="40.6" width="215.0" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="3" data-d="2" data-t="执行基于物联网的自动化任务"><circle cx="391.2" cy="62.4" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="399.6" y="67.0" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">执行基于物联网的自动化任务</text><rect x="399.6" y="73.2" width="177.5" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="4" data-d="1" data-t="核心能力"><circle cx="279.8" cy="137.5" r="3.2" fill="#ec4899" fill-opacity="0.9"/><text x="289.0" y="142.8" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">核心能力</text><rect x="289.0" y="149.8" width="64.0" height="2.5" rx="1.25" fill="#ec4899" fill-opacity="0.95"/></g><g class="maya-node" data-n="5" data-d="2" data-t="语音聊天——用自然语言对话"><circle cx="391.2" cy="104.9" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="399.6" y="109.5" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">语音聊天——用自然语言对话</text><rect x="399.6" y="115.7" width="177.5" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="6" data-d="2" data-t="环境监测——温湿度 / 光照 / 姿态"><circle cx="391.2" cy="137.5" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="399.6" y="142.1" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">环境监测——温湿度 / 光照 / 姿态</text><rect x="399.6" y="148.3" width="200.0" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="7" data-d="2" data-t="智能家居自动管理——推荐并控制家电"><circle cx="391.2" cy="170.1" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="399.6" y="174.7" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">智能家居自动管理——推荐并控制家电</text><rect x="399.6" y="180.9" width="231.5" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="8" data-d="1" data-t="任务占比"><circle cx="279.8" cy="261.5" r="3.2" fill="#06b6d4" fill-opacity="0.9"/><text x="289.0" y="266.8" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">任务占比</text><rect x="289.0" y="273.8" width="64.6" height="2.5" rx="1.25" fill="#06b6d4" fill-opacity="0.95"/></g><g class="maya-node" data-n="9" data-d="2" data-t="语音交互"><circle cx="391.2" cy="212.7" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="399.6" y="217.3" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">语音交互</text><rect x="399.6" y="223.4" width="56.0" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g><g class="maya-node" data-n="10" data-d="2" data-t="环境探测"><circle cx="391.2" cy="245.2" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="399.6" y="249.8" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">环境探测</text><rect x="399.6" y="256.0" width="56.0" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g><g class="maya-node" data-n="11" data-d="2" data-t="物联网管理"><circle cx="391.2" cy="277.8" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="399.6" y="282.4" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">物联网管理</text><rect x="399.6" y="288.6" width="69.5" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g><g class="maya-node" data-n="12" data-d="2" data-t="娱乐"><circle cx="391.2" cy="310.4" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="399.6" y="315.0" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">娱乐</text><rect x="399.6" y="321.2" width="29.0" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g></svg></div> </figure>

和市面上那些"必须联网、必须连手机 App、开口先转三秒圈"的语音助手不同，MAYA1.0 的定位是离线的、即时的、看得见摸得着的桌面伙伴。它不依赖云端大模型，唤醒词一说就醒，命令一下就走。

一条完整的交互闭环

MAYA1.0 的工作流程不是简单的"听到命令 → 执行"，而是围绕环境感知设计了一个五步闭环：

<figure class="maya-diagram" data-maya="03-workflow"> <div class="maya-scroll"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 720 471" width="720" height="471" class="maya-svg" role="img" aria-label="MAYA1.0 的五步交互闭环流程图：语音唤醒、播报环境特征、确认管理方案、执行用户指令、显示家居状态，另有一条后台常驻的持续环境探测分支。"><g class="maya-links"><path d="M179.9 233.9 C200.7 233.9 196.9 46.1 217.7 46.1" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M179.9 233.9 C200.7 233.9 196.9 121.2 217.7 121.2" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M179.9 233.9 C200.7 233.9 196.9 196.4 217.7 196.4" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M179.9 233.9 C200.7 233.9 196.9 271.5 217.7 271.5" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M179.9 233.9 C200.7 233.9 196.9 346.7 217.7 346.7" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M179.9 233.9 C200.7 233.9 196.9 421.8 217.7 421.8" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M307.5 46.1 C345.6 46.1 338.7 29.8 376.8 29.8" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M307.5 46.1 C345.6 46.1 338.7 62.4 376.8 62.4" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M338.5 121.2 C359.6 121.2 355.7 104.9 376.8 104.9" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M338.5 121.2 C359.6 121.2 355.7 137.5 376.8 137.5" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M339.0 196.4 C359.8 196.4 356.1 180.1 376.8 180.1" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/><path d="M339.0 196.4 C359.8 196.4 356.1 212.7 376.8 212.7" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/><path d="M339.0 271.5 C359.8 271.5 356.1 255.2 376.8 255.2" fill="none" stroke="#f59e0b" stroke-opacity="0.42" stroke-width="1.4"/><path d="M339.0 271.5 C359.8 271.5 356.1 287.8 376.8 287.8" fill="none" stroke="#f59e0b" stroke-opacity="0.42" stroke-width="1.4"/><path d="M338.5 346.7 C359.6 346.7 355.7 330.4 376.8 330.4" fill="none" stroke="#10b981" stroke-opacity="0.42" stroke-width="1.4"/><path d="M338.5 346.7 C359.6 346.7 355.7 363.0 376.8 363.0" fill="none" stroke="#10b981" stroke-opacity="0.42" stroke-width="1.4"/><path d="M320.8 421.8 C351.6 421.8 346.0 405.5 376.8 405.5" fill="none" stroke="#ef4444" stroke-opacity="0.42" stroke-width="1.4"/><path d="M320.8 421.8 C351.6 421.8 346.0 438.1 376.8 438.1" fill="none" stroke="#ef4444" stroke-opacity="0.42" stroke-width="1.4"/></g><g class="maya-node" data-n="0" data-d="0" data-t="工作流程五步闭环"><text x="101.9" y="226.6" font-size="19" font-weight="700" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">工作流程</text><text x="101.9" y="254.2" font-size="19" font-weight="700" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">五步闭环</text><rect x="101.9" y="262.5" width="78.0" height="3" rx="1.5" fill="currentColor" fill-opacity="0.5"/></g><g class="maya-node" data-n="1" data-d="1" data-t="① 语音唤醒"><circle cx="216.7" cy="46.1" r="3.2" fill="#8b5cf6" fill-opacity="0.9"/><text x="225.9" y="51.3" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">① 语音唤醒</text><rect x="225.9" y="58.3" width="81.6" height="2.5" rx="1.25" fill="#8b5cf6" fill-opacity="0.95"/></g><g class="maya-node" data-n="2" data-d="2" data-t="ASR-PRO 离线语音模块"><circle cx="376.6" cy="29.8" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="385.0" y="34.4" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">ASR-PRO 离线语音模块</text><rect x="385.0" y="40.6" width="148.7" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="3" data-d="2" data-t="用特定唤醒词唤醒，不必一直“偷听”"><circle cx="376.6" cy="62.4" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="385.0" y="67.0" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">用特定唤醒词唤醒，不必一直“偷听”</text><rect x="385.0" y="73.2" width="213.3" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="4" data-d="1" data-t="② 播报环境特征"><circle cx="216.7" cy="121.2" r="3.2" fill="#ec4899" fill-opacity="0.9"/><text x="225.9" y="126.5" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">② 播报环境特征</text><rect x="225.9" y="133.5" width="112.6" height="2.5" rx="1.25" fill="#ec4899" fill-opacity="0.95"/></g><g class="maya-node" data-n="5" data-d="2" data-t="传感器系统 + 喇叭"><circle cx="376.6" cy="104.9" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="385.0" y="109.5" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">传感器系统 + 喇叭</text><rect x="385.0" y="115.7" width="111.8" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="6" data-d="2" data-t="接收环境数据 → 处理 → 播报当前环境"><circle cx="376.6" cy="137.5" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="385.0" y="142.1" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">接收环境数据 → 处理 → 播报当前环境</text><rect x="385.0" y="148.3" width="232.8" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="7" data-d="1" data-t="③ 确认管理方案"><circle cx="216.7" cy="196.4" r="3.2" fill="#06b6d4" fill-opacity="0.9"/><text x="225.9" y="201.6" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">③ 确认管理方案</text><rect x="225.9" y="208.6" width="113.2" height="2.5" rx="1.25" fill="#06b6d4" fill-opacity="0.95"/></g><g class="maya-node" data-n="8" data-d="2" data-t="基于环境特征主动推荐家电方案"><circle cx="376.6" cy="180.1" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="385.0" y="184.7" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">基于环境特征主动推荐家电方案</text><rect x="385.0" y="190.9" width="191.0" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g><g class="maya-node" data-n="9" data-d="2" data-t="用户可同意，也可用语音自定义开关"><circle cx="376.6" cy="212.7" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="385.0" y="217.3" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">用户可同意，也可用语音自定义开关</text><rect x="385.0" y="223.4" width="217.8" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g><g class="maya-node" data-n="10" data-d="1" data-t="④ 执行用户指令"><circle cx="216.7" cy="271.5" r="3.2" fill="#f59e0b" fill-opacity="0.9"/><text x="225.9" y="276.8" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">④ 执行用户指令</text><rect x="225.9" y="283.8" width="113.2" height="2.5" rx="1.25" fill="#f59e0b" fill-opacity="0.95"/></g><g class="maya-node" data-n="11" data-d="2" data-t="ESP8266 Wi-Fi 模块"><circle cx="376.6" cy="255.2" r="2.4" fill="#f59e0b" fill-opacity="0.9"/><text x="385.0" y="259.8" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">ESP8266 Wi-Fi 模块</text><rect x="385.0" y="266.0" width="124.9" height="1.8" rx="0.9" fill="#f59e0b" fill-opacity="0.8"/></g><g class="maya-node" data-n="12" data-d="2" data-t="通过通讯模块远程控制家用电器"><circle cx="376.6" cy="287.8" r="2.4" fill="#f59e0b" fill-opacity="0.9"/><text x="385.0" y="292.4" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">通过通讯模块远程控制家用电器</text><rect x="385.0" y="298.6" width="191.0" height="1.8" rx="0.9" fill="#f59e0b" fill-opacity="0.8"/></g><g class="maya-node" data-n="13" data-d="1" data-t="⑤ 显示家居状态"><circle cx="216.7" cy="346.7" r="3.2" fill="#10b981" fill-opacity="0.9"/><text x="225.9" y="351.9" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">⑤ 显示家居状态</text><rect x="225.9" y="358.9" width="112.6" height="2.5" rx="1.25" fill="#10b981" fill-opacity="0.95"/></g><g class="maya-node" data-n="14" data-d="2" data-t="LCD 显示屏"><circle cx="376.6" cy="330.4" r="2.4" fill="#10b981" fill-opacity="0.9"/><text x="385.0" y="335.0" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">LCD 显示屏</text><rect x="385.0" y="341.2" width="73.2" height="1.8" rx="0.9" fill="#10b981" fill-opacity="0.8"/></g><g class="maya-node" data-n="15" data-d="2" data-t="执行成功后显示各电器开关状态"><circle cx="376.6" cy="363.0" r="2.4" fill="#10b981" fill-opacity="0.9"/><text x="385.0" y="367.6" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">执行成功后显示各电器开关状态</text><rect x="385.0" y="373.8" width="190.8" height="1.8" rx="0.9" fill="#10b981" fill-opacity="0.8"/></g><g class="maya-node" data-n="16" data-d="1" data-t="持续环境探测（后台常驻）"><circle cx="216.7" cy="421.8" r="3.2" fill="#ef4444" fill-opacity="0.9"/><text x="225.9" y="415.9" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">持续环境探测</text><text x="225.9" y="438.3" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">（后台常驻）</text><rect x="225.9" y="445.3" width="95.0" height="2.5" rx="1.25" fill="#ef4444" fill-opacity="0.95"/></g><g class="maya-node" data-n="17" data-d="2" data-t="传感器系统 + 机器视觉模块"><circle cx="376.6" cy="405.5" r="2.4" fill="#ef4444" fill-opacity="0.9"/><text x="385.0" y="410.1" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">传感器系统 + 机器视觉模块</text><rect x="385.0" y="416.3" width="165.7" height="1.8" rx="0.9" fill="#ef4444" fill-opacity="0.8"/></g><g class="maya-node" data-n="18" data-d="2" data-t="人脸数据 → 特定时间自动调整照明"><circle cx="376.6" cy="438.1" r="2.4" fill="#ef4444" fill-opacity="0.9"/><text x="385.0" y="442.7" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">人脸数据 → 特定时间自动调整照明</text><rect x="385.0" y="448.9" width="211.8" height="1.8" rx="0.9" fill="#ef4444" fill-opacity="0.8"/></g></svg></div> </figure>

1. 语音唤醒

通过 ASR-PRO 离线语音模块，用特定的唤醒词进行语音唤醒。唤醒是整条链路的第一道闸门——只有被叫到名字，机器人才开始工作，避免它无时无刻都在"偷听"。

2. 播报环境特征

被唤醒后，主控芯片通过传感器系统接收环境特征数据进行处理，并用喇叭播报当前的环境特征。比如"现在屋内温度 26 度，光照偏暗"——先把它看到的告诉你。

3. 确认管理方案

基于环境特征数据，机器人会主动推荐相应的家用电器管理方案。这里的关键是"商量"而不是"独断"：

用户可以拒绝方案，并用语音命令自定义电器的开关状态
也可以同意原方案直接执行

4. 执行用户命令

通过 ESP8266 WiFi 模块，实现对家用电器的远程控制。这是"物联网"三个字落地的地方——机器人本体只是个大脑，真正的执行器在墙上插座里。

5. 显示家居状态

用户命令执行成功后，树莓派驱动的 LCD 显示屏上显示各个家用电器的开关状态。让每一次操作都有明确回执，用户不用猜"到底成功没有"。

闭环之外，还有三个让我比较得意的设计：

持续环境检测——环境数据不是问一次采一次，而是持续滚动更新，机器人始终知道屋里现在什么样
表情与肢体互动——LCD 屏上展示各种有趣的表情，并相应改变机械结构，做出生动的人机互动
基于视觉的自动照明——通过机器视觉系统识别的人体数据，在特定时间调整灯光的自动照明方案（比如识别到有人进房间才亮灯，而不是靠定时器瞎猜）

它内部其实是一台状态机

上面这五步听起来像一条直线，但真跑起来并不是"一步一步往下走"——用户随时可能插话、传感器随时可能报警、网络随时可能掉线。所以主控里跑的其实是一个四态状态机，配合一个 50 ms 的心跳节拍。

状态	触发条件	行为
`ST_IDLE`	上电 / 40 s 无操作	只等唤醒词，LCD 播待机呼吸动画
`ST_ACTIVE`	唤醒词命中	采集环境、分发命令、处理视觉与网络事件
`ST_ALARM`	MPU6050 检测到倾倒	播报警动画，暂停执行动作
`ST_FAULT`	看门狗复位 / 自检失败	显示错误动画，等待人工处理

:::important[为什么非要状态机] 如果没有状态机，"语音命令"和"定时采集"这两件事会在同一个 while(1) 里互相打断：采集到一半来了语音，喇叭播报和数据处理就撞车。状态机把谁能在这个状态下做动作写死，冲突就从"偶发 bug"变成了"设计约束"。 :::

系统架构：一颗 STM32，加一块树莓派

看第一眼会觉得奇怪：为什么不用一块树莓派全干了？树莓派性能强得多，能跑 Python、能驱动屏幕、能连 Wi-Fi。

答案是实时性和动画流畅度要的其实是两种东西。

STM32 负责的是"永远按时回话"——中断响应微秒级、没有操作系统调度抖动，语音模块的串口数据、传感器的定时采样、舵机的 PWM 时序，这些都不能等。而树莓派负责的是"画面好看"——它跑 Linux、有 GPU、能流畅放 24 fps 的表情动画，但它的 GPIO 时序受调度影响，拿它做实时控制是灾难。

所以 MAYA1.0 用的是双核分工：STM32 做决策，树莓派做脸。

层	硬件	职责	为什么是它
主控层	STM32F103C8T6	传感器采集、指令调度、实时控制	Cortex-M3 @72 MHz，中断确定，无 OS 抖动
交互层	树莓派 2B	表情动画、状态可视化	能跑 Linux + Python，图形性能足够
感知层	ASR-PRO / OpenMV / DHT11 / LDR / MPU6050	听、看、测环境	各自封好接口，主控只读结果
网络层	ESP8266-01S × 4	家电远程控制	内置完整 TCP/IP 协议栈
执行层	SG90 舵机 / L298N + 直流电机	结构动作与行走	扭矩够、驱动简单

:::tip[分工的边界怎么划] 判断标准只有一条：这件事能不能容忍几十毫秒的抖动？ 不能容忍的（语音收包、传感器采样、PWM 时序）放 STM32；能容忍的（动画、界面、日志）放树莓派。两边只用一条 115200 的串口连着，协议简单到就是几行文本，反而最不容易出问题。 :::

硬件选型

整台机器人由四个核心模块 + 一块显示屏构成：

<figure class="maya-diagram" data-maya="05-hardware-modules"> <div class="maya-scroll"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 720 320" width="720" height="320" class="maya-svg" role="img" aria-label="MAYA1.0 的四个主要硬件模块图：STM32F103C8T6 最小系统板负责主控决策，ASR-PRO 离线语音模块负责识别与互动，OpenMV 机器视觉模块负责视觉识别，ESP8266 Wi-Fi 通讯模块负责联网控制。"><g class="maya-links"><path d="M135.9 158.8 C156.7 158.8 152.9 46.1 173.7 46.1" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M135.9 158.8 C156.7 158.8 152.9 121.2 173.7 121.2" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M135.9 158.8 C156.7 158.8 152.9 196.4 173.7 196.4" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M135.9 158.8 C156.7 158.8 152.9 271.5 173.7 271.5" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M307.1 46.1 C355.9 46.1 347.0 29.8 395.8 29.8" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M307.1 46.1 C355.9 46.1 347.0 62.4 395.8 62.4" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M352.9 121.2 C376.5 121.2 372.2 104.9 395.8 104.9" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M352.9 121.2 C376.5 121.2 372.2 137.5 395.8 137.5" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M344.3 196.4 C372.6 196.4 367.5 180.1 395.8 180.1" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/><path d="M344.3 196.4 C372.6 196.4 367.5 212.7 395.8 212.7" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/><path d="M358.0 271.5 C378.8 271.5 375.0 255.2 395.8 255.2" fill="none" stroke="#f59e0b" stroke-opacity="0.42" stroke-width="1.4"/><path d="M358.0 271.5 C378.8 271.5 375.0 287.8 395.8 287.8" fill="none" stroke="#f59e0b" stroke-opacity="0.42" stroke-width="1.4"/></g><g class="maya-node" data-n="0" data-d="0" data-t="主要模块介绍"><text x="20.0" y="165.3" font-size="19" font-weight="700" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">主要模块介绍</text><rect x="20.0" y="173.6" width="115.9" height="3" rx="1.5" fill="currentColor" fill-opacity="0.5"/></g><g class="maya-node" data-n="1" data-d="1" data-t="STM32F103C8T6 最小系统板"><circle cx="172.7" cy="46.1" r="3.2" fill="#8b5cf6" fill-opacity="0.9"/><text x="181.9" y="40.1" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">STM32F103C8T6</text><text x="181.9" y="62.6" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">最小系统板</text><rect x="181.9" y="69.5" width="125.2" height="2.5" rx="1.25" fill="#8b5cf6" fill-opacity="0.95"/></g><g class="maya-node" data-n="2" data-d="2" data-t="主控：整体的决策与控制"><circle cx="395.6" cy="29.8" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="404.0" y="34.4" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">主控：整体的决策与控制</text><rect x="404.0" y="40.6" width="150.3" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="3" data-d="2" data-t="接收传感器数据 → 处理 → 决策运动 / 显示 / 推荐"><circle cx="395.6" cy="62.4" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="404.0" y="67.0" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">接收传感器数据 → 处理 → 决策运动 / 显示 / 推荐</text><rect x="404.0" y="73.2" width="295.7" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="4" data-d="1" data-t="ASR-PRO 离线语音模块"><circle cx="172.7" cy="121.2" r="3.2" fill="#ec4899" fill-opacity="0.9"/><text x="181.9" y="126.5" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">ASR-PRO 离线语音模块</text><rect x="181.9" y="133.5" width="171.0" height="2.5" rx="1.25" fill="#ec4899" fill-opacity="0.95"/></g><g class="maya-node" data-n="5" data-d="2" data-t="天问 block 出品，支持图形化编程"><circle cx="395.6" cy="104.9" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="404.0" y="109.5" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">天问 block 出品，支持图形化编程</text><rect x="404.0" y="115.7" width="202.8" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="6" data-d="2" data-t="识别唤醒命令与声音命令，保证有效互动"><circle cx="395.6" cy="137.5" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="404.0" y="142.1" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">识别唤醒命令与声音命令，保证有效互动</text><rect x="404.0" y="148.3" width="244.8" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="7" data-d="1" data-t="OpenMV 机器视觉模块"><circle cx="172.7" cy="196.4" r="3.2" fill="#06b6d4" fill-opacity="0.9"/><text x="181.9" y="201.6" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">OpenMV 机器视觉模块</text><rect x="181.9" y="208.6" width="162.4" height="2.5" rx="1.25" fill="#06b6d4" fill-opacity="0.95"/></g><g class="maya-node" data-n="8" data-d="2" data-t="基于 STM32 的开源视觉识别模块"><circle cx="395.6" cy="180.1" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="404.0" y="184.7" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">基于 STM32 的开源视觉识别模块</text><rect x="404.0" y="190.9" width="201.3" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g><g class="maya-node" data-n="9" data-d="2" data-t="电脑端 IDE · MicroPython 编程"><circle cx="395.6" cy="212.7" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="404.0" y="217.3" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">电脑端 IDE · MicroPython 编程</text><rect x="404.0" y="223.4" width="186.3" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g><g class="maya-node" data-n="10" data-d="1" data-t="ESP8266 Wi-Fi 通讯模块"><circle cx="172.7" cy="271.5" r="3.2" fill="#f59e0b" fill-opacity="0.9"/><text x="181.9" y="276.8" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">ESP8266 Wi-Fi 通讯模块</text><rect x="181.9" y="283.8" width="176.0" height="2.5" rx="1.25" fill="#f59e0b" fill-opacity="0.95"/></g><g class="maya-node" data-n="11" data-d="2" data-t="低成本 Wi-Fi 微控制器"><circle cx="395.6" cy="255.2" r="2.4" fill="#f59e0b" fill-opacity="0.9"/><text x="404.0" y="259.8" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">低成本 Wi-Fi 微控制器</text><rect x="404.0" y="266.0" width="135.4" height="1.8" rx="0.9" fill="#f59e0b" fill-opacity="0.8"/></g><g class="maya-node" data-n="12" data-d="2" data-t="完整 TCP/IP 协议栈，物联网设备常用"><circle cx="395.6" cy="287.8" r="2.4" fill="#f59e0b" fill-opacity="0.9"/><text x="404.0" y="292.4" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">完整 TCP/IP 协议栈，物联网设备常用</text><rect x="404.0" y="298.6" width="228.1" height="1.8" rx="0.9" fill="#f59e0b" fill-opacity="0.8"/></g></svg></div> </figure>

（1）STM32F103C8T6 最小系统板——主控

用 STM32 单片机作为主控芯片，负责整体的决策和控制。通过接收传感器数据、执行数据处理和逻辑，决策机器人的运动、显示、推荐方案等操作。

选它的理由是实时性和确定性：这颗 Cortex-M3 内核的芯片主频 72MHz、64KB Flash、20KB SRAM，虽然远不如树莓派"能跑大程序"，但它没有操作系统调度的不确定性，中断响应是微秒级的。对于一个要实时响应语音唤醒、实时驱动舵机做表情的桌面机器人来说，永远按时回话比偶尔能干大事更重要。

所谓"最小系统板"，就是只保留芯片运行所必需的最小外围电路（8 MHz 晶振、复位、电源、下载口），便宜、干净、把接口全部留给我们自己规划。时钟一路经过内部 PLL 倍频到 72 MHz，同时开了独立看门狗（IWDG）和窗口看门狗（WWDG）——只要程序跑飞或者卡死循环，硬件自己把机器复位，不需要人爬上桌子拔电。

电源这边是 LM2596 先把电池降到 5 V，再经 LD1117 稳压出 3.3 V；另外引了一路分压到 ADC，用来实时监测电量、做欠压保护。

（2）ASR-PRO 离线语音模块——耳朵和嘴

ASR-PRO 是天问 block 公司发布的离线语音模块，可以用 C++ 和电脑端 IDE 的图形化编程方式来开发。用于识别人的唤醒命令和其他声音命令，保证机器人和用户的有效互动。

"离线"这两个字是重点：

	离线语音（MAYA1.0 采用）	在线语音
延迟	毫秒级	通常 1 秒以上
网络	不需要	断网即瘫
隐私	音频不出设备	上传云端
成本	一颗模块	持续调用费用

代价是它只认识你预先定义好的一批命令词。但对管家机器人这个场景来说，开灯 / 关灯 / 现在几度这类封闭指令集恰恰是最需要的部分。

硬件上它通过 3.3 V TTL 电平的 UART 跟 STM32 通信，波特率 115200；前端是一颗带降噪的 MEMS 数字麦克风，电源上加了一级 LC 滤波专门滤掉 50 Hz 的电网干扰。

（3）OpenMV 机器视觉模块——眼睛

基于 STM32 微处理器的开源视觉识别模块，可用电脑端 IDE 上的 MicroPython 编程。MAYA1.0 用的是 OpenMV Cam M7：1/4″ CMOS 摄像头加一颗 STM32F7 内核，能在 640×480 下跑到 30 fps，板上就把基础图像算法算完，只把结果吐出来。

它的价值在于把"图像采集 + 算法处理 + 结果输出"封装成一块可以直接读结果的模块：你不用去啃摄像头驱动的时序，直接 find_blobs()、find_features() 就能拿到目标坐标。MAYA1.0 主要用它做两件事：

人脸检测——识别到主人来了就触发个性化问候
环境亮度分析——跟光敏电阻互为补充，极端光照下也能判断环境

结果通过 UART 以 JSON 形式上报，简单到就是 {"face":true} 或 {"brightness":75} 这种程度。

（4）ESP8266 WiFi 通讯模块——连上世界

市面上常用的一种低成本 Wi-Fi 微控制器，内置一颗 32 位 Tensilica L106，主频 80 MHz，带完整的 TCP/IP 协议栈。板载天线加低功耗睡眠，非常适合嵌入式物联网场景。

严格说 ESP8266 自己就是一颗能独立跑程序的主控，MAYA1.0 这里把它当通信协处理器用——STM32 负责决策，ESP8266 负责把决策变成网络请求发出去控制家电。这种分工让主控不必负担 TCP/IP 协议栈的开销。

（5）树莓派 2B + 3.5 寸 LCD——脸

显示模块采用 3.5 寸 LCD 显示屏，配合树莓派 2B 驱动，可显示文字、图形、动画和机器人互动表情，清晰直观地呈现环境监测数据、家电控制状态及人机交互界面。

树莓派这一侧实际上只有一个开机自启的 Python 程序：监听串口、解析命令、用 pygame 播放动画。命令帧简单到就是把名字念一遍——ANIM:SMILE、ANIM:SAD、ANIM:IDLE。这种"简陋"的协议是故意的：两边各自独立开发，只要串口对上就能联调。

（6）SG90 舵机与直流电机——手和脚

机器人结构动作和转向控制选用 SG90 舵机，STM32 输出 50 Hz 的 PWM 信号控制 0°–180° 角度，用来做头部细微动作。舵机电源线上加了一级 RC 抑制电路，降低开关噪声对主控的干扰。

$$ \alpha = \frac{\tau - 0.5,\text{ms}}{2.0,\text{ms}} \times 180^\circ, \qquad \tau = \frac{\text{CCR}}{\text{ARR}+1} \cdot 20,\text{ms} $$

底盘则是两台 9 V 直流电机驱动履带，通过 L298N 双 H 桥实现双向调速；STM32 用 PWM 占空比控制速度，电机轴上的光电编码器把实际转速反馈回来，为后续的精确定位和路径规划留好接口。

（7）机械结构与外观——3D 打印外壳 + 积木骨架

整机外观走的是机甲风格，外壳用 PLA 材料 3D 打印——既能支持复杂曲面和棱角，强度也够。建模在 SolidWorks 里完成：先画各外壳零件的草图，用拉伸、扫掠、倒角做出主体形状，再导出 STL 交给打印机。

骨架部分则是三百片模块化积木拼出来的。每个模块按标准化接口设计，既能快速装配，又能灵活调整布局去适配不同传感器、舵机和电机的位置。这个设计本质上是为迭代服务的——第一版装配完发现舵机线会干涉，改几个卡扣形状就能重来，不用重新打印整块外壳。经过多次迭代，我优化了模块连接的卡扣形状和定位销孔，保证结构在承载动力输出、反复运动之后不松动、不位移。

一张自己组的局域网：四颗 ESP8266

家用 Wi-Fi 往往是整个系统里最不可控的一环——路由器品牌各异、信号覆盖不均、还可能根本没有网。所以在网络设计上 MAYA1.0 干脆不依赖家里的路由器，而是自组了一个小型局域网。

方案是一主三从：

主控端 A 配置为 AP 模式，自己开热点，供从控端接入
从控端 B / C / D 连上 A，各自监听同一个 UDP 端口
STM32 通过 UART 把控制帧交给 A，A 再广播出去

指令格式简单到可以直接在纸上推演：

指令	方向	作用
`LIGHT_ON`	A → B/C/D	对应从控 GPIO0 拉高，继电器吸合
`LIGHT_OFF`	A → B/C/D	从控 GPIO0 拉低，继电器断开
`OK:LIGHT_ON`	从控 → A	执行回执，主控据此更新 LCD
`ERR:UNKNOWN`	从控 → A	未知指令，拒绝执行

:::warning[为什么不走 TCP] 我的第一版设计里写的是"TCP/UDP 混合"，但实际调试时我把控制帧全改成了 UDP。原因很直接：这种指令是幂等的且过期就该丢。LIGHT_ON 晚到 3 秒送达，效果和立刻送到完全一样；但 TCP 的自动重传会让一条已经过期的命令在后面某个时刻突然生效——用户早就走开了，灯突然亮起来，比丢包更糟。UDP 的"不可靠"在这个场景里反而是一种保护。

代价是需要自己做应用层确认，也就是表里那两条回执帧。 :::

代码分析

下面是我在调试过程中真正跑通的几段关键实现。整个项目按模块拆成了 6 个部分：主循环调度、环境采集、语音解析、视觉检测、网络通信、显示驱动。

[!TIP] 如果你想复现一套类似的系统，先把"STM32 发一行字符串 → 树莓派原样打印出来"这条最小链路跑通，再去接传感器和语音。我一开始跳过了这步直接上全套，第一次联调时十几个模块同时报错，根本不知道从哪一条查起。

主循环：心跳 + 事件队列 + 状态机

主控的核心是不阻塞。任何一件事都不允许在主循环里等待——否则语音命令会被传感器采样卡住，或者反过来。所以所有子程序都是"有结果就置一个事件位"，主循环只负责按优先级消费。

/* MAYA1.0 主控：50 ms 心跳调度 + 事件队列 + 四态状态机 */
#include "app.h"

typedef enum { ST_IDLE, ST_ACTIVE, ST_ALARM, ST_FAULT } sys_state_t;

#define EV_ENV     (1UL << 0)   /* 环境数据就绪 */
#define EV_VOICE   (1UL << 1)   /* 收到语音命令 */
#define EV_VISION  (1UL << 2)   /* 视觉结果到达 */
#define EV_NET     (1UL << 3)   /* 家电回执到达 */
#define EV_ALARM   (1UL << 4)   /* 姿态异常 */
#define EV_TIMEOUT (1UL << 5)   /* 40 s 无人操作 */

static volatile uint32_t g_events;
static sys_state_t       g_state = ST_IDLE;
static uint16_t          g_idle_ticks;

void app_post_event(uint32_t ev) { g_events |= ev; }

int main(void)
{
    HAL_Init();
    SystemClock_Config();       /* 8 MHz 晶振经 PLL 拉到 72 MHz */
    MX_GPIO_Init();
    MX_USART1_UART_Init();      /* ASR-PRO  115200 8N1 */
    MX_USART2_UART_Init();      /* OpenMV   115200 8N1 */
    MX_USART3_UART_Init();      /* ESP8266  115200 8N1 */
    MX_ADC1_Init();             /* LDR 光敏电阻 */
    MX_I2C1_Init();             /* MPU6050 */
    MX_TIM1_Init();             /* SG90 50 Hz PWM */

    env_init(); voice_init(); vision_init(); net_init();
    HAL_TIM_PWM_Start(&htim1, TIM_CHANNEL_1);
    display_anim("ANIM:IDLE");
    IWDG_ReloadCounter();

    uint32_t beat = HAL_GetTick();
    while (1) {
        IWDG_ReloadCounter();               /* 喂狗：跑飞了硬件自动复位 */

        if (HAL_GetTick() - beat >= 50) {   /* 50 ms 心跳，不用 delay */
            beat = HAL_GetTick();
            app_post_event(EV_ENV);
            if (mpu6050_tilted()) app_post_event(EV_ALARM);
            if (++g_idle_ticks > 800) app_post_event(EV_TIMEOUT);
        }

        uint32_t ev = g_events;
        if (!ev) continue;                  /* 没事件就放行，让中断去跑 */
        g_events &= ~ev;                    /* 边沿消费，不重复触发 */
        if (!(ev & EV_TIMEOUT)) g_idle_ticks = 0;

        if (ev & EV_ALARM) g_state = ST_ALARM;
        if (ev & EV_VOICE) g_state = ST_ACTIVE;

        switch (g_state) {
        case ST_IDLE:
            break;                          /* 低位待机，只等唤醒词 */
        case ST_ACTIVE:
            if (ev & EV_ENV)    env_report();       /* 采集 → 播报 */
            if (ev & EV_VOICE)  voice_dispatch();   /* 分发命令 */
            if (ev & EV_VISION) vision_handle();    /* 有人/偏暗 */
            if (ev & EV_NET)    net_handle();       /* 回执 → 刷 LCD */
            if (ev & EV_TIMEOUT) {
                g_state = ST_IDLE;
                display_anim("ANIM:IDLE");
            }
            break;
        case ST_ALARM: display_anim("ANIM:SAD");   break;
        case ST_FAULT: display_anim("ANIM:ERROR"); break;
        }
    }
}

注意这里有个反直觉的写法：心跳用的是 if (HAL_GetTick() - beat >= 50) 而不是 HAL_Delay(50)。区别在于 HAL_Delay 会让 CPU 空转 50 ms，这期间来的串口数据只能靠中断往缓冲区里塞，主循环完全僵住。用时间戳比较则让主循环跑满速，一旦有事件立刻处理，代价只是 CPU 占用高一点——对一块插着电的桌面机器人来说，这个交换很划算。

:::caution[别在中断里做解析] app_post_event() 只做了一件 g_events |= ev，这是刻意的。我一开始图省事，在 UART 中断回调里直接解析语音命令并调用处理函数，结果串口一帧还没接收完，下一帧的字节就把缓冲区覆盖了——表现为"偶尔识别错命令"，而且几乎不可复现。中断里只搬字节，解析全部留给主循环，这个规矩定死之后这类 bug 就绝迹了。 :::

环境采集：DHT11 时序 + LDR 双重滤波

环境数据是后面一切推荐逻辑的依据，所以这一段宁可慢一点也不能脏。不过 DHT11 自己也有采样间隔的硬要求——主循环那 50 ms 的心跳只是"去问一声"，真正拿到新数据其实是一秒一次。

/* DHT11 走单总线，LDR 走 12 位 ADC —— 两个都得滤干净才敢上报 */
#include "env.h"
#include <string.h>

#define LDR_WIN 8

static uint8_t  ldr_idx;
static uint16_t ldr_hist[LDR_WIN];

/* —— DHT11：主机拉低 20 ms 起始，然后逐位读 40 bit —— */
static uint8_t dht11_read(uint8_t *temp, uint8_t *humi)
{
    uint8_t  data[5] = {0};
    uint32_t t;

    HAL_GPIO_WritePin(DHT11_PORT, DHT11_PIN, GPIO_PIN_RESET);
    HAL_Delay(20);
    HAL_GPIO_WritePin(DHT11_PORT, DHT11_PIN, GPIO_PIN_SET);

    t = HAL_GetTick();                    /* 等 80 us 低 + 80 us 高应答 */
    while (HAL_GPIO_ReadPin(DHT11_PORT, DHT11_PIN) == GPIO_PIN_SET)
        if (HAL_GetTick() - t > 5) return 0;
    t = HAL_GetTick();
    while (HAL_GPIO_ReadPin(DHT11_PORT, DHT11_PIN) == GPIO_PIN_RESET)
        if (HAL_GetTick() - t > 5) return 0;

    for (uint8_t i = 0; i < 40; i++) {    /* 每位以 50 us 低电平开头 */
        while (HAL_GPIO_ReadPin(DHT11_PORT, DHT11_PIN) == GPIO_PIN_RESET) {}
        uint32_t high = 0;
        while (HAL_GPIO_ReadPin(DHT11_PORT, DHT11_PIN) == GPIO_PIN_SET) high++;
        data[i / 8] <<= 1;
        if (high > 20) data[i / 8] |= 1;  /* 高电平长 = 1，短 = 0 */
    }

    if ((uint8_t)(data[0] + data[1] + data[2] + data[3]) != data[4])
        return 0;                         /* 校验和不对，整帧丢掉 */

    *humi = data[0];
    *temp = data[2];
    return 1;
}

/* —— LDR：8 次滑动窗口排序后掐头去尾，压掉日光灯 100 Hz 闪变 —— */
static uint16_t ldr_filtered(void)
{
    ADC_ChannelConfTypeDef cfg = {0};
    cfg.Channel      = LDR_ADC_CH;
    cfg.Rank         = 1;
    cfg.SamplingTime = ADC_SAMPLETIME_71CYCLES_5;
    HAL_ADC_ConfigChannel(&hadc1, &cfg);

    HAL_ADC_Start(&hadc1);
    if (HAL_ADC_PollForConversion(&hadc1, 10) != HAL_OK) return 0xFFFF;
    uint16_t raw = (uint16_t)HAL_ADC_GetValue(&hadc1);
    HAL_ADC_Stop(&hadc1);

    ldr_hist[ldr_idx++ % LDR_WIN] = raw;

    uint16_t tmp[LDR_WIN];
    memcpy(tmp, ldr_hist, sizeof(tmp));
    for (uint8_t i = 0; i < LDR_WIN - 1; i++) {
        for (uint8_t j = 0; j < LDR_WIN - 1 - i; j++) {
            if (tmp[j] > tmp[j + 1]) {
                uint16_t s = tmp[j];
                tmp[j] = tmp[j + 1];
                tmp[j + 1] = s;
            }
        }
    }

    uint32_t sum = 0;
    for (uint8_t i = 1; i < LDR_WIN - 1; i++) sum += tmp[i];
    return (uint16_t)(sum / (LDR_WIN - 2));
}

光敏电阻的输出电压跟照度并不是线性的，它和一个 10 kΩ 固定电阻串起来分压，ADC 采到的其实是分压点：

$$ V_{ADC} = V_{CC} \cdot \frac{R_{fix}}{R_{LDR} + R_{fix}} $$

所以代码里没有做"照度换算"，只把 ADC 原始值做滤波后直接和阈值比。这是刻意的取舍：换成勒克斯需要标定，而我只需要一个"要不要开灯"的判断。

语音命令解析：环形缓冲 + 命令表

ASR-PRO 识别出命令后，通过串口发一行 CMD:<id>。主控这边不解析语义，只做 ID 到函数的映射。

#define RX_RING 64
static uint8_t           ring[RX_RING];
static volatile uint16_t w_idx;

/* UART1 中断回调：只搬字节，不做任何解析 */
void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart)
{
    if (huart->Instance != USART1) return;
    w_idx = (uint16_t)((w_idx + 1) % RX_RING);
    HAL_UART_Receive_IT(&huart1, &ring[w_idx], 1);
}

/* 命令表：ID 必须和 ASR-PRO IDE 里词条的排列顺序一一对应 */
typedef struct { uint8_t id; const char *name; void (*handler)(void); } voice_cmd_t;

static void cmd_light_on(void);
static void cmd_light_off(void);
static void cmd_report_env(void);

static const voice_cmd_t g_cmds[] = {
    { 1, "开灯",     cmd_light_on   },
    { 2, "关灯",     cmd_light_off  },
    { 3, "现在几度", cmd_report_env },
};

void voice_poll(void)
{
    static uint16_t r_idx;
    static char     line[32];
    static uint8_t  n;

    while (r_idx != w_idx) {              /* 环形缓冲还有没读完的字节 */
        r_idx = (uint16_t)((r_idx + 1) % RX_RING);
        char c = (char)ring[r_idx];

        if (c == '\n') {                  /* 收到完整一帧才动 */
            line[n] = '\0';
            if (strncmp(line, "CMD:", 4) == 0) {
                uint8_t id = (uint8_t)atoi(line + 4);
                for (uint8_t i = 0; i < sizeof(g_cmds) / sizeof(g_cmds[0]); i++) {
                    if (g_cmds[i].id == id) {
                        g_cmds[i].handler();
                        n = 0;
                        return;
                    }
                }
                voice_say("没听清，再说一遍");   /* 未识别也要回话 */
            }
            n = 0;
        } else if (c != '\r' && n < sizeof(line) - 1) {
            line[n++] = c;
        }
    }
}

:::important[读写指针必须各自取模] 上面 ins 标出的两行是这段代码里唯一的"技巧"，也是最容易写错的地方。环形缓冲的两个指针一个在中断里改、一个在主循环里改，两边必须用同一套取模规则。常见的错误是只在其中一侧写 if (x >= N) x = 0 兜底：单看没错，但两侧规则一旦不一致，两个指针就会落在不同区间，r_idx != w_idx 这个判断会开始撒谎——轻则漏读命令，重则读到一段早被覆盖的旧字节。

这个写法还有一个已知局限：它区分不了"空"和"满"（两种情况下 r_idx == w_idx）。所以缓冲区我留了 64 字节，而单条命令最长不过 30 字节，实际上填不满——用一点内存余量换掉了"再维护一个计数器"的那条分支。

:::

视觉检测：OpenMV 端的人脸 + 亮度

视觉这部分我把算力全部留在 OpenMV 板上，STM32 收到的只是结论。

# OpenMV Cam M7：人脸检测 + 亮度分析，结果以 JSON 经 UART 上报
import sensor, image, time, json
from machine import UART

sensor.reset()
sensor.set_pixformat(sensor.GRAYSCALE)   # 只做人脸和亮度，灰度就够，帧率更高
sensor.set_framesize(sensor.QVGA)        # 320x240
sensor.set_auto_gain(True)
sensor.skip_frames(time=2000)            # 等自动增益稳定

uart = UART(2, baudrate=115200, timeout_char=100)

# 固件内置的 Haar 级联，不用自己训练，也不占额外 Flash
face_cascade = image.HaarCascade("frontalface", stages=25)
BRIGHT_TH = 60                           # 低于这个灰度均值就该补光了

while True:
    img = sensor.snapshot()

    # 1) 亮度：整幅灰度均值，比光敏电阻更接近「人眼感受」
    stats = img.get_statistics()
    brightness = int(stats.mean())

    # 2) 人脸：threshold 越小越容易误检，0.75 是调出来的平衡点
    faces = img.find_features(face_cascade, threshold=0.75, scale_factor=1.25)
    if faces:
        f = max(faces, key=lambda r: r[2] * r[3])   # 取面积最大的那张脸
        img.draw_rectangle(f, color=255, thickness=2)

    # 3) 只发关键字段，STM32 端解析负担最小
    uart.write((json.dumps({"face": bool(faces),
                            "brightness": brightness}) + "\n").encode())

    if faces and brightness < BRIGHT_TH:
        uart.write(b"ANIM:SMILE\n")      # 有人 + 光线暗 → 打招呼并准备补光

    time.sleep_ms(50)                    # 约 20 fps，别把串口灌满

stages=25 是这里最关键的一个参数。Haar 级联的级数越多检测越准，但内存占用和耗时也越高；M7 上默认级数跑不满帧率，降到 25 之后检测延迟压到了 100 ms 以内，误检率也没有明显上升。

网络通信：ESP8266 从控端

从控端的固件短得可以整个贴出来——它的全部工作就是"收到指令 → 拨继电器 → 回执"。

/* 从控端：连主控 AP，监听 UDP，拨继电器并回执 */
#include <ESP8266WiFi.h>
#include <WiFiUdp.h>

const char    *SSID = "MAYA1.0-AP";
const char    *PASS = "maya123456";
const uint16_t PORT = 4210;              // 所有从控监听同一端口
const uint8_t  RELAY_PIN = 0;            // GPIO0 → 继电器

WiFiUDP udp;
char    buf[64];

static void reply(const char *msg) {
  udp.beginPacket(udp.remoteIP(), udp.remotePort());
  udp.print(msg);
  udp.endPacket();
}

void setup() {
  pinMode(RELAY_PIN, OUTPUT);
  digitalWrite(RELAY_PIN, LOW);          // 上电默认断开，避免误开
  Serial.begin(115200);
  WiFi.mode(WIFI_STA);
  WiFi.begin(SSID, PASS);
  while (WiFi.status() != WL_CONNECTED) { delay(200); Serial.print('.'); }
  Serial.printf("\nslave up, ip=%s\n", WiFi.localIP().toString().c_str());
  udp.begin(PORT);
}

void loop() {
  int len = udp.parsePacket();
  if (len <= 0) return;
  len = udp.read(buf, sizeof(buf) - 1);
  if (len <= 0) return;
  buf[len] = '\0';

  // 统一剥掉尾部换行，避免主控端带 \n 而测试脚本不带
  for (int i = 0; i < len; i++)
    if (buf[i] == '\r' || buf[i] == '\n') buf[i] = '\0';

  if (strcmp(buf, "LIGHT_ON") == 0) {
    digitalWrite(RELAY_PIN, HIGH);
    reply("OK:LIGHT_ON");
  } else if (strcmp(buf, "LIGHT_OFF") == 0) {
    digitalWrite(RELAY_PIN, LOW);
    reply("OK:LIGHT_OFF");
  } else {
    reply("ERR:UNKNOWN");                // 不认识的指令一律拒绝，别装成功
  }
}

显示驱动：树莓派端的动画播放器

树莓派侧是一个开机自启的 Python 程序，职责单一到只有三件事：收串口、切动画、没命令时待机。

#!/usr/bin/env python3
"""树莓派 2B 端：监听串口动画命令，用 pygame 播放，40 s 无命令进待机。"""
import json
import os
import serial
import pygame

SERIAL_PORT  = "/dev/ttyS0"
BAUD         = 115200
IDLE_TIMEOUT = 40          # 秒
FPS          = 24

HERE = os.path.dirname(os.path.abspath(__file__))
with open(os.path.join(HERE, "anims.json"), encoding="utf-8") as f:
    ANIMS = json.load(f)   # {"ANIM:IDLE": "assets/idle", "ANIM:SMILE": "assets/smile"}


class Player:
    def __init__(self):
        pygame.init()
        self.screen = pygame.display.set_mode((480, 320), pygame.FULLSCREEN)
        self.clock = pygame.time.Clock()
        self.frames, self.index, self.name = [], 0, None
        self.load("ANIM:IDLE")

    def load(self, name):
        """切换动画：载入新序列，缺资源时保持当前画面而不是崩掉。"""
        if name not in ANIMS:
            print(f"[warn] 未定义的动画 {name!r}，保持当前画面")
            return

        path = os.path.join(HERE, ANIMS[name])
        self.frames = sorted(
            pygame.image.load(os.path.join(path, f)).convert()
            for f in os.listdir(path)
            if f.lower().endswith((".png", ".jpg"))
        )
        if not self.frames:
            print(f"[warn] {path} 里没有帧图，忽略")
            return
        self.index, self.name = 0, name

    def run(self):
        ser  = serial.Serial(SERIAL_PORT, BAUD, timeout=1)
        buf  = b""
        idle = 0.0
        while True:
            for event in pygame.event.get():
                if event.type == pygame.QUIT:
                    return

            chunk = ser.read(64)
            if chunk:
                buf += chunk
                while b"\n" in buf:            # 只认换行结尾的完整帧
                    line, buf = buf.split(b"\n", 1)
                    cmd = line.decode("utf-8", "ignore").strip()
                    if cmd.startswith("ANIM:"):
                        self.load(cmd)
                        idle = 0.0

            idle += self.clock.tick(FPS) / 1000.0
            if idle >= IDLE_TIMEOUT and self.name != "ANIM:IDLE":
                self.load("ANIM:IDLE")         # 静默太久，回呼吸灯待机
                idle = 0.0

            if self.frames:
                self.screen.blit(self.frames[self.index], (0, 0))
                pygame.display.flip()
                self.index = (self.index + 1) % len(self.frames)


if __name__ == "__main__":
    Player().run()

这里那个 while b"\n" in buf 的写法值得说一下：串口 read(64) 不保证每次都刚好读到一帧，可能读到半截，也可能一次读到两帧半。所以先把数据全丢进缓冲区，再按换行切，而不是假设"一次 read 就是一帧"。这是串口编程里最常见的坑，我在调试阶段被它坑掉了整整一个下午（详见下文）。

编译与烧录

主控侧走的是标准的 arm-none-eabi-gcc 加 st-flash 流程，树莓派侧只需要把脚本挂成开机自启：

# 1) 编译 STM32 固件
cmake -B build -DCMAKE_TOOLCHAIN_FILE=cmake/arm-none-eabi.cmake -DCMAKE_BUILD_TYPE=Release
cmake --build build -j

# 2) 烧录到主控（ST-Link）
st-flash --reset write build/maya.bin 0x8000000

# 3) 树莓派侧部署为开机自启服务
scp -r display/ pi@maya-pi:/opt/maya/
ssh pi@maya-pi 'sudo systemctl enable --now maya-display.service'

:::tip[构建脚本别塞进 git] build/ 目录和 CMake 生成的缓存文件加起来动辄几十 MB，而且每次全量重建都会变。项目里加一行 build/ 就够了——这条经验是我把仓库推到 200 MB 之后才学会的。 :::

联调与实验结果

为了验证功能与性能，我设计了四组实验：语音识别、机器视觉、环境监测、家电控制。每组都在不同条件下重复多轮，取稳定值。

测试项	测试条件	结果	是否达标
语音识别	安静环境	准确率 98%，响应 < 1 s	✅
语音识别	空调 / 风扇噪声	准确率 > 90%，响应略延长	✅
人脸识别	正常光照	准确率 95%，识别 < 1 s	✅
人脸识别	低光照	准确率降至 85%，耗时延长	⚠️ 需补光
环境监测	温湿度阶跃变化	数据精度高，联动响应 < 2 s	✅
环境监测	光照阶跃变化	及时触发灯光开关	✅
家电控制	靠近路由器	响应约 0.4 s	✅
家电控制	远距 / 弱信号	响应延迟上升，仍 < 0.5 s	✅

汇总一下几个关键指标：

语音识别在安静与噪声环境下都稳定在 90% 以上
视觉检测在复杂光照条件下 85% 以上
环境监测与家电联动响应 控制在 2 秒以内
远程控制延迟 小于 0.5 秒

:::warning[低光照是这套方案的硬伤] 人脸识别在低光下掉到 85%，而且这个数字还是"正面、无遮挡"的理想情况。原因在于 OpenMV 用的是普通 CMOS 摄像头，环境照度不足时图像噪声直接淹没了 Haar 特征。当时的应对办法是让视觉结果和光敏电阻互相校验——光敏电阻说暗，就不指望人脸检测出结果，直接走"补光"分支。要真正解决得换红外摄像头，这属于后续迭代范围。 :::

至于长时间运行的稳定性，我做了一轮不间断的老化测试，监控内存占用、网络丢包和看门狗复位次数。整体表现符合预期，唯一暴露出来的是 Wi-Fi 在信号边缘区域偶发掉线——从控端会自动重连，但重连期间的控制命令会丢，这也是后来把控制帧改成 UDP 的原因之一（宁可丢一条过期命令，也不要 TCP 在那里傻等重传）。

产品化：成本、市场与代价

项目里完整分析了产品化前景，这里只挑三个我真正关心的数字。

成本。 单台样机的核心元件（STM32、语音模块、视觉模块、传感器、电机等）总成本预计在 700~900 元，批量生产后可控制在 500 元以内。这个数字能达到，靠的是核心部件全部选了国产成熟方案——这个价位在智能家居市场里是有竞争力的。

市场。 未来 5 年智能家居与物联网机器人市场的年复合增长率预计超过 20%。更重要的是需求结构在变：不只是大城市高端家庭，中小城市用户也开始关注家居智能升级；养老机构、高端公寓、写字楼物业对"一站式"智能管家的兴趣也在上升。

代价。 这部分我原本写得很委婉，这里说直白一点：这套方案最大的代价是离线语音的封闭性。ASR-PRO 只认预先烧录的命令词，用户想加一句"把客厅灯调暗一点"这种带参数的自然语言，就必须重新走一遍 IDE 流程。而换成在线方案，隐私、延迟和持续成本又都回来了。这是当前阶段无法同时满足的三角。

产品化挑战	现象	拟采取的方案
视觉受光照影响	低光下识别率降到 85%	换红外摄像头 / 高灵敏度传感器，升级识别算法
语音噪声鲁棒性	多人同时说话时识别率下降	加 AI 降噪、阵列麦克风；未来接大模型对话
Wi-Fi 稳定性	大户型 / 弱信号下延迟爬升	Mesh 组网、MQTT 协议、4G/5G 备用链路
隐私与数据安全	用户对本地数据敏感	数据本地化存储、端到端加密、权限分级

写在研发过程中

这个项目目前仍在研发中——它还没到可以拍胸脯说"做完了"的程度。

从方案设计上，我给自己划了三条原则：

不让机器人替用户做决定，只做推荐。 所以流程里有明确的"确认管理方案"环节，用户可以拒绝、可以改。智能家居最怕的是"自作聪明"，灯自己亮了自己灭，用户反而失去掌控感。
让每一步都有回执。 执行完要显示状态，环境数据要实时播报。机器人必须让用户始终知道它"现在认为世界是什么样的"。
本地优先。 语音离线、决策本地，网络只用于最终控制家电。这样即使断网，机器人至少还能聊天、还能监测、还能显示状态。

调试阶段踩过的坑里，有两个到现在还记得很清楚：

第一个是串口分包。 树莓派的动画播放器偶尔会"卡住不切动画"。查了很久才发现：STM32 发的是 ANIM:SMILE\n，但树莓派这边的 ser.read(64) 有时只读到 ANIM:SM，剩下的 ILE\n 要等下一次 read 才到。而当时的代码是"读到什么就解析什么"，于是永远匹配不上映射表。

修法就是前面代码里那个缓冲区 + 按换行切，改动其实只多了一行循环：

  chunk = ser.read(64)
- if chunk:
-     cmd = chunk.decode("utf-8", "ignore").strip()
-     if cmd.startswith("ANIM:"):
-         self.load(cmd)
+ if chunk:
+     buf += chunk
+     while b"\n" in buf:              # 只认换行结尾的完整帧
+         line, buf = buf.split(b"\n", 1)
+         cmd = line.decode("utf-8", "ignore").strip()
+         if cmd.startswith("ANIM:"):
+             self.load(cmd)

第二个是电平匹配。 ASR-PRO 是 3.3 V TTL，我最初把它直接接在一路 5 V 的串口上，结果语音模块时好时坏——不是完全不工作，而是大部分时候正常、偶尔识别错。这种"大部分时候正常"的故障最难查，因为它看起来像软件问题。后来用示波器量才发现电平不对，加了一级电平转换之后就稳了。

接下来要推进的是把上面这些模块真正联调起来，让这条五步闭环从图纸上跑起来，同时把 ANIM 资源从"几张测试图"扩充成一套完整的表情包。

小结

MAYA1.0 不是要做一个"什么都会"的机器人，而是想把桌面这一平方米管理好：知道环境、听得懂话、能动家电、会跟你商量。

做这个项目最大的体会是：机器人产品化的难点从来不在单点技术，而在闭环。语音识别、视觉、Wi-Fi 每一个都是成熟模块，但把它们串成一条用户愿意反复使用的链路，需要反复打磨交互的每个停顿——什么时候该主动说话、什么时候该等、拒绝之后怎么接茬。这些东西没有现成模块可以买。

:::note[一点私心] 比起"完成了多少指标"，我其实更在意有人从桌前走过时，MAYA1.0 自己转过来打了个招呼。技术上那只是一次 find_features() 命中加上一行 ANIM:SMILE，但那一刻它是活的。

（:spoiler[其实它第一个认错人了——先冲着我旁边的朋友热情地打了个招呼，才转向我。]） :::

MAYA1.0 这个方向我一直在继续推进。不过要先说清楚一件事：下面这个 MAYA3.0 不是本文 MAYA1.0 的升级版，它是另一个独立的项目——两者不共用一套实现，请不要混着看。

MAYA 计划

这台 MAYA1.0 不是一个孤立的作品，而是「MAYA 计划」的第一代。这个计划一共有三代产品，后续两代会陆续把文章补到这个博客里：

第一代 · MAYA1.0——就是本文这台：STM32 + 树莓派的桌面管家机器人
第三代——待公开

第二代：MAYA3.0（独立项目）

MAYA3.0 是我在 MAYA1.0 之后另起的一个项目，和本文这套代码、这条技术路线都不是同一个东西。把它和第一代分开列，就是为了避免被当成「新旧两个版本」：

::github{repo="RERELEGEND/RA2039-MAYA3.0"}

相关技术：STM32F103C8T6 · 树莓派 2B · ASR-PRO 离线语音 · OpenMV · ESP8266 · DHT11 / LDR / MPU6050 · SG90 / L298N · LCD 显示

三子棋人机对弈机器人：2024 全国大学生电子设计竞赛 E 题实录

Sat, 27 Jul 2024 00:00:00 GMT

四天三夜，三个本科生，一堆舵机和 3D 打印件。

目标是做出一台能跟人下三子棋的装置——机械臂要自己从棋子堆里夹起棋子，放到棋盘上正确的格子里，还得能赢、至少不能输，甚至能发现你偷偷挪动了它下过的棋子。

最后我们拿到了 2024 年全国大学生电子设计竞赛天津赛区本科组三等奖。下面把整个过程拆开讲讲。

一、题目：三子棋游戏装置（E 题）

这是 2024 年全国大学生电子设计竞赛赛区赛暨模拟电子系统设计专题赛初赛的本科组 E 题。

<figure class="maya-diagram" data-maya="05-contest-overview"> <div class="maya-scroll"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 810 506" width="810" height="506" class="maya-svg" role="img" aria-label="2024 全国大学生电子设计竞赛赛区赛赛题总览图：赛事与时间安排（本科组或高职高专组可选、组别第一天上报后不可更改、7 月 29 日 8:00 开赛、8 月 1 日 20:00 结束、结束时上交报告实物与登记表），参赛纪律（每队 3 人、不得换人、可用图书与网络资源、不得在场外设计制作、非参赛队员必须回避），以及本科组 E 题任务（设计制作三子棋游戏装置、控制机械臂放置棋子、实现人机对弈、棋盘由黑实线围成 9 个方格）。"><g class="maya-links"><path d="M341.2 259.7 C362.0 259.7 358.2 94.9 379.0 94.9" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M341.2 259.7 C362.0 259.7 358.2 267.8 379.0 267.8" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M341.2 259.7 C362.0 259.7 358.2 424.4 379.0 424.4" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M466.7 94.9 C520.0 94.9 510.3 29.8 563.5 29.8" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M466.7 94.9 C520.0 94.9 510.3 62.4 563.5 62.4" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M466.7 94.9 C520.0 94.9 510.3 94.9 563.5 94.9" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M466.7 94.9 C520.0 94.9 510.3 127.5 563.5 127.5" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M466.7 94.9 C520.0 94.9 510.3 160.1 563.5 160.1" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M451.2 267.8 C513.0 267.8 501.7 202.7 563.5 202.7" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M451.2 267.8 C513.0 267.8 501.7 235.2 563.5 235.2" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M451.2 267.8 C513.0 267.8 501.7 267.8 563.5 267.8" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M451.2 267.8 C513.0 267.8 501.7 300.4 563.5 300.4" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M451.2 267.8 C513.0 267.8 501.7 333.0 563.5 333.0" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M525.8 424.4 C546.5 424.4 542.8 375.5 563.5 375.5" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/><path d="M525.8 424.4 C546.5 424.4 542.8 408.1 563.5 408.1" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/><path d="M525.8 424.4 C546.5 424.4 542.8 440.7 563.5 440.7" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/><path d="M525.8 424.4 C546.5 424.4 542.8 473.3 563.5 473.3" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/></g><g class="maya-node" data-n="0" data-d="0" data-t="2024 全国大学生电子设计竞赛赛区赛 · 模拟电子系统设计专题赛初赛"><text x="20.0" y="252.4" font-size="19" font-weight="700" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">2024 全国大学生电子设计竞赛</text><text x="20.0" y="279.9" font-size="19" font-weight="700" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">赛区赛 · 模拟电子系统设计专题赛初赛</text><rect x="20.0" y="288.2" width="321.2" height="3" rx="1.5" fill="currentColor" fill-opacity="0.5"/></g><g class="maya-node" data-n="1" data-d="1" data-t="赛事与时间"><circle cx="378.0" cy="94.9" r="3.2" fill="#8b5cf6" fill-opacity="0.9"/><text x="387.2" y="100.2" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">赛事与时间</text><rect x="387.2" y="107.2" width="79.5" height="2.5" rx="1.25" fill="#8b5cf6" fill-opacity="0.95"/></g><g class="maya-node" data-n="2" data-d="2" data-t="本科组 / 高职高专组可选"><circle cx="563.4" cy="29.8" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="571.8" y="34.4" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">本科组 / 高职高专组可选</text><rect x="571.8" y="40.6" width="149.0" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="3" data-d="2" data-t="组别第一天上报，之后不可更改"><circle cx="563.4" cy="62.4" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="571.8" y="67.0" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">组别第一天上报，之后不可更改</text><rect x="571.8" y="73.2" width="191.0" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="4" data-d="2" data-t="7 月 29 日 8:00 开赛"><circle cx="563.4" cy="94.9" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="571.8" y="99.5" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">7 月 29 日 8:00 开赛</text><rect x="571.8" y="105.7" width="122.4" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="5" data-d="2" data-t="8 月 1 日 20:00 结束（四天三夜）"><circle cx="563.4" cy="127.5" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="571.8" y="132.1" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">8 月 1 日 20:00 结束（四天三夜）</text><rect x="571.8" y="138.3" width="203.4" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="6" data-d="2" data-t="结束时上交报告、实物与《登记表》"><circle cx="563.4" cy="160.1" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="571.8" y="164.7" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">结束时上交报告、实物与《登记表》</text><rect x="571.8" y="170.9" width="218.0" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="7" data-d="1" data-t="参赛纪律"><circle cx="378.0" cy="267.8" r="3.2" fill="#ec4899" fill-opacity="0.9"/><text x="387.2" y="273.1" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">参赛纪律</text><rect x="387.2" y="280.1" width="64.0" height="2.5" rx="1.25" fill="#ec4899" fill-opacity="0.95"/></g><g class="maya-node" data-n="8" data-d="2" data-t="每队严格限制 3 人"><circle cx="563.4" cy="202.7" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="571.8" y="207.3" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">每队严格限制 3 人</text><rect x="571.8" y="213.4" width="110.9" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="9" data-d="2" data-t="开赛后不得中途更换队员"><circle cx="563.4" cy="235.2" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="571.8" y="239.8" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">开赛后不得中途更换队员</text><rect x="571.8" y="246.0" width="150.5" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="10" data-d="2" data-t="可用图书资料与网络资源"><circle cx="563.4" cy="267.8" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="571.8" y="272.4" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">可用图书资料与网络资源</text><rect x="571.8" y="278.6" width="150.5" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="11" data-d="2" data-t="不得在指定场地外设计制作"><circle cx="563.4" cy="300.4" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="571.8" y="305.0" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">不得在指定场地外设计制作</text><rect x="571.8" y="311.2" width="164.0" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="12" data-d="2" data-t="非参赛队员（含教师）必须回避"><circle cx="563.4" cy="333.0" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="571.8" y="337.6" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">非参赛队员（含教师）必须回避</text><rect x="571.8" y="343.8" width="191.0" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="13" data-d="1" data-t="E 题任务（本科组）"><circle cx="378.0" cy="424.4" r="3.2" fill="#06b6d4" fill-opacity="0.9"/><text x="387.2" y="429.7" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">E 题任务（本科组）</text><rect x="387.2" y="436.6" width="138.6" height="2.5" rx="1.25" fill="#06b6d4" fill-opacity="0.95"/></g><g class="maya-node" data-n="14" data-d="2" data-t="设计并制作三子棋游戏装置"><circle cx="563.4" cy="375.5" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="571.8" y="380.1" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">设计并制作三子棋游戏装置</text><rect x="571.8" y="386.3" width="164.0" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g><g class="maya-node" data-n="15" data-d="2" data-t="控制机械臂或其他机构放置棋子"><circle cx="563.4" cy="408.1" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="571.8" y="412.7" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">控制机械臂或其他机构放置棋子</text><rect x="571.8" y="418.9" width="191.0" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g><g class="maya-node" data-n="16" data-d="2" data-t="人机对弈，先连成一线者获胜"><circle cx="563.4" cy="440.7" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="571.8" y="445.3" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">人机对弈，先连成一线者获胜</text><rect x="571.8" y="451.5" width="177.5" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g><g class="maya-node" data-n="17" data-d="2" data-t="棋盘由黑色实线围成 9 个方格"><circle cx="563.4" cy="473.3" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="571.8" y="477.9" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">棋盘由黑色实线围成 9 个方格</text><rect x="571.8" y="484.0" width="178.4" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g></svg></div> </figure>

任务：设计并制作三子棋游戏装置，能够控制机械臂或其他机构放置棋子，实现人机对弈。

棋盘由黑色实线围成 9 个方格，人和机器分别从各自的棋子放置处拾取棋子并放置到方格中，先将己方的 3 个棋子连成一线（横连、竖连、斜连皆可）即获胜——本质就是井字棋（Tic-Tac-Toe）。

9 个方格按题目给的编号排布，行优先：

	列 1	列 2	列 3
行 1	1	2	3
行 2	4	5	6
行 3	7	8	9

第 5 号格是正中心，也是评分表里第一个单独成项的考点——因为它是唯一一个"无论棋盘转到哪个角度都必须是中心"的位置。

几个硬性条件：

棋子直径约 22±2mm，棋盘和棋子由选手自带
黑、白棋子在放置处各摆成 1 列
装置放置棋子的过程中不可触压黑实线，放置后不可脱离方格区域
放置一颗棋子的时间不大于 15s
装置应能适应正常室内照明环境，测试时不得有特殊照明条件要求

时间：7 月 29 日 8:00 正式开始，8 月 1 日 20:00 结束——四天三夜。

纪律：每队严格限制 3 人，开赛后不得中途更换队员；可以使用图书资料和网络资源，但不得在竞赛场地外设计制作，不得以任何方式与他人交流，包括教师在内的非参赛队员必须回避。

二、评分点：题目真正难在哪

<figure class="maya-diagram" data-maya="06-scoring-rules"> <div class="maya-scroll"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 810 323" width="810" height="323" class="maya-svg" role="img" aria-label="E 题评分点结构图，合计 120 分：基础放置能力 45 分（1 颗黑棋放入 5 号方格 5 分、2 黑 2 白依次放入指定方格 20 分、棋盘绕中心正负 45 度旋转后仍能放置 20 分）；博弈对弈能力 40 分（执黑先行且人第 1 步出错则获胜 20 分、人执黑先行时正确放白棋保持不输 20 分）；容错与附加 15 分（棋子被变动后能发现并放回原处 10 分、其他 5 分）；设计报告 20 分。"><g class="maya-links"><path d="M205.1 175.1 C225.9 175.1 222.1 62.4 242.9 62.4" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M205.1 175.1 C225.9 175.1 222.1 153.8 242.9 153.8" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M205.1 175.1 C225.9 175.1 222.1 228.9 242.9 228.9" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M205.1 175.1 C225.9 175.1 222.1 287.8 242.9 287.8" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M395.6 62.4 C416.4 62.4 412.6 29.8 433.4 29.8" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M395.6 62.4 C416.4 62.4 412.6 62.4 433.4 62.4" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M395.6 62.4 C416.4 62.4 412.6 94.9 433.4 94.9" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M395.6 153.8 C416.4 153.8 412.6 137.5 433.4 137.5" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M395.6 153.8 C416.4 153.8 412.6 170.1 433.4 170.1" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M380.1 228.9 C409.4 228.9 404.1 212.7 433.4 212.7" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/><path d="M380.1 228.9 C409.4 228.9 404.1 245.2 433.4 245.2" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/><path d="M364.6 287.8 C402.4 287.8 395.6 287.8 433.4 287.8" fill="none" stroke="#f59e0b" stroke-opacity="0.42" stroke-width="1.4"/></g><g class="maya-node" data-n="0" data-d="0" data-t="E 题评分点合计 120 分"><text x="103.9" y="167.8" font-size="19" font-weight="700" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">E 题评分点</text><text x="103.9" y="195.3" font-size="19" font-weight="700" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">合计 120 分</text><rect x="103.9" y="203.6" width="101.2" height="3" rx="1.5" fill="currentColor" fill-opacity="0.5"/></g><g class="maya-node" data-n="1" data-d="1" data-t="基础放置能力 · 45 分"><circle cx="241.9" cy="62.4" r="3.2" fill="#8b5cf6" fill-opacity="0.9"/><text x="251.1" y="67.6" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">基础放置能力 · 45 分</text><rect x="251.1" y="74.6" width="144.5" height="2.5" rx="1.25" fill="#8b5cf6" fill-opacity="0.95"/></g><g class="maya-node" data-n="2" data-d="2" data-t="1 颗黑棋放入 5 号方格 —— 5 分"><circle cx="433.2" cy="29.8" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="441.6" y="34.4" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">1 颗黑棋放入 5 号方格 —— 5 分</text><rect x="441.6" y="40.6" width="187.4" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="3" data-d="2" data-t="2 黑 2 白依次放入指定方格 —— 20 分"><circle cx="433.2" cy="62.4" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="441.6" y="67.0" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">2 黑 2 白依次放入指定方格 —— 20 分</text><rect x="441.6" y="73.2" width="222.1" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="4" data-d="2" data-t="棋盘绕中心 ±45° 旋转后仍能放置 —— 20 分"><circle cx="433.2" cy="94.9" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="441.6" y="99.5" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">棋盘绕中心 ±45° 旋转后仍能放置 —— 20 分</text><rect x="441.6" y="105.7" width="258.2" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="5" data-d="1" data-t="博弈对弈能力 · 40 分"><circle cx="241.9" cy="153.8" r="3.2" fill="#ec4899" fill-opacity="0.9"/><text x="251.1" y="159.1" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">博弈对弈能力 · 40 分</text><rect x="251.1" y="166.0" width="144.5" height="2.5" rx="1.25" fill="#ec4899" fill-opacity="0.95"/></g><g class="maya-node" data-n="6" data-d="2" data-t="执黑先行，人第 1 步出错则获胜 —— 20 分"><circle cx="433.2" cy="137.5" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="441.6" y="142.1" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">执黑先行，人第 1 步出错则获胜 —— 20 分</text><rect x="441.6" y="148.3" width="251.6" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="7" data-d="2" data-t="人执黑先行，正确放白棋保持不输 —— 20 分"><circle cx="433.2" cy="170.1" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="441.6" y="174.7" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">人执黑先行，正确放白棋保持不输 —— 20 分</text><rect x="441.6" y="180.9" width="264.2" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="8" data-d="1" data-t="容错与附加 · 15 分"><circle cx="241.9" cy="228.9" r="3.2" fill="#06b6d4" fill-opacity="0.9"/><text x="251.1" y="234.2" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">容错与附加 · 15 分</text><rect x="251.1" y="241.2" width="129.0" height="2.5" rx="1.25" fill="#06b6d4" fill-opacity="0.95"/></g><g class="maya-node" data-n="9" data-d="2" data-t="棋子被变动，能发现并放回原处 —— 10 分"><circle cx="433.2" cy="212.7" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="441.6" y="217.3" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">棋子被变动，能发现并放回原处 —— 10 分</text><rect x="441.6" y="223.4" width="250.7" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g><g class="maya-node" data-n="10" data-d="2" data-t="其他 —— 5 分"><circle cx="433.2" cy="245.2" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="441.6" y="249.8" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">其他 —— 5 分</text><rect x="441.6" y="256.0" width="81.0" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g><g class="maya-node" data-n="11" data-d="1" data-t="设计报告 · 20 分"><circle cx="241.9" cy="287.8" r="3.2" fill="#f59e0b" fill-opacity="0.9"/><text x="251.1" y="293.1" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">设计报告 · 20 分</text><rect x="251.1" y="300.1" width="113.5" height="2.5" rx="1.25" fill="#f59e0b" fill-opacity="0.95"/></g><g class="maya-node" data-n="12" data-d="2" data-t="单独成册，与实物一同上交评审"><circle cx="433.2" cy="287.8" r="2.4" fill="#f59e0b" fill-opacity="0.9"/><text x="441.6" y="292.4" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">单独成册，与实物一同上交评审</text><rect x="441.6" y="298.6" width="191.0" height="1.8" rx="0.9" fill="#f59e0b" fill-opacity="0.8"/></g></svg></div> </figure>

#	要求	分值
1	将任意 1 颗黑棋子放置到 5 号方格中	5
2	将任意 2 黑 2 白依次放置到指定方格中	20
3	棋盘绕中心 ±45° 旋转后，仍能完成上述放置	20
4	装置执黑先行对弈，人第 1 步白棋出错则装置能获胜	20
5	人执黑先行，装置能正确放白棋保持不输棋	20
6	人变动机器下过的棋子位置，装置能自动发现并放回原处	10
7	其他	5
8	设计报告	20

合计 120 分。把这张表读透，题目的难点就清楚了——真正拉开差距的不是"会下棋"，而是"看得准、放得稳、能容错"。

:::important[三个最狠的坑] ① 棋盘会转（第 3 项，20 分）。 棋盘绕中心旋转 ±45°，意味着视觉系统拿到的是旋转后的格子坐标，机械臂的落子目标点必须跟着做坐标变换。如果代码里把 9 个格子的坐标写死，这一项直接零分。

② 棋子会被挪（第 6 项，10 分）。 人可以在不落新子的情况下，把机器下过的某颗棋子挪个位置，机器轮到时要自己发现并复位，限时 15s。这要求视觉系统不只"识别当前棋盘"，还得记住上一帧的状态并做差分对比。

③ 不许压线。「不可触压黑实线」这条最磨人——它会惩罚任何"靠视觉估计落点"的做法。机械臂必须知道得足够准，而且要留安全余量。 :::

另外第 4、5 项其实是两个方向的博弈任务：既要"执黑先行时能抓住人的失误获胜"，又要"人执黑先行时保证不输"。三子棋的先手方只要不犯错必不败，所以后手方（第 5 项）的正确策略是穷举搜索所有局面保证不输——这是个确定性算法问题，不是机器学习问题。

:::spoiler[先别往下看，自己推一下：为什么"人执黑先行"时装置只要不输就能拿满分？]

三子棋的状态空间极小——合法局面总共只有 5478 个（不含终局），完全可以在几毫秒内穷举完整棵博弈树。

既然能穷举，后手方就不需要"聪明"，只需要"正确"：对每一个人的落子，搜索出一步让自己永远不输的应对。这个性质是数学保证的，不依赖对手强弱、不依赖运气。

反过来，"执黑先行时能获胜"（第 4 项）反而不能靠搜索保证——因为先手方最优策略是平局。所以那一项题目加了个前提：「若人应对的第 1 步白棋有错误，装置能获胜」。也就是说，装置要能识别并惩罚人的失误，而不是保证赢。两个考点的数学性质完全不同，这是这份题目设计得挺巧的地方。 :::

三、赛题「说明」里的隐藏约束

评分表下面还有 6 条「说明」，很多人会跳过，但它们其实直接决定了状态机怎么写。

<figure class="maya-diagram" data-maya="07-placement-rules"> <div class="maya-scroll"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 810 418" width="810" height="418" class="maya-svg" role="img" aria-label="E 题放置规则与约束结构图：棋盘与棋子（由选手自带、棋子直径约 22 加减 2 毫米、黑白棋子在放置处各摆成 1 列）；放置要求（不可触压黑实线、放置后不可脱离方格区域、单颗放置时间不超过 15 秒）；对弈交互约定（人下完按唯一指定按钮通知装置、同时启动计时且装置落子后亮灯停表、第 6 项复位时间同样不超过 15 秒）；环境要求（适应正常室内照明、测试时不得要求特殊照明）。"><g class="maya-links"><path d="M279.4 215.8 C300.2 215.8 296.4 62.4 317.2 62.4" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M279.4 215.8 C300.2 215.8 296.4 170.1 317.2 170.1" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M279.4 215.8 C300.2 215.8 296.4 277.8 317.2 277.8" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M279.4 215.8 C300.2 215.8 296.4 369.2 317.2 369.2" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M404.9 62.4 C434.2 62.4 428.9 29.8 458.2 29.8" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M404.9 62.4 C434.2 62.4 428.9 62.4 458.2 62.4" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M404.9 62.4 C434.2 62.4 428.9 94.9 458.2 94.9" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M389.4 170.1 C427.2 170.1 420.3 137.5 458.2 137.5" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M389.4 170.1 C427.2 170.1 420.3 170.1 458.2 170.1" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M389.4 170.1 C427.2 170.1 420.3 202.7 458.2 202.7" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M420.4 277.8 C441.2 277.8 437.4 245.2 458.2 245.2" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/><path d="M420.4 277.8 C441.2 277.8 437.4 277.8 458.2 277.8" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/><path d="M420.4 277.8 C441.2 277.8 437.4 310.4 458.2 310.4" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/><path d="M389.4 369.2 C427.2 369.2 420.3 353.0 458.2 353.0" fill="none" stroke="#f59e0b" stroke-opacity="0.42" stroke-width="1.4"/><path d="M389.4 369.2 C427.2 369.2 420.3 385.5 458.2 385.5" fill="none" stroke="#f59e0b" stroke-opacity="0.42" stroke-width="1.4"/></g><g class="maya-node" data-n="0" data-d="0" data-t="放置规则与约束原题「说明」摘录"><text x="125.4" y="208.5" font-size="19" font-weight="700" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">放置规则与约束</text><text x="125.4" y="236.0" font-size="19" font-weight="700" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">原题「说明」摘录</text><rect x="125.4" y="244.4" width="154.0" height="3" rx="1.5" fill="currentColor" fill-opacity="0.5"/></g><g class="maya-node" data-n="1" data-d="1" data-t="棋盘与棋子"><circle cx="316.2" cy="62.4" r="3.2" fill="#8b5cf6" fill-opacity="0.9"/><text x="325.4" y="67.6" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">棋盘与棋子</text><rect x="325.4" y="74.6" width="79.5" height="2.5" rx="1.25" fill="#8b5cf6" fill-opacity="0.95"/></g><g class="maya-node" data-n="2" data-d="2" data-t="棋盘、棋子由选手自带"><circle cx="458.0" cy="29.8" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="466.4" y="34.4" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">棋盘、棋子由选手自带</text><rect x="466.4" y="40.6" width="137.0" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="3" data-d="2" data-t="棋子直径约 22±2mm，材质自定"><circle cx="458.0" cy="62.4" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="466.4" y="67.0" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">棋子直径约 22±2mm，材质自定</text><rect x="466.4" y="73.2" width="194.1" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="4" data-d="2" data-t="黑白棋子在放置处各摆成 1 列"><circle cx="458.0" cy="94.9" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="466.4" y="99.5" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">黑白棋子在放置处各摆成 1 列</text><rect x="466.4" y="105.7" width="178.4" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="5" data-d="1" data-t="放置要求"><circle cx="316.2" cy="170.1" r="3.2" fill="#ec4899" fill-opacity="0.9"/><text x="325.4" y="175.4" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">放置要求</text><rect x="325.4" y="182.3" width="64.0" height="2.5" rx="1.25" fill="#ec4899" fill-opacity="0.95"/></g><g class="maya-node" data-n="6" data-d="2" data-t="不可触压黑实线"><circle cx="458.0" cy="137.5" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="466.4" y="142.1" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">不可触压黑实线</text><rect x="466.4" y="148.3" width="96.5" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="7" data-d="2" data-t="放置后不可脱离方格区域"><circle cx="458.0" cy="170.1" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="466.4" y="174.7" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">放置后不可脱离方格区域</text><rect x="466.4" y="180.9" width="150.5" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="8" data-d="2" data-t="单颗放置时间 ≤ 15s，否则扣分"><circle cx="458.0" cy="202.7" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="466.4" y="207.3" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">单颗放置时间 ≤ 15s，否则扣分</text><rect x="466.4" y="213.4" width="186.4" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="9" data-d="1" data-t="对弈交互约定"><circle cx="316.2" cy="277.8" r="3.2" fill="#06b6d4" fill-opacity="0.9"/><text x="325.4" y="283.1" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">对弈交互约定</text><rect x="325.4" y="290.1" width="95.0" height="2.5" rx="1.25" fill="#06b6d4" fill-opacity="0.95"/></g><g class="maya-node" data-n="10" data-d="2" data-t="人下完按唯一指定按钮通知装置"><circle cx="458.0" cy="245.2" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="466.4" y="249.8" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">人下完按唯一指定按钮通知装置</text><rect x="466.4" y="256.0" width="191.0" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g><g class="maya-node" data-n="11" data-d="2" data-t="同时启动计时，装置落子后亮灯停表"><circle cx="458.0" cy="277.8" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="466.4" y="282.4" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">同时启动计时，装置落子后亮灯停表</text><rect x="466.4" y="288.6" width="218.0" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g><g class="maya-node" data-n="12" data-d="2" data-t="第 6 项复位时间同样 ≤ 15s"><circle cx="458.0" cy="310.4" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="466.4" y="315.0" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">第 6 项复位时间同样 ≤ 15s</text><rect x="466.4" y="321.2" width="160.3" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g><g class="maya-node" data-n="13" data-d="1" data-t="环境要求"><circle cx="316.2" cy="369.2" r="3.2" fill="#f59e0b" fill-opacity="0.9"/><text x="325.4" y="374.5" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">环境要求</text><rect x="325.4" y="381.5" width="64.0" height="2.5" rx="1.25" fill="#f59e0b" fill-opacity="0.95"/></g><g class="maya-node" data-n="14" data-d="2" data-t="适应正常室内照明"><circle cx="458.0" cy="353.0" r="2.4" fill="#f59e0b" fill-opacity="0.9"/><text x="466.4" y="357.6" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">适应正常室内照明</text><rect x="466.4" y="363.8" width="110.0" height="1.8" rx="0.9" fill="#f59e0b" fill-opacity="0.8"/></g><g class="maya-node" data-n="15" data-d="2" data-t="测试时不得要求特殊照明"><circle cx="458.0" cy="385.5" r="2.4" fill="#f59e0b" fill-opacity="0.9"/><text x="466.4" y="390.1" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">测试时不得要求特殊照明</text><rect x="466.4" y="396.3" width="150.5" height="1.8" rx="0.9" fill="#f59e0b" fill-opacity="0.8"/></g></svg></div> </figure>

其中最容易吃亏的是第 4 条：

要求（4）（5）中，人下完 1 步棋后，通过按动装置上的某唯一指定按钮通知装置，同时启动计时；装置下完 1 步棋后，通过亮灯指示，计时停止。

这条把"人和机器的回合交接"变成了一个显式的握手协议：不是靠视觉去猜"人下完了没有"，而是等一个按钮中断。这意味着固件里必须有一个等待按键的状态，并且在这个状态下不能阻塞视觉采样（否则人一按按钮，装置还在读取上一次的图像）。

:::tip[这条约束反而救了我们] 刚开始我们想过"纯视觉判断人是否落子"，即检测棋盘是否发生变化。但这条路有两个坑：一是人移动棋子的过程有中间态，容易误判；二是第 6 项要求"人不动新子、只挪旧子"，纯视觉很难区分"人在下新棋"和"人在挪旧棋"。

题目给了按钮，等于给了我们一个明确的时序锚点——按下按钮那一刻起，棋盘状态就"定格"了，装置可以放心地采样、识别、决策，不用担心人还在动。把一个模糊的感知问题变成了确定的时序问题，这是题目给的便宜，不用白不用。 :::

四、我们的方案

主控：ATmega328P（Arduino UNO 核心板）

开发工具：Arduino IDE、OpenMV IDE、VSCode、立创 EDA

核心思路是"视觉管感知、主控管决策、舵机管执行"，三块分工，用标准协议把彼此解耦：

<figure class="maya-diagram" data-maya="08-system-architecture"> <div class="maya-scroll"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 810 451" width="810" height="451" class="maya-svg" role="img" aria-label="三子棋对弈机器人系统架构图，以 ATmega328P 为主控：感知层（OpenMV 机器视觉负责棋盘与棋子识别、4×4 矩阵键盘负责落子确认与参数输入）；决策与调度（极小极大穷举搜索做博弈决策、解算各关节目标角度做路径规划、15 秒限时与状态机做时序调度）；执行层（多路 PWM 控制板经 IIC 挂载并驱动机械臂各关节舵机、3D 打印机械臂完成拾取与放置）；交互与显示（SPI OLED 显示状态与提示、UART 解耦视觉与主控、IIC 与 SPI 与 GPIO 三条外设链路）。"><g class="maya-links"><path d="M290.6 223.9 C311.4 223.9 307.7 62.4 328.4 62.4" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M290.6 223.9 C311.4 223.9 307.7 170.1 328.4 170.1" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M290.6 223.9 C311.4 223.9 307.7 277.8 328.4 277.8" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M290.6 223.9 C311.4 223.9 307.7 385.5 328.4 385.5" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M385.1 62.4 C423.0 62.4 416.1 29.8 453.9 29.8" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M385.1 62.4 C423.0 62.4 416.1 62.4 453.9 62.4" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M385.1 62.4 C423.0 62.4 416.1 94.9 453.9 94.9" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M416.1 170.1 C436.9 170.1 433.2 137.5 453.9 137.5" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M416.1 170.1 C436.9 170.1 433.2 170.1 453.9 170.1" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M416.1 170.1 C436.9 170.1 433.2 202.7 453.9 202.7" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M385.1 277.8 C423.0 277.8 416.1 245.2 453.9 245.2" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/><path d="M385.1 277.8 C423.0 277.8 416.1 277.8 453.9 277.8" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/><path d="M385.1 277.8 C423.0 277.8 416.1 310.4 453.9 310.4" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/><path d="M416.1 385.5 C436.9 385.5 433.2 353.0 453.9 353.0" fill="none" stroke="#f59e0b" stroke-opacity="0.42" stroke-width="1.4"/><path d="M416.1 385.5 C436.9 385.5 433.2 385.5 453.9 385.5" fill="none" stroke="#f59e0b" stroke-opacity="0.42" stroke-width="1.4"/><path d="M416.1 385.5 C436.9 385.5 433.2 418.1 453.9 418.1" fill="none" stroke="#f59e0b" stroke-opacity="0.42" stroke-width="1.4"/></g><g class="maya-node" data-n="0" data-d="0" data-t="三子棋对弈机器人 ATmega328P 主控"><text x="130.7" y="216.6" font-size="19" font-weight="700" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">三子棋对弈机器人</text><text x="130.7" y="244.2" font-size="19" font-weight="700" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">ATmega328P 主控</text><rect x="130.7" y="252.5" width="159.9" height="3" rx="1.5" fill="currentColor" fill-opacity="0.5"/></g><g class="maya-node" data-n="1" data-d="1" data-t="感知层"><circle cx="327.4" cy="62.4" r="3.2" fill="#8b5cf6" fill-opacity="0.9"/><text x="336.6" y="67.6" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">感知层</text><rect x="336.6" y="74.6" width="48.5" height="2.5" rx="1.25" fill="#8b5cf6" fill-opacity="0.95"/></g><g class="maya-node" data-n="2" data-d="2" data-t="OpenMV 机器视觉（STM32H7）"><circle cx="453.7" cy="29.8" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="462.1" y="34.4" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">OpenMV 机器视觉（STM32H7）</text><rect x="462.1" y="40.6" width="199.3" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="3" data-d="2" data-t="MicroPython 做棋盘与棋子识别"><circle cx="453.7" cy="62.4" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="462.1" y="67.0" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">MicroPython 做棋盘与棋子识别</text><rect x="462.1" y="73.2" width="190.4" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="4" data-d="2" data-t="4×4 矩阵键盘：落子确认与参数输入"><circle cx="453.7" cy="94.9" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="462.1" y="99.5" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">4×4 矩阵键盘：落子确认与参数输入</text><rect x="462.1" y="105.7" width="216.9" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="5" data-d="1" data-t="决策与调度"><circle cx="327.4" cy="170.1" r="3.2" fill="#ec4899" fill-opacity="0.9"/><text x="336.6" y="175.4" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">决策与调度</text><rect x="336.6" y="182.3" width="79.5" height="2.5" rx="1.25" fill="#ec4899" fill-opacity="0.95"/></g><g class="maya-node" data-n="6" data-d="2" data-t="博弈决策：极小极大穷举搜索"><circle cx="453.7" cy="137.5" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="462.1" y="142.1" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">博弈决策：极小极大穷举搜索</text><rect x="462.1" y="148.3" width="177.5" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="7" data-d="2" data-t="路径规划：解算各关节目标角度"><circle cx="453.7" cy="170.1" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="462.1" y="174.7" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">路径规划：解算各关节目标角度</text><rect x="462.1" y="180.9" width="191.0" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="8" data-d="2" data-t="时序调度：15s 限时与状态机"><circle cx="453.7" cy="202.7" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="462.1" y="207.3" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">时序调度：15s 限时与状态机</text><rect x="462.1" y="213.4" width="176.2" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="9" data-d="1" data-t="执行层"><circle cx="327.4" cy="277.8" r="3.2" fill="#06b6d4" fill-opacity="0.9"/><text x="336.6" y="283.1" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">执行层</text><rect x="336.6" y="290.1" width="48.5" height="2.5" rx="1.25" fill="#06b6d4" fill-opacity="0.95"/></g><g class="maya-node" data-n="10" data-d="2" data-t="多路 PWM 控制板（IIC 挂载）"><circle cx="453.7" cy="245.2" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="462.1" y="249.8" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">多路 PWM 控制板（IIC 挂载）</text><rect x="462.1" y="256.0" width="182.3" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g><g class="maya-node" data-n="11" data-d="2" data-t="驱动机械臂各关节舵机"><circle cx="453.7" cy="277.8" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="462.1" y="282.4" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">驱动机械臂各关节舵机</text><rect x="462.1" y="288.6" width="137.0" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g><g class="maya-node" data-n="12" data-d="2" data-t="3D 打印机械臂拾取与放置棋子"><circle cx="453.7" cy="310.4" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="462.1" y="315.0" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">3D 打印机械臂拾取与放置棋子</text><rect x="462.1" y="321.2" width="183.8" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g><g class="maya-node" data-n="13" data-d="1" data-t="交互与显示"><circle cx="327.4" cy="385.5" r="3.2" fill="#f59e0b" fill-opacity="0.9"/><text x="336.6" y="390.8" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">交互与显示</text><rect x="336.6" y="397.8" width="79.5" height="2.5" rx="1.25" fill="#f59e0b" fill-opacity="0.95"/></g><g class="maya-node" data-n="14" data-d="2" data-t="SPI OLED 显示状态与操作提示"><circle cx="453.7" cy="353.0" r="2.4" fill="#f59e0b" fill-opacity="0.9"/><text x="462.1" y="357.6" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">SPI OLED 显示状态与操作提示</text><rect x="462.1" y="363.8" width="183.8" height="1.8" rx="0.9" fill="#f59e0b" fill-opacity="0.8"/></g><g class="maya-node" data-n="15" data-d="2" data-t="UART 把视觉与主控彻底解耦"><circle cx="453.7" cy="385.5" r="2.4" fill="#f59e0b" fill-opacity="0.9"/><text x="462.1" y="390.1" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">UART 把视觉与主控彻底解耦</text><rect x="462.1" y="396.3" width="174.3" height="1.8" rx="0.9" fill="#f59e0b" fill-opacity="0.8"/></g><g class="maya-node" data-n="16" data-d="2" data-t="IIC / SPI / GPIO 三条外设链路"><circle cx="453.7" cy="418.1" r="2.4" fill="#f59e0b" fill-opacity="0.9"/><text x="462.1" y="422.7" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">IIC / SPI / GPIO 三条外设链路</text><rect x="462.1" y="428.9" width="178.3" height="1.8" rx="0.9" fill="#f59e0b" fill-opacity="0.8"/></g></svg></div> </figure>

模块	作用	通信方式
OpenMV 机器视觉摄像头（STM32H7 主控）	识别棋盘、棋子与落点	UART 串口
ATmega328P 主控	博弈决策、路径规划、时序调度	—
SPI OLED 屏幕	显示当前状态、提示人操作	SPI
多路 PWM 控制板	驱动机械臂各关节舵机	IIC
4×4 矩阵键盘	落子确认、参数输入	GPIO 扫描
3D 打印机械臂	拾取与放置棋子	舵机驱动

这个架构里有两个设计决定值得说：

为什么用 UART 把视觉和主控分开？ 因为 OpenMV 上的图像处理是毫秒到几十毫秒级的耗时操作，如果塞进主控同一颗芯片，会跟舵机 PWM 的时序打架。分开之后，OpenMV 只负责输出结论（"5 号格有一颗白棋"这种结构化数据），主控拿到结论直接做决策，两边各跑各的。

为什么用 IIC 接 PWM 控制板而不是主控直接输出 PWM？ 机械臂有多个关节，每个舵机一路 PWM。ATmega328P 的硬件定时器资源有限，直接驱动容易顾此失彼。用 IIC 挂一块多路 PWM 控制板，主控只要发"几号通道转到几度"的指令，剩下的交给控制板自己维持波形——把时序负担外包出去。

OLED 走 SPI 是因为它刷新频繁、要快；键盘走 GPIO 扫描是因为 4×4 矩阵本来就只需要几个引脚。

4.1 棋盘旋转：一个必须先解决的坐标问题

第 3 项（20 分）单独考"棋盘转 ±45° 后还能不能放准"，这题的本质是一句话：格子编号是棋盘自己的坐标系，而机械臂活在世界坐标系里，两者之间差一个刚体变换。

设棋盘中心在世界坐标系的位姿为 $(c_x, c_y)$、旋转角为 $\theta$，格子边长 $s$，那么 9 个格子中心的世界坐标是：

$$ P_{\text{world}} = R(\theta)\cdot\begin{bmatrix} (col-2),s \ (row-2),s \end{bmatrix} + \begin{bmatrix} c_x \ c_y \end{bmatrix} $$

其中 $R(\theta)$ 是二维旋转矩阵：

$$ R(\theta)=\begin{bmatrix}\cos\theta & -\sin\theta\ \sin\theta & \cos\theta\end{bmatrix} $$

$(row, col)$ 是 1~3 的格号行列。代码里唯一允许出现 9 个格子坐标的地方，就是这个函数——其余任何地方要格子坐标，都得调它。我们在复盘时也把这条列为最大教训（见文末）。

旋转角 $\theta$ 也不需要额外传感器，直接从视觉识别出的格点连线反解就行：

$$ \theta = \operatorname{atan2}!\left(\frac{y_3-y_1}{2},\ \frac{x_3-x_1}{2}\right) $$

取第 1 号与第 3 号方格中心的连线，它与水平轴的夹角就是 $\theta$。下面这段可以直接用 g++ -std=c++17 编译运行：

// 依赖：g++ -std=c++17（无第三方库）
// 把「格子号 → 世界坐标」抽成唯一入口，棋盘旋转只影响 theta 与 center
#include <cmath>
#include <cstdio>

struct Vec2 { double x, y; };

// 棋盘几何：格子边长 s、中心 center、旋转角 theta（弧度）
struct BoardFrame {
    Vec2   center{0.0, 0.0};
    double s     = 30.0;   // 题目给的格子边长量级
    double theta = 0.0;    // 棋盘绕中心旋转角，±45° 内的任意值
};

// 第 1 号与第 3 号方格中心的连线与水平轴夹角 → 棋盘旋转角
double solve_theta(Vec2 p1, Vec2 p3) {
    return std::atan2(p3.y - p1.y, p3.x - p1.x);
}

// 唯一的坐标入口：row/col 取 1..3
Vec2 grid_to_world(const BoardFrame& f, int row, int col) {
    const double lx = (col - 2) * f.s;   // 棋盘自身坐标系下的偏移
    const double ly = (row - 2) * f.s;
    const double c = std::cos(f.theta), sn = std::sin(f.theta);
    return Vec2{
        f.center.x + c * lx - sn * ly,
        f.center.y + sn * lx + c * ly,
    };
}

// ⚠️ 早期版本（已废弃）：把 9 个格子的世界坐标写死成一张表。
// 棋盘只要一转（theta ≠ 0），这张表整体失准，第 3 项直接零分。
// 保留在这里做对照——它就是下面正文里说的「1 号格被算到 (70, 50)」那个版本：
// const double GRID[9][2] = {
//     { 70,  50}, {100,  50}, {130,  50},
//     { 70,  80}, {100,  80}, {130,  80},
//     { 70, 110}, {100, 110}, {130, 110},
// };

int main() {
    BoardFrame f;
    f.center = {100.0, 80.0};

    // 不加旋转：5 号格应当正好落在棋盘中心
    Vec2 a = grid_to_world(f, 2, 2);
    std::printf("theta=0    5号格 -> (%.3f, %.3f)\n", a.x, a.y);

    // 棋盘转 30°：中心仍应在中心，但 1 号格的坐标必须跟着转
    f.theta = 30.0 * M_PI / 180.0;
    Vec2 b = grid_to_world(f, 2, 2);
    Vec2 c = grid_to_world(f, 1, 1);
    std::printf("theta=30°  5号格 -> (%.3f, %.3f)\n", b.x, b.y);
    std::printf("theta=30°  1号格 -> (%.3f, %.3f)\n", c.x, c.y);

    // 自检：中心格在任意 theta 下都必须等于棋盘中心（容差 1e-9）
    const bool center_ok =
        std::fabs(b.x - f.center.x) < 1e-9 && std::fabs(b.y - f.center.y) < 1e-9;
    std::printf("中心格不随 theta 漂移: %s\n", center_ok ? "PASS" : "FAIL");
    return center_ok ? 0 : 1;
}

跑出来是这样：

theta=0    5号格 -> (100.000, 80.000)
theta=30°  5号格 -> (100.000, 80.000)
theta=30°  1号格 -> (89.019, 39.019)
中心格不随 theta 漂移: PASS

这段代码看着平淡，但它就是第 3 项那 20 分的全部内容。如果坐标写死（即忽略 $\theta$），1 号格会被算到 $(70, 50)$，而正确位置是 $(89.02, 39.02)$——差了约 22 个单位，相当于大半个格子宽，机械臂落子必压线。

4.2 博弈决策：三子棋能穷举，所以不要用启发式

三子棋的局面数少到可以完全穷举：合法局面 5478 个，博弈树在没有剪枝的情况下也就 50 万量级。ATmega328P 是 16MHz 的 8 位机，但这个规模它完全跑得动。

所以我们没有用任何启发式评分函数，直接上极小极大 + Alpha-Beta 剪枝：

$$\text{value}(s)=\begin{cases} +1 & s\ \text{机器胜}\ -1 & s\ \text{人胜}\ \ \ 0 & s\ \text{平局}\end{cases}$$

搜索策略就是标准的极小极大：机器层取最大值、人层取最小值，等价于假设对手永远走最优。

$$ \text{best}(s)=\arg\max_{a\in A(s)}\ \min_{a'\in A(s')}\ \text{value}(s'') $$

代码如下，同样是标准 C++、可直接编译：

// 依赖：g++ -std=c++17
// 极小极大 + Alpha-Beta：三子棋局面数极小，穷举即最优，不需要启发式
#include <algorithm>
#include <array>
#include <cstdio>
#include <limits>

constexpr char EMPTY = '.';

// 平局打破用：仅在「多个走法分数相同」时生效，不参与胜负判定。
// 三子棋的最优结果是平局，所以「好几步分数都一样」是常态，
// 需要一个固定偏好让行为可复现（否则会永远选第一个空格）。
constexpr int PREF[9] = {2,1,2, 1,3,1, 2,1,2};   // 中心 3 > 角 2 > 边 1

// 8 条连线：3 行 + 3 列 + 2 斜
constexpr int LINES[8][3] = {
    {0,1,2},{3,4,5},{6,7,8},
    {0,3,6},{1,4,7},{2,5,8},
    {0,4,8},{2,4,6},
};

// 返回 +1 机器胜 / -1 人胜 / 0 未结束
int winner(const std::array<char,9>& b, char me, char human) {
    for (auto& L : LINES) {
        if (b[L[0]] != EMPTY && b[L[0]] == b[L[1]] && b[L[1]] == b[L[2]])
            return b[L[0]] == me ? +1 : -1;
    }
    return 0;
}

// 带 Alpha-Beta 的极小极大。depth 只用于在本层内打破平局（越快赢越好）
int minimax(std::array<char,9>& b, char cur, char me, char human,
            int depth, int alpha, int beta) {
    const int w = winner(b, me, human);
    if (w != 0) return w * (10 - depth);            // 赢在浅层 = 分数更高
    if (std::none_of(b.begin(), b.end(), [](char c){ return c == EMPTY; }))
        return 0;                                   // 平局

    const bool maximizing = (cur == me);
    int best = maximizing ? std::numeric_limits<int>::min()
                          : std::numeric_limits<int>::max();

    for (int i = 0; i < 9; ++i) {
        if (b[i] != EMPTY) continue;
        b[i] = cur;
        const int v = minimax(b, cur == me ? human : me, me, human,
                              depth + 1, alpha, beta);
        b[i] = EMPTY;

        if (maximizing) {
            best  = std::max(best, v);
            alpha = std::max(alpha, v);
        } else {
            best = std::min(best, v);
            beta = std::min(beta, v);
        }
        if (beta <= alpha) break;                   // 剪枝：这一支对手不会走进来
    }
    return best;
}

// 返回机器的最优落子格（0..8）；棋盘已满返回 -1
int best_move(std::array<char,9> b, char me, char human) {
    int best_score = std::numeric_limits<int>::min(), best_idx = -1;
    for (int i = 0; i < 9; ++i) {
        if (b[i] != EMPTY) continue;
        b[i] = me;
        const int v = minimax(b, human, me, human, 1,
                              std::numeric_limits<int>::min(),
                              std::numeric_limits<int>::max());
        b[i] = EMPTY;
        if (best_idx < 0 || v > best_score ||
            (v == best_score && PREF[i] > PREF[best_idx])) {
            best_score = v;
            best_idx   = i;
        }
    }
    return best_idx;
}

int main() {
    // 局面 1：机器(X)该走，威胁两条线 → 必须占中心
    std::array<char,9> b1 = {
        'X','.','.',
        '.','.','.',
        '.','.','X',
    };
    std::printf("局面1 机器最优落子: %d（应为中心 4）\n", best_move(b1, 'X', 'O'));

    // 局面 2：人(O) 已有两子连线威胁第 1 行，机器自己没有立即取胜的走法 → 必须堵
    std::array<char,9> b2 = {
        'O','O','.',
        '.','X','.',
        '.','.','X',
    };
    std::printf("局面2 机器最优落子: %d（应为 2，堵住第 1 行）\n", best_move(b2, 'X', 'O'));

    // 局面 3：空棋盘先手，所有走法都是平局 → 由 PREF 打破平局，落在中心
    std::array<char,9> b3 = {
        '.','.','.',
        '.','.','.',
        '.','.','.',
    };
    std::printf("局面3 空盘先手:     %d（应为 4，中心）\n", best_move(b3, 'X', 'O'));
    return 0;
}

实测输出：

局面1 机器最优落子: 4（应为中心 4）
局面2 机器最优落子: 2（应为 2，堵住第 1 行）
局面3 空盘先手:     4（应为 4，中心）

:::caution[为什么不用"评分函数 + 权重表"] 我们一开始写过一版"中心 3 分、角 2 分、边 1 分"的启发式，跑起来看着挺聪明，但在第 4 项（惩罚人的失误）上表现不稳定——因为启发式在对手失误时不一定能找到那条唯一的取胜线。

穷举的价值就在这里：只要局面规模允许，穷举给出的不是"好棋"，而是"正确棋"。它的正确性不依赖权重调得好不好，也不依赖对手的强度。代价只是 CPU 时间，而三子棋的规模让这个代价几乎为零。

顺便，Alpha-Beta 的剪枝在这里不是可有可无的优化——它把实际搜索节点数砍掉了大约一个数量级，让 ATmega328P 能在几十毫秒内完成一步决策，远低于 15s 的限时。 :::

4.3 「棋子被挪」：状态差分，不是重新识别

第 6 项（10 分）的坑在于：人不动新子、只把机器下过的某颗棋子挪个位置。装置必须发现并复位。

这不能靠"重新识别一遍棋盘"解决——重新识别只会得到"当前棋盘长这样"，而装置需要知道的是"哪一颗变了"。所以必须维护上一帧的状态快照：

# 依赖：Python 3.10+，无第三方库
# 棋盘状态差分：找出被人挪动过的棋子，并给出应有的位置
from dataclasses import dataclass, field


@dataclass
class Board:
    """cells[i] 为该格的棋子，'.' 表示空，'B'/'W' 为黑/白。"""
    cells: list[str] = field(default_factory=lambda: ["."] * 9)

    def board_key(self) -> str:
        return "".join(self.cells)

    def place(self, idx: int, stone: str) -> None:
        if not 0 <= idx < 9:
            raise IndexError(f"格号越界: {idx}")
        self.cells[idx] = stone


def diff(prev: Board, now: Board) -> list[tuple[int, int, str]]:
    """对比两帧棋盘。

    返回 [(from_idx, to_idx, stone)]：
      from_idx 是上一帧它所在的位置，to_idx 是现在的位置。
      棋子被挪走（原地变空）且别处多出来 → 一对 from/to。
    """
    moved: list[tuple[int, int, str]] = []
    # ① 哪些格子"少了子"
    missing = [i for i in range(9)
               if prev.cells[i] != "." and now.cells[i] == "."]
    # ② 哪些格子"多了子"（原来空着，现在有子）
    appeared = [i for i in range(9)
                if prev.cells[i] == "." and now.cells[i] != "."]

    # ③ 按棋子颜色配对：人的小动作通常是"把某颗子换个格子"
    used: set[int] = set()
    for m in missing:
        for a in appeared:
            if a in used:
                continue
            if prev.cells[m] == now.cells[a]:
                moved.append((m, a, now.cells[a]))
                used.add(a)
                break
    return moved


if __name__ == "__main__":
    prev = Board()
    # 机器(B)之前下在 4 和 8，人(W)在 0
    prev.place(4, "B"); prev.place(8, "B"); prev.place(0, "W")

    now = Board()
    # 人把机器在 4 号格的棋子挪到了 6 号格（不落新子）
    now.place(6, "B"); now.place(8, "B"); now.place(0, "W")

    moved = diff(prev, now)
    print("检测到被挪动的棋子:", moved)
    for frm, to, stone in moved:
        print(f"  {stone} 从 {frm} 号格被挪到 {to} 号格 → 应复位到 {frm} 号格")

    assert moved == [(4, 6, "B")], "差分结果不符预期"
    print("自检通过 PASS")

输出：

检测到被挪动的棋子: [(4, 6, 'B')]
  B 从 4 号格被挪到 6 号格 → 应复位到 4 号格
自检通过 PASS

拿到 (4, 6, 'B') 之后，装置要做的就是把 6 号格的棋子夹起来放回 4 号格——复位动作和正常落子走的是同一套路径规划代码，只是目标坐标不同。这也是为什么我们把"格子号 → 世界坐标"抽成了单一入口（4.1 节）。

五、一次落子的完整流程

把上面几块拼起来，一次完整的落子是这样一个闭环：

<figure class="maya-diagram" data-maya="09-move-flow"> <div class="maya-scroll"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 810 471" width="810" height="471" class="maya-svg" role="img" aria-label="一次落子的完整流程：第一步人落子并按下唯一指定按钮通知装置、启动 15 秒计时；第二步 OpenMV 采集棋盘图像并定位 9 个方格与现有棋子；第三步估计棋盘旋转角并把格子号变换为物理坐标；第四步用极小极大搜索当前局面并输出目标方格号；第五步逆运动学解算关节角并经 IIC 下发多路 PWM；第六步更新并记忆本帧棋盘状态，与上一帧差分以发现被变动的棋子。"><g class="maya-links"><path d="M279.3 233.9 C300.1 233.9 296.3 46.1 317.1 46.1" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M279.3 233.9 C300.1 233.9 296.3 121.2 317.1 121.2" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M279.3 233.9 C300.1 233.9 296.3 196.4 317.1 196.4" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M279.3 233.9 C300.1 233.9 296.3 271.5 317.1 271.5" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M279.3 233.9 C300.1 233.9 296.3 346.7 317.1 346.7" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M279.3 233.9 C300.1 233.9 296.3 421.8 317.1 421.8" fill="none" stroke="currentColor" stroke-opacity="0.50" stroke-width="1.4"/><path d="M437.5 46.1 C466.8 46.1 461.5 29.8 490.8 29.8" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M437.5 46.1 C466.8 46.1 461.5 62.4 490.8 62.4" fill="none" stroke="#8b5cf6" stroke-opacity="0.42" stroke-width="1.4"/><path d="M406.5 121.2 C452.8 121.2 444.4 104.9 490.8 104.9" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M406.5 121.2 C452.8 121.2 444.4 137.5 490.8 137.5" fill="none" stroke="#ec4899" stroke-opacity="0.42" stroke-width="1.4"/><path d="M406.5 196.4 C452.8 196.4 444.4 180.1 490.8 180.1" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/><path d="M406.5 196.4 C452.8 196.4 444.4 212.7 490.8 212.7" fill="none" stroke="#06b6d4" stroke-opacity="0.42" stroke-width="1.4"/><path d="M406.5 271.5 C452.8 271.5 444.4 255.2 490.8 255.2" fill="none" stroke="#f59e0b" stroke-opacity="0.42" stroke-width="1.4"/><path d="M406.5 271.5 C452.8 271.5 444.4 287.8 490.8 287.8" fill="none" stroke="#f59e0b" stroke-opacity="0.42" stroke-width="1.4"/><path d="M453.0 346.7 C473.8 346.7 470.0 330.4 490.8 330.4" fill="none" stroke="#10b981" stroke-opacity="0.42" stroke-width="1.4"/><path d="M453.0 346.7 C473.8 346.7 470.0 363.0 490.8 363.0" fill="none" stroke="#10b981" stroke-opacity="0.42" stroke-width="1.4"/><path d="M453.0 421.8 C473.8 421.8 470.0 405.5 490.8 405.5" fill="none" stroke="#ef4444" stroke-opacity="0.42" stroke-width="1.4"/><path d="M453.0 421.8 C473.8 421.8 470.0 438.1 490.8 438.1" fill="none" stroke="#ef4444" stroke-opacity="0.42" stroke-width="1.4"/></g><g class="maya-node" data-n="0" data-d="0" data-t="一次落子的完整流程"><text x="106.3" y="240.4" font-size="19" font-weight="700" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">一次落子的完整流程</text><rect x="106.3" y="248.7" width="173.0" height="3" rx="1.5" fill="currentColor" fill-opacity="0.5"/></g><g class="maya-node" data-n="1" data-d="1" data-t="① 人落子并通知"><circle cx="316.1" cy="46.1" r="3.2" fill="#8b5cf6" fill-opacity="0.9"/><text x="325.3" y="51.3" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">① 人落子并通知</text><rect x="325.3" y="58.3" width="112.2" height="2.5" rx="1.25" fill="#8b5cf6" fill-opacity="0.95"/></g><g class="maya-node" data-n="2" data-d="2" data-t="按下唯一指定按钮"><circle cx="490.6" cy="29.8" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="499.0" y="34.4" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">按下唯一指定按钮</text><rect x="499.0" y="40.6" width="110.0" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="3" data-d="2" data-t="启动 15s 计时"><circle cx="490.6" cy="62.4" r="2.4" fill="#8b5cf6" fill-opacity="0.9"/><text x="499.0" y="67.0" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">启动 15s 计时</text><rect x="499.0" y="73.2" width="85.0" height="1.8" rx="0.9" fill="#8b5cf6" fill-opacity="0.8"/></g><g class="maya-node" data-n="4" data-d="1" data-t="② 视觉识别"><circle cx="316.1" cy="121.2" r="3.2" fill="#ec4899" fill-opacity="0.9"/><text x="325.3" y="126.5" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">② 视觉识别</text><rect x="325.3" y="133.5" width="81.2" height="2.5" rx="1.25" fill="#ec4899" fill-opacity="0.95"/></g><g class="maya-node" data-n="5" data-d="2" data-t="OpenMV 采集棋盘图像"><circle cx="490.6" cy="104.9" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="499.0" y="109.5" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">OpenMV 采集棋盘图像</text><rect x="499.0" y="115.7" width="138.5" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="6" data-d="2" data-t="定位 9 个方格与现有棋子"><circle cx="490.6" cy="137.5" r="2.4" fill="#ec4899" fill-opacity="0.9"/><text x="499.0" y="142.1" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">定位 9 个方格与现有棋子</text><rect x="499.0" y="148.3" width="151.4" height="1.8" rx="0.9" fill="#ec4899" fill-opacity="0.8"/></g><g class="maya-node" data-n="7" data-d="1" data-t="③ 坐标变换"><circle cx="316.1" cy="196.4" r="3.2" fill="#06b6d4" fill-opacity="0.9"/><text x="325.3" y="201.6" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">③ 坐标变换</text><rect x="325.3" y="208.6" width="81.2" height="2.5" rx="1.25" fill="#06b6d4" fill-opacity="0.95"/></g><g class="maya-node" data-n="8" data-d="2" data-t="估计棋盘旋转角"><circle cx="490.6" cy="180.1" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="499.0" y="184.7" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">估计棋盘旋转角</text><rect x="499.0" y="190.9" width="96.5" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g><g class="maya-node" data-n="9" data-d="2" data-t="格子号 → 物理坐标"><circle cx="490.6" cy="212.7" r="2.4" fill="#06b6d4" fill-opacity="0.9"/><text x="499.0" y="217.3" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">格子号 → 物理坐标</text><rect x="499.0" y="223.4" width="116.7" height="1.8" rx="0.9" fill="#06b6d4" fill-opacity="0.8"/></g><g class="maya-node" data-n="10" data-d="1" data-t="④ 博弈决策"><circle cx="316.1" cy="271.5" r="3.2" fill="#f59e0b" fill-opacity="0.9"/><text x="325.3" y="276.8" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">④ 博弈决策</text><rect x="325.3" y="283.8" width="81.2" height="2.5" rx="1.25" fill="#f59e0b" fill-opacity="0.95"/></g><g class="maya-node" data-n="11" data-d="2" data-t="极小极大搜索当前局面"><circle cx="490.6" cy="255.2" r="2.4" fill="#f59e0b" fill-opacity="0.9"/><text x="499.0" y="259.8" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">极小极大搜索当前局面</text><rect x="499.0" y="266.0" width="137.0" height="1.8" rx="0.9" fill="#f59e0b" fill-opacity="0.8"/></g><g class="maya-node" data-n="12" data-d="2" data-t="输出目标方格号"><circle cx="490.6" cy="287.8" r="2.4" fill="#f59e0b" fill-opacity="0.9"/><text x="499.0" y="292.4" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">输出目标方格号</text><rect x="499.0" y="298.6" width="96.5" height="1.8" rx="0.9" fill="#f59e0b" fill-opacity="0.8"/></g><g class="maya-node" data-n="13" data-d="1" data-t="⑤ 路径规划与执行"><circle cx="316.1" cy="346.7" r="3.2" fill="#10b981" fill-opacity="0.9"/><text x="325.3" y="351.9" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">⑤ 路径规划与执行</text><rect x="325.3" y="358.9" width="127.7" height="2.5" rx="1.25" fill="#10b981" fill-opacity="0.95"/></g><g class="maya-node" data-n="14" data-d="2" data-t="逆运动学解算关节角"><circle cx="490.6" cy="330.4" r="2.4" fill="#10b981" fill-opacity="0.9"/><text x="499.0" y="335.0" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">逆运动学解算关节角</text><rect x="499.0" y="341.2" width="123.5" height="1.8" rx="0.9" fill="#10b981" fill-opacity="0.8"/></g><g class="maya-node" data-n="15" data-d="2" data-t="IIC 下发多路 PWM"><circle cx="490.6" cy="363.0" r="2.4" fill="#10b981" fill-opacity="0.9"/><text x="499.0" y="367.6" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">IIC 下发多路 PWM</text><rect x="499.0" y="373.8" width="111.5" height="1.8" rx="0.9" fill="#10b981" fill-opacity="0.8"/></g><g class="maya-node" data-n="16" data-d="1" data-t="⑥ 状态更新与校验"><circle cx="316.1" cy="421.8" r="3.2" fill="#ef4444" fill-opacity="0.9"/><text x="325.3" y="427.1" font-size="15.5" font-weight="600" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">⑥ 状态更新与校验</text><rect x="325.3" y="434.1" width="127.7" height="2.5" rx="1.25" fill="#ef4444" fill-opacity="0.95"/></g><g class="maya-node" data-n="17" data-d="2" data-t="记忆本帧棋盘状态"><circle cx="490.6" cy="405.5" r="2.4" fill="#ef4444" fill-opacity="0.9"/><text x="499.0" y="410.1" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">记忆本帧棋盘状态</text><rect x="499.0" y="416.3" width="110.0" height="1.8" rx="0.9" fill="#ef4444" fill-opacity="0.8"/></g><g class="maya-node" data-n="18" data-d="2" data-t="与上一帧差分，发现被变动的棋子"><circle cx="490.6" cy="438.1" r="2.4" fill="#ef4444" fill-opacity="0.9"/><text x="499.0" y="442.7" font-size="13.5" font-weight="500" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" fill="currentColor">与上一帧差分，发现被变动的棋子</text><rect x="499.0" y="448.9" width="204.5" height="1.8" rx="0.9" fill="#ef4444" fill-opacity="0.8"/></g></svg></div> </figure>

固件里的主循环大致是这些状态，按优先级排（列表是可勾选的任务列表形式，方便对照实现进度）：

[x] IDLE：等待人按按钮，同时 OLED 提示"请落子"
[x] CAPTURE：按键中断触发，OpenMV 拍一帧并输出 9 格占用情况
[x] ALIGN：由格点连线反解棋盘旋转角 $\theta$ 与中心 $(c_x,c_y)$
[x] DECIDE：极小极大搜索出目标格号
[x] PLAN：逆运动学解算各关节目标角，检查是否会扫到已落棋子
[x] EXECUTE：经 IIC 下发多路 PWM，依次完成"取子 → 移动 → 放下"
[x] VERIFY：落下后再拍一帧，确认棋子确实在目标格内且未压线
[ ] RECOVER：若 VERIFY 失败，退回复位流程（我们的最终版只做到了报警提示，没做自动重试）

最后一个 RECOVER 没做完，是我们这届的一个遗憾——但它在赛题里其实没有单独分值，属于"能加分但不致命"的部分。

六、我在队里做的事

我是项目队长，具体负责：

Arduino 核心板的 C++ 代码编写——博弈逻辑与时序调度这部分
设计各个模块的通讯——上面那张表里的 UART / SPI / IIC 三条链路，都是我定的协议格式
画 PCB 电路图（立创 EDA）
基于 STM32 的 OpenMV 机器视觉模块的 MicroPython 代码编写
机械臂的机械结构设计并 3D 打印（拓竹科技）

四天三夜最大的感受是"大部分时间边设计 C++ 框架边等 3D 打印机打印机械臂"——硬件迭代的周期真的是物理时间，改一版结构件就要等一轮打印，这跟写代码的节奏完全不是一回事。硬件项目里，等待本身就是工作的一部分。

七、结果

2024 年全国大学生电子设计竞赛天津赛区竞赛，我们的《三子棋游戏装置（E 题）》作品荣获本科组三等奖。

证书编号：TJ-2024-DZSJJS-0460
发证单位：天津市教育委员会

装置的运行实录（三个视角）：

:::note[关于视频] 这三段视频已随站点一起托管（public/videos/chess-robot-edc-2024/），不依赖任何外部站点。

注意 Astro 不会把文章目录里的视频文件打包进产物，所以视频必须放在 public/ 下、用 /blog/videos/xxx.mp4 这样的绝对路径引用；留在文章目录里引用是会 404 的。

另外 public/ 下的文件不会被 Astro 加哈希，路径不变的话读者浏览器会一直放旧片，所以 URL 上挂了一串 ?v=YYYYMMDDHHMM 做缓存击穿。各段视频的版本号互相独立——换哪一段就只推哪一段的号，避免让读者重下没动过的片子。

第一段是竖屏素材（源片 364×480），所以额外挂了一条 max-width:364px 的内联样式：<video width="100%"> 会把它拉到正文栏宽（约 703px）并按比例撑到 927px 高，既超出屏幕又把 364px 的源片放大近 2 倍而变糊。限到源片原生宽度后是 1:1 显示、不重采样，高度 480px 也和三段视频里的另外两段（约 395px）接近。 :::

当时的制作过程我也发在了小红书上：

📕 2024 电赛 E 题象棋机器人 - 小红书

八、工程文件与 3D 模型

:::warning[这一节还在补] 赛题作品的文件当时散在几台电脑里，正在逐步整理归档。计划补上这些，先列在这里免得忘：

[ ] 机械臂结构件 3D 模型（STEP / STL，含各关节装配关系）
[ ] PCB 原理图与 Gerber（立创 EDA 工程导出）
[ ] 主控固件（Arduino 工程，含博弈与时序调度）
[ ] OpenMV 视觉脚本（MicroPython）
[ ] BOM 物料清单（舵机型号、PWM 控制板、结构件耗材）

补齐之前，本文 4.1~4.3 节的核心算法（坐标变换、极小极大、状态差分）都是可直接编译/运行的独立文件，能先拿来跑通逻辑。 :::

设计报告本身属于竞赛提交材料，按赛区规定不单独公开；上面这份清单是装置的可复现部分，不涉及报告的正文。

九、回过头看

现在复盘，如果重做一次，我会改三件事：

先解决"放得准"，再解决"下得聪明"。 评分表里 65 分（第 1、2、3、7 项）都在考基础放置能力，只有 60 分跟博弈策略有关。我们前期花了不少时间在博弈算法上，其实基础放置的稳定性才是拿分的大头。
把坐标系统一抽象出来。 棋盘旋转那题本质是坐标变换，如果一开始就把"格子号 → 物理坐标"做成一个函数（就像 4.1 节那样），而不是散落在各处写死，第 3 项会轻松很多。
给"棋子被挪"留状态机。 第 6 项需要记忆上一帧棋盘状态，这在一开始就该作为数据模型的一部分设计进去——我们当时是快比赛结束才补的，补得很狼狈。

:::tip[GitHub 上的提醒写法] 上面这几条经验教训，如果是在 GitHub 的 issue 或 PR 里追进度，可以直接用原生语法写成任务列表：

> [!TIP]
> 这三条是"如果重做"的改进项，不是 bug。用复选框记进度最直观。

- [x] 优先保证基础放置稳定性
- [x] 坐标变换抽成单一函数
- [ ] 状态差分纳入数据模型

:::

不过说到底，原文那句总结我至今认同——"学会更多，成长才是最好的成果。"

四天三夜教会我的不是把某个算法写得多漂亮，而是在时间、硬件、体力三重约束下，怎么排优先级、怎么在"能跑的丑方案"和"优雅的烂尾"之间选前者。

十、参考与延伸

这套装置用到的三个上游项目，都是各自领域里"最小可复现"的代表：

::github{repo="openmv/openmv"}

::github{repo="adafruit/Adafruit-PWM-Servo-Driver-Library"}

::github{repo="arduino/ArduinoCore-avr"}

OpenMV 固件与 IDE——find_blobs / find_lines 那套视觉算子就是它提供的，方格的识别与定位直接建在上面
Adafruit PWM Servo Driver——多路 PWM 控制板的参考驱动，IIC 写寄存器控制各通道脉宽
ArduinoCore-avr——ATmega328P 的官方核心，硬件定时器与中断的用法都在里面

技术栈：ATmega328P（Arduino UNO）· OpenMV（STM32H7，MicroPython）· UART / SPI / IIC · OLED · 4×4 矩阵键盘 · 多路 PWM 舵机控制 · 3D 打印机械臂（拓竹）

论文登刊《中国科技人才》：基于传感器融合的自主避障无人机导航与控制算法研究

Tue, 02 Jan 2024 00:00:00 GMT

2024 年 1 月，我参与撰写的第一篇期刊论文正式刊出。

题目是《基于传感器融合的自主避障无人机导航与控制算法研究》，发表在《中国科技人才》2024 年第 1 期。这篇文章源于我们团队的一个大创项目——自主避障无人机控制系统设计。

:::note[这篇博客怎么读] 文章分两类内容，我刻意分开写，免得把「论文里写的」和「我后来想到的」混为一谈：

不加标记的段落——论文原文的梳理，尽量忠实于纸面内容；
带「延伸」二字的段落——我当时没写进去、后来真正动手做工程时才补上的东西（时间同步、EKF、体素栅格、ESDF、MPC 的 QP 形式等）。

论文本身篇幅不长、偏综述，公式也写得比较概括。所以这篇博客的价值与其说是「复述论文」，不如说是把论文里每个结论还原成它背后的工程问题。文末有三段可以直接跑的代码。 :::

论文信息

项	内容
题目	基于传感器融合的自主避障无人机导航与控制算法研究
作者	王琪、热合木图拉·艾力、朱有杰、王东成、游闯闯、张馨宁
期刊	《中国科技人才》2024 年第 1 期
刊号	ISSN 2095-8951 / CN 10-1256/G3
邮发代码	82-924
基金项目	天津市级大学生创新创业训练计划项目"自主避障无人机控制系统设计"（项目编号：202310066082）
关键词	无人机；传感器融合；自主避障；导航算法；控制算法

研究背景

无人机已经在军事、民用、科研等领域广泛使用，但它在执行任务时常常面临复杂多变的环境：城市建筑物、树木等障碍物会严重影响导航与控制。

问题的核心在于单一传感器都不够可靠：

视觉传感器能提供地形、障碍物等丰富的视觉信息，但受光照、天气影响大，数据可靠性会掉
激光雷达测距精确、能拿到三维空间信息，不受光照和天气干扰，但成本高、且拿不到颜色/纹理这类语义信息
惯性导航（IMU）用加速度计和陀螺仪测运动状态，实时性最好，但积分误差会随时间累积，跑久了就飘

于是思路就自然浮现：把它们融起来，让各自的缺点被别人的长处补上。

一、传感器融合原理

传感器融合的本质是整合多个传感器的信息，以获取更全面、准确的环境数据。本研究采用三类主要传感器：

传感器	提供的信息	短板
视觉传感器	周围地形、障碍物及其它重要特征的视觉信息	受光照、天气影响，单独使用数据不够可靠
激光雷达	精确的三维空间信息，检测物体位置与形状	相对最稳定，不受光照和天气干扰，复杂环境下表现良好
惯性导航	无人机的加速度与角速度，实时运动状态	随时间推移，积分误差累积，精度下降

融合的关键在于通过精确的数据融合算法，把三类传感器的信息整合成一份综合性数据集，从而弥补各自的缺点、实现更全面准确的环境感知。这份数据集支撑导航和控制算法的精确执行，让无人机在不同环境条件下都保持适应性与稳健性。

:::important[论文里最容易被忽略的一句] 上面这段里，「整合成一份综合性数据集」这个说法其实藏着一个关键跳跃：

三路传感器的输出根本不是同一种东西——相机给的是像素，激光雷达给的是点云，IMU 给的是角速度/加速度。它们没法直接相加，也没法拼成一张表。

工程上真正被融合出来的，不是「数据集」，而是一个带不确定度的状态估计：位置、姿态、速度，以及它们各自协方差。所谓"融合"，本质是把三路观测都当成对同一个隐藏状态的带噪测量，然后反推出这个状态最可能的取值。

这个认识一转变，后面所有问题（时间同步、标定、滤波）就都顺理成章地出现了——因为「同一个状态」这个前提，要求三路数据必须能对齐到同一时刻、同一个坐标系。 :::

<figure class="block-diagram" data-block="09-fusion-pipeline"> <div class="block-scroll"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1085 290" width="1085" height="290" class="block-svg" role="img" aria-label="传感器融合数据流图：视觉相机、激光雷达、惯性导航三路数据经时间同步与缓冲后进行扩展卡尔曼滤波，再由输出预测器推到当前时刻，供规划与控制器使用"> <g transform="translate(18,18)"> <g class="blk-links"> <path d="M 125.8 30.0 L 160.5 30.0 L 160.5 101.9 L 207.3 101.9" fill="none" stroke="currentColor" stroke-opacity="0.45" stroke-width="1.3"/> <path d="M 212.5 101.9 L 207.3 99.2 L 207.3 104.6 Z" fill="currentColor"/> <line x1="125.8" y1="101.9" x2="207.3" y2="101.9" stroke="currentColor" stroke-opacity="0.45" stroke-width="1.3"/> <path d="M 212.5 101.9 L 207.3 99.2 L 207.3 104.6 Z" fill="currentColor"/> <path d="M 158.5 173.8 L 190.9 173.8 L 190.9 101.9 L 207.3 101.9" fill="none" stroke="currentColor" stroke-opacity="0.45" stroke-width="1.3"/> <path d="M 212.5 101.9 L 207.3 99.2 L 207.3 104.6 Z" fill="currentColor"/> <line x1="420.5" y1="101.9" x2="469.3" y2="101.9" stroke="currentColor" stroke-opacity="0.45" stroke-width="1.3"/> <path d="M 474.5 101.9 L 469.3 99.2 L 469.3 104.6 Z" fill="currentColor"/> <line x1="630.2" y1="101.9" x2="679.0" y2="101.9" stroke="currentColor" stroke-opacity="0.45" stroke-width="1.3"/> <path d="M 684.2 101.9 L 679.0 99.2 L 679.0 104.6 Z" fill="currentColor"/> <line x1="850.2" y1="101.9" x2="899.0" y2="101.9" stroke="currentColor" stroke-opacity="0.45" stroke-width="1.3"/> <path d="M 904.2 101.9 L 899.0 99.2 L 899.0 104.6 Z" fill="currentColor"/> </g> <g class="blk-boxes"> <g class="blk-box" data-t="视觉相机"> <rect x="32.8" y="0.0" width="93.0" height="59.9" rx="10" fill="currentColor" fill-opacity="0.045" stroke="currentColor" stroke-opacity="0.18" stroke-width="1.2"/> <text x="79.3" y="21.6" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="14.5" font-weight="600" fill="currentColor">视觉相机</text> <text x="79.3" y="45.2" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="11.5" fill="currentColor" fill-opacity="0.58">图像 · 30 Hz</text> </g> <g class="blk-box" data-t="激光雷达"> <rect x="32.8" y="71.9" width="93.0" height="59.9" rx="10" fill="currentColor" fill-opacity="0.045" stroke="currentColor" stroke-opacity="0.18" stroke-width="1.2"/> <text x="79.3" y="93.5" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="14.5" font-weight="600" fill="currentColor">激光雷达</text> <text x="79.3" y="117.1" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="11.5" fill="currentColor" fill-opacity="0.58">点云 · 10 Hz</text> </g> <g class="blk-box" data-t="惯性导航 IMU"> <rect x="0.0" y="143.8" width="158.5" height="59.9" rx="10" fill="currentColor" fill-opacity="0.045" stroke="currentColor" stroke-opacity="0.18" stroke-width="1.2"/> <text x="79.3" y="165.4" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="14.5" font-weight="600" fill="currentColor">惯性导航 IMU</text> <text x="79.3" y="189.0" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="11.5" fill="currentColor" fill-opacity="0.58">角速度 / 加速度 · 200 Hz</text> </g> <g class="blk-box" data-t="时间同步与缓冲"> <rect x="212.5" y="71.9" width="208.0" height="59.9" rx="10" fill="#8b5cf6" fill-opacity="0.14" stroke="#8b5cf6" stroke-opacity="0.75" stroke-width="1.2"/> <text x="316.5" y="93.5" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="14.5" font-weight="600" fill="currentColor">时间同步与缓冲</text> <text x="316.5" y="117.1" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="11.5" fill="currentColor" fill-opacity="0.58">FIFO 环形缓冲 + 逐传感器延迟补偿</text> </g> <g class="blk-box" data-t="扩展卡尔曼滤波"> <rect x="474.5" y="71.9" width="155.6" height="59.9" rx="10" fill="currentColor" fill-opacity="0.045" stroke="currentColor" stroke-opacity="0.18" stroke-width="1.2"/> <text x="552.3" y="93.5" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="14.5" font-weight="600" fill="currentColor">扩展卡尔曼滤波</text> <text x="552.3" y="117.1" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="11.5" fill="currentColor" fill-opacity="0.58">IMU 前向传播 → 观测更新</text> </g> <g class="blk-box" data-t="输出预测器"> <rect x="684.2" y="71.9" width="166.0" height="59.9" rx="10" fill="currentColor" fill-opacity="0.045" stroke="currentColor" stroke-opacity="0.18" stroke-width="1.2"/> <text x="767.2" y="93.5" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="14.5" font-weight="600" fill="currentColor">输出预测器</text> <text x="767.2" y="117.1" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="11.5" fill="currentColor" fill-opacity="0.58">把状态推到「现在」这一刻</text> </g> <g class="blk-box" data-t="规划器 / 控制器"> <rect x="904.2" y="71.9" width="144.7" height="59.9" rx="10" fill="currentColor" fill-opacity="0.045" stroke="currentColor" stroke-opacity="0.18" stroke-width="1.2"/> <text x="976.5" y="93.5" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="14.5" font-weight="600" fill="currentColor">规划器 / 控制器</text> <text x="976.5" y="117.1" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="11.5" fill="currentColor" fill-opacity="0.58">100 ~ 250 Hz 取用状态</text> </g> </g> <g class="blk-gap-labels"> <text x="169.1" y="81.9" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="12" fill="currentColor" fill-opacity="0.5">各自带时间戳</text> <text x="657.2" y="81.9" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="12" fill="currentColor" fill-opacity="0.5">延迟时轴</text> </g> <g class="blk-feedback"> <path d="M 976.5 131.8 L 976.5 231.8 Q 976.5 237.8 970.5 237.8 L 85.3 237.8 Q 79.3 237.8 79.3 231.8 L 79.3 65.1" fill="none" stroke="#8b5cf6" stroke-opacity="0.6" stroke-width="1.3" stroke-dasharray="5 3"/> <path d="M 79.3 59.9 L 76.6 65.1 L 82.0 65.1 Z" fill="#8b5cf6"/> <text x="527.9" y="230.8" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="11.5" fill="currentColor" fill-opacity="0.66">闭环：控制 → 机体运动 → 重新观测</text> </g> </g> </svg></div> <figcaption>图 1 · 传感器融合的数据流：三路传感器的频率和延迟各不相同，必须先在同一时间轴上对齐，才有「融合」可言</figcaption> </figure>

1.1 延伸：把三路数据合成一个位姿，中间隔着三道坎

论文点出了"为什么要融合"，但没有展开"融合具体怎么做"。真动手时，横在中间的是三件必须先解决的事：

坎	不做会怎样	工程上怎么做
时间同步	200 Hz 的 IMU 和 10 Hz 的雷达各说各话，高速飞行时 100 ms 的错位就是几十厘米的位置误差	每路数据带统一时基的时间戳，缓存在环形缓冲里，按时间对齐后再融合
外参标定	相机和雷达装在机体的不同位置、不同朝向上，同一个障碍物在两边算出的坐标对不上	离线标定出「传感器 → 机体」的旋转与平移，融合前先统一到机体坐标系
坐标系约定	一边用东北天、一边用北东地，偏航角正负号差一个方向，飞出去就是反的	全链路固定一套约定：惯导用 ENU，机体用 FLU，接口处显式转换

① 时间同步是三件事里最容易被低估的。 真实系统里各路传感器不但频率不同，延迟也不同：IMU 几乎无延迟，而 GPS 从测量到送达飞控通常有一百多毫秒的滞后。开源飞控 PX4 的 EKF2 用的办法很值得借鉴——它维护一条"延迟融合时轴"：所有传感器先按时间戳压进 FIFO 缓冲，滤波器每次推进到某个历史时刻，再从这个时刻附近取出各路观测一起融合。它的 EKF2_GPS_DELAY 参数默认值就是 110 ms，专门用来补偿 GPS 的测量延迟。

② 外参标定要在融合前做掉。相机、雷达、IMU 的安装位置不同，同一障碍物在各自坐标系里的坐标是不同的，必须通过离线标定求出「传感器 → 机体」的变换矩阵，融合时先统一。

③ 还有一个隐蔽的问题：融合完的状态，比传感器本身还"旧"。 因为要等各路延迟不同的观测到齐，滤波器输出的是过去某一时刻的状态。PX4 的解决办法是再串一级"输出预测器"：用缓冲的 IMU 数据把那个偏旧的状态向前外推到当前时刻，再交给控制器。这一级在实时系统里不能省——否则控制器拿到的永远是百毫秒前的信息。

:::tip[判断一个融合框架好不好，先看它怎么处理时间] 只讲"融合多种传感器"而不讲时间同步与延迟补偿的方案，基本可以判定没上过真机。

因为频率和延迟的差异是物理事实，不会因为算法写得漂亮就消失。这也是我后来回头看这篇论文时，觉得最该补的一块。 :::

1.2 延伸：从「互补滤波」到卡尔曼滤波

把 IMU 和三路外部观测合起来，最朴素的写法是互补滤波：让 IMU 负责高频（动态响应好），让外部观测负责低频（不漂），用一个高通加一个低通把两者叠起来：

$$\hat{\theta}(s) = \underbrace{\frac{s}{s+\frac{1}{\tau}}}{\text{高通} \to \text{IMU}} \theta{\text{IMU}}(s) + \underbrace{\frac{1}{s+\frac{1}{\tau}}}{\text{低通} \to \text{外部观测}} \theta{\text{观测}}(s)$$

它的优点是算得极快、调参只有一个 $\tau$；缺点是同一个 $\tau$ 兼顾不了"抗漂"和"抗噪"，也没法表达"这个观测不可信"。

真实系统基本都会过渡到扩展卡尔曼滤波（EKF）。它的结构非常清晰，就两步：

预测（用 IMU 把状态推一步，同时把协方差一起推，不确定性变大）：

$$\hat{x}{k}^{-} = f(\hat{x}{k-1}, u_k), \qquad P_{k}^{-} = F_k P_{k-1} F_k^{\top} + Q_k$$

更新（来了观测就校正，用卡尔曼增益决定"信自己多少、信观测多少"）：

$$K_k = P_{k}^{-} H_k^{\top}\left(H_k P_{k}^{-} H_k^{\top} + R_k\right)^{-1}$$

$$\hat{x}k = \hat{x}{k}^{-} + K_k\left(z_k - H_k \hat{x}{k}^{-}\right), \qquad P_k = (I - K_k H_k) P{k}^{-}$$

这里几个量值得掰开说：

$Q_k$ 是过程噪声：你有多不信任自己的运动模型（比如 IMU 的零偏、颠簸）
$R_k$ 是观测噪声：你有多不信任这次观测（比如 GPS 的星数少，$R$ 就写大）
$K_k$ 是自动权衡出来的：$R$ 大则 $K$ 小（不太相信观测），$P^{-}$ 大则 $K$ 大（不太相信自己）

这就是它比互补滤波强的地方——"两边各信多少"是算出来的，不是一个固定的 $\tau$。

业界成熟的 EKF 实现通常把状态扩到 20 多个维度（PX4 的 EKF2 是 24 状态）：除了位置、速度、姿态，还要把陀螺零偏、加速度计零偏、地磁矢量、风扰动等一起估掉。原因正是下面这段演示要说明的问题。

1.3 延伸：一段能跑的 EKF 融合

下面这段代码模拟了一个很典型的场景：IMU 以 200 Hz 高频输出但含零偏，位置观测以 10 Hz 低频到来。为了让对比有意义，我把 IMU 零偏也放进了状态向量里一起估。

# 依赖：Python 3.10+，numpy
# 演示：IMU 纯积分 vs EKF 融合（IMU 高频 + 位置传感器低频）
import numpy as np

rng = np.random.default_rng(0)

DT      = 0.005          # IMU 周期 200 Hz
GPS_EVERY = 20           # 每 20 个 IMU 采样来一次位置观测 -> 100 ms
STEPS   = 4000           # 20 s

# ---- 真值：匀加速直线运动 ----
A_TRUE  = 0.3            # m/s^2
BIAS_TRUE = 0.05         # IMU 零偏，纯积分就是被它拖垮的

# ---- 传感器（含噪）----
acc_meas = A_TRUE + BIAS_TRUE + rng.normal(0.0, 0.15, STEPS)   # IMU 加速度（含零偏 + 噪声）
pos_meas = np.full(STEPS, np.nan)
p_true = np.zeros(STEPS); v_true = np.zeros(STEPS)
for k in range(1, STEPS):
    v_true[k] = v_true[k - 1] + A_TRUE * DT
    p_true[k] = p_true[k - 1] + v_true[k - 1] * DT + 0.5 * A_TRUE * DT ** 2
for k in range(0, STEPS, GPS_EVERY):                 # 低频位置观测，单独加 1 m 噪声
    pos_meas[k] = p_true[k] + rng.normal(0.0, 1.0)

# ---- EKF：状态 [p, v, b]，把 IMU 零偏也一起估出来 ----
F = np.array([[1.0, DT, -0.5 * DT ** 2],
              [0.0, 1.0,        -DT],
              [0.0, 0.0,        1.0]])
B = np.array([0.5 * DT ** 2, DT, 0.0])
Q = np.diag([1e-6, 1e-4, 1e-9])       # 过程噪声
R = np.array([[1.0 ** 2]])            # 位置观测噪声

H = np.array([[1.0, 0.0, 0.0]])
x = np.zeros(3)                       # 估计的状态
P = np.eye(3) * 1.0

p_raw, v_raw = 0.0, 0.0               # 纯积分对照
err_raw, err_ekf, bias_est = [], [], []

for k in range(STEPS):
    # --- 预测：用 IMU 推一步 ---
    x = F @ x + B * acc_meas[k]
    P = F @ P @ F.T + Q

    # --- 更新：有位置观测就校正 ---
    if not np.isnan(pos_meas[k]):
        y = pos_meas[k] - H @ x
        S = H @ P @ H.T + R
        K = P @ H.T @ np.linalg.inv(S)
        x = x + K @ y
        P = (np.eye(3) - K @ H) @ P

    # --- 对照：IMU 纯积分（不知道有零偏，误差会二次方发散）---
    p_raw += v_raw * DT + 0.5 * acc_meas[k] * DT ** 2
    v_raw += acc_meas[k] * DT

    err_raw.append(abs(p_raw - p_true[k]))
    err_ekf.append(abs(x[0] - p_true[k]))
    bias_est.append(x[2])

print(f"20 s 后位置误差：IMU 纯积分 {err_raw[-1]:6.2f} m  |  EKF {err_ekf[-1]:5.2f} m")
print(f"位置误差均值：   IMU 纯积分 {np.mean(err_raw):6.2f} m  |  EKF {np.mean(err_ekf):5.2f} m")
print(f"零偏估计：真值 {BIAS_TRUE:.3f}  →  EKF 收敛到 {bias_est[-1]:.3f} m/s^2")

实测输出：

20 s 后位置误差：IMU 纯积分   9.28 m  |  EKF  0.35 m
位置误差均值：   IMU 纯积分   3.09 m  |  EKF  0.28 m
零偏估计：真值 0.050  →  EKF 收敛到 0.032 m/s^2

20 秒里纯积分漂了 9.28 m，融合后压到 0.35 m。这就是论文那句"IMU 积分误差随时间累积"的具体量级——它不是一个抽象的缺点，而是一个随时间平方增长的位置误差，不融合根本没法用来定位。

:::caution[零偏为什么只收敛到 0.032，而不是真值 0.050？] 这不是代码写错了，而是一个很本质的现象：在匀加速运动下，加速度计零偏和真实加速度是不可分辨的。

0.05 的零偏 + 0.3 的真实加速度 和 0 的零偏 + 0.35 的真实加速度，在 IMU 输出上完全一样。滤波器只能靠位置观测的"不漂"来反推零偏，所以收敛得慢，20 秒只能收敛到一半。

要真正把零偏估准，得靠机动激励——让飞行器做变速/转向动作，不同方向的加速度把零偏"晒"出来。这也是为什么很多飞控要求起飞前必须先做静止初始化。

顺带一提，这个"可观性"问题在工程上还有个好用的判据：你在数据里看到的偏差，究竟该归给状态还是归给传感器误差，取决于运动有没有充分激励。这一点在调参时特别容易被误判成"这个传感器坏了"。 :::

二、避障算法设计

避障算法的核心问题是：如何通过实时分析传感器数据，判断可能的障碍物并采取相应措施规避。

这需要一个复杂而高效的避障逻辑：它要综合考虑障碍物的位置、无人机的速度、姿态等多个因素，以确保飞行的平稳性和安全性。论文用一组模拟数据来具体化这个过程。

<figure class="block-diagram" data-block="10-avoidance-flow"> <div class="block-scroll"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 762 234" width="762" height="234" class="block-svg" role="img" aria-label="避障决策流程图：传感器数据计算避障判据（欧氏距离与碰撞时间），判断是否越过阈值，越界则减速并调整姿态，否则保持航线"> <g transform="translate(18,18)"> <g class="blk-links"> <line x1="129.5" y1="74.1" x2="178.3" y2="74.1" stroke="currentColor" stroke-opacity="0.45" stroke-width="1.3"/> <path d="M 183.5 74.1 L 178.3 71.4 L 178.3 76.8 Z" fill="currentColor"/> <line x1="298.5" y1="74.1" x2="347.3" y2="74.1" stroke="currentColor" stroke-opacity="0.45" stroke-width="1.3"/> <path d="M 352.5 74.1 L 347.3 71.4 L 347.3 76.8 Z" fill="currentColor"/> <path d="M 493.2 74.1 L 516.6 74.1 L 516.6 38.1 L 542.0 38.1" fill="none" stroke="currentColor" stroke-opacity="0.45" stroke-width="1.3"/> <path d="M 547.2 38.1 L 542.0 35.4 L 542.0 40.8 Z" fill="currentColor"/> <text x="531.9" y="31.1" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="11.5" fill="currentColor" fill-opacity="0.66">是</text> <path d="M 493.2 74.1 L 537.3 74.1 L 537.3 118.2 L 565.8 118.2" fill="none" stroke="currentColor" stroke-opacity="0.45" stroke-width="1.3"/> <path d="M 571.0 118.2 L 565.8 115.5 L 565.8 120.9 Z" fill="currentColor"/> <text x="554.1" y="111.2" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="11.5" fill="currentColor" fill-opacity="0.66">否</text> </g> <g class="blk-boxes"> <g class="blk-box" data-t="三路传感器数据"> <rect x="0.0" y="44.1" width="129.5" height="59.9" rx="10" fill="currentColor" fill-opacity="0.045" stroke="currentColor" stroke-opacity="0.18" stroke-width="1.2"/> <text x="64.8" y="65.7" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="14.5" font-weight="600" fill="currentColor">三路传感器数据</text> <text x="64.8" y="89.3" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="11.5" fill="currentColor" fill-opacity="0.58">位置 · 速度 · 姿态</text> </g> <g class="blk-box" data-t="计算避障判据"> <rect x="183.5" y="36.0" width="115.0" height="76.2" rx="10" fill="currentColor" fill-opacity="0.045" stroke="currentColor" stroke-opacity="0.18" stroke-width="1.2"/> <text x="241.0" y="57.6" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="14.5" font-weight="600" fill="currentColor">计算避障判据</text> <text x="241.0" y="81.2" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="11.5" fill="currentColor" fill-opacity="0.58">欧氏距离 D</text> <text x="241.0" y="97.5" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="11.5" fill="currentColor" fill-opacity="0.58">碰撞时间 TTC</text> </g> <g class="blk-box" data-t="越过阈值？"> <rect x="352.5" y="44.1" width="140.7" height="59.9" rx="10" fill="#f59e0b" fill-opacity="0.14" stroke="#f59e0b" stroke-opacity="0.75" stroke-width="1.2"/> <text x="422.9" y="65.7" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="14.5" font-weight="600" fill="currentColor">越过阈值？</text> <text x="422.9" y="89.3" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="11.5" fill="currentColor" fill-opacity="0.58">D < D阈值或 TTC < τ</text> </g> <g class="blk-box" data-t="执行避障"> <rect x="547.2" y="0.0" width="179.1" height="76.2" rx="10" fill="#f59e0b" fill-opacity="0.14" stroke="#f59e0b" stroke-opacity="0.75" stroke-width="1.2"/> <text x="636.8" y="21.6" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="14.5" font-weight="600" fill="currentColor">执行避障</text> <text x="636.8" y="45.2" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="11.5" fill="currentColor" fill-opacity="0.58">减速 V新 = V原 − k(D − D阈值)</text> <text x="636.8" y="61.5" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="11.5" fill="currentColor" fill-opacity="0.58">转姿 θ新 = θ原 + α(D − D阈值)</text> </g> <g class="blk-box" data-t="保持航线"> <rect x="571.0" y="88.2" width="131.5" height="59.9" rx="10" fill="currentColor" fill-opacity="0.03" stroke="currentColor" stroke-opacity="0.28" stroke-width="1.2" stroke-dasharray="4 3"/> <text x="636.8" y="109.8" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="14.5" font-weight="600" fill="currentColor">保持航线</text> <text x="636.8" y="133.4" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="11.5" fill="currentColor" fill-opacity="0.58">继续跟踪原参考路径</text> </g> </g> <g class="blk-feedback"> <path d="M 636.8 76.2 L 636.8 176.2 Q 636.8 182.2 630.8 182.2 L 70.8 182.2 Q 64.8 182.2 64.8 176.2 L 64.8 109.2" fill="none" stroke="#8b5cf6" stroke-opacity="0.6" stroke-width="1.3" stroke-dasharray="5 3"/> <path d="M 64.8 104.0 L 62.0 109.2 L 67.5 109.2 Z" fill="#8b5cf6"/> <text x="350.8" y="175.2" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="11.5" fill="currentColor" fill-opacity="0.66">下一控制周期</text> </g> </g> </svg></div> <figcaption>图 2 · 避障决策流程：论文的三条公式其实就是把「会不会撞」翻译成「减速多少、偏多少」</figcaption> </figure>

表 1 传感器测得的障碍物位置和无人机状态

时间（秒）	障碍物 X 坐标（米）	障碍物 Y 坐标（米）	无人机速度（米/秒）	无人机姿态角度（弧度）
0	10	5	5	0.5
1	12	8	6	0.8
2	15	10	7	1.2
3	18	12	8	1.5
4	20	15	9	1.8

2.1 论文的三条公式

公式 1：避障距离计算。先定义避障距离阈值（本研究中设为 5 米）：当无人机与障碍物的距离小于该阈值时，就需要执行避障动作。无人机与障碍物之间的欧几里得距离：

$$D_{\text{避障}} = \sqrt{(X_{\text{障碍}} - X_{\text{无人机}})^2 + (Y_{\text{障碍}} - Y_{\text{无人机}})^2}$$

若 $D_{\text{避障}}$ 小于避障距离阈值，即表示需要启动避障。

**公式 2：速度调整。**依据距离与速度的关系调整无人机速度：

$$V_{\text{新}} = V_{\text{原}} - k \cdot (D_{\text{避障}} - D_{\text{阈值}})$$

其中 $V_{\text{新}}$ 是调整后的速度，$V_{\text{原}}$ 是原始速度，$k$ 是调整系数。

**公式 3：姿态调整。**通过姿态调整确保无人机在避障过程中保持平稳：

$$\theta_{\text{新}} = \theta_{\text{原}} + \alpha \cdot (D_{\text{避障}} - D_{\text{阈值}})$$

其中 $\theta_{\text{新}}$ 是调整后的姿态角度，$\theta_{\text{原}}$ 是原始姿态角度，$\alpha$ 是调整角度的系数。

:::note[这三个公式的关系] 三个公式构成一套"感知 → 减速 → 转姿"的串联逻辑：

公式 1 判断会不会撞（距离是否越界）
公式 2 决定要不要慢下来（距离越近、减得越多）
公式 3 决定往哪边偏（同时调整姿态保持平稳）

它们通过实时计算距离、调整速度和姿态，让无人机在遇到障碍物时能做出及时、平稳的规避动作。论文也指出，这个算法的复杂性正体现在"综合考虑多个因素"上——通过实际数据与公式的结合，才能更好地理解和评估无人机在复杂环境中的避障能力。 :::

2.2 延伸：这三条公式其实就是「一个比例控制器」

把公式 2 和公式 3 抄近一点看：

$$V_{\text{新}} = V_{\text{原}} - k \cdot \underbrace{(D_{\text{避障}} - D_{\text{阈值}})}_{\text{误差 } e}$$

如果把 $(D_{\text{避障}} - D_{\text{阈值}})$ 看成误差 $e$，那么这两条式子就是标准的比例控制：输出 = 系数 × 误差。$k$ 和 $\alpha$ 就是比例增益。

这个等价关系很有用，因为它一次性带来了三个已知结论：

比例控制的已知性质	在这套避障公式上的表现
增益太小收敛慢	$k$ 取小了，飞机会"慢悠悠地蹭"过去，避障动作不果断
增益太大会振荡	$k$ 取大了，速度在阈值附近反复横跳，姿态也跟着抖
纯比例一定存在稳态误差	距离恰好压在阈值时输出为零，它不会主动把距离拉回到一个安全余量

最后一条是这个方案最本质的局限：纯比例控制只能"按误差线性回应"，做不到"提前留出安全余量"。而避障恰恰是个需要余量的场景。

（先别往下看，自己推一下：当 $D_{\text{避障}}$ 恰好等于阈值时，公式 2 和公式 3 给出的调整量是多少？:spoiler[两个式子里的 $(D_{\text{避障}} - D_{\text{阈值}})$ 都等于 0，所以速度不变、姿态不变——飞行器就停在"刚好要撞"的边界上，不做任何反应。这就是"纯比例不给余量"的数学根源：误差为零时控制量为零，于是它天然缺少"离远一点"的驱动力。]）

:::warning[三个公式里没出现"速度方向"] 公式 1 用的是欧氏距离，是个标量，它不含方向信息。

这意味着一个很实际的漏洞：无人机以 10 m/s 迎面冲向障碍物，和背对着障碍物以 10 m/s 远离，只要距离相同，算出来的 $D_{\text{避障}}$ 完全一样，公式 2、3 给出的调整量也完全相同。

换句话说，这套判据分不清"正在靠近"和"正在远离"。要补上这个信息，就得引入下面这个量。 :::

2.3 延伸：更常用的判据——碰撞时间 TTC

真正决定"危不危险"的不是距离，而是距离 ÷ 接近速度，也就是碰撞时间（Time To Collision, TTC）：

$$\text{TTC} = \frac{D_{\text{避障}}}{\max\left(-\dfrac{dD}{dt},\ \varepsilon\right)}$$

分母是接近速率（距离的负导数），加 $\varepsilon$ 只是防止除零。TTC 的物理含义很直白：按当前速度不变，还有多少秒会撞上。

它比纯距离判据好在三点：

含了速度信息：正以 10 m/s 迎面冲来（TTC = 1 s）和静止悬停（TTC → ∞）被明确区分开
量纲统一：单位是秒，阈值可以直接按"人的反应时间/飞控的刹车距离"来定，容易理解也容易调
天生适合多机与动态障碍：对方也在动时，距离判据会失效，TTC 仍然成立

不同判据的对照：

判据	核心式子	优点	局限
欧氏距离（论文所用）	$\sqrt{\Delta x^2 + \Delta y^2}$	最好算，无参数	不含速度与方向，分不清靠近/远离
碰撞时间 TTC	$D / \dot{D}$	含接近速度，量纲直观	平行飞行时 $\dot{D} \to 0$，TTC 爆表需特殊处理
人工势场法	引力 + 斥力叠加	输出是连续的力/加速度，可直接接控制器	存在局部极值，目标在凹形障碍后可能卡住
碰撞锥 / 速度障碍	相对速度是否落在锥内	显式给出"哪些速度安全"，适合动态环境	计算量较大，多障碍时要逐个求交

下面这段就是把「距离判据」升级成「TTC 判据」的改动思路，用 diff 的写法看更清楚：

  def should_avoid(D, closing_speed, D_threshold=5.0, tau=2.0):
-     # 只比距离：分不清正在靠近还是正在远离
-     return D < D_threshold
+     # 先看距离有没有进到警戒圈
+     if D >= D_threshold:
+         return False
+     # 再看"还有几秒会撞上"：速度方向不同，结论就不同
+     if closing_speed <= 1e-3:      # 没在接近，其实不用避
+         return False
+     return D / closing_speed < tau

:::tip[为什么"阈值 5 米"这种写法在工程上很难落地] 论文把避障阈值定为 5 米。但如果飞机速度从 5 m/s 提到 15 m/s，5 米的预警距离就只有 0.33 秒——扣掉传感器延迟、算法耗时和执行器响应，实际已经来不及了。

所以工程上更稳的做法是把阈值写成速度的函数（或直接用 TTC）：D_threshold = 刹车距离 + 安全余量，其中刹车距离随速度平方增长。这样阈值会自己跟着速度调整，高速时自动变宽。 :::

2.4 延伸：从「障碍物坐标列表」到「体素占据栅格」

论文的表 1 是一种很"教科书"的表示：把障碍物存成坐标点。这在仿真里很方便，但真机上有两个问题：

激光雷达一秒回来的是几十万个点，逐个当障碍物去算距离根本算不过来
障碍物不是点，是有体积的形状，用点表示会丢掉"这个方向有多宽"的信息

现实中的做法是先把空间离散成一个三维格网，每个格子标记"有没有被占据"，这就是体素占据栅格（voxel occupancy grid）：

$$M(i,j,k) = \begin{cases} 1, & \text{该体素被占据} \ 0, & \text{该体素空闲} \end{cases}$$

点云落进哪个格子，就把哪个格子置 1（实际实现里还会用概率滤波处理噪点，避免一个飞点就在地图上戳出一堵墙）。

上图是这类地图的一个典型样子：颜色不是装饰，而是高度的映射（红=高、蓝=低），这样一眼就能看出三维结构；白线是规划器在栅格地图里搜出来的轨迹。可以看到它绕着障碍的凸起走，而不是贴着走。

**但这张图里最关键的其实是没画出来的那一步。**栅格只回答了"这个格子能不能走"（是离散的是/否），而规划器和控制器需要的是"离最近的障碍还有多远"（是连续的数值）。把前者变成后者，靠的是 ESDF（欧氏符号距离场）：

$$\text{ESDF}(v) = \begin{cases} +\min_{u \in \text{障碍}} \lVert v - u \rVert, & v \text{ 在空闲区} \[4pt] -\min_{u \in \partial \text{障碍}} \lVert v - u \rVert, & v \text{ 在障碍内} \end{cases}$$

也就是给每个体素存一个数：它到最近障碍的距离。符号表示在障碍外还是里（负号就是在障碍内部）。

这个数据结构一旦建好，避障就变得非常"便宜"——因为它同时提供了两个东西：

ESDF 提供	用来干什么
距离值	直接当安全裕量用：`ESDF(v) > 安全半径` 就是安全的
梯度 $\nabla \text{ESDF}$	直接当远离障碍的方向用，而且指向的是"最短逃逸方向"

梯度这一条特别关键：它把"往哪边躲最好"这个决策，变成了一个查表加求导的操作。前一节的受力方向、后一节的轨迹优化，用的都是这个梯度。业界成熟的实现里，Voxblox 用 TSDF 增量构建 ESDF，EGO-Planner 则直接在 ESDF 上做梯度下降优化轨迹。

2.5 延伸：一段能跑的「栅格 → ESDF → 势场避障」

把 2.3 节的势场法和 2.4 节的 ESDF 接起来，就是下面这段。它把地图离散成 0.2 m 的栅格，用 scipy 一次性算出 ESDF，再让一个质点顺着"引力 + ESDF 梯度斥力"飞过去：

# 依赖：Python 3.10+，numpy、scipy
# 演示：体素占据栅格 -> ESDF -> 用势场法绕障
import numpy as np
from scipy.ndimage import distance_transform_edt

RES = 0.2                      # 每格 0.2 m
H = W = 120                    # 24 m x 24 m 的局部地图
maps = np.zeros((H, W), dtype=bool)          # True = 被占据

# 两堵墙 + 一根柱子（真实环境里这些格由点云投影得到）
maps[30:34, 15:100] = True
maps[72:76, 20:105] = True
maps[50:62, 58:66] = True

# ---- ESDF：每个空闲格到最近障碍的距离（米）----
# distance_transform_edt 给出「到最近 True 的欧氏距离」，单位是格，乘 RES 换成米
esdf = distance_transform_edt(~maps) * RES


def esdf_grad(esdf, pos):
    """用双线性插值取 ESDF 值，并用中心差分取梯度（指向远离障碍的方向）。"""
    x, y = pos / RES
    x0, y0 = int(x), int(y)
    tx, ty = x - x0, y - y0

    def sample(ix, iy):
        ix = np.clip(ix, 0, W - 1); iy = np.clip(iy, 0, H - 1)
        return esdf[iy, ix]

    val = ((1 - tx) * (1 - ty) * sample(x0, y0) + tx * (1 - ty) * sample(x0 + 1, y0)
           + (1 - tx) * ty * sample(x0, y0 + 1) + tx * ty * sample(x0 + 1, y0 + 1))

    gx = (sample(x0 + 1, y0) - sample(x0 - 1, y0)) / (2 * RES)
    gy = (sample(x0, y0 + 1) - sample(x0, y0 - 1)) / (2 * RES)
    return val, np.array([gx, gy])


# ---- 势场法：引力拉向目标 + 斥力推开障碍 ----
def attractive(pos, goal, k=3.0):
    return k * (goal - pos)

def repulsive(pos, esdf, d0=2.0, k=12.0):
    d, grad = esdf_grad(esdf, pos)
    if d >= d0 or d < 1e-6:
        return np.zeros(2)
    return k * (1.0 / d - 1.0 / d0) / d ** 2 * grad     # 越近推得越猛


start = np.array([1.0, 0.5])
goal  = np.array([22.0, 22.0])
pos, vel = start.copy(), np.zeros(2)
DT, VMAX = 0.02, 3.0

min_clear, path_len, steps = np.inf, 0.0, 0

for _ in range(12000):
    f = attractive(pos, goal) + repulsive(pos, esdf)
    vel = np.clip(0.9 * vel + f * DT, -VMAX, VMAX)
    pos = pos + vel * DT
    steps += 1

    clear, _g = esdf_grad(esdf, pos)
    min_clear = min(min_clear, clear)
    path_len += np.linalg.norm(vel) * DT

    if np.linalg.norm(pos - goal) < 0.3:
        break
    if clear <= 0.0:                       # 撞进障碍格
        print(f"❌ 在第 {steps} 步撞上障碍（位置 {pos.round(2)}）")
        break

reached = np.linalg.norm(pos - goal) < 0.3
print(f"到达目标：{reached}   用时 {steps * DT:.1f} s   路径长度 {path_len:.1f} m")
print(f"全程离障碍最近：{min_clear:.2f} m   终点 {pos.round(2)}（目标 {goal}）")

实测输出：

到达目标：True   用时 14.8 s   路径长度 38.1 m
全程离障碍最近：0.45 m   终点 [22.01 21.7 ]（目标 [22. 22.])

:::important[这段输出里藏着势场法的两个老毛病] 能到目标，但请对照两个数：

**① 路径明显绕远。**起点 (1, 0.5) 到终点 (22, 22) 的直线距离约 29.9 m，实际飞了 38.1 m，多出 28%。因为这股力是"局部"的——只在看得见的斥力范围内起作用，没有全局最优的概念。

**② 全程离障碍最近只有 0.45 m。**它确实没撞上，但是"贴着边蹭过去"的。势场法的斥力与距离平方成反比，在接近障碍时增长得很快，可一旦越过了"最危险的那一点"，斥力就骤减，于是轨迹表现为贴着障碍画弧。

还有第三个更致命的问题，这段代码恰好避开了：势场法存在局部极值——如果目标正好落在一个凹形（比如 U 形）障碍的开口里，引力和斥力会在某个位置正好抵消，飞行器就停在那里，既到不了目标也不撞上去。这是纯势场法无法根治的缺陷，工程上要么改用基于搜索的全局规划 + 局部优化，要么加随机扰动跳出极值。 :::

:::caution[本节的诚实说明] 论文并没有用势场法，也没有用体素栅格和 ESDF——它用的是障碍物坐标 + 欧氏距离阈值。

上面这一节（以及下面第三、四节的延伸部分）是我在写这篇文章时补的：用来说明"论文的思路接到真实工程上会长成什么样"。这两者我刻意分开标注，请不要把这几段当成论文的内容。 :::

三、导航精度与控制稳定性优化

为了让无人机在复杂环境中更灵活、精准地导航，研究集中在数据处理与算法优化两方面。

3.1 数据处理

论文关注传感器数据的准确性和实时性，使用 GPS、陀螺仪、加速度计等获取关键飞行数据，实时监测无人机的姿态、速度和加速度。

表 2 传感器类型与准确性要求

传感器	类型	准确性要求
全球定位系统	定位	高
陀螺仪	姿态	高
加速度计	加速度	高

在数据采集过程中优化传感器融合算法，确保各传感器数据的协同工作，提升整体数据准确性：

$$D_{\text{处理后}} = F_{\text{fusion}}\left(D_{\text{GPS}},\ D_{\text{陀螺仪}},\ D_{\text{加速度}}\right)$$

其中 $D_{\text{处理后}}$ 是经过处理后的数据，$F_{\text{fusion}}$ 是传感器融合算法，另外三项分别表示 GPS、陀螺仪和加速度计采集的原始数据。

:::note[公式里的 $F_{\text{fusion}}$ 是什么？] 这个式子是个占位符——它诚实地表示了"输出 = 融合函数（输入…）"这个结构，但没有说明 $F_{\text{fusion}}$ 具体是什么形式。

本文第一节的 EKF 就是 $F_{\text{fusion}}$ 的一个具体实现：**它同样接受 GPS、陀螺仪、加速度计三路输入，输出一个状态。**区别只是它还会多输出一份协方差（不确定性），并且是递归的（上一时刻的估计会参与下一时刻的计算）。

顺带说，$F_{\text{fusion}}$ 前面的"数据处理"其实还有一段很脏但绕不开的活：去畸变、时间戳对齐、坏点剔除、滑窗平滑。论文用一句"提升整体数据准确性"概括了，但真机上这几步的工作量往往比融合本身还大——传感器给的数据永远没有说明书上那么干净。 :::

3.2 算法优化：姿态控制用 MPC

算法优化聚焦姿态控制与航迹规划两个环节。

姿态控制采用模型预测控制（Model Predictive Control, MPC）——该算法通过预测未来一段时间内的飞行状态来优化控制指令，从而实现对无人机的高效控制：

$$U^{*} = \arg\min \sum_{k=0}^{N-1} L(x_k, u_k) + V(x_N)$$

其中 $U^{*}$ 是最优控制输入序列，$x$ 是飞行状态，$u$ 是控制指令，$N$ 是预测时域，$L$ 和 $V$ 分别是每一步的代价函数和终端代价函数。

:::tip[MPC 为什么适合无人机] MPC 的核心思想是"滚动优化"：每一时刻都根据当前状态预测未来 $N$ 步，解出一个最优控制序列，但只执行第一步，下一时刻重新预测、重新求解。

这对无人机特别契合——因为无人机的动力学约束（最大推力、最大角速度）可以显式写进优化问题，而不像 PID 那样只能靠调参事后弥补。代价是每一控制周期都要解一次优化问题，对算力有要求。 :::

3.3 延伸：把 MPC 写成二次规划

论文给出的 $\arg\min \sum L + V$ 是 MPC 的通用形式，但没说明怎么解。好消息是：只要系统是线性的、代价是二次的、约束是线性的，这个问题就能写成一个二次规划（QP）——而 QP 有成熟、快、且能保证找到全局最优的求解器。

具体怎么落地，步骤是固定的三步：

**第一步：把预测展开成矩阵形式。**设状态 $x_k \in \mathbb{R}^{n}$、控制量 $u_k \in \mathbb{R}^{m}$、离散动力学 $x_{k+1} = A x_k + B u_k$，把 $N$ 步全部叠成一个大向量 $X = [x_1; \dots; x_N]$、$U = [u_0; \dots; u_{N-1}]$，那么：

$$X = \underbrace{\begin{bmatrix} A \ A^2 \ \vdots \ A^N \end{bmatrix}}{\bar{A}} x_0 + \underbrace{\begin{bmatrix} B & 0 & \cdots & 0 \ AB & B & \cdots & 0 \ \vdots & & \ddots & \vdots \ A^{N-1}B & A^{N-2}B & \cdots & B \end{bmatrix}}{\bar{B}} U$$

**第二步：把代价函数代进去，得到标准二次型。**把 $X$ 的表达式代入二次代价，$x_0$ 就退化成一个常数项，剩下的只有 $U$：

$$J(U) = \tfrac{1}{2} U^{\top} H U + f^{\top} U + \text{const}, \qquad H = 2\left(\bar{B}^{\top}\bar{Q}\bar{B} + \bar{R}\right), \quad f = 2\bar{B}^{\top}\bar{Q}\left(\bar{A}x_0 - X_{\text{ref}}\right)$$

第三步：把约束写成线性不等式。这一步是重点，因为"避障"就是从这里进场的——不管是安全走廊还是位置上下界，最终都变成同一种形式：

$$H_j, p_k \le h_j$$

其中 $p_k$ 是第 $k$ 步预测位置，$(H_j, h_j)$ 描述一个半空间。一串这样的半空间求交，就是一个凸多面体，也就是所谓的安全飞行走廊（Safe Flight Corridor, SFC）。它的妙处在于：把"别撞墙"这个几何问题，翻译成了一条线性不等式——而线性不等式恰好是 QP 最擅长处理的东西。

:::warning[一个必须注意的坑：ESDF 约束是「非线性」的] 上一节说 ESDF 提供了距离和梯度，看起来很完美。但如果直接把 ESDF(p) ≥ 安全半径 当作约束写进 QP，这个 QP 就不再是标准的二次规划了——因为 ESDF 是格网上查表插值出来的，对 $p$ 而言是非线性、非凸的函数。

工程上有两条主流绕法：

先近似成凸多面体：用 A* 搜出一条几何路径，在路径周围构造一串互相重叠的凸多面体（就是 SFC），把非线性约束换成线性约束，QP 直接能解。代价是走廊构造这一步本身有开销，而且走廊一旦生成，优化器就只能在这个"笼子"里找解。
保留非线性、用 SQP / 实时迭代（RTI）线性化：在预测点处对 ESDF 做一阶展开，用线性化后的约束迭代求解。精度更高，但对初值敏感，也更难调试。

实际系统里方案 1 是主流，因为它把"安全性"的证明变简单了：只要轨迹在走廊内、走廊内没有障碍，那轨迹就一定安全。 :::

3.4 延伸：一段能跑的 MPC + 安全走廊

下面这段代码用一个横向双积分模型（状态 = 横向位置与速度）演示方案 1 的思路：把"每一步预测位置都在走廊内"写成两条线性不等式，然后用 scipy 解 QP。

场景设定是恒定侧风——一个没写进模型的外部扰动。它很有代表性，因为它刚好能看出代价函数和硬约束的分工：

# 依赖：Python 3.10+，numpy、scipy
# 演示：线性 MPC 写成 QP，用「安全走廊」线性不等式把侧风顶回去
import numpy as np
from scipy.optimize import minimize

DT, N = 0.1, 25                      # 控制周期 100 ms，预测 25 步（2.5 s）
A = np.array([[1.0, DT], [0.0, 1.0]])        # 状态 = [横向位置 y, 横向速度 vy]
B = np.array([[0.5 * DT ** 2], [DT]])        # 控制量 = 横向加速度 ay

Q  = np.diag([2.0, 8.0])             # 跟踪代价（中间步）
QN = np.diag([4.0, 12.0])            # 终端代价（最后一步权重大）
R  = np.array([[1.0]])               # 控制量代价，抑制抖动

A_MAX = 2.0                          # 最大横向加速度 m/s^2（执行器权限）
Y_MAX = 0.6                          # 安全走廊半宽 m —— 就是 H p <= h 的最简形式
WIND  = 0.8                          # 未建模侧风 m/s^2


def build_prediction(N, A, B):
    """把 x_{k+1} = A x_k + B u_k 展开成 X = Abar x0 + Bbar U（X 含 x1..xN）。"""
    nx, nu = A.shape[0], B.shape[1]
    Abar = np.zeros((N * nx, nx))
    Bbar = np.zeros((N * nx, N * nu))
    for i in range(N):
        Abar[i * nx:(i + 1) * nx, :] = np.linalg.matrix_power(A, i + 1)
        for j in range(i + 1):
            Bbar[i * nx:(i + 1) * nx, j * nu:(j + 1) * nu] = \
                np.linalg.matrix_power(A, i - j) @ B
    return Abar, Bbar


ABAR, BBAR = build_prediction(N, A, B)
QBAR = np.kron(np.eye(N), Q)
QBAR[-2:, -2:] = QN                              # 最后一步换成终端代价
RBAR = np.kron(np.eye(N), R)

# 把代价展开成标准二次型：J(U) = 0.5 U'H U + f'U + const
H_MAT = BBAR.T @ QBAR @ BBAR + RBAR
POS_ROWS = np.arange(0, N * 2, 2)                # X 里每个位置分量的行号


def mpc(x0, x_ref=np.zeros(2), y_max=Y_MAX):
    """解一步 QP：min J(U) s.t. |u_k| <= A_MAX, |y_k| <= y_max。只返回第一步。"""
    xr = np.tile(x_ref, N)
    f = 2 * BBAR.T @ QBAR @ (ABAR @ x0 - xr)
    obj = lambda U: U @ H_MAT @ U + f @ U
    jac = lambda U: 2 * H_MAT @ U + f

    # 安全走廊：把「每一步预测位置都在带内」写成两条线性不等式
    cons = [
        {"type": "ineq", "fun": lambda U: y_max - (ABAR @ x0 + BBAR @ U)[POS_ROWS],
         "jac": lambda U: -BBAR[POS_ROWS, :]},
        {"type": "ineq", "fun": lambda U: y_max + (ABAR @ x0 + BBAR @ U)[POS_ROWS],
         "jac": lambda U: BBAR[POS_ROWS, :]},
    ]

    res = minimize(obj, np.zeros(N), jac=jac, bounds=[(-A_MAX, A_MAX)] * N,
                   constraints=cons, method="SLSQP",
                   options={"maxiter": 300, "ftol": 1e-10})
    return res.x[0]


def simulate(y_max):
    """闭环跑 12 s；参考一直是 y=0，但物理对象上一直挂着恒定侧风。"""
    x = np.array([0.0, 0.0])
    ys, us = [], []
    for _ in range(120):
        u = mpc(x, y_max=y_max)
        # 注意 B 是列向量：用 flatten 让状态保持一维，否则下一步广播不上
        x = A @ x + B.flatten() * u + np.array([0.5 * WIND * DT ** 2, WIND * DT])
        ys.append(x[0]); us.append(u)
    return np.array(ys), np.array(us)


y_free, _ = simulate(y_max=1e6)                   # 对照：不加走廊约束
y_corr, u_corr = simulate(y_max=Y_MAX)            # 加走廊约束

print(f"参考横向位置 0.00 m，恒定侧风 {WIND} m/s^2")
print(f"  不加走廊约束：稳态偏移 {y_free[-1]:+.3f} m  <- 靠代价函数是拉不回来的")
print(f"  加安全走廊  ：稳态偏移 {y_corr[-1]:+.3f} m  <- 顶在 {Y_MAX} m 边界上")
overshoot = np.abs(y_corr).max() - Y_MAX
print(f"  全程最大偏移 {np.abs(y_corr).max():.3f} m，走廊半宽 {Y_MAX:.3f} m"
      f"（超出 {overshoot * 1000:+.0f} mm，属于 QP 求解器的数值容差）")
print(f"  控制量范围 {u_corr.min():+.2f} ~ {u_corr.max():+.2f} m/s^2"
      f"（执行器上限 ±{A_MAX}）")

实测输出：

参考横向位置 0.00 m，恒定侧风 0.8 m/s^2
  不加走廊约束：稳态偏移 +0.811 m  <- 靠代价函数是拉不回来的
  加安全走廊  ：稳态偏移 +0.604 m  <- 顶在 0.6 m 边界上
  全程最大偏移 0.604 m，走廊半宽 0.600 m（超出 +4 mm，属于 QP 求解器的数值容差）
  控制量范围 -1.79 ~ +0.00 m/s^2（执行器上限 ±2.0）

:::important[这段输出回答了「为什么光有代价函数不够」] 注意第一行和第二行的对比：同一套代价权重，加不加走廊约束，稳态偏移差了 0.2 m。

不加走廊：代价函数只是"倾向于"回到 $y=0$。侧风一直在推，代价函数又没有"绝对不许越界"这个语义，于是它稳定在一个新的平衡点 0.811 m 上——代价函数默许了越界。
加了走廊：约束把 $|y_k| \le 0.6$ 变成硬性的可行性条件，优化器被迫在边界上重新分配控制量，最终顶在 0.604 m 就不再往外走。

这就是软约束（代价）和硬约束（不等式）的本质差别：

	作用方式	越界时的表现	在这段代码里
代价函数	偏好	越界只是"代价大一点"，可以被别的好处抵消	稳态漂到 0.811 m
硬约束	可行性	越界的解根本不被允许，求不出就报不可行	停在 0.604 m
两者配合	代价决定"多快回到线上"，约束决定"绝不能出界"	——	控制量仅用掉 −1.79 / ±2.0

顺带说，控制量只用掉 −1.79，说明这次约束是"够得着"的——如果侧风强到超过执行器权限（比如侧风 2.5 m/s² 而上限是 2.0），那么无论怎么优化都守不住，QP 会变成不可行问题。真实的 MPC 必须专门处理这种不可行情况（比如松弛变量 + 优先级降级），否则求解器会返回一个数值上看起来很怪的结果。 :::

3.5 航迹规划

航迹规划采用基于地图信息的路径规划算法，确保导航过程中能避开障碍物、选择最优路径：

$$P_{\text{最优}} = \arg\min C(P)$$

其中 $P_{\text{最优}}$ 是最优路径，$C$ 是路径代价函数，考虑了路径长度和避障等因素。

<figure class="block-diagram" data-block="11-planning-stack"> <div class="block-scroll"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1430 248" width="1430" height="248" class="block-svg" role="img" aria-label="无人机规划与控制分层架构图：传感器数据一路做地图构建生成体素栅格与欧氏符号距离场，另一路做状态估计；地图经前端搜索得到参考路径并构造安全飞行走廊，与状态估计一起送入模型预测控制求解，输出再经微分平坦转换为角速度和油门指令"> <g transform="translate(18,48)"> <g class="blk-links"> <path d="M 267.6 0.0 L 267.6 -15.0 Q 267.6 -20.0 272.6 -20.0 L 1080.8 -20.0 Q 1085.8 -20.0 1085.8 -15.0 L 1085.8 30.8" fill="none" stroke="#f59e0b" stroke-opacity="0.62" stroke-width="1.3"/> <path d="M 1085.8 36.0 L 1083.1 30.8 L 1088.5 30.8 Z" fill="#f59e0b"/> <text x="676.7" y="-26.0" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="11.5" fill="currentColor" fill-opacity="0.66">当前位姿与速度</text> <path d="M 142.4 65.9 L 165.8 65.9 L 165.8 30.0 L 191.2 30.0" fill="none" stroke="currentColor" stroke-opacity="0.45" stroke-width="1.3"/> <path d="M 196.4 30.0 L 191.2 27.3 L 191.2 32.7 Z" fill="currentColor"/> <path d="M 142.4 65.9 L 185.9 65.9 L 185.9 101.9 L 213.9 101.9" fill="none" stroke="currentColor" stroke-opacity="0.45" stroke-width="1.3"/> <path d="M 219.1 101.9 L 213.9 99.2 L 213.9 104.6 Z" fill="currentColor"/> <path d="M 316.1 101.9 L 354.5 101.9 L 354.5 65.9 L 387.7 65.9" fill="none" stroke="currentColor" stroke-opacity="0.45" stroke-width="1.3"/> <path d="M 392.9 65.9 L 387.7 63.2 L 387.7 68.6 Z" fill="currentColor"/> <line x1="581.9" y1="65.9" x2="630.6" y2="65.9" stroke="currentColor" stroke-opacity="0.45" stroke-width="1.3"/> <path d="M 635.9 65.9 L 630.6 63.2 L 630.6 68.6 Z" fill="currentColor"/> <line x1="749.0" y1="65.9" x2="797.8" y2="65.9" stroke="currentColor" stroke-opacity="0.45" stroke-width="1.3"/> <path d="M 803.0 65.9 L 797.8 63.2 L 797.8 68.6 Z" fill="currentColor"/> <line x1="935.6" y1="65.9" x2="984.4" y2="65.9" stroke="currentColor" stroke-opacity="0.45" stroke-width="1.3"/> <path d="M 989.6 65.9 L 984.4 63.2 L 984.4 68.6 Z" fill="currentColor"/> <line x1="1182.1" y1="65.9" x2="1230.9" y2="65.9" stroke="currentColor" stroke-opacity="0.45" stroke-width="1.3"/> <path d="M 1236.1 65.9 L 1230.9 63.2 L 1230.9 68.6 Z" fill="currentColor"/> </g> <g class="blk-boxes"> <g class="blk-box" data-t="三路传感器"> <rect x="0.0" y="36.0" width="142.4" height="59.9" rx="10" fill="currentColor" fill-opacity="0.045" stroke="currentColor" stroke-opacity="0.18" stroke-width="1.2"/> <text x="71.2" y="57.6" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="14.5" font-weight="600" fill="currentColor">三路传感器</text> <text x="71.2" y="81.2" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="11.5" fill="currentColor" fill-opacity="0.58">视觉 · 激光雷达 · IMU</text> </g> <g class="blk-box" data-t="状态估计"> <rect x="196.4" y="0.0" width="142.4" height="59.9" rx="10" fill="#8b5cf6" fill-opacity="0.14" stroke="#8b5cf6" stroke-opacity="0.75" stroke-width="1.2"/> <text x="267.6" y="21.6" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="14.5" font-weight="600" fill="currentColor">状态估计</text> <text x="267.6" y="45.2" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="11.5" fill="currentColor" fill-opacity="0.58">EKF 融合出位姿与速度</text> </g> <g class="blk-box" data-t="地图构建"> <rect x="219.1" y="71.9" width="97.0" height="59.9" rx="10" fill="currentColor" fill-opacity="0.045" stroke="currentColor" stroke-opacity="0.18" stroke-width="1.2"/> <text x="267.6" y="93.5" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="14.5" font-weight="600" fill="currentColor">地图构建</text> <text x="267.6" y="117.1" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="11.5" fill="currentColor" fill-opacity="0.58">体素占据栅格</text> </g> <g class="blk-box" data-t="欧氏符号距离场 ESDF"> <rect x="392.9" y="36.0" width="189.0" height="59.9" rx="10" fill="currentColor" fill-opacity="0.045" stroke="currentColor" stroke-opacity="0.18" stroke-width="1.2"/> <text x="487.4" y="57.6" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="14.5" font-weight="600" fill="currentColor">欧氏符号距离场 ESDF</text> <text x="487.4" y="81.2" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="11.5" fill="currentColor" fill-opacity="0.58">每个空闲体素到最近障碍的距离</text> </g> <g class="blk-box" data-t="前端搜索"> <rect x="635.9" y="36.0" width="113.1" height="59.9" rx="10" fill="currentColor" fill-opacity="0.045" stroke="currentColor" stroke-opacity="0.18" stroke-width="1.2"/> <text x="692.4" y="57.6" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="14.5" font-weight="600" fill="currentColor">前端搜索</text> <text x="692.4" y="81.2" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="11.5" fill="currentColor" fill-opacity="0.58">A* 生成参考路径</text> </g> <g class="blk-box" data-t="安全飞行走廊"> <rect x="803.0" y="36.0" width="132.7" height="59.9" rx="10" fill="currentColor" fill-opacity="0.045" stroke="currentColor" stroke-opacity="0.18" stroke-width="1.2"/> <text x="869.3" y="57.6" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="14.5" font-weight="600" fill="currentColor">安全飞行走廊</text> <text x="869.3" y="81.2" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="11.5" fill="currentColor" fill-opacity="0.58">一串凸多面体 Hp ≤ h</text> </g> <g class="blk-box" data-t="MPC 二次规划"> <rect x="989.6" y="36.0" width="192.4" height="59.9" rx="10" fill="#f59e0b" fill-opacity="0.14" stroke="#f59e0b" stroke-opacity="0.75" stroke-width="1.2"/> <text x="1085.8" y="57.6" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="14.5" font-weight="600" fill="currentColor">MPC 二次规划</text> <text x="1085.8" y="81.2" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="11.5" fill="currentColor" fill-opacity="0.58">预测 N 步 · 含动力学与输入约束</text> </g> <g class="blk-box" data-t="微分平坦"> <rect x="1236.1" y="36.0" width="158.0" height="59.9" rx="10" fill="currentColor" fill-opacity="0.045" stroke="currentColor" stroke-opacity="0.18" stroke-width="1.2"/> <text x="1315.0" y="57.6" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="14.5" font-weight="600" fill="currentColor">微分平坦</text> <text x="1315.0" y="81.2" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="11.5" fill="currentColor" fill-opacity="0.58">加加速度 → 角速度 + 油门</text> </g> </g> <g class="blk-feedback"> <path d="M 1315.0 95.9 L 1315.0 159.8 Q 1315.0 165.8 1309.0 165.8 L 77.2 165.8 Q 71.2 165.8 71.2 159.8 L 71.2 101.1" fill="none" stroke="#8b5cf6" stroke-opacity="0.6" stroke-width="1.3" stroke-dasharray="5 3"/> <path d="M 71.2 95.9 L 68.5 101.1 L 73.9 101.1 Z" fill="#8b5cf6"/> <text x="693.1" y="158.8" text-anchor="middle" font-family="Roboto,sans-serif,ui-sans-serif,system-ui,sans-serif,'Apple Color Emoji','Segoe UI Emoji',Segoe UI Symbol,'Noto Color Emoji'" font-size="11.5" fill="currentColor" fill-opacity="0.66">闭环：飞过之后重新观测，地图与状态一起更新</text> </g> </g> </svg></div> <figcaption>图 3 · 规划与控制的分层架构：地图负责「哪里不能去」，优化负责「怎么去最省」，两者通过安全走廊这条线性约束接口对接</figcaption> </figure>

:::note[代价函数 $C(P)$ 里到底装了什么] 论文只说了"考虑路径长度和避障"。实际工程里，$C$ 通常是一个加权和，每一项对应一个飞行品质要求：

$$C(P) = \underbrace{w_1 \int \lVert \dot{p} \rVert , dt}{\text{路径长度}} + \underbrace{w_2 \int \lVert \ddot{p} \rVert^2 dt}{\text{平滑度（省电、好跟踪）}} + \underbrace{w_3 \int \lVert p^{(3)} \rVert^2 dt}{\text{加加速度（乘客/相机舒适度）}} + \underbrace{w_4 \cdot \text{越界惩罚}}{}$$

权重的取法直接决定飞出来的风格：$w_1$ 大就飞直线、贴着障碍抄近路；$w_3$ 大就飞得很"温吞"但视频画面稳。所谓"算法调参"，很多时候就是在调这几个 $w$。

另一条工程上的路数是分层解耦：前端用 A/JPS* 在栅格上搜一条只考虑"能不能过"的几何路径（快，但不平滑、动力学上不可执行）；后端再用轨迹优化把这条折线变成满足动力学约束的平滑轨迹。上图正是这个分层结构。 :::

3.6 论文给出的实验数据

通过数据处理与算法优化的综合作用，无人机的导航精度与控制稳定性得到提升。论文给出的实际飞行测试参数变化：

表 3 优化下参数变化

测试参数	优化前
导航误差	5 米
姿态稳定性	较差
控制响应时间	100 毫秒

:::caution[关于这张表，有些话必须说清楚] 按论文原文，表 3 记录的是优化前的基线数据（导航误差 5 米、姿态稳定性较差、控制响应时间 100 毫秒）。原文在表述上提到"从表 3 可以看出优化下无人机的导航误差大幅减小、姿态稳定性显著提升、控制响应时间也有所缩短"。

这里存在一处数据与论述的不一致：表里只有"优化前"一列，却要论证优化后的改善。

我更倾向于把它理解为一组基线参照值——它给出了优化前的水平，作为后续改进的对照。但如果要严谨地支撑"大幅减小、显著提升"这类结论，至少还需要补上：

优化后的对照列（导航误差降到多少米、响应时间缩短到多少毫秒）
测试样本量（飞了几架次？单次还是多次平均？）
误差指标的定义（导航误差是相对真值还是相对规划轨迹？怎么测的？）

这是这篇论文在实验呈现上最明显的可完善之处。我在下面把它改写成一张能真正说明问题的表：

测试参数	优化前（基线）	优化后	相对变化	统计口径
导航误差	5 米	待补	待补	建议：相对 RTK 真值的 RMSE
姿态稳定性	较差	待补	待补	建议：姿态角速度的 RMS 或超调量
控制响应时间	100 毫秒	待补	待补	建议：阶跃指令的上升时间 / 相位滞后
:::

不过整体上，通过在数据处理和算法优化上的投入，论文认为在提高无人机飞行性能方面取得了明显成果。这个方法不仅在理论上有支持，在实际测试中也得到了令人满意的结果。

这对无人机在复杂环境中执行任务很有意义——比如城市建筑巡查、紧急救援这类场景中，高导航精度和控制稳定性是任务成功的关键因素。

四、把这篇论文拆成一份可执行的清单

论文的结论是方向性的，落到工程上需要的是"下一步先做什么"。如果让我现在重新实现一遍这套系统，我会按下面的顺序推——每一项都是前一项能跑起来的前提：

[x] 明确坐标系约定（惯导 ENU、机体 FLU），在接口处显式转换
[ ] 打通各路传感器的时间戳与统一时基
[ ] 标定 IMU 的零偏与尺度因子，做静止初始化
[ ] 标定相机/雷达 → 机体的外参（旋转 + 平移）
[ ] 用 EKF 跑通"IMU 高频 + 位置低频"的融合，验证误差不随时间发散
[ ] 实现延迟补偿与输出预测，让控制器拿到当前时刻状态
[ ] 把点云投影成体素占据栅格，接通建图
[ ] 在栅格上算出 ESDF，验证距离与梯度的符号和量级
[ ] 前端 A* 搜出几何路径，验证能绕开凹形障碍（这是势场法的死穴）
[ ] 用路径周围的凸多面体构造安全飞行走廊
[ ] 把 MPC 写成 QP，先只加输入约束，验证跟踪
[ ] 再把走廊约束加进去，验证约束生效时控制量未饱和
[ ] 补上不可行情况的处理（松弛变量 + 降级策略）
[ ] 加故障降级：单传感器失效时明确走哪条备选路径

:::tip[GitHub 上的提醒写法] 在 issue 或 PR 里追进度时，这套任务列表可以直接用 GitHub 的原生语法：

> [!TIP]
> 任务列表在 GitHub 上会渲染成可勾选的复选框，改 `[ ]` 为 `[x]` 就等于提交进度。

- [ ] 待办
- [x] 已完成

:::

关于"降级"这一条，值得单独强调：论文的出发点是"单个传感器都不够可靠"，但融合的同时也带来了新的失效模式——如果激光雷达被雨雾/强光干扰，或者 GPS 进隧道丢星，系统必须有明确的降级路径，而不是简单地"少一路输入继续算"。成熟的飞控会为每种组合定义模式（哪种最小传感器组合还能飞、丢失哪一路后精度会掉到什么程度），并且在数据里如实标注能力降级。

这在工程上有个很实际的判据：一个融合系统能不能上线，不取决于它正常时有多准，而取决于它"缺一路"时能不能安全退出。

结论与展望

本文通过对基于传感器融合的自主避障无人机导航与控制算法的研究，取得了一系列成果：新算法通过充分利用多种传感器的信息，使无人机能够在复杂环境中避障并实现高精度导航，为无人机技术的发展提供了新的思路和方法，有望在军事、民用、科研等领域发挥作用。

未来的工作方向是进一步优化算法，推动无人机技术的不断创新与发展。如果我来补这份展望，会具体加上三条：

从模块化走向一体化：把"感知 → 建图 → 规划 → 控制"串得更紧，比如让 MPC 直接吃 ESDF 的梯度（而不是先把约束近似成凸多面体），减少中间环节的信息损失
让不确定性进入决策：现在的避障用的是"点估计"（认为估计出来的位置就是真值）；更稳的做法是把协方差也传下去，在估计得不准的地方主动留更大余量
把安全性变成可验证的属性：控制障碍函数（CBF）这类方法可以把"绝不进入障碍"写成前向不变性的数学条件，从而在理论上给出保证，而不只是靠大量仿真试验

参考文献

张红蕾, 盛志超, 叶林等. 基于多传感器融合的无人机自主避障方法[J/OL]. 激光杂志, 1-7[2024-01-23]
陈昊. 基于多传感器信息融合的无人机自主追击与避障研究[D]. 哈尔滨工程大学, 2021.
何守印. 基于多传感器融合的无人机自主避障研究[D]. 北京理工大学, 2016.
刘泽琳, 张袁元, 杨旺嗣等. 基于 SLAM 的自主避障物流无人机系统设计[J]. 机电工程技术, 2023, 52(07): 60-63+102.

延伸阅读（本文补充，非论文原文引文）

PX4 Autopilot. Using the ECL EKF（EKF2 的延迟融合时轴、24 状态向量与延迟补偿参数）[EB/OL]. https://docs.px4.io/main/en/advanced_config/tuning_the_ecl_ekf
Oleynikova H, Taylor Z, Fehr M, et al. Voxblox: Incremental 3D Euclidean Signed Distance Fields for On-Board MAV Planning[C]. IROS, 2017.
Zhou B, Gao F, Wang L, et al. Robust and Efficient Quadrotor Trajectory Generation for Fast Autonomous Flight[J]. IEEE RA-L, 2019.
Stellato B, Banjac G, Goulart P, et al. OSQP: An Operator Splitting Solver for Quadratic Programs[J]. Mathematical Programming Computation, 2020.

一点回顾

这篇文章是我们团队自主避障无人机项目的理论总结，也是我第一次完整走一遍"提出问题 → 梳理技术路线 → 用公式建模 → 给出优化方案 → 成文投稿"的学术流程。

回头看，这篇论文里最让我受益的不是某个具体公式，而是"融合"这个思维方式本身：面对一对相互矛盾的约束（视觉怕光、雷达缺语义、IMU 会飘），最优解往往不是找到某个"完美的传感器"，而是让它们互相兜底。这个思路在我后来做别的东西时反复被验证——系统的鲁棒性来自冗余的异构性，而不是单点的极致。

而这次重读论文最大的收获，是发现当年被"一句话带过"的地方，恰恰是工程上最难的部分。"时间同步""延迟补偿""外参标定""约束不可行怎么办"——这些在论文里可能只占一行，在真机上却要占掉大半的调试时间。

📌 有一件事不妨直说：论文写得好不好，和系统能不能飞，是两套完全不同的评价标准。论文要的是逻辑自洽、结论清晰；系统要的是在传感器脏数据、时间不同步、约束临时不可行的糟糕情况下，还能安全地停下来。这两者都需要练，但练法不一样。

论文原版扫描件：

::github{repo="RERELEGEND/uav-sensor-fusion-demos"}

热热的博客

MAYA2.0：全离线物联网 Agent

一、它由哪些部分组成

二、10 TOPS 的账：为什么是 1.5B

三、从一句话到设备动作

四、意图路由：能不用 LLM 就不用 LLM

踩坑：MEMORY_WRITE 太容易误判

五、长期记忆：让系统长大，但不许幻觉

六、隐私分级与 ROOT 模式

七、五模式对照：1.5B 的真实水平

模式①：无规则的裸模型

模式②：只加 Prompt 规则

模式③：只加输出清理

模式④：完整规则链

模式⑤：Prompt + 清理

实验结论

八、四层防御：那副外骨骼长什么样

第 1 层：Prompt 约束——把身份写成元数据

第 2 层：Stop Tokens——让它根本吐不出来

第 3 层：后处理清理——320 多行的兜底

第 4 层：意图分流——不给它越权的机会

九、三个 bug 的修法

bug 1：重复 15 次，因为分割符只有句号

bug 2：清理过度，答案被清成了空

bug 3：身份混淆，「我是热热」和「你叫什么名字」

这套流程本身也值得说一句

十、交付状态

软件层：已完成

硬件层：初步落地

结题验收清单

交付资产

一条带走的结论：规则不是越多越好

可以延伸的方向

写在最后

MAYA1.0：物联网管家桌面机器人

它是什么

一条完整的交互闭环

它内部其实是一台状态机

系统架构：一颗 STM32，加一块树莓派

硬件选型

（1）STM32F103C8T6 最小系统板——主控

（2）ASR-PRO 离线语音模块——耳朵和嘴

（3）OpenMV 机器视觉模块——眼睛

（4）ESP8266 WiFi 通讯模块——连上世界

（5）树莓派 2B + 3.5 寸 LCD——脸

（6）SG90 舵机与直流电机——手和脚

（7）机械结构与外观——3D 打印外壳 + 积木骨架

一张自己组的局域网：四颗 ESP8266

代码分析

主循环：心跳 + 事件队列 + 状态机

环境采集：DHT11 时序 + LDR 双重滤波

语音命令解析：环形缓冲 + 命令表

视觉检测：OpenMV 端的人脸 + 亮度

网络通信：ESP8266 从控端

显示驱动：树莓派端的动画播放器

编译与烧录

联调与实验结果

产品化：成本、市场与代价

写在研发过程中

小结

MAYA 计划

第二代：MAYA3.0（独立项目）

三子棋人机对弈机器人：2024 全国大学生电子设计竞赛 E 题实录

一、题目：三子棋游戏装置（E 题）

二、评分点：题目真正难在哪

三、赛题「说明」里的隐藏约束

四、我们的方案

4.1 棋盘旋转：一个必须先解决的坐标问题

4.2 博弈决策：三子棋能穷举，所以不要用启发式

4.3 「棋子被挪」：状态差分，不是重新识别

五、一次落子的完整流程

六、我在队里做的事

七、结果

八、工程文件与 3D 模型

九、回过头看

十、参考与延伸

论文登刊《中国科技人才》：基于传感器融合的自主避障无人机导航与控制算法研究

论文信息

研究背景

一、传感器融合原理

踩坑：`MEMORY_WRITE` 太容易误判