[](https://deepwiki.com/arn-c0de/Crawllama) [文档](docs/README.md) | [快速入门](docs/getting-started/QUICKSTART.md) | [API 指南](docs/guides/API_USAGE.md) | [自适应跳跃](docs/getting-started/ADAPTIVE_HOPS_QUICKSTART.md) | [安全](SECURITY.md) | [更新日志](CHANGELOG.md) [项目网站](https://arn-c0de.github.io/Crawllama/) **具备 OSINT 和多跳推理能力的 AI 研究代理** 当前版本：`1.4.9`（改进与修复） `1.4.8` 版新增：[公司情报开发者文档](docs/osint/COMPANY_INTELLIGENCE.md) ## 目录 - [概述](#overview) - [功能特性](#features) - [图片](#images) - [快速入门](#quickstart) - [安装](#installation) - [使用](#usage) - [REST API](#rest-api) - [CLI 命令与选项](#cli-commands--options) - [项目结构](#project-structure) - [配置](#configuration) - [测试](#testing) - [插件开发](#plugin-development) - [技术栈](#technology-stack) - [文档](#documentation) - [路线图](#roadmap) - [性能](#performance) - [法律声明](#legal-notices) - [故障排除](#troubleshooting) - [支持与社区](#support-and-community) - [贡献](#contributing) - [许可证](#license) - [致谢](#credits) - [更多文档](#further-documentation) ## 概述 一个完全本地化、具备高级情报功能的 AI 研究代理： - OSINT 模块：电子邮件、电话和 IP 情报；社交媒体分析；高级搜索运算符 - 使用 LangGraph 进行复杂查询的多跳推理 - 基于查询复杂度的自适应代理选择（低/中/高） - 基于 FastAPI 的 REST API，便于集成 - 可扩展的插件系统 - 针对大上下文支持和异步执行的性能优化 ## 功能特性 ### 核心功能 - **自适应代理跳跃系统** – 根据查询复杂度（低/中/高）自动选择代理，基于置信度的升级，以及资源感知适应（v1.4.4 新增） - **自适应报告的 UI 设置** – 直接在交互式设置菜单中切换自适应情报报告（v1.4.4 新增） - **多跳推理** – 基于 LangGraph 的代理，具有多步骤工作流（路由 → 搜索 → 分析 → 后续 → 综合 → 批判） - **重启命令** – 无需退出程序即可重启代理 - **并行化** – 使用线程池进行多方面搜索，以提升性能 - **性能优化** – 支持 RTX 3080 的 16k 上下文；异步和并行处理 - **多源网络搜索** – DuckDuckGo、Brave Search、Serper API，支持回退机制 - **Wikipedia 集成** – 专用 Wikipedia 搜索（德语/英语） - **高级 RAG 系统** – 批处理、多查询和混合搜索（[RAG 分析](docs/guides/RAG_ANALYSIS.md)） - **智能缓存** – 基于 TTL 的哈希键、LRU 淘汰机制，以及可配置的最大大小（500MB） - **工具编排** – 通过 LLM 自动选择工具 - **交互式设置菜单** – 实时配置 LLM、搜索、RAG 和 OSINT - **上下文使用跟踪器** – 使用 tiktoken 实时监控 token 使用情况 - **健康监控仪表板** – 具有丰富 UI 的交互式系统监控 - **延迟加载** – 按需加载工具和插件 - **异步操作** – 使用 aiohttp 进行并行 HTTP 请求 - **资源监控** – 内存使用率、性能跟踪和自动垃圾回收 - **FastAPI REST API** – 8 个以上端点，带自动文档（`/query`、`/plugins`、`/stats`、`/health`）（参见 `app.py`） - **插件系统** – 动态加载和卸载插件 - **增强型 CLI** – Rich 格式化和 Markdown 输出 - **安装脚本** – `setup.bat`、`setup.sh`，支持自动配置 - 可选云端 LLM 支持 ### OSINT 功能 - **高级搜索运算符** – `site:`、`inurl:`、`intext:`、`filetype:`、`email:`、`phone:`、`ip:` - **电子邮件情报** – 验证、MX 记录、一次性邮箱检测和变体 - **电话情报** – 验证、运营商查询、国家检测和格式化 - **持久化存储** – 在 `clear` 操作后依然保留；存储电子邮件、电话、IP、用户名、域名和笔记 - **存储 CRUD** – 使用 `forget` 命令的完整 CRUD 功能 - **批处理** – 同时分析多个电子邮件或电话并生成汇总统计数据 - **IP 情报** – IPv4/IPv6 分析、地理位置、ISP 信息、安全信誉和 VPN 检测 - **社交情报** – 支持 12 个平台（GitHub、LinkedIn、Twitter、Instagram、Facebook、YouTube、Reddit、Pinterest、TikTok、Snapchat、Discord、Steam） - **AI 查询增强** – 查询变体、运算符建议、实体检测和自动类型检测 - **合规模块** – 频率限制、使用条款、审计日志和 robots.txt 合规性 - **隐私保护** – 道德抓取、使用跟踪；无需 API 密钥 - **安全搜索过滤器** – 可配置的结果质量（关闭/适中/严格） ### 安全与性能 - **代码质量** – 重构后的专注方法，提高可维护性 - **精确 Token 计数** – 集成 tiktoken 以进行精确的 token 计数 - **智能重试逻辑** – 基于 Tenacity 的重试，带有指数退避 - **频率限制** – 1 次请求/秒及 robots.txt 检查 - **回退系统** – API 故障时的自动回退机制 - **安全配置** – 加密存储 API 密钥 - **输出验证** – 清理 LLM 输出 - **域名黑名单** – 防止访问不受欢迎的域名 - **RTX 3080 优化** – 16k 上下文支持（qwen3:8b），增加缓存大小 - **Windows 控制台兼容性** – ASCII 输出和 UTF-8 编码，提供稳健的 CLI 体验（v1.4.4 新增） - **Clear-all 命令** – 从 CLI 即时重置会话、缓存和内存（v1.4.4 新增） ## 图片 ### 健康仪表板 - 实时系统监控 具有丰富终端 UI 的实时监控，显示系统指标、组件健康状况和性能跟踪。  ### 交互式 CLI 界面 CrawlLama 的自适应智能系统，具有自动代理选择和交互式命令功能。  ### 测试仪表板 GUI 基于 Tkinter 的测试管理界面，具有自动测试检测和实时进度跟踪功能。  ## 快速入门 ## 安装 **Windows:** 1. 下载 Crawllama 2. 解压到任意文件夹（例如 `C:\Crawllama`） 3. 从 [ollama.ai/download](https://ollama.ai/download) 安装 Ollama 4. 启动 Ollama 并加载模型： ``` ollama serve ollama pull qwen3:4b ``` 5. 在 Crawllama 文件夹中： ``` setup.bat run.bat ``` **Linux/macOS:** 1. 下载并解压： ``` wget https://github.com/arn-c0de/Crawllama/archive/refs/tags/v1.4.7-preview.zip unzip v1.4.7-preview.zip cd Crawllama-v1.4.7-preview ``` 2. 安装 Ollama： ``` curl -fsSL https://ollama.ai/install.sh | sh ollama serve & ollama pull qwen3:4b ``` 3. 设置并启动： ``` chmod +x setup.sh run.sh ./setup.sh ./run.sh ``` ### 选项 1：安装脚本（推荐用于 Git 安装） **Windows:** ``` setup.bat ``` **Linux/macOS:** ``` chmod +x setup.sh ./setup.sh ``` 注意：初始安装后，您必须在安装过程中至少选择一个 LLM 模型。如果已安装模型，可以跳过此步骤——否则，必须进行选择以避免测试程序出错。 安装脚本将会： - 检查 Python 版本（3.10+） - 创建虚拟环境 - 让您选择要安装的功能和 LLM 模型（核心组件始终安装） - 安装所有选定的依赖项 - 创建必要的目录 - 将 `.env.example` 复制为 `.env` - 检查 Ollama 状态 初始安装注意事项： 当在新创建的虚拟环境中首次运行 `pip install -r requirements.txt` 时，安装所有依赖项——特别是 `torch`、`sentence-transformers` 和科学库——可能需要 **5-10 分钟**（或更长，具体取决于网络和硬件）。请等待过程完成；之后，虚拟环境即可使用。 磁盘空间注意事项：安装后（包括 `venv`），项目通常需要约 **1.2-1.5 GB** 的可用磁盘空间（v1.4 版本约为 1.23 GB）。根据操作系统、Python 包（例如较大的 PyTorch/CUDA wheels）和其他模型，该值可能会有显著差异。如果存储空间有限，请预留充足的额外空间。 模型下载大小（近似值）： - `qwen3:4b` — 约 **2-4 GB**（取决于格式/量化） - `qwen3:8b` — 约 **8-12 GB** - `deepseek-r1:8b` — 约 **6-10 GB** - `llama3:7b` — 约 **6-9 GB** - `mistral:7b` — 约 **4-8 GB** - `phi3:14b` — 约 **12-20+ GB** 注意：模型大小因提供商、格式（FP16、INT8 量化等）和附加资源而异。量化模型（如 INT8）可以显著减小大小，而 FP32/FP16 或包含附加分词器/词表文件的模型则需要更多空间。如果同时使用大型模型或多个模型，请规划足够的额外存储空间。 ### 选项 2：手动安装 **前置条件：** - Python 3.10+ ([python.org](https://www.python.org/downloads/)) - Git ([git-scm.com](https://git-scm.com/downloads)) - Ollama ([ollama.ai/download](https://ollama.ai/download)) **Windows - 逐步操作：** ``` # 1. Clone repository git clone https://github.com/arn-c0de/Crawllama.git cd Crawllama # 2. 创建虚拟环境 python -m venv venv venv\Scripts\activate # 3. 安装依赖（耗时 5-10 分钟） pip install -r requirements.txt # 4. 创建目录 mkdir data\cache data\embeddings data\history logs plugins # 5. 配置 copy .env.example .env notepad .env # Optional: Add API keys # 6. 启动 Ollama（单独终端） ollama serve # 7. 加载模型（单独终端） ollama pull qwen3:4b # 8. 启动 Crawllama python main.py --interactive ``` **Linux/macOS - 逐步操作：** ``` # 1. Clone repository git clone https://github.com/arn-c0de/Crawllama.git cd Crawllama # 2. 创建虚拟环境 python3 -m venv venv source venv/bin/activate # 3. 安装依赖（耗时 5-10 分钟） pip install -r requirements.txt # 4. 创建目录 mkdir -p data/cache data/embeddings data/history logs plugins # 5. 配置 cp .env.example .env nano .env # Optional: Add API keys # 6. 安装并启动 Ollama curl -fsSL https://ollama.ai/install.sh | sh ollama serve & # 7. 加载模型 ollama pull qwen3:4b # 8. 启动 Crawllama python main.py --interactive ``` **安装故障排除：** | 问题 | 解决方案 | |---------|--------| | `python not found` | 安装 Python 3.10+：[python.org](https://www.python.org/downloads/) | | `pip install` 失败 | 运行 `python -m pip install --upgrade pip` | | `ollama: command not found` | 安装 Ollama：[ollama.ai/download](https://ollama.ai/download) | | `Connection refused`（Ollama） | 启动 Ollama：`ollama serve` | | `ModuleNotFoundError` | 激活虚拟环境：`venv\Scripts\activate`（Windows）或 `source venv/bin/activate`（Linux） | | 磁盘空间已满 | 确保至少有 5 GB 可用空间用于 venv + 模型 | ### 选项 3：Git Clone（快速安装） ``` # 1. Clone git clone https://github.com/arn-c0de/Crawllama.git cd Crawllama # 2. 虚拟环境 python -m venv venv source venv/bin/activate # Linux/macOS venv\Scripts\activate # Windows # 3. 依赖 pip install -r requirements.txt # 4. 目录 mkdir -p data/cache data/embeddings data/history logs plugins # 5. 配置 cp .env.example .env ``` ### Ollama 设置 ``` # 安装 Ollama curl -fsSL https://ollama.ai/install.sh | sh # Linux/macOS # 或从 https://ollama.ai/download # Windows # 启动 Ollama ollama serve # 加载模型 ollama pull qwen3:4b # 备选：deepseek-r1:8b, llama3:7b, mistral ``` ## 使用 ### 1. CLI - 交互模式 ``` python main.py --interactive # 或使用安装脚本 run.bat # Windows ./run.sh # Linux/macOS ``` ``` ╭──────────────────────────────────────────────────────────────╮ │ CrawlLama - Local Search and Response Agent │ │ Commands: │ │ clear - Reset session (history + cache) │ │ clear-cache - Clear cache only │ │ save - Manually save session │ │ load - Reload session │ │ stats - Display statistics │ │ status - Show context usage │ │ settings - Show/edit settings │ │ restart - Restart agent (reload config) │ │ exit, quit - Exit │ ╰──────────────────────────────────────────────────────────────╯ What is Machine Learning? ``` **新命令：** - `status` - 显示 token 使用情况和可用上下文容量 ``` status Context Usage Tracker ┏━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━┓ ┃ Source ┃ Tokens ┃ Share ┃ ┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━┩ │ Conversation │ 850 │ 8.5% │ │ Search Results │ 320 │ 3.2% │ │ Total Used │ 1,170 │ 11.7% │ │ Available │ 8,830 │ 88.3% │ │ Maximum │ 10,000 │ 100% │ └───────────────────┴───────────┴───────────┘ ``` - `settings` - 交互式配置编辑器 ``` settings Displays all settings and allows: • Category selection (llm, search, rag, cache, osint, all) • Change LLM model (qwen3:8b, deepseek-r1:8b, etc.) • Adjust temperature (0.0-1.0) • Configure max tokens (now 16,000 for RTX 3080+) • Change search region (de-de, us-en, wt-wt) • Configure OSINT max results & rate limits • Enable/disable RAG • Enable/disable cache • Save changes directly to config.json • Auto-restart after saving (optional) ``` - `restart` - 重启代理 ``` restart • Reloads config.json • Fully reinitializes agent • Optional session preservation • No session interruption ``` ### 2. 健康监控仪表板 ``` # Windows health-dashboard.bat # Linux/macOS python health-dashboard.py ``` 仪表板显示： - 系统健康状况（CPU、内存、磁盘、网络） - 组件状态（LLM、缓存、RAG、工具） - 性能指标（响应时间） - 错误日志（最后 10 个错误） - 自动刷新（每 5 秒） 交互命令： - `r` - 刷新（手动） - `c` - 清除错误日志 - `t` - 运行组件测试 - `q` - 退出 ### 3. 能搜索如何工作？ 代理自动决定**何时以及如何**搜索： #### 自动决策 ``` Who is the current German Chancellor? 1. LLM analyzes: "Requires current info" 2. Agent performs web search 3. LLM processes search results 4. Agent delivers up-to-date response ``` #### 针对性搜索的搜索运算符 **OSINT 搜索运算符：** ``` # 特定领域搜索 site:github.com machine learning # Email Intelligence email:john.doe@company.com # Phone Intelligence phone:"+49 151 12345678" # IP Intelligence (NEW!) ip:8.8.8.8 192.168.1.1 # Auto-detects as IP # Social Media Intelligence (12 Platforms) username:elonmusk @microsoft github # Auto-detects as username # 文件格式搜索 site:example.com filetype:pdf # URL 过滤器 inurl:documentation python # 内容中的文本 intext:"contact email" site:example.com ``` **组合搜索：** ``` # 多重操作符 site:linkedin.com inurl:profile "software engineer" # 使用减号排除 python programming -java # OR 连接符 site:github.com OR site:gitlab.com "machine learning" ``` 有关所有功能，请参阅 **[OSINT 使用指南](docs/osint/OSINT_USAGE.md)**。 ### 4. CLI - 直接查询 ``` # 标准查询（Agent 自动决定是否需要 Web Search） python main.py "What is Python?" # Multi-Hop Reasoning（用于复杂查询） python main.py --multihop "Compare Python and JavaScript for web development" # 离线模式（无 Web Search，仅 LLM 知识） python main.py --no-web "Explain photosynthesis" # 带搜索操作符的 OSINT search python main.py "site:github.com python projects" python main.py "email:contact@example.com" # 指定特定模型 python main.py --model llama3:7b "Who discovered Einstein?" ``` ### 5. FastAPI 服务器 ``` # 启动服务器 python app.py # 或使用启动脚本 run_api.bat # Windows ./run_api.sh # Linux/macOS # 或手动 uvicorn app:app --host 0.0.0.0 --port 8000 ``` **API 文档：** http://localhost:8000/docs **可用端点：** **查询与推理：** - `POST /query` - 执行标准或多跳查询 - `POST /osint/query` - 带运算符的 OSINT 查询（email:、phone:、ip: 等） **内存存储（CRUD）：** - `GET /memory` - 检索所有存储的条目 - `POST /memory/remember` - 存储值（电子邮件、电话、IP、用户名、域名、笔记） - `GET /memory/recall/{category}` - 检索类别（电子邮件、电话、IP 等） - `DELETE /memory/forget` - 删除单个值、类别或所有内容 - `GET /memory/stats` - 内存存储统计 **会话管理：** - `POST /session/clear` - 重置会话 - `POST /session/save` - 保存会话 - `POST /session/load` - 加载会话 **缓存：** - `POST /cache/clear` - 清除缓存 - `GET /cache/stats` - 缓存统计 **配置：** - `GET /config` - 检索当前配置 - `PATCH /config` - 修改配置（llm、search、rag、cache、osint） - `GET /context/status` - Token 使用情况与上下文状态 **插件与工具：** - `GET /plugins` - 列出可用插件 - `POST /plugins/{name}/load` - 加载插件 - `POST /plugins/{name}/unload` - 卸载插件 - `GET /tools` - 列出可用工具 **系统：** - `GET /health` - 健康检查（代理、监控、组件） - `GET /stats` - 系统统计（代理统计、资源、性能） - `GET /security-info` - 安全配置（频率限制、功能） **API 安全（v1.4.2+）：** API 默认受多项安全功能保护： - **API 密钥认证** - 需要 X-API-Key 标头 - **频率限制** - 60 次请求/分钟（可配置） - **输入验证** - 基于 Pydantic 的验证 - **查询清理** - 防止注入攻击 - **请求日志** - 记录所有请求 - **CORS 保护** - 可配置的来源 - **受信任主机中间件** - 主机标头验证 **设置：** ``` # 1. 在 .env 中设置 API key CRAWLLAMA_API_KEY=your_secure_api_key_min_32_chars # 2. 用于本地开发（不带 API key） CRAWLLAMA_DEV_MODE=true # 3. 调整速率限制（可选） RATE_LIMIT=100 # 4. 配置 CORS origins（可选） ALLOWED_ORIGINS=http://localhost:3000,http://localhost:8080 ``` **使用 API 密钥：** ``` # 带 API key header curl -X POST http://localhost:8000/query \ -H "Content-Type: application/json" \ -H "X-API-Key: your_api_key_here" \ -d '{"query": "test"}' # 或在开发模式下（不带 API key） export CRAWLLAMA_DEV_MODE=true python app.py ``` **示例请求：** ``` # 标准查询（Agent 根据需要自动使用 Web Search） curl -X POST http://localhost:8000/query \ -H "Content-Type: application/json" \ -d '{ "query": "What is Machine Learning?", "use_multihop": false }' # Multi-hop query（用于复杂分析） curl -X POST http://localhost:8000/query \ -H "Content-Type: application/json" \ -d '{ "query": "Compare Python and JavaScript", "use_multihop": true, "max_hops": 3 }' # 带搜索操作符的 OSINT search curl -X POST http://localhost:8000/query \ -H "Content-Type: application/json" \ -d '{ "query": "site:github.com python machine-learning", "use_multihop": false }' # 检索统计信息 curl http://localhost:8000/stats # 列出插件 curl http://localhost:8000/plugins # 加载插件 curl -X POST http://localhost:8000/plugins/example_plugin/load ``` ## CLI 命令与选项 ### 基本选项 | 选项 | 描述 | |--------|--------------| | `--interactive` | 交互模式 | | `--debug` | 启用调试日志 | | `--no-web` | 离线模式（无网络搜索） | | `--model MODEL` | 选择 Ollama 模型 | | `--stats` | 显示系统统计 | | `--clear-cache` | 清除缓存 | ### 高级选项（v1.1） | 选项 | 描述 | |--------|--------------| | `--multihop` | 启用多跳推理 | | `--max-hops N` | 最大推理步骤（1-5） | | `--api` | 启动 API 服务器 | | `--plugins` | 列出可用插件 | | `--load-plugin NAME` | 加载插件 | | `--help-extended` | 显示扩展帮助 | | `--examples` | 显示使用示例 | | `--setup-keys` | 安全设置 API 密钥 | ### 交互命令 | 命令 | 描述 | |--------|--------------| | `exit`、`quit` | 退出程序 | | `clear` | 清屏 | | `stats` | 显示统计 | | `help` | 显示帮助 | ## REST API CrawlLama 提供完整的 REST API，以便集成到自定义应用程序中。 ### 启动 API 服务器 **Windows:** ``` run_api.bat ``` **Linux/macOS:** ``` ./run_api.sh ``` 或手动： ``` uvicorn app:app --host 0.0.0.0 --port 8000 ``` ### 快速入门 **1. 启动 API 服务器** ``` run_api.bat ``` **2. 打开 API 文档** - 交互式文档：http://localhost:8000/docs - ReDoc：http://localhost:8000/redoc **3. 发送查询** ``` curl -X POST http://localhost:8000/query \ -H "X-API-Key: your-key" \ -H "Content-Type: application/json" \ -d '{"query": "What is Python?", "use_tools": false}' ``` ### 主要端点 - `POST /query` - 执行查询（带/不带网络搜索、多跳） - `GET /health` - 健康检查 - `GET /stats` - 系统统计 - `POST /memory/remember` - 存储数据（OSINT） - `GET /memory/recall/{category}` - 检索数据 - `GET /plugins` - 管理插件 - `POST /cache/clear` - 清除缓存 ### 认证 在 `.env` 中设置 API 密钥： ``` CRAWLLAMA_API_KEY=your-secret-key-here ``` 或用于测试： ``` CRAWLLAMA_DEV_MODE=true ``` ### 完整文档 [API 使用指南](docs/guides/API_USAGE.md) - 包含示例的完整 API 文档 ## 项目结构 完整且最新的项目结构可在此处找到：[docs/development/PROJECT_STRUCTURE.md](docs/development/PROJECT_STRUCTURE.md) ## 配置 ### config.json ``` { "llm": { "base_url": "http://127.0.0.1:11434", "model": "qwen3:8b", "temperature": 0.7, "max_tokens": 10000, "stream": true }, "search": { "provider": "duckduckgo", "max_results": 5, "timeout": 10 }, "rag": { "enabled": true, "batch_size": 100, "max_workers": 4 }, "cache": { "enabled": true, "ttl_hours": 24, "max_size_mb": 500, "clear_on_startup": false }, "osint": { "max_results": 20, "email_search_limit": 50, "phone_search_limit": 50, "general_osint_limit": 100 }, "multihop": { "enabled": true, "max_hops": 3, "confidence_threshold": 0.7, "enable_critique": true }, "plugins": { "example_plugin": { "enabled": true } }, "security": { "rate_limit": 1.0, "max_context_length": 8000, "check_robots_txt": true } } ``` **推荐的 `max_tokens` 设置：** | GPU/硬件 | 推荐 max_tokens | 模型 | |-------------|----------------------|--------| | RTX 3080+ (10GB+) | 10,000 - 16,000 | qwen3:8b, deepseek-r1:8b | | RTX 3060/3070 (8GB) | 6,000 - 8,000 | qwen3:4b, llama3:7b | | 仅 CPU | 2,000 - 4,000 | qwen3:4b | **提示：** 使用 `status` 命令实时监控您的 token 使用情况！ ### .env（可选） ``` # API Keys（可选） BRAVE_API_KEY=your_brave_api_key SERPER_API_KEY=your_serper_api_key # 代理（可选） HTTP_PROXY=http://proxy:port HTTPS_PROXY=https://proxy:port ``` ## 测试 ``` # 所有测试 pytest tests/ -v # 带覆盖率 pytest --cov=core --cov=tools --cov=utils tests/ # 特定测试 pytest tests/test_multihop_reasoning.py -v pytest tests/test_error_simulation.py -v # 带调试输出 pytest tests/ -v --log-cli-level=INFO ``` ## 插件开发 ### 创建一个简单的插件 ``` # plugins/my_plugin.py from core.plugin_manager import Plugin, PluginMetadata class MyPlugin(Plugin): def get_metadata(self) -> PluginMetadata: return PluginMetadata( name="MyPlugin", version="1.0.0", description="My custom plugin", author="Your Name", dependencies=[] ) def get_tools(self): return [self.my_tool] def my_tool(self, input: str) -> str: return f"Processed: {input}" ``` **详见：** [插件教程](docs/guides/PLUGIN_TUTORIAL.md) ## 技术栈 ### 核心 - **LLM**：Ollama（qwen3:4b、deepseek-r1:8b、llama3、mistral） - **编排**：LangGraph（多跳推理） - **网络搜索**：duckduckgo-search、Brave API、Serper API - **RAG**：ChromaDB + Sentence Transformers ### 后端 - **API**：FastAPI + Uvicorn - **数据库**：SQLite（会话） - **异步**：aiohttp、asyncio - **监控**：psutil ### 工具 - **HTML 解析**：BeautifulSoup4 - **CLI**：Rich（格式化） - **重试**：Tenacity - **安全**：cryptography ### 开发 - **测试**：pytest、pytest-mock、pytest-cov - **CI/CD**：GitHub Actions（计划中） ## 文档 ### 用户指南 - [安装指南](docs/getting-started/INSTALLATION.md) - 详细安装说明 - [LangGraph 指南](docs/guides/LANGGRAPH_GUIDE.md) - 多跳推理 - [插件教程](docs/guides/PLUGIN_TUTORIAL.md) - 插件开发 - [健康监控](docs/health/HEALTH_MONITORING.md) - 系统监控 ### 开发者文档 - [项目结构](docs/development/PROJECT_STRUCTURE.md) - 项目概览 - `docs/development/RELEASE_PROCESS.md` - 发布流程（计划中/维护者说明） - 测试 - 有关示例，请参阅 `tests/` ### API 文档 - Swagger UI：http://localhost:8000/docs - ReDoc：http://localhost:8000/redoc ## 路线图 ### 第一阶段：核心功能（已完成） - Ollama 集成 - 网络搜索（DuckDuckGo） - 工具编排 - 基础 RAG 与缓存 - 使用 Rich 的 CLI ### 第二阶段：稳健性（已完成） - 回退系统 - 使用 tenacity 的重试逻辑 - 频率限制与 robots.txt - 域名黑名单 - 带代理支持的安全获取 - 多源网络搜索 - 全面测试（覆盖率 80%+） ### 第三阶段：智能化（已完成 - v1.1） - 使用 LangGraph 的多跳推理 - RAG 优化（批处理、多查询、混合） - 并行化 - 工具/插件的延迟加载 - 异步 HTTP 操作 - 内存与性能监控 ### 第四阶段：生产就绪（已完成 - v1.1） - FastAPI REST API - 多用户支持 - 插件系统 - 增强型 CLI - 安装脚本 - Systemd 服务 - 全面文档 ### 第五阶段：未来（计划中） - [] GUI（Streamlit/Gradio） - [] GraphQL API - [] 用于生产环境的 Redis 缓存 - [] Kubernetes 部署 - [] 监控仪表板 - [] 多语言支持 - [] 语音界面 ## 贡献 欢迎贡献！ **开发工作流：** 1. Fork 本仓库 2. 创建功能分支（`git checkout -b feature/amazing-feature`） 3. 提交更改（`git commit -m 'Add amazing feature'`） 4. 推送到分支（`git push origin feature/amazing-feature`） 5. 创建 Pull Request **编码规范：** - 符合 PEP8 规范 - 使用类型提示 - 为所有函数编写文档字符串 - 为新功能编写测试 ## 性能 ### 基准测试（基于 i7-8700K，32GB RAM） | 操作 | 平均值 | 备注 | |-----------|--------------|----------| | 标准查询 | 2-5s | 无网络搜索 | | 带网络搜索的查询 | 5-10s | 3-5 个结果 | | 多跳（3 跳） | 15-30s | 复杂 | | RAG 搜索 | <1s | 5 个结果 | | API 请求 | <100ms | 无工具 | ### 资源占用 - **内存**：200-500 MB（标准），500-800 MB（含 RAG） - **CPU**：10-30%（空闲），50-80%（活动） - **磁盘**：~100 MB（代码），可变（缓存/嵌入） ## 法律声明 ### 网络抓取 - 遵守 `robots.txt` - 频率限制（默认 1 次请求/秒） - 可识别的用户代理 - 用户有责任遵守当地法律法规 ### 数据隐私 - 所有数据均在本地处理 - 无云服务 - 完全控制日志/缓存 - 会话数据加密（可选） ### API 密钥 - Brave Search API：[brave.com/search/api](https://brave.com/search/api) - Serper API：[serper.dev](https://serper.dev) ## 故障排除 ### Ollama 无法连接 ``` # 检查状态 curl http://127.0.0.1:11434/api/tags # 启动 Ollama ollama serve ``` ### 导入错误 ``` # 重装依赖 pip install -r requirements.txt # 或重新运行安装 ./setup.sh # or setup.bat ``` ### ChromaDB 错误 ``` # 删除 Embeddings rm -rf data/embeddings/ # 重启 python main.py ``` ### API 频率限制 ``` # 在 config.json 中调整 "security": { "rate_limit": 2.0 # 2 req/s } ``` ## 支持与社区 - **问题反馈**：[GitHub Issues](https://github.com/arn-c0de/Crawllama/issues) - **支持**：[crawllama.support@protonmail.com](mailto:crawllama.support@protonmail.com) - **直接联系**：[arn-c0de@protonmail.com](mailto:arn-c0de@protonmail.com) - **安全/泄露**：[crawllama.support@protonmail.com](mailto:crawllama.support@protonmail.com)（通过 Proton Mail 加密） ## 许可证 **Crawllama 许可证（非商业）** – 免费用于使用和开发，但不允许商业销售。 **允许：** - 个人使用 - 教育与研究 - 修改与分享（非商业） - 为项目做贡献 **不允许：** - 出售软件 - 商业用途 - 集成到付费产品中 详见 [LICENSE](LICENSE)。 ## 致谢 构建于： - [Ollama](https://ollama.ai) - 本地 LLM - [LangGraph](https://github.com/langchain-ai/langgraph) - 代理编排 - [FastAPI](https://fastapi.tiangolo.com) - REST API - [ChromaDB](https://www.trychroma.com) - 向量数据库 - [Rich](https://github.com/Textualize/rich) - 终端格式化## 更多文档 - **[文档概览](docs/README.md)** - **快速入门与安装** - [QUICKSTART.md](docs/getting-started/QUICKSTART.md) – 5 分钟快速入门 - [INSTALLATION.md](docs/getting-started/INSTALLATION.md) – 详细安装说明 - **功能指南** - [LANGGRAPH_GUIDE.md](docs/guides/LANGGRAPH_GUIDE.md) – 多跳推理 - [OSINT_USAGE.md](docs/osint/OSINT_USAGE.md) – OSINT 功能 - [OSINT_CONTEXT_USAGE.md](docs/osint/OSINT_CONTEXT_USAGE.md) – OSINT 上下文使用 - [SOCIAL_INTELLIGENCE.md](docs/osint/SOCIAL_INTELLIGENCE.md) – 社交情报 - [PLUGIN_TUTORIAL.md](docs/guides/PLUGIN_TUTORIAL.md) – 插件开发 - [HALLUCINATION_DETECTION.md](docs/guides/HALLUCINATION_DETECTION.md) – 幻觉检测 - [SEARCH_LIMITATIONS.md](docs/guides/SEARCH_LIMITATIONS.md) – 搜索限制 - **健康监控** - [HEALTH_MONITORING.md](docs/health/HEALTH_MONITORING.md) – 健康系统 - [HEALTH_DASHBOARD.md](docs/health/HEALTH_DASHBOARD.md) – 仪表板使用 - [HEALTH_FEATURES.md](docs/health/HEALTH_FEATURES.md) – 可用功能 - [DASHBOARD_STARTER.md](docs/health/DASHBOARD_STARTER.md) – 仪表板入门 - **维护者文档** - `docs/development/RELEASE_PROCESS.md` – 发布流程（计划中/维护者说明） - [SECRET_LEAK_RESPONSE.md](docs/security/SECRET_LEAK_RESPONSE.md) – 密钥泄露响应计划 - `docs/development/PRE_RELEASE_CHECK.md` – 发布前检查清单（计划中/维护者说明） - [PROJECT_STRUCTURE.md](docs/development/PROJECT_STRUCTURE.md) – 项目结构 *最后更新：2026-02-12*

标签：AI风险缓解, ESC4, ESC8, LLM评估, Ollama, OSINT, Python, RAG, REST API, Ruby, 人工智能, 企业情报, 多跳推理, 实时处理, 密码管理, 情报分析, 无后门, 本地大模型, 检索增强生成, 用户模式Hook绕过, 知识库, 社会工程学, 网络安全, 网络诊断, 自动问答, 调试插件, 逆向工具, 隐私保护