feat: 添加 trace 结构清理脚本与产物

[xy200303]

概述

本 PR 针对 #5 新增一套保守的 trace 结构异常检测与修复流程，用于清理 data/entries.jsonl 中部分尚未人工校验样本的调用链结构问题。

主要变更：

• 新增 scripts/trace_structure_cleanup.py，支持 check 和 fix 两种模式。
• 检测 {file, line, code} 完全相同的重复 trace 节点。
• 检测同一文件内早于 entry_point 或晚于 critical_operation 的 trace 节点。
• 支持整数行号和 "start-end" 区间行号。
• 对跨文件 trace 节点保留原始顺序，不按行号简单排序。
• 新增保守修复产物：
  • data/entries.trace_fixed.jsonl
  • reports/trace_structure_fix_log.csv
  • reports/trace_structure_fix_log.jsonl
  • reports/trace_structure_report.md
• 新增 scripts/README_trace_structure_cleanup.md，说明运行方式、处理策略和限制。
• 新增 tests/test_trace_structure_cleanup.py，覆盖重复节点、desc 冲突、区间行号、跨文件跳过、保守修复和 bounds 修复策略。

为什么这样做

trace 字段用于描述从 entry_point 到 critical_operation 的证据链，是 VulnGym 作为白盒漏洞检测 benchmark 的关键 ground truth。当前部分 verify = 0 数据中存在结构性噪声，例如：

• trace 内部存在完全重复节点；
• 同一文件内 trace 节点出现在入口点之前；
• 同一文件内 trace 节点出现在关键操作之后；
• 行号既可能是整数，也可能是 "start-end" 区间；
• 跨文件调用链不能简单按行号排序，否则可能破坏真实调用语义。

如果这些问题直接进入评测，会影响调用链解释质量，也会增加后续人工审核成本。因此本 PR 的目标不是激进重写 trace，而是提供一套可复现、可审计、默认保守的清理工具：完整扫描和记录问题，只自动修复确定性较强的场景，把模糊情况留给人工复核。

设计取舍

1. 默认保守，不重排 trace

脚本不会对 trace 做排序。原因是 trace 表达的是跨函数、跨文件、跨模块的调用或数据传播链，而不是单文件内的源码顺序。简单按行号重排可能让跨文件调用链变得错误。

因此，本 PR 只在 trace 节点和 entry_point / critical_operation 位于同一文件时进行行号边界比较；跨文件节点保持原始顺序。

2. 默认只修复 verify = 0

verify = 1 数据已经通过人工审计，自动修改风险更高。默认 fix 模式只作用于 verify = 0 样本。

如果维护者希望扩大修复范围，可以显式执行：

python scripts/trace_structure_cleanup.py --mode fix --fix-verify all

3. critical_operation 之后的节点默认只记录

同一文件内晚于 critical_operation 的 trace 节点虽然可疑，但不一定总是错误。有些标注可能把 critical operation 定位到核心表达式，同时在 trace 中保留外层块、调用上下文或收尾语义。

为避免误删有价值的上下文，默认策略只将这类节点记录为人工复核项。

如果维护者希望采用更严格的边界修复策略，可以执行：

python scripts/trace_structure_cleanup.py --mode fix --order-policy bounds

4. 重复节点默认采用 safe 策略

当两个 trace 节点的 {file, line, code} 完全一致时，脚本会将其视为重复候选。但如果两个节点的 desc 不一致，说明标注者可能试图表达不同语义阶段。

因此默认 safe 策略会保留这类节点并写入人工复核日志，避免丢失解释信息。

如果维护者确认只需要按结构去重，可以执行：

python scripts/trace_structure_cleanup.py --mode fix --duplicate-policy drop-all

修复结果

使用默认保守修复策略运行：

python scripts/trace_structure_cleanup.py --mode fix

扫描结果：

• entries scanned: 408
• trace nodes scanned: 2073
• log events: 402
• changed entries: 2
• input schema errors: 0
• output schema errors: 0

默认自动修复了 2 个确定性越界 trace 节点：

• entry-00103
• entry-00320

issue 中点名的样本处理结果如下：

Entry	处理方式
entry-00103	删除同文件内早于 entry point 的确定性越界节点。
entry-00320	删除同文件内早于 entry point 的确定性越界节点。
entry-00185	检测到晚于 critical operation 的节点，默认记录为人工复核。
entry-00511	检测到 entry 边界重叠、post-critical、critical 边界重叠等情况，默认记录为人工复核。

这种处理方式可以先消除低风险结构噪声，同时避免对仍可能具有语义价值的 trace 节点做不可逆删除。

重复 PR 检查

已检查当前开放 PR，发现已有多个 PR 也在处理 issue #5，包括 #9、#10、#17、#18、#22 等。

本 PR 仍基于 main 独立提交，主要差异是：

• 默认策略更保守，避免对跨文件调用链和 post-critical 节点做激进修改。
• 自动修复范围默认限制在 verify = 0。
• 同时输出 CSV 和 JSONL 字段级日志，方便人工审核和脚本消费。
• 将 check / fix、重复节点处理策略、顺序边界修复策略设计为可配置参数。
• 新增单元测试覆盖关键边界条件，便于后续维护。

验证

已运行：

python -m unittest discover -s tests -p 'test_*.py'
python scripts\trace_structure_cleanup.py --mode check
python scripts\trace_structure_cleanup.py --mode fix
python scripts\trace_structure_cleanup.py --mode check --input data\entries.trace_fixed.jsonl --log-csv reports\trace_structure_fixed_check_log.tmp.csv --log-jsonl reports\trace_structure_fixed_check_log.tmp.jsonl --report reports\trace_structure_fixed_check_report.tmp.md
python examples\load_dataset.py
python -m py_compile scripts\trace_structure_cleanup.py
git diff --cached --check

验证结果：

• 12 个单元测试全部通过。
• 原始数据和修复后数据的 schema 校验错误数均为 0。
• examples/load_dataset.py 可正常加载 184 reports / 408 entries。
• 对 data/entries.trace_fixed.jsonl 再次执行 check，不会产生新的结构修改。
• git diff --cached --check 无 whitespace 错误。

Closes #5