wigolo 接入契约：MCP、REST、CLI 和 SDK 怎样给 Agent 提供可控 Web 能力

给 Agent 接 Web 能力，最危险的做法是把“浏览器”直接交给模型。wigolo 提供了更工程化的选择：MCP 面向模型工具调用，REST 面向服务集成，CLI 面向本地脚本，SDK 面向应用代码。真正要评估的是这些接口能否形成稳定契约：参数可控、结果结构化、失败可识别、权限可收回、调用可审计。

官方仓库 KnockOutEZ/wigolo 的定位是 local-first web intelligence for AI agents。v0.2.1 发布于 2026-07-19，HEAD 为 180ac3d7c39c8768fb4ed8ea25bd9a84bb57497b，主要语言 TypeScript，许可证 AGPL-3.0-only，Node.js >=20。核心搜索、抓取、爬取、抽取、缓存和相似查找不需要 API key；LLM 只在合成环节可选。这组事实决定了它适合作为 Agent 平台的基础工具层，而不只是个人命令行玩具。

MCP：给模型的工具边界

MCP 的意义是让 Agent 看到可枚举工具，而不是让模型自由解释网页。一个合理的接入方式是只暴露必要工具：问答 Agent 可以使用 search、fetch、extract；巡检 Agent 可以使用 watch、diff；知识库 Agent 可以使用 crawl、cache、find_similar。不同任务不应共享同一套无限权限。

{
  "mcpServers": {
    "wigolo": {
      "command": "wigolo",
      "args": ["mcp", "--config", "./wigolo.config.json"]
    }
  }
}

配置里还应限制最大 crawl 深度、单域名速率、私有地址访问、响应体大小和超时时间。Agent 工具调用一旦进入自动化流程，限制就不能只靠提示词。

REST：服务端集成更适合结构化调用

REST API 适合把 wigolo 接入内部平台、任务队列和审计系统。典型调用可以由服务端发起，统一注入 token、trace id 和超时策略：

curl -sS -H "Authorization: Bearer $WIGOLO_TOKEN"   -H "Content-Type: application/json"   -d '{"query":"wigolo docs tools configuration","limit":5}'   http://127.0.0.1:8787/v1/search

具体端点以官方 rest-api 文档为准，设计原则更重要：生产系统不要解析 CLI stdout，不要让前端直接持有高权限 token，不要把非 loopback 服务暴露在没有 token 的网络上。v0.2.1 release notes 明确提到 REST auth、body、timeout 相关改进，说明接口层正在处理真实集成痛点。

CLI：适合人和脚本，不适合偷懒做生产协议

CLI 的优势是低摩擦。开发者可以快速验证搜索和抽取：

wigolo search "Node.js 20 installation docs"
wigolo fetch "https://github.com/KnockOutEZ/wigolo"
wigolo crawl "https://knockoutez.github.io/wigolo/" --max-depth 2

但 CLI 不应成为生产 Agent 的唯一协议。stdout 格式、日志、进度输出和错误提示更适合人读。若需要生产集成，应优先用 REST 或 SDK，并把错误码、耗时、缓存命中、blocked_by_challenge、rate limit 等字段写入审计日志。

SDK：把 Web 情报放进业务代码

官方 docs/sdks.md 覆盖 SDK 用法。SDK 的价值是减少 shell 包装，让应用直接调用 search、fetch、extract、cache 等能力。研究平台可以把 SDK 封装成“证据采集任务”；代码助手可以把 SDK 封装成“读取官方文档”；监控系统可以把 watch/diff 封装成“变更通知”。

SDK 接入时要保留三类字段：原始 URL 与抓取时间，缓存键与内容 hash，失败状态与原因。没有这些字段，下游报告很难复查，也难以解释为什么一次 Agent 运行和下一次运行结论不同。

安全和网络边界

wigolo 的 privacy-security 文档强调 robots respect、rate limits、SSRF/private-target guards，非 loopback serve 需要 token。这些不是附加项，而是接入契约的一部分。Agent 平台里最小边界应包括：默认只监听 127.0.0.1；跨主机访问必须 token；禁止访问内网、metadata service 和私有 IP 段；默认遵守 robots；对每个域名设置速率；浏览器升级需要单独开关和资源限制。

结论

wigolo 的集成价值来自多接口一致性：MCP 给模型用，REST 给服务用，CLI 给开发者用，SDK 给应用代码用。接入时不要只验证 happy path 搜索结果，还要验证 blocked_by_challenge、超时、缓存命中、robots 拒绝、私有地址拦截、token 失败和非 loopback 暴露。只有失败语义稳定，Agent 才能把 Web 当作可靠工具，而不是不可控的外部幻觉来源。