alibabacloud-iqs-search

alibabacloud-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	字符串	是	-	搜索查询（1-500 个字符）
--engineType	字符串	否	LiteAdvanced	搜索引擎类型
--timeRange	字符串	否	NoLimit	时间范围筛选
--contents	字符串	否	-	返回内容的类型
--numResults	整数	否	10	搜索结果数量（1-10）

搜索最佳实践

1. 查询优化（--query）

• 查询应简洁（为获得最佳结果，少于 30 个字符）
• 使用具体关键词，避免使用停用词
• 搜索新闻时：在查询中加入时间信息

2. 引擎选择（--engineType）

四种引擎在延迟、召回深度、内容长度和成本方面差异显著。选择能满足任务需求的最便宜引擎——不要默认使用 Deep；它比标准引擎慢约 10 倍，成本高 50 倍。

引擎	平均响应时间	结果数量	摘要	正文	高级筛选	多语言支持	成本比（相对于 Standard）	适用场景
Generic	~950ms	~10	~150 字符	≤3000 字符	✗	中等	1×	通用搜索、新闻/实时信息、天气等场景查询（支持 city/ip）
LiteAdvanced	~500ms	1-50	~500 字符	≤3000 字符	✓	良好	Lite 层级 1×	默认推荐：低延迟语义搜索；摘要已足够丰富
Deep	~6s	1-50	≤500 字符	≤50000 字符	✓	良好（CN/EN）	垂直领域 50×	复杂多步推理、研究报告、需要深度浏览的离线/Agent 任务

选择规则：

• 默认选择 → LiteAdvanced：低延迟 + 语义搜索 + 摘要已能满足大多数 Agent 的需求，无需额外获取正文。
• 满足以下情况时选择 Generic：查询简短且以获取信息为主（新闻、天气、简单事实），或需要尽量降低成本；它也是唯一支持在场景结果（天气等）中使用 city / ip 的引擎。
• 仅在以下情况选择 Deep：问题涉及多跳/复杂推理（FRAMES/BrowseComp 风格），或下游大模型推理需要很长的正文（≤50000 个字符，比其他引擎长约 16 倍）。
  • ⚠️ 以下情况避免使用 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）

# Returns up to 50000-char mainText per result; latency ~6s. Default timeout auto-bumps to 60s for Deep.
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 命令后：

1. 检查退出代码：如果非零，则命令失败——不要声称成功。
2. 验证输出是否存在：如果将结果保存到文件，请运行 ls -la <filepath> 和 head -20 <filepath>，确认文件存在且包含有效数据。
3. 绝不编造结果：如果命令失败或返回错误，请如实报告失败。不要根据自己的知识生成内容并将其作为搜索结果呈现。

错误处理

ALIYUN_IQS_API_KEY 配置错误

如果脚本返回缺少 API 密钥的错误：

1. 立即停止当前任务。不要改用内置工具（WebFetch、web_search、curl 等）作为替代方案。

2. 向用户报告错误，并要求用户配置 API 密钥：

3. 按照以下说明重试任务： 方法 1：环境变量

export ALIYUN_IQS_API_KEY="your-api-key"

方法 2：配置文件 创建或编辑 ~/.alibabacloud/iqs/env：

ALIYUN_IQS_API_KEY=your-api-key