🚀 JustSearch: 智能 AI 深度搜索助手

中文 | English

JustSearch 是一款基于大语言模型（LLM）和自动化浏览器技术的深度搜索工具。它不仅仅是一个搜索界面，更是一个能够像人类一样"思考、搜索、阅读、总结"的智能代理。它能自动拆解复杂问题，深入网页正文提取关键信息，并生成带有精确引用的详尽答案。

💡 为什么选择 JustSearch？

传统的搜索引擎往往只给你一系列链接，而 JustSearch 会：

1. 深度理解：利用 LLM 拆解您的意图，不只是关键词匹配。
2. 真机阅读：通过 Playwright 模拟真人打开网页，绕过简单的反爬，获取正文。
3. 事实核查：在生成答案时强制要求标注引用，拒绝 AI 幻觉。
4. 自主迭代：如果初次搜索结果不足以回答，它会自己决定"再搜一次"。

✨ 核心特性

• 🎯 任务多级拆解：自动分析用户意图，将复杂问题拆解为多个搜索查询或直接访问特定 URL。
• 🕵️ 深度爬取与分析：模拟真实浏览器行为进入网页抓取正文。支持交互模式，能自动识别并点击"阅读更多"、"展开全文"等按钮（含中文按钮识别）。
• 🔄 迭代式搜索逻辑：AI 会评估当前获取的信息是否足以回答问题。如果不足，会自动发起补充搜索，直到获取足够证据。
• 📝 自动标注引用：生成答案时会严格标注来源编号 [1], [2]，并在文末提供对应的原始链接，确保信息真实可靠、可追溯。
• 🛡️ 浏览器反爬规避：集成 playwright-stealth 模拟真实人类行为，降低触发验证码（CAPTCHA）的概率。
• 🎨 现代 Web UI：支持流式输出（Streaming）、实时搜索过程可视化、对话历史管理（支持重命名）、深色/浅色模式切换。
• 🔐 安全认证：自动生成 Bearer Token 保护 API 与浏览器控制通道；本机访问会由服务端自动注入，无需额外配置。
• 🛡️ SSRF 防护：阻止对内网地址（含 IPv4-mapped IPv6 和代理/VPN 虚拟 IP 段）的访问，防止服务端请求伪造。
• 🐙 GitHub 深度优化：针对 GitHub 用户和仓库页面进行了专门的爬取逻辑优化，更准确地获取星数、活跃度等信息。
• 🔀 多模型切换：支持配置多个模型 ID（逗号分隔），在对话界面顶部实时切换。
• 🤖 验证码实时交互：搜索过程中遇到验证码时，UI 自动弹出浏览器实时画面，用户点击即可解决，无需中断流程。
• 📥 对话导出：支持将对话记录导出为 Markdown 文件，方便保存和分享。
• 🌓 跟随系统主题：支持浅色、深色、跟随系统三种主题模式。
• 🔍 多搜索引擎：支持 DuckDuckGo、Google、Bing、搜狗、Brave Search、SearXNG 六个搜索引擎。

🛠️ 技术栈

• 后端: Python 3.10+, FastAPI, Playwright (Headless Chromium)
• AI 模型: 兼容 OpenAI API 协议（支持 DeepSeek, GPT-4, Claude, NVIDIA NIM, GLM 等）
• 前端: 原生 JS (ES6 Modules), CSS3, Markdown-it, DOMPurify
• 部署: Docker / Docker Compose / 本地 Python 环境

🚀 快速启动

我们提供了一键部署脚本，支持 Docker 和本地环境。推荐使用 Docker 以获得最佳体验。

1. 克隆项目

git clone https://github.com/yeahhe365/JustSearch.git
cd JustSearch

2. 一键部署

Mac / Linux 用户

chmod +x deploy.sh
./deploy.sh

Windows 用户

双击运行 deploy.bat。

脚本逻辑说明：

1. 优先检查 Docker 环境，若存在则自动构建镜像并启动容器。
2. 若无 Docker，则自动回退至本地 Python 环境，创建虚拟环境、安装依赖并启动服务。

3. 访问与配置

1. 打开浏览器访问 http://localhost:8000。
   • 首次访问时，服务端会自动注入认证 Token，无需手动输入。
   • 仅在服务重启后 Token 变更时，本机页面会刷新到新 Token。
   • 如果需要从其他设备访问，请在目标 URL 后带上 ?token=<backend/.auth_token 中的值>。
2. 点击页面左下角的 设置 ⚙️ 按钮。
3. 输入您的 API Key 和 Base URL。
   • 默认配置为 DeepSeek API（https://api.deepseek.com/v1，模型 deepseek-v4-pro）。
   • 也支持 OpenAI、NVIDIA NIM、Claude、任何兼容 OpenAI 协议的 API 服务。
   • 💡 提示：API Key 支持输入多个（用英文逗号分隔），程序会自动轮询使用，适合多 Key 负载均衡。
4. 在 模型 ID 中填入模型名称，支持多个模型（逗号分隔），保存后可在对话界面顶部下拉切换。
5. 开始提问！

📦 手动安装指南 (针对开发者)

如果您希望手动控制开发环境：

1. 环境准备

python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r backend/requirements.txt

2. 安装浏览器内核

playwright install chromium

3. 运行服务

# 使用脚本运行
./run.sh

# 或手动启动
python3 -m uvicorn backend.app.main:app --host 0.0.0.0 --port 8000 --reload

环境变量

Docker 部署

docker-compose up -d

访问 http://localhost:8000。认证 Token 会自动注入到本机页面中，无需手动配置；远程访问请显式提供 token。

🔄 更新指南

如果您需要更新到最新版本，请执行以下步骤：

1. 获取最新代码

git pull

2. 重新部署

Docker 用户 (推荐)

直接运行：

./deploy.sh

或者手动运行：

docker-compose up -d --build

注意：使用 --build 参数确保 Docker 重新构建镜像以应用最新的代码和依赖变更。运行数据保存在 data/ 和 user_data/ 中，会通过 Docker volume 保留。

本地 Python 用户

./deploy.sh

或者手动更新：

source venv/bin/activate
pip install -r backend/requirements.txt
playwright install chromium

🤖 工作流程详解

JustSearch 采用多阶段迭代流程，确保回答的深度和准确性：

1. Phase I: 分析 (Analysis) - LLM 接收问题，决定是进行关键词搜索还是直接访问特定链接。
2. Phase II: 搜索 (Search) - 在 DuckDuckGo / Google / Bing 等引擎执行并发搜索。
3. Phase III: 评估 (Assess) - AI 筛选出最相关的多个结果进行深度阅读。评估时会优先选择官方权威来源。
4. Phase IV: 爬取与交互 (Crawl & Interact) - 浏览器进入页面抓取全文。如果开启"交互模式"，AI 会自动点击潜在的内容展开按钮。
5. Phase V: 生成 (Generate) - 融合所有来源，生成带引用的结构化答案。如果信息不足，则返回 Phase I 重新迭代。

🛠️ 实用工具：解决验证码 (CAPTCHA)

自动解决（推荐）

搜索过程中如果遇到验证码，JustSearch 会自动弹出浏览器实时画面窗口。您只需在弹窗中点击完成验证，搜索会自动继续。

手动预登录

如果您希望提前保存 Cookies 以减少验证码出现频率：

python tools/manual_login.py

这会启动一个可见的 Chrome 窗口。登录您的常用搜索账号并完成一次搜索验证，JustSearch 的后台爬虫将共享这些登录状态。

📂 项目结构

JustSearch/
├── backend/
│   ├── app/
│   │   ├── main.py              # FastAPI 入口，路由定义
│   │   ├── workflow.py          # 搜索工作流引擎（迭代式搜索核心）
│   │   ├── llm_client.py        # LLM 客户端（任务分析/评估/生成/交互决策）
│   │   ├── openai_client.py     # OpenAI 兼容客户端构造
│   │   ├── browser_manager.py   # 浏览器搜索引擎封装
│   │   ├── browser_context.py   # 全局浏览器生命周期与并发控制
│   │   ├── page_crawler.py      # 页面正文爬取与 GitHub 页面优化
│   │   ├── crawler/             # URL 安全校验与搜索引擎重定向解析
│   │   ├── search_result_cleanup.py # 搜索结果标题/内部页过滤
│   │   ├── engine_health.py     # 搜索引擎健康度与自动降级
│   │   ├── interaction.py       # 用户交互会话管理（验证码等）
│   │   ├── database.py          # SQLite 模型、对话历史、设置持久化
│   │   ├── legacy_migration.py  # 旧 JSON 数据一次性迁移
│   │   ├── auth.py              # Token 认证与 HTML 启动参数注入
│   │   ├── routers/             # API 路由（chat/history/settings/stats）
│   │   ├── prompts.py           # LLM Prompt 模板
│   │   └── search_engine.py     # 搜索引擎 CSS 选择器配置加载
│   ├── static/
│   │   ├── css/style.css        # 样式入口，按顺序导入 sections/
│   │   ├── css/sections/        # base/sidebar/chat/modal/markdown/responsive 等样式分层
│   │   ├── js/
│   │   │   ├── main.js          # 前端启动编排
│   │   │   └── modules/         # api/auth/chat/history/sidebar/settings/browser/source-renderer.js/ui 等模块
│   │   └── index.html
│   ├── settings.json.example    # 配置模板
│   └── requirements.txt
├── data/                        # SQLite 数据库运行目录（自动创建）
├── tools/
│   └── manual_login.py          # 手动登录脚本（保存 Cookies）
├── user_data/                   # 浏览器持久化数据 (自动创建)
├── Dockerfile                   # Docker 构建文件
├── docker-compose.yml
├── deploy.sh / deploy.bat       # 一键部署脚本 (推荐)
└── run.sh                       # 本地启动脚本

🤝 贡献

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建功能分支：git checkout -b feature/your-feature
3. 提交更改：git commit -m "feat: your feature"
4. 推送分支：git push origin feature/your-feature
5. 创建 Pull Request

⚙️ 环境变量配置

📄 开源协议

本项目采用 MIT License 协议。

友链

• Linux.do：也称 L 站，是一个活跃的中文技术社区，围绕 AI、软件开发、资源分享与前沿资讯展开讨论；社区愿景是“新的理想型社区”，社区文化是“真诚、友善、团结、专业，共建你我引以为荣之社区”。