1. 项目概述与核心价值最近在折腾个人知识库和自动化工作流时我一直在寻找一个能真正理解我意图、并能精准调用外部工具来完成复杂任务的“智能副手”。市面上很多AI助手要么能力单一要么需要繁琐的配置和编程。直到我深度体验了Kagi Search的“Skills”技能功能并发现了wawa1154/kagi-skills这个开源项目才感觉找到了“瑞士军刀”级别的解决方案。这个项目本质上是一个社区驱动的Kagi Skills仓库它允许任何用户贡献、分享和订阅由他人创建的、功能强大的自动化技能脚本。简单来说Kagi Skills就像给你的Kagi搜索一个注重隐私的搜索引擎装上了可编程的“超能力插件”。而wawa1154/kagi-skills项目则是这些插件的“开源应用商店”。它解决了几个核心痛点对于普通用户无需学习复杂的编程就能一键订阅诸如“总结网页内容”、“翻译并润色文本”、“查询天气并生成出行建议”等技能对于开发者或高级用户它提供了一个标准化框架来创建和分享自己的技能将想法快速转化为可复用的工具。无论你是想提升信息处理效率的研究者、需要快速整合多源信息的自媒体人还是热衷于自动化工具的极客这个项目都值得你深入了解。接下来我将从设计思路、核心机制到实战应用为你完整拆解如何利用这个项目释放生产力。2. 技能生态的设计理念与架构解析2.1 为什么是“技能”而非“插件”在深入代码之前理解Kagi Skills的设计哲学至关重要。它与传统浏览器插件或用户脚本如Tampermonkey有本质区别。后者通常作用于网页DOM进行样式修改或内容抓取其上下文局限于当前浏览器标签页。而Kagi Skills被设计为与AI助手Kagi Assistant深度集成的、基于意图识别和API调用的微服务。它的工作流程是这样的你在Kagi Assistant的聊天界面中用自然语言描述一个任务例如“请把https://example.com/article这篇文章的核心观点总结成三点并翻译成日语”。Assistant会首先判断你的意图——这涉及到“总结”和“翻译”。接着它会在已启用的技能库中寻找匹配的技能。如果找到了就会将任务连同URL、你的指令细节发送给对应技能的后端逻辑去执行。技能后端可以调用任意的外部API如OpenAI的GPT、Google Translate、WolframAlpha等处理数据最后将结构化的结果返回给Assistant呈现给你。wawa1154/kagi-skills项目仓库中的每一个技能都是一个独立、自包含的“功能包”。这种架构带来了几个显著优势隐私与安全技能逻辑运行在技能创建者指定的服务器或边缘环境如Cloudflare Workers你的原始查询和数据仅在Kagi与技能后端之间加密传输技能代码开源可审计。强大的集成能力由于可以自由调用API技能的能力边界几乎无限从查询实时加密货币价格、分析GitHub仓库数据到控制智能家居需相应API都可以实现。低门槛共享贡献者只需按照规范编写一个技能定义文件通常是skill.json描述技能的功能、触发词和端点其他人就能通过Kagi界面一键订阅无需部署代码。2.2 项目仓库结构深度解读打开wawa1154/kagi-skills的GitHub仓库你会发现其结构非常清晰旨在方便社区协作kagi-skills/ ├── skills/ # 核心目录所有社区贡献的技能存放于此 │ ├── web-summarizer/ # 示例网页总结技能 │ │ ├── skill.json # 技能元数据配置文件必选 │ │ ├── icon.png # 技能图标可选 │ │ └── README.md # 技能详细说明文档可选但推荐 │ ├── currency-converter/ │ └── ... # 更多技能文件夹 ├── CONTRIBUTING.md # 详细的技能贡献指南 ├── README.md # 项目总览和使用说明 └── .github/ # GitHub Actions工作流等核心文件skill.json剖析 这个文件是技能的“身份证”和“说明书”。Kagi平台通过解析它来了解如何展示和调用该技能。一个典型的配置如下{ schema_version: v1, display_name: 网页智能总结器, description: 提取任意网页文章的核心内容生成简洁、准确的摘要。支持指定摘要长度和语言。, skill_id: web-summarizer, invocation_name: { default: 总结这个网页, zh-CN: 总结这个网页 }, version: 1.0.0, author: 你的名字, endpoint: { url: https://your-worker.your-account.workers.dev/summarize, methods: [POST] }, input_schema: { type: object, properties: { url: { type: string, description: 需要总结的网页URL }, summary_length: { type: string, enum: [short, medium, long], default: medium, description: 摘要长度 }, target_language: { type: string, description: 目标语言代码如zh-CN, en, default: zh-CN } }, required: [url] }, output_schema: { type: object, properties: { summary: { type: string, description: 生成的摘要文本 }, key_points: { type: array, items: {type: string}, description: 关键要点列表 } } } }关键字段解读与配置心得invocation_name: 这是用户触发技能的关键词。设置时需考虑多语言和口语化。例如除了“总结”也可以考虑“概括”、“提炼一下”等同义词增加触发几率。在wawa1154/kagi-skills的很多技能中作者会精心设计中英文的触发词。endpoint.url: 技能后端服务的地址。这是实操中最容易出错的环节。对于个人开发者我强烈推荐使用Cloudflare Workers作为部署首选。它免费额度高、全球网络快、支持JavaScript/TypeScript并且配置简单非常适合这种轻量级、无状态的API服务。后文会详细演示部署过程。input_schema和output_schema: 定义了技能与Kagi Assistant通信的“合同”。清晰的Schema能帮助Assistant更好地引导用户输入并解析返回结果。output_schema的设计直接影响返回结果的展示效果结构化的数据如包含summary和key_points比单一文本更友好。注意在编写skill.json时务必确保skill_id在整个仓库内唯一。建议使用kebab-case短横线连接命名如weather-forecast。良好的description能大大提高技能在社区内的被发现和使用率。3. 从零到一创建并贡献一个自定义技能了解了架构最好的学习方式就是动手做一个。假设我们想创建一个“技术博客质量评估器”技能输入一篇技术博客的URL技能能返回对其内容深度、代码示例质量、可读性等方面的简要评分和评语。3.1 技能构思与skill.json编写首先在本地skills/目录下创建新文件夹tech-blog-rater。然后创建skill.json{ schema_version: v1, display_name: 技术博客质量评估器, description: 对给定的技术博客文章进行快速评估从内容深度、实践价值、可读性等方面提供简要评分和反馈。, skill_id: tech-blog-rater, invocation_name: { default: 评估这篇技术文章, en: rate this tech blog }, version: 0.1.0, author: [你的GitHub用户名], endpoint: { url: https://tech-blog-rater.[你的子域].workers.dev/, methods: [POST] }, input_schema: { type: object, properties: { url: { type: string, description: 待评估的技术博客文章URL }, focus_area: { type: string, enum: [frontend, backend, devops, algorithm, general], default: general, description: 重点关注的技术领域 } }, required: [url] }, output_schema: { type: object, properties: { overall_score: { type: number, minimum: 0, maximum: 10, description: 综合评分10分制 }, dimensions: { type: object, properties: { depth: {type: number, description: 内容深度评分}, practicality: {type: number, description: 实践价值评分}, clarity: {type: number, description: 表达清晰度评分} } }, feedback: { type: string, description: 总体评语与改进建议 }, suitable_for: { type: string, description: 文章适合的读者群体 } }, required: [overall_score, feedback] } }3.2 后端逻辑实现与部署Cloudflare Workers实战技能的核心逻辑在后端。我们使用Cloudflare Workers因为它与Kagi Skills的轻量、快速响应特性完美契合。步骤1初始化Worker项目使用WranglerCloudflare的命令行工具创建项目npm create cloudflarelatest tech-blog-rater-worker cd tech-blog-rater-worker选择“Hello World”模板语言选择TypeScript。步骤2编写核心逻辑编辑src/index.ts。我们需要完成1) 从URL获取文章内容2) 调用AI API进行分析3) 格式化返回结果。这里以使用OpenAI API为例也可用其他如Anthropic Claude、本地模型等。// src/index.ts interface Env { OPENAI_API_KEY: string; } export default { async fetch(request: Request, env: Env, ctx: ExecutionContext): PromiseResponse { // 1. 处理CORS预检请求 if (request.method OPTIONS) { return new Response(null, { headers: { Access-Control-Allow-Origin: *, Access-Control-Allow-Methods: POST, OPTIONS, Access-Control-Allow-Headers: Content-Type, }, }); } // 2. 仅处理POST请求 if (request.method ! POST) { return new Response(Method Not Allowed, { status: 405 }); } try { // 3. 解析Kagi发送的请求体 const requestBody await request.json(); const { url, focus_area general } requestBody; if (!url) { return new Response(JSON.stringify({ error: Missing required field: url }), { status: 400, headers: { Content-Type: application/json, Access-Control-Allow-Origin: * }, }); } // 4. 获取网页内容简化示例实际需处理反爬、动态内容等 const htmlResponse await fetch(url); const htmlText await htmlResponse.text(); // 简单提取正文生产环境应使用更健壮的库如readability或cheerio const textContent extractMainContent(htmlText); // 假设的提取函数 // 5. 构建发送给OpenAI的提示词 const prompt 你是一个资深技术编辑请对以下技术博客文章进行评估。 文章URL: ${url} 重点关注领域: ${focus_area} 文章内容摘要: ${textContent.substring(0, 3000)}... [内容可能被截断] 请从以下维度以1-10分打分10为最佳并给出总体评语 - 内容深度概念的深入程度、原理剖析是否透彻。 - 实践价值代码示例、实操步骤是否清晰有用能否直接指导实践。 - 表达清晰度结构是否清晰语言是否易懂。 请以JSON格式回复包含以下字段 { overall_score: 一个综合分数, dimensions: { depth: 分数, practicality: 分数, clarity: 分数 }, feedback: 总体评语与具体改进建议, suitable_for: 如初级开发者、架构师等 } ; // 6. 调用OpenAI API const openaiResponse await fetch(https://api.openai.com/v1/chat/completions, { method: POST, headers: { Authorization: Bearer ${env.OPENAI_API_KEY}, Content-Type: application/json, }, body: JSON.stringify({ model: gpt-4o-mini, // 或 gpt-3.5-turbo 控制成本 messages: [{ role: user, content: prompt }], temperature: 0.2, response_format: { type: json_object }, // 要求返回JSON }), }); const openaiData await openaiResponse.json(); const analysisResult JSON.parse(openaiData.choices[0].message.content); // 7. 返回符合output_schema的响应 return new Response(JSON.stringify(analysisResult), { headers: { Content-Type: application/json, Access-Control-Allow-Origin: *, }, }); } catch (error) { console.error(Skill execution error:, error); return new Response(JSON.stringify({ error: Internal server error, details: error.message }), { status: 500, headers: { Content-Type: application/json, Access-Control-Allow-Origin: * }, }); } }, }; // 简单的正文提取函数示例需增强 function extractMainContent(html: string): string { // 这里应使用更可靠的HTML解析库 // 为简化直接返回部分文本 const doc new DOMParser().parseFromString(html, text/html); return doc.body.textContent || ; }步骤3配置与部署在Cloudflare Dashboard的Workers Pages部分获取你的account_id。在wrangler.toml中配置name tech-blog-rater compatibility_date 2024-08-01 main src/index.ts设置环境变量OPENAI_API_KEYnpx wrangler secret put OPENAI_API_KEY # 然后输入你的API Key部署npx wrangler deploy部署成功后你会获得一个类似https://tech-blog-rater.your-subdomain.workers.dev的URL。将这个URL填回之前skill.json的endpoint.url中。实操心得在Worker中处理网页内容提取是一大挑战。直接fetch可能遇到动态渲染如React应用或反爬措施。一个更稳健的方案是1) 使用mozilla/readability这样的库在Worker内解析或者2) 调用专门的提取API如Mercury Parser的API但需注意成本。对于个人技能如果目标网站是静态博客如GitHub Pages、Hugo、Hexo生成简单提取通常就够用。3.3 本地测试与调试技巧在提交到wawa1154/kagi-skills仓库前务必进行充分测试。使用curl模拟Kagi请求curl -X POST https://tech-blog-rater.your-subdomain.workers.dev/ \ -H Content-Type: application/json \ -d {url: https://example.com/your-favorite-tech-blog-post, focus_area: backend}检查返回的JSON是否完全符合你定义的output_schema。在Kagi中临时测试将你的skill.json文件内容复制。登录Kagi进入Settings - Assistant - Skills。点击“Add a custom skill”粘贴skill.json内容并保存。在Assistant聊天框尝试触发你的技能如输入“评估一下这篇关于Redis缓存的文章 https://example.com/redis-cache”。观察Assistant是否能正确识别意图、调用你的技能并展示结果。如果失败检查Worker的日志在Cloudflare Dashboard查看和Kagi技能列表中的错误提示。3.4 向wawa1154/kagi-skills贡献你的技能测试无误后就可以贡献给社区了。Fork仓库在GitHub上forkwawa1154/kagi-skills。创建分支在你的fork中为你的技能创建一个新分支例如add-tech-blog-rater。添加文件将你的skills/tech-blog-rater/文件夹包含skill.json、icon.png、README.md添加到仓库的skills/目录下。编写README在技能文件夹内创建一个详细的README.md至少应包括技能功能简介使用示例在Kagi Assistant中怎么说话触发需要的参数说明技能后端实现的技术栈简介可选但有助于他人学习任何已知限制或注意事项提交Pull Request (PR)提交PR到原仓库。在PR描述中清晰说明技能的功能、使用场景和测试情况。贡献注意事项代码质量确保你的技能后端代码是安全、高效的避免有漏洞或滥用API。文档清晰好的文档能极大降低他人的使用门槛。遵守规范仔细阅读项目根目录的CONTRIBUTING.md文件遵循其中的代码风格和提交信息规范。维护性考虑技能的未来维护。如果你不再维护应在README中说明。4. 高阶应用技能组合与复杂工作流构建单个技能已经能提升效率但Kagi Skills的真正威力在于技能组合。Assistant可以在一轮对话中顺序或并行调用多个技能完成复杂工作流。4.1 链式调用实战研究助理工作流假设你正在研究“WebAssembly在边缘计算中的应用”。你可以设计一个对话让Assistant调用搜索技能或Kagi内置搜索找到最新、最相关的5篇文章。对每篇文章调用“网页总结器”技能获取核心摘要。调用“文本翻译器”技能如果需要将非母语摘要翻译。最后调用一个自定义的“综合报告生成器”技能将所有摘要作为输入生成一份对比分析报告。虽然目前Kagi Assistant不能完全自动化这个流程需要用户逐步引导但你可以通过精心设计提示词来接近自动化。例如你可以对Assistant说 “请搜索‘WebAssembly edge computing 2024 review’找到评分最高的3篇文章然后逐一用‘总结这个网页’技能为我生成中文摘要最后把所有摘要整理成一个对比表格。”实现“综合报告生成器”技能的思路 这个技能的后端需要能接收一个“文章摘要列表”作为输入。它的input_schema可能包含一个summaries数组。后端逻辑调用AI API提示词为“你是一名技术分析师。以下是关于[主题]的几篇文章摘要[插入摘要列表]。请分析它们生成一份综合报告包括技术趋势共识、主要应用场景、提到的关键工具/框架、以及存在的挑战或不同观点。用Markdown格式输出。”4.2 技能参数化与条件逻辑高级技能可以设计得更智能。例如一个“智能天气助手”技能其input_schema可以接受location城市名或坐标和query_type如“now”、“today”、“weekend”、“travel”。在后端逻辑中根据query_type调用不同的天气API数据并生成差异化的回复。query_type: travel可能返回未来几天天气并附加穿衣和出行建议。query_type: now只返回当前温度、体感温度和简短描述。这要求后端代码有清晰的条件分支逻辑。在skill.json中用enum定义好query_type的可选值并在description里向用户说明每种类型的用途。4.3 利用外部API与数据源增强技能技能的强大离不开丰富的外部服务。以下是一些常用方向数据查询接入WolframAlpha数学计算、事实查询、CoinGecko加密货币、Alpha Vantage股票金融。内容处理接入DeepL高质量翻译、Hugging Face Inference API各种NLP模型、Browserless无头浏览器用于复杂网页抓取。自动化接入IFTTT、Zapier、Make原Integromat的Webhooks从而间接控制智能家居、发送通知到Discord/Slack等。专业领域接入PubMed API医学文献、arXiv API预印本论文、GitHub API仓库分析。安全提醒在技能后端代码中调用第三方API时务必通过环境变量如Cloudflare Workers的env管理API密钥绝对不要硬编码在代码或提交到公开仓库。在wawa1154/kagi-skills的README中也应提醒技能使用者某些技能可能需要他们自行配置API密钥这通常意味着技能创建者需要提供详细的配置指南。5. 故障排查、优化与社区生态参与5.1 常见问题与解决方案速查表在开发和使用的过程中你可能会遇到以下典型问题问题现象可能原因排查步骤与解决方案技能在Kagi中启用失败提示“Invalid skill configuration”skill.json格式错误或缺少必填字段1. 使用JSON验证工具如JSONLint检查语法。2. 对照官方Schema检查所有必填字段schema_version,display_name,skill_id,endpoint等。3. 确保skill_id在本地测试时唯一。Assistant识别了意图但提示“Skill execution failed”或超时1. 后端端点URL错误或不可达。2. 后端服务内部错误500。3. 网络超时默认可能有时间限制。1. 用curl或Postman直接测试你的端点URL确认服务正常运行且返回正确JSON。2. 查看后端服务日志Cloudflare Workers Dashboard有实时日志。3. 检查后端代码确保处理了所有异常并返回了符合output_schema的响应即使是错误信息。4. 优化后端逻辑对于耗时的操作如调用慢速API考虑异步处理或增加超时设置。技能被触发但返回的结果格式混乱Assistant无法解析后端返回的JSON结构与output_schema定义不匹配。1. 严格对照skill.json中的output_schema确保后端返回的JSON键名、类型完全一致。2. 即使某个字段值为空也应包含该键如null或空字符串。3. 使用TypeScript接口或Python的Pydantic模型来强制约束返回结构减少人为错误。技能在某些查询下工作正常某些下失败输入参数处理不鲁棒或依赖的外部API有调用限制/失败。1. 在后端代码中增加输入验证和清理如URL格式校验。2. 为外部API调用添加重试机制和降级策略如主API失败时尝试备用API。3. 添加更详细的错误日志方便定位具体失败环节。自定义技能在Kagi中不显示或无法搜索到技能未成功添加到个人技能库或Kagi索引延迟。1. 确认在Kagi的Skills设置中已通过“Add a custom skill”成功添加并启用。2. 如果是提交到wawa1154/kagi-skills并希望公开需要等待项目维护者合并PR并且Kagi官方可能定期同步该仓库。这不是实时过程。5.2 性能优化与成本控制对于公开分享的技能尤其是可能被频繁调用的性能和成本是关键。缓存策略对于结果变化不频繁的技能如天气、货币汇率可容忍几分钟延迟在Worker中使用Cloudflare的Cache API进行响应缓存。// 在Cloudflare Worker中示例 const cacheKey result:${url}; let response await caches.default.match(cacheKey); if (!response) { // ... 执行昂贵的计算或API调用 ... response new Response(JSON.stringify(result), {...}); // 设置缓存TTL为5分钟 response.headers.append(Cache-Control, public, max-age300); ctx.waitUntil(caches.default.put(cacheKey, response.clone())); } return response;异步处理与队列对于非常耗时的任务如视频总结、大型文档分析不要让HTTP请求一直等待。可以立即返回一个“任务已接收”的响应然后通过Webhook、队列如Cloudflare Queues或Durable Objects在后台处理处理完成后再通过其他方式如邮件、通知告知用户。但这需要更复杂的架构且可能超出Kagi Skills当前简单的请求-响应模式。成本控制如果技能使用付费API如OpenAI、DeepL你需要考虑设置用量限制在Worker代码中为每个IP或API密钥设置调用频率限制rate limiting。使用更经济的模型例如用gpt-4o-mini代替gpt-4用claude-3-haiku代替claude-3-opus。提供清晰的成本说明在技能的README中明确说明该技能可能产生的API成本如果开源提醒其他部署者需要自行配置密钥和承担成本。5.3 参与社区与技能发现wawa1154/kagi-skills作为一个开源项目其活力源于社区。除了贡献技能你还可以通过以下方式参与测试与反馈尝试使用他人贡献的技能并在GitHub Issue中提供反馈报告bug或提出改进建议。文档改进帮助翻译文档、完善现有技能的说明降低使用门槛。技能创意讨论在GitHub Discussions中提出你希望看到但还没人实现的技能创意或许能吸引其他开发者一起实现。代码审查如果你有经验可以参与他人PR的代码审查帮助提升项目整体质量。通过这样的参与你不仅能获得自己需要的工具还能帮助塑造这个新兴生态让它对所有人更有用。从我个人的使用经验来看Kagi Skills的潜力远未被完全挖掘。随着更多开发者的加入和更复杂技能的出现它有可能成为一个去中心化的、由社区驱动的“AI智能体Agent市场”的雏形。你现在投入时间学习和贡献很可能是在为未来的工作流范式提前布局。