@cleversee/ai-sdk

阿里云 AI 原生搜索 CleverSee 的配套 SDK 工具包，为 Vercel AI SDK 提供开箱即用的联网搜索 tool，让模型在 generateText / streamText 中一行代码接入实时联网搜索。

• 零配置鉴权：默认走阿里云默认凭据链，也可传入自定义凭据；
• 一行接入：工厂函数直接返回标准 AI SDK tool，可搭配任意 AI SDK 支持的语言模型；
• 统一契约：归一化的扁平返回结构与统一错误类型，屏蔽上游细节。

安装

npm install @cleversee/ai-sdk

peer dependencies：ai（支持 5.x / 6.x / 7.x）与 zod（^4）。

凭据配置

方式一：环境变量（.env）

默认使用阿里云默认凭据链，会自动读取标准环境变量，配置后无需传 credential：

ALIBABA_CLOUD_ACCESS_KEY_ID=xxxx
ALIBABA_CLOUD_ACCESS_KEY_SECRET=xxxx
# 可选：STS 临时凭据，提供时按 STS 凭据处理
ALIBABA_CLOUD_SECURITY_TOKEN=xxxx

.env 中的变量需加载到进程环境变量后生效（Node.js 20.6+ 可用 node --env-file=.env， 或使用框架内置加载 / dotenv）。项目根目录 .env.example 已提供模板，.env 勿提交真实密钥。

默认凭据链的更多配置方式请参考官方文档。

方式二：直传凭据配置值

无需安装/导入 @alicloud/credentials：

webSearch({
  credential: {
    accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID!,
    accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET!,
    securityToken: process.env.ALIBABA_CLOUD_SECURITY_TOKEN, // 可选；提供时按 STS 凭据处理
  },
});

直传配置值时可省略 type：按是否提供 securityToken 推断为 access_key 或 sts； 显式指定 type（如 ram_role_arn）时字段原样透传。

方式三：传入 Credential 实例

安装 @alicloud/credentials 自行构造：

import Credential from '@alicloud/credentials';
webSearch({
  credential: new Credential({ type: 'access_key', accessKeyId: '...', accessKeySecret: '...' }),
});

优先级：显式 credential > 环境变量 / 默认凭据链。

快速开始

以通义千问（DashScope OpenAI 兼容端点）为例：

import { webSearch } from '@cleversee/ai-sdk';
import { generateText, stepCountIs } from 'ai';
import { createOpenAICompatible } from '@ai-sdk/openai-compatible';

const qwen = createOpenAICompatible({
  name: 'dashscope',
  baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
  apiKey: process.env.DASHSCOPE_API_KEY!,
});

const { text } = await generateText({
  model: qwen('qwen3.7-plus'),
  prompt: '调研一下 Vercel AI SDK 的最新特性',
  tools: { webSearch: webSearch() },
  stopWhen: stepCountIs(3),
});

API

webSearch(options?)

创建联网搜索 tool，可直接放入 generateText / streamText 的 tools。

WebSearchToolOptions（开发者配置，均可选）

| 配置项 | 类型 | 说明 | | --- | --- | --- | | description | string | 自定义 tool description（展示给模型，用于决定何时调用），缺省使用内置描述 | | credential | CredentialInput | 自定义凭据（Credential 实例或普通配置值对象），覆盖默认凭据链 | | endpoint | string | 服务地址，默认 maasaisearchproxy.aliyuncs.com | | searchType | 'pro' \| 'lite' | 搜索模式，缺省 pro；lite 仅支持 query、limit、startTime/endTime | | region | 'mainland_china' \| 'global' | 搜索地域，仅 searchType=pro 时有效，缺省 mainland_china | | limit | number | 默认结果条数（1-10 整数），可被模型入参覆盖 | | includeDomain | string[] | 默认域名白名单，可被模型入参整体覆盖；仅 searchType=pro 且 region=global 时支持，最多 30 个域名 | | excludeDomain | string[] | 默认域名黑名单，可被模型入参整体覆盖；仅 searchType=pro 时支持，最多 30 个域名 | | startTime / endTime | string | 时间范围，格式 YYYY-MM-DD | | timeoutMs | number | 请求超时（毫秒） |

模型输入（tool 入参 schema）

| 入参 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | query | string | 是 | 搜索词 | | limit | number | 否 | 结果条数（1-10） | | searchType | 'pro' \| 'lite' | 否 | 搜索模式，缺省 pro；lite 仅支持 query、limit、startTime/endTime | | region | 'mainland_china' \| 'global' | 否 | 搜索地域，仅 searchType=pro 时有效，缺省 mainland_china | | startTime / endTime | string | 否 | 发布时间范围，格式 YYYY-MM-DD | | includeDomain | string[] | 否 | 域名白名单（最多 30 个）；仅 searchType=pro 且 region=global 时支持 | | excludeDomain | string[] | 否 | 域名黑名单（最多 30 个）；仅 searchType=pro 时支持 |

合并规则：模型入参 > 工厂配置 > SDK 默认值（缺省 searchType=pro、region=mainland_china）； 数组类参数模型入参存在时整体覆盖，不做并集。跨字段约束（lite 模式禁用 region/域名过滤、 mainland_china 禁用 includeDomain）在发起请求前校验，违反时抛出 CleverSeeError （code: InvalidParameter），AI SDK 会将错误回传给模型以便自我纠正。

返回结构 WebSearchResponse

interface WebSearchResponse {
  query: string;   // 回显搜索词
  total?: number;  // 命中总数
  results: Array<{
    title?: string;
    url?: string;
    snippet?: string;
    date?: string;
    source?: { name?: string; domain?: string; favicon?: string };
  }>;
}

CleverSeeError

所有失败（网络异常、鉴权失败、业务失败等）统一抛出 CleverSeeError，保留底层错误信息（原始 message、RequestId 等），便于定位：

| 属性 | 说明 | | --- | --- | | message | 错误描述（优先采用底层错误消息，不会退化为无信息的兜底文案） | | code | 错误码（统一为字符串；上游数字业务码会归一） | | statusCode | HTTP 状态码 | | requestId | RequestId（排查用） | | recommend | 诊断地址 | | cause | 底层错误对象（SDK 异常本身，或业务失败时的原始响应体） |

完整示例

demo/ 目录提供可运行的最小服务端示例（Hono + streamText + SSE 流式输出）， 展示多步 tool 循环的完整形态，运行方式见其 README。根目录 .env.example 提供本地凭据模板， 复制为 .env 后由 demo 与集成测试（npm run test:integration）共用。