diff --git a/README.md b/README.md index fc5ca58..c99f518 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,9 @@ + +> [!NOTE] +> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 +> [English](./README.en.md) · [原始项目](https://github.com/vxcontrol/pentagi) · [上游 README](https://github.com/vxcontrol/pentagi/blob/HEAD/README.md) +> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。 + # PentAGI
@@ -6,7 +12,7 @@
-> **Join the Community!** Connect with security researchers, AI enthusiasts, and fellow ethical hackers. Get support, share insights, and stay updated with the latest PentAGI developments. +> **加入社区！** 与安全研究人员、AI 爱好者以及道德黑客（ethical hackers）同行交流。获取支持、分享见解，并及时了解 PentAGI 的最新进展。 [![Discord](https://img.shields.io/badge/Discord-7289DA?logo=discord&logoColor=white)](https://discord.gg/2xrMh7qX6m)⠀[![Telegram](https://img.shields.io/badge/Telegram-2CA5E0?logo=telegram&logoColor=white)](https://t.me/+Ka9i6CNwe71hMWQy) @@ -14,16 +20,16 @@
-## Table of Contents +## 目录 -- [Overview](#overview) -- [Features](#features) -- [Architecture](#architecture) - - [Agent Supervision](#advanced-agent-supervision) -- [Quick Start](#quick-start) -- [How to Use PentAGI After Login](#how-to-use-pentagi-after-login) -- [API Access](#api-access) - - [LLM Provider Configuration](#custom-llm-provider-configuration) +- [概述](#overview) +- [功能特性](#features) +- [架构](#architecture) + - [高级智能体监督](#advanced-agent-supervision) +- [快速开始](#quick-start) +- [登录后如何使用 PentAGI](#how-to-use-pentagi-after-login) +- [API 访问](#api-access) + - [LLM 提供商配置](#custom-llm-provider-configuration) - [Ollama](#ollama-provider-configuration) - [OpenAI](#openai-provider-configuration) - [Anthropic](#anthropic-provider-configuration) @@ -33,59 +39,59 @@ - [GLM](#glm-provider-configuration) - [Kimi](#kimi-provider-configuration) - [Qwen](#qwen-provider-configuration) -- [Advanced Setup](#advanced-setup) - - [Langfuse Integration](#langfuse-integration) - - [Monitoring and Observability](#monitoring-and-observability) - - [Knowledge Graph (Graphiti)](#knowledge-graph-integration-graphiti) - - [OAuth Integration](#github-and-google-oauth-integration) - - [Docker Image Configuration](#docker-image-configuration) -- [Development](#development) -- [Testing LLM Agents](#testing-llm-agents) -- [Embedding Configuration and Testing](#embedding-configuration-and-testing) -- [Function Testing with ftester](#function-testing-with-ftester) -- [Building](#building) -- [Credits](#credits) -- [License](#license) +- [高级配置](#advanced-setup) + - [Langfuse 集成](#langfuse-integration) + - [监控与可观测性](#monitoring-and-observability) + - [知识图谱 (Graphiti)](#knowledge-graph-integration-graphiti) + - [OAuth 集成](#github-and-google-oauth-integration) + - [Docker 镜像配置](#docker-image-configuration) +- [开发](#development) +- [测试 LLM 智能体](#testing-llm-agents) +- [Embedding 配置与测试](#embedding-configuration-and-testing) +- [使用 ftester 进行函数测试](#function-testing-with-ftester) +- [构建](#building) +- [致谢](#credits) +- [许可证](#license) -## Overview +## 概述 -PentAGI is an innovative tool for automated security testing that leverages cutting-edge artificial intelligence technologies. The project is designed for information security professionals, researchers, and enthusiasts who need a powerful and flexible solution for conducting penetration tests. +PentAGI 是一款创新的自动化安全测试工具，采用前沿的人工智能技术。该项目面向信息安全专业人员、研究人员和爱好者，为他们提供强大且灵活的渗透测试解决方案。 -You can watch the video **PentAGI overview**: +你可以观看视频 **PentAGI overview**： [![PentAGI Overview Video](https://github.com/user-attachments/assets/0828dc3e-15f1-4a1d-858e-9696a146e478)](https://youtu.be/R70x5Ddzs1o) -## Features +## 功能特性 -- Secure & Isolated. All operations are performed in a sandboxed Docker environment with complete isolation. -- Fully Autonomous. AI-powered agent that automatically determines and executes penetration testing steps with optional execution monitoring and intelligent task planning for enhanced reliability. -- Professional Pentesting Tools. Built-in suite of 20+ professional security tools including nmap, metasploit, sqlmap, and more. -- Smart Memory System. Long-term storage of research results and successful approaches for future use. -- Knowledge Graph Integration. Graphiti-powered knowledge graph using Neo4j for semantic relationship tracking and advanced context understanding. -- Web Intelligence. Built-in browser via [scraper](https://hub.docker.com/r/vxcontrol/scraper) for gathering latest information from web sources. -- External Search Systems. Integration with advanced search APIs including [Tavily](https://tavily.com), [Traversaal](https://traversaal.ai), [Perplexity](https://www.perplexity.ai), [DuckDuckGo](https://duckduckgo.com/), [Google Custom Search](https://programmablesearchengine.google.com/), [Sploitus Search](https://sploitus.com) and [Searxng](https://searxng.org) for comprehensive information gathering. -- Team of Specialists. Delegation system with specialized AI agents for research, development, and infrastructure tasks, enhanced with optional execution monitoring and intelligent task planning for optimal performance with smaller models. -- Comprehensive Monitoring. Detailed logging and integration with Grafana/Prometheus for real-time system observation. -- Detailed Reporting. Generation of thorough vulnerability reports with exploitation guides. -- Smart Container Management. Automatic Docker image selection based on specific task requirements. -- Modern Interface. Clean and intuitive web UI for system management and monitoring. -- Comprehensive APIs. Full-featured REST and GraphQL APIs with Bearer token authentication for automation and integration. -- Persistent Storage. All commands and outputs are stored in PostgreSQL with [pgvector](https://hub.docker.com/r/vxcontrol/pgvector) extension. -- Scalable Architecture. Microservices-based design supporting horizontal scaling. -- Self-Hosted Solution. Complete control over your deployment and data. -- Flexible Authentication. Support for 10+ LLM providers ([OpenAI](https://platform.openai.com/), [Anthropic](https://www.anthropic.com/), [Google AI/Gemini](https://ai.google.dev/), [AWS Bedrock](https://aws.amazon.com/bedrock/), [Ollama](https://ollama.com/), [DeepSeek](https://www.deepseek.com/en/), [GLM](https://z.ai/), [Kimi](https://platform.moonshot.ai/), [Qwen](https://www.alibabacloud.com/en/), Custom) plus aggregators ([OpenRouter](https://openrouter.ai/), [DeepInfra](https://deepinfra.com/)). For production local deployments, see our [vLLM + Qwen3.5-27B-FP8 guide](examples/guides/vllm-qwen35-27b-fp8.md). -- API Token Authentication. Secure Bearer token system for programmatic access to REST and GraphQL APIs. -- Quick Deployment. Easy setup through [Docker Compose](https://docs.docker.com/compose/) with comprehensive environment configuration. +- 安全且隔离。所有操作均在沙箱化的 Docker 环境中执行，实现完全隔离。 +- 完全自主。由 AI 驱动的智能体自动确定并执行渗透测试步骤，可选执行监控与智能任务规划，以提升可靠性。 +- 专业渗透测试工具。内置 20+ 款专业安全工具，包括 nmap、metasploit、sqlmap 等。 +- 智能记忆系统。长期存储研究成果与成功方法，供后续使用。 +- 知识图谱集成。基于 Graphiti 的知识图谱，使用 Neo4j 进行语义关系追踪与高级上下文理解。 +- 网络情报。通过内置浏览器与 [scraper](https://hub.docker.com/r/vxcontrol/scraper) 从网络来源收集最新信息。 +- 外部搜索系统。集成多种高级搜索 API，包括 [Tavily](https://tavily.com), [Traversaal](https://traversaal.ai), [Perplexity](https://www.perplexity.ai), [DuckDuckGo](https://duckduckgo.com/), [Google Custom Search](https://programmablesearchengine.google.com/), [Sploitus Search](https://sploitus.com) 以及 [Searxng](https://searxng.org)，用于全面的信息收集。 +- 专家团队。委派系统配备专业化 AI 智能体，分别负责研究、开发与基础设施任务，并可选执行监控与智能任务规划，以便在较小模型上也能获得最佳性能。 +- 全面监控。详细日志记录，并集成 Grafana/Prometheus，实现实时系统观测。 +- 详细报告。生成详尽的漏洞报告及利用指南。 +- 智能容器管理。根据具体任务需求自动选择 Docker 镜像。 +- 现代界面。简洁直观的 Web UI，用于系统管理与监控。 +- 完整 API。功能齐全的 REST 与 GraphQL API，支持 Bearer token 认证，便于自动化与集成。 +- 持久化存储。所有命令与输出均存储在 PostgreSQL 中，并使用 [pgvector](https://hub.docker.com/r/vxcontrol/pgvector) 扩展。 +- 可扩展架构。基于微服务的设计，支持水平扩展。 +- 自托管方案。完全掌控部署与数据。 +- 灵活认证。支持 10+ 种 LLM 提供商（[OpenAI](https://platform.openai.com/), [Anthropic](https://www.anthropic.com/), [Google AI/Gemini](https://ai.google.dev/), [AWS Bedrock](https://aws.amazon.com/bedrock/), [Ollama](https://ollama.com/), [DeepSeek](https://www.deepseek.com/en/), [GLM](https://z.ai/), [Kimi](https://platform.moonshot.ai/), [Qwen](https://www.alibabacloud.com/en/), Custom），以及聚合器（[OpenRouter](https://openrouter.ai/), [DeepInfra](https://deepinfra.com/)).。若要在生产环境本地部署，请参阅我们的 [vLLM + Qwen3.5-27B-FP8 指南](examples/guides/vllm-qwen35-27b-fp8.md)。 +- API Token 认证。安全的 Bearer token 系统，用于以编程方式访问 REST 与 GraphQL API。 +- 快速部署。通过 [Docker Compose](https://docs.docker.com/compose/) 轻松完成设置，并提供全面的环境配置。 -### Current Capability Boundaries +### 当前能力边界 -- PentAGI today is an autonomous and assistant-guided penetration testing platform, not a CALDERA-style Breach and Attack Simulation (BAS) or adversary emulation product with predefined campaigns or attack plans. -- BAS-like agent-authored attack scripts should be treated as conceptual or future work, not as a feature that is implemented today. -- The current flow report UI supports web view, copy to clipboard, Markdown download, and PDF download. JSON flow-report export is not documented as a supported output format today. -- Provider flexibility is available today through built-in providers and custom/OpenAI-compatible endpoints. See [Custom LLM Provider Configuration](#custom-llm-provider-configuration) and the [vLLM + Qwen3.5-27B-FP8 guide](examples/guides/vllm-qwen35-27b-fp8.md). +- PentAGI 目前是一个自主且由助手引导的渗透测试平台，而非 CALDERA 风格的入侵与攻击模拟（Breach and Attack Simulation，BAS）或带有预定义战役/攻击计划的对手仿真（adversary emulation）产品。 +- 类似 BAS 的由智能体编写的攻击脚本应视为概念性工作或未来规划，而非当前已实现的功能。 +- 当前的流程报告 UI 支持 Web 查看、复制到剪贴板、Markdown 下载与 PDF 下载。JSON 格式的 flow-report 导出目前未记录为受支持的输出格式。 +- 提供商灵活性目前可通过内置提供商以及自定义/OpenAI 兼容端点实现。请参阅 [自定义 LLM 提供商配置](#custom-llm-provider-configuration) 与 [vLLM + Qwen3.5-27B-FP8 指南](examples/guides/vllm-qwen35-27b-fp8.md)。 -## Architecture +## 架构 -### System Context +### 系统上下文 ```mermaid flowchart TB @@ -127,7 +133,7 @@ flowchart TB ```
-Container Architecture (click to expand) +容器架构（点击展开） ```mermaid graph TB @@ -203,7 +209,7 @@ graph TB
-Entity Relationship (click to expand) +实体关系（点击展开） ```mermaid erDiagram @@ -278,7 +284,7 @@ erDiagram
-Agent Interaction (click to expand) +Agent 交互（点击展开） ```mermaid sequenceDiagram @@ -323,7 +329,7 @@ sequenceDiagram
-Memory System (click to expand) +记忆系统（点击展开） ```mermaid graph TB @@ -373,9 +379,9 @@ graph TB
-Chain Summarization (click to expand) +链式摘要（点击展开） -The chain summarization system manages conversation context growth by selectively summarizing older messages. This is critical for preventing token limits from being exceeded while maintaining conversation coherence. +链式摘要（Chain Summarization）系统通过选择性摘要较早的消息来管理对话上下文的增长。这对于在保持对话连贯性的同时避免超出 token 限制至关重要。 ```mermaid flowchart TD @@ -400,37 +406,37 @@ flowchart TD class C,K output ``` -The algorithm operates on a structured representation of conversation chains (ChainAST) that preserves message types including tool calls and their responses. All summarization operations maintain critical conversation flow while reducing context size. +该算法作用于对话链的结构化表示（ChainAST），保留包括工具调用及其响应在内的消息类型。所有摘要操作在缩减上下文大小的同时保持关键对话流程。 -### Global Summarizer Configuration Options +### 全局摘要器配置选项 -| Parameter | Environment Variable | Default | Description | +| 参数 | 环境变量 | 默认值 | 说明 | | --------------------- | -------------------------------- | ------- | ---------------------------------------------------------- | -| Preserve Last | `SUMMARIZER_PRESERVE_LAST` | `true` | Whether to keep all messages in the last section intact | -| Use QA Pairs | `SUMMARIZER_USE_QA` | `true` | Whether to use QA pair summarization strategy | -| Summarize Human in QA | `SUMMARIZER_SUM_MSG_HUMAN_IN_QA` | `false` | Whether to summarize human messages in QA pairs | -| Last Section Size | `SUMMARIZER_LAST_SEC_BYTES` | `51200` | Maximum byte size for last section (50KB) | -| Max Body Pair Size | `SUMMARIZER_MAX_BP_BYTES` | `16384` | Maximum byte size for a single body pair (16KB) | -| Max QA Sections | `SUMMARIZER_MAX_QA_SECTIONS` | `10` | Maximum QA pair sections to preserve | -| Max QA Size | `SUMMARIZER_MAX_QA_BYTES` | `65536` | Maximum byte size for QA pair sections (64KB) | -| Keep QA Sections | `SUMMARIZER_KEEP_QA_SECTIONS` | `1` | Number of recent QA sections to keep without summarization | +| 保留最后一段 | `SUMMARIZER_PRESERVE_LAST` | `true` | 是否完整保留最后一段中的所有消息 | +| 使用 QA 配对 | `SUMMARIZER_USE_QA` | `true` | 是否使用 QA 配对摘要策略 | +| 摘要 QA 中的人类消息 | `SUMMARIZER_SUM_MSG_HUMAN_IN_QA` | `false` | 是否对 QA 配对中的人类消息进行摘要 | +| 最后一段大小 | `SUMMARIZER_LAST_SEC_BYTES` | `51200` | 最后一段的最大字节大小（50KB） | +| 最大正文配对大小 | `SUMMARIZER_MAX_BP_BYTES` | `16384` | 单个正文配对的最大字节大小（16KB） | +| 最大 QA 段数 | `SUMMARIZER_MAX_QA_SECTIONS` | `10` | 最多保留的 QA 配对段数 | +| 最大 QA 大小 | `SUMMARIZER_MAX_QA_BYTES` | `65536` | QA 配对段的最大字节大小（64KB） | +| 保留 QA 段数 | `SUMMARIZER_KEEP_QA_SECTIONS` | `1` | 保留最近 QA 段的数量（不进行摘要） | -### Assistant Summarizer Configuration Options +### Assistant 摘要器配置选项 -Assistant instances can use customized summarization settings to fine-tune context management behavior: +Assistant 实例可使用自定义摘要设置来微调上下文管理行为： -| Parameter | Environment Variable | Default | Description | +| 参数 | 环境变量 | 默认值 | 说明 | | ------------------ | --------------------------------------- | ------- | -------------------------------------------------------------------- | -| Preserve Last | `ASSISTANT_SUMMARIZER_PRESERVE_LAST` | `true` | Whether to preserve all messages in the assistant's last section | -| Last Section Size | `ASSISTANT_SUMMARIZER_LAST_SEC_BYTES` | `76800` | Maximum byte size for assistant's last section (75KB) | -| Max Body Pair Size | `ASSISTANT_SUMMARIZER_MAX_BP_BYTES` | `16384` | Maximum byte size for a single body pair in assistant context (16KB) | -| Max QA Sections | `ASSISTANT_SUMMARIZER_MAX_QA_SECTIONS` | `7` | Maximum QA sections to preserve in assistant context | -| Max QA Size | `ASSISTANT_SUMMARIZER_MAX_QA_BYTES` | `76800` | Maximum byte size for assistant's QA sections (75KB) | -| Keep QA Sections | `ASSISTANT_SUMMARIZER_KEEP_QA_SECTIONS` | `3` | Number of recent QA sections to preserve without summarization | +| 保留最后一段 | `ASSISTANT_SUMMARIZER_PRESERVE_LAST` | `true` | 是否保留 assistant 最后一段中的所有消息 | +| 最后一段大小 | `ASSISTANT_SUMMARIZER_LAST_SEC_BYTES` | `76800` | assistant 最后一段的最大字节大小（75KB） | +| 最大 Body Pair 大小 | `ASSISTANT_SUMMARIZER_MAX_BP_BYTES` | `16384` | assistant 上下文中单个 body pair 的最大字节大小（16KB） | +| 最大 QA 段数 | `ASSISTANT_SUMMARIZER_MAX_QA_SECTIONS` | `7` | 在 assistant 上下文中保留的最大 QA 段数 | +| 最大 QA 大小 | `ASSISTANT_SUMMARIZER_MAX_QA_BYTES` | `76800` | assistant QA 段的最大字节大小（75KB） | +| 保留 QA 段数 | `ASSISTANT_SUMMARIZER_KEEP_QA_SECTIONS` | `3` | 不进行摘要而保留的最近 QA 段数量 | -The assistant summarizer configuration provides more memory for context retention compared to the global settings, preserving more recent conversation history while still ensuring efficient token usage. +与全局设置相比，assistant 摘要器配置为上下文保留提供更多内存，在保留更多近期对话历史的同时仍确保高效的 token 使用。 -### Summarizer Environment Configuration +### 摘要器环境配置 ```bash # Default values for global summarizer logic @@ -456,137 +462,137 @@ ASSISTANT_SUMMARIZER_KEEP_QA_SECTIONS=3
-Advanced Agent Supervision (click to expand) +高级 Agent 监管（点击展开） -PentAGI includes sophisticated multi-layered agent supervision mechanisms to ensure efficient task execution, prevent infinite loops, and provide intelligent recovery from stuck states: +PentAGI 包含复杂的多层 agent 监管机制，以确保高效的任务执行、防止无限循环，并在陷入卡住状态时提供智能恢复： -### Execution Monitoring (Beta) -- **Automatic Mentor Intervention**: Adviser agent (mentor) is automatically invoked when execution patterns indicate potential issues -- **Pattern Detection**: Monitors identical tool calls (threshold: 5, configurable) and total tool calls (threshold: 10, configurable) -- **Progress Analysis**: Evaluates whether agent advances toward subtask objective, detects loops and inefficiencies -- **Alternative Strategies**: Recommends different approaches when current strategy fails -- **Information Retrieval Guidance**: Suggests searching for established solutions instead of reinventing -- **Enhanced Response Format**: Tool responses include both `` and `` sections -- **Configurable**: Enable via `EXECUTION_MONITOR_ENABLED` (default: false), customize thresholds with `EXECUTION_MONITOR_SAME_TOOL_LIMIT` and `EXECUTION_MONITOR_TOTAL_TOOL_LIMIT` +### 执行监控（Beta） +- **自动 Mentor 干预**：当执行模式表明可能存在问题时，会自动调用 Adviser agent（mentor） +- **模式检测**：监控相同的工具调用（阈值：5，可配置）和工具调用总数（阈值：10，可配置） +- **进度分析**：评估 agent 是否朝着子任务目标推进，检测循环和低效情况 +- **替代策略**：当前策略失败时推荐不同方法 +- **信息检索指导**：建议搜索已有解决方案，而非重新发明 +- **增强响应格式**：工具响应同时包含 `` 和 `` 段 +- **可配置**：通过 `EXECUTION_MONITOR_ENABLED` 启用（默认：false），使用 `EXECUTION_MONITOR_SAME_TOOL_LIMIT` 和 `EXECUTION_MONITOR_TOTAL_TOOL_LIMIT` 自定义阈值 -**Best for**: Smaller models (< 32B parameters), complex attack scenarios requiring continuous guidance, preventing agents from getting stuck on single approach +**最适合**：较小模型（< 32B 参数）、需要持续指导的复杂攻击场景、防止 agent 卡在单一方法上 -**Performance Impact**: 2-3x increase in execution time and token usage, but delivers **2x improvement in result quality** based on testing with Qwen3.5-27B-FP8 +**性能影响**：执行时间和 token 使用量增加 2-3 倍，但根据 Qwen3.5-27B-FP8 的测试，**结果质量提升 2 倍** -### Intelligent Task Planning (Beta) -- **Automated Decomposition**: Planner (adviser in planning mode) generates 3-7 specific, actionable steps before specialist agents begin work -- **Context-Aware Plans**: Analyzes full execution context via enricher agent to create informed plans -- **Structured Assignment**: Original request wrapped in `` structure with execution plan and instructions -- **Scope Management**: Prevents scope creep by keeping agents focused on current subtask only -- **Enriched Instructions**: Plans highlight critical actions, potential pitfalls, and verification points -- **Configurable**: Enable via `AGENT_PLANNING_STEP_ENABLED` (default: false) +### 智能任务规划（Beta） +- **自动分解**：Planner（规划模式下的 adviser）在 specialist agent 开始工作前生成 3-7 个具体可执行的步骤 +- **上下文感知计划**：通过 enricher agent 分析完整执行上下文以制定知情计划 +- **结构化分配**：原始请求包装在 `` 结构中，包含执行计划和指令 +- **范围管理**：通过让 agent 仅专注于当前子任务来防止范围蔓延 +- **增强指令**：计划突出关键操作、潜在陷阱和验证点 +- **可配置**：通过 `AGENT_PLANNING_STEP_ENABLED` 启用（默认：false） -**Best for**: Models < 32B parameters, complex penetration testing workflows, improving success rates on sophisticated tasks +**最适合**：< 32B 参数的模型、复杂渗透测试工作流、提高复杂任务的成功率 -**Enhanced Adviser Configuration**: Works exceptionally well when adviser agent uses stronger model or enhanced settings. Example: using same base model with maximum reasoning mode for adviser (see [`vllm-qwen3.5-27b-fp8.provider.yml`](examples/configs/vllm-qwen3.5-27b-fp8.provider.yml)) enables comprehensive task analysis and strategic planning from identical model architecture. +**增强 Adviser 配置**：当 adviser agent 使用更强模型或增强设置时效果特别好。示例：对 adviser 使用相同基础模型并开启最大推理模式（参见 [`vllm-qwen3.5-27b-fp8.provider.yml`](examples/configs/vllm-qwen3.5-27b-fp8.provider.yml)）可在相同模型架构下实现全面的任务分析和战略规划。 -**Performance Impact**: Adds planning overhead but significantly improves completion rates and reduces redundant work +**性能影响**：增加规划开销，但显著提高完成率并减少冗余工作 -### Tool Call Limits (Always Active) -- **Hard Limits**: Prevent runaway executions regardless of supervision mode status -- **Differentiated by Agent Type**: - - General agents (Assistant, Primary Agent, Pentester, Coder, Installer): `MAX_GENERAL_AGENT_TOOL_CALLS` (default: 100) - - Limited agents (Searcher, Enricher, Memorist, Generator, Reporter, Adviser, Reflector, Planner): `MAX_LIMITED_AGENT_TOOL_CALLS` (default: 20) -- **Graceful Termination**: Reflector guides agents to proper completion when approaching limits -- **Resource Protection**: Ensures system stability and prevents resource exhaustion +### 工具调用限制（始终启用） +- **硬性限制**：无论监管模式状态如何，均可防止失控执行 +- **按 Agent 类型区分**： + - 通用 agent（Assistant、Primary Agent、Pentester、Coder、Installer）：`MAX_GENERAL_AGENT_TOOL_CALLS`（默认：100） + - 受限 agent（Searcher、Enricher、Memorist、Generator、Reporter、Adviser、Reflector、Planner）：`MAX_LIMITED_AGENT_TOOL_CALLS`（默认：20） +- **优雅终止**：接近限制时 Reflector 引导 agent 正确完成 +- **资源保护**：确保系统稳定并防止资源耗尽 -### Reflector Integration (Always Active) -- **Automatic Correction**: Invoked when LLM fails to generate tool calls after 3 attempts -- **Strategic Guidance**: Analyzes failures and guides agents toward proper tool usage or barrier tools (`done`, `ask`) -- **Recovery Mechanism**: Provides contextual guidance based on specific failure patterns -- **Limit Enforcement**: Coordinates graceful termination when tool call limits are reached +### Reflector 集成（始终启用） +- **自动纠正**：LLM 在 3 次尝试后仍未能生成工具调用时触发 +- **战略指导**：分析失败并引导 agent 正确使用工具或屏障工具（`done`、`ask`） +- **恢复机制**：根据特定失败模式提供上下文指导 +- **限制执行**：达到工具调用限制时协调优雅终止 -### Recommendations for Open Source Models +### 开源模型建议 -**Must-Have for Models < 32B Parameters**: -Testing with Qwen3.5-27B-FP8 demonstrates that enabling both Execution Monitoring and Task Planning is **essential** for smaller open source models: -- **Quality Improvement**: 2x better results compared to baseline execution without supervision -- **Loop Prevention**: Significantly reduces infinite loops and redundant work -- **Attack Diversity**: Encourages exploration of multiple attack vectors instead of fixating on single approach -- **Air-Gapped Deployments**: Enables production-grade autonomous pentesting in closed network environments with local LLM inference +**< 32B 参数模型必备**： +Qwen3.5-27B-FP8 的测试表明，对于较小的开源模型，同时启用执行监控和任务规划是**必不可少的**： +- **质量提升**：与无监管的基线执行相比，结果好 2 倍 +- **循环预防**：显著减少无限循环和冗余工作 +- **攻击多样性**：鼓励探索多种攻击向量，而非执着于单一方法 +- **气隙部署**：在封闭网络环境中通过本地 LLM 推理实现生产级自主渗透测试 -**Trade-offs**: -- Token consumption: 2-3x increase due to mentor/planner invocations -- Execution time: 2-3x longer due to analysis and planning steps -- Result quality: 2x improvement in completeness, accuracy, and attack coverage -- Model requirements: Works best when adviser uses enhanced configuration (higher reasoning parameters, stronger model variant, or different model) +**权衡**： +- Token 消耗：由于 mentor/planner 调用增加 2-3 倍 +- 执行时间：由于分析和规划步骤延长 2-3 倍 +- 结果质量：完整性、准确性和攻击覆盖度提升 2 倍 +- 模型要求：adviser 使用增强配置时效果最佳（更高推理参数、更强模型变体或不同模型） -**Configuration Strategy**: -For optimal performance with smaller models, configure adviser agent with enhanced settings: -- Use same model with maximum reasoning mode (example: [`vllm-qwen3.5-27b-fp8.provider.yml`](examples/configs/vllm-qwen3.5-27b-fp8.provider.yml)) -- Or use stronger model for adviser while keeping base model for other agents -- Adjust monitoring thresholds based on task complexity and model capabilities +**配置策略**： +为在较小模型上获得最佳性能，请为 adviser agent 配置增强设置： +- 使用相同模型并开启最大推理模式（示例：[`vllm-qwen3.5-27b-fp8.provider.yml`](examples/configs/vllm-qwen3.5-27b-fp8.provider.yml)） +- 或为 adviser 使用更强模型，同时为其他 agent 保留基础模型 +- 根据任务复杂度和模型能力调整监控阈值
-The architecture of PentAGI is designed to be modular, scalable, and secure. Here are the key components: +PentAGI 的架构设计为模块化、可扩展且安全。以下是关键组件： -1. **Core Services** - - Frontend UI: React-based web interface with TypeScript for type safety - - Backend API: Go-based REST and GraphQL APIs with Bearer token authentication for programmatic access - - Vector Store: PostgreSQL with pgvector for semantic search and memory storage - - Task Queue: Async task processing system for reliable operation - - AI Agent: Multi-agent system with specialized roles for efficient testing +1. **核心服务** + - Frontend UI：基于 React 的 Web 界面，使用 TypeScript 确保类型安全 + - Backend API：基于 Go 的 REST 和 GraphQL API，支持 Bearer token 认证以实现程序化访问 + - Vector Store：PostgreSQL 配合 pgvector 用于语义搜索和记忆存储 + - Task Queue：异步任务处理系统，确保可靠运行 + - AI Agent：多 agent 系统，具有专门角色以实现高效测试 -2. **Knowledge Graph** - - Graphiti: Knowledge graph API for semantic relationship tracking and contextual understanding - - Neo4j: Graph database for storing and querying relationships between entities, actions, and outcomes - - Automatic capturing of agent responses and tool executions for building comprehensive knowledge base +2. **知识图谱（Knowledge Graph）** + - Graphiti：用于语义关系追踪与上下文理解的知识图谱 API + - Neo4j：用于存储和查询实体、操作与结果之间关系的图数据库 + - 自动捕获智能体响应与工具执行，以构建全面的知识库 -3. **Monitoring Stack** - - OpenTelemetry: Unified observability data collection and correlation - - Grafana: Real-time visualization and alerting dashboards - - VictoriaMetrics: High-performance time-series metrics storage - - Jaeger: End-to-end distributed tracing for debugging - - Loki: Scalable log aggregation and analysis +3. **监控栈（Monitoring Stack）** + - OpenTelemetry：统一的可观测性数据采集与关联 + - Grafana：实时可视化与告警仪表板 + - VictoriaMetrics：高性能时序指标存储 + - Jaeger：用于调试的端到端分布式追踪 + - Loki：可扩展的日志聚合与分析 -4. **Analytics Platform** - - Langfuse: Advanced LLM observability and performance analytics - - ClickHouse: Column-oriented analytics data warehouse - - Redis: High-speed caching and rate limiting - - MinIO: S3-compatible object storage for artifacts +4. **分析平台（Analytics Platform）** + - Langfuse：高级 LLM 可观测性与性能分析 + - ClickHouse：面向列的分析型数据仓库 + - Redis：高速缓存与速率限制 + - MinIO：用于存储产物的 S3 兼容对象存储 -5. **Security Tools** - - Web Scraper: Isolated browser environment for safe web interaction - - Pentesting Tools: Comprehensive suite of 20+ professional security tools - - Sandboxed Execution: All operations run in isolated containers +5. **安全工具（Security Tools）** + - Web Scraper：用于安全网页交互的隔离浏览器环境 + - Pentesting Tools：包含 20+ 款专业安全工具的综合套件 + - Sandboxed Execution：所有操作均在隔离容器中运行 -6. **Memory Systems** - - Long-term Memory: Persistent storage of knowledge and experiences - - Working Memory: Active context and goals for current operations - - Episodic Memory: Historical actions and success patterns - - Knowledge Base: Structured domain expertise and tool capabilities - - Context Management: Intelligently manages growing LLM context windows using chain summarization +6. **记忆系统（Memory Systems）** + - Long-term Memory：知识与经验的持久化存储 + - Working Memory：当前操作的活跃上下文与目标 + - Episodic Memory：历史操作与成功模式 + - Knowledge Base：结构化的领域专业知识与工具能力 + - Context Management：通过链式摘要智能管理不断增长的 LLM 上下文窗口 -The system uses Docker containers for isolation and easy deployment, with separate networks for core services, monitoring, and analytics to ensure proper security boundaries. Each component is designed to scale horizontally and can be configured for high availability in production environments. +系统使用 Docker 容器实现隔离与便捷部署，为核心服务、监控和分析划分独立网络，以确保适当的安全边界。每个组件均支持水平扩展，并可针对生产环境配置为高可用。 -## Quick Start +## 快速开始 -### System Requirements +### 系统要求 -- Docker and Docker Compose (or Podman - see [Podman configuration](#running-pentagi-with-podman)) -- Minimum 2 vCPU -- Minimum 4GB RAM -- 20GB free disk space -- Internet access for downloading images and updates +- Docker 与 Docker Compose（或 Podman — 参见 [Podman 配置](#running-pentagi-with-podman)） +- 至少 2 个 vCPU +- 至少 4GB RAM +- 20GB 可用磁盘空间 +- 可访问互联网以下载镜像与更新 -### Using Installer (Recommended) +### 使用安装程序（推荐） -PentAGI provides an interactive installer with a terminal-based UI for streamlined configuration and deployment. The installer guides you through system checks, LLM provider setup, search engine configuration, and security hardening. +PentAGI 提供带终端界面的交互式安装程序，用于简化配置与部署。安装程序会引导你完成系统检查、LLM 提供商设置、搜索引擎配置以及安全加固。 -**Supported Platforms:** -- **Linux**: amd64 [download](https://pentagi.com/downloads/linux/amd64/installer-latest.zip) | arm64 [download](https://pentagi.com/downloads/linux/arm64/installer-latest.zip) -- **Windows**: amd64 [download](https://pentagi.com/downloads/windows/amd64/installer-latest.zip) -- **macOS**: amd64 (Intel) [download](https://pentagi.com/downloads/darwin/amd64/installer-latest.zip) | arm64 (M-series) [download](https://pentagi.com/downloads/darwin/arm64/installer-latest.zip) +**支持的平台：** +- **Linux**：amd64 [download](https://pentagi.com/downloads/linux/amd64/installer-latest.zip) | arm64 [download](https://pentagi.com/downloads/linux/arm64/installer-latest.zip) +- **Windows**：amd64 [download](https://pentagi.com/downloads/windows/amd64/installer-latest.zip) +- **macOS**：amd64 (Intel) [download](https://pentagi.com/downloads/darwin/amd64/installer-latest.zip) | arm64 (M-series) [download](https://pentagi.com/downloads/darwin/arm64/installer-latest.zip) -**Quick Installation (Linux amd64):** +**快速安装（Linux amd64）：** ```bash # Create installation directory @@ -602,16 +608,16 @@ unzip installer.zip ./installer ``` -**Prerequisites & Permissions:** +**前提条件与权限：** -The installer requires appropriate privileges to interact with the Docker API for proper operation. By default, it uses the Docker socket (`/var/run/docker.sock`) which requires either: +安装程序需要适当权限以与 Docker API 交互，从而正常运行。默认情况下，它使用 Docker 套接字（`/var/run/docker.sock`），这需要满足以下任一条件： -- **Option 1 (Recommended for production):** Run the installer as root: +- **选项 1（生产环境推荐）：** 以 root 身份运行安装程序： ```bash sudo ./installer ``` -- **Option 2 (Development environments):** Grant your user access to the Docker socket by adding them to the `docker` group: +- **选项 2（开发环境）：** 将用户加入 `docker` 组，以授予其对 Docker 套接字的访问权限： ```bash # Add your user to the docker group sudo usermod -aG docker $USER @@ -623,68 +629,68 @@ The installer requires appropriate privileges to interact with the Docker API fo docker ps ``` - ⚠️ **Security Note:** Adding a user to the `docker` group grants root-equivalent privileges. Only do this for trusted users in controlled environments. For production deployments, consider using rootless Docker mode or running the installer with sudo. + ⚠️ **安全提示：** 将用户加入 `docker` 组会授予与 root 等效的权限。仅在受控环境中的可信用户上执行此操作。对于生产部署，请考虑使用 rootless Docker 模式，或以 sudo 运行安装程序。 -The installer will: -1. **System Checks**: Verify Docker, network connectivity, and system requirements -2. **Environment Setup**: Create and configure `.env` file with optimal defaults -3. **Provider Configuration**: Set up LLM providers (OpenAI, Anthropic, Gemini, Bedrock, Ollama, Custom) -4. **Search Engines**: Configure DuckDuckGo, Google, Tavily, Traversaal, Perplexity, Sploitus, Searxng -5. **Security Hardening**: Generate secure credentials and configure SSL certificates -6. **Deployment**: Start PentAGI with docker-compose +安装程序将执行以下步骤： +1. **系统检查**：验证 Docker、网络连接与系统要求 +2. **环境设置**：创建并配置 `.env` 文件，采用最优默认值 +3. **提供商配置**：设置 LLM 提供商（OpenAI、Anthropic、Gemini、Bedrock、Ollama、Custom） +4. **搜索引擎**：配置 DuckDuckGo、Google、Tavily、Traversaal、Perplexity、Sploitus、Searxng +5. **安全加固**：生成安全凭据并配置 SSL 证书 +6. **部署**：使用 docker-compose 启动 PentAGI -### Current Web Settings Coverage +### 当前 Web 设置覆盖范围 -The PentAGI web console already manages several settings areas after the server is up and running: +PentAGI Web 控制台在服务器启动运行后，已可管理多个设置区域： -- **Settings -> Providers**: Create, edit, delete, and test user-defined provider profiles for supported provider types. These profiles control per-agent model selection, runtime parameters, reasoning options, and pricing metadata. -- **Settings -> Prompts**: Manage system, human, and tool prompt templates. -- **Settings -> PentAGI API**: Create and manage PentAGI Bearer tokens for REST and GraphQL access. -- **Other UI-managed preferences**: Favorite flows are stored as user preferences, and theme selection is handled from the main sidebar/profile controls rather than the Settings pages. +- **Settings -> Providers**：为支持的提供商类型创建、编辑、删除并测试用户自定义的提供商配置文件。这些配置文件控制每个智能体的模型选择、运行时参数、推理选项以及定价元数据。 +- **Settings -> Prompts**：管理系统、人类与工具提示词模板。 +- **Settings -> PentAGI API**：创建并管理用于 REST 与 GraphQL 访问的 PentAGI Bearer 令牌。 +- **其他由 UI 管理的偏好设置**：收藏流程以用户偏好形式存储，主题选择由主侧边栏/个人资料控件处理，而非 Settings 页面。 -### Still Server-Managed +### 仍由服务器管理 -The following configuration areas still need to be set on the server through environment variables, compose files, or mounted config files: +以下配置区域仍需通过环境变量、compose 文件或挂载的配置文件在服务器端设置： -- **LLM credentials and connection details**: API keys, endpoints, auth modes, and provider-specific connection settings for OpenAI, Anthropic, Bedrock, Ollama, custom providers, and similar backends; config-path settings apply only where supported, such as `OLLAMA_SERVER_CONFIG_PATH` and `LLM_SERVER_CONFIG_PATH`. -- **Search provider credentials and options**: Settings such as `DUCKDUCKGO_*`, `GOOGLE_*`, `TAVILY_API_KEY`, `TRAVERSAAL_API_KEY`, `PERPLEXITY_*`, `SEARXNG_*`, and `SPLOITUS_ENABLED`. -- **Third-party integrations**: Langfuse, Graphiti, and similar external services remain server-side configuration. -- **MCP server management**: MCP settings pages are not currently exposed as a live web-console feature. +- **LLM 凭据与连接详情**：OpenAI、Anthropic、Bedrock、Ollama、自定义提供商及类似后端的 API 密钥、端点、认证模式与提供商特定连接设置；config-path 设置仅在受支持的场景下适用，例如 `OLLAMA_SERVER_CONFIG_PATH` 与 `LLM_SERVER_CONFIG_PATH`。 +- **搜索提供商凭据与选项**：如 `DUCKDUCKGO_*`、`GOOGLE_*`、`TAVILY_API_KEY`、`TRAVERSAAL_API_KEY`、`PERPLEXITY_*`、`SEARXNG_*` 以及 `SPLOITUS_ENABLED` 等设置。 +- **第三方集成**：Langfuse、Graphiti 及类似外部服务仍为服务器端配置。 +- **MCP 服务器管理**：MCP 设置页面目前尚未作为实时 Web 控制台功能开放。 -**For Production & Enhanced Security:** +**面向生产环境与增强安全性：** -For production deployments or security-sensitive environments, we **strongly recommend** using a distributed two-node architecture where worker operations are isolated on a separate server. This prevents untrusted code execution and network access issues on your main system. +对于生产部署或安全敏感环境，我们**强烈建议**采用分布式双节点架构，将 worker 操作隔离在独立服务器上。这可防止不可信代码执行与主系统上的网络访问问题。 -**See detailed guide**: [Worker Node Setup](examples/guides/worker_node.md) +**详见详细指南**：[Worker Node Setup](examples/guides/worker_node.md) -The two-node setup provides: -- **Isolated Execution**: Worker containers run on dedicated hardware -- **Network Isolation**: Separate network boundaries for penetration testing -- **Security Boundaries**: Docker-in-Docker with TLS authentication -- **OOB Attack Support**: Dedicated port ranges for out-of-band techniques +双节点部署提供： +- **隔离执行**：Worker 容器在专用硬件上运行 +- **网络隔离**：渗透测试采用独立的网络边界 +- **安全边界**：带 TLS 认证的 Docker-in-Docker +- **OOB 攻击支持**：为带外（out-of-band）技术提供专用端口范围 -### Manual Installation +### 手动安装 -1. Create a working directory or clone the repository: +1. 创建工作目录或克隆仓库： ```bash mkdir pentagi && cd pentagi ``` -2. Copy `.env.example` to `.env` or download it: +2. 将 `.env.example` 复制为 `.env`，或下载它： ```bash curl -o .env https://raw.githubusercontent.com/vxcontrol/pentagi/master/.env.example ``` -3. Touch examples files (`example.custom.provider.yml`, `example.ollama.provider.yml`) or download it: +3. 创建示例文件（`example.custom.provider.yml`、`example.ollama.provider.yml`），或下载它： ```bash curl -o example.custom.provider.yml https://raw.githubusercontent.com/vxcontrol/pentagi/master/examples/configs/custom-openai.provider.yml curl -o example.ollama.provider.yml https://raw.githubusercontent.com/vxcontrol/pentagi/master/examples/configs/ollama-llama318b.provider.yml ``` -4. Fill in the required API keys in `.env` file. +4. 在 `.env` 文件中填写所需的 API 密钥。 ```bash # Required: At least one of these LLM providers @@ -753,72 +759,72 @@ NEO4J_URI=bolt://neo4j:7687 ASSISTANT_USE_AGENTS=false # Default value for agent usage when creating new assistants ``` -5. Change all security related environment variables in `.env` file to improve security. +5. 修改 `.env` 文件中所有与安全相关的环境变量，以提升安全性。
- Security related environment variables + 与安全相关的环境变量 -### Main Security Settings -- `COOKIE_SIGNING_SALT` - Salt for cookie signing, change to random value -- `PUBLIC_URL` - Public URL of your server (eg. `https://pentagi.example.com`) -- `SERVER_SSL_CRT` and `SERVER_SSL_KEY` - Custom paths to your existing SSL certificate and key for HTTPS (these paths should be used in the docker-compose.yml file to mount as volumes) +### 主要安全设置 +- `COOKIE_SIGNING_SALT` - 用于 Cookie 签名的盐值，请改为随机值 +- `PUBLIC_URL` - 服务器的公开 URL（例如 `https://pentagi.example.com`） +- `SERVER_SSL_CRT` 和 `SERVER_SSL_KEY` - 现有 SSL 证书与密钥的自定义路径，用于 HTTPS（这些路径应在 docker-compose.yml 文件中作为卷挂载使用） -### Scraper Access -- `SCRAPER_PUBLIC_URL` - Public URL for scraper if you want to use different scraper server for public URLs -- `SCRAPER_PRIVATE_URL` - Private URL for scraper (local scraper server in docker-compose.yml file to access it to local URLs) +### 爬虫（Scraper）访问 +- `SCRAPER_PUBLIC_URL` - 若要为公开 URL 使用不同的爬虫服务器，请设置爬虫的公开 URL +- `SCRAPER_PRIVATE_URL` - 爬虫的私有 URL（docker-compose.yml 文件中的本地爬虫服务器，用于访问本地 URL） -### Access Credentials -- `PENTAGI_POSTGRES_USER` and `PENTAGI_POSTGRES_PASSWORD` - PostgreSQL credentials -- `NEO4J_USER` and `NEO4J_PASSWORD` - Neo4j credentials (for Graphiti knowledge graph) +### 访问凭据 +- `PENTAGI_POSTGRES_USER` 和 `PENTAGI_POSTGRES_PASSWORD` - PostgreSQL 凭据 +- `NEO4J_USER` 和 `NEO4J_PASSWORD` - Neo4j 凭据（用于 Graphiti 知识图谱）
-6. Remove all inline comments from `.env` file if you want to use it in VSCode or other IDEs as a envFile option: +6. 若要在 VSCode 或其他 IDE 中将其作为 envFile 选项使用，请移除 `.env` 文件中的所有行内注释： ```bash perl -i -pe 's/\s+#.*$//' .env ``` -7. Run the PentAGI stack: +7. 运行 PentAGI 栈： ```bash curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/master/docker-compose.yml docker compose up -d ``` -Visit [localhost:8443](https://localhost:8443) to access PentAGI Web UI (default is `admin@pentagi.com` / `admin`) +访问 [localhost:8443](https://localhost:8443) 以打开 PentAGI Web UI（默认为 `admin@pentagi.com` / `admin`） -#### Web UI Accounts +#### Web UI 账户 -PentAGI does not expose public self-service sign-up from the login page. A fresh installation creates the default local administrator account: +PentAGI 不会在登录页提供公开的自助注册。全新安装会创建默认的本地管理员账户： -- **Email**: `admin@pentagi.com` -- **Password**: `admin` +- **Email**：`admin@pentagi.com` +- **Password**：`admin` -On first login, change the default password before using the instance for real work. If the administrator password is lost later, use the installer maintenance menu to reset the default `admin@pentagi.com` account password. +首次登录时，请在使用该实例进行实际工作前修改默认密码。若之后遗失管理员密码，可使用安装程序的维护菜单重置默认 `admin@pentagi.com` 账户密码。 -For multi-user setups, an authenticated administrator can manage local users through the Users REST API (`/api/v1/users/`). The OpenAPI UI is available at `https://localhost:8443/api/v1/swagger/index.html` after the instance is running. +对于多用户部署，已认证的管理员可通过 Users REST API（`/api/v1/users/`）管理本地用户。实例运行后，可在 `https://localhost:8443/api/v1/swagger/index.html` 访问 OpenAPI UI。 > [!NOTE] -> If you caught an error about `pentagi-network` or `observability-network` or `langfuse-network` you need to run `docker-compose.yml` firstly to create these networks and after that run `docker-compose-langfuse.yml`, `docker-compose-graphiti.yml`, and `docker-compose-observability.yml` to use Langfuse, Graphiti, and Observability services. +> 若遇到与 `pentagi-network`、`observability-network` 或 `langfuse-network` 相关的错误，需先运行 `docker-compose.yml` 以创建这些网络，然后再运行 `docker-compose-langfuse.yml`、`docker-compose-graphiti.yml` 和 `docker-compose-observability.yml`，才能使用 Langfuse、Graphiti 和 Observability 服务。 > -> You have to set at least one Language Model provider (OpenAI, Anthropic, Gemini, AWS Bedrock, or Ollama) to use PentAGI. AWS Bedrock provides enterprise-grade access to multiple foundation models from leading AI companies, while Ollama provides zero-cost local inference if you have sufficient computational resources. Additional API keys for search engines are optional but recommended for better results. +> 必须至少配置一个语言模型（Language Model）提供商（OpenAI、Anthropic、Gemini、AWS Bedrock 或 Ollama）才能使用 PentAGI。AWS Bedrock 提供企业级访问，可调用多家领先 AI 公司的基础模型；若具备足够的计算资源，Ollama 可提供零成本的本地推理。搜索引擎的额外 API 密钥为可选项，但建议配置以获得更好效果。 > -> **For fully local deployment with advanced models**: See our comprehensive guide on [Running PentAGI with vLLM and Qwen3.5-27B-FP8](examples/guides/vllm-qwen35-27b-fp8.md) for a production-grade local LLM setup. This configuration achieves ~13,000 TPS for prompt processing and ~650 TPS for completion on 4× RTX 5090 GPUs, supporting 12+ concurrent flows with complete independence from cloud providers. +> **完全本地部署并使用高级模型**：请参阅我们的完整指南 [使用 vLLM 与 Qwen3.5-27B-FP8 运行 PentAGI](examples/guides/vllm-qwen35-27b-fp8.md)，了解生产级本地 LLM 配置。该方案在 4× RTX 5090 GPU 上可实现约 13,000 TPS 的提示处理吞吐与约 650 TPS 的补全吞吐，支持 12+ 个并发流程，且完全不依赖云服务商。 > -> `LLM_SERVER_*` environment variables are experimental feature and will be changed in the future. Right now you can use them to specify custom LLM server URL and one model for all agent types. +> `LLM_SERVER_*` 环境变量为实验性功能，未来可能会变更。目前可用它们指定自定义 LLM 服务器 URL，并为所有智能体类型指定同一模型。 > -> `PROXY_URL` is a global proxy URL for all LLM providers and external search systems. You can use it for isolation from external networks. +> `PROXY_URL` 是所有 LLM 提供商与外部搜索系统的全局代理 URL，可用于与外部网络隔离。 > -> The `docker-compose.yml` file runs the PentAGI service as root user because it needs access to docker.sock for container management. If you're using TCP/IP network connection to Docker instead of socket file, you can remove root privileges and use the default `pentagi` user for better security. +> `docker-compose.yml` 文件以 root 用户运行 PentAGI 服务，因为需要访问 docker.sock 以管理容器。若使用 TCP/IP 网络连接 Docker 而非套接字文件，可移除 root 权限，改用默认的 `pentagi` 用户以提升安全性。 -### Accessing PentAGI from External Networks +### 从外部网络访问 PentAGI -By default, PentAGI binds to `127.0.0.1` (localhost only) for security. To access PentAGI from other machines on your network, you need to configure external access. +默认情况下，PentAGI 绑定到 `127.0.0.1`（仅 localhost），以确保安全。若要从网络中的其他机器访问 PentAGI，需要配置外部访问。 -#### Configuration Steps +#### 配置步骤 -1. **Update `.env` file** with your server's IP address: +1. **更新 `.env` 文件**，填入服务器的 IP 地址： ```bash # Network binding - allow external connections @@ -835,35 +841,35 @@ CORS_ORIGINS=https://localhost:8443,https://192.168.1.100:8443 ``` > [!IMPORTANT] -> - Replace `192.168.1.100` with your actual server's IP address -> - Do NOT use `0.0.0.0` in `PUBLIC_URL` or `CORS_ORIGINS` - use the actual IP address -> - Include both localhost and your server IP in `CORS_ORIGINS` for flexibility +> - 将 `192.168.1.100` 替换为服务器的实际 IP 地址 +> - 不要在 `PUBLIC_URL` 或 `CORS_ORIGINS` 中使用 `0.0.0.0` —— 应使用实际 IP 地址 +> - 在 `CORS_ORIGINS` 中同时包含 localhost 与服务器 IP，以便灵活使用 -2. **Recreate containers** to apply the changes: +2. **重新创建容器**以应用更改： ```bash docker compose down docker compose up -d --force-recreate ``` -3. **Verify port binding:** +3. **验证端口绑定：** ```bash docker ps | grep pentagi ``` -You should see `0.0.0.0:8443->8443/tcp` or `:::8443->8443/tcp`. +应看到 `0.0.0.0:8443->8443/tcp` 或 `:::8443->8443/tcp`。 -If you see `127.0.0.1:8443->8443/tcp`, the environment variable wasn't picked up. In this case, directly edit `docker-compose.yml` line 31: +若看到 `127.0.0.1:8443->8443/tcp`，说明环境变量未被读取。此时请直接编辑 `docker-compose.yml` 第 31 行： ```yaml ports: - "0.0.0.0:8443:8443" ``` -Then recreate containers again. +然后再次重新创建容器。 -4. **Configure firewall** to allow incoming connections on port 8443: +4. **配置防火墙**，允许 8443 端口的入站连接： ```bash # Ubuntu/Debian with UFW @@ -875,25 +881,25 @@ sudo firewall-cmd --permanent --add-port=8443/tcp sudo firewall-cmd --reload ``` -5. **Access PentAGI:** +5. **访问 PentAGI：** -- **Local access:** `https://localhost:8443` -- **Network access:** `https://your-server-ip:8443` +- **本地访问：** `https://localhost:8443` +- **网络访问：** `https://your-server-ip:8443` > [!NOTE] -> You'll need to accept the self-signed SSL certificate warning in your browser when accessing via IP address. +> 通过 IP 地址访问时，需要在浏览器中接受自签名 SSL 证书警告。 --- -### Running PentAGI with Podman +### 使用 Podman 运行 PentAGI -PentAGI fully supports Podman as a Docker alternative. However, when using **Podman in rootless mode**, the scraper service requires special configuration because rootless containers cannot bind privileged ports (ports below 1024). +PentAGI 完全支持 Podman 作为 Docker 的替代方案。但在使用 **Podman 无根（rootless）模式**时，爬虫服务需要特殊配置，因为无根容器无法绑定特权端口（1024 以下端口）。 -#### Podman Rootless Configuration +#### Podman 无根模式配置 -The default scraper configuration uses port 443 (HTTPS), which is a privileged port. For Podman rootless, reconfigure the scraper to use a non-privileged port: +默认爬虫配置使用 443 端口（HTTPS），属于特权端口。对于 Podman 无根模式，需将爬虫重新配置为使用非特权端口： -**1. Edit `docker-compose.yml`** - modify the `scraper` service (around line 199): +**1. 编辑 `docker-compose.yml`** —— 修改 `scraper` 服务（约第 199 行）： ```yaml scraper: @@ -920,7 +926,7 @@ scraper: shm_size: 2g ``` -**2. Update `.env` file** - change the scraper URL to use HTTP and port 3000: +**2. 更新 `.env` 文件** —— 将爬虫 URL 改为使用 HTTP 与 3000 端口： ```bash # Scraper configuration for Podman rootless @@ -930,157 +936,157 @@ LOCAL_SCRAPER_PASSWORD=somepass ``` > [!IMPORTANT] -> Key changes for Podman: -> - Use **HTTP** instead of HTTPS for `SCRAPER_PRIVATE_URL` -> - Use port **3000** instead of 443 -> - Change internal `expose` to `3000/tcp` -> - Update port mapping to target `3000` instead of `443` +> Podman 的关键变更： +> - `SCRAPER_PRIVATE_URL` 使用 **HTTP** 而非 HTTPS +> - 使用端口 **3000** 而非 443 +> - 将内部 `expose` 改为 `3000/tcp` +> - 将端口映射目标从 `443` 更新为 `3000` -**3. Recreate containers:** +**3. 重新创建容器：** ```bash podman-compose down podman-compose up -d --force-recreate ``` -**4. Test scraper connectivity:** +**4. 测试爬虫连通性：** ```bash # Test from within the pentagi container podman exec -it pentagi wget -O- "http://someuser:somepass@scraper:3000/html?url=http://example.com" ``` -If you see HTML output, the scraper is working correctly. +若看到 HTML 输出，说明爬虫工作正常。 -#### Podman Rootful Mode +#### Podman 有根（Rootful）模式 -If you're running Podman in rootful mode (with sudo), you can use the default configuration without modifications. The scraper will work on port 443 as intended. +若以有根模式运行 Podman（使用 sudo），可使用默认配置而无需修改。爬虫将按预期在 443 端口上工作。 -#### Docker Compatibility +#### Docker 兼容性 -All Podman configurations remain fully compatible with Docker. The non-privileged port approach works identically on both container runtimes. +所有 Podman 配置与 Docker 完全兼容。非特权端口方案在两种容器运行时上的工作方式相同。 -### Assistant Configuration +### 助手配置 -PentAGI allows you to configure default behavior for assistants: +PentAGI 允许你为助手配置默认行为： | Variable | Default | Description | | ---------------------- | ------- | ----------------------------------------------------------------------- | -| `ASSISTANT_USE_AGENTS` | `false` | Controls the default value for agent usage when creating new assistants | +| `ASSISTANT_USE_AGENTS` | `false` | 控制创建新助手时代理（agent）用量的默认值 | -The `ASSISTANT_USE_AGENTS` setting affects the initial state of the "Use Agents" toggle when creating a new assistant in the UI: -- `false` (default): New assistants are created with agent delegation disabled by default -- `true`: New assistants are created with agent delegation enabled by default +`ASSISTANT_USE_AGENTS` 设置会影响在 UI 中创建新助手时「Use Agents」开关的初始状态： +- `false`（默认）：新助手默认创建时禁用代理委派 +- `true`：新助手默认创建时启用代理委派 -Note that users can always override this setting by toggling the "Use Agents" button in the UI when creating or editing an assistant. This environment variable only controls the initial default state. +请注意，用户在创建或编辑助手时，始终可以通过 UI 中的「Use Agents」按钮覆盖此设置。该环境变量仅控制初始默认状态。 -## How to Use PentAGI After Login +## 登录后如何使用 PentAGI -Once the stack is running and you can sign in to the web UI, the fastest way to start is through the Flows workflow. +堆栈运行且你可以登录 Web UI 后，最快的入门方式是通过 Flows 工作流。 -### 1. Create your first flow +### 1. 创建你的第一个 flow -1. Open **Flows** in the sidebar. -2. Click **New Flow**. -3. Choose the mode that fits your goal: - - **Automation**: fully autonomous execution for a testing goal you want PentAGI to carry out end-to-end - - **Assistant**: interactive back-and-forth help when you want to steer the investigation step by step. In this mode you can also enable the **Use Agents** toggle to let PentAGI delegate subtasks to specialized sub-agents for more complex investigations. -4. Select the LLM provider you want to use for this flow. -5. Describe the target and the objective in natural language in the message box. +1. 在侧边栏中打开 **Flows**。 +2. 点击 **New Flow**。 +3. 选择符合你目标的运行模式： + - **Automation**：针对你希望 PentAGI 端到端完成的测试目标，进行完全自主执行 + - **Assistant**：当你希望逐步引导调查时，进行交互式来回协助。在此模式下，你还可以启用 **Use Agents** 开关，让 PentAGI 将子任务委派给专门的子代理（sub-agent），以应对更复杂的调查。 +4. 选择要用于此 flow 的 LLM 提供商。 +5. 在消息框中用自然语言描述目标与目的。 -Good first prompts usually include: +良好的首个提示通常包括： -- the target system or URL -- the type of assessment you want -- any scope limitations or rules of engagement -- the result you expect, such as a vulnerability report or validation of a hypothesis +- 目标系统或 URL +- 你想要的评估类型 +- 任何范围限制或交战规则（rules of engagement） +- 你期望的结果，例如漏洞报告或对假设的验证 -Example: +示例： ```text Assess https://target.example for common web application vulnerabilities. Focus on authentication, file handling, and injection issues. Stay within the provided target only and summarize confirmed findings with reproduction steps. ``` -Only test systems you own or are explicitly authorized to assess. See [EULA.md](EULA.md) for the acceptable use requirements. +仅测试你拥有或已获明确授权评估的系统。可接受使用要求请参阅 [EULA.md](EULA.md)。 -### 2. Use templates for repeatable workflows +### 2. 使用模板实现可重复的工作流 -The new flow form includes a template picker, which can prefill the message box with a saved flow template. This is useful when you run similar assessments repeatedly. +新建 flow 表单包含模板选择器，可用已保存的 flow 模板预填消息框。当你反复运行类似评估时，这很有用。 -- Use an existing template if you already have one saved in **Templates** -- Start from the example prompt in [`examples/prompts/base_web_pentest.md`](examples/prompts/base_web_pentest.md) if you need a practical baseline for web testing -- Adjust the target, scope, and constraints before starting the flow +- 若你已在 **Templates** 中保存模板，可使用现有模板 +- 若需要 Web 测试的实用基线，可从 [`examples/prompts/base_web_pentest.md`](examples/prompts/base_web_pentest.md) 中的示例提示入手 +- 启动 flow 前，请调整目标、范围和约束 -Templates are starting points. You do not need special syntax to use PentAGI: plain natural-language instructions work well as long as the target and goal are clear. +模板只是起点。使用 PentAGI 无需特殊语法：只要目标与目的清晰，纯自然语言指令即可良好工作。 -### 3. Monitor execution and review output +### 3. 监控执行并审阅输出 -After submitting the flow, PentAGI opens the flow page automatically. +提交 flow 后，PentAGI 会自动打开 flow 页面。 -- Use the main flow view to follow messages, agent activity, and task progress -- Inspect tool activity and terminal output as the flow runs -- Review generated tasks and subtasks to understand what PentAGI is doing +- 使用主 flow 视图跟踪消息、代理活动与任务进度 +- 在 flow 运行期间检查工具活动与终端输出 +- 审阅生成的任务与子任务，以了解 PentAGI 正在做什么 -Once the flow has enough results, use the **Report** menu on the flow page to: +当 flow 已有足够结果时，使用 flow 页面上的 **Report** 菜单可： -- open the report in a web view -- copy the generated report to the clipboard -- download the report as Markdown -- download the report as PDF +- 在 Web 视图中打开报告 +- 将生成的报告复制到剪贴板 +- 将报告下载为 Markdown +- 将报告下载为 PDF -### 4. Use the Assistant view to steer an active flow +### 4. 使用 Assistant 视图引导活跃的 flow -Each flow also includes an **Assistant** view for interactive guidance. This is useful when the autonomous run uncovers something that needs human direction instead of a hard restart. +每个 flow 还包含用于交互式引导的 **Assistant** 视图。当自主运行发现需要人工指引而非硬性重启的情况时，这很有用。 -- Open the **Assistant** view for the same flow when you want to inspect the current state before changing anything. -- Use the assistant to check flow status, stop the current task, submit follow-up instructions, or patch the remaining planned subtasks before the next step runs. -- Treat this as an explicit control path for the current flow, not as an invisible background queue. If you want to change direction, say so clearly and keep the new instruction tied to the current engagement scope. -- This works best for clarifying scope, redirecting priorities after intermediate findings, or answering an automation checkpoint without losing the rest of the flow context. +- 在更改任何内容之前，若你想检查当前状态，请为同一 flow 打开 **Assistant** 视图。 +- 使用助手检查 flow 状态、停止当前任务、提交后续指令，或在下一步运行前修补剩余计划子任务。 +- 将其视为当前 flow 的显式控制路径，而非不可见的后台队列。若要改变方向，请明确说明，并使新指令与当前交战范围保持一致。 +- 这最适合澄清范围、在中间发现后重定向优先级，或在不丢失其余 flow 上下文的情况下响应自动化检查点。 -### 5. Manage flow-scoped files +### 5. 管理 flow 范围内的文件 -Each flow has its own **Files** tab in the flow page. Files are scoped to the parent flow: they live in `{dataDir}/flow-{id}-data/` on the host and never leak into other flows. +每个 flow 在 flow 页面都有各自的 **Files** 标签页。文件限定于父 flow：它们位于主机上的 `{dataDir}/flow-{id}-data/`，且绝不会泄漏到其他 flow。 -The tab exposes three sources of files: +该标签页展示三类文件来源： -- **Uploads** (`uploads/`): files you provide from the web UI. Use the **Upload files** action, or drag and drop directly onto the Files tab. While the agent container is running, uploaded files are also pushed into it at `/work/uploads/` so the agent can read them with normal shell tools. -- **Resources** (`resources/`): files attached from your saved user resources library via **Attach resources from library**. Attached resources are copied into the flow and pushed into the running container at `/work/resources/`. -- **Container** (`container/`): snapshots pulled from the running agent container via **Pull file or directory from container**. These are read-only on the flow side and are never sent back to the container. +- **Uploads**（`uploads/`）：你从 Web UI 提供的文件。使用 **Upload files** 操作，或直接拖放到 Files 标签页。代理容器运行时，上传的文件也会推送到其中的 `/work/uploads/`，以便代理用常规 shell 工具读取。 +- **Resources**（`resources/`）：通过 **Attach resources from library** 从你已保存的用户资源库附加的文件。附加的资源会复制到 flow，并推送到运行中容器的 `/work/resources/`。 +- **Container**（`container/`）：通过 **Pull file or directory from container** 从运行中的代理容器拉取的快照。它们在 flow 侧为只读，且绝不会发回容器。 -Per-file actions in the Files tab include **Download**, **Copy path**, **Save as resource** (promote a flow file into your reusable resources library), and **Delete**. The Pull action is disabled when the container is not running, with the tooltip "Container is not running". +Files 标签页中每个文件的操作包括 **Download**、**Copy path**、**Save as resource**（将 flow 文件提升到你可复用的资源库），以及 **Delete**。容器未运行时 Pull 操作会被禁用，工具提示为「Container is not running」。 -Uploaded files and attached resources are listed automatically in the agent's system prompts via the `{{.UserFiles}}` template variable, which renders a compact `` XML block (with nested `` and `` sections), so the assistant and automation agents can reference them by path without you pasting the contents into chat. Container snapshots are visible in the UI only and are not auto-injected back into the prompt. +上传的文件与附加资源会通过 `{{.UserFiles}}` 模板变量自动列在代理的系统提示中，该变量会渲染紧凑的 `` XML 块（含嵌套的 `` 与 `` 节），以便助手与自动化代理按路径引用它们，而无需你将内容粘贴到聊天中。容器快照仅在 UI 中可见，不会自动注入回提示。 -Current limits and limitations to be aware of: +需注意的当前限制： -- Maximum upload file size is 300 MB; per upload request up to 1000 files and 2 GB total. File names are capped at 255 bytes (roughly 255 ASCII characters; non-ASCII names use multiple bytes per character). -- Uploads and resources are mirrored into the running container at the fixed paths `/work/uploads/` and `/work/resources/`; files written to other container paths are not auto-mirrored back into the flow file model. Container snapshots can originate from any container path you pull (for example `/etc/...`) and are cached on the flow side under `container/`; they are not pushed back into the container. -- Container snapshots are point-in-time pulls. Editing a snapshot in the UI does not write back into the running container. -- Deleting a flow today removes the flow record and its long-term memory entries, but does not yet archive or remove the flow's `flow-{id}-data/` directory on disk. Operators are still expected to clean up the data directory manually if they want to reclaim the space. +- 单文件最大上传大小为 300 MB；单次上传请求最多 1000 个文件、总计 2 GB。文件名上限为 255 字节（约 255 个 ASCII 字符；非 ASCII 名称每个字符占用多个字节）。 +- 上传与资源会镜像到运行中容器的固定路径 `/work/uploads/` 与 `/work/resources/`；写入其他容器路径的文件不会自动镜像回 flow 文件模型。容器快照可来自你拉取的任意容器路径（例如 `/etc/...`），并在 flow 侧缓存于 `container/` 下；它们不会推回容器。 +- 容器快照为时间点拉取。在 UI 中编辑快照不会写回运行中的容器。 +- 目前删除 flow 会移除 flow 记录及其长期记忆条目，但尚未归档或删除磁盘上该 flow 的 `flow-{id}-data/` 目录。若运维人员希望回收空间，仍需手动清理数据目录。 -For early testing, start with a narrow target and a single clear objective. This makes the output easier to review and helps you refine your prompts before running larger assessments. +早期测试时，请从狭窄目标与单一清晰目的入手。这样输出更易审阅，也有助于在运行更大规模评估前优化提示。 -## API Access +## API 访问 -PentAGI provides comprehensive programmatic access through both REST and GraphQL APIs, allowing you to integrate penetration testing workflows into your automation pipelines, CI/CD processes, and custom applications. +PentAGI 通过 REST 与 GraphQL API 提供全面的程序化访问，使你能够将渗透测试工作流集成到自动化流水线、CI/CD 流程与自定义应用中。 -### Generating API Tokens +### 生成 API 令牌 -API tokens are managed through the PentAGI web interface: +API 令牌通过 PentAGI Web 界面管理： -1. Navigate to **Settings** → **API Tokens** in the web UI -2. Click **Create Token** to generate a new API token -3. Configure token properties: - - **Name** (optional): A descriptive name for the token - - **Expiration Date**: When the token will expire (minimum 1 minute, maximum 3 years) -4. Click **Create** and **copy the token immediately** - it will only be shown once for security reasons -5. Use the token as a Bearer token in your API requests +1. 在 Web UI 中导航至 **Settings** → **API Tokens** +2. 点击 **Create Token** 生成新的 API 令牌 +3. 配置令牌属性： + - **Name**（可选）：令牌的描述性名称 + - **Expiration Date**：令牌过期时间（最短 1 分钟，最长 3 年） +4. 点击 **Create** 并**立即复制令牌**——出于安全考虑，令牌仅显示一次 +5. 在 API 请求中将该令牌用作 Bearer 令牌 -Each token is associated with your user account and inherits your role's permissions. +每个令牌均与您的用户账户关联，并继承您角色所拥有的权限。 -### Using API Tokens +### 使用 API 令牌 -Include the API token in the `Authorization` header of your HTTP requests: +在 HTTP 请求的 `Authorization` 请求头中包含 API 令牌： ```bash # GraphQL API example @@ -1094,55 +1100,55 @@ curl https://your-pentagi-instance:8443/api/v1/flows \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` -### API Exploration and Testing +### API 探索与测试 -PentAGI provides interactive documentation for exploring and testing API endpoints: +PentAGI 提供交互式文档，用于探索和测试 API 端点： #### GraphQL Playground -Access the GraphQL Playground at `https://your-pentagi-instance:8443/api/v1/graphql/playground` +在 `https://your-pentagi-instance:8443/api/v1/graphql/playground` 访问 GraphQL Playground -1. Click the **HTTP Headers** tab at the bottom -2. Add your authorization header: +1. 点击底部的 **HTTP Headers** 标签页 +2. 添加您的授权请求头： ```json { "Authorization": "Bearer YOUR_API_TOKEN" } ``` -3. Explore the schema, run queries, and test mutations interactively +3. 交互式地探索 schema、运行查询并测试变更（mutation） #### Swagger UI -Access the REST API documentation at `https://your-pentagi-instance:8443/api/v1/swagger/index.html` +在 `https://your-pentagi-instance:8443/api/v1/swagger/index.html` 访问 REST API 文档 -1. Click the **Authorize** button -2. Enter your token in the format: `Bearer YOUR_API_TOKEN` -3. Click **Authorize** to apply -4. Test endpoints directly from the Swagger UI +1. 点击 **Authorize** 按钮 +2. 按以下格式输入您的令牌：`Bearer YOUR_API_TOKEN` +3. 点击 **Authorize** 以应用 +4. 直接在 Swagger UI 中测试端点 -### Generating API Clients +### 生成 API 客户端 -You can generate type-safe API clients for your preferred programming language using the schema files included with PentAGI: +您可以使用 PentAGI 附带的 schema 文件，为偏好的编程语言生成类型安全的 API 客户端： -#### GraphQL Clients +#### GraphQL 客户端 -The GraphQL schema is available at: -- **Web UI**: Navigate to Settings to download `schema.graphqls` -- **Direct file**: `backend/pkg/graph/schema.graphqls` in the repository +GraphQL schema 可通过以下方式获取： +- **Web UI**：前往 Settings 下载 `schema.graphqls` +- **直接文件**：仓库中的 `backend/pkg/graph/schema.graphqls` -Generate clients using tools like: -- **GraphQL Code Generator** (JavaScript/TypeScript): [https://the-guild.dev/graphql/codegen](https://the-guild.dev/graphql/codegen) -- **genqlient** (Go): [https://github.com/Khan/genqlient](https://github.com/Khan/genqlient) -- **Apollo iOS** (Swift): [https://www.apollographql.com/docs/ios](https://www.apollographql.com/docs/ios) +可使用以下工具生成客户端： +- **GraphQL Code Generator**（JavaScript/TypeScript）：[https://the-guild.dev/graphql/codegen](https://the-guild.dev/graphql/codegen) +- **genqlient**（Go）：[https://github.com/Khan/genqlient](https://github.com/Khan/genqlient) +- **Apollo iOS**（Swift）：[https://www.apollographql.com/docs/ios](https://www.apollographql.com/docs/ios) -#### REST API Clients +#### REST API 客户端 -The OpenAPI specification is available at: -- **Swagger JSON**: `https://your-pentagi-instance:8443/api/v1/swagger/doc.json` -- **Swagger YAML**: Available in `backend/pkg/server/docs/swagger.yaml` +OpenAPI 规范可通过以下方式获取： +- **Swagger JSON**：`https://your-pentagi-instance:8443/api/v1/swagger/doc.json` +- **Swagger YAML**：可在 `backend/pkg/server/docs/swagger.yaml` 中获取 -Generate clients using: -- **OpenAPI Generator**: [https://openapi-generator.tech](https://openapi-generator.tech) +可使用以下工具生成客户端： +- **OpenAPI Generator**：[https://openapi-generator.tech](https://openapi-generator.tech) ```bash openapi-generator-cli generate \ -i https://your-pentagi-instance:8443/api/v1/swagger/doc.json \ @@ -1150,7 +1156,7 @@ Generate clients using: -o ./pentagi-client ``` -- **Swagger Codegen**: [https://github.com/swagger-api/swagger-codegen](https://github.com/swagger-api/swagger-codegen) +- **Swagger Codegen**：[https://github.com/swagger-api/swagger-codegen](https://github.com/swagger-api/swagger-codegen) ```bash swagger-codegen generate \ -i https://your-pentagi-instance:8443/api/v1/swagger/doc.json \ @@ -1158,7 +1164,7 @@ Generate clients using: -o ./pentagi-client ``` -- **swagger-typescript-api** (TypeScript): [https://github.com/acacode/swagger-typescript-api](https://github.com/acacode/swagger-typescript-api) +- **swagger-typescript-api**（TypeScript）：[https://github.com/acacode/swagger-typescript-api](https://github.com/acacode/swagger-typescript-api) ```bash npx swagger-typescript-api \ -p https://your-pentagi-instance:8443/api/v1/swagger/doc.json \ @@ -1166,10 +1172,10 @@ Generate clients using: -n pentagi-api.ts ``` -### API Usage Examples +### API 使用示例
-Creating a New Flow (GraphQL) +创建新 Flow（GraphQL） ```graphql mutation CreateFlow { @@ -1188,7 +1194,7 @@ mutation CreateFlow {
-Listing Flows (REST API) +列出 Flow（REST API） ```bash curl https://your-pentagi-instance:8443/api/v1/flows \ @@ -1199,7 +1205,7 @@ curl https://your-pentagi-instance:8443/api/v1/flows \
-Python Client Example +Python 客户端示例 ```python import requests @@ -1260,7 +1266,7 @@ print(f"Total flows: {len(flows['flows'])}")
-TypeScript Client Example +TypeScript 客户端示例 ```typescript import axios, { AxiosInstance } from 'axios'; @@ -1336,83 +1342,83 @@ console.log(`Total flows: ${flows.length}`);
-### Security Best Practices +### 安全最佳实践 -When working with API tokens: +使用 API 令牌时： -- **Never commit tokens to version control** - use environment variables or secrets management -- **Rotate tokens regularly** - set appropriate expiration dates and create new tokens periodically -- **Use separate tokens for different applications** - makes it easier to revoke access if needed -- **Monitor token usage** - review API token activity in the Settings page -- **Revoke unused tokens** - disable or delete tokens that are no longer needed -- **Use HTTPS only** - never send API tokens over unencrypted connections +- **切勿将令牌提交到版本控制** — 请使用环境变量或密钥管理服务 +- **定期轮换令牌** — 设置合适的过期时间，并定期创建新令牌 +- **为不同应用使用独立令牌** — 便于在需要时撤销访问权限 +- **监控令牌使用情况** — 在 Settings 页面查看 API 令牌活动 +- **撤销未使用的令牌** — 禁用或删除不再需要的令牌 +- **仅使用 HTTPS** — 切勿通过未加密的连接发送 API 令牌 -### Token Management +### 令牌管理 -- **View tokens**: See all your active tokens in Settings → API Tokens -- **Edit tokens**: Update token names or revoke tokens -- **Delete tokens**: Permanently remove tokens (this action cannot be undone) -- **Token ID**: Each token has a unique ID that can be copied for reference +- **查看令牌**：在 Settings → API Tokens 中查看所有活跃令牌 +- **编辑令牌**：更新令牌名称或撤销令牌 +- **删除令牌**：永久删除令牌（此操作无法撤销） +- **令牌 ID**：每个令牌都有唯一的 ID，可复制以供参考 -The token list shows: -- Token name (if provided) -- Token ID (unique identifier) -- Status (active/revoked/expired) -- Creation date -- Expiration date +令牌列表显示： +- 令牌名称（如已提供） +- 令牌 ID（唯一标识符） +- 状态（active/revoked/expired） +- 创建日期 +- 过期日期 -### Custom LLM Provider Configuration +### 自定义 LLM 提供商配置 -When using custom LLM providers with the `LLM_SERVER_*` variables, you can fine-tune the reasoning format used in requests. +将自定义 LLM 提供商与 `LLM_SERVER_*` 变量配合使用时，您可以微调请求中使用的推理格式。 > [!TIP] -> For production-grade local deployments, consider using **vLLM** with **Qwen3.5-27B-FP8** for optimal performance. See our [comprehensive deployment guide](examples/guides/vllm-qwen35-27b-fp8.md) which includes hardware requirements, configuration templates ([thinking mode](examples/configs/vllm-qwen3.5-27b-fp8.provider.yml) and [non-thinking mode](examples/configs/vllm-qwen3.5-27b-fp8-no-think.provider.yml)), and performance benchmarks showing 13K TPS prompt processing on 4× RTX 5090 GPUs. +> 对于生产级本地部署，建议使用 **vLLM** 配合 **Qwen3.5-27B-FP8** 以获得最佳性能。请参阅我们的[完整部署指南](examples/guides/vllm-qwen35-27b-fp8.md)，其中包含硬件要求、配置模板（[thinking mode](examples/configs/vllm-qwen3.5-27b-fp8.provider.yml) 与 [non-thinking mode](examples/configs/vllm-qwen3.5-27b-fp8-no-think.provider.yml)），以及在 4× RTX 5090 GPU 上实现 13K TPS 提示词处理吞吐量的性能基准测试。 | Variable | Default | Description | | ------------------------------- | ------- | --------------------------------------------------------------------------------------- | -| `LLM_SERVER_URL` | | Base URL for the custom LLM API endpoint | -| `LLM_SERVER_KEY` | | API key for the custom LLM provider | -| `LLM_SERVER_MODEL` | | Default model to use (can be overridden in provider config) | -| `LLM_SERVER_CONFIG_PATH` | | Path to the YAML configuration file for agent-specific models | -| `LLM_SERVER_PROVIDER` | | Provider name prefix for model names (e.g., `openrouter`, `deepseek` for LiteLLM proxy) | -| `LLM_SERVER_LEGACY_REASONING` | `false` | Controls reasoning format in API requests | -| `LLM_SERVER_PRESERVE_REASONING` | `false` | Preserve reasoning content in multi-turn conversations (required by some providers) | +| `LLM_SERVER_URL` | | 自定义 LLM API 端点的 Base URL | +| `LLM_SERVER_KEY` | | 自定义 LLM 提供商的 API 密钥 | +| `LLM_SERVER_MODEL` | | 默认使用的模型（可在提供商配置中覆盖） | +| `LLM_SERVER_CONFIG_PATH` | | Agent 专用模型的 YAML 配置文件路径 | +| `LLM_SERVER_PROVIDER` | | 模型名称的提供商名前缀（例如，LiteLLM proxy 使用 `openrouter`、`deepseek`） | +| `LLM_SERVER_LEGACY_REASONING` | `false` | 控制 API 请求中的推理（reasoning）格式 | +| `LLM_SERVER_PRESERVE_REASONING` | `false` | 在多轮对话中保留推理内容（部分提供商要求） | -The `LLM_SERVER_PROVIDER` setting is particularly useful when using **LiteLLM proxy**, which adds a provider prefix to model names. For example, when connecting to Moonshot API through LiteLLM, models like `kimi-2.5` become `moonshot/kimi-2.5`. By setting `LLM_SERVER_PROVIDER=moonshot`, you can use the same provider configuration file for both direct API access and LiteLLM proxy access without modifications. +`LLM_SERVER_PROVIDER` 设置在使用 **LiteLLM proxy** 时特别有用，该代理会为模型名称添加提供商前缀。例如，通过 LiteLLM 连接 Moonshot API 时，像 `kimi-2.5` 这样的模型会变成 `moonshot/kimi-2.5`。通过设置 `LLM_SERVER_PROVIDER=moonshot`，你可以使用同一份提供商配置文件，无需修改即可同时支持直接 API 访问和 LiteLLM proxy 访问。 -The `LLM_SERVER_LEGACY_REASONING` setting affects how reasoning parameters are sent to the LLM: -- `false` (default): Uses modern format where reasoning is sent as a structured object with `max_tokens` parameter -- `true`: Uses legacy format with string-based `reasoning_effort` parameter +`LLM_SERVER_LEGACY_REASONING` 设置影响推理参数如何发送至 LLM： +- `false`（默认）：使用现代格式，推理以结构化对象发送，并带有 `max_tokens` 参数 +- `true`：使用旧版格式，采用基于字符串的 `reasoning_effort` 参数 -This setting is important when working with different LLM providers as they may expect different reasoning formats in their API requests. If you encounter reasoning-related errors with custom providers, try changing this setting. +在使用不同 LLM 提供商时，此设置很重要，因为各提供商可能在 API 请求中期望不同的推理格式。若在使用自定义提供商时遇到与推理相关的错误，请尝试更改此设置。 -The `LLM_SERVER_PRESERVE_REASONING` setting controls whether reasoning content is preserved in multi-turn conversations: -- `false` (default): Reasoning content is not preserved in conversation history -- `true`: Reasoning content is preserved and sent in subsequent API calls +`LLM_SERVER_PRESERVE_REASONING` 设置控制是否在多轮对话中保留推理内容： +- `false`（默认）：对话历史中不保留推理内容 +- `true`：保留推理内容并在后续 API 调用中发送 -This setting is required by some LLM providers (e.g., Moonshot) that return errors like "thinking is enabled but reasoning_content is missing in assistant tool call message" when reasoning content is not included in multi-turn conversations. Enable this setting if your provider requires reasoning content to be preserved. +部分 LLM 提供商（例如 Moonshot）要求此设置；若多轮对话中未包含推理内容，可能返回类似 "thinking is enabled but reasoning_content is missing in assistant tool call message" 的错误。若你的提供商要求保留推理内容，请启用此设置。 -### Ollama Provider Configuration +### Ollama 提供商配置 -PentAGI supports Ollama for both local LLM inference (zero-cost, enhanced privacy) and Ollama Cloud (managed service with free tier). +PentAGI 支持 Ollama，可用于本地 LLM 推理（零成本、增强隐私）以及 Ollama Cloud（带免费额度的托管服务）。 -#### Configuration Variables +#### 配置变量 | Variable | Default | Description | | ----------------------------------- | ----------- | ----------------------------------------- | -| `OLLAMA_SERVER_URL` | | URL of your Ollama server or Ollama Cloud | -| `OLLAMA_SERVER_API_KEY` | | API key for Ollama Cloud authentication | -| `OLLAMA_SERVER_MODEL` | | Default model for inference | -| `OLLAMA_SERVER_CONFIG_PATH` | | Path to custom agent configuration file | -| `OLLAMA_SERVER_PULL_MODELS_TIMEOUT` | `600` | Timeout for model downloads (seconds) | -| `OLLAMA_SERVER_PULL_MODELS_ENABLED` | `false` | Auto-download models on startup | -| `OLLAMA_SERVER_LOAD_MODELS_ENABLED` | `false` | Query server for available models | +| `OLLAMA_SERVER_URL` | | Ollama 服务器或 Ollama Cloud 的 URL | +| `OLLAMA_SERVER_API_KEY` | | Ollama Cloud 身份验证的 API 密钥 | +| `OLLAMA_SERVER_MODEL` | | 推理默认模型 | +| `OLLAMA_SERVER_CONFIG_PATH` | | 自定义 Agent 配置文件路径 | +| `OLLAMA_SERVER_PULL_MODELS_TIMEOUT` | `600` | 模型下载超时时间（秒） | +| `OLLAMA_SERVER_PULL_MODELS_ENABLED` | `false` | 启动时自动下载模型 | +| `OLLAMA_SERVER_LOAD_MODELS_ENABLED` | `false` | 向服务器查询可用模型 | -#### Ollama Cloud Configuration +#### Ollama Cloud 配置 -Ollama Cloud provides managed inference with a generous free tier and scalable paid plans. +Ollama Cloud 提供托管推理服务，拥有慷慨的免费额度以及可扩展的付费方案。 -**Free Tier Setup (Single Model)** +**免费层级设置（单模型）** ```bash # Free tier allows one model at a time @@ -1421,9 +1427,9 @@ OLLAMA_SERVER_API_KEY=your_ollama_cloud_api_key OLLAMA_SERVER_MODEL=gpt-oss:120b # Example: OpenAI OSS 120B model ``` -**Paid Tier Setup (Multi-Model with Pre-built Configuration)** +**付费层级设置（多模型与预构建配置）** -For paid tiers supporting multiple concurrent models, use the pre-built Ollama Cloud configuration: +对于支持多个并发模型的付费层级，请使用预构建的 Ollama Cloud 配置： ```bash # Using pre-built Ollama Cloud configuration (included in Docker image) @@ -1432,18 +1438,18 @@ OLLAMA_SERVER_API_KEY=your_ollama_cloud_api_key OLLAMA_SERVER_CONFIG_PATH=/opt/pentagi/conf/ollama-cloud.provider.yml ``` -The pre-built `ollama-cloud.provider.yml` configuration includes optimized model assignments for all agent types: -- **Simple/Assistant**: `nemotron-3-super:cloud` - Fast general-purpose model -- **Primary Agent**: `qwen3-coder-next:cloud` - Advanced reasoning with high effort mode -- **Coder/Pentester**: `qwen3-coder-next:cloud` - Specialized coding models -- **Searcher**: `qwen3.5:397b-cloud` - Large context for information gathering -- **Refiner/Refactor**: `glm-5:cloud` - High-quality text refinement -- **Adviser/Enricher**: `minimax-m2.7:cloud` - Efficient advisory tasks -- **Installer**: `devstral-2:123b-cloud` - Installation and setup tasks +预构建的 `ollama-cloud.provider.yml` 配置包含针对所有 Agent 类型的优化模型分配： +- **Simple/Assistant**：`nemotron-3-super:cloud` - 快速通用模型 +- **Primary Agent**：`qwen3-coder-next:cloud` - 高努力模式的高级推理 +- **Coder/Pentester**：`qwen3-coder-next:cloud` - 专用编码模型 +- **Searcher**：`qwen3.5:397b-cloud` - 大上下文信息收集 +- **Refiner/Refactor**：`glm-5:cloud` - 高质量文本精炼 +- **Adviser/Enricher**：`minimax-m2.7:cloud` - 高效咨询任务 +- **Installer**：`devstral-2:123b-cloud` - 安装与设置任务 -**Custom Configuration (Advanced)** +**自定义配置（高级）** -To create your own agent configuration, mount a custom file from your host filesystem: +要创建你自己的 Agent 配置，请从宿主机文件系统挂载自定义文件： ```bash # Using custom provider configuration @@ -1455,9 +1461,9 @@ OLLAMA_SERVER_CONFIG_PATH=/opt/pentagi/conf/ollama.provider.yml PENTAGI_OLLAMA_SERVER_CONFIG_PATH=/path/on/host/my-ollama-config.yml ``` -The `PENTAGI_OLLAMA_SERVER_CONFIG_PATH` environment variable maps your host configuration file to `/opt/pentagi/conf/ollama.provider.yml` inside the container. +`PENTAGI_OLLAMA_SERVER_CONFIG_PATH` 环境变量将你的宿主机配置文件映射到容器内的 `/opt/pentagi/conf/ollama.provider.yml`。 -**Example custom configuration** (`my-ollama-config.yml`): +**自定义配置示例**（`my-ollama-config.yml`）： ```yaml primary_agent: @@ -1474,9 +1480,9 @@ coder: max_tokens: 20480 ``` -#### Local Ollama Configuration +#### 本地 Ollama 配置 -For self-hosted Ollama instances: +对于自托管的 Ollama 实例： ```bash # Basic local Ollama setup @@ -1497,22 +1503,22 @@ OLLAMA_SERVER_CONFIG_PATH=/opt/pentagi/conf/ollama-qwen332b-fp16-tc.provider.yml OLLAMA_SERVER_CONFIG_PATH=/opt/pentagi/conf/ollama-qwq32b-fp16-tc.provider.yml ``` -**Performance Considerations:** +**性能注意事项：** -- **Model Discovery** (`OLLAMA_SERVER_LOAD_MODELS_ENABLED=true`): Adds 1-2s startup latency querying Ollama API -- **Auto-pull** (`OLLAMA_SERVER_PULL_MODELS_ENABLED=true`): First startup may take several minutes downloading models -- **Pull timeout** (`OLLAMA_SERVER_PULL_MODELS_TIMEOUT=900`): 15 minutes in seconds -- **Static Config**: Disable both flags and specify models in config file for fastest startup +- **模型发现**（`OLLAMA_SERVER_LOAD_MODELS_ENABLED=true`）：查询 Ollama API 会增加 1-2 秒启动延迟 +- **自动拉取**（`OLLAMA_SERVER_PULL_MODELS_ENABLED=true`）：首次启动可能需要数分钟下载模型 +- **拉取超时**（`OLLAMA_SERVER_PULL_MODELS_TIMEOUT=900`）：15 分钟（以秒为单位） +- **静态配置**：禁用上述两个标志并在配置文件中指定模型，可获得最快启动速度 -#### Creating Custom Ollama Models with Extended Context +#### 使用扩展上下文创建自定义 Ollama 模型 -PentAGI requires models with larger context windows than the default Ollama configurations. You need to create custom models with increased `num_ctx` parameter through Modelfiles. While typical agent workflows consume around 64K tokens, PentAGI uses 110K context size for safety margin and handling complex penetration testing scenarios. +PentAGI 需要比默认 Ollama 配置更大的上下文窗口。你需要通过 Modelfile 创建带有更大 `num_ctx` 参数的自定义模型。虽然典型 Agent 工作流大约消耗 64K token，但 PentAGI 使用 110K 上下文大小，以留出安全余量并处理复杂的渗透测试场景。 -**Important**: The `num_ctx` parameter can only be set during model creation via Modelfile - it cannot be changed after model creation or overridden at runtime. +**重要**：`num_ctx` 参数只能在通过 Modelfile 创建模型时设置——模型创建后无法更改，也无法在运行时覆盖。 -##### Example: Qwen3 32B FP16 with Extended Context +##### 示例：带扩展上下文的 Qwen3 32B FP16 -Create a Modelfile named `Modelfile_qwen3_32b_fp16_tc`: +创建一个名为 `Modelfile_qwen3_32b_fp16_tc` 的 Modelfile： ```dockerfile FROM qwen3:32b-fp16 @@ -1524,15 +1530,15 @@ PARAMETER top_k 20 PARAMETER repeat_penalty 1.1 ``` -Build the custom model: +构建自定义模型： ```bash ollama create qwen3:32b-fp16-tc -f Modelfile_qwen3_32b_fp16_tc ``` -##### Example: QwQ 32B FP16 with Extended Context +##### 示例：QwQ 32B FP16 扩展上下文 -Create a Modelfile named `Modelfile_qwq_32b_fp16_tc`: +创建一个名为 `Modelfile_qwq_32b_fp16_tc` 的 Modelfile： ```dockerfile FROM qwq:32b-fp16 @@ -1544,28 +1550,28 @@ PARAMETER top_k 40 PARAMETER repeat_penalty 1.2 ``` -Build the custom model: +构建自定义模型： ```bash ollama create qwq:32b-fp16-tc -f Modelfile_qwq_32b_fp16_tc ``` -> **Note**: The QwQ 32B FP16 model requires approximately **71.3 GB VRAM** for inference. Ensure your system has sufficient GPU memory before attempting to use this model. +> **注意**：QwQ 32B FP16 模型推理大约需要 **71.3 GB VRAM**。在尝试使用该模型之前，请确保系统拥有足够的 GPU 显存。 -These custom models are referenced in the pre-built provider configuration files (`ollama-qwen332b-fp16-tc.provider.yml` and `ollama-qwq32b-fp16-tc.provider.yml`) that are included in the Docker image at `/opt/pentagi/conf/`. +这些自定义模型会在 Docker 镜像中 `/opt/pentagi/conf/` 路径下附带的预构建提供商配置文件（`ollama-qwen332b-fp16-tc.provider.yml` 和 `ollama-qwq32b-fp16-tc.provider.yml`）中被引用。 -### OpenAI Provider Configuration +### OpenAI 提供商配置 -PentAGI integrates with OpenAI's comprehensive model lineup, featuring advanced reasoning capabilities with extended chain-of-thought, agentic models with enhanced tool integration, and specialized code models for security engineering. +PentAGI 与 OpenAI 全面的模型阵容集成，具备扩展思维链（chain-of-thought）的高级推理能力、增强工具集成的智能体（agentic）模型，以及面向安全工程的专业代码模型。 -#### Configuration Variables +#### 配置变量 -| Variable | Default | Description | +| 变量 | 默认值 | 说明 | | -------------------- | --------------------------- | --------------------------- | -| `OPEN_AI_KEY` | | API key for OpenAI services | -| `OPEN_AI_SERVER_URL` | `https://api.openai.com/v1` | OpenAI API endpoint | +| `OPEN_AI_KEY` | | OpenAI 服务的 API 密钥 | +| `OPEN_AI_SERVER_URL` | `https://api.openai.com/v1` | OpenAI API 端点 | -#### Configuration Examples +#### 配置示例 ```bash # Basic OpenAI setup @@ -1577,108 +1583,108 @@ OPEN_AI_KEY=your_openai_api_key PROXY_URL=http://your-proxy:8080 ``` -#### Supported Models +#### 支持的模型 -PentAGI supports 31 OpenAI models with tool calling, streaming, reasoning modes, and prompt caching. Models marked with `*` are used in default configuration. +PentAGI 支持 31 个具备工具调用、流式输出、推理模式和提示缓存（prompt caching）的 OpenAI 模型。标记为 `*` 的模型用于默认配置。 -**GPT-5.2 Series - Latest Flagship Agentic (December 2025)** +**GPT-5.2 系列 - 最新旗舰智能体模型（2025 年 12 月）** -| Model ID | Thinking | Price (Input/Output/Cache) | Use Case | +| 模型 ID | 思考模式 | 价格（输入/输出/缓存） | 使用场景 | | --------------------- | -------- | -------------------------- | ----------------------------------------------- | -| `gpt-5.2`* | ✅ | $1.75/$14.00/$0.18 | Latest flagship with enhanced reasoning and tool integration, autonomous security research | -| `gpt-5.2-pro` | ✅ | $21.00/$168.00/$0.00 | Premium version with superior agentic coding, mission-critical security research, zero-day discovery | -| `gpt-5.2-codex` | ✅ | $1.75/$14.00/$0.18 | Most advanced code-specialized, context compaction, strong cybersecurity capabilities | +| `gpt-5.2`* | ✅ | $1.75/$14.00/$0.18 | 最新旗舰模型，具备增强推理与工具集成，适用于自主安全研究 | +| `gpt-5.2-pro` | ✅ | $21.00/$168.00/$0.00 | 高级版本，具备卓越智能体编码能力，适用于关键任务安全研究与零日漏洞发现 | +| `gpt-5.2-codex` | ✅ | $1.75/$14.00/$0.18 | 最先进的代码专用模型，支持上下文压缩，具备强大网络安全能力 | -**GPT-5/5.1 Series - Advanced Agentic Models** +**GPT-5/5.1 系列 - 高级智能体模型** -| Model ID | Thinking | Price (Input/Output/Cache) | Use Case | +| 模型 ID | 思考模式 | 价格（输入/输出/缓存） | 使用场景 | | --------------------- | -------- | -------------------------- | ----------------------------------------------- | -| `gpt-5` | ✅ | $1.25/$10.00/$0.13 | Premier agentic with advanced reasoning, autonomous security research, exploit chain development | -| `gpt-5.1` | ✅ | $1.25/$10.00/$0.13 | Enhanced agentic with adaptive reasoning, balanced penetration testing with strong tool coordination | -| `gpt-5-pro` | ✅ | $15.00/$120.00/$0.00 | Premium version with major reasoning improvements, reduced hallucinations, critical security operations | -| `gpt-5-mini` | ✅ | $0.25/$2.00/$0.03 | Efficient balancing speed and intelligence, automated vulnerability analysis, exploit generation | -| `gpt-5-nano` | ✅ | $0.05/$0.40/$0.01 | Fastest for high-throughput scanning, reconnaissance, bulk vulnerability detection | +| `gpt-5` | ✅ | $1.25/$10.00/$0.13 | 顶级智能体模型，具备高级推理能力，适用于自主安全研究与漏洞利用链开发 | +| `gpt-5.1` | ✅ | $1.25/$10.00/$0.13 | 增强型智能体模型，具备自适应推理，适用于均衡渗透测试与强大工具协同 | +| `gpt-5-pro` | ✅ | $15.00/$120.00/$0.00 | 高级版本，具备重大推理改进与更少幻觉，适用于关键安全操作 | +| `gpt-5-mini` | ✅ | $0.25/$2.00/$0.03 | 在速度与智能之间高效平衡，适用于自动化漏洞分析与漏洞利用生成 | +| `gpt-5-nano` | ✅ | $0.05/$0.40/$0.01 | 最快的高吞吐量扫描模型，适用于侦察与批量漏洞检测 | -**GPT-5/5.1 Codex Series - Code-Specialized** +**GPT-5/5.1 Codex 系列 - 代码专用模型** -| Model ID | Thinking | Price (Input/Output/Cache) | Use Case | +| 模型 ID | 思考模式 | 价格（输入/输出/缓存） | 使用场景 | | --------------------- | -------- | -------------------------- | ----------------------------------------------- | -| `gpt-5.1-codex-max` | ✅ | $1.25/$10.00/$0.13 | Enhanced reasoning for sophisticated coding, proven CVE findings, systematic exploit development | -| `gpt-5.1-codex` | ✅ | $1.25/$10.00/$0.13 | Standard code-optimized with strong reasoning, exploit generation, vulnerability analysis | -| `gpt-5-codex` | ✅ | $1.25/$10.00/$0.13 | Foundational code-specialized, vulnerability scanning, basic exploit generation | -| `gpt-5.1-codex-mini` | ✅ | $0.25/$2.00/$0.03 | Compact high-performance, 4x higher capacity, rapid vulnerability detection | -| `codex-mini-latest` | ✅ | $1.50/$6.00/$0.38 | Latest compact code model, automated code review, basic vulnerability analysis | +| `gpt-5.1-codex-max` | ✅ | $1.25/$10.00/$0.13 | 面向复杂编码的增强推理，适用于已验证 CVE 发现与系统化漏洞利用开发 | +| `gpt-5.1-codex` | ✅ | $1.25/$10.00/$0.13 | 标准代码优化模型，具备强大推理能力，适用于漏洞利用生成与漏洞分析 | +| `gpt-5-codex` | ✅ | $1.25/$10.00/$0.13 | 基础代码专用模型，适用于漏洞扫描与基础漏洞利用生成 | +| `gpt-5.1-codex-mini` | ✅ | $0.25/$2.00/$0.03 | 紧凑高性能模型，容量提升 4 倍，适用于快速漏洞检测 | +| `codex-mini-latest` | ✅ | $1.50/$6.00/$0.38 | 最新紧凑代码模型，适用于自动化代码审查与基础漏洞分析 | -**GPT-4.1 Series - Enhanced Intelligence** +**GPT-4.1 系列 - 增强智能模型** -| Model ID | Thinking | Price (Input/Output/Cache) | Use Case | +| 模型 ID | 思考模式 | 价格（输入/输出/缓存） | 使用场景 | | --------------------- | -------- | -------------------------- | ----------------------------------------------- | -| `gpt-4.1` | ❌ | $2.00/$8.00/$0.50 | Enhanced flagship with superior function calling, complex threat analysis, sophisticated exploit development | -| `gpt-4.1-mini`* | ❌ | $0.40/$1.60/$0.10 | Balanced performance with improved efficiency, routine security assessments, automated code analysis | -| `gpt-4.1-nano` | ❌ | $0.10/$0.40/$0.03 | Ultra-fast lightweight, bulk security scanning, rapid reconnaissance, continuous monitoring | +| `gpt-4.1` | ❌ | $2.00/$8.00/$0.50 | 增强旗舰模型，具备卓越函数调用能力，适用于复杂威胁分析与高级漏洞利用开发 | +| `gpt-4.1-mini`* | ❌ | $0.40/$1.60/$0.10 | 性能均衡且效率更高，适用于常规安全评估与自动化代码分析 | +| `gpt-4.1-nano` | ❌ | $0.10/$0.40/$0.03 | 超快轻量模型，适用于批量安全扫描、快速侦察与持续监控 | -**GPT-4o Series - Multimodal Flagship** +**GPT-4o 系列 - 多模态旗舰模型** -| Model ID | Thinking | Price (Input/Output/Cache) | Use Case | +| 模型 ID | 思考模式 | 价格（输入/输出/缓存） | 使用场景 | | --------------------- | -------- | -------------------------- | ----------------------------------------------- | -| `gpt-4o` | ❌ | $2.50/$10.00/$1.25 | Multimodal flagship with vision, image analysis, web UI assessment, multi-tool orchestration | -| `gpt-4o-mini` | ❌ | $0.15/$0.60/$0.08 | Compact multimodal with strong function calling, high-frequency scanning, cost-effective bulk operations | +| `gpt-4o` | ❌ | $2.50/$10.00/$1.25 | 多模态旗舰模型，具备视觉能力，适用于图像分析、Web UI 评估与多工具编排 | +| `gpt-4o-mini` | ❌ | $0.15/$0.60/$0.08 | 紧凑多模态模型，具备强大函数调用能力，适用于高频扫描与高性价比批量操作 | -**o-Series - Advanced Reasoning Models** +**o 系列 - 高级推理模型** -| Model ID | Thinking | Price (Input/Output/Cache) | Use Case | +| 模型 ID | 思考模式 | 价格（输入/输出/缓存） | 使用场景 | | --------------------- | -------- | -------------------------- | ----------------------------------------------- | -| `o4-mini`* | ✅ | $1.10/$4.40/$0.28 | Next-gen reasoning with enhanced speed, methodical security assessments, systematic exploit development | -| `o3`* | ✅ | $2.00/$8.00/$0.50 | Advanced reasoning powerhouse, multi-stage attack chains, deep vulnerability analysis | -| `o3-mini` | ✅ | $1.10/$4.40/$0.55 | Compact reasoning with extended thinking, step-by-step attack planning, logical vulnerability chaining | -| `o1` | ✅ | $15.00/$60.00/$7.50 | Premier reasoning with maximum depth, advanced penetration testing, novel exploit research | -| `o3-pro` | ✅ | $20.00/$80.00/$0.00 | Most advanced reasoning, 80% cheaper than o1-pro, zero-day research, critical security investigations | -| `o1-pro` | ✅ | $150.00/$600.00/$0.00 | Previous-gen premium reasoning, exhaustive security analysis, mission-critical challenges | +| `o4-mini`* | ✅ | $1.10/$4.40/$0.28 | 下一代推理模型，速度更快，适用于系统化安全评估与系统化漏洞利用开发 | +| `o3`* | ✅ | $2.00/$8.00/$0.50 | 高级推理强力模型，适用于多阶段攻击链与深度漏洞分析 | +| `o3-mini` | ✅ | $1.10/$4.40/$0.55 | 紧凑推理模型，支持扩展思考，适用于分步攻击规划与逻辑化漏洞串联 | +| `o1` | ✅ | $15.00/$60.00/$7.50 | 顶级推理模型，具备最大深度，适用于高级渗透测试与新型漏洞利用研究 | +| `o3-pro` | ✅ | $20.00/$80.00/$0.00 | 最先进推理模型，比 o1-pro 便宜 80%，适用于零日研究与关键安全调查 | +| `o1-pro` | ✅ | $150.00/$600.00/$0.00 | 上一代高级推理模型，适用于详尽安全分析与关键任务挑战 | -**Prices**: Per 1M tokens. Reasoning models include thinking tokens in output pricing. +**价格**：按每 100 万 token 计费。推理模型的输出定价包含思考 token。 > [!WARNING] -> **GPT-5* Models - Trusted Access Required** +> **GPT-5* 模型 - 需要可信访问权限** > -> All GPT-5 series models (`gpt-5`, `gpt-5.1`, `gpt-5.2`, `gpt-5-pro`, `gpt-5.2-pro`, and all Codex variants) work **unstably with PentAGI** and may trigger OpenAI's cybersecurity safety mechanisms without verified access. +> 所有 GPT-5 系列模型（`gpt-5`、`gpt-5.1`、`gpt-5.2`、`gpt-5-pro`、`gpt-5.2-pro` 以及所有 Codex 变体）在 PentAGI 中运行**不稳定**，且在没有经过验证的访问权限时可能触发 OpenAI 的网络安全安全机制。 > -> **To use GPT-5* models reliably:** -> 1. **Individual users**: Verify your identity at [chatgpt.com/cyber](https://chatgpt.com/cyber) -> 2. **Enterprise teams**: Request trusted access through your OpenAI representative -> 3. **Security researchers**: Apply for the [Cybersecurity Grant Program](https://openai.com/form/cybersecurity-grant-program/) (includes $10M in API credits) +> **要可靠使用 GPT-5* 模型：** +> 1. **个人用户**：在 [chatgpt.com/cyber](https://chatgpt.com/cyber) 验证身份 +> 2. **企业团队**：通过 OpenAI 代表申请可信访问权限 +> 3. **安全研究人员**：申请 [网络安全资助计划（Cybersecurity Grant Program）](https://openai.com/form/cybersecurity-grant-program/)（包含 1000 万美元 API 额度） > -> **Recommended alternatives without verification:** -> - Use `o-series` models (o3, o4-mini, o1) for reasoning tasks -> - Use `gpt-4.1` series for general intelligence and function calling -> - All o-series and gpt-4.x models work reliably without special access +> **无需验证的推荐替代方案：** +> - 推理任务使用 `o-series` 模型（o3、o4-mini、o1） +> - 通用智能与函数调用使用 `gpt-4.1` 系列 +> - 所有 o 系列和 gpt-4.x 模型无需特殊访问权限即可稳定运行 -**Reasoning Effort Levels**: -- **High**: Maximum reasoning depth (refiner - o3 with high effort) -- **Medium**: Balanced reasoning (primary_agent, assistant, reflector - o4-mini/o3 with medium effort) -- **Low**: Efficient targeted reasoning (coder, installer, pentester - o3/o4-mini with low effort; adviser - gpt-5.2 with low effort) +**推理力度等级**： +- **High**：最大推理深度（refiner - o3，high effort） +- **Medium**：均衡推理（primary_agent、assistant、reflector - o4-mini/o3，medium effort） +- **Low**：高效定向推理（coder、installer、pentester - o3/o4-mini，low effort；adviser - gpt-5.2，low effort） -**Key Features**: -- **Extended Reasoning**: o-series models with chain-of-thought for complex security analysis -- **Agentic Intelligence**: GPT-5/5.1/5.2 series with enhanced tool integration and autonomous capabilities -- **Prompt Caching**: Cost reduction on repeated context (10-50% of input price) -- **Code Specialization**: Dedicated Codex models for vulnerability discovery and exploit development -- **Multimodal Support**: GPT-4o series for vision-based security assessments -- **Tool Calling**: Robust function calling across all models for pentesting tool orchestration -- **Streaming**: Real-time response streaming for interactive workflows -- **Proven Track Record**: Industry-leading models with CVE discoveries and real-world security applications +**核心特性**： +- **扩展推理（Extended Reasoning）**：o 系列模型配合思维链（chain-of-thought），用于复杂安全分析 +- **智能体能力（Agentic Intelligence）**：GPT-5/5.1/5.2 系列，增强工具集成与自主能力 +- **提示缓存（Prompt Caching）**：重复上下文可降低成本（约为输入价格的 10-50%） +- **代码专精**：专用 Codex 模型，用于漏洞发现与 exploit 开发 +- **多模态支持**：GPT-4o 系列，用于基于视觉的安全评估 +- **工具调用（Tool Calling）**：全系模型稳健函数调用，用于渗透测试工具编排 +- **流式输出（Streaming）**：实时响应流，用于交互式工作流 +- **成熟实绩**：行业领先模型，具备 CVE 发现与真实场景安全应用记录 -### Anthropic Provider Configuration +### Anthropic 提供商配置 -PentAGI integrates with Anthropic's Claude models, featuring advanced extended thinking capabilities, exceptional safety mechanisms, and sophisticated understanding of complex security contexts with prompt caching. +PentAGI 集成 Anthropic 的 Claude 模型，具备先进的扩展思考能力、卓越的安全机制，以及对复杂安全语境的深刻理解，并支持提示缓存。 -#### Configuration Variables +#### 配置变量 | Variable | Default | Description | | ---------------------- | ------------------------------ | ------------------------------ | -| `ANTHROPIC_API_KEY` | | API key for Anthropic services | -| `ANTHROPIC_SERVER_URL` | `https://api.anthropic.com/v1` | Anthropic API endpoint | +| `ANTHROPIC_API_KEY` | | Anthropic 服务 API 密钥 | +| `ANTHROPIC_SERVER_URL` | `https://api.anthropic.com/v1` | Anthropic API 端点 | -#### Configuration Examples +#### 配置示例 ```bash # Basic Anthropic setup @@ -1691,74 +1697,74 @@ PROXY_URL=http://your-proxy:8080 ``` > [!NOTE] -> **Google Vertex AI for Claude models** +> **适用于 Claude 模型的 Google Vertex AI** > -> PentAGI does not currently expose a dedicated Google Vertex AI configuration path for Anthropic Claude in `.env`. There is no separate Vertex AI API key field at this time, and the existing Anthropic variables (`ANTHROPIC_API_KEY`, `ANTHROPIC_SERVER_URL`) target the direct Anthropic API. Supported routes for Claude are: +> PentAGI 目前在 `.env` 中尚未提供面向 Anthropic Claude 的专用 Google Vertex AI 配置路径。目前尚无独立的 Vertex AI API 密钥字段，现有 Anthropic 变量（`ANTHROPIC_API_KEY`、`ANTHROPIC_SERVER_URL`）指向 Anthropic 直连 API。Claude 的支持路由包括： > -> - **Direct Anthropic API**: `ANTHROPIC_API_KEY` and `ANTHROPIC_SERVER_URL` (see above). -> - **AWS Bedrock**: `BEDROCK_*` variables (see [AWS Bedrock Provider Configuration](#aws-bedrock-provider-configuration)). +> - **Anthropic 直连 API**：`ANTHROPIC_API_KEY` 与 `ANTHROPIC_SERVER_URL`（见上文）。 +> - **AWS Bedrock**：`BEDROCK_*` 相关变量（见 [AWS Bedrock 提供商配置](#aws-bedrock-provider-configuration)）。 > -> If you need to use Vertex AI today, the safest supported workaround is to expose Vertex AI through an OpenAI-compatible proxy or gateway that translates Vertex AI calls into the Chat Completions format while preserving the chat and tool-call behavior PentAGI relies on, then point the Custom LLM provider at that gateway via `LLM_SERVER_URL`, `LLM_SERVER_KEY`, and `LLM_SERVER_MODEL`. This path is only as reliable as the gateway you choose. +> 若你当下需要使用 Vertex AI，最安全且受支持的变通方案是：通过 OpenAI 兼容代理或网关暴露 Vertex AI，将 Vertex AI 调用转换为 Chat Completions 格式，同时保留 PentAGI 所依赖的聊天与 tool-call 行为，然后通过 `LLM_SERVER_URL`、`LLM_SERVER_KEY` 与 `LLM_SERVER_MODEL` 将 Custom LLM 提供商指向该网关。此路径的可靠性取决于你所选网关。 -#### Supported Models +#### 支持的模型 -PentAGI supports 10 Claude models with tool calling, streaming, extended thinking, adaptive thinking, and prompt caching. Models marked with `*` are used in default configuration. +PentAGI 支持 10 款 Claude 模型，具备工具调用、流式输出、扩展思考、自适应思考与提示缓存。标有 `*` 的模型用于默认配置。 -**Claude 4 Series - Latest Models (2025-2026)** +**Claude 4 系列 — 最新模型（2025-2026）** | Model ID | Thinking | Release Date | Price (Input/Output/Cache R/W) | Use Case | | ------------------------ | -------- | ------------ | ------------------------------ | ----------------------------------------------- | -| `claude-opus-4-6`* | ✅ | May 2025 | $5.00/$25.00/$0.50/$6.25 | Most intelligent model for autonomous agents and coding. Extended + adaptive thinking for complex exploit development, multi-stage attack simulation | -| `claude-sonnet-4-6`* | ✅ | Aug 2025 | $3.00/$15.00/$0.30/$3.75 | Best speed/intelligence balance with adaptive thinking. Multi-phase security assessments, intelligent vulnerability analysis, real-time threat hunting | -| `claude-haiku-4-5`* | ✅ | Oct 2025 | $1.00/$5.00/$0.10/$1.25 | Fastest model with near-frontier intelligence. High-frequency scanning, real-time monitoring, bulk automated testing | +| `claude-opus-4-6`* | ✅ | May 2025 | $5.00/$25.00/$0.50/$6.25 | 面向自主智能体与编码的最强模型。扩展 + 自适应思考，用于复杂 exploit 开发、多阶段攻击模拟 | +| `claude-sonnet-4-6`* | ✅ | Aug 2025 | $3.00/$15.00/$0.30/$3.75 | 速度与智能的最佳平衡，具备自适应思考。多阶段安全评估、智能漏洞分析、实时威胁狩猎 | +| `claude-haiku-4-5`* | ✅ | Oct 2025 | $1.00/$5.00/$0.10/$1.25 | 速度最快、接近前沿智能的模型。高频扫描、实时监控、批量自动化测试 | -**Legacy Models - Still Supported** +**旧版模型 — 仍受支持** | Model ID | Thinking | Release Date | Price (Input/Output/Cache R/W) | Use Case | | ------------------------ | -------- | ------------ | ------------------------------ | ----------------------------------------------- | -| `claude-sonnet-4-5` | ✅ | Sep 2025 | $3.00/$15.00/$0.30/$3.75 | State-of-the-art reasoning (superseded by 4-6). Sophisticated penetration testing, advanced threat analysis | -| `claude-opus-4-5` | ✅ | Nov 2025 | $5.00/$25.00/$0.50/$6.25 | Ultimate reasoning (superseded by opus-4-6). Critical security research, zero-day discovery, red team operations | -| `claude-opus-4-1` | ✅ | Aug 2025 | $15.00/$75.00/$1.50/$18.75 | Advanced reasoning (superseded). Complex penetration testing, sophisticated threat modeling | -| `claude-sonnet-4-0` | ✅ | May 2025 | $3.00/$15.00/$0.30/$3.75 | High-performance reasoning (superseded). Complex threat modeling, multi-tool coordination | -| `claude-opus-4-0` | ✅ | May 2025 | $15.00/$75.00/$1.50/$18.75 | First generation Opus (superseded). Multi-step exploit development, autonomous pentesting workflows | +| `claude-sonnet-4-5` | ✅ | Sep 2025 | $3.00/$15.00/$0.30/$3.75 | 顶尖推理能力（已被 4-6 取代）。复杂渗透测试、高级威胁分析 | +| `claude-opus-4-5` | ✅ | Nov 2025 | $5.00/$25.00/$0.50/$6.25 | 极致推理（已被 opus-4-6 取代）。关键安全研究、零日漏洞发现、红队行动 | +| `claude-opus-4-1` | ✅ | Aug 2025 | $15.00/$75.00/$1.50/$18.75 | 高级推理（已取代）。复杂渗透测试、精细威胁建模 | +| `claude-sonnet-4-0` | ✅ | May 2025 | $3.00/$15.00/$0.30/$3.75 | 高性能推理（已取代）。复杂威胁建模、多工具协同 | +| `claude-opus-4-0` | ✅ | May 2025 | $15.00/$75.00/$1.50/$18.75 | 第一代 Opus（已取代）。多步骤 exploit 开发、自主渗透测试工作流 | -**Deprecated Models - Migrate to Current Models** +**已弃用模型 — 请迁移至当前模型** | Model ID | Thinking | Release Date | Price (Input/Output/Cache R/W) | Notes | | ---------------------------- | -------- | ------------ | ------------------------------ | -------------------------------------------- | -| `claude-3-haiku-20240307` | ❌ | Mar 2024 | $0.25/$1.25/$0.03/$0.30 | Will be retired April 19, 2026. Migrate to claude-haiku-4-5 | +| `claude-3-haiku-20240307` | ❌ | Mar 2024 | $0.25/$1.25/$0.03/$0.30 | 将于 2026 年 4 月 19 日停用。请迁移至 claude-haiku-4-5 | -**Prices**: Per 1M tokens. Cache pricing includes both Read and Write costs. +**价格**：按每 100 万 token 计。缓存定价包含读与写成本。 -**Extended Thinking Configuration**: -- **Max Tokens 4096**: Generator (claude-opus-4-6) for maximum reasoning depth on complex exploit development -- **Max Tokens 2048**: Coder (claude-sonnet-4-6) for balanced code analysis and vulnerability research -- **Max Tokens 1024**: Primary agent, assistant, refiner, adviser, reflector, searcher, installer, pentester for focused reasoning on specific tasks -- **Extended Thinking**: All Claude 4.5+ and 4.6 models support configurable extended thinking for deep reasoning tasks +**扩展思考配置**： +- **Max Tokens 4096**：Generator（claude-opus-4-6），用于复杂 exploit 开发的最大推理深度 +- **Max Tokens 2048**：Coder（claude-sonnet-4-6），用于均衡的代码分析与漏洞研究 +- **Max Tokens 1024**：Primary agent、assistant、refiner、adviser、reflector、searcher、installer、pentester，用于针对特定任务的聚焦推理 +- **Extended Thinking**：所有 Claude 4.5+ 与 4.6 模型均支持可配置的扩展思考，用于深度推理任务 -**Key Features**: -- **Extended Thinking**: All Claude 4.5+ and 4.6 models with configurable chain-of-thought reasoning depths for complex security analysis -- **Adaptive Thinking**: Claude 4.6 series (Opus/Sonnet) dynamically adjusts reasoning depth based on task complexity for optimal performance -- **Prompt Caching**: Significant cost reduction with separate read/write pricing (10% read, 125% write of input) -- **Extended Context Window**: 200K tokens standard, up to 1M tokens (beta) for Claude Opus/Sonnet 4.6 for comprehensive codebase analysis -- **Tool Calling**: Robust function calling with exceptional accuracy for security tool orchestration -- **Streaming**: Real-time response streaming for interactive penetration testing workflows -- **Safety-First Design**: Built-in safety mechanisms ensuring responsible security testing practices -- **Multimodal Support**: Vision capabilities in latest models for screenshot analysis and UI security assessment -- **Constitutional AI**: Advanced safety training providing reliable and ethical security guidance +**核心特性**： +- **扩展思考（Extended Thinking）**：所有 Claude 4.5+ 与 4.6 模型，可配置思维链推理深度，用于复杂安全分析 +- **自适应思考（Adaptive Thinking）**：Claude 4.6 系列（Opus/Sonnet）根据任务复杂度动态调整推理深度，以获得最佳性能 +- **提示缓存（Prompt Caching）**：显著降低成本，读写分开计价（读为输入的 10%，写为输入的 125%） +- **扩展上下文窗口**：标准 200K token，Claude Opus/Sonnet 4.6 最高可达 1M token（beta），用于全面代码库分析 +- **工具调用（Tool Calling）**：稳健的函数调用，精度出色，用于安全工具编排 +- **流式输出（Streaming）**：实时响应流，用于交互式渗透测试工作流 +- **安全优先设计**：内置安全机制，确保负责任的安全测试实践 +- **多模态支持**：最新模型具备视觉能力，用于截图分析与 UI 安全评估 +- **Constitutional AI**：先进安全训练，提供可靠且合乎伦理的安全指导 -### Google AI (Gemini) Provider Configuration +### Google AI（Gemini）提供商配置 -PentAGI integrates with Google's Gemini models through the Google AI API, offering state-of-the-art multimodal reasoning capabilities with extended thinking and context caching. +PentAGI 通过 Google AI API 集成 Google 的 Gemini 模型，提供顶尖多模态推理能力，并支持扩展思考与上下文缓存。 -#### Configuration Variables +#### 配置变量 | Variable | Default | Description | | ------------------- | ------------------------------------------- | ------------------------------ | -| `GEMINI_API_KEY` | | API key for Google AI services | -| `GEMINI_SERVER_URL` | `https://generativelanguage.googleapis.com` | Google AI API endpoint | +| `GEMINI_API_KEY` | | Google AI 服务 API 密钥 | +| `GEMINI_SERVER_URL` | `https://generativelanguage.googleapis.com` | Google AI API 端点 | -#### Configuration Examples +#### 配置示例 ```bash # Basic Gemini setup @@ -1770,92 +1776,92 @@ GEMINI_API_KEY=your_gemini_api_key PROXY_URL=http://your-proxy:8080 ``` -#### Supported Models +#### 支持的模型 -PentAGI supports 9 Gemini models with tool calling, streaming, thinking modes, and context caching. Models marked with `*` are used in default configuration. +PentAGI 支持 9 款 Gemini 模型，具备工具调用（tool calling）、流式输出（streaming）、思考模式（thinking modes）和上下文缓存（context caching）能力。标记为 `*` 的模型用于默认配置。 -**Gemini 3.5 Series - Latest Stable Flash (May 2026)** +**Gemini 3.5 系列 - 最新稳定版 Flash（2026 年 5 月）** | Model ID | Thinking | Context | Price (Input/Output/Cache) | Use Case | | ------------------------------------- | -------- | ------- | -------------------------- | ----------------------------------------------- | -| `gemini-3.5-flash`* | ✅ | 1M | $1.50/$9.00/$0.15 | Most intelligent Flash model with sustained frontier performance on agentic and coding tasks, superior search and grounding | +| `gemini-3.5-flash`* | ✅ | 1M | $1.50/$9.00/$0.15 | 最智能的 Flash 模型，在智能体与编码任务上持续保持前沿性能，搜索与 grounding 能力出众 | -**Gemini 3.1 Series - Stable Flash-Lite + Pro Preview (Feb-May 2026)** +**Gemini 3.1 系列 - 稳定版 Flash-Lite + Pro 预览版（2026 年 2 月至 5 月）** | Model ID | Thinking | Context | Price (Input/Output/Cache) | Use Case | | ------------------------------------- | -------- | ------- | -------------------------- | ----------------------------------------------- | -| `gemini-3.1-pro-preview`* | ✅ | 1M | $2.00/$12.00/$0.20 | Latest flagship with refined thinking, improved token efficiency, optimized for software engineering and agentic workflows | -| `gemini-3.1-pro-preview-customtools` | ✅ | 1M | $2.00/$12.00/$0.20 | Custom tools endpoint optimized for bash and custom tools (view_file, search_code) prioritization | -| `gemini-3.1-flash-lite`* | ✅ | 1M | $0.25/$1.50/$0.025 | Most cost-efficient stable multimodal model, frontier-class performance for high-volume agentic tasks and low-latency applications | +| `gemini-3.1-pro-preview`* | ✅ | 1M | $2.00/$12.00/$0.20 | 最新旗舰模型，思考能力更精炼、token 效率更高，针对软件工程与智能体工作流优化 | +| `gemini-3.1-pro-preview-customtools` | ✅ | 1M | $2.00/$12.00/$0.20 | 面向 bash 与自定义工具（view_file、search_code）优先级的自定义工具端点 | +| `gemini-3.1-flash-lite`* | ✅ | 1M | $0.25/$1.50/$0.025 | 最具成本效益的稳定多模态模型，面向高吞吐量智能体任务与低延迟应用提供前沿级性能 | -**Gemini 2.5 Series - Advanced Thinking Models (active until October 16, 2026)** +**Gemini 2.5 系列 - 高级思考模型（活跃至 2026 年 10 月 16 日）** | Model ID | Thinking | Context | Price (Input/Output/Cache) | Use Case | | ---------------------------------------- | -------- | ------- | -------------------------- | ----------------------------------------------- | -| `gemini-2.5-pro` | ✅ | 1M | $1.25/$10.00/$0.125 | State-of-the-art for complex coding and reasoning, sophisticated threat modeling | -| `gemini-2.5-flash` | ✅ | 1M | $0.30/$2.50/$0.03 | First hybrid reasoning model with thinking budgets, best price-performance for large-scale assessments | -| `gemini-2.5-flash-lite` | ✅ | 1M | $0.10/$0.40/$0.01 | Smallest and most cost-effective for at-scale usage, high-throughput scanning | +| `gemini-2.5-pro` | ✅ | 1M | $1.25/$10.00/$0.125 | 复杂编码与推理的顶尖选择，擅长精细化威胁建模 | +| `gemini-2.5-flash` | ✅ | 1M | $0.30/$2.50/$0.03 | 首款支持思考预算（thinking budgets）的混合推理模型，大规模评估场景下性价比最佳 | +| `gemini-2.5-flash-lite` | ✅ | 1M | $0.10/$0.40/$0.01 | 体量最小、成本最低，适合大规模使用与高吞吐量扫描 | -**Gemma 4 Open-Source Models (Apache 2.0, Free Tier)** +**Gemma 4 开源模型（Apache 2.0，免费层）** | Model ID | Thinking | Context | Price (Input/Output/Cache) | Use Case | | ------------------------------------- | -------- | ------- | -------------------------- | ----------------------------------------------- | -| `gemma-4-31b-it` | ✅ | 256K | Free/Free/Free | Largest open-source Gemma 4 dense model (~31B params), multimodal text+image, 140+ languages, on-premises security operations | -| `gemma-4-26b-a4b-it` | ✅ | 256K | Free/Free/Free | MoE architecture (~26B total / ~3.8B active params), highly efficient inference on consumer GPUs for on-premises high-throughput scanning | +| `gemma-4-31b-it` | ✅ | 256K | Free/Free/Free | 最大的 Gemma 4 开源稠密模型（约 31B 参数），多模态文本+图像，支持 140+ 种语言，适用于本地部署安全运营 | +| `gemma-4-26b-a4b-it` | ✅ | 256K | Free/Free/Free | MoE 架构（总参数约 26B / 激活参数约 3.8B），在消费级 GPU 上高效推理，适合本地高吞吐量扫描 | -**Prices**: Per 1M tokens (Standard Paid tier). Context window is input token limit. +**价格**：按每 100 万 token 计费（Standard Paid 层）。上下文窗口为输入 token 上限。 > [!NOTE] -> **Gemini 2.5 Series Shutdown** +> **Gemini 2.5 系列下线** > -> `gemini-2.5-pro`, `gemini-2.5-flash`, and `gemini-2.5-flash-lite` will be **shut down on October 16, 2026**. Recommended migrations: +> `gemini-2.5-pro`、`gemini-2.5-flash` 和 `gemini-2.5-flash-lite` 将于 **2026 年 10 月 16 日** **下线**。建议迁移路径： > -> - `gemini-2.5-pro` → `gemini-3.1-pro-preview` (same $2.00 input pricing tier) -> - `gemini-2.5-flash` → `gemini-3.5-flash` (improved frontier capabilities) -> - `gemini-2.5-flash-lite` → `gemini-3.1-flash-lite` (same $0.25 input pricing) +> - `gemini-2.5-pro` → `gemini-3.1-pro-preview`（相同 $2.00 输入定价层） +> - `gemini-2.5-flash` → `gemini-3.5-flash`（增强的前沿能力） +> - `gemini-2.5-flash-lite` → `gemini-3.1-flash-lite`（相同 $0.25 输入定价） -**Default Model Assignments (config.yml)**: -- **`gemini-3.1-pro-preview`** - `primary_agent`, `assistant`, `generator`, `refiner`, `adviser`, `coder`, `pentester` -- **`gemini-3.5-flash`** - `reflector`, `searcher`, `enricher`, `installer` -- **`gemini-3.1-flash-lite`** - `simple`, `simple_json` +**默认模型分配（config.yml）**： +- **`gemini-3.1-pro-preview`** - `primary_agent`、`assistant`、`generator`、`refiner`、`adviser`、`coder`、`pentester` +- **`gemini-3.5-flash`** - `reflector`、`searcher`、`enricher`、`installer` +- **`gemini-3.1-flash-lite`** - `simple`、`simple_json` -**Key Features**: -- **Extended Thinking**: Step-by-step reasoning for complex security analysis (all Gemini 3.x, 2.5 series, and Gemma 4 with toggleable thinking) -- **Context Caching**: Significant cost reduction on repeated context (10% of input price for most models) -- **Ultra-Long Context**: 1M tokens for Gemini chat models, 256K tokens for Gemma 4 open-source models -- **Multimodal Support**: Text, image, video, audio, and PDF processing for comprehensive assessments -- **Tool Calling**: Seamless integration with 20+ pentesting tools via function calling -- **Streaming**: Real-time response streaming for interactive security workflows -- **Code Execution**: Built-in code execution for offensive tool testing and exploit validation -- **Search Grounding**: Google Search integration for threat intelligence and CVE research -- **File Search**: Document retrieval and RAG capabilities for knowledge-based assessments -- **Batch API**: 50% cost reduction for non-real-time batch processing -- **Custom Tools Endpoint**: Dedicated `gemini-3.1-pro-preview-customtools` route for tool-heavy agentic workflows that prefer registered tools over bash +**核心特性**： +- **扩展思考（Extended Thinking）**：面向复杂安全分析的逐步推理（所有 Gemini 3.x、2.5 系列及 Gemma 4 均支持可切换的思考模式） +- **上下文缓存（Context Caching）**：重复上下文可显著降低成本（多数模型为输入价格的 10%） +- **超长上下文（Ultra-Long Context）**：Gemini 对话模型支持 1M token，Gemma 4 开源模型支持 256K token +- **多模态支持（Multimodal Support）**：支持文本、图像、视频、音频和 PDF 处理，便于全面评估 +- **工具调用（Tool Calling）**：通过函数调用无缝集成 20+ 款渗透测试工具 +- **流式输出（Streaming）**：实时响应流，适用于交互式安全工作流 +- **代码执行（Code Execution）**：内置代码执行，用于攻击性工具测试与漏洞利用验证 +- **搜索 Grounding（Search Grounding）**：集成 Google Search，用于威胁情报与 CVE 研究 +- **文件搜索（File Search）**：文档检索与 RAG 能力，支持基于知识的评估 +- **批量 API（Batch API）**：非实时批量处理可节省 50% 成本 +- **自定义工具端点（Custom Tools Endpoint）**：专用 `gemini-3.1-pro-preview-customtools` 路由，面向偏好已注册工具而非 bash 的工具密集型智能体工作流 -**Reasoning Effort Levels**: -- **High**: Maximum thinking depth for complex multi-step analysis (generator) -- **Medium**: Balanced reasoning for general agentic tasks (primary_agent, assistant, refiner, adviser) -- **Low**: Efficient thinking for focused tasks (coder, installer, pentester) +**推理力度级别（Reasoning Effort Levels）**： +- **High**：最大思考深度，适用于复杂多步分析（generator） +- **Medium**：均衡推理，适用于通用智能体任务（primary_agent、assistant、refiner、adviser） +- **Low**：高效思考，适用于聚焦型任务（coder、installer、pentester） -### AWS Bedrock Provider Configuration +### AWS Bedrock 提供商配置 -PentAGI integrates with Amazon Bedrock, offering access to 20+ foundation models from leading AI companies including Anthropic, Amazon, Cohere, DeepSeek, OpenAI, Qwen, Mistral, and Moonshot. +PentAGI 集成 Amazon Bedrock，可访问来自 Anthropic、Amazon、Cohere、DeepSeek、OpenAI、Qwen、Mistral 和 Moonshot 等领先 AI 公司的 20+ 款基础模型。 -#### Configuration Variables +#### 配置变量 | Variable | Default | Description | | --------------------------- | ----------- | --------------------------------------------------------------------------------------------------- | -| `BEDROCK_REGION` | `us-east-1` | AWS region for Bedrock service | -| `BEDROCK_DEFAULT_AUTH` | `false` | Use AWS SDK default credential chain (environment, EC2 role, ~/.aws/credentials) - highest priority | -| `BEDROCK_BEARER_TOKEN` | | Bearer token authentication - priority over static credentials | -| `BEDROCK_ACCESS_KEY_ID` | | AWS access key ID for static credentials | -| `BEDROCK_SECRET_ACCESS_KEY` | | AWS secret access key for static credentials | -| `BEDROCK_SESSION_TOKEN` | | AWS session token for temporary credentials (optional, used with static credentials) | -| `BEDROCK_SERVER_URL` | | Custom Bedrock endpoint (VPC endpoints, local testing) | +| `BEDROCK_REGION` | `us-east-1` | Bedrock 服务所在的 AWS 区域 | +| `BEDROCK_DEFAULT_AUTH` | `false` | 使用 AWS SDK 默认凭证链（环境变量、EC2 角色、~/.aws/credentials）——优先级最高 | +| `BEDROCK_BEARER_TOKEN` | | Bearer token 认证——优先级高于静态凭证 | +| `BEDROCK_ACCESS_KEY_ID` | | 静态凭证的 AWS 访问密钥 ID | +| `BEDROCK_SECRET_ACCESS_KEY` | | 静态凭证的 AWS 秘密访问密钥 | +| `BEDROCK_SESSION_TOKEN` | | 临时凭证的 AWS 会话令牌（可选，与静态凭证配合使用） | +| `BEDROCK_SERVER_URL` | | 自定义 Bedrock 端点（VPC 端点、本地测试） | -**Authentication Priority**: `BEDROCK_DEFAULT_AUTH` → `BEDROCK_BEARER_TOKEN` → `BEDROCK_ACCESS_KEY_ID`+`BEDROCK_SECRET_ACCESS_KEY` +**认证优先级**：`BEDROCK_DEFAULT_AUTH` → `BEDROCK_BEARER_TOKEN` → `BEDROCK_ACCESS_KEY_ID`+`BEDROCK_SECRET_ACCESS_KEY` -#### Configuration Examples +#### 配置示例 ```bash # Recommended: Default AWS SDK authentication (EC2/ECS/Lambda roles) @@ -1878,93 +1884,93 @@ BEDROCK_SERVER_URL=https://bedrock-runtime.us-east-1.vpce-xxx.amazonaws.com PROXY_URL=http://your-proxy:8080 ``` -#### Supported Models +#### 支持的模型 -PentAGI supports 21 AWS Bedrock models with tool calling, streaming, and multimodal capabilities. Models marked with `*` are used in default configuration. +PentAGI 支持 21 个具备工具调用、流式输出和多模态能力的 AWS Bedrock 模型。标有 `*` 的模型用于默认配置。 | Model ID | Provider | Thinking | Multimodal | Price (Input/Output) | Use Case | | ------------------------------------------------ | --------------- | -------- | ---------- | -------------------- | --------------------------------------- | -| `us.amazon.nova-2-lite-v1:0` | Amazon Nova | ❌ | ✅ | $0.33/$2.75 | Adaptive reasoning, efficient thinking | -| `us.amazon.nova-premier-v1:0` | Amazon Nova | ❌ | ✅ | $2.50/$12.50 | Complex reasoning, advanced analysis | -| `us.amazon.nova-pro-v1:0` | Amazon Nova | ❌ | ✅ | $0.80/$3.20 | Balanced accuracy, speed, cost | -| `us.amazon.nova-lite-v1:0` | Amazon Nova | ❌ | ✅ | $0.06/$0.24 | Fast processing, high-volume operations | -| `us.amazon.nova-micro-v1:0` | Amazon Nova | ❌ | ❌ | $0.035/$0.14 | Ultra-low latency, real-time monitoring | -| `us.anthropic.claude-opus-4-6-v1`* | Anthropic | ✅ | ✅ | $5.00/$25.00 | World-class coding, enterprise agents | -| `us.anthropic.claude-sonnet-4-6` | Anthropic | ✅ | ✅ | $3.00/$15.00 | Frontier intelligence, enterprise scale | -| `us.anthropic.claude-opus-4-5-20251101-v1:0` | Anthropic | ✅ | ✅ | $5.00/$25.00 | Multi-day software development | -| `us.anthropic.claude-haiku-4-5-20251001-v1:0`* | Anthropic | ✅ | ✅ | $1.00/$5.00 | Near-frontier performance, high speed | -| `us.anthropic.claude-sonnet-4-5-20250929-v1:0`* | Anthropic | ✅ | ✅ | $3.00/$15.00 | Real-world agents, coding excellence | -| `us.anthropic.claude-sonnet-4-20250514-v1:0` | Anthropic | ✅ | ✅ | $3.00/$15.00 | Balanced performance, production-ready | -| `us.anthropic.claude-3-5-haiku-20241022-v1:0` | Anthropic | ❌ | ❌ | $0.80/$4.00 | Fastest model, cost-effective scanning | -| `cohere.command-r-plus-v1:0` | Cohere | ❌ | ❌ | $3.00/$15.00 | Large-scale operations, superior RAG | -| `deepseek.v3.2` | DeepSeek | ❌ | ❌ | $0.58/$1.68 | Long-context reasoning, efficiency | -| `openai.gpt-oss-120b-1:0`* | OpenAI (OSS) | ✅ | ❌ | $0.15/$0.60 | Strong reasoning, scientific analysis | -| `openai.gpt-oss-20b-1:0` | OpenAI (OSS) | ✅ | ❌ | $0.07/$0.30 | Efficient coding, software development | -| `qwen.qwen3-next-80b-a3b` | Qwen | ❌ | ❌ | $0.15/$1.20 | Ultra-long context, flagship reasoning | -| `qwen.qwen3-32b-v1:0` | Qwen | ❌ | ❌ | $0.15/$0.60 | Balanced reasoning, research use cases | -| `qwen.qwen3-coder-30b-a3b-v1:0` | Qwen | ❌ | ❌ | $0.15/$0.60 | Vibe coding, natural-language first | -| `qwen.qwen3-coder-next` | Qwen | ❌ | ❌ | $0.45/$1.80 | Tool use, function calling optimized | -| `mistral.mistral-large-3-675b-instruct` | Mistral | ❌ | ✅ | $4.00/$12.00 | Advanced multimodal, long-context | -| `moonshotai.kimi-k2.5` | Moonshot | ❌ | ✅ | $0.60/$3.00 | Vision, language, code in one model | +| `us.amazon.nova-2-lite-v1:0` | Amazon Nova | ❌ | ✅ | $0.33/$2.75 | 自适应推理、高效思考 | +| `us.amazon.nova-premier-v1:0` | Amazon Nova | ❌ | ✅ | $2.50/$12.50 | 复杂推理、高级分析 | +| `us.amazon.nova-pro-v1:0` | Amazon Nova | ❌ | ✅ | $0.80/$3.20 | 准确度、速度与成本均衡 | +| `us.amazon.nova-lite-v1:0` | Amazon Nova | ❌ | ✅ | $0.06/$0.24 | 快速处理、高吞吐量操作 | +| `us.amazon.nova-micro-v1:0` | Amazon Nova | ❌ | ❌ | $0.035/$0.14 | 超低延迟、实时监控 | +| `us.anthropic.claude-opus-4-6-v1`* | Anthropic | ✅ | ✅ | $5.00/$25.00 | 世界级编码、企业级智能体 | +| `us.anthropic.claude-sonnet-4-6` | Anthropic | ✅ | ✅ | $3.00/$15.00 | 前沿智能、企业级规模 | +| `us.anthropic.claude-opus-4-5-20251101-v1:0` | Anthropic | ✅ | ✅ | $5.00/$25.00 | 多日软件开发 | +| `us.anthropic.claude-haiku-4-5-20251001-v1:0`* | Anthropic | ✅ | ✅ | $1.00/$5.00 | 接近前沿性能、高速响应 | +| `us.anthropic.claude-sonnet-4-5-20250929-v1:0`* | Anthropic | ✅ | ✅ | $3.00/$15.00 | 真实场景智能体、卓越编码能力 | +| `us.anthropic.claude-sonnet-4-20250514-v1:0` | Anthropic | ✅ | ✅ | $3.00/$15.00 | 性能均衡、可用于生产 | +| `us.anthropic.claude-3-5-haiku-20241022-v1:0` | Anthropic | ❌ | ❌ | $0.80/$4.00 | 最快模型、高性价比扫描 | +| `cohere.command-r-plus-v1:0` | Cohere | ❌ | ❌ | $3.00/$15.00 | 大规模操作、卓越 RAG | +| `deepseek.v3.2` | DeepSeek | ❌ | ❌ | $0.58/$1.68 | 长上下文推理、高效 | +| `openai.gpt-oss-120b-1:0`* | OpenAI (OSS) | ✅ | ❌ | $0.15/$0.60 | 强推理能力、科学分析 | +| `openai.gpt-oss-20b-1:0` | OpenAI (OSS) | ✅ | ❌ | $0.07/$0.30 | 高效编码、软件开发 | +| `qwen.qwen3-next-80b-a3b` | Qwen | ❌ | ❌ | $0.15/$1.20 | 超长上下文、旗舰级推理 | +| `qwen.qwen3-32b-v1:0` | Qwen | ❌ | ❌ | $0.15/$0.60 | 推理均衡、研究场景 | +| `qwen.qwen3-coder-30b-a3b-v1:0` | Qwen | ❌ | ❌ | $0.15/$0.60 | Vibe coding、自然语言优先 | +| `qwen.qwen3-coder-next` | Qwen | ❌ | ❌ | $0.45/$1.80 | 工具使用、函数调用优化 | +| `mistral.mistral-large-3-675b-instruct` | Mistral | ❌ | ✅ | $4.00/$12.00 | 高级多模态、长上下文 | +| `moonshotai.kimi-k2.5` | Moonshot | ❌ | ✅ | $0.60/$3.00 | 视觉、语言与代码一体化模型 | -**Prices**: Per 1M tokens. Models with thinking/reasoning support additional compute costs during reasoning phase. +**价格**：按每 100 万 token 计费。支持思考/推理的模型在推理阶段会产生额外计算成本。 -#### Tested but Incompatible Models +#### 已测试但不兼容的模型 -Some AWS Bedrock models were tested but are **not supported** due to technical limitations: +部分 AWS Bedrock 模型已完成测试，但由于技术限制**不受支持**： | Model Family | Reason for Incompatibility | | ------------------------- | ----------------------------------------------------------------------------------------- | -| **GLM (Z.AI)** | Tool calling format incompatible with Converse API (expects string instead of JSON) | -| **AI21 Jamba** | Severe rate limits (1-2 req/min) prevent reliable testing and production use | -| **Meta Llama 3.3/3.1** | Unstable tool call result processing, causes unexpected failures in multi-turn workflows | -| **Mistral Magistral** | Tool calling not supported by the model | -| **Moonshot K2-Thinking** | Unstable streaming behavior with tool calls, unreliable in production | -| **Qwen3-VL** | Unstable streaming with tool calling, multimodal + tools combination fails intermittently | +| **GLM (Z.AI)** | 工具调用格式与 Converse API 不兼容（期望字符串而非 JSON） | +| **AI21 Jamba** | 严格的速率限制（1-2 req/min）导致无法可靠测试及用于生产环境 | +| **Meta Llama 3.3/3.1** | 工具调用结果处理不稳定，会在多轮工作流中引发意外失败 | +| **Mistral Magistral** | 模型不支持工具调用 | +| **Moonshot K2-Thinking** | 带工具调用的流式输出行为不稳定，在生产环境中不可靠 | +| **Qwen3-VL** | 带工具调用的流式输出不稳定，多模态与工具组合会间歇性失败 | > [!IMPORTANT] -> **Rate Limits & Quota Management** +> **速率限制与配额管理** > -> Default AWS Bedrock quotas for Claude models are **extremely restrictive** (2-20 requests/minute for new accounts). For production penetration testing: +> Claude 模型的默认 AWS Bedrock 配额**极其严格**（新账户为 2-20 requests/minute）。用于生产级渗透测试时： > -> 1. **Request quota increases** through AWS Service Quotas console for models you plan to use -> 2. **Use Amazon Nova models** - higher default quotas and excellent performance -> 3. **Enable provisioned throughput** for consistent high-volume testing -> 4. **Monitor usage** - AWS throttles aggressively at quota limits +> 1. **申请提高配额**——通过 AWS Service Quotas 控制台为计划使用的模型提交配额提升申请 +> 2. **使用 Amazon Nova 模型**——默认配额更高，性能出色 +> 3. **启用预置吞吐量（provisioned throughput）**——用于稳定的高吞吐量测试 +> 4. **监控用量**——达到配额上限时 AWS 会进行激进限流 > -> Without quota increases, expect frequent delays and workflow interruptions. +> 若不提高配额，预计会出现频繁延迟和工作流中断。 > [!WARNING] -> **Converse API Requirements** +> **Converse API 要求** > -> PentAGI uses Amazon Bedrock **Converse API** for unified model access. All supported models require: +> PentAGI 使用 Amazon Bedrock **Converse API** 实现统一模型访问。所有受支持的模型均需满足： > -> - ✅ Converse/ConverseStream API support -> - ✅ Tool use (function calling) for penetration testing workflows -> - ✅ Streaming tool use for real-time feedback +> - ✅ 支持 Converse/ConverseStream API +> - ✅ 支持工具使用（function calling），用于渗透测试工作流 +> - ✅ 支持流式工具使用，以实现实时反馈 > -> Verify model capabilities at: [AWS Bedrock Model Features](https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference-supported-models-features.html) +> 请在以下地址核实模型能力：[AWS Bedrock Model Features](https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference-supported-models-features.html) -**Key Features**: -- **Automatic Prompt Caching**: 40-70% cost reduction on repeated context (Claude 4.x models) -- **Extended Thinking**: Step-by-step reasoning for complex security analysis (Claude, DeepSeek R1, OpenAI GPT) -- **Multimodal Analysis**: Process screenshots, diagrams, video for comprehensive testing (Nova, Claude, Mistral, Kimi) -- **Tool Calling**: Seamless integration with 20+ pentesting tools via function calling -- **Streaming**: Real-time response streaming for interactive security assessment workflows +**核心特性**： +- **自动提示缓存（Automatic Prompt Caching）**：重复上下文成本降低 40-70%（Claude 4.x 模型） +- **扩展思考（Extended Thinking）**：针对复杂安全分析的逐步推理（Claude、DeepSeek R1、OpenAI GPT） +- **多模态分析（Multimodal Analysis）**：处理截图、图表、视频以进行全面测试（Nova、Claude、Mistral、Kimi） +- **工具调用（Tool Calling）**：通过函数调用与 20+ 渗透测试工具无缝集成 +- **流式输出（Streaming）**：实时响应流，适用于交互式安全评估工作流 -### DeepSeek Provider Configuration +### DeepSeek 提供商配置 -PentAGI integrates with DeepSeek, providing access to advanced AI models with strong reasoning, coding capabilities, and context caching at competitive prices. +PentAGI 集成 DeepSeek，以具有竞争力的价格提供先进 AI 模型访问，具备强推理能力、编码能力以及上下文缓存。 -#### Configuration Variables +#### 配置变量 | Variable | Default Value | Description | | --------------------- | -------------------------- | --------------------------------------------------- | -| `DEEPSEEK_API_KEY` | | DeepSeek API key for authentication | -| `DEEPSEEK_SERVER_URL` | `https://api.deepseek.com` | DeepSeek API endpoint URL | -| `DEEPSEEK_PROVIDER` | | Provider prefix for LiteLLM integration (optional) | +| `DEEPSEEK_API_KEY` | | 用于身份验证的 DeepSeek API 密钥 | +| `DEEPSEEK_SERVER_URL` | `https://api.deepseek.com` | DeepSeek API 端点 URL | +| `DEEPSEEK_PROVIDER` | | 用于 LiteLLM 集成的提供商前缀（可选） | -#### Configuration Examples +#### 配置示例 ```bash # Direct API usage @@ -1977,28 +1983,26 @@ DEEPSEEK_SERVER_URL=http://litellm-proxy:4000 DEEPSEEK_PROVIDER=deepseek # Adds prefix to model names (deepseek/deepseek-v4-flash) for LiteLLM ``` -#### Supported Models +#### 支持的模型 -PentAGI supports 2 DeepSeek V4 models with tool calling, streaming, hybrid thinking/non-thinking modes, and context caching. Both models support thinking mode by default and can be switched to non-thinking mode via `extra_body`. Models marked with `*` are used in default configuration. +PentAGI 支持 2 款 DeepSeek V4 模型，具备工具调用（tool calling）、流式输出（streaming）、混合思考/非思考模式以及上下文缓存（context caching）能力。两款模型默认启用思考模式，可通过 `extra_body` 切换为非思考模式。标有 `*` 的模型用于默认配置。 | Model ID | Thinking | Max Output | Context | Price (Input/Output/Cache) | Use Case | | --------------------- | -------- | ---------- | ------- | -------------------------- | ---------------------------------------------------- | -| `deepseek-v4-flash`* | ✅ hybrid | 384K | 1M | $0.14/$0.28/$0.0028 | Utility agents, general dialogue, fast tool calling | -| `deepseek-v4-pro`* | ✅ hybrid | 384K | 1M | $1.74/$3.48/$0.0145 | Advanced reasoning, complex logic, security analysis | +| `deepseek-v4-flash`* | ✅ hybrid | 384K | 1M | $0.14/$0.28/$0.0028 | 实用型智能体、通用对话、快速工具调用 | +| `deepseek-v4-pro`* | ✅ hybrid | 384K | 1M | $1.74/$3.48/$0.0145 | 高级推理、复杂逻辑、安全分析 | -**Prices**: Per 1M tokens. Cache pricing applies to prompt tokens served from cache (input cache hit, reduced to 1/10 of launch price since 2026-04-26). Both models support hybrid thinking — `thinking` mode is enabled by default; pass `extra_body.thinking.type: disabled` to switch to non-thinking mode for faster/cheaper responses. +**价格**：按每 100 万 token 计费。缓存定价适用于从缓存提供的提示词 token（输入缓存命中，自 2026-04-26 起降至首发价格的 1/10）。两款模型均支持混合思考——默认启用 `thinking` 模式；传入 `extra_body.thinking.type: disabled` 可切换为非思考模式，以获得更快、更便宜的响应。 -> **Pricing Note (deepseek-v4-pro)**: The 75% promotional discount on `deepseek-v4-pro` officially ended on 2026-05-31 15:59 UTC. The prices above reflect the standard post-promotional pricing. If you have legacy configurations using the discounted prices ($0.435/$0.87/$0.003625), update them to the current rates for accurate cost tracking. +> **定价说明（deepseek-v4-pro）**：`deepseek-v4-pro` 的 75% 促销折扣已于 2026-05-31 15:59 UTC 正式结束。上表价格为促销结束后的标准定价。若你仍使用旧配置中的折扣价（$0.435/$0.87/$0.003625），请更新为当前费率，以便准确追踪成本。 -> The legacy model names `deepseek-chat` and `deepseek-reasoner` are scheduled -> for deprecation by DeepSeek on 2026-07-24. Existing user configurations -> referencing the legacy names continue to work until then; the defaults above -> use the current V4 names. `deepseek-chat` maps to `deepseek-v4-flash` -> non-thinking mode; `deepseek-reasoner` maps to `deepseek-v4-flash` thinking mode. +> 旧版模型名称 `deepseek-chat` 和 `deepseek-reasoner` 已由 DeepSeek 计划于 2026-07-24 弃用。 +> 引用这些旧名称的现有用户配置在此之前仍可正常使用；上表默认配置使用当前 V4 名称。`deepseek-chat` 映射至 `deepseek-v4-flash` +> 非思考模式；`deepseek-reasoner` 映射至 `deepseek-v4-flash` 思考模式。 -**Default Agent Configuration**: +**默认智能体配置**： -Strategy: prefer `deepseek-v4-flash` (12x cheaper input, 12x cheaper output) as the workhorse for utility/lightweight agents; reserve `deepseek-v4-pro` for complex multi-step reasoning. The `installer` agent runs on Flash with thinking enabled because environment setup tasks (shell commands, config edits) rarely require pro-level reasoning. Run A/B tests on your own workloads before promoting more agents to Pro. +策略：优先将 `deepseek-v4-flash`（输入便宜 12 倍、输出便宜 12 倍）作为实用型/轻量级智能体的主力；将 `deepseek-v4-pro` 保留给复杂的多步推理任务。`installer` 智能体在 Flash 上运行并启用思考模式，因为环境搭建任务（shell 命令、配置编辑）通常不需要 Pro 级推理能力。在将更多智能体升级为 Pro 之前，请针对自身工作负载进行 A/B 测试。 | Agent Role | Default Model | Thinking | Reasoning Effort | Max Output | Temperature | Top P | | ------------------------------------------- | -------------------- | -------- | ---------------- | ---------- | ----------- | ----- | @@ -2010,36 +2014,36 @@ Strategy: prefer `deepseek-v4-flash` (12x cheaper input, 12x cheaper output) as | Reflector / Searcher / Enricher | `deepseek-v4-flash` | Disabled | — | 4096 | 0.5 | 0.9 | | Simple / Simple JSON | `deepseek-v4-flash` | Disabled | — | 2048 | 0.3 | 0.9 | -> **Note**: When thinking mode is enabled, DeepSeek silently ignores `temperature`, `top_p`, `presence_penalty`, and `frequency_penalty`. The langchaingo client automatically nullifies `temperature`/`top_p` when `reasoning_effort` is set, so they appear as "(auto)" in the table above. All thinking-enabled agents also explicitly pass `extra_body.thinking.type: enabled` as defensive coding against future provider default changes. +> **说明**：启用思考模式时，DeepSeek 会静默忽略 `temperature`、`top_p`、`presence_penalty` 和 `frequency_penalty`。当设置 `reasoning_effort` 时，langchaingo 客户端会自动将 `temperature`/`top_p` 置空，因此上表中显示为 "(auto)"。所有启用思考的智能体还会显式传入 `extra_body.thinking.type: enabled`，作为防御性编码，以应对未来提供商默认设置的变更。 -**Key Features**: -- **Hybrid Thinking Modes**: Switch between thinking (deep reasoning) and non-thinking (fast) modes via `extra_body.thinking.type` -- **Automatic Prompt Caching**: Significant cost reduction on repeated context via cache-hit pricing (1/10 of launch price) -- **Extended Thinking**: Reinforcement learning CoT for complex security analysis (both V4 models) -- **Strong Coding**: Optimized for code generation and exploit development -- **Long Context**: 1M token context window with up to 384K output tokens -- **Tool Calling**: Seamless integration with 20+ pentesting tools via function calling -- **Streaming**: Real-time response streaming for interactive workflows -- **Multilingual**: Strong Chinese and English support -- **Additional Features**: JSON Output, Chat Prefix Completion (beta), FIM/Fill-in-the-Middle Completion (non-thinking mode only) +**核心特性**： +- **混合思考模式（Hybrid Thinking Modes）**：通过 `extra_body.thinking.type` 在思考模式（深度推理）与非思考模式（快速响应）之间切换 +- **自动提示词缓存（Automatic Prompt Caching）**：通过缓存命中定价（首发价格的 1/10）显著降低重复上下文的成本 +- **扩展思考（Extended Thinking）**：面向复杂安全分析的强化学习 CoT（两款 V4 模型均支持） +- **强编码能力（Strong Coding）**：针对代码生成与漏洞利用开发进行优化 +- **长上下文（Long Context）**：100 万 token 上下文窗口，最多 384K 输出 token +- **工具调用（Tool Calling）**：通过函数调用与 20+ 渗透测试工具无缝集成 +- **流式输出（Streaming）**：为交互式工作流提供实时响应流 +- **多语言（Multilingual）**：强大的中英文支持 +- **其他特性（Additional Features）**：JSON 输出、Chat Prefix Completion（beta）、FIM/Fill-in-the-Middle Completion（仅非思考模式） -**Concurrency Limits**: `deepseek-v4-flash`: 2500 concurrent requests; `deepseek-v4-pro`: 500 concurrent requests. +**并发限制**：`deepseek-v4-flash`：2500 个并发请求；`deepseek-v4-pro`：500 个并发请求。 -**LiteLLM Integration**: Set `DEEPSEEK_PROVIDER=deepseek` to enable model name prefixing when using default PentAGI configurations with LiteLLM proxy. Leave empty for direct API usage. +**LiteLLM 集成**：设置 `DEEPSEEK_PROVIDER=deepseek` 可在使用默认 PentAGI 配置配合 LiteLLM 代理时启用模型名称前缀。直连 API 使用时请留空。 -### GLM Provider Configuration +### GLM 提供商配置 -PentAGI integrates with GLM from Zhipu AI (Z.AI), providing advanced language models with MoE architecture, strong reasoning, and agentic capabilities developed by Tsinghua University. +PentAGI 集成智谱 AI（Z.AI）的 GLM，提供由清华大学开发、采用 MoE 架构、具备强推理与智能体能力的高级语言模型。 -#### Configuration Variables +#### 配置变量 | Variable | Default Value | Description | | ----------------- | ------------------------------- | ---------------------------------------------------------- | -| `GLM_API_KEY` | | GLM API key for authentication | -| `GLM_SERVER_URL` | `https://api.z.ai/api/paas/v4` | GLM API endpoint URL (international) | -| `GLM_PROVIDER` | | Provider prefix for LiteLLM integration (optional) | +| `GLM_API_KEY` | | 用于身份验证的 GLM API 密钥 | +| `GLM_SERVER_URL` | `https://api.z.ai/api/paas/v4` | GLM API 端点 URL（国际版） | +| `GLM_PROVIDER` | | LiteLLM 集成的提供商前缀（可选） | -#### Configuration Examples +#### 配置示例 ```bash # Direct API usage (international endpoint) @@ -2056,98 +2060,98 @@ GLM_SERVER_URL=http://litellm-proxy:4000 GLM_PROVIDER=zai # Adds prefix to model names (zai/glm-4) for LiteLLM ``` -#### Supported Models +#### 支持的模型 -PentAGI supports 13 GLM models with tool calling, streaming, hybrid thinking modes, and prompt caching. Models marked with `*` are used in default configuration. Thinking is controlled via `extra_body.thinking.type` ("enabled"/"disabled"); unlike Kimi, GLM is permissive about temperature in either mode. +PentAGI 支持 13 款 GLM 模型，具备工具调用、流式输出、混合思考模式以及提示词缓存能力。标有 `*` 的模型用于默认配置。思考模式通过 `extra_body.thinking.type`（"enabled"/"disabled"）控制；与 Kimi 不同，GLM 在两种模式下对 temperature 的限制都较为宽松。 -**GLM-5.x Series - Latest Generation (200K context, 128K max output)** +**GLM-5.x 系列 - 最新一代（200K 上下文，128K 最大输出）** | Model ID | Thinking | Context | Max Output | Price (Input/Output/Cache) | Use Case | | ---------------- | -------- | ------- | ---------- | -------------------------- | ------------------------------------------------------------------- | -| `glm-5.1`* | ✅ Hybrid | 200K | 128K | $1.40/$4.40/$0.26 | Newest flagship: 8h sustained autonomous execution, Claude Opus 4.6-aligned (generator/refiner/adviser/coder/pentester default) | -| `glm-5` | ✅ Hybrid | 200K | 128K | $1.00/$3.20/$0.20 | Foundation for Agentic Engineering, MoE 744B/40B active, Claude Opus 4.5-level coding | -| `glm-5-turbo`* | ✅ Hybrid | 200K | 128K | $1.20/$4.00/$0.24 | OpenClaw-native: optimized for tool invocation, persistent tasks, long-chain execution (primary_agent/assistant default) | +| `glm-5.1`* | ✅ Hybrid | 200K | 128K | $1.40/$4.40/$0.26 | 最新旗舰：8 小时持续自主执行，对齐 Claude Opus 4.6（generator/refiner/adviser/coder/pentester 默认） | +| `glm-5` | ✅ Hybrid | 200K | 128K | $1.00/$3.20/$0.20 | 智能体工程（Agentic Engineering）基座，MoE 744B/40B active，Claude Opus 4.5 级编码能力 | +| `glm-5-turbo`* | ✅ Hybrid | 200K | 128K | $1.20/$4.00/$0.24 | OpenClaw 原生：针对工具调用、持久化任务、长链执行优化（primary_agent/assistant 默认） | -**GLM-4.7 Series - Premium with Interleaved Thinking** +**GLM-4.7 系列 - 高级版，支持交错思考（Interleaved Thinking）** | Model ID | Thinking | Context | Max Output | Price (Input/Output/Cache) | Use Case | | ----------------- | -------- | ------- | ---------- | -------------------------- | --------------------------------------------------- | -| `glm-4.7` | ✅ Hybrid | 200K | 128K | $0.60/$2.20/$0.11 | Enhanced programming, stable multi-step reasoning | -| `glm-4.7-flashx` | ✅ Hybrid | 200K | 128K | $0.07/$0.40/$0.01 | Ultra-cheap with priority GPU, but lower RPM limits (avoid for high-frequency use) | -| `glm-4.7-flash` | ✅ Hybrid | 200K | 128K | Free/Free/Free | Free ~30B SOTA model, 1 concurrent request | +| `glm-4.7` | ✅ Hybrid | 200K | 128K | $0.60/$2.20/$0.11 | 增强编程能力，稳定的多步推理 | +| `glm-4.7-flashx` | ✅ Hybrid | 200K | 128K | $0.07/$0.40/$0.01 | 超低价且享有优先 GPU，但 RPM 限制较低（不适合高频使用） | +| `glm-4.7-flash` | ✅ Hybrid | 200K | 128K | Free/Free/Free | 免费约 30B SOTA 模型，1 个并发请求 | -**GLM-4.6 Series - Balanced with Auto-Thinking** +**GLM-4.6 系列 - 均衡型，支持自动思考（Auto-Thinking）** | Model ID | Thinking | Context | Max Output | Price (Input/Output/Cache) | Use Case | | --------- | -------- | ------- | ---------- | -------------------------- | ------------------------------------------------- | -| `glm-4.6` | ✅ Auto | 200K | 128K | $0.60/$2.20/$0.11 | Balanced, streaming tool calls, token-efficient | +| `glm-4.6` | ✅ Auto | 200K | 128K | $0.60/$2.20/$0.11 | 均衡型、流式工具调用、省 token | -**GLM-4.5 Series - Unified Reasoning/Coding/Agents** +**GLM-4.5 系列 - 统一推理/编码/智能体** | Model ID | Thinking | Context | Max Output | Price (Input/Output/Cache) | Use Case | | ---------------- | -------- | ------- | ---------- | -------------------------- | ------------------------------------------------- | -| `glm-4.5` | ✅ Auto | 128K | 96K | $0.60/$2.20/$0.11 | Unified, MoE 355B/32B active | -| `glm-4.5-x` | ✅ Auto | 128K | 96K | $2.20/$8.90/$0.45 | Ultra-fast premium, lowest latency | -| `glm-4.5-air`* | ✅ Auto | 128K | 96K | $0.20/$1.10/$0.03 | Cost-effective MoE 106B/12B (simple/simple_json/reflector/searcher/enricher/installer default) | -| `glm-4.5-airx` | ✅ Auto | 128K | 96K | $1.10/$4.50/$0.22 | Accelerated Air with priority GPU | -| `glm-4.5-flash` | ✅ Auto | 128K | 96K | Free/Free/Free | Free with reasoning/coding/agents support | +| `glm-4.5` | ✅ Auto | 128K | 96K | $0.60/$2.20/$0.11 | 统一型，MoE 355B/32B 激活参数 | +| `glm-4.5-x` | ✅ Auto | 128K | 96K | $2.20/$8.90/$0.45 | 超快高端版，最低延迟 | +| `glm-4.5-air`* | ✅ Auto | 128K | 96K | $0.20/$1.10/$0.03 | 高性价比 MoE 106B/12B（simple/simple_json/reflector/searcher/enricher/installer 默认） | +| `glm-4.5-airx` | ✅ Auto | 128K | 96K | $1.10/$4.50/$0.22 | 加速版 Air，优先 GPU | +| `glm-4.5-flash` | ✅ Auto | 128K | 96K | Free/Free/Free | 免费，支持推理/编码/智能体 | -**GLM-4 Legacy - Dense Architecture** +**GLM-4 旧版 - 稠密架构（Dense Architecture）** | Model ID | Thinking | Context | Max Output | Price (Input/Output) | Use Case | | --------------------- | -------- | ------- | ---------- | -------------------- | --------------------------------------------- | -| `glm-4-32b-0414-128k` | ❌ | 128K | 16K | $0.10/$0.10 | Ultra-budget dense 32B, parsing without reasoning | +| `glm-4-32b-0414-128k` | ❌ | 128K | 16K | $0.10/$0.10 | 超低成本稠密 32B，无推理的解析任务 | -**Prices**: Per 1M tokens. Cache pricing is for prompt cache hit; cache storage is currently free per Z.AI promotion. GLM-4-32B has no cache support. +**价格**：按每 100 万 token 计费。缓存价格为提示词缓存命中价格；根据 Z.AI 促销，缓存存储目前免费。GLM-4-32B 不支持缓存。 -**Default Agent Configuration**: +**默认智能体配置**： -Strategy: `glm-5.1` (newest flagship, $1.40 input) for critical reasoning, `glm-5-turbo` (OpenClaw-native, agent-optimized) for orchestration, `glm-4.5-air` (cheap MoE with hybrid thinking and reliable RPM) for all utility/installer agents. `glm-4.7-flashx` is avoided as default due to lower RPM limits causing frequent 429 errors at high frequency. +策略：关键推理使用 `glm-5.1`（最新旗舰，输入 $1.40），编排使用 `glm-5-turbo`（OpenClaw 原生、面向智能体优化），所有 utility/installer 智能体使用 `glm-4.5-air`（低价 MoE，支持混合思考且 RPM 稳定）。由于 RPM 限制较低，高频调用时易出现 429 错误，默认配置避免使用 `glm-4.7-flashx`。 | Agent Role | Default Model | Thinking | Temperature | Top P | Max Output | | ----------------------------------- | ------------- | -------- | ----------- | ----- | ---------- | -| Generator / Refiner | `glm-5.1` | Enabled | 1.0 | 0.95 | 32768 | -| Coder | `glm-5.1` | Enabled | 1.0 | 0.95 | 20480 | -| Adviser / Pentester | `glm-5.1` | Enabled | 1.0 | 0.95 | 16384 | -| Primary Agent / Assistant | `glm-5-turbo` | Enabled | 1.0 | 0.95 | 16384 | -| Installer | `glm-4.5-air` | Enabled | 1.0 | 0.95 | 16384 | -| Simple / Reflector | `glm-4.5-air` | Disabled | 0.6 | 0.9 | 8192 | -| Searcher / Enricher / Simple JSON | `glm-4.5-air` | Disabled | 0.6 | 0.9 | 4096 | +| 生成器 / 精炼器 | `glm-5.1` | 启用 | 1.0 | 0.95 | 32768 | +| 编码器 | `glm-5.1` | 启用 | 1.0 | 0.95 | 20480 | +| 顾问 / 渗透测试 | `glm-5.1` | 启用 | 1.0 | 0.95 | 16384 | +| 主智能体 / 助手 | `glm-5-turbo` | 启用 | 1.0 | 0.95 | 16384 | +| 安装器 | `glm-4.5-air` | 启用 | 1.0 | 0.95 | 16384 | +| Simple / Reflector | `glm-4.5-air` | 禁用 | 0.6 | 0.9 | 8192 | +| 搜索器 / 增强器 / Simple JSON | `glm-4.5-air` | 禁用 | 0.6 | 0.9 | 4096 | -> **Note on temperature**: GLM accepts both `1.0` and `0.6` in either thinking/non-thinking mode (per Z.AI docs). langchaingo's `IsReasoningModel` matches `glm-4.5*`/`glm-4.6*`/`glm-4.7*` prefixes and force-overrides temperature to 1.0 in `createChatRequest` — this is harmless for GLM (unlike Kimi) but means temperature values for those models in YAML are advisory. `glm-5`/`glm-5.1`/`glm-5-turbo` are not matched, so explicit values pass through unchanged. +> **关于 temperature 的说明**：根据 Z.AI 文档，GLM 在思考/非思考模式下均接受 `1.0` 和 `0.6`。langchaingo 的 `IsReasoningModel` 会匹配 `glm-4.5*`/`glm-4.6*`/`glm-4.7*` 前缀，并在 `createChatRequest` 中强制将 temperature 覆盖为 1.0——这对 GLM 无害（与 Kimi 不同），但意味着这些模型在 YAML 中的 temperature 值仅供参考。`glm-5`/`glm-5.1`/`glm-5-turbo` 不会被匹配，因此显式设置的值会原样传递。 -**Thinking Modes**: -- **Hybrid** (GLM-5.x, GLM-4.7): Explicit toggle via `extra_body.thinking.type` -- **Auto** (GLM-4.6, GLM-4.5 series): Model automatically determines when reasoning is needed -- **Preserved Thinking** (Z.AI Coding capability): all thinking-enabled agents in PentAGI also pass `extra_body.thinking.clear_thinking: false` so that `reasoning_content` from previous assistant turns is retained across the conversation. This is required on the standard API endpoint (`/api/paas/v4`) — on the Coding Plan endpoint it would be enabled by default. Improves reasoning continuity and cache hit rates in multi-turn tool call chains. -- All thinking-enabled agents also pass `extra_body.tool_choice: auto` defensively +**思考模式**： +- **Hybrid（混合）**（GLM-5.x、GLM-4.7）：通过 `extra_body.thinking.type` 显式切换 +- **Auto（自动）**（GLM-4.6、GLM-4.5 系列）：模型自动判断何时需要推理 +- **Preserved Thinking（保留思考）**（Z.AI Coding 能力）：PentAGI 中所有启用思考的智能体也会传递 `extra_body.thinking.clear_thinking: false`，以便在对话中保留先前助手轮次的 `reasoning_content`。这在标准 API 端点（`/api/paas/v4`）上是必需的——在 Coding Plan 端点上默认启用。可提升多轮工具调用链中的推理连续性和缓存命中率。 +- 所有启用思考的智能体也会出于防御性目的传递 `extra_body.tool_choice: auto` -**Key Features**: -- **Long-Horizon Tasks**: GLM-5.1 supports 8-hour sustained autonomous execution, ideal for complex multi-stage agentic workflows -- **OpenClaw-Native Orchestration**: GLM-5-Turbo is specifically optimized for tool invocation, instruction following, and long-chain execution -- **Prompt Caching**: Significant cost reduction on repeated context (cached input pricing shown) -- **Ultra-Long Context**: 200K tokens for GLM-5.x/4.7/4.6 series -- **MoE Architecture**: Efficient 744B/40B active (GLM-5/5.1), 355B/32B (GLM-4.5), 106B/12B (GLM-4.5-Air) -- **Tool Calling**: Seamless integration with 20+ pentesting tools via function calling -- **Streaming**: Real-time streaming with streaming tool calls support (GLM-4.6+) -- **Multilingual**: Exceptional Chinese and English NLP capabilities -- **Free Options**: GLM-4.7-Flash and GLM-4.5-Flash for prototyping and experimentation +**核心特性**： +- **长程任务（Long-Horizon Tasks）**：GLM-5.1 支持最长 8 小时的持续自主执行，适合复杂的多阶段智能体工作流 +- **OpenClaw 原生编排**：GLM-5-Turbo 专门针对工具调用、指令遵循和长链执行进行了优化 +- **提示词缓存（Prompt Caching）**：重复上下文可显著降低成本（表中已列出缓存输入价格） +- **超长上下文**：GLM-5.x/4.7/4.6 系列支持 200K token +- **MoE 架构**：高效 744B/40B 激活参数（GLM-5/5.1）、355B/32B（GLM-4.5）、106B/12B（GLM-4.5-Air） +- **工具调用（Tool Calling）**：通过 function calling 与 20+ 渗透测试工具无缝集成 +- **流式输出（Streaming）**：实时流式输出，支持流式工具调用（GLM-4.6+） +- **多语言**：出色的中英文 NLP 能力 +- **免费选项**：GLM-4.7-Flash 和 GLM-4.5-Flash 可用于原型开发与实验 -**LiteLLM Integration**: Set `GLM_PROVIDER=zai` to enable model name prefixing when using default PentAGI configurations with LiteLLM proxy. Leave empty for direct API usage. +**LiteLLM 集成**：将 `GLM_PROVIDER=zai` 设置为启用模型名前缀，以便在使用 LiteLLM 代理的默认 PentAGI 配置时生效。直接调用 API 时请留空。 -### Kimi Provider Configuration +### Kimi 提供商配置 -PentAGI integrates with Kimi from Moonshot AI, providing ultra-long context models with multimodal capabilities perfect for analyzing extensive codebases and documentation. +PentAGI 集成 Moonshot AI 的 Kimi，提供具备多模态能力的超长上下文模型，非常适合分析大型代码库和文档。 -#### Configuration Variables +#### 配置变量 | Variable | Default Value | Description | | ------------------ | -----------------------------| --------------------------------------------------- | -| `KIMI_API_KEY` | | Kimi API key for authentication | -| `KIMI_SERVER_URL` | `https://api.moonshot.ai/v1` | Kimi API endpoint URL (international) | -| `KIMI_PROVIDER` | | Provider prefix for LiteLLM integration (optional) | +| `KIMI_API_KEY` | | Kimi API 密钥，用于身份验证 | +| `KIMI_SERVER_URL` | `https://api.moonshot.ai/v1` | Kimi API 端点 URL（国际版） | +| `KIMI_PROVIDER` | | LiteLLM 集成的提供商前缀（可选） | -#### Configuration Examples +#### 配置示例 ```bash # Direct API usage (international endpoint) @@ -2163,46 +2167,46 @@ KIMI_SERVER_URL=http://litellm-proxy:4000 KIMI_PROVIDER=moonshot # Adds prefix to model names (moonshot/kimi-k2.5) for LiteLLM ``` -#### Supported Models +#### 支持的模型 -PentAGI supports 8 Kimi/Moonshot models with tool calling, streaming, hybrid thinking modes, and multimodal capabilities (text/image/video for K2.x). All `kimi-k2-*` legacy models (turbo-preview, 0905-preview, 0711-preview, thinking, thinking-turbo) were deprecated by Moonshot on 2026-05-25 and are NOT included. Models marked with `*` are used in default configuration. +PentAGI 支持 8 个具备工具调用、流式输出、混合思考模式及多模态能力（K2.x 支持文本/图像/视频）的 Kimi/Moonshot 模型。所有 `kimi-k2-*` 旧版模型（turbo-preview、0905-preview、0711-preview、thinking、thinking-turbo）已于 2026-05-25 被 Moonshot 弃用，未包含在内。标记为 `*` 的模型用于默认配置。 -**Kimi K2.x Series - Multimodal Flagship** +**Kimi K2.x 系列 - 多模态旗舰** | Model ID | Thinking | Multimodal | Context | Price (Input Miss / Output / Cache Hit) | Use Case | | ---------------- | -------- | ---------- | ------- | --------------------------------------- | ------------------------------------------------------- | -| `kimi-k2.6`* | ✅ hybrid | ✅ | 256K | $0.95 / $4.00 / $0.16 | Latest flagship: native multimodal, stronger code, improved instruction compliance (generator/refiner/adviser/coder/pentester default) | -| `kimi-k2.5`* | ✅ hybrid | ✅ | 256K | $0.60 / $3.00 / $0.10 | Previous-gen: 36% cheaper input, same architecture (primary/assistant/installer/utility default) | +| `kimi-k2.6`* | ✅ hybrid | ✅ | 256K | $0.95 / $4.00 / $0.16 | 最新旗舰：原生多模态、更强代码能力、指令遵从性更佳（generator/refiner/adviser/coder/pentester 默认） | +| `kimi-k2.5`* | ✅ hybrid | ✅ | 256K | $0.60 / $3.00 / $0.10 | 上一代：输入价格低 36%，架构相同（primary/assistant/installer/utility 默认） | -**Moonshot V1 Series - Generation Models (Flexible Parameters)** +**Moonshot V1 系列 - 生成模型（灵活参数）** | Model ID | Thinking | Multimodal | Context | Price (Input / Output) | Use Case | | ------------------- | -------- | ---------- | ------- | ---------------------- | ---------------------------------------------- | -| `moonshot-v1-8k` | ❌ | ❌ | 8K | $0.20 / $2.00 | Short text generation, ultra-cheap | -| `moonshot-v1-32k` | ❌ | ❌ | 32K | $1.00 / $3.00 | Long text generation | -| `moonshot-v1-128k` | ❌ | ❌ | 128K | $2.00 / $5.00 | Very long context | +| `moonshot-v1-8k` | ❌ | ❌ | 8K | $0.20 / $2.00 | 短文本生成，超低成本 | +| `moonshot-v1-32k` | ❌ | ❌ | 32K | $1.00 / $3.00 | 长文本生成 | +| `moonshot-v1-128k` | ❌ | ❌ | 128K | $2.00 / $5.00 | 超长上下文 | -**Moonshot V1 Vision Series - Image Understanding** +**Moonshot V1 Vision 系列 - 图像理解** | Model ID | Thinking | Multimodal | Context | Price (Input / Output) | Use Case | | --------------------------------- | -------- | ---------- | ------- | ---------------------- | --------------------------------------- | -| `moonshot-v1-8k-vision-preview` | ❌ | ✅ | 8K | $0.20 / $2.00 | Vision + short context | -| `moonshot-v1-32k-vision-preview` | ❌ | ✅ | 32K | $1.00 / $3.00 | Vision + medium context | -| `moonshot-v1-128k-vision-preview` | ❌ | ✅ | 128K | $2.00 / $5.00 | Vision + long context | +| `moonshot-v1-8k-vision-preview` | ❌ | ✅ | 8K | $0.20 / $2.00 | 视觉 + 短上下文 | +| `moonshot-v1-32k-vision-preview` | ❌ | ✅ | 32K | $1.00 / $3.00 | 视觉 + 中等上下文 | +| `moonshot-v1-128k-vision-preview` | ❌ | ✅ | 128K | $2.00 / $5.00 | 视觉 + 长上下文 | -**Prices**: Per 1M tokens. Cache pricing applies to prompt tokens served from automatic context cache (only Kimi K2.x models support cache). +**价格**：按每 100 万 token 计费。缓存定价适用于从自动上下文缓存（automatic context cache）提供的提示 token（仅 Kimi K2.x 模型支持缓存）。 -> **CRITICAL — Kimi K2.6/K2.5 parameter constraints**: API returns `invalid_request_error` for any deviation: -> - `temperature`: MUST be `1.0` in thinking mode, MUST be `0.6` in non-thinking mode -> - `top_p`: MUST be `0.95` -> - `n`: MUST be `1` -> - `presence_penalty` and `frequency_penalty`: MUST be `0` (not modifiable) +> **重要 — Kimi K2.6/K2.5 参数约束**：API 对任何偏离将返回 `invalid_request_error`： +> - `temperature`：在 thinking 模式下 MUST 为 `1.0`，在非 thinking 模式下 MUST 为 `0.6` +> - `top_p`：MUST 为 `0.95` +> - `n`：MUST 为 `1` +> - `presence_penalty` 与 `frequency_penalty`：MUST 为 `0`（不可修改） > -> Moonshot V1 models use standard OpenAI-compatible parameters with no such constraints. +> Moonshot V1 模型使用标准 OpenAI 兼容参数，无此类约束。 -**Default Agent Configuration**: +**默认 Agent 配置**： -Strategy: prefer `kimi-k2.5` as cost-effective workhorse (36% cheaper input vs `kimi-k2.6`); reserve `kimi-k2.6` for critical reasoning. All `kimi-k2.x` agents are configured with the API-required fixed parameters (temp/top_p/n) and explicit `extra_body.thinking.type`. For thinking-enabled agents, `extra_body.thinking.keep: "all"` is set to preserve historical `reasoning_content` in multi-turn tool call chains (without it Moonshot returns "thinking is enabled but reasoning_content is missing"). +策略：优先选用 `kimi-k2.5` 作为高性价比主力模型（输入成本比 `kimi-k2.6` 低 36%）；将 `kimi-k2.6` 保留给关键推理任务。所有 `kimi-k2.x` agent 均配置 API 要求的固定参数（temp/top_p/n）及显式 `extra_body.thinking.type`。对于启用 thinking 的 agent，`extra_body.thinking.keep: "all"` 设置为在多轮工具调用链中保留历史 `reasoning_content`（若无此设置，Moonshot 将返回 "thinking is enabled but reasoning_content is missing"）。 | Agent Role | Default Model | Thinking | Temperature | Top P | Max Output | | -------------------------------------------- | ------------- | -------- | ----------- | ----- | ---------- | @@ -2215,33 +2219,33 @@ Strategy: prefer `kimi-k2.5` as cost-effective workhorse (36% cheaper input vs ` | Reflector / Searcher / Enricher | `kimi-k2.5` | Disabled | 0.6 | 0.95 | 4096 | | Simple / Simple JSON | `kimi-k2.5` | Disabled | 0.6 | 0.95 | 2048 | -**Key Features**: -- **Ultra-Long Context**: Up to 256K tokens (K2.x) for comprehensive codebase/documentation analysis -- **Native Multimodal**: K2.6/K2.5 support text + image + video input out of the box -- **Hybrid Thinking**: K2.6/K2.5 toggle between thinking and non-thinking via `extra_body.thinking.type` -- **Preserved Thinking** (K2.6): `thinking.keep: "all"` preserves historical `reasoning_content` across turns — required for multi-turn tool call chains -- **Automatic Context Caching**: K2.x models cache repeated prefixes (~17% of miss price for K2.6, ~17% for K2.5) -- **Tool Calling**: Full function-calling support for K2.x and Moonshot V1 -- **Self-Correction**: K2.6 features improved instruction compliance and self-correction -- **Multilingual**: Strong Chinese, English, and multi-language support +**核心特性**： +- **超长上下文（Ultra-Long Context）**：最高 256K token（K2.x），适用于全面的代码库/文档分析 +- **原生多模态（Native Multimodal）**：K2.6/K2.5 开箱即用地支持文本 + 图像 + 视频输入 +- **混合思考（Hybrid Thinking）**：K2.6/K2.5 可通过 `extra_body.thinking.type` 在 thinking 与非 thinking 模式间切换 +- **思考内容保留（Preserved Thinking）**（K2.6）：`thinking.keep: "all"` 在多轮对话中保留历史 `reasoning_content` — 多轮工具调用链所必需 +- **自动上下文缓存（Automatic Context Caching）**：K2.x 模型缓存重复前缀（K2.6 约为未命中价格的 ~17%，K2.5 约为 ~17%） +- **工具调用（Tool Calling）**：K2.x 与 Moonshot V1 全面支持 function-calling +- **自我纠错（Self-Correction）**：K2.6 具备更强的指令遵循与自我纠错能力 +- **多语言（Multilingual）**：强大的中文、英文及多语言支持 -**Multi-turn with thinking + tool calls**: PentAGI's universal reasoning preservation pattern (`TextPartWithReasoning` + `WithPreserveReasoningContent`) automatically ensures `reasoning_content` is sent back in the required TextContent → ToolCall order, satisfying Moonshot's "thinking is enabled but reasoning_content is missing in assistant tool call message" requirement. +**Thinking + 工具调用的多轮对话**：PentAGI 的通用推理保留模式（`TextPartWithReasoning` + `WithPreserveReasoningContent`）自动确保按所需的 TextContent → ToolCall 顺序回传 `reasoning_content`，满足 Moonshot 对 "thinking is enabled but reasoning_content is missing in assistant tool call message" 的要求。 -**LiteLLM Integration**: Set `KIMI_PROVIDER=moonshot` to enable model name prefixing when using default PentAGI configurations with LiteLLM proxy. Leave empty for direct API usage. +**LiteLLM 集成**：将 `KIMI_PROVIDER=moonshot` 设置为在使用默认 PentAGI 配置配合 LiteLLM 代理时启用模型名称前缀。直连 API 使用时留空即可。 -### Qwen Provider Configuration +### Qwen 提供商配置 -PentAGI integrates with Qwen from Alibaba Cloud Model Studio (DashScope), providing powerful multilingual models with reasoning capabilities and context caching support. +PentAGI 集成阿里云百炼（DashScope）的 Qwen，提供具备推理能力与上下文缓存支持的强大多语言模型。 -#### Configuration Variables +#### 配置变量 | Variable | Default Value | Description | | ------------------ | ------------------------------------------------------ | --------------------------------------------------- | -| `QWEN_API_KEY` | | Qwen API key for authentication | -| `QWEN_SERVER_URL` | `https://dashscope-us.aliyuncs.com/compatible-mode/v1` | Qwen API endpoint URL (international) | -| `QWEN_PROVIDER` | | Provider prefix for LiteLLM integration (optional) | +| `QWEN_API_KEY` | | 用于身份验证的 Qwen API 密钥 | +| `QWEN_SERVER_URL` | `https://dashscope-us.aliyuncs.com/compatible-mode/v1` | Qwen API 端点 URL（国际版） | +| `QWEN_PROVIDER` | | LiteLLM 集成的提供商前缀（可选） | -#### Configuration Examples +#### 配置示例 ```bash # Direct API usage (Global/US endpoint) @@ -2258,122 +2262,122 @@ QWEN_SERVER_URL=http://litellm-proxy:4000 QWEN_PROVIDER=dashscope # Adds prefix to model names (dashscope/qwen-plus) for LiteLLM ``` -#### Supported Models +#### 支持的模型 -PentAGI supports 33 Qwen models curated for agent workflows: text reasoning, code generation, and vision-language (browser screenshots). All models are non-snapshot main aliases with tool calling, streaming, thinking modes, and context caching. Models marked with `*` are used in default configuration. +PentAGI 支持 33 款为 agent 工作流精选的 Qwen 模型：文本推理、代码生成及视觉语言（浏览器截图）。所有模型均为非快照主别名，支持工具调用、流式输出、thinking 模式及上下文缓存。标记有 `*` 的模型用于默认配置。 -**Flagship Models (Top-tier Reasoning)** +**旗舰模型（顶级推理）** | Model ID | Thinking | Intl | Global/US | China | Price (Input/Output/Cache) | Use Case | | ---------------------------- | -------- | ---- | --------- | ----- | -------------------------- | ------------------------------------------------------- | -| `qwen3.7-max`* | ✅ | ✅ | ✅ | ✅ | $2.50/$7.50/$0.50 | Next-gen flagship for agent-centric era (generator/refiner/adviser default) | -| `qwen3.6-max-preview` | ✅ | ✅ | ✅ | ✅ | $1.30/$7.80/$0.13 | Preview Max with enhanced vibe coding & front-end skills | -| `qwen3-max` | ✅ | ✅ | ✅ | ✅ | $1.20/$6.00/$0.24 | Previous-gen flagship with agent programming upgrades | -| `qwen-plus` | ✅ | ✅ | ✅ | ✅ | $0.40/$4.00/$0.08 | Qwen3-backbone Plus with switchable thinking modes | +| `qwen3.7-max`* | ✅ | ✅ | ✅ | ✅ | $2.50/$7.50/$0.50 | 面向 agent 时代的新一代旗舰（generator/refiner/adviser 默认） | +| `qwen3.6-max-preview` | ✅ | ✅ | ✅ | ✅ | $1.30/$7.80/$0.13 | 预览版 Max，增强 vibe coding 与前端技能 | +| `qwen3-max` | ✅ | ✅ | ✅ | ✅ | $1.20/$6.00/$0.24 | 上一代旗舰，具备 agent 编程升级 | +| `qwen-plus` | ✅ | ✅ | ✅ | ✅ | $0.40/$4.00/$0.08 | 基于 Qwen3 的 Plus，可切换 thinking 模式 | -**Balanced Plus Models (Mid-tier)** +**均衡 Plus 模型（中档）** | Model ID | Thinking | Intl | Global/US | China | Price (Input/Output/Cache) | Use Case | | ---------------------------- | -------- | ---- | --------- | ----- | -------------------------- | ------------------------------------------------------- | -| `qwen3.6-plus`* | ✅ | ✅ | ✅ | ✅ | $0.50/$3.00/$0.05 | Native VL Plus with agentic coding (primary/assistant/pentester default) | -| `qwen3.5-plus` | ✅ | ✅ | ✅ | ✅ | $0.40/$2.40/$0.04 | Previous-gen native VL with strong multimodal capabilities | +| `qwen3.6-plus`* | ✅ | ✅ | ✅ | ✅ | $0.50/$3.00/$0.05 | 原生 VL Plus，具备 agentic coding（primary/assistant/pentester 默认） | +| `qwen3.5-plus` | ✅ | ✅ | ✅ | ✅ | $0.40/$2.40/$0.04 | 上一代原生 VL，多模态能力强劲 | -**Fast Flash Models (Cost-optimized)** +**快速 Flash 模型（成本优化）** | Model ID | Thinking | Intl | Global/US | China | Price (Input/Output/Cache) | Use Case | | ---------------------------- | -------- | ---- | --------- | ----- | -------------------------- | ------------------------------------------------------- | -| `qwen3.6-flash` | ✅ | ✅ | ✅ | ✅ | $0.25/$1.50/$0.025 | Latest Flash with significant agentic-coding boost | -| `qwen3.5-flash`* | ✅ | ✅ | ✅ | ✅ | $0.10/$0.40/$0.01 | Ultra-fast lightweight (simple/reflector/searcher/enricher default) | -| `qwen-flash` | ✅ | ✅ | ✅ | ✅ | $0.05/$0.40/$0.01 | Qwen3-series Flash with 1M context, tiered pricing | +| `qwen3.6-flash` | ✅ | ✅ | ✅ | ✅ | $0.25/$1.50/$0.025 | 最新 Flash，显著增强 agentic 编码能力 | +| `qwen3.5-flash`* | ✅ | ✅ | ✅ | ✅ | $0.10/$0.40/$0.01 | 超快轻量（simple/reflector/searcher/enricher 默认） | +| `qwen-flash` | ✅ | ✅ | ✅ | ✅ | $0.05/$0.40/$0.01 | Qwen3 系列 Flash，1M 上下文，阶梯定价 | -**Code-Specialized Models** +**代码专用模型** | Model ID | Thinking | Intl | Global/US | China | Price (Input/Output/Cache) | Use Case | | ---------------------------- | -------- | ---- | --------- | ----- | -------------------------- | ------------------------------------------------------- | -| `qwen3-coder-plus`* | ❌ | ✅ | ✅ | ✅ | $1.00/$5.00/$0.20 | Strong coding agent with autonomous programming (coder default) | -| `qwen3-coder-flash`* | ❌ | ✅ | ✅ | ✅ | $0.30/$1.50/$0.06 | Fast code-gen with multi-turn tool stability (installer default) | -| `qwen3-coder-next` | ❌ | ✅ | ✅ | ✅ | $0.30/$1.50/— | Open-source code generation, SOTA at same scale | +| `qwen3-coder-plus`* | ❌ | ✅ | ✅ | ✅ | $1.00/$5.00/$0.20 | 强力编码智能体，支持自主编程（coder 默认） | +| `qwen3-coder-flash`* | ❌ | ✅ | ✅ | ✅ | $0.30/$1.50/$0.06 | 快速代码生成，多轮工具调用稳定（installer 默认） | +| `qwen3-coder-next` | ❌ | ✅ | ✅ | ✅ | $0.30/$1.50/— | 开源代码生成，同规模 SOTA | -**Vision-Language Models (Browser & Screenshot Analysis)** +**视觉语言模型（浏览器与截图分析）** | Model ID | Thinking | Intl | Global/US | China | Price (Input/Output/Cache) | Use Case | | ---------------------------- | -------- | ---- | --------- | ----- | -------------------------- | ------------------------------------------------------- | -| `qwen3-vl-plus` | ✅ | ✅ | ✅ | ✅ | $0.20/$1.60/$0.04 | VL with visual agent capabilities, ultra-long video understanding | -| `qwen3-vl-flash` | ✅ | ✅ | ✅ | ✅ | $0.05/$0.40/$0.01 | Small VL with 2D/3D localization for browser triage | -| `qvq-max` | ✅ | ✅ | ✅ | ✅ | $1.20/$4.80/— | Visual reasoning with chain-of-thought | +| `qwen3-vl-plus` | ✅ | ✅ | ✅ | ✅ | $0.20/$1.60/$0.04 | 具备视觉智能体能力的 VL，超长视频理解 | +| `qwen3-vl-flash` | ✅ | ✅ | ✅ | ✅ | $0.05/$0.40/$0.01 | 小型 VL，2D/3D 定位，用于浏览器分流 | +| `qvq-max` | ✅ | ✅ | ✅ | ✅ | $1.20/$4.80/— | 视觉推理，支持思维链（chain-of-thought） | -**Open-Source Qwen3.6 Series** +**开源 Qwen3.6 系列** | Model ID | Thinking | Intl | Global/US | China | Price (Input/Output/Cache) | Use Case | | ---------------------------- | -------- | ---- | --------- | ----- | -------------------------- | ------------------------------------------------------- | -| `qwen3.6-27b` | ✅ | ✅ | ✅ | ✅ | $0.60/$3.60/— | Native VL on hybrid architecture, on-premises ready | -| `qwen3.6-35b-a3b` | ✅ | ✅ | ✅ | ✅ | $0.25/$1.49/— | Efficient 35B MoE (~3B active) for continuous monitoring | +| `qwen3.6-27b` | ✅ | ✅ | ✅ | ✅ | $0.60/$3.60/— | 混合架构原生 VL，支持本地部署 | +| `qwen3.6-35b-a3b` | ✅ | ✅ | ✅ | ✅ | $0.25/$1.49/— | 高效 35B MoE（约 3B 活跃参数），适合持续监控 | -**Open-Source Qwen3.5 Series** +**开源 Qwen3.5 系列** | Model ID | Thinking | Intl | Global/US | China | Price (Input/Output/Cache) | Use Case | | ---------------------------- | -------- | ---- | --------- | ----- | -------------------------- | ------------------------------------------------------- | -| `qwen3.5-397b-a17b` | ✅ | ✅ | ✅ | ✅ | $0.60/$3.60/— | Largest 397B params (~17B active), exceptional reasoning | -| `qwen3.5-122b-a10b` | ✅ | ✅ | ✅ | ✅ | $0.40/$3.20/— | Large 122B params (~10B active), strong balance | -| `qwen3.5-35b-a3b` | ✅ | ✅ | ✅ | ✅ | $0.25/$2.00/— | Efficient 35B MoE (~3B active), cost-effective | -| `qwen3.5-27b` | ✅ | ✅ | ✅ | ✅ | $0.30/$2.40/— | Medium 27B with hybrid linear attention + sparse MoE | +| `qwen3.5-397b-a17b` | ✅ | ✅ | ✅ | ✅ | $0.60/$3.60/— | 最大 397B 参数（约 17B 活跃），卓越推理能力 | +| `qwen3.5-122b-a10b` | ✅ | ✅ | ✅ | ✅ | $0.40/$3.20/— | 大型 122B 参数（约 10B 活跃），强劲均衡 | +| `qwen3.5-35b-a3b` | ✅ | ✅ | ✅ | ✅ | $0.25/$2.00/— | 高效 35B MoE（约 3B 活跃参数），性价比高 | +| `qwen3.5-27b` | ✅ | ✅ | ✅ | ✅ | $0.30/$2.40/— | 中型 27B，混合线性注意力 + 稀疏 MoE | -**Open-Source Qwen3 Coder Series** +**开源 Qwen3 Coder 系列** | Model ID | Thinking | Intl | Global/US | China | Price (Input/Output/Cache) | Use Case | | ------------------------------------- | -------- | ---- | --------- | ----- | -------------------------- | ------------------------------------------------------- | -| `qwen3-coder-480b-a35b-instruct` | ❌ | ✅ | ✅ | ✅ | $1.50/$7.50/— | Largest open coder MoE (480B/~35B active) | -| `qwen3-coder-30b-a3b-instruct` | ❌ | ✅ | ✅ | ✅ | $0.45/$2.25/— | Efficient 30B MoE (~3B active), repository-scale | +| `qwen3-coder-480b-a35b-instruct` | ❌ | ✅ | ✅ | ✅ | $1.50/$7.50/— | 最大开源 Coder MoE（480B/约 35B 活跃） | +| `qwen3-coder-30b-a3b-instruct` | ❌ | ✅ | ✅ | ✅ | $0.45/$2.25/— | 高效 30B MoE（约 3B 活跃参数），仓库级规模 | -**Open-Source Qwen3 Dense & MoE Series** +**开源 Qwen3 Dense 与 MoE 系列** | Model ID | Thinking | Intl | Global/US | China | Price (Input/Output/Cache) | Use Case | | ------------------------------------- | -------- | ---- | --------- | ----- | -------------------------- | ------------------------------------------------------- | -| `qwen3-next-80b-a3b-thinking` | ✅ | ✅ | ✅ | ✅ | $0.15/$1.20/— | Next-gen 80B MoE (~3B active) thinking-only | -| `qwen3-next-80b-a3b-instruct` | ❌ | ✅ | ✅ | ✅ | $0.15/$1.20/— | Next-gen 80B MoE instruction-following | -| `qwen3-235b-a22b` | ✅ | ✅ | ✅ | ✅ | $0.70/$8.40/— | Dual-mode 235B MoE (~22B active) | -| `qwen3-32b` | ✅ | ✅ | ✅ | ✅ | $0.16/$0.64/— | Versatile 32B dense dual-mode | -| `qwen3-30b-a3b` | ✅ | ✅ | ✅ | ✅ | $0.20/$2.40/— | Efficient 30B MoE (~3B active) | -| `qwen3-14b` | ✅ | ✅ | ✅ | ✅ | $0.35/$4.20/— | Medium 14B dense performance-cost balance | -| `qwen3-8b` | ✅ | ✅ | ✅ | ✅ | $0.18/$2.10/— | Compact 8B dense efficiency | -| `qwen3-4b` | ✅ | ✅ | ✅ | ✅ | $0.11/$1.26/— | Lightweight 4B dense for simple tasks | -| `qwen3-1.7b` | ✅ | ✅ | ✅ | ✅ | $0.11/$1.26/— | Ultra-compact 1.7B basic checks | -| `qwen3-0.6b` | ✅ | ✅ | ✅ | ✅ | $0.11/$1.26/— | Smallest 0.6B for edge monitoring | +| `qwen3-next-80b-a3b-thinking` | ✅ | ✅ | ✅ | ✅ | $0.15/$1.20/— | 下一代 80B MoE（约 3B 活跃参数），仅思考模式 | +| `qwen3-next-80b-a3b-instruct` | ❌ | ✅ | ✅ | ✅ | $0.15/$1.20/— | 下一代 80B MoE，指令遵循 | +| `qwen3-235b-a22b` | ✅ | ✅ | ✅ | ✅ | $0.70/$8.40/— | 双模式 235B MoE（约 22B 活跃） | +| `qwen3-32b` | ✅ | ✅ | ✅ | ✅ | $0.16/$0.64/— | 多功能 32B dense 双模式 | +| `qwen3-30b-a3b` | ✅ | ✅ | ✅ | ✅ | $0.20/$2.40/— | 高效 30B MoE（约 3B 活跃参数） | +| `qwen3-14b` | ✅ | ✅ | ✅ | ✅ | $0.35/$4.20/— | 中型 14B dense，性能与成本均衡 | +| `qwen3-8b` | ✅ | ✅ | ✅ | ✅ | $0.18/$2.10/— | 紧凑 8B dense，高效 | +| `qwen3-4b` | ✅ | ✅ | ✅ | ✅ | $0.11/$1.26/— | 轻量 4B dense，适合简单任务 | +| `qwen3-1.7b` | ✅ | ✅ | ✅ | ✅ | $0.11/$1.26/— | 超紧凑 1.7B，基础检查 | +| `qwen3-0.6b` | ✅ | ✅ | ✅ | ✅ | $0.11/$1.26/— | 最小 0.6B，边缘监控 | -**Prices**: Per 1M tokens. Cache pricing reflects implicit cache hit (when available); MoE/dense open-source models do not expose cache pricing. Tiered models (Max/Plus) show lowest-tier pricing (typically ≤32k or ≤256k input); larger contexts incur higher rates per Alibaba Cloud pricing. +**价格**：按每 100 万 token 计费。缓存价格反映隐式缓存命中（如可用）；MoE/dense 开源模型不提供缓存定价。阶梯模型（Max/Plus）显示最低档价格（通常 ≤32k 或 ≤256k 输入）；更大上下文按阿里云定价收取更高费率。 -**Region Availability**: -- **Intl** (International): Singapore region (`dashscope-intl.aliyuncs.com`) -- **Global/US**: US Virginia region (`dashscope-us.aliyuncs.com`) -- **China**: Chinese Mainland Beijing region (`dashscope.aliyuncs.com`) +**区域可用性**： +- **Intl**（国际）：新加坡区域（`dashscope-intl.aliyuncs.com`） +- **Global/US**：美国弗吉尼亚区域（`dashscope-us.aliyuncs.com`） +- **China**：中国大陆北京区域（`dashscope.aliyuncs.com`） -**Default Agent Configuration**: +**默认智能体配置**： | Agent Role | Default Model | Tier | | ------------------------------------------------ | -------------------- | --------- | -| Generator / Refiner / Adviser (planning, mentor) | `qwen3.7-max` | Flagship | +| Generator / Refiner / Adviser（规划、导师） | `qwen3.7-max` | Flagship | | Primary / Assistant / Pentester | `qwen3.6-plus` | Balanced | -| Coder (exploit development) | `qwen3-coder-plus` | Code+ | -| Installer (env setup) | `qwen3-coder-flash` | Code Fast | +| Coder（漏洞利用开发） | `qwen3-coder-plus` | Code+ | +| Installer（环境配置） | `qwen3-coder-flash` | Code Fast | | Simple / Reflector / Searcher / Enricher | `qwen3.5-flash` | Fast | -**Key Features**: -- **Agent-Centric Design**: Qwen3.7-Max is purpose-built for long-horizon autonomous execution and tool invocation -- **Automatic Context Caching**: 30-50% cost reduction on repeated context with implicit cache -- **Extended Thinking**: Chain-of-thought reasoning for complex security analysis (Qwen3.7/3.6/3.5/3-Max, QVQ-Max) -- **Code Specialization**: Qwen3-Coder series with multi-turn tool interaction and repository-level understanding -- **Vision-Language**: Qwen3-VL series for browser screenshot triage, 2D/3D localization, OCR-level analysis -- **Tool Calling**: Seamless integration with 20+ pentesting tools via function calling -- **Streaming**: Real-time response streaming for interactive workflows -- **Multilingual**: Strong Chinese, English, and multi-language support -- **Open-Source Variants**: Dense and MoE models from 0.6B to 480B for on-premises/air-gapped deployments +**核心特性**： +- **以 Agent 为中心的设计**：Qwen3.7-Max 专为长周期自主执行与工具调用而打造 +- **自动上下文缓存（Automatic Context Caching）**：通过隐式缓存，在重复上下文场景下可降低 30-50% 成本 +- **扩展思考（Extended Thinking）**：面向复杂安全分析的链式思维推理（Qwen3.7/3.6/3.5/3-Max、QVQ-Max） +- **代码专精**：Qwen3-Coder 系列支持多轮工具交互与仓库级理解 +- **视觉-语言（Vision-Language）**：Qwen3-VL 系列适用于浏览器截图分诊、2D/3D 定位、OCR 级分析 +- **工具调用（Tool Calling）**：通过 function calling 与 20+ 款渗透测试工具无缝集成 +- **流式输出（Streaming）**：为交互式工作流提供实时响应流 +- **多语言（Multilingual）**：对中文、英文及多种语言有良好支持 +- **开源变体（Open-Source Variants）**：提供 0.6B 至 480B 的 Dense 与 MoE 模型，适用于本地部署/气隙（air-gapped）环境 -**LiteLLM Integration**: Set `QWEN_PROVIDER=dashscope` to enable model name prefixing when using default PentAGI configurations with LiteLLM proxy. Leave empty for direct API usage. +**LiteLLM 集成**：将 `QWEN_PROVIDER=dashscope` 设置为在使用默认 PentAGI 配置配合 LiteLLM 代理时启用模型名称前缀。若直接调用 API，请留空。 -#### Alternative Integrations +#### 其他集成方式 -DashScope is fully OpenAI-compatible, so Qwen can also power two other PentAGI subsystems through the standard OpenAI client. +DashScope 完全兼容 OpenAI，因此 Qwen 也可通过标准 OpenAI 客户端为 PentAGI 的另外两个子系统提供能力。 -**As embedding provider** (`text-embedding-v4`, see [Alibaba Cloud Model Studio pricing](https://modelstudio.console.alibabacloud.com/ap-southeast-1?tab=doc#/doc/?type=model&url=prices)): +**作为嵌入（embedding）提供方**（`text-embedding-v4`，参见 [Alibaba Cloud Model Studio 定价](https://modelstudio.console.alibabacloud.com/ap-southeast-1?tab=doc#/doc/?type=model&url=prices)): ```bash EMBEDDING_PROVIDER=openai @@ -2385,47 +2389,47 @@ EMBEDDING_BATCH_SIZE= # optional, default applies EMBEDDING_STRIP_NEW_LINES= # optional, default applies ``` -> Note: the Global/US DashScope endpoint (`dashscope-us.aliyuncs.com`) does **not** expose embedding APIs — use the International or China endpoints for `text-embedding-v4`. +> 注意：Global/US DashScope 端点（`dashscope-us.aliyuncs.com`）**不**提供 embedding API —— 请使用 International 或 China 端点以配置 `text-embedding-v4`。 -**As OpenAI-typed custom LLM provider**: instead of the dedicated `QWEN_*` variables, you can wire any Qwen chat model through PentAGI's custom OpenAI-compatible provider by pointing `OPENAI_SERVER_URL` (or a custom provider entry) to the DashScope `/compatible-mode/v1` endpoint and selecting the desired Qwen model name. Useful when you already manage all model traffic through a single OpenAI-shaped client (e.g. shared with LiteLLM/OneAPI proxies). +**作为 OpenAI 类型的自定义 LLM 提供方**：无需使用专用的 `QWEN_*` 变量，可将任意 Qwen 对话模型通过 PentAGI 的自定义 OpenAI 兼容提供方接入：将 `OPENAI_SERVER_URL`（或自定义 provider 条目）指向 DashScope 的 `/compatible-mode/v1` 端点，并选择所需的 Qwen 模型名称。适用于你已通过单一 OpenAI 形态客户端统一管理全部模型流量（例如与 LiteLLM/OneAPI 代理共用）的场景。 -## Advanced Setup +## 高级配置 -### Langfuse Integration +### Langfuse 集成 -Langfuse provides advanced capabilities for monitoring and analyzing AI agent operations. +Langfuse 为监控与分析 AI Agent 运行提供高级能力。 -1. Configure Langfuse environment variables in existing `.env` file. +1. 在现有的 `.env` 文件中配置 Langfuse 环境变量。
- Langfuse valuable environment variables + Langfuse 重要环境变量 -### Database Credentials -- `LANGFUSE_POSTGRES_USER` and `LANGFUSE_POSTGRES_PASSWORD` - Langfuse PostgreSQL credentials -- `LANGFUSE_CLICKHOUSE_USER` and `LANGFUSE_CLICKHOUSE_PASSWORD` - ClickHouse credentials -- `LANGFUSE_REDIS_AUTH` - Redis password +### 数据库凭据 +- `LANGFUSE_POSTGRES_USER` 与 `LANGFUSE_POSTGRES_PASSWORD` - Langfuse PostgreSQL 凭据 +- `LANGFUSE_CLICKHOUSE_USER` 与 `LANGFUSE_CLICKHOUSE_PASSWORD` - ClickHouse 凭据 +- `LANGFUSE_REDIS_AUTH` - Redis 密码 -### Encryption and Security Keys -- `LANGFUSE_SALT` - Salt for hashing in Langfuse Web UI -- `LANGFUSE_ENCRYPTION_KEY` - Encryption key (32 bytes in hex) -- `LANGFUSE_NEXTAUTH_SECRET` - Secret key for NextAuth +### 加密与安全密钥 +- `LANGFUSE_SALT` - Langfuse Web UI 中用于哈希的盐值 +- `LANGFUSE_ENCRYPTION_KEY` - 加密密钥（32 字节十六进制） +- `LANGFUSE_NEXTAUTH_SECRET` - NextAuth 密钥 -### Admin Credentials -- `LANGFUSE_INIT_USER_EMAIL` - Admin email -- `LANGFUSE_INIT_USER_PASSWORD` - Admin password -- `LANGFUSE_INIT_USER_NAME` - Admin username +### 管理员凭据 +- `LANGFUSE_INIT_USER_EMAIL` - 管理员邮箱 +- `LANGFUSE_INIT_USER_PASSWORD` - 管理员密码 +- `LANGFUSE_INIT_USER_NAME` - 管理员用户名 -### API Keys and Tokens -- `LANGFUSE_INIT_PROJECT_PUBLIC_KEY` - Project public key (used from PentAGI side too) -- `LANGFUSE_INIT_PROJECT_SECRET_KEY` - Project secret key (used from PentAGI side too) +### API 密钥与令牌 +- `LANGFUSE_INIT_PROJECT_PUBLIC_KEY` - 项目公钥（PentAGI 侧也会使用） +- `LANGFUSE_INIT_PROJECT_SECRET_KEY` - 项目私钥（PentAGI 侧也会使用） -### S3 Storage -- `LANGFUSE_S3_ACCESS_KEY_ID` - S3 access key ID -- `LANGFUSE_S3_SECRET_ACCESS_KEY` - S3 secret access key +### S3 存储 +- `LANGFUSE_S3_ACCESS_KEY_ID` - S3 访问密钥 ID +- `LANGFUSE_S3_SECRET_ACCESS_KEY` - S3 秘密访问密钥
-2. Enable integration with Langfuse for PentAGI service in `.env` file. +2. 在 `.env` 文件中为 PentAGI 服务启用 Langfuse 集成。 ```bash LANGFUSE_BASE_URL=http://langfuse-web:3000 @@ -2434,47 +2438,47 @@ LANGFUSE_PUBLIC_KEY= # default: value from ${LANGFUSE_INIT_PROJECT_PUBLIC_KEY} LANGFUSE_SECRET_KEY= # default: value from ${LANGFUSE_INIT_PROJECT_SECRET_KEY} ``` -3. Run the Langfuse stack: +3. 启动 Langfuse 栈： ```bash curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/master/docker-compose-langfuse.yml docker compose -f docker-compose.yml -f docker-compose-langfuse.yml up -d ``` -Visit [localhost:4000](http://localhost:4000) to access Langfuse Web UI with credentials from `.env` file: +访问 [localhost:4000](http://localhost:4000) 以使用 `.env` 文件中的凭据登录 Langfuse Web UI： -- `LANGFUSE_INIT_USER_EMAIL` - Admin email -- `LANGFUSE_INIT_USER_PASSWORD` - Admin password +- `LANGFUSE_INIT_USER_EMAIL` - 管理员邮箱 +- `LANGFUSE_INIT_USER_PASSWORD` - 管理员密码 -### Monitoring and Observability +### 监控与可观测性 -For detailed system operation tracking, integration with monitoring tools is available. +如需详细跟踪系统运行，可集成监控工具。 -1. Enable integration with OpenTelemetry and all observability services for PentAGI in `.env` file. +1. 在 `.env` 文件中为 PentAGI 启用 OpenTelemetry 及全部可观测性服务集成。 ```bash OTEL_HOST=otelcol:8148 ``` -2. Run the observability stack: +2. 启动可观测性栈： ```bash curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/master/docker-compose-observability.yml docker compose -f docker-compose.yml -f docker-compose-observability.yml up -d ``` -Visit [localhost:3000](http://localhost:3000) to access Grafana Web UI. +访问 [localhost:3000](http://localhost:3000) 以打开 Grafana Web UI。 > [!NOTE] -> If you want to use Observability stack with Langfuse, you need to enable integration in `.env` file to set `LANGFUSE_OTEL_EXPORTER_OTLP_ENDPOINT` to `http://otelcol:4318`. +> 若要将可观测性栈与 Langfuse 一起使用，需在 `.env` 文件中启用集成，将 `LANGFUSE_OTEL_EXPORTER_OTLP_ENDPOINT` 设置为 `http://otelcol:4318`。 > -> To run all available stacks together (Langfuse, Graphiti, and Observability): +> 要同时运行所有可用栈（Langfuse、Graphiti 与 Observability）： > > ```bash > docker compose -f docker-compose.yml -f docker-compose-langfuse.yml -f docker-compose-graphiti.yml -f docker-compose-observability.yml up -d > ``` > -> You can also register aliases for these commands in your shell to run it faster: +> 你也可以在 shell 中为这些命令注册别名以便更快执行： > > ```bash > alias pentagi="docker compose -f docker-compose.yml -f docker-compose-langfuse.yml -f docker-compose-graphiti.yml -f docker-compose-observability.yml" @@ -2482,27 +2486,27 @@ Visit [localhost:3000](http://localhost:3000) to access Grafana Web UI. > alias pentagi-down="docker compose -f docker-compose.yml -f docker-compose-langfuse.yml -f docker-compose-graphiti.yml -f docker-compose-observability.yml down" > ``` -### Knowledge Graph Integration (Graphiti) +### 知识图谱集成（Graphiti） > [!IMPORTANT] -> The Graphiti integration is currently a **beta** feature and has notable provider limitations. See [Current Limitations](#current-limitations) below before enabling it in production. +> Graphiti 集成目前为 **beta** 功能，存在明显的提供方限制。在生产环境启用前，请参阅下文 [当前限制](#current-limitations)。 -PentAGI integrates with [Graphiti](https://github.com/vxcontrol/pentagi-graphiti), a temporal knowledge graph system powered by Neo4j, to provide advanced semantic understanding and relationship tracking for AI agent operations. The vxcontrol fork provides custom entity and edge types that are specific to pentesting purposes. +PentAGI 与 [Graphiti](https://github.com/vxcontrol/pentagi-graphiti), 集成 —— 这是一个由 Neo4j 驱动的时序知识图谱系统，可为 AI Agent 运行提供高级语义理解与关系追踪。vxcontrol 分支提供了针对渗透测试场景的自定义实体与边类型。 -#### What is Graphiti? +#### 什么是 Graphiti？ -Graphiti automatically extracts and stores structured knowledge from agent interactions, building a graph of entities, relationships, and temporal context. This enables: +Graphiti 会自动从 Agent 交互中提取并存储结构化知识，构建实体、关系与时序上下文的图谱。由此可实现： -- **Semantic Memory**: Store and recall relationships between tools, targets, vulnerabilities, and techniques -- **Contextual Understanding**: Track how different pentesting actions relate to each other over time -- **Knowledge Reuse**: Learn from past penetration tests and apply insights to new assessments -- **Advanced Querying**: Search for complex patterns like "What tools were effective against similar targets?" +- **语义记忆（Semantic Memory）**：存储并回忆工具、目标、漏洞与技术之间的关联 +- **上下文理解（Contextual Understanding）**：追踪不同渗透测试操作如何随时间相互关联 +- **知识复用（Knowledge Reuse）**：从过往渗透测试中学习，并将洞察应用于新评估 +- **高级查询（Advanced Querying）**：搜索复杂模式，例如「哪些工具对类似目标有效？」 -#### Enabling Graphiti +#### 启用 Graphiti -The Graphiti knowledge graph is **optional** and disabled by default. To enable it: +Graphiti 知识图谱为**可选**功能，默认关闭。启用步骤： -1. Configure Graphiti environment variables in `.env` file: +1. 在 `.env` 文件中配置 Graphiti 环境变量： ```bash ## Graphiti knowledge graph settings @@ -2521,7 +2525,7 @@ NEO4J_URI=bolt://neo4j:7687 OPEN_AI_KEY=your_openai_api_key ``` -2. Run the Graphiti stack along with the main PentAGI services: +2. 与 PentAGI 主服务一并启动 Graphiti 栈： ```bash # Download the Graphiti compose file if needed @@ -2531,7 +2535,7 @@ curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/master/docker-compos docker compose -f docker-compose.yml -f docker-compose-graphiti.yml up -d ``` -3. Verify Graphiti is running: +3. 验证 Graphiti 是否正在运行： ```bash # Check service health @@ -2548,48 +2552,48 @@ docker compose -f docker-compose.yml -f docker-compose-graphiti.yml logs -f grap ``` > [!NOTE] -> The Graphiti service is defined in `docker-compose-graphiti.yml` as a separate stack. You must run both compose files together to enable the knowledge graph functionality. The pre-built Docker image `vxcontrol/graphiti:latest` is used by default. +> Graphiti 服务在 `docker-compose-graphiti.yml` 中定义为独立堆栈。你必须同时运行这两个 compose 文件才能启用知识图谱功能。默认使用预构建的 Docker 镜像 `vxcontrol/graphiti:latest`。 -#### What Gets Stored +#### 存储内容 -When enabled, PentAGI automatically captures: +启用后，PentAGI 会自动捕获： -- **Agent Responses**: All agent reasoning, analysis, and decisions -- **Tool Executions**: Commands executed, tools used, and their results -- **Context Information**: Flow, task, and subtask hierarchy +- **Agent 响应（Agent Responses）**：所有 agent 的推理、分析与决策 +- **工具执行（Tool Executions）**：已执行的命令、使用的工具及其结果 +- **上下文信息（Context Information）**：Flow、任务与子任务的层级结构 -#### Current Limitations +#### 当前限制 -The Graphiti integration is currently a beta feature. Operators should plan around the following constraints before enabling it in production: +Graphiti 集成目前为 beta 功能。在生产环境中启用前，运维人员应针对以下约束做好规划： -- **OpenAI-compatible LLM only.** The bundled `vxcontrol/graphiti` image authenticates against a single OpenAI-compatible endpoint configured through PentAGI's `.env` variables `OPEN_AI_KEY` and `OPEN_AI_SERVER_URL` (default `https://api.openai.com/v1`). `docker-compose-graphiti.yml` maps these into the container as `OPENAI_API_KEY` and `OPENAI_BASE_URL`, so operators do not set the container variables directly. Provider credentials configured elsewhere in PentAGI for Anthropic, Google AI (Gemini), AWS Bedrock, DeepSeek, GLM, Kimi, or Qwen are **not** used by Graphiti for entity extraction. If your deployment cannot reach an OpenAI-compatible endpoint, leave `GRAPHITI_ENABLED=false`. -- **Single fixed model per deployment.** Graphiti uses one model name (`GRAPHITI_MODEL_NAME`, default `gpt-5-mini`) for all extractions. The model cannot be selected per agent or per flow. -- **Independent billing.** Even when a flow runs against a non-OpenAI provider, Graphiti still incurs cost on the configured OpenAI-compatible endpoint. -- **No in-app graph explorer yet.** Browsing the captured graph relies on the Neo4j Browser at `http://localhost:7474` and the Graphiti Swagger UI at `http://localhost:8000/docs`. There is no PentAGI UI surface for the graph today. +- **仅支持 OpenAI 兼容 LLM。** 捆绑的 `vxcontrol/graphiti` 镜像针对通过 PentAGI 的 `.env` 变量 `OPEN_AI_KEY` 与 `OPEN_AI_SERVER_URL`（默认 `https://api.openai.com/v1`）配置的单一 OpenAI 兼容端点进行认证。`docker-compose-graphiti.yml` 会将其映射到容器内的 `OPENAI_API_KEY` 与 `OPENAI_BASE_URL`，因此运维人员无需直接设置容器变量。PentAGI 中在其他位置为 Anthropic、Google AI（Gemini）、AWS Bedrock、DeepSeek、GLM、Kimi 或 Qwen 配置的提供商凭据**不会**被 Graphiti 用于实体抽取。若你的部署无法访问 OpenAI 兼容端点，请保持 `GRAPHITI_ENABLED=false`。 +- **每个部署固定单一模型。** Graphiti 对所有抽取使用同一模型名称（`GRAPHITI_MODEL_NAME`，默认 `gpt-5-mini`）。无法按 agent 或 flow 选择模型。 +- **独立计费。** 即使 flow 使用非 OpenAI 提供商运行，Graphiti 仍会在所配置的 OpenAI 兼容端点上产生费用。 +- **尚无应用内图谱浏览器。** 浏览已捕获的图谱需依赖 `http://localhost:7474` 上的 Neo4j Browser 与 `http://localhost:8000/docs` 上的 Graphiti Swagger UI。目前 PentAGI 没有面向图谱的 UI 界面。 -When `GRAPHITI_ENABLED=false`, PentAGI continues to operate with its primary memory and vector store; only the additional knowledge graph features are skipped. +当 `GRAPHITI_ENABLED=false` 时，PentAGI 会继续使用其主内存与向量存储运行；仅跳过额外的知识图谱功能。 -### GitHub and Google OAuth Integration +### GitHub 与 Google OAuth 集成 -OAuth integration with GitHub and Google allows users to authenticate using their existing accounts on these platforms. This provides several benefits: +与 GitHub 和 Google 的 OAuth 集成允许用户使用这些平台上的现有账户进行身份验证。这带来多项好处： -- Simplified login process without need to create separate credentials -- Enhanced security through trusted identity providers -- Access to user profile information from GitHub/Google accounts -- Seamless integration with existing development workflows +- 简化登录流程，无需创建独立凭据 +- 通过可信身份提供商增强安全性 +- 可访问 GitHub/Google 账户中的用户资料信息 +- 与现有开发工作流无缝集成 -PentAGI uses `PUBLIC_URL` as the public origin/base URL for OAuth redirects. In the default deployment, both GitHub and Google callbacks are handled by: +PentAGI 使用 `PUBLIC_URL` 作为 OAuth 重定向的公开源站/基础 URL。在默认部署中，GitHub 与 Google 回调均由以下端点处理： ```text ${PUBLIC_URL}/api/v1/auth/login-callback ``` -For GitHub OAuth: +GitHub OAuth： -1. Create a new OAuth App in your GitHub account. -2. Set **Homepage URL** to your `PUBLIC_URL`. -3. Set **Authorization callback URL** to `${PUBLIC_URL}/api/v1/auth/login-callback`. -4. Add the client credentials to your `.env` file: +1. 在你的 GitHub 账户中创建新的 OAuth App。 +2. 将 **Homepage URL** 设置为你的 `PUBLIC_URL`。 +3. 将 **Authorization callback URL** 设置为 `${PUBLIC_URL}/api/v1/auth/login-callback`。 +4. 将客户端凭据添加到你的 `.env` 文件： ```bash PUBLIC_URL=https://pentagi.example.com @@ -2597,11 +2601,11 @@ OAUTH_GITHUB_CLIENT_ID=your_github_client_id OAUTH_GITHUB_CLIENT_SECRET=your_github_client_secret ``` -For Google OAuth: +Google OAuth： -1. Create OAuth credentials in your Google Cloud project. -2. Use the same callback endpoint: `${PUBLIC_URL}/api/v1/auth/login-callback`. -3. Add the client credentials to your `.env` file: +1. 在你的 Google Cloud 项目中创建 OAuth 凭据。 +2. 使用相同的回调端点：`${PUBLIC_URL}/api/v1/auth/login-callback`。 +3. 将客户端凭据添加到你的 `.env` 文件： ```bash PUBLIC_URL=https://pentagi.example.com @@ -2609,27 +2613,27 @@ OAUTH_GOOGLE_CLIENT_ID=your_google_client_id OAUTH_GOOGLE_CLIENT_SECRET=your_google_client_secret ``` -Make sure `PUBLIC_URL` matches the externally accessible HTTPS address of your PentAGI instance and does not include the callback path itself. If the URL configured in the OAuth provider does not exactly match the callback generated by PentAGI, the provider will reject the login attempt with a redirect URI mismatch error. +请确保 `PUBLIC_URL` 与 PentAGI 实例对外可访问的 HTTPS 地址一致，且本身不包含回调路径。若在 OAuth 提供商处配置的 URL 与 PentAGI 生成的回调不完全匹配，提供商将因 redirect URI 不匹配而拒绝登录尝试。 -### Docker Image Configuration +### Docker 镜像配置 -PentAGI allows you to configure Docker image selection for executing various tasks. The system automatically chooses the most appropriate image based on the task type, but you can constrain this selection by specifying your preferred images: +PentAGI 允许你配置用于执行各类任务的 Docker 镜像选择。系统会根据任务类型自动选择最合适的镜像，但你可以通过指定首选镜像来约束这一选择： | Variable | Default | Description | | ---------------------------------- | ---------------------- | ----------------------------------------------------------- | -| `PENTAGI_IMAGE` | `vxcontrol/pentagi:latest` | Docker image used for the main PentAGI application service | -| `DOCKER_DEFAULT_IMAGE` | `debian:latest` | Default Docker image for general tasks and ambiguous cases | -| `DOCKER_DEFAULT_IMAGE_FOR_PENTEST` | `vxcontrol/kali-linux` | Default Docker image for security/penetration testing tasks | +| `PENTAGI_IMAGE` | `vxcontrol/pentagi:latest` | 主 PentAGI 应用服务使用的 Docker 镜像 | +| `DOCKER_DEFAULT_IMAGE` | `debian:latest` | 一般任务与模糊场景的默认 Docker 镜像 | +| `DOCKER_DEFAULT_IMAGE_FOR_PENTEST` | `vxcontrol/kali-linux` | 安全/渗透测试任务的默认 Docker 镜像 | -`PENTAGI_IMAGE` changes the image used by the main `pentagi` service in `docker-compose.yml`. The `DOCKER_DEFAULT_IMAGE` and `DOCKER_DEFAULT_IMAGE_FOR_PENTEST` variables only affect automatic worker image selection for task execution inside PentAGI. They do not rewrite the rest of the Compose stack, so services such as `pgvector`, `scraper`, and the optional `graphiti` stack still use the image references defined in the compose files. +`PENTAGI_IMAGE` 会更改 `docker-compose.yml` 中主 `pentagi` 服务所使用的镜像。`DOCKER_DEFAULT_IMAGE` 与 `DOCKER_DEFAULT_IMAGE_FOR_PENTEST` 变量仅影响 PentAGI 内部任务执行时的自动 worker 镜像选择。它们不会改写 Compose 堆栈的其余部分，因此 `pgvector`、`scraper` 以及可选的 `graphiti` 堆栈等服务仍使用 compose 文件中定义的镜像引用。 -When `DOCKER_DEFAULT_IMAGE` and `DOCKER_DEFAULT_IMAGE_FOR_PENTEST` are set, AI agents will be limited to the image choices you specify. This is particularly useful for: +当设置 `DOCKER_DEFAULT_IMAGE` 与 `DOCKER_DEFAULT_IMAGE_FOR_PENTEST` 时，AI agent 将仅限于你指定的镜像选择。这在以下场景尤其有用： -- **Security Enforcement**: Restricting usage to only verified and trusted images -- **Environment Standardization**: Using corporate or customized images across all operations -- **Performance Optimization**: Utilizing pre-built images with necessary tools already installed +- **安全强制（Security Enforcement）**：限制仅使用已验证且受信任的镜像 +- **环境标准化（Environment Standardization）**：在所有操作中使用企业或定制镜像 +- **性能优化（Performance Optimization）**：使用已预装必要工具的镜像 -Configuration examples: +配置示例： ```bash # Using a custom PentAGI application image @@ -2643,22 +2647,22 @@ DOCKER_DEFAULT_IMAGE_FOR_PENTEST=mycompany/pentest-tools:v2.0 ``` > [!NOTE] -> If a user explicitly specifies a particular Docker image in their task, the system will try to use that exact image, ignoring these settings. These variables only affect the system's automatic image selection process. +> 若用户在任务中显式指定了特定 Docker 镜像，系统将尝试使用该确切镜像，忽略这些设置。这些变量仅影响系统的自动镜像选择流程。 -For an advanced OpenVAS/GVM experiment that uses a custom pentest image, see [OpenVAS via a Custom Pentest Image](examples/guides/openvas-custom-image.md). +有关使用自定义渗透测试镜像进行高级 OpenVAS/GVM 实验，请参阅 [OpenVAS via a Custom Pentest Image](examples/guides/openvas-custom-image.md)。 -#### Restricted Networks, Docker Mirrors, and Proxies +#### 受限网络、Docker 镜像源与代理 -If your environment cannot reach Docker Hub (`docker.io`) directly, changing PentAGI environment variables is usually not enough to fix image download failures. PentAGI still relies on Docker's own registry access for Compose-managed services, and the installer network checks also validate Docker Hub reachability. +若你的环境无法直接访问 Docker Hub（`docker.io`），仅修改 PentAGI 环境变量通常不足以解决镜像下载失败。PentAGI 仍依赖 Docker 自身的 registry 访问来管理 Compose 服务，安装程序的网络检查也会验证 Docker Hub 可达性。 -For restricted networks: +对于受限网络： -1. Confirm that the host can resolve and reach `docker.io`. -2. If your environment requires an outbound proxy for PentAGI or installer HTTP traffic, set the `PROXY_URL` environment variable. To route Docker image pulls through a proxy, configure the Docker daemon or Docker Desktop proxy separately — Docker does not use PentAGI's `PROXY_URL` for registry access. -3. If Docker Hub is blocked or heavily rate-limited, configure an organization-approved registry mirror or registry proxy before running the installer or `docker compose up`. -4. Restart Docker after changing the daemon configuration, then rerun the installer checks or Compose startup. +1. 确认主机能够解析并访问 `docker.io`。 +2. 若环境需要出站代理以访问 PentAGI 或安装程序的 HTTP 流量，请设置 `PROXY_URL` 环境变量。若要通过代理拉取 Docker 镜像，请单独配置 Docker 守护进程或 Docker Desktop 代理——Docker 不会使用 PentAGI 的 `PROXY_URL` 进行 registry 访问。 +3. 若 Docker Hub 被封锁或严重限流，请在运行安装程序或 `docker compose up` 之前配置组织批准的 registry 镜像或 registry 代理。 +4. 修改守护进程配置后重启 Docker，然后重新运行安装程序检查或 Compose 启动。 -Example Docker daemon mirror configuration: +Docker 守护进程镜像源配置示例： ```json { @@ -2666,13 +2670,13 @@ Example Docker daemon mirror configuration: } ``` -On Linux, this is typically configured in `/etc/docker/daemon.json`. On Docker Desktop, use the equivalent Docker Engine or proxy settings. A Docker Hub mirror covers Docker Hub-hosted images such as `vxcontrol/*`, but the main Compose stack already includes `quay.io/prometheuscommunity/postgres-exporter`, and the optional observability stack includes `gcr.io/cadvisor/cadvisor`. Those registries still need direct access or individually approved proxy/mirror paths. +在 Linux 上，通常可在 `/etc/docker/daemon.json` 中进行配置。在 Docker Desktop 上，请使用等效的 Docker Engine 或代理设置。Docker Hub 镜像可覆盖 Docker Hub 托管的镜像（例如 `vxcontrol/*`），但主 Compose 栈已包含 `quay.io/prometheuscommunity/postgres-exporter`，可选的可观测性栈则包含 `gcr.io/cadvisor/cadvisor`。这些 registry 仍需要直连访问，或单独获批的代理/镜像路径。 -See the official Docker documentation for [registry mirrors](https://docs.docker.com/docker-hub/image-library/mirror/) and [daemon proxy configuration](https://docs.docker.com/engine/daemon/proxy/). +请参阅官方 Docker 文档：[registry mirrors](https://docs.docker.com/docker-hub/image-library/mirror/) 和 [daemon proxy configuration](https://docs.docker.com/engine/daemon/proxy/). -## Development +## 开发 -### Development Requirements +### 开发环境要求 - golang - nodejs @@ -2680,97 +2684,97 @@ See the official Docker documentation for [registry mirrors](https://docs.docker - postgres - commitlint -### Environment Setup +### 环境配置 -#### Backend Setup +#### 后端配置 -Run once `cd backend && go mod download` to install needed packages. +运行一次 `cd backend && go mod download` 以安装所需软件包。 -For generating swagger files have to run +生成 swagger 文件需要运行 ```bash swag init -g ../../pkg/server/router.go -o pkg/server/docs/ --parseDependency --parseInternal --parseDepth 2 -d cmd/pentagi ``` -before installing `swag` package via +然后通过以下方式安装 `swag` 软件包 ```bash go install github.com/swaggo/swag/cmd/swag@v1.8.7 ``` -For generating graphql resolver files have to run +生成 graphql resolver 文件需要运行 ```bash go run github.com/99designs/gqlgen --config ./gqlgen/gqlgen.yml ``` -after that you can see the generated files in `pkg/graph` folder. +之后可在 `pkg/graph` 文件夹中查看生成的文件。 -For generating ORM methods (database package) from sqlc configuration +根据 sqlc 配置生成 ORM 方法（database 包） ```bash docker run --rm -v $(pwd):/src -w /src --network pentagi-network -e DATABASE_URL="{URL}" sqlc/sqlc:1.27.0 generate -f sqlc/sqlc.yml ``` -For generating Langfuse SDK from OpenAPI specification +根据 OpenAPI 规范生成 Langfuse SDK ```bash fern generate --local ``` -and to install fern-cli +并安装 fern-cli ```bash pnpm add -g fern-api ``` -#### Testing +#### 测试 -For running tests `cd backend && go test -v ./...` +运行测试：`cd backend && go test -v ./...` -#### Frontend Setup +#### 前端配置 -Run once `cd frontend && pnpm install` to install needed packages. +运行一次 `cd frontend && pnpm install` 以安装所需软件包。 -For generating graphql files have to run `pnpm run graphql:generate` which using `graphql-codegen.ts` file. +生成 graphql 文件需要运行 `pnpm run graphql:generate`，它使用 `graphql-codegen.ts` 文件。 -Be sure that you have `graphql-codegen` installed globally: +请确保已全局安装 `graphql-codegen`： ```bash pnpm add -g graphql-codegen ``` -After that you can run: -* `pnpm run prettier` to check if your code is formatted correctly -* `pnpm run prettier:fix` to fix it -* `pnpm run lint` to check if your code is linted correctly -* `pnpm run lint:fix` to fix it +之后可以运行： +* `pnpm run prettier` —— 检查代码格式是否正确 +* `pnpm run prettier:fix` —— 修复格式问题 +* `pnpm run lint` —— 检查代码 lint 是否正确 +* `pnpm run lint:fix` —— 修复 lint 问题 -For generating SSL certificates you need to run `pnpm run ssl:generate` which using `generate-ssl.ts` file or it will be generated automatically when you run `pnpm run dev`. +生成 SSL 证书需要运行 `pnpm run ssl:generate`（使用 `generate-ssl.ts` 文件），或在运行 `pnpm run dev` 时会自动生成。 -#### Backend Configuration +#### 后端配置 -Edit the configuration for `backend` in `.vscode/launch.json` file: -- `DATABASE_URL` - PostgreSQL database URL (eg. `postgres://postgres:postgres@localhost:5432/pentagidb?sslmode=disable`) -- `DOCKER_HOST` - Docker SDK API (eg. for macOS `DOCKER_HOST=unix:///Users//Library/Containers/com.docker.docker/Data/docker.raw.sock`) [more info](https://stackoverflow.com/a/62757128/5922857) +在 `.vscode/launch.json` 文件中编辑 `backend` 的配置： +- `DATABASE_URL` - PostgreSQL 数据库 URL（例如 `postgres://postgres:postgres@localhost:5432/pentagidb?sslmode=disable`） +- `DOCKER_HOST` - Docker SDK API（例如 macOS 上为 `DOCKER_HOST=unix:///Users//Library/Containers/com.docker.docker/Data/docker.raw.sock`）[更多信息](https://stackoverflow.com/a/62757128/5922857) -Optional: -- `SERVER_PORT` - Port to run the server (default: `8443`) -- `SERVER_USE_SSL` - Enable SSL for the server (default: `false`) +可选： +- `SERVER_PORT` - 服务器运行端口（默认：`8443`） +- `SERVER_USE_SSL` - 是否为服务器启用 SSL（默认：`false`） -##### PostgreSQL / pgvector connection pool sizing +##### PostgreSQL / pgvector 连接池大小 -PentAGI opens two independent connection pools to the same Postgres instance: +PentAGI 会向同一 Postgres 实例打开两个独立的连接池： -| Pool | Env var | Default | Used by | +| 连接池 | 环境变量 | 默认值 | 使用者 | |---|---|---|---| -| Shared `sql.DB` | `DATABASE_MAX_OPEN_CONNS` | `25` | All sqlc queries and GORM handlers share a single `*sql.DB` | -| Shared `pgxpool` | `DATABASE_VECTOR_MAX_CONNS` | `10` | All pgvector stores (agent memory + knowledge API) share a single pool | +| 共享 `sql.DB` | `DATABASE_MAX_OPEN_CONNS` | `25` | 所有 sqlc 查询与 GORM handler 共享同一个 `*sql.DB` | +| 共享 `pgxpool` | `DATABASE_VECTOR_MAX_CONNS` | `10` | 所有 pgvector 存储（agent memory + knowledge API）共享同一个连接池 | -Additional tuning knob: -- `DATABASE_MAX_IDLE_CONNS` — maximum idle connections kept open in the `sql.DB` pool between requests (default: `5`). +额外调优参数： +- `DATABASE_MAX_IDLE_CONNS` — `sql.DB` 连接池在请求之间保持打开的最大空闲连接数（默认：`5`）。 -**Budget for the stock `vxcontrol/pgvector` image** (`max_connections = 100`, `superuser_reserved_connections = 3`): +**标准 `vxcontrol/pgvector` 镜像的连接预算**（`max_connections = 100`、`superuser_reserved_connections = 3`）： ``` Available for client connections = 97 @@ -2783,7 +2787,7 @@ Available for client connections = 97 Free buffer = 56 (≈ 58 %) ``` -The defaults are sized for **10 parallel flows** with concurrent API requests. If you run more flows or deploy multiple PentAGI instances against the same Postgres, raise `max_connections` via the `command` override in `docker-compose.yml` and increase the pool sizes proportionally: +默认配置面向 **10 个并行 flow** 及并发 API 请求。若运行更多 flow，或在同一 Postgres 上部署多个 PentAGI 实例，请通过 `docker-compose.yml` 中的 `command` 覆盖提高 `max_connections`，并同比例增大连接池大小： ```yaml pgvector: @@ -2791,7 +2795,7 @@ pgvector: command: postgres -c max_connections=200 ``` -To inspect the live connection budget on a running deployment: +若要查看运行中部署的实时连接预算： ```bash # Postgres limits @@ -2813,53 +2817,53 @@ docker exec pgvector sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c \ GROUP BY 1, 2, 3 ORDER BY count DESC;"' ``` -#### Frontend Configuration +#### 前端配置 -Edit the configuration for `frontend` in `.vscode/launch.json` file: -- `VITE_API_URL` - Backend API URL. *Omit* the URL scheme (e.g., `localhost:8080` *NOT* `http://localhost:8080`) -- `VITE_USE_HTTPS` - Enable SSL for the server (default: `false`) -- `VITE_PORT` - Port to run the server (default: `8000`) -- `VITE_HOST` - Host to run the server (default: `0.0.0.0`) +在 `.vscode/launch.json` 文件中编辑 `frontend` 的配置： +- `VITE_API_URL` - 后端 API URL。*省略* URL scheme（例如 `localhost:8080`，*而非* `http://localhost:8080`） +- `VITE_USE_HTTPS` - 是否为服务器启用 SSL（默认：`false`） +- `VITE_PORT` - 服务器运行端口（默认：`8000`） +- `VITE_HOST` - 服务器运行主机（默认：`0.0.0.0`） -### Running the Application +### 运行应用 -#### Backend +#### 后端 -Run the command(s) in `backend` folder: -- Use `.env` file to set environment variables like a `source .env` -- Run `go run cmd/pentagi/main.go` to start the server +在 `backend` 文件夹中运行以下命令： +- 使用 `.env` 文件设置环境变量，如同 `source .env` +- 运行 `go run cmd/pentagi/main.go` 启动服务器 > [!NOTE] -> The first run can take a while as dependencies and docker images need to be downloaded to setup the backend environment. +> 首次运行可能耗时较长，因为需要下载依赖和 docker 镜像以配置后端环境。 -#### Frontend +#### 前端 -Run the command(s) in `frontend` folder: -- Run `pnpm install` to install the dependencies -- Run `pnpm run dev` to run the web app -- Run `pnpm run build` to build the web app +在 `frontend` 文件夹中运行以下命令： +- 运行 `pnpm install` 安装依赖 +- 运行 `pnpm run dev` 启动 Web 应用 +- 运行 `pnpm run build` 构建 Web 应用 -Open your browser and visit the web app URL. +打开浏览器并访问 Web 应用 URL。 -## Testing LLM Agents +## 测试 LLM Agent -PentAGI includes a powerful utility called `ctester` for testing and validating LLM agent capabilities. This tool helps ensure your LLM provider configurations work correctly with different agent types, allowing you to optimize model selection for each specific agent role. +PentAGI 包含名为 `ctester` 的强大工具，用于测试和验证 LLM agent 能力。该工具可帮助确保你的 LLM 提供商配置能与不同 agent 类型正确配合，从而针对各 agent 角色优化模型选择。 -The utility features parallel testing of multiple agents, detailed reporting, and flexible configuration options. +该工具支持多 agent 并行测试、详细报告和灵活配置选项。 -### Key Features +### 主要特性 -- **Parallel Testing**: Tests multiple agents simultaneously for faster results -- **Comprehensive Test Suite**: Evaluates basic completion, JSON responses, function calling, and penetration testing knowledge -- **Detailed Reporting**: Generates markdown reports with success rates and performance metrics -- **Flexible Configuration**: Test specific agents or test groups as needed -- **Specialized Test Groups**: Includes domain-specific tests for cybersecurity and penetration testing scenarios +- **并行测试（Parallel Testing）**：同时测试多个 agent，更快获得结果 +- **全面测试套件（Comprehensive Test Suite）**：评估基础补全、JSON 响应、function calling 及渗透测试知识 +- **详细报告（Detailed Reporting）**：生成包含成功率与性能指标的 markdown 报告 +- **灵活配置（Flexible Configuration）**：按需测试特定 agent 或测试组 +- **专用测试组（Specialized Test Groups）**：包含面向网络安全与渗透测试场景的领域专项测试 -### Usage Scenarios +### 使用场景 -#### For Developers (with local Go environment) +#### 面向开发者（本地 Go 环境） -If you've cloned the repository and have Go installed: +若已克隆仓库并安装 Go： ```bash # Default configuration with .env file @@ -2879,9 +2883,9 @@ go run cmd/ctester/*.go -agents simple,simple_json,primary_agent -verbose go run cmd/ctester/*.go -groups basic,advanced -verbose ``` -#### For Users (using Docker image) +#### 面向用户（使用 Docker 镜像） -If you prefer to use the pre-built Docker image without setting up a development environment: +若希望使用预构建 Docker 镜像、无需搭建开发环境： ```bash # Using Docker to test with default environment @@ -2900,9 +2904,9 @@ docker run --rm \ vxcontrol/pentagi /opt/pentagi/bin/ctester -report /opt/pentagi/output/report.md ``` -#### Using Pre-configured Providers +#### 使用预配置的提供商 -The Docker image comes with built-in support for major providers (OpenAI, Anthropic, Gemini, Ollama) and pre-configured provider files for additional services (OpenRouter, DeepInfra, DeepSeek, Moonshot, Novita): +Docker 镜像内置了对主流提供商（OpenAI、Anthropic、Gemini、Ollama）的支持，并为其他服务（OpenRouter、DeepInfra、DeepSeek、Moonshot、Novita）提供了预配置的提供商文件： ```bash # Test with OpenRouter configuration @@ -2957,7 +2961,7 @@ docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/ollam docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/ollama-qwq32b-fp16-tc.provider.yml ``` -To use these configurations, your `.env` file only needs to contain: +要使用这些配置，你的 `.env` 文件只需包含： ``` LLM_SERVER_URL=https://openrouter.ai/api/v1 # or https://api.deepinfra.com/v1/openai or https://api.openai.com/v1 or https://api.novita.ai/openai @@ -3027,11 +3031,11 @@ OLLAMA_SERVER_PULL_MODELS_ENABLED=false OLLAMA_SERVER_LOAD_MODELS_ENABLED=false ``` -#### Using OpenAI with Unverified Organizations +#### 在未验证组织中使用 OpenAI -For OpenAI accounts with unverified organizations that don't have access to the latest reasoning models (o1, o3, o4-mini), you need to use a custom configuration. +对于所属组织未验证、无法使用最新推理模型（o1、o3、o4-mini）的 OpenAI 账户，你需要使用自定义配置。 -To use OpenAI with unverified organization accounts, configure your `.env` file as follows: +若要在未验证组织账户下使用 OpenAI，请按如下方式配置你的 `.env` 文件： ```bash LLM_SERVER_URL=https://api.openai.com/v1 @@ -3041,9 +3045,9 @@ LLM_SERVER_CONFIG_PATH=/opt/pentagi/conf/custom-openai.provider.yml LLM_SERVER_LEGACY_REASONING=true # Required for OpenAI reasoning format ``` -This configuration uses the pre-built `custom-openai.provider.yml` file that maps all agent types to models available for unverified organizations, using `o3-mini` instead of models like `o1`, `o3`, and `o4-mini`. +该配置使用预构建的 `custom-openai.provider.yml` 文件，将所有 Agent 类型映射到未验证组织可用的模型，使用 `o3-mini`，而非 `o1`、`o3` 和 `o4-mini` 等模型。 -You can test this configuration using: +你可以使用以下方式测试此配置： ```bash # Test with custom OpenAI configuration for unverified accounts @@ -3051,11 +3055,11 @@ docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/custo ``` > [!NOTE] -> The `LLM_SERVER_LEGACY_REASONING=true` setting is crucial for OpenAI compatibility as it ensures reasoning parameters are sent in the format expected by OpenAI's API. +> `LLM_SERVER_LEGACY_REASONING=true` 设置对于 OpenAI 兼容性至关重要，因为它可确保推理参数以 OpenAI API 所期望的格式发送。 -#### Using LiteLLM Proxy +#### 使用 LiteLLM Proxy -When using LiteLLM proxy to access various LLM providers, model names are prefixed with the provider name (e.g., `moonshot/kimi-2.5` instead of `kimi-2.5`). To use the same provider configuration files with both direct API access and LiteLLM proxy, set the `LLM_SERVER_PROVIDER` variable: +当使用 LiteLLM proxy 访问各类 LLM 提供商时，模型名称会带有提供商前缀（例如 `moonshot/kimi-2.5`，而非 `kimi-2.5`）。若要在直接 API 访问与 LiteLLM proxy 之间共用同一套提供商配置文件，请设置 `LLM_SERVER_PROVIDER` 变量： ```bash # Direct access to Moonshot API @@ -3071,23 +3075,23 @@ LLM_SERVER_CONFIG_PATH=/opt/pentagi/conf/moonshot.provider.yml LLM_SERVER_PROVIDER=moonshot # Provider prefix for LiteLLM ``` -With `LLM_SERVER_PROVIDER=moonshot`, the system automatically prefixes all model names from the configuration file with `moonshot/`, making them compatible with LiteLLM's model naming convention. +设置 `LLM_SERVER_PROVIDER=moonshot` 后，系统会自动为配置文件中的所有模型名称添加 `moonshot/` 前缀，使其与 LiteLLM 的模型命名约定兼容。 -**LiteLLM Provider Name Mapping:** +**LiteLLM 提供商名称映射：** -When using LiteLLM proxy, set the corresponding `*_PROVIDER` variable to enable model prefixing: +使用 LiteLLM proxy 时，请设置相应的 `*_PROVIDER` 变量以启用模型前缀： -- `deepseek` - for DeepSeek models (`DEEPSEEK_PROVIDER=deepseek` → `deepseek/deepseek-v4-flash`) -- `zai` - for GLM models (`GLM_PROVIDER=zai` → `zai/glm-4`) -- `moonshot` - for Kimi models (`KIMI_PROVIDER=moonshot` → `moonshot/kimi-k2.5`) -- `dashscope` - for Qwen models (`QWEN_PROVIDER=dashscope` → `dashscope/qwen-plus`) -- `openai`, `anthropic`, `gemini` - for major cloud providers -- `openrouter` - for OpenRouter aggregator -- `deepinfra` - for DeepInfra hosting -- `novita` - for Novita AI -- Any other provider name configured in your LiteLLM instance +- `deepseek` - 用于 DeepSeek 模型（`DEEPSEEK_PROVIDER=deepseek` → `deepseek/deepseek-v4-flash`） +- `zai` - 用于 GLM 模型（`GLM_PROVIDER=zai` → `zai/glm-4`） +- `moonshot` - 用于 Kimi 模型（`KIMI_PROVIDER=moonshot` → `moonshot/kimi-k2.5`） +- `dashscope` - 用于 Qwen 模型（`QWEN_PROVIDER=dashscope` → `dashscope/qwen-plus`） +- `openai`、`anthropic`、`gemini` - 用于主流云提供商 +- `openrouter` - 用于 OpenRouter 聚合器 +- `deepinfra` - 用于 DeepInfra 托管 +- `novita` - 用于 Novita AI +- 你在 LiteLLM 实例中配置的任何其他提供商名称 -**Example with LiteLLM:** +**LiteLLM 示例：** ```bash # Use DeepSeek models via LiteLLM proxy with model prefixing DEEPSEEK_API_KEY=your_litellm_proxy_key @@ -3100,14 +3104,14 @@ DEEPSEEK_SERVER_URL=https://api.deepseek.com # Leave DEEPSEEK_PROVIDER empty ``` -This approach allows you to: -- Use the same configuration files for both direct and proxied access -- Switch between providers without modifying configuration files -- Easily test different routing strategies with LiteLLM +此方法可让你： +- 在直接访问与代理访问之间共用同一套配置文件 +- 在不修改配置文件的情况下切换提供商 +- 通过 LiteLLM 轻松测试不同的路由策略 -#### Running Tests in a Production Environment +#### 在生产环境中运行测试 -If you already have a running PentAGI container and want to test the current configuration: +如果你已有正在运行的 PentAGI 容器，并希望测试当前配置： ```bash # Run ctester in an existing container using current environment variables @@ -3123,49 +3127,49 @@ docker exec -it pentagi /opt/pentagi/bin/ctester -report /opt/pentagi/data/agent docker cp pentagi:/opt/pentagi/data/agent-test-report.md ./ ``` -### Command-line Options +### 命令行选项 -The utility accepts several options: +该工具接受以下选项： -- `-env ` - Path to environment file (default: `.env`) -- `-type ` - Provider type: `custom`, `openai`, `anthropic`, `ollama`, `bedrock`, `gemini` (default: `custom`) -- `-config ` - Path to custom provider config (default: from `LLM_SERVER_CONFIG_PATH` env variable) -- `-tests ` - Path to custom tests YAML file (optional) -- `-report ` - Path to write the report file (optional) -- `-agents ` - Comma-separated list of agent types to test (default: `all`) -- `-groups ` - Comma-separated list of test groups to run (default: `all`) -- `-verbose` - Enable verbose output with detailed test results for each agent +- `-env ` - 环境文件路径（默认：`.env`） +- `-type ` - 提供商类型：`custom`、`openai`、`anthropic`、`ollama`、`bedrock`、`gemini`（默认：`custom`） +- `-config ` - 自定义提供商配置路径（默认：来自 `LLM_SERVER_CONFIG_PATH` 环境变量） +- `-tests ` - 自定义测试 YAML 文件路径（可选） +- `-report ` - 报告文件写入路径（可选） +- `-agents ` - 要测试的 agent 类型列表，以逗号分隔（默认：`all`） +- `-groups ` - 要运行的测试组列表，以逗号分隔（默认：`all`） +- `-verbose` - 启用详细输出，显示每个 agent 的详细测试结果 -### Available Agent Types +### 可用的 Agent 类型 -Agents are tested in the following deterministic order: +Agent 按以下确定性顺序进行测试： -1. **simple** - Basic completion tasks -2. **simple_json** - JSON-structured responses -3. **primary_agent** - Main reasoning agent -4. **assistant** - Interactive assistant mode -5. **generator** - Content generation -6. **refiner** - Content refinement and improvement -7. **adviser** - Expert advice and consultation -8. **reflector** - Self-reflection and analysis -9. **searcher** - Information gathering and search -10. **enricher** - Data enrichment and expansion -11. **coder** - Code generation and analysis -12. **installer** - Installation and setup tasks -13. **pentester** - Penetration testing and security assessment +1. **simple** - 基础补全任务 +2. **simple_json** - JSON 结构化响应 +3. **primary_agent** - 主推理 agent +4. **assistant** - 交互式助手模式 +5. **generator** - 内容生成 +6. **refiner** - 内容精炼与改进 +7. **adviser** - 专家建议与咨询 +8. **reflector** - 自我反思与分析 +9. **searcher** - 信息收集与搜索 +10. **enricher** - 数据丰富与扩展 +11. **coder** - 代码生成与分析 +12. **installer** - 安装与配置任务 +13. **pentester** - 渗透测试与安全评估 -### Available Test Groups +### 可用的测试组 -- **basic** - Fundamental completion and prompt response tests -- **advanced** - Complex reasoning and function calling tests -- **json** - JSON format validation and structure tests (specifically designed for `simple_json` agent) -- **knowledge** - Domain-specific cybersecurity and penetration testing knowledge tests +- **basic** - 基础补全与提示响应测试 +- **advanced** - 复杂推理与函数调用（function calling）测试 +- **json** - JSON 格式验证与结构测试（专为 `simple_json` agent 设计） +- **knowledge** - 特定领域的网络安全与渗透测试知识测试 -> **Note**: The `json` test group is specifically designed for the `simple_json` agent type, while all other agents are tested with `basic`, `advanced`, and `knowledge` groups. This specialization ensures optimal testing coverage for each agent's intended purpose. +> **注意**：`json` 测试组专为 `simple_json` agent 类型设计，而所有其他 agent 使用 `basic`、`advanced` 和 `knowledge` 组进行测试。这种专门化可确保针对每个 agent 的预期用途实现最优测试覆盖。 -### Example Provider Configuration +### 提供商配置示例 -Provider configuration defines which models to use for different agent types: +提供商配置定义了不同 agent 类型应使用哪些模型： ```yaml simple: @@ -3186,42 +3190,42 @@ simple_json: # ... other agent types ... ``` -### Optimization Workflow +### 优化工作流 -1. **Create a baseline**: Run tests with default configuration to establish benchmark performance -2. **Analyze agent-specific performance**: Review the deterministic agent ordering to identify underperforming agents -3. **Test specialized configurations**: Experiment with different models for each agent type using provider-specific configs -4. **Focus on domain knowledge**: Pay special attention to knowledge group tests for cybersecurity expertise -5. **Validate function calling**: Ensure tool-based tests pass consistently for critical agent types -6. **Compare results**: Look for the best success rate and performance across all test groups -7. **Deploy optimal configuration**: Use in production with your optimized setup +1. **创建基线**：使用默认配置运行测试，建立基准性能 +2. **分析各 agent 的性能**：查看确定性 agent 排序，识别表现不佳的 agent +3. **测试专用配置**：使用特定于提供商的配置，为各 agent 类型尝试不同模型 +4. **关注领域知识**：特别关注 knowledge 组测试，以评估网络安全专业能力 +5. **验证函数调用**：确保基于工具的测试对关键 agent 类型稳定通过 +6. **对比结果**：在所有测试组中寻找最佳成功率与性能 +7. **部署最优配置**：在生产环境中使用优化后的配置 -This tool helps ensure your AI agents are using the most effective models for their specific tasks, improving reliability while optimizing costs. +该工具可帮助确保你的 AI agent 为其特定任务使用最有效的模型，在优化成本的同时提升可靠性。 -## Embedding Configuration and Testing +## 嵌入（Embedding）配置与测试 -PentAGI uses vector embeddings for semantic search, knowledge storage, and memory management. The system supports multiple embedding providers that can be configured according to your needs and preferences. +PentAGI 使用向量嵌入（vector embeddings）进行语义搜索、知识存储与记忆管理。系统支持多种嵌入提供商，可根据你的需求与偏好进行配置。 -### Supported Embedding Providers +### 支持的嵌入提供商 -PentAGI supports the following embedding providers: +PentAGI 支持以下嵌入提供商： -- **OpenAI** (default): Uses OpenAI's text embedding models -- **Ollama**: Local embedding model through Ollama -- **Mistral**: Mistral AI's embedding models -- **Jina**: Jina AI's embedding service -- **HuggingFace**: Models from HuggingFace -- **GoogleAI**: Google's embedding models -- **VoyageAI**: VoyageAI's embedding models +- **OpenAI**（默认）：使用 OpenAI 的文本嵌入模型 +- **Ollama**：通过 Ollama 使用本地嵌入模型 +- **Mistral**：Mistral AI 的嵌入模型 +- **Jina**：Jina AI 的嵌入服务 +- **HuggingFace**：来自 HuggingFace 的模型 +- **GoogleAI**：Google 的嵌入模型 +- **VoyageAI**：VoyageAI 的嵌入模型 -> **OpenAI-compatible third parties**: any provider exposing OpenAI's `/embeddings` API can be plugged in via `EMBEDDING_PROVIDER=openai` with a custom `EMBEDDING_URL`. For example, **Qwen DashScope** offers `text-embedding-v4` through the `/compatible-mode/v1` endpoint (International and Chinese Mainland regions only — the US region does not expose embeddings). See the [Qwen Alternative Integrations](#alternative-integrations) subsection for the full configuration snippet. +> **OpenAI 兼容第三方**：任何提供 OpenAI `/embeddings` API 的提供商，均可通过 `EMBEDDING_PROVIDER=openai` 配合自定义 `EMBEDDING_URL` 接入。例如，**Qwen DashScope** 通过 `/compatible-mode/v1` 端点提供 `text-embedding-v4`（仅限国际版与中国大陆地区——美国区域不提供嵌入服务）。完整配置片段请参阅 [Qwen Alternative Integrations](#alternative-integrations) 小节。
Embedding Provider Configuration (click to expand) -### Environment Variables +### 环境变量 -To configure the embedding provider, set the following environment variables in your `.env` file: +要配置嵌入（embedding）提供方，请在 `.env` 文件中设置以下环境变量： ```bash # Primary embedding configuration @@ -3245,13 +3249,13 @@ EXTERNAL_SSL_INSECURE=false # Skip certificate verification (use only for te ```
-How to Add Custom CA Certificates (click to expand) +如何添加自定义 CA 证书（点击展开） -If you see this error: `tls: failed to verify certificate: x509: certificate signed by unknown authority` +如果你看到此错误：`tls: failed to verify certificate: x509: certificate signed by unknown authority` -**Step 1:** Get your CA certificate bundle in PEM format (can contain multiple certificates) +**步骤 1：** 获取 PEM 格式的 CA 证书包（可包含多个证书） -**Step 2:** Place the file in the SSL directory on your host machine: +**步骤 2：** 将文件放在宿主机的 SSL 目录中： ```bash # Default location (if PENTAGI_SSL_DIR is not set) cp ca-bundle.pem ./pentagi-ssl/ @@ -3260,58 +3264,58 @@ cp ca-bundle.pem ./pentagi-ssl/ cp ca-bundle.pem /path/to/your/ssl/dir/ ``` -**Step 3:** Set the path in `.env` file (path must be inside the container): +**步骤 3：** 在 `.env` 文件中设置路径（路径必须在容器内部）： ```bash # The volume pentagi-ssl is mounted to /opt/pentagi/ssl inside the container EXTERNAL_SSL_CA_PATH=/opt/pentagi/ssl/ca-bundle.pem EXTERNAL_SSL_INSECURE=false ``` -**Step 4:** Restart PentAGI: +**步骤 4：** 重启 PentAGI： ```bash docker compose restart pentagi ``` -**Notes:** -- The `pentagi-ssl` volume is mounted to `/opt/pentagi/ssl` inside the container -- You can change host directory using `PENTAGI_SSL_DIR` variable in docker-compose.yml -- File supports multiple certificates and intermediate CAs in one PEM file -- Use `EXTERNAL_SSL_INSECURE=true` only for testing (not recommended for production) +**说明：** +- `pentagi-ssl` 卷会挂载到容器内的 `/opt/pentagi/ssl` +- 可在 docker-compose.yml 中使用 `PENTAGI_SSL_DIR` 变量更改宿主机目录 +- 单个 PEM 文件可包含多个证书及中间 CA +- 仅将 `EXTERNAL_SSL_INSECURE=true` 用于测试（不建议用于生产环境）
-### Provider-Specific Limitations +### 各提供方特定限制 -Each provider has specific limitations and supported features: +各提供方有特定的限制和支持的功能： -- **OpenAI**: Supports all configuration options -- **Ollama**: Does not support `EMBEDDING_KEY` as it uses local models -- **Mistral**: Does not support `EMBEDDING_MODEL` or custom HTTP client -- **Jina**: Does not support custom HTTP client -- **HuggingFace**: Requires `EMBEDDING_KEY` and supports all other options -- **GoogleAI**: Does not support `EMBEDDING_URL`, requires `EMBEDDING_KEY` -- **VoyageAI**: Supports all configuration options +- **OpenAI**：支持所有配置选项 +- **Ollama**：不支持 `EMBEDDING_KEY`，因其使用本地模型 +- **Mistral**：不支持 `EMBEDDING_MODEL` 或自定义 HTTP 客户端 +- **Jina**：不支持自定义 HTTP 客户端 +- **HuggingFace**：需要 `EMBEDDING_KEY`，并支持所有其他选项 +- **GoogleAI**：不支持 `EMBEDDING_URL`，需要 `EMBEDDING_KEY` +- **VoyageAI**：支持所有配置选项 -If `EMBEDDING_URL` and `EMBEDDING_KEY` are not specified, the system will attempt to use the corresponding LLM provider settings (e.g., `OPEN_AI_KEY` when `EMBEDDING_PROVIDER=openai`). +如果未指定 `EMBEDDING_URL` 和 `EMBEDDING_KEY`，系统将尝试使用对应的 LLM 提供方设置（例如，当 `EMBEDDING_PROVIDER=openai` 时使用 `OPEN_AI_KEY`）。 -### Why Consistent Embedding Providers Matter +### 为何嵌入提供方需保持一致 -It's crucial to use the same embedding provider consistently because: +始终使用同一嵌入提供方至关重要，原因如下： -1. **Vector Compatibility**: Different providers produce vectors with different dimensions and mathematical properties -2. **Semantic Consistency**: Changing providers can break semantic similarity between previously embedded documents -3. **Memory Corruption**: Mixed embeddings can lead to poor search results and broken knowledge base functionality +1. **向量兼容性（Vector Compatibility）**：不同提供方产生的向量在维度和数学属性上各不相同 +2. **语义一致性（Semantic Consistency）**：更换提供方可能破坏先前已嵌入文档之间的语义相似性 +3. **记忆污染（Memory Corruption）**：混用不同嵌入可能导致搜索结果变差，知识库功能失效 -If you change your embedding provider, you should flush and reindex your entire knowledge base (see `etester` utility below). +如果更换嵌入提供方，应清空并重新索引整个知识库（见下文 `etester` 工具）。
-### Embedding Tester Utility (etester) +### 嵌入测试工具（etester） -PentAGI includes a specialized `etester` utility for testing, managing, and debugging embedding functionality. This tool is essential for diagnosing and resolving issues related to vector embeddings and knowledge storage. +PentAGI 包含专用的 `etester` 工具，用于测试、管理和调试嵌入功能。该工具对于诊断和解决与向量嵌入及知识存储相关的问题至关重要。
-Etester Commands (click to expand) +Etester 命令（点击展开） ```bash # Test embedding provider and database connection @@ -3331,9 +3335,9 @@ go run cmd/etester/main.go reindex go run cmd/etester/main.go search -query "How to install PostgreSQL" -limit 5 ``` -### Using Docker +### 使用 Docker -If you're running PentAGI in Docker, you can use etester from within the container: +如果你在 Docker 中运行 PentAGI，可在容器内使用 etester： ```bash # Test embedding provider @@ -3343,9 +3347,9 @@ docker exec -it pentagi /opt/pentagi/bin/etester test docker exec -it pentagi /opt/pentagi/bin/etester info -verbose ``` -### Advanced Search Options +### 高级搜索选项 -The `search` command supports various filters to narrow down results: +`search` 命令支持多种筛选条件以缩小结果范围： ```bash # Filter by document type @@ -3358,55 +3362,55 @@ docker exec -it pentagi /opt/pentagi/bin/etester search -query "Code examples" - docker exec -it pentagi /opt/pentagi/bin/etester search -help ``` -Available search parameters: -- `-query STRING`: Search query text (required) -- `-doc_type STRING`: Filter by document type (answer, memory, guide, code) -- `-flow_id NUMBER`: Filter by flow ID (positive number) -- `-answer_type STRING`: Filter by answer type (guide, vulnerability, code, tool, other) -- `-guide_type STRING`: Filter by guide type (install, configure, use, pentest, development, other) -- `-limit NUMBER`: Maximum number of results (default: 3) -- `-threshold NUMBER`: Similarity threshold (0.0-1.0, default: 0.7) +可用的搜索参数： +- `-query STRING`：搜索查询文本（必填） +- `-doc_type STRING`：按文档类型筛选（answer、memory、guide、code） +- `-flow_id NUMBER`：按 flow ID 筛选（正整数） +- `-answer_type STRING`：按回答类型筛选（guide、vulnerability、code、tool、other） +- `-guide_type STRING`：按指南类型筛选（install、configure、use、pentest、development、other） +- `-limit NUMBER`：最大结果数量（默认：3） +- `-threshold NUMBER`：相似度阈值（0.0-1.0，默认：0.7） -### Memory Lifecycle Across Flows +### 跨 Flow 的记忆生命周期 -PentAGI stores several kinds of vector documents, and they serve different purposes: +PentAGI 存储多种向量文档，各自用途不同： -- `memory` captures flow-specific execution history such as tool results and agent observations -- `guide`, `answer`, and `code` are intended for reusable knowledge that can help future runs +- `memory` 记录与 flow 相关的执行历史，例如工具结果和 agent 观测 +- `guide`、`answer` 和 `code` 用于可在后续运行中复用的知识 -If you want to inspect what happened in one engagement, search the vector store with the related `flow_id`. If you want knowledge to survive beyond a single run, store the durable result explicitly as a `guide`, `answer`, or `code` document instead of relying on execution memory alone. +若要查看某次 engagement 中发生了什么，请使用相关的 `flow_id` 在向量存储中搜索。若希望知识在单次运行之外仍能保留，应显式将持久结果存储为 `guide`、`answer` 或 `code` 文档，而非仅依赖执行记忆。 -For example, if a target has recurring setup notes, authentication quirks, or target-specific testing methodology, instruct the agent to save that information as a `guide` and search for it at the beginning of the next engagement. This is the safest current workflow when you want a new flow to start with reusable context. +例如，若目标存在重复出现的搭建说明、认证特性或目标专属测试方法，可指示 agent 将该信息保存为 `guide`，并在下次 engagement 开始时搜索它。若希望新 flow 以可复用上下文启动，这是当前最稳妥的工作流程。 -Flow deletion removes the flow from normal queries through PentAGI's soft-delete mechanism, so reusable knowledge should be treated as a separate concern from per-flow execution history. If you enable the optional Graphiti knowledge graph described earlier in this README, treat its current search context as scoped to the active flow or engagement unless you explicitly build a separate cross-flow reuse workflow. +删除 flow 会通过 PentAGI 的软删除机制将其从常规查询中移除，因此可复用知识应与各 flow 的执行历史分开管理。若启用本 README 前文所述的可选 Graphiti 知识图谱，应将其当前搜索上下文视为限定于活动 flow 或 engagement，除非你显式构建独立的跨 flow 复用工作流。 -### Common Troubleshooting Scenarios +### 常见故障排查场景 -1. **After changing embedding provider**: Always run `flush` or `reindex` to ensure consistency -2. **Poor search results**: Try adjusting the similarity threshold or check if embeddings are correctly generated -3. **Database connection issues**: Verify PostgreSQL is running with pgvector extension installed -4. **Missing API keys**: Check environment variables for your chosen embedding provider +1. **更换嵌入提供方后**：务必运行 `flush` 或 `reindex` 以确保一致性 +2. **搜索结果不佳**：尝试调整相似度阈值，或检查嵌入是否正确生成 +3. **数据库连接问题**：确认 PostgreSQL 正在运行且已安装 pgvector 扩展 +4. **缺少 API 密钥**：检查所选嵌入提供方的环境变量
-## Function Testing with ftester +## 使用 ftester 进行函数测试 -PentAGI includes a versatile utility called `ftester` for debugging, testing, and developing specific functions and AI agent behaviors. While `ctester` focuses on testing LLM model capabilities, `ftester` allows you to directly invoke individual system functions and AI agent components with precise control over execution context. +PentAGI 包含一款名为 `ftester` 的多功能工具，用于调试、测试和开发特定函数及 AI 智能体（agent）行为。`ctester` 侧重于测试 LLM 模型能力，而 `ftester` 则允许你直接调用各个系统函数和 AI 智能体组件，并对执行上下文进行精确控制。 -### Key Features +### 主要特性 -- **Direct Function Access**: Test individual functions without running the entire system -- **Mock Mode**: Test functions without a live PentAGI deployment using built-in mocks -- **Interactive Input**: Fill function arguments interactively for exploratory testing -- **Detailed Output**: Color-coded terminal output with formatted responses and errors -- **Context-Aware Testing**: Debug AI agents within the context of specific flows, tasks, and subtasks -- **Observability Integration**: All function calls are logged to Langfuse and Observability stack +- **直接访问函数**：无需运行整个系统即可测试单个函数 +- **Mock 模式**：使用内置 mock，无需在线 PentAGI 部署即可测试函数 +- **交互式输入**：交互式填写函数参数，便于探索性测试 +- **详细输出**：带颜色编码的终端输出，包含格式化的响应与错误信息 +- **上下文感知测试**：在特定流程（flow）、任务（task）和子任务（subtask）的上下文中调试 AI 智能体 +- **可观测性集成**：所有函数调用都会记录到 Langfuse 和 Observability 技术栈 -### Usage Modes +### 使用模式 -#### Command Line Arguments +#### 命令行参数 -Run ftester with specific function and arguments directly from the command line: +在命令行中直接指定函数和参数来运行 ftester： ```bash # Basic usage with mock mode @@ -3423,9 +3427,9 @@ go run cmd/ftester/main.go -flow 123 terminal -command "whoami" -message "Check go run cmd/ftester/main.go -flow 123 -task 456 -subtask 789 pentester -message "Find vulnerabilities" ``` -#### Interactive Mode +#### 交互模式 -Run ftester without arguments for a guided interactive experience: +不带参数运行 ftester，获得引导式交互体验： ```bash # Start interactive mode @@ -3436,45 +3440,45 @@ go run cmd/ftester/main.go browser ```
-Available Functions (click to expand) +可用函数（点击展开） -### Environment Functions -- **terminal**: Execute commands in a container and return the output -- **file**: Perform file operations (read, write, list) in a container +### 环境函数 +- **terminal**：在容器中执行命令并返回输出 +- **file**：在容器中执行文件操作（读取、写入、列出） -### Search Functions -- **browser**: Access websites and capture screenshots -- **google**: Search the web using Google Custom Search -- **duckduckgo**: Search the web using DuckDuckGo -- **tavily**: Search using Tavily AI search engine -- **traversaal**: Search using Traversaal AI search engine -- **perplexity**: Search using Perplexity AI -- **sploitus**: Search for security exploits, vulnerabilities (CVEs), and pentesting tools -- **searxng**: Search using Searxng meta search engine (aggregates results from multiple engines) +### 搜索函数 +- **browser**：访问网站并截取屏幕截图 +- **google**：使用 Google Custom Search 搜索网络 +- **duckduckgo**：使用 DuckDuckGo 搜索网络 +- **tavily**：使用 Tavily AI 搜索引擎进行搜索 +- **traversaal**：使用 Traversaal AI 搜索引擎进行搜索 +- **perplexity**：使用 Perplexity AI 进行搜索 +- **sploitus**：搜索安全漏洞利用、漏洞（CVE）和渗透测试工具 +- **searxng**：使用 Searxng 元搜索引擎进行搜索（聚合多个引擎的结果） -### Vector Database Functions -- **search_in_memory**: Search for information in vector database -- **search_guide**: Find guidance documents in vector database -- **search_answer**: Find answers to questions in vector database -- **search_code**: Find code examples in vector database +### 向量数据库函数 +- **search_in_memory**：在向量数据库中搜索信息 +- **search_guide**：在向量数据库中查找指导文档 +- **search_answer**：在向量数据库中查找问题的答案 +- **search_code**：在向量数据库中查找代码示例 -### AI Agent Functions -- **advice**: Get expert advice from an AI agent -- **coder**: Request code generation or modification -- **maintenance**: Run system maintenance tasks -- **memorist**: Store and organize information in vector database -- **pentester**: Perform security tests and vulnerability analysis -- **search**: Complex search across multiple sources +### AI 智能体函数 +- **advice**：从 AI 智能体获取专家建议 +- **coder**：请求生成或修改代码 +- **maintenance**：运行系统维护任务 +- **memorist**：在向量数据库中存储和组织信息 +- **pentester**：执行安全测试和漏洞分析 +- **search**：跨多个来源进行复杂搜索 -### Utility Functions -- **describe**: Show information about flows, tasks, and subtasks +### 工具函数 +- **describe**：显示有关流程、任务和子任务的信息
-Debugging Flow Context (click to expand) +调试流程上下文（点击展开） -The `describe` function provides detailed information about tasks and subtasks within a flow. This is particularly useful for diagnosing issues when PentAGI encounters problems or gets stuck. +`describe` 函数提供流程内任务和子任务的详细信息。当 PentAGI 遇到问题或卡住时，这对于诊断问题特别有用。 ```bash # List all flows in the system @@ -3493,14 +3497,14 @@ go run cmd/ftester/main.go -flow 123 -task 456 -subtask 789 describe go run cmd/ftester/main.go -flow 123 describe -verbose ``` -This function allows you to identify the exact point where a flow might be stuck and resume processing by directly invoking the appropriate agent function. +该函数可帮助你定位流程可能卡住的精确位置，并通过直接调用相应的智能体函数来恢复处理。
-Function Help and Discovery (click to expand) +函数帮助与发现（点击展开） -Each function has a help mode that shows available parameters: +每个函数都有帮助模式，可显示可用参数： ```bash # Get help for a specific function @@ -3512,7 +3516,7 @@ go run cmd/ftester/main.go browser -help go run cmd/ftester/main.go describe -help ``` -You can also run ftester without arguments to see a list of all available functions: +你也可以不带参数运行 ftester，查看所有可用函数的列表： ```bash go run cmd/ftester/main.go @@ -3521,38 +3525,38 @@ go run cmd/ftester/main.go
-Output Format (click to expand) +输出格式（点击展开） -The `ftester` utility uses color-coded output to make interpretation easier: +`ftester` 工具使用颜色编码输出，便于解读： -- **Blue headers**: Section titles and key names -- **Cyan [INFO]**: General information messages -- **Green [SUCCESS]**: Successful operations -- **Red [ERROR]**: Error messages -- **Yellow [WARNING]**: Warning messages -- **Yellow [MOCK]**: Indicates mock mode operation -- **Magenta values**: Function arguments and results +- **蓝色标题**：章节标题和键名 +- **青色 [INFO]**：一般信息消息 +- **绿色 [SUCCESS]**：操作成功 +- **红色 [ERROR]**：错误消息 +- **黄色 [WARNING]**：警告消息 +- **黄色 [MOCK]**：表示处于 mock 模式运行 +- **洋红色值**：函数参数和结果 -JSON and Markdown responses are automatically formatted for readability. +JSON 和 Markdown 响应会自动格式化，以提高可读性。
-Advanced Usage Scenarios (click to expand) +高级使用场景（点击展开） -### Debugging Stuck AI Flows +### 调试卡住的 AI 流程 -When PentAGI gets stuck in a flow: +当 PentAGI 在流程中卡住时： -1. Pause the flow through the UI -2. Use `describe` to identify the current task and subtask -3. Directly invoke the agent function with the same task/subtask IDs -4. Examine the detailed output to identify the issue -5. Resume the flow or manually intervene as needed +1. 通过 UI 暂停流程 +2. 使用 `describe` 识别当前任务和子任务 +3. 使用相同的任务/子任务 ID 直接调用智能体函数 +4. 检查详细输出以定位问题 +5. 根据需要恢复流程或手动干预 -### Testing Environment Variables +### 测试环境变量 -Verify that API keys and external services are configured correctly: +验证 API 密钥和外部服务是否配置正确： ```bash # Test Google search API configuration @@ -3562,18 +3566,18 @@ go run cmd/ftester/main.go google -query "pentesting tools" go run cmd/ftester/main.go browser -url "https://example.com" ``` -### Developing New AI Agent Behaviors +### 开发新的 AI 智能体行为 -When developing new prompt templates or agent behaviors: +在开发新的提示词模板或智能体行为时： -1. Create a test flow in the UI -2. Use ftester to directly invoke the agent with different prompts -3. Observe responses and adjust prompts accordingly -4. Check Langfuse for detailed traces of all function calls +1. 在 UI 中创建测试流程 +2. 使用 ftester 以不同提示词直接调用智能体 +3. 观察响应并相应调整提示词 +4. 在 Langfuse 中查看所有函数调用的详细追踪记录 -### Verifying Docker Container Setup +### 验证 Docker 容器配置 -Ensure containers are properly configured: +确保容器配置正确： ```bash go run cmd/ftester/main.go -flow 123 terminal -command "env | grep -i proxy" -message "Check proxy settings" @@ -3582,9 +3586,9 @@ go run cmd/ftester/main.go -flow 123 terminal -command "env | grep -i proxy" -me
-Docker Container Usage (click to expand) +Docker 容器用法（点击展开） -If you have PentAGI running in Docker, you can use ftester from within the container: +如果你在 Docker 中运行 PentAGI，可以在容器内使用 ftester： ```bash # Run ftester inside the running PentAGI container @@ -3595,56 +3599,56 @@ docker exec -it pentagi /opt/pentagi/bin/ftester -flow 123 describe docker exec -it pentagi /opt/pentagi/bin/ftester -flow 123 terminal -command "ps aux" -message "List processes" ``` -This is particularly useful for production deployments where you don't have a local development environment. +这对于没有本地开发环境的生产部署特别有用。
-Integration with Observability Tools (click to expand) +与可观测性工具集成（点击展开） -All function calls made through ftester are logged to: +通过 ftester 进行的所有函数调用都会记录到： -1. **Langfuse**: Captures the entire AI agent interaction chain, including prompts, responses, and function calls -2. **OpenTelemetry**: Records metrics, traces, and logs for system performance analysis -3. **Terminal Output**: Provides immediate feedback on function execution +1. **Langfuse**：捕获完整的 AI 智能体交互链，包括提示词、响应和函数调用 +2. **OpenTelemetry**：记录指标、追踪和日志，用于系统性能分析 +3. **终端输出**：提供函数执行的即时反馈 -To access detailed logs: +要访问详细日志： -- Check Langfuse UI for AI agent traces (typically at `http://localhost:4000`) -- Use Grafana dashboards for system metrics (typically at `http://localhost:3000`) -- Examine terminal output for immediate function results and errors +- 在 Langfuse UI 中查看 AI 智能体追踪记录（通常位于 `http://localhost:4000`） +- 使用 Grafana 仪表板查看系统指标（通常位于 `http://localhost:3000`） +- 检查终端输出以获取即时的函数结果和错误信息
-### Command-line Options +### 命令行选项 -The main utility accepts several options: +主工具接受以下若干选项： -- `-env ` - Path to environment file (optional, default: `.env`) -- `-provider ` - Provider type to use (default: `custom`, options: `openai`, `anthropic`, `ollama`, `bedrock`, `gemini`, `custom`) -- `-flow ` - Flow ID for testing (0 means using mocks, default: `0`) -- `-task ` - Task ID for agent context (optional) -- `-subtask ` - Subtask ID for agent context (optional) +- `-env ` - 环境文件路径（可选，默认：`.env`） +- `-provider ` - 要使用的提供商类型（默认：`custom`，可选：`openai`、`anthropic`、`ollama`、`bedrock`、`gemini`、`custom`） +- `-flow ` - 用于测试的 Flow ID（0 表示使用 mock，默认：`0`） +- `-task ` - 智能体上下文的 Task ID（可选） +- `-subtask ` - 智能体上下文的 Subtask ID（可选） -Function-specific arguments are passed after the function name using `-name value` format. +函数专属参数在函数名之后传递，格式为 `-name value`。 -### Pentesting Prompt Methodology +### 渗透测试提示词方法论 -When refining prompts for offensive security work, give the agent a clear methodology instead of a flat list of payloads: +在为攻击性安全工作优化提示词时，应为智能体提供清晰的方法论，而非平铺直叙的载荷列表： -1. Start with explicit scope, authorization, and success criteria -2. Map the application first: roles, routes, parameters, uploads, integrations, and trust boundaries -3. Prioritize attack surfaces systematically instead of testing everything at once -4. Validate findings with reproducible evidence before escalating to deeper exploitation -5. Finish with report-ready notes that capture impact, prerequisites, and next steps +1. 首先明确范围、授权和成功标准 +2. 先映射应用：角色、路由、参数、上传、集成和信任边界 +3. 系统性地优先排序攻击面，而不是一次性测试所有内容 +4. 在深入利用之前，用可复现的证据验证发现 +5. 最后整理可直接用于报告的笔记，记录影响、前置条件和后续步骤 -For PentAGI-specific prompt guidance, see [`backend/docs/prompt_engineering_pentagi.md`](backend/docs/prompt_engineering_pentagi.md). For a practical starting point, reuse and adapt [`examples/prompts/base_web_pentest.md`](examples/prompts/base_web_pentest.md) to match the target application, technology stack, and engagement scope. +有关 PentAGI 专属的提示词指导，请参阅 [`backend/docs/prompt_engineering_pentagi.md`](backend/docs/prompt_engineering_pentagi.md)。如需实用的起点，可复用并调整 [`examples/prompts/base_web_pentest.md`](examples/prompts/base_web_pentest.md)，以匹配目标应用、技术栈和项目范围。 -## Building +## 构建 -### Building Docker Image +### 构建 Docker 镜像 -The Docker build process automatically embeds version information from git tags. To properly version your build, use the provided scripts: +Docker 构建过程会自动从 git 标签嵌入版本信息。要正确为构建打上版本号，请使用提供的脚本： #### Linux/macOS @@ -3674,7 +3678,7 @@ docker buildx build \ --push . ``` -#### Windows (PowerShell) +#### Windows（PowerShell） ```powershell # Load version variables @@ -3694,41 +3698,41 @@ docker buildx build ` -t pentagi:$env:PACKAGE_VER . ``` -#### Quick build without version +#### 无版本信息的快速构建 -For development builds without version tracking: +适用于无需版本追踪的开发构建： ```bash docker build -t pentagi:dev . ``` > [!NOTE] -> - The build scripts automatically determine version from git tags -> - Release builds (on tag commit) have no revision suffix -> - Development builds (after tag) include commit hash as revision (e.g., `1.1.0-bc6e800`) -> - To use the built image locally, update the image name in `docker-compose.yml` or use the `build` option +> - 构建脚本会自动根据 git 标签确定版本 +> - 发布构建（在标签提交上）没有修订后缀 +> - 开发构建（标签之后）将提交哈希作为修订号（例如，`1.1.0-bc6e800`） +> - 要在本地使用构建的镜像，请在 `docker-compose.yml` 中更新镜像名称，或使用 `build` 选项 -## Credits +## 致谢 -This project is made possible thanks to the following research and developments: -- [Emerging Architectures for LLM Applications](https://lilianweng.github.io/posts/2023-06-23-agent) -- [A Survey of Autonomous LLM Agents](https://arxiv.org/abs/2403.08299) -- [Codel](https://github.com/semanser/codel) by Andriy Semenets - initial architectural inspiration for agent-based automation +本项目的实现得益于以下研究与开发成果： +- [面向 LLM 应用的新兴架构](https://lilianweng.github.io/posts/2023-06-23-agent) +- [自主 LLM 智能体综述](https://arxiv.org/abs/2403.08299) +- [Codel](https://github.com/semanser/codel) by Andriy Semenets - 基于智能体的自动化初期架构灵感 -## License +## 许可证 -**PentAGI** is licensed under the [MIT License](LICENSE). +**PentAGI** 根据 [MIT License](LICENSE) 授权。 Copyright (c) 2025 PentAGI Development Team -### Third-Party Dependencies +### 第三方依赖 -All third-party dependencies use MIT-compatible licenses. See [licenses/](licenses/) directory for detailed license reports. +所有第三方依赖均采用与 MIT 兼容的许可证。详见 [licenses/](licenses/) 目录中的详细许可证报告。 ### VXControl Cloud Services -⚠️ **Note:** While the VXControl Cloud SDK code is MIT licensed, accessing **VXControl Cloud Services** (threat intelligence, AI support, premium features) requires a separate License Key and compliance with [Terms of Service](https://github.com/vxcontrol/cloud#license-and-terms). +⚠️ **注意：** 虽然 VXControl Cloud SDK 代码采用 MIT 许可证，但访问 **VXControl Cloud Services**（威胁情报、AI 支持、高级功能）需要单独的 License Key，并须遵守 [服务条款](https://github.com/vxcontrol/cloud#license-and-terms). -The SDK code itself is free to use - service access requires registration. +SDK 代码本身可免费使用——服务访问需要注册。 -For questions contact: **info@pentagi.com** or **info@vxcontrol.com** +如有疑问，请联系：**info@pentagi.com** 或 **info@vxcontrol.com**