# CTF 方向配置手册

## 📋 目录

1. [概述](#概述)
2. [配置入口](#配置入口)
3. [基础信息配置](#基础信息配置)
4. [表单设计](#表单设计)
5. [阶段配置](#阶段配置)
6. [Prompt 模板配置](#prompt-模板配置)
7. [知识库配置](#知识库配置)
8. [配置验证与测试](#配置验证与测试)
9. [常见问题](#常见问题)
10. [最佳实践](#最佳实践)

---

## 概述

方向配置是 CTF 题目生成系统的核心配置，它定义了：
- **方向类型**：如 Web 安全、PWN、Reverse、Crypto 等
- **生成流程**：题目生成的各个阶段及其顺序
- **AI 指导**：每个阶段的具体 Prompt 指令
- **用户输入**：题目生成时需要的表单字段

每个方向都有独立的配置，互不影响。

---

## 配置入口

### 访问路径

1. 登录系统后，进入 **管理后台**
2. 点击左侧菜单的 **方向管理**
3. 选择要配置的方向，或创建新方向

### 权限说明

- **管理员**：可以配置所有方向
- **方向管理员**：只能配置被分配的方向
- **查看者**：只能查看配置，不能修改

---

## 基础信息配置

### 配置项说明

| 配置项 | 说明 | 必填 | 示例 |
|--------|------|------|------|
| **方向ID** | 唯一标识符，用于系统内部识别 | ✅ | `web`, `pwn`, `reverse` |
| **方向名称** | 显示名称 | ✅ | `Web 安全`, `PWN`, `逆向工程` |
| **方向描述** | 简要描述该方向的特点 | ❌ | `Web 安全方向的题目配置` |
| **排序顺序** | 在列表中的显示顺序 | ❌ | `1`, `2`, `3` |
| **是否启用** | 是否允许使用该方向生成题目 | ✅ | `是` / `否` |

### 配置步骤

1. 在方向列表页面，点击 **创建新方向** 或选择现有方向
2. 填写基础信息
3. 点击 **保存**

### 注意事项

- **方向ID** 一旦创建不能修改，请谨慎填写
- 方向ID 建议使用小写字母和数字，避免特殊字符
- 方向名称会显示在题目生成页面，请使用清晰易懂的名称

---

## 表单设计

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

### 字段类型

系统支持以下字段类型：

| 字段类型 | 说明 | 适用场景 |
|----------|------|----------|
| **文本输入** | 单行文本 | 场景名称、额外要求等 |
| **多行文本** | 多行文本 | 详细描述、特殊要求等 |
| **下拉选择** | 单选下拉框 | 编程语言、难度级别等 |
| **多选** | 多选复选框 | 漏洞类型（可多选） |
| **数字输入** | 数字 | 数量、端口号等 |
| **日期选择** | 日期 | 截止日期等 |

### 配置步骤

1. 进入方向详情页面，点击 **表单设计** 标签
2. 点击 **添加字段** 按钮
3. 配置字段属性：
   - **字段名称**：显示给用户的标签
   - **字段ID**：系统内部使用的标识符
   - **字段类型**：选择上述类型之一
   - **是否必填**：是否强制用户填写
   - **默认值**：字段的默认值（可选）
   - **选项列表**：对于下拉选择和多选，需要配置选项
4. 拖拽字段调整顺序
5. 点击 **保存**

### 字段配置示例

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

```json
{
  "id": "language",
  "label": "编程语言",
  "type": "select",
  "required": true,
  "options": [
    {"value": "Python", "label": "Python"},
    {"value": "PHP", "label": "PHP"},
    {"value": "Node.js", "label": "Node.js"},
    {"value": "Java", "label": "Java"}
  ],
  "default": "Python"
}
```

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

```json
{
  "id": "vulnerabilities",
  "label": "漏洞类型",
  "type": "multiselect",
  "required": true,
  "options": [
    {"value": "SQL注入", "label": "SQL注入"},
    {"value": "XSS", "label": "XSS"},
    {"value": "文件上传", "label": "文件上传"},
    {"value": "反序列化", "label": "反序列化"}
  ]
}
```

#### 示例3：场景描述（文本输入）

```json
{
  "id": "scene",
  "label": "应用场景",
  "type": "text",
  "required": true,
  "placeholder": "例如：支付平台、博客系统、OA系统"
}
```

### 字段变量使用

在 Prompt 配置中，可以使用 `{{字段ID}}` 来引用表单字段的值。

例如：
- `{{language}}` - 获取用户选择的编程语言
- `{{vulnerabilities}}` - 获取用户选择的漏洞类型列表
- `{{scene}}` - 获取用户输入的场景描述

---

## 阶段配置

阶段配置定义了题目生成的流程，每个阶段代表生成过程中的一个步骤。

### 阶段结构

每个阶段包含以下配置：

| 配置项 | 说明 | 必填 |
|--------|------|------|
| **阶段ID** | 阶段的唯一标识符 | ✅ |
| **阶段名称** | 显示名称 | ✅ |
| **阶段描述** | 该阶段的作用说明 | ❌ |
| **关键输出** | 该阶段应该产生的关键输出 | ❌ |
| **是否可跳过** | 是否允许 AI 跳过该阶段 | ❌ |
| **是否必需** | 该阶段是否必需执行 | ❌ |

### 配置步骤

1. 进入方向详情页面，点击 **阶段配置** 标签
2. 点击 **添加阶段** 或编辑现有阶段
3. 填写阶段信息
4. 调整阶段顺序（拖拽）
5. 点击 **保存**

### 标准阶段流程（Web 方向示例）

| 阶段ID | 阶段名称 | 说明 |
|--------|----------|------|
| 1 | 用户输入需求 | 确认用户输入的语言、难度、漏洞、场景等 |
| 2 | 漏洞主次分类 | 区分主漏洞和辅助漏洞（如果难度允许多个漏洞） |
| 3 | 知识库获取 | 从知识库中获取相关的 writeup 和知识点 |
| 4 | 知识模块化与映射 | 整理知识库内容，提取关键技巧 |
| 5 | 题目设计 | 设计题目的利用链、故事背景等 |
| 6 | 质量检查与优化 | 检查题目质量，确保可解性和趣味性 |
| 7 | 代码生成与验证 | 生成题目代码，确保代码可运行 |
| 8 | Docker 环境构建 | 构建 Docker 容器环境 |
| 9 | exp 和 writeup | 生成 exploit 脚本和 writeup 文档 |
| 10 | 成品输出 | 整理最终输出，确保文件完整 |

### 阶段顺序调整

- 使用拖拽功能调整阶段顺序
- 阶段顺序会影响生成流程的执行顺序
- 建议按照逻辑顺序排列：需求确认 → 知识获取 → 设计 → 实现 → 测试 → 输出

### 注意事项

- **阶段ID** 建议使用数字（1, 2, 3...）或带小数点的数字（1, 1.5, 2...）
- 阶段名称要清晰描述该阶段的作用
- 关键输出字段用于提示 AI 该阶段应该产生什么内容

---

## Prompt 模板配置

Prompt 模板是指导 AI 生成题目的核心配置，包括系统提示词和各阶段的详细指令。

### 配置结构

Prompt 配置分为两部分：

1. **系统提示词**：全局规则，适用于所有阶段
2. **阶段 Prompt**：每个阶段的具体指令

### 系统提示词配置

系统提示词定义了全局规则，包括：

- **禁止事项**：AI 不应该做的事情
- **关键信息保持**：需要在整个生成过程中保持一致的信息
- **输出格式要求**：文件命名、目录结构等

#### 配置步骤

1. 进入方向详情页面，点击 **Prompt 模板** 标签
2. 在 **系统提示配置** 区域编辑内容
3. 点击 **保存**

#### 系统提示词模板示例

```markdown
## 🚫 禁止事项

**禁止词汇**：
- "由于篇幅/时间/上下文限制" "直接进入" "快速实现" "跳过" "省略"

**禁止行为**：
- 跳过任何阶段（特别是质量检查阶段）
- 只输出标题而无实际内容
- 通过降低难度来解决技术问题

**✅ 你有无限的时间和空间，直接执行，不要解释**

---

## ⚠️ 关键信息保持

1. **题目名称**：一旦确定，后续所有文件必须使用相同名称
2. **利用链设计**：设计阶段的步骤必须在代码生成阶段完整实现
3. **关键 payload**：设计的 payload 必须与代码中的过滤逻辑兼容
4. **输出目录**：所有文件保存到 `output/{YYYYMMDD_HHMMSS}_{题目名称}/`
```

### 阶段 Prompt 配置

每个阶段可以配置独立的 Prompt，包括：

- **系统固定内容**：系统自动生成的固定指令（可选）
- **用户扩展内容**：管理员自定义的详细指令

#### 配置步骤

1. 在 **Prompt 模板** 标签页，找到 **基于难度的 Prompt 配置** 区域
2. 选择要配置的难度（入门、简单、中等、困难）
3. 展开要配置的阶段
4. 在文本框中编辑该阶段的 Prompt 内容
5. 点击 **保存**

#### 阶段 Prompt 示例

**阶段 3：知识库获取**

```markdown
## 任务目标

从知识库中获取与以下漏洞相关的 writeup：
- 漏洞类型：{{vulnerabilities}}
- 难度级别：{{difficulty}}

## 执行步骤

1. 使用 `data/scripts/choice.py` 脚本从知识库中选择相关 writeup
2. 命令格式：`python3 data/scripts/choice.py --difficulty={{difficulty}} --count=5 "{{vulnerabilities}}"`
3. 读取选中的 writeup 文件，提取关键技巧
4. 总结每个 writeup 的核心知识点

## 输出要求

- 列出选中的 writeup 文件名
- 提取每个 writeup 中的关键代码片段
- 总结可借鉴的技巧
```

**阶段 5：题目设计**

```markdown
## 设计目标

设计一个符合以下要求的 CTF 题目：
- 难度：{{difficulty}}
- 漏洞：{{vulnerabilities}}
- 场景：{{scene}}
- 语言：{{language}}

## 设计要点

1. **利用链设计**：设计清晰的利用步骤，每个步骤要有明确的技术点
2. **故事背景**：设计合理的业务场景，让题目更有趣味性
3. **难度控制**：确保题目难度符合 {{difficulty}} 级别的要求
4. **创新性**：与现有题目保持差异度 ≥20%

## 输出格式

请按照以下格式输出：

### 利用链设计
| 步骤 | 类型 | 技术点 | 深度 |
|------|------|--------|------|
| Step 1 | ... | ... | ... |

### 故事背景
...

### 核心代码预写
...
```

### 变量使用

在 Prompt 中可以使用以下变量：

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

### 完整 Prompt 预览

配置完成后，可以点击 **完整 Prompt 预览** 按钮查看最终编译后的完整 Prompt。

预览会显示：
- 系统提示词
- 任务流程表格
- 每个阶段的详细指令
- 所有变量替换后的内容

### 注意事项

1. **阶段标记格式**：AI 必须输出 `阶段X：阶段名称` 来标识当前阶段
2. **完成标记**：最后一个阶段完成后，AI 必须输出 `## [CTF_GENERATION_COMPLETE]`
3. **变量替换**：变量会在运行时自动替换，无需手动处理
4. **Markdown 格式**：Prompt 支持 Markdown 格式，可以使用标题、列表、代码块等

---

## 知识库配置

知识库存储了用于学习参考的 writeup 和知识点。

### 知识库结构

知识库文件存储在 `ge10/{方向ID}/data/` 目录下：

```
ge10/web/data/
├── writeups/          # writeup 文件目录
│   ├── writeup1.md
│   ├── writeup2.md
│   └── ...
├── scripts/          # 知识库选择脚本
│   └── choice.py     # 从知识库中选择 writeup 的脚本
└── .augmentignore    # Augment 忽略文件配置
```

### 知识库文件管理

1. 进入方向详情页面，点击 **知识库** 标签
2. 使用文件浏览器上传或管理文件
3. 支持的操作：
   - **上传文件**：点击上传按钮选择文件
   - **创建目录**：创建新的文件夹
   - **删除文件**：删除不需要的文件
   - **查看文件**：查看文件内容

### writeup 文件格式

writeup 文件建议使用 Markdown 格式，包含以下内容：

- **题目信息**：题目名称、难度、类型等
- **解题思路**：详细的解题步骤
- **关键代码**：exploit 代码片段
- **知识点总结**：涉及的技术点

### choice.py 脚本

`choice.py` 脚本用于从知识库中选择相关的 writeup。

#### 脚本参数

- `--difficulty`: 难度级别（入门、简单、中等、困难）
- `--count`: 选择的数量
- 位置参数：漏洞类型关键词

#### 使用示例

```bash
python3 data/scripts/choice.py --difficulty=入门 --count=5 "SQL注入"
```

#### 脚本输出

脚本会输出选中的 writeup 文件列表，格式如下：

```
📚 最终汇总选出的 5 篇文章：
  - writeup1.md
  - writeup2.md
  - writeup3.md
  - writeup4.md
  - writeup5.md
```

### .augmentignore 配置

`.augmentignore` 文件用于配置 Augment 应该忽略的文件和目录。

#### 配置示例

```
# 忽略日志文件
*.log
logs/

# 忽略临时文件
*.tmp
temp/

# 忽略特定文件
README.md
```

---

## 配置验证与测试

### 配置验证

在保存配置后，系统会自动验证配置的完整性：

1. **必填项检查**：检查所有必填项是否已填写
2. **格式验证**：验证 JSON 格式、字段类型等
3. **一致性检查**：检查阶段配置与 Prompt 配置是否一致

### 测试配置

#### 1. Prompt 预览测试

1. 在 **Prompt 模板** 标签页，点击 **完整 Prompt 预览**
2. 检查预览内容是否正确
3. 确认所有变量都能正确替换

#### 2. 实际生成测试

1. 进入题目生成页面
2. 选择配置的方向
3. 填写表单字段
4. 启动生成任务
5. 观察生成过程，检查：
   - 阶段是否正确执行
   - Prompt 是否正确传递
   - 输出是否符合预期

#### 3. 日志检查

如果生成过程中出现问题，可以查看日志：

1. 在生成任务页面查看实时日志
2. 检查日志中的错误信息
3. 根据错误信息调整配置

---

## 常见问题

### Q1: 如何添加新的阶段？

**A**: 在阶段配置页面，点击"添加阶段"按钮，填写阶段信息后保存。

### Q2: 如何修改阶段的执行顺序？

**A**: 在阶段配置页面，使用拖拽功能调整阶段顺序。

### Q3: Prompt 中的变量不生效怎么办？

**A**: 检查：
1. 变量名称是否正确（区分大小写）
2. 表单字段ID是否与变量名匹配
3. 是否在正确的难度配置中编辑

### Q4: 如何让 AI 输出特定格式的内容？

**A**: 在阶段 Prompt 中明确指定输出格式，使用 Markdown 表格、代码块等格式。

### Q5: 知识库文件上传失败？

**A**: 检查：
1. 文件大小是否超过限制
2. 文件格式是否支持
3. 目录权限是否正确

### Q6: 如何配置不同难度的不同 Prompt？

**A**: 在 Prompt 模板页面，使用难度标签切换不同难度的配置，每个难度可以独立配置各阶段的 Prompt。

### Q7: 阶段检测不准确怎么办？

**A**: 确保：
1. Prompt 中明确要求 AI 输出 `阶段X：阶段名称` 格式
2. 阶段编号从 1 开始（不是从 0）
3. 最后一个阶段完成后输出 `## [CTF_GENERATION_COMPLETE]`

### Q8: 如何备份配置？

**A**: 在方向列表页面，点击"导出"按钮可以导出配置为 JSON 文件。

---

## 最佳实践

### 1. 阶段设计

- **保持阶段独立性**：每个阶段应该有明确的输入和输出
- **合理的阶段数量**：建议 8-12 个阶段，太少可能不够详细，太多可能过于复杂
- **清晰的阶段名称**：使用动词开头的名称，如"获取知识库"、"生成代码"等

### 2. Prompt 编写

- **明确指令**：使用清晰的指令，避免模糊的表达
- **提供示例**：在 Prompt 中提供输出示例，帮助 AI 理解要求
- **分步骤说明**：将复杂任务分解为多个步骤
- **格式要求**：明确指定输出格式，使用 Markdown 表格、代码块等

### 3. 变量使用

- **合理使用变量**：只在需要动态内容的地方使用变量
- **变量命名**：使用有意义的变量名，与表单字段ID保持一致
- **默认值**：为变量提供合理的默认值

### 4. 知识库管理

- **定期更新**：定期添加新的 writeup，保持知识库的新鲜度
- **分类管理**：使用目录结构对 writeup 进行分类
- **质量保证**：确保 writeup 内容完整、准确

### 5. 测试与迭代

- **小步测试**：每次修改后都进行测试
- **日志分析**：仔细分析生成日志，找出问题
- **持续优化**：根据测试结果不断优化配置

### 6. 配置维护

- **版本控制**：定期导出配置备份
- **文档记录**：记录重要的配置变更
- **团队协作**：多人协作时，明确配置责任

---

## 附录

### 配置导出格式示例

```json
{
  "id": "web",
  "name": "Web 安全",
  "description": "Web 安全方向的题目配置",
  "enabled": true,
  "sort_order": 1,
  "form_fields": [...],
  "stages": [...],
  "difficulties": {
    "入门": {
      "stages": [...],
      "rules": {...}
    }
  },
  "advanced_config": {
    "system_prompt": "..."
  }
}
```

### 相关文档

- [系统使用手册](./系统使用手册.md)
- [API 文档](./API文档.md)
- [故障排查指南](./故障排查指南.md)

---

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