Google Surf Mcp

google-surf-mcp

英语 | 韩语

由 SearchApi 赞助

网页搜索、论文和 GitHub 仓库会以 PKM、本体和谱系的形式存储。上方视图由 project_memory(action="export", export_format="html", export_view="graph", all_projects=true) 生成。

「将 Google 搜索、论文和代码库转化为供 AI Agent 使用的自动本地知识图谱和谱系，无需 API 密钥，也无需外部服务。」

Google Surf 会将搜索和提取结果存储在项目范围内的本地知识图谱中。

随着搜索的进行，论文、代码、网络来源、会话意图、计划、实验和决策会逐渐累积到个人 PKM 中。新的研究会同时检索已存储的知识和最新网络结果，在持续发现新信息的同时减少重复工作。

默认情况下，各项目彼此隔离。系统只会添加可验证的关联，例如匹配的 DOI、仓库 URL 或明确的别名，因此一个项目的知识可以在另一个项目中复用，而不会合并原始记录。

检索会分别执行精确搜索、BM25、向量搜索、代码和图谱搜索以及实时网络搜索，然后通过 RRF 和一个共享的重排器将结果合并。

Live web + Papers + Codebases + Project memory
                        ↓
Exact + BM25 + Vector + Code graph + Graph PPR
                        ↓
              RRF + Shared reranker
                        ↓
        Results with evidence and provenance

默认提供七种工具：search / search_parallel / extract / scholar_search / project_memory_search / project_memory / health。

研究模式和自动捕获默认启用。设置 SURF_RESEARCH=false，即可在不打开数据库或图谱辅助进程的情况下使用搜索和提取；在此模式下不会注册项目记忆工具。

禁用研究模式后，实时 search 和 search_parallel 结果仍会使用轻量级内存重排器。该重排器通过 RRF 融合提供方排序和查询 BM25 排名，不会加载向量模型或打开本地存储。

浏览器搜索无需 API 密钥。SearchApi 可配置为可选的主提供方或备用提供方。

核心功能

• 网页、论文和代码库搜索： 默认使用 Google 网页搜索，论文专属元数据则使用 Scholar。SearchApi 可作为可选的主要提供方或备用方案。
• 网页和学术文档提取： HTML 和 PDF 提取会返回可获取的标题、作者、DOI、出版元数据和正文。search 和 search_parallel 可包含摘要或完整正文。
• 自动项目记忆： 搜索结果、提取的正文和代码仓库都会存储在当前项目中。未读结果仍为元数据；提取的内容则成为活跃的 RAG 证据。
• 结构化代码库搜索： Tree-sitter 会关联本地项目和相关 GitHub 仓库中的文件、符号、导入项和调用。通过精确搜索、BM25、向量搜索和图搜索检索代码。
• 图混合检索： 分别搜索最新网页结果、论文、存储内容、代码库和项目图。通过 RRF 和一个共享重排器组合精确搜索、BM25、向量搜索和 PPR 候选结果。
• 本体与数据沿袭： 网页来源、论文、代码、计划、实验和决策会转化为带类型的实体和关系。证据路径从来源延伸至文档、片段、符号、证据和断言。
• 跨项目知识复用： 项目彼此隔离，但可以同时搜索选定的项目。只有可验证的链接才能连接匹配的实体。
• 持久研究历史： MCP 主机提供的会话意图、计划、实验、失败和决策会作为修订存储，并关联到支持它们的证据。
• 本地图分析与导出： 无需单独的 Neo4j 服务即可运行 PageRank、PPR、连通分量和 Louvain 社区分析。结果可导出为 HTML、Graphviz、D3 JSON 和 Neo4j 导入格式。

搜索

• 无需 API 密钥的系统 Chrome 搜索
• 专用的未登录配置文件，绝不读取或复制用户的 Chrome 配置文件
• 采用几何验证的多策略 SERP 解析
• 移除赞助内容区块和知识面板
• CAPTCHA 检测和特定环境的恢复
• 解析器自我修复和上下文回退

数据

搜索速度

	结果
search	每个查询 4.0-5.1 秒
scholar_search	每个查询 3.8-5.6 秒

实时网页搜索重排器检查

32 个留出查询	nDCG@5	MRR	Precision@5
提供方顺序	0.8949	0.8203	0.6375
BM25 + RRF	0.8971	0.8203	0.6500

• BM25+RRF 网页搜索响应最多可减少 75% 的大型检索负载。 在连接速度为 1Gb/s 的工作站上，对每个提供方的三个未缓存查询进行测量。网络和 Google 响应时间会有所不同。

技术栈

• 运行时： Node.js、TypeScript、Model Context Protocol SDK
• 网页搜索： 系统 Chrome + CDP、Playwright 兼容性回退、SearchApi 备用方案
• 网页提取： Mozilla Readability、Turndown
• PDF 提取： LiteParse/PDFium、可选 OCR、pdf-lib 元数据解析
• 代码采集： 本地项目根目录和受控的 GitHub 稀疏下载
• 代码解析： 使用 Tree-sitter 解析文件、符号、导入项和调用关系
• 代码搜索： 精确查找、BM25、多语言 E5 向量搜索和图 PPR
• 本地数据库： 基于 RocksDB 的嵌入式 SurrealDB
• 混合检索： 通过 RRF 组合实时网页、论文、项目记忆和代码库结果
• 排序： 倒数排名融合和共享向量重排
• 图分析： Graphology、PageRank、PPR、连通分量和 Louvain 社区分析
• 知识模型： 版本化本体、数据沿袭、跨项目架构和实体链接
• 恢复： CAPTCHA 恢复、Playwright 池回退和确定性解析器自我修复

安装

需要 Node 20.18.1+。浏览器模式还需要 Google Chrome 或 Chromium。

npx google-surf-mcp   # actual MCP - register in client config

首次调用工具时会自动初始化预热配置文件（你可能会看到 Chrome 短暂打开）。

或者克隆到本地：

git clone https://github.com/HarimxChoi/google-surf-mcp
cd google-surf-mcp
npm install

如果自动初始化失败（少见），请手动运行：

npm run bootstrap

如有需要，可覆盖路径：

CHROME_PATH=/path/to/chrome SURF_TZ=America/New_York npm run bootstrap

可选的 Codex 输出保护

Google Surf 可以安装一个可选的 Codex hook，在超长 Bash 输出到达模型之前对其进行排序。命令仍由主机执行；hook 仅应用无状态的源顺序、精确匹配和 BM25 排序，并使用 RRF。它既不会打开 Google Surf 数据库或浏览器，也不会存储命令输出。

npx -y google-surf-mcp@latest hooks install --host codex

重启 Codex，然后打开 /hooks 查看并信任这些定义。从 1,500 个字符开始对 Shell 输出重新排序，默认显示预算为 1,500 个字符；对于不同的查询匹配证据记录或代码块，预算最多可扩展到 3,000 个字符。显式覆盖值可以超过 3,000；每轮没有累计输出限制。两个相同或近乎重复的搜索，以及显式的前台轮询循环，都会被阻止。对于已运行的统一命令，现有的 write_stdin 轮询仍由 Codex 运行时控制，而非此 hook。

JSON/JSONL 摘要使用紧凑记录，包含相对于输入的 JSON 指针、祖先身份/条件引用以及原始结果值。Markdown 表格行会保留表头和相邻上下文，包括源行。选中的记录及其必需上下文必须能一并容纳；渲染器会报告遗漏内容，而不是截断记录。纯日志仍采用代码块重新排序。选择是确定性的，基于词法，不使用模型、数据库或额外子进程。上下文提取使用结构/字段名称启发式，而非语义理解；未选字段仍保留在原始输入中。这些摘录不能替代实验日志或 SSOT 历史记录。相对于输入的指针不是持久的检索句柄。现有已安装的 hook 包需要更新后才能使用变更后的代码。

npx -y google-surf-mcp@latest hooks status --host codex
npx -y google-surf-mcp@latest hooks update --host codex
npx -y google-surf-mcp@latest hooks uninstall --host codex

与 Claude Code 搭配使用

将以下内容粘贴到你的 ~/.claude.json 中：

{
  "mcpServers": {
    "google-surf": {
      "command": "npx",
      "args": ["-y", "google-surf-mcp"]
    }
  }
}

重启 Claude Code。默认情况下，所有七个工具（包括 project_memory_search 和 project_memory）均可用。

对于其他 MCP 客户端，请在其配置文件中使用相同的 JSON 结构。

搜索提供商

浏览器搜索仍为默认选项。SearchApi 可设为主要提供商，也可仅在浏览器搜索失败时使用。

值	行为
browser	默认。使用系统 Chrome 和专用的未登录配置文件，隐藏原生搜索窗口，且无需 SEARCH_API。多个 MCP 会话共用一个本地浏览器代理。
searchapi	使用 SearchApi 作为主要提供商，该工具不会初始化 Chrome。
fallback	先尝试一次当前浏览器层级，然后在浏览器出错、遇到 CAPTCHA/速率限制、配置文件失败或解析器性能下降时使用 SearchApi。不会等待人工解决 CAPTCHA。浏览器返回成功响应或正常的空响应时不会重试。

SURF_SEARCH_PROVIDER 控制 search 和 search_parallel。SURF_SCHOLAR_PROVIDER 控制 scholar_search。SearchApi 模式需要你拥有自己的 SearchApi 账户、密钥和可用额度。

SURF_BROWSER_ENGINE=auto 会在本地桌面上选择原生 Chrome，在云端或远程调试模式下选择 Playwright 兼容路径。原生模式使用普通的隐藏 Chrome 窗口，而非无头 Chrome。设置为 native 或 playwright 可固定引擎。

{
  "mcpServers": {
    "google-surf": {
      "command": "npx",
      "args": ["-y", "google-surf-mcp"],
      "env": {
        "SEARCH_API": "your-searchapi-key",
        "SURF_SEARCH_PROVIDER": "fallback",
        "SURF_SCHOLAR_PROVIDER": "searchapi"
      }
    }
  }
}

本地克隆版本：

{
  "mcpServers": {
    "google-surf": {
      "command": "node",
      "args": ["/abs/path/to/google-surf-mcp/build/index.js"]
    }
  }
}

工具

• search(query, limit?, extract_mode?, extract_limit?, response_content?, max_chars?) - 用于实时发现和阅读的主要单查询工具。需要查找并阅读新来源时，应在此调用中设置 extract_mode，而不是下载 PDF、克隆仓库或单独调用 extract。仅当确切的公开 URL 已知且无需发现来源时，才使用 extract。指定 project_id 后，存储的项目知识会与实时结果融合，但调用不会变为纯本地搜索。limit 为 1-20。提取默认为 none；extract_limit 为 1-10，默认值为 5。response_content 默认为 summary，以限制单次调用的输出量。
• scholar_search(query, limit?) - Google Scholar 元数据搜索，最多 10 篇论文。支持 browser、SearchApi 主模式和回退模式。
• search_parallel(queries[], limit?, extract_mode?, extract_limit?, response_content?, max_chars?) - 通过连续的四标签页队列进行广泛实时发现和阅读的主要多查询工具。需要阅读公开网页、PDF、论文或 GitHub 仓库时，应在同一次调用中设置 extract_mode。仅在处理本地文件或进行视觉布局工作时使用本地 PDF 工具；仅在需要编辑、构建、测试或查看完整 Git 历史时克隆仓库。每个查询的 limit 为 1-20。整个调用的 extract_limit 默认值为 12；abstract 模式最多允许 20，full 模式默认且最多允许 10。response_content 默认为 summary，以限制单次调用的输出量。
• 集成搜索提取会报告 requested、applied、skipped、truncated 和 total_chars。可将 remaining_urls 传递给 extract，无需重复搜索。
• extract(url, max_chars?, mode?, response_content?) - 当确切的公开 URL 已知且无需发现新来源时使用的次级提取工具。如果仍需查找来源，请改用带有 extract_mode 的 search 或 search_parallel。
  • mode="full"（默认值）：读取最多 1000000 个字符以供研究收录。研究模式会存储确定性的 4000 字符分块；response_content="full" 最多返回 50000 个字符，summary 则返回 1500 字符的证据摘录。
  • mode="abstract"：约 1500 字符的概览（PDF 第 1 页或 HTML 元描述）。启用研究模式时，会包含文档元数据并与概览一同存储。
  • mode="metadata"：仅返回元数据，不含正文文本。返回可用的标题、作者、出版物、日期、DOI、描述、关键词、规范 URL，以及包括页数在内的 PDF 属性。
  • GitHub 仓库 URL 在元数据模式下会读取 README。abstract 和 full 使用相同的下载门控，仅索引的来源深度不同。
  • 响应：内容字段及可用的文档元数据。失败时返回 { error }，不会抛出异常。
• project_memory_search(query, query_variants?, project_id?, include_project_ids?, all_projects?, limit?, request_id?, response_deadline_ms?) - 仅搜索存储的本地知识。最多 19 个可选变体会在一次 broker 请求中运行，并使用批量查询嵌入、RRF 融合、证据引导的图扩展，以及针对 query 的最终重排。响应仅包含根据最终排名生成的、范围受限且聚焦于查询的摘要；存储的正文保留在数据库中。调用方提供的 request_id 可使长查询可观察，并支持通过 project_memory 协同取消。如果检索已生成候选项后才到达截止时间，则已完成的通道会作为明确标记的部分结果返回，而不会被丢弃。它不会打开浏览器，也不会调用 Google 或 SearchApi。
• project_memory(action, ...) - 在 SURF_RESEARCH=true 时管理持久项目知识。
  • action="search"：project_memory_search 的兼容别名。
  • action="project_update"：以经过修订检查的配置文件修订形式，更新现有项目的名称、用途、约束或受保护的父级。
  • action="context"：分别呈现持久项目用途、已确认的会话意图、暂定的近期查询、当前计划、科学实验状态和观察到的进程存活状态。
  • action="get"：通过有界 UTF-8 字节范围返回精确的类型化记录或旧版记录。仅需元数据时，将 body_bytes=0；若要无损分页，请使用 next_body_offset。
  • action="show"：始终返回包含计数和活动记录 ID 的有界摘要。为兼容性接受 detail_level="full"，但绝不会转储所有记录正文。请使用 project_memory_search 获取相关正文，或使用 target_id 指定单条断言或实体。
  • action="record"：存储提交的正文，仅返回其 ID、修订版本和状态。回执会区分首次写入与幂等重放。
  • action="query_status" / action="query_cancel"：检查或协同停止一个在执行前通过 request_id 标识的本地检索。
  • action="export"：在 <research-root>/exports 下写入独立的交互式 HTML 浏览器、Graphviz DOT、D3 节点链接 JSON 或 Neo4j 导入包。
• health() - 服务状态，包括本地研究运行时。 | 需求 | 工具 | |---|---| | 仅搜索已存储的研究和项目记忆 | project_memory_search | | 在网络上查找新信息 | search | | 将新的网络搜索结果与已存储的项目知识进行比较 | 使用 project_id 调用 search | | 运行多个新的网络查询 | search_parallel |

可重放的研究采集

google-surf-collect 通过一个持久 MCP 会话运行版本化 JSON 规范。规范可以混合实时 search 任务与仅限本地的 project_memory_search 任务。实时任务可以在同一次调用中提取正文，而本地任务则会复用已编入索引的项目知识，无需打开 Google。

npx google-surf-collect examples/research-collection.example.json

在源代码检出目录中：

npm run build
npm run research:collect -- examples/research-collection.example.json

项目工作流还可以记录持久会话和计划、重建获准的代码根目录、搜索由此生成的本地知识，并导出其图谱：

npm run research:collect -- examples/project-memory-workflow.example.json

project_memory 采集任务支持 record、rebuild 和 export。采集架构不接受具有破坏性的 forget 操作。除非请求导出所有项目，否则项目级 project_id 会应用于每个任务。

输出为只追加的 JSONL。其清单会记录规范化规范的哈希值、软件包版本、Git 提交、Node 运行时、平台、项目设置和服务运行状况。每个搜索、记录、重建和导出结果都会记录稳定的任务 ID、精确的工具参数、尝试次数、时间戳、耗时、响应和错误状态。成功的任务会在恢复运行时跳过；失败的任务会重试。规范变更后必须使用新的输出文件。如果运行器应创建缺失的项目，请同时设置 project_name 和 project_id；如果项目已存在，则会重复使用。

如果必须确保之前的项目 RAG 状态不会影响实时结果排序，请将 retrieval_mode 设为 live。结果仍会保存在 project_id 下。如果采集需要将新的网络证据与已存储的项目知识一同排序，请使用 hybrid。API 密钥和环境变量值绝不会写入采集日志。

这样，采集流程和返回的快照便可重放和审计。实时网络结果仍可能随时间、区域设置、网络路由和上游排序而变化。

使用本体和溯源的图谱混合 RAG

flowchart TB
    subgraph SOURCES["1. Search and research"]
        direction LR
        LIVE["Live web<br/>Google browser • SearchApi fallback"]
        PAPER["Pages and papers<br/>extract • Scholar metadata"]
        PROJECT_INPUT["Code and project records<br/>local roots • GitHub • host-provided session/plan"]
    end

    INGEST["2. Deterministic capture<br/>normalize • deduplicate • content hash<br/>repository source gate • Tree-sitter"]

    subgraph KNOWLEDGE_BASE["3. SurrealDB knowledge base"]
        direction LR
        CONTENT["Content and code index<br/>exact • BM25 • HNSW vector<br/>documents • chunks • symbols"]
        PROV["Data lineage and provenance<br/>source → evidence → assertion<br/>valid time • recorded time • correction"]
        ONTOLOGY["Versioned ontology<br/>core/project term revisions<br/>entity type • relation • alias • merge/split"]
        MEMORY["Project memory<br/>session intent • plan revisions<br/>experiments • decisions"]
    end

    subgraph INTELLIGENCE["4. Graph intelligence"]
        direction LR
        SCHEMA["Cross-project schema linking<br/>type and relation alignment<br/>stable identifier → identity bridge"]
        SIDECAR["Typed graph sidecar<br/>PageRank • Louvain • query-time PPR"]
    end

    FUSION["5. Hybrid retrieval<br/>live • exact • BM25 • vector • graph<br/>deterministic RRF • shared reranker • fresh-web floor"]
    RESULTS["Results + provenance<br/>short storage receipt"]

    LIVE --> INGEST
    PAPER --> INGEST
    PROJECT_INPUT --> INGEST
    INGEST --> CONTENT
    INGEST --> PROV
    INGEST --> ONTOLOGY
    INGEST --> MEMORY
    ONTOLOGY --> SCHEMA
    CONTENT --> SIDECAR
    PROV --> SIDECAR
    MEMORY --> SIDECAR
    SCHEMA --> SIDECAR
    LIVE --> FUSION
    CONTENT --> FUSION
    SIDECAR --> FUSION
    FUSION --> RESULTS
    RESULTS -. "automatic search/extract capture" .-> INGEST

    classDef inputStyle fill:#eef6ff,stroke:#2563eb,color:#172554
    classDef processStyle fill:#fff7ed,stroke:#ea580c,color:#431407
    classDef storageStyle fill:#ecfdf5,stroke:#059669,color:#052e16
    classDef intelligenceStyle fill:#f5f3ff,stroke:#7c3aed,color:#2e1065
    classDef outputStyle fill:#f8fafc,stroke:#475569,color:#0f172a
    class LIVE,PAPER,PROJECT_INPUT inputStyle
    class INGEST processStyle
    class CONTENT,PROV,ONTOLOGY,MEMORY storageStyle
    class SCHEMA,SIDECAR intelligenceStyle
    class FUSION,RESULTS outputStyle

一个本地知识库

一个 SurrealDB 实例是以下三个不同层的权威数据源：

• 目录： 稳定标识、修订版本、项目成员关系、本体、来源信息和时间链接。
• 载荷： 精确正文、来源快照、清单和工件引用。相同内容只存储一次，并可按 ID 和字节范围获取。
• 派生视图： 精确匹配、BM25、向量、代码和图谱索引，以及精简的当前项目视图。这些视图按来源哈希进行版本控制，并可重建。

单个本地研究代理负责管理嵌入式 RocksDB 连接。多个 MCP 会话通过经过身份验证的本地 IPC 连接、并发执行有界读取，并串行处理写入，而无需启动另一个数据库进程。即使正文、嵌入或图谱结构经过去重，原始证据和历史记录仍可通过地址访问。

持久化记录与增量索引

project_memory 将项目档案、计划、实验、尝试、测量、制品、文档、决策和会话写入为类型化记录。稳定的资产 ID 会接收修订版本；使用相同幂等键进行的不确定重试会返回已提交的修订版本，并设置 idempotent_replay=true 和 applied_this_request=false。body_path 可流式传输最大 256 MiB 的正文，制品清单采用分页而非切片，get/get_batch 通过有界正文跨度返回精确的类型化或旧版记录。精简的写入回执会报告已接受的字节数、引用、修订版本和精确的回读句柄，不会回显提交的正文。

sync 接受已注册的根目录，或显式指定的变更和移除路径。未变更的根目录和父级标识保持不变，无操作不会重写派生索引，单个文件变更只会发布受影响的代次。代码、检索和图谱发布在同一个持久化作业 ID 下运行。job_wait 使用修订游标，job_cancel 会在安全的阶段边界停止作业，未完成的作业会在进程重启后恢复。在工作进程软内存限制下，前台请求优先完成；可重建的索引作业会在持久化的阶段边界创建检查点，并在替换后的工作进程中恢复，而不会取消已提交的记录。

本体与跨项目链接

版本化本体会将实体类型和关系的变更保留为修订版本。模式链接会将项目特定的类型和关系映射到共享模式。只有在 DOI、存储库 URL 或显式别名等可验证标识符匹配时，实体链接才会连接同一篇论文、同一个存储库或同一个实体。不会自动链接有歧义的候选项。

数据与研究溯源

• 来源溯源： source → document → chunk → evidence → assertion
• 代码溯源： repository → directory → file → symbol → import/call
• 研究溯源： session → intent → plan revision → experiment → decision

这会保留声明和决策背后的证据，同时留存已更正或已取代的历史记录。

图谱检索

Graphology 基于 SurrealDB 构建类型化图谱投影，并计算 PageRank、连通分量和 Louvain 社区。检索时，相关节点会作为基于 PPR 的多跳搜索的种子。实时网络、精确匹配、BM25、向量和图谱候选项会通过确定性的 RRF 和一个共享重排器进行整合。

本地多查询检索会批量处理查询嵌入，在整个 RRF 过程中保持精确匹配、BM25 和向量通道相互独立，只扩展一次图谱，只载入一次选定的文本块，并只进行一次重排。仅使用图谱的全项目搜索会使用轻量级记忆节点索引和经过验证的身份别名，最多选取四个图谱范围，而不是在查询时构建每个项目的图谱。

如果查询嵌入失败或未返回向量，本地搜索会直接返回其词法/图谱排序结果，不会在重排时重试模型。计时字段是互不重叠的墙钟时间分区：embedding_ms 加上 retrieval_ms 表示检索结束所需时间，rerank_ms 则覆盖剩余的响应处理工作。检索可能与嵌入并行，因此 retrieval_ms 并非独立的数据库执行时间。提供的 response_deadline_ms 从代理接纳请求后开始计时；传输看门狗会在该期限之外额外保留五分钟的排队/IPC 宽限时间。超出部分响应时限的原生查询会继续占用其代理读取槽，直至查询完成。

研究检索检查

60 条查询的回归测试夹具会比较词法基线与完整的本地 RAG 流程。为将检索变化与 HNSW 近似计算区分开来，此检查固定使用一个嵌入线程，并采用穷举向量评分。表格报告三个独立进程运行结果的中位数：

60 条受控查询	Recall@10	nDCG@10	MRR@10
词法基线	0.3333	0.3333	0.3333
精确检索 + BM25 + 向量 + 图 RRF	0.9833	0.8194	0.7668
+ 共享重排器	0.9833	0.8194	0.7668

所有检索目标均通过精确溯源回读检查。保守的重排器在此测试夹具中保留了融合后的排序；此检查不代表生产环境中的搜索质量，也不声称重排器带来了提升。

npm run research:vector-backends -- --rows 5000 使用确定性测试向量比较不同物理表示。以下示例不包含 E5 模型加载，应在目标机器上重新运行：

后端	输入行数	存储向量数	插入耗时	查询 p95	召回率
HNSW	5,000	5,000	1292.1 ms	10.77 ms	1.000
Compact	5,000	1,250	357.1 ms	3.96 ms	1.000
Exhaustive	5,000	5,000	1197.1 ms	289.79 ms	1.000

默认仍使用 HNSW，以覆盖完整分块的语义检索。Compact 为每个来源索引一个代表性分块；在此短记录测试夹具中，它占用的内存更少，且总体召回率相当，但可能会遗漏长来源末尾附近的罕见细节。

Broker 与持久性检查

最近 100 次本地查询压力测试	结果
浏览器 Broker 启动次数	0
活跃数据库所有者重启次数	0
查询 RSS 变化	+10.9 MiB
观测到的研究工作进程 RSS 峰值	375.5 MiB
空闲排空与透明重新打开	通过
无操作同步 / 单文件增量同步	通过 / 通过

npm run research:reopen-probe 还会验证字节精确的正文分页、包含 225 个引用的分页制品清单，以及重启进程后恢复并变为可搜索状态的待处理重建任务。此压力测试禁用向量模型，以单独测量 Broker、数据库和查询生命周期的内存；向量后端已在上方单独测量。

项目隔离与知识复用

project_id 用于选择新结果的存储位置。include_project_ids 可扩大读取范围，但不会更改写入目标。原始记录仍按项目隔离，而经过验证的架构和实体链接可让论文、代码和实验结果在选定项目之间复用。

交互式图谱与导出

使用 project_memory(action="export", export_format="html", export_view="graph")。返回的独立 HTML 文件无需服务器即可在本地打开，并包含三个相互协调的视图。使用 project_id 指定一个项目，使用 include_project_ids 指定所选项目的组合图谱，或使用 all_projects=true 包含所有项目。

• PKM 按社区对集成项目图谱分组，并根据 PageRank 设置节点大小。
• Lineage 将来源和代码沿袭与会话、意图、计划、实验和决策沿袭分开，同时按阶段对齐两种流程。
• Ontology 展示核心类型和关系、对齐后的共享架构以及带类型的实例。只有在稳定标识符或明确别名能够证明跨项目匹配时，才会显示已验证的身份层。

数据与研究沿袭

本体与共享架构

搜索、类型筛选器、一到三跳的局部聚焦、平移、缩放以及来源检查器都可在文件中使用。对于大型图谱，系统会使用确定性的语义投影，平衡节点类型、PageRank、度数和社区覆盖率。查看器会报告来源与显示的数量，将内部 ID 替换为本地别名，为重复标签消歧，并且不会嵌入来源 ID、本地路径、节点正文、计划文本或证据引文。

项目菜单可在导出文件中嵌入的所有项目与集成的 All projects 视图之间切换。导出时使用 all_projects=true 可包含本地数据库中的所有具名项目；也可使用 project_id 和 include_project_ids 指定范围。点击画布空白处可清除局部节点聚焦。PNG 会导出当前画布；JSON 会仅使用匿名化的查看器载荷导出当前选项卡、项目、类型筛选器和局部聚焦。独立文件采用 nonce 绑定的脚本 CSP，不会建立网络连接，并且只允许使用已剥离的公共 HTTP 或 HTTPS URL 作为来源链接。

Neo4j 导出

使用 project_memory(action="export", export_format="neo4j", export_view="graph")。返回的目录包含 nodes.csv、relationships.csv、constraints.cypher、load.cypher、manifest.json 和 README.txt。PageRank、社区、本体、沿袭、项目 ID、来源 ID 和证据 ID 均会保留。节点正文、计划文本和证据引文不会导出。

对于新的或空的本地数据库，请在导出目录中运行 Neo4j 离线导入器：

neo4j-admin database import full --nodes=nodes.csv --relationships=relationships.csv neo4j

对于现有的本地数据库，请将两个 CSV 文件复制到 Neo4j 导入目录，然后运行：

cypher-shell -f constraints.cypher
cypher-shell -f load.cypher

离线导入器会创建带类型的节点标签和关系类型。在线加载器使用 SurfNode 和 SURF_RELATION，并将原始种类和关系类型保留为属性。neo4j-admin database import full 适用于新的或空的数据库；现有数据库请使用 LOAD CSV。请参阅官方 Neo4j 导入 和 LOAD CSV 文档。Bolt 是一种连接协议，而不是导出文件格式，因此此命令不会连接 Neo4j 服务，也不会对其进行修改。

存储范围与安全性

研究模式默认启用。search、search_parallel、scholar_search 和 extract 的结果会自动捕获。只有当 MCP 主机通过 project_memory 发送会话意图、计划、实验和决策时，这些内容才会被存储；随后会自动进行版本管理、本体映射和溯源关联。检索模式属于服务配置，而非单次调用的参数。

图像检索、图像嵌入和视觉重排不属于研究记忆。OCR 仅用于从扫描版 PDF 页面中恢复可搜索文本。

凭据文件和私钥文件不会纳入正文索引。HTML 导出会省略源 ID、本地路径、节点正文、计划文本和证据引文。查看器不会发起网络请求，只有在用户操作后才会打开已剥离参数的公共 HTTP 或 HTTPS 源链接。

删除项目和断言需要先预览数量，并提供确认令牌。这些操作会创建可撤销的墓碑，并保留证据和更正历史。事实更正只接受 target_id、replacement 和 reason；先前的断言会作为双时态历史保留。计划修订仅追加。实验会绑定到当前修订，且必须明确以 success、failed 或 inconclusive 结束。系统不会根据日志推断结果。回执仅列出已存储的类别：

Project: Graph memory | Session: temporal graph research | Stored: paper 1 (Graphiti), repo 1 (getzep), search summaries 3 | Status: ready

将 SURF_RESEARCH=false 设为关闭数据库和侧车服务，并省略 project_memory_search 和 project_memory。目前不包含 Obsidian 和 Notion 同步；将来添加时，也会由项目级配置选择启用。

本地操作 CLI

这些命令使用与 MCP 会话相同的经过身份验证的研究代理。它们不会再打开另一个嵌入式数据库所有者或浏览器：

npx google-surf-mcp doctor --json
npx google-surf-mcp daemon start --background --no-window
npx google-surf-mcp memory get --project PROJECT --record RECORD --json
npx google-surf-mcp memory sync --project PROJECT --manifest changes.json --json
npx google-surf-mcp memory current --project PROJECT --json
npx google-surf-mcp job wait --project PROJECT --id JOB --after-revision 0 --json
npx google-surf-mcp job cancel --project PROJECT --id JOB --reason "operator request" --json
npx google-surf-mcp daemon drain --json

doctor 为被动操作：它会报告进程身份、版本、功能、队列计数器、记忆计数器、缓存字节数、当前生命周期状态、前台／后台所有权、检查点排空状态，以及阻止工作线程回收的确切原因；整个过程中不会打开数据库、向量模型或图谱。当有意义的工作处于空闲状态后，即使 MCP 客户端仍保持连接，代理也会排空；活动请求和提交会推迟排空，而可重建的后台作业会在内存压力下于安全阶段边界创建检查点。下一个请求会透明地重新连接。

环境变量

变量	默认值	说明
SEARCH_API	unset	SearchApi API 密钥。仅当任一提供方设置为 searchapi 或 fallback 时必需。以 bearer token 形式发送，绝不会放入请求 URL。
SEARCHAPI_API_KEY	unset	SEARCH_API 的别名。
SURF_SEARCH_PROVIDER	browser	search 和 search_parallel 使用的提供方：browser、searchapi 或 fallback。
SURF_SCHOLAR_PROVIDER	browser	scholar_search 使用的提供方：browser、searchapi 或 fallback。
SURF_BROWSER_ENGINE	auto	浏览器引擎：auto、native 或 playwright。Native Chrome 会先执行请求，然后以只读方式通过 CDP 附加。
CHROME_PATH	auto-detected	Chrome 二进制文件的绝对路径
SURF_PROFILE_ROOT	~/.google-surf-mcp	热配置文件所在位置
SURF_RESEARCH	true	启用本地项目记忆、采集、索引、project_memory_search 和 project_memory；设为 false 可仅用于搜索和提取
SURF_RETRIEVAL_MODE	hybrid	研究搜索路径：live 或 hybrid；仅在 SURF_RESEARCH=true 时使用
SURF_RESEARCH_ROOT	<profile>/research	内嵌 SurrealDB 数据目录
SURF_RESEARCH_DB_ENDPOINT	unset	可选的远程 SurrealDB 端点；必须使用 wss/https，但 localhost 可使用 ws/http
SURF_RESEARCH_DB_NAMESPACE	google_surf	研究目录使用的 SurrealDB 命名空间
SURF_RESEARCH_DB_DATABASE	research	研究目录使用的 SurrealDB 数据库
SURF_RESEARCH_DB_TOKEN	unset	远程研究数据库的 bearer token；也可设置 SURF_RESEARCH_DB_USERNAME 和 SURF_RESEARCH_DB_PASSWORD
SURF_RESEARCH_VECTOR_MODEL	Xenova/multilingual-e5-small	HNSW 向量检索和最终重排使用的本地 384 维模型。默认模型版本已固定；设为 off 可禁用向量通道。
SURF_RESEARCH_VECTOR_LOW_MEMORY	true	禁用 ONNX CPU 内存 arena 和内存模式；设为 false 可用更高的峰值内存换取更快的初始索引速度
SURF_RESEARCH_VECTOR_THREADS	4	ONNX 算子内线程数，限制在 1-16
SURF_RESEARCH_VECTOR_BATCH_SIZE	8	推理微批大小，限制在 1-32；每个批次完成后都会检查点保存生成的嵌入
SURF_RESEARCH_VECTOR_BACKEND	hnsw	向量表示方式：hnsw、内容去重的 compact，或有界的 exhaustive
SURF_RESEARCH_REPO_AUTO	true	每次搜索调用时，自动对最多一个相关的小型 GitHub 仓库建立稀疏索引
SURF_RESEARCH_REPO_AUTO_MAX_MB	20	自动为 GitHub 建立索引时，可搜索源文本的最大大小；不包括资源文件
SURF_RESEARCH_REPO_AUTO_MAX_FILES	2000	自动为 GitHub 建立索引时，可搜索源文件的最大数量
SURF_RESEARCH_BROKER_IDLE_MS	60000	最后一项实质性工作结束后的排空延迟，即使客户端仍保持连接也适用；活动请求和后台任务会推迟排空
SURF_RESEARCH_READ_CONCURRENCY	4	Broker 并发读取上限；相同的进行中读取会共享同一操作
SURF_RESEARCH_QUERY_TIMEOUT_MS	120000	每次内嵌 SurrealDB 查询的超时时间，限制在 1-600 秒；超时的检索通道会标记为部分结果，其他通道仍会返回结果
SURF_RESEARCH_GRAPH_CACHE_MAX_MB	64	进程内图投影和分析产物的字节预算
SURF_RESEARCH_WORKER_SOFT_MEMORY_MB	2048	RSS 阈值；活动工作完成后会触发立即空闲排空
SURF_RERANK_TRIGGER_CHARS	1500	shell 输出拦截阈值（含边界）；即使低于此阈值，也会对敏感输出进行净化
SURF_RERANK_MAX_CHARS	adaptive: 1500–3000	可选的 shell 摘要长度上限，支持设置高于 3000 的值；默认值为 min(3000, ceil(1500 + 750*log2(max(1,n))))，其中 n 为不同的查询匹配记录/区块数，而非重复输出量
GITHUB_TOKEN	unset	可选的 GitHub token，可提高仓库检查的 API 限额
SURF_RESEARCH_CODE_WORKERS	auto, max 4	用于初始代码结构索引的 Tree-sitter 工作线程数
SURF_LOCALE	en-US	浏览器区域设置
SURF_TZ	system tz	例如 America/New_York
SURF_HEADLESS	true	控制 Playwright 提取、兼容性和恢复路径。Native 搜索会隐藏正常的系统 Chrome 窗口，仅在 CAPTCHA 恢复时显示。
SURF_REMOTE_DEBUG	false	在配备远程 DevTools 的无头服务端上设为 true。CAPTCHA 路径会输出 DevTools 端口并抛出错误，而不会启动窗口；通过 SSH 端口转发，从本地机器附加 chrome://inspect 进行验证。
SURF_CAPTCHA_TIMEOUT_MS	180000	后台人工恢复窗口的存续时间。MCP 调用会立即返回，不会等待此超时。
SURF_IDLE_CLOSE_MS	30000	关闭顺序 ctx 和池之前的空闲毫秒数。0 可禁用空闲自动关闭。值越低，清理越快；值越高，间隔调用时缓存越热。
SURF_ALLOW_PRIVATE	false	设为 true 可让 extract 获取私有/环回地址（localhost、127.0.0.1、10.x、192.168.x、169.254.x 等）。默认会阻止这些地址，以防范 SSRF。
SURF_EXTRACT_MAX_CHARS	50000	完整提取的长度上限（200-50000）；摘要默认限制为 1500；单次调用的 max_chars 可覆盖这两个值
SURF_EXTRACT_OCR	false	使用 Tesseract 对扫描版/图像 PDF 进行 OCR（速度较慢；默认关闭）
SURF_CLOUD_MODE	false	无头/无服务器模式：绕过 TLS 检查 + --no-sandbox + --disable-dev-shm-usage + 禁用工作线程池 + 遇到 CAPTCHA 时快速失败
SURF_CASCADE_DISABLED	false	固定使用单一隐身模式（由 SURF_USE_STEALTH 选择），而不是 3 层自动级联
SURF_USE_STEALTH	true	初始隐身层级；仅在 SURF_CASCADE_DISABLED=true 时读取
SURF_HUMANLIKE_MODE	background	off / background（返回结果后异步执行，不等待）/ inline（返回前等待，速度较慢）
SURF_RATE_LIMIT_PER_MIN	10	面向 Google 的请求每分钟内部上限
SURF_CACHE_TTL_SEARCH_MS	86400000	搜索缓存 TTL（24h）；0 可禁用缓存
SURF_CACHE_MAX_ENTRIES	1000	每个缓存命名空间的 LRU 上限
SURF_CACHE_ROOT	<profile>/cache	缓存目录
SURF_INSECURE_TLS	=SURF_CLOUD_MODE	--ignore-certificate-errors（云模式下自动启用）
SURF_NO_SANDBOX	=SURF_CLOUD_MODE	--no-sandbox（云模式下自动启用）
SURF_TELEMETRY	false	设为 true 可在 {SURF_TELEMETRY_ROOT} 下启用 jsonl 事件日志（搜索结果、缓存命中/未命中、工具错误、解析器过期情况）。设计为自愈流水线的输入数据源。默认关闭。
SURF_TELEMETRY_ROOT	<profile>/telemetry	jsonl 遥测文件目录。按 UTC 日期每天生成一个文件（YYYY-MM-DD.jsonl）。
SURF_SELF_HEALING	true	按策略跟踪结果并持久化调整顺序。自愈策略必须领先 3 次结果才会触发重新排序，因此不可能因单次调用而反复切换。设为 false 可固定默认策略顺序。
SURF_SELF_HEALING_FILE	<profile>/.heal/strategy-order.json	自愈状态的持久化路径。使用原子 tmp+rename 写入；延迟 5s。
SURF_LLM_HEAL	false	启用 LLM 辅助选择器修复的选项，仅用于工作流专用的 repairWithLLM 辅助函数。默认关闭，因此不会发起第三方 LLM 请求。
SURF_LLM_PROVIDER	anthropic	LLM 修复提供方：anthropic 或 orcarouter。
SURF_LLM_MODEL	provider default	LLM 辅助修复使用的模型。Anthropic 默认使用 claude-sonnet-4-6，OrcaRouter 默认使用 orcarouter/auto。
ANTHROPIC_API_KEY	unset	仅在启用 LLM 修复且提供方为 Anthropic 时使用的 Anthropic 密钥。
ORCAROUTER_API_KEY	unset	仅在启用 LLM 修复且提供方为 OrcaRouter 时使用的 OrcaRouter 密钥。
ORCA_KEY	unset	ORCAROUTER_API_KEY 的别名。

内嵌资源预算

内嵌存储的默认配置为：512 MiB RocksDB 块缓存、128 MiB HNSW 向量缓存、两个 32 MiB 写入缓冲区，以及两个后台任务，而非按机器规格调整的服务端默认值。显式设置 SURREAL_HNSW_CACHE_SIZE、SURREAL_ROCKSDB_BLOCK_CACHE_SIZE、SURREAL_ROCKSDB_WRITE_BUFFER_SIZE、SURREAL_ROCKSDB_MAX_WRITE_BUFFER_NUMBER、SURREAL_ROCKSDB_THREAD_COUNT 和 SURREAL_ROCKSDB_JOBS_COUNT 时，以这些设置为准。

后台索引一次运行一个任务。同一项目中排队等待的采集会共享当前索引过程，待处理的采集请求会在代理重启后保留。推理调用共享一个队列，每个小型嵌入批次都会在检查是否需要排空队列之前保存。文档索引不会加载无关的代码正文。已有的缓存嵌入仍可复用；较小的批次设置不会强制执行完整重新索引。这些是组件级资源预算，并非整个进程 RSS 的硬性上限。原生存储默认值会在代理打开其数据库时生效，不适用于已经运行的代理。

OrcaRouter

SURF_LLM_HEAL=true
SURF_LLM_PROVIDER=orcarouter
ORCAROUTER_API_KEY=...
SURF_LLM_MODEL=orcarouter/auto

故障排除

• 原生搜索会保持当前会话打开，并在出现 CAPTCHA 时显示 Chrome。在该窗口中完成验证并重试；下次调用会验证页面、恢复隐藏窗口保护，并继续使用同一会话。仍可通过 SURF_SEARCH_PROVIDER=fallback 和 SURF_SCHOLAR_PROVIDER=fallback 使用 SearchApi 回退方案。
• Playwright CAPTCHA 恢复有 4 种模式（根据环境变量自动选择）：
  • 默认（本地桌面）：触发系统通知，打开有头模式的 Chrome，然后返回调用；完成验证后重试
  • SURF_HEADLESS=false：打开有头模式的 Chrome，不触发通知；完成验证后重试
  • SURF_REMOTE_DEBUG=true：输出 DevTools 端口和说明，在本地连接 chrome://inspect 完成验证
  • SURF_CLOUD_MODE=true：快速失败并返回 CAPTCHA_REQUIRED 错误
• 有头模式的 Chrome 打开后显示的是普通搜索框，而不是 CAPTCHA：在搜索框中输入任意查询并按 Enter 即可。后续调用将正常工作。
• “未找到 Chrome”：安装 Chrome 或设置 CHROME_PATH。
• 选择器过期：运行时会按策略重新排序（由 SURF_SELF_HEALING 控制，具有确定性）；此外，还可手动触发修复工作流（SURF_LLM_HEAL 可选，需人工审核，绝不会自动合并）。
• Playwright 搜索速度低于预期：检查 health().pool.fallback。true 表示工作线程池使用的是单个上下文。原生搜索会在 MCP 会话之间使用一个经过身份验证的本地浏览器代理。该代理保留一个隐藏的 Chrome 进程，并为 search、search_parallel 和 scholar_search 提供最多四个可重复使用的标签页。查询会错开启动。出现 CAPTCHA 时会显示并保留该会话，供用户完成验证；下次调用时会恢复窗口保护。浏览器崩溃后，下次调用会启动新会话。
• SSRF：extract 默认会拦截 localhost、私有 IP 和 AWS 元数据。设置 SURF_ALLOW_PRIVATE=true 可允许访问这些地址。
• 清理缓存：npm run cache:clear 会删除搜索、提取和下载的向量模型缓存，但不会删除研究数据库。
• 本地研究数据库未加密。若设备或备份需要静态数据保护，请使用操作系统账户权限和 BitLocker 或 FileVault 等磁盘加密功能。

更新日志

请参阅 CHANGELOG.md。

许可证

MIT