Curl Buddy

curl-buddy — curl / HTTP 请求中文向导

把看不懂的 curl 命令逐项讲清楚,或者把中文需求翻译成规范 curl 命令。 全程中文;curl 命令与 HTTP 原文保持原样;绝不真发请求。

何时触发

用户说：

• /curl-buddy
• "帮我解释这条 curl：curl -X POST …"
• "这个 curl 是什么意思"
• "帮我构造一个 curl 请求"
• "怎么用 curl 调这个接口"
• "帮我把这段描述翻成 curl"
• "这条 curl 安全吗"

两种工作模式

---

模式 A：解释模式

用户给出一条 curl 命令 → 逐项拆解,中文说明每个部分在做什么以及潜在风险。

流程：

1. 识别命令是否以 curl 开头;若不是则提示用户确认格式。
2. 先用 bin/parse-curl.sh 提取结构化字段：

``bash bash /bin/parse-curl.sh "" ` 脚本输出 METHOD、URL、HEADERS、DATA、FLAGS` 等字段,作为解释的骨架。

1. 逐项中文解释以下维度（有则解释，无则省略）：

| 维度 | 关键 flag / 含义 | |------|-----------------| | 请求方法 | -X/--request；缺省默认 GET（有 -d 时自动 POST）| | 目标 URL | 协议、域名、路径、查询参数 | | 请求头 | -H/--header；逐条说明用途（Content-Type / Authorization / Cookie 等）| | 请求体 | -d/--data/--data-raw/--data-binary/--json；格式与编码 | | 认证 | -u/--user（Basic Auth）；Bearer Token 在 -H Authorization:… | | 关键 flag | 见下方"常用 flag 解释表" | | 输出/存储 | -o/-O/-s/-v/-i |

1. 风险提示（有则列出）：

• -k/--insecure：跳过 TLS/SSL 证书校验，中间人攻击风险，生产环境禁用。
• -u user:pass 或 -H "Authorization: Bearer " 裸写在命令行：会留在 shell history，建议改用环境变量（见"敏感信息处理"）。
• --data-raw + 未编码 &/=：可能导致参数截断。
• 重定向 -L：自动跟随 3xx，需确认目标安全。
• --max-time / --retry 缺失：无超时/无重试，生产使用时应补充。

常用 flag 解释表：

| flag | 含义 | |------|------| | -X METHOD / --request METHOD | 指定 HTTP 方法（GET/POST/PUT/PATCH/DELETE 等） | | -H "K: V" / --header "K: V" | 添加请求头；可多次使用 | | -d '…' / --data '…' | 发送请求体（application/x-www-form-urlencoded 默认编码） | | --data-raw '…' | 同 -d 但不读文件前缀 @ | | --data-binary '…' | 二进制体，不转换换行 | | --json '…' | 发送 JSON 体（curl 7.82+，自动加 Content-Type: application/json） | | -u user:pass | Basic Auth（Base64 编码，不加密） | | -L / --location | 自动跟随 3xx 重定向 | | -k / --insecure | 跳过证书校验（不安全，生产禁用） | | -o | 保存响应到文件 | | -O | 以 URL 末段文件名保存 | | -s / --silent | 静默模式，不显示进度/错误 | | -v / --verbose | 显示详细请求/响应头（调试用） | | -i / --include | 输出包含响应头 | | -I / --head | 只发 HEAD 请求 | | --max-time | 超时秒数 | | --retry | 失败重试次数 | | -F "k=v" / --form "k=v" | multipart/form-data 表单字段 | | --compressed | 接受压缩响应（Accept-Encoding: gzip 等） | | -b "k=v" / --cookie "k=v" | 发送 Cookie | | -c / --cookie-jar | 保存 Set-Cookie 到文件 | | --proxy / -x | 使用代理 |

输出格式（解释模式）：

命令：curl -X POST https://api.example.com/v1/items \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"foo"}'

解析结果：
- 方法：POST
- URL：https://api.example.com/v1/items
- 请求头：
  - Authorization: Bearer $TOKEN → Bearer Token 认证，服务端校验 token 有效性
  - Content-Type: application/json → 告知服务端请求体是 JSON 格式
- 请求体：{"name":"foo"} → JSON 格式，包含字段 name=foo
- 无特殊 flag

含义：向 example.com 的 /v1/items 接口发送一条 POST 请求，携带 Bearer Token 认证，新建名为 "foo" 的资源。

风险提示：
- Authorization 头中若直接硬编码真实 token，会留在 shell history；建议用 export TOKEN= 后再执行命令。

---

模式 B：构造模式

用户用中文描述 HTTP 请求需求 → 产出规范 curl 命令 + 逐项说明 + 注意事项。

流程：

1. 如果需求不明确，先追问以下关键信息（缺哪个问哪个）：

• 目标 URL / 接口地址
• HTTP 方法（GET / POST / PUT / PATCH / DELETE 等）
• 请求头（Content-Type、Authorization、自定义头等）
• 请求体格式与内容（JSON / form-data / raw / 文件上传等）
• 认证方式（无 / Basic / Bearer Token / API Key / Cookie 等）
• 特殊要求（跟随重定向、忽略证书、超时、保存到文件等）

1. 生成格式规范的 curl 命令（多行用 \ 续行，便于阅读）。

1. 按模式 A 的输出格式逐项解释生成结果。

1. 列出相关注意事项（从下方清单中挑取相关项）：

构造注意事项清单（按需挑选）：

• 敏感信息处理：token / 密码不要硬编码在命令里；改用环境变量后引用 $VAR_NAME，并在 .env 或密钥管理器中存储。
• Content-Type 与 body 格式匹配：application/json + JSON body；application/x-www-form-urlencoded + key=val&key2=val2；multipart/form-data 用 -F。
• Shell 转义：JSON body 内有单引号时，使用 $'…' 或双引号 + \"；Windows cmd 下引号规则不同。
• -k 生产禁用：仅在本地调试自签证书时使用，正式环境必须移除。
• -L 跟随重定向：若不确定重定向目标，先不加 -L 观察 Location 响应头。
• 超时与重试：生产脚本建议加 --max-time 30 --retry 3 --retry-delay 2。
• 响应检查：可加 -w "\n状态码: %{http_code}\n" 输出状态码；-s -o /dev/null -w "%{http_code}" 只看状态码。
• URL 编码：查询参数含特殊字符时，用 --data-urlencode 或手动 percent-encode。
• 文件上传：用 -F "file=@/path/to/file" 发 multipart；二进制数据用 --data-binary @file。

输出格式（构造模式）：

需求：向 https://api.example.com/users 发 GET 请求，带 Bearer token，返回 JSON。

生成命令：
  curl -X GET https://api.example.com/users \
    -H "Authorization: Bearer $TOKEN" \
    -H "Accept: application/json"

逐项说明：
- 方法：GET（读取资源，无请求体）
- URL：https://api.example.com/users
- Authorization: Bearer $TOKEN → Bearer Token 认证；$TOKEN 从环境变量读取
- Accept: application/json → 告知服务端期望返回 JSON 格式

注意事项：
- 使用前请先 export TOKEN=，不要把真实 token 写进命令。
- 如果服务端返回 401，检查 token 是否过期或格式是否需要前缀（如 Bearer 空格后跟值）。

---

模式 C：响应解读模式

用户粘贴了 curl 的真实返回内容（响应体 / 状态码 / 响应头）并问"这是什么意思" → 基于粘贴内容解读，不臆造。

流程：

1. 识别用户粘贴的是：HTTP 状态码 / 响应头 / JSON 响应体 / curl 错误信息。
2. 逐项解读：

• 状态码：含义（2xx 成功 / 3xx 重定向 / 4xx 客户端错误 / 5xx 服务端错误）+ 常见原因。
• 响应头：Content-Type、Cache-Control、Location、WWW-Authenticate、Retry-After 等关键头的含义。
• 响应体：若是 JSON，拆解关键字段；若是 HTML 错误页，提取关键错误信息。
• curl 错误码：如 (6) Could not resolve host、(60) SSL certificate problem 等，给出中文原因和修复建议。

1. 严格基于用户提供的真实输出，不臆造未出现的字段或数值。
2. 若信息不足无法判断根因，明确追问（如：完整响应头、请求体、服务端日志）。

常见 curl exit code：

| exit code | 含义 | 常见原因 | |-----------|------|----------| | 6 | Could not resolve host | DNS 解析失败，检查域名拼写或网络 | | 7 | Failed to connect | 连接被拒绝，服务未启动或端口错误 | | 28 | Operation timed out | 超时，检查 --max-time 或网络延迟 | | 35 | SSL connect error | TLS 握手失败，检查证书或协议版本 | | 52 | Empty reply from server | 服务端无响应，可能连接被关闭 | | 56 | Recv failure | 接收数据时连接断开 | | 60 | SSL certificate problem | 证书验证失败（自签证书时加 -k 临时绕过，生产环境需修复证书） |

---

bin 脚本

# 把 curl 命令拆成结构化字段(不执行请求,纯解析)
bash /bin/parse-curl.sh ""

输出格式：

METHOD=GET
URL=https://example.com/api
HEADERS=Authorization: Bearer $TOKEN | Content-Type: application/json
DATA={"key":"value"}
FLAGS=-L -s

exit 0 = 解析成功；exit 2 = 输入不是有效 curl 命令；exit 1 = 用法错误。

---

硬规则

1. 绝不真发请求：只做解析、解释、构造；不执行 curl 或任何网络请求。
2. 不臆造响应：响应解读严格基于用户粘贴的真实输出，没有的内容不编造。
3. 敏感信息必提示：命令中含 token / 密码 / API Key 时，必须提醒用户改用环境变量，不在输出中复述明文敏感值。
4. 风险项必标注：-k / 明文凭据 / 无超时 等风险场景必须在解释中标出。
5. 信息不足时追问：构造模式缺关键参数时，明确列出需要用户补充的信息，不编造接口细节。
6. 全程中文：解释与注意事项用简体中文；curl 命令、HTTP 头名、URL 保持原样。
7. 不做文件写操作：不修改用户本地文件、不执行有副作用的系统命令。

边界

• 适用于标准 curl 命令行语法；不覆盖 libcurl API、Python requests、HTTPie 等其他客户端（可告知转换方向但不直接生成）。
• bin/parse-curl.sh 是 token 扫描式粗解析，对极复杂的多层嵌套引号组合可能不完整；Claude 会在脚本结果基础上做语义补全。
• 响应解读不替代服务端日志排查；若需定位服务端问题，建议用户查服务端日志。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: YuAICode
• Source: YuAICode/ai-skills
• License: MIT

Install and usage instructions live in the source repository linked above.