企业官网建设流程全解析

wigolo的--json契约设计：机器可读输出如何直连自动化流水线

【免费下载链接】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 是面向 AI 编码代理的本地优先 Web 搜索、抓取与调研工具，而--json标志正是它机器可读输出契约的核心：任何命令加上--json，stdout 上就只有一份结构化 JSON，日志全部走 stderr，退出码直接充当自动化门控——不写一行胶水代码，就能把 wigolo 的 Web 智能接进 jq、cron 和 CI 流水线。

一句话说清--json契约：三个保证

整条契约浓缩起来只有三句话：

这个契约在源码注释中被明确写下，见 src/cli/tool-run.ts：

RESULT → stdout, ALL logs → stderr.--jsonemits the tool's MCP-shape JSON on stdout (exit 0), a failure exits 1, and under--jsona failure prints a JSON error object on stdout.

完整条目参考 docs/cli.md 的 “The --json contract” 一节。

如何把 wigolo 输出干净地喂给 jq

新手最容易踩的坑是：命令一边打进度一边打结果，管道里混进了杂质。--json的设计从源头杜绝了这一点——tool-run.ts 中的emit函数在--json模式下只调用一个formatJson，不输出任何别的东西：

wigolo search "zig comptime" --json 2>/dev/null | jq '.results[].url'

• 不需要grep出"从第几行开始才是真正的输出"
• 不会被日志行破坏 JSON 解析
• 结果自带results、evidence、citations、engine_telemetry等字段，和 MCP 客户端拿到的形状完全一致——为 CLI 写好的管道换到 MCP 或 REST 接口时无需重写

退出码与 JSON 错误信封：失败也能被程序接住

很多 CLI 工具失败时只在 stderr 吼一句，脚本无从结构化处理。wigolo 在--json下失败时，stdout 上输出的仍是一个可解析的 JSON 错误信封（结果对象本身携带error字段），退出码为1：

printf 'fetch https://no-such-host.invalid\n' \ | wigolo shell --json 2>/dev/null | jq -c '{url, error}' # {"url":"https://no-such-host.invalid","error":"DNS resolution failed (ENOTFOUND)"} # echo $? → 1

配合set -o pipefail，即使后面挂了| jq，非零退出码也能穿透管道，正是 CI 门控想要的行为。这个一次性 CLI 的完整演示在 examples/one-shot-cli/：

批量自动化：NDJSON shell 流水线

一次性命令简单，但每次调用都要重新冷启动进程（模型、缓存、浏览器池）。面对 50 个 URL 的抓取清单或定时 cron 任务，wigolo shell --json是正解：

• 命令从 stdin 逐行喂入，stdout一行一个 JSON 文档（NDJSON），每行独立可解析
• 人类闲聊照旧走 stderr，数据流不被污染
• 管道中任何一条命令失败，整个会话以1退出，失败信封仍是可解析 JSON

printf 'search "bun test runner"\nfetch https://bun.sh/docs/cli/test\n' \ | wigolo shell --json 2>/dev/null \ | jq -r '.results[]?.url // .url'

启动成本只付一次：同一批任务从"每条命令冷启动"的分钟级降到秒级。可直接运行的参考脚本在 examples/shell-ndjson-pipeline/pipeline.sh：

统一契约：CLI、shell、MCP、REST 同一种 JSON

--json输出的不是"CLI 私有格式"，而是工具层的全局契约形状，四个入口共享同一份结构：

JSON 序列化逻辑集中在 src/repl/formatters.ts：formatJson是一次性的美化格式，formatJsonLine是 NDJSON 用的紧凑单行格式，文档内绝不插入换行——所以逐行过滤永远是安全的。

管理命令（init、doctor、verify、status、health、config、plugin、skills、backfill、uninstall等）同样接受--json，serve因输出协议流而例外。REST 侧的完整契约见 docs/rest-api.md，OpenAPI 文件可直接从守护进程拉取。

新手三步接入流水线清单

1. ✅加--json：给任意工具命令加上，获得纯净的单文档输出
2. ✅用jq取字段：如jq '.results[].url'，失败时读.error
3. ✅门控退出码：set -o pipefail+if ! wigolo ... --json; then 重试或告警; fi

更多可运行示例见 examples/README.md，工具参数与字段语义见 docs/tools.md。掌握这条--json契约后，wigolo 的本地 Web 智能就能像curl一样，成为你任何自动化流水线里的一环。

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