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。当你提出一个问题时它会在后台使用Kagi搜索进行实时查询。获取并分析相关的网页内容。利用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更适用于学术/技术文档。不同引擎可能产生不同风格的总结。典型工作流AI智能体通过kagi-search找到一篇长文。判断文章可能包含所需信息但篇幅太长于是调用kagi-summarizer --url 文章链接 --length medium。在几秒内获得一个段落长度的核心摘要据此决定是让用户阅读摘要还是基于摘要进一步提取关键点或者发现需要全文阅读再调用--extract。注意事项总结服务按输出内容的Token数计费。一个“中等”长度的总结大约在500-800个Token约合300-500英文单词。对于超长文档总结可能会自动截断或分层。对于技术文档使用agnes引擎通常能得到更准确的技术术语和逻辑关系保留。3.4 kagi-enrich挖掘独立视角的探测器这个工具专门用于查询Kagi的Teclis独立高质量网站和TinyGem另类新闻索引。当你的智能体需要摆脱主流信息源的束缚寻找小众专家观点、独立分析报告或者了解非主流媒体报道时它就派上了用场。核心参数与使用场景-q, --query查询词。-s, --source指定搜索源可选teclis、tinygem或both默认。--jsonJSON格式输出。独特价值假设你在分析某个开源项目的生态。用普通搜索可能得到的是官方文档、主流技术媒体文章。而用kagi-enrich --query “项目名 community review” --source teclis你可能会发现某个个人技术博客上深度评测或者一个小型开发者论坛里的激烈讨论这些信息往往更真实、更接地气。提示kagi-enrich的每次查询费用极低$0.002非常适合作为常规搜索的补充进行低成本、广撒网式的信息探索。你可以让智能体先进行常规搜索再对关键主题用enrich查一下看看有没有遗漏的“宝石”。4. 从零开始部署与集成到你的AI智能体理论讲完了我们来动手把它用起来。整个过程可以分为获取钥匙API Key、安装工具、集成到智能体三个步骤。4.1 获取并配置Kagi API密钥注册账户访问 kagi.com/signup 注册一个Kagi账户。你可以先选择免费试用或直接充值。生成API密钥登录后点击右上角头像进入Settings然后找到API选项卡或直接访问 kagi.com/settings?papi 。点击“Generate New Token”为你的智能体项目创建一个专用的密钥并为其命名如“my-ai-agent”。账户充值Kagi API是预付费模式。你需要在账户中充值通常最低10美元起产生的API调用费用会从余额中扣除。计费清晰在API页面可以查看使用明细。环境变量配置这是让命令行工具能工作的关键。将你的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 CodeClaude 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结果解析摘要然后根据最相关的一两条结果为我总结出配置建议如limitshttpx.Limits(max_keepalive_connections10, max_connections100)并附上了参考来源链接。整个过程无需我离开编辑器去打开浏览器搜索信息流无缝衔接。5. 高级技巧与实战避坑指南掌握了基本用法后一些实战中的技巧和常见问题的解决方法能让你和你的智能体用得更顺手。5.1 技能调用的优化策略查询构造的艺术AI智能体尤其是早期版本生成的搜索查询可能过于宽泛或机械。指导你的智能体构造更有效的查询词。例如不是“Python web scraping”而是“Python web scraping BeautifulSoup vs Scrapy performance comparison 2024”。包含年份、具体的对比项、使用场景能大幅提升首条结果的相关性。链式调用模式这是发挥工具集威力的关键。一个典型的信息处理链条可能是探索阶段kagi-enrich- 发现小众高质量文章。定位阶段kagi-search- 对感兴趣的主题进行精准搜索获取链接。评估阶段kagi-summarizer- 对关键长文进行快速总结判断价值。深度获取kagi-search --extract- 对高价值文章提取全文。综合解答kagi-fastgpt- 基于多个信息源让AI直接给出综合答案。 你可以为智能体设计这样的工作流规则让它自动判断在何种情境下使用哪个工具。成本控制在智能体设置中可以为工具调用增加确认环节尤其是对于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账户设置中已启用。检查账户余额是否充足。问题3kagi-search --extract返回的内容杂乱或缺失。原因网页内容提取依赖于Kagi的后端解析器对于JavaScript重度渲染的页面或结构特殊的网站提取效果可能不佳。应对这是一个已知限制。可以尝试不使用--extract而是让智能体根据摘要和链接引导用户直接打开网页。或者让智能体调用kagi-summarizer对原URL进行总结总结模型通常能更好地抓住核心内容。问题4响应速度慢。分析kagi-fastgpt和kagi-summarizer涉及AI推理速度取决于查询复杂度和服务器负载通常需要几秒到十几秒。纯搜索kagi-search不带--extract最快。优化对于需要快速响应的交互优先使用纯搜索。将耗时操作如总结长文档设计为后台任务或提供进度提示。问题5如何在我的自定义AI Agent中集成核心你的Agent需要具备调用外部shell命令或子进程的能力。步骤将编译好的kagi-*二进制文件放在Agent可访问的路径。在你的Agent逻辑中当判定需要搜索/总结时构造相应的命令行参数。使用你编程语言的子进程库如Python的subprocessNode.js的child_process来执行命令并捕获其标准输出stdout。如果使用--json标志则用JSON解析器处理输出否则处理纯文本输出。将处理后的结果融入Agent的回复中。 本质上你就是手动实现了SKILL.md描述的解析和调用逻辑。5.3 安全与隐私考量API密钥安全如前所述永远不要硬编码密钥。使用环境变量或专业的密钥管理服务如HashiCorp Vault、AWS Secrets Manager。查询日志请注意通过API发送的查询内容会经过Kagi的服务器。虽然Kagi有严格的隐私政策但如果你处理的是高度敏感的商业信息或个人数据需评估风险。对于公开信息检索这通常不是问题。依赖管理如果你将集成了此工具集的智能体项目商业化或交付给客户需要确保客户拥有自己的Kagi API账户并自行配置密钥或者将API成本清晰地纳入你的服务计费中。将kagi-skills集成到你的AI工作流中不仅仅是增加了一个搜索功能。它是在为你的数字助手建立一个高质量、可控的外部信息感知系统。从被SEO噪音污染的信息海洋转向一个更干净、更以用户为中心的信息网络这中间的差异在你日常的开发和信息处理中会日积月累地体现出来。开始尝试让智能体去查询那些独立技术博客里的深度分析或者快速消化一篇新的RFC文档你会发现获取信息的效率和信度真的可以不一样。