Skill: lichm1007/issuefinder-tool (version 1.0.0)

--- name: issuefinder-tool description: 功能强大的车辆日志下载与解析工具，支持云端日志下载、本地日志处理、自动故障分析等功能 --- # issuefinder-tool ## 工具概述 `issuefinder-tool` 是一个专业的车辆日志分析工具，提供云端日志下载、本地日志解析、自动故障分析等功能。工具能够自动识别日志类型，支持多种日志格式，并可与 IssueFinder API 集成进行智能分析。 ### 核心功能 - **车辆日志下载**：从云端下载指定 VIN 和时间的车辆日志 - **智能故障分析**：自动分析车辆重启原因和故障信息 - **本地日志处理**：支持多种日志格式的解析和转换 - **自动类型识别**：智能检测日志文件类型，自动选择合适的解析工具 - **归档文件支持**：自动解压 zip、tar.gz、7z 等压缩格式 --- ## 🚀 推荐使用方式 为了更好地管理日志输出路径，**强烈推荐使用包装脚本** `iflog` 命令。 ### 为什么使用包装脚本？ - ✅ **自动路径管理**：日志自动保存到 `ISSUEFINDER_LOGS_PATH` 环境变量指定的路径 - ✅ **日期分组**：自动按 `年/月/日` 创建目录结构，便于管理 - ✅ **完全兼容**：支持原始工具的所有参数和功能 - ✅ **独立维护**：不影响原始工具的云端同步更新 ### 快速开始 ```bash # 1. 设置环境变量（已配置为 /home/lixiang/work/sdata/iss-log） export ISSUEFINDER_LOGS_PATH=[REDACTED_SECRET] # 2. 设置命令别名（添加到 ~/.bashrc 或 ~/.zshrc） alias iflog='/home/lixiang/.openclaw/skills/issuefinder-tool/scripts/iflog' # 3. 重新加载配置 source ~/.bashrc # 或 source ~/.zshrc # 4. 使用 iflog 命令（自动按日期分组） iflog --direct-download --vin HLX33B124P1767770 --happen-time "2025-10-27 18:43" iflog -u /path/to/lastlog_file iflog --issuefinder --vin HLX33B124P1767770 --happen-time "2025-10-27 18:43" ``` ### 自动生成的目录结构 ``` /home/lixiang/work/sdata/iss-log/ ├── 2026/ │ ├── 02/ │ │ ├── 28/ │ │ │ ├── VIN_HLX33B124P1767770/ # 云端下载的日志 │ │ │ ├── vehicle_logs.zip/ # 本地处理的日志 │ │ │ └── ... │ │ └── 26/ │ │ └── ... ``` **详细文档**：查看 [WRAPPER_USAGE.md](./WRAPPER_USAGE.md) 了解更多信息 --- ## 工作模式 ### 本地文件处理模式（默认） 上传并处理本地日志文件，支持自动类型识别。 **适用场景**：已有日志文件，需要解析或转换格式 **基础用法**（推荐使用 iflog 命令，自动管理输出路径）： ```bash # 自动检测文件类型并处理（使用配置的路径） iflog -u /path/to/lastlog_file # 处理压缩包（自动解压） iflog -u /path/to/logs.zip # 手动指定工具类型 iflog -t lastlog_unpack -u /path/to/lastlog_file --verbose # 或使用原始工具（需手动指定输出路径） issuefinder-tool.py -u /path/to/lastlog_file --output /home/lixiang/work/sdata/iss-log/$(date +%Y/%m/%d) ``` --- ### IssueFinder 分析模式 通过 IssueFinder API 自动分析车辆重启原因和故障信息。 **适用场景**：需要自动分析车辆故障原因 **基础用法**（推荐使用 iflog 命令）： ```bash # 分析车辆重启原因（自动保存到配置路径） iflog --issuefinder --vin HLX33B124P1767770 --happen-time "2025-10-27 18:43" # 支持多种时间格式 iflog --issuefinder --vin HLX33B124P1767770 --happen-time "2025-10-27T18:43" iflog --issuefinder --vin HLX33B124P1767770 --happen-time "2025/10/27 18:43:00" ``` **分析结果包含**： - 重启原因（reboot reason） - 最终分析结果（final result） - 屏幕状态（screen status） - 相关日志文件下载 --- ### 云端日志下载模式 通过 IssueFinder API 下载云端日志文件。 **适用场景**：需要获取云端存储的车辆日志 **基础用法**（推荐使用 iflog 命令）： ```bash # 下载指定 VIN 和时间的日志（自动保存到配置路径） iflog --cloud-log \ --vin HLX33B124P1767770 \ --happen-time "2025-10-27 18:43" \ --task-type 1731484362257596488 # 自定义任务类型 iflog --cloud-log \ --vin HLX33B124P1767770 \ --happen-time "2025-10-27 18:43" \ --task-type YOUR_TASK_ID \ --poll-interval 30 ``` --- ### 直接云端下载模式（推荐） 直接从云端存储下载日志，绕过 IssueFinder API，速度更快。 **适用场景**：仅需要下载日志文件，不需要分析 **基础用法**（推荐使用 iflog 命令，自动管理输出路径）： ```bash # 下载 Klog 类型日志（自动保存到 /home/lixiang/work/sdata/iss-log/YYYY/MM/DD/） iflog --direct-download \ --vin HLX14B175S1996368 \ --happen-time "2025-11-06 18:00" # 下载特定类型的日志，指定时间范围 iflog --direct-download \ --vin HLX14B175S1996368 \ --happen-time "2025-11-06 18:00" \ --log-type log_HUF_Klog \ --time-range 120 # 从测试环境下载 iflog --direct-download \ --vin HLX14B175S1996368 \ --happen-time "2025-11-06 18:00" \ --env testtwo ``` --- ## 支持的日志解析工具 | 工具名称 | 适用文件类型 | 说明 | |---------|------------|------| | `lastlog_unpack` | lastlog 文件 | 解析系统 lastlog 日志 | | `minidump_unpack` | minidump 文件 | 解析系统崩溃转储文件 | | `clp_decompress` | *.clp, *.clp.zst | 解压 CLP 压缩格式日志 | | `md_parser_slog` | md_qx_slog2.bin | 解析 modem SLOG 格式日志 | | `xbllog_unpack` | xbllog 文件 | 解析 XBL bootloader 日志 | | `logfs_unpack` | logfs 文件 | 解压 logfs 文件系统日志 | | `ftrace_console_parser` | gvmbootlog, gvmlog | 解析 ftrace 控制台日志 | | `archive_extractor` | .zip, .tar.gz, .7z | 解压归档文件 | **自动识别**：工具会根据文件名自动选择合适的解析工具，也可以通过 `-t` 参数手动指定。 --- ## 常用参数说明 ### 云端下载相关参数 | 参数 | 说明 | 示例 | |-----|------|------| | `--vin` | 车辆 VIN 码（必需） | `HLX33B124P1767770` | | `--happen-time` | 问题发生时间（必需） | `"2025-10-27 18:43"` | | `--log-type` | 日志类型（默认：log_HUF_Klog） | `log_HUF_kernel` | | `--time-range` | 时间范围，单位分钟（默认：±60） | `120` | | `--env` | 环境选择（默认：prod） | `prod`, `testtwo`, `ontest` | | `--task-type` | 任务类型/Flow ID | `1731484362257596488` | ### 本地处理相关参数 | 参数 | 说明 | 示例 | |-----|------|------| | `-u, --upload` | 要处理的文件路径 | `/path/to/log.bin` | | `-t, --tool` | 指定工具类型（可选） | `lastlog_unpack` | ### 通用参数 | 参数 | 说明 | 默认值 | |-----|------|--------| | `--server` | IssueFinder 服务器地址 | `https://issuefinder-playground-init-dev.inner.chj.cloud` | | `--output` | 输出目录 | `./results` | | `--timeout` | 超时时间（秒） | `300` | | `--poll-interval` | 轮询间隔（秒） | `30` | | `--verbose` | 显示详细输出 | - | | `--keep-env` | 保留云端环境（不自动清理） | - | | `--skip-version-check` | 跳过版本检查 | - | --- ## 常用日志类型 ### HUF（主机端）日志类型 - `log_HUF_Klog` - 主机 Kernel 日志（默认） - `log_HUF_kernel` - 主机内核日志 - `log_HUF_8155_android` - 8155 芯片 Android 日志 - `log_HUF_mcu` - MCU 日志 ### HUR（其他）日志类型 - `log_HUR_Klog` - HUR Kernel 日志 **提示**：不同日志类型包含的文件数量和类型不同，根据实际需求选择合适的类型。 --- ## 支持的时间格式 工具支持以下时间格式输入（会自动转换为标准格式）： ```bash # ISO 格式 2025-10-27T18:43 # 空格分隔（需要引号） "2025-10-27 18:43" "2025-10-27 18:43:00" # 斜杠分隔（需要引号） "2025/10/27 18:43" "2025/10/27 18:43:00" ``` --- ## 使用示例 ### 示例 1: 快速分析车辆故障 ```bash # 自动下载日志并分析重启原因 issuefinder-tool.py --issuefinder \ --vin HLX33B124P1767770 \ --happen-time "2025-10-27 18:43" ``` **输出**： - 分析结果：重启原因、最终结论 - 下载的日志文件 - 保存位置：`./results/` --- ### 示例 2: 下载指定时间范围的所有日志 ```bash # 下载前后 2 小时的日志 issuefinder-tool.py --direct-download \ --vin HLX14B175S1996368 \ --happen-time "2025-11-06 18:00" \ --time-range 120 \ --output ./my_logs ``` --- ### 示例 3: 处理本地压缩包中的日志 ```bash # 自动解压并识别处理所有日志文件 issuefinder-tool.py -u /path/to/vehicle_logs.zip --verbose # 指定特定工具处理 issuefinder-tool.py -t lastlog_unpack -u /path/to/logs.tar.gz ``` --- ### 示例 5: 批量处理多个文件 ```bash # 处理目录中的所有日志文件（通过脚本循环） for file in /path/to/logs/*; do issuefinder-tool.py -u "$file" --output ./results/$(basename "$file") done ``` --- ## 高级功能 ### 自动版本更新 工具会自动检查服务器版本并更新到最新版本： - 更新文件保存在：`~/.issuefinder/issuefinder-tool.py` - 可使用 `--skip-version-check` 跳过版本检查 ### 环境管理 - **自动清理**：默认完成后自动删除云端环境 - **保留环境**：使用 `--keep-env` 参数保留环境供后续使用 - **环境 ID**：工具会输出环境 ID，可用于调试 --- ## 故障排查 ### 常见问题 **1. 找不到文件或无法识别类型** ```bash # 使用 -t 参数手动指定工具类型 issuefinder-tool.py -t lastlog_unpack -u /path/to/file ``` **2. 云端下载失败** ```bash # 使用 --verbose 查看详细错误信息 issuefinder-tool.py --direct-download --vin XXX --happen-time "..." --verbose ``` **3. 环境清理失败** - 环境会在 1 小时不活动后自动清理 - 使用 `--keep-env` 可以保留环境供后续使用 **4. 连接超时** ```bash # 增加超时时间 issuefinder-tool.py -u file --timeout 600 ``` --- ## 最佳实践 1. **使用直接下载模式**：如果只需要日志文件，使用 `--direct-download` 比 `--cloud-log` 更快 2. **合理设置时间范围**：默认 ±60 分钟通常足够，特殊情况可扩大到 ±120 分钟 3. **启用详细输出**：调试时使用 `--verbose` 查看详细信息 4. **指定输出目录**：使用 `--output` 将不同任务的日志分开存储 5. **批量处理**：结合 Shell 脚本实现批量下载和处理 --- ## 相关资源 - **服务器地址**：`https://issuefinder-playground-init-dev.inner.chj.cloud` - **工具位置**：`.siada-cli/skills/issuefinder-tool/scripts/` - `issuefinder-tool.py` - 原始工具（从云端同步） - `issuefinder-tool-wrapper.py` - 包装脚本（推荐） - `iflog` - 便捷命令（推荐） - **默认输出目录**： - 原始工具：`./results/` - 包装脚本：`$ISSUEFINDER_LOGS_PATH/YYYY/MM/DD/` (已配置为 [REDACTED_SECRET]) - **更新位置**：`~/.issuefinder/issuefinder-tool.py` - **包装脚本文档**：[WRAPPER_USAGE.md](./WRAPPER_USAGE.md) --- ## 获取帮助 ```bash # 查看完整帮助信息 issuefinder-tool.py -h # 查看版本信息 issuefinder-tool.py --version ``` --- **最后更新**：2026-02-28

path: WRAPPER_USAGE.md
content: # IssueFinder Tool Wrapper 使用说明

## 概述

`issuefinder-tool-wrapper.py` 是对原始 `issuefinder-tool.py` 的包装脚本，用于自动管理日志输出路径，无需修改原始工具脚本。

## 功能特性

- ✅ **自动路径管理**：使用 `ISSUEFINDER_LOGS_PATH` 环境变量管理日志路径
- ✅ **日期分组**：自动按 `年/月/日` 创建目录结构
- ✅ **保持兼容**：完全兼容原始工具的所有参数和功能
- ✅ **灵活覆盖**：仍可通过 `--output` 参数指定自定义路径

## 环境变量

### ISSUEFINDER_LOGS_PATH

指定日志输出的基础路径。

**默认值**：`~/issuefinder_mcp_log`

**设置方法**：

```bash
# 临时设置（当前会话）
export ISSUEFINDER_LOGS_PATH="/your/custom/path"

# 永久设置（添加到 ~/.bashrc 或 ~/.zshrc）
echo 'export ISSUEFINDER_LOGS_PATH="/your/custom/path"' >> ~/.bashrc
source ~/.bashrc
```

## 目录结构

包装脚本会自动创建以下目录结构：

```
$ISSUEFINDER_LOGS_PATH/
├── 2026/
│   ├── 02/
│   │   ├── 26/
│   │   │   ├── VIN_HLX33B124P1767770/        # 云端下载日志
│   │   │   │   ├── lastlog
│   │   │   │   ├── minidump
│   │   │   │   └── ...
│   │   │   ├── vehicle_logs.zip/             # 本地处理日志
│   │   │   │   ├── parsed_lastlog.txt
│   │   │   │   └── ...
│   │   │   └── ...
│   │   └── 28/
│   └── ...
└── ...
```

## 使用方法

### 方法 1: 使用便捷命令 `iflog`

最简单的方式，推荐使用：

```bash
# 添加到 PATH（一次性设置）
export PATH="$PATH:/home/lixiang/git/bug-bye-bye-agent/.siada-cli/skills/issuefinder-tool/scripts"

# 或添加别名到 ~/.bashrc 或 ~/.zshrc
alias iflog='/home/lixiang/git/bug-bye-bye-agent/.siada-cli/skills/issuefinder-tool/scripts/iflog'

# 使用示例
iflog --direct-download --vin HLX33B124P1767770 --happen-time "2025-10-27 18:43"
iflog -u /path/to/lastlog_file
iflog --issuefinder --vin HLX33B124P1767770 --happen-time "2025-10-27 18:43"
```

### 方法 2: 直接调用包装脚本

```bash
python3 .siada-cli/skills/issuefinder-tool/scripts/issuefinder-tool-wrapper.py [参数]
```

### 方法 3: 直接调用原始工具（手动指定路径）

```bash
python3 .siada-cli/skills/issuefinder-tool/scripts/issuefinder-tool.py --output ~/issuefinder_mcp_log/2026/02/28 [其他参数]
```

## 使用示例

### 示例 1: 云端下载日志（自动按日期分组）

```bash
# 使用包装脚本，自动输出到 ~/issuefinder_mcp_log/2026/02/28/VIN_HLX33B124P1767770/
iflog --direct-download \
  --vin HLX33B124P1767770 \
  --happen-time "2025-10-27 18:43"

# 输出位置：$ISSUEFINDER_LOGS_PATH/2026/02/28/VIN_HLX33B124P1767770/
```

### 示例 2: 本地日志处理（自动按日期分组）

```bash
# 处理本地日志文件，自动输出到日期目录
iflog -u /path/to/vehicle_logs.zip

# 输出位置：$ISSUEFINDER_LOGS_PATH/2026/02/28/vehicle_logs.zip/
```

### 示例 3: IssueFinder 分析（自动按日期分组）

```bash
# 自动分析并下载日志
iflog --issuefinder \
  --vin HLX33B124P1767770 \
  --happen-time "2025-10-27 18:43"

# 输出位置：$ISSUEFINDER_LOGS_PATH/2026/02/28/VIN_HLX33B124P1767770/
```

### 示例 4: 覆盖默认路径（使用 --output）

```bash
# 即使使用包装脚本，仍可手动指定输出路径
iflog -u /path/to/logs.zip --output /custom/path

# 输出位置：/custom/path/logs.zip/
```

## 与原始工具的区别

| 特性 | 原始工具 | 包装脚本 |
|------|---------|---------|
| 默认输出路径 | `./results` | `$ISSUEFINDER_LOGS_PATH/YYYY/MM/DD/` |
| 日期分组 | ❌ 不支持 | ✅ 自动创建 |
| 环境变量支持 | ❌ 不支持 | ✅ 支持 ISSUEFINDER_LOGS_PATH |
| 参数兼容性 | - | ✅ 100% 兼容 |
| 手动指定路径 | ✅ 支持 | ✅ 支持（覆盖默认） |

## 工作原理

包装脚本的工作流程：

1. **读取环境变量**：获取 `ISSUEFINDER_LOGS_PATH`（默认 `~/issuefinder_mcp_log`）
2. **创建日期目录**：自动创建 `年/月/日` 目录结构
3. **传递参数**：如果没有指定 `--output`，自动添加 `--output <日期目录>`
4. **调用原始工具**：使用修改后的参数调用 `issuefinder-tool.py`
5. **透传结果**：将原始工具的输出和退出码透传回用户

## 推荐的 Shell 配置

将以下内容添加到 `~/.bashrc` 或 `~/.zshrc`：

```bash
# IssueFinder 日志工具配置
export ISSUEFINDER_LOGS_PATH="$HOME/issuefinder_mcp_log"
alias iflog='python3 /home/lixiang/git/bug-bye-bye-agent/.siada-cli/skills/issuefinder-tool/scripts/issuefinder-tool-wrapper.py'

# 或使用便捷脚本
alias iflog='/home/lixiang/git/bug-bye-bye-agent/.siada-cli/skills/issuefinder-tool/scripts/iflog'
```

重新加载配置：

```bash
source ~/.bashrc  # 或 source ~/.zshrc
```

## 故障排查

### 问题 1: 找不到原始工具脚本

**错误信息**：`错误: 找不到原始工具脚本`

**解决方法**：确保 `issuefinder-tool.py` 与包装脚本在同一目录

### 问题 2: 权限错误

**错误信息**：`Permission denied`

**解决方法**：
```bash
chmod +x .siada-cli/skills/issuefinder-tool/scripts/issuefinder-tool-wrapper.py
chmod +x .siada-cli/skills/issuefinder-tool/scripts/iflog
```

### 问题 3: 环境变量未生效

**解决方法**：确认环境变量已设置
```bash
echo $ISSUEFINDER_LOGS_PATH
```

如果为空，重新设置并 source 配置文件。

## 维护和更新

- ✅ **原始工具更新**：包装脚本无需修改，自动使用最新版本
- ✅ **云端同步**：原始 `issuefinder-tool.py` 可从云端同步更新
- ✅ **独立维护**：包装脚本与原始工具独立，互不影响

## 文件说明

```
.siada-cli/skills/issuefinder-tool/scripts/
├── issuefinder-tool.py           # 原始工具（从云端同步，不要修改）
├── issuefinder-tool-wrapper.py   # 包装脚本（本地维护）
├── iflog                          # 便捷命令脚本
└── WRAPPER_USAGE.md               # 本文档
```

---

**创建日期**：2026-02-28  
**维护者**：本地项目


path: scripts/issuefinder-tool-wrapper.py
content: #!/usr/bin/env python3
"""
IssueFinder Tool Wrapper
包装脚本，自动管理日志输出到 ISSUEFINDER_LOGS_PATH 环境变量指定的路径
默认路径：~/issuefinder_mcp_log
目录结构：年/月/日/VIN_xxx 或 年/月/日/文件名/
"""

import os
import sys
import subprocess
from datetime import datetime
from pathlib import Path


def get_base_log_dir():
    """获取基础日志目录"""
    base_dir = os.environ.get('ISSUEFINDER_LOGS_PATH', os.path.expanduser('~/issuefinder_mcp_log'))
    return base_dir


def get_dated_output_dir():
    """
    获取带日期结构的输出目录: base_dir/YYYY/MM/DD/
    """
    base_dir = get_base_log_dir()
    now = datetime.now()
    dated_path = os.path.join(base_dir, now.strftime("%Y"), now.strftime("%m"), now.strftime("%d"))
    os.makedirs(dated_path, exist_ok=True)
    return dated_path


def extract_output_subdir_from_args(args):
    """
    从命令行参数中提取输出子目录名称
    
    Args:
        args: 命令行参数列表
        
    Returns:
        str: 子目录名称，如 "VIN_xxx" 或本地文件名
    """
    # 检查是否是云端下载模式（有 --vin 参数）
    if '--vin' in args:
        vin_index = args.index('--vin')
        if vin_index + 1 < len(args):
            vin = args[vin_index + 1]
            return f"VIN_{vin}"
    
    # 检查是否是本地处理模式（有 -u 或 --upload 参数）
    if '-u' in args:
        upload_index = args.index('-u')
        if upload_index + 1 < len(args):
            file_path = args[upload_index + 1]
            return os.path.basename(file_path)
    
    if '--upload' in args:
        upload_index = args.index('--upload')
        if upload_index + 1 < len(args):
            file_path = args[upload_index + 1]
            return os.path.basename(file_path)
    
    # 默认使用时间戳
    return datetime.now().strftime("log_%Y%m%d_%H%M%S")


def main():
    """主函数"""
    # 获取原始 issuefinder-tool.py 的路径
    script_dir = os.path.dirname(os.path.abspath(__file__))
    original_tool = os.path.join(script_dir, 'issuefinder-tool.py')
    
    if not os.path.exists(original_tool):
        print(f"错误: 找不到原始工具脚本: {original_tool}")
        sys.exit(1)
    
    # 获取命令行参数（排除脚本名本身）
    args = sys.argv[1:]
    
    # 检查是否已经指定了 --output 参数
    has_output = '--output' in args or any(arg.startswith('--output=') for arg in args)
    
    # 如果没有指定 --output，则使用带日期结构的默认路径
    if not has_output:
        dated_dir = get_dated_output_dir()
        # 不在这里添加子目录，让原始脚本自己处理
        # 因为原始脚本会根据 VIN 或文件名创建子目录
        args = ['--output', dated_dir] + args
        print(f"[INFO] 使用默认输出目录: {dated_dir}")
    
    # 构建完整的命令
    cmd = [sys.executable, original_tool] + args
    
    # 执行原始工具
    try:
        result = subprocess.run(cmd, check=False)
        sys.exit(result.returncode)
    except KeyboardInterrupt:
        print("\n操作被用户中断")
        sys.exit(1)
    except Exception as e:
        print(f"错误: {e}")
        sys.exit(1)


if __name__ == "__main__":
    main()


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)