Wigolo Windsurf 全局规则指南为 AI 编码 Agent 配置本地优先的 Web 智能工具链【免费下载链接】wigoloThe go-to web for your AI coding agent — local-first search, fetch, crawl research over MCP. No API keys, no cloud, $0/query. Public beta.项目地址: https://gitcode.com/GitHub_Trending/wi/wigolo导读本文围绕仓库中为 Windsurf 准备的 rules-global.md 全局规则展开系统讲解 Wigolo 这套本地优先Local-firstWeb 智能 MCP 工具链在 AI 编码 Agent 中的最佳实践——从缓存优先、搜索升级的十条升级阶梯Escalation ladder到search/fetch/crawl/extract/research等核心工具的参数速查与调用规范。读完本文你将掌握如何让 Agent 在零 API Key、零云依赖的前提下用更便宜、更可复现的方式完成搜索、抓取、爬取与研究工作并理解每条规则背后的源码实现依据。为什么 Windsurf 需要一份全局 Web 智能规则Windsurf 的全局规则global rules会注入到每一次 Agent 会话上下文中用于约束 Agent 的默认行为。仓库中的rules-global.md只做了一件事告诉 Agent 所有 Web 操作优先使用 Wigolo 的 MCP 工具而不是内置的 WebSearch / WebFetch。它与项目级规则rules-project.md配合使用前者负责全项目通用约束后者负责当前仓库的具体配置。这份规则背后对应的是一个通过 stdio 传输运行的 MCP 服务器SKILL.md 与 mcp_config.json.block 中有完整配置示例。Windsurf 侧接入方式如下{ mcpServers: { wigolo: { command: npx, args: [wigolo] } } }首次使用建议先执行npx wigolo warmup安装浏览器引擎并引导搜索后端可选npx wigolo warmup --all安装 Firefox、WebKit、ML 重排序器与向量嵌入模型。接入后Agent 的所有联网操作都会落在本地缓存与可解释的评分体系内这正是rules-global.md强调的三点价值Local-first结果本地化处理无云端往返Zero API keys不需要申请任何搜索或抓取服务的密钥ML-reranked多引擎结果经过机器学习重排序与缓存复用。十条升级阶梯Agent 应该先查缓存再上网rules-global.md的核心骨架是一条升级阶梯Escalation ladder它定义了从最便宜到最重型的十级操作顺序。Agent 应当严格按此顺序决策阶梯工具适用场景1cache总是先查本地缓存即时、免费2search还没有 URL用多查询数组multi-query arrays扩大覆盖面3fetch已有 URL取回干净的 Markdown4crawl需要整个站点区块如文档、API 参考5extract需要结构化数据表格、JSON-LD、schema6find_similar已有优质来源想找相关内容的延伸阅读7research需要带引用的综合分析8agent需要自主的多源数据收集9diff对比两个页面版本10watch持续监控页面随时间的变化这条阶梯的底层逻辑是成本优先缓存命中零网络开销、零费用搜索比逐页抓取便宜结构化提取比全文阅读更省 Token。仓库在 skills/wigolo/rules/cache-first.md 中给出了更量化的理由——缓存命中是 0ms 网络、免费、且已经是干净 Markdown一次冗余的 fetch 会浪费 5–15 秒。十个工具的参数速查One-linersrules-global.md用紧凑的 One-liners 形式概括了每个工具的核心参数下面逐一展开为可直接套用的调用模板参数默认值与取值范围取自 tool-schemas.ts 的真实定义。search多引擎搜索与 ML 重排序{ query: [react server components patterns, RSC data fetching, react server components streaming], category: docs, include_domains: [react.dev], max_results: 5 }query支持字符串或字符串数组传数组时各变体并行搜索、去重后统一重排序通常 3–5 个关键词变体比单个长句召回更多来源include_domains/exclude_domains按域名白名单/黑名单过滤框架类查询务必带上官方站点format: answer请求 LLM 采样合成直接答案采样不可用时回退为证据形式search_depthultra-fast纯缓存≤300ms/fast≤1s仅引擎不抓正文/balanced默认完整流水线/deep最大富集。从实现看handleSearch是薄处理器src/tools/search.ts真正的编排在 src/search/core/ 下完成核心 provider 在ultra-fast模式下缓存未命中时直接返回空结果并附带说明而不是强行发起网络请求见 core-provider.ts 中ultraFastMiss分支。fetchURL 到干净 Markdown{ url: https://react.dev/reference/react/useState, section: Parameters }section只返回指定标题下的内容是读取长页面最省成本的方式section_index指定命中第几个同名校标题默认 0use_auth复用已保存的浏览器会话抓取登录后内容force_refresh绕过缓存强制拉取新内容适用于新闻、状态页、changelog 等高频变动页面其他常用项render_js: auto | always | never、max_content_chars智能截断、actions提交前依次执行 click/type/wait/scroll 等浏览器动作。crawl整站或站点区块爬取{ url: https://docs.python.org/3/library/, strategy: sitemap, max_pages: 30, include_patterns: [^https://docs\\.python\\.org/3/library/asyncio] }strategybfs默认广度优先/dfs/sitemap读 sitemap.xml对文档站更快更全/map仅返回 URL 清单不抓正文用于爬取前低成本圈定范围include_patterns/exclude_patterns正则白名单/黑名单必须配置以避免把导航、页脚和垃圾 URL 一起抓进来每次爬取的内容都会落进本地缓存并生成嵌入向量为后续find_similar提供素材。cache本地知识库查询{ query: oauth2 pkce, url_pattern: *auth0.com* }query全文检索支持AND/OR/NOT/精确短语modefts默认FTS5 关键字 BM25 检索或hybrid关键字 语义向量二者通过 Reciprocal Rank Fusion 融合召回更高向量索引不可用时自动回退 FTS见 src/tools/cache.ts 的runHybridSearchstats返回缓存总量统计check_changes重新抓取匹配条目并报告变化与 diff 摘要clear删除匹配条目必须至少带一个过滤条件。extract超越 Markdown 的结构化提取{ url: https://example.com/pricing, mode: structured }mode: structured一次调用同时返回表格、dl定义列表、JSON-LD、图表提示与键值对优先于串联多次 extractschemaJSON Schema 定义精确字段字段值会对照页面来源校验幻觉值返回 null工具 schema 的描述明确注明 hallucinated values returned as nullnamed_schemaArticle/Recipe/Product/CodeSnippet/Paper/EventListing/JobPosting等严格命名 schema纯启发式匹配、无需 LLM与schema互斥其余模式selectorCSS 选择器、tables、metadata、brandLogo/配色/字体/社交链接带来源溯源。find_similar相似内容发现{ url: https://react.dev/reference/react/useMemo, max_results: 6, include_domains: [react.dev] }url或concept二选一传 URL 会先抓取或读缓存再分析关键术语没有具体 URL 时用概念描述融合三种信号本地关键字 语义向量 实时 Web 搜索使用 Reciprocal Rank Fusionk60src/search/rrf.ts本地信号弱时会返回cold_start提示字符串——规则要求 Agent 把这段说明原样转述给用户在crawl之后使用效果最好。research多步研究流水线{ question: How do modern JS bundlers tree-shake ESM vs CJS?, depth: standard, include_domains: [webpack.js.org, rollupjs.org, esbuild.github.io, vitejs.dev] }depthquick约 15s/standard约 40s默认/comprehensive约 80s7 个子查询、20–25 个来源max_sources覆盖深度默认来源数上限 50schema让报告按指定字段结构化输出research内部会自动查缓存无需预先探测MCP sampling 可用时直接合成报告否则输出带topics/highlights/key_findings的brief脚手架由宿主 LLM 据此撰写最终报告。agent自然语言多源数据收集{ prompt: Compare pricing tiers for Supabase, Firebase, and Clerk, schema: { type: object, properties: { provider: { type: string }, free_tier: { type: string }, paid_start: { type: string } } }, max_pages: 12 }prompt必填自然语言描述要收集什么urls可预置种子 URLschema对每个页面做结构化提取并合并max_pages默认 10上限 100、max_time_ms默认 60000输出包含steps数组记录 plan → search → fetch → extract → synthesize 每一步的动作与耗时可用于排查弱结果。diff页面版本对比{ old: { url: https://docs.example.com/api }, new: { url: https://docs.example.com/api }, output: hunks, granularity: section }old侧支持{ url, markdown, content_hash }new侧支持{ url, markdown }outputunifiedgit 风格补丁默认/hunks按区块分段的结构化 diff/summary仅行数统计granularityline默认/word行内 token 级适合行内编辑/section按 H1/H2/H3 边界两侧填同一个 URL 时用新鲜抓取对比缓存副本old侧填 URL 但缓存缺失会返回cache_miss并提示先 fetch/crawl见 src/tools/diff.ts 的resolveSide。watch页面变更监控{ action: create, url: https://nodejs.org/en/blog, interval_seconds: 21600 }actioncreate/list/check/pause/resume/deleteinterval_seconds创建时必填最小 60 秒notificationinline下次 check 时返回结果默认或 SSRF 防护的 webhook URLwatch 采用惰性执行模型没有后台守护进程检查发生在调用check或某个过期 job 被其他工具运行顺带触发时src/watch/scheduler.ts 的注释明确说明了这一设计webhook 目标受 src/watch/ssrf.ts 防护不能指向内网或回环地址。四条硬性规则与背后的工程理由rules-global.md末尾用一行概括了最关键的四个约束它们不是风格偏好而是被实现与测试支撑的行为准则Cache before search——cache命中即时且免费先探测缓存再决定是否上网research和agent内部已做缓存检查无需手动预探测见 skills/wigolo/rules/cache-first.md 的 Exceptions。Keyword arrays not questions——搜索用关键词数组而非自然语言问句。how do I debounce in React hooks不如react useDebounce hook custom单查询在低召回时核心 provider 还会基于同义词映射自动触发一次改写并通过query_understanding.rewrites回报core-provider.ts。include_domainsfor framework queries——框架/库查询必须限定官方域名避免搜索引擎把无关页面混进结果。search_depth: ultra-fastfor sub-second budgets——对硬性亚秒级延迟要求只能接受缓存命中冷缓存无法赶在截止时间前完成一次真实网络往返此时应明确降级为纯缓存模式或直接跳过联网。配套的rules-project.mdassets/blocks/windsurf/rules-project.md还补充了搜索后端选择默认WIGOLO_SEARCHcore直连引擎 RRF ML 重排可选searxng旧聚合器与hybridcore 为主、信号异常时自动回退响应带fallback_signal标记。响应字段Agent 可消费的可解释信号无论调用哪个工具返回结构都包含一组通用响应字段便于 Agent 判断结果可信度evidence_score证据评分衡量结果与查询的相关程度query_understanding查询理解信息含自动改写记录brand_collision_warning品牌冲突预警freshness_signal时效性信号response_time_ms本次调用耗时engine_telemetry各搜索引擎的遥测数据。这些字段在 mcp_config.json.block 的 Response fields 一节也有并列说明。Wigolo 本身不内置 LLM它返回的是结构化证据最终答案由宿主模型也就是你撰写——因此 Agent 应把这些字段保留进回答而不是折叠丢弃。工作流速查表与反模式清单参数速查Parameter Cheat Sheet场景推荐调用已知站点的定点查找searchmax_results: 3include_domains宽泛主题调研searchquery: [...3-5 变体]max_results: 8必须最新内容任意工具 force_refresh: true文档站索引crawlstrategy: sitemap仅要站点 URL 清单crawlstrategy: map长页面只读一个小节fetchsection: ...登录后内容fetch/crawluse_auth: true需要直接答案searchformat: answer需要带引用的段落searchformat: highlights复杂问题多源综合researchdepth: standard多页结构化提取agentschema单页结构化数据extractmode: structured变更追踪cachecheck_changes: true典型工作流缓存优先查找先cache({ query: oauth2 pkce, url_pattern: *auth0.com* })落空再search({ query: oauth2 pkce flow, include_domains: [auth0.com] })。限定范围的文档研究先crawlsitemap 策略、限制max_pages与include_patterns再cache查询缓存例如抓取 docs.astro.build 后用cache({ query: server islands hydration, url_pattern: *docs.astro.build* })。结构化多源采集agent配schema一次跑完替代 5 次手动 search/fetch。必须避免的反模式跳过缓存直接 search/fetch内容已在磁盘时纯属浪费向search传自然语言问句关键词数组召回更稳不带过滤器爬max_pages: 100导航、页脚、sitemap 垃圾全进来必须加include_patterns默认开force_refresh: true这等于废掉缓存只对新闻/状态/changelog 类页面使用给extract传没有properties的 JSON Schema处理器会直接拒绝。部署接入与配置参考全局规则生效的前提是 MCP 服务器已正确接入 Windsurf。完整配置块见 mcp_config.json.block其中还包含一张任务 → 工具 → 关键参数速查表可作为rules-global.md的补充。常用环境变量全部可选、默认值安全变量默认值作用WIGOLO_DATA_DIR~/.wigolo缓存库、搜索状态、插件、嵌入向量WIGOLO_RERANKERnone设为flashrank启用 ML 重排WIGOLO_EMBEDDING_MODELBAAI/bge-small-en-v1.5find_similar使用的嵌入模型CACHE_TTL_CONTENT6048007 天缓存页面过期秒数WIGOLO_CDP_URL未设置Chrome DevTools 端点供use_auth使用LOG_LEVELinfo日志级别完整的变量清单可查看 src/config.ts。需要深入理解每个工具的参数校验与默认值时建议对照 tool-schemas.ts十份 schema 的权威定义与 SKILL.md含完整 CLI 命令、工作流示例与反模式清单一起阅读——这份全局规则文件是它们的浓缩指令形态适合作为 Agent 每次会话的第一份上下文。【免费下载链接】wigoloThe go-to web for your AI coding agent — local-first search, fetch, crawl research over MCP. No API keys, no cloud, $0/query. Public beta.项目地址: https://gitcode.com/GitHub_Trending/wi/wigolo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考