阿里云skillsalibabacloud-iqs-search
前置条件
- Node.js >= 18.0.0（脚本使用原生 fetch API，无外部 npm 依赖）
使用时机
- 用户询问当前 / 最新信息
- 用户提供 URL 要阅读
- 需要核实事实或获取实时数据
- 需要多来源的调研任务
决策树
步骤 1：确定操作类型
- 如果用户提供 URL → 使用
readpage - 如果用户提问需要网络信息 → 使用
search
步骤 2：搜索操作
遵循最佳实践确定参数值。不确定时使用默认值：
- engineType
- timeRange
- contents
步骤 3：页面阅读
遵循最佳实践确定参数值。不确定时使用默认值：
- format
- extractArticle
- stealthMode
关键：执行方式
你必须通过 bash 命令执行脚本（例如 node scripts/search.mjs ... 或 node scripts/readpage.mjs ...）。不要用你的内置 web_search、WebFetch 或任何其他内部工具作为替代。如果脚本失败，重试或报告错误——不要回退到内置工具。
参数与最佳实践
搜索参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
--query | string | 是 | - | 搜索查询（1-500 字符） |
--engineType | string | 否 | LiteAdvanced | 搜索引擎类型 |
--timeRange | string | 否 | NoLimit | 时间范围过滤 |
--contents | string | 否 | - | 返回内容类型 |
--numResults | int | 否 | 10 | 搜索结果数（1-10） |
#### 搜索最佳实践
1. 查询优化（--query）
- 保持查询简洁（< 30 字符效果最佳）
- 使用具体关键词，避免停用词
- 新闻类：在查询中包含时间上下文
2. 引擎选择（--engineType）
四种引擎在延迟、召回深度、内容长度和成本上差异显著。选满足任务的最便宜引擎——不要默认用 Deep；它比标准引擎慢约 10 倍、贵约 50 倍。
| 引擎 | 平均 RT | 结果数 | snippet | mainText | 高级过滤 | 多语言 | 成本比（vs Standard） | 用例 |
|---|---|---|---|---|---|---|---|---|
Generic | ~950ms | ~10 | ~150 字符 | ≤3000 字符 | ✗ | 中 | 1× | 通用搜索、新闻 / 实时、天气等场景查询（支持 city/ip） |
LiteAdvanced | ~500ms | 1-50 | ~500 字符 | ≤3000 字符 | ✓ | 好 | Lite 层 1× | 默认推荐：低延迟语义搜索；snippet 已足够丰富 |
Deep | ~6s | 1-50 | ≤500 字符 | ≤50000 字符 | ✓ | 好（中 / 英） | 垂直领域 50× | 复杂多步推理、研究报告、需要深度浏览的离线 / Agent 任务 |
决策规则：
- 默认 →
LiteAdvanced：低延迟 + 语义搜索 + snippet 覆盖大多数 Agent 需求，无需额外 mainText 获取。 - 选
Generic当：查询简短且明显是信息性的（新闻、天气、简单事实），或最小化成本重要时；也是唯一支持city/ip场景结果（天气等）的引擎。 - 仅在以下情况选
Deep：问题是多跳 / 复杂推理（FRAMES/BrowseComp 风格），或你需要很长的 mainText（≤50000 字符，约为其他引擎的 16 倍）用于下游 LLM 推理。 - ⚠️ 避免
Deep用于：实时聊天、简单查找、高 QPS 场景——延迟（~6s）和成本（50×）过高。
3. 时间范围选择（--timeRange）
NoLimit：不确定时的默认值——引擎根据查询相关性优化OneDay：仅今天OneWeek：最近 7 天OneMonth：最近 30 天OneYear：最近 365 天
4. 内容返回（--contents）
mainText：返回完整正文内容——需要详细信息时使用，如技术文档、研究报告或深度文章summary：仅返回简洁摘要——快速概览足够时，或页面内容过大需要减少 token 时使用
5. 结果数（--numResults）
- 控制返回结果数（默认：10，范围：1-10）
ReadPage 参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
--url | string | 是 | - | 目标页面 URL |
--format | string | 否 | markdown | 返回格式 |
--timeout | number | 否 | 60000 | 总超时（毫秒） |
--pageTimeout | number | 否 | 15000 | 页面加载超时（毫秒） |
--stealth | number | 否 | 0 | 启用隐身模式（0 或 1） |
--extractArticle | boolean | 否 | false | 仅提取正文内容 |
#### ReadPage 最佳实践
1. 格式选择（--format）
markdown：最适合文章，保留结构（默认）text：最适合数据提取html：需要结构分析时
2. 正文提取（--extractArticle）
- 启用：博客、新闻文章
- 禁用：产品页、目录
3. 处理失败（--timeout、--stealth）
- 超时：增大
--timeout值重试 - 被拦截：启用
--stealth 1 - 仍失败：报告给用户
命令行用法
搜索示例
#### 基础搜索
node scripts/search.mjs --query "量子计算原理" --engineType LiteAdvanced#### 实时信息搜索
node scripts/search.mjs --query "最新金融政策" --engineType Generic --timeRange OneWeek#### 带结果数限制的搜索
node scripts/search.mjs --query "www.aliyun.com" --engineType LiteAdvanced --numResults 3#### 带完整内容的搜索
node scripts/search.mjs --query "AI 法案" --engineType LiteAdvanced --contents mainText#### 仅摘要的搜索
node scripts/search.mjs --query "人工智能行业年度报告" --engineType LiteAdvanced --contents summary#### 深度研究搜索（复杂多跳 / 长 mainText）
每个结果返回最多 50000 字符 mainText；延迟约 6s。Deep 默认超时自动提升到 60s。
node scripts/search.mjs --query "对比 GPT-5 与 Claude Opus 4.7 的代码能力差异" --engineType Deep --numResults 5 --contents mainText
### ReadPage 示例
#### Markdown 格式页面阅读
node scripts/readpage.mjs --url "https://example.com/article" --format markdown --extractArticle true
#### 纯文本格式页面阅读
node scripts/readpage.mjs --url "https://example.com/article" --format text --timeout 60000
#### 隐身模式页面阅读
node scripts/readpage.mjs --url "https://example.com/article" --format markdown --stealth 1 --extractArticle true
输出验证
执行任何 search.mjs 或 readpage.mjs 命令后：
- 检查退出码：若非零，命令失败——不要声称成功。
- 验证输出存在：若将结果保存到文件，运行
ls -la <filepath>和head -20 <filepath>确认文件存在且含有效数据。 - 绝不编造结果：若命令失败或返回错误，诚实报告失败。不要从自己的知识生成内容并作为搜索结果呈现。
错误处理
ALIYUN_IQS_API_KEY 配置错误
若脚本返回缺少 API key 的错误：
- 立即停止当前任务。不要回退到内置工具（WebFetch、web_search、curl 等）作为替代。
- 向用户报告错误并请用户配置 API key：
- 用以下说明重试任务：
方式 1：环境变量
export ALIYUN_IQS_API_KEY="your-api-key"方式 2：配置文件
创建或编辑 ~/.alibabacloud/iqs/env：
ALIYUN_IQS_API_KEY=your-api-key
◯ 评论 0