# 7884结构归纳引擎 AI编码工具调用规范

## 一、规范说明

本文档专为第三方独立编码AI工具（如Cursor、CodeBuddy、Codeium及各类大厂编码助手）设计，旨在明确如何调用7884结构归纳引擎的可执行文件，理解其输出结果，并基于这些结果开发定制化工具。

目标读者：具备代码编写能力的AI助手或开发者，需要将7884引擎集成到自动化工作流中。

## 二、AI核心任务

1. 学会调用编译后的7884引擎可执行文件
2. 了解引擎输出的文件结构和内容
3. 学会如何使用这些输出结果开发定制化工具

## 三、引擎可执行文件调用指南

### 1. 调用形式

采用命令行（CLI）方式直接调用编译后的可执行文件，无复杂依赖、无网络交互、无SDK接入。

调用返回值（Exit Code）：
- `0` — 成功完成
- `1` — 执行失败（参数错误、文件不存在、分析失败等）

### 2. 结构归纳模式（完整参数列表）

```bash
7884_brain.exe --input <输入目录> --output <输出目录> [可选参数...]
```

**必填参数：**

| 参数 | 简写 | 说明 |
|------|------|------|
| `--input` | `-i` | 输入样本所在目录的绝对/相对路径，目录必须存在且包含至少1个有效文件 |
| `--output` | `-o` | 输出结果目录的绝对/相对路径，引擎会自动创建`output_YYYYMMDD_HHMMSS`子目录 |

**可选参数：**

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--mode full` | full | 完整模式：CPU结构分析 + GPU推理加速 |
| `--mode cpu-only` | — | 仅CPU模式：不使用GPU进行推理 |
| `--mode lightweight` | — | 轻量模式：跳过GPU推理，仅做基础结构分析 |

**输入目录要求：**
- 目录必须存在且可读
- 需包含至少1个二进制样本文件
- 推荐提供2~5个同格式样本以获得更好的分析结果
- 支持任意二进制格式（BMP、PNG、ZIP、PE、ELF等）
- 目录中的`.txt`、`.md`、`.log`等纯文本文件会被自动跳过
- 单个文件大小限制：建议不超过100MB

**路径规范：**
- 支持绝对路径（如 `C:\samples`）和相对路径（如 `.\samples`）
- 路径中包含空格时必须用双引号包裹（如 `"C:\My Samples\input"`）
- Windows路径分隔符使用 `\` 或 `/` 均可

### 3. Gen模式（模糊测试样本生成）

```bash
7884_brain.exe --Gen <xml_file> [-i N] [-o PATH] [-s SEED] [--engine basic|pro]
```

参数说明：
- `--Gen`: 启动Gen模式，后接Peach XML文件路径（必填）
- `-i, --iterations N`: 迭代次数（默认1000，无上限）
- `-o, --output PATH`: 输出路径模板，用 `{0}` 作占位符（默认：当前目录`fuzz_{0}.bin`）
- `-s, --seed N`: 随机种子（整数，相同种子可复现相同结果）
- `--range N,M`: 运行迭代N到M（从N开始到M结束，含两端）
- `--engine basic`: 15种变异策略（默认）
- `--engine pro`: 46种变异策略（终极版，含Havoc组合叠加、确定性遍历、字典注入等）

### 4. 典型工作流

```bash
# 步骤1：分析样本（完整模式）
7884_brain.exe --input C:\samples --output C:\output\result1

# 步骤2：从生成的Peach XML生成变异样本（Basic引擎）
7884_brain.exe --Gen "C:\output\result1\output_20260510_120000\example\format_schema_peach.xml" -i 10000 -o "C:\fuzz\{0}.bin"

# 步骤3：Pro终极版深度模糊测试
7884_brain.exe --Gen "C:\output\result1\output_20260510_120000\example\format_schema_peach.xml" --engine pro -i 50000 -o "C:\fuzz\{0}.bin"

# 步骤4：轻量模式快速分析（跳过GPU推理）
7884_brain.exe --input C:\samples --output C:\output\quick --mode lightweight
```

> **重要提示**：步骤2和步骤3中 `--Gen` 参数指向的XML文件路径必须使用步骤1实际生成的完整路径。输出目录结构见第四节。

## 四、引擎输出文件结构

引擎执行后，在 `--output` 指定的目录下自动创建时间戳子目录：
```
<output目录>/output_YYYYMMDD_HHMMSS/
```

该目录下包含以下文件：

### 1. 输出目录顶层文件

| 文件名 | 格式 | 用途 |
|--------|------|------|
| structure_report.html | HTML | 综合HTML报告（含所有分析结果，可在浏览器直接打开） |
| structure_report.json | JSON | JSON格式完整结构报告（含字段、关系、聚类、质量指标） |
| ai_verify.json | JSON | AI验证结果（字段预测准确率评估） |
| detailed_analysis_report.txt | 文本 | 详细分析报告（所有字段的偏移、大小、类型、置信度） |

### 2. example/ 子目录 — 结构化输出文件

| 文件名 | 格式 | 用途 |
|--------|------|------|
| format_schema.py | Python | 格式校验与修复脚本（可直接执行） |
| format_schema.bt | 010 Editor BT | 二进制模板（用于010 Editor人工分析） |
| format_schema_peach.xml | Peach XML | 模糊测试配置文件（供 --Gen 模式调用） |
| format_schema.ksy | Kaitai Struct | Kaitai Struct规则（可编译为Python/Java/C++等） |
| format_schema_final.json | JSON | 完整结构数据（字段详情/关系详情/质量指标） |
| format_schema.yar | YARA | YARA规则（用于恶意样本匹配检测） |

### 3. JSON输出结构 (format_schema_final.json)

```json
{
  "format_name": "BMP",
  "fields": 8,
  "relations": 3,
  "field_details": [
    {"name": "Signature", "type": "Blob", "offset": 0, "size": 2, "confidence": 0.95},
    {"name": "FileSize", "type": "DWORD", "offset": 2, "size": 4, "confidence": 0.90}
  ],
  "relation_details": [
    {"source": "FileSize", "target": "Data", "type": "size", "confidence": 0.85}
  ],
  "quality": {
    "overall": 0.82,
    "coverage": 0.75,
    "consistency": 0.90,
    "refutation": 0.80,
    "cross_validation": 0.85
  }
}
```

**质量指标说明：**
- `overall` (0.0~1.0): 综合质量评分，≥0.70为可用，≥0.85为可靠
- `coverage` (0.0~1.0): 样本覆盖度，表示已识别的字段占样本总字节的比例
- `consistency` (0.0~1.0): 跨样本一致性，表示不同样本间字段结构的一致程度
- `refutation` (0.0~1.0): 反证验证度，表示结构假设被反例验证的程度
- `cross_validation`: 交叉验证分数

**字段类型参考表：**
| 类型 | 说明 | 典型大小 |
|------|------|---------|
| Blob | 原始字节块 | 不定 |
| BYTE | 单字节整数 | 1 |
| WORD | 双字节整数 | 2 |
| DWORD | 四字节整数 | 4 |
| QWORD | 八字节整数 | 8 |
| Magic | 魔术字/签名 | 2~8 |
| StringZ | 零结尾字符串 | 不定 |
| Float | 单精度浮点 | 4 |
| Double | 双精度浮点 | 8 |
| GUID | 全局唯一标识符 | 16 |
| Timestamp | 时间戳 | 4~8 |

## 五、AI使用引擎结果的步骤

1. **执行引擎**：使用命令行调用7884_brain.exe，传入样本目录和输出目录
2. **检查返回码**：检查进程退出码，`0`=成功，`1`=失败（检查stderr获取错误信息）
3. **定位输出目录**：在output目录下找到最新的`output_YYYYMMDD_HHMMSS`子目录
4. **读取输出**：
   - 需要完整结构数据 → 读取 `example/format_schema_final.json`
   - 需要模糊测试 → 使用 `example/format_schema_peach.xml`
   - 需要人工分析 → 打开 `structure_report.html`
   - 需要格式校验 → 使用 `example/format_schema.py`
   - 需要恶意样本检测 → 使用 `example/format_schema.yar`
5. **分析结果**：根据需求选择合适的输出文件
6. **开发工具**：基于读取的结果开发定制化工具

## 六、常见应用场景

### 1. 模糊测试工具开发
- 使用format_schema_peach.xml作为模糊测试配置
- 基于format_schema.py添加自定义测试逻辑
- 使用--Gen模式直接生成变异样本

### 2. 恶意样本检测工具
- 使用format_schema.ksy提取特征规则
- 基于format_schema.bt分析样本结构特征

### 3. 文件格式校验工具
- 直接使用format_schema.py进行基础校验
- 基于structure_report.html理解文件结构

### 4. 漏洞分析辅助工具
- 使用format_schema.bt和format_schema_final.json进行结构分析
- 结合structure_report.html理解数据关系

## 七、变异引擎说明

| 特性 | Basic（默认） | Pro（终极版） |
|------|-------------|-------------|
| 变异策略数 | 15种 | 46种 |
| Havoc组合叠加 | 无 | 8~32层 |
| 确定性遍历 | 无 | 7阶段 |
| 字典/Token注入 | 无 | 16内置+可扩展 |
| 类型感知 | 否 | 是（尊重size/endian） |
| 整数溢出 | 无 | 8/16/32-bit |
| 魔术字替换 | 无 | 14种文件格式 |
| 命令 | 默认 | `--engine pro` |

## 八、错误处理与故障排除

### 1. 常见错误及含义

| 错误信息 | 原因 | 解决方法 |
|---------|------|---------|
| `Error: Failed to create sample analyzer` | 内存不足或内部错误 | 检查可用内存，重试 |
| `Error: Failed to load samples from directory: <path>` | 输入目录不存在或为空 | 确认目录存在且包含二进制文件 |
| `Reason: Directory does not exist or is not accessible` | 目录路径无效 | 检查路径拼写和权限 |
| `Reason: Directory is empty or contains no readable files` | 目录中无有效文件 | 放入二进制样本文件 |
| `Error: Failed to create CUDA manager` | GPU不可用但使用了full模式 | 改用`--mode cpu-only` |
| `Error: Failed to generate results` | 输出目录不可写 | 检查磁盘空间和写权限 |

### 2. 控制台输出说明

从v6起，引擎默认精简输出（仅显示警告和错误）。正常步骤进度不再打印到控制台。所有详细信息写入日志文件。

## 九、AI执行准则

1. **专注调用**：AI只需关注如何调用7884_brain.exe，无需了解其内部实现
2. **结果导向**：重点关注引擎输出的文件内容和结构，而非引擎内部函数
3. **工具开发**：基于引擎输出结果开发定制化工具，满足用户需求
4. **稳定性**：严格遵循命令行调用格式，确保调用稳定可靠
5. **结果复用**：充分利用引擎生成的结构化文件，减少重复开发
6. **文件名准确**：使用正确的输出文件名（format_schema_peach.xml而非fuzzer.xml等）
7. **错误处理**：始终检查进程退出码，0=成功，非0=失败（读取stderr获取具体原因）
8. **路径安全**：路径含空格时必须使用双引号包裹完整路径
9. **模式选择**：GPU不可用时应使用`--mode cpu-only`，避免CUDA初始化失败
10. **输出定位**：引擎在output目录下自动创建时间戳子目录，非直接在output目录写入文件
11. **样本准备**：至少2个同格式样本才能获得质量≥0.70的分析结果，推荐3~5个
12. **Gen模式依赖**：--Gen模式需要首先运行结构归纳模式生成Peach XML配置文件

> 引擎版本: v6 | 最后更新: 2026-05-10
