从"摸黑调试"到"拨云见日"
AI编程调试的五层进化

// ===== 结构化正日志 =====
#define LOG(level, fmt, ...) printf("[%s] %s:%d " fmt "\r\n", level, __FILE__, __LINE__, ##__VA_ARGS__)
#define LOG_STATE(state, epoch) LOG("INFO", "state=%s epoch=%d", state_to_str(state), epoch)

// ===== 负日志引擎 =====
#define EXPECT_WITHIN(ms, event_str, condition) do { \
    uint32_t _start = get_tick_ms(); \
    while (!(condition)) { \
        if ((get_tick_ms() - _start) > (ms)) { \
            LOG("NEGATIVE", "%s expected '%s' within %dms, not occurred.", __func__, event_str, ms); \
            break; \
        } \
        delay_ms(1); \
    } \
} while(0)

#define EVENT_OCCURRED(event_name) do { \
    LOG("POSITIVE", "EVENT: %s occurred at tick=%lu", event_name, get_tick_ms()); \
} while(0)

// ===== 使用示例 =====
void can_protocol_task(void) {
    LOG_STATE(COMPLETING, epoch);
    send_REQUEST_frame();
    EXPECT_WITHIN(50, "COMMIT_frame", commit_received_flag);
    if (commit_received_flag) {
        EVENT_OCCURRED("COMMIT_received");
        LOG("INFO", "Protocol completed successfully");
    }
}

project/
            ├── firmware/                    # 固件主目录
            │   ├── src/                     # 源码（驱动、协议、应用）
            │   ├── inc/                     # 头文件（日志宏、负日志引擎）
            │   └── build/                   # 编译配置
            ├── host/                        # 上位机CLI工具
            │   ├── cli_can.py              # CAN帧发送/监听
            │   ├── cli_serial.py           # 串口调试
            │   └── test_automation.py     # 自动化测试脚本
            ├── docs/                        # 协议规范与硬件连接图
            ├── logs/                        # 日志目录（典型/异常案例）
            ├── .vscode/
            │   └── tasks.json             # 一键自动化任务
            └── agents.md                   # AI协作规范（核心创新）

# agents.md - 放入项目根目录，AI助手自动加载
            ## 行为准则
            1. 当看到数字状态码，必须映射到枚举名再分析
            2. 分析日志时优先检查 [NEGATIVE] 条目
            3. 输出修改建议必须使用 git diff 格式
            4. 运行测试前先确认环境：`python host/cli_can.py --ping`
            ## 已知陷阱
            - epoch在COMMIT处理后才递增
            - CAN设备名为can0，波特率250000
            - 负日志超时阈值：50ms

// .vscode/tasks.json
            {
                "version": "2.0.0",
                "tasks": [
                    { "label": "build", "type": "shell", "command": "cmake --build build" },
                    { "label": "flash", "dependsOn": ["build"], "type": "shell", "command": "openocd ..." },
                    { "label": "monitor_log", "dependsOn": ["flash"], "type": "shell", "command": "python host/cli_serial.py ..." },
                    { "label": "cli_test", "dependsOn": ["monitor_log"], "type": "shell", "command": "python host/test_automation.py ..." },
                    { "label": "full_loop", "dependsOn": ["cli_test"], "group": { "kind": "test", "isDefault": true } }
                ]
            }