@dowanw0w/alibaba-cleversee

Unofficial Pi extension and CLI for Alibaba Cloud CleverSee web search and page fetch

Packages

Package details

extension

Install @dowanw0w/alibaba-cleversee from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:@dowanw0w/alibaba-cleversee
Package
@dowanw0w/alibaba-cleversee
Version
1.0.0
Published
Oct 31, 2026
Downloads
240/mo · 240/wk
Author
dowanw0w
License
MIT
Types
extension
Size
58.6 KB
Dependencies
0 dependencies · 0 peers
Pi manifest JSON
{
  "extensions": [
    "./extension/index.mjs"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

alibaba-cleversee

把 阿里云 CleverSee（开析） 封装成 Pi 的搜索与网页读取能力，同时提供 CLI。

Unofficial project. This package is not affiliated with, endorsed by, or sponsored by Alibaba Cloud. "CleverSee" / "开析" is a product of Alibaba Cloud; this project is an independent client for its public HTTP API.

  • Search：POST /search/unified，默认 CNLiteBasic 引擎。
  • Fetch：POST /readpage/basic，可选降级到浏览器渲染的 POST /readpage/scrape。
  • 两种形态：Pi 扩展（cleversee_search / cleversee_fetch 工具 + /alibaba-cleversee 命令）与 CLI。
  • 零运行时依赖，只用 Node 内置模块，无构建步骤。

安装

# Pi 扩展
pi install npm:@dowanw0w/alibaba-cleversee@1.0.0

# 或只装 CLI
npm install -g @dowanw0w/alibaba-cleversee

Pi 会按包内 pi.extensions 自动注册工具与命令。版本被 pin 住，升级需重新 pi install 到新版本或运行 pi update。

准备 API Key

本项目不内置任何 key、不提供共享额度。使用前请在阿里云 CleverSee / 开析控制台自行开通并签发 API Key，费用按调用量计（见下方成本表）。

# Linux / macOS（fish 示例）
set -gx CLEVERSEE_API_KEY '<your-api-key>'

# bash / zsh
export CLEVERSEE_API_KEY='<your-api-key>'

# Windows PowerShell
$env:CLEVERSEE_API_KEY = '<your-api-key>'

Key 只从环境变量读取，不写文件、不进日志、不进仓库。请勿把 key 提交到任何地方；如需长期保存，建议放在 shell 的私有配置文件（权限 600）或系统的密钥管理工具里。

Pi 工具

cleversee_search

参数 类型 默认 说明
query string 必填 查询词；不支持 site: / after: / lang: 等操作符，请用下面两个结构化参数
count integer 1–50 5 返回条数（受引擎上限约束）
recency day|week|month|year — 时间范围
include_domains string[] — 只保留这些域名（CNLiteBasic / GlobalAdvanced 支持）
exclude_domains string[] — 排除这些域名（同上）
need_content boolean false 请求正文（CleverSee mainText 上限约 3000 字）

cleversee_fetch

参数 类型 默认 说明
url string 必填 仅 http/https；默认拒绝回环/私网地址与 URL 内凭据
scrape boolean false 允许 readpage/basic 失败后降级到浏览器渲染的 readpage/scrape（更慢、更贵）
refresh boolean false 跳过进程内缓存

成功结果会进入进程内 LRU 缓存（默认 10 分钟 / 100 条），避免同一 URL 重复计费。

命令

/alibaba-cleversee status        # provider 配置、熔断状态、计数器、缓存
/alibaba-cleversee doctor        # 发一次真实检索，报告实际服务 provider 与耗时
/alibaba-cleversee clear-cache   # 清空 fetch 缓存

CLI

alibaba-cleversee status
alibaba-cleversee search "Kubernetes 1.31 release notes" -n 3
alibaba-cleversee search "vLLM" --include docs.vllm.ai --recency month --json
alibaba-cleversee fetch https://example.com/
alibaba-cleversee doctor

引擎与成本

价格单位：元/千次（以官方最新价格为准，本表仅用于估算与展示）。

引擎 说明 单次上限 域名过滤 搜索单价
CNLiteBasic（默认） 国内极速版 50 ✅ 8
CNAuto 国内智能版 10 ❌ 18
LiteAdvanced 极速版（旧规格） 50 ✅ 12
Generic 通用标准版 10 ❌ 42
GenericAdvanced 通用增强版 80 ❌ 44.8
GlobalAdvanced 国际版 20 ✅ 56
Deep 深度版 10 ❌ 按官方

ReadPage：basic 2 元/千次，scrape 10 元/千次；增强摘要 summary 另加 2.8 元/千次。搜索结果里会带 estimatedCostCny，只统计成功调用。

默认引擎面向国内信源。需要海外结果时请显式切换：

CLEVERSEE_ENGINE=GlobalAdvanced alibaba-cleversee search "..."

路由、限速与熔断

单上游，没有 provider 兜底；同一请求内只有 fetch 的 basic → scrape 一档降级。

上游结果 动作
搜索成功且非空 直接返回
搜索成功但 0 条 报 empty 错误（不会静默返回空列表）
fetch readpage/basic 失败且开了 scrape 继续尝试 readpage/scrape
401/403（凭据未激活等） 直接报 auth，不重试
402 余额不足 / 429 限流 / 5xx / 超时 / 网络错误 报对应 kind；计入熔断
目标网页 404/403/反爬（ReadPage.SecurityRestrict 等） 报 target；不计入熔断
本地限速排队超时 报 local-throttle；不计入熔断
  • 熔断：同一 provider 同一能力（fetch 按 basic/scrape 分开）连续失败 3 次 → open 120s，之后 half-open 放一个探针。只统计上游自身故障；target、local-throttle、invalid 不计入。
  • 限速：搜索 10 QPS、ReadPage 5 QPS；排队超过 1.5s 直接失败（local-throttle）。

配置项

变量 默认 说明
CLEVERSEE_API_KEY — 阿里云 CleverSee API Key（必填）
CLEVERSEE_ENGINE CNLiteBasic 引擎档位
CLEVERSEE_ALLOW_PRIVATE 0 置 1 允许抓取私网/回环地址
CLEVERSEE_CACHE_TTL 600 fetch 缓存秒数，0 关闭
CLEVERSEE_CACHE_MAX 100 缓存条数上限
CLEVERSEE_QPS 10 搜索限速
CLEVERSEE_READPAGE_QPS 5 ReadPage 限速
CLEVERSEE_SEARCH_TIMEOUT_MS 15000 搜索超时
CLEVERSEE_READPAGE_TIMEOUT_MS 15000 ReadPage 超时
CLEVERSEE_SCRAPE_TIMEOUT_MS 30000 Scrape 超时
CLEVERSEE_SUMMARY 0 置 1 开启 CleverSee 增强摘要（+2.8 元/千次）
CLEVERSEE_SCRAPE 0 置 1 让 fetch 默认带 Scrape 兜底
CLEVERSEE_READPAGE_MAX_AGE 0 ReadPage 服务端缓存秒数，0 表示不使用
CLEVERSEE_BREAKER_THRESHOLD 3 熔断失败阈值
CLEVERSEE_BREAKER_COOLDOWN_MS 120000 熔断冷却时间
CLEVERSEE_LIMITER_MAX_WAIT_MS 1500 限速最大排队时间
CLEVERSEE_DEBUG 0 置 1 输出每次调用的结构化日志（不含 query/URL/Key）
CLEVERSEE_BASE_URL https://cloud-iqs.aliyuncs.com 仅调试用

安全

  • 凭据只从环境变量读取；任何输出、日志、错误信息都不包含 Key。
  • 日志只记录 provider / 能力 / 结果 / 耗时 / 字符数，不记录 query 原文、URL 正文。
  • Fetch 默认拒绝 localhost、回环、私网、链路本地与 metadata.google.internal；拒绝 URL 内嵌凭据；只允许 http/https。
  • 不写文件、不起监听端口、不落盘缓存。

已知限制

  • 没有 query 操作符：site: / after: / -site: / lang: 不适用，请用 include_domains / exclude_domains / recency（CNAuto、Generic 等引擎不支持站点过滤，会返回 warning 并忽略）。
  • 单上游无兜底：CleverSee 不可用时直接失败，没有第二家可切。
  • 返回条数受引擎上限约束（见上表）。
  • ReadPageScrape 平均耗时可达 30s，默认关闭。
  • 不提供代理、cookie、PDF/YouTube 专项抓取。
  • 不做模型内置搜索（enable_search / Responses web_search），只暴露独立 API 能力。
  • 账号余额、配额、数据合规与计费由使用者与阿里云之间解决，与本项目无关。

开发

git clone https://github.com/Dowanw0w/alibaba-cleversee.git
cd alibaba-cleversee
node --test test/*.test.mjs                                  # 离线测试，无网络
CLEVERSEE_LIVE=1 node --test test/live.test.mjs              # 真实 API 联调（需 key）

离线用例覆盖参数/响应映射、错误分类、空结果、429/5xx/超时、熔断半开、ReadPage basic→scrape 链、缓存、URL 校验、引擎档位透传、扩展注册与格式化。

License

MIT © 2026 Dowanw0w