做一个有屏幕的语音桌面助手：状态、按键、对话和故障反馈

python tools/verify_project.py
python tools/project.py configure
python tools/project.py build
python tools/project.py manifest

python tools/project.py flash --port YOUR_UART_BRIDGE_PORT
python tools/project.py monitor --port YOUR_UART_BRIDGE_PORT

python tests/run_panel_host.py --output /tmp/a10-panel-contract
python tests/run_mcp_host.py --output /tmp/a10-mcp-contract
python tests/check_ui_serialization.py --output /tmp/a10-ui-contract

// ---- firmware/main/lab_desk_policy.h ----
// SPDX-License-Identifier: MIT
#pragma once
#include <cstdint>
namespace a10 {
enum class Phase { BOOT, CONFIG, ACTIVATE, CONNECT, READY, LISTEN, PLAY, UPDATE, TEST, FATAL };
struct Frame {
    const char* status;
    const char* hint;
    bool suppress_chat;
};
class Panel {
public:
    void network(bool up) {
        network_known_ = true;
        network_up_ = up;
        if (!up)
            awaiting_ = false;
    }
    void backend_error() {
        backend_error_ = true;
        awaiting_ = false;
    }
    void backend_connected() { backend_error_ = false; }
    void tool_error() { tool_error_ = true; }
    void tool_success() { tool_error_ = false; }
    void gpio_fault() { gpio_fault_ = true; }
    // A UI acknowledgement, not a network cancel or hardware repair.
    void acknowledge() {
        tool_error_ = false;
        if (network_up_)
            backend_error_ = false;
        awaiting_ = false;
    }
    void stop_listening(uint64_t now) {
        awaiting_ = true;
        wait_at_ = now;
    }
    void tick(uint64_t now) {
        if (awaiting_ && (now < wait_at_ || now - wait_at_ >= 60000000ULL))
            backend_error();
    }
    Frame frame(Phase phase, bool playback_busy, uint64_t now) {
        if (phase == Phase::LISTEN || phase == Phase::PLAY || playback_busy)
            awaiting_ = false;
        tick(now);
        if (gpio_fault_)
            return {"GPIO ERR", "Repair + RESET", true};
        if (phase == Phase::FATAL)
            return {"SYS ERR", "Check UART; RESET", true};
        if (phase == Phase::CONFIG)
            return {"CONFIG", "Use setup WiFi", true};
        if (network_known_ && !network_up_)
            return {"WIFI ERR", "Check AP / USB", true};
        if (backend_error_)
            return {"BACK ERR", "Mute; retry", true};
        if (tool_error_)
            return {"TOOL ERR", "Check args/id", true};
        if (phase == Phase::ACTIVATE)
            return {"ACTIVATE", "Check UART", true};
        if (phase == Phase::CONNECT)
            return {"CONNECT", "Opening link", true};
        if (phase == Phase::UPDATE)
            return {"UPDATE", "Keep power", true};
        if (phase == Phase::TEST)
            return {"TEST", "Local loopback", true};
        if (phase == Phase::PLAY || playback_busy)
            return {"PLAY", "", false};
        if (phase == Phase::LISTEN)
            return {"LISTEN", "", false};
        if (awaiting_)
            return {"THINK", "Waiting server", false};
        if (phase == Phase::READY)
            return {"READY", "Hold GPIO47", false};
        return {"BOOT", "Check UART", true};
    }

private:
    uint64_t wait_at_ = 0;
    bool awaiting_ = false, network_known_ = false, network_up_ = false;
    bool backend_error_ = false, tool_error_ = false, gpio_fault_ = false;
};
}  // namespace a10

// ---- firmware/main/lab_desk_runtime.h ----
// SPDX-License-Identifier: MIT
#pragma once
#include <esp_log.h>
#include <esp_timer.h>
#include <cstring>
#include "device_state.h"
#include "lab_desk_policy.h"
#if !CONFIG_BOARD_TYPE_BREAD_COMPACT_WIFI || !CONFIG_OLED_SSD1306_128X32 || \
    CONFIG_USE_AUDIO_PROCESSOR || !CONFIG_WAKE_WORD_DISABLED
#error "A10 scope: bread-compact-wifi128x32 raw/manual configuration only"
#endif
namespace a10 {
// All model mutation/rendering is owned by Application main loop. Register these
// callbacks during Board construction, before that loop starts.
inline Panel& panel() {
    static Panel p;
    return p;
}
inline uint64_t now() { return static_cast<uint64_t>(esp_timer_get_time()); }
using Present = void (*)(const Frame&);
using FaultReader = bool (*)();
inline Present& presenter() {
    static Present p = nullptr;
    return p;
}
inline FaultReader& fault_reader() {
    static FaultReader p = nullptr;
    return p;
}
inline Phase phase(DeviceState s) {
    switch (s) {
        case kDeviceStateIdle:
            return Phase::READY;
        case kDeviceStateWifiConfiguring:
            return Phase::CONFIG;
        case kDeviceStateActivating:
            return Phase::ACTIVATE;
        case kDeviceStateConnecting:
            return Phase::CONNECT;
        case kDeviceStateListening:
            return Phase::LISTEN;
        case kDeviceStateSpeaking:
            return Phase::PLAY;
        case kDeviceStateFatalError:
            return Phase::FATAL;
        case kDeviceStateAudioTesting:
            return Phase::TEST;
        case kDeviceStateUpgrading:
            return Phase::UPDATE;
        default:
            return Phase::BOOT;
    }
}
inline void render(DeviceState s, bool playback_busy) {
    if (fault_reader() && fault_reader()())
        panel().gpio_fault();
    const auto f = panel().frame(phase(s), playback_busy, now());
    static const char* last = nullptr;
    if (!last || std::strcmp(last, f.status)) {
        ESP_LOGI("a10", "A10v1 status=%s oled_adapter=%d; queue/protocol/digital evidence only",
                 f.status, presenter() != nullptr);
        last = f.status;
    }
    if (presenter())
        presenter()(f);
}
}  // namespace a10

// ---- firmware/main/lab_desk_display.h ----
// SPDX-License-Identifier: MIT
#pragma once
#include <cstring>
#include <mutex>
#include "display/oled_display.h"
#include "lab_desk_runtime.h"
namespace a10 {
class DeskDisplay : public OledDisplay {
public:
    using OledDisplay::OledDisplay;
    void SetupUI() override {
        std::lock_guard<std::mutex> owner(ui_mutex_);
        OledDisplay::SetupUI();
        DisplayLockGuard lock(this);
        // Reserve the entire96px right column for a short ASCII state label.
        for (auto* p : {network_label_, mute_label_, battery_label_})
            if (p)
                lv_obj_add_flag(p, LV_OBJ_FLAG_HIDDEN);
        if (status_label_) {
            lv_obj_set_width(status_label_, 94);
            lv_label_set_long_mode(status_label_, LV_LABEL_LONG_CLIP);
        }
    }
    void SetStatus(const char* text) override {
        std::lock_guard<std::mutex> owner(ui_mutex_);
        if (!active_)
            OledDisplay::SetStatus(text);
    }
    void ShowNotification(const char* text, int ms = 3000) override {
        {
            std::lock_guard<std::mutex> owner(ui_mutex_);
            if (!active_) {
                OledDisplay::ShowNotification(text, ms);
                return;
            }
        }
        ESP_LOGI("a10", "upstream notification retained in UART: %s", text);
    }
    void ShowNotification(const std::string& text, int ms = 3000) override {
        ShowNotification(text.c_str(), ms);
    }
    void SetChatMessage(const char* role, const char* text) override {
        std::lock_guard<std::mutex> owner(ui_mutex_);
        if (!suppress_)
            OledDisplay::SetChatMessage(role, text);
    }
    void present(const Frame& f) {
        std::lock_guard<std::mutex> owner(ui_mutex_);
        if (!IsSetupUICalled())
            return;
        if (!active_) {
            active_ = true;
            if (notification_timer_)
                esp_timer_stop(notification_timer_);
        }
        suppress_ = f.suppress_chat;
        if (last_status_ != f.status) {
            OledDisplay::SetStatus(f.status);
            last_status_ = f.status;
        }
        if (f.suppress_chat || std::strcmp(f.status, "READY") == 0) {
            if (last_hint_ != f.hint) {
                OledDisplay::SetChatMessage("system", f.hint);
                last_hint_ = f.hint;
            }
        } else
            last_hint_.clear();
    }

private:
    // Serialize gate checks with their qualified base UI call, including the
    // first activation and late chat concurrent with an error. Atomic flags
    // alone leave a check/use window and can hide a persistent error.
    std::mutex ui_mutex_;
    bool active_ = false, suppress_ = true;
    std::string last_status_, last_hint_;
};
inline DeskDisplay*& display() {
    static DeskDisplay* p = nullptr;
    return p;
}
inline void present_to_oled(const Frame& f) {
    if (display())
        display()->present(f);
}
}  // namespace a10

// ---- firmware/main/boards/bread-compact-wifi/compact_wifi_board.cc ----
#include <esp_random.h>
#include "application.h"
#include "assets/lang_config.h"
#include "audited_led_gpio.h"
#include "audited_led_mcp.h"
#include "button.h"
#include "codecs/no_audio_codec.h"
#include "config.h"
#include "display/oled_display.h"
#include "lab_desk_display.h"
#include "led/single_led.h"
#include "mcp_server.h"
#include "system_reset.h"
#include "wifi_board.h"

#include <esp_log.h>
#include <driver/i2c_master.h>
#include <esp_lcd_panel_ops.h>
#include <esp_lcd_panel_vendor.h>

#ifdef SH1106
#include <esp_lcd_panel_sh1106.h>
#endif

#define TAG "CompactWifiBoard"

class CompactWifiBoard : public WifiBoard {
private:
    i2c_master_bus_handle_t display_i2c_bus_;
    esp_lcd_panel_io_handle_t panel_io_ = nullptr;
    esp_lcd_panel_handle_t panel_ = nullptr;
    Display* display_ = nullptr;
    Button boot_button_;
    Button touch_button_;
    Button volume_up_button_;
    Button volume_down_button_;

    void InitializeDisplayI2c() {
        i2c_master_bus_config_t bus_config = {
            .i2c_port = (i2c_port_t)0,
            .sda_io_num = DISPLAY_SDA_PIN,
            .scl_io_num = DISPLAY_SCL_PIN,
            .clk_source = I2C_CLK_SRC_DEFAULT,
            .glitch_ignore_cnt = 7,
            .intr_priority = 0,
            .trans_queue_depth = 0,
            .flags = {
                .enable_internal_pullup = 1,
            },
        };
        ESP_ERROR_CHECK(i2c_new_master_bus(&bus_config, &display_i2c_bus_));
    }

    void InitializeSsd1306Display() {
        // SSD1306 config
        esp_lcd_panel_io_i2c_config_t io_config = {
            .dev_addr = 0x3C,
            .on_color_trans_done = nullptr,
            .user_ctx = nullptr,
            .control_phase_bytes = 1,
            .dc_bit_offset = 6,
            .lcd_cmd_bits = 8,
            .lcd_param_bits = 8,
            .flags =
                {
                    .dc_low_on_data = 0,
                    .disable_control_phase = 0,
                },
            .scl_speed_hz = 400 * 1000,
        };

        ESP_ERROR_CHECK(esp_lcd_new_panel_io_i2c(display_i2c_bus_, &io_config, &panel_io_));

        ESP_LOGI(TAG, "Install SSD1306 driver");
        esp_lcd_panel_dev_config_t panel_config = {};
        panel_config.reset_gpio_num = GPIO_NUM_NC;
        panel_config.bits_per_pixel = 1;

        esp_lcd_panel_ssd1306_config_t ssd1306_config = {
            .height = static_cast<uint8_t>(DISPLAY_HEIGHT),
        };
        panel_config.vendor_config = &ssd1306_config;

#ifdef SH1106
        ESP_ERROR_CHECK(esp_lcd_new_panel_sh1106(panel_io_, &panel_config, &panel_));
#else
        ESP_ERROR_CHECK(esp_lcd_new_panel_ssd1306(panel_io_, &panel_config, &panel_));
#endif
        ESP_LOGI(TAG, "SSD1306 driver installed");

        // Reset the display
        ESP_ERROR_CHECK(esp_lcd_panel_reset(panel_));
        if (esp_lcd_panel_init(panel_) != ESP_OK) {
            ESP_LOGE(TAG, "Failed to initialize display");
            display_ = new NoDisplay();
            return;
        }
        ESP_ERROR_CHECK(esp_lcd_panel_invert_color(panel_, false));

        // Set the display to on
        ESP_LOGI(TAG, "Turning display on");
        ESP_ERROR_CHECK(esp_lcd_panel_disp_on_off(panel_, true));

        a10::display() = new a10::DeskDisplay(panel_io_, panel_, DISPLAY_WIDTH, DISPLAY_HEIGHT,
                                              DISPLAY_MIRROR_X, DISPLAY_MIRROR_Y);
        display_ = a10::display();
        a10::presenter() = &a10::present_to_oled;
    }

    void InitializeButtons() {
        boot_button_.OnClick([this]() {
            auto& app = Application::GetInstance();
            if (app.GetDeviceState() == kDeviceStateStarting) {
                EnterWifiConfigMode();
                return;
            }
            app.ToggleChatState();
        });
        touch_button_.OnPressDown([this]() {
            Application::GetInstance().StartListening();
        });
        touch_button_.OnPressUp([this]() {
            Application::GetInstance().StopListening();
        });

        volume_up_button_.OnClick([this]() {
            auto codec = GetAudioCodec();
            auto volume = codec->output_volume() + 10;
            if (volume > 100) {
                volume = 100;
            }
            codec->SetOutputVolume(volume);
            GetDisplay()->ShowNotification(Lang::Strings::VOLUME + std::to_string(volume));
        });

        volume_up_button_.OnLongPress([this]() {
            GetAudioCodec()->SetOutputVolume(100);
            GetDisplay()->ShowNotification(Lang::Strings::MAX_VOLUME);
        });

        volume_down_button_.OnClick([this]() {
            auto codec = GetAudioCodec();
            auto volume = codec->output_volume() - 10;
            if (volume < 0) {
                volume = 0;
            }
            codec->SetOutputVolume(volume);
            GetDisplay()->ShowNotification(Lang::Strings::VOLUME + std::to_string(volume));
        });

        volume_down_button_.OnLongPress([this]() {
            GetAudioCodec()->SetOutputVolume(0);
            GetDisplay()->ShowNotification(Lang::Strings::MUTED);
            Application::GetInstance().Schedule([]() { a10::panel().acknowledge(); });
        });
    }

    // 物联网初始化，逐步迁移到 MCP 协议
    void InitializeTools() {
        static a08::GpioLed led_io(LAMP_GPIO);
        static a08::LedPolicy<a08::GpioLed> led(led_io, esp_random());
        a10::fault_reader() = +[]() { return led.snapshot().fault; };
        static const bool registered = []() {
            a08::register_tools(McpServer::GetInstance(), led);
            return true;
        }();
        (void)registered;
    }

public:
    CompactWifiBoard() :
        boot_button_(BOOT_BUTTON_GPIO),
        touch_button_(TOUCH_BUTTON_GPIO),
        volume_up_button_(VOLUME_UP_BUTTON_GPIO),
        volume_down_button_(VOLUME_DOWN_BUTTON_GPIO) {
        InitializeDisplayI2c();
        InitializeSsd1306Display();
        InitializeButtons();
        InitializeTools();
    }

    virtual Led* GetLed() override {
        static SingleLed led(BUILTIN_LED_GPIO);
        return &led;
    }

    virtual AudioCodec* GetAudioCodec() override {
#ifdef AUDIO_I2S_METHOD_SIMPLEX
        static NoAudioCodecSimplex audio_codec(AUDIO_INPUT_SAMPLE_RATE, AUDIO_OUTPUT_SAMPLE_RATE,
            AUDIO_I2S_SPK_GPIO_BCLK, AUDIO_I2S_SPK_GPIO_LRCK, AUDIO_I2S_SPK_GPIO_DOUT, AUDIO_I2S_MIC_GPIO_SCK, AUDIO_I2S_MIC_GPIO_WS, AUDIO_I2S_MIC_GPIO_DIN);
#else
        static NoAudioCodecDuplex audio_codec(AUDIO_INPUT_SAMPLE_RATE, AUDIO_OUTPUT_SAMPLE_RATE,
            AUDIO_I2S_GPIO_BCLK, AUDIO_I2S_GPIO_WS, AUDIO_I2S_GPIO_DOUT, AUDIO_I2S_GPIO_DIN);
#endif
        return &audio_codec;
    }

    virtual Display* GetDisplay() override {
        return display_;
    }
};

DECLARE_BOARD(CompactWifiBoard);

// ---- firmware/main/boards/bread-compact-wifi/audited_led_mcp.h ----
// SPDX-License-Identifier: MIT
#pragma once
#include <esp_log.h>
#include "application.h"
#include "audited_led_policy.h"
#include "audited_led_wire.h"
#include "lab_desk_runtime.h"
#include "mcp_server.h"
namespace a08 {
inline cJSON* snapshot_json(const Snapshot& s) {
    cJSON* j = cJSON_CreateObject();
    if (!j)
        throw std::runtime_error("A08 allocation failed");
    cJSON_AddNumberToObject(j, "boot_id", s.boot_id);
    cJSON_AddBoolToObject(j, "fault", s.fault);
    cJSON_AddBoolToObject(j, "last_confirmed_power", s.last_confirmed_power);
    if (s.pad_known)
        cJSON_AddBoolToObject(j, "digital_pad_level", s.pad_level);
    else
        cJSON_AddNullToObject(j, "digital_pad_level");
    if (s.has_last_request)
        cJSON_AddNumberToObject(j, "last_applied_request_id", s.last_request);
    else
        cJSON_AddNullToObject(j, "last_applied_request_id");
    cJSON_AddStringToObject(j, "feedback", "digital_gpio_only_not_optical");
    cJSON_AddNumberToObject(j, "dedup_entries", 16);
    return j;
}
template <class Io>
void register_tools(McpServer& server, LedPolicy<Io>& policy) {
    auto* set_tool = new McpTool(
        "self.lab_led.set",
        "Set only the external laboratory LED. power is boolean. request_id is an integer "
        "0..2147483647. Use a new id for a new command; retry with the same id and power. Cache "
        "holds last16 successful ids for this boot only. Never use this example for a safety "
        "actuator.",
        PropertyList({Property("power", kPropertyTypeBoolean),
                      Property("request_id", kPropertyTypeInteger, 0, 2147483647)}),
        [&policy](const PropertyList& args) -> ReturnValue {
            const bool power = args["power"].template value<bool>();
            const auto id = static_cast<uint32_t>(args["request_id"].template value<int>());
            const Result result = policy.set(id, power);
            ESP_LOGI("a08", "SET request=%lu requested=%d outcome=%s",
                     static_cast<unsigned long>(id), power,
                     result == Result::APPLIED     ? "APPLIED"
                     : result == Result::DUPLICATE ? "DUPLICATE"
                     : result == Result::CONFLICT  ? "CONFLICT"
                                                   : "FAULT");
            if (result == Result::CONFLICT) {
                a10::panel().tool_error();
                throw std::runtime_error("A08 request id conflict");
            }
            if (result == Result::FAULT) {
                a10::panel().gpio_fault();
                throw std::runtime_error("A08 GPIO fault; repair and RESET");
            }
            const Snapshot state = policy.snapshot();
            ESP_LOGI("a08", "PAD boot=%lu confirmed=%d known=%d value=%d fault=%d",
                     static_cast<unsigned long>(state.boot_id), state.last_confirmed_power,
                     state.pad_known, state.pad_level, state.fault);
            if (state.fault) {
                a10::panel().gpio_fault();
                throw std::runtime_error("A08 GPIO fault; repair and RESET");
            }
            a10::panel().tool_success();
            cJSON* j = snapshot_json(state);
            cJSON_AddNumberToObject(j, "request_id", id);
            cJSON_AddBoolToObject(j, "requested_power", power);
            cJSON_AddBoolToObject(j, "duplicate", result == Result::DUPLICATE);
            return j;
        });
    set_tool->set_validator([](const cJSON* args) {
        auto error = validate_arguments("self.lab_led.set", args);
        if (error)
            Application::GetInstance().Schedule([]() { a10::panel().tool_error(); });
        return error;
    });
    server.AddTool(set_tool);
    auto* query_tool = new McpTool(
        "self.lab_led.get_state",
        "Query the laboratory LED digital pad and latched fault. No arguments. Digital feedback "
        "does not prove visible light. A fault needs repair and RESET; a query does not clear it.",
        PropertyList(), [&policy](const PropertyList&) -> ReturnValue {
            const Snapshot state = policy.snapshot();
            ESP_LOGI("a08", "QUERY boot=%lu confirmed=%d known=%d value=%d fault=%d",
                     static_cast<unsigned long>(state.boot_id), state.last_confirmed_power,
                     state.pad_known, state.pad_level, state.fault);
            return snapshot_json(state);
        });
    query_tool->set_validator([](const cJSON* args) {
        auto error = validate_arguments("self.lab_led.get_state", args);
        if (error)
            Application::GetInstance().Schedule([]() { a10::panel().tool_error(); });
        return error;
    });
    server.AddTool(query_tool);
}
}  // namespace a08