# embedded_auto_debugger

**Repository Path**: posty_banana/embedded_auto_debugger

## Basic Information

- **Project Name**: embedded_auto_debugger
- **Description**: 这或许是个伟大的无敌的牛逼的项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2026-08-28
- **Last Updated**: 2026-09-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# embedded_auto_debugger

`embedded_auto_debugger` 是一个面向嵌入式Linux板卡调试的本地串口服务。它让一个 AI 或脚本能够在不依赖 MobaXterm 的情况下，读取板端实时日志、发送受控串口命令，并把完整 RX/TX 证据保存在仓库中。

当前稳定能力是“日志观察 → AI 分析 → 受控串口交互 → 留存证据”。推荐模式是启动后台服务后，让 Codex 使用 `embedded-auto-debugger-operator` Skill 读取增量日志并诊断问题。普通控制台串口工具也保留，方便人工查看。

当前**尚未**自动修改源码、编译、烧录、复位或自行无限循环修复；这些 HIL 自动化能力需要在明确板卡、构建和烧录流程后逐步接入。工具不会自行猜测端口、抢占已被其他程序打开的串口，或向局域网暴露服务。

## 我应该怎么用？

日常让 AI 分析板子，按下面三步即可：

1. 首次在 Windows 电脑上运行 `./bootstrap-windows.cmd`，然后运行一次 `./install-codex-skill.cmd`。
2. 每次调试运行 `./run-service.cmd`，选择 COM 口；波特率直接回车默认为 `115200`。
3. 保持服务窗口运行，在新的 Codex 对话中说：`使用 embedded-auto-debugger-operator 分析当前串口日志；只做无害诊断。`

同一串口同一时间只能由一个程序使用；启动服务前请关闭 MobaXterm、串口助手和其他串口终端。

## 快速开始

在任何系统上，同一个串口只能被一个程序打开。启动前请关闭 MobaXterm、串口助手、IDE 终端或其他占用目标端口的工具。

### Windows PowerShell（使用 COM 口）

打开本仓库文件夹，例如 `D:\Desktop\00-embedded-auto-debugger`，然后在此目录的 PowerShell 中只需执行一条命令。它会以当前进程的 Bypass 策略启动 PowerShell 引导脚本，自动安装/定位 Python，创建 `.venv-windows`，并安装依赖。

```powershell
.\bootstrap-windows.cmd
```

环境建好后，一条命令打开交互式串口选择器：

```powershell
.\run-serial.cmd
```

已知端口时可跳过询问，例如：

```powershell
.\run-serial.cmd -Port COM22 -Baud 115200
```

> GUI 版本目前是实验性原型：已知在高频日志下存在卡顿和乱码问题，暂不推荐用于日常调试。请优先使用上面的控制台版；GUI 保留仅供后续优化验证。

日志很快、需要固定输入框和右侧快捷按钮时，可尝试 GUI 版本：

```powershell
.\run-serial-gui.ps1
```

GUI 的日志区独立滚动，底部输入框不会被日志覆盖；输入框支持 Tab，右侧按钮可依次发送配置的命令。

这个 PowerShell 启动器内部使用 `run-serial.py`，会依次询问端口和波特率。例如：输入 `22` 并回车，再输入 `115200` 并回车，它会打开 `COM22`。也可以输入完整的 `COM22`。如需直接运行 Python 文件，使用 `.\.venv-windows\Scripts\python.exe .\run-serial.py`；不依赖 Windows 的 `.py` 文件关联。

串口终端是即时按键模式：按下 **Tab** 会作为真正的 `0x09` 字符发送给板子，Enter 才提交整条命令；板子日志中的 Tab 会显示为 8 个空格。默认串口接收刷新延迟最多 50ms。若设备需要其他显示宽度，可在直接运行命令时追加 `--tab-width 4`。

### 配置 GUI 快捷命令

将 `shortcuts.example.json` 复制为本机的 `shortcuts.json` 后编辑；后者已被 Git 忽略。每个 `text` 步骤都会发送文本和默认行结尾，`delay_ms` 表示等待毫秒数。密码不要写进 JSON：使用 `secret_env` 引用环境变量。敏感步骤不会写入 GUI、`console.log`、事件文件或原始 TX 文件。

```powershell
Copy-Item .\shortcuts.example.json .\shortcuts.json
$env:BOARD_PASSWORD = '你的密码'
.\run-serial-gui.ps1
```

不知道端口时，在本仓库中运行：

```powershell
.\.venv-windows\Scripts\python.exe .\embedded_auto_debugger.py ports
```

如果引导脚本报告缺少 Python 且计算机没有 `winget`，从 Python 官方安装包安装 Python 3.10+，勾选 “Add Python to PATH”，然后重新执行 `.\bootstrap-windows.cmd`。

## AI 后台服务（推荐给 AI，不占用交互终端）

后台服务独占串口，并且仅在本机 `127.0.0.1` 提供 JSON API。启动服务后，不要再用 MobaXterm、控制台版或 GUI 打开同一 COM 口。

```powershell
.\run-service.cmd
```

它会列出当前可见 COM 口，请输入 `22` 或 `COM22`；波特率直接回车即为 `115200`。已知参数、由 AI 或脚本无提示启动时仍可使用：

```powershell
.\run-service.cmd -Port COM22 -Baud 115200
```

另开一个 PowerShell 窗口，AI 或脚本可通过项目客户端读取状态、读取新日志、发送命令并等待首个响应事件：

```powershell
.\.venv-windows\Scripts\python.exe .\ead_client.py health
.\.venv-windows\Scripts\python.exe .\ead_client.py events --after 0
.\.venv-windows\Scripts\python.exe .\ead_client.py send "echo EAD_TOOL_VERIFY"
.\.venv-windows\Scripts\python.exe .\ead_client.py command <命令ID> --wait-ms 3000
```

API 只在本机回环地址监听：`GET /health`、`GET /events?after=<事件ID>`、`GET /alerts?after=<告警ID>`、`POST /commands`、`GET /commands/<命令ID>?wait_ms=<毫秒>`。服务会把 UART 原始字节和结构化事件持续写入 `tmp_log/`；内存事件窗口保留最近 2000 条。`response_received` 表示命令发送后收到了第一条 UART 输出，不等同于业务命令一定成功，AI 应结合内容判定。

### 整晚复现（长时间）：本地零 token 异常监控

服务启动后会在本地持续匹配内置的 `kernel panic`、watchdog、segmentation fault、断言失败等异常。这个监控器不调用 AI、不会上传日志、不会消耗 token；命中时服务窗口会立即打印 `[ALERT]`，并在本次会话目录创建 `alerts/alert-xxxxxx.json`。该文件包含命中规则、严重级别、命中前 4096 个字符、触发文本及随后 50 个 UART 接收事件。

#### 两种模式的 token 边界

- `./run-service.cmd`：本地采集、规则匹配和告警保存，**零 token**。
- `./run-service.cmd -AutoAnalyzeCritical`：仅在 `critical` 告警发生时启动一次只读 Codex 分析，**按实际触发次数消耗 token**。

本次更新后请再执行一次 `./install-codex-skill.cmd`，让 Codex 使用包含告警流程的最新版 operator Skill。

早上或收到告警后，在另一个终端运行：

```powershell
.\.venv-windows\Scripts\python.exe .\ead_client.py alerts --after 0
```

只把返回的告警和对应事件范围交给 AI，不要让 AI 从 `events --after 0` 扫描整晚日志。服务健康状态还会返回 `latest_alert`，可作为下次查询的游标。

如需匹配板卡私有的报错，复制示例文件为本机配置（该文件不会上传 Git），修改其中的正则后重启服务：

```powershell
Copy-Item .\watch_rules.example.json .\watch_rules.json
notepad .\watch_rules.json
```

每条规则包含小写 `id`、`severity`（`info`、`warning`、`error`、`critical`）和 `patterns` 正则数组。默认同一规则 60 秒内只产生一次告警，避免高频重复刷屏。

#### 只在 critical 告警时自动启动 Codex 分析（可选）

这是事件触发模式：没有 critical 告警时不会启动 AI；critical 告警出现后，服务立即启动一个独立 Codex CLI 任务，只读取该告警包并生成分析报告。它不是零 token，但不会像定时轮询一样在正常整晚持续消耗用量。

首次启用前，在 PowerShell 登录 Codex CLI（登录是你的账号操作，本项目不会替你执行）：

```powershell
codex login
```

之后用下列方式启动服务；每个服务会话默认最多自动分析 3 次，连续触发间隔至少 5 分钟，并且同时最多运行一个分析任务：

```powershell
.\run-service.cmd -AutoAnalyzeCritical
```

自动任务固定使用 `read-only` 沙箱，明确禁止编辑文件、构建、启动/停止服务、打开串口或发送 UART 命令。报告、标准输出、标准错误和调度记录保存在本次会话的 `auto-analysis/` 目录。CLI 未安装或未登录时，带 `-AutoAnalyzeCritical` 的启动会清晰失败；去掉该参数即可回到纯本地零 token 采集模式。

WSL 中，确保该 WSL 发行版可运行且已登录 `codex` 后：

```bash
EAD_AUTO_ANALYZE_CRITICAL=1 bash run-service.sh /dev/ttyUSB0 115200
```

自动分析只会处理 severity 为 `critical` 的规则。因此，想让板卡私有错误触发 AI 时，请在 `watch_rules.json` 中为该规则设置 `"severity": "critical"`。自动报告是诊断建议，不是修复成功证明；它不会自行改代码或操作板子。

### 最无脑的 Codex 接入方式

只需在仓库执行一次安装命令：

```powershell
.\install-codex-skill.cmd
```

重开 Codex 对话后，先启动上面的后台服务，然后直接对 AI 说：

```text
使用 embedded-auto-debugger-operator 分析当前串口日志；只做无害诊断。
```

Skill 会固定使用本项目的后台服务和 `ead_client.py`，先检查连接、再读取增量日志；未明确授权时不会猜端口、抢占串口、发送危险命令或尝试烧录/复位。Windows 文档中的 `.cmd` 是跨执行策略的正式入口；`.ps1` 是其内部实现文件，不建议直接运行。

### WSL Ubuntu（使用 `/dev/ttyUSB*` 或 `/dev/serial/by-id/*`）

在 Ubuntu WSL 终端中运行。以下命令会自动安装 `python3`/`venv` 缺失部分，并在本仓库中建立独立 `.venv-wsl`：

```bash
cd /mnt/d/Desktop/00-embedded-auto-debugger
bash scripts/bootstrap-wsl-ubuntu.sh
```

环境建好后，一条命令打开串口：

```bash
bash run-serial.sh /dev/ttyUSB0 115200
```

以后台服务方式启动：

```bash
bash run-service.sh /dev/ttyUSB0 115200
```

先查看 WSL 能见的端口：

```bash
./.venv-wsl/bin/python embedded_auto_debugger.py ports
ls -l /dev/serial/by-id/
```

优先使用 `/dev/serial/by-id/...` 这种稳定路径，而不是可能随拔插变化的 `/dev/ttyUSB0`。

## 依赖安装与失败排查

当前工程的运行依赖保持最小化：Python 3.10+ 和 `pyserial` 3.5+。Windows 一条命令为 `.\bootstrap-windows.cmd`；Ubuntu/WSL 一条命令为 `bash scripts/bootstrap-wsl-ubuntu.sh`。它们会依次打印和校验：

- 系统 Python 版本；
- 项目独立 `.venv-windows` 或 `.venv-wsl`；
- `requirements.txt` 中的 `pyserial`；
- `pip check` 依赖一致性和 `pyserial` 导入。

引导失败不会隐藏错误：它会打印失败阶段和建议。优先检查网络/代理、磁盘空间、项目目录写权限；WSL 另外检查 `sudo` 与 apt 源。如果已有损坏的依赖环境，仅删除本项目对应的 `.venv-windows` 或 `.venv-wsl` 目录后重新运行引导命令；不需要删除代码。

## 连接 USB 串口到 WSL

如果 Windows 能看到 COM 口而 WSL 看不到 `/dev/ttyUSB*`，可通过 `usbipd-win` 把 USB 串口设备附加给 WSL。在管理员 PowerShell 中执行（`<BUSID>` 从第一条命令的输出中获取）：

```powershell
usbipd list
usbipd bind --busid <BUSID>
usbipd attach --wsl --busid <BUSID>
```

回到 WSL 后用 `ls -l /dev/serial/by-id/` 确认。若设备存在但无权限，一次性执行 `sudo usermod -aG dialout $USER`，关闭所有 WSL 终端并重开。USB 串口被附加到 WSL 时，不要同时在 Windows 中打开它。

## 交互方式

启动后：

- 板子的输出会直接显示在终端。
- 输入任意普通文本并回车，工具会按默认 `CRLF` 发给板子。
- 按 `Ctrl+C` 会立即向板子发送控制字符 `0x03`（不附带换行）；输入 `debug_exit` 安全保存并退出工具。
- 输入 `/help` 查看本地帮助。
- 板子仅使用 LF 时，在直接 Python 命令后追加 `--eol lf`。

## 日志文件

每次会话在仓库内的 `tmp_log/<时间戳>-<随机标识>/` 生成一个独立目录；Windows 和 WSL 使用同一位置，便于 AI 直接读取。目录内包含：

```text
manifest.json       # 端口、波特率、工具版本和产物路径
raw/uart-rx.bin     # 完整接收字节，解码失败也不丢失
raw/uart-tx.bin     # 完整发送字节
events.jsonl        # 带时间戳、序号、文本和字节哈希的结构化事件
console.log         # 便于人工阅读的 TX/RX 日志
alerts/             # 本地异常监控生成的紧凑证据包
auto-analysis/      # 仅启用自动分析时的 Codex 报告和调度记录
```

`tmp_log/` 默认被 `.gitignore` 忽略，不会进入代码提交。

## 实板验收

1. 停止 MobaXterm 对目标端口的连接。
2. 运行 `ports` 确认端口。
3. 以正确波特率运行 `run-serial` 脚本。
4. 确认板端启动日志实时出现。
5. 输入一个无害的板端命令（例如 `help`），确认响应。
6. 输入 `debug_exit`，打开终端打印的会话目录并确认上述 5 个日志文件存在。

## 常见问题

- **`py` 或 `python` 找不到**：先运行对应平台的 `bootstrap` 脚本。Windows 安装 Python 后必须重开 PowerShell 以更新 PATH。
- **`Access is denied` / `Permission denied`**：端口已被占用，或 WSL 用户缺少 `dialout` 权限。不要强抢端口。
- **WSL `ports` 为空**：先用 `usbipd` 附加 USB 设备，然后重新查看 `/dev/serial/by-id/`。
- **有输出但输入无响应**：检查波特率、串口参数与行结尾。默认是 115200 8N1 和 CRLF；某些 shell 需要 `--eol lf`。
- **注意检查换行符**。shell脚本运行失败有可能是换行符导致的。可以安装 `dos2unix` 工具转换。

## 开发自检

在 WSL Ubuntu 中可运行：

```bash
./.venv-wsl/bin/python -m unittest discover -s tests -v
```

测试包括真实的伪串口端到端 RX/TX 会话，无需接入开发板。