安装本身只有三条命令，但装之前最好先确认四件事，能省掉后面大半排错时间。

1. 一个支持 Agent Skill 的环境——Claude Code、OpenCode、Cursor、Windsurf、Codex 等都可以。先查清你这个平台的 skill 目录路径，后面「移进去并改名」要用。
2. 一种可用运行时——推荐 Python ≥ 3.6（需 requests 库），或 Node.js ≥ 12（无外部依赖）。注意 macOS 上通常只有 python3 而不是 python。
3. 一个真实可收信的邮箱（可选但推荐）——用来注册 API Key，换取比匿名更高的速率限制与配额。
4. 命令行能跑 curl 与 unzip——Windows 用户可用 PowerShell 或 Git Bash，下载解压逻辑一致。

AnySearch 的安装路径不是 pip，而是「下载 release zip → 解压 → 移入 agent 的 skill 目录并改名为 anysearch」。三步里最容易翻车的是第三步，先记住结论：解压出来的目录名带 ref，移进去时必须改名成 anysearch。

# 下载固定 tag 的 release（推荐），把 v3.1.1 换成最新 tag
curl -L -o anysearch-skill.zip https://github.com/anysearch-ai/anysearch-skill/archive/refs/tags/v3.1.1.zip

# 或者用 wget
# 想跟进未发布改动，把 refs/tags/v3.1.1 换成 refs/heads/main

# 解压——会生成一个名为 anysearch-skill-3.1.1 的目录
unzip anysearch-skill.zip

# Claude Code
mv anysearch-skill-3.1.1 ~/.claude/skills/anysearch

# OpenCode
mv anysearch-skill-3.1.1 ~/.config/opencode/skills/anysearch

# Cursor / Windsurf（项目级）
mv anysearch-skill-3.1.1 <project>/.skills/anysearch

# 通用：任意 agent 的 skill 目录
mv anysearch-skill-3.1.1 <your_agent_skill_dir>/anysearch

# 多工具共享目录
mv anysearch-skill-3.1.1 ~/.agents/skills/anysearch

如果你的 agent 平台自带 skill 市场／商店，可以更省事：在商店里直接搜 anysearch 安装，跳过下载解压。没有市场时才走上面的手动流程。

* 只要目录名保留了 -<ref> 后缀没有改，skill 就大概率加载不上——这是本文最强调的一个坑。

装好之后，这个 skill 对 agent 暴露四类实时搜索能力。它们共用一个入口，只是调用的子命令不同。

关于 extract，README 划清了边界：支持 HTML/XHTML、纯文本、JSON、Markdown；不支持 PDF、DOC/DOCX、图片、音视频、压缩包、流媒体、播放列表等二进制格式。它的输出已经是 Markdown，不要再传 --format 之类的参数，只接受 URL 位置参数或 --url／-u。

API Key 是可选的，但官方强烈推荐：没有 key 时全部搜索功能仍可通过匿名访问使用，只是速率限制与配额更低。注册只需一个真实、可收信的邮箱——邮箱会直接成为账户用户名，agent 会一次性自动完成整个流程，无需验证码。

让 agent 帮你注册，本质上是调用一次注册接口：

curl -s -X POST "https://api.anysearch.com/v1/auth/email/register" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

成功（code: 0）会返回账户信息和一次性明文 API Key（形如 as_sk_...）。拿到后，agent 必须把它写进 .env，并把用户名（即邮箱）和登录地址告诉你。你也可以直接到 https://anysearch.com/console/api-keys 注册并创建免费 key。

cp .env.example .env
# 编辑 .env，设置：ANYSEARCH_API_KEY=<your_api_key_here>

# 或者直接用环境变量
export ANYSEARCH_API_KEY=<your_api_key_here>   # Linux/macOS
set ANYSEARCH_API_KEY=<your_api_key_here>       # Windows CMD
$env:ANYSEARCH_API_KEY="<your_api_key_here>"    # Windows PowerShell

key 的生效优先级是：--api_key 命令行参数 > .env 文件 > 环境变量 > 匿名访问。要注意，注册与匿名使用是互斥的，选定一种就别在流程中途切换。

这个 skill 是「给 AI Agent 用」的，理解它怎么被加载，比记命令更重要。目录里的 SKILL.md 是写给 agent 的技能定义，而实际用哪个命令行工具，则由安装时生成的 runtime.conf 决定：agent 加载 skill 时会先读 runtime.conf 来确定当前 CLI，文件缺失或损坏时才回退到 SKILL.md 里的平台探测流程。

~/.agents/skills/ 是一个实用的共享安装位置：当 Codex、Cursor、OpenClaw 的个人 agent skill 等多个工具从同一目录读取 skill 时，放这里就能一次装、多处用。项目 topics 里也列出了 hermes、openclaw、qclaw 等 agent 生态。运行时选择的推荐优先级是 Python > Node.js > Shell。

runtime.conf 落定后，agent 日常调用应直接用里面存好的 Command，不必每次搜索前都跑一遍 doc：

python3 <skill_dir>/scripts/anysearch_cli.py search "query" --max_results 5
python3 <skill_dir>/scripts/anysearch_cli.py batch_search --queries '[{"query":"q1","max_results":5},{"query":"q2","max_results":5}]'
python3 <skill_dir>/scripts/anysearch_cli.py extract "https://example.com/page"

某个子命令的参数不清楚或报错时，针对那个子命令跑 <command> <subcommand> --help，而不是每次都跑完整的 doc。

README 在安装之后专门设了 Post-Install Verification，也就是「entry test」。它的目的不是搜一次，而是探测出你这台机器上最干净的运行时，并把它固化到 runtime.conf。三步走：

python --version     # 需要 >= 3.6，依赖 requests 库
python3 --version    # 同上；macOS 常见
node --version       # 需要 >= 12，无外部依赖
# 兜底：Windows PowerShell 5.1+ / Linux/macOS bash 3.2+（还需 jq 与 curl）

python  <skill_dir>/scripts/anysearch_cli.py doc
python3 <skill_dir>/scripts/anysearch_cli.py doc
node    <skill_dir>/scripts/anysearch_cli.js doc
powershell -ExecutionPolicy Bypass -File <skill_dir>/scripts/anysearch_cli.ps1 doc
bash <skill_dir>/scripts/anysearch_cli.sh doc

echo "Runtime: Python" > <skill_dir>/runtime.conf
echo "Command: python3 <skill_dir>/scripts/anysearch_cli.py" >> <skill_dir>/runtime.conf

python <skill_dir>/scripts/anysearch_cli.py search "hello world" --max_results 1
# 若系统没有 python，用 python3；返回正常 JSON 即表示连接可用