# JSON 配置示例解析

本文档基于 `web_category_config_20260104_163348.json` 文件，详细解析各项配置的含义和编写方法。

---

## 📋 文件概览

这是一个 **Web 安全方向**的完整配置，包含了：
- ✅ 4个表单字段（语言、难度、漏洞、场景）
- ✅ 2行2列的表单布局
- ✅ 完整的输出和UI配置
- ✅ 4个难度的完整配置（入门、简单、中等、困难）
- ✅ 每个难度10个阶段的详细 Prompt

---

## 🔍 逐项解析

### 1. 基础信息部分

```json
{
  "id": "web",                    // 方向ID：唯一标识符，用于系统内部识别
  "name": "Web 安全",              // 方向名称：显示在生成页面的标题
  "icon": "globe",                 // 图标：FontAwesome图标类名（globe = fa-globe）
  "description": "Web 应用安全漏洞题目...",  // 描述：方向的简要说明
  "enabled": true,                 // 启用状态：控制是否在生成页面显示
  "sort_order": 1                  // 排序：数字越小越靠前
}
```

**编写要点**：
- `id` 必须唯一，建议使用小写字母
- `name` 会显示给用户，要清晰易懂
- `enabled` 设为 `false` 可以临时禁用该方向

---

### 2. 表单字段配置详解

#### 字段1：语言选择（下拉选择）

```json
{
  "id": "language",               // 字段ID：在Prompt中使用 {{language}} 引用
  "label": "语言",                // 显示标签：用户看到的字段名称
  "type": "select",               // 字段类型：下拉选择
  "required": true,               // 必填：用户必须选择
  "order": 1,                     // 显示顺序：第1个字段
  "visible": true,                // 可见：显示在表单中
  "icon": "code",                 // 图标：字段前的图标
  "help_text": "选择题目使用的后端语言",  // 帮助文本：字段说明
  "options": [                    // 选项列表：下拉框的选项
    {
      "value": "Python",          // 选项值：实际存储的值
      "label": "Python",           // 显示标签：用户看到的文本
      "icon": "fab fa-python"      // 图标：选项前的图标（完整FontAwesome类名）
    }
  ]
}
```

**编写要点**：
- `id` 必须唯一，建议使用小写字母和下划线
- `options` 中的 `value` 会传递给 AI，`label` 只用于显示
- 图标使用 FontAwesome 完整类名（如 `fab fa-python`）

#### 字段2：难度级别（带依赖的下拉选择）

```json
{
  "id": "difficulty",
  "label": "难度级别",
  "type": "select",
  "required": true,
  "order": 2,
  "readonly": true,                // 只读：用户不能直接修改（可能由系统自动设置）
  "depends_on": {                  // 字段依赖：控制字段的显示/隐藏
    "field": "language",           // 依赖字段：当 language 字段有值时
    "condition": "not_empty"      // 条件：不为空时显示此字段
  },
  "options": [
    {
      "value": "入门",
      "label": "入门",
      "description": "最多1个漏洞，适合新手",  // 选项描述：鼠标悬停时显示
      "icon": "seedling"
    }
  ]
}
```

**编写要点**：
- `depends_on` 用于实现字段联动，例如：选择语言后才显示难度
- `readonly` 可以防止用户修改某些字段
- `description` 可以提供选项的额外说明

#### 字段3：漏洞类型（分类多选，带数量限制）

```json
{
  "id": "vulnerability",
  "label": "漏洞类型",
  "type": "multi_select_categorized",  // 类型：分类多选
  "required": true,
  "order": 3,
  "depends_on": {
    "field": "difficulty",
    "condition": "not_empty"
  },
  "max_count_rules": {            // 最大数量规则：根据难度限制选择数量
    "source": "difficulty",       // 来源字段：根据 difficulty 字段的值
    "mapping": {                   // 映射关系：难度 -> 最大数量
      "入门": 1,
      "简单": 2,
      "中等": 3,
      "困难": 5
    }
  },
  "options": [                    // 分类选项：按类别组织
    {
      "category": "注入类漏洞",   // 分类名称：显示为分组标题
      "items": [                   // 该分类下的选项
        {
          "value": "SQL注入",
          "label": "SQL注入"
        }
      ]
    }
  ]
}
```

**编写要点**：
- `multi_select_categorized` 适合选项很多的情况，可以按类别分组
- `max_count_rules` 实现动态限制，根据难度自动调整最大选择数
- `category` 和 `items` 结构用于组织大量选项

#### 字段4：应用场景（下拉选择）

```json
{
  "id": "scene",
  "label": "应用场景",
  "type": "select",
  "required": true,
  "order": 4,
  "depends_on": {
    "field": "vulnerability",
    "condition": "count_gt_0"     // 条件：漏洞数量大于0时显示
  },
  "options": [
    {
      "value": "none",            // 特殊值：表示"无场景"
      "label": "无场景",
      "icon": "ban"
    },
    {
      "value": "支付平台",
      "label": "支付平台",
      "icon": "university"
    }
  ]
}
```

**编写要点**：
- `count_gt_0` 用于多选字段，表示选择数量大于0时显示
- 可以提供一个"无场景"选项，允许用户不选择场景

---

### 3. 表单布局配置

```json
{
  "form_layout": {
    "rows": [
      {
        "id": "row_1",
        "columns": 2,              // 列数：2列布局（每个字段占50%宽度）
        "fields": [
          "language",              // 字段ID：必须与 form_fields 中的 id 对应
          "difficulty"
        ]
      },
      {
        "id": "row_2",
        "columns": 2,
        "fields": [
          "vulnerability",
          "scene"
        ]
      }
    ]
  }
}
```

**编写要点**：
- `columns` 决定每行的列数：1=全宽，2=半宽，3=三分之一，4=四分之一
- `fields` 数组中的字段ID必须与 `form_fields` 中的 `id` 完全匹配
- 字段会按照 `fields` 数组的顺序从左到右排列

---

### 4. 输出配置

```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配置

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

**编写要点**：
- 颜色使用十六进制格式（`#RRGGBB`）
- 按钮文本可以根据方向特点自定义

---

### 6. 高级配置

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

**编写要点**：
- `global_rules` 会添加到所有阶段的 Prompt 前面
- 超时时间根据题目复杂度调整
- 重试机制用于处理临时错误

---

### 7. 难度配置（重点）

#### 难度规则

```json
{
  "入门": {
    "rules": {
      "max_count": 1,             // 最大漏洞数：入门难度只允许1个漏洞
      "writeup_count": 5,          // writeup数量：从知识库获取5篇
      "depth_range": [1.5, 4.0],   // 深度范围：题目深度在1.5-4.0之间
      "diff_rate": 0.2             // 差异度：与现有题目差异度≥20%
    }
  }
}
```

**编写要点**：
- `max_count` 必须与表单字段中的 `max_count_rules` 保持一致
- `writeup_count` 建议：入门/简单=5，中等/困难=10
- `depth_range` 用于质量检查，确保题目难度符合要求
- `diff_rate` 控制创新性：0.2=20%，0.5=50%，0.7=70%

#### 阶段配置

每个阶段包含以下关键字段：

```json
{
  "id": "1",                      // 阶段ID：字符串格式，建议使用数字
  "name": "用户输入需求",         // 阶段名称：显示在进度条中
  "order": 0,                     // 排序：从0开始，决定执行顺序
  "output": "语言、漏洞、场景、难度",  // 关键输出：该阶段应该产生的内容
  "prompt": "...",                // Prompt内容：详细的AI指令（Markdown格式）
  "required": true,               // 是否必需：true表示不能跳过
  "fixed_position": true,        // 固定位置：不允许调整顺序
  "system_stage": true,          // 系统阶段：系统自动处理的阶段
  "skip_forbidden": false,        // 禁止跳过：通常用于质量检查阶段
  "condition": "knowledge_count > 1"  // 显示条件：只有满足条件时才显示
}
```

**阶段 Prompt 编写要点**：

1. **使用 Markdown 格式**：
   ```markdown
   ### 3.1 获取学习材料
   
   **步骤说明**：
   1. 第一步
   2. 第二步
   ```

2. **使用变量引用**：
   ```markdown
   语言：{{language}}
   漏洞：{{vulnerabilities}}
   难度：{{difficulty}}
   ```

3. **明确任务要求**：
   ```markdown
   **⚠️ 重要**：必须使用 choice.py 获取 writeup
   **禁止**：使用 WebSearch 工具
   ```

4. **提供输出格式示例**：
   ```markdown
   **输出格式**：
   ```markdown
   | 步骤 | 类型 | 技术点 | 深度 |
   |------|------|--------|------|
   ```
   ```

---

## 📝 编写 JSON 配置的步骤

### 步骤1：规划表单字段

1. 列出需要的字段（语言、难度、漏洞、场景等）
2. 确定每个字段的类型（文本、下拉、多选等）
3. 设计字段之间的依赖关系

### 步骤2：设计阶段流程

1. 确定需要哪些阶段
2. 规划阶段的执行顺序
3. 为每个阶段设计任务和目标

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

1. 从阶段1开始，逐个编写 Prompt
2. 使用变量引用表单字段值
3. 明确说明任务、步骤、输出格式

### 步骤4：配置难度规则

1. 为每个难度设置规则（漏洞数、writeup数、深度范围）
2. 根据难度调整阶段 Prompt 的详细程度
3. 确保难度规则与表单字段的 `max_count_rules` 一致

### 步骤5：测试验证

1. 导入 JSON 文件
2. 测试表单字段的显示和联动
3. 测试生成流程，检查 Prompt 是否正确

---

## ⚠️ 常见错误

### ❌ 错误1：字段ID不匹配

```json
// form_fields 中
{"id": "language", ...}

// form_layout 中
{"fields": ["Language"]}  // ❌ 错误：大小写不匹配
```

**正确**：
```json
{"fields": ["language"]}  // ✅ 正确
```

### ❌ 错误2：变量名不匹配

```json
// form_fields 中
{"id": "language", ...}

// prompt 中
"语言：{{Language}}"  // ❌ 错误：变量名大小写不匹配
```

**正确**：
```json
"语言：{{language}}"  // ✅ 正确
```

### ❌ 错误3：阶段order不连续

```json
{"id": "1", "order": 0},
{"id": "2", "order": 1},
{"id": "3", "order": 3}  // ❌ 错误：跳过了2
```

**正确**：
```json
{"id": "1", "order": 0},
{"id": "2", "order": 1},
{"id": "3", "order": 2}  // ✅ 正确
```

### ❌ 错误4：缺少完成标记要求

最后一个阶段的 Prompt 必须包含完成标记要求：

```json
{
  "id": "10",
  "name": "成品输出",
  "prompt": "...\n\n**⚠️ 完成所有任务后，必须输出**：\n```\n## [CTF_GENERATION_COMPLETE]\n```"
}
```

---

## 📚 参考资源

- **完整示例**：`web_category_config_20260104_163348.json`
- **配置手册**：[方向配置手册](./方向配置手册.md)
- **快速参考**：[方向配置快速参考](./方向配置快速参考.md)
- **JSON格式说明**：[方向配置JSON格式说明](./方向配置JSON格式说明.md)

---

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