深入拆解PentAGI：全栈AI自动化渗透测试平台架构解析

# 文件位置: backend/pkg/graph/schema.graphqls
# GraphQL 类型定义 —— 核心执行模型的骨架

# ==================== 核心实体 ====================

type Flow {
  id: ID!            # 全局唯一标识
  title: String!     # 用户为本次渗透测试起的名称
  status: StatusType! # 生命周期: active / completed / failed
  terminals: [Terminal!]   # 沙箱终端会话列表
  provider: Provider!      # 绑定的 LLM 提供商
  createdAt: Time!          # 创建时间
  updatedAt: Time!          # 最近一次更新时间
}

type Task {
  id: ID!            # 全局唯一标识
  title: String!     # 任务名称，如"端口扫描"
  status: StatusType! # pending / running / done / failed
  input: String!     # 用户的输入描述（从 Flow 传递过来）
  result: String!    # 执行结果摘要（Agent 链完成后填充）
  flowId: ID!        # 所属 Flow 的外键
  subtasks: [Subtask!]  # 该任务下的所有子任务
  createdAt: Time!
  updatedAt: Time!
}

type Subtask {
  id: ID!            # 全局唯一标识
  status: StatusType! # queued / running / completed / failed
  title: String!     # 子任务标题
  description: String! # 详细描述，包含执行目标和注意事项
  result: String!    # 执行结果，由 Reporter Agent 填充
  taskId: ID!        # 所属 Task 的外键
  createdAt: Time!
  updatedAt: Time!
}

flowchart TB
    subgraph Flow层
        F[Flow 渗透测试会话]
    end

    subgraph Task层
        T1[Task 信息收集]
        T2[Task 漏洞识别]
        T3[Task 利用验证]
        T4[Task 报告生成]
    end

    subgraph SubTask层
        ST1[SubTask 端口扫描]
        ST2[SubTask 服务识别]
        ST3[SubTask CVE匹配]
        ST4[SubTask 漏洞利用]
    end

    subgraph Agent链
        A1[Primary Agent<br/>主协调者]
        A2[Researcher<br/>研究员]
        A3[Pentester<br/>渗透者]
        A4[Reporter<br/>报告员]
    end

    F --> T1
    F --> T2
    F --> T3
    F --> T4
    T1 --> ST1
    T1 --> ST2
    T2 --> ST3
    T3 --> ST4
    ST1 --> A1 --> A2
    ST2 --> A1 --> A3
    ST3 --> A1 --> A3
    ST4 --> A1 --> A4

flowchart LR
    subgraph 协调层
        PA[Primary Agent<br/>主引导者]
        AS[Assistant<br/>交互助手]
    end

    subgraph 规划层
        GEN[Generator<br/>任务生成器]
        REF[Refiner<br/>任务优化器]
        ADV[Adviser<br/>顾问]
        PLA[Planner<br/>规划器]
    end

    subgraph 执行层
        PEN[Pentester<br/>渗透执行者]
        COD[Coder<br/>代码编写者]
        SEA[Searcher<br/>信息搜索者]
        ENR[Enricher<br/>上下文丰富者]
        INS[Installer<br/>工具安装者]
    end

    subgraph 记忆与反思层
        MEM[Memorist<br/>记忆管理者]
        REFL[Reflector<br/>反思校验者]
        SUM[Summarizer<br/>摘要生成者]
        TC[Tool Call Fixer<br/>工具调用修复者]
    end

    subgraph 输出层
        REP[Reporter<br/>报告生成者]
    end

    PA --> GEN
    GEN --> REF
    REF --> PEN & COD & SEA
    SEA --> ENR
    PA --> AS
    PEN --> MEM
    COD --> MEM
    MEM --> PA
    PEN & COD --> REFL
    REFL --> TC
    REFL --> SUM
    PA --> REP
    ADV --> PA
    PLA --> GEN

    style PA fill:#1a73e8,stroke:#0d47a1,color:#fff
    style REP fill:#388e3c,stroke:#1b5e20,color:#fff
    style REFL fill:#e65100,stroke:#bf360c,color:#fff

# 文件位置: backend/pkg/graph/schema.graphqls
# Agent 角色枚举 —— 系统所有预定义角色的精确清单

enum AgentType {
  primary_agent    # 主协调者: 负责任务分解与 Agent 调度
  reporter         # 报告生成者: 结构化输出测试报告
  generator        # 任务生成者: 从用户输入生成子任务计划
  refiner          # 任务优化者: 优化子任务覆盖面和质量
  reflector        # 反思校验者: 验证执行结果，发现异常
  enricher         # 上下文丰富者: 提炼和丰富搜索结果
  adviser          # 导师顾问: 监控执行并提供策略建议
  coder            # 代码编写者: 编写自定义攻击代码
  memorist         # 记忆管理者: 管理向量存储和知识库
  searcher         # 信息搜索者: 多引擎情报收集
  installer        # 工具安装者: 在沙箱中安装额外工具
  pentester        # 渗透执行者: 执行扫描/利用/横向移动
  summarizer       # 摘要生成者: 压缩长对话链控制上下文
  tool_call_fixer  # 工具调用修复者: 修正失败的 LLM 工具调用
  assistant        # 交互助手: 处理用户的实时问答
}

// 文件位置: backend/pkg/graph/model/models_gen.go
// AgentType 字符串常量 —— 由 gqlgen 从 GraphQL Schema 自动生成

type AgentType string

const (
    AgentTypePrimaryAgent  AgentType = "primary_agent"
    AgentTypeReporter      AgentType = "reporter"
    AgentTypeGenerator     AgentType = "generator"
    AgentTypeRefiner       AgentType = "refiner"
    AgentTypeReflector     AgentType = "reflector"
    AgentTypeEnricher      AgentType = "enricher"
    AgentTypeAdviser       AgentType = "adviser"
    AgentTypeCoder         AgentType = "coder"
    AgentTypeMemorist      AgentType = "memorist"
    AgentTypeSearcher      AgentType = "searcher"
    AgentTypeInstaller     AgentType = "installer"
    AgentTypePentester     AgentType = "pentester"
    AgentTypeSummarizer    AgentType = "summarizer"
    AgentTypeToolCallFixer AgentType = "tool_call_fixer"
    AgentTypeAssistant     AgentType = "assistant"
)

// AllAgentType 用于枚举校验和遍历
var AllAgentType = []AgentType{
    AgentTypePrimaryAgent,
    AgentTypeReporter,
    // ... 省略其他常量
}

// 文件位置: backend/pkg/tools/registry.go
// 工具注册表 —— 所有工具以 FunctionDefinition 格式统一注册
// 每个注册条目包含: 名称、用途描述、JSON Schema 参数

// registryDefinitions 存储所有已注册的工具定义
// LLM 通过 function calling 机制调用这些工具，参数由反射自动生成 Schema
var registryDefinitions = map[string]llms.FunctionDefinition{
    // 终端执行工具 —— 在 Docker 沙箱中执行任意命令
    TerminalToolName: {
        Name: TerminalToolName, // 常量值: "terminal"
        Description: "Calls a terminal command in blocking mode. " +
            "Use timeout=0 or a negative value to apply the configured server default timeout. " +
            "Explicit positive values are accepted up to 10800 seconds (3 hours); " +
            "values outside this range are replaced by the server default. " +
            "Only one command can be executed at a time",
        Parameters: reflector.Reflect(&TerminalAction{}),
        // ^ 自动反射 TerminalAction 结构体为 JSON Schema
    },
    // 文件操作工具 —— 读写容器内的文件
    FileToolName: {
        Name:        FileToolName, // 常量值: "file"
        Description: "Modifies or reads local files",
        Parameters:  reflector.Reflect(&FileAction{}),
    },
    // 浏览器工具 —— 在隔离的 scraper 容器中打开网页
    BrowserToolName: {
        Name:        BrowserToolName, // 常量值: "browser"
        Description: "Opens a browser to look for additional information from the web site",
        Parameters:  reflector.Reflect(&Browser{}),
    },
    // Google 搜索引擎 —— 快速查询，返回短内容
    GoogleToolName: {
        Name: GoogleToolName, // 常量值: "google"
        Description: "Search in the google search engine, it's a fast query and the shortest content " +
            "to check some information or collect public links by short query",
        Parameters: reflector.Reflect(&SearchAction{}),
    },
    // Sploitus 漏洞利用聚合器 —— 搜索公开的 PoC 和漏洞利用代码
    SploitusToolName: {
        Name: SploitusToolName, // 常量值: "sploitus"
        Description: "Search the Sploitus exploit aggregator (https://sploitus.com) " +
            "for public exploits, proof-of-concept code, and offensive security tools. " +
            "Sploitus indexes ExploitDB, Packet Storm, GitHub Security Advisories, " +
            "and many other sources. Use this tool to find exploit code and PoCs " +
            "for specific software, services, CVEs, or vulnerability classes.",
        Parameters: reflector.Reflect(&SploitusAction{}),
    },
    // done 屏障工具 —— 标记子任务完成，终止当前 Agent 链
    FinalyToolName: {
        Name:        FinalyToolName, // 常量值: "done"
        Description: "If you need to finish the task with success or failure, use this tool",
        Parameters:  reflector.Reflect(&Done{}),
    },
    // ... 其他工具的注册在此省略
}

// 工具类型映射 —— 将每个工具名称归类，用于权限控制
var toolsTypeMapping = map[string]ToolType{
    FinalyToolName:            BarrierToolType,        // 屏障类
    AskUserToolName:           BarrierToolType,        // 屏障类
    CoderToolName:             AgentToolType,          // Agent 委托类
    PentesterToolName:         AgentToolType,          // Agent 委托类
    TerminalToolName:          EnvironmentToolType,    // 环境操作类
    FileToolName:              EnvironmentToolType,    // 环境操作类
    BrowserToolName:           SearchNetworkToolType,  // 网络搜索类
    GoogleToolName:            SearchNetworkToolType,  // 网络搜索类
    // ... 其他工具的映射
}

// 文件位置: backend/pkg/tools/registry.go
// 允许摘要压缩结果的工具 —— 这些工具的输出可能非常大，需要压缩
var allowedSummarizingToolsResult = []string{
    TerminalToolName, // 终端命令输出可能需要摘要
    BrowserToolName,  // 浏览器页面内容可能需要摘要
}

// 允许自动存入记忆的工具 —— 这些工具的执行结果对长期学习有价值
var allowedStoringInMemoryTools = []string{
    TerminalToolName,     // 终端的命令和输出
    FileToolName,         // 文件读写内容
    SearchToolName,       // 搜索请求和结果
    GoogleToolName,       // Google 搜索结果
    TavilyToolName,       // Tavily 搜索结果
    SploitusToolName,     // Sploitus 漏洞搜索结果
    PentesterToolName,    // 渗透测试结果
    CoderToolName,        // 代码执行结果
    AdviceToolName,       // 顾问建议
    // ... 其他工具
}

flowchart TB
    subgraph 长期记忆
        VS[(向量存储<br/>pgvector 嵌入)]
        KB[知识库<br/>领域专业知识]
        TK[工具知识<br/>使用模式与经验]
    end

    subgraph 工作记忆
        CTX[当前上下文<br/>任务状态]
        GOAL[活跃目标<br/>当前目标]
        STATE[系统状态<br/>资源状态]
    end

    subgraph 情景记忆
        PAST[历史操作<br/>命令记录]
        RES[操作结果<br/>执行产出]
        PATT[成功模式<br/>最佳实践]
    end

    CTX -->|查询| VS
    VS -->|检索| CTX
    GOAL -->|咨询| KB
    KB -->|指导| GOAL
    STATE -->|记录| PAST
    PAST -->|学习| PATT
    PATT -->|存储| VS
    TK -->|通知| STATE
    RES -->|更新| TK
    VS -->|增强| KB
    KB -->|索引| VS

    style VS fill:#e1bee7,stroke:#7b1fa2,color:#000
    style CTX fill:#bbdefb,stroke:#1565c0,color:#000
    style PAST fill:#c8e6c9,stroke:#2e7d32,color:#000

flowchart TB
    subgraph 第一层 工具调用硬限制
        HARD[硬限制<br/>MAX_GENERAL=100<br/>MAX_LIMITED=20]
    end

    subgraph 第二层 Reflector 反思校验
        REFLECT[Reflector<br/>3次失败自动介入<br/>引导正确工具调用]
    end

    subgraph 第三层 Execution Monitor 执行监控
        MON[模式检测<br/>相同工具≥5次提醒<br/>进度分析<br/>替代策略推荐]
    end

    subgraph 第四层 Intelligent Task Planning 智能规划
        PLAN[Planner<br/>自动分解3-7步骤<br/>上下文感知<br/>范围管控]
    end

    AGENT[Agent 执行] --> HARD
    HARD -->|接近上限| REFLECT
    REFLECT -->|异常模式| MON
    MON -->|复杂任务| PLAN
    PLAN -->|规划指导| AGENT

    style HARD fill:#ffcdd2,stroke:#c62828,color:#000
    style REFLECT fill:#fff3e0,stroke:#e65100,color:#000
    style MON fill:#fff9c4,stroke:#f9a825,color:#000
    style PLAN fill:#e8f5e9,stroke:#2e7d32,color:#000

// 文件位置: backend/pkg/providers/performer.go
// Agent 链执行引擎 —— 控制 Agent 与 LLM 之间的迭代对话循环
// 每次迭代: Agent 发送消息 → LLM 响应(文本+工具调用) → 执行工具 → 处理结果

// performAgentChain 是 Agent 链的执行主循环
// 参数说明:
//   chainID    - 消息链的唯一标识，用于持久化和日志关联
//   taskID/subtaskID - 当前任务/子任务，用于隔离执行上下文
//   chain      - 当前对话消息链（累积的 LLM 对话历史）
//   executor   - 工具执行器，根据 Agent 角色包装了权限信息
//   summarizer - 链摘要器，在上下文接近 token 限制时自动压缩
func (fp *flowProvider) performAgentChain(
    ctx context.Context,
    optAgentType pconfig.ProviderOptionsType, // Agent 类型（pentester/coder/...）
    chainID int64,
    taskID, subtaskID *int64,
    chain []llms.MessageContent,       // 累积的对话链
    executor tools.ContextToolsExecutor, // 工具执行器
    summarizer csum.Summarizer,         // 链摘要器
) error {
    var (
        wantToStop bool
        // 构建执行监控器，用于检测重复工具调用和进度停滞
        monitor  = fp.buildMonitor()
        // 重复调用检测器，追踪连续相同的工具调用
        detector = &repeatingDetector{}
    )

    // 根据 Agent 类型决定最大工具调用次数
    // 通用 Agent (Assistant/Pentester/Coder) 上限更高
    // 受限 Agent (Searcher/Enricher/Memorist) 上限更低
    var maxCallsLimit int
    switch optAgentType {
    case pconfig.OptionsTypeAssistant, pconfig.OptionsTypePrimaryAgent,
        pconfig.OptionsTypePentester, pconfig.OptionsTypeCoder, pconfig.OptionsTypeInstaller:
        // 通用 Agent: 默认 100 次工具调用
        maxCallsLimit = maxGeneralAgentChainIterations // 常量: 100
    default:
        // 受限 Agent: 默认 20 次工具调用
        maxCallsLimit = maxLimitedAgentChainIterations // 常量: 20
    }

    // ========== 主迭代循环 ==========
    // 每次迭代: 调用 LLM → 处理响应 → 执行工具 → 追加结果到消息链
    for iteration := 0; ; iteration++ {
        // 硬限制: 超过最大迭代次数则报错
        if iteration >= maxCallsLimit {
            return errors.New("agent chain exceeded maximum iterations")
        }

        var result *callResult

        // 当迭代次数接近上限时，自动触发 Reflector 引导 Agent 优雅终止
        if iteration >= maxCallsLimit-maxAgentShutdownIterations {
            // Reflector 告知 Agent 无法继续，要求其调用 done 工具
            result = &callResult{
                content: fmt.Sprintf(
                    "I can't continue this multi-turn chain because " +
                    "I'm too close to the AI agent iteration limit (%d).",
                    maxCallsLimit,
                ),
            }
        } else {
            // 正常调用: 向 LLM 发送当前对话链，获取响应
            result, err = fp.callWithRetries(ctx, optAgentType, chainID,
                taskID, subtaskID, chain, executor, executionContext)
            if err != nil {
                return err
            }
        }

        // 如果 LLM 没有返回任何工具调用（纯文本响应）
        iflen(result.funcCalls) == 0 {
            if optAgentType == pconfig.OptionsTypeAssistant {
                // Assistant 的纯文本响应直接返回给用户
                return fp.processAssistantResult(...)
            } else {
                // 其他 Agent: 通过 Reflector 分析 LLM 为什么没有做决策
                // Reflector 会尝试引导 Agent 正确使用工具
                result, err = fp.performReflector(...)
                if err != nil {
                    return err
                }
            }
        }

        // 将 LLM 的响应（文本+工具调用）追加到对话链
        msg := llms.MessageContent{Role: llms.ChatMessageTypeAI}
        // 保留推理内容（如 Anthropic 的 extended thinking）
        if result.content != "" || !result.thinking.IsEmpty() {
            msg.Parts = append(msg.Parts,
                llms.TextPartWithReasoning(result.content, result.thinking))
        }
        for _, toolCall := range result.funcCalls {
            msg.Parts = append(msg.Parts, toolCall)
        }
        chain = append(chain, msg)

        // ====== 遍历执行所有工具调用 ======
        for idx, toolCall := range result.funcCalls {
            funcName := toolCall.FunctionCall.Name
            // 执行单个工具调用，monitor 和 detector 在其中生效
            response, err := fp.execToolCall(
                ctx, optAgentType, chainID, idx, result,
                monitor, detector, executor, taskID, subtaskID, chain,
            )

            if toolTypeMapping[funcName] != tools.AgentToolType {
                // 非 Agent 委托类工具的调用记录写入 Graphiti 知识图谱
                fp.storeToolExecutionToGraphiti(...)
            }

            // 将工具执行结果作为 Tool 角色的消息追加到对话链
            chain = append(chain, llms.MessageContent{
                Role: llms.ChatMessageTypeTool,
                Parts: []llms.ContentPart{
                    llms.ToolCallResponse{
                        ToolCallID: toolCall.ID,
                        Name:       funcName,
                        Content:    response,
                    },
                },
            })

            // 如果 Agent 调用了屏障工具（done / ask），标记终止
            if executor.IsBarrierFunction(funcName) {
                wantToStop = true
            }
        }

        if wantToStop {
            returnnil// 正常结束 Agent 链
        }

        // 链摘要: 当消息链总长度接近 token 限制时，
        // 自动对历史消息进行智能压缩，保留关键信息
        if summarizer != nil {
            chain, err = summarizer.SummarizeChain(ctx,
                summarizerHandler, chain, fp.tcIDTemplate)
        }
    }
}

// 文件位置: backend/pkg/providers/provider/provider.go
// Provider 接口 —— 所有 LLM 提供商必须实现此接口
// 这是 PentAGI 插件式 LLM 集成架构的核心抽象

type Provider interface {
    // 基础信息
    Type() ProviderType       // 返回提供商类型: openai / anthropic / gemini / ...
    Name() ProviderName       // 返回实例名称，支持同一类型多个实例
    Model(opt pconfig.ProviderOptionsType) string// 返回当前使用的模型名称

    // 带提供商前缀的模型名称，用于 LLM API 调用和 Langfuse 日志记录
    ModelWithPrefix(opt pconfig.ProviderOptionsType) string

    // 从 LLM 返回的 usage 元数据中提取 token 消耗信息
    GetUsage(info map[string]any) pconfig.CallUsage

    // 核心调用方法
    Call(ctx context.Context, opt pconfig.ProviderOptionsType,
        prompt string) (string, error)
    // ^ 简单文本调用：将 prompt 发送给 LLM，返回纯文本响应

    CallEx(ctx context.Context, opt pconfig.ProviderOptionsType,
        chain []llms.MessageContent,
        streamCb streaming.Callback,
    ) (*llms.ContentResponse, error)
    // ^ 多轮对话调用：发送完整的消息链，支持流式回调

    CallWithTools(ctx context.Context, opt pconfig.ProviderOptionsType,
        chain []llms.MessageContent,
        tools []llms.Tool,
        streamCb streaming.Callback,
    ) (*llms.ContentResponse, error)
    // ^ 带工具调用的对话 —— 这是多 Agent 系统的核心调用路径
    //   Agent 向 LLM 发送对话历史和可用工具列表，
    //   LLM 返回文本响应 和/或 工具调用请求

    // 配置访问
    GetRawConfig() []byte                        // 原始配置（YAML 格式）
    GetProviderConfig() *pconfig.ProviderConfig   // 解析后的配置

    // 定价信息和模型列表
    GetPriceInfo(opt pconfig.ProviderOptionsType) *pconfig.PriceInfo
    GetModels() pconfig.ModelsConfig

    // 工具调用 ID 模板，每个提供商可能有不同的命名格式
    GetToolCallIDTemplate(ctx context.Context, prompter templates.Prompter) (string, error)
}