From d58bf08472b26ff65848b99db5020e81486f290d Mon Sep 17 00:00:00 2001
From: impressionyang <impressionyang@users.noreply.example.com>
Date: Wed, 15 Apr 2026 18:43:35 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E8=B0=83=E8=AF=95?=
 =?UTF-8?q?=E4=BF=A1=E6=81=AF=E6=94=B6=E9=9B=86=E6=8C=87=E5=8D=97?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

用于排查配置向导 500 错误，包含:
- 日志收集方法
- Python 语法检查
- 依赖验证
- 常见问题解决方案
- 快速诊断脚本

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 调试信息收集.md | 313 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 313 insertions(+)
 create mode 100644 调试信息收集.md

diff --git a/调试信息收集.md b/调试信息收集.md
new file mode 100644
index 0000000..bfc9b55
--- /dev/null
+++ b/调试信息收集.md
@@ -0,0 +1,313 @@
+# 调试信息收集指南
+
+**问题**: 配置向导 500 Internal Server Error
+
+---
+
+## 1. 必收集的信息
+
+### 1.1 Home Assistant 日志
+
+```bash
+# 实时查看日志（在添加集成时）
+tail -f ~/.homeassistant/home-assistant.log | grep -E "(sigmesh|error|Error|ERROR)" -i
+
+# 或查看完整日志
+cat ~/.homeassistant/home-assistant.log > ~/ha_full_log.txt
+```
+
+**关键信息**:
+- [ ] 集成加载时的错误堆栈
+- [ ] 任何提到 `sigmesh_gateway` 的行
+- [ ] 错误发生时间点的日志
+
+---
+
+### 1.2 Home Assistant 版本信息
+
+```bash
+# 查看 HA 版本
+ha --version
+
+# 或在 HA UI: 设置 → 关于
+# 记录：HA 版本、Python 版本、操作系统
+```
+
+**需要记录**:
+- Home Assistant 版本：__________
+- Python 版本：__________
+- 操作系统：__________
+- 安装方式（HAOS/Container/Supervised/Core）: __________
+
+---
+
+### 1.3 浏览器控制台错误
+
+**Chrome/Edge**:
+1. 按 `F12` 打开开发者工具
+2. 切换到 `Console` 标签
+3. 点击添加集成按钮
+4. 截图或复制所有红色错误信息
+
+**需要记录**:
+- [ ] 控制台错误截图
+- [ ] Network 标签中失败的请求详情
+
+---
+
+## 2. 代码相关问题排查
+
+### 2.1 检查集成文件完整性
+
+```bash
+# 检查文件是否存在
+ls -la ~/.homeassistant/custom_components/sigmesh_gateway/
+
+# 预期输出应包含:
+# __init__.py
+# config_flow.py
+# const.py
+# coordinator.py
+# manifest.json
+# serial_reader.py
+# protocol_parser.py
+```
+
+**检查项**:
+- [ ] 所有文件都存在
+- [ ] 文件大小不为 0
+- [ ] 文件权限正确（homeassistant 用户可读）
+
+---
+
+### 2.2 验证 manifest.json 格式
+
+```bash
+# 检查 JSON 格式
+python3 -m json.tool ~/.homeassistant/custom_components/sigmesh_gateway/manifest.json
+```
+
+**如报错，说明 JSON 格式有问题**
+
+---
+
+### 2.3 检查 Python 语法错误
+
+```bash
+# 逐个检查 Python 文件
+python3 -m py_compile ~/.homeassistant/custom_components/sigmesh_gateway/__init__.py
+python3 -m py_compile ~/.homeassistant/custom_components/sigmesh_gateway/config_flow.py
+python3 -m py_compile ~/.homeassistant/custom_components/sigmesh_gateway/const.py
+python3 -m py_compile ~/.homeassistant/custom_components/sigmesh_gateway/coordinator.py
+python3 -m py_compile ~/.homeassistant/custom_components/sigmesh_gateway/serial_reader.py
+python3 -m py_compile ~/.homeassistant/custom_components/sigmesh_gateway/protocol_parser.py
+
+# 检查 platforms 目录
+python3 -m py_compile ~/.homeassistant/custom_components/sigmesh_gateway/platforms/sensor.py
+python3 -m py_compile ~/.homeassistant/custom_components/sigmesh_gateway/platforms/switch.py
+python3 -m py_compile ~/.homeassistant/custom_components/sigmesh_gateway/platforms/light.py
+python3 -m py_compile ~/.homeassistant/custom_components/sigmesh_gateway/platforms/binary_sensor.py
+python3 -m py_compile ~/.homeassistant/custom_components/sigmesh_gateway/platforms/device_tracker.py
+```
+
+**如报错，记录具体错误信息**:
+```
+文件：__________
+错误：__________
+行号：__________
+```
+
+---
+
+### 2.4 检查依赖是否安装
+
+```bash
+# 查看 manifest.json 中的依赖
+cat ~/.homeassistant/custom_components/sigmesh_gateway/manifest.json | grep requirements
+
+# 检查是否已安装
+pip list | grep -E "(pyserial|bleak)"
+```
+
+**当前依赖**:
+```json
+"requirements": ["pyserial-asyncio==0.6", "bleak-mesh>=0.2.0"]
+```
+
+---
+
+## 3. 启用详细日志
+
+### 3.1 修改 configuration.yaml
+
+```yaml
+# configuration.yaml
+logger:
+  default: warning
+  logs:
+    custom_components.sigmesh_gateway: debug
+    custom_components.sigmesh_gateway.config_flow: debug
+    custom_components.sigmesh_gateway.serial_reader: debug
+    custom_components.sigmesh_gateway.protocol_parser: debug
+    custom_components.sigmesh_gateway.coordinator: debug
+    homeassistant.loader: debug
+    homeassistant.config_entries: debug
+```
+
+### 3.2 重启后重新测试
+
+```bash
+# 重启 HA
+ha core restart
+
+# 等待 30 秒后查看日志
+tail -f ~/.homeassistant/home-assistant.log
+```
+
+---
+
+## 4. 常见问题和解决方案
+
+### 问题 1: `No module named 'serial'`
+
+**解决方案**:
+```bash
+# 进入 HA 环境安装
+docker exec homeassistant pip install pyserial-asyncio==0.6
+
+# 或 HAOS
+ha addons ssh
+
+# 然后重启
+ha core restart
+```
+
+### 问题 2: `cannot import name 'XXX' from 'homeassistant.XXX'`
+
+**原因**: HA 版本不兼容
+
+**解决方案**:
+- 检查 HA 版本是否 ≥ 2024.1.0
+- 如版本过低，升级 HA 或修改代码适配
+
+### 问题 3: `ModuleNotFoundError: No module named 'custom_components'`
+
+**原因**: 文件路径错误
+
+**解决方案**:
+```bash
+# 确认目录结构
+ls -la ~/.homeassistant/custom_components/
+# 应该是 sigmesh_gateway/ 直接在 custom_components/ 下
+```
+
+### 问题 4: config_flow 导入错误
+
+**检查**:
+```bash
+# 查看 config_flow.py 的导入语句
+head -30 ~/.homeassistant/custom_components/sigmesh_gateway/config_flow.py
+```
+
+---
+
+## 5. 调试信息模板
+
+**请填写以下信息**:
+
+```
+=== 环境信息 ===
+HA 版本：__________
+Python 版本：__________
+操作系统：__________
+安装方式：__________
+
+=== 错误信息 ===
+浏览器控制台错误：
+__________
+
+HA 日志错误（完整堆栈）:
+__________
+
+=== 已尝试的排查 ===
+- [ ] 检查文件完整性
+- [ ] 验证 Python 语法
+- [ ] 检查依赖安装
+- [ ] 启用详细日志
+
+=== 附加信息 ===
+- 集成文件部署路径：__________
+- 是否已重启 HA: [ ] 是 [ ] 否
+- 之前是否能正常加载：[ ] 是 [ ] 否
+- 最近是否有代码变更：[ ] 是 [ ] 否
+```
+
+---
+
+## 6. 快速诊断脚本
+
+```bash
+#!/bin/bash
+# diagnose.sh - 快速诊断脚本
+
+HA_CONFIG="${HOME}/.homeassistant"
+INTEGRATION="${HA_CONFIG}/custom_components/sigmesh_gateway"
+
+echo "=== SigMesh Gateway 诊断工具 ==="
+echo ""
+
+# 1. 检查文件存在
+echo "1. 检查文件完整性..."
+if [ -d "$INTEGRATION" ]; then
+    echo "   ✓ 集成目录存在"
+    ls -1 "$INTEGRATION"
+else
+    echo "   ✗ 集成目录不存在"
+    exit 1
+fi
+
+# 2. 检查 Python 语法
+echo ""
+echo "2. 检查 Python 语法..."
+for file in "$INTEGRATION"/*.py "$INTEGRATION"/platforms/*.py; do
+    if python3 -m py_compile "$file" 2>/dev/null; then
+        echo "   ✓ $(basename $file)"
+    else
+        echo "   ✗ $(basename $file) - 语法错误"
+    fi
+done
+
+# 3. 检查依赖
+echo ""
+echo "3. 检查依赖..."
+pip list | grep -E "(serial|bleak)" || echo "   未找到相关依赖"
+
+# 4. 查看最近日志
+echo ""
+echo "4. 最近日志 (sigmesh 相关)..."
+tail -100 "${HA_CONFIG}/home-assistant.log" | grep -i sigmesh || echo "   无相关日志"
+
+echo ""
+echo "=== 诊断完成 ==="
+```
+
+保存为 `diagnose.sh`，运行：
+```bash
+chmod +x diagnose.sh
+./diagnose.sh
+```
+
+---
+
+## 7. 下一步
+
+收集完上述信息后：
+
+1. **查看日志中的完整错误堆栈** - 这是定位问题的关键
+2. **运行快速诊断脚本** - 自动检查常见问题
+3. **提供调试信息模板中的内容** - 用于进一步分析
+
+**最关键的调试信息**:
+1. `home-assistant.log` 中集成加载时的完整错误堆栈
+2. 浏览器控制台的 JavaScript 错误
+3. `python3 -m py_compile` 的语法检查结果