企业官网建设流程全解析

Claude Code 快速参考：wigolo 本地优先 Web 智能工具的 10 个 MCP 工具实战指南

【免费下载链接】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

本文是 wigolo 为 Claude Code 提供的命令速查文档（仓库中对应assets/blocks/claude-code/wigolo-command.md）的深度展开。该命令块面向在 Claude Code 中开发、调试、调研的场景：无需任何 API Key、不经过云端、零成本地完成搜索、抓取、爬站、缓存、结构化提取、相似内容发现、深度研究与页面变化监控。读完本文，你将掌握 wigolo 10 个 MCP 工具的选型逻辑、核心参数、常见调用模式，以及这些工具在仓库源码中的真实实现位置，可直接在 Claude Code 中按需取用。

命令块在 Claude Code 中的角色

wigolo-command.md会被安装为 Claude Code 的 slash command（/wigolo），源码在 src/cli/agents/claude-code.ts 中把该文件写入~/.claude/commands/wigolo.md：

async function installCommand(): Promise<void> { const content = readAsset('blocks/claude-code/wigolo-command.md'); const commandsDir = join(claudeDir(), 'commands'); mkdirSync(commandsDir, { recursive: true }); writeFileSync(join(commandsDir, 'wigolo.md'), content, 'utf-8'); }

与之配套安装的还有三件事（见同一文件的installMcp/installInstructions/installSkills）：

• MCP 服务注册：claude mcp add wigolo --scope user -- <command>，--scope user保证只写入一次用户级配置，避免每个目录重复写入脏行；
• 全局指令块：~/.claude/CLAUDE.md中注入assets/blocks/claude-code/CLAUDE.md.block（引导 Agent 对 Web 操作优先使用 wigolo 而非内置 WebSearch/WebFetch）；
• Skills：由技能引擎安装skills/目录下的全套技能包（如 skills/wigolo/SKILL.md）。

10 个 MCP 工具一览

wigolo 提供 10 个 MCP 工具，覆盖本地优先 Web 访问的完整闭环。下表是命令块中的选型速查表，本文按列展开：

十个工具在仓库中的对应实现为 src/tools/ 目录下的同名处理函数（handleSearch、handleFetch、handleCrawl、handleCache、handleExtract、handleFindSimilar、handleResearch、handleDiff、handleWatch），参数校验、默认值与错误提示都能在源码中直接核实。

工具详解与源码佐证

search：多查询、可排序、带直接答案的搜索

search是最核心的工具，query接受字符串或字符串数组（数组形式用于广度召回）。完整参数见命令块配套的CLAUDE.md.block：

• query：字符串或字符串数组，数组传 3-5 个关键词变体可获得更广召回；
• include_domains/exclude_domains：限定/排除站点，官方库框架查询（如["react.dev", "nextjs.org"]）必传；
• category、time_range（day/week/month/year）、from_date/to_date、country：时效与地域约束；
• exact_match：短语精确匹配；
• search_depth：ultra-fast（仅走缓存、亚秒级预算）/fast（≤1s）/balanced（默认）/deep（最大增强）；
• include_images/include_favicon：富媒体字段；
• format：answer或stream_answer触发合成式直接答案，默认返回带证据形状的结果供引用。

在源码 src/search/core/core-provider.ts 中可以看到search_depth的实际语义：默认balanced；当depth === 'ultra-fast'且未命中缓存时会给出 cache-miss 提示（data.notice = 'cache miss, retry with search_depth=fast or higher'），而fast档会短路内容抓取阶段，deep档才会走完整增强链路。入口 handler 位于 src/tools/search.ts，按WIGOLO_SEARCH环境变量选择 provider。

fetch：单页抓取，支持段落提取与强制刷新

fetch抓取单页并转换为 Markdown，核心参数：url、section（按标题提取指定段落）、use_auth、render_js（默认auto）、max_content_chars、force_refresh。

源码 src/tools/fetch.ts 揭示了完整的执行链路：请求先经过 URL 预校验（拒绝 localhost 非法端口，例如localhost:99999）与 SSRF 防护（默认阻断内网段与云元数据端点，WIGOLO_FETCH_ALLOW_PRIVATE=1可放行家庭局域网设备）；随后优先查缓存，force_refresh或缓存过期时才走实时抓取；抓取成功后写入缓存并异步生成 embedding。响应体还包含content_hash（全文 sha256 指纹）、http_status、fetch_method（cache/http/tls/playwright等路由层选中的通道）、changed/diff_summary变化信号，以及site_data（Reddit、YouTube、Amazon 等站点的结构化 JSON，见 src/extraction/site-extractors/）。

值得注意的两个"防静默失败"设计（代码注释中有明确说明）：section未命中时不会返回整页兜底，而是清空正文并置section_matched: false供调用方分支处理；纯文本端点（raw.githubusercontent.com等）返回 4xx/5xx 时直接把 HTTP 错误上抛，避免把错误体当成正文喂给抽取器。

crawl：整站爬取，四种策略

crawl的strategy支持sitemap（优先 sitemap）/bfs/dfs/map四种，配合max_depth、max_pages、include_patterns使用。源码 src/tools/crawl.ts 显示map是轻量分支——只做 URL 发现（返回urls、total_found、sitemap_found），不走完整爬取管线；其余策略由 src/crawl/crawler.ts 驱动，逐页复用handleFetch，抓取后还会做跨页内容去重（deduplicatePages，见 src/crawl/dedup.ts）。

响应默认带整页 Markdown（include_full_markdown默认true），并受max_total_chars（默认 100000 字符）与随页数缩放的平均 token 预算约束（每页约 2000 token，上限 60000，见PER_PAGE_TOKENS/MAX_TOKENS_OUT_CEILING常量）；超预算的页面会被截断并统计在dropped_over_budget中，而不是悄悄丢失。

cache：本地持久化知识缓存，永远先查

cache是本地优先理念的基石：query、url_pattern（如*auth0.com*）、since、stats（返回缓存统计）、limit、clear、check_changes。源码 src/tools/cache.ts 展示了query搜索的默认返回上限为5 条（DEFAULT_CACHE_QUERY_LIMIT），防止缓存表里成千上万行数据撑爆 token 预算；mode: "hybrid"时走 FTS5 全文检索 + 向量检索的混合路径，用 Reciprocal Rank Fusion（k=60）融合后返回（见 src/tools/cache.ts）。check_changes则对匹配条目重新抓取并运行detectChange，把 200→404 这类状态码变化也识别为变更。

规则第一条就是"先 cache 后 search"——命中时零延迟返回完整 Markdown，且不消耗任何外部请求。

extract：六种抽取模式的结构化数据提取

extract的mode支持metadata（默认）、structured、schema、tables、selector、brand，另有named_schema命名模式。源码 src/tools/extract.ts 中可以看到每个模式的真实行为：

• structured：extractStructured生成结构化 JSON（src/extraction/structured.ts）；
• tables：合并<table>与 div/flex 网格卡片（detectDivGridTables），因此纯 div 布局的定价页也能抽出表格；空结果会返回no_tables_detected并提示可重试execution_mode: "stealth"；
• schema：按 JSON Schema 抽取，有required字段时走extractWithSchemaDetailed，可配合本地 LLM 补全缺字段，但补全值会经过 evidence-only 过滤器——凡在原文中找不到依据的模型猜测字段会被置为null并在warnings中点名，杜绝幻觉数据；
• selector：需同时传css_selector，支持multiple；
• brand：JSON-LD/OG/favicon/CSS 变量 + 图片 k-means 调色板（src/extraction/brand.ts）。

所有模式都支持max_tokens_out，超限时表格按行优先裁剪（保留表头结构）、数组保留前部、超长字符串就地截断，并用warnings明确列出每次裁剪，保证"没有静默的数据丢失"。

find_similar、research、agent：发现、研究、收集

• find_similar：传url或concept找相关内容，threshold控制相似度门槛。源码 src/tools/find-similar.ts 显示一个贴心细节：当传入 URL 且该域名缓存不足 5 条时，会自动用"末路径段 + 主域名"构造种子查询触发一次搜索来预热缓存（冷启动，cache_seeded: true）；max_results上限 50；
• research：question+depth（quick/standard/comprehensive）+schema，max_sources上限 50（src/tools/research.ts），由 src/research/pipeline.ts 驱动分解、检索、来源验证与综合；
• agent：用prompt+schema+urls/max_pages/max_time_ms让 Agent 自主收集数据。

diff与watch：版本对比与变化监控

diff的old/new各接受url、markdown或content_hash三种输入形态，output支持unified/hunks/summary，granularity支持line/word/section（默认unified+line）。源码 src/tools/diff.ts 显示 URL 形态会从本地缓存取内容，缓存未命中时明确报cache_miss并提示先fetch/crawl填充缓存，或直接传 markdown。

watch的action为create/list/check，interval_seconds最小 60 秒（MIN_INTERVAL_SECONDS），支持urls批量创建（上限 1000 条）与 webhooknotification。值得注意的实现模型（src/tools/watch.ts 注释）：watch 是惰性执行的，没有常驻后台守护进程——检查只在显式调用check、或任意其他工具执行后发现任务逾期（scheduleOverdueCheck）时触发。SSRF 防护在注册时就已施加，坏 URL 永远不会落进持久化状态。

常用调用模式（原命令块示例完整解读）

命令块给出的 6 个典型模式，每一行都对应一种高频实战场景：

// 1) 缓存优先查询：先查本地缓存，命中秒回；未命中再落到 search cache({ "query": "oauth2 pkce", "url_pattern": "*auth0.com*" }) // → 若为空，再执行搜索兜底 // 2) 多查询广度搜索 + 直接答案合成 search({ "query": ["react hooks 2026", "useEffect patterns", "react state management"], "format": "answer" }) // 3) 亚秒级纯缓存搜索（search_depth 最低档，命中即回） search({ "query": "react hooks", "search_depth": "ultra-fast" }) // 4) 短语精确错误检索（排错场景：字面量匹配 + code 分类） search({ "query": "Cannot read properties of undefined", "exact_match": true, "category": "code" }) // 5) 定向文档段落抓取（只取 Parameters 一节，响应更紧凑） fetch({ "url": "https://react.dev/reference/react/useState", "section": "Parameters" }) // 6) 站点索引：以 sitemap 策略爬取前 30 页，为后续 find_similar 预热本地缓存 crawl({ "url": "https://docs.example.com", "strategy": "sitemap", "max_pages": 30 })

模式 3 依赖ultra-fast档"只查缓存、不触网"的设计（见前文core-provider中 251 行附近的 cache-miss 提示逻辑）；模式 6 之所以推荐crawl后紧跟find_similar，正是因为相似度检索在本地缓存预热后效果最佳。

使用规则与响应字段

配套的 assets/blocks/claude-code/CLAUDE.md.block 给出了 Agent 侧的 8 条使用规则，是命令块的最佳实践补充：

1. 先查缓存再搜索：cache命中即返回完整 Markdown；
2. 用关键词而非问句：query传 3-5 个关键词变体保证广度召回；
3. 库/框架查询必须限定官方域名：始终传include_domains；
4. 按预算选深度档：ultra-fast亚秒、fast≤1s、balanced默认、deep最大增强；
5. 短语查询用exact_match: true；
6. 直接答案用format: 'answer'/'stream_answer'，引用工作用默认证据形状；
7. 新闻/价格/状态要新鲜度：设force_refresh: true，配time_range/from_date/to_date限定时间窗；
8. crawl 后紧跟 find_similar：本地缓存温热时效果最佳。

处理响应时建议向用户呈现以下字段：evidence_score（证据得分拆解：相关度、域名质量、词法对齐、新鲜度）、query_understanding（意图/实体/日期提示/语言/品牌冲突风险的分类视图）、brand_collision_warning（品牌-域名冲突 Top-3 及改写建议）、freshness_signal（发布日期与置信度）、response_time_ms、engines_used/engine_telemetry（各引擎延迟与去重统计）、fallback_signal（仅 hybrid 模式，指明触发的回退信号）。

搜索后端：core / searxng / hybrid

默认WIGOLO_SEARCH=core，即直连搜索引擎 + RRF 融合 + ML 重排（核心编排在 src/search/core/）。两个可选模式：

• searxng：遗留聚合器，需显式开启，长尾召回更高但冷启动更慢；
• hybrid：先跑core，当信号触发（brand_collision_suspect、include_domains_over_filter、all_engines_failed、top1_high_score_low_overlap）时回退到searxng并做 RRF 融合，响应携带fallback_signal指明触发原因。

在 Claude Code 中的安装与卸载

安装由wigolo install完成（对应 src/cli/agents/claude-code.ts 的installMcp/installInstructions/installSkills/installCommand四步），卸载由uninstall完成：claude mcp remove wigolo --scope user、移除~/.claude/CLAUDE.md中的指令块、删除~/.claude/commands/wigolo.md。技能目录的清理由技能引擎按 receipts 处理，避免误删用户改过的文件。

完整文档与逐工具技能说明位于~/.claude/skills/wigolo/SKILL.md与各工具技能中，仓库内的源文件可参考 skills/wigolo/SKILL.md、skills/wigolo-agent/SKILL.md、skills/wigolo-cache/SKILL.md 等全套技能包。

【免费下载链接】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