# 方向配置 JSON 格式说明

## 📋 概述

方向配置 JSON 文件是方向配置的完整导出格式，包含了方向的所有配置信息。可以通过导入这个 JSON 文件来快速创建或恢复方向配置。

---

## 📁 文件结构

JSON 文件采用扁平化结构，包含以下主要部分：

```json
{
  "id": "方向ID",
  "name": "方向名称",
  "icon": "图标名称",
  "description": "方向描述",
  "enabled": true/false,
  "sort_order": 数字,
  "form_fields": [...],           // 表单字段配置
  "form_layout": {...},            // 表单布局配置
  "output_config": {...},          // 输出配置
  "ui_config": {...},              // UI配置
  "advanced_config": {...},        // 高级配置
  "difficulties": {...}            // 难度配置（包含阶段和Prompt）
}
```

---

## 🔧 各配置项详解

### 1. 基础信息

```json
{
  "id": "web",                    // 方向ID（必填，唯一标识符，小写字母）
  "name": "Web 安全",              // 方向名称（必填，显示名称）
  "icon": "globe",                 // 图标名称（可选，FontAwesome图标）
  "description": "Web 应用安全漏洞题目...",  // 方向描述（可选）
  "enabled": true,                 // 是否启用（必填，true/false）
  "sort_order": 1                  // 排序顺序（可选，数字，越小越靠前）
}
```

**说明**：
- `id`：一旦创建不能修改，建议使用小写字母和数字，避免特殊字符
- `name`：会显示在题目生成页面，使用清晰易懂的名称
- `icon`：使用 FontAwesome 图标类名（不含 `fa-` 前缀）
- `enabled`：控制该方向是否在生成页面显示

---

### 2. 表单字段配置 (`form_fields`)

表单字段定义了用户在生成题目时需要填写的字段。

#### 字段基本结构

```json
{
  "id": "字段ID",                  // 必填，系统内部标识符
  "label": "字段标签",             // 必填，显示给用户的标签
  "type": "字段类型",              // 必填，见下方类型说明
  "required": true/false,          // 必填，是否强制填写
  "order": 数字,                   // 必填，显示顺序
  "visible": true/false,           // 可选，是否可见
  "hidden": false,                 // 可选，是否隐藏
  "readonly": false,               // 可选，是否只读
  "icon": "图标名称",              // 可选，字段图标
  "help_text": "帮助文本",         // 可选，字段说明
  "depends_on": {...},             // 可选，字段依赖关系
  "options": [...],                // 可选，选项列表（下拉选择/多选）
  "max_count_rules": {...}        // 可选，最大数量规则（多选字段）
}
```

#### 字段类型 (`type`)

| 类型值 | 说明 | 是否需要 `options` |
|--------|------|-------------------|
| `text` | 单行文本输入 | ❌ |
| `textarea` | 多行文本输入 | ❌ |
| `select` | 下拉选择（单选） | ✅ |
| `multiselect` | 多选（复选框） | ✅ |
| `multi_select_categorized` | 分类多选 | ✅ |
| `number` | 数字输入 | ❌ |
| `date` | 日期选择 | ❌ |

#### 字段依赖 (`depends_on`)

用于实现字段的显示/隐藏逻辑：

```json
{
  "depends_on": {
    "field": "language",           // 依赖的字段ID
    "condition": "not_empty"        // 条件：not_empty（不为空时显示）
  }
}
```

**支持的条件**：
- `not_empty`：依赖字段不为空时显示
- `count_gt_0`：依赖字段数量大于0时显示（用于多选字段）
- `equals`：依赖字段等于指定值时显示（需要配合 `value` 使用）

#### 选项配置 (`options`)

**简单选项**（用于 `select`）：

```json
{
  "options": [
    {
      "value": "Python",           // 选项值
      "label": "Python",           // 显示标签
      "icon": "fab fa-python"      // 图标（可选）
    }
  ]
}
```

**分类选项**（用于 `multi_select_categorized`）：

```json
{
  "options": [
    {
      "category": "注入类漏洞",     // 分类名称
      "items": [                   // 该分类下的选项
        {
          "value": "SQL注入",
          "label": "SQL注入"
        }
      ]
    }
  ]
}
```

#### 最大数量规则 (`max_count_rules`)

用于限制多选字段的最大选择数量：

```json
{
  "max_count_rules": {
    "source": "difficulty",        // 来源字段ID
    "mapping": {                   // 映射关系
      "入门": 1,
      "简单": 2,
      "中等": 3,
      "困难": 5
    }
  }
}
```

**说明**：根据 `difficulty` 字段的值，动态限制 `vulnerability` 字段的最大选择数量。

#### 完整字段示例

**示例1：编程语言选择（下拉选择）**

```json
{
  "id": "language",
  "label": "语言",
  "type": "select",
  "required": true,
  "order": 1,
  "visible": true,
  "icon": "code",
  "help_text": "选择题目使用的后端语言",
  "options": [
    {
      "value": "Python",
      "label": "Python",
      "icon": "fab fa-python"
    },
    {
      "value": "PHP",
      "label": "PHP",
      "icon": "fab fa-php"
    }
  ]
}
```

**示例2：漏洞类型（分类多选）**

```json
{
  "id": "vulnerability",
  "label": "漏洞类型",
  "type": "multi_select_categorized",
  "required": true,
  "order": 3,
  "visible": true,
  "icon": "bug",
  "depends_on": {
    "field": "difficulty",
    "condition": "not_empty"
  },
  "max_count_rules": {
    "source": "difficulty",
    "mapping": {
      "入门": 1,
      "简单": 2,
      "中等": 3,
      "困难": 5
    }
  },
  "options": [
    {
      "category": "注入类漏洞",
      "items": [
        {
          "value": "SQL注入",
          "label": "SQL注入"
        },
        {
          "value": "SSTI模板注入",
          "label": "SSTI模板注入"
        }
      ]
    }
  ]
}
```

---

### 3. 表单布局配置 (`form_layout`)

定义表单的布局结构，支持多行多列布局：

```json
{
  "form_layout": {
    "rows": [
      {
        "id": "row_1",             // 行ID
        "columns": 2,              // 列数（1-4）
        "fields": [                // 该行包含的字段ID列表
          "language",
          "difficulty"
        ]
      },
      {
        "id": "row_2",
        "columns": 2,
        "fields": [
          "vulnerability",
          "scene"
        ]
      }
    ]
  }
}
```

**说明**：
- `columns`：每行的列数，决定字段的宽度（1=全宽，2=半宽，3=三分之一，4=四分之一）
- `fields`：字段ID列表，必须与 `form_fields` 中的 `id` 对应

---

### 4. 输出配置 (`output_config`)

定义题目输出的相关配置：

```json
{
  "output_config": {
    "docker": true,                // 是否生成Docker文件
    "exp": true,                   // 是否生成exp.py
    "writeup": true,               // 是否生成writeup.md
    "attachment": false,          // 是否生成附件
    "directory_pattern": "{timestamp}_{name}",  // 目录命名模式
    "port_range": [42500, 42600], // 端口范围
    "flag_format": "DASCTF{...}"  // Flag格式
  }
}
```

**说明**：
- `directory_pattern`：支持变量 `{timestamp}`（时间戳）和 `{name}`（题目名称）
- `port_range`：Docker 容器的外部端口范围

---

### 5. UI配置 (`ui_config`)

定义生成页面的UI显示：

```json
{
  "ui_config": {
    "page_title": "CTF Web 题目生成向导",
    "page_description": "按顺序完成配置，快速生成高质量 CTF 题目",
    "generate_button": "开始生成",
    "reset_button": "重置",
    "primary_color": "#6366f1",    // 主色调（十六进制颜色）
    "secondary_color": "#ec4899"   // 次色调（十六进制颜色）
  }
}
```

---

### 6. 高级配置 (`advanced_config`)

包含系统提示词和全局规则：

```json
{
  "advanced_config": {
    "system_prompt": "",           // 系统提示词（可选）
    "global_rules": "## 🚫 禁止事项\n\n...",  // 全局规则（Markdown格式）
    "ai_timeout": 600,             // AI超时时间（秒）
    "docker_timeout": 300,         // Docker超时时间（秒）
    "max_retries": 3,              // 最大重试次数
    "retry_interval": 10           // 重试间隔（秒）
  }
}
```

**说明**：
- `global_rules`：全局规则会添加到所有阶段的 Prompt 前面
- `system_prompt`：系统提示词（已废弃，使用 `global_rules` 代替）

---

### 7. 难度配置 (`difficulties`)

这是最复杂的部分，包含了每个难度的阶段配置和 Prompt 配置。

#### 难度结构

```json
{
  "difficulties": {
    "入门": {                      // 难度名称（中文）
      "rules": {...},              // 难度规则
      "stages": [...]              // 阶段列表
    },
    "简单": {...},
    "中等": {...},
    "困难": {...}
  }
}
```

#### 难度规则 (`rules`)

```json
{
  "rules": {
    "max_count": 1,               // 最大漏洞数量
    "writeup_count": 5,            // writeup数量
    "depth_range": [1.5, 4.0],     // 深度范围 [最小值, 最大值]
    "diff_rate": 0.2               // 差异度要求（0-1之间）
  }
}
```

**说明**：
- `max_count`：该难度允许的最大漏洞数量
- `writeup_count`：从知识库获取的 writeup 数量
- `depth_range`：题目深度的范围，用于质量检查
- `diff_rate`：与现有题目的差异度要求（0.2=20%，0.5=50%）

#### 阶段配置 (`stages`)

每个阶段包含以下配置：

```json
{
  "id": "1",                       // 阶段ID（必填，字符串格式）
  "name": "用户输入需求",          // 阶段名称（必填）
  "order": 0,                      // 排序顺序（必填，数字，从0开始）
  "output": "语言、漏洞、场景、难度",  // 关键输出（可选）
  "prompt": "...",                 // 阶段Prompt内容（必填，Markdown格式）
  "required": true,                 // 是否必需（可选，true/false）
  "skip_forbidden": false,         // 是否禁止跳过（可选，true/false）
  "fixed_position": false,         // 是否固定位置（可选，true/false）
  "system_stage": false,           // 是否系统阶段（可选，true/false）
  "condition": "knowledge_count > 1",  // 显示条件（可选，表达式）
  "description": "...",            // 阶段描述（可选）
  "system_prompt": "...",          // 系统固定内容（可选）
  "user_extension": "",            // 用户扩展内容（可选，已废弃，使用prompt）
  "knowledge_script_path": "",     // 知识库脚本路径（可选）
  "output_format": "json"          // 输出格式（可选）
}
```

**重要字段说明**：

1. **`id`**：阶段ID，建议使用数字字符串（"1", "2", "3"）或带小数点的数字（"1.5"）
2. **`order`**：排序顺序，从0开始，决定阶段的执行顺序
3. **`prompt`**：阶段的详细指令，支持 Markdown 格式，可以使用变量（如 `{{language}}`）
4. **`condition`**：条件显示，例如 `"knowledge_count > 1"` 表示只有漏洞数量大于1时才显示该阶段
5. **`fixed_position`**：固定位置，通常用于阶段1（用户输入需求），不允许调整顺序
6. **`skip_forbidden`**：禁止跳过，通常用于质量检查阶段，确保AI不会跳过

#### 阶段 Prompt 变量

在 `prompt` 字段中可以使用以下变量：

| 变量 | 说明 | 示例值 |
|------|------|--------|
| `{{language}}` | 编程语言 | `Python`, `PHP` |
| `{{vulnerabilities}}` | 漏洞类型列表 | `SQL注入, XSS` |
| `{{difficulty}}` | 难度级别 | `入门`, `简单`, `中等`, `困难` |
| `{{scene}}` | 应用场景 | `支付平台`, `博客系统` |
| `{{category}}` | 方向名称 | `Web 安全` |
| `{{writeup_count}}` | writeup数量 | `5`, `10` |
| `{{max_knowledge}}` | 最大漏洞数 | `1`, `2`, `3`, `5` |
| `{{depth_range}}` | 深度范围 | `[1.5, 4.0]` |
| `{{difficulty_table}}` | 难度表格 | 自动生成 |

#### 完整阶段示例

```json
{
  "id": "3",
  "name": "知识库获取",
  "order": 2,
  "output": "选中的writeup列表",
  "prompt": "### 3.1 获取学习材料（必须使用 choice.py）\n\n```bash\npython3 data/scripts/choice.py --difficulty={{difficulty}} --count={{writeup_count}} \"{{vulnerabilities}}\"\n```\n\n**⚠️ 漏洞名称必须使用用户输入的完整名称，禁止简化或缩写！**\n",
  "required": true,
  "system_stage": true,
  "description": "根据用户输入和配置的脚本，从知识库中筛选并获取相关的知识点和 Writeup",
  "output_format": "json"
}
```

---

## 📝 编写 JSON 配置文件的步骤

### 步骤1：创建基础结构

```json
{
  "id": "your_category_id",
  "name": "你的方向名称",
  "enabled": true,
  "sort_order": 1,
  "form_fields": [],
  "form_layout": {
    "rows": []
  },
  "output_config": {
    "docker": true,
    "exp": true,
    "writeup": true,
    "directory_pattern": "{timestamp}_{name}",
    "port_range": [42500, 42600],
    "flag_format": "DASCTF{...}"
  },
  "ui_config": {
    "page_title": "CTF 题目生成向导",
    "generate_button": "开始生成"
  },
  "advanced_config": {
    "global_rules": "## 🚫 禁止事项\n\n..."
  },
  "difficulties": {}
}
```

### 步骤2：添加表单字段

按照需求添加字段，注意：
- 字段ID使用小写字母和下划线
- 必填字段设置 `"required": true`
- 下拉选择和多选需要配置 `options`

### 步骤3：配置表单布局

根据字段数量和显示需求，配置 `form_layout`：
- 每行最多4列
- 字段ID必须与 `form_fields` 中的ID对应

### 步骤4：配置难度和阶段

为每个难度（入门、简单、中等、困难）配置：
1. **难度规则**：`max_count`, `writeup_count`, `depth_range`, `diff_rate`
2. **阶段列表**：按顺序添加阶段，每个阶段包含 `id`, `name`, `order`, `prompt` 等

### 步骤5：编写阶段 Prompt

为每个阶段编写详细的 Prompt：
- 使用 Markdown 格式
- 使用变量引用表单字段值
- 明确说明该阶段的任务和要求

---

## ⚠️ 注意事项

### 1. JSON 格式要求

- 所有字符串必须用双引号 `"`，不能用单引号
- 最后一个属性后不能有逗号
- 数字和布尔值不需要引号
- 数组和对象格式要正确

### 2. 字段ID命名

- 使用小写字母
- 可以使用下划线 `_`
- 避免使用特殊字符和空格
- 保持简洁和有意义

### 3. 阶段配置

- 阶段ID建议使用数字字符串（"1", "2", "3"）
- `order` 从0开始，必须连续
- `prompt` 内容要详细，明确说明任务
- 最后一个阶段必须包含完成标记要求

### 4. 变量使用

- 变量格式：`{{变量名}}`
- 变量名必须与表单字段ID完全匹配（区分大小写）
- 系统变量（如 `{{writeup_count}}`）会自动替换

### 5. 难度配置

- 必须配置所有4个难度（入门、简单、中等、困难）
- 每个难度至少要有阶段1（用户输入需求）
- 阶段顺序要合理，符合生成流程

---

## 🔍 配置验证

在导入 JSON 文件前，建议检查：

1. **JSON 格式**：使用 JSON 验证工具检查格式是否正确
2. **必填字段**：确保所有必填字段都已填写
3. **字段ID唯一性**：确保 `form_fields` 中的 `id` 不重复
4. **阶段ID唯一性**：确保每个难度下的阶段 `id` 不重复
5. **变量引用**：确保 Prompt 中使用的变量在表单字段中存在
6. **阶段顺序**：确保 `order` 从0开始且连续

---

## 📚 完整示例

参考 `web_category_config_20260104_163348.json` 文件，它包含了：

- ✅ 4个表单字段（语言、难度、漏洞、场景）
- ✅ 2行2列的表单布局
- ✅ 完整的输出和UI配置
- ✅ 4个难度的完整配置（入门、简单、中等、困难）
- ✅ 每个难度10个阶段的详细 Prompt

---

## 🛠️ 导入和导出

### 导出配置

1. 在管理后台进入方向详情页面
2. 点击"导出"按钮
3. 系统会生成 JSON 文件供下载

### 导入配置

1. 在管理后台进入方向列表页面
2. 点击"导入"按钮
3. 选择 JSON 文件上传
4. 系统会自动解析并创建/更新方向配置

---

## 💡 最佳实践

1. **先配置基础信息**：确定方向ID和名称
2. **再配置表单字段**：根据需求设计字段
3. **然后配置阶段**：设计合理的生成流程
4. **最后编写 Prompt**：为每个阶段编写详细的指令
5. **测试验证**：导入后测试生成流程，确保配置正确

---

## 📖 相关文档

- [方向配置手册](./方向配置手册.md) - 详细的配置说明
- [方向配置快速参考](./方向配置快速参考.md) - 快速查阅指南

---

**最后更新**：2026-01-04  
**版本**：v1.0