# crash_locator

**Repository Path**: rvsmart-porting/crash_locator

## Basic Information

- **Project Name**: crash_locator
- **Description**: Crash Locator for Java Program
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-04-30
- **Last Updated**: 2025-10-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Crash Locator

Crash Locator 是一款面向 RISC-V 适配场景的 Java 崩溃报告智能过滤与定位工具。它位于 CrashTracker 等静态分析系统之后，通过预处理、调用图补全、语义约束推理和混合式候选过滤等模块，为开发者提供高置信度的缺陷候选及解释，并输出完整的运行统计与对话追溯数据。

## 项目结构

```text
repo_root/
├── crash_locator/
│   ├── __init__.py
│   ├── __main__.py            # uv run -m crash_locator 的入口
│   ├── config.py              # 配置项、路径与缓存设定
│   ├── exceptions.py          # 自定义异常定义
│   ├── my_types.py            # Pydantic 数据结构与统计模型
│   ├── pre_check.py           # 预处理流水线
│   ├── prompt.py              # LLM Prompt 模板
│   ├── run.py                 # 候选过滤主流程（异步调度）
│   ├── types/                 # LLM API 类型定义
│   └── utils/                 # 解析、调用图、LLM 交互等工具集
├── Data/                      # 运行时生成（包含 resources/、pre_check/、results/）
├── figures/                   # 项目文档中使用的截图
└── README.md
```

> `Data/` 目录不会随仓库提交，运行流程会按需创建其中的 `cache/`、`pre_check/`、`results/<日期>/` 等子目录。

## 环境准备

- Python ≥ 3.11
- [uv](https://docs.astral.sh/uv/)（推荐作为依赖管理与运行工具）
- C/C++ 编译环境（tree-sitter 相关依赖在首次安装时需要）

## 配置说明

`config.Config` 通过环境变量（或 `.env` 文件）驱动，命名均为小写加前缀 `crash_locator_`。建议至少配置以下字段：

| 配置项 | 默认值 | 说明 |
| --- | --- | --- |
| `crash_locator_preset` | `None` | 预设方案，支持 `baseline`（关闭高阶能力）与 `full`（全部功能开启）。设置后会自动填充下列布尔开关。 |
| `crash_locator_enable_extract_constraint` | – | 是否启用语义约束提取。未使用 `preset` 时需显式指定。 |
| `crash_locator_enable_notes` | – | 是否在输出中附带说明文本。 |
| `crash_locator_enable_candidate_reason` | – | 是否记录每个候选的判定理由。 |
| `crash_locator_enable_candidate_correction` | – | 是否启动候选纠偏与补充机制。 |
| `crash_locator_openai_base_url` | – | OpenAI 兼容接口地址。 |
| `crash_locator_openai_api_key` | – | OpenAI API Key。 |
| `crash_locator_openai_model` | – | 模型名称，例如 `gpt-4.1-mini`。 |
| `crash_locator_reasoning_effort` | `None` | （可选）启用 Reasoning 模型时指定推理级别。 |
| `crash_locator_max_workers` | `4` | 并发任务数量。可在命令行通过 `--max-workers` 覆盖。 |
| `crash_locator_result_dir_name` | 当日日期 | 结果输出目录名称。 |
| `crash_locator_resources_dir_name` | `resources` | `Data/` 下资源目录名，可在多数据源场景切换。 |
| `crash_locator_crash_reports_dir_name` | `all-0427` | 崩溃报告子目录名。 |
| `crash_locator_debug` | `False` | 调试模式，仅处理 `crash_locator_debug_pre_check_reports` 列表中的报告。 |
| `crash_locator_retry_failed_reports` | `True` | 是否在下次运行时重试失败的报告。 |

示例 `.env`：

```ini
crash_locator_preset=full
crash_locator_openai_base_url=https://api.openai.com/v1
crash_locator_openai_api_key=sk-***
crash_locator_openai_model=gpt-4.1-mini
```

> 配置也可通过命令行传参（例如 `uv run -m crash_locator --preset full --max-workers 8`），CLI 参数的命名与环境变量保持一致，使用中划线形式。

## 数据准备

请在 `Data/resources` 下放置运行所需的静态数据：

- `crash_reports/<数据集名>/`: CrashTracker 等工具导出的原始崩溃报告（JSON）。
- `android_code/platform_frameworks_base-android-<version>_r1/`: 对应版本的 Android 源码，至少包含 `core/java` 与 `location/java` 等子目录。
- `android_support_code/src/`: Android Support 代码。
- `application_code/<apk_name>/sources/`: 应用源码及 `resources/AndroidManifest.xml`、`resources/res/values/strings.xml`。
- `android_cg/android<version>/android<version>_cg.txt`: Android 框架调用图。
- `apk_cg/<apk_name>/<apk_name>_cg.txt`: 应用调用图。

路径命名可通过前述配置项灵活调整。

## 快速开始

### 1. 预处理（Pre-check）

```bash
uv run -m crash_locator.pre_check --preset baseline
```

- 自动读取 `Data/resources/crash_reports`，补全调用栈并生成标准化 `report_info.json`。
- 输出位于 `Data/pre_check/`：包含 `reports/<报告名>/report_info.json`、`statistic.json` 以及 `app.log`。
- 使用 `--debug true --debug-pre-check-reports <report_name>` 可仅处理指定样本。

### 2. 候选过滤主流程

```bash
uv run -m crash_locator --preset full --max-workers 8
```

- 读取预处理结果，按需异步调度 LLM 对话与启发式过滤。
- 若单报告仅有一条候选，将自动标记为 `skipped` 并跳过昂贵推理。
- 运行产物存放于 `Data/results/<结果目录名>/`，包括：
  - `statistic.json`：整体指标（候选数量、过滤率、token 使用量等）。
  - `reports/<报告名>/`: 原始报告、标准化结果、保留候选与 LLM 对话记录。
  - `app.log`：结合 `setup_logging` 输出的详细流水日志。

### 3. 常用命令行参数

| 参数 | 作用 | 示例 |
| --- | --- | --- |
| `--preset` | 切换能力组合，自动设置布尔开关。 | `--preset baseline` |
| `--enable-extract-constraint` | 开启/关闭语义约束提取。 | `--enable-extract-constraint true` |
| `--enable-notes` | 是否生成辅助说明。 | `--enable-notes false` |
| `--enable-candidate-reason` | 是否输出候选判定理由。 | `--enable-candidate-reason true` |
| `--enable-candidate-correction` | 控制候选纠偏流程。 | `--enable-candidate-correction true` |
| `--max-workers` | 并发任务数量。 | `--max-workers 8` |
| `--result-dir-name` | 自定义结果目录。 | `--result-dir-name 20240930-full` |
| `--debug` | 启用调试模式。 | `--debug true` |

布尔参数需显式指定 `true` 或 `false`；命令行传参优先级高于 `.env`。

## 后续路线图

- [ ] 构建领域数据集，微调轻量 LLM 并支持本地推理，以进一步优化成本与响应时间。
- [ ] 扩展到 JNI / native 代码解析，使跨语言调用同样纳入约束推理。
- [ ] 封装标准 CLI/服务接口，与 CI/CD 流水线集成并自动推送缺陷摘要。