终结 Vibe Coding 技术债。审计你的代码库，用独角兽级别的
第三方库替换重复造轮子的代码，并输出迁移方案 + "删除代码"清单。
English | 简体中文
快速开始 • 功能特性 • 工作原理 • 方案对比 • API 接口 • 示例 • 贡献指南
--- ## 为什么选择 Next-Unicorn？ 每个代码库都会逐渐积累本应使用成熟第三方库的手写实现。自制的日期格式化器、DIY 日志器、临时状态机、草率的 i18n 方案——这些都是 **Vibe Coding 技术债**。 Snyk、Dependabot 和 Renovate 管理的是你*已有*的依赖。它们无法发现你写了但*应该替换为*依赖的代码，也无法发现项目*完全缺失*的能力。 **Next-Unicorn 三管齐下** —— 替换分析、缺口分析和依赖管理 —— 所有推荐均通过 [Context7 MCP](https://context7.com) 进行真实文档验证。 ## 快速开始 ### 从 Smithery 安装（推荐） 在 Smithery 技能市场中浏览并直接安装： > **[Next-Unicorn on Smithery](https://smithery.ai/skills/nebutra/next-unicorn-skill)** ### 从 npmjs.org 安装 ```bash npm install @nebutra/next-unicorn-skill # 或 pnpm add @nebutra/next-unicorn-skill ``` ### 从 GitHub Packages 安装 先配置 `.npmrc`： ```shell echo "@nebutra:registry=https://npm.pkg.github.com" >> .npmrc ``` 然后安装： ```bash npm install @nebutra/next-unicorn-skill ``` ```typescript import { analyze, scanCodebase } from '@nebutra/next-unicorn-skill'; import type { Recommender, GapRecommendation } from '@nebutra/next-unicorn-skill'; // 推荐器：AI 代理决定每个检测结果应使用哪个库 const recommender: Recommender = (detection) => ({ library: '@lingui/core', version: '^4.0.0', license: 'MIT', rationale: '编译时 i18n，近乎零运行时开销', ecosystem: [ { library: '@lingui/macro', version: '^4.0.0', role: '标签模板' }, { library: '@lingui/cli', version: '^4.0.0', role: 'CI 消息提取' }, ], antiPatterns: ['如果在意包体积，避免使用 i18next —— Lingui 会在编译时消除'], alternatives: [ { library: 'next-intl', when: '使用 Next.js App Router 和服务端组件时' }, ], }); // 缺口分析：项目应有但未实现的能力 const gaps: GapRecommendation[] = [ { domain: 'observability', description: '未检测到结构化日志', recommendedLibrary: { name: 'pino', version: '^9.0.0', license: 'MIT', rationale: '最快的 Node.js JSON 日志库，支持数据脱敏和子日志器', }, priority: 'critical', }, ]; const result = await analyze({ input: { projectMetadata: { repoPath: './my-project', languages: ['typescript'], packageManagers: ['pnpm'], currentLibraries: { react: '18.2.0', next: '14.1.0' }, }, optimizationGoals: ['减少自定义代码', '提升可维护性'], constraints: { licenseAllowlist: ['MIT', 'Apache-2.0', 'ISC'] }, priorityFocusAreas: ['i18n', 'observability', 'auth-security'], }, context7Client: myContext7Client, recommender, gaps, }); if (result.success) { console.log(result.prettyJson); // result.scanResult — 原始检测结果 + 结构化发现，供 AI 分析使用 // result.output.gapAnalysis — Context7 验证过的缺口推荐 } ``` 或作为 **MCP SKILL** 使用 —— 将 [`SKILL.md`](./SKILL.md) 提供给你的 AI 代理（Claude Code、Kiro、Cursor 等）。 ## 功能特性 ### 核心分析 | 功能 | 描述 | |------|------| | **基于模式的扫描** | 使用 52 个正则模式跨 31 个领域检测手写代码（设计系统、认证、状态管理、代码组织等） | | **结构分析** | 检测 Monorepo 架构缺陷：缺失的 Token 层、依赖流向违规、硬编码配置值 | | **缺口分析** | AI 代理识别缺失的能力 —— 不仅是手写代码，还包括你应有但没有的东西 | | **生态级推荐** | 解决方案包含理由、配套包、反模式和替代方案 | | **Context7 验证** | 每条推荐（替换和缺口）均经过指数退避重试验证 | | **7 维影响评分** | 可扩展性、性能、安全性、可维护性、功能丰富度、用户体验、UI 美观度 | | **分阶段迁移计划** | 低 / 中 / 高风险阶段，含适配器策略 | | **删除清单** | 列出每个待删文件和行范围，附预估节省行数 | | **UX 完整性审计** | 无障碍、错误/空/加载状态、表单验证、设计系统对齐 | | **设计系统支持** | 两条路径：从参考仓库搭建（Primer、Polaris、Supabase、Dub）或从现有代码中提取 | | **代码组织分析** | 检测上帝目录、混合命名规范、过深嵌套、Barrel 膨胀、万能目录和循环依赖（通过 import 图遍历） | | **人机协作闸门** | 4 个结构化决策闸门：分诊、偏好选择（SWOT）、接受/拒绝推荐、执行确认 | | **Monorepo 支持** | 独立检测 npm、pip、cargo、go 工作区 | ### 依赖管理 | 功能 | 描述 | |------|------| | **漏洞扫描** | 通过 OSV 扫描当前和推荐的依赖 —— 防止"升级引入漏洞" | | **自动更新依赖** | 基于影响评分的版本升级，通过 Context7 检测破坏性变更 | | **自动创建 PR** | GitHub/GitLab PR，包含常规提交标题、影响表格、审查清单 | | **迁移 PR** | 包含适配器代码脚手架的 PR，用于替换手写代码 | ## 工作原理 ### 架构图 ```mermaid flowchart TB subgraph input [输入] I[InputSchema JSON] end subgraph deterministic [确定性层 — TypeScript] V[Zod 验证器] S[扫描器 — 52 个正则模式覆盖 31 个领域] SA[结构分析器 — Monorepo 架构、依赖流向、Token 层] C7[Context7 验证器 — 指数退避、查询排序] VS[漏洞扫描器 — OSV 数据库] PC[Peer 检查器 — semver 范围验证] PR[PR 策略 + 执行器] end subgraph agent [AI 代理层 — Claude 泛化] GA[缺口分析 — 单库 / 生态 / 架构级缺口] REC[推荐器 — 生态级解决方案含理由] UX[UX 审计 — 8 个类别] DS{设计系统？} DSE[从现有代码提取] DSS[从参考仓库搭建] end subgraph output [输出] O[OutputSchema JSON] end I --> V --> S S --> SA S --> REC SA --> GA GA --> DS DS -->|有前端| DSE DS -->|无前端| DSS GA --> O REC --> C7 --> O S --> PC --> O S --> VS --> O UX --> O O --> PR ``` ### 设计原则 | 原则 | 实现方式 | |------|----------| | **奥卡姆剃刀** | 仅保留 17 个 TS 模块 —— 每个模块做 Claude 无法做的事（正则、semver、文件 I/O、API 调用、import 图遍历）。评分、规划、UX 审计、PR 描述由 AI 代理驱动。 | | **不硬编码推荐** | 模式目录中不包含任何库名。`Recommender` 回调和 `GapRecommendation` 由 AI 代理在运行时填充。 | | **Context7 最佳实践** | 指数退避（3 次重试），用于排序的查询参数，按库隔离。替换和缺口均经过验证。 | | **渐进式披露** | SKILL.md 仅 111 行。`references/` 文件仅在检测到设计系统缺口时加载。 | | **双分析模式** | **替换**：扫描器发现手写代码 → 代理推荐库。**缺口**：代理识别缺失能力 → 通过 Context7 验证。 | | **设计系统支持** | 结构分析器检测缺失层。两条路径：从 25+ 参考仓库搭建，或从现有代码提取规范（6 原则，5 阶段）。 | 每个阶段都是具有结构化 I/O 的纯函数。所有外部依赖（Context7、OSV、npm 注册表、GitHub API）均通过**接口注入**以保证可测试性。 ### 前后对比| 之前（手写实现） | 之后（推荐方案） |
|---|---|
| ```tsx // 自定义 i18n 散布在 47 个文件中 const translations = { en: { greeting: 'Hello' }, es: { greeting: 'Hola' }, }; function t(key, locale) { return translations[locale]?.[key] ?? key; } // 无复数、无插值、无 RTL 支持 ``` |
```tsx
// @lingui/core — Context7 已验证，MIT
// 生态：@lingui/macro + @lingui/cli
// 影响：9.2/10 | 风险：低 | 工时：8h
import { useLingui } from '@lingui/react';
export default function Page() {
const { t } = useLingui();
return {t`greeting`}; } ``` |
| ```typescript // 使用 console.log 的自定义日志器 function logRequest(req) { console.log(JSON.stringify({ time: new Date().toISOString(), method: req.method, url: req.url, })); } // 无日志级别、无脱敏、无轮转 ``` | ```typescript // pino — Context7 已验证，MIT // 缺口分析："未检测到结构化日志" // 优先级：关键 import pino from 'pino'; const logger = pino({ level: 'info', redact: ['req.headers.authorization'], }); ``` |