wigolo one-shot CLI把 search、fetch、research 当作普通终端命令的实战指南【免费下载链接】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 仓库的 one-shot CLI 示例 为核心讲解如何在不启动服务器、不管理会话的前提下用wigolo tool args一行命令直接完成网页搜索、页面抓取与多步调研并借助--json让结果可以无缝接入jq、Shell 脚本与任意编程语言。读完本文你将掌握 one-shot CLI 的完整命令集、输出契约、退出码语义以及这些能力在底层源码中的实现路径。核心思想每个 MCP 工具都是一条终端命令wigolo 是一个 local-first 的 AI 编码 Agent 基础设施搜索 / 抓取 / 爬取 / 调研均通过 MCP 暴露。one-shot CLI 示例点出了它的一个关键设计每一个工具既是 MCP 工具也是一条普通终端命令。不需要先启动 daemon、不需要维护一个交互式 session直接执行wigolo tool args结果是stdout日志是stderr退出码可以直接作为脚本分支的判定依据。这与通常的先起服务、再调 API模式形成了鲜明对比——一次命令一次结果进程退出即结束。从源码角度one-shot 命令是 CLI 子命令体系的正式成员。在 src/cli/index.ts 中Command联合类型里与mcp、serve、shell等并列声明了 11 个工具命令search、fetch、crawl、extract、cache、find-similar及蛇形别名find_similar、research、agent、diff、watch。parseCommand会把首个参数与已知命令集合比对命中即把剩余参数作为工具参数继续分发。环境准备运行 one-shot CLI 需要Node.js ≥ 20jq仅当你要用--json | jq解析结果时必需run.sh脚本最后一步使用了它两条使用路径# 方式一无需全局安装通过 npx 直接运行 npx wigolo search css grid layout guide --max-results 5 # 方式二先全局安装 wigolo再直接调用 npm install -g wigolo wigolo search css grid layout guide --max-results 5三个开箱即用的示例命令README 给出了三条最小可用示例覆盖了 wigolo 最常用的三个工具# 1. 搜索带评分排序的结果列表 npx wigolo search css grid layout guide --max-results 5 # 2. 抓取任意 URL 转成干净 Markdown npx wigolo fetch https://developer.mozilla.org/en-US/docs/Web/API/structuredClone # 3. 调研多步问题分解 结构化简报直接管道给 jq npx wigolo research how does sqlite full text search work --depth quick --json \ | jq -r .brief.highlights[0].text其中第三条命令值得拆解--depth quick指定调研深度为快速档--json让整个输出变成机器可读的 JSON随后| jq -r .brief.highlights[0].text直接提取简报的第一条核心要点。这证明了research 的输出并非一段无法解析的散文而是带brief、highlights、sources、citations等结构化字段的完整对象对应的输出类型定义见 src/types.ts 的ResearchOutput与ResearchBrief。一键跑完三个工具run.sh示例目录里的 run.sh 把上面三条命令串成了一个脚本并允许通过环境变量覆盖要调用的 wigolo 二进制./run.sh # 使用 npx wigolo WIGOLOwigolo ./run.sh # 使用全局安装的 wigolo或任何你偏好的二进制/入口脚本内部的关键逻辑默认WIGOLO${WIGOLO:-npx wigolo}因此不设置环境变量时走 npx 路径set -euo pipefail保证任何一步失败都会中断脚本并暴露非零退出码依次输出 search带评分、fetch干净 Markdown、research经 jq 提取的要点三段演示。在演示录制脚本 demo.tape 中还能看到同样的命令序列它额外演示了--json | jq .results[0]提取单条结果字段的用法并说明 repeat 查询走本地缓存后响应在毫秒级——这也是下文3ms数字的真实来源。输出解读三种工具返回什么search带证据评分的排序结果Search: css grid layout guide (5 results, 3ms, engines: mdn, duckduckgo) [1] Basic concepts of grid layout - developer.mozilla.org (score: 1.00) CSS grid layout introduces a two-dimensional grid system to CSS. Grids can be used to lay out major page areas or small user interface elements. ... [2] Relationship of grid layout to other layout methods - developer.mozilla.org (score: 0.91) CSS grid layout is designed to work alongside other parts of CSS, as part of a complete system for doing the layout. ...首行汇总了查询词、结果数、耗时与命中的引擎列表每条结果带[n]序号、标题、域名与scorerelevance_score取值 01。这个格式由 src/repl/formatters.ts 的formatSearchResults生成。值得注意的细节是那个3ms是真实的重复查询直接命中本地知识缓存local knowledge cache无需再次访问搜索引擎首次运行才会真正请求引擎约数秒而学到的内容会全部落盘供后续复用。这与项目local-first、无 API key、无云依赖的定位一致。在--json形态下SearchOutput见 src/types.ts会携带比终端文本更丰富的信息包括engines_used、engine_telemetry每个引擎的延迟与结果数、evidence证据片段、citations等字段。fetch任意 URL 变成干净 MarkdownFetch: https://developer.mozilla.org/en-US/docs/Web/API/structuredClone # Window: structuredClone() method Baseline Widely available [cached: true, 9570 chars]fetch 会把页面正文抽取为干净 Markdown 并在开头预览前几行末尾标注[cached: true/false, N chars]是否命中缓存 字符数。README 特别强调即使是 JS 渲染的页面也能抓取——浏览器引擎只在需要时介入在 src/fetch/browser-pool.ts 与 src/fetch/router.ts 中SmartRouter 会根据页面情况决定走 HTTP 直连层还是浏览器层参见 src/cli/tool-run.ts。research结构化简报与子查询research 会执行多步问题分解返回一份结构化 brief。--json让整个输出可管道化$ npx wigolo research how does sqlite full text search work --depth quick --json \ | jq -r .brief.highlights[0].text At its core, full-text search in SQLite is designed to split text into terms or phrases and index these for fast search retrieval. When a full-text search is queried, it doesnt scan rows linearly. Instead, it uses indexed tokens to match search criteria, making full-text search much quicker than traditional LIKE queries on large datasets.ResearchOutput中除了report长文还包含sources带relevance_score与fetched标记的来源列表、citations引用列表、sub_queries分解出的子问题与brief结构化简报topics、highlights、key_findings、sections等方便下游程序做进一步处理。--json与 MCP 完全同构的机器可读输出one-shot CLI 最实用的特性之一就是--json。它输出的是工具完整输出对象的 JSON 序列化——形状与 MCP 客户端拿到的完全一致包括results、evidence、citations、engine_telemetry等字段。这意味着# 提取第一条结果的标题、URL 与评分 npx wigolo search node worker threads --limit 3 --json | jq .results[0] | {title, url, relevance_score} # 提取调研简报的所有关键发现 npx wigolo research ... --json | jq .brief.key_findings # 查看 fetch 结果的完整元数据 npx wigolo fetch https://example.com --json | jq .metadata在实现层面--json模式下 stdout 上只有JSON零日志泄漏因此对整个 stdout 执行JSON.parse永远可以成功——这是 src/cli/tool-run.ts 中emit函数的有意设计。统一契约结果上 stdout、日志走 stderr、失败退 1README 用四条规则总结了 one-shot CLI 的全部行为契约这也是编写脚本时最重要的依据契约说明结果 → stdout工具输出文本或--json只写 stdout日志 → stderr所有日志通过 logger 走 stderr管道保持干净--json完整输出与 MCP 客户端拿到的形状一致results、evidence、citations、engine_telemetry……失败 → 退出码 1失败时返回 1--json下 stdout 上输出可解析的错误包络error envelope--help全量参数每个工具都支持wigolo tool --help打印完整 flags 集在源码中这些契约在 src/cli/tool-run.ts 的runTool中有明确实现rawArgs.includes(--help) || rawArgs.includes(-h)时打印TOOL_HELP[command]并返回 0失败判定为typeof result.error string result.error.length 0返回码failed ? 1 : 0--json 失败时把携带.error字段的整个结果对象序列化到 stdout本身就是可解析的错误包络非--json 异常时错误写入 stderr 的Error: ...finally中执行browserPool.shutdown()与closeDatabase()确保一次命令不留残留进程。--help从 JSON Schema 实时生成的参数表npx wigolo search --help输出的是从工具 JSON Schema 实时生成的完整参数列表而非手写死文本。机制见 src/cli/help.ts 的buildToolHelp与 src/cli/flag-bridge.ts 的toolFlagSpecs遍历 src/server/tool-schemas.ts 中每个工具的 schema properties自动推导--flag名称、取值类型boolean / number / enum / array-string / object 等与描述再叠加精选的别名行如 search 的--limit、--domains、--from/--to、--no-contentresearch 的--max-sources。这意味着schema 是唯一事实来源工具能力变化时帮助文本自动同步。常用参数速查search参数说明query查询词位置参数--max-resultsN/--limitN最大结果数--domainsa,b仅保留这些域名--exclude-domainsa,b排除这些域名--fromYYYY-MM-DD/--toYYYY-MM-DD发布日期的起止过滤--no-content跳过全文内容增强更快、省 token--json输出机器可读 JSONfetch参数说明url目标 URL位置参数--max-charsN截断返回的 Markdown 长度--section...只返回匹配章节--screenshot同时截图--force-refresh跳过缓存强制重新抓取--json输出完整FetchOutput含metadata、links、cached、content_hash等research参数说明question调研问题位置参数--depthquick\|standard\|comprehensive调研深度默认standard--max-sourcesN来源数量上限--domainsa,b限定调研来源域名--exclude-domainsa,b排除指定域名--json输出结构化简报除此之外crawl、extract、cache、find-similar、agent、diff、watch也全部支持 one-shot 调用每个工具都有自己的子命令/别名体系例如cache stats、cache search query、cache clear [--queryQ] [--url-patternP] [--sinceT]diff url或diff --oldtext --newtext两种模式watch add/list/rm/run/pause/resume详细用法都可以用wigolo tool --help查看。底层实现一次 one-shot 调用的完整生命周期把上面的命令行为与源码对应起来一次npx wigolo research ... --depth quick --json的调用链是命令解析parseCommand识别research为工具命令src/cli/index.ts其余参数交给工具执行器参数桥接--depth、--json等被flag-bridge解析--depth是 research schema 的原生 enum 属性quick|standard|comprehensive校验失败会给出明确的错误信息src/repl/commands/research.ts未知 flag 还会通过 Levenshtein 距离给出--did you mean建议src/cli/flag-bridge.ts环境初始化runTool创建数据目录、初始化 SQLite 数据库wigolo.db、构建SmartRouterHTTP 浏览器池与BackendStatussrc/cli/tool-run.ts引擎装配research/agent/find-similar 等管道直接用keyless 直连引擎DuckDuckGoEngineBingEngine见 src/cli/tool-run.ts 的注释——与 MCP server 使用同一批直连适配器且刻意不启动 searxng sidecar 进程保证 one-shot 场景零额外进程执行与输出dispatch分发到对应 executor如executeResearch拿到结果后emit决定走人类可读文本还是--json格式化逻辑全部集中在 src/repl/formatters.ts--json走formatJsonJSON.stringify(data, null, 2)美化输出收尾关闭浏览器池与数据库连接按失败与否返回 0 或 1。这套实现把一次命令、一次进程、干净退出做成了结构性保证也让 one-shot 模式天然适合 cron 任务、CI 冒烟测试和 Shell 管道。下一步从单条命令到流水线one-shot CLI 是整个 CLI 生态的地基README 提供了四个延伸方向均已转换为仓库根路径Shell NDJSON 流水线在一个进程内串起多条命令输出按 NDJSON 流式交付REST 调用示例同一套工具通过 HTTP daemon 暴露时的 curl 用法TypeScript SDK 示例用类型化客户端在 Node 侧驱动 researchPython SDK 示例用 Python 客户端编排 Agent 数据采集。如果你需要把搜索、抓取、调研能力嵌入到自有脚本、自动化任务或 CI 中one-shot CLI 的 stdout/stderr 分离与退出码契约可以让你用最小的胶水代码完成集成。【免费下载链接】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），仅供参考 
长河君 · 2026/9/18 9:29:32 · 阅读 1.2k wigolo one-shot CLI：把 search、fetch、research 当作普通终端命令的实战指南
wigolo one-shot CLI把 search、fetch、research 当作普通终端命令的实战指南【免费下载链接】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 仓库的 one-shot CLI 示例 为核心讲解如何在不启动服务器、不管理会话的前提下用wigolo tool args一行命令直接完成网页搜索、页面抓取与多步调研并借助--json让结果可以无缝接入jq、Shell 脚本与任意编程语言。读完本文你将掌握 one-shot CLI 的完整命令集、输出契约、退出码语义以及这些能力在底层源码中的实现路径。核心思想每个 MCP 工具都是一条终端命令wigolo 是一个 local-first 的 AI 编码 Agent 基础设施搜索 / 抓取 / 爬取 / 调研均通过 MCP 暴露。one-shot CLI 示例点出了它的一个关键设计每一个工具既是 MCP 工具也是一条普通终端命令。不需要先启动 daemon、不需要维护一个交互式 session直接执行wigolo tool args结果是stdout日志是stderr退出码可以直接作为脚本分支的判定依据。这与通常的先起服务、再调 API模式形成了鲜明对比——一次命令一次结果进程退出即结束。从源码角度one-shot 命令是 CLI 子命令体系的正式成员。在 src/cli/index.ts 中Command联合类型里与mcp、serve、shell等并列声明了 11 个工具命令search、fetch、crawl、extract、cache、find-similar及蛇形别名find_similar、research、agent、diff、watch。parseCommand会把首个参数与已知命令集合比对命中即把剩余参数作为工具参数继续分发。环境准备运行 one-shot CLI 需要Node.js ≥ 20jq仅当你要用--json | jq解析结果时必需run.sh脚本最后一步使用了它两条使用路径# 方式一无需全局安装通过 npx 直接运行 npx wigolo search css grid layout guide --max-results 5 # 方式二先全局安装 wigolo再直接调用 npm install -g wigolo wigolo search css grid layout guide --max-results 5三个开箱即用的示例命令README 给出了三条最小可用示例覆盖了 wigolo 最常用的三个工具# 1. 搜索带评分排序的结果列表 npx wigolo search css grid layout guide --max-results 5 # 2. 抓取任意 URL 转成干净 Markdown npx wigolo fetch https://developer.mozilla.org/en-US/docs/Web/API/structuredClone # 3. 调研多步问题分解 结构化简报直接管道给 jq npx wigolo research how does sqlite full text search work --depth quick --json \ | jq -r .brief.highlights[0].text其中第三条命令值得拆解--depth quick指定调研深度为快速档--json让整个输出变成机器可读的 JSON随后| jq -r .brief.highlights[0].text直接提取简报的第一条核心要点。这证明了research 的输出并非一段无法解析的散文而是带brief、highlights、sources、citations等结构化字段的完整对象对应的输出类型定义见 src/types.ts 的ResearchOutput与ResearchBrief。一键跑完三个工具run.sh示例目录里的 run.sh 把上面三条命令串成了一个脚本并允许通过环境变量覆盖要调用的 wigolo 二进制./run.sh # 使用 npx wigolo WIGOLOwigolo ./run.sh # 使用全局安装的 wigolo或任何你偏好的二进制/入口脚本内部的关键逻辑默认WIGOLO${WIGOLO:-npx wigolo}因此不设置环境变量时走 npx 路径set -euo pipefail保证任何一步失败都会中断脚本并暴露非零退出码依次输出 search带评分、fetch干净 Markdown、research经 jq 提取的要点三段演示。在演示录制脚本 demo.tape 中还能看到同样的命令序列它额外演示了--json | jq .results[0]提取单条结果字段的用法并说明 repeat 查询走本地缓存后响应在毫秒级——这也是下文3ms数字的真实来源。输出解读三种工具返回什么search带证据评分的排序结果Search: css grid layout guide (5 results, 3ms, engines: mdn, duckduckgo) [1] Basic concepts of grid layout - developer.mozilla.org (score: 1.00) CSS grid layout introduces a two-dimensional grid system to CSS. Grids can be used to lay out major page areas or small user interface elements. ... [2] Relationship of grid layout to other layout methods - developer.mozilla.org (score: 0.91) CSS grid layout is designed to work alongside other parts of CSS, as part of a complete system for doing the layout. ...首行汇总了查询词、结果数、耗时与命中的引擎列表每条结果带[n]序号、标题、域名与scorerelevance_score取值 01。这个格式由 src/repl/formatters.ts 的formatSearchResults生成。值得注意的细节是那个3ms是真实的重复查询直接命中本地知识缓存local knowledge cache无需再次访问搜索引擎首次运行才会真正请求引擎约数秒而学到的内容会全部落盘供后续复用。这与项目local-first、无 API key、无云依赖的定位一致。在--json形态下SearchOutput见 src/types.ts会携带比终端文本更丰富的信息包括engines_used、engine_telemetry每个引擎的延迟与结果数、evidence证据片段、citations等字段。fetch任意 URL 变成干净 MarkdownFetch: https://developer.mozilla.org/en-US/docs/Web/API/structuredClone # Window: structuredClone() method Baseline Widely available [cached: true, 9570 chars]fetch 会把页面正文抽取为干净 Markdown 并在开头预览前几行末尾标注[cached: true/false, N chars]是否命中缓存 字符数。README 特别强调即使是 JS 渲染的页面也能抓取——浏览器引擎只在需要时介入在 src/fetch/browser-pool.ts 与 src/fetch/router.ts 中SmartRouter 会根据页面情况决定走 HTTP 直连层还是浏览器层参见 src/cli/tool-run.ts。research结构化简报与子查询research 会执行多步问题分解返回一份结构化 brief。--json让整个输出可管道化$ npx wigolo research how does sqlite full text search work --depth quick --json \ | jq -r .brief.highlights[0].text At its core, full-text search in SQLite is designed to split text into terms or phrases and index these for fast search retrieval. When a full-text search is queried, it doesnt scan rows linearly. Instead, it uses indexed tokens to match search criteria, making full-text search much quicker than traditional LIKE queries on large datasets.ResearchOutput中除了report长文还包含sources带relevance_score与fetched标记的来源列表、citations引用列表、sub_queries分解出的子问题与brief结构化简报topics、highlights、key_findings、sections等方便下游程序做进一步处理。--json与 MCP 完全同构的机器可读输出one-shot CLI 最实用的特性之一就是--json。它输出的是工具完整输出对象的 JSON 序列化——形状与 MCP 客户端拿到的完全一致包括results、evidence、citations、engine_telemetry等字段。这意味着# 提取第一条结果的标题、URL 与评分 npx wigolo search node worker threads --limit 3 --json | jq .results[0] | {title, url, relevance_score} # 提取调研简报的所有关键发现 npx wigolo research ... --json | jq .brief.key_findings # 查看 fetch 结果的完整元数据 npx wigolo fetch https://example.com --json | jq .metadata在实现层面--json模式下 stdout 上只有JSON零日志泄漏因此对整个 stdout 执行JSON.parse永远可以成功——这是 src/cli/tool-run.ts 中emit函数的有意设计。统一契约结果上 stdout、日志走 stderr、失败退 1README 用四条规则总结了 one-shot CLI 的全部行为契约这也是编写脚本时最重要的依据契约说明结果 → stdout工具输出文本或--json只写 stdout日志 → stderr所有日志通过 logger 走 stderr管道保持干净--json完整输出与 MCP 客户端拿到的形状一致results、evidence、citations、engine_telemetry……失败 → 退出码 1失败时返回 1--json下 stdout 上输出可解析的错误包络error envelope--help全量参数每个工具都支持wigolo tool --help打印完整 flags 集在源码中这些契约在 src/cli/tool-run.ts 的runTool中有明确实现rawArgs.includes(--help) || rawArgs.includes(-h)时打印TOOL_HELP[command]并返回 0失败判定为typeof result.error string result.error.length 0返回码failed ? 1 : 0--json 失败时把携带.error字段的整个结果对象序列化到 stdout本身就是可解析的错误包络非--json 异常时错误写入 stderr 的Error: ...finally中执行browserPool.shutdown()与closeDatabase()确保一次命令不留残留进程。--help从 JSON Schema 实时生成的参数表npx wigolo search --help输出的是从工具 JSON Schema 实时生成的完整参数列表而非手写死文本。机制见 src/cli/help.ts 的buildToolHelp与 src/cli/flag-bridge.ts 的toolFlagSpecs遍历 src/server/tool-schemas.ts 中每个工具的 schema properties自动推导--flag名称、取值类型boolean / number / enum / array-string / object 等与描述再叠加精选的别名行如 search 的--limit、--domains、--from/--to、--no-contentresearch 的--max-sources。这意味着schema 是唯一事实来源工具能力变化时帮助文本自动同步。常用参数速查search参数说明query查询词位置参数--max-resultsN/--limitN最大结果数--domainsa,b仅保留这些域名--exclude-domainsa,b排除这些域名--fromYYYY-MM-DD/--toYYYY-MM-DD发布日期的起止过滤--no-content跳过全文内容增强更快、省 token--json输出机器可读 JSONfetch参数说明url目标 URL位置参数--max-charsN截断返回的 Markdown 长度--section...只返回匹配章节--screenshot同时截图--force-refresh跳过缓存强制重新抓取--json输出完整FetchOutput含metadata、links、cached、content_hash等research参数说明question调研问题位置参数--depthquick\|standard\|comprehensive调研深度默认standard--max-sourcesN来源数量上限--domainsa,b限定调研来源域名--exclude-domainsa,b排除指定域名--json输出结构化简报除此之外crawl、extract、cache、find-similar、agent、diff、watch也全部支持 one-shot 调用每个工具都有自己的子命令/别名体系例如cache stats、cache search query、cache clear [--queryQ] [--url-patternP] [--sinceT]diff url或diff --oldtext --newtext两种模式watch add/list/rm/run/pause/resume详细用法都可以用wigolo tool --help查看。底层实现一次 one-shot 调用的完整生命周期把上面的命令行为与源码对应起来一次npx wigolo research ... --depth quick --json的调用链是命令解析parseCommand识别research为工具命令src/cli/index.ts其余参数交给工具执行器参数桥接--depth、--json等被flag-bridge解析--depth是 research schema 的原生 enum 属性quick|standard|comprehensive校验失败会给出明确的错误信息src/repl/commands/research.ts未知 flag 还会通过 Levenshtein 距离给出--did you mean建议src/cli/flag-bridge.ts环境初始化runTool创建数据目录、初始化 SQLite 数据库wigolo.db、构建SmartRouterHTTP 浏览器池与BackendStatussrc/cli/tool-run.ts引擎装配research/agent/find-similar 等管道直接用keyless 直连引擎DuckDuckGoEngineBingEngine见 src/cli/tool-run.ts 的注释——与 MCP server 使用同一批直连适配器且刻意不启动 searxng sidecar 进程保证 one-shot 场景零额外进程执行与输出dispatch分发到对应 executor如executeResearch拿到结果后emit决定走人类可读文本还是--json格式化逻辑全部集中在 src/repl/formatters.ts--json走formatJsonJSON.stringify(data, null, 2)美化输出收尾关闭浏览器池与数据库连接按失败与否返回 0 或 1。这套实现把一次命令、一次进程、干净退出做成了结构性保证也让 one-shot 模式天然适合 cron 任务、CI 冒烟测试和 Shell 管道。下一步从单条命令到流水线one-shot CLI 是整个 CLI 生态的地基README 提供了四个延伸方向均已转换为仓库根路径Shell NDJSON 流水线在一个进程内串起多条命令输出按 NDJSON 流式交付REST 调用示例同一套工具通过 HTTP daemon 暴露时的 curl 用法TypeScript SDK 示例用类型化客户端在 Node 侧驱动 researchPython SDK 示例用 Python 客户端编排 Agent 数据采集。如果你需要把搜索、抓取、调研能力嵌入到自有脚本、自动化任务或 CI 中one-shot CLI 的 stdout/stderr 分离与退出码契约可以让你用最小的胶水代码完成集成。【免费下载链接】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），仅供参考