http-fetch 是一个子技能(sub-skill),定位为单次 HTTP 请求的直接 shell 包装器。它的主要用途是替代那些唯一工作就是对一个 URL 执行 GET/POST 的 sub-agent 步骤,从而避免 LLM 往返、工具面和迭代循环,速度可提升一个数量级。
主要能力:
- 通过 HTTP/HTTPS 获取 URL 并返回响应正文文本。
- 支持 GET / POST / PUT / DELETE 方法(大小写不敏感)。
- 可携带请求正文(通过 stdin 管道传入,用于 POST/PUT;为空表示无正文)。
- 可设置请求超时(默认 30 秒)。
- 可限制响应正文大小(默认 2000000 字节),超出部分会被截断并追加省略后缀。
使用方式(输入参数,通过 with: 传入):
- url:必填,绝对 http(s) URL。
- method:可选,默认 GET,可选 GET / POST / PUT / DELETE(大小写不敏感)。
- body:可选,默认空字符串,请求正文,通过 stdin 管道传入(用于 POST/PUT);为空表示无正文。
- timeout:可选,默认 30,请求超时秒数。
- max_bytes:可选,默认 2000000,响应正文上限;更大的负载会被截断并追加省略后缀。
输出行为:
- 成功:响应正文输出到 stdout(UTF-8 解码,若超过 max_bytes 则截断;有损解码会替换无效字节)。
- 非 2xx 响应:退出码 1,stderr 输出 HTTP <code>: <reason> <body[:200]>;stdout 仍携带正文,供需要检查的调用方使用。
- 网络 / DNS / 超时失败:退出码 2,stderr 输出原因。
适用场景:
- 仅需对单个 URL 执行一次 GET/POST 等请求并获取响应正文的简单任务。
不适用场景(When NOT to use):
- 爬取多个页面 → 使用 scrapling(通过 sub-agent)。
- JS 渲染页面 → 使用 sub-agent + 浏览器工具。
- OAuth 流程 / 多步认证 → 使用 sub-agent。
- 流式响应 → 不支持(本技能会缓冲后返回)。
回退方案(Fallback): 如果此技能不可用,调用方应启动 sub-agent 执行 curl/requests 任务——结果相同,但延迟约为 10 倍,且工具循环具有非确定性。