RS485管理器

负责串口打开/关闭、轮询帧发送、超时重试。内部同样集成了正/负日志（输出到文件）。

# host/rs485_manager.pydef poll_device(self):    self.send_frame(CMD_POLL)    t0 = time.time()    while not self.response_received:        if time.time() - t0 > 0.05:            self.logger.negative("POLL_RESPONSE",                f"Device {self.dev_id} not responding")            break        time.sleep(0.001)    if self.response_received:        self.logger.positive("POLL_RESPONSE",            f"temp={self.temp}, press={self.press}")

数据管理

存储传感器历史数据，支持CSV导出。日志记录每次操作的成功/失败状态，便于AI诊断。

5. Python调试助手：三合一监控与自动总结

这是整个模板的灵魂脚本，它实现了对三个数据源的实时监控：

1. RS485总线监听
   （通过USB转RS485适配器，监听模式）
2. 控制板串口日志
   （通过另一个COM口读取固件printf输出）
3. 上位机文件日志
   （实时tail -f，监控日志文件新增行）

脚本将所有日志统一为结构化格式，并在测试结束后、检测到负日志时、或定时周期自动输出AI可读的总结报告，方便复制给AI模型诊断。

#!/usr/bin/env python3# debug_tools/debug_assistant.py"""三合一调试助手：监听RS485总线、控制板串口日志、上位机日志文件，并按正/负日志规范输出统一的结构化日志与AI诊断总结。用法：    python debug_assistant.py --rs485 COM3 --mcu COM4 --host-log ../host/logs/app.log选项：    --summary-interval 10  每10秒自动输出一次总结（默认检测到负日志时立即输出）    --output-summary-only  仅输出总结，不输出实时日志行"""import serialimport timeimport reimport osimport argparsefrom datetime import datetimefrom collections import defaultdictclass DebugAssistant:    def __init__(self, rs485_port, mcu_port, host_log_path, summary_interval=0):        self.rs485 = serial.Serial(rs485_port, 9600, timeout=0.1) if rs485_port else None        self.mcu = serial.Serial(mcu_port, 115200, timeout=0.1) if mcu_port else None        self.host_log_path = host_log_path        self.host_log_pos = 0        self.summary_interval = summary_interval  # 0表示仅负日志触发        self.negative_events = []        self.positive_events = []        self.last_summary_time = time.time()        self.running = True    def read_rs485_line(self):        if self.rs485 and self.rs485.in_waiting:            line = self.rs485.readline().decode('utf-8', errors='ignore').strip()            if line:                print(f"[RS485] {line}")                self.categorize_log(line, source='RS485')    def read_mcu_line(self):        if self.mcu and self.mcu.in_waiting:            line = self.mcu.readline().decode('utf-8', errors='ignore').strip()            if line:                print(f"[MCU] {line}")                self.categorize_log(line, source='MCU')    def read_host_log(self):        if not os.path.exists(self.host_log_path):            return        with open(self.host_log_path, 'r', encoding='utf-8') as f:            f.seek(0, 2)            size = f.tell()            if size > self.host_log_pos:                f.seek(self.host_log_pos)                new_lines = f.read().splitlines()                self.host_log_pos = size                for line in new_lines:                    print(f"[HOST] {line}")                    self.categorize_log(line, source='HOST')    def categorize_log(self, line, source):        """根据日志内容分类为正/负事件"""        if 'NEGATIVE' in line or 'expected' in line.lower():            self.negative_events.append((source, line))        elif 'POSITIVE' in line or 'occurred' in line.lower():            self.positive_events.append((source, line))    def generate_summary(self):        """生成AI可读的诊断总结"""        summary = []        summary.append("=" * 40)        summary.append(f"🕒 调试总结 [{datetime.now().strftime('%H:%M:%S')}]")        summary.append(f"📊 正事件数量: {len(self.positive_events)}")        summary.append(f"⚠️ 负事件数量: {len(self.negative_events)}")        if self.negative_events:            summary.append("--- 负事件详情 (期望但未发生) ---")            for src, evt in self.negative_events[-5:]:  # 最近5条                summary.append(f"  [{src}] {evt}")        if self.positive_events:            summary.append("--- 最近正事件 ---")            for src, evt in self.positive_events[-3:]:                summary.append(f"  [{src}] {evt}")        summary.append("=" * 40)        return "\n".join(summary)    def run(self):        print("🚀 调试助手启动，按Ctrl+C停止...")        try:            while self.running:                self.read_rs485_line()                self.read_mcu_line()                self.read_host_log()                # 触发总结的条件：                # 1. 检测到新的负事件立即输出                # 2. 或者按间隔周期输出                now = time.time()                if self.negative_events and (self.summary_interval == 0 or now - self.last_summary_time > self.summary_interval):                    print("\n" + self.generate_summary())                    self.last_summary_time = now                    # 仅保留最近的汇总，防止重复输出同一批                    self.negative_events = self.negative_events[-1:]                time.sleep(0.05)        except KeyboardInterrupt:            print("\n🛑 停止监控，输出最终总结：")            print(self.generate_summary())if __name__ == "__main__":    parser = argparse.ArgumentParser(description="三合一调试助手")    parser.add_argument("--rs485", help="RS485监听串口")    parser.add_argument("--mcu", help="控制板日志串口")    parser.add_argument("--host-log", help="上位机日志文件路径")    parser.add_argument("--summary-interval", type=int, default=0, help="总结输出间隔(秒)，0=仅负日志触发")    args = parser.parse_args()    assistant = DebugAssistant(args.rs485, args.mcu, args.host_log, args.summary_interval)    assistant.run()

💡 这个脚本就是CLI闭环的物理载体：AI可以通过命令 python debug_tools/debug_assistant.py --rs485 COM3 --mcu COM4 --host-log host/logs/app.log 直接启动监控，并实时获取结构化总结，无需人工解读日志。

6. agents.md：AI协作契约

放入项目根目录，任何接入的AI助手都会自动遵守项目规范。

# agents.md - RS485传感器采集项目## 项目概述- 嵌入式平台：STM32F407，RS485总线9600bps- 传感器：温湿度SHT30、压力传感器（模拟量）- 上位机：Python/PyQt，通过USB-RS485适配器通信## 状态枚举| 数值 | 枚举名 | 含义 ||------|--------|------|| 0 | IDLE | 空闲 || 1 | WAITING_FOR_POLL | 等待上位机轮询 || 2 | SENDING_RESPONSE | 正在发送数据 |## 行为准则1. 所有日志分析优先查找 [NEGATIVE] 和 [POSITIVE] 标签2. 上位机日志位于 host/logs/ 下，格式为结构化键值对3. 调试助手启动命令：`python debug_tools/debug_assistant.py --rs485 COMx --mcu COMy --host-log host/logs/app.log`4. 建议修改固件时，使用 git diff 格式输出5. 遇到通讯超时，优先检查RS485总线终端电阻和设备地址## 已知陷阱- 轮询间隔必须 > 50ms，否则固件可能因中断过载丢帧- RS485收发切换需延时2ms，避免总线竞争

7. VSCode Tasks：一键全自动测试

// .vscode/tasks.json{    "version": "2.0.0",    "tasks": [        {            "label": "build-fw",            "type": "shell",            "command": "cd firmware/build && cmake --build .",            "problemMatcher": ["$gcc"]        },        {            "label": "flash",            "dependsOn": ["build-fw"],            "type": "shell",            "command": "openocd -f interface/stlink.cfg -f target/stm32f4x.cfg -c 'program firmware/build/firmware.elf verify reset exit'"        },        {            "label": "start-debug-assistant",            "dependsOn": ["flash"],            "type": "shell",            "command": "python debug_tools/debug_assistant.py --rs485 COM3 --mcu COM4 --host-log host/logs/app.log",            "isBackground": true,            "problemMatcher": []        },        {            "label": "run-host-app",            "dependsOn": ["start-debug-assistant"],            "type": "shell",            "command": "python host/main.py"        },        {            "label": "full-test",            "dependsOn": ["run-host-app"],            "group": { "kind": "test", "isDefault": true }        }    ]}

8. 五层进化在本项目中的映射

🎯 使用场景：当AI助手（如Claude、GPT）接入此项目时，只需读取 agents.md 和项目结构，即可自主运行 full-test 任务，读取调试助手输出的总结，并基于正/负日志定位问题。整个过程无需人工解释硬件细节。

这个模板可以直接克隆到任何RS485传感器采集项目中。只需修改传感器驱动和协议帧定义，其余工程化组件（日志、调试助手、agents.md、tasks.json）均可复用。真正的"一次搭建，终身受益"。

itg ·-lvgl-