AGNXI：AI编码助手技能目录的全栈实现与部署指南

1. 项目概述：AGNXI - 一个为AI编码助手打造的技能目录

如果你和我一样，日常开发已经离不开像 Claude Code、Cursor 这类 AI 编码助手，那你肯定也遇到过这样的场景：面对一个特定的开发任务，比如“如何用 Next.js 配置一个高效的图片优化管道”，或者“怎么给项目快速集成一个完整的监控告警系统”，你希望助手能给出最精准、最专业的指导，而不是泛泛而谈。这时候，一个专门为这些 AI 助手编写的、结构化的技能文件（SKILL.md）就显得至关重要。它就像给 AI 装上了一本专业的“工具手册”，让它能调用特定领域的知识来帮你解决问题。

AGNXI 这个项目，就是这样一个“技能目录”的集散中心。它的核心目标很简单：自动发现、索引并归类 GitHub 上所有公开的 SKILL.md 文件，为开发者提供一个可以浏览、搜索、收藏这些技能的中央仓库。想象一下，你不再需要去各个仓库里翻找，或者凭记忆回想某个好用的技能；打开 AGNXI，就像打开一个为 AI 助手量身定做的“应用商店”，你可以按类别（前端、后端、DevOps、测试等）浏览，按热度（GitHub 星标数）排序，找到心仪的技能后，一键复制安装命令，立刻就能在你的 Cursor 或 Windsurf 里用上。

这个项目本身也是一个非常值得学习的现代全栈应用范例。它采用了 Next.js 16（App Router）、TypeScript、Tailwind CSS、PostgreSQL 等一整套前沿且务实的技术栈。更特别的是，它深度集成了 AI（用于技能自动分类）和后台任务调度（用于定期同步技能库），是一个典型的“AI 增强型”应用。接下来，我会带你深入拆解这个项目的设计思路、技术实现细节，并分享我在复现和探索过程中的一些实操心得与避坑指南。

2. 核心架构与设计思路拆解

2.1 为什么需要“技能目录”？解决什么痛点？

在深入代码之前，我们先聊聊“为什么”。AI 编码助手的“技能”本质上是一种上下文增强文件。当你把一个SKILL.md文件加载到助手的上下文中，它就获得了执行某一类任务所需的特定知识、最佳实践和代码模板。痛点随之而来：

1. 发现困难：优质的技能散落在 GitHub 的各个角落，没有统一的索引。开发者要么靠社区口口相传，要么自己大海捞针。
2. 质量参差：找到的技能文件，其完整性、准确性和实用性无法保证。
3. 管理不便：即使收藏了几个技能，时间一长也容易忘记，更别提在不同项目、不同助手间同步使用了。

AGNXI 的定位就是解决这三个核心痛点。它通过 GitHub 的 Code Search API 主动爬取SKILL.md文件，利用 AI 模型自动解析和分类，并提供一个带搜索、筛选、排序功能的 Web 界面进行集中展示。这形成了一个从“生产”（开发者编写技能）到“消费”（其他开发者使用技能）的良性循环生态。

2.2 技术栈选型背后的逻辑

项目 README 里给出了清晰的技术栈表格，每一个选择都很有讲究：

• Next.js 16 (App Router): 这是当前构建全栈 React 应用的事实标准。App Router 提供了基于文件系统的路由、服务端组件、流式渲染等现代特性，非常适合 AGNXI 这种兼具动态内容（技能列表）和静态页面（营销页）的应用。服务端组件能直接访问数据库，简化了数据获取逻辑。
• Bun: 替代 Node.js 作为运行时和包管理器。Bun 的启动速度和执行效率更高，内置了测试运行器、打包工具等，能简化开发工具链。对于需要频繁执行脚本（如数据库迁移、后台任务）的项目来说，提升明显。
• TypeScript: 对于涉及复杂数据模型（技能元数据、分类）和多个服务（数据库、AI、缓存）交互的项目，TypeScript 提供的类型安全是必不可少的，能极大减少运行时错误。
• Tailwind CSS 4: 快速构建一致、响应式 UI 的利器。AGNXI 的界面看起来干净专业，Tailwind 功不可没，它让开发者能专注于组件逻辑而非 CSS 细节。
• PostgreSQL + Drizzle ORM: PostgreSQL 是功能强大的关系型数据库，适合存储结构化的技能、分类、用户收藏等数据。Drizzle 是一个新兴的、类型安全的 ORM，它的 API 设计更接近 SQL，避免了传统 ORM 的“魔法”，学习曲线平缓且性能可观，与 TypeScript 搭配是天作之合。
• Clerk: 身份认证服务。自己实现一套完整、安全的用户系统（注册、登录、管理）费时费力且容易出错。Clerk 提供了开箱即用的解决方案，集成简单，专注于核心业务逻辑。
• Vercel AI SDK + Google Gemini: AI SDK 统一了与不同 AI 模型交互的接口。选择 Google Gemini 可能是出于成本、速率限制或对特定任务（如文本分类）效果的考量。这里 AI 的核心作用是对爬取到的技能进行自动分类。
• Upstash Redis: 托管式 Redis 服务。用于缓存高频访问的数据（如热门技能列表、分类信息），减轻数据库压力，提升响应速度。
• Inngest: 后台任务调度服务。技能库的同步、AI 分类、数据清理等耗时操作不适合在用户请求中同步执行。Inngest 允许你定义函数，由特定事件（如定时器、API 调用）触发，在后台异步运行，保证了 Web 服务的响应性。

实操心得：技术选型的平衡这个技术栈体现了“现代、高效、托管服务优先”的思路。对于个人项目或初创项目，优先使用像 Clerk、Upstash、Inngest 这样的托管服务，能让你用最少的基础设施运维成本，快速获得生产级的可靠功能。虽然会产生一些费用，但相比自己搭建和维护，在项目早期性价比极高。

3. 核心模块解析与实操要点

3.1 技能发现与索引引擎

这是 AGNXI 最核心的“发动机”，位于lib/features/skills/目录下。它的工作流程可以拆解为以下几个关键步骤：

步骤一：基于 GitHub Code Search 的爬取它并非漫无目的地爬取整个 GitHub，而是精准地搜索包含SKILL.md文件路径的仓库。通常会使用 GitHub 的 REST API 或 GraphQL API 的 code search 功能。查询语句可能类似于filename:SKILL.md path:/。为了提高效率和遵守 GitHub API 的速率限制，爬取策略需要精心设计：

• 增量爬取：记录上次爬取的时间戳或仓库的pushed_at时间，只获取新增或更新的文件。
• 分页处理：妥善处理 API 返回的大量结果。
• 错误处理与重试：网络请求难免失败，需要有健壮的重试机制和日志记录。

步骤二：技能元数据解析爬取到SKILL.md的原始内容后，需要从中提取结构化信息。一个规范的SKILL.md通常在文件头部用 YAML Front Matter 定义元数据，例如：

--- name: ‘Next.js Image Optimization Skill’ description: ‘Best practices for optimizing images in Next.js projects’ author: ‘someuser’ tools: [‘cursor’, ‘claude’] tags: [‘nextjs’, ‘performance’, ‘images’] ---

解析器需要读取这部分内容，并可能解析正文来补充描述。这里需要处理各种边缘情况，比如格式不标准、缺少必要字段等。

步骤三：AI 驱动的自动分类这是项目的亮点。解析出的技能描述（description）和标签（tags）会被发送给 Gemini 这样的 LLM，要求其根据预定义的分类体系（如“前端开发”、“后端开发”、“测试”、“DevOps”、“文档”等）为技能打上最合适的一个或多个分类标签。

• Prompt 设计是关键：你需要给 AI 清晰的指令，例如：“你是一个技术分类专家。请根据以下技能描述，从 [‘前端’, ‘后端’, ‘DevOps’, ‘测试’, ‘文档’, ‘工具’] 中选择最相关的1-3个分类。只返回分类名称，用逗号分隔。”
• 处理不确定性：AI 的输出可能不稳定，可能需要设置置信度阈值，或者提供“未分类”作为兜底选项。

步骤四：数据存储将解析和分类后的结构化数据，通过 Drizzle ORM 存入 PostgreSQL 数据库。主要的数据表可能包括：

• skills: 存储技能的核心信息（名称、描述、GitHub 链接、原始内容哈希等）。
• categories: 存储分类。
• skill_categories: 技能与分类的多对多关联表。
• repositories: 存储仓库信息，与技能关联。

注意事项：遵守平台规则与伦理

1. API 速率限制：严格遵守 GitHub API 的速率限制。对于未认证的请求，限制非常严格；使用GITHUB_TOKEN进行认证可以大幅提升限额。在代码中必须实现间隔（throttling）和退避（backoff）逻辑。
2. 仓库许可证：只索引公开仓库，并尊重仓库所采用的许可证（如 MIT, GPL）。AGNXI 本身是目录，不存储技能的完整代码，但索引其元数据和描述通常被认为是合理使用（fair use），不过最好在网站页脚添加相关声明。
3. 用户隐私：如果技能文件包含个人信息，应避免索引或进行脱敏处理。不过SKILL.md通常是技术文档，这个问题不常见。

3.2 后台任务与同步机制

技能库需要保持更新。新技能被创建，旧技能可能被修改或删除。同步任务通过 Inngest 来管理。

Inngest 函数示例： 在lib/inngest/目录下，你可能会看到类似sync-skills.ts的函数。

import { inngest } from '@/lib/inngest/client'; export const syncSkills = inngest.createFunction( { id: 'sync-skills', name: 'Sync Skills from GitHub' }, { cron: '0 */6 * * *' }, // 每6小时运行一次 async ({ step }) => { // 1. 调用发现引擎，获取新增/更新的技能 const newSkills = await step.run('discover-skills', async () => { return discoverNewSkills(); }); // 2. 对每个新技能，运行AI分类 for (const skill of newSkills) { await step.run(`classify-skill-${skill.id}`, async () => { return classifySkillWithAI(skill); }); } // 3. 清理已删除或失效的技能 await step.run('cleanup-skills', async () => { return cleanupDeletedSkills(); }); return { message: `Synced ${newSkills.length} skills` }; } );

Inngest 的优势在于它提供了强大的工作流控制（step.run）、重试机制和可视化仪表板，让复杂的异步任务变得可管理。

3.3 前端界面与用户体验

前端部分（app/,components/,features/）负责将数据呈现给用户。

• 技能列表页 (app/skills/page.tsx)：这是核心页面。通常会使用服务端组件获取数据，结合搜索参数（来自 URL searchParams）进行过滤和排序。排序逻辑（按星标、按分叉数、按更新时间）需要在数据库查询层面实现，以确保效率。
• 技能详情页 (app/[owner]/[skillName]/page.tsx)：动态路由页面，展示单个技能的详细信息、原始SKILL.md内容，以及最重要的——一键复制安装命令。这个命令会根据技能兼容的工具（Cursor, Claude等）生成不同的格式，例如对于 Cursor：/skill install https://github.com/username/repo/blob/main/SKILL.md。
• 收藏功能：用户登录（通过 Clerk）后，可以收藏技能。这涉及在数据库中添加一个user_favorites表，并在 UI 上提供收藏/取消收藏的交互。
• 管理后台 (app/admin/)：提供手动触发同步、查看同步日志、管理分类等功能的界面，通常需要设置管理员权限。

4. 本地开发环境搭建与核心配置

让我们动手，从零开始让 AGNXI 在本地跑起来。这是理解项目依赖和配置的最佳方式。

4.1 环境准备与依赖安装

首先，确保你的系统已经安装了 Bun。如果没有，去 Bun 官网按照指引安装，速度很快。

# 1. 克隆仓库 git clone https://github.com/doanbactam/agent-skills-directory.git cd agent-skills-directory # 2. 安装项目依赖 # 使用 Bun 安装，速度比 npm/yarn 快很多 bun install

如果bun install过程中遇到问题，通常是网络或某些原生模块编译的问题。可以尝试设置镜像或检查系统是否安装了必要的构建工具（如 Python、C++编译器等）。

4.2 关键环境变量配置

项目根目录下有一个.env.example文件，这是配置模板。复制它并创建你自己的.env.local文件（Next.js 默认读取此文件）。

cp .env.example .env.local

现在，打开.env.local，你需要逐一填写以下关键配置。这是项目能否运行起来的重中之重。

1. 数据库 (PostgreSQL):

   DATABASE_URL="postgresql://username:password@localhost:5432/agnxi_db"

   • 你需要本地安装并运行 PostgreSQL，或者使用云服务（如 Neon, Supabase）提供的连接字符串。
   • 创建一个名为agnxi_db的数据库。

2. 身份认证 (Clerk):

   NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_... CLERK_SECRET_KEY=sk_test_...

   • 前往 Clerk 官网 注册并创建一个新应用。
   • 在 Dashboard 中找到 API Keys，将NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY和CLERK_SECRET_KEY填入。

3. GitHub API:

   GITHUB_TOKEN=ghp_...

   • 在 GitHub 设置中生成一个 Personal Access Token (Classic)。
   • 需要勾选repo和read:packages等权限，以便 Code Search API 能正常工作。没有这个 Token，技能发现功能将无法使用或受到严格限制。

4. AI 模型 (Google Gemini):

   GOOGLE_GENERATIVE_AI_API_KEY=AIza...

   • 前往 Google AI Studio 创建一个 API 密钥。
   • 启用 Gemini API 服务。注意，此服务可能非免费，需留意用量。

5. 缓存 (Upstash Redis):

   UPSTASH_REDIS_REST_URL=https://xxx.upstash.io UPSTASH_REDIS_REST_TOKEN=xxx

   • 在 Upstash 创建一个 Redis 数据库，免费 tier 足够开发使用。
   • 将提供的 REST URL 和 Token 填入。

6. 后台任务 (Inngest):

   INNGEST_EVENT_KEY=xxx INNGEST_SIGNING_KEY=xxx

   • 在 Inngest 创建一个账户和项目。
   • 在项目设置中找到 Keys，填入对应值。开发环境下，你也可以暂时不配置，但后台同步功能将无法工作。

踩坑实录：环境变量与类型安全我第一次配置时，在.env.local里填好了所有值，但运行时还是报错说缺少某个变量。原因是 Next.js 只在启动时读取.env.local，而我在运行bun db:push这个脚本时，脚本可能直接读取了process.env。解决方案：确保你的脚本（在package.json的scripts里）也通过dotenv或类似方式加载了环境变量。另一个常见问题是变量名拼写错误，务必与.env.example和代码中process.env.XXX的引用完全一致。

4.3 数据库初始化与数据迁移

配置好环境变量后，就可以初始化数据库了。

# 运行 Drizzle 的 push 命令，根据你的 schema 文件在数据库中创建所有表 bun db:push # （可选）如果项目提供了种子数据脚本，可以运行它来预置一些分类数据 bun db:seed:categories

bun db:push这个命令非常方便，它直接同步你的 TypeScript schema 定义到数据库，适合开发阶段。在生产环境，更推荐使用生成迁移文件并执行的方式 (bun db:generate->bun db:migrate)，以便对变更进行版本控制。

4.4 启动开发服务器

如果以上步骤都没报错，那么恭喜你，最艰难的部分已经过去了。

bun dev

打开浏览器，访问http://localhost:3000。你应该能看到 AGNXI 的首页。由于数据库是空的，技能列表可能为空。此时，你可以尝试触发一次手动的技能同步（如果管理后台已搭建），或者直接通过前端界面提交一个已知的SKILL.md文件 URL 进行测试。

5. 深入代码：技能分类的 AI 集成实现

让我们深入一个具体的技术点：AI 如何给技能分类。这是项目智能化的核心。

代码位置猜想：逻辑很可能在lib/ai/classify-skill.ts或lib/actions/classify-skill.action.ts中。

实现解析：

import { GoogleGenerativeAI } from '@google/generative-ai'; // 初始化 Gemini const genAI = new GoogleGenerativeAI(process.env.GOOGLE_GENERATIVE_AI_API_KEY!); const model = genAI.getGenerativeModel({ model: 'gemini-1.5-flash' }); // 使用轻量快速的模型 export async function classifySkill(skillDescription: string, skillTags: string[] = []) { // 1. 构建Prompt。清晰的指令是获得稳定结果的关键。 const prompt = ` 你是一个资深的软件开发技术分类专家。 请根据以下技能描述和标签，从以下分类列表中选择最相关的1到3个分类。 请只返回分类名称，用英文逗号分隔。如果都不相关，返回“Uncategorized”。 【分类列表】 - Frontend Development - Backend Development - DevOps & Infrastructure - Testing & QA - Documentation & Writing - Tooling & Utilities - AI & Machine Learning - Security - Mobile Development - Data Science & Analytics 【技能描述】 ${skillDescription} 【技能标签】 ${skillTags.join(', ')} 请直接给出分类结果： `; // 2. 调用AI模型 try { const result = await model.generateContent(prompt); const response = await result.response; const text = response.text().trim(); // 3. 解析结果 const categories = text.split(',').map(cat => cat.trim()).filter(Boolean); // 4. 验证分类是否在预定义列表中 const validCategories = [...predefinedCategoryList]; // 从数据库或配置中读取 const filteredCategories = categories.filter(cat => validCategories.includes(cat)); return filteredCategories.length > 0 ? filteredCategories : ['Uncategorized']; } catch (error) { console.error('AI classification failed:', error); // 降级策略：如果AI调用失败，尝试从标签中匹配，或者返回默认分类 return fallbackClassification(skillTags); } } // 降级策略函数示例 function fallbackClassification(tags: string[]): string[] { const tagToCategoryMap: Record<string, string> = { 'react': 'Frontend Development', 'nextjs': 'Frontend Development', 'node': 'Backend Development', 'docker': 'DevOps & Infrastructure', 'jest': 'Testing & QA', // ... 更多映射 }; const mapped = tags.map(tag => tagToCategoryMap[tag.toLowerCase()]).filter(Boolean); return [...new Set(mapped)]; // 去重 }

关键要点与优化建议：

1. Prompt 工程：上面的 Prompt 包含了角色设定、清晰的任务说明、分类列表、输入数据和输出格式要求。这是获得高质量、结构化结果的基础。在实际项目中，可能需要反复调试 Prompt。
2. 错误处理与降级：AI 服务可能不稳定或超时。必须有健壮的错误处理。降级策略（如基于标签的关键词匹配）能保证系统在 AI 服务不可用时依然能运行，尽管准确性会下降。
3. 成本与延迟考虑：gemini-1.5-flash是性价比高的选择。对于大量技能的分类，可以考虑批量处理，或者将分类结果缓存起来，避免对同一技能的重复分类。
4. 结果验证：AI 可能返回不在列表中的分类名。代码中增加了验证步骤，确保只返回系统认可的分类。

6. 部署与生产环境考量

让项目在本地运行只是第一步。要真正提供服务，你需要部署它。

6.1 部署平台选择

AGNXI 的技术栈天然适合部署在Vercel上。

• 无缝集成：Next.js 是 Vercel 的亲儿子，部署体验最好，支持 Serverless Functions、Edge Functions 等。
• 环境变量管理：Vercel 项目设置中可以方便地配置所有环境变量。
• 数据库连接：需要确保你的 PostgreSQL 数据库（如 Neon）允许从 Vercel 的 IP 连接。通常云数据库服务都提供了连接串和 IP 白名单功能。
• 后台任务：Inngest 服务是独立的，部署后需要将你的 Inngest 函数服务器（通常是一个单独的 Node.js 服务）也部署出去，并配置好INNGEST_EVENT_KEY等。Vercel 的 Serverless Functions 可以运行 Inngest 函数。

6.2 生产环境配置差异

1. 数据库迁移：生产环境绝对不要使用db:push。应该使用迁移：

   bun db:generate # 在修改 schema 后生成迁移文件 bun db:migrate # 在生产环境运行此命令来应用迁移

2. 环境变量：在 Vercel 等平台，严格区分开发和生产环境变量。像CLERK_SECRET_KEY、DATABASE_URL这些敏感信息，绝不能提交到代码仓库。
3. Clerk 配置：在 Clerk Dashboard 中，为你的生产域名（如https://agnxi.vercel.app）配置正确的回调 URL（Callback URL）和重定向 URL。
4. 缓存策略：生产环境下，合理配置 Upstash Redis 的持久化策略和内存大小。为高频访问的接口（如技能列表 API）设置缓存，并注意缓存失效策略。
5. 监控与日志：配置错误监控（如 Sentry）和日志收集服务，以便及时发现和排查问题。

6.3 自定义域名与 SEO

AGNXI 作为一个目录网站，SEO 很重要。

• 自定义域名：在 Vercel 项目中绑定你自己的域名。
• SEO 组件：项目中的components/seo/目录应该包含了用于管理页面标题、描述的组件。确保每个技能详情页都有独特的、包含关键词的title和description。
• 站点地图：项目提供了bun ping:indexnow脚本，用于向搜索引擎提交站点地图。你需要确保app/sitemap.ts（或robots.ts）文件正确生成，并包含了所有技能页面的链接。
• 性能优化：使用 Next.js 的Image组件优化图片，对技能列表页使用generateStaticParams进行部分静态生成或增量静态再生（ISR），以提升加载速度和 SEO 表现。

7. 常见问题排查与扩展思路

在复现和使用 AGNXI 的过程中，你可能会遇到以下问题：

7.1 问题排查速查表

7.2 项目扩展与二次开发思路

AGNXI 提供了一个优秀的起点，你可以在此基础上添加更多功能：

1. 技能评分与评论系统：让用户可以对技能进行评分和评论，形成社区反馈，帮助其他人判断技能质量。
2. 技能依赖分析：解析SKILL.md，自动识别该技能可能依赖的其他技能或工具，并建立关联图谱。
3. 个性化推荐：根据用户收藏、浏览历史，利用协同过滤等算法推荐可能感兴趣的技能。
4. 技能版本管理：跟踪SKILL.md文件的更新历史，允许用户查看差异并选择使用特定版本。
5. 离线模式或浏览器扩展：开发一个浏览器扩展，让用户能在 GitHub 仓库页面直接看到该技能的 AGNXI 评分和信息，并一键安装。
6. 支持更多 AI 助手：除了 Claude Code 和 Cursor，可以扩展对更多编辑器和 IDE 插件的支持，如 VS Code 的 Continue 插件等。

这个项目清晰地展示了一个全栈应用如何将数据爬取、AI 处理、后台任务、现代前端和用户体验有机结合。无论你是想直接使用这个技能目录来提升自己的开发效率，还是想学习如何构建一个类似的平台，AGNXI 的代码都值得你花时间深入研究。我在搭建过程中最大的体会是，清晰的架构设计和对第三方服务的合理运用，能让你一个人也能快速构建出功能复杂、体验专业的应用。遇到问题多查日志、善用调试工具，并勇于翻阅官方文档，大部分技术难题都能迎刃而解。