为AI智能体接入Kagi搜索：提升信息获取质量与效率

1. 项目概述：为AI智能体接入更纯净的搜索与信息处理能力

如果你正在使用像Claude Code、Cursor、Pi这类AI编程助手，或者自己构建了基于shell命令调用的智能体，那你肯定遇到过这样的场景：需要让AI助手帮你查找最新的技术文档、搜索某个开源库的用法、或者快速理解一篇长文的核心内容。这时候，你可能会让AI去调用搜索引擎，但结果往往不尽如人意——充斥着SEO优化过的营销文章、广告链接，或者信息源单一，缺乏深度。

这正是joelazar/kagi-skills这个项目要解决的问题。它是一套轻量级的命令行工具集，专门设计用来为任何能够执行shell命令的AI智能体，接入Kagi搜索及其AI服务的API。Kagi是一个由用户直接付费支持的搜索引擎，没有广告、不追踪用户、不出售数据。它的商业模式决定了其搜索结果更倾向于质量和相关性，而非点击率和广告收益。对于需要获取可靠、干净信息源的AI智能体来说，这种“对齐”至关重要。

这套工具集包含了四个核心技能：kagi-search用于网页搜索并提取页面内容，kagi-fastgpt能基于实时网络搜索生成AI合成的答案，kagi-summarizer可以总结任何URL、PDF或文本块，而kagi-enrich则专注于从独立网站和另类新闻源中挖掘信息。它们就像给你的AI助手装上了更敏锐、更干净的“眼睛”和“大脑”，让它在信息获取和初步处理阶段，就能站在一个更高的起点上。

2. 为什么选择Kagi：理解背后的“干净信息”哲学

在深入工具使用之前，我们有必要先搞清楚，为什么在众多API中要特别选择Kagi。这不仅仅是技术选型，更关乎你构建的AI智能体所依赖的信息质量根基。

2.1 商业模式决定信息质量

主流的搜索引擎，其核心收入来源于广告。这意味着它们的算法优化目标，天然地包含了“最大化用户点击广告的可能性”。这种优化可能会间接导致搜索结果倾向于那些更能吸引眼球、引发互动（有时甚至是争议）的内容，而不是最权威、最相关或最简洁的答案。此外，为了维持庞大的免费服务，数据收集和用户画像构建也成了默认操作。

Kagi则采用了完全不同的路径：它是一个付费搜索引擎。用户按月或按使用量付费，这就将Kagi的利益与用户的利益直接绑定在了一起。它的目标变成了“提供让付费用户满意的搜索体验”。因此，Kagi可以大胆地屏蔽低质量网站、减少甚至消除广告干扰，并且无需为了广告收入去过度追踪用户。这种商业模式上的根本差异，直接转化成了搜索结果质量的差异。当你把搜索结果喂给AI进行推理或总结时，输入信息的“信噪比”越高，最终输出的质量自然也更可控。

2.2 为AI优化：非商业索引与权威源

Kagi不仅仅是一个干净的谷歌替代品。它还为AI应用场景做了专门优化。根据Kagi官方博客的研究，大型语言模型在使用Kagi搜索作为信息源时，其输出质量相比使用传统广告驱动引擎，有显著提升（据称可达80%）。这背后的原因在于Kagi维护着自己的非商业爬虫索引：

• Teclis索引：专注于收录来自小型、独立网站的高质量内容。这些网站在商业搜索引擎的算法中往往因为流量小、SEO权重低而被埋没，但它们可能是某个细分领域真正的专家。Teclis确保了你的AI智能体能够触及到这些“深巷好酒”。
• TinyGem索引：覆盖了另类和独立新闻来源。这为获取多元化的观点、避免信息茧房提供了可能，对于需要分析时事或社会趋势的智能体尤其有用。

这两个索引是Kagi提供给付费用户的独特价值，也是kagi-enrich工具的核心数据来源。它们共同构成了一个更丰富、更去中心化的信息网络。

2.3 简单透明的成本结构

对于开发者而言，API的计费方式是否清晰、可预测同样重要。Kagi API采用简单的按次或按Token计费，没有复杂的套餐层级、月度配额或者“免费额度用完后天价收费”的陷阱。例如，一次搜索查询固定花费$0.025，一次FastGPT查询$0.015，总结服务按每千Token $0.030计费。这种模式让你能够精确地计算和控制智能体运行的成本，特别适合项目开发和中小规模部署阶段。

3. 工具集深度解析：四个技能如何各司其职

kagi-skills项目将Kagi的核心API封装成了四个独立的命令行工具，每个工具都专注于一个特定的信息处理任务。理解它们各自的能力边界和适用场景，是高效利用这套工具的关键。

3.1 kagi-search：精准的网页抓取器

这是最基础也是最常用的工具。它的工作流程分为两步：首先，它向Kagi搜索API发送查询，获取一组相关的搜索结果（包含标题、URL和摘要）；其次，它可以选择性地提取指定结果页面的完整文本内容。

核心参数与使用场景：

• -q, --query：指定搜索关键词。这是必填参数。
• -l, --limit：控制返回的搜索结果数量，默认是10条。对于AI智能体，有时5条高质量结果比10条普通结果更有用。
• -e, --extract：这是一个关键标志。当启用时，工具不仅返回搜索结果列表，还会自动去抓取排名第一（或通过--index指定）的搜索结果页面的完整正文内容，并返回。这对于需要深度阅读单一页面的任务非常有用。
• --index：配合--extract使用，指定要提取内容的搜索结果序号（从0开始）。
• --json：以JSON格式输出结果，这是与AI智能体集成时的推荐格式，便于程序化解析。

实操示例与输出解读：假设我们想让AI了解“Rust语言2024年的异步编程有哪些新进展”。在Claude Code中，我们可以设计一个技能调用：

kagi-search --query "Rust async programming 2024 release edition" --limit 5 --json

工具会返回一个JSON数组，每个元素包含title、url、snippet字段。AI智能体可以解析这个JSON，快速浏览5个最相关链接的摘要，判断是否需要进一步深入。

如果确定第一个结果（比如是Rust官方博客）最有价值，可以再次调用：

kagi-search --query "Rust async programming 2024" --extract --index 0

这次返回的将是该页面的完整文本内容（经过清理，去除了导航栏、广告等噪音），AI可以直接基于这段干净的文本进行总结、分析或问答。

注意：--extract功能会产生额外的数据处理，虽然不额外计费，但可能会增加响应时间，并且对于某些结构复杂或反爬的页面，提取效果可能不完美。对于需要最高速度的交互，可以仅使用搜索功能。

3.2 kagi-fastgpt：即时的问答专家

这个工具可以理解为“联网版的GPT”。它内部调用了Kagi的FastGPT API。当你提出一个问题时，它会：

1. 在后台使用Kagi搜索进行实时查询。
2. 获取并分析相关的网页内容。
3. 利用AI模型综合这些信息，生成一个直接、简洁的答案，并附上引用来源。

核心参数与使用场景：

• -q, --query：你的问题。例如“Explain the difference between React Server Components and Client Components with examples”。
• -c, --context：可以提供一段额外的上下文文本，帮助AI更好地理解问题的背景，生成更贴切的答案。
• --json：同样，以JSON格式输出答案和引用。

与普通搜索的区别：kagi-search给你的是原材料（链接和摘要），需要AI自己阅读和理解。而kagi-fastgpt给你的是加工好的成品（一个综合性的答案）。这对于需要快速获得一个可靠、有据可查的概述性答案的场景非常高效。例如，智能体在编写代码时需要快速理解一个新概念，或者用户在聊天中问了一个事实性问题。

实操心得：FastGPT的答案质量高度依赖于搜索查询的表述。尽量使用完整、清晰的问句，而不是零散的关键词。例如，“What are the best practices for error handling in Go?” 就比 “Go error handling best practices” 更能引导AI生成结构良好的回答。另外，答案中引用的来源（references）是黄金信息，智能体可以将其作为跳转链接，供用户进一步查阅。

3.3 kagi-summarizer：高效的内容消化器

这是我个人使用频率极高的工具。它能够对任何公开可访问的URL、PDF文件链接，或者直接输入的一段原始文本进行总结。总结的模型针对信息密度和可读性进行了优化，可以指定总结的长度（简短、中等、详细）。

核心参数与使用场景：

• 输入源三选一：
  • -u, --url：要总结的网页地址。
  • -f, --file：本地PDF文件的路径（工具会处理上传）。
  • -t, --text：直接输入要总结的文本字符串。
• -l, --length：控制总结的详细程度，可选short、medium（默认）、long。
• -e, --engine：选择总结引擎，例如cecil（通用型）或agnes（更适用于学术/技术文档）。不同引擎可能产生不同风格的总结。

典型工作流：

1. AI智能体通过kagi-search找到一篇长文。
2. 判断文章可能包含所需信息但篇幅太长，于是调用kagi-summarizer --url <文章链接> --length medium。
3. 在几秒内获得一个段落长度的核心摘要，据此决定是让用户阅读摘要，还是基于摘要进一步提取关键点，或者发现需要全文阅读再调用--extract。

注意事项：总结服务按输出内容的Token数计费。一个“中等”长度的总结大约在500-800个Token（约合300-500英文单词）。对于超长文档，总结可能会自动截断或分层。对于技术文档，使用agnes引擎通常能得到更准确的技术术语和逻辑关系保留。

3.4 kagi-enrich：挖掘独立视角的探测器

这个工具专门用于查询Kagi的Teclis（独立高质量网站）和TinyGem（另类新闻）索引。当你的智能体需要摆脱主流信息源的束缚，寻找小众专家观点、独立分析报告，或者了解非主流媒体报道时，它就派上了用场。

核心参数与使用场景：

• -q, --query：查询词。
• -s, --source：指定搜索源，可选teclis、tinygem或both（默认）。
• --json：JSON格式输出。

独特价值：假设你在分析某个开源项目的生态。用普通搜索可能得到的是官方文档、主流技术媒体文章。而用kagi-enrich --query “<项目名> community review” --source teclis，你可能会发现某个个人技术博客上深度评测，或者一个小型开发者论坛里的激烈讨论，这些信息往往更真实、更接地气。

提示：kagi-enrich的每次查询费用极低（$0.002），非常适合作为常规搜索的补充，进行低成本、广撒网式的信息探索。你可以让智能体先进行常规搜索，再对关键主题用enrich查一下，看看有没有遗漏的“宝石”。

4. 从零开始：部署与集成到你的AI智能体

理论讲完了，我们来动手把它用起来。整个过程可以分为获取钥匙（API Key）、安装工具、集成到智能体三个步骤。

4.1 获取并配置Kagi API密钥

1. 注册账户：访问 kagi.com/signup 注册一个Kagi账户。你可以先选择免费试用或直接充值。
2. 生成API密钥：登录后，点击右上角头像进入Settings，然后找到API选项卡（或直接访问 kagi.com/settings?p=api ）。点击“Generate New Token”，为你的智能体项目创建一个专用的密钥，并为其命名（如“my-ai-agent”）。
3. 账户充值：Kagi API是预付费模式。你需要在账户中充值（通常最低10美元起），产生的API调用费用会从余额中扣除。计费清晰，在API页面可以查看使用明细。
4. 环境变量配置：这是让命令行工具能工作的关键。将你的API密钥设置为名为KAGI_API_KEY的环境变量。

   # 在Linux/macOS的bash或zsh中，可以添加到~/.bashrc或~/.zshrc文件末尾 export KAGI_API_KEY="你的实际API密钥" # 然后使配置生效 source ~/.zshrc # 如果你用zsh # 或者在当前终端会话中临时设置 export KAGI_API_KEY="你的实际API密钥" # 在fish shell中 set -Ux KAGI_API_KEY “你的实际API密钥”

   安全提醒：切勿将API密钥直接提交到版本控制系统（如Git）。环境变量是最基础的保密方式。在团队或生产环境中，应考虑使用更安全的密钥管理服务。

4.2 安装kagi-skills工具集

项目推荐通过源码编译安装，这能确保获得与你的系统完全兼容的最新版本。前提是你的机器上需要安装Go语言环境（1.26+）。

# 1. 克隆仓库 git clone https://github.com/joelazar/kagi-skills.git cd kagi-skills # 2. 编译所有工具 go build ./... # 这会在项目根目录生成四个可执行文件：kagi-search, kagi-fastgpt, kagi-summarizer, kagi-enrich # 3. 将工具移动到系统路径（可选，但推荐） sudo cp kagi-* /usr/local/bin/ # 或者只移动你需要的工具 sudo cp kagi-search kagi-summarizer /usr/local/bin/

验证安装：打开一个新的终端窗口，输入kagi-search --help，如果能看到帮助信息，说明安装成功，并且环境变量已生效（否则会提示缺少API密钥）。

备用安装方式（无需Go环境）：如果你不想安装Go，工具也提供了预编译的二进制文件。当你第一次运行某个工具（且系统没有Go）时，它会提示你是否从GitHub Releases下载对应平台的二进制文件。你可以选择“是”来自动完成下载和安装。不过，手动编译能让你始终使用最新的主分支代码。

4.3 集成到主流AI编码智能体

这是最激动人心的部分。kagi-skills的设计目标就是“即插即用”。每个工具都是一个独立的文件夹，里面包含了可执行文件和一份SKILL.md描述文件。AI智能体（如Claude Code、Pi）会读取SKILL.md来理解这个工具叫什么、怎么用、参数是什么。

通用集成步骤（以Pi/Gemini CLI/Codex为例）：

这些智能体通常将技能存放在~/.agents/skills/目录下。

# 进入你克隆的kagi-skills目录 cd /path/to/kagi-skills # 使用循环为所有kagi-开头的技能创建符号链接 for skill in kagi-*/; do ln -s "$(pwd)/$skill" ~/.agents/skills/"$skill" done # 检查是否链接成功 ls -la ~/.agents/skills/ | grep kagi

现在，重启你的AI智能体（或重新加载技能列表）。当你在对话中提出需要搜索或总结的需求时，智能体应该就能识别并建议使用kagi-search或kagi-summarizer等技能了。

集成到Claude Code：

Claude Code的技能目录通常是~/.claude/skills/。

cd /path/to/kagi-skills for skill in kagi-*/; do ln -s "$(pwd)/$skill" ~/.claude/skills/"$skill" done

集成到Cursor或自定义智能体：

Cursor等智能体的技能加载方式可能有所不同，请查阅其官方文档。但核心原理不变：你需要让智能体知道这些命令行工具的存在及其用法。SKILL.md文件就是工具的“说明书”。即使智能体没有自动扫描技能目录的功能，你也可以手动将SKILL.md中的用法描述配置到智能体的工具调用设置中。

实操现场记录：集成后的效果以Claude Code为例，集成后，当我正在编写一个网络请求函数时，我直接说：“帮我查一下Python httpx库最新版本中，异步客户端连接池的最佳配置参数是什么？” Claude Code的思考过程会显示它识别到了kagi-search技能，并生成类似以下的调用建议：

我可以使用kagi-search技能来查找最新的信息。调用：`kagi-search --query “Python httpx async client connection pool configuration best practices 2024” --limit 3 --json`

在我同意后，它执行命令，获取JSON结果，解析摘要，然后根据最相关的一两条结果，为我总结出配置建议，如limits=httpx.Limits(max_keepalive_connections=10, max_connections=100)，并附上了参考来源链接。整个过程无需我离开编辑器去打开浏览器搜索，信息流无缝衔接。

5. 高级技巧与实战避坑指南

掌握了基本用法后，一些实战中的技巧和常见问题的解决方法，能让你和你的智能体用得更顺手。

5.1 技能调用的优化策略

1. 查询构造的艺术：AI智能体（尤其是早期版本）生成的搜索查询可能过于宽泛或机械。指导你的智能体构造更有效的查询词。例如，不是“Python web scraping”，而是“Python web scraping BeautifulSoup vs Scrapy performance comparison 2024”。包含年份、具体的对比项、使用场景，能大幅提升首条结果的相关性。
2. 链式调用模式：这是发挥工具集威力的关键。一个典型的信息处理链条可能是：
   • 探索阶段：kagi-enrich-> 发现小众高质量文章。
   • 定位阶段：kagi-search-> 对感兴趣的主题进行精准搜索，获取链接。
   • 评估阶段：kagi-summarizer-> 对关键长文进行快速总结，判断价值。
   • 深度获取：kagi-search --extract-> 对高价值文章提取全文。
   • 综合解答：kagi-fastgpt-> 基于多个信息源，让AI直接给出综合答案。 你可以为智能体设计这样的工作流规则，让它自动判断在何种情境下使用哪个工具。
3. 成本控制：在智能体设置中，可以为工具调用增加确认环节，尤其是对于kagi-summarizer（按输出Token计费，处理长文档可能较贵）和kagi-fastgpt。对于简单的、事实性的查询，优先使用kagi-search。kagi-enrich很便宜，可以多用。

5.2 常见问题与排查

问题1：智能体找不到或无法调用技能。

• 检查：确认符号链接创建正确，且链接指向的源文件夹内包含SKILL.md和可执行文件。
• 检查：确认可执行文件有运行权限 (chmod +x kagi-search)。
• 检查：某些智能体可能需要重启或执行重载技能的命令（如Claude Code的/reload指令）。
• 检查：智能体的技能目录路径是否自定义过？查看其配置文件。

问题2：工具执行时报错“Invalid API key”或“Authentication failed”。

• 检查：环境变量KAGI_API_KEY是否在当前终端会话中已设置且正确。可以通过echo $KAGI_API_KEY验证。
• 检查：API密钥是否在Kagi账户设置中已启用。
• 检查：账户余额是否充足。

问题3：kagi-search --extract返回的内容杂乱或缺失。

• 原因：网页内容提取依赖于Kagi的后端解析器，对于JavaScript重度渲染的页面或结构特殊的网站，提取效果可能不佳。
• 应对：这是一个已知限制。可以尝试不使用--extract，而是让智能体根据摘要和链接，引导用户直接打开网页。或者，让智能体调用kagi-summarizer对原URL进行总结，总结模型通常能更好地抓住核心内容。

问题4：响应速度慢。

• 分析：kagi-fastgpt和kagi-summarizer涉及AI推理，速度取决于查询复杂度和服务器负载，通常需要几秒到十几秒。纯搜索（kagi-search不带--extract）最快。
• 优化：对于需要快速响应的交互，优先使用纯搜索。将耗时操作（如总结长文档）设计为后台任务或提供进度提示。

问题5：如何在我的自定义AI Agent中集成？

• 核心：你的Agent需要具备调用外部shell命令或子进程的能力。
• 步骤：
  1. 将编译好的kagi-*二进制文件放在Agent可访问的路径。
  2. 在你的Agent逻辑中，当判定需要搜索/总结时，构造相应的命令行参数。
  3. 使用你编程语言的子进程库（如Python的subprocess，Node.js的child_process）来执行命令并捕获其标准输出（stdout）。
  4. 如果使用--json标志，则用JSON解析器处理输出；否则，处理纯文本输出。
  5. 将处理后的结果融入Agent的回复中。 本质上，你就是手动实现了SKILL.md描述的解析和调用逻辑。

5.3 安全与隐私考量

• API密钥安全：如前所述，永远不要硬编码密钥。使用环境变量或专业的密钥管理服务（如HashiCorp Vault、AWS Secrets Manager）。
• 查询日志：请注意，通过API发送的查询内容会经过Kagi的服务器。虽然Kagi有严格的隐私政策，但如果你处理的是高度敏感的商业信息或个人数据，需评估风险。对于公开信息检索，这通常不是问题。
• 依赖管理：如果你将集成了此工具集的智能体项目商业化或交付给客户，需要确保客户拥有自己的Kagi API账户并自行配置密钥，或者将API成本清晰地纳入你的服务计费中。

将kagi-skills集成到你的AI工作流中，不仅仅是增加了一个搜索功能。它是在为你的数字助手建立一个高质量、可控的外部信息感知系统。从被SEO噪音污染的信息海洋，转向一个更干净、更以用户为中心的信息网络，这中间的差异，在你日常的开发和信息处理中会日积月累地体现出来。开始尝试让智能体去查询那些独立技术博客里的深度分析，或者快速消化一篇新的RFC文档，你会发现，获取信息的效率和信度，真的可以不一样。