当 agent 需要通过 StepFun 官方 /v1/search 接口执行联网检索时使用。 触发于用户提到 StepFun 搜索、step-1-search、联网搜索、网页检索， 或要求把 StepFun Search 封装成可复用脚本、CLI、Skill 的场景。 适用于需要本地脚本直接调用 StepFun Search API，而不是通用浏览器搜索的情况。
本 Skill 规范了通过 StepFun POST /v1/search 接口执行本地联网搜索的完整执行流程。
当用户有以下意图时，必须调用本 Skill：
根据当前环境选择唯一入口：
scripts/step-web-search.shscripts/step-web-search.cmdnode scripts/step-web-search.mjsscripts/step-web-search.mjs检查 skill 根目录下是否存在 config.json：
api_keyconfig.example.json 为 config.json 并填入真实 key--api-key 参数或 STEPFUN_API_KEY 环境变量传入标准命令格式：
# Unix
./scripts/step-web-search.sh "<query>" --n <number> --category <value>
# Windows
cd step-web-search-skill
.\scripts\step-web-search.cmd "<query>" --n <number> --category <value>
# Node.js 跨平台
node scripts/step-web-search.mjs "<query>" --n <number> --category <value> --format json
PowerShell 特别注意：命令分隔符用分号 ; 代替 &&。
.sh / .cmd 默认输出原始 JSON.mjs 可通过 --format markdown 或 --format table 输出可读格式| 异常现象 | 判断 | 处理动作 |
|---|---|---|
SEC_E_NO_CREDENTIALS 或 AcquireCredentialsHandle failed | Windows curl TLS 握手失败 | 立即换用 node scripts/step-web-search.mjs |
HTTP 401 | API key 无效或缺失 | 检查 config.json 中的 api_key 是否正确 |
HTTP 400 | 参数错误 | 检查 category 是否使用了未支持的值 |
| 超时无响应 | 网络或服务端问题 | 增加 --timeout-ms 重试，或检查 base_url |
| 参数 | 用途 | 默认值 |
|---|---|---|
--n | 返回结果数量 | 10（或 config.json 中的 default_n） |
--category | 搜索分类过滤 | 空字符串（通用搜索） |
--api-key | 临时覆盖 API key | 读取环境变量或 config.json |
--base-url | 临时覆盖接口域名 | https://api.stepfun.com |
--timeout-ms | 请求超时（毫秒） | 30000 |
--format | 输出格式（仅 .mjs 支持） | json，可选 markdown / table |
--dry-run | 仅打印请求参数，不发送 | 关闭 |
--insecure | 透传 -k 给 curl（仅排查证书用） | 关闭 |
category 的可用取值（已实跑验证）：programming、research、gov、business。
.mjs 入口并指定 --format markdown 或 --format table.sh / .cmd 的默认 JSON 输出config.json 已加入 .gitignore，禁止将其提交到版本控制config.example.json