ShadowCrawl

CortexScout (cortex-scout) — 面向 AI Agent 的搜索与网页提取引擎

CortexScout 是 Cortex-Works 生态系统中的深度研究与网页提取模块。

专为需要高效利用 token 检索网页、可靠处理反机器人机制，并可选用人在回路（HITL）回退方案的 Agent 工作负载而设计。

---

概述

CortexScout 提供一个可自托管的 Rust 单一二进制文件，通过 MCP（stdio）和可选的 HTTP 服务提供搜索、提取和有状态浏览器自动化功能。输出格式经过结构化处理，并针对下游大模型进行了优化。

它通过逐级回退机制处理网页检索中的常见故障场景（速率限制、机器人验证、JavaScript 密集型页面）：原生检索 → Chromium CDP 渲染 → 有状态端到端测试 → HITL 工作流。

---

工具（功能一览）

领域	MCP 工具 / 功能
搜索	web_search（发现 URL）或 web_search(include_content=true)（一次调用完成搜索与内容获取）
抓取与爬取	`web_fetch(mode="single"
提取	extract_fields（主要的结构化提取工具）
自动化	scout_browser_automate / browser_automate（有状态全能工具）、scout_agent_profile_auth、scout_browser_close
反机器人处理	CDP 渲染、代理轮换、针对拦截的重试
HITL	visual_scout、`hitl_web_fetch(auth_mode="challenge"
记忆	memory_search（由 LanceDB 支持的研究历史记录）
深度研究	deep_research（多跳搜索 + 抓取 + 综合分析）

为兼容性保留了旧名称，可继续调用（web_search_json、web_fetch_batch、web_crawl、fetch_then_extract、human_auth_session）。Agent 应优先使用上述统一的主要工具。

生态集成

CortexScout 目前作为独立工具运行，但设计上支持与 CortexDB 和 CortexStudio 集成，以实现多 Agent 扩展、检索产物共享和集中治理。

---

🎭 “Playwright 杀手”（有状态浏览器自动化）

CortexScout 内置了专为 AI Agent 设计的有状态 CDP 自动化引擎，旨在彻底取代 Playwright 或 Cypress 等重量级框架，用于端到端测试工作流。

• 静默全能工具（scout_browser_automate）：Agent 无需调用数十种浏览器工具，只需传入一个 steps 数组。运行时现在可通过一次调用涵盖 Playwright 风格的操作类别：导航、悬停／点击／输入／等待、基于定位器的操作、断言、标签页、截图／PDF、文件上传、表单填写、对话框策略、坐标鼠标操作、路由模拟、控制台／网络捕获，以及 Cookie／存储的增删改查。
• 持久化 Agent 配置文件：自动化在后台静默运行（--headless=new），使用专用的隔离配置文件（~/.cortex-scout/agent_profile）。它会在多次工具调用之间保留 Cookie、localStorage 和会话状态，同时避免与当前桌面浏览器发生 SingletonLock 冲突。
• QA 模拟、跟踪与验证引擎：Agent 可以安装路由模拟（mock_api、route_list、unroute），并覆盖／剥除响应头；跟踪流程（trace_start、trace_stop、trace_export）；捕获控制台／网络日志；创建浏览器状态检查点；并运行基于 CSS 和定位器的断言，以及 Playwright 风格的验证辅助工具。
• Agent 身份验证入口（scout_agent_profile_auth）：如果静默 Agent 在新域名上遇到 CAPTCHA 或复杂的 OAuth 登录（例如 Google／Microsoft），此工具会在可见窗口中启动 Agent 的配置文件。你只需解决一次 CAPTCHA，Cookie 就会保存下来，之后 Agent 将始终恢复静默自动化。

Playwright 风格覆盖范围一览

功能类别	Cortex Scout 操作
导航和输入	navigate、navigate_back、click、hover、type、press_key、scroll、wait_for、wait_for_selector、wait_for_locator
定位器和验证	click_locator、type_locator、assert、assert_locator、generate_locator、verify_element_visible、verify_text_visible、verify_list_visible、verify_value
标签页和媒体	tabs、resize、screenshot、snapshot、pdf_save、file_upload、fill_form、handle_dialog
网络和模拟	network_tap、network_dump、network_state_set、mock_api、route_list、unroute
浏览器状态	storage_clear、storage_state_export、storage_state_import、storage_checkpoint、storage_rollback、cookie_*、localstorage_*、sessionstorage_*
底层指针控制	mouse_click_xy、mouse_down、mouse_move_xy、mouse_drag_xy、mouse_up、mouse_wheel

与原生 Playwright MCP 相比，主要取舍在于封装方式，而非功能范围：Cortex Scout 将浏览器功能集成在一个有状态的全能工具中，让 Agent 用更少的轮次和更少的令牌来协调多步骤流程。

反机器人效能与验证

此仓库包含捕获的证据文件，用于验证针对具有代表性的受保护目标的提取和 HITL 流程。

目标	防护措施	证据	备注
LinkedIn	Cloudflare + 身份验证	JSON · 片段	提取受身份验证保护的列表
Ticketmaster	Cloudflare Turnstile	JSON · 片段	处理质询后的提取
Airbnb	DataDome	JSON · 片段	在机器人防护下处理大量结果
Upwork	reCAPTCHA	JSON · 片段	获取受保护的列表
Amazon	AWS Shield	JSON · 片段	提取搜索结果
nowsecure.nl	Cloudflare	JSON	已验证手动返回路径

有关方法和原始输出，请参阅 proof/README.md。

---

快速开始

选项 A — 预构建二进制文件

从 GitHub Releases 下载最新的发布资产，并运行以下其中一个：

• cortex-scout-mcp — MCP stdio 服务（推荐用于 VS Code / Cursor / Claude Desktop）
• cortex-scout — 可选的 HTTP 服务（默认端口 5000；可通过 --port、PORT 或 CORTEX_SCOUT_PORT 覆盖）

健康检查（HTTP 服务）：

./cortex-scout --port 5000
curl http://localhost:5000/health

选项 B — 从源代码构建

首先安装 protoc。lance-encoding 在发布构建期间使用 Protocol Buffers，因此 protoc 必须位于 PATH 中。

• macOS：brew install protobuf
• Ubuntu/Debian：sudo apt-get install -y protobuf-compiler
• Fedora：sudo dnf install -y protobuf-compiler

基本构建（搜索、抓取、深度研究、记忆）：

git clone https://github.com/cortex-works/cortex-scout.git
cd cortex-scout
cargo build --release --manifest-path mcp-server/Cargo.toml --bin cortex-scout-mcp

由于清单路径是显式指定的，因此可以在仓库根目录运行此命令。

完整构建（包含 hitl_web_fetch / 可视浏览器 HITL）：

cargo build --release --manifest-path mcp-server/Cargo.toml --all-features --bin cortex-scout-mcp

如果还需要可选的 HTTP 服务二进制文件，请使用 cargo build --release --bin cortex-scout 显式构建。

本地 MCP 冒烟测试：

python3 publish/ci/smoke_mcp.py

此命令会针对本地 cortex-scout-mcp 二进制文件运行一个以换行符分隔的 JSON-RPC stdio 会话，并使用安全的示例输入测试主要的公开工具。

---

MCP 集成（VS Code / Cursor / Claude Desktop）

在 MCP 配置中添加一个服务条目。

VS Code（mcp.json — 全局配置，或在 settings.json 中使用 mcp.servers）：

下方的硬超时保护变量是 MCP 配置中的必需项。它们是安全保障，可防止异常页面、卡住的浏览器启动或停滞的抓取阶段无限期占用整个 MCP 会话。

// mcp.json (global): top-level key is "servers"
// settings.json (workspace): use "mcp.servers" instead
{
  "servers": {
    "cortex-scout": {
      "type": "stdio",
      "command": "env",
      "args": [
        "RUST_LOG=warn",
        "CORTEX_SCOUT_TOOL_TIMEOUT_SECS=90",
        "CORTEX_SCOUT_TOOL_TIMEOUT_SECS_SCRAPE_URL=90",
        "CORTEX_SCOUT_TOOL_TIMEOUT_SECS_SEARCH_STRUCTURED=120",
        "CORTEX_SCOUT_TOOL_TIMEOUT_SECS_VISUAL_SCOUT=45",
        "CORTEX_SCOUT_BROWSER_LAUNCH_TIMEOUT_SECS=12",
        "CORTEX_SCOUT_BROWSER_TAB_PROBE_TIMEOUT_SECS=4",
        "CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS=20",
        "CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS_CDP_INITIAL_ATTEMPT=25",
        "CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS_CDP_RETRY_ATTEMPT=25",
        "CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS_FORCED_CDP_ATTEMPT=25",
        "CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS_NATIVE_CDP_FALLBACK=25",
        "SEARCH_ENGINES=google,bing,duckduckgo,brave",
        "LANCEDB_URI=/YOUR_PATH/cortex-scout/lancedb",
        "HTTP_TIMEOUT_SECS=30",
        "MAX_CONTENT_CHARS=10000",
        "/YOUR_PATH/cortex-scout/mcp-server/target/release/cortex-scout-mcp"
      ]
    }
  }
}

默认行为是直接连接／不使用代理。只有在需要使用代理工具时，才添加 IP_LIST_PATH 和 PROXY_SOURCE_PATH。如果希望启用 proxy_control，但不通过代理路由常规流量，请将 IP_LIST_PATH 指向一个空的 ip.txt 文件，让 Agent 按需填充。

重要： 始终使用 RUST_LOG=warn，不要使用 info。在 info 级别下，服务每个请求都会向 stderr 输出数百行日志，这可能会干扰监控 stderr 的 MCP 客户端。

Windows： Windows 没有 env 命令。请改用 command+env 对象格式 — 参见 docs/IDE_SETUP.md。

启用深度研究（通过 OpenRouter / 任意兼容 OpenAI 的 API 进行大模型综合）：

{
  "servers": {
    "cortex-scout": {
      "type": "stdio",
      "command": "env",
      "args": [
        "RUST_LOG=warn",
        "CORTEX_SCOUT_TOOL_TIMEOUT_SECS=90",
        "CORTEX_SCOUT_TOOL_TIMEOUT_SECS_SCRAPE_URL=90",
        "CORTEX_SCOUT_TOOL_TIMEOUT_SECS_SEARCH_STRUCTURED=120",
        "CORTEX_SCOUT_TOOL_TIMEOUT_SECS_VISUAL_SCOUT=45",
        "CORTEX_SCOUT_BROWSER_LAUNCH_TIMEOUT_SECS=12",
        "CORTEX_SCOUT_BROWSER_TAB_PROBE_TIMEOUT_SECS=4",
        "CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS=20",
        "CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS_CDP_INITIAL_ATTEMPT=25",
        "CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS_CDP_RETRY_ATTEMPT=25",
        "CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS_FORCED_CDP_ATTEMPT=25",
        "CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS_NATIVE_CDP_FALLBACK=25",
        "SEARCH_ENGINES=google,bing,duckduckgo,brave",
        "LANCEDB_URI=/YOUR_PATH/cortex-scout/lancedb",
        "HTTP_TIMEOUT_SECS=30",
        "MAX_CONTENT_CHARS=10000",
        "OPENAI_BASE_URL=https://openrouter.ai/api/v1",
        "OPENAI_API_KEY=sk-or-v1-...",
        "DEEP_RESEARCH_LLM_MODEL=moonshotai/kimi-k2.5",
        "DEEP_RESEARCH_ENABLED=1",
        "DEEP_RESEARCH_SYNTHESIS=1",
        "DEEP_RESEARCH_SYNTHESIS_MAX_TOKENS=4096",
        "/YOUR_PATH/cortex-scout/mcp-server/target/release/cortex-scout-mcp"
      ]
    }
  }
}

多 IDE 指南：docs/IDE_SETUP.md

---

配置（cortex-scout.json）

在与二进制文件相同的目录（或仓库根目录）中创建 cortex-scout.json。所有字段均为可选；环境变量可用作回退值。

{
  "deep_research": {
    "enabled": true,
    "llm_base_url": "http://localhost:1234/v1",
    "llm_api_key": "",
    "llm_model": "lfm2-2.6b",
    "synthesis_enabled": true,
    "synthesis_max_sources": 3,
    "synthesis_max_chars_per_source": 800,
    "synthesis_max_tokens": 1024
  }
}

---

关键环境变量

Core

Variable	Default	Description
RUST_LOG	warn	日志级别。MCP 标准输入输出请保持为 warn——info 会向 stderr 输出大量日志，干扰 MCP 客户端
HTTP_TIMEOUT_SECS	30	每次请求的读取超时时间（秒）
HTTP_CONNECT_TIMEOUT_SECS	10	TCP 连接超时时间（秒）
OUTBOUND_LIMIT	16	并发出站 HTTP 连接数上限
MAX_CONTENT_CHARS	10000	每个抓取页面返回的最大字符数
CORTEX_SCOUT_TOOL_TIMEOUT_SECS	tool-specific	每次 MCP/HTTP 工具调用的硬性超时上限。超过此时间后，Cortex Scout 会取消该工具调用，并返回结构化超时响应，而非一直等待
CORTEX_SCOUT_TOOL_TIMEOUT_SECS_<TOOL>	unset	单个工具的超时覆盖值，例如 CORTEX_SCOUT_TOOL_TIMEOUT_SECS_SCRAPE_URL=90 或 CORTEX_SCOUT_TOOL_TIMEOUT_SECS_VISUAL_SCOUT=20
CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS	stage-specific	抓取过程中各耗时阶段的共享超时时间，例如 CDP 获取、原生抓取、语义裁剪和历史记录写入
CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS_<STAGE>	unset	单个阶段的超时覆盖值，例如 CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS_CDP_INITIAL_ATTEMPT=30

Browser / Anti-bot

Variable	Default	Description
CHROME_EXECUTABLE	auto-detected	覆盖 Chromium/Chrome/Brave 二进制文件的路径
SEARCH_CDP_FALLBACK	true	搜索引擎获取内容遭到拦截时，通过原生 Chromium CDP 重试
SEARCH_TIER2_NON_ROBOT	unset	设置为 1，允许将 hitl_web_fetch 作为最后手段提升搜索级别
MAX_LINKS	100	每次页面爬取最多跟进的链接数

Search

Variable	Default	Description
SEARCH_ENGINES	google,bing,duckduckgo,brave	启用的搜索引擎（以逗号分隔）
SEARCH_MAX_ENGINES_PER_QUERY	3	每次搜索最多查询的引擎数，之后根据健康状况轮换选择下一组引擎
SEARCH_MAX_RESULTS_PER_ENGINE	10	每个引擎在合并和去重前返回的结果数
SEARCH_ENGINE_STAGGER_MS	125	各引擎启动之间的延迟，以减少突发请求触发反机器人机制
SEARCH_COMMUNITY_TRIGGER_RESULTS	4	仅当主搜索返回的结果少于此数量时，才扩展搜索 Reddit/HN 社区内容
SEARCH_SHARED_CACHE	true	在同一主机上并发运行的 Cortex Scout 进程之间共享成功的搜索结果
SEARCH_SHARED_CACHE_TTL_SECS	300	跨进程共享搜索缓存的 TTL
SEARCH_HOST_MIN_GAP_MS	engine-tuned	同一主机 IP 发出的搜索引擎请求之间的跨进程最小间隔
SEARCH_HOST_MAX_GAP_MS	engine-tuned	同一主机 IP 发出的搜索引擎请求之间的跨进程最大间隔／抖动
SCRAPE_HOST_MIN_GAP_MS	900	向同一主机发送抓取请求的跨进程最小间隔
SCRAPE_HOST_MAX_GAP_MS	1800	向同一主机发送抓取请求的跨进程最大间隔／抖动
CORTEX_SCOUT_HOST_GUARD_DISABLED	false	仅在明确要禁用共享主机级限流时设置为 1

Proxy

Variable	Default	Description
IP_LIST_PATH	—	ip.txt 的可选路径（每行一个代理：http://、socks5://）。留空以完全禁用代理支持，或指向空文件，以保留代理工具但默认不启用
PROXY_SOURCE_PATH	—	proxy_source.json 的可选路径（由 proxy_control grab 使用）

Semantic Memory (LanceDB)

Variable	Default	Description
LANCEDB_URI	—	持久化研究记忆的目录路径。省略则禁用
CORTEX_SCOUT_MEMORY_DISABLED	0	即使设置了 LANCEDB_URI，仍可设置为 1 以禁用记忆
MODEL2VEC_MODEL	built-in	用于嵌入的 HuggingFace 模型 ID 或本地路径（例如 minishlab/potion-base-8M）

深度研究

变量	默认值	描述
DEEP_RESEARCH_ENABLED	1	设置为 0 可在运行时禁用 deep_research 工具
OPENAI_API_KEY	—	用于大模型综合的 API 密钥。使用无需密钥的本地端点（Ollama）时可省略
OPENAI_BASE_URL	https://api.openai.com/v1	兼容 OpenAI 的端点（OpenRouter、Ollama、LM Studio 等）
DEEP_RESEARCH_LLM_MODEL	gpt-4o-mini	模型标识符（必须受端点支持）
DEEP_RESEARCH_SYNTHESIS	1	设置为 0 可跳过大模型综合（仅搜索和抓取）
DEEP_RESEARCH_HOP_TIMEOUT_SECS	90	单次跳转的抓取超时时间。超过该时间时，deep_research 会返回部分结果，而不会一直等待到 MCP 调用方超时
DEEP_RESEARCH_SYNTHESIS_MAX_TOKENS	1024	综合回复的最大令牌数。对于大上下文模型，请使用 4096 以上
DEEP_RESEARCH_SYNTHESIS_MAX_SOURCES	8	提供给大模型综合的源文档数量上限
DEEP_RESEARCH_SYNTHESIS_MAX_CHARS_PER_SOURCE	2500	每个来源可提取用于综合的最大字符数

仅限 HTTP 服务

变量	默认值	描述
CORTEX_SCOUT_PORT / PORT	5000	HTTP 服务二进制文件（cortex-scout）的监听端口

---

Agent 最佳实践

建议的操作流程：

1. 开始任何新的研究前，先调用 memory_search；如果相似度 ≥ 0.60 且 skip_live_fetch 为 true，则跳过实时抓取。
2. 发现主题时，使用 web_search 仅发现 URL，或使用 web_search(include_content=true) 在一次往返中搜索并抓取排名靠前的结果。
3. 对于已知 URL，使用 output_format="clean_json" 调用 web_fetch(mode="single")，并设置 query + strict_relevance=true，仅保留相关章节。
4. 遇到 403/429 时：使用 action:"grab" 调用 proxy_control 以刷新代理列表，然后使用 use_proxy:true 重试。
5. 对于需要身份验证的页面：当 auth_risk_score >= 0.4 时运行 visual_scout，然后对于 CAPTCHA 拦截页使用 hitl_web_fetch(auth_mode="challenge")，对于登录拦截页使用 hitl_web_fetch(auth_mode="auth")。
6. 对于深度研究：deep_research 会自动处理多跳搜索、抓取和大模型综合。根据每次运行的成本预算调整 depth（1–3）和 max_sources。
7. 对于 UI 自动化和 E2E 测试：使用 scout_browser_automate 的步骤数组处理标签页、定位器断言、截图/PDF、路由模拟、文件上传和浏览器状态设置。如果首次登录/CAPTCHA 导致阻塞，请调用 scout_agent_profile_auth，然后恢复自动化。

---

常见问题

为什么使用 Ollama 或 qwen3.5 时，deep_research 有时会失败或退回启发式模式？

某些具备推理能力的本地模型会返回兼容 OpenAI 的 /v1/chat/completions 响应，其中 message.reasoning 有内容，但 message.content 为空。检测到这种情况时，Cortex Scout 现在会通过原生 /api/chat 使用 think:false 重试本地 Ollama 端点。

本地 4B 级 Ollama 模型的推荐配置：

• cortex-scout.json 中的 llm_api_key: "" 有效，表示“无需身份验证”
• 将 synthesis_max_sources 保持在 1-2
• 将 synthesis_max_chars_per_source 保持在 600-1000 左右
• 将 synthesis_max_tokens 保持在 512-768 左右

如果综合仍然缓慢或不稳定，请先降低 synthesis_max_sources，再考虑提高令牌上限。

为什么我会看到 Chromium 配置文件锁定错误？

每个无头请求都会使用唯一的临时配置文件，因此常规抓取和 deep_research 不会遇到配置文件锁定竞争。只有 HITL 工作流（如 hitl_web_fetch）使用真实浏览器配置文件时，如果你并发运行它们，或 Brave/Chrome 正在使用同一配置文件，就可能发生锁定。为避免这种情况：一次只运行一个 HITL 调用，并在重用配置文件前关闭所有浏览器窗口。

检查清单：

1. 使用近期构建版本（2026-03-05 或更新版本）
2. 除非需要已登录的会话，否则避免使用持久配置文件路径
3. 按顺序运行 HITL/配置文件工作流
4. 重用配置文件前关闭所有浏览器窗口
5. 让 Cortex Scout 使用各自的临时配置文件进行并发研究

我的 MCP 客户端已连接，但工具会立即失败或超时。我应该先检查什么？

请先检查以下事项：

1. 使用 RUST_LOG=warn，不要使用 info。
2. 在 macOS/Linux 的 env 风格配置中，将二进制文件路径直接放在环境变量赋值之后。不要在 mcp.json 参数中插入 "--"。
3. 在 Windows 上，不要使用 env；请使用 command 和 env 对象。
4. 确认二进制文件路径指向当前构建版本。

---

版本管理与更新日志

请参阅 CHANGELOG.md。

---

许可证

MIT。请参阅 LICENSE。