1. 项目概述一个为Kagi搜索定制的技能库如果你和我一样对传统搜索引擎的广告泛滥和结果同质化感到厌倦那么Kagi这个新兴的搜索工具很可能已经进入了你的视野。它主打无广告、高隐私和高度可定制化确实带来了不一样的搜索体验。但Kagi的魅力远不止于此其真正的潜力在于它的“技能”系统。今天要聊的就是这个生态中一个非常有意思的项目wawa1154/kagi-skills。简单来说这是一个托管在GitHub上的开源仓库里面汇集了众多为Kagi搜索开发的“技能”。你可以把它理解为一个Kagi的“应用商店”或“插件中心”。这些技能本质上是一些小型的、功能特定的程序或脚本它们能直接嵌入到你的Kagi搜索结果页面中在你搜索特定内容时自动触发并返回结构化的、增强的信息。比如搜索一个编程问题它可能直接调用一个代码解释器技能在侧边栏给出清晰的解答和示例搜索一个电影名一个电影信息技能可能会直接展示评分、演员表和简介。这个项目解决了什么问题核心就是效率与深度。它让搜索从“返回一堆链接让你自己点”变成了“直接给你答案和结构化信息”。对于开发者、研究者、学生乃至任何需要高效获取信息的用户来说这无疑是一个生产力利器。wawa1154/kagi-skills仓库的价值在于它将这些分散的技能集中管理、开源共享降低了普通用户使用技能的门槛也为开发者提供了一个展示和协作的平台。无论你是想直接使用这些现成的技能来武装你的Kagi还是想学习如何开发自己的技能这个项目都是一个绝佳的起点。2. Kagi技能系统深度解析架构、原理与生态在深入使用或开发技能之前我们必须先理解Kagi技能系统是如何工作的。这不仅仅是“安装即用”那么简单理解其背后的架构能帮助我们在选择、配置乃至排错时事半功倍。2.1 Kagi技能的核心架构与运行机制Kagi技能系统采用了典型的“事件驱动”架构。整个流程可以概括为用户发起搜索 - Kagi解析查询意图 - 匹配并触发相关技能 - 技能执行并返回结果 - Kagi将结果渲染到搜索页面。技能定义与注册每个技能都是一个独立的、符合Kagi规范的项目。它通常包含一个核心的脚本文件如Python、JavaScript和一个manifest.json之类的配置文件。这个配置文件定义了技能的“元数据”技能的唯一ID、名称、描述、触发关键词或模式、所需的权限以及结果展示的模板。开发者将技能代码部署到一个可公开访问的URL例如通过Vercel、Cloudflare Workers等Serverless平台或自己的服务器。然后在Kagi的开发者后台通过这个URL“注册”技能将其纳入Kagi的生态系统。查询意图识别与技能匹配这是Kagi的“大脑”。当你输入一个搜索词时Kagi的后台不仅会进行传统的网页索引匹配还会并行分析查询语句判断其是否匹配某个已注册技能的触发条件。触发条件可以是简单的关键词如“define [某个词]”触发词典技能也可以是更复杂的自然语言模式如“weather in [城市名]”触发天气技能。匹配算法是Kagi的核心竞争力之一它决定了技能的“智能”程度。技能执行与数据获取一旦匹配成功Kagi会向技能部署的端点发送一个HTTP请求通常是POST请求请求体中包含了搜索查询、用户上下文如语言偏好、地理位置需用户授权等信息。技能后端接收到请求后执行其核心逻辑这可能包括调用外部API如OpenAI的GPT接口、GitHub API、天气API、查询数据库、或者进行本地计算。结构化结果返回与前端渲染技能执行完毕后需要按照Kagi规定的格式返回数据。这通常是一个结构化的JSON对象包含了标题、摘要、详细内容、链接、图片等字段。Kagi的前端收到这个JSON后会使用预定义的或技能自定义的UI模板将结果优雅地嵌入到搜索结果页面的侧边栏或顶部区域。这种结构化的展示方式远比一堆蓝色链接要直观和高效。2.2wawa1154/kagi-skills仓库的生态位与价值理解了技能系统本身我们再来看wawa1154/kagi-skills这个项目。它并非Kagi的官方组件而是一个社区驱动的开源集合。它的核心价值体现在以下几个方面降低使用门槛对于非技术用户逐个寻找、理解、部署技能是困难的。这个仓库像是一个“精选集”用户可以直接浏览README找到自己感兴趣的技能通常只需在Kagi设置中填入该技能提供的公共端点URL即可启用无需关心背后的服务器和代码。促进开发与学习对于开发者这个仓库是绝佳的学习范本和灵感来源。你可以看到不同复杂度的技能是如何实现的学习如何编写manifest.json如何处理Kagi的请求如何设计返回的数据结构。它本质上是一个开放的、不断增长的“代码食谱”。质量筛选与社区维护虽然仓库收录的技能质量参差不齐但通过开源协作社区可以共同改进代码、修复Bug、提交新的技能创意。仓库的维护者如wawa1154在一定程度上扮演了“策展人”的角色通过合并Pull Request来保证收录技能的基本可用性。填补官方生态空白Kagi官方也会提供一些技能但数量和种类有限。社区仓库极大地丰富了技能生态覆盖了从生产力工具如代码解释、单位换算、娱乐信息电影、音乐、到实用查询快递跟踪、加密货币价格等方方面面满足了长尾需求。注意使用社区技能时务必注意隐私和安全。技能后端会接收到你的搜索查询。虽然大多数开源技能代码可审计且部署在可信平台但仍建议只启用你信任的技能并避免在触发技能时搜索高度敏感的个人信息。3. 核心技能实战从安装到深度使用理论讲得再多不如亲手一试。我们以wawa1154/kagi-skills仓库中几个典型且实用的技能为例带你走通从发现、安装到深度配置的全过程。3.1 技能发现与筛选指南打开wawa1154/kagi-skills的GitHub页面你会发现技能可能以文件夹或列表形式组织。如何快速找到适合自己的技能按类别浏览查看仓库的README或目录结构技能常被分为“开发者工具”、“生活实用”、“学习与参考”、“娱乐”等类别。这是最直接的筛选方式。阅读技能描述与预览每个技能文件夹下都应有详细的README.md其中会说明技能的功能、触发方式、返回结果的截图示例。仔细阅读这些内容判断它是否符合你的预期。检查活跃度与维护状态查看技能文件夹的最后更新日期、是否有未解决的Issue问题。一个近期有更新、Issue较少的技能通常更可靠。对于代码类技能可以简单浏览一下源码看其结构是否清晰。理解触发方式这是关键。技能描述中必须明确写明触发关键词或句式。例如“/crypto Bitcoin”意味着你要在Kagi搜索框输入“/crypto Bitcoin”来触发加密货币查询技能。有些技能是“静默触发”的比如当你搜索“Python lambda function”时一个编程解答技能可能会自动匹配并显示结果。3.2 实战安装以“代码解释器”技能为例假设我们找到了一个名为“Code Explainer”的技能它可以用通俗语言解释你粘贴的代码片段。我们来看看如何安装它。获取技能端点URL在技能的README中开发者通常会提供一个公共可用的端点URL。例如https://code-explainer.example.com/api/explain。有些技能可能需要你自己部署这时README里会提供部署到Vercel或Netlify的“一键部署”按钮。对于wawa1154/kagi-skills中的技能请仔细查看说明确认是使用公共端点还是需要自部署。在Kagi中配置技能登录你的Kagi账户进入设置Settings。找到“搜索”Search或“实验室”Labs下的“技能”Skills或“自定义答案”Custom Answers板块。点击“添加新技能”或类似按钮。在弹出的表单中你需要填写技能名称自定义一个易记的名字如“My Code Explainer”。端点URL粘贴你从README中获取的URL。触发模式选择或填写触发方式。对于代码解释器可能是当查询包含“explain this code”或“/explain”时触发。这里需要严格按照技能文档的说明填写。其他参数有些技能可能需要额外的API密钥例如如果它后端调用了OpenAI你需要提供自己的OpenAI API Key。这些信息也需要在Kagi的技能配置界面中填写通常以“环境变量”或“附加头信息”的形式提供。测试与验证保存配置后打开一个新的Kagi搜索标签页。输入触发词并加上一段测试代码例如“/explaindef factorial(n): return 1 if n0 else n*factorial(n-1)”。观察侧边栏是否出现了代码的解释结果。如果失败返回检查URL、触发模式和API密钥是否正确。3.3 高级配置与个性化技巧安装只是第一步要让技能更好地为你服务还需要一些个性化配置。调整触发优先级如果你安装了多个可能对同一查询产生反应的技能比如一个通用词典技能和一个编程术语词典技能你可以在Kagi设置中调整它们的优先级顺序确保更专业的技能优先触发。利用环境变量管理密钥对于需要第三方API密钥的技能绝对不要将密钥硬编码在你要部署的代码中或泄露给不可信的公共端点。如果自部署使用部署平台如Vercel的环境变量功能来安全地存储密钥。如果使用公共端点请确保你完全信任该技能的维护者。技能组合使用Kagi技能可以协同工作。例如你可以先用一个“GitHub Repo Summary”技能快速了解一个项目然后针对项目中的具体技术问题用“Code Explainer”技能进行深入询问。这种“技能链”式的使用能极大提升研究效率。关注技能更新订阅你常用技能所在GitHub仓库的Release通知或Star仓库。技能的维护者可能会修复Bug、增加新功能或优化触发逻辑。定期更新你的技能端点URL或重新部署能获得最佳体验。4. 从使用者到创造者开发你的第一个Kagi技能当你用熟了别人的技能很可能会产生一些独特的想法“要是有个能查XX的技能就好了”。别犹豫Kagi技能开发的门槛并不高我们来一步步实现它。4.1 开发环境准备与项目初始化我们计划开发一个“今日历史事件”技能当用户搜索“today in history”或“历史上的今天”时返回当天发生的历史事件列表。选择技术栈Kagi技能后端对语言没有限制只要能处理HTTP请求并返回JSON即可。这里我们选择Node.jsJavaScript/TypeScript因为它部署到Serverless平台非常方便。确保你的电脑安装了Node.js和npm。初始化项目mkdir kagi-today-in-history cd kagi-today-in-history npm init -y安装依赖我们需要一个Web框架来处理请求以及一个HTTP客户端来获取历史事件数据。这里选择Express和Axios。npm install express axios4.2 核心代码实现与Kagi API对接创建主文件index.jsconst express require(express); const axios require(axios); const app express(); const port process.env.PORT || 3000; // 中间件解析JSON格式的请求体 app.use(express.json()); // 定义技能端点 app.post(/api/today-in-history, async (req, res) { try { // 1. 从Kagi的请求中获取查询内容可选本例中触发词已固定 const query req.body.query || ; console.log(Received query: ${query}); // 2. 调用外部API获取“历史上的今天”数据 // 这里使用一个假设的公共API实际开发中请寻找可靠的数据源例如https://history.muffinlabs.com/date const today new Date(); const month today.getMonth() 1; // 月份从0开始 const day today.getDate(); const apiUrl https://history.muffinlabs.com/date/${month}/${day}; const response await axios.get(apiUrl); const data response.data; // 3. 构建符合Kagi格式的响应 const kagiResponse { // 结果卡片显示的标题 title: On This Day: ${month}/${day}, // 简短的摘要 subtitle: Notable historical events that happened on ${month}/${day}, // 详细的HTML内容Kagi会安全地渲染 content: h3Selected Events:/h3 ul ${data.data.Events.slice(0, 5).map(event listrong${event.year}:/strong ${event.text}/li).join()} /ul pemData provided by a href${data.url}Muffin Labs/a/em/p , // 可选的图标 icon: https://example.com/icon.png, // 可选的链接 url: data.url }; // 4. 返回JSON响应 res.json(kagiResponse); } catch (error) { console.error(Error fetching history data:, error); // 出错时返回一个友好的错误信息给Kagi res.status(500).json({ title: Error, content: pSorry, I couldnt fetch historical data at the moment. Please try again later./p }); } }); // 启动服务器 app.listen(port, () { console.log(Kagi skill server listening on port ${port}); });这段代码创建了一个简单的Express服务器监听/api/today-in-history端点的POST请求。当请求到来时它会获取当天的日期调用一个公共的历史事件API然后将获取的数据格式化成Kagi能识别的JSON结构并返回。创建技能清单文件manifest.json可选但推荐 虽然Kagi注册时主要需要端点URL但创建一个manifest.json有助于说明你的技能。{ id: today-in-history, name: Today in History, description: Shows historical events that happened on the current day., trigger: { pattern: [today in history, 历史上的今天, on this day] }, endpoint: /api/today-in-history, permissions: [network] }4.3 本地测试与部署上线本地测试在项目目录下运行node index.js。使用工具如curl或Postman模拟Kagi的请求curl -X POST http://localhost:3000/api/today-in-history \ -H Content-Type: application/json \ -d {query: today in history}检查返回的JSON是否符合预期格式是否正确。部署到Serverless平台以Vercel为例在项目根目录创建vercel.json配置文件{ version: 2, builds: [ { src: index.js, use: vercel/node } ], routes: [ { src: /api/(.*), dest: index.js } ] }将代码推送到GitHub。登录Vercel导入你的GitHub仓库部署。Vercel会自动分配一个如https://your-project.vercel.app的域名。你的技能端点URL就是https://your-project.vercel.app/api/today-in-history。在Kagi中注册你的技能进入Kagi设置 - 技能 - 添加新技能。名称填“Today in History”端点URL填上面Vercel提供的URL。触发模式可以填“today in history”或“历史上的今天”。保存后在Kagi搜索框输入“today in history”你的技能就应该被触发并显示结果了5. 常见问题排查与性能优化实战录在开发和使用技能的过程中你一定会遇到各种问题。下面是我在实践中总结的一些典型问题及其解决方案。5.1 技能不触发或返回错误这是最常见的问题排查思路可以遵循以下链条问题现象可能原因排查步骤与解决方案搜索触发词后无任何反应1. 触发模式配置错误2. 技能端点URL无法访问3. Kagi技能服务暂时性故障1.检查触发模式确保在Kagi设置中填写的触发词与技能设计完全一致注意大小写和空格。可以尝试更简单的触发词测试。2.测试端点URL在浏览器或curl中直接访问你的端点URL如果是GET或用Postman发送一个模拟POST请求看服务器是否正常响应。检查Serverless平台的部署日志。3.检查网络确保你的网络环境能正常访问技能部署的域名如vercel.app。技能触发但显示“暂时无法获取结果”或错误信息1. 技能后端代码逻辑错误或崩溃2. 依赖的外部API失效或限流3. 返回的JSON格式不符合Kagi规范1.查看后端日志这是最重要的排错手段。去Vercel、Cloudflare Workers等平台的控制台查看函数调用日志找到具体的错误信息。2.模拟请求调试用Postman完全模拟Kagi发送的请求包括请求体格式在你的本地或测试环境运行技能代码逐行调试。3.验证返回格式确保你的技能返回的是一个有效的JSON对象且包含title和content等必需字段。content字段内的HTML必须是良构的。技能结果展示错乱或样式异常返回的HTML内容存在样式冲突或不符合Kagi的渲染预期1.简化HTML避免在content中使用复杂的CSS或JavaScript。尽量使用简单的标签如p,ul,li,strong,em。2.使用内联样式如果必须定义样式使用内联style属性避免style标签或外部CSS因为Kagi的安全策略可能会过滤它们。5.2 性能优化与成本控制心得当你的技能用户增多或者技能逻辑变复杂时性能和成本就需要纳入考量了。冷启动优化Serverless函数有“冷启动”延迟。对于Node.js/Python可以通过以下方式缓解保持函数轻量精简依赖包只引入必需的库。使用更快的运行时考虑使用Bun、Deno或Go等冷启动更快的运行时来重写技能。配置预留实例如果平台支持如AWS Lambda可以配置预留并发让函数实例常驻但这会增加成本。缓存是王道对于频繁请求且数据变化不快的技能如“历史上的今天”一天内数据不变必须引入缓存。内存缓存对于短期、单实例缓存可以使用node-cache这样的库。分布式缓存对于多实例部署使用Redis或平台提供的KV存储如Vercel KV、Cloudflare KV。缓存策略示例在获取历史事件数据前先检查缓存中是否有当天的数据。如果有直接返回如果没有再调用外部API并将结果存入缓存设置过期时间为24小时。这能极大减少外部API调用次数提升响应速度并节省API调用成本。异步处理与超时设置Kagi对技能响应有时间限制通常几秒。如果你的技能需要执行长时间操作如调用慢速API或复杂计算务必设置合理的超时并考虑将同步操作改为异步先返回一个“正在处理”的状态再通过Webhook等方式推送最终结果如果Kagi支持。目前更常见的做法是优化技能逻辑确保在超时限制内返回。成本监控如果你调用的外部API是付费的如OpenAI、某些数据API或者你的Serverless平台用量激增务必设置用量告警和预算限制。在技能代码中加入简单的调用计数和日志便于分析使用模式。5.3 安全与隐私最佳实践开发技能尤其是公开分享的技能安全至关重要。永远不要硬编码密钥将API密钥、数据库密码等敏感信息通过环境变量管理。所有主流部署平台都支持此功能。验证请求来源可选但推荐理论上只有Kagi的服务器会向你的技能端点发送请求。你可以验证请求头中是否包含Kagi特定的签名或Token如果Kagi未来提供此功能或者至少验证请求的User-Agent。这可以防止你的端点被滥用。对用户输入进行清理和转义虽然Kagi传递的query通常相对安全但如果你允许用户输入更多参数务必对输入进行严格的验证和清理防止注入攻击如SQL注入、XSS。在返回的HTMLcontent中对动态内容进行HTML实体转义。隐私声明如果你的技能会收集或记录用户的查询数据即使只是匿名统计必须在技能的描述中明确告知用户并遵守相关的数据保护法规。开发一个稳定、高效、安全的Kagi技能其成就感不亚于构建一个独立的应用。它让你能直接参与到重塑搜索体验的进程中用代码解决自己遇到的具体问题。wawa1154/kagi-skills这样的仓库正是这股创新力量的集散地。从使用到贡献再到独立创造这条路径清晰地摆在每个用户面前。